274 274
275Hooks de arquivos de configurações, configurações de política gerenciada e plugins também executam dentro de [subagentes](/docs/pt/sub-agents). Quando um subagente chama uma ferramenta, eventos de ferramenta como `PreToolUse` e `PostToolUse` disparam os mesmos hooks configurados que na conversa principal, e a entrada carrega os campos de entrada comuns `agent_id` e `agent_type` [](#common-input-fields) que identificam o subagente.275Hooks de arquivos de configurações, configurações de política gerenciada e plugins também executam dentro de [subagentes](/docs/pt/sub-agents). Quando um subagente chama uma ferramenta, eventos de ferramenta como `PreToolUse` e `PostToolUse` disparam os mesmos hooks configurados que na conversa principal, e a entrada carrega os campos de entrada comuns `agent_id` e `agent_type` [](#common-input-fields) que identificam o subagente.
276 276
277Administradores corporativos podem usar `allowManagedHooksOnly` para restringir quais hooks executam:277Administradores podem usar [`allowManagedHooksOnly`](/docs/pt/settings-reference#allowmanagedhooksonly) em [configurações gerenciadas](/docs/pt/managed-settings) para restringir quais hooks executam:
278 278
279* Seus hooks de usuário, projeto, local e plugin são bloqueados. Hooks de plugins forçadamente ativados em configurações gerenciadas `enabledPlugins` são isentos279* Seus hooks de usuário, projeto, local e plugin são bloqueados. Hooks de plugins forçadamente ativados em configurações gerenciadas `enabledPlugins` são isentos
280* Claude Code também restringe suas configurações [`statusLine`](/docs/pt/statusline), [`fileSuggestion`](/docs/pt/settings-reference#filesuggestion) e [`subagentStatusLine`](/docs/pt/statusline#subagent-status-lines) às configurações gerenciadas280* Claude Code também restringe suas configurações [`statusLine`](/docs/pt/statusline), [`fileSuggestion`](/docs/pt/settings-reference#filesuggestion) e [`subagentStatusLine`](/docs/pt/statusline#subagent-status-lines) às configurações gerenciadas
304 304
305Um matcher no caminho de expressão regular é testado com `RegExp.prototype.test` do JavaScript, que sucede em uma correspondência em qualquer lugar no valor. `Edit.*` corresponde tanto a `Edit` quanto a `NotebookEdit`; envolva o padrão em `^` e `$`, como em `^Edit$`, quando você precisa de uma correspondência de string inteira.305Um matcher no caminho de expressão regular é testado com `RegExp.prototype.test` do JavaScript, que sucede em uma correspondência em qualquer lugar no valor. `Edit.*` corresponde tanto a `Edit` quanto a `NotebookEdit`; envolva o padrão em `^` e `$`, como em `^Edit$`, quando você precisa de uma correspondência de string inteira.
306 306
307Hífens no conjunto de correspondência exata requerem Claude Code v2.1.195 ou posterior. Em versões anteriores, um nome com hífen como `code-reviewer` é avaliado como uma expressão regular não ancorada, então também dispara para `senior-code-reviewer`; ancorá-lo como `^code-reviewer$` nessas versões para corresponder apenas a esse nome.
308
309`FileChanged` e `StopFailure` usam um conjunto de correspondência exata mais estreito de apenas letras, dígitos, `_` e `|`. Um hífen, espaço ou vírgula em um matcher para esses dois eventos o mantém no caminho de expressão regular, e apenas `|` separa alternativas. Todos os outros eventos com suporte a matcher na tabela a seguir aceitam `|` ou `,`.307`FileChanged` e `StopFailure` usam um conjunto de correspondência exata mais estreito de apenas letras, dígitos, `_` e `|`. Um hífen, espaço ou vírgula em um matcher para esses dois eventos o mantém no caminho de expressão regular, e apenas `|` separa alternativas. Todos os outros eventos com suporte a matcher na tabela a seguir aceitam `|` ou `,`.
310 308
311O evento `FileChanged` não segue essas regras ao construir sua lista de monitoramento. Consulte [FileChanged](#filechanged).309O evento `FileChanged` não segue essas regras ao construir sua lista de monitoramento. Consulte [FileChanged](#filechanged).
380* `mcp__brave-search__.*` corresponde a todas as ferramentas de um servidor cujo nome contém um hífen378* `mcp__brave-search__.*` corresponde a todas as ferramentas de um servidor cujo nome contém um hífen
381* `mcp__.*__write.*` corresponde a qualquer ferramenta cujo nome começa com `write` de qualquer servidor379* `mcp__.*__write.*` corresponde a qualquer ferramenta cujo nome começa com `write` de qualquer servidor
382 380
383Hífens no conjunto de correspondência exata requerem Claude Code v2.1.195 ou posterior. Em versões anteriores, um prefixo com hífen simples como `mcp__brave-search` é avaliado como uma expressão regular não ancorada e corresponde a cada ferramenta daquele servidor. A forma `mcp__brave-search__.*` funciona em todas as versões.
384
385Ferramentas de um [servidor MCP fornecido por plugin](/docs/pt/mcp#plugin-provided-mcp-servers) usam um segmento de servidor com escopo que inclui o nome do plugin: `mcp__plugin_<plugin-name>_<server-name>__<tool>`. Um matcher escrito contra a chave do servidor simples nunca dispara para essas ferramentas. Para um plugin nomeado `my-plugin` que agrupa um servidor sob a chave `db`, uma ferramenta `query` aparece como `mcp__plugin_my-plugin_db__query`, então o matcher para cada ferramenta daquele servidor é `mcp__plugin_my-plugin_db__.*`. Use o mesmo nome de ferramenta com escopo no campo [`if`](#common-fields) de um manipulador. Consulte [Servidores MCP fornecidos por plugin](/docs/pt/mcp#plugin-provided-mcp-servers) para saber como o nome com escopo é construído.381Ferramentas de um [servidor MCP fornecido por plugin](/docs/pt/mcp#plugin-provided-mcp-servers) usam um segmento de servidor com escopo que inclui o nome do plugin: `mcp__plugin_<plugin-name>_<server-name>__<tool>`. Um matcher escrito contra a chave do servidor simples nunca dispara para essas ferramentas. Para um plugin nomeado `my-plugin` que agrupa um servidor sob a chave `db`, uma ferramenta `query` aparece como `mcp__plugin_my-plugin_db__query`, então o matcher para cada ferramenta daquele servidor é `mcp__plugin_my-plugin_db__.*`. Use o mesmo nome de ferramenta com escopo no campo [`if`](#common-fields) de um manipulador. Consulte [Servidores MCP fornecidos por plugin](/docs/pt/mcp#plugin-provided-mcp-servers) para saber como o nome com escopo é construído.
386 382
387Este exemplo registra todas as operações do servidor memory e valida operações de escrita de qualquer servidor MCP:383Este exemplo registra todas as operações do servidor memory e valida operações de escrita de qualquer servidor MCP:
919| :- | :- | :- |915| :- | :- | :- |
920| `PreToolUse` | Sim | Bloqueia a chamada da ferramenta |916| `PreToolUse` | Sim | Bloqueia a chamada da ferramenta |
921| `PermissionRequest` | Não | Código de saída 2 não é honrado para este evento e o fluxo de permissão prossegue inalterado. Negue através do objeto [`decision`](#permissionrequest-decision-control) em vez disso |917| `PermissionRequest` | Não | Código de saída 2 não é honrado para este evento e o fluxo de permissão prossegue inalterado. Negue através do objeto [`decision`](#permissionrequest-decision-control) em vez disso |
922| `UserPromptSubmit` | Sim | Bloqueia o processamento de prompt e apaga o prompt |918| `UserPromptSubmit` | Sim | Bloqueia o prompt, para que nunca chegue ao Claude. Consulte [O que um prompt bloqueado deixa para trás](#what-a-blocked-prompt-leaves-behind) |
923| `UserPromptExpansion` | Sim | Bloqueia a expansão |919| `UserPromptExpansion` | Sim | Bloqueia a expansão |
924| `Stop` | Sim | Previne Claude de parar, continua a conversa |920| `Stop` | Sim | Previne Claude de parar, continua a conversa |
925| `SubagentStop` | Sim | Previne o subagente de parar |921| `SubagentStop` | Sim | Previne o subagente de parar |
1175 SessionStart1171 SessionStart
1176</h3>1172</h3>
1177 1173
1178Executado quando Claude Code inicia uma nova sessão ou retoma uma sessão existente. Útil para carregar contexto de desenvolvimento como problemas existentes ou mudanças recentes no seu código, ou configurar variáveis de ambiente. Para contexto estático que não requer um script, use [CLAUDE.md](/docs/pt/memory) em vez disso.1174Executa quando Claude Code inicia uma nova sessão ou retoma uma sessão existente. Útil para carregar contexto de desenvolvimento como problemas existentes ou mudanças recentes no seu código, ou configurar variáveis de ambiente. Para contexto estático que não requer um script, use [CLAUDE.md](/docs/pt/memory) em vez disso.
1179 1175
1180SessionStart é executado em cada sessão, portanto mantenha esses hooks rápidos. Apenas hooks `type: "command"` e `type: "mcp_tool"` são suportados. Veja [campos de hook de ferramenta MCP](#mcp-tool-hook-fields) para quando hooks `mcp_tool` são executados.1176SessionStart é executado em cada sessão, então mantenha esses hooks rápidos. Apenas hooks `type: "command"` e `type: "mcp_tool"` são suportados. Veja [campos de hook de ferramenta MCP](#mcp-tool-hook-fields) para quando hooks `mcp_tool` são executados.
1181 1177
1182O valor do matcher corresponde a como a sessão foi iniciada:1178O valor do matcher corresponde a como a sessão foi iniciada:
1183 1179
1187| `resume` | `--resume`, `--continue`, ou `/resume` |1183| `resume` | `--resume`, `--continue`, ou `/resume` |
1188| `clear` | `/clear` |1184| `clear` | `/clear` |
1189| `compact` | Compactação automática ou manual |1185| `compact` | Compactação automática ou manual |
1190| `fork` | Uma nova sessão bifurcada de uma existente: `--fork-session` com `--resume` ou `--continue`, a cópia de fundo `/fork`, ou `/branch` |1186| `fork` | Uma nova sessão bifurcada de uma existente: `--fork-session` com `--resume` ou `--continue`, a cópia de fundo `/fork`, `/branch` ou uma conversa que você [move para o fundo](/docs/pt/agent-view#from-inside-a-session) |
1191 1187
1192Antes da v2.1.214, sessões bifurcadas relatavam fonte `"resume"`.1188Antes da v2.1.214, sessões bifurcadas relatavam fonte `"resume"`.
1193 1189
1194Quando você inicia uma sessão interativa, retoma uma conversa no lançamento com `--continue` ou `--resume`, ou executa `/clear`, hooks SessionStart são executados em segundo plano. Você pode digitar imediatamente, e uma conversa que você retomou aparece sem esperar pelos hooks. A primeira resposta de Claude ainda espera os hooks terminarem, portanto seu contexto chega a Claude.1190Quando você inicia uma sessão interativa, retoma uma conversa no lançamento com `--continue` ou `--resume`, ou executa `/clear`, hooks SessionStart são executados em segundo plano. Você pode digitar imediatamente, e uma conversa que você retomou aparece sem esperar pelos hooks. A primeira resposta do Claude ainda espera os hooks terminarem, então seu contexto chega ao Claude.
1195 1191
1196Quando você muda de conversas com `/resume` dentro de uma sessão, a mudança espera os hooks terminarem. Se você executar `/clear` ou mudar para outra conversa enquanto hooks de fundo ainda estão em execução, nada que eles retornem se aplica à sessão.1192Quando você muda de conversas com `/resume` dentro de uma sessão, a mudança espera os hooks terminarem. Se você executar `/clear` ou mudar para outra conversa enquanto hooks de fundo ainda estão em execução, nada que eles retornem se aplica à sessão.
1197 1193
1198A mesma espera se aplica no lançamento, incluindo uma sessão retomada: um prompt que você envia enquanto hooks SessionStart ainda estão em execução não chega a Claude até que terminem.1194A mesma espera se aplica no lançamento, incluindo uma sessão retomada: um prompt que você envia enquanto hooks SessionStart ainda estão em execução não chega ao Claude até que terminem.
1199 1195
1200Durante qualquer espera, pressione `Esc` para levar o prompt de volta para a entrada sem enviá-lo. Os hooks continuam em execução.1196Durante qualquer espera, pressione `Esc` para levar o prompt de volta para a entrada sem enviá-lo. Os hooks continuam em execução.
1201 1197
1208| Campo | Descrição |1204| Campo | Descrição |
1209| :- | :- |1205| :- | :- |
1210| `source` | Como a sessão começou: `"startup"` para novas sessões, `"resume"` para sessões retomadas, `"clear"` após `/clear`, `"compact"` após compactação, ou `"fork"` para uma nova sessão bifurcada de uma existente |1206| `source` | Como a sessão começou: `"startup"` para novas sessões, `"resume"` para sessões retomadas, `"clear"` após `/clear`, `"compact"` após compactação, ou `"fork"` para uma nova sessão bifurcada de uma existente |
1211| `model` | O identificador do modelo ativo. Pode ser omitido, por exemplo após `/clear` ou quando uma sessão é restaurada através de recuperação de conversa, portanto verifique o campo antes de lê-lo |1207| `model` | O identificador do modelo ativo. Pode ser omitido, por exemplo após `/clear` ou quando uma sessão é restaurada através de recuperação de conversa, então verifique o campo antes de lê-lo |
1212| `agent_type` | O nome do agente, presente quando você inicia Claude Code com `claude --agent <name>` |1208| `agent_type` | O nome do agente, presente quando você inicia Claude Code com `claude --agent <name>` |
1213| `session_title` | O título da sessão atual se um já estiver definido, por exemplo via `--name` ou `/rename`. Um hook que emite `sessionTitle` pode verificar `session_title` primeiro para evitar sobrescrever um título que o usuário definiu explicitamente |1209| `session_title` | O título da sessão atual se um já estiver definido, por exemplo via `--name` ou `/rename`. Um hook que emite `sessionTitle` pode verificar `session_title` primeiro para evitar sobrescrever um título que o usuário definiu explicitamente |
1214 1210
1215Quando `source` é `"resume"` ou `"fork"` e a transcrição contém pelo menos uma resposta de Claude, hooks SessionStart também recebem os quatro campos abaixo. Seu hook pode usá-los para relatar qual é o custo de retomar uma conversa obsoleta antes da primeira solicitação, por exemplo em um [`systemMessage`](#json-output). Esses campos requerem Claude Code v2.1.251 ou posterior.1211Quando `source` é `"resume"` ou `"fork"` e a transcrição contém pelo menos uma resposta do Claude, hooks SessionStart também recebem os quatro campos abaixo. Seu hook pode usá-los para relatar qual é o custo de retomar uma conversa obsoleta antes da primeira solicitação, por exemplo em um [`systemMessage`](#json-output). Esses campos requerem Claude Code v2.1.251 ou posterior.
1216 1212
1217| Campo | Descrição |1213| Campo | Descrição |
1218| :- | :- |1214| :- | :- |
1242 Controle de decisão SessionStart1238 Controle de decisão SessionStart
1243</h4>1239</h4>
1244 1240
1245Claude Code adiciona stdout que [trata como texto simples](#exit-code-0) ao contexto de Claude. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar esses campos específicos do evento:1241Claude Code adiciona stdout que [trata como texto simples](#exit-code-0) ao contexto do Claude. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar esses campos específicos do evento:
1246 1242
1247| Campo | Descrição |1243| Campo | Descrição |
1248| :- | :- |1244| :- | :- |
1249| `additionalContext` | String adicionada ao contexto de Claude no início da conversa, antes do primeiro prompt. Veja [Adicionar contexto para Claude](#add-context-for-claude) para como o texto é entregue e o que colocar nele |1245| `additionalContext` | String adicionada ao contexto do Claude no início da conversa, antes do primeiro prompt. Veja [Adicionar contexto para Claude](#add-context-for-claude) para como o texto é entregue e o que colocar nele |
1250| `initialUserMessage` | String usada como a primeira mensagem do usuário da sessão. Aplica-se em [modo não interativo](/docs/pt/headless) com a flag `-p`, onde se torna o primeiro turno mesmo que nenhum prompt seja fornecido. Se um prompt for fornecido, ele segue como o próximo turno. Ao contrário de `additionalContext`, que se anexa a um turno existente, isso cria o turno |1246| `initialUserMessage` | String usada como a primeira mensagem do usuário da sessão. Aplica-se em [modo não interativo](/docs/pt/headless) com a flag `-p`, onde se torna o primeiro turno mesmo que nenhum prompt seja fornecido. Se um prompt for fornecido, ele segue como o próximo turno. Ao contrário de `additionalContext`, que se anexa a um turno existente, isso cria o turno |
1251| `sessionTitle` | Define o título da sessão, com o mesmo efeito de `/rename`. Use para nomear sessões automaticamente a partir da pasta de lançamento, branch git ou nome de worktree. Aplica-se quando `source` é `"startup"`, `"resume"` ou `"fork"`; ignorado em `"clear"` e `"compact"` |1247| `sessionTitle` | Define o título da sessão, com o mesmo efeito de `/rename`. Use para nomear sessões automaticamente a partir da pasta de lançamento, branch git ou nome de worktree. Aplica-se quando `source` é `"startup"`, `"resume"` ou `"fork"`; ignorado em `"clear"` e `"compact"` |
1252| `watchPaths` | Array de caminhos absolutos para observar eventos [FileChanged](#filechanged) durante esta sessão |1248| `watchPaths` | Array de caminhos absolutos para observar eventos [FileChanged](#filechanged) durante esta sessão |
1253| `reloadSkills` | Booleano. Quando `true`, Claude Code verifica novamente os diretórios de [skill](/docs/pt/skills) e comando após os hooks SessionStart serem concluídos, portanto skills que o hook instalou estão disponíveis na mesma sessão, começando com o primeiro prompt |1249| `reloadSkills` | Booleano. Quando `true`, Claude Code verifica novamente os diretórios de [skill](/docs/pt/skills) e comando após os hooks SessionStart serem concluídos, para que skills que o hook instalou estejam disponíveis na mesma sessão, começando com o primeiro prompt |
1254 1250
1255```json theme={null}1251```json theme={null}
1256{1252{
1262}1258}
1263```1259```
1264 1260
1265Como stdout simples já chega a Claude para este evento, um hook que apenas carrega contexto pode imprimir para stdout diretamente sem construir JSON. Use o formulário JSON quando você precisar combinar contexto com outros campos como `sessionTitle`.1261Como stdout simples já chega ao Claude para este evento, um hook que apenas carrega contexto pode imprimir para stdout diretamente sem construir JSON. Use a forma JSON quando você precisa combinar contexto com outros campos como `sessionTitle`.
1266 1262
1267Use `reloadSkills` quando um hook SessionStart instala ou atualiza skills. A descoberta de skills normalmente é executada antes dos hooks SessionStart terminarem, portanto arquivos que o hook escreve em `~/.claude/skills/` ou `.claude/skills/` caso contrário apareceriam apenas na próxima sessão. Este exemplo sincroniza um repositório de skills compartilhado e solicita a nova verificação:1263Use `reloadSkills` quando um hook SessionStart instala ou atualiza skills. A descoberta de skills normalmente é executada antes dos hooks SessionStart terminarem, então arquivos que o hook escreve em `~/.claude/skills/` ou `.claude/skills/` caso contrário só apareceriam na próxima sessão. Este exemplo sincroniza um repositório de skills compartilhado e solicita a nova verificação:
1268 1264
1269```bash theme={null}1265```bash theme={null}
1270#!/bin/bash1266#!/bin/bash
1275echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1271echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'
1276```1272```
1277 1273
1278A URL do repositório é um espaço reservado; substitua-a pelo seu próprio repositório de skills. Com o espaço reservado, o clone falha e imprime uma mensagem `fatal:` para stderr. Stderr de um hook SessionStart que sai com 0 é apenas informativo, portanto a solicitação `reloadSkills` ainda se aplica.1274A URL do repositório é um espaço reservado; substitua-a pelo seu próprio repositório de skills. Com o espaço reservado, o clone falha e imprime uma mensagem `fatal:` para stderr. Stderr de um hook SessionStart que sai com 0 é apenas informativo, então a solicitação `reloadSkills` ainda se aplica.
1279 1275
1280<h4 id="persist-environment-variables">1276<h4 id="persist-environment-variables">
1281 Persistir variáveis de ambiente1277 Persistir variáveis de ambiente
1324 Setup1320 Setup
1325</h3>1321</h3>
1326 1322
1327Disparado apenas quando você inicia Claude Code com `--init-only`, ou com `--init` ou `--maintenance` em [modo não interativo](/docs/pt/headless) com a flag `-p`. Não é disparado no startup normal. Use-o para instalação de dependência única ou limpeza agendada que você dispara explicitamente de CI ou scripts, separado do startup normal da sessão. Para inicialização por sessão, use [SessionStart](#sessionstart) em vez disso.1323Dispara apenas quando você inicia Claude Code com `--init-only`, ou com `--init` ou `--maintenance` em [modo não interativo](/docs/pt/headless) com a flag `-p`. Não dispara no startup normal. Use-o para instalação de dependência única ou limpeza agendada que você dispara explicitamente de CI ou scripts, separado do startup normal da sessão. Para inicialização por sessão, use [SessionStart](#sessionstart) em vez disso.
1328 1324
1329O valor do matcher corresponde à flag CLI que disparou o hook:1325O valor do matcher corresponde à flag CLI que disparou o hook:
1330 1326
1339 1335
1340No sucesso, `--init-only` não imprime nada no terminal. Para confirmar que os hooks foram executados, comece com `claude --debug-file <path> --init-only`, substituindo `<path>` por um local de arquivo de log, e verifique o log para as entradas de hook Setup e SessionStart.1336No sucesso, `--init-only` não imprime nada no terminal. Para confirmar que os hooks foram executados, comece com `claude --debug-file <path> --init-only`, substituindo `<path>` por um local de arquivo de log, e verifique o log para as entradas de hook Setup e SessionStart.
1341 1337
1342Como Setup não é disparado a cada lançamento, um plugin que precisa de uma dependência instalada não pode contar apenas com Setup. O padrão prático é verificar a dependência no primeiro uso e instalar se ausente, por exemplo um hook ou skill que testa `${CLAUDE_PLUGIN_DATA}/node_modules` e executa `npm install` se ausente. Veja o [diretório de dados persistentes](/docs/pt/plugins/components#path-variables-and-persistent-data) para onde armazenar dependências instaladas. Se você distribuir seu plugin através de um marketplace, você pode não precisar deste padrão: Claude Code [instala automaticamente dependências de pacote Node.js elegíveis](/docs/pt/plugins/loading#node-js-package-dependencies) quando armazena em cache o plugin.1338Como Setup não dispara em cada lançamento, um plugin que precisa de uma dependência instalada não pode contar apenas com Setup. O padrão prático é verificar a dependência no primeiro uso e instalar se ausente, por exemplo um hook ou skill que testa `${CLAUDE_PLUGIN_DATA}/node_modules` e executa `npm install` se ausente. Veja o [diretório de dados persistentes](/docs/pt/plugins/components#path-variables-and-persistent-data) para onde armazenar dependências instaladas. Se você distribuir seu plugin através de um marketplace, você pode não precisar deste padrão: Claude Code [instala automaticamente dependências de pacote Node.js elegíveis](/docs/pt/plugins/loading#node-js-package-dependencies) quando armazena em cache o plugin.
1343 1339
1344<h4 id="setup-input">1340<h4 id="setup-input">
1345 Entrada Setup1341 Entrada Setup
1361 Controle de decisão Setup1357 Controle de decisão Setup
1362</h4>1358</h4>
1363 1359
1364Hooks Setup não podem bloquear; a execução continua em qualquer código de saída. Em cada código de saída, Claude Code descarta os [campos de saída JSON](#json-output) de um hook Setup, como `systemMessage`, `continue` e `hookSpecificOutput.additionalContext`. Com `-p`, stdout, stderr e código de saída de um hook Setup aparecem na saída da execução apenas como [eventos `hook_response`](/docs/pt/headless#read-session-metadata) quando você inicia com `--output-format stream-json --verbose`.1360Hooks Setup não podem bloquear; a execução continua em qualquer código de saída. Em cada código de saída, Claude Code descarta [campos de saída JSON](#json-output) de um hook Setup, como `systemMessage`, `continue` e `hookSpecificOutput.additionalContext`. Com `-p`, stdout, stderr e código de saída de um hook Setup aparecem na saída da execução apenas como [eventos `hook_response`](/docs/pt/headless#read-session-metadata) quando você inicia com `--output-format stream-json --verbose`.
1365 1361
1366Hooks Setup têm acesso a `CLAUDE_ENV_FILE`. Variáveis escritas nesse arquivo persistem em comandos Bash subsequentes para a sessão, assim como em [hooks SessionStart](#persist-environment-variables). Apenas hooks `type: "command"` são executados em `Setup`. Um hook `type: "mcp_tool"` em `Setup` é sempre ignorado, conforme descrito em [campos de hook de ferramenta MCP](#mcp-tool-hook-fields).1362Hooks Setup têm acesso a `CLAUDE_ENV_FILE`. Variáveis escritas nesse arquivo persistem em comandos Bash subsequentes para a sessão, assim como em [hooks SessionStart](#persist-environment-variables). Apenas hooks `type: "command"` são executados em `Setup`. Um hook `type: "mcp_tool"` em `Setup` é sempre ignorado, conforme descrito em [campos de hook de ferramenta MCP](#mcp-tool-hook-fields).
1367 1363
1369 InstructionsLoaded1365 InstructionsLoaded
1370</h3>1366</h3>
1371 1367
1372Disparado quando um arquivo `CLAUDE.md` ou `.claude/rules/*.md` é carregado no contexto. Este evento é disparado no início da sessão para arquivos carregados com entusiasmo e novamente mais tarde quando arquivos são carregados preguiçosamente, por exemplo quando Claude acessa um subdiretório que contém um `CLAUDE.md` aninhado ou quando regras condicionais com frontmatter `paths:` correspondem. O hook não suporta bloqueio ou controle de decisão. Ele é executado de forma assíncrona para fins de observabilidade.1368Dispara quando um arquivo `CLAUDE.md` ou `.claude/rules/*.md` é carregado no contexto. Este evento dispara no início da sessão para arquivos carregados com entusiasmo e novamente mais tarde quando arquivos são carregados preguiçosamente, por exemplo quando Claude acessa um subdiretório que contém um `CLAUDE.md` aninhado ou quando regras condicionais com frontmatter `paths:` correspondem. O hook não suporta bloqueio ou controle de decisão. Ele é executado de forma assíncrona para fins de observabilidade.
1373 1369
1374Este evento não é disparado quando Claude [lê `AGENTS.md` diretamente](/docs/pt/memory#agents-md) através 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 symlink para ele, como um carregamento normal de `CLAUDE.md`.1370Este evento não dispara quando Claude [lê `AGENTS.md` diretamente](/docs/pt/memory#agents-md) através da configuração **Project instructions**. Ele dispara quando um `CLAUDE.md` importa seu `AGENTS.md`, com `load_reason` definido como `include` como para qualquer outro arquivo importado, e quando `CLAUDE.md` é um symlink para ele, como um carregamento normal de `CLAUDE.md`.
1375 1371
1376O matcher é executado contra `load_reason`. Por exemplo, use `"matcher": "session_start"` para disparar apenas para arquivos carregados no início da sessão, ou `"matcher": "path_glob_match|nested_traversal"` para disparar apenas para carregamentos preguiçosos.1372O matcher é executado contra `load_reason`. Por exemplo, use `"matcher": "session_start"` para disparar apenas para arquivos carregados no início da sessão, ou `"matcher": "path_glob_match|nested_traversal"` para disparar apenas para carregamentos preguiçosos.
1377 1373
1385| :- | :- |1381| :- | :- |
1386| `file_path` | Caminho absoluto para o arquivo de instrução que foi carregado |1382| `file_path` | Caminho absoluto para o arquivo de instrução que foi carregado |
1387| `memory_type` | Escopo do arquivo: `"User"`, `"Project"`, `"Local"` ou `"Managed"` |1383| `memory_type` | Escopo do arquivo: `"User"`, `"Project"`, `"Local"` ou `"Managed"` |
1388| `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ção são recarregados após um evento de compactação |1384| `load_reason` | Por que o arquivo foi carregado: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"` ou `"compact"`. O valor `"compact"` dispara quando arquivos de instrução são recarregados após um evento de compactação |
1389| `globs` | Padrões de glob de caminho do frontmatter `paths:` do arquivo, se houver. Presente apenas para carregamentos `path_glob_match` |1385| `globs` | Padrões de glob de caminho do frontmatter `paths:` do arquivo, se houver. Presente apenas para carregamentos `path_glob_match` |
1390| `trigger_file_path` | Caminho para o arquivo cujo acesso disparou este carregamento, para carregamentos preguiçosos |1386| `trigger_file_path` | Caminho para o arquivo cujo acesso disparou este carregamento, para carregamentos preguiçosos |
1391| `parent_file_path` | Caminho para o arquivo de instrução pai que incluiu este, para carregamentos `include` |1387| `parent_file_path` | Caminho para o arquivo de instrução pai que incluiu este, para carregamentos `include` |
1412 UserPromptSubmit1408 UserPromptSubmit
1413</h3>1409</h3>
1414 1410
1415Executado quando o usuário envia um prompt, antes de Claude processá-lo. Isso permite que você adicione contexto adicional com base no prompt/conversa, valide prompts ou bloqueie certos tipos de prompts.1411Executa quando o usuário envia um prompt, antes de Claude processá-lo. Isso permite que você adicione contexto adicional com base no prompt/conversa, valide prompts ou bloqueie certos tipos de prompts.
1416 1412
1417Hooks `UserPromptSubmit` têm um tempo limite padrão de 30 segundos para tipos `command`, `http` e `mcp_tool`, mais curto que o padrão de 600 segundos para esses tipos na maioria dos outros eventos. Como este hook é executado antes de cada prompt e bloqueia o processamento do modelo até ser concluído, um hook travado paralisa a sessão. Se seu hook precisar de mais tempo, defina o campo `timeout` na entrada do hook.1413Hooks `UserPromptSubmit` têm um tempo limite padrão de 30 segundos para tipos `command`, `http` e `mcp_tool`, mais curto que o padrão de 600 segundos para esses tipos na maioria dos outros eventos. Como este hook é executado antes de cada prompt e bloqueia o processamento do modelo até ser concluído, um hook travado paralisa a sessão. Se seu hook precisar de mais tempo, defina o campo `timeout` na entrada do hook.
1418 1414
1419Além de um hook de comando que você executa com [`async: true`](#run-hooks-in-the-background), um hook `UserPromptSubmit` command, HTTP ou MCP tool que atinge seu tempo limite é cancelado e sua saída, incluindo qualquer `additionalContext`, é descartada. O prompt ainda chega a Claude sem esse contexto. A transcrição mostra um aviso nomeando o hook, o tempo limite que foi disparado e que a saída foi descartada.1415Além de um hook de comando que você executa com [`async: true`](#run-hooks-in-the-background), um hook `UserPromptSubmit` command, HTTP ou MCP tool que atinge seu tempo limite é cancelado e sua saída, incluindo qualquer `additionalContext`, é descartada. O prompt ainda chega ao Claude sem esse contexto. A transcrição mostra um aviso nomeando o hook, o tempo limite que disparou e que a saída foi descartada.
1420 1416
1421Um [hook de callback do Agent SDK](/docs/pt/agent-sdk/hooks) em `UserPromptSubmit` que atinge seu tempo limite bloqueia o prompt com uma mensagem nomeando o hook e o tempo limite, porque um callback lá pode estar agindo como um portão de política que não deve falhar aberto. A sessão continua. Antes da v2.1.208, um tempo limite de callback nesse evento terminava o turno com um erro de execução.1417Um hook de callback [Agent SDK](/docs/pt/agent-sdk/hooks) em `UserPromptSubmit` que atinge seu tempo limite bloqueia o prompt com uma mensagem nomeando o hook e o tempo limite, porque um callback lá pode estar agindo como uma porta de política que não deve falhar aberta. A sessão continua. Antes da v2.1.208, um tempo limite de callback naquele evento terminava o turno com um erro de execução.
1422 1418
1423<h4 id="userpromptsubmit-input">1419<h4 id="userpromptsubmit-input">
1424 Entrada UserPromptSubmit1420 Entrada UserPromptSubmit
1425</h4>1421</h4>
1426 1422
1427Além dos [campos de entrada comuns](#common-input-fields), hooks UserPromptSubmit recebem o campo `prompt` contendo o texto que o usuário enviou. Conteúdo colado que colapsou para um espaço reservado `[Pasted text #N]` chega expandido no lugar. Em sessões onde Claude Code [marca texto colado para Claude](/docs/pt/terminal-config#how-claude-treats-pasted-text), esse conteúdo expandido fica entre uma linha `<pasted_content id="…">` e uma linha `</pasted_content id="…">`, portanto leve em conta essas linhas se seu hook analisa o prompt.1423Além dos [campos de entrada comuns](#common-input-fields), hooks UserPromptSubmit recebem o campo `prompt` contendo o texto que o usuário enviou. Conteúdo colado que colapsou para um espaço reservado `[Pasted text #N]` chega expandido no lugar. Em sessões onde Claude Code [marca texto colado para Claude](/docs/pt/terminal-config#how-claude-treats-pasted-text), esse conteúdo expandido fica entre uma linha `<pasted_content id="…">` e uma linha `</pasted_content id="…">`, então leve em conta essas linhas se seu hook analisa o prompt.
1428 1424
1429```json theme={null}1425```json theme={null}
1430{1426{
1445 1441
1446Existem duas maneiras de adicionar contexto à conversa no código de saída 0:1442Existem duas maneiras de adicionar contexto à conversa no código de saída 0:
1447 1443
1448* **Stdout de texto simples**: Claude Code adiciona stdout que [trata como texto simples](#exit-code-0) ao contexto de Claude1444* **Stdout de texto simples**: Claude Code adiciona stdout que [trata como texto simples](#exit-code-0) ao contexto do Claude
1449* **JSON com `additionalContext`**: use o formato JSON abaixo para mais controle. O campo `additionalContext` é adicionado como contexto1445* **JSON com `additionalContext`**: use o formato JSON abaixo para mais controle. O campo `additionalContext` é adicionado como contexto
1450 1446
1451Nenhum canal produz uma entrada de transcrição visível. Stdout simples e o valor `additionalContext` são cada um injetados como um lembrete do sistema que começa com o nome do hook; Claude lê ambos. Para confirmar a entrega, verifique o [log de depuração](#debug-hooks).1447Nenhum canal produz uma entrada de transcrição visível. Stdout simples e o valor `additionalContext` são cada um injetados como um lembrete do sistema que começa com o nome do hook; Claude lê ambos. Para confirmar a entrega, verifique o [log de depuração](#debug-hooks).
1454 1450
1455| Campo | Descrição |1451| Campo | Descrição |
1456| :- | :- |1452| :- | :- |
1457| `decision` | `"block"` impede que o prompt seja processado e o apaga do contexto. Omita para permitir que o prompt prossiga |1453| `decision` | `"block"` impede que o prompt seja processado. Omita para permitir que o prompt prossiga |
1458| `reason` | Mostrado ao usuário quando `decision` é `"block"`. Não adicionado ao contexto |1454| `reason` | Mostrado ao usuário quando `decision` é `"block"`. Não adicionado ao contexto |
1459| `additionalContext` | String adicionada ao contexto de Claude ao lado do prompt enviado. Veja [Adicionar contexto para Claude](#add-context-for-claude) |1455| `additionalContext` | String adicionada ao contexto do Claude junto com o prompt enviado. Veja [Adicionar contexto para Claude](#add-context-for-claude) |
1460| `sessionTitle` | Define o título da sessão. Use para nomear sessões automaticamente com base no conteúdo do prompt |1456| `sessionTitle` | Define o título da sessão. Use para nomear sessões automaticamente com base no conteúdo do prompt |
1461| `suppressOriginalPrompt` | Se `true` quando `decision` é `"block"`, omite o texto do prompt original da mensagem de bloqueio mostrada ao usuário |1457| `suppressOriginalPrompt` | Se `true` quando o hook bloqueia o prompt, deixa o texto do prompt original fora da mensagem de bloqueio. Veja [O que um prompt bloqueado deixa para trás](#what-a-blocked-prompt-leaves-behind) |
1462 1458
1463Um hook que bloqueia ao sair com 2 roteia da mesma forma que `reason`: a mensagem de bloqueio mostra o texto stderr ao usuário, e não é adicionada ao contexto.1459Um hook que bloqueia ao sair com 2 roteia da mesma forma que `reason`: a mensagem de bloqueio mostra o texto stderr ao usuário, e não é adicionada ao contexto.
1464 1460
1469 "hookSpecificOutput": {1465 "hookSpecificOutput": {
1470 "hookEventName": "UserPromptSubmit",1466 "hookEventName": "UserPromptSubmit",
1471 "additionalContext": "My additional context here",1467 "additionalContext": "My additional context here",
1472 "sessionTitle": "My session title"1468 "sessionTitle": "My session title",
1469 "suppressOriginalPrompt": true
1473 }1470 }
1474}1471}
1475```1472```
1476 1473
1474<h4 id="what-a-blocked-prompt-leaves-behind">
1475 O que um prompt bloqueado deixa para trás
1476</h4>
1477
1478Um prompt bloqueado nunca chega ao Claude, mas seu texto não é removido em todos os lugares. Por padrão, a mensagem de bloqueio mostrada ao usuário termina com `Original prompt:` seguido pelo texto enviado, e Claude Code escreve essa mensagem no arquivo de transcrição da sessão no disco. Para deixar o texto fora da mensagem, imprima JSON com `"suppressOriginalPrompt": true` dentro de `hookSpecificOutput`. Isso funciona se o hook bloqueia com `decision: "block"` ou ao sair com 2. Um hook de saída 2 que não imprime JSON sempre obtém o texto do prompt em sua mensagem de bloqueio.
1479
1480`suppressOriginalPrompt` muda apenas a mensagem de bloqueio. O texto enviado ainda pode aparecer em arquivos locais como a transcrição da sessão e seu histórico de prompts, então um hook de bloqueio não é uma maneira de manter um segredo fora do disco. Para limitar ou remover esses arquivos, veja [Armazenamento em texto simples](/docs/pt/claude-directory#plaintext-storage) e [Limpar dados locais](/docs/pt/claude-directory#clear-local-data).
1481
1477<h3 id="userpromptexpansion">1482<h3 id="userpromptexpansion">
1478 UserPromptExpansion1483 UserPromptExpansion
1479</h3>1484</h3>
1480 1485
1481Executado quando um comando digitado pelo usuário se expande em um prompt antes de chegar a Claude. Use isso para bloquear comandos específicos de invocação direta, injetar contexto para uma skill particular ou registrar quais comandos os usuários invocam. Por exemplo, um hook correspondente a `deploy` pode bloquear `/deploy` a menos que um arquivo de aprovação esteja presente, ou um hook correspondente a uma skill de revisão pode anexar a lista de verificação de revisão da equipe como `additionalContext`.1486Executa quando um comando digitado pelo usuário se expande em um prompt antes de chegar ao Claude. Use isso para bloquear comandos específicos de invocação direta, injetar contexto para uma skill particular ou registrar quais comandos os usuários invocam. Por exemplo, um hook correspondente a `deploy` pode bloquear `/deploy` a menos que um arquivo de aprovação esteja presente, ou um hook correspondente a uma skill de revisão pode anexar a lista de verificação de revisão da equipe como `additionalContext`.
1482 1487
1483Este evento cobre o caminho que `PreToolUse` não cobre: um hook `PreToolUse` correspondente à ferramenta `Skill` é disparado apenas quando Claude chama a ferramenta, mas digitar `/skillname` diretamente ignora `PreToolUse`. `UserPromptExpansion` é disparado nesse caminho direto.1488Este evento cobre o caminho que `PreToolUse` não cobre: um hook `PreToolUse` correspondente à ferramenta `Skill` dispara apenas quando Claude chama a ferramenta, mas digitar `/skillname` diretamente ignora `PreToolUse`. `UserPromptExpansion` dispara naquele caminho direto.
1484 1489
1485Corresponde a `command_name`. Deixe o matcher vazio para disparar em cada comando do tipo prompt.1490Corresponde a `command_name`. Deixe o matcher vazio para disparar em cada comando do tipo prompt.
1486 1491
1515| :- | :- |1520| :- | :- |
1516| `decision` | `"block"` impede que o comando se expanda. Omita para permitir que prossiga |1521| `decision` | `"block"` impede que o comando se expanda. Omita para permitir que prossiga |
1517| `reason` | Mostrado ao usuário quando `decision` é `"block"` |1522| `reason` | Mostrado ao usuário quando `decision` é `"block"` |
1518| `additionalContext` | String adicionada ao contexto de Claude ao lado do prompt expandido. Veja [Adicionar contexto para Claude](#add-context-for-claude) |1523| `additionalContext` | String adicionada ao contexto do Claude junto com o prompt expandido. Veja [Adicionar contexto para Claude](#add-context-for-claude) |
1519 1524
1520Um hook que bloqueia ao sair com 2 roteia da mesma forma que `reason`: a mensagem de bloqueio mostra o texto stderr ao usuário.1525Um hook que bloqueia ao sair com 2 roteia da mesma forma que `reason`: a mensagem de bloqueio mostra o texto stderr ao usuário.
1521 1526
1534 MessageDisplay1539 MessageDisplay
1535</h3>1540</h3>
1536 1541
1537Executado enquanto uma mensagem do assistente é transmitida para a tela. Claude Code exibe a mensagem em incrementos: cada vez que um lote de linhas recém-concluídas está pronto para renderizar, o hook é executado uma vez com essas linhas e Claude Code renderiza o texto de substituição do hook em seu lugar. Uma mensagem longa produz várias chamadas; uma mensagem curta pode produzir apenas uma.1542Executa enquanto uma mensagem do assistente é transmitida para a tela. Claude Code exibe a mensagem em incrementos: cada vez que um lote de linhas recém-concluídas está pronto para renderizar, o hook é executado uma vez com essas linhas e Claude Code renderiza o texto de substituição do hook em seu lugar. Uma mensagem longa produz várias chamadas; uma mensagem curta pode produzir apenas uma.
1538 1543
1539Use MessageDisplay para:1544Use MessageDisplay para:
1540 1545
1541* remover markdown para uma exibição mínima1546* remover markdown para uma exibição mínima
1542* transformar o texto que um aplicativo Agent SDK mostra aos seus usuários1547* transformar o texto que um aplicativo Agent SDK mostra aos seus usuários
1543* redactar chaves de API ou nomes de host internos das respostas de Claude1548* redactar chaves de API ou nomes de host internos das respostas do Claude
1544 1549
1545Claude Code mantém cada lote até que seu hook retorne, portanto mantenha o hook rápido. Se o hook falhar ou atingir o tempo limite, Claude Code exibe o texto original. O tempo limite padrão para este evento é 10 segundos; se seu hook precisar de mais tempo, defina o campo `timeout` na entrada do hook.1550Claude Code mantém cada lote até que seu hook retorne, então mantenha o hook rápido. Se o hook falhar ou atingir o tempo limite, Claude Code exibe o texto original. O tempo limite padrão para este evento é 10 segundos; se seu hook precisar de mais tempo, defina o campo `timeout` na entrada do hook.
1546 1551
1547MessageDisplay é apenas para exibição: o texto de substituição altera apenas o que é renderizado na tela. A transcrição e o que Claude vê mantêm o texto original, portanto Claude nunca vê a substituição, e o modo detalhado mostra o original. O hook recebe apenas texto de mensagem do assistente, portanto resultados de ferramentas e o texto que você digita são renderizados inalterados.1552MessageDisplay é apenas para exibição: o texto de substituição muda apenas o que é renderizado na tela. A transcrição e o que Claude vê mantêm o texto original, então Claude nunca vê a substituição, e o modo detalhado mostra o original. O hook recebe apenas texto de mensagem do assistente, então resultados de ferramentas e o texto que você digita são renderizados inalterados.
1548 1553
1549MessageDisplay não suporta matchers e é disparado para cada mensagem do assistente que transmite texto; mensagens sem texto, como respostas apenas de chamada de ferramenta, não o disparam.1554MessageDisplay não suporta matchers e dispara para cada mensagem do assistente que transmite texto; mensagens sem texto, como respostas apenas de chamada de ferramenta, não o disparam.
1550 1555
1551Em execuções não interativas, incluindo consultas do Agent SDK e `claude -p`, MessageDisplay é executado uma vez por mensagem do assistente em vez de uma vez por lote de linhas. A chamada única chega após a mensagem ser concluída e carrega o texto completo da mensagem: `index` é `0`, `final` é `true` e `delta` contém a mensagem inteira. Um hook que coleta o texto `delta` para cada mensagem recebe o mesmo texto total em ambos os modos.1556Em execuções não interativas, incluindo consultas Agent SDK e `claude -p`, MessageDisplay é executado uma vez por mensagem do assistente em vez de uma vez por lote de linhas. A chamada única chega após a mensagem ser concluída e carrega o texto completo da mensagem: `index` é `0`, `final` é `true` e `delta` contém a mensagem inteira. Um hook que coleta o texto `delta` para cada mensagem recebe o mesmo texto total em ambos os modos.
1552 1557
1553<h4 id="messagedisplay-input">1558<h4 id="messagedisplay-input">
1554 Entrada MessageDisplay1559 Entrada MessageDisplay
1555</h4>1560</h4>
1556 1561
1557Além dos [campos de entrada comuns](#common-input-fields), hooks MessageDisplay recebem identificadores para o turno e mensagem, a posição desta chamada dentro da mensagem e o novo texto em `delta`. Os limites de lote dependem de como o texto é transmitido, portanto use `index` e `final` para rastrear o progresso através de uma mensagem em vez de esperar que as linhas sejam agrupadas de uma forma particular.1562Além dos [campos de entrada comuns](#common-input-fields), hooks MessageDisplay recebem identificadores para o turno e mensagem, a posição desta chamada dentro da mensagem e o novo texto em `delta`. Os limites de lote dependem de como o texto é transmitido, então use `index` e `final` para rastrear o progresso através de uma mensagem em vez de esperar que as linhas sejam agrupadas de uma forma particular.
1558 1563
1559| Campo | Descrição |1564| Campo | Descrição |
1560| :- | :- |1565| :- | :- |
1561| `turn_id` | UUID do turno atual |1566| `turn_id` | UUID do turno atual |
1562| `message_id` | UUID da mensagem do assistente sendo exibida. Estável em cada lote da mesma mensagem. Este não é o ID `msg_…` da API, portanto não pode ser correlacionado com IDs de mensagem de transcrição |1567| `message_id` | UUID da mensagem do assistente sendo exibida. Estável em cada lote da mesma mensagem. Este não é o ID `msg_…` da API, então não pode ser correlacionado com IDs de mensagem de transcrição |
1563| `index` | Índice baseado em zero deste lote dentro da mensagem |1568| `index` | Índice baseado em zero deste lote dentro da mensagem |
1564| `final` | `true` no último lote da mensagem. Cada mensagem tem exatamente um lote final |1569| `final` | `true` no último lote da mensagem. Cada mensagem tem exatamente um lote final |
1565| `delta` | As linhas recém-concluídas desde o lote anterior, incluindo quebras de linha finais. Sempre linhas inteiras, exceto o lote final que pode terminar no meio da linha. Em execuções interativas, o delta do lote final está vazio quando a mensagem termina em uma quebra de linha, portanto trate `final`, 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 |1570| `delta` | As linhas recém-concluídas desde o lote anterior, incluindo quebras de linha finais. Sempre linhas inteiras, exceto o lote final que pode terminar no meio da linha. Em execuções interativas, o delta do lote final está vazio quando a mensagem termina em uma quebra de linha, então trate `final`, não um delta não vazio, como o sinal de fim de mensagem. Em execuções Agent SDK e `claude -p`, a chamada única carrega a mensagem inteira |
1566 1571
1567```json theme={null}1572```json theme={null}
1568{1573{
1588| :- | :- |1593| :- | :- |
1589| `displayContent` | Texto exibido no lugar do delta. Omita para exibir o original |1594| `displayContent` | Texto exibido no lugar do delta. Omita para exibir o original |
1590 1595
1591Hooks MessageDisplay não têm controle de decisão. Eles não podem bloquear a mensagem ou alterar o que é armazenado na transcrição ou enviado a Claude. Claude Code atua em `displayContent` de sua saída JSON e descarta `systemMessage` e `continue`.1596Hooks MessageDisplay não têm controle de decisão. Eles não podem bloquear a mensagem ou mudar o que é armazenado na transcrição ou enviado ao Claude. Claude Code age em `displayContent` de sua saída JSON e descarta `systemMessage` e `continue`.
1592 1597
1593Este exemplo remove formatação markdown das respostas de Claude para uma exibição de texto simples. O script lê cada lote de stdin, remove marcadores em negrito e backticks de código inline de `delta` e retorna o resultado como `displayContent`.1598Este exemplo remove formatação markdown das respostas do Claude para uma exibição de texto simples. O script lê cada lote de stdin, remove marcadores em negrito e backticks de código inline de `delta` e retorna o resultado como `displayContent`.
1594 1599
1595<Tabs>1600<Tabs>
1596 <Tab title="macOS/Linux">1601 <Tab title="macOS/Linux">
1672 PreToolUse1677 PreToolUse
1673</h3>1678</h3>
1674 1679
1675Executado após Claude criar parâmetros de ferramenta e antes de processar a chamada de ferramenta. Corresponde a qualquer nome de ferramenta exceto `EndConversation`: ferramentas integradas como `Bash`, `PowerShell`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `Workflow`, `WebFetch`, `WebSearch`, `AskUserQuestion` e `ExitPlanMode`, e qualquer [nome de ferramenta MCP](#match-mcp-tools).1680Executa após Claude criar parâmetros de ferramenta e antes de processar a chamada de ferramenta. Corresponde a qualquer nome de ferramenta exceto `EndConversation`: ferramentas integradas como `Bash`, `PowerShell`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `Workflow`, `WebFetch`, `WebSearch`, `AskUserQuestion` e `ExitPlanMode`, e qualquer [nome de ferramenta MCP](#match-mcp-tools).
1676 1681
1677Para executar um hook quando um arquivo específico muda no disco, seja qual for o que o escreveu, use [FileChanged](#filechanged) em vez de corresponder a ferramentas de edição de arquivo por nome. Ao contrário de PreToolUse, Claude Code executa hooks FileChanged após a mudança, e eles não têm controle de decisão, portanto não podem bloquear a escrita.1682Para executar um hook quando um arquivo específico muda no disco, seja qual for o que o escreveu, use [FileChanged](#filechanged) em vez de corresponder a ferramentas de edição de arquivo por nome. Ao contrário de PreToolUse, Claude Code executa hooks FileChanged após a mudança, e eles não têm controle de decisão, então não podem bloquear a escrita.
1678 1683
1679<Warning>1684<Warning>
1680 PreToolUse é executado apenas quando Claude chama uma ferramenta. Arquivos que você [referencia com `@` em seu prompt](/docs/pt/common-workflows#reference-files-and-directories) são adicionados sem nenhuma chamada de ferramenta: Claude Code insere seu conteúdo ao construir o prompt, portanto nenhum hook PreToolUse é disparado para eles, incluindo hooks correspondentes a `Read`. Para bloquear caminhos específicos de referências `@`, use uma [regra de negação `Read`](/docs/pt/permissions#read-and-edit) em vez disso.1685 PreToolUse é executado apenas quando Claude chama uma ferramenta. Arquivos que você [referencia com `@` em seu prompt](/docs/pt/common-workflows#reference-files-and-directories) são adicionados sem nenhuma chamada de ferramenta: Claude Code insere seu conteúdo ao construir o prompt, então nenhum hook PreToolUse dispara para eles, incluindo hooks correspondentes a `Read`. Para bloquear caminhos específicos de referências `@`, use uma [regra de negação `Read`](/docs/pt/permissions#read-and-edit) em vez disso.
1681 1686
1682 PreToolUse também não é disparado para [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior).1687 PreToolUse também não dispara para [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior).
1683</Warning>1688</Warning>
1684 1689
1685Use [controle de decisão PreToolUse](#pretooluse-decision-control) para permitir, negar, perguntar ou adiar a chamada de ferramenta.1690Use [controle de decisão PreToolUse](#pretooluse-decision-control) para permitir, negar, perguntar ou adiar a chamada de ferramenta.
1686 1691
1687Um [hook de callback do Agent SDK](/docs/pt/agent-sdk/hooks) em `PreToolUse` que excede seu tempo limite bloqueia a chamada de ferramenta, e Claude recebe um resultado de erro nomeando o tempo limite. Uma negação explícita retornada por outro hook ainda tem precedência.1692Um hook de callback [Agent SDK](/docs/pt/agent-sdk/hooks) em `PreToolUse` que excede seu tempo limite bloqueia a chamada de ferramenta, e Claude recebe um resultado de erro nomeando o tempo limite. Uma negação explícita retornada por outro hook ainda tem precedência.
1688 1693
1689<h4 id="pretooluse-input">1694<h4 id="pretooluse-input">
1690 Entrada PreToolUse1695 Entrada PreToolUse
1692 1697
1693Além dos [campos de entrada comuns](#common-input-fields), hooks PreToolUse recebem `tool_name`, `tool_input` e `tool_use_id`.1698Além dos [campos de entrada comuns](#common-input-fields), hooks PreToolUse recebem `tool_name`, `tool_input` e `tool_use_id`.
1694 1699
1695Para uma [ferramenta MCP](#match-mcp-tools), a entrada também carrega `mcp_server`, um objeto com o `name` do servidor e uma `source` que diz de onde veio a definição do servidor. Os valores `source` incluem `plugin`, `sdk` e escopos de configuração como `user` e `project`. [`McpServerProvenance`](/docs/pt/agent-sdk/typescript#mcpserverprovenance) na referência do Agent SDK lista todos eles e diz como tratar um que você não reconhece. Baseie decisões de confiança em `source` em vez de em `name` ou no prefixo de nome de ferramenta `mcp__<server>__`. O campo `mcp_server` requer Claude Code v2.1.274 ou posterior.1700Para uma [ferramenta MCP](#match-mcp-tools), a entrada também carrega `mcp_server`, um objeto com o `name` do servidor e uma `source` que diz de onde veio a definição do servidor. Os valores `source` incluem `plugin`, `sdk` e escopos de configuração como `user` e `project`. [`McpServerProvenance`](/docs/pt/agent-sdk/typescript#mcpserverprovenance) na referência Agent SDK lista todos eles e diz como tratar um que você não reconhece. Baseie decisões de confiança em `source` em vez de em `name` ou no prefixo de nome de ferramenta `mcp__<server>__`. O campo `mcp_server` requer Claude Code v2.1.274 ou posterior.
1696 1701
1697Para as ferramentas de arquivo `Write`, `Edit` e `Read`, `tool_input.file_path` é sempre absoluto:1702Para as ferramentas de arquivo `Write`, `Edit` e `Read`, `tool_input.file_path` é sempre absoluto:
1698 1703
1699* Claude Code expande `~` e caminhos relativos antes dos hooks serem executados, portanto um hook que corresponde a caminhos não pode ser contornado via `~` ou uma ortografia relativa do mesmo caminho1704* Claude Code expande `~` e caminhos relativos antes dos hooks serem executados, então um hook que corresponde a caminhos não pode ser contornado via `~` ou uma ortografia relativa do mesmo caminho
1700* No Windows, o caminho chega com separadores de barra invertida, mesmo quando seu hook é executado sob Git Bash onde `$PWD` parece `/c/project`1705* No Windows, o caminho chega com separadores de barra invertida, mesmo quando seu hook é executado sob Git Bash onde `$PWD` parece `/c/project`
1701* Uma comparação escrita com barras para frente, como uma verificação `/src/`, nunca corresponde a um caminho de barra invertida, e a chamada de ferramenta prossegue como se o hook não tivesse nada a bloquear1706* Uma comparação escrita com barras para frente, como uma verificação `/src/`, nunca corresponde a um caminho de barra invertida, e a chamada de ferramenta prossegue como se o hook não tivesse nada a bloquear
1702* Normalize separadores antes de comparar: `FILE_PATH="${FILE_PATH//\\//}"` em Bash, ou `file_path.replace("\\", "/")` em Python, depois corresponda a um segmento de caminho como `/src/` em vez de ancorar com `^`, já que o caminho é absoluto1707* Normalize separadores antes de comparar: `FILE_PATH="${FILE_PATH//\\//}"` em Bash, ou `file_path.replace("\\", "/")` em Python, depois corresponda a um segmento de caminho como `/src/` em vez de ancorar com `^`, já que o caminho é absoluto
1732| `timeout` | number | `120000` | Tempo limite opcional em milissegundos. Valores acima do [máximo](/docs/pt/tools-reference#bash-tool-behavior) são reduzidos ao máximo em vez de rejeitados |1737| `timeout` | number | `120000` | Tempo limite opcional em milissegundos. Valores acima do [máximo](/docs/pt/tools-reference#bash-tool-behavior) são reduzidos ao máximo em vez de rejeitados |
1733| `run_in_background` | boolean | `false` | Se o comando deve ser executado em segundo plano |1738| `run_in_background` | boolean | `false` | Se o comando deve ser executado em segundo plano |
1734 1739
1735Quando um comando Bash altera arquivos em um repositório Git, Claude Code pode registrar o que mudou. Ele registra as mudanças em cada modo de permissão quando a configuração [`bashEditDiffEnabled`](/docs/pt/settings-reference#basheditdiffenabled) ativa o registro; a entrada dessa configuração diz quais arquivos podem defini-la. Caso contrário, ele as registra apenas em modo automático e modo `bypassPermissions`, e apenas quando Claude Code direciona Claude a editar arquivos através de Bash. Defina `bashEditDiffEnabled` como `false` para desativar o registro. Comandos de fundo e comandos somente leitura não carregam diff.1740Quando um comando Bash muda arquivos em um repositório Git, Claude Code pode registrar o que mudou. Ele registra as mudanças em cada modo de permissão quando a configuração [`bashEditDiffEnabled`](/docs/pt/settings-reference#basheditdiffenabled) ativa o registro; a entrada dessa configuração diz quais arquivos podem defini-la. Caso contrário, ele as registra apenas em modo automático e modo `bypassPermissions`, e apenas quando Claude Code direciona Claude a editar arquivos através de Bash. Defina `bashEditDiffEnabled` como `false` para desativar o registro. Comandos de fundo e comandos somente leitura não carregam diff.
1736 1741
1737Seu [hook PostToolUse](#posttooluse) então recebe os arquivos alterados em `tool_response.bashEditDiff`. A lista cobre o que mudou sob o repositório enquanto o comando era executado. Arquivos que Git ignora e arquivos em submódulos não são listados. Requer Claude Code v2.1.269 ou posterior.1742Seu hook [PostToolUse](#posttooluse) então recebe os arquivos alterados em `tool_response.bashEditDiff`. A lista cobre o que mudou sob o repositório enquanto o comando era executado. Arquivos que Git ignora e arquivos em submódulos não são listados. Requer Claude Code v2.1.269 ou posterior.
1738 1743
1739<Note>1744<Note>
1740 A lista é melhor esforço e em beta público. Claude Code pode perder uma mudança, incluir um arquivo que outro processo mudou ao mesmo tempo, ou parar em seus limites de tamanho. A forma do campo pode mudar. Use a lista para encontrar o que revisar, não para impor uma política.1745 A lista é melhor esforço e em beta público. Claude Code pode perder uma mudança, incluir um arquivo que outro processo mudou ao mesmo tempo, ou parar em seus limites de tamanho. A forma do campo pode mudar. Use a lista para encontrar o que revisar, não para impor uma política.
1741</Note>1746</Note>
1742 1747
1743`changedFiles` e `files` listam o que o comando mudou; os campos restantes dizem como completo e confiável essa lista é.1748`changedFiles` e `files` listam o que o comando mudou; os campos restantes dizem como completo e confiável é essa lista.
1744 1749
1745| Campo | Tipo | Exemplo | Descrição |1750| Campo | Tipo | Exemplo | Descrição |
1746| :- | :- | :- | :- |1751| :- | :- | :- | :- |
1748| `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 |1753| `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 |
1749| `moreFiles` | number | `2` | Contagem de arquivos alterados sem diff em `files` |1754| `moreFiles` | number | `2` | Contagem de arquivos alterados sem diff em `files` |
1750| `unavailable` | boolean | `true` | Definido quando o diff está incompleto ou não pôde ser obtido |1755| `unavailable` | boolean | `true` | Definido quando o diff está incompleto ou não pôde ser obtido |
1751| `skipped` | boolean | `true` | Definido para um comando Git que move a árvore de trabalho, como `git checkout` ou `git stash`, portanto Claude Code não obtém diff |1756| `skipped` | boolean | `true` | Definido para um comando Git que move a árvore de trabalho, como `git checkout` ou `git stash`, então Claude Code não obtém diff |
1752| `shared` | boolean | `true` | Definido quando outra chamada de ferramenta Bash, como a de um subagente, foi executada no mesmo repositório ao mesmo tempo, portanto algumas mudanças listadas podem ser desse comando |1757| `shared` | boolean | `true` | Definido quando outra chamada de ferramenta Bash, como a de um subagente, foi executada no mesmo repositório ao mesmo tempo, então algumas mudanças listadas podem ser daquele comando |
1753 1758
1754<a id="powershell" />1759<a id="powershell" />
1755 1760
1770 1775
1771Corresponda a `Bash|PowerShell` em hooks que inspecionam comandos de shell, para que cubram ambas as ferramentas:1776Corresponda a `Bash|PowerShell` em hooks que inspecionam comandos de shell, para que cubram ambas as ferramentas:
1772 1777
1773* No Windows, onde quer que a ferramenta PowerShell esteja habilitada, Claude trata o PowerShell como o shell primário e roteia comandos de shell através dele.1778* No Windows, onde quer que a ferramenta PowerShell esteja habilitada, Claude trata PowerShell como o shell primário e roteia comandos de shell através dele.
1774* No Windows sem Git Bash, a ferramenta é habilitada automaticamente e Claude Code não registra a ferramenta Bash.1779* No Windows sem Git Bash, a ferramenta é habilitada automaticamente e Claude Code não registra a ferramenta Bash.
1775* Um hook que corresponde apenas a `Bash` nunca é disparado lá.1780* Um hook que corresponde apenas a `Bash` nunca dispara lá.
1776 1781
1777<h5 id="write">1782<h5 id="write">
1778 Write1783 Write
1872| `subagent_type` | string | `"Explore"` | Tipo de agente especializado a usar |1877| `subagent_type` | string | `"Explore"` | Tipo de agente especializado a usar |
1873| `model` | string | `"sonnet"` | Alias de modelo opcional para sobrescrever o padrão |1878| `model` | string | `"sonnet"` | Alias de modelo opcional para sobrescrever o padrão |
1874 1879
1875Quando uma chamada Agent em primeiro plano é concluída, seu [hook PostToolUse](#posttooluse) recebe o resultado do subagente e telemetria de execução em `tool_response`. Leia esses campos para inspecionar a execução; para rollups de token e custo entre subagentes, use os [contadores de token e custo](/docs/pt/monitoring-usage#token-counter) filtrados para `query_source` `"subagent"`, já que `totalTokens` e `usage` cobrem apenas a solicitação final:1880Quando uma chamada Agent em primeiro plano é concluída, seu hook [PostToolUse](#posttooluse) recebe o resultado do subagente e telemetria de execução em `tool_response`. Leia esses campos para inspecionar a execução; para rollups de token e custo entre subagentes, use os [contadores de token e custo](/docs/pt/monitoring-usage#token-counter) filtrados para `query_source` `"subagent"`, já que `totalTokens` e `usage` cobrem apenas a solicitação final:
1876 1881
1877| Campo | Tipo | Exemplo | Descrição |1882| Campo | Tipo | Exemplo | Descrição |
1878| :- | :- | :- | :- |1883| :- | :- | :- | :- |
1879| `status` | string | `"completed"` | `"completed"` para subagentes em primeiro plano, `"async_launched"` para subagentes em segundo plano. A partir da v2.1.198, subagentes são executados em segundo plano por padrão, portanto um `run_in_background` omitido também produz `"async_launched"` |1884| `status` | string | `"completed"` | `"completed"` para subagentes em primeiro plano, `"async_launched"` para subagentes em segundo plano. A partir da v2.1.198, subagentes são executados em segundo plano por padrão, então um `run_in_background` omitido também produz `"async_launched"` |
1880| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificador para a execução do subagente |1885| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificador para a execução do subagente |
1881| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | Os blocos de texto final do subagente, ou, para um subagente cujo relatório passa por `SubagentHandback`, uma nota breve sobre esse hand-back em seu lugar |1886| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | Os blocos de texto final do subagente, ou, para um subagente cujo relatório passa por `SubagentHandback`, uma nota breve sobre esse handback em seu lugar |
1882| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modelo em que o subagente começou, que pode diferir do modelo solicitado |1887| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modelo em que o subagente começou, que pode diferir do modelo solicitado |
1883| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Modelos usados em ordem, com repetições consecutivas colapsadas; definido apenas quando o modelo foi trocado no meio da execução. Requer Claude Code v2.1.212 ou posterior |1888| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Modelos usados em ordem, com repetições consecutivas colapsadas; definido apenas quando o modelo foi trocado durante a execução. Requer Claude Code v2.1.212 ou posterior |
1884| `totalTokens` | number | `12450` | Contagem de tokens da solicitação final da API do subagente: tokens de entrada, saída e cache combinados. Isso não é um total em toda a execução |1889| `totalTokens` | number | `12450` | Contagem de tokens da solicitação final da API do subagente: tokens de entrada, saída e cache combinados. Isso não é um total em toda a execução |
1885| `totalDurationMs` | number | `48211` | Duração de tempo real da execução do subagente |1890| `totalDurationMs` | number | `48211` | Duração de tempo real da execução do subagente |
1886| `totalToolUseCount` | number | `7` | Contagem de chamadas de ferramenta que o subagente fez |1891| `totalToolUseCount` | number | `7` | Contagem de chamadas de ferramenta que o subagente fez |
1887| `usage` | object | `{"input_tokens": 8320, ...}` | Divisão de tokens por tipo da solicitação final da API: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |1892| `usage` | object | `{"input_tokens": 8320, ...}` | Divisão de tokens por tipo da solicitação final da API: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |
1888 1893
1889No Claude Code v2.1.271 ou posterior, um subagente que é executado com a ferramenta [`SubagentHandback`](/docs/pt/tools-reference), que Claude Code fornece em [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), entrega seu relatório através dessa ferramenta em vez de retorná-lo como texto. O campo `content` de seu resultado `completed` então carrega uma nota breve sobre esse hand-back em vez do relatório em si. Para ler o relatório, corresponda um hook `PreToolUse` ou `PostToolUse` em `SubagentHandback` e leia `tool_input.message`.1894No Claude Code v2.1.271 ou posterior, um subagente que é executado com a ferramenta [`SubagentHandback`](/docs/pt/tools-reference), que Claude Code fornece em [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), entrega seu relatório através dessa ferramenta em vez de retorná-lo como texto. O campo `content` de seu resultado `completed` então carrega uma nota breve sobre esse handback em vez do relatório em si. Para ler o relatório, corresponda um hook `PreToolUse` ou `PostToolUse` em `SubagentHandback` e leia `tool_input.message`.
1890 1895
1891Para subagentes em segundo plano, a ferramenta retorna quando a tarefa se move 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 Claude Code coloca em segundo plano no meio da execução retorna nessa transição. Ele tem `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile` e `resolvedModel`.1896Para subagentes em segundo plano, a ferramenta retorna quando a tarefa se move para o segundo plano, então `tool_response` não carrega campos de uso: um lançamento em segundo plano retorna imediatamente, e uma tarefa em primeiro plano que Claude Code coloca em segundo plano durante a execução retorna nessa transição. Ele tem `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile` e `resolvedModel`.
1892 1897
1893Em uma resposta `completed`, `resolvedModel` nomeia o modelo em que o subagente começou, que pode diferir do valor `model` em `tool_input`, como quando `availableModels` ou outra sobrescrita se aplica. Em uma resposta `async_launched`, `resolvedModel` nomeia o modelo em uso quando o agente se moveu para o segundo plano, portanto uma troca que aconteceu antes de colocar em segundo plano é refletida lá. `modelsUsed` e o comportamento de `resolvedModel` no tempo de colocação em segundo plano requerem Claude Code v2.1.212 ou posterior.1898Em uma resposta `completed`, `resolvedModel` nomeia o modelo em que o subagente começou, que pode diferir do valor `model` em `tool_input`, como quando `availableModels` ou outra sobrescrita se aplica. Em uma resposta `async_launched`, `resolvedModel` nomeia o modelo em uso quando o agente se moveu para o segundo plano, então uma troca que aconteceu antes de colocar em segundo plano é refletida lá. `modelsUsed` e o comportamento de `resolvedModel` no tempo de colocação em segundo plano requerem Claude Code v2.1.212 ou posterior.
1894 1899
1895<a id="askuserquestion" />1900<a id="askuserquestion" />
1896 1901
1903| Campo | Tipo | Exemplo | Descrição |1908| Campo | Tipo | Exemplo | Descrição |
1904| :- | :- | :- | :- |1909| :- | :- | :- | :- |
1905| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | Perguntas a apresentar, cada uma com uma string `question`, `header` curto, array `options` e flag `multiSelect` opcional |1910| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | Perguntas a apresentar, cada uma com uma string `question`, `header` curto, array `options` e flag `multiSelect` opcional |
1906| `answers` | object | `{"Which framework?": "React"}` | Opcional. Mapeia texto de pergunta para o rótulo de opção selecionada. Respostas de seleção múltipla unem rótulos com vírgulas. Claude não define este campo; forneça-o via `updatedInput` para responder programaticamente |1911| `answers` | object | `{"Which framework?": "React"}` | Opcional. Mapeia texto de pergunta para rótulo de opção selecionada. Respostas de seleção múltipla unem rótulos com vírgulas. Claude não define este campo; forneça-o via `updatedInput` para responder programaticamente |
1907 1912
1908<h5 id="exitplanmode">1913<h5 id="exitplanmode">
1909 ExitPlanMode1914 ExitPlanMode
1910</h5>1915</h5>
1911 1916
1912Apresenta um plano e pede ao usuário para aprová-lo antes de Claude sair do [modo de plano](/docs/pt/permission-modes#analyze-before-you-edit-with-plan-mode). Claude escreve o plano em um arquivo no disco antes de chamar a ferramenta, portanto o `tool_input` literal do modelo é tipicamente vazio. Claude Code injeta o conteúdo do plano e o caminho do arquivo antes de passar a entrada para hooks.1917Apresenta um plano e pede ao usuário para aprová-lo antes de Claude sair do [modo de plano](/docs/pt/permission-modes#analyze-before-you-edit-with-plan-mode). Claude escreve o plano em um arquivo no disco antes de chamar a ferramenta, então o `tool_input` literal do modelo é tipicamente vazio. Claude Code injeta o conteúdo do plano e o caminho do arquivo antes de passar a entrada para hooks.
1913 1918
1914| Campo | Tipo | Exemplo | Descrição |1919| Campo | Tipo | Exemplo | Descrição |
1915| :- | :- | :- | :- |1920| :- | :- | :- | :- |
1928| Campo | Descrição |1933| Campo | Descrição |
1929| :- | :- |1934| :- | :- |
1930| `permissionDecision` | `"allow"` pula o prompt de permissão, exceto para as [ações que nenhum modo auto-aprova](/docs/pt/permission-modes#actions-no-mode-auto-approves) e para `AskUserQuestion` e `ExitPlanMode`, que precisam de [`updatedInput` emparelhado com ele](#allow-with-updatedinput). `"deny"` impede a chamada de ferramenta. `"ask"` solicita ao usuário para confirmar. `"defer"` sai graciosamente para que a ferramenta possa ser retomada mais tarde. [Regras de negação e pergunta](/docs/pt/permissions#manage-permissions) ainda são avaliadas independentemente do que o hook retorna |1935| `permissionDecision` | `"allow"` pula o prompt de permissão, exceto para as [ações que nenhum modo auto-aprova](/docs/pt/permission-modes#actions-no-mode-auto-approves) e para `AskUserQuestion` e `ExitPlanMode`, que precisam de [`updatedInput` emparelhado com ele](#allow-with-updatedinput). `"deny"` impede a chamada de ferramenta. `"ask"` solicita ao usuário para confirmar. `"defer"` sai graciosamente para que a ferramenta possa ser retomada mais tarde. [Regras de negação e pergunta](/docs/pt/permissions#manage-permissions) ainda são avaliadas independentemente do que o hook retorna |
1931| `permissionDecisionReason` | Para `"ask"`, mostrado ao usuário mas não a Claude. Para `"deny"`, mostrado a Claude. Para `"allow"` e `"defer"`, escrito apenas no [log de depuração](#debug-hooks) |1936| `permissionDecisionReason` | Para `"ask"`, mostrado ao usuário mas não ao Claude. Para `"deny"`, mostrado ao Claude. Para `"allow"` e `"defer"`, escrito apenas no [log de depuração](#debug-hooks) |
1932| `updatedInput` | Modifica os parâmetros de entrada da ferramenta antes da execução. Substitui o objeto de entrada inteiro, portanto inclua campos inalterados ao lado dos modificados. Claude Code avalia regras de permissão e a elegibilidade de [auto-fundo](/docs/pt/tools-reference#background-commands) de um comando Bash contra a entrada que seu hook retorna, não a entrada que Claude enviou. Combine com `"allow"` para auto-aprovar, ou `"ask"` para mostrar a entrada modificada ao usuário. Para `"defer"`, ignorado |1937| `updatedInput` | Modifica os parâmetros de entrada da ferramenta antes da execução. Substitui o objeto de entrada inteiro, então inclua campos inalterados junto com os modificados. Claude Code avalia regras de permissão e a elegibilidade de [colocação em segundo plano automático](/docs/pt/tools-reference#background-commands) de um comando Bash contra a entrada que seu hook retorna, não a entrada que Claude enviou. Combine com `"allow"` para auto-aprovar, ou `"ask"` para mostrar a entrada modificada ao usuário. Para `"defer"`, ignorado |
1933| `additionalContext` | String adicionada ao contexto de Claude ao lado do resultado da ferramenta. Ignorado quando `permissionDecision` é `"defer"`. Veja [Adicionar contexto para Claude](#add-context-for-claude) |1938| `additionalContext` | String adicionada ao contexto do Claude junto com o resultado da ferramenta. Ignorado quando `permissionDecision` é `"defer"`. Veja [Adicionar contexto para Claude](#add-context-for-claude) |
1934 1939
1935Quando vários hooks PreToolUse retornam decisões diferentes, a precedência é `deny` > `defer` > `ask` > `allow`.1940Quando vários hooks PreToolUse retornam decisões diferentes, a precedência é `deny` > `defer` > `ask` > `allow`.
1936 1941
1956 1961
1957<span id="allow-with-updatedinput" />1962<span id="allow-with-updatedinput" />
1958 1963
1959Em [modo não interativo](/docs/pt/headless) com a flag `-p`, Claude Code oferece `AskUserQuestion` e `ExitPlanMode` apenas quando a execução tem um [host de permissão](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs) para receber o prompt, como um callback `canUseTool` do Agent SDK. Essas ferramentas requerem interação do usuário. Retornar `permissionDecision: "allow"` junto com `updatedInput` satisfaz esse requisito: o hook lê a entrada da ferramenta de stdin, coleta a resposta através de sua própria UI e a retorna em `updatedInput` para que a ferramenta seja executada sem solicitar. Retornar `"allow"` sozinho não é suficiente para essas ferramentas. Para `AskUserQuestion`, repita o array `questions` original e adicione um objeto [`answers`](#askuserquestion) mapeando o texto de cada pergunta para a resposta escolhida.1964Em [modo não interativo](/docs/pt/headless) com a flag `-p`, Claude Code oferece `AskUserQuestion` e `ExitPlanMode` apenas quando a execução tem um [host de permissão](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs) para receber o prompt, como um callback `canUseTool` do Agent SDK. Essas ferramentas requerem interação do usuário. Retornar `permissionDecision: "allow"` junto com `updatedInput` satisfaz esse requisito: o hook lê a entrada da ferramenta de stdin, coleta a resposta através de sua própria UI e a retorna em `updatedInput` para que a ferramenta seja executada sem solicitar. Retornar `"allow"` sozinho não é suficiente para essas ferramentas. Para `AskUserQuestion`, ecoar de volta o array `questions` original e adicionar um objeto [`answers`](#askuserquestion) mapeando o texto de cada pergunta para a resposta escolhida.
1960 1965
1961A partir da v2.1.199, uma ferramenta MCP cujo servidor a marca com [`_meta["anthropic/requiresUserInteraction"]`](/docs/pt/mcp#require-approval-for-a-specific-tool) é mais rigorosa: um hook não pode pular seu prompt de aprovação com `"allow"`, com ou sem `updatedInput`, porque Claude Code não pode confirmar que o hook coletou a interação que a ferramenta precisa.1966A partir da v2.1.199, uma ferramenta MCP cujo servidor a marca com [`_meta["anthropic/requiresUserInteraction"]`](/docs/pt/mcp#require-approval-for-a-specific-tool) é mais rigorosa: um hook não pode pular seu prompt de aprovação com `"allow"`, com ou sem `updatedInput`, porque Claude Code não pode confirmar que o hook coletou a interação que a ferramenta precisa.
1962 1967
1970 1975
1971`"defer"` é para integrações que executam `claude -p` como um subprocesso e leem sua saída JSON, como um aplicativo Agent SDK ou uma UI personalizada construída sobre Claude Code. Permite que esse processo de chamada pause Claude em uma chamada de ferramenta, colete entrada através de sua própria interface e retome onde parou. Claude Code honra este valor apenas em [modo não interativo](/docs/pt/headless) com a flag `-p`. Em sessões interativas, ele registra um aviso e ignora o resultado do hook.1976`"defer"` é para integrações que executam `claude -p` como um subprocesso e leem sua saída JSON, como um aplicativo Agent SDK ou uma UI personalizada construída sobre Claude Code. Permite que esse processo de chamada pause Claude em uma chamada de ferramenta, colete entrada através de sua própria interface e retome onde parou. Claude Code honra este valor apenas em [modo não interativo](/docs/pt/headless) com a flag `-p`. Em sessões interativas, ele registra um aviso e ignora o resultado do hook.
1972 1977
1973A ferramenta `AskUserQuestion` é o caso típico: Claude quer fazer uma pergunta ao usuário, mas não há terminal para responder. Uma execução `-p` oferece `AskUserQuestion` apenas quando tem um [host de permissão](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs), como uma ferramenta MCP que você passa com `--permission-prompt-tool`, portanto comece a execução com uma. A viagem de ida e volta funciona assim:1978A ferramenta `AskUserQuestion` é o caso típico: Claude quer fazer uma pergunta ao usuário, mas não há terminal para responder. Uma execução `-p` oferece `AskUserQuestion` apenas quando tem um [host de permissão](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs), como uma ferramenta MCP que você passa com `--permission-prompt-tool`, então comece a execução com um. A viagem de ida e volta funciona assim:
1974 1979
19751. Claude chama `AskUserQuestion`. O hook `PreToolUse` é disparado.19801. Claude chama `AskUserQuestion`. O hook `PreToolUse` dispara.
19762. 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.19812. 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.
19773. O processo de chamada lê `deferred_tool_use` do resultado do SDK, exibe a pergunta em sua própria UI e espera por uma resposta.19823. O processo de chamada lê `deferred_tool_use` do resultado do SDK, exibe a pergunta em sua própria UI e espera por uma resposta.
19784. O processo de chamada executa `claude -p --resume <session-id>` com o mesmo host de permissão. A mesma chamada de ferramenta dispara `PreToolUse` novamente.19834. O processo de chamada executa `claude -p --resume <session-id>` com o mesmo host de permissão. A mesma chamada de ferramenta dispara `PreToolUse` novamente.
1994}1999}
1995```2000```
1996 2001
1997Não há tempo limite ou limite de tentativas. A sessão permanece no disco até que você a retome, sujeita à varredura de retenção [`cleanupPeriodDays`](/docs/pt/settings-reference#cleanupperioddays), que deleta arquivos de sessão após 30 dias por padrão, seguindo as [regras de varredura de retenção](/docs/pt/claude-directory#cleaned-up-automatically). Se a resposta não estiver pronta quando você retomar, o hook pode retornar `"defer"` novamente e o processo sai da mesma forma. O processo de chamada controla quando quebrar o loop retornando eventualmente `"allow"` ou `"deny"` do hook.2002Não há tempo limite ou limite de tentativas. A sessão permanece no disco até que você a retome, sujeita à varredura de retenção [`cleanupPeriodDays`](/docs/pt/settings-reference#cleanupperioddays), que exclui arquivos de sessão após 30 dias por padrão, seguindo as [regras de varredura de retenção](/docs/pt/claude-directory#cleaned-up-automatically). Se a resposta não estiver pronta quando você retomar, o hook pode retornar `"defer"` novamente e o processo sai da mesma forma. O processo de chamada controla quando quebrar o loop eventualmente retornando `"allow"` ou `"deny"` do hook.
1998 2003
1999`"defer"` funciona apenas quando Claude faz uma única chamada de ferramenta no turno. Se Claude faz várias chamadas de ferramenta de uma vez, `"defer"` é ignorado com um aviso e a ferramenta prossegue através do fluxo de permissão normal. A restrição existe porque retomar pode apenas re-executar uma ferramenta: não há maneira de adiar uma chamada de um lote sem deixar as outras não resolvidas.2004`"defer"` funciona apenas quando Claude faz uma única chamada de ferramenta no turno. Se Claude faz várias chamadas de ferramenta de uma vez, `"defer"` é ignorado com um aviso e a ferramenta prossegue através do fluxo de permissão normal. A restrição existe porque retomar pode apenas re-executar uma ferramenta: não há maneira de adiar uma chamada de um lote sem deixar as outras não resolvidas.
2000 2005
2001Se a ferramenta adiada não estiver mais disponível quando você retomar, o processo sai com `stop_reason: "tool_deferred_unavailable"` e `is_error: true` antes do hook ser disparado. Isso acontece quando um servidor MCP que forneceu a ferramenta não está conectado para a sessão retomada. O payload `deferred_tool_use` ainda é incluído para que você possa identificar qual ferramenta desapareceu.2006Se a ferramenta adiada não estiver mais disponível quando você retomar, o processo sai com `stop_reason: "tool_deferred_unavailable"` e `is_error: true` antes do hook disparar. Isso acontece quando um servidor MCP que forneceu a ferramenta não está conectado para a sessão retomada. O payload `deferred_tool_use` ainda é incluído para que você possa identificar qual ferramenta desapareceu.
2002 2007
2003<Note>2008<Note>
2004 Para retomar uma sessão adiada em modo de plano, passe [`--permission-prompt-tool`](/docs/pt/cli-reference#cli-flags) junto com `--resume` para que Claude Code possa apresentar o plano para aprovação. Se você passar certas outras flags de lançamento, a execução retomada não retorna ao modo de plano; veja [Retomar em modo de plano com `-p`](/docs/pt/sessions#resume-in-plan-mode-with-p). Requer Claude Code v2.1.246 ou posterior.2009 Para retomar uma sessão adiada em modo de plano, passe [`--permission-prompt-tool`](/docs/pt/cli-reference#cli-flags) junto com `--resume` para que Claude Code possa apresentar o plano para aprovação. Se você passar certas outras flags de lançamento, a execução retomada não retorna ao modo de plano; veja [Retomar em modo de plano com `-p`](/docs/pt/sessions#resume-in-plan-mode-with-p). Requer Claude Code v2.1.246 ou posterior.
2005 2010
2006 Quando você retoma com `-p`, Claude Code não restaura nenhum outro modo de permissão armazenado. Ele inicia a execução no modo de permissão que uma nova execução `claude -p` iniciaria, portanto passe `--permission-mode` ou `--dangerously-skip-permissions` novamente se a sessão adiada usou uma. Quando você retoma com `claude --resume <session-id>` sem `-p`, Claude Code restaura o modo de permissão armazenado, com as exceções listadas em [modo de permissão ao retomar](/docs/pt/sessions#permission-mode-on-resume).2011 Quando você retoma com `-p`, Claude Code não restaura nenhum outro modo de permissão armazenado. Ele inicia a execução no modo de permissão que uma nova execução `claude -p` iniciaria, então passe `--permission-mode` ou `--dangerously-skip-permissions` novamente se a sessão adiada usou um. Quando você retoma com `claude --resume <session-id>` sem `-p`, Claude Code restaura o modo de permissão armazenado, com as exceções listadas em [modo de permissão ao retomar](/docs/pt/sessions#permission-mode-on-resume).
2007</Note>2012</Note>
2008 2013
2009<h3 id="permissionrequest">2014<h3 id="permissionrequest">
2010 PermissionRequest2015 PermissionRequest
2011</h3>2016</h3>
2012 2017
2013Executado quando Claude Code está prestes a pedir permissão para usar uma ferramenta. Em sessões que não podem mostrar um prompt, como subagentes de fundo em [modo não interativo](/docs/pt/headless), Claude Code ainda executa esses hooks, e se nenhum hook retornar uma decisão, ele nega a chamada de ferramenta.2018Executa quando Claude Code está prestes a pedir permissão para usar uma ferramenta. Em sessões que não podem mostrar um prompt, como subagentes de fundo em [modo não interativo](/docs/pt/headless), Claude Code ainda executa esses hooks, e se nenhum hook retornar uma decisão, ele nega a chamada de ferramenta.
2014Use [controle de decisão PermissionRequest](#permissionrequest-decision-control) para permitir ou negar em nome do usuário.2019Use [controle de decisão PermissionRequest](#permissionrequest-decision-control) para permitir ou negar em nome do usuário.
2015 2020
2016Use este evento quando você precisar de um sinal no momento em que Claude pede permissão para usar uma ferramenta. Claude Code executa um hook [Notification](#notification) com o tipo `permission_prompt` apenas após o prompt ter esperado cerca de seis segundos.2021Use este evento quando você precisa de um sinal no momento em que Claude pede permissão para usar uma ferramenta. Claude Code executa um hook [Notification](#notification) com o tipo `permission_prompt` apenas após o prompt ter esperado cerca de seis segundos.
2017 2022
2018Claude Code não executa hooks PermissionRequest para a [solicitação de rede](/docs/pt/sandboxing#network-isolation) de um comando em sandbox. Para obter um sinal para esse prompt, use o tipo de notificação `permission_prompt`.2023Claude Code não executa hooks PermissionRequest para a [solicitação de rede](/docs/pt/sandboxing#network-isolation) de um comando em sandbox. Para obter um sinal para esse prompt, use o tipo de notificação `permission_prompt`.
2019 2024
2023 Entrada PermissionRequest2028 Entrada PermissionRequest
2024</h4>2029</h4>
2025 2030
2026Hooks PermissionRequest recebem campos `tool_name` e `tool_input` como hooks PreToolUse, mas sem `tool_use_id`. Para uma ferramenta MCP, eles também recebem o objeto [`mcp_server`](#pretooluse-input). Um array `permission_suggestions` opcional contém as [atualizações de permissão](#permission-update-entries) que Claude Code sugere para esta solicitação, como adicionar uma regra de permissão ou alterar o modo de permissão.2031Hooks PermissionRequest recebem campos `tool_name` e `tool_input` como hooks PreToolUse, mas sem `tool_use_id`. Para uma ferramenta MCP, eles também recebem o objeto [`mcp_server`](#pretooluse-input). Um array `permission_suggestions` opcional contém as [atualizações de permissão](#permission-update-entries) que Claude Code sugere para esta solicitação, como adicionar uma regra de permissão ou mudar o modo de permissão.
2027 2032
2028O array `permission_suggestions` não é uma lista exata das opções que você vê, porque cada diálogo de permissão constrói suas próprias opções. Alguns diálogos, como o para edições de arquivo, não leem o array e derivam suas opções da solicitação em si. Um diálogo que o lê pode ainda reter uma opção cuja sugestão permanece no array, por exemplo quando [`allowManagedPermissionRulesOnly`](/docs/pt/settings-reference#allowmanagedpermissionrulesonly) oculta opções de salvamento de regra. Ele também pode oferecer opções que não têm entrada de sugestão, como [**Yes, and switch to auto mode**](/docs/pt/permission-modes#switch-permission-modes), que altera o modo de permissão diretamente em vez de através de uma atualização de permissão.2033O array `permission_suggestions` não é uma lista exata das opções que você vê, porque cada diálogo de permissão constrói suas próprias opções. Alguns diálogos, como o para edições de arquivo, não leem o array e derivam suas opções da solicitação em si. Um diálogo que o lê pode ainda reter uma opção cuja sugestão fica no array, por exemplo quando [`allowManagedPermissionRulesOnly`](/docs/pt/settings-reference#allowmanagedpermissionrulesonly) oculta opções de salvamento de regra. Ele também pode oferecer opções que não têm entrada de sugestão, como [**Sim, e mude para modo automático**](/docs/pt/permission-modes#switch-permission-modes), que muda o modo de permissão diretamente em vez de através de uma atualização de permissão.
2029 2034
2030Hooks PreToolUse são executados antes de cada chamada de ferramenta, independentemente de precisar de permissão. Hooks PermissionRequest são executados apenas quando Claude Code está prestes a pedir permissão, ou quando caso contrário auto-negaria uma chamada que não pode solicitar. Nenhum evento é disparado para [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior).2035Hooks PreToolUse são executados antes de cada chamada de ferramenta, independentemente de precisar de permissão. Hooks PermissionRequest são executados apenas quando Claude Code está prestes a pedir permissão, ou quando caso contrário auto-negaria uma chamada que não pode solicitar. Nenhum evento dispara para [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior).
2031 2036
2032```json theme={null}2037```json theme={null}
2033{2038{
2060 2065
2061| Campo | Descrição |2066| Campo | Descrição |
2062| :- | :- |2067| :- | :- |
2063| `behavior` | `"allow"` concede a permissão, `"deny"` a nega. [Regras de negação e pergunta](/docs/pt/permissions#manage-permissions) ainda são avaliadas, portanto um hook retornando `"allow"` não sobrescreve uma regra de negação correspondente |2068| `behavior` | `"allow"` concede a permissão, `"deny"` a nega. [Regras de negação e pergunta](/docs/pt/permissions#manage-permissions) ainda são avaliadas, então um hook retornando `"allow"` não sobrescreve uma regra de negação correspondente |
2064| `updatedInput` | Para `"allow"` apenas: modifica os parâmetros de entrada da ferramenta antes da execução. Substitui o objeto de entrada inteiro, portanto inclua campos inalterados ao lado dos modificados. A entrada modificada é re-avaliada contra regras de negação e pergunta |2069| `updatedInput` | Para `"allow"` apenas: modifica os parâmetros de entrada da ferramenta antes da execução. Substitui o objeto de entrada inteiro, então inclua campos inalterados junto com os modificados. A entrada modificada é re-avaliada contra regras de negação e pergunta |
2065| `updatedPermissions` | Para `"allow"` apenas: array de [entradas de atualização de permissão](#permission-update-entries) a aplicar, como adicionar uma regra de permissão ou alterar o modo de permissão da sessão |2070| `updatedPermissions` | Para `"allow"` apenas: array de [entradas de atualização de permissão](#permission-update-entries) a aplicar, como adicionar uma regra de permissão ou mudar o modo de permissão da sessão |
2066| `message` | Para `"deny"` apenas: diz por que a permissão foi negada |2071| `message` | Para `"deny"` apenas: diz ao Claude por que a permissão foi negada |
2067| `interrupt` | Para `"deny"` apenas: se `true`, para Claude |2072| `interrupt` | Para `"deny"` apenas: se `true`, para Claude |
2068 2073
2069Um hook que sai com 2 sem um objeto `decision` deixa o fluxo de permissão inalterado, e seu stderr é descartado. Apenas o objeto `decision` pode conceder ou negar a solicitação.2074Um hook que sai com 2 sem um objeto `decision` deixa o fluxo de permissão inalterado, e seu stderr é descartado. Apenas o objeto `decision` pode conceder ou negar a solicitação.
2093| `addRules` | `rules`, `behavior`, `destination` | Adiciona regras de permissão. `rules` é um array de objetos `{toolName, ruleContent?}`. Omita `ruleContent` para corresponder a toda a ferramenta. `behavior` é `"allow"`, `"deny"` ou `"ask"` |2098| `addRules` | `rules`, `behavior`, `destination` | Adiciona regras de permissão. `rules` é um array de objetos `{toolName, ruleContent?}`. Omita `ruleContent` para corresponder a toda a ferramenta. `behavior` é `"allow"`, `"deny"` ou `"ask"` |
2094| `replaceRules` | `rules`, `behavior`, `destination` | Substitui todas as regras do `behavior` dado no `destination` pelas `rules` fornecidas |2099| `replaceRules` | `rules`, `behavior`, `destination` | Substitui todas as regras do `behavior` dado no `destination` pelas `rules` fornecidas |
2095| `removeRules` | `rules`, `behavior`, `destination` | Remove regras correspondentes do `behavior` dado |2100| `removeRules` | `rules`, `behavior`, `destination` | Remove regras correspondentes do `behavior` dado |
2096| `setMode` | `mode`, `destination` | Altera o modo de permissão. Modos válidos são `default`, `auto`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` e `manual` como um alias para `default`. O alias `manual` requer Claude Code v2.1.200 ou posterior |2101| `setMode` | `mode`, `destination` | Muda o modo de permissão. Modos válidos são `default`, `auto`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` e `manual` como um alias para `default`. O alias `manual` requer Claude Code v2.1.200 ou posterior |
2097| `addDirectories` | `directories`, `destination` | Adiciona diretórios de trabalho. `directories` é um array de strings de caminho |2102| `addDirectories` | `directories`, `destination` | Adiciona diretórios de trabalho. `directories` é um array de strings de caminho |
2098| `removeDirectories` | `directories`, `destination` | Remove diretórios de trabalho |2103| `removeDirectories` | `directories`, `destination` | Remove diretórios de trabalho |
2099 2104
2103 `bypassPermissions` nunca é persistido como `defaultMode` independentemente de `destination`.2108 `bypassPermissions` nunca é persistido como `defaultMode` independentemente de `destination`.
2104</Note>2109</Note>
2105 2110
2106O campo `destination` em cada entrada determina se a mudança permanece na memória ou persiste em um arquivo de configurações.2111O campo `destination` em cada entrada determina se a mudança fica na memória ou persiste em um arquivo de configurações.
2107 2112
2108| `destination` | Escreve para |2113| `destination` | Escreve para |
2109| :- | :- |2114| :- | :- |
2118 PostToolUse2123 PostToolUse
2119</h3>2124</h3>
2120 2125
2121Executado imediatamente após uma ferramenta ser concluída com sucesso.2126Executa imediatamente após uma ferramenta ser concluída com sucesso.
2122 2127
2123Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.2128Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.
2124 2129
2131 Entrada PostToolUse2136 Entrada PostToolUse
2132</h4>2137</h4>
2133 2138
2134Hooks `PostToolUse` são disparados após uma ferramenta já ter sido executada com sucesso. A entrada inclui tanto `tool_input`, os argumentos enviados para a ferramenta, quanto `tool_response`, o resultado que ela retornou. O esquema exato para ambos depende da ferramenta. Caminhos `tool_input` de ferramenta de arquivo chegam no mesmo formato que para [PreToolUse](#pretooluse-input): sempre absoluto, com os separadores nativos da plataforma, portanto barras invertidas no Windows. Para uma ferramenta MCP, a entrada também carrega o objeto [`mcp_server`](#pretooluse-input).2139Hooks `PostToolUse` disparam após uma ferramenta já ter sido executada com sucesso. A entrada inclui tanto `tool_input`, os argumentos enviados para a ferramenta, quanto `tool_response`, o resultado que ela retornou. O esquema exato para ambos depende da ferramenta. Caminhos `tool_input` de ferramentas de arquivo chegam no mesmo formato que para [PreToolUse](#pretooluse-input): sempre absoluto, com os separadores nativos da plataforma, então barras invertidas no Windows. Para uma ferramenta MCP, a entrada também carrega o objeto [`mcp_server`](#pretooluse-input).
2135 2140
2136```json theme={null}2141```json theme={null}
2137{2142{
2162 Controle de decisão PostToolUse2167 Controle de decisão PostToolUse
2163</h4>2168</h4>
2164 2169
2165Hooks `PostToolUse` podem fornecer feedback a Claude após a execução da ferramenta. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar esses campos específicos do evento:2170Hooks `PostToolUse` podem fornecer feedback ao Claude após a execução da ferramenta. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar esses campos específicos do evento:
2166 2171
2167| Campo | Descrição |2172| Campo | Descrição |
2168| :- | :- |2173| :- | :- |
2169| `decision` | `"block"` adiciona o `reason` ao lado do resultado da ferramenta. Claude ainda vê a saída original; para substituí-la, use `updatedToolOutput` |2174| `decision` | `"block"` adiciona o `reason` ao lado do resultado da ferramenta. Claude ainda vê a saída original; para substituí-la, use `updatedToolOutput` |
2170| `reason` | Explicação mostrada a Claude quando `decision` é `"block"` |2175| `reason` | Explicação mostrada ao Claude quando `decision` é `"block"` |
2171| `additionalContext` | String adicionada ao contexto de Claude ao lado do resultado da ferramenta. Veja [Adicionar contexto para Claude](#add-context-for-claude) |2176| `additionalContext` | String adicionada ao contexto do Claude junto com o resultado da ferramenta. Veja [Adicionar contexto para Claude](#add-context-for-claude) |
2172| `classifierContext` | Nota breve sobre o resultado desta chamada para o classificador de [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) em vez de para Claude. Veja [Anotar um resultado para o classificador de modo automático](#annotate-a-result-for-the-auto-mode-classifier). Requer Claude Code v2.1.236 ou posterior |2177| `classifierContext` | Nota breve sobre o resultado desta chamada para o classificador de [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) em vez de para Claude. Veja [Anotar um resultado para o classificador de modo automático](#annotate-a-result-for-the-auto-mode-classifier). Requer Claude Code v2.1.236 ou posterior |
2173| `updatedToolOutput` | Substitui a saída da ferramenta pelo valor fornecido antes de ser enviado a Claude. O valor deve corresponder à forma de saída da ferramenta |2178| `updatedToolOutput` | Substitui a saída da ferramenta pelo valor fornecido antes de ser enviado ao Claude. O valor deve corresponder à forma de saída da ferramenta |
2174| `updatedMCPToolOutput` | Substitui a saída para [ferramentas MCP](#match-mcp-tools) apenas. Prefira `updatedToolOutput`, que funciona para todas as ferramentas |2179| `updatedMCPToolOutput` | Substitui a saída para [ferramentas MCP](#match-mcp-tools) apenas. Prefira `updatedToolOutput`, que funciona para todas as ferramentas |
2175 2180
2176O exemplo abaixo substitui a saída de uma chamada `Bash`. O valor de substituição corresponde à forma de saída da ferramenta `Bash`:2181O exemplo abaixo substitui a saída de uma chamada `Bash`. O valor de substituição corresponde à forma de saída da ferramenta `Bash`:
2191```2196```
2192 2197
2193<Warning>2198<Warning>
2194 `updatedToolOutput` apenas altera o que Claude vê. A ferramenta já foi executada no momento em que o hook é disparado, portanto qualquer arquivo escrito, comando executado ou solicitação de rede enviada já teve efeito. Telemetria como spans de ferramenta OpenTelemetry e eventos de análise também capturam a saída original antes do hook ser executado. Para impedir ou modificar uma chamada de ferramenta antes de ser executada, use um hook [PreToolUse](#pretooluse) em vez disso.2199 `updatedToolOutput` apenas muda o que Claude vê. A ferramenta já foi executada no momento em que o hook dispara, então quaisquer arquivos escritos, comandos executados ou solicitações de rede enviadas já tiveram efeito. Telemetria como spans de ferramentas OpenTelemetry e eventos de análise também capturam a saída original antes do hook ser executado. Para impedir ou modificar uma chamada de ferramenta antes de ser executada, use um hook [PreToolUse](#pretooluse) em vez disso.
2195 2200
2196 O valor de substituição deve corresponder à forma de saída da ferramenta. Ferramentas integradas retornam objetos estruturados em vez de strings simples. Por exemplo, `Bash` retorna um objeto com campos `stdout`, `stderr`, `interrupted` e `isImage`. Para ferramentas integradas, um valor que não corresponde ao esquema de saída da ferramenta é ignorado e a saída original é usada. A saída de ferramenta MCP é passada sem validação de esquema. Remover detalhes de erro que Claude precisa pode fazer com que ele prossiga em uma suposição falsa.2201 O valor de substituição deve corresponder à forma de saída da ferramenta. Ferramentas integradas retornam objetos estruturados em vez de strings simples. Por exemplo, `Bash` retorna um objeto com campos `stdout`, `stderr`, `interrupted` e `isImage`. Para ferramentas integradas, um valor que não corresponde ao esquema de saída da ferramenta é ignorado e a saída original é usada. A saída de ferramentas MCP é passada sem validação de esquema. Remover detalhes de erro que Claude precisa pode fazer com que ele prossiga em uma suposição falsa.
2197</Warning>2202</Warning>
2198 2203
2199<h4 id="annotate-a-result-for-the-auto-mode-classifier">2204<h4 id="annotate-a-result-for-the-auto-mode-classifier">
2200 Anotar um resultado para o classificador de modo automático2205 Anotar um resultado para o classificador de modo automático
2201</h4>2206</h4>
2202 2207
2203Retorne `classifierContext` para enviar uma nota breve sobre o resultado da chamada de ferramenta para o classificador de [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) em vez de para Claude. O classificador [nunca recebe resultados de ferramentas em si](/docs/pt/permission-modes#how-the-classifier-evaluates-actions), portanto este campo é a forma suportada de contar algo sobre o que uma chamada retornou antes de revisar ações posteriores. O campo requer Claude Code v2.1.236 ou posterior.2208Retorne `classifierContext` para enviar uma nota breve sobre o resultado da chamada de ferramenta para o classificador de [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) em vez de para Claude. O classificador [nunca recebe resultados de ferramentas em si](/docs/pt/permission-modes#how-the-classifier-evaluates-actions), então este campo é a forma suportada de dizer algo sobre o que uma chamada retornou antes de revisar ações posteriores. O campo requer Claude Code v2.1.236 ou posterior.
2204 2209
2205O exemplo abaixo diz ao classificador de onde a saída de uma consulta veio:2210O exemplo abaixo diz ao classificador de onde a saída de uma consulta veio:
2206 2211
2216Quanto peso o classificador dá à nota depende de onde você configurou o hook:2221Quanto peso o classificador dá à nota depende de onde você configurou o hook:
2217 2222
2218* **Hooks configurados em Claude Code**: para hooks de arquivos de configurações, plugins, skills e frontmatter de agente, o classificador trata a nota como contexto não verificado fornecido pela aplicação. A nota nunca estabelece intenção do usuário, e se ela afirma que você aprovou ou solicitou algo, o classificador verifica essa afirmação contra suas próprias mensagens na conversa2223* **Hooks configurados em Claude Code**: para hooks de arquivos de configurações, plugins, skills e frontmatter de agente, o classificador trata a nota como contexto não verificado fornecido pela aplicação. A nota nunca estabelece intenção do usuário, e se ela afirma que você aprovou ou solicitou algo, o classificador verifica essa afirmação contra suas próprias mensagens na conversa
2219* **Callbacks do Agent SDK em processo**: quando um aplicativo que incorpora Claude Code registra o hook como um [callback do SDK TypeScript](/docs/pt/agent-sdk/hooks) e retorna a nota durante a sessão ao vivo, o classificador pode pesar uma declaração do usuário retransmitida na nota como intenção do usuário. Tal declaração pode satisfazer um requisito de consentimento que o classificador aceitaria de uma mensagem que você envia, mas nunca levanta um bloqueio que sua própria mensagem não pudesse levantar também. Após uma sessão retomar, Claude Code trata notas restauradas como contexto não verificado. Quando hooks de ambos os grupos anotam a mesma chamada, o classificador trata a nota combinada como não verificada2224* **Callbacks Agent SDK em processo**: quando um aplicativo incorporando Claude Code registra o hook como um [callback SDK TypeScript](/docs/pt/agent-sdk/hooks) e retorna a nota durante a sessão ao vivo, o classificador pode pesar uma declaração do usuário retransmitida na nota como intenção do usuário. Tal declaração pode satisfazer um requisito de consentimento que o classificador aceitaria de uma mensagem que você envia, mas nunca levanta um bloqueio que sua própria mensagem não pudesse levantar também. Após uma sessão retomar, Claude Code trata notas restauradas como contexto não verificado. Quando hooks de ambos os grupos anotam a mesma chamada, o classificador trata a nota combinada como não verificada
2220 2225
2221Claude Code aplica esses limites ao entregar a nota:2226Claude Code aplica esses limites ao entregar a nota:
2222 2227
2223* **Comprimento**: Claude Code limita as notas para uma chamada de ferramenta a 2.000 caracteres e trunca o resto. O limite é compartilhado entre cada hook que responde a essa chamada2228* **Comprimento**: Claude Code limita as notas para uma chamada de ferramenta a 2.000 caracteres e trunca o resto. O limite é compartilhado entre cada hook que responde a essa chamada
2224* **Apenas respostas síncronas**: Claude Code ignora o campo na resposta de um hook que [é executado em segundo plano](#run-hooks-in-the-background), porque essa resposta chega após Claude Code registrar o resultado da ferramenta2229* **Apenas respostas síncronas**: Claude Code ignora o campo na resposta de um hook que [é executado em segundo plano](#run-hooks-in-the-background), porque essa resposta chega após Claude Code registrar o resultado da ferramenta
2225* **Chamadas que o classificador não registra**: a transcrição do classificador omite pesquisas somente leitura como leituras de arquivo e pesquisas. Claude Code descarta uma nota anexada a uma dessas chamadas2230* **Chamadas que o classificador não registra**: a transcrição do classificador omite buscas somente leitura como leituras de arquivo e pesquisas. Claude Code descarta uma nota anexada a uma dessas chamadas
2226* **Interação com reescritas**: quando a nota descreve saída que você está substituindo com `updatedToolOutput`, retorne ambos os campos na mesma resposta do hook. Claude Code descarta a nota se essa reescrita for rejeitada ou outra reescrita do hook a substituir. Claude Code entrega uma nota que você retorna sem uma reescrita mesmo quando outro hook reescreve a saída2231* **Interação com reescritas**: quando a nota descreve saída que você está substituindo com `updatedToolOutput`, retorne ambos os campos na mesma resposta do hook. Claude Code descarta a nota se essa reescrita for rejeitada ou outra reescrita do hook a substituir. Claude Code entrega uma nota que você retorna sem uma reescrita mesmo quando outro hook reescreve a saída
2227 2232
2228<Warning>2233<Warning>
2229 O classificador lê conteúdo que você coloca em `classifierContext` como informação do aplicativo hospedando a sessão, portanto não copie saída de ferramenta não confiável ou texto de terceiros nele. Mantenha a nota para uma breve afirmação sobre esta uma chamada, como um fato sobre sua origem ou uma declaração do usuário sobre ela; não use o campo para entregar mensagens não relacionadas ou um fluxo de eventos.2234 O classificador lê conteúdo que você coloca em `classifierContext` como informação do aplicativo hospedando a sessão, então não copie saída de ferramenta não confiável ou texto de terceiros nele. Mantenha a nota para uma afirmação breve sobre esta uma chamada, como um fato sobre sua origem ou uma declaração do usuário sobre ela; não use o campo para entregar mensagens não relacionadas ou um fluxo de eventos.
2230</Warning>2235</Warning>
2231 2236
2232<h3 id="posttoolusefailure">2237<h3 id="posttoolusefailure">
2233 PostToolUseFailure2238 PostToolUseFailure
2234</h3>2239</h3>
2235 2240
2236Executado quando uma ferramenta que começou a executar falha: a ferramenta lançou um erro, ou uma ferramenta MCP retornou um resultado de erro. Use isso para registrar falhas, enviar alertas ou fornecer feedback corretivo a Claude.2241Executa quando uma ferramenta que começou a executar falha: a ferramenta lançou um erro, ou uma ferramenta MCP retornou um resultado de erro. Use isso para registrar falhas, enviar alertas ou fornecer feedback corretivo ao Claude.
2237 2242
2238Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.2243Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.
2239 2244
2240<Note>2245<Note>
2241 Este evento não é disparado para chamadas de ferramenta rejeitadas antes da execução: um nome de ferramenta desconhecido, entrada que falha na validação de esquema ou específica da ferramenta, ou uma negação de permissão. Rejeições de validação são retornadas como resultados `tool_use_error` e acontecem antes dos hooks serem executados, portanto não disparam nem `PreToolUse` nem este evento. Negações de permissão disparam `PreToolUse` mas não este evento; veja [PermissionDenied](#permissiondenied).2246 Este evento não dispara para chamadas de ferramenta rejeitadas antes da execução: um nome de ferramenta desconhecido, entrada que falha na validação de esquema ou específica da ferramenta, ou uma negação de permissão. Rejeições de validação são retornadas como resultados `tool_use_error` e acontecem antes dos hooks serem executados, então não disparam nem `PreToolUse` nem `PostToolUseFailure`. Negações de permissão disparam `PreToolUse` mas não este evento; veja [PermissionDenied](#permissiondenied).
2242</Note>2247</Note>
2243 2248
2244<h4 id="posttoolusefailure-input">2249<h4 id="posttoolusefailure-input">
2269| Campo | Descrição |2274| Campo | Descrição |
2270| :- | :- |2275| :- | :- |
2271| `error` | String descrevendo o que deu errado. O formato depende da ferramenta que falhou |2276| `error` | String descrevendo o que deu errado. O formato depende da ferramenta que falhou |
2272| `is_interrupt` | Booleano opcional. True quando a falha chegou a Claude Code como uma interrupção em vez de um erro que a ferramenta relatou. Cancelar uma ferramenta em execução não dispara este hook; o resultado da ferramenta carrega a mensagem de interrupção em vez disso |2277| `is_interrupt` | Booleano opcional. True quando a falha chegou ao Claude Code como um aborto em vez de um erro que a ferramenta relatou. Cancelar uma ferramenta em execução não dispara este hook; o resultado da ferramenta carrega a mensagem de interrupção em vez disso |
2273| `duration_ms` | Opcional. Tempo de execução da ferramenta em milissegundos. Exclui tempo gasto em prompts de permissão e hooks PreToolUse |2278| `duration_ms` | Opcional. Tempo de execução da ferramenta em milissegundos. Exclui tempo gasto em prompts de permissão e hooks PreToolUse |
2274 2279
2275A string `error` é geralmente o mesmo texto que Claude recebe como resultado da ferramenta falhada. Seu formato varia por ferramenta e falha. Chave seu hook em `tool_name`, `is_interrupt` e a primeira linha `Exit code N`; trate o resto da string como texto de exibição, não um formato estável.2280A string `error` é geralmente o mesmo texto que Claude recebe como resultado da ferramenta falhada. Seu formato varia por ferramenta e falha. Chave seu hook em `tool_name`, `is_interrupt` e a primeira linha `Exit code N`; trate o resto da string como texto de exibição, não um formato estável.
2276 2281
2277* Para Bash e PowerShell, um comando que foi executado e saiu produz uma primeira linha `Exit code N`, depois qualquer saída que o comando produziu como um bloco com stdout e stderr intercalados2282* Para Bash e PowerShell, um comando que foi executado e saiu produz uma primeira linha `Exit code N`, depois qualquer saída que o comando produziu como um bloco com stdout e stderr intercalados
2278* Um payload também pode carregar uma mensagem de falha simples sem linha de código de saída, quando Claude Code não pôde iniciar o próprio processo de shell2283* Um payload também pode carregar uma mensagem de falha simples sem linha de código de saída, quando Claude Code não pôde iniciar o próprio processo de shell
2279* Claude Code trunca no meio strings longas em torno de um marcador `... [N characters truncated] ...`, e pode inserir linhas de sua própria conta, como `Command timed out after 2m 0s`2284* Claude Code trunca no meio strings longas em torno de um marcador `... [N characters truncated] ...`, e pode inserir linhas suas próprias, como `Command timed out after 2m 0s`
2280 2285
2281<h4 id="posttoolusefailure-decision-control">2286<h4 id="posttoolusefailure-decision-control">
2282 Controle de decisão PostToolUseFailure2287 Controle de decisão PostToolUseFailure
2283</h4>2288</h4>
2284 2289
2285Hooks `PostToolUseFailure` podem fornecer contexto a Claude após uma falha de ferramenta. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar esses campos específicos do evento:2290Hooks `PostToolUseFailure` podem fornecer contexto ao Claude após uma falha de ferramenta. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar esses campos específicos do evento:
2286 2291
2287| Campo | Descrição |2292| Campo | Descrição |
2288| :- | :- |2293| :- | :- |
2289| `additionalContext` | String adicionada ao contexto de Claude ao lado do erro. Veja [Adicionar contexto para Claude](#add-context-for-claude) |2294| `additionalContext` | String adicionada ao contexto do Claude junto com o erro. Veja [Adicionar contexto para Claude](#add-context-for-claude) |
2290 2295
2291```json theme={null}2296```json theme={null}
2292{2297{
2301 PostToolBatch2306 PostToolBatch
2302</h3>2307</h3>
2303 2308
2304Executado uma vez após cada chamada de ferramenta em um lote ter sido resolvida, antes de Claude Code enviar a próxima solicitação para o modelo. `PostToolUse` é disparado uma vez por ferramenta, o que significa que é disparado simultaneamente quando Claude faz chamadas de ferramenta paralelas. `PostToolBatch` é disparado exatamente uma vez com o lote completo, portanto é o lugar certo para injetar contexto que depende do conjunto de ferramentas que foram executadas em vez de em qualquer ferramenta única. Não há matcher para este evento.2309Executa uma vez após cada chamada de ferramenta em um lote ter sido resolvida, antes de Claude Code enviar a próxima solicitação para o modelo. `PostToolUse` dispara uma vez por ferramenta, o que significa que dispara concorrentemente quando Claude faz chamadas de ferramenta paralelas. `PostToolBatch` dispara exatamente uma vez com o lote completo, então é o lugar certo para injetar contexto que depende do conjunto de ferramentas que foram executadas em vez de em qualquer ferramenta única. Não há matcher para este evento.
2305 2310
2306<h4 id="posttoolbatch-input">2311<h4 id="posttoolbatch-input">
2307 Entrada PostToolBatch2312 Entrada PostToolBatch
2333}2338}
2334```2339```
2335 2340
2336`tool_response` contém o mesmo conteúdo que o modelo recebe no bloco `tool_result` correspondente. O valor é uma string serializada ou array de bloco de conteúdo, exatamente como a ferramenta o emitiu. Para `Read`, isso significa texto com prefixo de número de linha em vez de conteúdo de arquivo bruto. Respostas podem ser grandes, portanto analise apenas os campos que você precisa.2341`tool_response` contém o mesmo conteúdo que o modelo recebe no bloco `tool_result` correspondente. O valor é uma string serializada ou array de bloco de conteúdo, exatamente como a ferramenta o emitiu. Para `Read`, isso significa texto com prefixo de número de linha em vez de conteúdo de arquivo bruto. Respostas podem ser grandes, então analise apenas os campos que você precisa.
2337 2342
2338<Note>2343<Note>
2339 A forma `tool_response` difere da de `PostToolUse`. `PostToolUse` passa o objeto `Output` estruturado da ferramenta, como `{filePath: "...", type: "create"}` para `Write`; `PostToolBatch` passa o conteúdo `tool_result` serializado que o modelo vê.2344 A forma `tool_response` difere da de `PostToolUse`. `PostToolUse` passa o objeto `Output` estruturado da ferramenta, como `{filePath: "...", type: "create"}` para `Write`; `PostToolBatch` passa o conteúdo `tool_result` serializado que o modelo vê.
2358}2363}
2359```2364```
2360 2365
2361Retornar `decision: "block"` ou `continue: false` para o loop agentico antes da próxima chamada do modelo. A mensagem de bloqueio vem do JSON `reason` ou `stopReason`, ou de stderr ao sair com 2. Você a vê como um aviso na transcrição, e ela permanece na conversa, portanto Claude a vê quando a conversa continua.2366Retornar `decision: "block"` ou `continue: false` para o loop agentico antes da próxima chamada do modelo. A mensagem de bloqueio vem do JSON `reason` ou `stopReason`, ou de stderr ao sair com 2. Você a vê como um aviso na transcrição, e ela fica na conversa, então Claude a vê quando a conversa continua.
2362 2367
2363<h3 id="permissiondenied">2368<h3 id="permissiondenied">
2364 PermissionDenied2369 PermissionDenied
2365</h3>2370</h3>
2366 2371
2367Executado quando [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) nega uma chamada de ferramenta, incluindo quando nega sem um veredicto do classificador porque [uma verificação de segurança separada do modo automático recusou a própria solicitação do classificador](/docs/pt/errors#auto-mode-cannot-determine-the-safety-of-an-action) ou sua resposta não foi analisada. Este hook é disparado apenas em modo automático: não é executado quando você nega manualmente um diálogo de permissão, quando um hook `PreToolUse` bloqueia uma chamada, ou quando uma regra `deny` corresponde. Use-o para registrar negações, ajustar configuração ou dizer ao modelo que pode tentar novamente a chamada de ferramenta.2372Executa quando [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) nega uma chamada de ferramenta, incluindo quando nega sem um veredicto do classificador porque [uma verificação de segurança separada do modo automático recusou a própria solicitação do classificador](/docs/pt/errors#auto-mode-cannot-determine-the-safety-of-an-action) ou sua resposta não foi analisada. Este hook dispara apenas em modo automático: não é executado quando você nega manualmente um diálogo de permissão, quando um hook `PreToolUse` bloqueia uma chamada, ou quando uma regra `deny` corresponde. Use-o para registrar negações, ajustar configuração ou dizer ao modelo que pode tentar novamente a chamada de ferramenta.
2368 2373
2369Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.2374Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.
2370 2375
2418 Notification2423 Notification
2419</h3>2424</h3>
2420 2425
2421Executado quando Claude Code envia notificações. Corresponde ao tipo de notificação. Omita o matcher para executar hooks para todos os tipos de notificação.2426Executa quando Claude Code envia notificações. Corresponde ao tipo de notificação. Omita o matcher para executar hooks para todos os tipos de notificação.
2422 2427
2423Você recebe esses eventos de hook mesmo com notificações de desktop desativadas: a configuração `preferredNotifChannel`, incluindo `notifications_disabled`, altera apenas como você é alertado, não se seu hook é executado.2428Você recebe esses eventos de hook mesmo com notificações de desktop desativadas: a configuração `preferredNotifChannel`, incluindo `notifications_disabled`, muda apenas como você é alertado, não se seu hook é executado.
2424 2429
2425| Matcher | Quando é disparado |2430| Matcher | Quando é disparado |
2426| :- | :- |2431| :- | :- |
2427| `permission_prompt` | Claude precisa de sua permissão para usar uma ferramenta ou a [solicitação de rede](/docs/pt/sandboxing#network-isolation) de um comando em sandbox, e o prompt esperou cerca de seis segundos |2432| `permission_prompt` | Claude precisa de sua aprovação para usar uma ferramenta ou a [solicitação de rede](/docs/pt/sandboxing#network-isolation) de um comando em sandbox, e o prompt esperou cerca de seis segundos |
2428| `idle_prompt` | Claude terminou de responder cerca de 60 segundos atrás e você não digitou desde então |2433| `idle_prompt` | Claude terminou de responder cerca de 60 segundos atrás e você não digitou desde então |
2429| `auth_success` | Autenticação é concluída |2434| `auth_success` | Autenticação é concluída |
2430| `elicitation_dialog` | Um servidor MCP abre um formulário de elicitação e você não digitou por cerca de seis segundos |2435| `elicitation_dialog` | Um servidor MCP abre um formulário de elicitação e você não digitou por cerca de seis segundos |
2431| `elicitation_url_dialog` | Um servidor MCP pede que você abra uma URL do navegador e você não digitou por cerca de seis segundos |2436| `elicitation_url_dialog` | Um servidor MCP pede que você abra uma URL do navegador e você não digitou por cerca de seis segundos |
2432| `elicitation_complete` | Um servidor MCP relata que uma [elicitação de modo URL](#elicitation-input) está completa |2437| `elicitation_complete` | Um servidor MCP relata que uma [elicitação de modo URL](#elicitation-input) está completa |
2433| `elicitation_response` | Uma resposta de elicitação MCP é enviada de volta para o servidor |2438| `elicitation_response` | Uma resposta de elicitação MCP é enviada de volta para o servidor |
2434| `agent_needs_input` | Uma sessão de fundo começa a esperar sua entrada enquanto [agent view](/docs/pt/agent-view) está aberta em um terminal, ou a sessão atual pede uma pergunta de configuração de terminal de um [colega de equipe de agente](/docs/pt/agent-teams#choose-a-display-mode) e você não digitou por cerca de seis segundos |2439| `agent_needs_input` | Uma sessão de fundo começa a esperar sua entrada enquanto [visualização de agente](/docs/pt/agent-view) está aberta em um terminal. Também dispara quando uma sessão de terminal mostra a você uma [pergunta de configuração de terminal de colega de equipe de agente](/docs/pt/agent-teams#choose-a-display-mode) ou aviso de modo automático sobre [cobranças de solicitação do classificador](/docs/pt/auto-mode-classifier-billing) e você não digitou por cerca de seis segundos |
2435| `agent_completed` | Uma sessão de fundo termina ou falha. Disparado apenas enquanto [agent view](/docs/pt/agent-view) está aberta em um terminal |2440| `agent_completed` | Uma sessão de fundo termina ou falha. Dispara apenas enquanto [visualização de agente](/docs/pt/agent-view) está aberta em um terminal |
2436| `quota_auto_resume_fired` | Claude Code continua sua tarefa após um limite de uso de claude.ai pausá-la: na redefinição, ou mais cedo quando algo que você faz em Claude Code durante a espera, como adicionar créditos de uso, atualizar seu plano ou trocar modelos, torna o uso disponível novamente, com a [exceção de configuração de modelo](/docs/pt/interactive-mode#wait-for-a-usage-limit-to-reset) |2441| `quota_auto_resume_fired` | Claude Code continua sua tarefa após um limite de uso de claude.ai pausá-la: na redefinição, ou mais cedo quando algo que você faz em Claude Code durante a espera, como adicionar créditos de uso, atualizar seu plano ou mudar modelos, torna o uso disponível novamente, com a [exceção de configuração de modelo](/docs/pt/interactive-mode#wait-for-a-usage-limit-to-reset) |
2437| `quota_auto_resume_stale` | Um limite de uso de claude.ai foi redefinido enquanto seu computador dormia por mais de cerca de 30 minutos. Claude Code espera que você pressione `Enter` em vez de continuar. Após um sono mais curto, ele continua e dispara `quota_auto_resume_fired` em vez disso |2442| `quota_auto_resume_stale` | Um limite de uso de claude.ai foi redefinido enquanto seu computador dormia por mais de cerca de 30 minutos. Claude Code espera que você pressione `Enter` em vez de continuar. Após um sono mais curto, ele continua e dispara `quota_auto_resume_fired` em vez disso |
2438| `quota_auto_resume_disabled` | Claude Code termina sua espera por um limite de uso de claude.ai sem continuar sua tarefa: [`autoContinueAtUsageLimit`](/docs/pt/settings-reference#autocontinueatusagelimit) foi desativado ou a redefinição se moveu mais de 24 horas no futuro durante uma espera que Claude Code iniciou por conta própria, a tarefa continuada continuou atingindo o limite, ou a continuação foi bloqueada antes de chegar ao modelo. Não é disparado quando você pressiona `Esc` ou `Ctrl+C`, ou escolhe **Don't continue automatically** |2443| `quota_auto_resume_disabled` | Claude Code termina sua espera por um limite de uso de claude.ai sem continuar sua tarefa: [`autoContinueAtUsageLimit`](/docs/pt/settings-reference#autocontinueatusagelimit) foi desativado ou a redefinição se moveu mais de 24 horas durante uma espera que Claude Code iniciou por conta própria, a tarefa continuada continuou atingindo o limite, ou a continuação foi bloqueada antes de chegar ao modelo. Não dispara quando você pressiona `Esc` ou `Ctrl+C`, ou escolhe **Don't continue automatically** |
2439 2444
2440Os tipos `agent_needs_input` e `agent_completed` requerem Claude Code v2.1.198 ou posterior.2445Os tipos `agent_needs_input` e `agent_completed` requerem Claude Code v2.1.198 ou posterior.
2441 2446
2443 2448
2444Em sessões de terminal, `permission_prompt` para a solicitação de rede de um comando em sandbox requer Claude Code v2.1.246 ou posterior.2449Em sessões de terminal, `permission_prompt` para a solicitação de rede de um comando em sandbox requer Claude Code v2.1.246 ou posterior.
2445 2450
2446`agent_needs_input` para a pergunta de configuração de terminal de um colega requer Claude Code v2.1.248 ou posterior.2451`agent_needs_input` para a pergunta de configuração de terminal de um colega de equipe requer Claude Code v2.1.248 ou posterior.
2447 2452
2448<Note>2453<Note>
2449 Os tipos `permission_prompt`, `idle_prompt`, `elicitation_dialog` e `elicitation_url_dialog` compartilham seu tempo com notificações de desktop, portanto em sessões de terminal você só os vê quando parece que você está longe do terminal:2454 Os tipos `permission_prompt`, `idle_prompt`, `elicitation_dialog` e `elicitation_url_dialog` compartilham seu tempo com notificações de desktop, então em sessões de terminal você só os vê quando parece que você está longe do terminal:
2450 2455
2451 * Espere `permission_prompt` uma vez que você não digitou por cerca de seis segundos. O temporizador começa quando o prompt de permissão aparece, e cada pressionamento de tecla o adia. Para executar um hook imediatamente quando Claude pede permissão para usar uma ferramenta, use [PermissionRequest](#permissionrequest) em vez disso.2456 * Espere `permission_prompt` uma vez que você não digitou por cerca de seis segundos. O temporizador começa quando o prompt de permissão aparece, e cada pressionamento de tecla o adia. Para executar um hook imediatamente quando Claude pede permissão para usar uma ferramenta, use [PermissionRequest](#permissionrequest) em vez disso.
2452 * Espere `idle_prompt` cerca de 60 segundos após Claude terminar de responder, e apenas se você não digitou desde então. Claude Code não envia `idle_prompt` enquanto espera um limite de uso de claude.ai ser redefinido. Quando a espera termina por conta própria, um dos tipos `quota_auto_resume_*` é disparado em vez disso.2457 * Espere `idle_prompt` cerca de 60 segundos após Claude terminar de responder, e apenas se você não digitou desde então. Claude Code não envia `idle_prompt` enquanto espera um limite de uso de claude.ai ser redefinido. Quando a espera termina por conta própria, um dos tipos `quota_auto_resume_*` dispara em vez disso.
2453 * Espere `elicitation_dialog` para um formulário de elicitação, ou `elicitation_url_dialog` para uma solicitação de URL do navegador, uma vez que você não digitou por cerca de seis segundos. Ambos compartilham o mesmo portão de seis segundos que `permission_prompt`: o temporizador começa quando o diálogo aparece, e cada pressionamento de tecla o adia.2458 * Espere `elicitation_dialog` para um formulário de elicitação, ou `elicitation_url_dialog` para uma solicitação de URL do navegador, uma vez que você não digitou por cerca de seis segundos. Ambos compartilham o mesmo portão de seis segundos que `permission_prompt`: o temporizador começa quando o diálogo aparece, e cada pressionamento de tecla o adia.
2454 2459
2455 Uma solicitação de permissão ou elicitação que chega enquanto outro diálogo está na tela mantém o mesmo portão de seis segundos, cronometrado a partir de quando a solicitação chega. Sua notificação pode alcançá-lo enquanto a solicitação ainda espera atrás do diálogo aberto.2460 Uma solicitação de permissão ou elicitação que chega enquanto outro diálogo está na tela mantém o mesmo portão de seis segundos, cronometrado a partir de quando a solicitação chega. Sua notificação pode alcançá-lo enquanto a solicitação ainda espera atrás do diálogo aberto.
2461* Se você ou um hook [PermissionRequest](#permissionrequest) responder mais cedo, Claude Code não executa `permission_prompt`.2466* Se você ou um hook [PermissionRequest](#permissionrequest) responder mais cedo, Claude Code não executa `permission_prompt`.
2462* Defina [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/pt/env-vars) como `1` para desativar `permission_prompt` nessas sessões.2467* Defina [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/pt/env-vars) como `1` para desativar `permission_prompt` nessas sessões.
2463 2468
2464Antes da v2.1.233, `permission_prompt` não era disparado nessas sessões.2469Antes da v2.1.233, `permission_prompt` não disparava nessas sessões.
2465 2470
2466Use matchers separados para executar diferentes manipuladores dependendo do tipo de notificação. Esta configuração dispara um script de alerta específico de permissão quando Claude precisa de aprovação de permissão e uma notificação diferente quando Claude está inativo:2471Use matchers separados para executar diferentes manipuladores dependendo do tipo de notificação. Esta configuração dispara um script de alerta específico de permissão quando Claude precisa de aprovação de permissão e uma notificação diferente quando Claude está ocioso:
2467 2472
2468```json theme={null}2473```json theme={null}
2469{2474{
2496 Entrada Notification2501 Entrada Notification
2497</h4>2502</h4>
2498 2503
2499Além dos [campos de entrada comuns](#common-input-fields), hooks Notification recebem `message` com o texto de notificação, um `title` opcional e `notification_type` indicando qual tipo foi disparado.2504Além dos [campos de entrada comuns](#common-input-fields), hooks Notification recebem `message` com o texto de notificação, um `title` opcional e `notification_type` indicando qual tipo disparou.
2500 2505
2501```json theme={null}2506```json theme={null}
2502{2507{
2510}2515}
2511```2516```
2512 2517
2513Hooks Notification não podem bloquear ou modificar notificações. Claude Code descarta seus campos `systemMessage` e `continue` mas ainda emite [`terminalSequence`](#emit-terminal-notifications), que é no que o exemplo de notificação de desktop se baseia. Hooks Notification são destinados a efeitos colaterais como encaminhar a notificação para um serviço externo.2518Hooks Notification não podem bloquear ou modificar notificações. Claude Code descarta seus campos `systemMessage` e `continue` mas ainda emite [`terminalSequence`](#emit-terminal-notifications), que é o que o exemplo de notificação de desktop depende. Hooks Notification são destinados a efeitos colaterais como encaminhar a notificação para um serviço externo.
2514 2519
2515<h3 id="subagentstart">2520<h3 id="subagentstart">
2516 SubagentStart2521 SubagentStart
2517</h3>2522</h3>
2518 2523
2519Executado quando Claude gera um subagente com a ferramenta Agent, quando Claude [retoma um subagente](/docs/pt/sub-agents#resume-subagents) e cada vez que um [colega de equipe de agente](/docs/pt/agent-teams) em processo manipula uma nova mensagem. Suporta matchers para filtrar por nome de tipo de agente. Para agentes integrados, este é o nome do agente como `general-purpose`, `Explore` ou `Plan`. Para [subagentes personalizados](/docs/pt/sub-agents), este é o campo `name` do frontmatter do agente, não o nome do arquivo.2524Executa quando Claude gera um subagente com a ferramenta Agent, quando Claude [retoma um subagente](/docs/pt/sub-agents#resume-subagents) e cada vez que um colega de equipe de [agente de equipe](/docs/pt/agent-teams) em processo lida com uma nova mensagem. Suporta matchers para filtrar por nome de tipo de agente. Para agentes integrados, este é o nome do agente como `general-purpose`, `Explore` ou `Plan`. Para [subagentes personalizados](/docs/pt/sub-agents), este é o campo `name` do frontmatter do agente, não o nome do arquivo.
2520 2525
2521Para subagentes enviados por um [plugin](/docs/pt/plugins/overview), o tipo de agente é o identificador com escopo de plugin como `my-plugin:reviewer`, não o nome de frontmatter simples. O dois-pontos coloca um nome com escopo de plugin no caminho de expressão regular, portanto ancor o matcher com `^` e `$` para uma correspondência exata: `^my-plugin:reviewer$`.2526Para subagentes enviados por um [plugin](/docs/pt/plugins/overview), o tipo de agente é o identificador com escopo de plugin como `my-plugin:reviewer`, não o nome de frontmatter simples. O dois-pontos coloca um nome com escopo de plugin no caminho de expressão regular, então ancorize o matcher com `^` e `$` para uma correspondência exata: `^my-plugin:reviewer$`.
2522 2527
2523<h4 id="subagentstart-input">2528<h4 id="subagentstart-input">
2524 Entrada SubagentStart2529 Entrada SubagentStart
2558 SubagentStop2563 SubagentStop
2559</h3>2564</h3>
2560 2565
2561Executado quando um subagente de Claude Code terminou de responder. Corresponde ao tipo de agente, mesmos valores que SubagentStart.2566Executa quando um subagente Claude Code terminou de responder. Corresponde ao tipo de agente, mesmos valores que SubagentStart.
2562 2567
2563<h4 id="subagentstop-input">2568<h4 id="subagentstop-input">
2564 Entrada SubagentStop2569 Entrada SubagentStop
2565</h4>2570</h4>
2566 2571
2567Além dos [campos de entrada comuns](#common-input-fields), hooks SubagentStop recebem `stop_hook_active`, `agent_id`, `agent_type`, `agent_transcript_path` e `last_assistant_message`. O campo `agent_type` é o valor usado para filtragem de matcher. O `transcript_path` é a transcrição da sessão principal, enquanto `agent_transcript_path` é a própria transcrição do subagente armazenada em uma pasta `subagents/` aninhada. O campo `last_assistant_message` contém o conteúdo de texto da resposta final do subagente, portanto hooks podem acessá-lo sem analisar o arquivo de transcrição.2572Além dos [campos de entrada comuns](#common-input-fields), hooks SubagentStop recebem `stop_hook_active`, `agent_id`, `agent_type`, `agent_transcript_path` e `last_assistant_message`. O campo `agent_type` é o valor usado para filtragem de matcher. O `transcript_path` é a transcrição da sessão principal, enquanto `agent_transcript_path` é a própria transcrição do subagente armazenada em uma pasta `subagents/` aninhada. O campo `last_assistant_message` contém o conteúdo de texto da resposta final do subagente, então hooks podem acessá-lo sem analisar o arquivo de transcrição.
2568 2573
2569Nem todo evento SubagentStop vem de um subagente que Claude gerou. Claude Code também executa agentes internos para alguns de seus próprios recursos, como [sugestões de prompt](/docs/pt/interactive-mode#prompt-suggestions) e [perguntas laterais `/btw`](/docs/pt/interactive-mode#side-questions-with-%2Fbtw), e SubagentStop é disparado quando um desses termina também. Para esses eventos, `agent_type` é o nome do agente que a sessão em si executa, como um definido com [`--agent`](/docs/pt/cli-reference#cli-flags) ou a configuração [`agent`](/docs/pt/settings-reference#agent), e uma string vazia quando a sessão é executada sem um.2574Nem todo evento SubagentStop vem de um subagente que Claude gerou. Claude Code também executa agentes internos para alguns de seus próprios recursos, como [sugestões de prompt](/docs/pt/interactive-mode#prompt-suggestions) e [perguntas laterais `/btw`](/docs/pt/interactive-mode#side-questions-with-%2Fbtw), e SubagentStop dispara quando um desses termina também. Para esses eventos, `agent_type` é o nome do agente que a sessão em si executa, como um definido com [`--agent`](/docs/pt/cli-reference#cli-flags) ou a configuração [`agent`](/docs/pt/settings-reference#agent), e uma string vazia quando a sessão é executada sem um.
2570 2575
2571Um `matcher` que nomeia tipos de agente não corresponde a um `agent_type` vazio. Um hook cujo matcher é omitido, `""` ou `"*"`, ou é uma expressão regular que corresponde a uma string vazia, é executado para eventos com um `agent_type` vazio também.2576Um `matcher` que nomeia tipos de agente não corresponde a um `agent_type` vazio. Um hook cujo matcher é omitido, `""` ou `"*"`, ou é uma expressão regular que corresponde a uma string vazia, é executado para eventos com um `agent_type` vazio também.
2572 2577
2597 TaskCreated2602 TaskCreated
2598</h3>2603</h3>
2599 2604
2600Executado quando uma tarefa está sendo criada via ferramenta `TaskCreate`. Use isso para impor convenções de nomenclatura, exigir descrições de tarefa ou impedir que certas tarefas sejam criadas. Em uma [sessão sem as ferramentas Task](/docs/pt/tools-reference#task-tool-availability), este evento não é disparado.2605Executa quando uma tarefa está sendo criada via ferramenta `TaskCreate`. Use isso para impor convenções de nomenclatura, exigir descrições de tarefa ou impedir que certas tarefas sejam criadas. Em uma [sessão sem as ferramentas Task](/docs/pt/tools-reference#task-tool-availability), este evento não dispara.
2601 2606
2602Hooks TaskCreated não suportam matchers e são disparados em cada ocorrência.2607Hooks TaskCreated não suportam matchers e disparam em cada ocorrência.
2603 2608
2604<h4 id="taskcreated-input">2609<h4 id="taskcreated-input">
2605 Entrada TaskCreated2610 Entrada TaskCreated
2626| `task_id` | Identificador da tarefa sendo criada |2631| `task_id` | Identificador da tarefa sendo criada |
2627| `task_subject` | Título da tarefa |2632| `task_subject` | Título da tarefa |
2628| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |2633| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |
2629| `teammate_name` | Nome do colega criando a tarefa. Pode estar ausente |2634| `teammate_name` | Nome do colega de equipe criando a tarefa. Pode estar ausente |
2630| `team_name` | Descontinuado. Nome de equipe derivado de sessão; será removido em uma versão futura |2635| `team_name` | Descontinuado. Nome de equipe derivado de sessão; será removido em uma versão futura |
2631 2636
2632<h4 id="taskcreated-decision-control">2637<h4 id="taskcreated-decision-control">
2633 Controle de decisão TaskCreated2638 Controle de decisão TaskCreated
2634</h4>2639</h4>
2635 2640
2636Um hook TaskCreated pode bloquear a criação de duas maneiras. De qualquer forma, Claude Code deleta a tarefa e retorna sua mensagem a Claude como o erro da ferramenta. Claude Code ignora `continue: false` deste evento e Claude continua trabalhando.2641Um hook TaskCreated pode bloquear a criação de duas maneiras. De qualquer forma, Claude Code exclui a tarefa e retorna sua mensagem ao Claude como o erro da ferramenta. Claude Code ignora `continue: false` deste evento e Claude continua trabalhando.
2637 2642
2638* **Código de saída 2**: Claude Code retorna o texto stderr como a mensagem.2643* **Código de saída 2**: Claude Code retorna o texto stderr como a mensagem.
2639* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code retorna `reason` como a mensagem.2644* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code retorna `reason` como a mensagem.
2657 TaskCompleted2662 TaskCompleted
2658</h3>2663</h3>
2659 2664
2660Executado 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 através da ferramenta TaskUpdate, ou quando um [colega de equipe de agente](/docs/pt/agent-teams) termina seu turno com tarefas em andamento. Use isso para impor critérios de conclusão como testes passando ou verificações de lint antes que uma tarefa possa fechar.2665Executa quando uma tarefa está sendo marcada como concluída. Isso dispara em duas situações: quando qualquer agente marca explicitamente uma tarefa como concluída através da ferramenta TaskUpdate, ou quando um colega de equipe de [agente de equipe](/docs/pt/agent-teams) termina seu turno com tarefas em andamento. Use isso para impor critérios de conclusão como testes passando ou verificações de lint antes de uma tarefa poder fechar.
2661 2666
2662Hooks TaskCompleted não suportam matchers e são disparados em cada ocorrência.2667Hooks TaskCompleted não suportam matchers e disparam em cada ocorrência.
2663 2668
2664<h4 id="taskcompleted-input">2669<h4 id="taskcompleted-input">
2665 Entrada TaskCompleted2670 Entrada TaskCompleted
2687| `task_id` | Identificador da tarefa sendo concluída |2692| `task_id` | Identificador da tarefa sendo concluída |
2688| `task_subject` | Título da tarefa |2693| `task_subject` | Título da tarefa |
2689| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |2694| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |
2690| `teammate_name` | Nome do colega concluindo a tarefa. Pode estar ausente |2695| `teammate_name` | Nome do colega de equipe concluindo a tarefa. Pode estar ausente |
2691| `team_name` | Descontinuado. Nome de equipe derivado de sessão; será removido em uma versão futura |2696| `team_name` | Descontinuado. Nome de equipe derivado de sessão; será removido em uma versão futura |
2692 2697
2693<h4 id="taskcompleted-decision-control">2698<h4 id="taskcompleted-decision-control">
2697Hooks TaskCompleted suportam duas maneiras de controlar a conclusão da tarefa:2702Hooks TaskCompleted suportam duas maneiras de controlar a conclusão da tarefa:
2698 2703
2699* **Código de saída 2**: a tarefa não é marcada como concluída e a mensagem stderr é retornada ao modelo como feedback.2704* **Código de saída 2**: a tarefa não é marcada como concluída e a mensagem stderr é retornada ao modelo como feedback.
2700* **JSON `{"continue": false, "stopReason": "..."}`**: quando um colega terminando seu turno disparou o evento, para o colega inteiramente, correspondendo ao comportamento do hook `Stop`. O `stopReason` é mostrado ao usuário. Quando a ferramenta `TaskUpdate` disparou o evento, Claude Code ignora `continue: false`; código de saída 2 ainda bloqueia a conclusão.2705* **JSON `{"continue": false, "stopReason": "..."}`**: quando um colega de equipe terminando seu turno disparou o evento, para o colega de equipe inteiramente, correspondendo ao comportamento do hook `Stop`. O `stopReason` é mostrado ao usuário. Quando a ferramenta `TaskUpdate` disparou o evento, Claude Code ignora `continue: false`; código de saída 2 ainda bloqueia a conclusão.
2701 2706
2702Este exemplo executa testes e bloqueia a conclusão da tarefa se falharem:2707Este exemplo executa testes e bloqueia a conclusão da tarefa se falharem:
2703 2708
2719 Stop2724 Stop
2720</h3>2725</h3>
2721 2726
2722Executado quando o agente principal de Claude Code terminou de responder. Não é executado se a parada ocorreu devido a uma interrupção do usuário. Erros de API disparam [StopFailure](#stopfailure) em vez disso.2727Executa quando o agente Claude Code principal terminou de responder. Não é executado se a parada ocorreu devido a uma interrupção do usuário. Erros de API disparam [StopFailure](#stopfailure) em vez disso.
2723 2728
2724<Tip>2729<Tip>
2725 O comando [`/goal`](/docs/pt/goal) é um atalho integrado para um hook Stop com escopo de sessão baseado em prompt. Use-o quando você quer que Claude continue trabalhando em direção a uma condição sem escrever configuração de hook.2730 O comando [`/goal`](/docs/pt/goal) é um atalho integrado para um hook Stop com escopo de sessão baseado em prompt. Use-o quando você quer que Claude continue trabalhando em direção a uma condição sem escrever configuração de hook.
2731 2736
2732Além dos [campos de entrada comuns](#common-input-fields), hooks Stop recebem `stop_hook_active`, `last_assistant_message`, `background_tasks` e `session_crons`. O campo `stop_hook_active` é `true` quando Claude Code já está continuando como resultado de um hook stop. Verifique este valor ou processe a transcrição para evitar bloquear em uma condição que nunca será resolvida. Claude Code aplica um limite de 8 continuações consecutivas: após hooks stop terem continuado o turno oito vezes seguidas, Claude Code sobrescreve o próximo bloqueio e termina o turno. Para aumentar o limite, defina [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/pt/env-vars).2737Além dos [campos de entrada comuns](#common-input-fields), hooks Stop recebem `stop_hook_active`, `last_assistant_message`, `background_tasks` e `session_crons`. O campo `stop_hook_active` é `true` quando Claude Code já está continuando como resultado de um hook stop. Verifique este valor ou processe a transcrição para evitar bloquear em uma condição que nunca será resolvida. Claude Code aplica um limite de 8 continuações consecutivas: após hooks stop terem continuado o turno oito vezes seguidas, Claude Code sobrescreve o próximo bloqueio e termina o turno. Para aumentar o limite, defina [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/pt/env-vars).
2733 2738
2734O campo `last_assistant_message` contém o conteúdo de texto da resposta final de Claude, portanto hooks podem acessá-lo sem analisar o arquivo de transcrição. Para hooks que agem no turno recém-concluído, como hooks de leitura em voz alta ou notificação, use este campo em vez de ler `transcript_path`: o arquivo de transcrição não é garantido incluir a mensagem final no tempo de Stop em todas as versões.2739O campo `last_assistant_message` contém o conteúdo de texto da resposta final do Claude, então hooks podem acessá-lo sem analisar o arquivo de transcrição. Para hooks que agem no turno recém-concluído, como hooks de leitura em voz alta ou notificação, use este campo em vez de ler `transcript_path`: o arquivo de transcrição não é garantido incluir a mensagem final no tempo de Stop em todas as versões.
2735 2740
2736Os arrays `background_tasks` e `session_crons` permitem que hooks distingam "sessão está feita" de "sessão está pausada esperando que trabalho de fundo a acorde novamente". Ambos os arrays estão presentes quando o registro de tarefas é alcançável e estão vazios quando nada está em voo ou agendado.2741Os arrays `background_tasks` e `session_crons` deixam hooks distinguir "sessão está feita" de "sessão está pausada esperando que trabalho de fundo a acorde novamente". Ambos os arrays estão presentes quando o registro de tarefas é alcançável e estão vazios quando nada está em voo ou agendado.
2737 2742
2738Cada entrada em `background_tasks` descreve uma tarefa em voo e usa esses campos:2743Cada entrada em `background_tasks` descreve uma tarefa em voo e usa esses campos:
2739 2744
2740| Campo | Descrição |2745| Campo | Descrição |
2741| :- | :- |2746| :- | :- |
2742| `id` | Identificador de tarefa |2747| `id` | Identificador de tarefa |
2743| `type` | Rótulo de tipo de tarefa amigável como `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session` ou `MCP task`. Cada rótulo identifica qual recurso de Claude Code criou a tarefa. Volta para o discriminante bruto para tipos não reconhecidos |2748| `type` | Rótulo de tipo de tarefa amigável como `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session` ou `MCP task`. Cada rótulo identifica qual recurso Claude Code criou a tarefa. Volta para o discriminante bruto para tipos não reconhecidos |
2744| `status` | Status atual da tarefa |2749| `status` | Status atual da tarefa |
2745| `description` | Descrição em texto livre, limitada a 1000 caracteres com um marcador `… [+N chars]` em string quando cortado |2750| `description` | Descrição em texto livre, limitada a 1000 caracteres com um marcador `… [+N chars]` em string quando cortado |
2746| `command` | Linha de comando de shell, limitada a 1000 caracteres. Presente apenas para tarefas `shell` |2751| `command` | Linha de comando de shell, limitada a 1000 caracteres. Presente apenas para tarefas `shell` |
2798| Campo | Descrição |2803| Campo | Descrição |
2799| :- | :- |2804| :- | :- |
2800| `decision` | `"block"` impede que Claude pare. Omita para permitir que Claude pare |2805| `decision` | `"block"` impede que Claude pare. Omita para permitir que Claude pare |
2801| `reason` | Obrigatório quando `decision` é `"block"`. Diz a Claude por que deve continuar |2806| `reason` | Obrigatório quando `decision` é `"block"`. Diz ao Claude por que deve continuar |
2802| `hookSpecificOutput.additionalContext` | Feedback sem erro para Claude. A conversa continua para que Claude possa agir sobre ele, mas ao contrário de `decision: "block"` é mostrado na transcrição como feedback de hook em vez de um erro de hook |2807| `hookSpecificOutput.additionalContext` | Feedback sem erro para Claude. A conversa continua para que Claude possa agir sobre ele, mas ao contrário de `decision: "block"` é mostrado na transcrição como feedback de hook em vez de um erro de hook |
2803 2808
2804Um hook que bloqueia ao sair com 2 roteia da mesma forma que `reason`: Claude recebe a mensagem stderr como a explicação para por que deve continuar.2809Um hook que bloqueia ao sair com 2 roteia da mesma forma que `reason`: Claude recebe a mensagem stderr como a explicação para por que deve continuar.
2810}2815}
2811```2816```
2812 2817
2813Use `additionalContext` quando o hook está funcionando conforme projetado e dando orientação a Claude, como "execute a suite de testes antes de terminar". Mantém a conversa passando através das mesmas proteções de loop que `decision: "block"`, a saber a entrada `stop_hook_active` e o limite de 8 continuações consecutivas, mas a transcrição a rotula como `Stop hook feedback` e nenhuma notificação de erro de hook é mostrada:2818Use `additionalContext` quando o hook está funcionando como projetado e dando orientação ao Claude, como "execute a suite de testes antes de terminar". Mantém a conversa passando através das mesmas proteções de loop que `decision: "block"`, a saber a entrada `stop_hook_active` e o limite de 8 continuações consecutivas, mas a transcrição a rotula como `Stop hook feedback` e nenhuma notificação de erro de hook é mostrada:
2814 2819
2815```json theme={null}2820```json theme={null}
2816{2821{
2825 StopFailure2830 StopFailure
2826</h3>2831</h3>
2827 2832
2828Executado em vez de [Stop](#stop) quando o turno termina devido a um erro de API. Claude Code ignora a saída e código de saída do hook, além de [`terminalSequence`](#emit-terminal-notifications). Use isso para registrar falhas, enviar alertas ou tomar ações de recuperação quando Claude não pode completar uma resposta devido a limites de taxa, problemas de autenticação ou outros erros de API.2833Executa em vez de [Stop](#stop) quando o turno termina devido a um erro de API. Claude Code ignora a saída e código de saída do hook, além de [`terminalSequence`](#emit-terminal-notifications). Use isso para registrar falhas, enviar alertas ou tomar ações de recuperação quando Claude não pode completar uma resposta devido a limites de taxa, problemas de autenticação ou outros erros de API.
2829 2834
2830<h4 id="stopfailure-input">2835<h4 id="stopfailure-input">
2831 Entrada StopFailure2836 Entrada StopFailure
2837| :- | :- |2842| :- | :- |
2838| `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` |2843| `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` |
2839| `error_details` | Detalhes adicionais sobre o erro, quando disponível |2844| `error_details` | Detalhes adicionais sobre o erro, quando disponível |
2840| `last_assistant_message` | O texto de erro renderizado mostrado na conversa. Ao contrário de `Stop` e `SubagentStop`, onde este campo contém a saída conversacional de Claude, para `StopFailure` ele contém a string de erro da API em si, como `"API Error: Rate limit reached"` |2845| `last_assistant_message` | O texto de erro renderizado mostrado na conversa. Ao contrário de `Stop` e `SubagentStop`, onde este campo contém a saída conversacional do Claude, para `StopFailure` ele contém a string de erro da API em si, como `"API Error: Rate limit reached"` |
2841 2846
2842```json theme={null}2847```json theme={null}
2843{2848{
2857 TeammateIdle2862 TeammateIdle
2858</h3>2863</h3>
2859 2864
2860Executado quando um [colega de equipe de agente](/docs/pt/agent-teams) está prestes a ficar inativo após terminar seu turno. Use isso para impor portões de qualidade antes que um colega pare de trabalhar, como exigir verificações de lint passando ou verificar que arquivos de saída existem.2865Executa quando um colega de equipe de [agente de equipe](/docs/pt/agent-teams) está prestes a ficar ocioso após terminar seu turno. Use isso para impor portões de qualidade antes de um colega de equipe parar de trabalhar, como exigir verificações de lint passando ou verificar que arquivos de saída existem.
2861 2866
2862Hooks TeammateIdle não suportam matchers e são disparados em cada ocorrência.2867Hooks TeammateIdle não suportam matchers e disparam em cada ocorrência.
2863 2868
2864<h4 id="teammateidle-input">2869<h4 id="teammateidle-input">
2865 Entrada TeammateIdle2870 Entrada TeammateIdle
2881 2886
2882| Campo | Descrição |2887| Campo | Descrição |
2883| :- | :- |2888| :- | :- |
2884| `teammate_name` | Nome do colega que está prestes a ficar inativo |2889| `teammate_name` | Nome do colega de equipe que está prestes a ficar ocioso |
2885| `team_name` | Descontinuado. Nome de equipe derivado de sessão; será removido em uma versão futura |2890| `team_name` | Descontinuado. Nome de equipe derivado de sessão; será removido em uma versão futura |
2886 2891
2887<h4 id="teammateidle-decision-control">2892<h4 id="teammateidle-decision-control">
2888 Controle de decisão TeammateIdle2893 Controle de decisão TeammateIdle
2889</h4>2894</h4>
2890 2895
2891Hooks TeammateIdle suportam duas maneiras de controlar o comportamento do colega:2896Hooks TeammateIdle suportam duas maneiras de controlar o comportamento do colega de equipe:
2892 2897
2893* **Código de saída 2**: o colega recebe a mensagem stderr como feedback e continua trabalhando em vez de ficar inativo.2898* **Código de saída 2**: o colega de equipe recebe a mensagem stderr como feedback e continua trabalhando em vez de ficar ocioso.
2894* **JSON `{"continue": false, "stopReason": "..."}`**: para o colega inteiramente, correspondendo ao comportamento do hook `Stop`. O `stopReason` é mostrado ao usuário.2899* **JSON `{"continue": false, "stopReason": "..."}`**: para o colega de equipe inteiramente, correspondendo ao comportamento do hook `Stop`. O `stopReason` é mostrado ao usuário.
2895 2900
2896Este exemplo verifica que um artefato de compilação existe antes de permitir que um colega fique inativo:2901Este exemplo verifica se um artefato de compilação existe antes de permitir que um colega de equipe fique ocioso:
2897 2902
2898```bash theme={null}2903```bash theme={null}
2899#!/bin/bash2904#!/bin/bash
2910 ConfigChange2915 ConfigChange
2911</h3>2916</h3>
2912 2917
2913Executado quando um arquivo de configuração muda durante uma sessão. Use isso para auditar mudanças de configurações, impor políticas de segurança ou bloquear modificações não autorizadas em arquivos de configuração.2918Executa quando um arquivo de configuração muda durante uma sessão. Use isso para auditar mudanças de configurações, impor políticas de segurança ou bloquear modificações não autorizadas em arquivos de configuração.
2914 2919
2915Claude Code executa hooks ConfigChange quando um arquivo de configurações, um arquivo de política gerenciada ou um arquivo de skill muda. Para política gerenciada, ele os executa apenas quando `managed-settings.json` ou um arquivo em `managed-settings.d/` muda. Ele aplica [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) e mudanças em preferências gerenciadas macOS ou política de registro Windows sem executá-los. Em WSL com [`wslInheritsWindowsSettings`](/docs/pt/settings-reference#wslinheritswindowssettings), ele também aplica um arquivo de configurações gerenciadas do lado Windows alterado em sua pesquisa de política sem executá-los.2920Claude Code executa hooks ConfigChange quando um arquivo de configurações, um arquivo de política gerenciada ou um arquivo de skill muda. Para política gerenciada, ele os executa apenas quando `managed-settings.json` ou um arquivo em `managed-settings.d/` muda. Ele aplica [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) e mudanças em preferências gerenciadas macOS ou política de registro Windows sem executá-los. Em WSL com [`wslInheritsWindowsSettings`](/docs/pt/settings-reference#wslinheritswindowssettings), ele também aplica um arquivo de configurações gerenciadas do lado Windows alterado em sua pesquisa de política sem executá-los.
2916 2921
2979}2984}
2980```2985```
2981 2986
2982Mudanças `policy_settings` não podem ser bloqueadas. Hooks ainda são disparados para fontes `policy_settings` quando um arquivo de configurações gerenciadas na máquina muda, portanto você pode usá-los para registrar essas edições, mas qualquer decisão de bloqueio é ignorada. Isso garante que as configurações gerenciadas pela empresa sempre entrem em vigor. Claude Code não executa hooks `ConfigChange` quando [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) chegam ou são atualizadas.2987Mudanças `policy_settings` não podem ser bloqueadas. Hooks ainda disparam para fontes `policy_settings` quando um arquivo de configurações gerenciadas na máquina muda, então você pode usá-los para registrar essas edições, mas qualquer decisão de bloqueio é ignorada. Isso garante que configurações gerenciadas pela empresa sempre entrem em vigor. Claude Code não executa hooks `ConfigChange` quando [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) chegam ou são atualizadas.
2983 2988
2984Claude Code atua na decisão de bloqueio da saída JSON de um hook ConfigChange e descarta `systemMessage` e `continue`. Uma mudança bloqueada não exibe nenhuma mensagem para você ou para Claude, independentemente de você bloquear com `reason` ou com stderr ao sair com 2. Claude Code apenas escreve uma linha no log de depuração.2989Claude Code age na decisão de bloqueio da saída JSON de um hook ConfigChange e descarta `systemMessage` e `continue`. Uma mudança bloqueada não exibe nenhuma mensagem para você ou para Claude, independentemente de você bloquear com `reason` ou com stderr ao sair com 2. Claude Code apenas escreve uma linha no log de depuração.
2985 2990
2986<h3 id="cwdchanged">2991<h3 id="cwdchanged">
2987 CwdChanged2992 CwdChanged
2988</h3>2993</h3>
2989 2994
2990Executado quando um comando de shell na conversa principal muda o diretório de trabalho, por exemplo quando Claude executa um comando `cd`. Use isso para reagir a mudanças de diretório: recarregar variáveis de ambiente, ativar toolchains específicas do projeto ou executar scripts de configuração automaticamente. Emparelha com [FileChanged](#filechanged) para ferramentas como [direnv](https://direnv.net/) que gerenciam ambiente por diretório.2995Executa quando um comando de shell na conversa principal muda o diretório de trabalho, por exemplo quando Claude executa um comando `cd`. Use isso para reagir a mudanças de diretório: recarregar variáveis de ambiente, ativar toolchains específicas do projeto ou executar scripts de configuração automaticamente. Emparelha com [FileChanged](#filechanged) para ferramentas como [direnv](https://direnv.net/) que gerenciam ambiente por diretório.
2991 2996
2992Hooks CwdChanged têm acesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Variáveis escritas nesse arquivo persistem em comandos Bash subsequentes até o próximo evento CwdChanged, quando Claude Code as limpa.2997Hooks CwdChanged têm acesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Variáveis escritas nesse arquivo persistem em comandos Bash subsequentes até o próximo evento CwdChanged, quando Claude Code as limpa.
2993 2998
2994CwdChanged não suporta matchers e é disparado em cada ocorrência.2999CwdChanged não suporta matchers e dispara em cada ocorrência.
2995 3000
2996<h4 id="cwdchanged-input">3001<h4 id="cwdchanged-input">
2997 Entrada CwdChanged3002 Entrada CwdChanged
3022 3027
3023Hooks CwdChanged não têm controle de decisão. Eles não podem bloquear a mudança de diretório.3028Hooks CwdChanged não têm controle de decisão. Eles não podem bloquear a mudança de diretório.
3024 3029
3025Claude Code lê `watchPaths` e `systemMessage` de sua saída JSON e descarta `continue`. Em sessões interativas, mostra o `systemMessage` como uma breve notificação de terminal. A mensagem não chega ao fluxo de mensagens do SDK.3030Claude Code lê `watchPaths` e `systemMessage` de sua saída JSON e descarta `continue`. Em sessões interativas, mostra o `systemMessage` como uma notificação de terminal breve. A mensagem não chega ao fluxo de mensagens do SDK.
3026 3031
3027<h3 id="directoryadded">3032<h3 id="directoryadded">
3028 DirectoryAdded3033 DirectoryAdded
3029</h3>3034</h3>
3030 3035
3031Executado após você adicionar um diretório de trabalho no meio da sessão com o comando `/add-dir`, ou após um cliente SDK adicionar um com a solicitação de controle `register_repo_root`. Use isso para preparar um repositório recém-adicionado, por exemplo instalando suas dependências.3036Executa após você adicionar um diretório de trabalho no meio da sessão com o comando `/add-dir`, ou após um cliente SDK adicionar um com a solicitação de controle `register_repo_root`. Use isso para preparar um repositório recém-adicionado, por exemplo instalando suas dependências.
3032 3037
3033Claude Code não dispara este evento quando:3038Claude Code não dispara este evento quando:
3034 3039
3036* Você adiciona um diretório na aba Workspace `/permissions`3041* Você adiciona um diretório na aba Workspace `/permissions`
3037* Você adiciona um diretório que já é um diretório de trabalho ou está dentro de um3042* Você adiciona um diretório que já é um diretório de trabalho ou está dentro de um
3038 3043
3039Claude Code dispara DirectoryAdded após atualizar estado de sandbox e permissão, portanto ferramentas em sandbox já veem o novo diretório quando seu hook é executado. Comandos de hook em si são executados sem sandbox.3044Claude Code dispara DirectoryAdded após atualizar estado de sandbox e permissão, então ferramentas em sandbox já veem o novo diretório quando seu hook é executado. Comandos de hook em si são executados sem sandbox.
3040 3045
3041Claude Code não espera pelo hook: a adição é concluída imediatamente, e o hook é executado em segundo plano com o tempo limite padrão de 600 segundos.3046Claude Code não espera pelo hook: a adição é concluída imediatamente, e o hook é executado em segundo plano com o tempo limite padrão de 600 segundos.
3042 3047
3071 3076
3072Hooks DirectoryAdded não têm controle de decisão. Eles não podem bloquear a adição, que já foi concluída quando o hook é executado. Claude Code descarta o campo `continue` de sua saída JSON e exibe o resto diferentemente por fonte:3077Hooks DirectoryAdded não têm controle de decisão. Eles não podem bloquear a adição, que já foi concluída quando o hook é executado. Claude Code descarta o campo `continue` de sua saída JSON e exibe o resto diferentemente por fonte:
3073 3078
3074* `slash_command`: Claude Code entrega o `systemMessage` do hook a Claude como contexto no próximo turno de conversa, em vez de mostrar a você. Uma contagem de hooks falhados aparece na transcrição. Saída de falha completa vai para o log de depuração3079* `slash_command`: Claude Code entrega o `systemMessage` do hook ao Claude como contexto no próximo turno de conversa, em vez de mostrar a você. Uma contagem de hooks falhados aparece na transcrição. Saída de falha completa vai para o log de depuração
3075* `register_repo_root`: Claude Code escreve saída `systemMessage` e saída de falha apenas no log de depuração3080* `register_repo_root`: Claude Code escreve saída `systemMessage` e saída de falha apenas no log de depuração
3076 3081
3077<h3 id="filechanged">3082<h3 id="filechanged">
3078 FileChanged3083 FileChanged
3079</h3>3084</h3>
3080 3085
3081Executado quando um arquivo observado muda no disco. Claude Code detecta mudanças com um observador de sistema de arquivos, não inspecionando chamadas de ferramenta, portanto executa o hook não importa o que mudou o arquivo: uma chamada de ferramenta `Edit` ou `Write`, um script que Claude executa com `Bash`, ou um processo fora de Claude Code inteiramente. Um uso comum é recarregar variáveis de ambiente quando arquivos de configuração do projeto mudam.3086Executa quando um arquivo observado muda no disco. Claude Code detecta mudanças com um observador de sistema de arquivos, não inspecionando chamadas de ferramenta, então executa o hook não importa o que mudou o arquivo: uma chamada de ferramenta `Edit` ou `Write`, um script que Claude executa com `Bash`, ou um processo fora de Claude Code inteiramente. Um uso comum é recarregar variáveis de ambiente quando arquivos de configuração do projeto mudam.
3082 3087
3083O `matcher` para este evento serve dois papéis:3088O `matcher` para este evento serve dois papéis:
3084 3089
3085* **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, portanto `".envrc|.env"` observa exatamente esses dois arquivos. Padrões regex não são úteis aqui: um valor como `^\.env` observaria um arquivo literalmente nomeado `^\.env`.3090* **Construir a lista de observação**: o valor é dividido em `|` e cada segmento é registrado como um nome de arquivo literal no diretório de trabalho, então `".envrc|.env"` observa exatamente esses dois arquivos. Padrões regex não são úteis aqui: um valor como `^\.env` observaria um arquivo literalmente nomeado `^\.env`.
3086* **Filtrar quais hooks são executados**: quando um arquivo observado muda, o mesmo valor filtra quais grupos de hook são executados usando as [regras de matcher](#matcher-patterns) padrão contra o nome base do arquivo alterado.3091* **Filtrar quais hooks são executados**: quando um arquivo observado muda, o mesmo valor filtra quais grupos de hook são executados usando as [regras de matcher](#matcher-patterns) padrão contra o nome base do arquivo alterado.
3087 3092
3088Este exemplo normaliza terminações de linha em `data.csv` após qualquer mudança, incluindo um comando `Bash` ou um script externo reescrevendo o arquivo:3093Este exemplo normaliza terminações de linha em `data.csv` após qualquer mudança, incluindo um comando `Bash` ou um script externo reescrevendo o arquivo:
3105}3110}
3106```3111```
3107 3112
3108O hook lê o caminho absoluto do arquivo alterado do campo `file_path` da [entrada JSON](#filechanged-input) em stdin. Sua guarda `grep` testa a mesma coisa que `perl` remove, um CR no final de uma linha, portanto a execução após uma normalização sai sem tocar no arquivo. Uma guarda mais solta faz um loop para sempre, porque `perl -i` reescreve o arquivo mesmo quando não substitui nada e Claude Code executa o hook novamente após cada reescrita. Salve este script em `/path/to/normalize-line-endings.sh` e torne-o executável:3113O hook lê o caminho absoluto do arquivo alterado do campo `file_path` da [entrada JSON](#filechanged-input) em stdin. Sua guarda `grep` testa a mesma coisa que `perl` remove, um CR no final de uma linha, então a execução após uma normalização sai sem tocar no arquivo. Uma guarda mais solta faz um loop infinito, porque `perl -i` reescreve o arquivo mesmo quando não substitui nada e Claude Code executa o hook novamente após cada reescrita. Salve este script em `/path/to/normalize-line-endings.sh` e torne-o executável:
3109 3114
3110```bash theme={null}3115```bash theme={null}
3111#!/bin/bash3116#!/bin/bash
3115fi3120fi
3116```3121```
3117 3122
3118Para confirmar que o hook funciona, peça a Claude para anexar uma linha CRLF a `data.csv` com um comando `Bash`. Claude Code executa o hook e o arquivo termina com terminações LF.3123Para confirmar que o hook funciona, peça ao Claude para anexar uma linha CRLF a `data.csv` com um comando `Bash`. Claude Code executa o hook e o arquivo termina com terminações LF.
3119 3124
3120Para observar arquivos que você não pode nomear antecipadamente, retorne [`watchPaths`](#filechanged-output) de um hook para atualizar a lista de observação dinamicamente. Claude Code inicia o observador apenas quando algo nomeia um arquivo para observar, portanto semeie a lista com um grupo FileChanged cujo matcher nomeia pelo menos um arquivo, ou com um hook [SessionStart](#sessionstart-decision-control) ou [CwdChanged](#cwdchanged) que retorna `watchPaths`. O matcher ainda filtra quais grupos de hook são executados quando um arquivo observado muda, portanto dê ao grupo que manipula caminhos dinâmicos um matcher omitido, que corresponde a cada arquivo observado e não adiciona nada à lista de observação. Um matcher `"*"` também corresponde a cada arquivo, mas Claude Code o registra na lista de observação como um arquivo literal nomeado `*`.3125Para observar arquivos que você não pode nomear antecipadamente, retorne [`watchPaths`](#filechanged-output) de um hook para atualizar a lista de observação dinamicamente. Claude Code inicia o observador apenas quando algo nomeia um arquivo para observar, então semeie a lista com um grupo FileChanged cujo matcher nomeia pelo menos um arquivo, ou com um hook [SessionStart](#sessionstart-decision-control) ou [CwdChanged](#cwdchanged) que retorna `watchPaths`. O matcher ainda filtra quais grupos de hook são executados quando um arquivo observado muda, então dê ao grupo que lida com caminhos dinâmicos um matcher omitido, que corresponde a cada arquivo observado e não adiciona nada à lista de observação. Um matcher `"*"` também corresponde a cada arquivo, mas Claude Code o registra na lista de observação como qualquer outro valor, como um arquivo literal nomeado `*`.
3121 3126
3122Hooks FileChanged têm acesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Variáveis escritas nesse arquivo persistem em comandos Bash subsequentes até o próximo evento [CwdChanged](#cwdchanged), quando Claude Code as limpa.3127Hooks FileChanged têm acesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Variáveis escritas nesse arquivo persistem em comandos Bash subsequentes até o próximo evento [CwdChanged](#cwdchanged), quando Claude Code as limpa.
3123 3128
3130| Campo | Descrição |3135| Campo | Descrição |
3131| :- | :- |3136| :- | :- |
3132| `file_path` | Caminho absoluto para o arquivo que mudou |3137| `file_path` | Caminho absoluto para o arquivo que mudou |
3133| `event` | O que aconteceu: `"change"` para um arquivo modificado, `"add"` para um arquivo criado ou `"unlink"` para um arquivo deletado |3138| `event` | O que aconteceu: `"change"` para um arquivo modificado, `"add"` para um arquivo criado ou `"unlink"` para um arquivo excluído |
3134 3139
3135```json theme={null}3140```json theme={null}
3136{3141{
3155 3160
3156Hooks FileChanged não têm controle de decisão. Eles não podem bloquear a mudança de arquivo de ocorrer.3161Hooks FileChanged não têm controle de decisão. Eles não podem bloquear a mudança de arquivo de ocorrer.
3157 3162
3158Claude Code lê `watchPaths` e `systemMessage` de sua saída JSON e descarta `continue`. Em sessões interativas, mostra o `systemMessage` como uma breve notificação de terminal. A mensagem não chega ao fluxo de mensagens do SDK.3163Claude Code lê `watchPaths` e `systemMessage` de sua saída JSON e descarta `continue`. Em sessões interativas, mostra o `systemMessage` como uma notificação de terminal breve. A mensagem não chega ao fluxo de mensagens do SDK.
3159 3164
3160<h3 id="worktreecreate">3165<h3 id="worktreecreate">
3161 WorktreeCreate3166 WorktreeCreate
3162</h3>3167</h3>
3163 3168
3164Executado quando uma worktree está sendo criada, seja de `claude --worktree`, de um [subagente usando `isolation: "worktree"`](/docs/pt/sub-agents#choose-the-subagent-scope), ou para uma [sessão de fundo](/docs/pt/agent-view#how-file-edits-are-isolated) que Claude Code isola em sua própria worktree. Por padrão, Claude Code cria a cópia de trabalho isolada com `git worktree`. Configurar um hook WorktreeCreate substitui esse comportamento git padrão, permitindo que você use um sistema de controle de versão diferente como SVN, Perforce ou Mercurial.3169Executa quando uma worktree está sendo criada, seja de `claude --worktree`, de um [subagente usando `isolation: "worktree"`](/docs/pt/sub-agents#choose-the-subagent-scope), ou para uma [sessão de fundo](/docs/pt/agent-view#how-file-edits-are-isolated) que Claude Code isola em sua própria worktree. Por padrão, Claude Code cria a cópia de trabalho isolada com `git worktree`. Configurar um hook WorktreeCreate substitui esse comportamento git padrão, permitindo que você use um sistema de controle de versão diferente como SVN, Perforce ou Mercurial.
3165 3170
3166Como o hook substitui o comportamento padrão inteiramente, [`.worktreeinclude`](/docs/pt/worktrees#copy-gitignored-files-into-worktrees) não é processado. Se você precisar copiar arquivos de configuração local como `.env` para a nova worktree, faça-o dentro de seu script de hook.3171Como o hook substitui o comportamento padrão inteiramente, [`.worktreeinclude`](/docs/pt/worktrees#copy-gitignored-files-into-worktrees) não é processado. Se você precisar copiar arquivos de configuração local como `.env` para a nova worktree, faça-o dentro de seu script de hook.
3167 3172
3168O hook deve retornar o caminho para o diretório de worktree criado. Claude Code usa este caminho como o diretório de trabalho para a sessão isolada. Veja [saída WorktreeCreate](#worktreecreate-output) para como cada tipo de hook retorna o caminho.3173O hook deve retornar o caminho para o diretório de worktree criado. Claude Code usa este caminho como o diretório de trabalho para a sessão isolada. Veja [saída WorktreeCreate](#worktreecreate-output) para como cada tipo de hook retorna o caminho.
3169 3174
3170Claude Code atua no sucesso do hook e no caminho retornado, e descarta `systemMessage` e `continue`.3175Claude Code age no sucesso do hook e no caminho retornado, e descarta `systemMessage` e `continue`.
3171 3176
3172Este exemplo cria uma cópia de trabalho SVN e imprime o caminho para Claude Code usar. Substitua a URL do repositório pela sua própria:3177Este exemplo cria uma cópia de trabalho SVN e imprime o caminho para Claude Code usar. Substitua a URL do repositório pela sua própria:
3173 3178
3210 Saída WorktreeCreate3215 Saída WorktreeCreate
3211</h4>3216</h4>
3212 3217
3213Hooks WorktreeCreate não usam o modelo de decisão padrão permitir/bloquear. Em vez disso, o sucesso ou falha do hook determina o resultado. O hook deve retornar o caminho para o diretório de worktree criado:3218Hooks WorktreeCreate não usam o modelo de decisão permitir/bloquear padrão. Em vez disso, o sucesso ou falha do hook determina o resultado. O hook deve retornar o caminho para o diretório de worktree criado:
3214 3219
3215* **Hooks de comando** (`type: "command"`): imprima o caminho como a última linha não vazia de stdout. Claude Code remove códigos de escape ANSI antes de ler essa linha, portanto banners de startup de shell impressos antes de seu `echo` são ignorados. Redirecione qualquer outra saída de hook para stderr.3220* **Hooks de comando** (`type: "command"`): imprima o caminho como a última linha não vazia de stdout. Claude Code remove códigos de escape ANSI antes de ler essa linha, então banners de startup de shell impressos antes de seu `echo` são ignorados. Redirecione qualquer outra saída de hook para stderr.
3216* **Hooks HTTP** (`type: "http"`): retorne `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` no corpo da resposta.3221* **Hooks HTTP** (`type: "http"`): retorne `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` no corpo da resposta.
3217 3222
3218Se o hook falhar ou não produzir um caminho, a criação de worktree falha com um erro.3223Se o hook falhar ou não produzir um caminho, a criação de worktree falha com um erro.
3219 3224
3220Claude Code resolve um caminho relativo contra o diretório em que o hook foi executado, colapsando qualquer segmento `.` ou `..` nele. Se o caminho resultante não for um diretório que Claude Code possa entrar, a sessão imprime um erro nomeando o caminho e sai com código 1.3225Claude Code resolve um caminho relativo contra o diretório em que o hook foi executado, colapsando quaisquer segmentos `.` ou `..` nele. Se o caminho resultante não for um diretório que Claude Code possa entrar, a sessão imprime um erro nomeando o caminho e sai com código 1.
3221 3226
3222Claude Code recusa um caminho absoluto que contém segmentos `.` ou `..`, e qualquer caminho que passa através de um symlink abaixo da raiz do repositório, porque um symlink comprometido no repositório poderia redirecionar a worktree para fora dele. O erro nomeia o componente rejeitado. Retorne um caminho normalizado que não passa através de um symlink dentro do repositório. Antes da v2.1.216, a criação de worktree seguia o caminho do hook sem essa triagem.3227Claude Code recusa um caminho absoluto que contém segmentos `.` ou `..`, e qualquer caminho que passa através de um symlink abaixo da raiz do repositório, porque um symlink comprometido no repositório poderia redirecionar a worktree para fora dele. O erro nomeia o componente rejeitado. Retorne um caminho normalizado que não passa através de um symlink dentro do repositório. Antes da v2.1.216, a criação de worktree seguia o caminho do hook sem essa triagem.
3223 3228
3225 WorktreeRemove3230 WorktreeRemove
3226</h3>3231</h3>
3227 3232
3228Executado quando uma worktree está sendo removida. Este é o equivalente de limpeza para [WorktreeCreate](#worktreecreate). O evento é disparado quando:3233Executa quando uma worktree está sendo removida. Este é o equivalente de limpeza para [WorktreeCreate](#worktreecreate). O evento dispara quando:
3229 3234
3230* você sai de uma sessão `--worktree` e escolhe removê-la3235* você sai de uma sessão `--worktree` e escolhe removê-la
3231* um subagente com `isolation: "worktree"` termina3236* um subagente com `isolation: "worktree"` termina
3232* você deleta uma [sessão de fundo](/docs/pt/agent-view#what-deleting-a-session-removes) cuja worktree o hook criou3237* você exclui uma [sessão de fundo](/docs/pt/agent-view#what-deleting-a-session-removes) cuja worktree o hook criou
3233 3238
3234Para worktrees baseadas em git, Claude Code manipula limpeza automaticamente com `git worktree remove`. Se você configurou um hook WorktreeCreate, emparelhe-o com um hook WorktreeRemove para controlar limpeza das worktrees que ele cria:3239Para worktrees baseadas em git, Claude Code lida com limpeza automaticamente com `git worktree remove`. Se você configurou um hook WorktreeCreate, emparelhe-o com um hook WorktreeRemove para controlar a limpeza das worktrees que ele cria:
3235 3240
3236* **Sem hook WorktreeRemove**: quando você sai de uma sessão `--worktree` e escolhe remoção, Claude Code volta para `git worktree remove --force` no caminho que seu hook WorktreeCreate retornou, portanto uma worktree que git reconhece é removida. Uma worktree que git não reconhece, por exemplo uma que seu hook criou com um sistema de controle de versão não-git, permanece no disco. Para o que deletar uma [sessão de fundo](/docs/pt/agent-view#what-deleting-a-session-removes) faz com uma worktree criada por hook, veja as regras de delete da agent view.3241* **Sem hook WorktreeRemove**: quando você sai de uma sessão `--worktree` e escolhe remoção, Claude Code volta para `git worktree remove --force` no caminho que seu hook WorktreeCreate retornou, então uma worktree que git reconhece é removida. Uma worktree que git não reconhece, por exemplo uma que seu hook criou com um sistema de controle de versão não-git, fica no disco. Para o que excluir uma [sessão de fundo](/docs/pt/agent-view#what-deleting-a-session-removes) faz com uma worktree criada por hook, veja as regras de exclusão da visualização de agente.
3237* **Hook sai com 0**: a worktree é contada como removida. Claude Code não lê nada mais do hook, portanto certifique-se de que seu hook deletou o diretório.3242* **Hook sai com 0**: a worktree é contada como removida. Claude Code não lê nada mais do hook, então certifique-se de que seu hook excluiu o diretório.
3238* **Hook sai com não-zero**: a remoção falha se o diretório em `worktree_path` ainda existir depois, e a worktree permanece no disco sem fallback git. Um hook que deletou o diretório antes de sair com não-zero é contado como removido. Para como a falha é relatada, veja [entrada WorktreeRemove](#worktreeremove-input).3243* **Hook sai com código não-zero**: a remoção falha se o diretório em `worktree_path` ainda existir depois, e a worktree fica no disco sem fallback git. Um hook que excluiu o diretório antes de sair com código não-zero é contado como removido. Para como a falha é relatada, veja [entrada WorktreeRemove](#worktreeremove-input).
3239 3244
3240Claude Code nunca deleta um branch pertencente a uma worktree criada por hook, porque ele só conhece o caminho que seu hook WorktreeCreate retornou. Se seu hook WorktreeCreate cria um branch, delete-o em seu hook WorktreeRemove.3245Claude Code nunca exclui um branch pertencente a uma worktree criada por hook, porque ele só conhece o caminho que seu hook WorktreeCreate retornou. Se seu hook WorktreeCreate cria um branch, exclua-o em seu hook WorktreeRemove.
3241 3246
3242Claude Code descarta [campos de saída JSON](#json-output) de um hook WorktreeRemove, como `systemMessage` e `continue`.3247Claude Code descarta [campos de saída JSON](#json-output) de um hook WorktreeRemove, como `systemMessage` e `continue`.
3243 3248
3244Para um delete de sessão de fundo, Claude Code verifica o caminho de worktree armazenado antes de executar o hook e recusa um caminho que é um symlink ou passa através de um abaixo da raiz do repositório. O hook é executado para uma worktree que ainda contém arquivos apenas quando você confirma o delete em [agent view](/docs/pt/agent-view#what-deleting-a-session-removes); para tal worktree, [`claude rm`](/docs/pt/agent-view#manage-sessions-from-the-shell) mantém a sessão e worktree em vez disso. Antes da v2.1.216, o hook era executado no caminho armazenado sem essas verificações.3249Para uma exclusão de sessão de fundo, Claude Code verifica o caminho de worktree armazenado antes de executar o hook e recusa um caminho que é um symlink ou passa através de um abaixo da raiz do repositório. O hook é executado para uma worktree que ainda contém arquivos apenas quando você confirma a exclusão em [visualização de agente](/docs/pt/agent-view#what-deleting-a-session-removes); para tal worktree, [`claude rm`](/docs/pt/agent-view#manage-sessions-from-the-shell) mantém a sessão e worktree em vez disso. Antes da v2.1.216, o hook era executado no caminho armazenado sem essas verificações.
3245 3250
3246Claude Code passa o caminho retornado por WorktreeCreate como `worktree_path` na entrada do hook. Este exemplo lê esse caminho e remove o diretório:3251Claude Code passa o caminho retornado por WorktreeCreate como `worktree_path` na entrada do hook. Este exemplo lê esse caminho e remove o diretório:
3247 3252
3278}3283}
3279```3284```
3280 3285
3281O código de saída de um hook WorktreeRemove decide o resultado. Quando um hook sai com não-zero e o diretório em `worktree_path` ainda existe depois, a remoção falha:3286O código de saída de um hook WorktreeRemove decide o resultado. Quando um hook sai com código não-zero e o diretório em `worktree_path` ainda existe depois, a remoção falha:
3282 3287
3283* A worktree permanece no disco, e o comando do hook e stderr vão para o [log de depuração](#debug-hooks).3288* A worktree fica no disco, e o comando do hook e stderr vão para o [log de depuração](#debug-hooks).
3284* Se você estava deletando uma sessão de fundo, a sessão também permanece. A mensagem de recusa em [agent view](/docs/pt/agent-view#what-deleting-a-session-removes) relata como o hook terminou, como `exited 1`, cita o início de seu stderr e diz se deletar a sessão novamente remove o diretório de qualquer forma.3289* Se você estava excluindo uma sessão de fundo, a sessão também fica. A mensagem de recusa em [visualização de agente](/docs/pt/agent-view#what-deleting-a-session-removes) relata como o hook terminou, como `exited 1`, cita o início de seu stderr e diz se excluir a sessão novamente remove o diretório de qualquer forma.
3285 3290
3286<h3 id="precompact">3291<h3 id="precompact">
3287 PreCompact3292 PreCompact
3288</h3>3293</h3>
3289 3294
3290Executado antes de Claude Code estar prestes a executar uma operação de compactação.3295Executa antes de Claude Code estar prestes a executar uma operação de compactação.
3291 3296
3292O valor do matcher indica se a compactação foi disparada manualmente ou automaticamente:3297O valor do matcher indica se a compactação foi disparada manualmente ou automaticamente:
3293 3298
3298 3303
3299Saia com código 2 para bloquear a compactação. Para um `/compact` manual, a mensagem stderr é mostrada ao usuário. Você também pode bloquear retornando JSON com `"decision": "block"`.3304Saia com código 2 para bloquear a compactação. Para um `/compact` manual, a mensagem stderr é mostrada ao usuário. Você também pode bloquear retornando JSON com `"decision": "block"`.
3300 3305
3301Bloquear compactação automática tem efeitos diferentes dependendo de quando é disparado. Se a compactação foi disparada proativamente antes do limite de contexto, Claude Code a pula e a conversa continua não compactada. Se a compactação foi disparada para recuperar de um erro de limite de contexto já retornado pela API, o erro subjacente aparece e a solicitação atual falha.3306Bloquear compactação automática tem efeitos diferentes dependendo de quando dispara. Se a compactação foi disparada proativamente antes do limite de contexto, Claude Code a pula e a conversa continua não compactada. Se a compactação foi disparada para recuperar de um erro de limite de contexto já retornado pela API, o erro subjacente aparece e a solicitação atual falha.
3302 3307
3303Claude Code descarta campos `systemMessage` e `continue` de um hook PreCompact.3308Claude Code descarta campos `systemMessage` e `continue` de um hook PreCompact.
3304 3309
3323 PostCompact3328 PostCompact
3324</h3>3329</h3>
3325 3330
3326Executado após Claude Code completar uma operação de compactação. Use este evento para reagir ao novo estado compactado, por exemplo para registrar o resumo gerado ou atualizar estado externo. Claude Code descarta campos `systemMessage` e `continue` de um hook PostCompact.3331Executa após Claude Code completar uma operação de compactação. Use este evento para reagir ao novo estado compactado, por exemplo para registrar o resumo gerado ou atualizar estado externo. Claude Code descarta campos `systemMessage` e `continue` de um hook PostCompact.
3327 3332
3328Os mesmos valores de matcher se aplicam como para `PreCompact`:3333Os mesmos valores de matcher se aplicam como para `PreCompact`:
3329 3334
3355 PreModelSwitch3360 PreModelSwitch
3356</h3>3361</h3>
3357 3362
3358Executado antes de Claude Code aplicar uma mudança de modelo que você ou um cliente solicitou. Use-o para bloquear uma mudança, exigir confirmação ou mostrar qual será o custo da mudança antes que aconteça.3363Executa antes de Claude Code aplicar uma mudança de modelo que você ou um cliente solicitou. Use-o para bloquear uma mudança, exigir confirmação ou mostrar qual será o custo da mudança antes de acontecer.
3359 3364
3360PreModelSwitch requer Claude Code v2.1.251 ou posterior. Claude Code o executa para essas solicitações:3365PreModelSwitch requer Claude Code v2.1.251 ou posterior. Claude Code o executa para essas solicitações:
3361 3366
3362* `/model <name>` e o picker `/model`3367* `/model <name>` e o seletor `/model`
3363* O picker de modelo `Option+P` ou `Alt+P`3368* O seletor de modelo `Option+P` ou `Alt+P`
3364* A configuração Model em `/config`3369* A configuração Model em `/config`
3365* Ativar [modo rápido](/docs/pt/fast-mode) quando isso muda o modelo da sessão3370* Ativar [modo rápido](/docs/pt/fast-mode) quando isso muda o modelo da sessão
3366* Uma solicitação `set_model`, ou uma mudança de modelo em uma solicitação `apply_flag_settings`, de um host [Agent SDK](/docs/pt/agent-sdk/typescript#query-object) ou [Remote Control](/docs/pt/remote-control)3371* Uma solicitação `set_model`, ou uma mudança de modelo em uma solicitação `apply_flag_settings`, de um host [Agent SDK](/docs/pt/agent-sdk/typescript#query-object) ou [Remote Control](/docs/pt/remote-control)
3367 3372
3368Claude Code não executa hooks PreModelSwitch para mudanças que ele faz por conta própria, como um [fallback de modelo automático](/docs/pt/model-config#automatic-model-fallback) ou restaurar o modelo quando você retoma uma sessão. Essas mudanças chegam a [PostModelSwitch](#postmodelswitch) apenas.3373Claude Code não executa hooks PreModelSwitch para mudanças que faz por conta própria, como um [fallback de modelo automático](/docs/pt/model-config#automatic-model-fallback) ou restaurar o modelo quando você retoma uma sessão. Essas mudanças chegam a [PostModelSwitch](#postmodelswitch) apenas.
3369 3374
3370Claude Code compara o matcher contra o nome canônico do modelo para o qual a sessão está mudando, ignorando qualquer sufixo `[1m]`. Um alias como `opus`, um ID de modelo datado e um ID específico do provedor como um ID de modelo Amazon Bedrock todos correspondem ao um nome canônico que resolvem, portanto `claude-opus-5` cobre cada ortografia de Opus 5.3375Claude Code compara o matcher contra o nome canônico do modelo para o qual a sessão está mudando, ignorando qualquer sufixo `[1m]`. Um alias como `opus`, um ID de modelo datado e um ID específico do provedor como um ID de modelo Amazon Bedrock todos correspondem ao um nome canônico que resolvem, então `claude-opus-5` cobre cada ortografia de Opus 5.
3371 3376
3372Quando Claude Code não pode determinar um nome canônico para o alvo, por exemplo um ID de modelo personalizado que apenas seu [gateway LLM](/docs/pt/llm-gateway) conhece, ele executa cada hook PreModelSwitch independentemente do matcher. Um hook que bloqueia deve portanto verificar `to_model` de sua entrada em vez de confiar apenas no matcher.3377Quando Claude Code não pode determinar um nome canônico para o alvo, por exemplo um ID de modelo personalizado que apenas seu [gateway LLM](/docs/pt/llm-gateway) conhece, ele executa cada hook PreModelSwitch independentemente do matcher. Um hook que bloqueia deve portanto verificar `to_model` de sua entrada em vez de confiar apenas no matcher.
3373 3378
3374Escreva o matcher como um nome exato, uma lista separada por `|` como `claude-opus-4-6|claude-opus-5`, ou uma expressão regular como `.*opus.*`. Este exemplo usa um matcher de nome exato e também verifica `to_model` da entrada do hook, portanto recusa uma mudança para Opus 4.6 ao sair com código 2 e deixa qualquer outro alvo passar:3379Escreva o matcher como um nome exato, uma lista separada por `|` como `claude-opus-4-6|claude-opus-5`, ou uma expressão regular como `.*opus.*`. Este exemplo usa um matcher de nome exato e também verifica `to_model` da entrada do hook, então recusa uma mudança para Opus 4.6 ao sair com código 2 e deixa qualquer outro alvo passar:
3375 3380
3376<Tabs>3381<Tabs>
3377 <Tab title="macOS/Linux">3382 <Tab title="macOS/Linux">
3443 Entrada PreModelSwitch3448 Entrada PreModelSwitch
3444</h4>3449</h4>
3445 3450
3446Além dos [campos de entrada comuns](#common-input-fields), hooks PreModelSwitch recebem os campos nesta tabela. Os últimos cinco descrevem qual é o custo de reenviar a conversa para o novo modelo, portanto um hook pode mostrar essa figura antes da mudança acontecer.3451Além dos [campos de entrada comuns](#common-input-fields), hooks PreModelSwitch recebem os campos nesta tabela. Os últimos cinco descrevem qual é o custo de reenviar a conversa para o novo modelo, então um hook pode mostrar essa figura antes da mudança acontecer.
3447 3452
3448| Campo | Tipo | Descrição |3453| Campo | Tipo | Descrição |
3449| :- | :- | :- |3454| :- | :- | :- |
3450| `from_model` | string | ID de modelo de que a mudança muda |3455| `from_model` | string | ID de modelo da mudança de |
3451| `to_model` | string | ID de modelo para o qual a mudança muda. O matcher compara contra o nome canônico deste modelo |3456| `to_model` | string | ID de modelo da mudança para. O matcher compara contra o nome canônico deste modelo |
3452| `requested_model` | string ou `null` | O modelo que a solicitação nomeou: um alias como `opus`, um ID de modelo completo, ou `null` quando a solicitação foi para o modelo padrão |3457| `requested_model` | string ou `null` | O modelo que a solicitação nomeou: um alias como `opus`, um ID de modelo completo, ou `null` quando a solicitação foi para o modelo padrão |
3453| `source` | string | De onde a solicitação veio: `"command"` para `/model <name>`, a configuração Model em `/config` ou ativar modo rápido; `"picker"` para um picker de modelo; `"sdk"` para uma solicitação `set_model`, ou uma mudança de modelo em uma solicitação `apply_flag_settings`, de um host Agent SDK ou Remote Control |3458| `source` | string | De onde a solicitação veio: `"command"` para `/model <name>`, a configuração Model em `/config` ou ativar modo rápido; `"picker"` para um seletor de modelo; `"sdk"` para uma solicitação `set_model`, ou uma mudança de modelo em uma solicitação `apply_flag_settings`, de um host Agent SDK ou Remote Control |
3454| `context_tokens` | number | Tokens que a próxima solicitação reenvia como seu prompt: os tokens de entrada, leitura de cache, criação de cache e saída da última resposta na conversa principal, combinados. `0` antes da primeira resposta |3459| `context_tokens` | number | Tokens que a próxima solicitação reenvia como seu prompt: os tokens de entrada, leitura de cache, criação de cache e saída da última resposta na conversa principal, combinados. `0` antes da primeira resposta |
3455| `prompt_cache_warm` | boolean | Se o cache de prompt do modelo atual provavelmente ainda está quente, significando que a mudança o perde |3460| `prompt_cache_warm` | boolean | Se o cache de prompt do modelo atual provavelmente ainda está quente, significando que a mudança o perde |
3456| `cache_ttl` | string | [Tempo de vida do cache de prompt](/docs/pt/prompt-caching#cache-lifetime) que Claude Code solicita para esta sessão: `"5m"` ou `"1h"` |3461| `cache_ttl` | string | [Tempo de vida do cache de prompt](/docs/pt/prompt-caching#cache-lifetime) que Claude Code solicita para esta sessão: `"5m"` ou `"1h"` |
3457| `estimated_cache_write_usd` | number | Custo estimado em dólares americanos de escrever `context_tokens` no cache de prompt em `to_model` na taxa `cache_ttl`, excluindo a próxima resposta. O servidor pode não precisar re-cachear todo o contexto, portanto trate-o como uma estimativa |3462| `estimated_cache_write_usd` | number | Custo estimado em dólares americanos de escrever `context_tokens` no cache de prompt em `to_model` na taxa `cache_ttl`, excluindo a próxima resposta. O servidor pode não precisar re-cachear todo o contexto, então trate-o como uma estimativa |
3458| `pricing` | string | Como Claude Code precificou `estimated_cache_write_usd`: `"configured"` em suas próprias taxas de organização quando as configurou, `"catalog"` no preço de lista, ou `"default"` quando `to_model` não tem preço conhecido e Claude Code assumiu uma taxa padrão |3463| `pricing` | string | Como Claude Code precificou `estimated_cache_write_usd`: `"configured"` em suas próprias taxas da organização quando as configurou, `"catalog"` ao preço de lista, ou `"default"` quando `to_model` não tem preço conhecido e Claude Code assumiu uma taxa padrão |
3459 3464
3460Este exemplo mostra a entrada para `/model opus` em uma sessão executando Sonnet 5:3465Este exemplo mostra a entrada para `/model opus` em uma sessão executando Sonnet 5:
3461 3466
3506 3511
3507Quando vários hooks PreModelSwitch retornam decisões diferentes, a precedência é `deny` > `ask` > `allow`.3512Quando vários hooks PreModelSwitch retornam decisões diferentes, a precedência é `deny` > `ask` > `allow`.
3508 3513
3509Claude Code mostra ao usuário qualquer `systemMessage` que seu hook retorna independentemente da decisão, portanto um hook de relatório de custo pode retornar `{"systemMessage": "..."}` e sair com 0.3514Claude Code mostra ao usuário qualquer `systemMessage` que seu hook retorna independentemente da decisão, então um hook de relatório de custo pode retornar `{"systemMessage": "..."}` e sair com 0.
3510 3515
3511Um hook PreModelSwitch que não responde antes de seu tempo limite bloqueia a mudança. Em [PreToolUse](#timeouts), por contraste, um hook de comando que atingiu tempo limite deixa a chamada de ferramenta continuar. O tempo limite padrão para este evento é 30 segundos. `PreModelSwitch` executa apenas hooks `command`, `http` e `mcp_tool`, portanto os padrões `prompt` e `agent` não se aplicam.3516Um hook PreModelSwitch que não responde antes de seu tempo limite bloqueia a mudança. Em [PreToolUse](#timeouts), por contraste, um hook de comando que atingiu tempo limite deixa a chamada de ferramenta continuar. O tempo limite padrão para este evento é 30 segundos. `PreModelSwitch` executa apenas hooks `command`, `http` e `mcp_tool`, então os padrões `prompt` e `agent` não se aplicam.
3512 3517
3513Um hook que sai com um código diferente de 0 ou 2 e não imprime nenhuma decisão JSON não bloqueia: Claude Code mostra seu stderr e aplica a mudança, conforme descrito em [Outros códigos de saída](#other-exit-codes).3518Um hook que sai com um código diferente de 0 ou 2 e não imprime nenhuma decisão JSON não bloqueia: Claude Code mostra seu stderr e aplica a mudança, conforme descrito em [Outros códigos de saída](#other-exit-codes).
3514 3519
3516 PostModelSwitch3521 PostModelSwitch
3517</h3>3522</h3>
3518 3523
3519Executado após o modelo da sessão mudar. Use-o para dar orientação específica do modelo a Claude sem editar cada CLAUDE.md, por exemplo uma instrução em toda a organização que se aplica em certos modelos.3524Executa após o modelo da sessão mudar. Use-o para dar orientação específica do modelo ao Claude sem editar cada CLAUDE.md, por exemplo uma instrução em toda a organização que se aplica em certos modelos.
3520 3525
3521PostModelSwitch requer Claude Code v2.1.251 ou posterior. Não pode bloquear, porque o modelo já mudou. Claude Code executa hooks PostModelSwitch após qualquer uma dessas mudanças:3526PostModelSwitch requer Claude Code v2.1.251 ou posterior. Não pode bloquear, porque o modelo já mudou. Claude Code executa hooks PostModelSwitch após qualquer uma dessas mudanças:
3522 3527
3549}3554}
3550```3555```
3551 3556
3552Para confirmar que o hook funciona, mude para um modelo Opus de uma sessão executando um modelo diferente, por exemplo execute `/model opus` de uma sessão Sonnet, depois pergunte a Claude qual orientação ela tem sobre o modelo atual.3557Para confirmar que o hook funciona, mude para um modelo Opus de uma sessão executando um modelo diferente, por exemplo execute `/model opus` de uma sessão Sonnet, depois pergunte ao Claude qual orientação ele tem sobre o modelo atual.
3553 3558
3554<h4 id="postmodelswitch-input">3559<h4 id="postmodelswitch-input">
3555 Entrada PostModelSwitch3560 Entrada PostModelSwitch
3563 Controle de decisão PostModelSwitch3568 Controle de decisão PostModelSwitch
3564</h4>3569</h4>
3565 3570
3566Claude Code pega seu [stdout de texto simples](#exit-code-0) do hook ao sair com 0, ou `additionalContext` de saída JSON, e o entrega a Claude com a próxima solicitação após a mudança. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar:3571Claude Code pega seu [stdout de texto simples](#exit-code-0) de hook ao sair com 0, ou `additionalContext` de saída JSON, e o entrega ao Claude com a próxima solicitação após a mudança. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar:
3567 3572
3568| Campo | Descrição |3573| Campo | Descrição |
3569| :- | :- |3574| :- | :- |
3570| `additionalContext` | String adicionada ao contexto de Claude com a próxima solicitação. Veja [Adicionar contexto para Claude](#add-context-for-claude) |3575| `additionalContext` | String adicionada ao contexto do Claude com a próxima solicitação. Veja [Adicionar contexto para Claude](#add-context-for-claude) |
3571 3576
3572Se o hook não terminar dentro de cinco segundos após você enviar a próxima solicitação, Claude Code envia essa solicitação sem a saída e a anexa à solicitação seguinte em vez disso. Se o modelo mudar várias vezes antes da próxima solicitação, Claude Code entrega apenas a saída para a mudança do modelo alvo final.3577Se o hook não terminar dentro de cinco segundos após você enviar a próxima solicitação, Claude Code envia essa solicitação sem a saída e a anexa à solicitação seguinte em vez disso. Se o modelo mudar várias vezes antes da próxima solicitação, Claude Code entrega apenas a saída para a mudança de alvo do último modelo.
3573 3578
3574<h3 id="sessionend">3579<h3 id="sessionend">
3575 SessionEnd3580 SessionEnd
3576</h3>3581</h3>
3577 3582
3578Executado quando uma sessão de Claude Code termina. Útil para tarefas de limpeza, registrar estatísticas de sessão ou salvar estado de sessão. Suporta matchers para filtrar por motivo de saída.3583Executa quando uma sessão Claude Code termina. Útil para tarefas de limpeza, registrar estatísticas de sessão ou salvar estado de sessão. Suporta matchers para filtrar por motivo de saída.
3579 3584
3580O campo `reason` na entrada do hook indica por que a sessão terminou:3585O campo `reason` na entrada do hook indica por que a sessão terminou:
3581 3586
3582| Motivo | Descrição |3587| Motivo | Descrição |
3583| :- | :- |3588| :- | :- |
3584| `clear` | Sessão limpa com comando `/clear` |3589| `clear` | Sessão limpa com comando `/clear` |
3585| `resume` | Sessão mudou via `/resume` interativo |3590| `resume` | Sessão mudada via `/resume` interativo |
3586| `logout` | Usuário fez logout |3591| `logout` | Usuário fez logout |
3587| `prompt_input_exit` | Usuário saiu enquanto entrada de prompt estava visível |3592| `prompt_input_exit` | Usuário saiu enquanto entrada de prompt estava visível |
3588| `other` | Outros motivos de saída |3593| `other` | Outros motivos de saída |
3608 3613
3609Hooks SessionEnd têm um tempo limite padrão de 1,5 segundos. Aplica-se quando você sai, executa `/clear` ou muda de sessões com `/resume` interativo. Você pode dar a um hook mais tempo de duas maneiras:3614Hooks SessionEnd têm um tempo limite padrão de 1,5 segundos. Aplica-se quando você sai, executa `/clear` ou muda de sessões com `/resume` interativo. Você pode dar a um hook mais tempo de duas maneiras:
3610 3615
3611* **`timeout` por hook**: defina `timeout` na configuração desse hook. O orçamento geral sobe automaticamente para corresponder ao `timeout` por hook mais alto em seus arquivos de configurações, até 60 segundos. Se você aumentar o orçamento dessa forma, um hook sem seu próprio `timeout` ainda mantém o padrão. Tempos limite definidos em hooks fornecidos por plugin não aumentam o orçamento.3616* **`timeout` por hook**: defina `timeout` na configuração daquele hook. O orçamento geral sobe automaticamente para corresponder ao `timeout` por hook mais alto em seus arquivos de configurações, até 60 segundos. Se você aumentar o orçamento dessa forma, um hook sem seu próprio `timeout` ainda mantém o padrão. Tempos limite definidos em hooks fornecidos por plugin não aumentam o orçamento.
3612* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**: defina esta variável de ambiente em milissegundos para sobrescrever o orçamento explicitamente. O valor que você define também se torna o tempo limite para cada hook sem seu próprio `timeout`.3617* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**: defina esta variável de ambiente em milissegundos para sobrescrever o orçamento explicitamente. O valor que você define também se torna o tempo limite para cada hook sem seu próprio `timeout`.
3613 3618
3614Este exemplo define o orçamento para 5 segundos:3619Este exemplo define o orçamento para 5 segundos:
3623 Elicitation3628 Elicitation
3624</h3>3629</h3>
3625 3630
3626Executado quando um servidor MCP solicita entrada do usuário no meio da tarefa. Por padrão, Claude Code mostra um diálogo interativo para o usuário responder. Hooks podem interceptar esta solicitação e responder programaticamente, pulando o diálogo inteiramente.3631Executa quando um servidor MCP solicita entrada do usuário no meio da tarefa. Por padrão, Claude Code mostra um diálogo interativo para o usuário responder. Hooks podem interceptar esta solicitação e responder programaticamente, pulando o diálogo inteiramente.
3627 3632
3628O campo matcher corresponde ao nome do servidor MCP.3633O campo matcher corresponde ao nome do servidor MCP.
3629 3634
3633 3638
3634Além dos [campos de entrada comuns](#common-input-fields), hooks Elicitation recebem `mcp_server_name`, `message` e campos opcionais `mode`, `url`, `elicitation_id` e `requested_schema`.3639Além dos [campos de entrada comuns](#common-input-fields), hooks Elicitation recebem `mcp_server_name`, `message` e campos opcionais `mode`, `url`, `elicitation_id` e `requested_schema`.
3635 3640
3636Para elicitação de modo formulário, o caso mais comum:3641Para elicitação de modo de formulário, o caso mais comum:
3637 3642
3638```json theme={null}3643```json theme={null}
3639{3644{
3693 3698
3694Código de saída 2 nega a elicitação. Claude Code não mostra sua mensagem stderr em lugar algum.3699Código de saída 2 nega a elicitação. Claude Code não mostra sua mensagem stderr em lugar algum.
3695 3700
3696Claude Code atua em `hookSpecificOutput` da saída JSON de um hook Elicitation e descarta `systemMessage` e `continue`.3701Claude Code age em `hookSpecificOutput` de uma saída JSON de hook Elicitation e descarta `systemMessage` e `continue`.
3697 3702
3698<h3 id="elicitationresult">3703<h3 id="elicitationresult">
3699 ElicitationResult3704 ElicitationResult
3700</h3>3705</h3>
3701 3706
3702Executado após um usuário responder a uma elicitação MCP. Hooks podem observar, modificar ou bloquear a resposta antes de ser enviada de volta para o servidor MCP.3707Executa após um usuário responder a uma elicitação MCP. Hooks podem observar, modificar ou bloquear a resposta antes de ser enviada de volta para o servidor MCP.
3703 3708
3704O campo matcher corresponde ao nome do servidor MCP.3709O campo matcher corresponde ao nome do servidor MCP.
3705 3710
3746 3751
3747Código de saída 2 bloqueia a resposta, mudando a ação efetiva para `decline`. Claude Code não mostra sua mensagem stderr em lugar algum.3752Código de saída 2 bloqueia a resposta, mudando a ação efetiva para `decline`. Claude Code não mostra sua mensagem stderr em lugar algum.
3748 3753
3749Claude Code atua em `hookSpecificOutput` da saída JSON de um hook ElicitationResult e descarta `systemMessage` e `continue`.3754Claude Code age em `hookSpecificOutput` de uma saída JSON de hook ElicitationResult e descarta `systemMessage` e `continue`.
3750 3755
3751<h2 id="prompt-based-hooks">3756<h2 id="prompt-based-hooks">
3752 Hooks baseados em prompt3757 Hooks baseados em prompt
