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
1175 SessionStart1175 SessionStart
1176</h3>1176</h3>
1177 1177
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.1178Executa 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 1179
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.1180SessionStart é 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 1181
1182O valor do matcher corresponde a como a sessão foi iniciada:1182O valor do matcher corresponde a como a sessão foi iniciada:
1183 1183
1187| `resume` | `--resume`, `--continue`, ou `/resume` |1187| `resume` | `--resume`, `--continue`, ou `/resume` |
1188| `clear` | `/clear` |1188| `clear` | `/clear` |
1189| `compact` | Compactação automática ou manual |1189| `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` |1190| `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 1191
1192Antes da v2.1.214, sessões bifurcadas relatavam fonte `"resume"`.1192Antes da v2.1.214, sessões bifurcadas relatavam fonte `"resume"`.
1193 1193
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.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 do Claude ainda espera os hooks terminarem, então seu contexto chega ao Claude.
1195 1195
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.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.
1197 1197
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.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 ao Claude até que terminem.
1199 1199
1200Durante qualquer espera, pressione `Esc` para levar o prompt de volta para a entrada sem enviá-lo. Os hooks continuam em execução.1200Durante qualquer espera, pressione `Esc` para levar o prompt de volta para a entrada sem enviá-lo. Os hooks continuam em execução.
1201 1201
1208| Campo | Descrição |1208| Campo | Descrição |
1209| :- | :- |1209| :- | :- |
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 |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 |
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 |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, 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>` |1212| `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 |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 |
1214 1214
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.1215Quando `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 1216
1217| Campo | Descrição |1217| Campo | Descrição |
1218| :- | :- |1218| :- | :- |
1242 Controle de decisão SessionStart1242 Controle de decisão SessionStart
1243</h4>1243</h4>
1244 1244
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:1245Claude 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 1246
1247| Campo | Descrição |1247| Campo | Descrição |
1248| :- | :- |1248| :- | :- |
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 |1249| `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 |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 |
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"` |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"` |
1252| `watchPaths` | Array de caminhos absolutos para observar eventos [FileChanged](#filechanged) durante esta sessão |1252| `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 |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, para que skills que o hook instalou estejam disponíveis na mesma sessão, começando com o primeiro prompt |
1254 1254
1255```json theme={null}1255```json theme={null}
1256{1256{
1262}1262}
1263```1263```
1264 1264
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`.1265Como 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 1266
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:1267Use `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 1268
1269```bash theme={null}1269```bash theme={null}
1270#!/bin/bash1270#!/bin/bash
1275echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1275echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'
1276```1276```
1277 1277
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.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, então a solicitação `reloadSkills` ainda se aplica.
1279 1279
1280<h4 id="persist-environment-variables">1280<h4 id="persist-environment-variables">
1281 Persistir variáveis de ambiente1281 Persistir variáveis de ambiente
1324 Setup1324 Setup
1325</h3>1325</h3>
1326 1326
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.1327Dispara 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 1328
1329O valor do matcher corresponde à flag CLI que disparou o hook:1329O valor do matcher corresponde à flag CLI que disparou o hook:
1330 1330
1339 1339
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.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.
1341 1341
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.1342Como 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 1343
1344<h4 id="setup-input">1344<h4 id="setup-input">
1345 Entrada Setup1345 Entrada Setup
1361 Controle de decisão Setup1361 Controle de decisão Setup
1362</h4>1362</h4>
1363 1363
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`.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 [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 1365
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).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).
1367 1367
1369 InstructionsLoaded1369 InstructionsLoaded
1370</h3>1370</h3>
1371 1371
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.1372Dispara 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 1373
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`.1374Este 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 1375
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.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.
1377 1377
1385| :- | :- |1385| :- | :- |
1386| `file_path` | Caminho absoluto para o arquivo de instrução que foi carregado |1386| `file_path` | Caminho absoluto para o arquivo de instrução que foi carregado |
1387| `memory_type` | Escopo do arquivo: `"User"`, `"Project"`, `"Local"` ou `"Managed"` |1387| `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 |1388| `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` |1389| `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 |1390| `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` |1391| `parent_file_path` | Caminho para o arquivo de instrução pai que incluiu este, para carregamentos `include` |
1412 UserPromptSubmit1412 UserPromptSubmit
1413</h3>1413</h3>
1414 1414
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.1415Executa 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 1416
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.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.
1418 1418
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.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 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 1420
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.1421Um 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 1422
1423<h4 id="userpromptsubmit-input">1423<h4 id="userpromptsubmit-input">
1424 Entrada UserPromptSubmit1424 Entrada UserPromptSubmit
1425</h4>1425</h4>
1426 1426
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.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="…">`, então leve em conta essas linhas se seu hook analisa o prompt.
1428 1428
1429```json theme={null}1429```json theme={null}
1430{1430{
1445 1445
1446Existem duas maneiras de adicionar contexto à conversa no código de saída 0:1446Existem duas maneiras de adicionar contexto à conversa no código de saída 0:
1447 1447
1448* **Stdout de texto simples**: Claude Code adiciona stdout que [trata como texto simples](#exit-code-0) ao contexto de Claude1448* **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 contexto1449* **JSON com `additionalContext`**: use o formato JSON abaixo para mais controle. O campo `additionalContext` é adicionado como contexto
1450 1450
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).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).
1456| :- | :- |1456| :- | :- |
1457| `decision` | `"block"` impede que o prompt seja processado e o apaga do contexto. Omita para permitir que o prompt prossiga |1457| `decision` | `"block"` impede que o prompt seja processado e o apaga do contexto. Omita para permitir que o prompt prossiga |
1458| `reason` | Mostrado ao usuário quando `decision` é `"block"`. Não adicionado ao contexto |1458| `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) |1459| `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 |1460| `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 |1461| `suppressOriginalPrompt` | Se `true` quando `decision` é `"block"`, omite o texto do prompt original da mensagem de bloqueio mostrada ao usuário |
1462 1462
1478 UserPromptExpansion1478 UserPromptExpansion
1479</h3>1479</h3>
1480 1480
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`.1481Executa 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 1482
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.1483Este 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 1484
1485Corresponde a `command_name`. Deixe o matcher vazio para disparar em cada comando do tipo prompt.1485Corresponde a `command_name`. Deixe o matcher vazio para disparar em cada comando do tipo prompt.
1486 1486
1515| :- | :- |1515| :- | :- |
1516| `decision` | `"block"` impede que o comando se expanda. Omita para permitir que prossiga |1516| `decision` | `"block"` impede que o comando se expanda. Omita para permitir que prossiga |
1517| `reason` | Mostrado ao usuário quando `decision` é `"block"` |1517| `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) |1518| `additionalContext` | String adicionada ao contexto do Claude junto com o prompt expandido. Veja [Adicionar contexto para Claude](#add-context-for-claude) |
1519 1519
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.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.
1521 1521
1534 MessageDisplay1534 MessageDisplay
1535</h3>1535</h3>
1536 1536
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.1537Executa 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 1538
1539Use MessageDisplay para:1539Use MessageDisplay para:
1540 1540
1541* remover markdown para uma exibição mínima1541* remover markdown para uma exibição mínima
1542* transformar o texto que um aplicativo Agent SDK mostra aos seus usuários1542* 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 Claude1543* redactar chaves de API ou nomes de host internos das respostas do Claude
1544 1544
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.1545Claude 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 1546
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.1547MessageDisplay é 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 1548
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.1549MessageDisplay 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 1550
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.1551Em 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 1552
1553<h4 id="messagedisplay-input">1553<h4 id="messagedisplay-input">
1554 Entrada MessageDisplay1554 Entrada MessageDisplay
1555</h4>1555</h4>
1556 1556
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.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, 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 1558
1559| Campo | Descrição |1559| Campo | Descrição |
1560| :- | :- |1560| :- | :- |
1561| `turn_id` | UUID do turno atual |1561| `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 |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, 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 |1563| `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 |1564| `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 |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, 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 1566
1567```json theme={null}1567```json theme={null}
1568{1568{
1588| :- | :- |1588| :- | :- |
1589| `displayContent` | Texto exibido no lugar do delta. Omita para exibir o original |1589| `displayContent` | Texto exibido no lugar do delta. Omita para exibir o original |
1590 1590
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`.1591Hooks 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 1592
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`.1593Este 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 1594
1595<Tabs>1595<Tabs>
1596 <Tab title="macOS/Linux">1596 <Tab title="macOS/Linux">
1672 PreToolUse1672 PreToolUse
1673</h3>1673</h3>
1674 1674
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).1675Executa 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 1676
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.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, então não podem bloquear a escrita.
1678 1678
1679<Warning>1679<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.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, 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 1681
1682 PreToolUse também não é disparado para [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior).1682 PreToolUse também não dispara para [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior).
1683</Warning>1683</Warning>
1684 1684
1685Use [controle de decisão PreToolUse](#pretooluse-decision-control) para permitir, negar, perguntar ou adiar a chamada de ferramenta.1685Use [controle de decisão PreToolUse](#pretooluse-decision-control) para permitir, negar, perguntar ou adiar a chamada de ferramenta.
1686 1686
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.1687Um 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 1688
1689<h4 id="pretooluse-input">1689<h4 id="pretooluse-input">
1690 Entrada PreToolUse1690 Entrada PreToolUse
1692 1692
1693Além dos [campos de entrada comuns](#common-input-fields), hooks PreToolUse recebem `tool_name`, `tool_input` e `tool_use_id`.1693Além dos [campos de entrada comuns](#common-input-fields), hooks PreToolUse recebem `tool_name`, `tool_input` e `tool_use_id`.
1694 1694
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.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 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 1696
1697Para as ferramentas de arquivo `Write`, `Edit` e `Read`, `tool_input.file_path` é sempre absoluto:1697Para as ferramentas de arquivo `Write`, `Edit` e `Read`, `tool_input.file_path` é sempre absoluto:
1698 1698
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 caminho1699* 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`1700* 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 bloquear1701* 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 é absoluto1702* 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 |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 |
1733| `run_in_background` | boolean | `false` | Se o comando deve ser executado em segundo plano |1733| `run_in_background` | boolean | `false` | Se o comando deve ser executado em segundo plano |
1734 1734
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.1735Quando 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 1736
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.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.
1738 1738
1739<Note>1739<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.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.
1741</Note>1741</Note>
1742 1742
1743`changedFiles` e `files` listam o que o comando mudou; os campos restantes dizem como completo e confiável essa lista é.1743`changedFiles` e `files` listam o que o comando mudou; os campos restantes dizem como completo e confiável é essa lista.
1744 1744
1745| Campo | Tipo | Exemplo | Descrição |1745| Campo | Tipo | Exemplo | Descrição |
1746| :- | :- | :- | :- |1746| :- | :- | :- | :- |
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 |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 |
1749| `moreFiles` | number | `2` | Contagem de arquivos alterados sem diff em `files` |1749| `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 |1750| `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 |1751| `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 |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, então algumas mudanças listadas podem ser daquele comando |
1753 1753
1754<a id="powershell" />1754<a id="powershell" />
1755 1755
1770 1770
1771Corresponda a `Bash|PowerShell` em hooks que inspecionam comandos de shell, para que cubram ambas as ferramentas:1771Corresponda a `Bash|PowerShell` em hooks que inspecionam comandos de shell, para que cubram ambas as ferramentas:
1772 1772
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.1773* 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.1774* 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á.1775* Um hook que corresponde apenas a `Bash` nunca dispara lá.
1776 1776
1777<h5 id="write">1777<h5 id="write">
1778 Write1778 Write
1872| `subagent_type` | string | `"Explore"` | Tipo de agente especializado a usar |1872| `subagent_type` | string | `"Explore"` | Tipo de agente especializado a usar |
1873| `model` | string | `"sonnet"` | Alias de modelo opcional para sobrescrever o padrão |1873| `model` | string | `"sonnet"` | Alias de modelo opcional para sobrescrever o padrão |
1874 1874
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: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:
1876 1876
1877| Campo | Tipo | Exemplo | Descrição |1877| Campo | Tipo | Exemplo | Descrição |
1878| :- | :- | :- | :- |1878| :- | :- | :- | :- |
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"` |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, então um `run_in_background` omitido também produz `"async_launched"` |
1880| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificador para a execução do subagente |1880| `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 |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 handback em seu lugar |
1882| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modelo em que o subagente começou, que pode diferir do modelo solicitado |1882| `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 |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 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 |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 |
1885| `totalDurationMs` | number | `48211` | Duração de tempo real da execução do subagente |1885| `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 |1886| `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` |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` |
1888 1888
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`.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 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 1890
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`.1891Para 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 1892
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.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, 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 1894
1895<a id="askuserquestion" />1895<a id="askuserquestion" />
1896 1896
1903| Campo | Tipo | Exemplo | Descrição |1903| Campo | Tipo | Exemplo | Descrição |
1904| :- | :- | :- | :- |1904| :- | :- | :- | :- |
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 |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 |
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 |1906| `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 1907
1908<h5 id="exitplanmode">1908<h5 id="exitplanmode">
1909 ExitPlanMode1909 ExitPlanMode
1910</h5>1910</h5>
1911 1911
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.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, 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 1913
1914| Campo | Tipo | Exemplo | Descrição |1914| Campo | Tipo | Exemplo | Descrição |
1915| :- | :- | :- | :- |1915| :- | :- | :- | :- |
1928| Campo | Descrição |1928| Campo | Descrição |
1929| :- | :- |1929| :- | :- |
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 |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 |
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) |1931| `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 |1932| `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) |1933| `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 1934
1935Quando vários hooks PreToolUse retornam decisões diferentes, a precedência é `deny` > `defer` > `ask` > `allow`.1935Quando vários hooks PreToolUse retornam decisões diferentes, a precedência é `deny` > `defer` > `ask` > `allow`.
1936 1936
1956 1956
1957<span id="allow-with-updatedinput" />1957<span id="allow-with-updatedinput" />
1958 1958
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.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`, ecoar de volta o array `questions` original e adicionar um objeto [`answers`](#askuserquestion) mapeando o texto de cada pergunta para a resposta escolhida.
1960 1960
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.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.
1962 1962
1970 1970
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.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.
1972 1972
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: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`, então comece a execução com um. A viagem de ida e volta funciona assim:
1974 1974
19751. Claude chama `AskUserQuestion`. O hook `PreToolUse` é disparado.19751. 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.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.
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.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.
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.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.
1994}1994}
1995```1995```
1996 1996
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.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 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 1998
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.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.
2000 2000
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.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 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 2002
2003<Note>2003<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.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.
2005 2005
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).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, 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>2007</Note>
2008 2008
2009<h3 id="permissionrequest">2009<h3 id="permissionrequest">
2010 PermissionRequest2010 PermissionRequest
2011</h3>2011</h3>
2012 2012
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.2013Executa 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.2014Use [controle de decisão PermissionRequest](#permissionrequest-decision-control) para permitir ou negar em nome do usuário.
2015 2015
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.2016Use 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 2017
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`.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`.
2019 2019
2023 Entrada PermissionRequest2023 Entrada PermissionRequest
2024</h4>2024</h4>
2025 2025
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.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 mudar o modo de permissão.
2027 2027
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.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 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 2029
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).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 dispara para [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior).
2031 2031
2032```json theme={null}2032```json theme={null}
2033{2033{
2060 2060
2061| Campo | Descrição |2061| Campo | Descrição |
2062| :- | :- |2062| :- | :- |
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 |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, 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 |2064| `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 |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 mudar o modo de permissão da sessão |
2066| `message` | Para `"deny"` apenas: diz por que a permissão foi negada |2066| `message` | Para `"deny"` apenas: diz ao Claude por que a permissão foi negada |
2067| `interrupt` | Para `"deny"` apenas: se `true`, para Claude |2067| `interrupt` | Para `"deny"` apenas: se `true`, para Claude |
2068 2068
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.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.
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"` |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"` |
2094| `replaceRules` | `rules`, `behavior`, `destination` | Substitui todas as regras do `behavior` dado no `destination` pelas `rules` fornecidas |2094| `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 |2095| `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 |2096| `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 |2097| `addDirectories` | `directories`, `destination` | Adiciona diretórios de trabalho. `directories` é um array de strings de caminho |
2098| `removeDirectories` | `directories`, `destination` | Remove diretórios de trabalho |2098| `removeDirectories` | `directories`, `destination` | Remove diretórios de trabalho |
2099 2099
2103 `bypassPermissions` nunca é persistido como `defaultMode` independentemente de `destination`.2103 `bypassPermissions` nunca é persistido como `defaultMode` independentemente de `destination`.
2104</Note>2104</Note>
2105 2105
2106O campo `destination` em cada entrada determina se a mudança permanece na memória ou persiste em um arquivo de configurações.2106O campo `destination` em cada entrada determina se a mudança fica na memória ou persiste em um arquivo de configurações.
2107 2107
2108| `destination` | Escreve para |2108| `destination` | Escreve para |
2109| :- | :- |2109| :- | :- |
2118 PostToolUse2118 PostToolUse
2119</h3>2119</h3>
2120 2120
2121Executado imediatamente após uma ferramenta ser concluída com sucesso.2121Executa imediatamente após uma ferramenta ser concluída com sucesso.
2122 2122
2123Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.2123Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.
2124 2124
2131 Entrada PostToolUse2131 Entrada PostToolUse
2132</h4>2132</h4>
2133 2133
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).2134Hooks `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 2135
2136```json theme={null}2136```json theme={null}
2137{2137{
2162 Controle de decisão PostToolUse2162 Controle de decisão PostToolUse
2163</h4>2163</h4>
2164 2164
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:2165Hooks `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 2166
2167| Campo | Descrição |2167| Campo | Descrição |
2168| :- | :- |2168| :- | :- |
2169| `decision` | `"block"` adiciona o `reason` ao lado do resultado da ferramenta. Claude ainda vê a saída original; para substituí-la, use `updatedToolOutput` |2169| `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"` |2170| `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) |2171| `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 |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 |
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 |2173| `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 |2174| `updatedMCPToolOutput` | Substitui a saída para [ferramentas MCP](#match-mcp-tools) apenas. Prefira `updatedToolOutput`, que funciona para todas as ferramentas |
2175 2175
2176O exemplo abaixo substitui a saída de uma chamada `Bash`. O valor de substituição corresponde à forma de saída da ferramenta `Bash`:2176O exemplo abaixo substitui a saída de uma chamada `Bash`. O valor de substituição corresponde à forma de saída da ferramenta `Bash`:
2191```2191```
2192 2192
2193<Warning>2193<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.2194 `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 2195
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.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 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>2197</Warning>
2198 2198
2199<h4 id="annotate-a-result-for-the-auto-mode-classifier">2199<h4 id="annotate-a-result-for-the-auto-mode-classifier">
2200 Anotar um resultado para o classificador de modo automático2200 Anotar um resultado para o classificador de modo automático
2201</h4>2201</h4>
2202 2202
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.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), 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 2204
2205O exemplo abaixo diz ao classificador de onde a saída de uma consulta veio:2205O exemplo abaixo diz ao classificador de onde a saída de uma consulta veio:
2206 2206
2216Quanto peso o classificador dá à nota depende de onde você configurou o hook:2216Quanto peso o classificador dá à nota depende de onde você configurou o hook:
2217 2217
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 conversa2218* **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 verificada2219* **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 2220
2221Claude Code aplica esses limites ao entregar a nota:2221Claude Code aplica esses limites ao entregar a nota:
2222 2222
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 chamada2223* **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 ferramenta2224* **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 chamadas2225* **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ída2226* **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 2227
2228<Warning>2228<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.2229 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>2230</Warning>
2231 2231
2232<h3 id="posttoolusefailure">2232<h3 id="posttoolusefailure">
2233 PostToolUseFailure2233 PostToolUseFailure
2234</h3>2234</h3>
2235 2235
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.2236Executa 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 2237
2238Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.2238Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.
2239 2239
2240<Note>2240<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).2241 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>2242</Note>
2243 2243
2244<h4 id="posttoolusefailure-input">2244<h4 id="posttoolusefailure-input">
2269| Campo | Descrição |2269| Campo | Descrição |
2270| :- | :- |2270| :- | :- |
2271| `error` | String descrevendo o que deu errado. O formato depende da ferramenta que falhou |2271| `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 |2272| `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 |2273| `duration_ms` | Opcional. Tempo de execução da ferramenta em milissegundos. Exclui tempo gasto em prompts de permissão e hooks PreToolUse |
2274 2274
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.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.
2276 2276
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 intercalados2277* 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 shell2278* 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`2279* 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 2280
2281<h4 id="posttoolusefailure-decision-control">2281<h4 id="posttoolusefailure-decision-control">
2282 Controle de decisão PostToolUseFailure2282 Controle de decisão PostToolUseFailure
2283</h4>2283</h4>
2284 2284
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:2285Hooks `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 2286
2287| Campo | Descrição |2287| Campo | Descrição |
2288| :- | :- |2288| :- | :- |
2289| `additionalContext` | String adicionada ao contexto de Claude ao lado do erro. Veja [Adicionar contexto para Claude](#add-context-for-claude) |2289| `additionalContext` | String adicionada ao contexto do Claude junto com o erro. Veja [Adicionar contexto para Claude](#add-context-for-claude) |
2290 2290
2291```json theme={null}2291```json theme={null}
2292{2292{
2301 PostToolBatch2301 PostToolBatch
2302</h3>2302</h3>
2303 2303
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.2304Executa 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 2305
2306<h4 id="posttoolbatch-input">2306<h4 id="posttoolbatch-input">
2307 Entrada PostToolBatch2307 Entrada PostToolBatch
2333}2333}
2334```2334```
2335 2335
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.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, então analise apenas os campos que você precisa.
2337 2337
2338<Note>2338<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ê.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ê.
2358}2358}
2359```2359```
2360 2360
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.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 fica na conversa, então Claude a vê quando a conversa continua.
2362 2362
2363<h3 id="permissiondenied">2363<h3 id="permissiondenied">
2364 PermissionDenied2364 PermissionDenied
2365</h3>2365</h3>
2366 2366
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.2367Executa 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 2368
2369Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.2369Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.
2370 2370
2418 Notification2418 Notification
2419</h3>2419</h3>
2420 2420
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.2421Executa 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 2422
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.2423Você 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 2424
2425| Matcher | Quando é disparado |2425| Matcher | Quando é disparado |
2426| :- | :- |2426| :- | :- |
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 |2427| `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 |2428| `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 |2429| `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 |2430| `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 |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 |
2432| `elicitation_complete` | Um servidor MCP relata que uma [elicitação de modo URL](#elicitation-input) está completa |2432| `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 |2433| `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 |2434| `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 |2435| `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) |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 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 |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 |
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** |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 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 2439
2440Os tipos `agent_needs_input` e `agent_completed` requerem Claude Code v2.1.198 ou posterior.2440Os tipos `agent_needs_input` e `agent_completed` requerem Claude Code v2.1.198 ou posterior.
2441 2441
2443 2443
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.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.
2445 2445
2446`agent_needs_input` para a pergunta de configuração de terminal de um colega requer Claude Code v2.1.248 ou posterior.2446`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 2447
2448<Note>2448<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:2449 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 2450
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.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.
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.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_*` 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.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.
2454 2454
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.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.
2461* Se você ou um hook [PermissionRequest](#permissionrequest) responder mais cedo, Claude Code não executa `permission_prompt`.2461* 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.2462* Defina [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/pt/env-vars) como `1` para desativar `permission_prompt` nessas sessões.
2463 2463
2464Antes da v2.1.233, `permission_prompt` não era disparado nessas sessões.2464Antes da v2.1.233, `permission_prompt` não disparava nessas sessões.
2465 2465
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: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á ocioso:
2467 2467
2468```json theme={null}2468```json theme={null}
2469{2469{
2496 Entrada Notification2496 Entrada Notification
2497</h4>2497</h4>
2498 2498
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.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 disparou.
2500 2500
2501```json theme={null}2501```json theme={null}
2502{2502{
2510}2510}
2511```2511```
2512 2512
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.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 é 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 2514
2515<h3 id="subagentstart">2515<h3 id="subagentstart">
2516 SubagentStart2516 SubagentStart
2517</h3>2517</h3>
2518 2518
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.2519Executa 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 2520
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$`.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, então ancorize o matcher com `^` e `$` para uma correspondência exata: `^my-plugin:reviewer$`.
2522 2522
2523<h4 id="subagentstart-input">2523<h4 id="subagentstart-input">
2524 Entrada SubagentStart2524 Entrada SubagentStart
2558 SubagentStop2558 SubagentStop
2559</h3>2559</h3>
2560 2560
2561Executado quando um subagente de Claude Code terminou de responder. Corresponde ao tipo de agente, mesmos valores que SubagentStart.2561Executa quando um subagente Claude Code terminou de responder. Corresponde ao tipo de agente, mesmos valores que SubagentStart.
2562 2562
2563<h4 id="subagentstop-input">2563<h4 id="subagentstop-input">
2564 Entrada SubagentStop2564 Entrada SubagentStop
2565</h4>2565</h4>
2566 2566
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.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, então hooks podem acessá-lo sem analisar o arquivo de transcrição.
2568 2568
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.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 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 2570
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.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.
2572 2572
2597 TaskCreated2597 TaskCreated
2598</h3>2598</h3>
2599 2599
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.2600Executa 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 2601
2602Hooks TaskCreated não suportam matchers e são disparados em cada ocorrência.2602Hooks TaskCreated não suportam matchers e disparam em cada ocorrência.
2603 2603
2604<h4 id="taskcreated-input">2604<h4 id="taskcreated-input">
2605 Entrada TaskCreated2605 Entrada TaskCreated
2626| `task_id` | Identificador da tarefa sendo criada |2626| `task_id` | Identificador da tarefa sendo criada |
2627| `task_subject` | Título da tarefa |2627| `task_subject` | Título da tarefa |
2628| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |2628| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |
2629| `teammate_name` | Nome do colega criando a tarefa. Pode estar ausente |2629| `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 |2630| `team_name` | Descontinuado. Nome de equipe derivado de sessão; será removido em uma versão futura |
2631 2631
2632<h4 id="taskcreated-decision-control">2632<h4 id="taskcreated-decision-control">
2633 Controle de decisão TaskCreated2633 Controle de decisão TaskCreated
2634</h4>2634</h4>
2635 2635
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.2636Um 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 2637
2638* **Código de saída 2**: Claude Code retorna o texto stderr como a mensagem.2638* **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.2639* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code retorna `reason` como a mensagem.
2657 TaskCompleted2657 TaskCompleted
2658</h3>2658</h3>
2659 2659
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.2660Executa 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 2661
2662Hooks TaskCompleted não suportam matchers e são disparados em cada ocorrência.2662Hooks TaskCompleted não suportam matchers e disparam em cada ocorrência.
2663 2663
2664<h4 id="taskcompleted-input">2664<h4 id="taskcompleted-input">
2665 Entrada TaskCompleted2665 Entrada TaskCompleted
2687| `task_id` | Identificador da tarefa sendo concluída |2687| `task_id` | Identificador da tarefa sendo concluída |
2688| `task_subject` | Título da tarefa |2688| `task_subject` | Título da tarefa |
2689| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |2689| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |
2690| `teammate_name` | Nome do colega concluindo a tarefa. Pode estar ausente |2690| `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 |2691| `team_name` | Descontinuado. Nome de equipe derivado de sessão; será removido em uma versão futura |
2692 2692
2693<h4 id="taskcompleted-decision-control">2693<h4 id="taskcompleted-decision-control">
2697Hooks TaskCompleted suportam duas maneiras de controlar a conclusão da tarefa:2697Hooks TaskCompleted suportam duas maneiras de controlar a conclusão da tarefa:
2698 2698
2699* **Código de saída 2**: a tarefa não é marcada como concluída e a mensagem stderr é retornada ao modelo como feedback.2699* **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.2700* **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 2701
2702Este exemplo executa testes e bloqueia a conclusão da tarefa se falharem:2702Este exemplo executa testes e bloqueia a conclusão da tarefa se falharem:
2703 2703
2719 Stop2719 Stop
2720</h3>2720</h3>
2721 2721
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.2722Executa 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 2723
2724<Tip>2724<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.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.
2731 2731
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).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).
2733 2733
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.2734O 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 2735
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.2736Os 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 2737
2738Cada entrada em `background_tasks` descreve uma tarefa em voo e usa esses campos:2738Cada entrada em `background_tasks` descreve uma tarefa em voo e usa esses campos:
2739 2739
2740| Campo | Descrição |2740| Campo | Descrição |
2741| :- | :- |2741| :- | :- |
2742| `id` | Identificador de tarefa |2742| `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 |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 Claude Code criou a tarefa. Volta para o discriminante bruto para tipos não reconhecidos |
2744| `status` | Status atual da tarefa |2744| `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 |2745| `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` |2746| `command` | Linha de comando de shell, limitada a 1000 caracteres. Presente apenas para tarefas `shell` |
2798| Campo | Descrição |2798| Campo | Descrição |
2799| :- | :- |2799| :- | :- |
2800| `decision` | `"block"` impede que Claude pare. Omita para permitir que Claude pare |2800| `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 |2801| `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 |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 |
2803 2803
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.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.
2810}2810}
2811```2811```
2812 2812
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:2813Use `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 2814
2815```json theme={null}2815```json theme={null}
2816{2816{
2825 StopFailure2825 StopFailure
2826</h3>2826</h3>
2827 2827
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.2828Executa 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 2829
2830<h4 id="stopfailure-input">2830<h4 id="stopfailure-input">
2831 Entrada StopFailure2831 Entrada StopFailure
2837| :- | :- |2837| :- | :- |
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` |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` |
2839| `error_details` | Detalhes adicionais sobre o erro, quando disponível |2839| `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"` |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 do Claude, para `StopFailure` ele contém a string de erro da API em si, como `"API Error: Rate limit reached"` |
2841 2841
2842```json theme={null}2842```json theme={null}
2843{2843{
2857 TeammateIdle2857 TeammateIdle
2858</h3>2858</h3>
2859 2859
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.2860Executa 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 2861
2862Hooks TeammateIdle não suportam matchers e são disparados em cada ocorrência.2862Hooks TeammateIdle não suportam matchers e disparam em cada ocorrência.
2863 2863
2864<h4 id="teammateidle-input">2864<h4 id="teammateidle-input">
2865 Entrada TeammateIdle2865 Entrada TeammateIdle
2881 2881
2882| Campo | Descrição |2882| Campo | Descrição |
2883| :- | :- |2883| :- | :- |
2884| `teammate_name` | Nome do colega que está prestes a ficar inativo |2884| `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 |2885| `team_name` | Descontinuado. Nome de equipe derivado de sessão; será removido em uma versão futura |
2886 2886
2887<h4 id="teammateidle-decision-control">2887<h4 id="teammateidle-decision-control">
2888 Controle de decisão TeammateIdle2888 Controle de decisão TeammateIdle
2889</h4>2889</h4>
2890 2890
2891Hooks TeammateIdle suportam duas maneiras de controlar o comportamento do colega:2891Hooks TeammateIdle suportam duas maneiras de controlar o comportamento do colega de equipe:
2892 2892
2893* **Código de saída 2**: o colega recebe a mensagem stderr como feedback e continua trabalhando em vez de ficar inativo.2893* **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.2894* **JSON `{"continue": false, "stopReason": "..."}`**: para o colega de equipe inteiramente, correspondendo ao comportamento do hook `Stop`. O `stopReason` é mostrado ao usuário.
2895 2895
2896Este exemplo verifica que um artefato de compilação existe antes de permitir que um colega fique inativo:2896Este exemplo verifica se um artefato de compilação existe antes de permitir que um colega de equipe fique ocioso:
2897 2897
2898```bash theme={null}2898```bash theme={null}
2899#!/bin/bash2899#!/bin/bash
2910 ConfigChange2910 ConfigChange
2911</h3>2911</h3>
2912 2912
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.2913Executa 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 2914
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.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.
2916 2916
2979}2979}
2980```2980```
2981 2981
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.2982Mudanç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 2983
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.2984Claude 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 2985
2986<h3 id="cwdchanged">2986<h3 id="cwdchanged">
2987 CwdChanged2987 CwdChanged
2988</h3>2988</h3>
2989 2989
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.2990Executa 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 2991
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.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.
2993 2993
2994CwdChanged não suporta matchers e é disparado em cada ocorrência.2994CwdChanged não suporta matchers e dispara em cada ocorrência.
2995 2995
2996<h4 id="cwdchanged-input">2996<h4 id="cwdchanged-input">
2997 Entrada CwdChanged2997 Entrada CwdChanged
3022 3022
3023Hooks CwdChanged não têm controle de decisão. Eles não podem bloquear a mudança de diretório.3023Hooks CwdChanged não têm controle de decisão. Eles não podem bloquear a mudança de diretório.
3024 3024
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.3025Claude 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 3026
3027<h3 id="directoryadded">3027<h3 id="directoryadded">
3028 DirectoryAdded3028 DirectoryAdded
3029</h3>3029</h3>
3030 3030
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.3031Executa 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 3032
3033Claude Code não dispara este evento quando:3033Claude Code não dispara este evento quando:
3034 3034
3036* Você adiciona um diretório na aba Workspace `/permissions`3036* 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 um3037* Você adiciona um diretório que já é um diretório de trabalho ou está dentro de um
3038 3038
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.3039Claude 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 3040
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.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.
3042 3042
3071 3071
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: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:
3073 3073
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ção3074* `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ção3075* `register_repo_root`: Claude Code escreve saída `systemMessage` e saída de falha apenas no log de depuração
3076 3076
3077<h3 id="filechanged">3077<h3 id="filechanged">
3078 FileChanged3078 FileChanged
3079</h3>3079</h3>
3080 3080
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.3081Executa 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 3082
3083O `matcher` para este evento serve dois papéis:3083O `matcher` para este evento serve dois papéis:
3084 3084
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`.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, 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.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.
3087 3087
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: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:
3105}3105}
3106```3106```
3107 3107
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: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, 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 3109
3110```bash theme={null}3110```bash theme={null}
3111#!/bin/bash3111#!/bin/bash
3115fi3115fi
3116```3116```
3117 3117
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.3118Para 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 3119
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 `*`.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, 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 3121
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.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.
3123 3123
3130| Campo | Descrição |3130| Campo | Descrição |
3131| :- | :- |3131| :- | :- |
3132| `file_path` | Caminho absoluto para o arquivo que mudou |3132| `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 |3133| `event` | O que aconteceu: `"change"` para um arquivo modificado, `"add"` para um arquivo criado ou `"unlink"` para um arquivo excluído |
3134 3134
3135```json theme={null}3135```json theme={null}
3136{3136{
3155 3155
3156Hooks FileChanged não têm controle de decisão. Eles não podem bloquear a mudança de arquivo de ocorrer.3156Hooks FileChanged não têm controle de decisão. Eles não podem bloquear a mudança de arquivo de ocorrer.
3157 3157
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.3158Claude 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 3159
3160<h3 id="worktreecreate">3160<h3 id="worktreecreate">
3161 WorktreeCreate3161 WorktreeCreate
3162</h3>3162</h3>
3163 3163
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.3164Executa 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 3165
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.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.
3167 3167
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.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.
3169 3169
3170Claude Code atua no sucesso do hook e no caminho retornado, e descarta `systemMessage` e `continue`.3170Claude Code age no sucesso do hook e no caminho retornado, e descarta `systemMessage` e `continue`.
3171 3171
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: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:
3173 3173
3210 Saída WorktreeCreate3210 Saída WorktreeCreate
3211</h4>3211</h4>
3212 3212
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:3213Hooks 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 3214
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.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, 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.3216* **Hooks HTTP** (`type: "http"`): retorne `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` no corpo da resposta.
3217 3217
3218Se o hook falhar ou não produzir um caminho, a criação de worktree falha com um erro.3218Se o hook falhar ou não produzir um caminho, a criação de worktree falha com um erro.
3219 3219
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.3220Claude 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 3221
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.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.
3223 3223
3225 WorktreeRemove3225 WorktreeRemove
3226</h3>3226</h3>
3227 3227
3228Executado quando uma worktree está sendo removida. Este é o equivalente de limpeza para [WorktreeCreate](#worktreecreate). O evento é disparado quando:3228Executa quando uma worktree está sendo removida. Este é o equivalente de limpeza para [WorktreeCreate](#worktreecreate). O evento dispara quando:
3229 3229
3230* você sai de uma sessão `--worktree` e escolhe removê-la3230* você sai de uma sessão `--worktree` e escolhe removê-la
3231* um subagente com `isolation: "worktree"` termina3231* 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 criou3232* você exclui uma [sessão de fundo](/docs/pt/agent-view#what-deleting-a-session-removes) cuja worktree o hook criou
3233 3233
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:3234Para 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 3235
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.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, 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.3237* **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).3238* **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 3239
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.3240Claude 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 3241
3242Claude Code descarta [campos de saída JSON](#json-output) de um hook WorktreeRemove, como `systemMessage` e `continue`.3242Claude Code descarta [campos de saída JSON](#json-output) de um hook WorktreeRemove, como `systemMessage` e `continue`.
3243 3243
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.3244Para 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 3245
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: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:
3247 3247
3278}3278}
3279```3279```
3280 3280
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:3281O 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 3282
3283* A worktree permanece no disco, e o comando do hook e stderr vão para o [log de depuração](#debug-hooks).3283* 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.3284* 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 3285
3286<h3 id="precompact">3286<h3 id="precompact">
3287 PreCompact3287 PreCompact
3288</h3>3288</h3>
3289 3289
3290Executado antes de Claude Code estar prestes a executar uma operação de compactação.3290Executa antes de Claude Code estar prestes a executar uma operação de compactação.
3291 3291
3292O valor do matcher indica se a compactação foi disparada manualmente ou automaticamente:3292O valor do matcher indica se a compactação foi disparada manualmente ou automaticamente:
3293 3293
3298 3298
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"`.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"`.
3300 3300
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.3301Bloquear 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 3302
3303Claude Code descarta campos `systemMessage` e `continue` de um hook PreCompact.3303Claude Code descarta campos `systemMessage` e `continue` de um hook PreCompact.
3304 3304
3323 PostCompact3323 PostCompact
3324</h3>3324</h3>
3325 3325
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.3326Executa 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 3327
3328Os mesmos valores de matcher se aplicam como para `PreCompact`:3328Os mesmos valores de matcher se aplicam como para `PreCompact`:
3329 3329
3355 PreModelSwitch3355 PreModelSwitch
3356</h3>3356</h3>
3357 3357
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.3358Executa 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 3359
3360PreModelSwitch requer Claude Code v2.1.251 ou posterior. Claude Code o executa para essas solicitações:3360PreModelSwitch requer Claude Code v2.1.251 ou posterior. Claude Code o executa para essas solicitações:
3361 3361
3362* `/model <name>` e o picker `/model`3362* `/model <name>` e o seletor `/model`
3363* O picker de modelo `Option+P` ou `Alt+P`3363* O seletor de modelo `Option+P` ou `Alt+P`
3364* A configuração Model em `/config`3364* A configuração Model em `/config`
3365* Ativar [modo rápido](/docs/pt/fast-mode) quando isso muda o modelo da sessão3365* 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)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)
3367 3367
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.3368Claude 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 3369
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.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, então `claude-opus-5` cobre cada ortografia de Opus 5.
3371 3371
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.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.
3373 3373
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: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, então recusa uma mudança para Opus 4.6 ao sair com código 2 e deixa qualquer outro alvo passar:
3375 3375
3376<Tabs>3376<Tabs>
3377 <Tab title="macOS/Linux">3377 <Tab title="macOS/Linux">
3443 Entrada PreModelSwitch3443 Entrada PreModelSwitch
3444</h4>3444</h4>
3445 3445
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.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, então um hook pode mostrar essa figura antes da mudança acontecer.
3447 3447
3448| Campo | Tipo | Descrição |3448| Campo | Tipo | Descrição |
3449| :- | :- | :- |3449| :- | :- | :- |
3450| `from_model` | string | ID de modelo de que a mudança muda |3450| `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 |3451| `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 |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 |
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 |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 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 |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 |
3455| `prompt_cache_warm` | boolean | Se o cache de prompt do modelo atual provavelmente ainda está quente, significando que a mudança o perde |3455| `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"` |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"` |
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 |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, 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 |3458| `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 3459
3460Este exemplo mostra a entrada para `/model opus` em uma sessão executando Sonnet 5:3460Este exemplo mostra a entrada para `/model opus` em uma sessão executando Sonnet 5:
3461 3461
3506 3506
3507Quando vários hooks PreModelSwitch retornam decisões diferentes, a precedência é `deny` > `ask` > `allow`.3507Quando vários hooks PreModelSwitch retornam decisões diferentes, a precedência é `deny` > `ask` > `allow`.
3508 3508
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.3509Claude 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 3510
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.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`, então os padrões `prompt` e `agent` não se aplicam.
3512 3512
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).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).
3514 3514
3516 PostModelSwitch3516 PostModelSwitch
3517</h3>3517</h3>
3518 3518
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.3519Executa 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 3520
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: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:
3522 3522
3549}3549}
3550```3550```
3551 3551
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.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 ao Claude qual orientação ele tem sobre o modelo atual.
3553 3553
3554<h4 id="postmodelswitch-input">3554<h4 id="postmodelswitch-input">
3555 Entrada PostModelSwitch3555 Entrada PostModelSwitch
3563 Controle de decisão PostModelSwitch3563 Controle de decisão PostModelSwitch
3564</h4>3564</h4>
3565 3565
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:3566Claude 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 3567
3568| Campo | Descrição |3568| Campo | Descrição |
3569| :- | :- |3569| :- | :- |
3570| `additionalContext` | String adicionada ao contexto de Claude com a próxima solicitação. Veja [Adicionar contexto para Claude](#add-context-for-claude) |3570| `additionalContext` | String adicionada ao contexto do Claude com a próxima solicitação. Veja [Adicionar contexto para Claude](#add-context-for-claude) |
3571 3571
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.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 de alvo do último modelo.
3573 3573
3574<h3 id="sessionend">3574<h3 id="sessionend">
3575 SessionEnd3575 SessionEnd
3576</h3>3576</h3>
3577 3577
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.3578Executa 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 3579
3580O campo `reason` na entrada do hook indica por que a sessão terminou:3580O campo `reason` na entrada do hook indica por que a sessão terminou:
3581 3581
3582| Motivo | Descrição |3582| Motivo | Descrição |
3583| :- | :- |3583| :- | :- |
3584| `clear` | Sessão limpa com comando `/clear` |3584| `clear` | Sessão limpa com comando `/clear` |
3585| `resume` | Sessão mudou via `/resume` interativo |3585| `resume` | Sessão mudada via `/resume` interativo |
3586| `logout` | Usuário fez logout |3586| `logout` | Usuário fez logout |
3587| `prompt_input_exit` | Usuário saiu enquanto entrada de prompt estava visível |3587| `prompt_input_exit` | Usuário saiu enquanto entrada de prompt estava visível |
3588| `other` | Outros motivos de saída |3588| `other` | Outros motivos de saída |
3608 3608
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: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:
3610 3610
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.3611* **`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`.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`.
3613 3613
3614Este exemplo define o orçamento para 5 segundos:3614Este exemplo define o orçamento para 5 segundos:
3623 Elicitation3623 Elicitation
3624</h3>3624</h3>
3625 3625
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.3626Executa 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 3627
3628O campo matcher corresponde ao nome do servidor MCP.3628O campo matcher corresponde ao nome do servidor MCP.
3629 3629
3633 3633
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`.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`.
3635 3635
3636Para elicitação de modo formulário, o caso mais comum:3636Para elicitação de modo de formulário, o caso mais comum:
3637 3637
3638```json theme={null}3638```json theme={null}
3639{3639{
3693 3693
3694Código de saída 2 nega a elicitação. Claude Code não mostra sua mensagem stderr em lugar algum.3694Código de saída 2 nega a elicitação. Claude Code não mostra sua mensagem stderr em lugar algum.
3695 3695
3696Claude Code atua em `hookSpecificOutput` da saída JSON de um hook Elicitation e descarta `systemMessage` e `continue`.3696Claude Code age em `hookSpecificOutput` de uma saída JSON de hook Elicitation e descarta `systemMessage` e `continue`.
3697 3697
3698<h3 id="elicitationresult">3698<h3 id="elicitationresult">
3699 ElicitationResult3699 ElicitationResult
3700</h3>3700</h3>
3701 3701
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.3702Executa 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 3703
3704O campo matcher corresponde ao nome do servidor MCP.3704O campo matcher corresponde ao nome do servidor MCP.
3705 3705
3746 3746
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.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.
3748 3748
3749Claude Code atua em `hookSpecificOutput` da saída JSON de um hook ElicitationResult e descarta `systemMessage` e `continue`.3749Claude Code age em `hookSpecificOutput` de uma saída JSON de hook ElicitationResult e descarta `systemMessage` e `continue`.
3750 3750
3751<h2 id="prompt-based-hooks">3751<h2 id="prompt-based-hooks">
3752 Hooks baseados em prompt3752 Hooks baseados em prompt
