757 Entrada e saída de hook757 Entrada e saída de hook
758</h2>758</h2>
759 759
760Hooks de comando recebem dados JSON via stdin e comunicam resultados através de códigos de saída, stdout e stderr. Hooks HTTP recebem o mesmo JSON como corpo da solicitação POST e comunicam resultados através do corpo da resposta HTTP. Esta seção cobre campos e comportamento comuns a todos os eventos. Cada seção de evento sob [Eventos de hook](#hook-events) inclui seu esquema de entrada específico e opções de controle de decisão.760Hooks de comando recebem dados JSON via stdin e comunicam resultados através de códigos de saída, stdout e stderr. Hooks HTTP recebem o mesmo JSON como corpo da requisição POST e comunicam resultados através do corpo da resposta HTTP. Esta seção cobre campos e comportamento comuns a todos os eventos. Cada seção de evento sob [Eventos de hook](#hook-events) inclui seu esquema de entrada específico e opções de controle de decisão.
761 761
762No macOS e Linux, hooks de comando executam em sua própria sessão sem um terminal controlador. O processo de hook e qualquer processo filho não podem abrir `/dev/tty` ou enviar sequências de escape diretamente para a interface do Claude Code. Windows não tem `/dev/tty`.762No macOS e Linux, hooks de comando executam em sua própria sessão sem um terminal controlador. O processo de hook e qualquer processo filho não podem abrir `/dev/tty` ou enviar sequências de escape diretamente para a interface do Claude Code. Windows não tem `/dev/tty`.
763 763
767 Campos de entrada comuns767 Campos de entrada comuns
768</h3>768</h3>
769 769
770Eventos de hook recebem esses campos como JSON, além de campos específicos do evento documentados em cada seção [evento de hook](#hook-events). Para hooks de comando, este JSON chega via stdin. Para hooks HTTP, chega como corpo da solicitação POST.770Eventos de hook recebem esses campos como JSON, além de campos específicos do evento documentados em cada seção [evento de hook](#hook-events). Para hooks de comando, este JSON chega via stdin. Para hooks HTTP, chega como corpo da requisição POST.
771 771
772| Campo | Descrição |772| Campo | Descrição |
773| :- | :- |773| :- | :- |
774| `session_id` | Identificador de sessão atual |774| `session_id` | Identificador de sessão atual |
775| `prompt_id` | UUID identificando o prompt do usuário sendo processado atualmente. Corresponde ao [atributo `prompt.id` em eventos OpenTelemetry](/docs/pt/monitoring-usage#event-correlation-attributes), para que você possa correlacionar saída de hook com telemetria para um único prompt. Ausente até a primeira entrada do usuário |775| `prompt_id` | UUID identificando o prompt do usuário sendo processado atualmente. Corresponde ao [atributo `prompt.id` em eventos OpenTelemetry](/docs/pt/monitoring-usage#event-correlation-attributes), para que você possa correlacionar saída de hook com telemetria para um único prompt. Ausente até a primeira entrada do usuário |
776| `transcript_path` | Caminho para JSON de conversa. O arquivo de transcrição é escrito de forma assíncrona e pode ficar atrás da conversa na memória, portanto pode não incluir ainda as mensagens mais recentes da rodada atual quando um hook dispara. Hooks que precisam do texto final do assistente da rodada atual devem usar `last_assistant_message` em [Stop](#stop) e [SubagentStop](#subagentstop) em vez de ler a transcrição |776| `transcript_path` | Caminho para JSON de conversa. O arquivo de transcrição é escrito de forma assíncrona e pode ficar atrás da conversa na memória, portanto pode não incluir ainda as mensagens mais recentes do turno atual quando um hook dispara. Hooks que precisam do texto final do assistente do turno atual devem usar `last_assistant_message` em [Stop](#stop) e [SubagentStop](#subagentstop) em vez de ler a transcrição |
777| `cwd` | Diretório de trabalho atual quando o hook é invocado |777| `cwd` | Diretório de trabalho atual quando o hook é invocado |
778| `scratchpad_dir` | Caminho para o [diretório scratchpad da sessão](/docs/pt/claude-directory#session-scratchpad-directory), onde Claude mantém arquivos de trabalho temporários. Ausente quando a sessão não tem scratchpad ou o diretório temporário não está disponível. Requer Claude Code v2.1.257 ou posterior |778| `scratchpad_dir` | Caminho para o [diretório scratchpad da sessão](/docs/pt/claude-directory#session-scratchpad-directory), onde Claude mantém arquivos de trabalho temporários. Ausente quando a sessão não tem scratchpad ou o diretório temporário não está disponível. Requer Claude Code v2.1.257 ou posterior |
779| `permission_mode` | [Modo de permissão](/docs/pt/permissions#permission-modes) atual: `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"` ou `"bypassPermissions"`. O modo rotulado **Manual** chega como `"default"`, nunca como `"manual"`, portanto scripts que correspondem a `"default"` continuam funcionando. Nem todos os eventos recebem este campo. Verifique o exemplo JSON em cada seção [evento de hook](#hook-events) |779| `permission_mode` | [Modo de permissão](/docs/pt/permissions#permission-modes) atual: `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"` ou `"bypassPermissions"`. O modo rotulado **Manual** chega como `"default"`, nunca como `"manual"`, portanto scripts que correspondem a `"default"` continuam funcionando. Nem todos os eventos recebem este campo. Verifique o exemplo JSON em cada seção [evento de hook](#hook-events) |
823 823
824O código de saída do seu comando de hook diz ao Claude Code se a ação deve prosseguir, ser bloqueada ou ser ignorada. O código de saída não atua sozinho. Claude Code lê [campos de saída JSON](#json-output) de stdout em cada código de saída, não apenas 0, e para eventos que usam o modelo de decisão padrão, um objeto analisado que passa na validação de esquema entra em vigor ao lado do código. O bloqueio da saída 2 é o único resultado que JSON não pode substituir.824O código de saída do seu comando de hook diz ao Claude Code se a ação deve prosseguir, ser bloqueada ou ser ignorada. O código de saída não atua sozinho. Claude Code lê [campos de saída JSON](#json-output) de stdout em cada código de saída, não apenas 0, e para eventos que usam o modelo de decisão padrão, um objeto analisado que passa na validação de esquema entra em vigor ao lado do código. O bloqueio da saída 2 é o único resultado que JSON não pode substituir.
825 825
826Duas tabelas possuem as exceções por evento: [Comportamento de código de saída 2 por evento](#exit-code-2-behavior-per-event) diz o que códigos de saída fazem para cada evento, e [Controle de decisão](#decision-control) diz quais campos de decisão cada evento honra. Campos universais como `systemMessage` funcionam em muitos eventos e são listados na tabela [Saída JSON](#json-output).826Duas tabelas possuem as exceções por evento: [Comportamento de código de saída 2 por evento](#exit-code-2-behavior-per-event) diz o que códigos de saída fazem para cada evento, e [Controle de decisão](#decision-control) diz quais campos de decisão cada evento honra. Campos universais como `systemMessage` funcionam na maioria dos eventos e são listados na tabela [Saída JSON](#json-output).
827 827
828<h4 id="exit-code-0">828<h4 id="exit-code-0">
829 Código de saída 0829 Código de saída 0
924| `StopFailure` | Não | Saída e código de saída são ignorados, exceto `terminalSequence` |924| `StopFailure` | Não | Saída e código de saída são ignorados, exceto `terminalSequence` |
925| `PostToolUse` | Não | Mostra stderr ao Claude; a ferramenta já executou |925| `PostToolUse` | Não | Mostra stderr ao Claude; a ferramenta já executou |
926| `PostToolUseFailure` | Não | Mostra stderr ao Claude; a ferramenta já falhou |926| `PostToolUseFailure` | Não | Mostra stderr ao Claude; a ferramenta já falhou |
927| `PostToolBatch` | Sim | Para o loop agentic antes da próxima chamada de modelo |927| `PostToolBatch` | Sim | Para o loop agêntico antes da próxima chamada de modelo |
928| `PermissionDenied` | Não | Código de saída e stderr são ignorados porque a negação já ocorreu. Use JSON `hookSpecificOutput.retry: true` para dizer ao modelo que pode tentar novamente; Claude Code ignora `retry: true` para [negações sem veredicto](#permissiondenied-decision-control) |928| `PermissionDenied` | Não | Código de saída e stderr são ignorados porque a negação já ocorreu. Use JSON `hookSpecificOutput.retry: true` para dizer ao modelo que pode tentar novamente; Claude Code ignora `retry: true` para [negações sem veredicto](#permissiondenied-decision-control) |
929| `Notification` | Não | Código de saída e stderr são ignorados |929| `Notification` | Não | Código de saída e stderr são ignorados |
930| `SubagentStart` | Não | Mostra stderr apenas ao usuário |930| `SubagentStart` | Não | Mostra stderr apenas ao usuário |
938| `PostCompact` | Não | Mostra stderr apenas ao usuário |938| `PostCompact` | Não | Mostra stderr apenas ao usuário |
939| `PreModelSwitch` | Sim | Bloqueia a mudança de modelo e mostra stderr ao usuário |939| `PreModelSwitch` | Sim | Bloqueia a mudança de modelo e mostra stderr ao usuário |
940| `PostModelSwitch` | Não | Mostra stderr apenas ao usuário; o modelo já mudou |940| `PostModelSwitch` | Não | Mostra stderr apenas ao usuário; o modelo já mudou |
941| `Elicitation` | Sim | Nega a elicitação |941| `Elicitation` | Sim | Recusa a solicitação, e nenhuma caixa de diálogo aparece |
942| `ElicitationResult` | Sim | Bloqueia a resposta (ação se torna decline) |942| `ElicitationResult` | Sim | Bloqueia a resposta (ação se torna decline) |
943| `WorktreeCreate` | Sim | Qualquer código de saída não-zero causa falha na criação de worktree |943| `WorktreeCreate` | Sim | Qualquer código de saída não-zero causa falha na criação de worktree |
944| `WorktreeRemove` | Sim | Qualquer código de saída não-zero causa falha na remoção de worktree se o diretório ainda existir depois. Consulte [WorktreeRemove](#worktreeremove) para o que acontece com o diretório |944| `WorktreeRemove` | Sim | Qualquer código de saída não-zero causa falha na remoção de worktree se o diretório ainda existir depois. Consulte [WorktreeRemove](#worktreeremove) para o que acontece com o diretório |
972 Escolha uma abordagem por hook: ou use códigos de saída sozinhos para sinalizar, ou saia 0 e imprima JSON para controle estruturado. Se você misturar, saída 2 mantém seu [efeito de bloqueio](#exit-code-2-behavior-per-event), e Claude Code ainda lê os campos JSON, com a exceção de elicitação única anotada em [Código de saída 2](#exit-code-2).972 Escolha uma abordagem por hook: ou use códigos de saída sozinhos para sinalizar, ou saia 0 e imprima JSON para controle estruturado. Se você misturar, saída 2 mantém seu [efeito de bloqueio](#exit-code-2-behavior-per-event), e Claude Code ainda lê os campos JSON, com a exceção de elicitação única anotada em [Código de saída 2](#exit-code-2).
973</Note>973</Note>
974 974
975O stdout do seu hook deve conter apenas o objeto JSON. Se seu perfil shell imprime texto na inicialização, pode interferir com análise JSON. Consulte [Hook JSON não tem efeito](/docs/pt/hooks-guide#hook-json-has-no-effect) no guia de troubleshooting.975O stdout do seu hook deve conter apenas o objeto JSON. Se seu perfil shell imprime texto na inicialização, pode interferir com análise JSON. Consulte [Hook JSON não tem efeito](/docs/pt/hooks-guide#hook-json-has-no-effect) no guia de solução de problemas.
976 976
977As strings de saída de hook `additionalContext`, `systemMessage` e `initialUserMessage`, e seu stdout simples, são limitadas a 10.000 caracteres:977As strings de saída de hook `additionalContext`, `systemMessage` e `initialUserMessage`, e seu stdout simples, são limitadas a 10.000 caracteres:
978 978
992| `stopReason` | nenhum | Mensagem mostrada ao usuário quando `continue` é `false`. Fica na conversa, portanto Claude a vê se a conversa continuar |992| `stopReason` | nenhum | Mensagem mostrada ao usuário quando `continue` é `false`. Fica na conversa, portanto Claude a vê se a conversa continuar |
993| `suppressOutput` | `false` | Não tem efeito: Claude Code aceita o campo mas não age sobre ele. O stdout de um hook bem-sucedido nunca é mostrado na transcrição e é registrado no log de debug |993| `suppressOutput` | `false` | Não tem efeito: Claude Code aceita o campo mas não age sobre ele. O stdout de um hook bem-sucedido nunca é mostrado na transcrição e é registrado no log de debug |
994| `systemMessage` | nenhum | Mensagem de aviso mostrada ao usuário. Em [Agent SDK](/docs/pt/agent-sdk/overview) e saída [`--output-format stream-json`](/docs/pt/headless), pode chegar como um [`SDKInformationalMessage`](/docs/pt/agent-sdk/typescript#sdkinformationalmessage) |994| `systemMessage` | nenhum | Mensagem de aviso mostrada ao usuário. Em [Agent SDK](/docs/pt/agent-sdk/overview) e saída [`--output-format stream-json`](/docs/pt/headless), pode chegar como um [`SDKInformationalMessage`](/docs/pt/agent-sdk/typescript#sdkinformationalmessage) |
995| `terminalSequence` | nenhum | Uma sequência de escape de terminal para Claude Code emitir em seu nome, como uma notificação de desktop, título de janela ou sino. Restrito a OSC `0`/`1`/`2`/`9`/`99`/`777` e BEL. Se o valor contiver algo fora da lista de permissões, o campo é ignorado. Use isso em vez de escrever para `/dev/tty`, que não está disponível para hooks |995| `terminalSequence` | nenhum | Uma sequência de escape de terminal para Claude Code emitir em seu nome, como uma notificação de desktop, título de janela ou sino. Restrito a OSC `0`/`1`/`2`/`9`/`99`/`777` e BEL. Se o valor contiver algo fora da allowlist, o campo é ignorado. Use isso em vez de escrever para `/dev/tty`, que não está disponível para hooks |
996 996
997Para parar Claude inteiramente:997Para parar Claude inteiramente:
998 998
1008 1008
1009Hooks executam sem um terminal controlador, portanto escrever sequências de escape diretamente para `/dev/tty` falha. Em vez disso, retorne a sequência de escape no campo `terminalSequence` e Claude Code a emite para você através de seu próprio caminho de escrita de terminal. Isso é livre de corrida, funciona dentro de tmux e GNU screen, e funciona no Windows onde não há `/dev/tty`.1009Hooks executam sem um terminal controlador, portanto escrever sequências de escape diretamente para `/dev/tty` falha. Em vez disso, retorne a sequência de escape no campo `terminalSequence` e Claude Code a emite para você através de seu próprio caminho de escrita de terminal. Isso é livre de corrida, funciona dentro de tmux e GNU screen, e funciona no Windows onde não há `/dev/tty`.
1010 1010
1011O campo aceita uma string de uma ou mais sequências de escape na lista de permissões:1011O campo aceita uma string de uma ou mais sequências de escape da allowlist:
1012 1012
1013* OSC `0`, `1`, `2`: títulos de janela e ícone1013* OSC `0`, `1`, `2`: títulos de janela e ícone
1014* OSC `9`: notificações iTerm2, ConEmu, Windows Terminal e WezTerm, incluindo progresso de barra de tarefas `9;4`1014* OSC `9`: notificações iTerm2, ConEmu, Windows Terminal e WezTerm, incluindo progresso de barra de tarefas `9;4`
1016* OSC `777`: notificações urxvt, Ghostty e Warp1016* OSC `777`: notificações urxvt, Ghostty e Warp
1017* BEL simples1017* BEL simples
1018 1018
1019Sequências podem ser terminadas com BEL ou com ST. Qualquer coisa fora da lista de permissões, incluindo sequências de cursor e cor CSI, sequências de paleta OSC, hiperlinks OSC 8, escritas de área de transferência OSC 52 e OSC 1337, é rejeitada e o campo é ignorado.1019Sequências podem ser terminadas com BEL ou com ST. Qualquer coisa fora da allowlist, incluindo sequências de cursor e cor CSI, sequências de paleta OSC, hiperlinks OSC 8, escritas de área de transferência OSC 52 e OSC 1337, é rejeitada e o campo é ignorado.
1020 1020
1021Claude Code escreve a sequência em si quando processa a saída do seu hook, portanto o campo funciona em eventos que descartam `systemMessage` e `continue`, como `Notification` e `StopFailure`. Tem dois limites:1021Claude Code escreve a sequência em si quando processa a saída do seu hook, portanto o campo funciona em eventos que descartam `systemMessage` e `continue`, como `Notification` e `StopFailure`. Tem dois limites:
1022 1022
1023* Claude Code escreve a sequência apenas em uma sessão interativa, e apenas enquanto sua interface está na tela. Em modo não-interativo com a flag `-p` e no Agent SDK, ignora o campo.1023* Claude Code escreve a sequência apenas em uma sessão interativa, e apenas enquanto sua interface está na tela. Em modo não interativo com a flag `-p` e no Agent SDK, ignora o campo.
1024* Um hook de comando `WorktreeCreate` não pode retornar JSON, porque Claude Code lê seu stdout como o caminho de worktree. Um hook HTTP `WorktreeCreate` retorna JSON e pode incluir o campo.1024* Um hook de comando `WorktreeCreate` não pode retornar JSON, porque Claude Code lê seu stdout como o caminho de worktree. Um hook HTTP `WorktreeCreate` retorna JSON e pode incluir o campo.
1025 1025
1026O exemplo abaixo dispara uma notificação de desktop de um hook `Notification`. A sequência de escape é construída com `printf` escapes octais para que os bytes de controle nunca apareçam na linha de comando do shell, e `jq -n --arg` constrói a saída JSON para que aspas, barras invertidas e quebras de linha na mensagem de notificação sejam escapadas corretamente:1026O exemplo abaixo dispara uma notificação de desktop de um hook `Notification`. A sequência de escape é construída com `printf` escapes octais para que os bytes de controle nunca apareçam na linha de comando do shell, e `jq -n --arg` constrói a saída JSON para que aspas, barras invertidas e quebras de linha na mensagem de notificação sejam escapadas corretamente:
1041 Adicionar contexto para Claude1041 Adicionar contexto para Claude
1042</h4>1042</h4>
1043 1043
1044O campo `additionalContext` passa uma string do seu hook para a janela de contexto do Claude. Claude Code envolve a string em um [lembrete do sistema](/docs/pt/glossary#system-reminder) e a insere na conversa no ponto onde o hook disparou. Claude lê o lembrete na próxima solicitação de modelo, mas não aparece como uma mensagem de chat na interface.1044O campo `additionalContext` passa uma string do seu hook para a janela de contexto do Claude. Claude Code envolve a string em um [lembrete do sistema](/docs/pt/glossary#system-reminder) e a insere na conversa no ponto onde o hook disparou. Claude lê o lembrete na próxima requisição ao modelo, mas não aparece como uma mensagem de chat na interface.
1045 1045
1046Retorne `additionalContext` dentro de `hookSpecificOutput` ao lado do nome do evento:1046Retorne `additionalContext` dentro de `hookSpecificOutput` ao lado do nome do evento:
1047 1047
1059* [SessionStart](#sessionstart) e [SubagentStart](#subagentstart): no início da conversa, antes do primeiro prompt1059* [SessionStart](#sessionstart) e [SubagentStart](#subagentstart): no início da conversa, antes do primeiro prompt
1060* [UserPromptSubmit](#userpromptsubmit) e [UserPromptExpansion](#userpromptexpansion): ao lado do prompt enviado1060* [UserPromptSubmit](#userpromptsubmit) e [UserPromptExpansion](#userpromptexpansion): ao lado do prompt enviado
1061* [PreToolUse](#pretooluse), [PostToolUse](#posttooluse), [PostToolUseFailure](#posttoolusefailure) e [PostToolBatch](#posttoolbatch): ao lado do resultado da ferramenta1061* [PreToolUse](#pretooluse), [PostToolUse](#posttooluse), [PostToolUseFailure](#posttoolusefailure) e [PostToolBatch](#posttoolbatch): ao lado do resultado da ferramenta
1062* [Stop](#stop) e [SubagentStop](#subagentstop): no final da rodada. A conversa continua para que Claude possa agir sobre o feedback. Consulte [Controle de decisão Stop](#stop-decision-control)1062* [Stop](#stop) e [SubagentStop](#subagentstop): no final do turno. A conversa continua para que Claude possa agir sobre o feedback. Consulte [Controle de decisão Stop](#stop-decision-control)
1063* [PostModelSwitch](#postmodelswitch): com a próxima solicitação após a mudança. Consulte [Controle de decisão PostModelSwitch](#postmodelswitch-decision-control) para timing1063* [PostModelSwitch](#postmodelswitch): com a próxima requisição após a mudança. Consulte [Controle de decisão PostModelSwitch](#postmodelswitch-decision-control) para timing
1064 1064
1065Quando vários hooks retornam `additionalContext` para o mesmo evento, Claude recebe todos os valores.1065Quando vários hooks retornam `additionalContext` para o mesmo evento, Claude recebe todos os valores.
1066 1066
1069Use `additionalContext` para informações que Claude deve saber sobre o estado atual do seu ambiente ou a operação que acabou de executar:1069Use `additionalContext` para informações que Claude deve saber sobre o estado atual do seu ambiente ou a operação que acabou de executar:
1070 1070
1071* **Estado do ambiente**: o branch atual, alvo de implantação ou sinalizadores de recurso ativos1071* **Estado do ambiente**: o branch atual, alvo de implantação ou sinalizadores de recurso ativos
1072* **Regras de projeto condicional**: qual comando de teste se aplica ao arquivo que acabou de ser editado, quais diretórios são somente leitura nesta worktree1072* **Regras de projeto condicional**: qual comando de teste se aplica ao arquivo que acabou de ser editado, quais diretórios são somente leitura neste worktree
1073* **Dados externos**: problemas abertos atribuídos a você, resultados recentes de CI, conteúdo obtido de um serviço interno1073* **Dados externos**: problemas abertos atribuídos a você, resultados recentes de CI, conteúdo obtido de um serviço interno
1074 1074
1075Para instruções que nunca mudam, prefira [CLAUDE.md](/docs/pt/memory). Ele carrega sem executar um script e é o lugar padrão para convenções de projeto estáticas.1075Para instruções que nunca mudam, prefira [CLAUDE.md](/docs/pt/memory). Ele carrega sem executar um script e é o lugar padrão para convenções de projeto estáticas.
1095| PermissionDenied | `hookSpecificOutput` | `retry: true` diz ao modelo que pode tentar novamente a chamada de ferramenta negada; Claude Code ignora para [negações sem veredicto](#permissiondenied-decision-control) |1095| PermissionDenied | `hookSpecificOutput` | `retry: true` diz ao modelo que pode tentar novamente a chamada de ferramenta negada; Claude Code ignora para [negações sem veredicto](#permissiondenied-decision-control) |
1096| WorktreeCreate | retorno de caminho | Hook de comando imprime caminho em stdout; hook HTTP retorna `hookSpecificOutput.worktreePath`. Falha de hook ou caminho ausente falha na criação |1096| WorktreeCreate | retorno de caminho | Hook de comando imprime caminho em stdout; hook HTTP retorna `hookSpecificOutput.worktreePath`. Falha de hook ou caminho ausente falha na criação |
1097| WorktreeRemove | Código de saída | Qualquer código de saída não-zero faz a remoção falhar se o diretório ainda existir depois. Saída JSON é descartada |1097| WorktreeRemove | Código de saída | Qualquer código de saída não-zero faz a remoção falhar se o diretório ainda existir depois. Saída JSON é descartada |
1098| Elicitation | `hookSpecificOutput` | `action` (accept/decline/cancel), `content` (valores de campo de formulário para accept) |1098| Elicitation, ElicitationResult | `hookSpecificOutput` ou `decision` de nível superior | `action` (accept/decline/cancel), `content` (valores de campo de formulário). `decision: "block"` também [recusa](#other-ways-to-decline-an-elicitation) |
1099| ElicitationResult | `hookSpecificOutput` | `action` (accept/decline/cancel), `content` (valores de campo de formulário override) |
1100| MessageDisplay | `hookSpecificOutput` | `displayContent` substitui o texto exibido na tela. Apenas exibição: a transcrição e o que Claude vê mantêm o original |1099| MessageDisplay | `hookSpecificOutput` | `displayContent` substitui o texto exibido na tela. Apenas exibição: a transcrição e o que Claude vê mantêm o original |
1101| SessionStart, SubagentStart, PostModelSwitch | Apenas contexto | `hookSpecificOutput.additionalContext` adiciona contexto para Claude. SessionStart também aceita [`initialUserMessage`, `watchPaths`, `sessionTitle` e `reloadSkills`](#sessionstart-decision-control). Sem bloqueio ou controle de decisão |1100| SessionStart, SubagentStart, PostModelSwitch | Apenas contexto | `hookSpecificOutput.additionalContext` adiciona contexto para Claude. SessionStart também aceita [`initialUserMessage`, `watchPaths`, `sessionTitle` e `reloadSkills`](#sessionstart-decision-control). Sem bloqueio ou controle de decisão |
1102| Setup, Notification, SessionEnd, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, DirectoryAdded, FileChanged | Nenhum | Sem controle de decisão. Usado para efeitos colaterais como logging ou limpeza |1101| Setup, Notification, SessionEnd, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, DirectoryAdded, FileChanged | Nenhum | Sem controle de decisão. Usado para efeitos colaterais como logging ou limpeza |
1163 Eventos de hook1162 Eventos de hook
1164</h2>1163</h2>
1165 1164
1166Cada evento corresponde a um ponto no ciclo de vida do Claude Code em que os hooks podem ser executados. As seções abaixo estão ordenadas de acordo com o ciclo de vida: da configuração da sessão, passando pelo loop agêntico, até o fim da sessão. Cada seção descreve quando o evento é disparado, quais matchers ele suporta, a entrada JSON que ele recebe e como controlar o comportamento por meio da saída.1165Cada evento corresponde a um ponto no ciclo de vida do Claude Code em que hooks podem ser executados. As seções abaixo estão ordenadas de acordo com o ciclo de vida: da configuração da sessão, passando pelo loop agêntico, até o fim da sessão. Cada seção descreve quando o evento é disparado, quais matchers ele suporta, a entrada JSON que ele recebe e como controlar o comportamento por meio da saída.
1167 1166
1168<h3 id="sessionstart">1167<h3 id="sessionstart">
1169 SessionStart1168 SessionStart
1170</h3>1169</h3>
1171 1170
1172É executado quando o Claude Code inicia uma nova sessão ou retoma uma sessão existente. Útil para carregar contexto de desenvolvimento, como issues existentes ou alterações recentes na sua base de código, ou para configurar variáveis de ambiente. Para contexto estático que não exige um script, use o [CLAUDE.md](/docs/pt/memory).1171É executado quando o Claude Code inicia uma nova sessão ou retoma uma sessão existente. Útil para carregar contexto de desenvolvimento, como issues existentes ou alterações recentes na sua base de código, ou para configurar variáveis de ambiente. Para contexto estático que não exige um script, use [CLAUDE.md](/docs/pt/memory) em vez disso.
1173 1172
1174O SessionStart é executado em todas as sessões, então mantenha esses hooks rápidos. Somente hooks `type: "command"` e `type: "mcp_tool"` são suportados. Consulte [Campos de hook de ferramenta MCP](#mcp-tool-hook-fields) para saber quando os hooks `mcp_tool` são executados.1173O SessionStart é executado em todas as sessões, portanto mantenha esses hooks rápidos. Apenas hooks `type: "command"` e `type: "mcp_tool"` são suportados. Consulte [campos de hook de ferramenta MCP](#mcp-tool-hook-fields) para saber quando hooks `mcp_tool` são executados.
1175 1174
1176O valor do matcher corresponde à forma como a sessão foi iniciada:1175O valor do matcher corresponde a como a sessão foi iniciada:
1177 1176
1178| Matcher | Quando é disparado |1177| Matcher | Quando é disparado |
1179| :- | :- |1178| :- | :- |
1185 1184
1186Antes da v2.1.214, sessões bifurcadas informavam a origem `"resume"`.1185Antes da v2.1.214, sessões bifurcadas informavam a origem `"resume"`.
1187 1186
1188Quando você inicia uma sessão interativa, retoma uma conversa na inicialização com `--continue` ou `--resume`, ou executa `/clear`, os hooks SessionStart são executados em segundo plano. Você pode digitar imediatamente, e uma conversa retomada aparece sem esperar pelos hooks. A primeira resposta do Claude ainda espera os hooks terminarem, para que o contexto deles chegue ao Claude.1187Quando você inicia uma sessão interativa, retoma uma conversa na inicialização com `--continue` ou `--resume`, ou executa `/clear`, os hooks SessionStart são executados em segundo plano. Você pode digitar imediatamente, e uma conversa que você retomou aparece sem esperar pelos hooks. A primeira resposta do Claude ainda espera os hooks terminarem, para que o contexto deles chegue ao Claude.
1189 1188
1190Quando você alterna entre conversas com `/resume` dentro de uma sessão, a troca espera os hooks terminarem. Se você executar `/clear` ou alternar para outra conversa enquanto hooks em segundo plano ainda estiverem em execução, nada do que eles retornarem se aplica à sessão.1189Quando você troca de conversa com `/resume` dentro de uma sessão, a troca espera os hooks terminarem. Se você executar `/clear` ou trocar para outra conversa enquanto hooks em segundo plano ainda estiverem em execução, nada do que eles retornarem se aplica à sessão.
1191 1190
1192A mesma espera se aplica na inicialização, incluindo uma sessão retomada: um prompt que você envia enquanto os hooks SessionStart ainda estão em execução não chega ao Claude até que eles terminem.1191A mesma espera se aplica na inicialização, incluindo uma sessão retomada: um prompt que você envia enquanto os hooks SessionStart ainda estão em execução não chega ao Claude até que eles terminem.
1193 1192
1201 1200
1202| Campo | Descrição |1201| Campo | Descrição |
1203| :- | :- |1202| :- | :- |
1204| `source` | Como a sessão começou: `"startup"` para novas sessões, `"resume"` para sessões retomadas, `"clear"` após `/clear`, `"compact"` após a compactação ou `"fork"` para uma nova sessão bifurcada de uma existente |1203| `source` | Como a sessão foi iniciada: `"startup"` para novas sessões, `"resume"` para sessões retomadas, `"clear"` após `/clear`, `"compact"` após compactação ou `"fork"` para uma nova sessão bifurcada de uma existente |
1205| `model` | O identificador do modelo ativo. Ele pode ser omitido, por exemplo após `/clear` ou quando uma sessão é restaurada pela recuperação de conversa, então verifique a existência do campo antes de lê-lo |1204| `model` | O identificador do modelo ativo. Pode ser omitido, por exemplo após `/clear` ou quando uma sessão é restaurada por meio da recuperação de conversa, portanto verifique se o campo existe antes de lê-lo |
1206| `agent_type` | O nome do agente, presente quando você inicia o Claude Code com `claude --agent <name>` |1205| `agent_type` | O nome do agente, presente quando você inicia o Claude Code com `claude --agent <name>` |
1207| `session_title` | O título personalizado da sessão, presente quando um está definido, por exemplo com `--name`, `/rename`, a saída `sessionTitle` de um hook ou `renameSession()` do Agent SDK. Um hook que emite `sessionTitle` pode verificar esse campo primeiro para evitar sobrescrever um título personalizado existente |1206| `session_title` | O título personalizado da sessão, presente quando um estiver definido, por exemplo com `--name`, `/rename`, a saída `sessionTitle` de um hook ou o `renameSession()` do Agent SDK. Um hook que emite `sessionTitle` pode verificar este campo primeiro para evitar sobrescrever um título personalizado existente |
1208 1207
1209Uma sessão que você não nomeou ainda pode ter um [título gerado](/docs/pt/sessions#name-your-sessions). Esse título não é um título personalizado e não aparece em `session_title`.1208Uma sessão que você não nomeou ainda pode ter um [título gerado](/docs/pt/sessions#name-your-sessions). Esse título não é um título personalizado e não aparece em `session_title`.
1210 1209
1243| Campo | Descrição |1242| Campo | Descrição |
1244| :- | :- |1243| :- | :- |
1245| `additionalContext` | String adicionada ao contexto do Claude no início da conversa, antes do primeiro prompt. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) para saber como o texto é entregue e o que colocar nele |1244| `additionalContext` | String adicionada ao contexto do Claude no início da conversa, antes do primeiro prompt. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) para saber como o texto é entregue e o que colocar nele |
1246| `initialUserMessage` | String usada como a primeira mensagem do usuário da sessão. Aplica-se no [modo não interativo](/docs/pt/headless) com a flag `-p`, onde se torna o primeiro turno mesmo que nenhum prompt seja fornecido. Se um prompt for fornecido, ele vem em seguida como o próximo turno. Diferentemente de `additionalContext`, que se anexa a um turno existente, isso cria o turno |1245| `initialUserMessage` | String usada como a primeira mensagem do usuário da sessão. Aplica-se no [modo não interativo](/docs/pt/headless) com a flag `-p`, onde se torna o primeiro turno mesmo que nenhum prompt seja fornecido. Se um prompt for fornecido, ele vem como o próximo turno. Ao contrário de `additionalContext`, que se anexa a um turno existente, isto cria o turno |
1247| `sessionTitle` | Define o título da sessão, com o mesmo efeito de `/rename`. Use para nomear sessões automaticamente a partir da pasta de inicialização, do branch do git ou do nome do worktree. Aplica-se quando `source` é `"startup"`, `"resume"` ou `"fork"`; ignorado em `"clear"` e `"compact"` |1246| `sessionTitle` | Define o título da sessão, com o mesmo efeito de `/rename`. Use para nomear sessões automaticamente a partir da pasta de inicialização, do branch do git ou do nome do worktree. Aplica-se quando `source` é `"startup"`, `"resume"` ou `"fork"`; ignorado em `"clear"` e `"compact"` |
1248| `watchPaths` | Array de caminhos absolutos a observar para eventos [FileChanged](#filechanged) durante esta sessão |1247| `watchPaths` | Array de caminhos absolutos a observar para eventos [FileChanged](#filechanged) durante esta sessão |
1249| `reloadSkills` | Booleano. Quando `true`, o Claude Code examina novamente os diretórios de [skills](/docs/pt/skills) e comandos após a conclusão dos hooks SessionStart, para que as skills instaladas pelo hook estejam disponíveis na mesma sessão, a partir do primeiro prompt |1248| `reloadSkills` | Booleano. Quando `true`, o Claude Code examina novamente os diretórios de [skills](/docs/pt/skills) e comandos após a conclusão dos hooks SessionStart, para que as skills instaladas pelo hook fiquem disponíveis na mesma sessão, a partir do primeiro prompt |
1250 1249
1251```json theme={null}1250```json theme={null}
1252{1251{
1258}1257}
1259```1258```
1260 1259
1261Como o stdout simples já chega ao Claude para este evento, um hook que apenas carrega contexto pode imprimir diretamente no stdout sem montar JSON. Use o formato JSON quando precisar combinar contexto com outros campos, como `sessionTitle`.1260Como o stdout simples já chega ao Claude neste evento, um hook que apenas carrega contexto pode imprimir diretamente no stdout sem montar JSON. Use o formato JSON quando precisar combinar contexto com outros campos, como `sessionTitle`.
1262 1261
1263Use `reloadSkills` quando um hook SessionStart instala ou atualiza skills. A descoberta de skills normalmente é executada antes de os hooks SessionStart terminarem, então os arquivos que o hook grava em `~/.claude/skills/` ou `.claude/skills/` só apareceriam, de outra forma, na próxima sessão. Este exemplo sincroniza um repositório de skills compartilhado e solicita a nova varredura:1262Use `reloadSkills` quando um hook SessionStart instalar ou atualizar skills. A descoberta de skills normalmente é executada antes de os hooks SessionStart terminarem, então arquivos que o hook grava em `~/.claude/skills/` ou `.claude/skills/` só apareceriam na próxima sessão. Este exemplo sincroniza um repositório de skills compartilhado e solicita a nova varredura:
1264 1263
1265```bash theme={null}1264```bash theme={null}
1266#!/bin/bash1265#!/bin/bash
1271echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1270echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'
1272```1271```
1273 1272
1274A URL do repositório é um placeholder; substitua-a pelo seu próprio repositório de skills. Com o placeholder, o clone falha e imprime uma mensagem `fatal:` no stderr. O stderr de um hook SessionStart que sai com 0 é apenas informativo, então a solicitação `reloadSkills` ainda se aplica.1273A 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:` no stderr. O stderr de um hook SessionStart que sai com 0 é apenas informativo, portanto a solicitação de `reloadSkills` ainda se aplica.
1275 1274
1276<h4 id="persist-environment-variables">1275<h4 id="persist-environment-variables">
1277 Persistir variáveis de ambiente1276 Persistir variáveis de ambiente
1279 1278
1280Os hooks SessionStart têm acesso à variável de ambiente `CLAUDE_ENV_FILE`, que fornece um caminho de arquivo onde você pode persistir variáveis de ambiente para comandos Bash subsequentes.1279Os hooks SessionStart têm acesso à variável de ambiente `CLAUDE_ENV_FILE`, que fornece um caminho de arquivo onde você pode persistir variáveis de ambiente para comandos Bash subsequentes.
1281 1280
1282Para definir variáveis de ambiente individuais, grave instruções `export` em `CLAUDE_ENV_FILE`. Use anexação (`>>`) para preservar variáveis definidas por outros hooks:1281Para definir variáveis de ambiente individuais, escreva instruções `export` em `CLAUDE_ENV_FILE`. Use anexação (`>>`) para preservar variáveis definidas por outros hooks:
1283 1282
1284```bash theme={null}1283```bash theme={null}
1285#!/bin/bash1284#!/bin/bash
1293exit 01292exit 0
1294```1293```
1295 1294
1296Para capturar todas as alterações de ambiente feitas por comandos de configuração, compare as variáveis exportadas antes e depois:1295Para capturar todas as alterações de ambiente de comandos de configuração, compare as variáveis exportadas antes e depois:
1297 1296
1298```bash theme={null}1297```bash theme={null}
1299#!/bin/bash1298#!/bin/bash
1313```1312```
1314 1313
1315<Note>1314<Note>
1316 `CLAUDE_ENV_FILE` está disponível para hooks SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged) e [FileChanged](#filechanged). Outros tipos de hook não têm acesso a essa variável.1315 `CLAUDE_ENV_FILE` está disponível para os hooks SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged) e [FileChanged](#filechanged). Outros tipos de hook não têm acesso a essa variável.
1317</Note>1316</Note>
1318 1317
1319<h3 id="setup">1318<h3 id="setup">
1320 Setup1319 Setup
1321</h3>1320</h3>
1322 1321
1323É disparado somente quando você inicia o Claude Code com `--init-only`, ou com `--init` ou `--maintenance` no [modo não interativo](/docs/pt/headless) com a flag `-p`. Ele não é disparado na inicialização normal. Use-o para instalação única de dependências ou limpeza agendada que você aciona explicitamente a partir de CI ou scripts, separadamente da inicialização normal da sessão. Para inicialização por sessão, use o [SessionStart](#sessionstart).1322É disparado apenas quando você inicia o Claude Code com `--init-only`, ou com `--init` ou `--maintenance` no [modo não interativo](/docs/pt/headless) com a flag `-p`. Não é disparado na inicialização normal. Use-o para instalação única de dependências ou limpeza agendada que você aciona explicitamente a partir de CI ou scripts, separadamente da inicialização normal da sessão. Para inicialização por sessão, use [SessionStart](#sessionstart) em vez disso.
1324 1323
1325O valor do matcher corresponde à flag da CLI que acionou o hook:1324O valor do matcher corresponde à flag da CLI que acionou o hook:
1326 1325
1333 1332
1334Quando você inicia ou continua uma conversa com `-p`, também precisa fornecer um prompt, como argumento ou via pipe no stdin. Você pode omitir o prompt quando um hook `SessionStart` fornece [`initialUserMessage`](#sessionstart-decision-control) ou quando você retoma uma sessão com uma [chamada de ferramenta adiada](#defer-a-tool-call-for-later).1333Quando você inicia ou continua uma conversa com `-p`, também precisa fornecer um prompt, como argumento ou via pipe no stdin. Você pode omitir o prompt quando um hook `SessionStart` fornece [`initialUserMessage`](#sessionstart-decision-control) ou quando você retoma uma sessão com uma [chamada de ferramenta adiada](#defer-a-tool-call-for-later).
1335 1334
1336Em caso de sucesso, `--init-only` não imprime nada no terminal. Para confirmar que os hooks foram executados, inicie com `claude --debug-file <path> --init-only`, substituindo `<path>` por um local de arquivo de log, e verifique no log as entradas dos hooks Setup e SessionStart.1335Em caso de sucesso, `--init-only` não imprime nada no terminal. Para confirmar que os hooks foram executados, inicie com `claude --debug-file <path> --init-only`, substituindo `<path>` pelo local de um arquivo de log, e verifique no log as entradas dos hooks Setup e SessionStart.
1337 1336
1338Como o Setup não é disparado a cada inicialização, um plugin que precisa de uma dependência instalada não pode depender apenas do Setup. O padrão prático é verificar a dependência no primeiro uso e instalá-la se estiver ausente, por exemplo um hook ou skill que testa `${CLAUDE_PLUGIN_DATA}/node_modules` e executa `npm install` se não existir. Consulte o [diretório de dados persistentes](/docs/pt/plugins/components#path-variables-and-persistent-data) para saber onde armazenar dependências instaladas. Se você distribui seu plugin por meio de um marketplace, talvez não precise desse padrão: o Claude Code [instala automaticamente as dependências de pacotes Node.js elegíveis](/docs/pt/plugins/loading#node-js-package-dependencies) ao armazenar o plugin em cache.1337Como o Setup não é disparado em toda inicialização, um plugin que precisa de uma dependência instalada não pode depender apenas do Setup. O padrão prático é verificar a dependência no primeiro uso e instalá-la se estiver ausente, por exemplo um hook ou skill que testa a existência de `${CLAUDE_PLUGIN_DATA}/node_modules` e executa `npm install` se não existir. Consulte o [diretório de dados persistentes](/docs/pt/plugins/components#path-variables-and-persistent-data) para saber onde armazenar dependências instaladas. Se você distribui seu plugin por meio de um marketplace, talvez não precise desse padrão: o Claude Code [instala automaticamente as dependências de pacotes Node.js elegíveis](/docs/pt/plugins/loading#node-js-package-dependencies) quando armazena o plugin em cache.
1339 1338
1340<h4 id="setup-input">1339<h4 id="setup-input">
1341 Entrada do Setup1340 Entrada do Setup
1357 Controle de decisão do Setup1356 Controle de decisão do Setup
1358</h4>1357</h4>
1359 1358
1360Os hooks Setup não podem bloquear; a execução continua com qualquer código de saída. Em todo código de saída, o Claude Code descarta os [campos de saída JSON](#json-output) de um hook Setup, como `systemMessage`, `continue` e `hookSpecificOutput.additionalContext`. Com `-p`, o stdout, o stderr e o código de saída de um hook Setup aparecem na saída da execução somente como [eventos `hook_response`](/docs/pt/headless#read-session-metadata) quando você inicia com `--output-format stream-json --verbose`.1359Os hooks Setup não podem bloquear; a execução continua com qualquer código de saída. Em todos os códigos de saída, o Claude Code descarta os [campos de saída JSON](#json-output) de um hook Setup, como `systemMessage`, `continue` e `hookSpecificOutput.additionalContext`. Com `-p`, o stdout, o stderr e o código de saída de um hook Setup aparecem na saída da execução apenas como [eventos `hook_response`](/docs/pt/headless#read-session-metadata) quando você inicia com `--output-format stream-json --verbose`.
1361 1360
1362Os hooks Setup têm acesso a `CLAUDE_ENV_FILE`. As variáveis gravadas nesse arquivo persistem nos comandos Bash subsequentes da sessão, como nos [hooks SessionStart](#persist-environment-variables). Somente hooks `type: "command"` são executados no `Setup`. Um hook `type: "mcp_tool"` no `Setup` é sempre ignorado, conforme descrito em [campos de hook de ferramenta MCP](#mcp-tool-hook-fields).1361Os hooks Setup têm acesso a `CLAUDE_ENV_FILE`. Variáveis gravadas nesse arquivo persistem nos comandos Bash subsequentes da sessão, como nos [hooks SessionStart](#persist-environment-variables). Apenas hooks `type: "command"` são executados no `Setup`. Um hook `type: "mcp_tool"` no `Setup` é sempre ignorado, conforme descrito em [campos de hook de ferramenta MCP](#mcp-tool-hook-fields).
1363 1362
1364<h3 id="instructionsloaded">1363<h3 id="instructionsloaded">
1365 InstructionsLoaded1364 InstructionsLoaded
1366</h3>1365</h3>
1367 1366
1368É disparado quando um arquivo `CLAUDE.md` ou `.claude/rules/*.md` é carregado no contexto. Este evento é disparado no início da sessão para arquivos carregados antecipadamente e novamente mais tarde quando arquivos são carregados sob demanda, por exemplo quando o Claude acessa um subdiretório que contém um `CLAUDE.md` aninhado ou quando regras condicionais com frontmatter `paths:` correspondem. O hook não suporta bloqueio nem controle de decisão. Ele é executado de forma assíncrona para fins de observabilidade.1367É disparado quando um arquivo `CLAUDE.md` ou `.claude/rules/*.md` é carregado no contexto. Este evento é disparado no início da sessão para arquivos carregados antecipadamente e novamente mais tarde quando arquivos são carregados de forma preguiçosa, por exemplo quando o Claude acessa um subdiretório que contém um `CLAUDE.md` aninhado ou quando regras condicionais com frontmatter `paths:` correspondem. O hook não suporta bloqueio nem controle de decisão. Ele é executado de forma assíncrona para fins de observabilidade.
1369 1368
1370Este evento não é disparado quando o Claude [lê `AGENTS.md` diretamente](/docs/pt/memory#agents-md) por meio da configuração **Project instructions**. Ele é disparado quando um `CLAUDE.md` importa seu `AGENTS.md`, com `load_reason` definido como `include`, como para qualquer outro arquivo importado, e quando `CLAUDE.md` é um link simbólico para ele, como um carregamento normal de `CLAUDE.md`.1369Este evento não é disparado quando o Claude [lê `AGENTS.md` diretamente](/docs/pt/memory#agents-md) por meio da configuração **Project instructions**. Ele é disparado quando um `CLAUDE.md` importa seu `AGENTS.md`, com `load_reason` definido como `include`, como para qualquer outro arquivo importado, e quando `CLAUDE.md` é um link simbólico para ele, como um carregamento normal de `CLAUDE.md`.
1371 1370
1372O matcher é avaliado contra `load_reason`. Por exemplo, use `"matcher": "session_start"` para disparar somente para arquivos carregados no início da sessão, ou `"matcher": "path_glob_match|nested_traversal"` para disparar somente para carregamentos tardios.1371O matcher é avaliado contra `load_reason`. Por exemplo, use `"matcher": "session_start"` para disparar apenas para arquivos carregados no início da sessão, ou `"matcher": "path_glob_match|nested_traversal"` para disparar apenas para carregamentos preguiçosos.
1373 1372
1374<h4 id="instructionsloaded-input">1373<h4 id="instructionsloaded-input">
1375 Entrada do InstructionsLoaded1374 Entrada do InstructionsLoaded
1381| :- | :- |1380| :- | :- |
1382| `file_path` | Caminho absoluto para o arquivo de instruções que foi carregado |1381| `file_path` | Caminho absoluto para o arquivo de instruções que foi carregado |
1383| `memory_type` | Escopo do arquivo: `"User"`, `"Project"`, `"Local"` ou `"Managed"` |1382| `memory_type` | Escopo do arquivo: `"User"`, `"Project"`, `"Local"` ou `"Managed"` |
1384| `load_reason` | Por que o arquivo foi carregado: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"` ou `"compact"`. O valor `"compact"` é disparado quando os arquivos de instruções são recarregados após um evento de compactação |1383| `load_reason` | Por que o arquivo foi carregado: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"` ou `"compact"`. O valor `"compact"` é disparado quando arquivos de instruções são recarregados após um evento de compactação |
1385| `globs` | Padrões glob de caminho do frontmatter `paths:` do arquivo, se houver. Presente somente para carregamentos `path_glob_match` |1384| `globs` | Padrões glob de caminho do frontmatter `paths:` do arquivo, se houver. Presente apenas para carregamentos `path_glob_match` |
1386| `trigger_file_path` | Caminho para o arquivo cujo acesso acionou este carregamento, para carregamentos tardios |1385| `trigger_file_path` | Caminho para o arquivo cujo acesso acionou este carregamento, para carregamentos preguiçosos |
1387| `parent_file_path` | Caminho para o arquivo de instruções pai que incluiu este, para carregamentos `include` |1386| `parent_file_path` | Caminho para o arquivo de instruções pai que incluiu este, para carregamentos `include` |
1388 1387
1389```json theme={null}1388```json theme={null}
1408 UserPromptSubmit1407 UserPromptSubmit
1409</h3>1408</h3>
1410 1409
1411É executado quando um prompt é enviado, antes que o Claude o processe. Isso permite1410É executado quando um prompt é enviado, antes de o Claude processá-lo. Isso permite
1412que você adicione contexto adicional com base no prompt/conversa, valide prompts ou1411adicionar contexto extra com base no prompt/conversa, validar prompts ou
1413bloqueie certos tipos de prompts.1412bloquear certos tipos de prompts.
1414 1413
1415Os hooks `UserPromptSubmit` não são disparados apenas em prompts que você digita. O Claude Code também os executa quando:1414Os hooks `UserPromptSubmit` não são disparados apenas em prompts que você digita. O Claude Code também os executa quando:
1416 1415
1418* Um [subagente em segundo plano](/docs/pt/sub-agents#run-subagents-in-foreground-or-background) reporta de volta à sessão que o iniciou1417* Um [subagente em segundo plano](/docs/pt/sub-agents#run-subagents-in-foreground-or-background) reporta de volta à sessão que o iniciou
1419* Uma [mensagem que outra sessão envia](/docs/pt/cross-session-messaging) chega à sua conversa principal1418* Uma [mensagem que outra sessão envia](/docs/pt/cross-session-messaging) chega à sua conversa principal
1420 1419
1421Os hooks `UserPromptSubmit` têm um timeout padrão de 30 segundos para os tipos `command`, `http` e `mcp_tool`, menor que o padrão de 600 segundos desses tipos na maioria dos outros eventos. Como este hook é executado antes de cada prompt e bloqueia o processamento do modelo até ser concluído, um hook travado paralisa a sessão. Se o seu hook precisar de mais tempo, defina o campo `timeout` na entrada do hook.1420Os hooks `UserPromptSubmit` têm um timeout padrão de 30 segundos para os tipos `command`, `http` e `mcp_tool`, menor que o padrão de 600 segundos desses tipos na maioria dos outros eventos. Como este hook é executado antes de cada prompt e bloqueia o processamento do modelo até terminar, um hook travado paralisa a sessão. Se seu hook precisar de mais tempo, defina o campo `timeout` na entrada do hook.
1422 1421
1423Exceto por um hook de comando que você executa com [`async: true`](#run-hooks-in-the-background), um hook `UserPromptSubmit` de comando, HTTP ou ferramenta MCP que atinge seu timeout é cancelado e sua saída, incluindo qualquer `additionalContext`, é descartada. O prompt ainda chega ao Claude sem esse contexto. A transcrição mostra um aviso nomeando o hook, o timeout que foi atingido e que a saída foi descartada.1422Exceto por um hook de comando que você executa com [`async: true`](#run-hooks-in-the-background), um hook `UserPromptSubmit` de comando, HTTP ou ferramenta MCP que atinge seu timeout é cancelado e sua saída, incluindo qualquer `additionalContext`, é descartada. O prompt ainda chega ao Claude sem esse contexto. A transcrição mostra um aviso com o nome do hook, o timeout que foi atingido e que a saída foi descartada.
1424 1423
1425Um [hook de callback do Agent SDK](/docs/pt/agent-sdk/hooks) em `UserPromptSubmit` que atinge seu timeout bloqueia o prompt com uma mensagem nomeando o hook e o timeout, porque um callback nesse ponto pode estar atuando como uma barreira de política que não deve falhar de forma aberta. A sessão continua. Antes da v2.1.208, um timeout de callback nesse evento encerrava o turno com um erro de execução.1424Um [hook de callback do Agent SDK](/docs/pt/agent-sdk/hooks) em `UserPromptSubmit` que atinge seu timeout bloqueia o prompt com uma mensagem que nomeia o hook e o timeout, porque um callback nesse ponto pode estar atuando como uma barreira de política que não deve falhar de forma permissiva. A sessão continua. Antes da v2.1.208, um timeout de callback nesse evento encerrava o turno com um erro de execução.
1426 1425
1427<h4 id="userpromptsubmit-input">1426<h4 id="userpromptsubmit-input">
1428 Entrada do UserPromptSubmit1427 Entrada do UserPromptSubmit
1429</h4>1428</h4>
1430 1429
1431Além dos [campos de entrada comuns](#common-input-fields), os hooks UserPromptSubmit recebem o campo `prompt` contendo o texto enviado. Conteúdo colado que foi recolhido em um espaço reservado `[Pasted text #N]` chega expandido no lugar. Em sessões em que o Claude Code [marca o texto colado para o Claude](/docs/pt/terminal-config#how-claude-treats-pasted-text), esse conteúdo expandido fica entre uma linha `<pasted_content id="…">` e uma linha `</pasted_content id="…">`, então leve essas linhas em conta se o seu hook analisar o prompt.1430Além dos [campos de entrada comuns](#common-input-fields), os hooks UserPromptSubmit recebem o campo `prompt` contendo o texto enviado. Conteúdo colado que foi recolhido em um espaço reservado `[Pasted text #N]` chega expandido no lugar. Em sessões em que o Claude Code [marca o texto colado para o Claude](/docs/pt/terminal-config#how-claude-treats-pasted-text), esse conteúdo expandido fica entre uma linha `<pasted_content id="…">` e uma linha `</pasted_content id="…">`, portanto leve essas linhas em conta se seu hook analisar o prompt.
1432 1431
1433Os hooks UserPromptSubmit também recebem `session_title` quando a sessão tem um título personalizado, com o mesmo significado do [campo `session_title` do SessionStart](#sessionstart-input).1432Os hooks UserPromptSubmit também recebem `session_title` quando a sessão tem um título personalizado, com o mesmo significado do [campo `session_title` do SessionStart](#sessionstart-input).
1434 1433
1449 1448
1450Os hooks `UserPromptSubmit` podem controlar se um prompt enviado é processado e adicionar contexto. Todos os [campos de saída JSON](#json-output) estão disponíveis.1449Os hooks `UserPromptSubmit` podem controlar se um prompt enviado é processado e adicionar contexto. Todos os [campos de saída JSON](#json-output) estão disponíveis.
1451 1450
1452Há duas formas de adicionar contexto à conversa com código de saída 0:1451Há duas maneiras de adicionar contexto à conversa com o código de saída 0:
1453 1452
1454* **Stdout de texto simples**: o Claude Code adiciona ao contexto do Claude o stdout que ele [trata como texto simples](#exit-code-0)1453* **Stdout em texto simples**: o Claude Code adiciona ao contexto do Claude o stdout que ele [trata como texto simples](#exit-code-0)
1455* **JSON com `additionalContext`**: use o formato JSON abaixo para ter mais controle. O campo `additionalContext` é adicionado como contexto1454* **JSON com `additionalContext`**: use o formato JSON abaixo para ter mais controle. O campo `additionalContext` é adicionado como contexto
1456 1455
1457Nenhum dos canais produz uma entrada visível na transcrição. O stdout simples e o valor de `additionalContext` são, cada um, injetados como um lembrete do sistema que começa com o nome do hook; o Claude lê ambos. Para confirmar a entrega, verifique o [log de depuração](#debug-hooks).1456Nenhum dos canais produz uma entrada visível na transcrição. O stdout simples e o valor de `additionalContext` são injetados, cada um, como um lembrete do sistema que começa com o nome do hook; o Claude lê ambos. Para confirmar a entrega, verifique o [log de depuração](#debug-hooks).
1458 1457
1459Para bloquear um prompt, retorne um objeto JSON com `decision` definido como `"block"`:1458Para bloquear um prompt, retorne um objeto JSON com `decision` definido como `"block"`:
1460 1459
1466| `sessionTitle` | Define o título da sessão. Use para nomear sessões automaticamente com base no conteúdo do prompt |1465| `sessionTitle` | Define o título da sessão. Use para nomear sessões automaticamente com base no conteúdo do prompt |
1467| `suppressOriginalPrompt` | Se `true` quando o hook bloqueia o prompt, deixa o texto do prompt fora da mensagem de bloqueio. Consulte [O que um prompt bloqueado deixa para trás](#what-a-blocked-prompt-leaves-behind) |1466| `suppressOriginalPrompt` | Se `true` quando o hook bloqueia o prompt, deixa o texto do prompt fora da mensagem de bloqueio. Consulte [O que um prompt bloqueado deixa para trás](#what-a-blocked-prompt-leaves-behind) |
1468 1467
1469Um hook que bloqueia saindo com 2 é encaminhado da mesma forma que `reason`: a mensagem de bloqueio mostra o texto do stderr ao usuário, e ele não é adicionado ao contexto.1468Um hook que bloqueia saindo com 2 é tratado da mesma forma que `reason`: a mensagem de bloqueio mostra o texto do stderr ao usuário, e ele não é adicionado ao contexto.
1470 1469
1471```json theme={null}1470```json theme={null}
1472{1471{
1485 O que um prompt bloqueado deixa para trás1484 O que um prompt bloqueado deixa para trás
1486</h4>1485</h4>
1487 1486
1488Um prompt bloqueado nunca chega ao Claude, mas seu texto não é removido de todos os lugares. Por padrão, a mensagem de bloqueio mostrada ao usuário termina com `Original prompt:` seguido do texto enviado, e o Claude Code grava essa mensagem no arquivo de transcrição da sessão em disco. Para omitir o texto da mensagem, imprima JSON com `"suppressOriginalPrompt": true` dentro de `hookSpecificOutput`. Isso funciona tanto se o hook bloquear com `decision: "block"` quanto saindo com 2.1487Um prompt bloqueado nunca chega ao Claude, mas seu texto não é removido de todos os lugares. Por padrão, a mensagem de bloqueio mostrada ao usuário termina com `Original prompt:` seguido do texto enviado, e o Claude Code grava essa mensagem no arquivo de transcrição da sessão no disco. Para deixar o texto fora da mensagem, imprima JSON com `"suppressOriginalPrompt": true` dentro de `hookSpecificOutput`. Isso funciona tanto quando o hook bloqueia com `decision: "block"` quanto saindo com 2.
1489 1488
1490`suppressOriginalPrompt` altera apenas a mensagem de bloqueio. O texto enviado ainda pode aparecer em arquivos locais, como a transcrição da sessão e seu histórico de prompts, então um hook de bloqueio não é uma forma de manter um segredo fora do disco. Para limitar ou remover esses arquivos, consulte [Armazenamento em texto simples](/docs/pt/claude-directory#plaintext-storage) e [Limpar dados locais](/docs/pt/claude-directory#clear-local-data).1489`suppressOriginalPrompt` altera apenas a mensagem de bloqueio. O texto enviado ainda pode aparecer em arquivos locais, como a transcrição da sessão e seu histórico de prompts, portanto um hook de bloqueio não é uma forma de manter um segredo fora do disco. Para limitar ou remover esses arquivos, consulte [Armazenamento em texto simples](/docs/pt/claude-directory#plaintext-storage) e [Limpar dados locais](/docs/pt/claude-directory#clear-local-data).
1491 1490
1492<h3 id="userpromptexpansion">1491<h3 id="userpromptexpansion">
1493 UserPromptExpansion1492 UserPromptExpansion
1494</h3>1493</h3>
1495 1494
1496É executado quando um comando digitado pelo usuário se expande em um prompt antes de chegar ao Claude. Use isso para impedir que comandos específicos sejam invocados diretamente, injetar contexto para uma skill específica ou registrar em log quais comandos os usuários invocam. Por exemplo, um hook que corresponde a `deploy` pode bloquear `/deploy` a menos que um arquivo de aprovação esteja presente, ou um hook que corresponde a uma skill de revisão pode anexar a checklist de revisão da equipe como `additionalContext`.1495É executado quando um comando digitado pelo usuário é expandido em um prompt antes de chegar ao Claude. Use-o para impedir que comandos específicos sejam invocados diretamente, injetar contexto para uma skill específica ou registrar em log quais comandos os usuários invocam. Por exemplo, um hook que corresponde a `deploy` pode bloquear `/deploy` a menos que um arquivo de aprovação esteja presente, ou um hook que corresponde a uma skill de revisão pode anexar a checklist de revisão da equipe como `additionalContext`.
1497 1496
1498Este evento cobre o caminho que o `PreToolUse` não cobre: um hook `PreToolUse` que corresponde à ferramenta `Skill` é disparado somente quando o Claude chama a ferramenta, mas digitar `/skillname` diretamente contorna o `PreToolUse`. O `UserPromptExpansion` é disparado nesse caminho direto.1497Este evento cobre o caminho que o `PreToolUse` não cobre: um hook `PreToolUse` que corresponde à ferramenta `Skill` é disparado apenas quando o Claude chama a ferramenta, mas digitar `/skillname` diretamente contorna o `PreToolUse`. O `UserPromptExpansion` é disparado nesse caminho direto.
1499 1498
1500Faz a correspondência em `command_name`. Deixe o matcher vazio para disparar em todo comando do tipo prompt.1499Faz a correspondência com `command_name`. Deixe o matcher vazio para disparar em todo comando do tipo prompt.
1501 1500
1502<h4 id="userpromptexpansion-input">1501<h4 id="userpromptexpansion-input">
1503 Entrada do UserPromptExpansion1502 Entrada do UserPromptExpansion
1504</h4>1503</h4>
1505 1504
1506Além dos [campos de entrada comuns](#common-input-fields), os hooks UserPromptExpansion recebem `expansion_type`, `command_name`, `command_args`, `command_source` e a string `prompt` original. O campo `expansion_type` é `slash_command` para skills e comandos personalizados, ou `mcp_prompt` para prompts de servidor MCP.1505Além dos [campos de entrada comuns](#common-input-fields), os hooks UserPromptExpansion recebem `expansion_type`, `command_name`, `command_args`, `command_source` e a string `prompt` original. O campo `expansion_type` é `slash_command` para skills e comandos personalizados, ou `mcp_prompt` para prompts de servidores MCP.
1507 1506
1508```json theme={null}1507```json theme={null}
1509{1508{
1528 1527
1529| Campo | Descrição |1528| Campo | Descrição |
1530| :- | :- |1529| :- | :- |
1531| `decision` | `"block"` impede que o comando se expanda. Omita para permitir que ele prossiga |1530| `decision` | `"block"` impede que o comando seja expandido. Omita para permitir que ele prossiga |
1532| `reason` | Mostrado ao usuário quando `decision` é `"block"` |1531| `reason` | Mostrado ao usuário quando `decision` é `"block"` |
1533| `additionalContext` | String adicionada ao contexto do Claude junto com o prompt expandido. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |1532| `additionalContext` | String adicionada ao contexto do Claude junto com o prompt expandido. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |
1534 1533
1535Um hook que bloqueia saindo com 2 é encaminhado da mesma forma que `reason`: a mensagem de bloqueio mostra o texto do stderr ao usuário.1534Um hook que bloqueia saindo com 2 é tratado da mesma forma que `reason`: a mensagem de bloqueio mostra o texto do stderr ao usuário.
1536 1535
1537```json theme={null}1536```json theme={null}
1538{1537{
1549 MessageDisplay1548 MessageDisplay
1550</h3>1549</h3>
1551 1550
1552É executado enquanto uma mensagem do assistente é transmitida para a tela. O Claude Code exibe a mensagem em incrementos: cada vez que um lote de linhas recém-concluídas está pronto para renderização, o hook é executado uma vez com essas linhas e o Claude Code renderiza o texto de substituição do hook no lugar delas. Uma mensagem longa produz várias chamadas; uma mensagem curta pode produzir apenas uma.1551É executado enquanto uma mensagem do assistente é transmitida para a tela. O Claude Code exibe a mensagem em incrementos: cada vez que um lote de linhas recém-concluídas está pronto para ser renderizado, o hook é executado uma vez com essas linhas e o Claude Code renderiza o texto de substituição do hook no lugar delas. Uma mensagem longa produz várias chamadas; uma mensagem curta pode produzir apenas uma.
1553 1552
1554Use o MessageDisplay para:1553Use o MessageDisplay para:
1555 1554
1556* remover markdown para uma exibição mínima1555* remover markdown para uma exibição minimalista
1557* transformar o texto que uma aplicação do Agent SDK mostra aos seus usuários1556* transformar o texto que uma aplicação do Agent SDK mostra aos seus usuários
1558* ocultar chaves de API ou hostnames internos das respostas do Claude1557* ocultar chaves de API ou nomes de host internos das respostas do Claude
1559 1558
1560O Claude Code retém cada lote até que seu hook retorne, então mantenha o hook rápido. Se o hook falhar ou atingir o timeout, o Claude Code exibe o texto original. O timeout padrão para este evento é de 10 segundos; se o seu hook precisar de mais tempo, defina o campo `timeout` na entrada do hook.1559O Claude Code retém cada lote até que seu hook retorne, portanto mantenha o hook rápido. Se o hook falhar ou atingir o timeout, o Claude Code exibe o texto original. O timeout padrão para este evento é de 10 segundos; se seu hook precisar de mais tempo, defina o campo `timeout` na entrada do hook.
1561 1560
1562O MessageDisplay serve apenas para exibição: o texto de substituição altera somente o que é renderizado na tela. A transcrição e o que o Claude vê mantêm o texto original, então o Claude nunca vê a substituição, e o modo verbose mostra o original. O hook recebe apenas o texto das mensagens do assistente, então os resultados de ferramentas e o texto que você digita são renderizados sem alteração.1561O MessageDisplay é apenas de exibição: o texto de substituição altera somente o que é renderizado na tela. A transcrição e o que o Claude vê mantêm o texto original, então o Claude nunca vê a substituição, e o modo verboso mostra o original. O hook recebe apenas o texto das mensagens do assistente, portanto resultados de ferramentas e o texto que você digita são renderizados sem alterações.
1563 1562
1564O MessageDisplay não suporta matchers e é disparado para toda mensagem do assistente que transmite texto; mensagens sem texto, como respostas que contêm apenas chamadas de ferramenta, não o acionam.1563O MessageDisplay não suporta matchers e é disparado para toda mensagem do assistente que transmite texto; mensagens sem texto, como respostas que contêm apenas chamadas de ferramenta, não o acionam.
1565 1564
1566Em execuções não interativas, incluindo consultas do Agent SDK e `claude -p`, o MessageDisplay é executado uma vez por mensagem do assistente em vez de uma vez por lote de linhas. A chamada única chega depois que a mensagem é concluída e carrega o texto completo da mensagem: `index` é `0`, `final` é `true` e `delta` contém a mensagem inteira. Um hook que coleta o texto de `delta` de cada mensagem recebe o mesmo texto total em ambos os modos.1565Em execuções não interativas, incluindo consultas do Agent SDK e `claude -p`, o MessageDisplay é executado uma vez por mensagem do assistente em vez de uma vez por lote de linhas. A chamada única chega depois que a mensagem é concluída e carrega o texto completo da mensagem: `index` é `0`, `final` é `true` e `delta` contém a mensagem inteira. Um hook que coleta o texto de `delta` para cada mensagem recebe o mesmo texto total em ambos os modos.
1567 1566
1568<h4 id="messagedisplay-input">1567<h4 id="messagedisplay-input">
1569 Entrada do MessageDisplay1568 Entrada do MessageDisplay
1570</h4>1569</h4>
1571 1570
1572Além dos [campos de entrada comuns](#common-input-fields), os hooks MessageDisplay recebem identificadores do turno e da mensagem, a posição desta chamada dentro da mensagem e o novo texto em `delta`. Os limites dos lotes dependem de como o texto é transmitido, então use `index` e `final` para acompanhar o progresso de uma mensagem em vez de esperar que as linhas sejam agrupadas de uma forma específica.1571Além dos [campos de entrada comuns](#common-input-fields), os hooks MessageDisplay recebem identificadores do turno e da mensagem, a posição desta chamada dentro da mensagem e o novo texto em `delta`. Os limites dos lotes dependem de como o texto é transmitido, portanto use `index` e `final` para acompanhar o progresso em uma mensagem, em vez de esperar que as linhas sejam agrupadas de uma forma específica.
1573 1572
1574| Campo | Descrição |1573| Campo | Descrição |
1575| :- | :- |1574| :- | :- |
1576| `turn_id` | UUID do turno atual |1575| `turn_id` | UUID do turno atual |
1577| `message_id` | UUID da mensagem do assistente sendo exibida. Estável em todos os lotes da mesma mensagem. Este não é o id `msg_…` da API, então não pode ser correlacionado com os ids de mensagens da transcrição |1576| `message_id` | UUID da mensagem do assistente sendo exibida. Estável em todos os lotes da mesma mensagem. Este não é o id `msg_…` da API, portanto não pode ser correlacionado com os ids de mensagem da transcrição |
1578| `index` | Índice, começando em zero, deste lote dentro da mensagem |1577| `index` | Índice baseado em zero deste lote dentro da mensagem |
1579| `final` | `true` no último lote da mensagem. Cada mensagem tem exatamente um lote final |1578| `final` | `true` no último lote da mensagem. Cada mensagem tem exatamente um lote final |
1580| `delta` | As linhas recém-concluídas desde o lote anterior, incluindo as quebras de linha finais. Sempre linhas inteiras, exceto o lote final, que pode terminar no meio de uma linha. Em execuções interativas, o delta do lote final fica vazio quando a mensagem termina com uma quebra de linha, então trate `final`, e não um delta não vazio, como o sinal de fim da mensagem. Em execuções do Agent SDK e de `claude -p`, a chamada única carrega a mensagem inteira |1579| `delta` | As linhas recém-concluídas desde o lote anterior, incluindo as quebras de linha finais. Sempre linhas inteiras, exceto o lote final, que pode terminar no meio de uma linha. Em execuções interativas, o delta do lote final fica vazio quando a mensagem termina com uma quebra de linha, portanto trate `final`, e não um delta não vazio, como o sinal de fim de mensagem. Em execuções do Agent SDK e `claude -p`, a chamada única carrega a mensagem inteira |
1581 1580
1582```json theme={null}1581```json theme={null}
1583{1582{
1605 1604
1606Os hooks MessageDisplay não têm controle de decisão. Eles não podem bloquear a mensagem nem alterar o que é armazenado na transcrição ou enviado ao Claude. O Claude Code age com base em `displayContent` da saída JSON deles e descarta `systemMessage` e `continue`.1605Os hooks MessageDisplay não têm controle de decisão. Eles não podem bloquear a mensagem nem alterar o que é armazenado na transcrição ou enviado ao Claude. O Claude Code age com base em `displayContent` da saída JSON deles e descarta `systemMessage` e `continue`.
1607 1606
1608Este exemplo remove a formatação markdown das respostas do Claude para uma exibição em texto simples. O script lê cada lote do stdin, remove os marcadores de negrito e os acentos graves de código inline de `delta` e retorna o resultado como `displayContent`.1607Este exemplo remove a formatação markdown das respostas do Claude para uma exibição em texto simples. O script lê cada lote do stdin, remove os marcadores de negrito e as crases de código inline de `delta` e retorna o resultado como `displayContent`.
1609 1608
1610<Tabs>1609<Tabs>
1611 <Tab title="macOS/Linux">1610 <Tab title="macOS/Linux">
1681 </Tab>1680 </Tab>
1682</Tabs>1681</Tabs>
1683 1682
1684Lotes sem markdown passam sem alteração. Se o script falhar, por exemplo porque o `jq` não está instalado, o Claude Code exibe o texto original e registra a falha somente na [saída de depuração](#debug-hooks), não na sessão.1683Lotes sem markdown passam sem alterações. Se o script falhar, por exemplo porque o `jq` não está instalado, o Claude Code exibe o texto original e registra a falha apenas na [saída de depuração](#debug-hooks), não na sessão.
1685 1684
1686<h3 id="pretooluse">1685<h3 id="pretooluse">
1687 PreToolUse1686 PreToolUse
1688</h3>1687</h3>
1689 1688
1690É executado depois que o Claude cria os parâmetros da ferramenta e antes de processar a chamada de ferramenta. Faz a correspondência com qualquer nome de ferramenta exceto `EndConversation`: ferramentas integradas como `Bash`, `PowerShell`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `Workflow`, `WebFetch`, `WebSearch`, `AskUserQuestion` e `ExitPlanMode`, e quaisquer [nomes de ferramentas MCP](#match-mcp-tools).1689É executado depois que o Claude cria os parâmetros da ferramenta e antes de processar a chamada de ferramenta. Faz correspondência com qualquer nome de ferramenta, exceto `EndConversation`: ferramentas integradas como `Bash`, `PowerShell`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `Workflow`, `WebFetch`, `WebSearch`, `AskUserQuestion` e `ExitPlanMode`, e quaisquer [nomes de ferramentas MCP](#match-mcp-tools).
1691 1690
1692Para executar um hook quando um arquivo específico muda no disco, independentemente de quem o gravou, use o [FileChanged](#filechanged) em vez de fazer a correspondência de ferramentas de edição de arquivos pelo nome. Diferentemente do PreToolUse, o Claude Code executa os hooks FileChanged após a alteração, e eles não têm controle de decisão, então não podem bloquear a gravação.1691Para executar um hook quando um arquivo específico muda no disco, independentemente de quem o gravou, use [FileChanged](#filechanged) em vez de corresponder às ferramentas de edição de arquivos pelo nome. Ao contrário do PreToolUse, o Claude Code executa os hooks FileChanged depois da alteração, e eles não têm controle de decisão, portanto não podem bloquear a gravação.
1693 1692
1694<Warning>1693<Warning>
1695 O PreToolUse é executado somente quando o Claude chama uma ferramenta. Os arquivos que você [referencia com `@` no seu prompt](/docs/pt/common-workflows#reference-files-and-directories) são adicionados sem nenhuma chamada de ferramenta: o Claude Code insere o conteúdo deles ao montar o prompt, então nenhum hook PreToolUse é disparado para eles, incluindo hooks que correspondem a `Read`. Para impedir caminhos específicos em referências `@`, use uma [regra de negação de `Read`](/docs/pt/permissions#read-and-edit).1694 O PreToolUse é executado apenas quando o Claude chama uma ferramenta. Arquivos que você [referencia com `@` no seu prompt](/docs/pt/common-workflows#reference-files-and-directories) são adicionados sem nenhuma chamada de ferramenta: o Claude Code insere o conteúdo deles ao montar o prompt, portanto nenhum hook PreToolUse é disparado para eles, incluindo hooks que correspondem a `Read`. Para bloquear caminhos específicos de referências `@`, use uma [regra de negação de `Read`](/docs/pt/permissions#read-and-edit) em vez disso.
1696 1695
1697 O PreToolUse também não é disparado para [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior).1696 O PreToolUse também não é disparado para [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior).
1698</Warning>1697</Warning>
1699 1698
1700Use o [controle de decisão do PreToolUse](#pretooluse-decision-control) para permitir, negar, perguntar ou adiar a chamada de ferramenta.1699Use o [controle de decisão do PreToolUse](#pretooluse-decision-control) para permitir, negar, pedir confirmação ou adiar a chamada de ferramenta.
1701 1700
1702Um [hook de callback do Agent SDK](/docs/pt/agent-sdk/hooks) em `PreToolUse` que excede seu timeout bloqueia a chamada de ferramenta, e o Claude recebe um resultado de erro nomeando o timeout. Uma negação explícita retornada por outro hook ainda tem precedência.1701Um [hook de callback do Agent SDK](/docs/pt/agent-sdk/hooks) em `PreToolUse` que excede seu timeout bloqueia a chamada de ferramenta, e o Claude recebe um resultado de erro que nomeia o timeout. Uma negação explícita retornada por outro hook ainda tem precedência.
1703 1702
1704<h4 id="pretooluse-input">1703<h4 id="pretooluse-input">
1705 Entrada do PreToolUse1704 Entrada do PreToolUse
1707 1706
1708Além dos [campos de entrada comuns](#common-input-fields), os hooks PreToolUse recebem `tool_name`, `tool_input` e `tool_use_id`.1707Além dos [campos de entrada comuns](#common-input-fields), os hooks PreToolUse recebem `tool_name`, `tool_input` e `tool_use_id`.
1709 1708
1710Para uma [ferramenta MCP](#match-mcp-tools), a entrada também carrega `mcp_server`, um objeto com o `name` do servidor e um `source` que informa de onde veio a definição do servidor. Os valores de `source` incluem `plugin`, `sdk` e escopos de configuração como `user` e `project`. [`McpServerProvenance`](/docs/pt/agent-sdk/typescript#mcpserverprovenance) na referência do Agent SDK lista todos eles e explica como tratar um que você não reconhece. Baseie as decisões de confiança em `source`, e não em `name` ou no prefixo de nome de ferramenta `mcp__<server>__`. O campo `mcp_server` exige o Claude Code v2.1.274 ou posterior.1709Para uma [ferramenta MCP](#match-mcp-tools), a entrada também carrega `mcp_server`, um objeto com o `name` do servidor e um `source` que indica de onde veio a definição do servidor. Os valores de `source` incluem `plugin`, `sdk` e escopos de configuração como `user` e `project`. [`McpServerProvenance`](/docs/pt/agent-sdk/typescript#mcpserverprovenance) na referência do Agent SDK lista todos eles e explica como tratar um que você não reconhece. Baseie decisões de confiança em `source`, e não em `name` ou no prefixo de nome de ferramenta `mcp__<server>__`. O campo `mcp_server` exige o Claude Code v2.1.274 ou posterior.
1711 1710
1712Para as ferramentas de arquivo `Write`, `Edit` e `Read`, `tool_input.file_path` é sempre absoluto:1711Para as ferramentas de arquivo `Write`, `Edit` e `Read`, `tool_input.file_path` é sempre absoluto:
1713 1712
1714* O Claude Code expande `~` e caminhos relativos antes de os hooks serem executados, então um hook que faz correspondência em caminhos não pode ser contornado via `~` ou uma forma relativa de escrever o mesmo caminho1713* O Claude Code expande `~` e caminhos relativos antes de os hooks serem executados, portanto um hook que faz correspondência por caminhos não pode ser contornado via `~` ou por uma grafia relativa do mesmo caminho
1715* No Windows, o caminho chega com separadores de barra invertida, mesmo quando seu hook é executado no Git Bash, onde `$PWD` se parece com `/c/project`1714* No Windows, o caminho chega com separadores de barra invertida, mesmo quando seu hook é executado no Git Bash, onde `$PWD` se parece com `/c/project`
1716* Uma comparação escrita com barras normais, como uma verificação de `/src/`, nunca corresponde a um caminho com barras invertidas, e a chamada de ferramenta prossegue como se o hook não tivesse nada a bloquear1715* Uma comparação escrita com barras normais, como uma verificação de `/src/`, nunca corresponde a um caminho com barras invertidas, e a chamada de ferramenta prossegue como se o hook não tivesse nada a bloquear
1717* Normalize os separadores antes de comparar: `FILE_PATH="${FILE_PATH//\\//}"` no Bash, ou `file_path.replace("\\", "/")` no Python, e então faça a correspondência de um segmento de caminho como `/src/` em vez de ancorar com `^`, já que o caminho é absoluto1716* Normalize os separadores antes de comparar: `FILE_PATH="${FILE_PATH//\\//}"` no Bash, ou `file_path.replace("\\", "/")` no Python, e então faça a correspondência com um segmento de caminho como `/src/` em vez de ancorar com `^`, já que o caminho é absoluto
1718 1717
1719Uma chamada `Write` no Windows entrega:1718Uma chamada `Write` no Windows entrega:
1720 1719
1747| `timeout` | number | `120000` | Timeout opcional em milissegundos. Valores acima do [máximo](/docs/pt/tools-reference#bash-tool-behavior) são reduzidos ao máximo em vez de rejeitados |1746| `timeout` | number | `120000` | Timeout opcional em milissegundos. Valores acima do [máximo](/docs/pt/tools-reference#bash-tool-behavior) são reduzidos ao máximo em vez de rejeitados |
1748| `run_in_background` | boolean | `false` | Se o comando deve ser executado em segundo plano |1747| `run_in_background` | boolean | `false` | Se o comando deve ser executado em segundo plano |
1749 1748
1750Quando um comando Bash altera arquivos em um repositório Git, o Claude Code pode registrar o que mudou. Ele registra as alterações em todos os modos de permissão quando a configuração [`bashEditDiffEnabled`](/docs/pt/settings-reference#basheditdiffenabled) ativa o registro; a entrada dessa configuração informa quais arquivos podem defini-la. Caso contrário, ele as registra somente no modo auto e no modo `bypassPermissions`, e somente quando o Claude Code orienta o Claude a editar arquivos por meio do Bash. Defina `bashEditDiffEnabled` como `false` para desativar o registro. Comandos em segundo plano e comandos somente leitura não carregam diff.1749Quando um comando Bash altera arquivos em um repositório Git, o Claude Code pode registrar o que mudou. Ele registra as alterações em todos os modos de permissão quando a configuração [`bashEditDiffEnabled`](/docs/pt/settings-reference#basheditdiffenabled) ativa o registro; a entrada dessa configuração indica quais arquivos podem defini-la. Caso contrário, ele as registra apenas no modo auto e no modo `bypassPermissions`, e somente quando o Claude Code orienta o Claude a editar arquivos por meio do Bash. Defina `bashEditDiffEnabled` como `false` para desativar o registro. Comandos em segundo plano e comandos somente leitura não carregam diff.
1751 1750
1752Seu [hook PostToolUse](#posttooluse) então recebe os arquivos alterados em `tool_response.bashEditDiff`. A lista cobre o que mudou no repositório enquanto o comando era executado. Arquivos que o Git ignora e arquivos em submódulos não são listados. Exige o Claude Code v2.1.269 ou posterior.1751Seu [hook PostToolUse](#posttooluse) então recebe os arquivos alterados em `tool_response.bashEditDiff`. A lista cobre o que mudou no repositório enquanto o comando era executado. Arquivos que o Git ignora e arquivos em submódulos não são listados. Exige o Claude Code v2.1.269 ou posterior.
1753 1752
1754<Note>1753<Note>
1755 A lista é de melhor esforço e está em beta público. O Claude Code pode deixar de detectar uma alteração, incluir um arquivo que outro processo alterou ao mesmo tempo ou parar em seus limites de tamanho. O formato do campo pode mudar. Use a lista para encontrar o que revisar, não para impor uma política.1754 A lista é de melhor esforço e está em beta público. O Claude Code pode deixar passar uma alteração, incluir um arquivo que outro processo alterou ao mesmo tempo ou parar em seus limites de tamanho. O formato do campo pode mudar. Use a lista para descobrir o que revisar, não para impor uma política.
1756</Note>1755</Note>
1757 1756
1758`changedFiles` e `files` listam o que o comando alterou; os campos restantes informam quão completa e quão confiável é essa lista.1757`changedFiles` e `files` listam o que o comando alterou; os demais campos indicam quão completa e quão confiável essa lista é.
1759 1758
1760| Campo | Tipo | Exemplo | Descrição |1759| Campo | Tipo | Exemplo | Descrição |
1761| :- | :- | :- | :- |1760| :- | :- | :- | :- |
1783| `timeout` | number | `120000` | Timeout opcional em milissegundos |1782| `timeout` | number | `120000` | Timeout opcional em milissegundos |
1784| `run_in_background` | boolean | `false` | Se o comando deve ser executado em segundo plano |1783| `run_in_background` | boolean | `false` | Se o comando deve ser executado em segundo plano |
1785 1784
1786Use `Bash|PowerShell` como matcher em hooks que inspecionam comandos de shell, para que cubram ambas as ferramentas:1785Use `Bash|PowerShell` como matcher em hooks que inspecionam comandos de shell, para que eles cubram ambas as ferramentas:
1787 1786
1788* No Windows, onde quer que a ferramenta PowerShell esteja habilitada, o Claude trata o PowerShell como o shell principal e encaminha os comandos de shell por meio dele.1787* No Windows, sempre que a ferramenta PowerShell estiver habilitada, o Claude trata o PowerShell como o shell principal e encaminha os comandos de shell por ele.
1789* No Windows sem Git Bash, a ferramenta é habilitada automaticamente e o Claude Code não registra a ferramenta Bash.1788* No Windows sem Git Bash, a ferramenta é habilitada automaticamente e o Claude Code não registra a ferramenta Bash.
1790* Um hook que corresponde apenas a `Bash` nunca é disparado nesse caso.1789* Um hook que corresponde apenas a `Bash` nunca é disparado nesse caso.
1791 1790
1834| Campo | Tipo | Exemplo | Descrição |1833| Campo | Tipo | Exemplo | Descrição |
1835| :- | :- | :- | :- |1834| :- | :- | :- | :- |
1836| `pattern` | string | `"**/*.ts"` | Padrão glob com o qual os arquivos serão comparados |1835| `pattern` | string | `"**/*.ts"` | Padrão glob com o qual os arquivos serão comparados |
1837| `path` | string | `"/path/to/dir"` | Diretório opcional no qual pesquisar. O padrão é o diretório de trabalho atual |1836| `path` | string | `"/path/to/dir"` | Diretório opcional onde pesquisar. O padrão é o diretório de trabalho atual |
1838 1837
1839<h5 id="grep">1838<h5 id="grep">
1840 Grep1839 Grep
1845| Campo | Tipo | Exemplo | Descrição |1844| Campo | Tipo | Exemplo | Descrição |
1846| :- | :- | :- | :- |1845| :- | :- | :- | :- |
1847| `pattern` | string | `"TODO.*fix"` | Padrão de expressão regular a ser pesquisado |1846| `pattern` | string | `"TODO.*fix"` | Padrão de expressão regular a ser pesquisado |
1848| `path` | string | `"/path/to/dir"` | Arquivo ou diretório opcional no qual pesquisar |1847| `path` | string | `"/path/to/dir"` | Arquivo ou diretório opcional onde pesquisar |
1849| `glob` | string | `"*.ts"` | Padrão glob opcional para filtrar arquivos |1848| `glob` | string | `"*.ts"` | Padrão glob opcional para filtrar arquivos |
1850| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"` ou `"count"`. O padrão é `"files_with_matches"` |1849| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"` ou `"count"`. O padrão é `"files_with_matches"` |
1851| `-i` | boolean | `true` | Pesquisa sem diferenciar maiúsculas de minúsculas |1850| `-i` | boolean | `true` | Pesquisa sem diferenciar maiúsculas de minúsculas |
1852| `multiline` | boolean | `false` | Habilita a correspondência em várias linhas |1851| `multiline` | boolean | `false` | Habilita correspondência em várias linhas |
1853 1852
1854<h5 id="webfetch">1853<h5 id="webfetch">
1855 WebFetch1854 WebFetch
1859 1858
1860| Campo | Tipo | Exemplo | Descrição |1859| Campo | Tipo | Exemplo | Descrição |
1861| :- | :- | :- | :- |1860| :- | :- | :- | :- |
1862| `url` | string | `"https://example.com/api"` | URL da qual buscar o conteúdo |1861| `url` | string | `"https://example.com/api"` | URL de onde buscar o conteúdo |
1863| `prompt` | string | `"Extract the API endpoints"` | Prompt a ser executado sobre o conteúdo buscado |1862| `prompt` | string | `"Extract the API endpoints"` | Prompt a ser executado sobre o conteúdo buscado |
1864 1863
1865<h5 id="websearch">1864<h5 id="websearch">
1871| Campo | Tipo | Exemplo | Descrição |1870| Campo | Tipo | Exemplo | Descrição |
1872| :- | :- | :- | :- |1871| :- | :- | :- | :- |
1873| `query` | string | `"react hooks best practices"` | Consulta de pesquisa |1872| `query` | string | `"react hooks best practices"` | Consulta de pesquisa |
1874| `allowed_domains` | array | `["docs.example.com"]` | Opcional: incluir somente resultados destes domínios |1873| `allowed_domains` | array | `["docs.example.com"]` | Opcional: incluir apenas resultados destes domínios |
1875| `blocked_domains` | array | `["spam.example.com"]` | Opcional: excluir resultados destes domínios |1874| `blocked_domains` | array | `["spam.example.com"]` | Opcional: excluir resultados destes domínios |
1876 1875
1877<h5 id="agent">1876<h5 id="agent">
1891 1890
1892| Campo | Tipo | Exemplo | Descrição |1891| Campo | Tipo | Exemplo | Descrição |
1893| :- | :- | :- | :- |1892| :- | :- | :- | :- |
1894| `status` | string | `"completed"` | `"completed"` para subagentes em primeiro plano, `"async_launched"` para subagentes em segundo plano. Os subagentes são executados em segundo plano por padrão, então uma chamada Agent que omite `run_in_background` também produz `"async_launched"` |1893| `status` | string | `"completed"` | `"completed"` para subagentes em primeiro plano, `"async_launched"` para subagentes em segundo plano. Subagentes são executados em segundo plano por padrão, portanto uma chamada Agent que omite `run_in_background` também produz `"async_launched"` |
1895| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificador da execução do subagente |1894| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificador da execução do subagente |
1896| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | Os blocos de texto finais do subagente ou, para um subagente cujo relatório passa por `SubagentHandback`, uma nota curta sobre essa entrega no lugar deles |1895| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | Os blocos de texto finais do subagente ou, para um subagente cujo relatório passa por `SubagentHandback`, uma nota curta sobre essa entrega no lugar deles |
1897| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modelo com o qual o subagente começou, que pode ser diferente do modelo solicitado |1896| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modelo com o qual o subagente começou, que pode ser diferente do modelo solicitado |
1898| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Modelos usados em ordem, com repetições consecutivas recolhidas; definido somente quando o modelo foi trocado no meio da execução. Exige o Claude Code v2.1.212 ou posterior |1897| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Modelos usados em ordem, com repetições consecutivas condensadas; definido apenas quando o modelo foi trocado no meio da execução. Exige o Claude Code v2.1.212 ou posterior |
1899| `totalTokens` | number | `12450` | Contagem de tokens da requisição final de API do subagente: tokens de entrada, de saída e de cache combinados. Não é um total de toda a execução |1898| `totalTokens` | number | `12450` | Contagem de tokens da requisição final à API do subagente: tokens de entrada, saída e cache combinados. Isso não é um total de toda a execução |
1900| `totalDurationMs` | number | `48211` | Duração em tempo real da execução do subagente |1899| `totalDurationMs` | number | `48211` | Duração em tempo real da execução do subagente |
1901| `totalToolUseCount` | number | `7` | Contagem de chamadas de ferramenta feitas pelo subagente |1900| `totalToolUseCount` | number | `7` | Contagem de chamadas de ferramenta que o subagente fez |
1902| `usage` | object | `{"input_tokens": 8320, ...}` | Detalhamento de tokens por tipo da requisição final de API: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |1901| `usage` | object | `{"input_tokens": 8320, ...}` | Detalhamento de tokens por tipo da requisição final à API: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |
1903 1902
1904No Claude Code v2.1.271 ou posterior, um subagente que é executado com a ferramenta [`SubagentHandback`](/docs/pt/tools-reference), que o Claude Code fornece no [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), entrega seu relatório por meio dessa ferramenta em vez de retorná-lo como texto. O campo `content` do seu resultado `completed` então carrega uma nota curta sobre essa entrega em vez do próprio relatório. Para ler o relatório, faça a correspondência de um hook `PreToolUse` ou `PostToolUse` em `SubagentHandback` e leia `tool_input.message`.1903No Claude Code v2.1.271 ou posterior, um subagente executado com a ferramenta [`SubagentHandback`](/docs/pt/tools-reference), que o Claude Code fornece no [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), entrega seu relatório por meio dessa ferramenta em vez de retorná-lo como texto. O campo `content` do seu resultado `completed` então carrega uma nota curta sobre essa entrega em vez do próprio relatório. Para ler o relatório, configure um hook `PreToolUse` ou `PostToolUse` com matcher em `SubagentHandback` e leia `tool_input.message`.
1905 1904
1906Para subagentes em segundo plano, a ferramenta retorna quando a tarefa passa para o segundo plano, então `tool_response` não carrega campos de uso: uma inicialização em segundo plano retorna imediatamente, e uma tarefa em primeiro plano que o Claude Code move para o segundo plano no meio da execução retorna nessa transição. Ela tem `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile` e `resolvedModel`.1905Para subagentes em segundo plano, a ferramenta retorna quando a tarefa passa para o segundo plano, portanto `tool_response` não carrega campos de uso: uma inicialização em segundo plano retorna imediatamente, e uma tarefa em primeiro plano que o Claude Code move para o segundo plano no meio da execução retorna nessa transição. Ela tem `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile` e `resolvedModel`.
1907 1906
1908Em uma resposta `completed`, `resolvedModel` nomeia o modelo com o qual o subagente começou, que pode ser diferente do valor de `model` em `tool_input`, como quando `availableModels` ou outra substituição se aplica. Em uma resposta `async_launched`, `resolvedModel` nomeia o modelo em uso quando o agente passou para o segundo plano, de modo que uma troca que ocorreu antes disso é refletida ali. `modelsUsed` e o comportamento de `resolvedModel` no momento da passagem para o segundo plano exigem o Claude Code v2.1.212 ou posterior.1907Em uma resposta `completed`, `resolvedModel` nomeia o modelo com o qual o subagente começou, que pode ser diferente do valor de `model` em `tool_input`, como quando `availableModels` ou outra substituição se aplica. Em uma resposta `async_launched`, `resolvedModel` nomeia o modelo em uso quando o agente passou para o segundo plano, de modo que uma troca ocorrida antes disso é refletida ali. `modelsUsed` e o comportamento de `resolvedModel` no momento da passagem para segundo plano exigem o Claude Code v2.1.212 ou posterior.
1909 1908
1910<a id="askuserquestion" />1909<a id="askuserquestion" />
1911 1910
1917 1916
1918| Campo | Tipo | Exemplo | Descrição |1917| Campo | Tipo | Exemplo | Descrição |
1919| :- | :- | :- | :- |1918| :- | :- | :- | :- |
1920| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}], "multiSelect": false}]` | Perguntas a serem apresentadas, cada uma com uma string `question`, um `header` curto, um array `options` e uma flag `multiSelect` opcional |1919| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}], "multiSelect": false}]` | Perguntas a apresentar, cada uma com uma string `question`, um `header` curto, um array `options` e uma flag `multiSelect` opcional |
1921| `answers` | object | `{"Which framework?": "React"}` | Opcional. Mapeia o texto da pergunta para o rótulo da opção selecionada. Respostas de seleção múltipla unem os rótulos com vírgulas. O Claude não define este campo; forneça-o via `updatedInput` para responder programaticamente |1920| `answers` | object | `{"Which framework?": "React"}` | Opcional. Mapeia o texto da pergunta para o rótulo da opção selecionada. Respostas de múltipla seleção unem os rótulos com vírgulas. O Claude não define este campo; forneça-o via `updatedInput` para responder programaticamente |
1922 1921
1923<h5 id="exitplanmode">1922<h5 id="exitplanmode">
1924 ExitPlanMode1923 ExitPlanMode
1925</h5>1924</h5>
1926 1925
1927Apresenta um plano e pede ao usuário que o aprove antes que o Claude saia do [modo de planejamento](/docs/pt/permission-modes#analyze-before-you-edit-with-plan-mode). O Claude grava o plano em um arquivo no disco antes de chamar a ferramenta, então o `tool_input` literal vindo do modelo normalmente está vazio. O Claude Code injeta o conteúdo do plano e o caminho do arquivo antes de passar a entrada aos hooks.1926Apresenta um plano e pede ao usuário que o aprove antes de o Claude sair do [modo de planejamento](/docs/pt/permission-modes#analyze-before-you-edit-with-plan-mode). O Claude grava o plano em um arquivo no disco antes de chamar a ferramenta, portanto o `tool_input` literal vindo do modelo normalmente está vazio. O Claude Code injeta o conteúdo do plano e o caminho do arquivo antes de passar a entrada para os hooks.
1928 1927
1929| Campo | Tipo | Exemplo | Descrição |1928| Campo | Tipo | Exemplo | Descrição |
1930| :- | :- | :- | :- |1929| :- | :- | :- | :- |
1931| `plan` | string | `"## Refactor auth\n1. Extract..."` | Conteúdo do plano em Markdown. Injetado a partir do arquivo do plano no disco |1930| `plan` | string | `"## Refactor auth\n1. Extract..."` | Conteúdo do plano em Markdown. Injetado a partir do arquivo de plano no disco |
1932| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Caminho para o arquivo do plano. Injetado |1931| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Caminho para o arquivo de plano. Injetado |
1933| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | Descontinuado. O Claude Code aceita o campo, mas o ignora. Antes da v2.1.205, ele carregava permissões baseadas em prompt que o Claude solicitava para implementar o plano |1932| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | Descontinuado. O Claude Code aceita o campo, mas o ignora. Antes da v2.1.205, ele carregava permissões baseadas em prompt que o Claude solicitava para implementar o plano |
1934 1933
1935No `PostToolUse`, `tool_response` é um objeto com os campos `plan` e `filePath` contendo o plano aprovado, além de flags de status internas. Leia `tool_response.plan` para obter o conteúdo do plano em vez de ler o arquivo novamente do disco.1934No `PostToolUse`, `tool_response` é um objeto com os campos `plan` e `filePath` contendo o plano aprovado, além de flags de status internas. Leia `tool_response.plan` para obter o conteúdo do plano em vez de ler o arquivo do disco novamente.
1936 1935
1937<h4 id="pretooluse-decision-control">1936<h4 id="pretooluse-decision-control">
1938 Controle de decisão do PreToolUse1937 Controle de decisão do PreToolUse
1939</h4>1938</h4>
1940 1939
1941Os hooks `PreToolUse` podem controlar se uma chamada de ferramenta prossegue. Diferentemente de outros hooks que usam um campo `decision` de nível superior, o PreToolUse retorna sua decisão dentro de um objeto `hookSpecificOutput`. Isso lhe dá um controle mais rico: quatro resultados (allow, deny, ask ou defer), além da capacidade de modificar a entrada da ferramenta antes da execução.1940Os hooks `PreToolUse` podem controlar se uma chamada de ferramenta prossegue. Ao contrário de outros hooks que usam um campo `decision` de nível superior, o PreToolUse retorna sua decisão dentro de um objeto `hookSpecificOutput`. Isso lhe dá um controle mais rico: quatro resultados (permitir, negar, pedir confirmação ou adiar) e a capacidade de modificar a entrada da ferramenta antes da execução.
1942 1941
1943| Campo | Descrição |1942| Campo | Descrição |
1944| :- | :- |1943| :- | :- |
1945| `permissionDecision` | `"allow"` pula o prompt de permissão, exceto para as [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves) e para `AskUserQuestion` e `ExitPlanMode`, que precisam de [`updatedInput` combinado a ele](#allow-with-updatedinput). `"deny"` impede a chamada de ferramenta. `"ask"` solicita a confirmação do usuário. `"defer"` sai de forma controlada para que a ferramenta possa ser retomada depois. As [regras deny e ask](/docs/pt/permissions#manage-permissions) ainda são avaliadas independentemente do que o hook retornar |1944| `permissionDecision` | `"allow"` pula o prompt de permissão, exceto para as [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves) e para `AskUserQuestion` e `ExitPlanMode`, que precisam de [`updatedInput` combinado com ele](#allow-with-updatedinput). `"deny"` impede a chamada de ferramenta. `"ask"` solicita confirmação ao usuário. `"defer"` sai de forma controlada para que a ferramenta possa ser retomada depois. [Regras de negação e de confirmação](/docs/pt/permissions#manage-permissions) ainda são avaliadas, independentemente do que o hook retornar |
1946| `permissionDecisionReason` | Para `"ask"`, mostrado ao usuário no prompt de permissão. Quando o Claude Code [nega a chamada](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs) em uma execução `-p` na qual ninguém pode responder a esse prompt, o Claude lê o motivo no resultado da ferramenta. Para `"deny"`, mostrado ao Claude. Para `"allow"` e `"defer"`, gravado somente no [log de depuração](#debug-hooks) |1945| `permissionDecisionReason` | Para `"ask"`, mostrado ao usuário no prompt de permissão. Quando o Claude Code [nega a chamada](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs) em uma execução `-p` em que ninguém pode responder a esse prompt, o Claude lê o motivo no resultado da ferramenta. Para `"deny"`, mostrado ao Claude. Para `"allow"` e `"defer"`, gravado apenas no [log de depuração](#debug-hooks) |
1947| `updatedInput` | Modifica os parâmetros de entrada da ferramenta antes da execução. Substitui o objeto de entrada inteiro, então inclua os campos inalterados junto com os modificados. O Claude Code avalia as regras de permissão e a [elegibilidade para segundo plano automático](/docs/pt/tools-reference#foreground-commands-that-move-to-the-background) de um comando Bash com base na entrada que seu hook retorna, e não na entrada que o Claude enviou. Combine com `"allow"` para aprovar automaticamente, ou com `"ask"` para mostrar a entrada modificada ao usuário. Para `"defer"`, ignorado |1946| `updatedInput` | Modifica os parâmetros de entrada da ferramenta antes da execução. Substitui todo o objeto de entrada, portanto inclua os campos inalterados junto com os modificados. O Claude Code avalia as regras de permissão e a [elegibilidade para segundo plano automático](/docs/pt/tools-reference#foreground-commands-that-move-to-the-background) de um comando Bash com base na entrada que seu hook retorna, não na entrada que o Claude enviou. Combine com `"allow"` para aprovar automaticamente, ou com `"ask"` para mostrar a entrada modificada ao usuário. Para `"defer"`, é ignorado |
1948| `additionalContext` | String adicionada ao contexto do Claude junto com o resultado da ferramenta. Ignorado quando `permissionDecision` é `"defer"`. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |1947| `additionalContext` | String adicionada ao contexto do Claude junto com o resultado da ferramenta. Ignorada quando `permissionDecision` é `"defer"`. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |
1949 1948
1950Quando vários hooks PreToolUse retornam decisões diferentes, a precedência é `deny` > `defer` > `ask` > `allow`.1949Quando vários hooks PreToolUse retornam decisões diferentes, a precedência é `deny` > `defer` > `ask` > `allow`.
1951 1950
1952Um hook que bloqueia saindo com 2 é encaminhado da mesma forma que `"deny"`: o Claude vê a mensagem do stderr como o motivo da negação.1951Um hook que bloqueia saindo com 2 é tratado da mesma forma que `"deny"`: o Claude vê a mensagem do stderr como o motivo da negação.
1953 1952
1954Quando um hook retorna `"ask"`, o prompt de permissão exibido ao usuário inclui um rótulo que identifica a origem do hook: `[settings]` para um hook de qualquer arquivo de configurações ou do frontmatter de um agente, `[plugin:<name>]` para o hook de um plugin ou `[skill]` para um hook do frontmatter de uma skill. Isso ajuda os usuários a entender qual fonte de configuração está solicitando a confirmação.1953Quando um hook retorna `"ask"`, o prompt de permissão exibido ao usuário inclui um rótulo que identifica a origem do hook: `[settings]` para um hook de qualquer arquivo de configurações ou do frontmatter de um agente, `[plugin:<name>]` para o hook de um plugin, ou `[skill]` para um hook do frontmatter de uma skill. Isso ajuda os usuários a entender qual fonte de configuração está solicitando a confirmação.
1955 1954
1956O `"ask"` de um hook também força um prompt de permissão no [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode): o classificador ainda pode negar a chamada de ferramenta, mas não pode aprová-la silenciosamente. Antes da v2.1.211, o classificador podia aprovar um comando Bash executado fora do [sandbox](/docs/pt/sandboxing) sem mostrar o prompt solicitado pelo hook; o classificador ainda aplicava suas próprias regras de segurança a esse comando, e um `"deny"` de hook era sempre respeitado.1955Um `"ask"` de um hook também força um prompt de permissão no [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode): o classificador ainda pode negar a chamada de ferramenta, mas não pode aprová-la silenciosamente. Antes da v2.1.211, o classificador podia aprovar um comando Bash executado fora do [sandbox](/docs/pt/sandboxing) sem mostrar o prompt que o hook solicitou; o classificador ainda aplicava suas próprias regras de segurança a esse comando, e um `"deny"` de hook sempre era respeitado.
1957 1956
1958```json theme={null}1957```json theme={null}
1959{1958{
1970```1969```
1971 1970
1972<Note>1971<Note>
1973 O PreToolUse usava anteriormente os campos `decision` e `reason` de nível superior, mas eles estão descontinuados para este evento. Use `hookSpecificOutput.permissionDecision` e `hookSpecificOutput.permissionDecisionReason`. Os valores descontinuados `"approve"` e `"block"` correspondem a `"allow"` e `"deny"`, respectivamente. Outros eventos, como PostToolUse e Stop, continuam usando `decision` e `reason` de nível superior como seu formato atual.1972 O PreToolUse usava anteriormente os campos `decision` e `reason` de nível superior, mas eles estão descontinuados para este evento. Use `hookSpecificOutput.permissionDecision` e `hookSpecificOutput.permissionDecisionReason` em vez disso. Os valores descontinuados `"approve"` e `"block"` são mapeados para `"allow"` e `"deny"`, respectivamente. Outros eventos, como PostToolUse e Stop, continuam usando `decision` e `reason` de nível superior como seu formato atual.
1974</Note>1973</Note>
1975 1974
1976<h4 id="allow-with-updatedinput">1975<h4 id="allow-with-updatedinput">
1977 Ferramentas que exigem interação do usuário1976 Ferramentas que exigem interação do usuário
1978</h4>1977</h4>
1979 1978
1980`AskUserQuestion` e `ExitPlanMode` exigem interação do usuário. No [modo não interativo](/docs/pt/headless) com a flag `-p`, o Claude Code as oferece somente quando a execução tem um [host de permissão](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs) para receber o prompt, como um callback `canUseTool` do Agent SDK.1979`AskUserQuestion` e `ExitPlanMode` exigem interação do usuário. No [modo não interativo](/docs/pt/headless) com a flag `-p`, o Claude Code as oferece apenas quando a execução tem um [host de permissão](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs) para receber o prompt, como um callback `canUseTool` do Agent SDK.
1981 1980
1982Um hook `PreToolUse` atende a esse requisito quando faz o seguinte:1981Um hook `PreToolUse` satisfaz esse requisito quando faz o seguinte:
1983 1982
19841. Lê a entrada da ferramenta do stdin19831. Lê a entrada da ferramenta do stdin
19852. Coleta a resposta por meio da sua própria interface19842. Coleta a resposta por meio da sua própria interface
2009}2008}
2010```2009```
2011 2010
2012Uma ferramenta MCP cujo servidor a marca com [`_meta["anthropic/requiresUserInteraction"]`](/docs/pt/mcp#require-approval-for-a-specific-tool) é mais restrita: um hook não pode pular seu prompt de aprovação com `"allow"`, com ou sem `updatedInput`, porque o Claude Code não consegue confirmar que o hook coletou a interação de que a ferramenta precisa.2011Uma ferramenta MCP cujo servidor a marca com [`_meta["anthropic/requiresUserInteraction"]`](/docs/pt/mcp#require-approval-for-a-specific-tool) é mais restrita: um hook não pode pular seu prompt de aprovação com `"allow"`, com ou sem `updatedInput`, porque o Claude Code não pode confirmar que o hook coletou a interação de que a ferramenta precisa.
2013 2012
2014<h4 id="defer-a-tool-call-for-later">2013<h4 id="defer-a-tool-call-for-later">
2015 Adiar uma chamada de ferramenta para mais tarde2014 Adiar uma chamada de ferramenta para depois
2016</h4>2015</h4>
2017 2016
2018`"defer"` é para integrações que executam `claude -p` como subprocesso e leem sua saída JSON, como um app do Agent SDK ou uma UI personalizada construída sobre o Claude Code. Ele permite que esse processo chamador pause o Claude em uma chamada de ferramenta, colete a entrada por meio da sua própria interface e retome de onde parou. O Claude Code respeita este valor somente no [modo não interativo](/docs/pt/headless) com a flag `-p`. Em sessões interativas, ele registra um aviso em log e ignora o resultado do hook.2017`"defer"` é para integrações que executam `claude -p` como subprocesso e leem sua saída JSON, como um app do Agent SDK ou uma interface personalizada construída sobre o Claude Code. Ele permite que esse processo chamador pause o Claude em uma chamada de ferramenta, colete a entrada por meio de sua própria interface e retome de onde parou. O Claude Code respeita esse valor apenas no [modo não interativo](/docs/pt/headless) com a flag `-p`. Em sessões interativas, ele registra um aviso em log e ignora o resultado do hook.
2019 2018
2020A ferramenta `AskUserQuestion` é o caso típico: o Claude quer perguntar algo ao usuário, mas não há terminal para responder. Uma execução `-p` oferece `AskUserQuestion` somente quando tem um [host de permissão](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs), como uma ferramenta MCP que você passa com `--permission-prompt-tool`, então inicie a execução com um. O ciclo funciona assim:2019A ferramenta `AskUserQuestion` é o caso típico: o Claude quer perguntar algo ao usuário, mas não há terminal para responder. Uma execução `-p` oferece `AskUserQuestion` apenas quando tem um [host de permissão](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs), como uma ferramenta MCP que você passa com `--permission-prompt-tool`, portanto inicie a execução com um. O ciclo completo funciona assim:
2021 2020
20221. O Claude chama `AskUserQuestion`. O hook `PreToolUse` é disparado.20211. O Claude chama `AskUserQuestion`. O hook `PreToolUse` é disparado.
20232. O hook retorna `permissionDecision: "defer"`. A ferramenta não é executada. O processo sai com `stop_reason: "tool_deferred"` e a chamada de ferramenta pendente preservada na transcrição.20222. 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.
20243. O processo chamador lê `deferred_tool_use` do resultado do SDK, apresenta a pergunta na sua própria UI e aguarda uma resposta.20233. O processo chamador lê `deferred_tool_use` do resultado do SDK, apresenta a pergunta em sua própria interface e aguarda uma resposta.
20254. O processo chamador executa `claude -p --resume <session-id>` com o mesmo host de permissão. A mesma chamada de ferramenta dispara o `PreToolUse` novamente.20244. O processo chamador executa `claude -p --resume <session-id>` com o mesmo host de permissão. A mesma chamada de ferramenta dispara o `PreToolUse` novamente.
20265. O hook retorna `permissionDecision: "allow"` com a resposta em `updatedInput`. A ferramenta é executada e o Claude continua.20255. O hook retorna `permissionDecision: "allow"` com a resposta em `updatedInput`. A ferramenta é executada e o Claude continua.
2027 2026
2041}2040}
2042```2041```
2043 2042
2044Não há timeout nem limite de novas tentativas. A sessão permanece no disco até que você a retome, sujeita à limpeza de retenção [`cleanupPeriodDays`](/docs/pt/settings-reference#cleanupperioddays), que exclui os arquivos de sessão após 30 dias por padrão, seguindo as [regras de limpeza de retenção](/docs/pt/claude-directory#cleaned-up-automatically). Se a resposta não estiver pronta quando você retomar, o hook pode retornar `"defer"` novamente e o processo sai da mesma forma. O processo chamador controla quando interromper o loop, retornando eventualmente `"allow"` ou `"deny"` do hook.2043Não há timeout nem limite de novas tentativas. A sessão permanece no disco até que você a retome, sujeita à varredura de retenção [`cleanupPeriodDays`](/docs/pt/settings-reference#cleanupperioddays), que exclui arquivos de sessão após 30 dias por padrão, seguindo as [regras da varredura de retenção](/docs/pt/claude-directory#cleaned-up-automatically). Se a resposta não estiver pronta quando você retomar, o hook pode retornar `"defer"` novamente e o processo sai da mesma forma. O processo chamador controla quando interromper o loop, retornando eventualmente `"allow"` ou `"deny"` a partir do hook.
2045 2044
2046`"defer"` só funciona quando o Claude faz uma única chamada de ferramenta no turno. Se o Claude fizer várias chamadas de ferramenta de uma vez, `"defer"` é ignorado com um aviso e a ferramenta prossegue pelo fluxo normal de permissões. A restrição existe porque a retomada só pode executar novamente uma ferramenta: não há como adiar uma chamada de um lote sem deixar as outras sem resolução.2045`"defer"` só funciona quando o Claude faz uma única chamada de ferramenta no turno. Se o Claude fizer várias chamadas de ferramenta de uma vez, `"defer"` é ignorado com um aviso e a ferramenta prossegue pelo fluxo normal de permissão. A restrição existe porque a retomada só pode reexecutar uma ferramenta: não há como adiar uma chamada de um lote sem deixar as outras sem resolução.
2047 2046
2048Se a ferramenta adiada não estiver mais disponível quando você retomar, o processo sai com `stop_reason: "tool_deferred_unavailable"` e `is_error: true` antes que o hook seja disparado. Isso acontece quando um servidor MCP que fornecia a ferramenta não está conectado na sessão retomada. O payload `deferred_tool_use` ainda é incluído para que você possa identificar qual ferramenta ficou ausente.2047Se a ferramenta adiada não estiver mais disponível quando você retomar, o processo sai com `stop_reason: "tool_deferred_unavailable"` e `is_error: true` antes de o hook ser disparado. Isso acontece quando um servidor MCP que fornecia a ferramenta não está conectado na sessão retomada. O payload `deferred_tool_use` ainda é incluído para que você possa identificar qual ferramenta ficou indisponível.
2049 2048
2050<Note>2049<Note>
2051 Para retomar uma sessão adiada no modo de planejamento, passe [`--permission-prompt-tool`](/docs/pt/cli-reference#cli-flags) junto com `--resume` para que o Claude Code possa apresentar o plano para aprovação. Se você passar certas outras flags de inicialização, a execução retomada não volta ao modo de planejamento; consulte [Retomar no modo de planejamento com `-p`](/docs/pt/sessions#resume-in-plan-mode-with-p). Exige o Claude Code v2.1.246 ou posterior.2050 Para retomar uma sessão adiada no modo de planejamento, passe [`--permission-prompt-tool`](/docs/pt/cli-reference#cli-flags) junto com `--resume` para que o Claude Code possa apresentar o plano para aprovação. Se você passar certas outras flags de inicialização, a execução retomada não volta ao modo de planejamento; consulte [Retomar no modo de planejamento com `-p`](/docs/pt/sessions#resume-in-plan-mode-with-p). Exige o Claude Code v2.1.246 ou posterior.
2052 2051
2053 Quando você retoma com `-p`, o Claude Code não restaura nenhum outro modo de permissão armazenado. Ele inicia a execução no modo de permissão em que uma nova execução `claude -p` iniciaria, então passe `--permission-mode` ou `--dangerously-skip-permissions` novamente se a sessão adiada usava um deles. Quando você retoma com `claude --resume <session-id>` sem `-p`, o Claude Code restaura o modo de permissão armazenado, com as exceções listadas em [modo de permissão na retomada](/docs/pt/sessions#permission-mode-on-resume).2052 Quando você retoma com `-p`, o Claude Code não restaura nenhum outro modo de permissão armazenado. Ele inicia a execução no modo de permissão em que uma nova execução `claude -p` iniciaria, portanto passe `--permission-mode` ou `--dangerously-skip-permissions` novamente se a sessão adiada usava um deles. Quando você retoma com `claude --resume <session-id>` sem `-p`, o Claude Code restaura o modo de permissão armazenado, com as exceções listadas em [modo de permissão na retomada](/docs/pt/sessions#permission-mode-on-resume).
2054</Note>2053</Note>
2055 2054
2056<h3 id="permissionrequest">2055<h3 id="permissionrequest">
2057 PermissionRequest2056 PermissionRequest
2058</h3>2057</h3>
2059 2058
2060É executado quando o Claude Code está prestes a pedir sua permissão para usar uma ferramenta. Em sessões que não podem mostrar um prompt, como subagentes em segundo plano no [modo não interativo](/docs/pt/headless), o Claude Code ainda executa esses hooks e, se nenhum hook retornar uma decisão, ele nega a chamada de ferramenta. Para uma chamada que chega a um `--permission-prompt-tool` ou ao [callback `canUseTool`](/docs/pt/agent-sdk/permissions) do Agent SDK, os hooks são executados junto com o seu host, e o que decidir primeiro se aplica.2059É executado quando o Claude Code está prestes a pedir sua permissão para usar uma ferramenta. Em sessões que não podem mostrar um prompt, como subagentes em segundo plano no [modo não interativo](/docs/pt/headless), o Claude Code ainda executa esses hooks e, se nenhum hook retornar uma decisão, nega a chamada de ferramenta. Para uma chamada que chega a um `--permission-prompt-tool` ou ao [callback `canUseTool`](/docs/pt/agent-sdk/permissions) do Agent SDK, os hooks são executados junto com seu host, e vale a decisão de quem decidir primeiro.
2061Use o [controle de decisão do PermissionRequest](#permissionrequest-decision-control) para permitir ou negar em nome do usuário.2060Use o [controle de decisão do PermissionRequest](#permissionrequest-decision-control) para permitir ou negar em nome do usuário.
2062 2061
2063Use este evento quando precisar de um sinal no momento em que o Claude pede permissão para usar uma ferramenta. O Claude Code executa um hook [Notification](#notification) com o tipo `permission_prompt` somente depois que o prompt esperou cerca de seis segundos.2062Use este evento quando precisar de um sinal no momento em que o Claude pede permissão para usar uma ferramenta. O Claude Code executa um hook [Notification](#notification) com o tipo `permission_prompt` somente depois que o prompt aguardou cerca de seis segundos.
2064 2063
2065O Claude Code não executa hooks PermissionRequest para a [requisição de rede](/docs/pt/sandboxing#network-isolation) de um comando em sandbox. Para obter um sinal para esse prompt, use o tipo de notificação `permission_prompt`.2064O Claude Code não executa hooks PermissionRequest para a [requisição de rede](/docs/pt/sandboxing#network-isolation) de um comando em sandbox. Para obter um sinal para esse prompt, use o tipo de notificação `permission_prompt`.
2066 2065
2067Faz a correspondência com o nome da ferramenta, com os mesmos valores do PreToolUse.2066Faz correspondência com o nome da ferramenta, com os mesmos valores do PreToolUse.
2068 2067
2069<h4 id="permissionrequest-input">2068<h4 id="permissionrequest-input">
2070 Entrada do PermissionRequest2069 Entrada do PermissionRequest
2071</h4>2070</h4>
2072 2071
2073Os hooks PermissionRequest recebem os campos `tool_name` e `tool_input` como os hooks PreToolUse, mas sem `tool_use_id`. Para uma ferramenta MCP, eles também recebem o objeto [`mcp_server`](#pretooluse-input). Um array opcional `permission_suggestions` contém as [atualizações de permissão](#permission-update-entries) que o Claude Code sugere para esta solicitação, como adicionar uma regra allow ou alterar o modo de permissão.2072Os hooks PermissionRequest recebem os campos `tool_name` e `tool_input` como os hooks PreToolUse, mas sem `tool_use_id`. Para uma ferramenta MCP, eles também recebem o objeto [`mcp_server`](#pretooluse-input). Um array opcional `permission_suggestions` contém as [atualizações de permissão](#permission-update-entries) que o Claude Code sugere para esta solicitação, como adicionar uma regra de permissão ou alterar o modo de permissão.
2074 2073
2075O array `permission_suggestions` não é uma lista exata das opções que você vê, porque cada diálogo de permissão monta suas próprias opções. Alguns diálogos, como o de edições de arquivos, não leem o array de forma alguma e derivam suas opções da própria solicitação. Um diálogo que o lê ainda pode omitir uma opção cuja sugestão permanece no array, por exemplo quando [`allowManagedPermissionRulesOnly`](/docs/pt/settings-reference#allowmanagedpermissionrulesonly) oculta as opções de salvar regras. Ele também pode oferecer opções que não têm entrada de sugestão, como [**Yes, and switch to auto mode**](/docs/pt/permission-modes#switch-permission-modes), que altera o modo de permissão diretamente em vez de por meio de uma atualização de permissão.2074O array `permission_suggestions` não é uma lista exata das opções que você vê, porque cada diálogo de permissão monta suas próprias opções. Alguns diálogos, como o de edição de arquivos, não leem o array e derivam suas opções da própria solicitação. Um diálogo que o lê ainda pode ocultar uma opção cuja sugestão permanece no array, por exemplo quando [`allowManagedPermissionRulesOnly`](/docs/pt/settings-reference#allowmanagedpermissionrulesonly) oculta as opções de salvar regras. Ele também pode oferecer opções que não têm entrada de sugestão, como [**Yes, and switch to auto mode**](/docs/pt/permission-modes#switch-permission-modes), que altera o modo de permissão diretamente em vez de por meio de uma atualização de permissão.
2076 2075
2077Os hooks PreToolUse são executados antes de cada chamada de ferramenta, precise ela de permissão ou não. Os hooks PermissionRequest são executados somente quando o Claude Code está prestes a pedir sua permissão, ou quando, de outra forma, ele negaria automaticamente uma chamada que não pode exibir um prompt. Nenhum dos dois eventos é disparado para [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior).2076Os hooks PreToolUse são executados antes de toda chamada de ferramenta, precise ela de permissão ou não. Os hooks PermissionRequest são executados apenas quando o Claude Code está prestes a pedir sua permissão, ou quando ele negaria automaticamente uma chamada que não pode solicitar confirmação. Nenhum dos dois eventos é disparado para [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior).
2078 2077
2079```json theme={null}2078```json theme={null}
2080{2079{
2107 2106
2108| Campo | Descrição |2107| Campo | Descrição |
2109| :- | :- |2108| :- | :- |
2110| `behavior` | `"allow"` concede a permissão, `"deny"` a nega. As [regras deny e ask](/docs/pt/permissions#manage-permissions) ainda são avaliadas, então um hook que retorna `"allow"` não sobrescreve uma regra deny correspondente |2109| `behavior` | `"allow"` concede a permissão, `"deny"` a nega. [Regras de negação e de confirmação](/docs/pt/permissions#manage-permissions) ainda são avaliadas, portanto um hook que retorna `"allow"` não sobrescreve uma regra de negação correspondente |
2111| `updatedInput` | Somente para `"allow"`: modifica os parâmetros de entrada da ferramenta antes da execução. Substitui o objeto de entrada inteiro, então inclua os campos inalterados junto com os modificados. A entrada modificada é reavaliada com base nas regras deny e ask |2110| `updatedInput` | Apenas para `"allow"`: modifica os parâmetros de entrada da ferramenta antes da execução. Substitui todo o objeto de entrada, portanto inclua os campos inalterados junto com os modificados. A entrada modificada é reavaliada com base nas regras de negação e de confirmação |
2112| `updatedPermissions` | Somente para `"allow"`: array de [entradas de atualização de permissão](#permission-update-entries) a serem aplicadas, como adicionar uma regra allow ou alterar o modo de permissão da sessão |2111| `updatedPermissions` | Apenas para `"allow"`: array de [entradas de atualização de permissão](#permission-update-entries) a aplicar, como adicionar uma regra de permissão ou alterar o modo de permissão da sessão |
2113| `message` | Somente para `"deny"`: informa ao Claude por que a permissão foi negada |2112| `message` | Apenas para `"deny"`: informa ao Claude por que a permissão foi negada |
2114| `interrupt` | Somente para `"deny"`: se `true`, interrompe o Claude |2113| `interrupt` | Apenas para `"deny"`: se `true`, interrompe o Claude |
2115 2114
2116Um hook que sai com 2 sem um objeto `decision` deixa o fluxo de permissões inalterado, e seu stderr é descartado. Somente o objeto `decision` pode conceder ou negar a solicitação.2115Um 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.
2117 2116
2118```json theme={null}2117```json theme={null}
2119{2118{
2140| `addRules` | `rules`, `behavior`, `destination` | Adiciona regras de permissão. `rules` é um array de objetos `{toolName, ruleContent?}`. Omita `ruleContent` para corresponder à ferramenta inteira. `behavior` é `"allow"`, `"deny"` ou `"ask"` |2139| `addRules` | `rules`, `behavior`, `destination` | Adiciona regras de permissão. `rules` é um array de objetos `{toolName, ruleContent?}`. Omita `ruleContent` para corresponder à ferramenta inteira. `behavior` é `"allow"`, `"deny"` ou `"ask"` |
2141| `replaceRules` | `rules`, `behavior`, `destination` | Substitui todas as regras do `behavior` informado no `destination` pelas `rules` fornecidas |2140| `replaceRules` | `rules`, `behavior`, `destination` | Substitui todas as regras do `behavior` informado no `destination` pelas `rules` fornecidas |
2142| `removeRules` | `rules`, `behavior`, `destination` | Remove as regras correspondentes do `behavior` informado |2141| `removeRules` | `rules`, `behavior`, `destination` | Remove as regras correspondentes do `behavior` informado |
2143| `setMode` | `mode`, `destination` | Altera o modo de permissão. Os modos válidos são `default`, `auto`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` e `manual` como alias para `default` |2142| `setMode` | `mode`, `destination` | Altera o modo de permissão. Os modos válidos são `default`, `auto`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` e `manual` como alias de `default` |
2144| `addDirectories` | `directories`, `destination` | Adiciona diretórios de trabalho. `directories` é um array de strings de caminho |2143| `addDirectories` | `directories`, `destination` | Adiciona diretórios de trabalho. `directories` é um array de strings de caminho |
2145| `removeDirectories` | `directories`, `destination` | Remove diretórios de trabalho |2144| `removeDirectories` | `directories`, `destination` | Remove diretórios de trabalho |
2146 2145
2147<Note>2146<Note>
2148 `setMode` com `bypassPermissions` só tem efeito se você iniciou a sessão com o modo bypass já disponível: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions` ou `permissions.defaultMode: "bypassPermissions"` nas [configurações de usuário, de `--settings` ou gerenciadas](/docs/pt/settings-reference#permissions-defaultmode). Caso contrário, a atualização não tem efeito. A atualização também não tem efeito quando [`permissions.disableBypassPermissionsMode`](/docs/pt/permissions#managed-settings) desativa o modo, ou quando a sessão inicia em [modo restrito](/docs/pt/cli-reference#cli-flags).2147 `setMode` com `bypassPermissions` só tem efeito se você iniciou a sessão com o modo bypass já disponível: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions` ou `permissions.defaultMode: "bypassPermissions"` nas [configurações de usuário, de `--settings` ou gerenciadas](/docs/pt/settings-reference#permissions-defaultmode). Caso contrário, a atualização não tem efeito. A atualização também não tem efeito quando [`permissions.disableBypassPermissionsMode`](/docs/pt/permissions#managed-settings) desativa o modo, ou quando a sessão é iniciada em [modo restrito](/docs/pt/cli-reference#cli-flags).
2149 2148
2150 `bypassPermissions` nunca é persistido como `defaultMode`, independentemente de `destination`.2149 `bypassPermissions` nunca é persistido como `defaultMode`, independentemente do `destination`.
2151</Note>2150</Note>
2152 2151
2153O campo `destination` em cada entrada determina se a alteração permanece na memória ou é persistida em um arquivo de configurações.2152O campo `destination` em cada entrada determina se a alteração permanece na memória ou é persistida em um arquivo de configurações.
2159| `projectSettings` | `.claude/settings.json` |2158| `projectSettings` | `.claude/settings.json` |
2160| `userSettings` | `~/.claude/settings.json` |2159| `userSettings` | `~/.claude/settings.json` |
2161 2160
2162Um hook pode ecoar uma das `permission_suggestions` que recebeu como sua própria saída `updatedPermissions`.2161Um hook pode repetir uma das `permission_suggestions` que recebeu como sua própria saída `updatedPermissions`.
2163 2162
2164<h3 id="posttooluse">2163<h3 id="posttooluse">
2165 PostToolUse2164 PostToolUse
2169 2168
2170Faz correspondência pelo nome da ferramenta, com os mesmos valores de PreToolUse.2169Faz correspondência pelo nome da ferramenta, com os mesmos valores de PreToolUse.
2171 2170
2172Faça uma correspondência mais ampla quando o nome da ferramenta não for o filtro adequado:2171Faça uma correspondência mais ampla quando o nome da ferramenta não for o filtro certo:
2173 2172
2174* Para executar um hook após qualquer ferramenta ser concluída com sucesso, omita o `matcher` ou defina-o como `"*"`. Seu hook pode então descobrir por conta própria o que mudou, por exemplo executando `git status --porcelain`, que também lista arquivos não rastreados que o `git diff` não mostra. Para chamadas de ferramenta que falham, adicione o mesmo hook em [PostToolUseFailure](#posttoolusefailure).2173* Para executar um hook após qualquer ferramenta ser concluída com sucesso, omita o `matcher` ou defina-o como `"*"`. Seu hook pode então descobrir por conta própria o que mudou, por exemplo executando `git status --porcelain`, que também lista arquivos não rastreados que o `git diff` deixa passar. Para chamadas de ferramenta que falham, adicione o mesmo hook em [PostToolUseFailure](#posttoolusefailure).
2175* Para executar um hook quando um arquivo específico muda no disco, independentemente de quem o gravou, use [FileChanged](#filechanged). O Claude Code não executa um hook `PostToolUse` que corresponde a `Edit|Write` quando um comando `Bash` ou um processo fora do Claude Code reescreve o mesmo arquivo.2174* Para executar um hook quando um arquivo específico mudar no disco, independentemente do que o gravou, use [FileChanged](#filechanged). O Claude Code não executa um hook `PostToolUse` que corresponde a `Edit|Write` quando um comando `Bash` ou um processo fora do Claude Code reescreve o mesmo arquivo.
2176 2175
2177<h4 id="posttooluse-input">2176<h4 id="posttooluse-input">
2178 Entrada do PostToolUse2177 Entrada de PostToolUse
2179</h4>2178</h4>
2180 2179
2181Os hooks `PostToolUse` são disparados depois que uma ferramenta já foi executada com sucesso. A entrada inclui tanto `tool_input`, os argumentos enviados à ferramenta, quanto `tool_response`, o resultado que ela retornou. O esquema exato de ambos depende da ferramenta. Os caminhos em `tool_input` de ferramentas de arquivo chegam no mesmo formato que em [PreToolUse](#pretooluse-input): sempre absolutos, com os separadores nativos da plataforma, portanto barras invertidas no Windows. Para uma ferramenta MCP, a entrada também inclui o objeto [`mcp_server`](#pretooluse-input).2180Os hooks `PostToolUse` são disparados depois que uma ferramenta já foi executada com sucesso. A entrada inclui tanto `tool_input`, os argumentos enviados à ferramenta, quanto `tool_response`, o resultado que ela retornou. O esquema exato de ambos depende da ferramenta. Os caminhos em `tool_input` das ferramentas de arquivo chegam no mesmo formato que em [PreToolUse](#pretooluse-input): sempre absolutos, com os separadores nativos da plataforma, ou seja, barras invertidas no Windows. Para uma ferramenta MCP, a entrada também traz o objeto [`mcp_server`](#pretooluse-input).
2182 2181
2183```json theme={null}2182```json theme={null}
2184{2183{
2206| `duration_ms` | Opcional. Tempo de execução da ferramenta em milissegundos. Exclui o tempo gasto em prompts de permissão e em hooks PreToolUse |2205| `duration_ms` | Opcional. Tempo de execução da ferramenta em milissegundos. Exclui o tempo gasto em prompts de permissão e em hooks PreToolUse |
2207 2206
2208<h4 id="posttooluse-decision-control">2207<h4 id="posttooluse-decision-control">
2209 Controle de decisão do PostToolUse2208 Controle de decisão de PostToolUse
2210</h4>2209</h4>
2211 2210
2212Os hooks `PostToolUse` podem fornecer feedback ao Claude após a execução da ferramenta. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar estes campos específicos do evento:2211Os hooks `PostToolUse` podem fornecer feedback ao Claude após a execução da ferramenta. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar estes campos específicos do evento:
2217| `reason` | Explicação mostrada ao Claude quando `decision` é `"block"` |2216| `reason` | Explicação mostrada ao Claude quando `decision` é `"block"` |
2218| `additionalContext` | String adicionada ao contexto do Claude junto com o resultado da ferramenta. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |2217| `additionalContext` | String adicionada ao contexto do Claude junto com o resultado da ferramenta. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |
2219| `classifierContext` | Nota curta sobre o resultado desta chamada destinada ao classificador do [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), e não ao Claude. Consulte [Anotar um resultado para o classificador do modo auto](#annotate-a-result-for-the-auto-mode-classifier). Requer Claude Code v2.1.236 ou posterior |2218| `classifierContext` | Nota curta sobre o resultado desta chamada destinada ao classificador do [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), e não ao Claude. Consulte [Anotar um resultado para o classificador do modo auto](#annotate-a-result-for-the-auto-mode-classifier). Requer Claude Code v2.1.236 ou posterior |
2220| `updatedToolOutput` | Substitui a saída da ferramenta pelo valor fornecido antes de ela ser enviada ao Claude. O valor deve corresponder ao formato de saída da ferramenta |2219| `updatedToolOutput` | Substitui a saída da ferramenta pelo valor fornecido antes que ela seja enviada ao Claude. O valor deve corresponder ao formato de saída da ferramenta |
2221| `updatedMCPToolOutput` | Substitui a saída somente para [ferramentas MCP](#match-mcp-tools). Prefira `updatedToolOutput`, que funciona para todas as ferramentas |2220| `updatedMCPToolOutput` | Substitui a saída apenas para [ferramentas MCP](#match-mcp-tools). Prefira `updatedToolOutput`, que funciona para todas as ferramentas |
2222 2221
2223O exemplo abaixo substitui a saída de uma chamada `Bash`. O valor de substituição corresponde ao formato de saída da ferramenta `Bash`:2222O exemplo abaixo substitui a saída de uma chamada `Bash`. O valor de substituição corresponde ao formato de saída da ferramenta `Bash`:
2224 2223
2238```2237```
2239 2238
2240<Warning>2239<Warning>
2241 `updatedToolOutput` altera apenas o que o Claude vê. A ferramenta já foi executada quando o hook é disparado, portanto quaisquer arquivos gravados, comandos executados ou requisições de rede enviadas já surtiram efeito. A telemetria, como spans de ferramentas do OpenTelemetry e eventos de análise, também captura a saída original antes de o hook ser executado. Para impedir ou modificar uma chamada de ferramenta antes de ela ser executada, use um hook [PreToolUse](#pretooluse).2240 `updatedToolOutput` altera apenas o que o Claude vê. A ferramenta já foi executada quando o hook é disparado, portanto quaisquer arquivos gravados, comandos executados ou requisições de rede enviadas já tiveram efeito. A telemetria, como spans de ferramenta do OpenTelemetry e eventos de analytics, também captura a saída original antes de o hook ser executado. Para impedir ou modificar uma chamada de ferramenta antes que ela seja executada, use um hook [PreToolUse](#pretooluse).
2242 2241
2243 O valor de substituição deve corresponder ao formato de saída da ferramenta. As ferramentas integradas retornam objetos estruturados em vez de strings simples. Por exemplo, `Bash` retorna um objeto com os campos `stdout`, `stderr`, `interrupted` e `isImage`. Para ferramentas integradas, um valor que não corresponde ao esquema de saída da ferramenta é ignorado e a saída original é usada. A saída de ferramentas MCP é repassada sem validação de esquema. Remover detalhes de erro de que o Claude precisa pode fazê-lo prosseguir com base em uma suposição falsa.2242 O valor de substituição deve corresponder ao formato de saída da ferramenta. As ferramentas integradas retornam objetos estruturados em vez de strings simples. Por exemplo, `Bash` retorna um objeto com os campos `stdout`, `stderr`, `interrupted` e `isImage`. Para ferramentas integradas, um valor que não corresponda ao esquema de saída da ferramenta é ignorado e a saída original é usada. A saída de ferramentas MCP é repassada sem validação de esquema. Remover detalhes de erro de que o Claude precisa pode fazer com que ele prossiga com base em uma suposição falsa.
2244</Warning>2243</Warning>
2245 2244
2246<h4 id="annotate-a-result-for-the-auto-mode-classifier">2245<h4 id="annotate-a-result-for-the-auto-mode-classifier">
2247 Anotar um resultado para o classificador do modo auto2246 Anotar um resultado para o classificador do modo auto
2248</h4>2247</h4>
2249 2248
2250Retorne `classifierContext` para enviar uma nota curta sobre o resultado da chamada de ferramenta ao classificador do [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), e não ao Claude. O classificador [nunca recebe os próprios resultados das ferramentas](/docs/pt/permission-modes#how-the-classifier-evaluates-actions), então este campo é a forma suportada de informá-lo sobre o que uma chamada retornou antes que ele revise ações posteriores. O campo requer Claude Code v2.1.236 ou posterior.2249Retorne `classifierContext` para enviar uma nota curta sobre o resultado da chamada de ferramenta ao classificador do [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), e não ao Claude. O classificador [nunca recebe os próprios resultados das ferramentas](/docs/pt/permission-modes#how-the-classifier-evaluates-actions), então este campo é a forma suportada de informar algo sobre o que uma chamada retornou antes que ele revise ações posteriores. O campo requer Claude Code v2.1.236 ou posterior.
2251 2250
2252O exemplo abaixo informa ao classificador de onde veio a saída de uma consulta:2251O exemplo abaixo informa ao classificador de onde veio a saída de uma consulta:
2253 2252
2262 2261
2263O peso que o classificador dá à nota depende de onde você configurou o hook:2262O peso que o classificador dá à nota depende de onde você configurou o hook:
2264 2263
2265* **Hooks configurados no Claude Code**: para hooks de arquivos de configurações, plugins, skills e frontmatter de agentes, o classificador trata a nota como contexto não verificado fornecido pela aplicação. A nota nunca estabelece a intenção do usuário e, se afirmar que você aprovou ou solicitou algo, o classificador verifica essa afirmação com base nas suas próprias mensagens na conversa2264* **Hooks configurados no Claude Code**: para hooks de arquivos de configurações, plugins, skills e frontmatter de agentes, o classificador trata a nota como contexto não verificado fornecido pela aplicação. A nota nunca estabelece a intenção do usuário e, se afirmar que você aprovou ou solicitou algo, o classificador verifica essa afirmação em relação às suas próprias mensagens na conversa
2266* **Callbacks in-process do Agent SDK**: quando uma aplicação que incorpora o Claude Code registra o hook como um [callback do TypeScript SDK](/docs/pt/agent-sdk/hooks) e retorna a nota durante a sessão ativa, o classificador pode considerar uma declaração do usuário repassada na nota como intenção do usuário. Tal declaração pode satisfazer um requisito de consentimento que o classificador aceitaria de uma mensagem enviada por você, mas nunca remove um bloqueio que sua própria mensagem também não conseguiria remover. Depois que uma sessão é retomada, o Claude Code trata as notas restauradas como contexto não verificado. Quando hooks de ambos os grupos anotam a mesma chamada, o classificador trata a nota combinada como não verificada2265* **Callbacks do Agent SDK em processo**: quando uma aplicação que incorpora o Claude Code registra o hook como um [callback do SDK em TypeScript](/docs/pt/agent-sdk/hooks) e retorna a nota durante a sessão ativa, o classificador pode considerar uma declaração do usuário repassada na nota como intenção do usuário. Essa declaração pode satisfazer um requisito de consentimento que o classificador aceitaria de uma mensagem enviada por você, mas nunca suspende um bloqueio que sua própria mensagem também não conseguiria suspender. Depois que uma sessão é retomada, o Claude Code trata as notas restauradas como contexto não verificado. Quando hooks de ambos os grupos anotam a mesma chamada, o classificador trata a nota combinada como não verificada
2267 2266
2268O Claude Code aplica estes limites ao entregar a nota:2267O Claude Code aplica estes limites ao entregar a nota:
2269 2268
2273* **Interação com reescritas**: quando a nota descreve uma saída que você está substituindo com `updatedToolOutput`, retorne ambos os campos na mesma resposta do hook. O Claude Code descarta a nota se essa reescrita for rejeitada ou se a reescrita de outro hook a substituir. O Claude Code entrega uma nota que você retorna sem reescrita mesmo quando outro hook reescreve a saída2272* **Interação com reescritas**: quando a nota descreve uma saída que você está substituindo com `updatedToolOutput`, retorne ambos os campos na mesma resposta do hook. O Claude Code descarta a nota se essa reescrita for rejeitada ou se a reescrita de outro hook a substituir. O Claude Code entrega uma nota que você retorna sem reescrita mesmo quando outro hook reescreve a saída
2274 2273
2275<Warning>2274<Warning>
2276 O classificador lê o conteúdo que você coloca em `classifierContext` como informação da aplicação que hospeda a sessão, portanto não copie saídas de ferramentas não confiáveis ou texto de terceiros para ele. Limite a nota a uma afirmação curta sobre essa única chamada, como um fato sobre sua origem ou uma declaração do usuário a respeito dela; não use o campo para entregar mensagens não relacionadas ou um fluxo de eventos.2275 O classificador lê o conteúdo que você coloca em `classifierContext` como informação da aplicação que hospeda a sessão, então não copie saídas de ferramentas não confiáveis nem textos de terceiros para ele. Limite a nota a uma afirmação curta sobre esta única chamada, como um fato sobre sua origem ou uma declaração do usuário sobre ela; não use o campo para entregar mensagens não relacionadas ou um fluxo de eventos.
2277</Warning>2276</Warning>
2278 2277
2279<h3 id="posttoolusefailure">2278<h3 id="posttoolusefailure">
2285Faz correspondência pelo nome da ferramenta, com os mesmos valores de PreToolUse.2284Faz correspondência pelo nome da ferramenta, com os mesmos valores de PreToolUse.
2286 2285
2287<Note>2286<Note>
2288 Este evento não é disparado para chamadas de ferramenta rejeitadas antes da execução: um nome de ferramenta desconhecido, uma entrada que falha na validação de esquema ou específica da ferramenta, ou uma negação de permissão. As rejeições de validação são retornadas como resultados `tool_use_error` e ocorrem antes da execução dos hooks, portanto não disparam nem `PreToolUse` nem `PostToolUseFailure`. As negações de permissão disparam `PreToolUse`, mas não este evento; consulte [PermissionDenied](#permissiondenied).2287 Este evento não é disparado para chamadas de ferramenta rejeitadas antes da execução: um nome de ferramenta desconhecido, uma entrada que falha na validação de esquema ou na validação específica da ferramenta, ou uma negação de permissão. As rejeições de validação são retornadas como resultados `tool_use_error` e acontecem antes de os hooks serem executados, portanto não disparam nem `PreToolUse` nem `PostToolUseFailure`. As negações de permissão disparam `PreToolUse`, mas não este evento; consulte [PermissionDenied](#permissiondenied).
2289</Note>2288</Note>
2290 2289
2291<h4 id="posttoolusefailure-input">2290<h4 id="posttoolusefailure-input">
2292 Entrada do PostToolUseFailure2291 Entrada de PostToolUseFailure
2293</h4>2292</h4>
2294 2293
2295Os hooks PostToolUseFailure recebem os mesmos campos `tool_name` e `tool_input` que o PostToolUse, junto com informações de erro como campos de nível superior. Para uma ferramenta MCP, eles também recebem o objeto [`mcp_server`](#pretooluse-input). Por exemplo, um comando `npm test` com falha pode entregar:2294Os hooks PostToolUseFailure recebem os mesmos campos `tool_name` e `tool_input` que PostToolUse, junto com informações de erro como campos de nível superior. Para uma ferramenta MCP, eles também recebem o objeto [`mcp_server`](#pretooluse-input). Por exemplo, um comando `npm test` com falha poderia entregar:
2296 2295
2297```json theme={null}2296```json theme={null}
2298{2297{
2316| Campo | Descrição |2315| Campo | Descrição |
2317| :- | :- |2316| :- | :- |
2318| `error` | String que descreve o que deu errado. O formato depende da ferramenta que falhou |2317| `error` | String que descreve o que deu errado. O formato depende da ferramenta que falhou |
2319| `is_interrupt` | Booleano opcional. Verdadeiro quando a falha chegou ao Claude Code como uma interrupção, e não como um erro relatado pela ferramenta. Cancelar uma ferramenta em execução não dispara este hook; em vez disso, o resultado da ferramenta contém a mensagem de interrupção |2318| `is_interrupt` | Booleano opcional. Verdadeiro quando a falha chegou ao Claude Code como um aborto, e não como um erro relatado pela ferramenta. Cancelar uma ferramenta em execução não dispara este hook; em vez disso, o resultado da ferramenta traz a mensagem de interrupção |
2320| `duration_ms` | Opcional. Tempo de execução da ferramenta em milissegundos. Exclui o tempo gasto em prompts de permissão e em hooks PreToolUse |2319| `duration_ms` | Opcional. Tempo de execução da ferramenta em milissegundos. Exclui o tempo gasto em prompts de permissão e em hooks PreToolUse |
2321 2320
2322A string `error` geralmente é o mesmo texto que o Claude recebe como resultado da ferramenta que falhou. Seu formato varia conforme a ferramenta e a falha. Baseie seu hook em `tool_name`, `is_interrupt` e na primeira linha `Exit code N`; trate o restante da string como texto de exibição, não como um formato estável.2321A string `error` geralmente é o mesmo texto que o Claude recebe como resultado da ferramenta com falha. Seu formato varia conforme a ferramenta e a falha. Baseie seu hook em `tool_name`, `is_interrupt` e na primeira linha `Exit code N`; trate o restante da string como texto de exibição, não como um formato estável.
2323 2322
2324* Para Bash e PowerShell, um comando que foi executado e encerrado produz uma primeira linha `Exit code N`, seguida de qualquer saída que o comando produziu como um único bloco com stdout e stderr intercalados2323* Para Bash e PowerShell, um comando que foi executado e encerrado produz uma primeira linha `Exit code N`, seguida de qualquer saída que o comando tenha produzido como um único bloco com stdout e stderr intercalados
2325* Um payload também pode conter uma mensagem de falha simples sem linha de código de saída, quando o Claude Code não conseguiu iniciar o próprio processo do shell2324* Um payload também pode trazer apenas uma mensagem de falha sem linha de código de saída, quando o Claude Code não conseguiu iniciar o próprio processo do shell
2326* O Claude Code trunca strings longas no meio em torno de um marcador `... [N characters truncated] ...` e pode inserir linhas próprias, como `Command timed out after 2m 0s`2325* O Claude Code trunca strings longas no meio em torno de um marcador `... [N characters truncated] ...` e pode inserir linhas próprias, como `Command timed out after 2m 0s`
2327 2326
2328<h4 id="posttoolusefailure-decision-control">2327<h4 id="posttoolusefailure-decision-control">
2329 Controle de decisão do PostToolUseFailure2328 Controle de decisão de PostToolUseFailure
2330</h4>2329</h4>
2331 2330
2332Os hooks `PostToolUseFailure` podem fornecer contexto ao Claude após uma falha de ferramenta. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar estes campos específicos do evento:2331Os hooks `PostToolUseFailure` podem fornecer contexto ao Claude após uma falha de ferramenta. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar estes campos específicos do evento:
2348 PostToolBatch2347 PostToolBatch
2349</h3>2348</h3>
2350 2349
2351É executado uma vez depois que todas as chamadas de ferramenta de um lote foram resolvidas, antes de o Claude Code enviar a próxima requisição ao modelo. `PostToolUse` é disparado uma vez por ferramenta, o que significa que é disparado simultaneamente quando o Claude faz chamadas de ferramenta em paralelo. `PostToolBatch` é disparado exatamente uma vez com o lote completo, portanto é o lugar certo para injetar contexto que depende do conjunto de ferramentas executadas, e não de uma única ferramenta. Não há matcher para este evento.2350É executado uma vez depois que todas as chamadas de ferramenta de um lote foram resolvidas, antes que o Claude Code envie a próxima requisição ao modelo. `PostToolUse` é disparado uma vez por ferramenta, o que significa que é disparado de forma concorrente quando o Claude faz chamadas de ferramenta paralelas. `PostToolBatch` é disparado exatamente uma vez com o lote completo, então é o lugar certo para injetar contexto que depende do conjunto de ferramentas executadas, e não de uma única ferramenta. Não há matcher para este evento.
2352 2351
2353<h4 id="posttoolbatch-input">2352<h4 id="posttoolbatch-input">
2354 Entrada do PostToolBatch2353 Entrada de PostToolBatch
2355</h4>2354</h4>
2356 2355
2357Além dos [campos de entrada comuns](#common-input-fields), os hooks PostToolBatch recebem `tool_calls`, um array que descreve cada chamada de ferramenta no lote:2356Além dos [campos de entrada comuns](#common-input-fields), os hooks PostToolBatch recebem `tool_calls`, um array que descreve cada chamada de ferramenta do lote:
2358 2357
2359```json theme={null}2358```json theme={null}
2360{2359{
2380}2379}
2381```2380```
2382 2381
2383`tool_response` contém o mesmo conteúdo que o modelo recebe no bloco `tool_result` correspondente. O valor é uma string serializada ou um array de blocos de conteúdo, exatamente como a ferramenta o emitiu. Para `Read`, isso significa texto prefixado com números de linha em vez do conteúdo bruto do arquivo. As respostas podem ser grandes, portanto analise apenas os campos de que você precisa.2382`tool_response` contém o mesmo conteúdo que o modelo recebe no bloco `tool_result` correspondente. O valor é uma string serializada ou um array de blocos de conteúdo, exatamente como a ferramenta o emitiu. Para `Read`, isso significa texto prefixado com números de linha, e não o conteúdo bruto do arquivo. As respostas podem ser grandes, então analise apenas os campos de que você precisa.
2384 2383
2385<Note>2384<Note>
2386 O formato de `tool_response` difere do de `PostToolUse`. `PostToolUse` passa o objeto `Output` estruturado da ferramenta, como `{filePath: "...", type: "create"}` para `Write`; `PostToolBatch` passa o conteúdo serializado de `tool_result` que o modelo vê.2385 O formato de `tool_response` difere do de `PostToolUse`. `PostToolUse` passa o objeto `Output` estruturado da ferramenta, como `{filePath: "...", type: "create"}` para `Write`; `PostToolBatch` passa o conteúdo serializado de `tool_result` que o modelo vê.
2387</Note>2386</Note>
2388 2387
2389<h4 id="posttoolbatch-decision-control">2388<h4 id="posttoolbatch-decision-control">
2390 Controle de decisão do PostToolBatch2389 Controle de decisão de PostToolBatch
2391</h4>2390</h4>
2392 2391
2393Os hooks `PostToolBatch` podem injetar contexto para o Claude. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar estes campos específicos do evento:2392Os hooks `PostToolBatch` podem injetar contexto para o Claude. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar estes campos específicos do evento:
2394 2393
2395| Campo | Descrição |2394| Campo | Descrição |
2396| :- | :- |2395| :- | :- |
2397| `additionalContext` | String de contexto injetada uma vez antes da próxima chamada ao modelo. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) para detalhes de entrega, o que incluir e como sessões retomadas lidam com valores anteriores |2396| `additionalContext` | String de contexto injetada uma vez antes da próxima chamada ao modelo. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) para detalhes de entrega, o que colocar nela e como as sessões retomadas lidam com valores anteriores |
2398 2397
2399```json theme={null}2398```json theme={null}
2400{2399{
2405}2404}
2406```2405```
2407 2406
2408Retornar `decision: "block"` ou `continue: false` interrompe o loop agêntico antes da próxima chamada ao modelo. A mensagem de bloqueio vem do `reason` ou `stopReason` do JSON, ou do stderr no código de saída 2. Você a vê como um aviso na transcrição, e ela permanece na conversa, então o Claude a vê quando a conversa continua.2407Retornar `decision: "block"` ou `continue: false` interrompe o loop agêntico antes da próxima chamada ao modelo. A mensagem de bloqueio vem do `reason` ou do `stopReason` do JSON, ou do stderr no código de saída 2. Você a vê como um aviso na transcrição, e ela permanece na conversa, então o Claude a vê quando a conversa continua.
2409 2408
2410<h3 id="permissiondenied">2409<h3 id="permissiondenied">
2411 PermissionDenied2410 PermissionDenied
2412</h3>2411</h3>
2413 2412
2414É executado quando o [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) nega uma chamada de ferramenta, inclusive quando nega sem um veredito do classificador porque [uma verificação de segurança separada do modo auto recusou a própria requisição do classificador](/docs/pt/errors#auto-mode-cannot-determine-the-safety-of-an-action) ou porque a resposta dele não pôde ser analisada. Este hook só é disparado no modo auto: ele não é executado quando você nega manualmente uma caixa de diálogo de permissão, quando um hook `PreToolUse` bloqueia uma chamada ou quando uma regra `deny` corresponde. Use-o para registrar negações em log, ajustar a configuração ou informar ao modelo que ele pode tentar novamente a chamada de ferramenta.2413É executado quando o [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) nega uma chamada de ferramenta, inclusive quando nega sem um veredito do classificador porque [uma verificação de segurança separada do modo auto recusou a própria requisição do classificador](/docs/pt/errors#auto-mode-cannot-determine-the-safety-of-an-action) ou porque sua resposta não pôde ser analisada. Este hook só é disparado no modo auto: ele não é executado quando você nega manualmente uma caixa de diálogo de permissão, quando um hook `PreToolUse` bloqueia uma chamada ou quando uma regra `deny` corresponde. Use-o para registrar negações em log, ajustar a configuração ou informar ao modelo que ele pode tentar novamente a chamada de ferramenta.
2415 2414
2416Faz correspondência pelo nome da ferramenta, com os mesmos valores de PreToolUse.2415Faz correspondência pelo nome da ferramenta, com os mesmos valores de PreToolUse.
2417 2416
2418<h4 id="permissiondenied-input">2417<h4 id="permissiondenied-input">
2419 Entrada do PermissionDenied2418 Entrada de PermissionDenied
2420</h4>2419</h4>
2421 2420
2422Além dos [campos de entrada comuns](#common-input-fields), os hooks PermissionDenied recebem `tool_name`, `tool_input`, `tool_use_id` e `reason`. Para uma ferramenta MCP, eles também recebem o objeto [`mcp_server`](#pretooluse-input).2421Além dos [campos de entrada comuns](#common-input-fields), os hooks PermissionDenied recebem `tool_name`, `tool_input`, `tool_use_id` e `reason`. Para uma ferramenta MCP, eles também recebem o objeto [`mcp_server`](#pretooluse-input).
2440 2439
2441| Campo | Descrição |2440| Campo | Descrição |
2442| :- | :- |2441| :- | :- |
2443| `reason` | O motivo da negação. Para um veredito do classificador, na maioria das sessões ele nomeia a regra correspondente entre colchetes, como `[Data Exfiltration]`; consulte [Revisar negações](/docs/pt/auto-mode-config#review-denials) para as outras formas. Para uma [negação sem veredito](#permissiondenied-decision-control), ele começa com `Auto mode could not evaluate this action and is blocking it for safety`. Para uma negação porque o modelo classificador estava indisponível, é o texto fixo `Classifier unavailable` |2442| `reason` | O motivo da negação. Para um veredito do classificador, na maioria das sessões ele nomeia a regra correspondente entre colchetes, como `[Data Exfiltration]`; consulte [Revisar negações](/docs/pt/auto-mode-config#review-denials) para as outras formas. Para uma [negação sem veredito](#permissiondenied-decision-control), ele começa com `Auto mode could not evaluate this action and is blocking it for safety`. Para uma negação porque o modelo do classificador estava indisponível, é o texto fixo `Classifier unavailable` |
2444 2443
2445<h4 id="permissiondenied-decision-control">2444<h4 id="permissiondenied-decision-control">
2446 Controle de decisão do PermissionDenied2445 Controle de decisão de PermissionDenied
2447</h4>2446</h4>
2448 2447
2449Os hooks PermissionDenied podem informar ao modelo que ele pode tentar novamente a chamada de ferramenta negada. Retorne um objeto JSON com `hookSpecificOutput.retry` definido como `true`:2448Os hooks PermissionDenied podem informar ao modelo que ele pode tentar novamente a chamada de ferramenta negada. Retorne um objeto JSON com `hookSpecificOutput.retry` definido como `true`:
2457}2456}
2458```2457```
2459 2458
2460Quando `retry` é `true`, o Claude Code adiciona uma mensagem à conversa informando ao modelo que ele pode tentar novamente a chamada de ferramenta. O próprio Claude Code não reverte a negação. Se o seu hook não retornar JSON, ou retornar `retry: false`, a negação se mantém e o modelo recebe a mensagem de rejeição original.2459Quando `retry` é `true`, o Claude Code adiciona uma mensagem à conversa informando ao modelo que ele pode tentar novamente a chamada de ferramenta. O Claude Code não reverte a negação em si. Se o seu hook não retornar JSON, ou retornar `retry: false`, a negação permanece e o modelo recebe a mensagem de rejeição original.
2461 2460
2462O Claude Code ignora `retry: true` quando o classificador não produziu [nenhum veredito sobre a ação](/docs/pt/errors#auto-mode-cannot-determine-the-safety-of-an-action): sua resposta não pôde ser analisada, ou uma verificação de segurança separada do modo auto recusou a própria requisição do classificador. Para essas negações, o Claude Code já informa ao modelo, na mensagem de rejeição, se deve tentar novamente mais tarde ou seguir em frente.2461O Claude Code ignora `retry: true` quando o classificador não produziu [nenhum veredito sobre a ação](/docs/pt/errors#auto-mode-cannot-determine-the-safety-of-an-action): sua resposta não pôde ser analisada, ou uma verificação de segurança separada do modo auto recusou a própria requisição do classificador. Para essas negações, o Claude Code já informa ao modelo, na mensagem de rejeição, se deve tentar novamente mais tarde ou seguir em frente.
2463 2462
2471 2470
2472| Matcher | Quando é disparado |2471| Matcher | Quando é disparado |
2473| :- | :- |2472| :- | :- |
2474| `permission_prompt` | O Claude precisa que você aprove o uso de uma ferramenta ou uma [requisição de rede](/docs/pt/sandboxing#network-isolation) de um comando em sandbox, e o prompt está aguardando há cerca de seis segundos |2473| `permission_prompt` | O Claude precisa que você aprove o uso de uma ferramenta ou a [requisição de rede](/docs/pt/sandboxing#network-isolation) de um comando em sandbox, e o prompt está aguardando há cerca de seis segundos |
2475| `idle_prompt` | O Claude terminou de responder há cerca de 60 segundos e você não digitou nada desde então |2474| `idle_prompt` | O Claude terminou de responder há cerca de 60 segundos e você não digitou nada desde então |
2476| `auth_success` | A autenticação é concluída |2475| `auth_success` | A autenticação é concluída |
2477| `elicitation_dialog` | Um servidor MCP abre um formulário de elicitação e você não digitou nada por cerca de seis segundos |2476| `elicitation_dialog` | Um servidor MCP abre um formulário de elicitação e você não digita há cerca de seis segundos |
2478| `elicitation_url_dialog` | Um servidor MCP pede que você abra uma URL no navegador e você não digitou nada por cerca de seis segundos |2477| `elicitation_url_dialog` | Um servidor MCP pede que você abra uma URL no navegador e você não digita há cerca de seis segundos |
2479| `elicitation_complete` | Um servidor MCP informa que uma [elicitação no modo URL](#elicitation-input) foi concluída |2478| `elicitation_complete` | Um servidor MCP informa que uma [elicitação no modo URL](#elicitation-input) foi concluída |
2480| `elicitation_response` | Uma resposta de elicitação MCP é enviada de volta ao servidor |2479| `elicitation_response` | Uma resposta de elicitação MCP é enviada de volta ao servidor |
2481| `agent_needs_input` | Uma sessão em segundo plano começa a aguardar sua entrada enquanto a [visualização de agentes](/docs/pt/agent-view) está aberta em um terminal. Também é disparado quando uma sessão de terminal mostra a você uma [pergunta de configuração de terminal de um colega de equipe de agentes](/docs/pt/agent-teams#choose-a-display-mode) ou o aviso do modo auto sobre [cobranças por requisições do classificador](/docs/pt/auto-mode-classifier-billing) e você não digitou nada por cerca de seis segundos |2480| `agent_needs_input` | Uma sessão em segundo plano começa a aguardar sua entrada enquanto a [visualização de agentes](/docs/pt/agent-view) está aberta em um terminal. Também é disparado quando uma sessão de terminal mostra a você uma [pergunta de configuração de terminal de um colega de uma equipe de agentes](/docs/pt/agent-teams#choose-a-display-mode) ou o aviso do modo auto sobre [cobranças de requisições do classificador](/docs/pt/auto-mode-classifier-billing) e você não digita há cerca de seis segundos |
2482| `agent_completed` | Uma sessão em segundo plano termina ou falha. É disparado somente enquanto a [visualização de agentes](/docs/pt/agent-view) está aberta em um terminal |2481| `agent_completed` | Uma sessão em segundo plano termina ou falha. É disparado somente enquanto a [visualização de agentes](/docs/pt/agent-view) está aberta em um terminal |
2483| `quota_auto_resume_fired` | O Claude Code continua sua tarefa depois que um limite de uso do claude.ai a pausou: na redefinição, ou antes quando algo que você faz no Claude Code durante a espera, como adicionar créditos de uso, fazer upgrade do seu plano ou trocar de modelo, torna o uso disponível novamente, com a [exceção da configuração de modelo](/docs/pt/interactive-mode#wait-for-a-usage-limit-to-reset) |2482| `quota_auto_resume_fired` | O Claude Code continua sua tarefa depois que um limite de uso do claude.ai a pausou: no momento da redefinição, ou antes disso quando algo que você faz no Claude Code durante a espera, como adicionar créditos de uso, fazer upgrade do seu plano ou trocar de modelo, torna o uso disponível novamente, com a [exceção da configuração de modelo](/docs/pt/interactive-mode#wait-for-a-usage-limit-to-reset) |
2484| `quota_auto_resume_stale` | Um limite de uso do claude.ai foi redefinido enquanto seu computador estava em suspensão por mais de cerca de 30 minutos. O Claude Code aguarda você pressionar `Enter` em vez de continuar. Após uma suspensão mais curta, ele continua e dispara `quota_auto_resume_fired` |2483| `quota_auto_resume_stale` | Um limite de uso do claude.ai foi redefinido enquanto seu computador ficou em suspensão por mais de cerca de 30 minutos. O Claude Code aguarda que você pressione `Enter` em vez de continuar. Após uma suspensão mais curta, ele continua e dispara `quota_auto_resume_fired` em vez disso |
2485| `quota_auto_resume_disabled` | O Claude Code encerra sua espera por um limite de uso do claude.ai sem continuar sua tarefa: [`autoContinueAtUsageLimit`](/docs/pt/settings-reference#autocontinueatusagelimit) foi desativado ou a redefinição passou para mais de 24 horas adiante durante uma espera que o Claude Code iniciou por conta própria, a tarefa continuada continuou atingindo o limite, ou a continuação foi bloqueada antes de chegar ao modelo. Não é disparado quando você pressiona `Esc` ou `Ctrl+C`, ou escolhe **Don't continue automatically** |2484| `quota_auto_resume_disabled` | O Claude Code encerra a espera por um limite de uso do claude.ai sem continuar sua tarefa: [`autoContinueAtUsageLimit`](/docs/pt/settings-reference#autocontinueatusagelimit) foi desativado ou a redefinição foi adiada para mais de 24 horas durante uma espera que o Claude Code iniciou por conta própria, a tarefa continuada continuou atingindo o limite, ou a continuação foi bloqueada antes de chegar ao modelo. Não é disparado quando você pressiona `Esc` ou `Ctrl+C`, ou escolhe **Don't continue automatically** |
2486 2485
2487Os tipos `quota_auto_resume_fired`, `quota_auto_resume_stale` e `quota_auto_resume_disabled` requerem Claude Code v2.1.234 ou posterior.2486Os tipos `quota_auto_resume_fired`, `quota_auto_resume_stale` e `quota_auto_resume_disabled` requerem Claude Code v2.1.234 ou posterior.
2488 2487
2489Em sessões de terminal, `permission_prompt` para a requisição de rede de um comando em sandbox requer Claude Code v2.1.246 ou posterior.2488Em sessões de terminal, `permission_prompt` para a requisição de rede de um comando em sandbox requer Claude Code v2.1.246 ou posterior.
2490 2489
2491`agent_needs_input` para a pergunta de configuração de terminal de um colega de equipe requer Claude Code v2.1.248 ou posterior.2490`agent_needs_input` para a pergunta de configuração de terminal de um colega requer Claude Code v2.1.248 ou posterior.
2492 2491
2493<Note>2492<Note>
2494 Os tipos `permission_prompt`, `idle_prompt`, `elicitation_dialog` e `elicitation_url_dialog` compartilham seu tempo com as notificações da área de trabalho, portanto, em sessões de terminal, você só os vê quando parece estar longe do terminal:2493 Os tipos `permission_prompt`, `idle_prompt`, `elicitation_dialog` e `elicitation_url_dialog` compartilham o tempo com as notificações da área de trabalho, então, em sessões de terminal, você só os vê quando parece estar longe do terminal:
2495 2494
2496 * Espere `permission_prompt` quando você não tiver digitado nada por cerca de seis segundos. O temporizador começa quando o prompt de permissão aparece, e cada tecla pressionada o adia. Para executar um hook imediatamente quando o Claude pede permissão para usar uma ferramenta, use [PermissionRequest](#permissionrequest).2495 * Espere `permission_prompt` quando você não digitar por cerca de seis segundos. O temporizador começa quando o prompt de permissão aparece, e cada tecla pressionada o adia. Para executar um hook imediatamente quando o Claude pedir permissão para usar uma ferramenta, use [PermissionRequest](#permissionrequest) em vez disso.
2497 * Espere `idle_prompt` cerca de 60 segundos depois que o Claude terminar de responder, e somente se você não tiver digitado nada desde então e nenhum agente em segundo plano, como um [subagente](/docs/pt/sub-agents) em segundo plano, ainda estiver em execução. O Claude Code não envia `idle_prompt` enquanto aguarda a redefinição de um limite de uso do claude.ai. Quando a espera termina por conta própria, um dos tipos `quota_auto_resume_*` é disparado.2496 * Espere `idle_prompt` cerca de 60 segundos depois que o Claude terminar de responder, e somente se você não tiver digitado desde então e nenhum agente em segundo plano, como um [subagente](/docs/pt/sub-agents) em segundo plano, ainda estiver em execução. O Claude Code não envia `idle_prompt` enquanto aguarda a redefinição de um limite de uso do claude.ai. Quando a espera termina por conta própria, um dos tipos `quota_auto_resume_*` é disparado em vez disso.
2498 * Espere `elicitation_dialog` para um formulário de elicitação, ou `elicitation_url_dialog` para uma solicitação de URL do navegador, quando você não tiver digitado nada por cerca de seis segundos. Ambos compartilham o mesmo limite de seis segundos de `permission_prompt`: o temporizador começa quando a caixa de diálogo aparece, e cada tecla pressionada o adia.2497 * Espere `elicitation_dialog` para um formulário de elicitação, ou `elicitation_url_dialog` para uma solicitação de URL no navegador, quando você não digitar por cerca de seis segundos. Ambos compartilham o mesmo limite de seis segundos que `permission_prompt`: o temporizador começa quando a caixa de diálogo aparece, e cada tecla pressionada o adia.
2499 2498
2500 Uma solicitação de permissão ou elicitação que chega enquanto outra caixa de diálogo está na tela mantém o mesmo limite de seis segundos, contado a partir da chegada da solicitação. Sua notificação pode chegar até você enquanto a solicitação ainda aguarda atrás da caixa de diálogo aberta.2499 Uma solicitação de permissão ou elicitação que chega enquanto outra caixa de diálogo está na tela mantém o mesmo limite de seis segundos, contado a partir da chegada da solicitação. Sua notificação pode chegar até você enquanto a solicitação ainda aguarda atrás da caixa de diálogo aberta.
2501</Note>2500</Note>
2502 2501
2503O Claude Code cronometra `permission_prompt` de forma diferente em sessões nas quais envia solicitações de permissão ao [callback `canUseTool`](/docs/pt/agent-sdk/user-input) do Agent SDK, que é como o Claude Desktop e a extensão do VS Code hospedam o Claude Code:2502O Claude Code temporiza `permission_prompt` de forma diferente em sessões nas quais envia solicitações de permissão ao [callback `canUseTool`](/docs/pt/agent-sdk/user-input) do Agent SDK, que é como o Claude Desktop e a extensão do VS Code hospedam o Claude Code:
2504 2503
2505* Espere `permission_prompt` cerca de seis segundos depois que o Claude pede permissão. O Claude Code não o adia enquanto você digita.2504* Espere `permission_prompt` cerca de seis segundos depois que o Claude pedir permissão. O Claude Code não o adia enquanto você digita.
2506* Se você ou um hook [PermissionRequest](#permissionrequest) responder antes, o Claude Code não executa `permission_prompt`.2505* Se você ou um hook [PermissionRequest](#permissionrequest) responder antes, o Claude Code não executa `permission_prompt`.
2507* Defina [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/pt/env-vars) como `1` para desativar `permission_prompt` nessas sessões.2506* Defina [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/pt/env-vars) como `1` para desativar `permission_prompt` nessas sessões.
2508 2507
2538```2537```
2539 2538
2540<h4 id="notification-input">2539<h4 id="notification-input">
2541 Entrada do Notification2540 Entrada de Notification
2542</h4>2541</h4>
2543 2542
2544Além dos [campos de entrada comuns](#common-input-fields), os hooks Notification recebem `message` com o texto da notificação, um `title` opcional e `notification_type` indicando qual tipo foi disparado.2543Além dos [campos de entrada comuns](#common-input-fields), os hooks Notification recebem `message` com o texto da notificação, um `title` opcional e `notification_type`, que indica qual tipo foi disparado.
2545 2544
2546```json theme={null}2545```json theme={null}
2547{2546{
2555}2554}
2556```2555```
2557 2556
2558Os hooks Notification não podem bloquear nem modificar notificações. O Claude Code descarta seus campos `systemMessage` e `continue`, mas ainda emite [`terminalSequence`](#emit-terminal-notifications), que é o que o exemplo de notificação da área de trabalho utiliza. Os hooks Notification destinam-se a efeitos colaterais, como encaminhar a notificação para um serviço externo.2557Os hooks Notification não podem bloquear nem modificar notificações. O Claude Code descarta seus campos `systemMessage` e `continue`, mas ainda emite [`terminalSequence`](#emit-terminal-notifications), que é o recurso em que o exemplo de notificação da área de trabalho se baseia. Os hooks Notification destinam-se a efeitos colaterais, como encaminhar a notificação a um serviço externo.
2559 2558
2560<h3 id="subagentstart">2559<h3 id="subagentstart">
2561 SubagentStart2560 SubagentStart
2562</h3>2561</h3>
2563 2562
2564É executado quando o Claude cria um subagente com a ferramenta Agent, quando o Claude [retoma um subagente](/docs/pt/sub-agents#resume-subagents) e sempre que um colega de uma [equipe de agentes](/docs/pt/agent-teams) in-process processa uma nova mensagem. Suporta matchers para filtrar pelo nome do tipo de agente. Para agentes integrados, é o nome do agente, como `general-purpose`, `Explore` ou `Plan`. Para [subagentes personalizados](/docs/pt/sub-agents), é o campo `name` do frontmatter do agente, não o nome do arquivo.2563É executado quando o Claude cria um subagente com a ferramenta Agent, quando o Claude [retoma um subagente](/docs/pt/sub-agents#resume-subagents) e sempre que um colega em processo de uma [equipe de agentes](/docs/pt/agent-teams) processa uma nova mensagem. Oferece suporte a matchers para filtrar pelo nome do tipo de agente. Para agentes integrados, é o nome do agente, como `general-purpose`, `Explore` ou `Plan`. Para [subagentes personalizados](/docs/pt/sub-agents), é o campo `name` do frontmatter do agente, não o nome do arquivo.
2565 2564
2566Para subagentes fornecidos por um [plugin](/docs/pt/plugins/overview), o tipo de agente é o identificador com escopo de plugin, como `my-plugin:reviewer`, não o nome simples do frontmatter. Os dois-pontos colocam um nome com escopo de plugin no caminho de expressão regular, portanto ancore o matcher com `^` e `$` para uma correspondência exata: `^my-plugin:reviewer$`.2565Para subagentes distribuídos por um [plugin](/docs/pt/plugins/overview), o tipo de agente é o identificador com escopo de plugin, como `my-plugin:reviewer`, e não o nome simples do frontmatter. Os dois-pontos colocam um nome com escopo de plugin no caminho de expressão regular, então ancore o matcher com `^` e `$` para uma correspondência exata: `^my-plugin:reviewer$`.
2567 2566
2568<h4 id="subagentstart-input">2567<h4 id="subagentstart-input">
2569 Entrada do SubagentStart2568 Entrada de SubagentStart
2570</h4>2569</h4>
2571 2570
2572Além dos [campos de entrada comuns](#common-input-fields), os hooks SubagentStart recebem `agent_id` com o identificador único do subagente e `agent_type` com o nome do agente pelo qual o matcher filtra.2571Além dos [campos de entrada comuns](#common-input-fields), os hooks SubagentStart recebem `agent_id` com o identificador exclusivo do subagente e `agent_type` com o nome do agente pelo qual o matcher filtra.
2573 2572
2574```json theme={null}2573```json theme={null}
2575{2574{
2586 2585
2587| Campo | Descrição |2586| Campo | Descrição |
2588| :- | :- |2587| :- | :- |
2589| `additionalContext` | String adicionada ao contexto do subagente no início de sua conversa, antes de seu primeiro prompt. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |2588| `additionalContext` | String adicionada ao contexto do subagente no início de sua conversa, antes do seu primeiro prompt. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |
2590 2589
2591```json theme={null}2590```json theme={null}
2592{2591{
2597}2596}
2598```2597```
2599 2598
2600Quando o hook é executado novamente para o mesmo subagente, o Claude Code injeta o contexto retornado somente quando o contexto do subagente ainda não contém a cópia de uma execução anterior. A cópia injetada na inicialização permanece no lugar, mantendo intacto o [cache de prompt](/docs/pt/prompt-caching#subagents-and-the-cache) do subagente. Depois que a [compactação automática](/docs/pt/sub-agents#auto-compaction) descarta essa cópia, o Claude Code injeta novamente o contexto da próxima execução.2599Quando o hook é executado novamente para o mesmo subagente, o Claude Code injeta o contexto retornado somente quando o contexto do subagente ainda não contém a cópia de uma execução anterior. A cópia injetada na inicialização permanece no lugar, mantendo intacto o [cache de prompt](/docs/pt/prompt-caching#subagents-and-the-cache) do subagente. Depois que a [compactação automática](/docs/pt/sub-agents#auto-compaction) descarta essa cópia, o Claude Code injeta novamente o contexto da execução seguinte.
2601 2600
2602<h3 id="subagentstop">2601<h3 id="subagentstop">
2603 SubagentStop2602 SubagentStop
2606É executado quando um subagente do Claude Code termina de responder. Faz correspondência pelo tipo de agente, com os mesmos valores de SubagentStart.2605É executado quando um subagente do Claude Code termina de responder. Faz correspondência pelo tipo de agente, com os mesmos valores de SubagentStart.
2607 2606
2608<h4 id="subagentstop-input">2607<h4 id="subagentstop-input">
2609 Entrada do SubagentStop2608 Entrada de SubagentStop
2610</h4>2609</h4>
2611 2610
2612Além dos [campos de entrada comuns](#common-input-fields), os hooks SubagentStop recebem `stop_hook_active`, `agent_id`, `agent_type`, `agent_transcript_path` e `last_assistant_message`. O campo `agent_type` é o valor usado para a filtragem do matcher. O `transcript_path` é a transcrição da sessão principal, enquanto `agent_transcript_path` é a transcrição do próprio subagente, armazenada em uma pasta aninhada `subagents/`. O campo `last_assistant_message` contém o conteúdo de texto da resposta final do subagente, para que os hooks possam acessá-lo sem analisar o arquivo de transcrição.2611Além dos [campos de entrada comuns](#common-input-fields), os hooks SubagentStop recebem `stop_hook_active`, `agent_id`, `agent_type`, `agent_transcript_path` e `last_assistant_message`. O campo `agent_type` é o valor usado para a filtragem do matcher. O `transcript_path` é a transcrição da sessão principal, enquanto `agent_transcript_path` é a transcrição do próprio subagente, armazenada em uma pasta aninhada `subagents/`. O campo `last_assistant_message` contém o conteúdo de texto da resposta final do subagente, para que os hooks possam acessá-lo sem analisar o arquivo de transcrição.
2613 2612
2614Nem todo evento SubagentStop vem de um subagente criado pelo Claude. O Claude Code também executa agentes internos para alguns de seus próprios recursos, como [sugestões de prompt](/docs/pt/interactive-mode#prompt-suggestions) e [perguntas paralelas com `/btw`](/docs/pt/interactive-mode#side-questions-with-%2Fbtw), e o SubagentStop também é disparado quando um deles termina. Para esses eventos, `agent_type` é o nome do agente com o qual a própria sessão é executada, como um definido com [`--agent`](/docs/pt/cli-reference#cli-flags) ou com a [configuração `agent`](/docs/pt/settings-reference#agent), e uma string vazia quando a sessão é executada sem um.2613Nem todo evento SubagentStop vem de um subagente criado pelo Claude. O Claude Code também executa agentes internos para alguns de seus próprios recursos, como [sugestões de prompt](/docs/pt/interactive-mode#prompt-suggestions) e [perguntas paralelas com `/btw`](/docs/pt/interactive-mode#side-questions-with-%2Fbtw), e SubagentStop também é disparado quando um deles termina. Para esses eventos, `agent_type` é o nome do agente com o qual a própria sessão é executada, como um definido com [`--agent`](/docs/pt/cli-reference#cli-flags) ou com a [configuração `agent`](/docs/pt/settings-reference#agent), e uma string vazia quando a sessão é executada sem um.
2615 2614
2616Um `matcher` que nomeia tipos de agente não corresponde a um `agent_type` vazio. Um hook cujo matcher é omitido, `""` ou `"*"`, ou é uma expressão regular que corresponde a uma string vazia, também é executado para eventos com `agent_type` vazio.2615Um `matcher` que nomeia tipos de agente não corresponde a um `agent_type` vazio. Um hook cujo matcher é omitido, `""` ou `"*"`, ou é uma expressão regular que corresponde a uma string vazia, também é executado para eventos com `agent_type` vazio.
2617 2616
2618No Claude Code v2.1.271 ou posterior, um subagente executado com a ferramenta [`SubagentHandback`](/docs/pt/tools-reference) entrega seu relatório por meio dessa ferramenta antes de parar. O campo `last_assistant_message` passa então a conter o texto final do subagente, se houver, que não é o relatório entregue. O relatório é a entrada `message` dessa chamada, que um hook `PreToolUse` ou `PostToolUse` com correspondência em `SubagentHandback` recebe como `tool_input.message`.2617No Claude Code v2.1.271 ou posterior, um subagente que é executado com a ferramenta [`SubagentHandback`](/docs/pt/tools-reference) entrega seu relatório por meio dessa ferramenta antes de parar. O campo `last_assistant_message` então contém o texto final do subagente, se houver, que não é o relatório entregue. O relatório é a entrada `message` dessa chamada, que um hook `PreToolUse` ou `PostToolUse` com correspondência em `SubagentHandback` recebe como `tool_input.message`.
2619 2618
2620Os hooks SubagentStop também recebem os arrays `background_tasks` e `session_crons` descritos em [Entrada do Stop](#stop-input). Ambos os arrays têm escopo na sessão pai, não no subagente.2619Os hooks SubagentStop também recebem os arrays `background_tasks` e `session_crons` descritos em [Entrada de Stop](#stop-input). Ambos os arrays têm escopo na sessão pai, não no subagente.
2621 2620
2622```json theme={null}2621```json theme={null}
2623{2622{
2636}2635}
2637```2636```
2638 2637
2639Os hooks SubagentStop usam o mesmo formato de controle de decisão dos [hooks Stop](#stop-decision-control), incluindo `hookSpecificOutput.additionalContext` com `hookEventName` definido como `"SubagentStop"`, para feedback que não é de erro e que mantém o subagente em execução. Retornar `decision: "block"` com um `reason` mantém o subagente em execução e entrega `reason` ao subagente como sua próxima instrução. Um hook que bloqueia saindo com código 2 entrega sua mensagem de stderr da mesma forma. Para injetar contexto na sessão pai depois que um subagente retorna, use um hook [`PostToolUse`](#posttooluse) na ferramenta `Agent`.2638Os hooks SubagentStop usam o mesmo formato de controle de decisão que os [hooks Stop](#stop-decision-control), incluindo `hookSpecificOutput.additionalContext` com `hookEventName` definido como `"SubagentStop"`, para feedback sem erro que mantém o subagente em execução. Retornar `decision: "block"` com um `reason` mantém o subagente em execução e entrega `reason` ao subagente como sua próxima instrução. Um hook que bloqueia saindo com código 2 entrega sua mensagem de stderr da mesma forma. Para injetar contexto na sessão pai depois que um subagente retorna, use um hook [`PostToolUse`](#posttooluse) na ferramenta `Agent`.
2640 2639
2641<h3 id="taskcreated">2640<h3 id="taskcreated">
2642 TaskCreated2641 TaskCreated
2644 2643
2645É executado quando uma tarefa está sendo criada por meio da ferramenta `TaskCreate`. Use-o para impor convenções de nomenclatura, exigir descrições de tarefas ou impedir que determinadas tarefas sejam criadas. Em uma [sessão sem as ferramentas Task](/docs/pt/tools-reference#task-tool-availability), este evento não é disparado.2644É executado quando uma tarefa está sendo criada por meio da ferramenta `TaskCreate`. Use-o para impor convenções de nomenclatura, exigir descrições de tarefas ou impedir que determinadas tarefas sejam criadas. Em uma [sessão sem as ferramentas Task](/docs/pt/tools-reference#task-tool-availability), este evento não é disparado.
2646 2645
2647Os hooks TaskCreated não suportam matchers e são disparados em todas as ocorrências.2646Os hooks TaskCreated não oferecem suporte a matchers e são disparados em todas as ocorrências.
2648 2647
2649<h4 id="taskcreated-input">2648<h4 id="taskcreated-input">
2650 Entrada do TaskCreated2649 Entrada de TaskCreated
2651</h4>2650</h4>
2652 2651
2653Além dos [campos de entrada comuns](#common-input-fields), os hooks TaskCreated recebem `task_id`, `task_subject` e, opcionalmente, `task_description`, `teammate_name` e `team_name`.2652Além dos [campos de entrada comuns](#common-input-fields), os hooks TaskCreated recebem `task_id`, `task_subject` e, opcionalmente, `task_description`, `teammate_name` e `team_name`.
2671| `task_id` | Identificador da tarefa que está sendo criada |2670| `task_id` | Identificador da tarefa que está sendo criada |
2672| `task_subject` | Título da tarefa |2671| `task_subject` | Título da tarefa |
2673| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |2672| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |
2674| `teammate_name` | Nome do colega de equipe que está criando a tarefa. Pode estar ausente |2673| `teammate_name` | Nome do colega que está criando a tarefa. Pode estar ausente |
2675| `team_name` | Descontinuado. Nome da equipe derivado da sessão; será removido em uma versão futura |2674| `team_name` | Descontinuado. Nome da equipe derivado da sessão; será removido em uma versão futura |
2675| `agent_id` | Neste evento, o [campo de entrada comum](#common-input-fields) identifica o subagente ou o [colega em processo](/docs/pt/agent-teams#choose-a-display-mode) que está criando a tarefa. Pode estar ausente. Requer Claude Code v2.1.290 ou posterior |
2676 2676
2677<h4 id="taskcreated-decision-control">2677<h4 id="taskcreated-decision-control">
2678 Controle de decisão do TaskCreated2678 Controle de decisão de TaskCreated
2679</h4>2679</h4>
2680 2680
2681Um hook TaskCreated pode bloquear a criação de duas formas. Em ambos os casos, o Claude Code exclui a tarefa e retorna sua mensagem ao Claude como o erro da ferramenta. O Claude Code ignora `continue: false` deste evento e o Claude continua trabalhando.2681Um hook TaskCreated pode bloquear a criação de duas maneiras. Em ambos os casos, o Claude Code exclui a tarefa e retorna sua mensagem ao Claude como o erro da ferramenta. O Claude Code ignora `continue: false` deste evento e o Claude continua trabalhando.
2682 2682
2683* **Código de saída 2**: o Claude Code retorna o texto do stderr como a mensagem.2683* **Código de saída 2**: o Claude Code retorna o texto do stderr como a mensagem.
2684* **JSON `{"decision": "block", "reason": "..."}`**: o Claude Code retorna `reason` como a mensagem.2684* **JSON `{"decision": "block", "reason": "..."}`**: o Claude Code retorna `reason` como a mensagem.
2702 TaskCompleted2702 TaskCompleted
2703</h3>2703</h3>
2704 2704
2705É executado quando uma tarefa está sendo marcada como concluída. Isso é disparado em duas situações: quando qualquer agente marca explicitamente uma tarefa como concluída por meio da ferramenta TaskUpdate, ou quando um colega de uma [equipe de agentes](/docs/pt/agent-teams) termina seu turno com tarefas em andamento. Use-o para impor critérios de conclusão, como testes ou verificações de lint aprovados, antes que uma tarefa possa ser fechada.2705É executado quando uma tarefa está sendo marcada como concluída. Isso é disparado em duas situações: quando qualquer agente marca explicitamente uma tarefa como concluída por meio da ferramenta TaskUpdate, ou quando um colega de uma [equipe de agentes](/docs/pt/agent-teams) termina seu turno com tarefas em andamento. Use-o para impor critérios de conclusão, como testes aprovados ou verificações de lint, antes que uma tarefa possa ser fechada.
2706 2706
2707Os hooks TaskCompleted não suportam matchers e são disparados em todas as ocorrências.2707Os hooks TaskCompleted não oferecem suporte a matchers e são disparados em todas as ocorrências.
2708 2708
2709<h4 id="taskcompleted-input">2709<h4 id="taskcompleted-input">
2710 Entrada do TaskCompleted2710 Entrada de TaskCompleted
2711</h4>2711</h4>
2712 2712
2713Além dos [campos de entrada comuns](#common-input-fields), os hooks TaskCompleted recebem `task_id`, `task_subject` e, opcionalmente, `task_description`, `teammate_name` e `team_name`.2713Além dos [campos de entrada comuns](#common-input-fields), os hooks TaskCompleted recebem `task_id`, `task_subject` e, opcionalmente, `task_description`, `teammate_name` e `team_name`.
2732| `task_id` | Identificador da tarefa que está sendo concluída |2732| `task_id` | Identificador da tarefa que está sendo concluída |
2733| `task_subject` | Título da tarefa |2733| `task_subject` | Título da tarefa |
2734| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |2734| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |
2735| `teammate_name` | Nome do colega de equipe que está concluindo a tarefa. Pode estar ausente |2735| `teammate_name` | Nome do colega que está concluindo a tarefa. Pode estar ausente |
2736| `team_name` | Descontinuado. Nome da equipe derivado da sessão; será removido em uma versão futura |2736| `team_name` | Descontinuado. Nome da equipe derivado da sessão; será removido em uma versão futura |
2737| `agent_id` | Neste evento, o [campo de entrada comum](#common-input-fields) identifica o subagente ou o [colega em processo](/docs/pt/agent-teams#choose-a-display-mode) que está concluindo a tarefa. Pode estar ausente. Requer Claude Code v2.1.290 ou posterior |
2737 2738
2738<h4 id="taskcompleted-decision-control">2739<h4 id="taskcompleted-decision-control">
2739 Controle de decisão do TaskCompleted2740 Controle de decisão de TaskCompleted
2740</h4>2741</h4>
2741 2742
2742Os hooks TaskCompleted suportam duas formas de controlar a conclusão de tarefas:2743Os hooks TaskCompleted oferecem duas formas de controlar a conclusão de tarefas:
2743 2744
2744* **Código de saída 2**: a tarefa não é marcada como concluída e a mensagem de stderr é devolvida ao modelo como feedback.2745* **Código de saída 2**: a tarefa não é marcada como concluída e a mensagem do stderr é enviada de volta ao modelo como feedback.
2745* **JSON `{"continue": false, "stopReason": "..."}`**: quando um colega de equipe que termina seu turno acionou o evento, interrompe o colega completamente, correspondendo ao comportamento do hook `Stop`. O `stopReason` é mostrado ao usuário. Quando a ferramenta `TaskUpdate` acionou o evento, o Claude Code ignora `continue: false`; o código de saída 2 ainda bloqueia a conclusão.2746* **JSON `{"continue": false, "stopReason": "..."}`**: quando um colega terminando seu turno acionou o evento, interrompe o colega completamente, correspondendo ao comportamento do hook `Stop`. O `stopReason` é mostrado ao usuário. Quando a ferramenta `TaskUpdate` acionou o evento, o Claude Code ignora `continue: false`; o código de saída 2 ainda bloqueia a conclusão.
2746 2747
2747Este exemplo executa testes e bloqueia a conclusão da tarefa se eles falharem:2748Este exemplo executa testes e bloqueia a conclusão da tarefa se eles falharem:
2748 2749
2769[StopFailure](#stopfailure) em vez disso.2770[StopFailure](#stopfailure) em vez disso.
2770 2771
2771<Tip>2772<Tip>
2772 O comando [`/goal`](/docs/pt/goal) é um atalho integrado para um hook Stop baseado em prompt com escopo de sessão. Use-o quando quiser que o Claude continue trabalhando em direção a uma condição sem escrever a configuração do hook.2773 O comando [`/goal`](/docs/pt/goal) é um atalho integrado para um hook Stop baseado em prompt com escopo de sessão. Use-o quando quiser que o Claude continue trabalhando em direção a uma condição sem escrever uma configuração de hook.
2773</Tip>2774</Tip>
2774 2775
2775<h4 id="stop-input">2776<h4 id="stop-input">
2776 Entrada do Stop2777 Entrada de Stop
2777</h4>2778</h4>
2778 2779
2779Alé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 o Claude Code já está continuando como resultado de um hook de parada. Verifique esse valor ou processe a transcrição para evitar bloquear em uma condição que nunca será resolvida.2780Além dos [campos de entrada comuns](#common-input-fields), os hooks Stop recebem `stop_hook_active`, `last_assistant_message`, `background_tasks` e `session_crons`. O campo `stop_hook_active` é `true` quando o Claude Code já está continuando como resultado de um hook de parada. Verifique esse valor ou processe a transcrição para evitar bloquear com base em uma condição que nunca será resolvida.
2780 2781
2781O Claude Code aplica um limite de 8 continuações consecutivas: depois que os hooks de parada continuaram o turno oito vezes seguidas, o Claude Code sobrescreve o próximo bloqueio e encerra o turno. A contagem de continuações consecutivas é redefinida cada vez que o Claude chama uma ferramenta. Para aumentar o limite, defina [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/pt/env-vars).2782O Claude Code aplica um limite de 8 continuações consecutivas: depois que os hooks de parada continuarem o turno oito vezes seguidas, o Claude Code sobrescreve o próximo bloqueio e encerra o turno. A contagem de continuações consecutivas é redefinida sempre que o Claude chama uma ferramenta. Para aumentar o limite, defina [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/pt/env-vars).
2782 2783
2783O campo `last_assistant_message` contém o conteúdo de texto da resposta final do Claude, para que os hooks possam acessá-lo sem analisar o arquivo de transcrição. Para hooks que atuam sobre o turno recém-concluído, como hooks de leitura em voz alta ou de notificação, use este campo em vez de ler `transcript_path`: não há garantia de que o arquivo de transcrição inclua a mensagem final no momento do Stop em todas as versões.2784O campo `last_assistant_message` contém o conteúdo de texto da resposta final do Claude, para que os hooks possam acessá-lo sem analisar o arquivo de transcrição. Para hooks que atuam sobre o turno recém-concluído, como hooks de leitura em voz alta ou de notificação, use este campo em vez de ler `transcript_path`: não há garantia de que o arquivo de transcrição inclua a mensagem final no momento do Stop em todas as versões.
2784 2785
2785Os arrays `background_tasks` e `session_crons` permitem que os hooks distingam "a sessão terminou" de "a sessão está pausada aguardando que um trabalho em segundo plano a desperte novamente". Ambos os arrays estão presentes quando o registro de tarefas está acessível e ficam vazios quando não há nada em andamento ou agendado.2786Os arrays `background_tasks` e `session_crons` permitem que os hooks distingam entre "a sessão terminou" e "a sessão está pausada aguardando que um trabalho em segundo plano a desperte novamente". Ambos os arrays estão presentes quando o registro de tarefas está acessível e ficam vazios quando nada está em andamento ou agendado.
2786 2787
2787Cada entrada em `background_tasks` descreve uma tarefa em andamento e usa estes campos:2788Cada entrada em `background_tasks` descreve uma tarefa em andamento e usa estes campos:
2788 2789
2791| `id` | Identificador da tarefa |2792| `id` | Identificador da tarefa |
2792| `type` | Rótulo amigável do tipo de tarefa, como `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session` ou `MCP task`. Cada rótulo identifica qual recurso do Claude Code criou a tarefa. Usa o discriminante bruto como alternativa para tipos não reconhecidos |2793| `type` | Rótulo amigável do tipo de tarefa, como `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session` ou `MCP task`. Cada rótulo identifica qual recurso do Claude Code criou a tarefa. Usa o discriminante bruto como alternativa para tipos não reconhecidos |
2793| `status` | Status atual da tarefa |2794| `status` | Status atual da tarefa |
2794| `description` | Descrição em texto livre, limitada a 1000 caracteres com um marcador `… [+N chars]` na string quando cortada |2795| `description` | Descrição em texto livre, limitada a 1000 caracteres, com um marcador `… [+N chars]` na própria string quando cortada |
2795| `command` | Linha de comando do shell, limitada a 1000 caracteres. Presente somente para tarefas `shell` |2796| `command` | Linha de comando do shell, limitada a 1000 caracteres. Presente somente para tarefas `shell` |
2796| `agent_type` | Nome do tipo de subagente. Presente somente para tarefas `subagent` |2797| `agent_type` | Nome do tipo de subagente. Presente somente para tarefas `subagent` |
2797| `server` | Nome do servidor MCP. Presente somente para tarefas `monitor` e `MCP task` |2798| `server` | Nome do servidor MCP. Presente somente para tarefas `monitor` e `MCP task` |
2807| `recurring` | `false` para despertares únicos cujo agendamento codifica um único horário de disparo, `true` para tarefas que disparam novamente a cada correspondência |2808| `recurring` | `false` para despertares únicos cujo agendamento codifica um único horário de disparo, `true` para tarefas que disparam novamente a cada correspondência |
2808| `prompt` | Prompt enviado quando o cron é disparado, limitado a 1000 caracteres com o mesmo marcador `… [+N chars]` |2809| `prompt` | Prompt enviado quando o cron é disparado, limitado a 1000 caracteres com o mesmo marcador `… [+N chars]` |
2809 2810
2810Este exemplo mostra uma entrada de Stop com uma tarefa de shell em andamento e um cron recorrente:2811Este exemplo mostra uma entrada de Stop com uma tarefa shell em andamento e um cron recorrente:
2811 2812
2812```json theme={null}2813```json theme={null}
2813{2814{
2839```2840```
2840 2841
2841<h4 id="stop-decision-control">2842<h4 id="stop-decision-control">
2842 Controle de decisão do Stop2843 Controle de decisão de Stop
2843</h4>2844</h4>
2844 2845
2845Os hooks `Stop` e `SubagentStop` podem controlar se o Claude continua. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar estes campos específicos do evento:2846Os hooks `Stop` e `SubagentStop` podem controlar se o Claude continua. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar estes campos específicos do evento:
2848| :- | :- |2849| :- | :- |
2849| `decision` | `"block"` impede que o Claude pare. Omita para permitir que o Claude pare |2850| `decision` | `"block"` impede que o Claude pare. Omita para permitir que o Claude pare |
2850| `reason` | Obrigatório quando `decision` é `"block"`. Informa ao Claude por que ele deve continuar |2851| `reason` | Obrigatório quando `decision` é `"block"`. Informa ao Claude por que ele deve continuar |
2851| `hookSpecificOutput.additionalContext` | Feedback que não é de erro para o Claude. A conversa continua para que o Claude possa agir com base nele, mas, ao contrário de `decision: "block"`, ele é mostrado na transcrição como feedback do hook em vez de um erro do hook |2852| `hookSpecificOutput.additionalContext` | Feedback sem erro para o Claude. A conversa continua para que o Claude possa agir sobre ele, mas, diferentemente de `decision: "block"`, ele é mostrado na transcrição como feedback de hook, e não como erro de hook |
2852 2853
2853Um hook que bloqueia saindo com código 2 é encaminhado da mesma forma que `reason`: o Claude recebe a mensagem de stderr como a explicação de por que deve continuar.2854Um hook que bloqueia saindo com código 2 é encaminhado da mesma forma que `reason`: o Claude recebe a mensagem do stderr como a explicação de por que deve continuar.
2854 2855
2855```json theme={null}2856```json theme={null}
2856{2857{
2859}2860}
2860```2861```
2861 2862
2862Use `additionalContext` quando o hook está funcionando conforme projetado e fornecendo orientação ao Claude, como "execute a suíte de testes antes de terminar". Ele mantém a conversa em andamento com as mesmas proteções contra loop de `decision: "block"`, ou seja, a entrada `stop_hook_active` e o limite de 8 continuações consecutivas, mas a transcrição o rotula como `Stop hook feedback` e nenhuma notificação de erro de hook é mostrada:2863Use `additionalContext` quando o hook estiver funcionando conforme projetado e dando orientações ao Claude, como "execute o conjunto de testes antes de terminar". Ele mantém a conversa em andamento com as mesmas proteções contra loop que `decision: "block"`, ou seja, a entrada `stop_hook_active` e o limite de 8 continuações consecutivas, mas a transcrição o rotula como `Stop hook feedback` e nenhuma notificação de erro de hook é mostrada:
2863 2864
2864```json theme={null}2865```json theme={null}
2865{2866{
2874 StopFailure2875 StopFailure
2875</h3>2876</h3>
2876 2877
2877É executado em vez de [Stop](#stop) quando o turno termina devido a um erro de API. O Claude Code ignora a saída e o código de saída do hook, exceto [`terminalSequence`](#emit-terminal-notifications). Use-o para registrar falhas em log, enviar alertas ou tomar ações de recuperação quando o Claude não consegue concluir uma resposta devido a rate limits, problemas de autenticação ou outros erros de API.2878É executado em vez de [Stop](#stop) quando o turno termina devido a um erro de API. O Claude Code ignora a saída e o código de saída do hook, com exceção de [`terminalSequence`](#emit-terminal-notifications). Use-o para registrar falhas em log, enviar alertas ou tomar ações de recuperação quando o Claude não consegue concluir uma resposta devido a rate limits, problemas de autenticação ou outros erros de API.
2878 2879
2879<h4 id="stopfailure-input">2880<h4 id="stopfailure-input">
2880 Entrada do StopFailure2881 Entrada de StopFailure
2881</h4>2882</h4>
2882 2883
2883Além dos [campos de entrada comuns](#common-input-fields), os hooks StopFailure recebem `error`, `error_details` opcional e `last_assistant_message` opcional. O campo `error` identifica o tipo de erro e é usado para a filtragem do matcher.2884Além dos [campos de entrada comuns](#common-input-fields), os hooks StopFailure recebem `error`, `error_details` opcional e `last_assistant_message` opcional. O campo `error` identifica o tipo de erro e é usado para a filtragem do matcher.
2886| :- | :- |2887| :- | :- |
2887| `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` |2888| `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` |
2888| `error_details` | Detalhes adicionais sobre o erro, quando disponíveis |2889| `error_details` | Detalhes adicionais sobre o erro, quando disponíveis |
2889| `last_assistant_message` | O texto de erro renderizado mostrado na conversa. Ao contrário de `Stop` e `SubagentStop`, em que este campo contém a saída conversacional do Claude, para `StopFailure` ele contém a própria string de erro da API, como `"API Error: Rate limit reached"` |2890| `last_assistant_message` | O texto de erro renderizado mostrado na conversa. Diferentemente de `Stop` e `SubagentStop`, em que este campo contém a saída conversacional do Claude, para `StopFailure` ele contém a própria string do erro de API, como `"API Error: Rate limit reached"` |
2890 2891
2891```json theme={null}2892```json theme={null}
2892{2893{
2900}2901}
2901```2902```
2902 2903
2903Os hooks StopFailure não têm controle de decisão. Eles são executados apenas para fins de notificação e log.2904Os hooks StopFailure não têm controle de decisão. Eles são executados apenas para fins de notificação e registro em log.
2904 2905
2905<h3 id="teammateidle">2906<h3 id="teammateidle">
2906 TeammateIdle2907 TeammateIdle
2908 2909
2909É executado quando um colega de uma [equipe de agentes](/docs/pt/agent-teams) está prestes a ficar ocioso após terminar seu turno. Use-o para impor critérios de qualidade antes que um colega pare de trabalhar, como exigir verificações de lint aprovadas ou verificar se os arquivos de saída existem.2910É executado quando um colega de uma [equipe de agentes](/docs/pt/agent-teams) está prestes a ficar ocioso após terminar seu turno. Use-o para impor critérios de qualidade antes que um colega pare de trabalhar, como exigir verificações de lint aprovadas ou verificar se os arquivos de saída existem.
2910 2911
2911Os hooks TeammateIdle não suportam matchers e são disparados em todas as ocorrências.2912Os hooks TeammateIdle não oferecem suporte a matchers e são disparados em todas as ocorrências.
2912 2913
2913<h4 id="teammateidle-input">2914<h4 id="teammateidle-input">
2914 Entrada do TeammateIdle2915 Entrada de TeammateIdle
2915</h4>2916</h4>
2916 2917
2917Além dos [campos de entrada comuns](#common-input-fields), os hooks TeammateIdle recebem `teammate_name` e `team_name`.2918Além dos [campos de entrada comuns](#common-input-fields), os hooks TeammateIdle recebem `teammate_name` e `team_name`.
2930 2931
2931| Campo | Descrição |2932| Campo | Descrição |
2932| :- | :- |2933| :- | :- |
2933| `teammate_name` | Nome do colega de equipe que está prestes a ficar ocioso |2934| `teammate_name` | Nome do colega que está prestes a ficar ocioso |
2934| `team_name` | Descontinuado. Nome da equipe derivado da sessão; será removido em uma versão futura |2935| `team_name` | Descontinuado. Nome da equipe derivado da sessão; será removido em uma versão futura |
2936| `agent_id` | Neste evento, o [campo de entrada comum](#common-input-fields) identifica o [colega em processo](/docs/pt/agent-teams#choose-a-display-mode) que está prestes a ficar ocioso. Pode estar ausente. Requer Claude Code v2.1.290 ou posterior |
2935 2937
2936<h4 id="teammateidle-decision-control">2938<h4 id="teammateidle-decision-control">
2937 Controle de decisão do TeammateIdle2939 Controle de decisão de TeammateIdle
2938</h4>2940</h4>
2939 2941
2940Os hooks TeammateIdle suportam duas formas de controlar o comportamento do colega de equipe:2942Os hooks TeammateIdle oferecem duas formas de controlar o comportamento do colega:
2941 2943
2942* **Código de saída 2**: o colega recebe a mensagem de stderr como feedback e continua trabalhando em vez de ficar ocioso.2944* **Código de saída 2**: o colega recebe a mensagem do stderr como feedback e continua trabalhando em vez de ficar ocioso.
2943* **JSON `{"continue": false, "stopReason": "..."}`**: interrompe o colega completamente, correspondendo ao comportamento do hook `Stop`. O `stopReason` é mostrado ao usuário.2945* **JSON `{"continue": false, "stopReason": "..."}`**: interrompe o colega completamente, correspondendo ao comportamento do hook `Stop`. O `stopReason` é mostrado ao usuário.
2944 2946
2945Este exemplo verifica se um artefato de build existe antes de permitir que um colega fique ocioso:2947Este exemplo verifica se um artefato de build existe antes de permitir que um colega fique ocioso:
2994```2996```
2995 2997
2996<h4 id="configchange-input">2998<h4 id="configchange-input">
2997 Entrada do ConfigChange2999 Entrada de ConfigChange
2998</h4>3000</h4>
2999 3001
3000Além dos [campos de entrada comuns](#common-input-fields), os hooks ConfigChange recebem `source` e, opcionalmente, `file_path`. O campo `source` indica qual tipo de configuração mudou, e `file_path` fornece o caminho do arquivo específico que foi modificado.3002Além dos [campos de entrada comuns](#common-input-fields), os hooks ConfigChange recebem `source` e, opcionalmente, `file_path`. O campo `source` indica qual tipo de configuração mudou, e `file_path` fornece o caminho para o arquivo específico que foi modificado.
3001 3003
3002```json theme={null}3004```json theme={null}
3003{3005{
3011```3013```
3012 3014
3013<h4 id="configchange-decision-control">3015<h4 id="configchange-decision-control">
3014 Controle de decisão do ConfigChange3016 Controle de decisão de ConfigChange
3015</h4>3017</h4>
3016 3018
3017Os hooks ConfigChange podem impedir que alterações de configuração entrem em vigor. Use o código de saída 2 ou um `decision` em JSON para impedir a alteração. Quando bloqueadas, as novas configurações não são aplicadas à sessão em execução.3019Os hooks ConfigChange podem impedir que alterações de configuração entrem em vigor. Use o código de saída 2 ou uma `decision` em JSON para impedir a alteração. Quando bloqueadas, as novas configurações não são aplicadas à sessão em execução.
3018 3020
3019| Campo | Descrição |3021| Campo | Descrição |
3020| :- | :- |3022| :- | :- |
3021| `decision` | `"block"` impede que a alteração de configuração seja aplicada. Omita para permitir a alteração |3023| `decision` | `"block"` impede que a alteração de configuração seja aplicada. Omita para permitir a alteração |
3022| `reason` | Aceito, mas nunca exibido |3024| `reason` | Aceito, mas nunca mostrado |
3023 3025
3024```json theme={null}3026```json theme={null}
3025{3027{
3028}3030}
3029```3031```
3030 3032
3031As alterações de `policy_settings` não podem ser bloqueadas. Os hooks ainda são disparados para origens `policy_settings` quando um arquivo de configurações gerenciadas na máquina muda, então você pode usá-los para registrar essas edições em log, mas qualquer decisão de bloqueio é ignorada. Isso garante que as configurações gerenciadas pela empresa sempre entrem em vigor. O Claude Code não executa hooks `ConfigChange` quando [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) chegam ou são atualizadas.3033Alterações de `policy_settings` não podem ser bloqueadas. Os hooks ainda são disparados para origens `policy_settings` quando um arquivo de configurações gerenciadas na máquina muda, então você pode usá-los para registrar essas edições em log, mas qualquer decisão de bloqueio é ignorada. Isso garante que as configurações gerenciadas pela empresa sempre entrem em vigor. O Claude Code não executa hooks `ConfigChange` quando [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) chegam ou são atualizadas.
3032 3034
3033O Claude Code age com base na decisão de bloqueio da saída JSON de um hook ConfigChange e descarta `systemMessage` e `continue`. Uma alteração bloqueada não exibe nenhuma mensagem para você nem para o Claude, seja o bloqueio feito com `reason` ou com stderr no código de saída 2. O Claude Code apenas grava uma linha no log de depuração.3035O Claude Code age sobre a decisão de bloqueio da saída JSON de um hook ConfigChange e descarta `systemMessage` e `continue`. Uma alteração bloqueada não exibe nenhuma mensagem para você nem para o Claude, seja bloqueando com `reason` ou com stderr no código de saída 2. O Claude Code apenas grava uma linha no log de depuração.
3034 3036
3035<h3 id="cwdchanged">3037<h3 id="cwdchanged">
3036 CwdChanged3038 CwdChanged
3037</h3>3039</h3>
3038 3040
3039É executado quando um comando de shell na conversa principal altera o diretório de trabalho, por exemplo quando o Claude executa um comando `cd`. Use-o para reagir a mudanças de diretório: recarregar variáveis de ambiente, ativar toolchains específicas do projeto ou executar scripts de configuração automaticamente. Funciona em conjunto com [FileChanged](#filechanged) para ferramentas como [direnv](https://direnv.net/) que gerenciam o ambiente por diretório.3041É executado quando um comando de shell na conversa principal altera o diretório de trabalho, por exemplo quando o Claude executa um comando `cd`. Use-o para reagir a mudanças de diretório: recarregar variáveis de ambiente, ativar toolchains específicos do projeto ou executar scripts de configuração automaticamente. Funciona em conjunto com [FileChanged](#filechanged) para ferramentas como o [direnv](https://direnv.net/), que gerenciam o ambiente por diretório.
3040 3042
3041Os hooks CwdChanged têm acesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). As variáveis gravadas nesse arquivo persistem nos comandos Bash subsequentes até o próximo evento CwdChanged, quando o Claude Code as limpa.3043Os hooks CwdChanged têm acesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). As variáveis gravadas nesse arquivo persistem nos comandos Bash subsequentes até o próximo evento CwdChanged, quando o Claude Code as limpa.
3042 3044
3043O CwdChanged não suporta matchers e é disparado em todas as ocorrências.3045CwdChanged não oferece suporte a matchers e é disparado em todas as ocorrências.
3044 3046
3045<h4 id="cwdchanged-input">3047<h4 id="cwdchanged-input">
3046 Entrada do CwdChanged3048 Entrada de CwdChanged
3047</h4>3049</h4>
3048 3050
3049Além dos [campos de entrada comuns](#common-input-fields), os hooks CwdChanged recebem `old_cwd` e `new_cwd`.3051Além dos [campos de entrada comuns](#common-input-fields), os hooks CwdChanged recebem `old_cwd` e `new_cwd`.
3060```3062```
3061 3063
3062<h4 id="cwdchanged-output">3064<h4 id="cwdchanged-output">
3063 Saída do CwdChanged3065 Saída de CwdChanged
3064</h4>3066</h4>
3065 3067
3066Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, os hooks CwdChanged podem retornar `watchPaths` para definir dinamicamente quais caminhos de arquivo o [FileChanged](#filechanged) monitora:3068Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, os hooks CwdChanged podem retornar `watchPaths` para definir dinamicamente quais caminhos de arquivo o [FileChanged](#filechanged) observa:
3067 3069
3068| Campo | Descrição |3070| Campo | Descrição |
3069| :- | :- |3071| :- | :- |
3070| `watchPaths` | Array de caminhos absolutos. Substitui a lista de monitoramento dinâmica atual. Os caminhos da sua configuração de `matcher` são sempre monitorados. Retornar um array vazio limpa a lista dinâmica, o que é comum ao entrar em um novo diretório |3072| `watchPaths` | Array de caminhos absolutos. Substitui a lista dinâmica de observação atual. Os caminhos da sua configuração de `matcher` são sempre observados. Retornar um array vazio limpa a lista dinâmica, o que é comum ao entrar em um novo diretório |
3071 3073
3072Os hooks CwdChanged não têm controle de decisão. Eles não podem bloquear a mudança de diretório.3074Os hooks CwdChanged não têm controle de decisão. Eles não podem bloquear a mudança de diretório.
3073 3075
3074O Claude Code lê `watchPaths` e `systemMessage` da saída JSON deles e descarta `continue`. Em sessões interativas, ele mostra o `systemMessage` como uma breve notificação no terminal. A mensagem não chega ao fluxo de mensagens do SDK.3076O Claude Code lê `watchPaths` e `systemMessage` da saída JSON desses hooks e descarta `continue`. Em sessões interativas, ele mostra o `systemMessage` como uma breve notificação no terminal. A mensagem não chega ao fluxo de mensagens do SDK.
3075 3077
3076<h3 id="directoryadded">3078<h3 id="directoryadded">
3077 DirectoryAdded3079 DirectoryAdded
3078</h3>3080</h3>
3079 3081
3080É executado depois que você adiciona um diretório de trabalho no meio da sessão com o comando `/add-dir`, ou depois que um cliente SDK adiciona um com a requisição de controle `register_repo_root`. Use-o para preparar um repositório recém-adicionado, por exemplo instalando suas dependências.3082É executado depois que você adiciona um diretório de trabalho no meio da sessão com o comando `/add-dir`, ou depois que um cliente do SDK adiciona um com a requisição de controle `register_repo_root`. Use-o para preparar um repositório recém-adicionado, por exemplo instalando suas dependências.
3081 3083
3082O Claude Code não dispara este evento quando:3084O Claude Code não dispara este evento quando:
3083 3085
3084* Você passa um diretório com a flag de inicialização `--add-dir`; [SessionStart](#sessionstart) cobre esses diretórios3086* Você passa um diretório com a flag de inicialização `--add-dir`; [SessionStart](#sessionstart) cobre esses diretórios
3085* Você adiciona um diretório na aba Workspace de `/permissions`3087* Você adiciona um diretório na aba Workspace de `/permissions`
3086* Você adiciona um diretório que já é um diretório de trabalho ou está dentro de um3088* Você adiciona um diretório que já é um diretório de trabalho ou que está dentro de um
3087 3089
3088O Claude Code dispara o DirectoryAdded depois de atualizar o estado do sandbox e das permissões, então as ferramentas em sandbox já veem o novo diretório quando seu hook é executado. Os próprios comandos de hook são executados fora do sandbox.3090O Claude Code dispara DirectoryAdded depois de atualizar o estado do sandbox e das permissões, então as ferramentas em sandbox já veem o novo diretório quando seu hook é executado. Os próprios comandos do hook são executados fora do sandbox.
3089 3091
3090O Claude Code não espera pelo hook: a adição é concluída imediatamente, e o hook é executado em segundo plano com o timeout padrão de 600 segundos.3092O Claude Code não espera pelo hook: a adição é concluída imediatamente, e o hook é executado em segundo plano com o timeout padrão de 600 segundos.
3091 3093
3094| Matcher | Quando é disparado |3096| Matcher | Quando é disparado |
3095| :- | :- |3097| :- | :- |
3096| `slash_command` | Você adiciona um diretório com `/add-dir` |3098| `slash_command` | Você adiciona um diretório com `/add-dir` |
3097| `register_repo_root` | Um cliente SDK adiciona um diretório com a requisição de controle `register_repo_root` |3099| `register_repo_root` | Um cliente do SDK adiciona um diretório com a requisição de controle `register_repo_root` |
3098 3100
3099<h4 id="directoryadded-input">3101<h4 id="directoryadded-input">
3100 Entrada do DirectoryAdded3102 Entrada de DirectoryAdded
3101</h4>3103</h4>
3102 3104
3103Além dos [campos de entrada comuns](#common-input-fields), os hooks DirectoryAdded recebem `directory` e `source`.3105Além dos [campos de entrada comuns](#common-input-fields), os hooks DirectoryAdded recebem `directory` e `source`.
3105| Campo | Descrição |3107| Campo | Descrição |
3106| :- | :- |3108| :- | :- |
3107| `directory` | Caminho absoluto do diretório que foi adicionado |3109| `directory` | Caminho absoluto do diretório que foi adicionado |
3108| `source` | Como o diretório foi adicionado, `"slash_command"` para `/add-dir` ou `"register_repo_root"` para a requisição de controle do SDK |3110| `source` | Como o diretório foi adicionado: `"slash_command"` para `/add-dir` ou `"register_repo_root"` para a requisição de controle do SDK |
3109 3111
3110```json theme={null}3112```json theme={null}
3111{3113{
3118}3120}
3119```3121```
3120 3122
3121Os hooks DirectoryAdded não têm controle de decisão. Eles não podem bloquear a adição, que já foi concluída quando o hook é executado. O Claude Code descarta o campo `continue` da saída JSON deles e apresenta o restante de forma diferente conforme a origem:3123Os hooks DirectoryAdded não têm controle de decisão. Eles não podem bloquear a adição, que já foi concluída quando o hook é executado. O Claude Code descarta o campo `continue` da saída JSON desses hooks e exibe o restante de forma diferente conforme a origem:
3122 3124
3123* `slash_command`: o Claude Code entrega o `systemMessage` do hook ao Claude como contexto no próximo turno da conversa, em vez de mostrá-lo a você. Uma contagem de hooks com falha aparece na transcrição. A saída completa das falhas vai para o log de depuração3125* `slash_command`: o Claude Code entrega o `systemMessage` do hook ao Claude como contexto no próximo turno da conversa, em vez de mostrá-lo a você. Uma contagem de hooks com falha aparece na transcrição. A saída completa da falha vai para o log de depuração
3124* `register_repo_root`: o Claude Code grava a saída de `systemMessage` e a saída de falhas somente no log de depuração3126* `register_repo_root`: o Claude Code grava a saída de `systemMessage` e a saída de falhas somente no log de depuração
3125 3127
3126<h3 id="filechanged">3128<h3 id="filechanged">
3127 FileChanged3129 FileChanged
3128</h3>3130</h3>
3129 3131
3130É executado quando um arquivo monitorado muda no disco. O Claude Code detecta alterações com um monitor do sistema de arquivos, não inspecionando chamadas de ferramenta, portanto executa o hook independentemente do que alterou o arquivo: uma chamada de ferramenta `Edit` ou `Write`, um script que o Claude executa com `Bash` ou um processo totalmente fora do Claude Code. Um uso comum é recarregar variáveis de ambiente quando arquivos de configuração do projeto mudam.3132É executado quando um arquivo observado muda no disco. O Claude Code detecta mudanças com um observador do sistema de arquivos, e não inspecionando chamadas de ferramenta, então executa o hook independentemente do que alterou o arquivo: uma chamada de ferramenta `Edit` ou `Write`, um script que o Claude executa com `Bash` ou um processo totalmente fora do Claude Code. Um uso comum é recarregar variáveis de ambiente quando arquivos de configuração do projeto mudam.
3131 3133
3132O `matcher` deste evento tem duas funções:3134O `matcher` deste evento tem duas funções:
3133 3135
3134* **Construir a lista de monitoramento**: o valor é dividido em `|` e cada segmento é registrado como um nome de arquivo literal no diretório de trabalho, então `".envrc|.env"` monitora exatamente esses dois arquivos. Padrões regex não são úteis aqui: um valor como `^\.env` monitoraria um arquivo literalmente chamado `^\.env`.3136* **Construir a lista de observação**: o valor é dividido em `|` e cada segmento é registrado como um nome de arquivo literal no diretório de trabalho, então `".envrc|.env"` observa exatamente esses dois arquivos. Padrões regex não são úteis aqui: um valor como `^\.env` observaria um arquivo literalmente chamado `^\.env`.
3135* **Filtrar quais hooks são executados**: quando um arquivo monitorado muda, o mesmo valor filtra quais grupos de hooks são executados usando as [regras de matcher](#matcher-patterns) padrão em relação ao nome base do arquivo alterado.3137* **Filtrar quais hooks são executados**: quando um arquivo observado muda, o mesmo valor filtra quais grupos de hooks são executados usando as [regras de matcher](#matcher-patterns) padrão em relação ao nome base do arquivo alterado.
3136 3138
3137Este exemplo normaliza as terminações de linha em `data.csv` após qualquer alteração, incluindo um comando `Bash` ou um script externo que reescreve o arquivo:3139Este exemplo normaliza as terminações de linha em `data.csv` após qualquer alteração, incluindo um comando `Bash` ou um script externo que reescreva o arquivo:
3138 3140
3139```json theme={null}3141```json theme={null}
3140{3142{
3154}3156}
3155```3157```
3156 3158
3157O hook lê o caminho absoluto do arquivo alterado do campo `file_path` da [entrada JSON](#filechanged-input) no stdin. Sua proteção com `grep` testa a mesma coisa que o `perl` remove, um CR no final de uma linha, portanto a execução após uma normalização termina sem tocar no arquivo. Uma proteção menos rigorosa entra em loop para sempre, porque `perl -i` reescreve o arquivo mesmo quando não substitui nada, e o Claude Code executa o hook novamente após cada reescrita. Salve este script em `/path/to/normalize-line-endings.sh` e torne-o executável:3159O hook lê o caminho absoluto do arquivo alterado do campo `file_path` da [entrada JSON](#filechanged-input) no stdin. Sua verificação com `grep` testa exatamente o que o `perl` remove, um CR no final de uma linha, então a execução após uma normalização termina sem tocar no arquivo. Uma verificação mais frouxa entra em loop infinito, porque `perl -i` reescreve o arquivo mesmo quando não substitui nada e o Claude Code executa o hook novamente após cada reescrita. Salve este script em `/path/to/normalize-line-endings.sh` e torne-o executável:
3158 3160
3159```bash theme={null}3161```bash theme={null}
3160#!/bin/bash3162#!/bin/bash
3164fi3166fi
3165```3167```
3166 3168
3167Para confirmar que o hook funciona, peça ao Claude para acrescentar uma linha CRLF a `data.csv` com um comando `Bash`. O Claude Code executa o hook e o arquivo fica com terminações LF.3169Para confirmar que o hook funciona, peça ao Claude para acrescentar uma linha CRLF a `data.csv` com um comando `Bash`. O Claude Code executa o hook e o arquivo termina com terminações LF.
3168 3170
3169Para monitorar arquivos que você não pode nomear de antemão, retorne [`watchPaths`](#filechanged-output) de um hook para atualizar a lista de monitoramento dinamicamente. O Claude Code inicia o monitor somente quando algo nomeia um arquivo a ser monitorado, então inicialize a lista com um grupo FileChanged cujo matcher nomeie pelo menos um arquivo, ou com um hook [SessionStart](#sessionstart-decision-control) ou [CwdChanged](#cwdchanged) que retorne `watchPaths`. O matcher ainda filtra quais grupos de hooks são executados quando um arquivo monitorado muda, então dê ao grupo que lida com caminhos dinâmicos um matcher omitido, que corresponde a todos os arquivos monitorados e não adiciona nada à lista de monitoramento. Um matcher `"*"` também corresponde a todos os arquivos, mas o Claude Code o registra na lista de monitoramento como qualquer outro valor, como um arquivo literal chamado `*`.3171Para observar arquivos que você não consegue nomear de antemão, retorne [`watchPaths`](#filechanged-output) de um hook para atualizar a lista de observação dinamicamente. O Claude Code inicia o observador somente quando algo nomeia um arquivo a ser observado, então inicialize a lista com um grupo FileChanged cujo matcher nomeie pelo menos um arquivo, ou com um hook [SessionStart](#sessionstart-decision-control) ou [CwdChanged](#cwdchanged) que retorne `watchPaths`. O matcher ainda filtra quais grupos de hooks são executados quando um arquivo observado muda, então deixe o matcher omitido no grupo que lida com caminhos dinâmicos, o que corresponde a todo arquivo observado e não adiciona nada à lista de observação. Um matcher `"*"` também corresponde a todos os arquivos, mas o Claude Code o registra na lista de observação como qualquer outro valor, como um arquivo literal chamado `*`.
3170 3172
3171Os hooks FileChanged têm acesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). As variáveis gravadas nesse arquivo persistem nos comandos Bash subsequentes até o próximo evento [CwdChanged](#cwdchanged), quando o Claude Code as limpa.3173Os hooks FileChanged têm acesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). As variáveis gravadas nesse arquivo persistem nos comandos Bash subsequentes até o próximo evento [CwdChanged](#cwdchanged), quando o Claude Code as limpa.
3172 3174
3173<h4 id="filechanged-input">3175<h4 id="filechanged-input">
3174 Entrada do FileChanged3176 Entrada de FileChanged
3175</h4>3177</h4>
3176 3178
3177Além dos [campos de entrada comuns](#common-input-fields), os hooks FileChanged recebem `file_path` e `event`.3179Além dos [campos de entrada comuns](#common-input-fields), os hooks FileChanged recebem `file_path` e `event`.
3178 3180
3179| Campo | Descrição |3181| Campo | Descrição |
3180| :- | :- |3182| :- | :- |
3181| `file_path` | Caminho absoluto do arquivo que mudou |3183| `file_path` | Caminho absoluto para o arquivo que mudou |
3182| `event` | O que aconteceu: `"change"` para um arquivo modificado, `"add"` para um arquivo criado ou `"unlink"` para um arquivo excluído |3184| `event` | O que aconteceu: `"change"` para um arquivo modificado, `"add"` para um arquivo criado ou `"unlink"` para um arquivo excluído |
3183 3185
3184```json theme={null}3186```json theme={null}
3193```3195```
3194 3196
3195<h4 id="filechanged-output">3197<h4 id="filechanged-output">
3196 Saída do FileChanged3198 Saída de FileChanged
3197</h4>3199</h4>
3198 3200
3199Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, os hooks FileChanged podem retornar `watchPaths` para atualizar dinamicamente quais caminhos de arquivo são monitorados:3201Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, os hooks FileChanged podem retornar `watchPaths` para atualizar dinamicamente quais caminhos de arquivo são observados:
3200 3202
3201| Campo | Descrição |3203| Campo | Descrição |
3202| :- | :- |3204| :- | :- |
3203| `watchPaths` | Array de caminhos absolutos. Substitui a lista de monitoramento dinâmica atual. Os caminhos da sua configuração de `matcher` são sempre monitorados. Use isto quando seu script de hook descobrir arquivos adicionais a monitorar com base no arquivo alterado |3205| `watchPaths` | Array de caminhos absolutos. Substitui a lista dinâmica de observação atual. Os caminhos da sua configuração de `matcher` são sempre observados. Use isto quando seu script de hook descobrir arquivos adicionais a serem observados com base no arquivo alterado |
3204 3206
3205Os hooks FileChanged não têm controle de decisão. Eles não podem impedir que a alteração do arquivo ocorra.3207Os hooks FileChanged não têm controle de decisão. Eles não podem impedir que a alteração do arquivo ocorra.
3206 3208
3207O Claude Code lê `watchPaths` e `systemMessage` da saída JSON deles e descarta `continue`. Em sessões interativas, ele mostra o `systemMessage` como uma breve notificação no terminal. A mensagem não chega ao fluxo de mensagens do SDK.3209O Claude Code lê `watchPaths` e `systemMessage` da saída JSON desses hooks e descarta `continue`. Em sessões interativas, ele mostra o `systemMessage` como uma breve notificação no terminal. A mensagem não chega ao fluxo de mensagens do SDK.
3208 3210
3209<h3 id="worktreecreate">3211<h3 id="worktreecreate">
3210 WorktreeCreate3212 WorktreeCreate
3211</h3>3213</h3>
3212 3214
3213É executado quando um worktree está sendo criado, seja a partir de `claude --worktree`, de um [subagente usando `isolation: "worktree"`](/docs/pt/sub-agents#choose-the-subagent-scope) ou para uma [sessão em segundo plano](/docs/pt/agent-view#how-file-edits-are-isolated) que o Claude Code isola em seu próprio worktree. Por padrão, o Claude Code cria a cópia de trabalho isolada com `git worktree`. Configurar um hook WorktreeCreate substitui esse comportamento padrão do git, permitindo que você use um sistema de controle de versão diferente, como SVN, Perforce ou Mercurial.3215É executado quando um worktree está sendo criado, seja a partir de `claude --worktree`, de um [subagente usando `isolation: "worktree"`](/docs/pt/sub-agents#choose-the-subagent-scope), ou para uma [sessão em segundo plano](/docs/pt/agent-view#how-file-edits-are-isolated) que o Claude Code isola em seu próprio worktree. Por padrão, o Claude Code cria a cópia de trabalho isolada com `git worktree`. Configurar um hook WorktreeCreate substitui esse comportamento padrão do git, permitindo que você use um sistema de controle de versão diferente, como SVN, Perforce ou Mercurial.
3214 3216
3215Como o hook substitui o comportamento padrão por completo, [`.worktreeinclude`](/docs/pt/worktrees#copy-gitignored-files-into-worktrees) não é processado. Se você precisar copiar arquivos de configuração locais como `.env` para o novo worktree, faça isso dentro do seu script de hook.3217Como o hook substitui totalmente o comportamento padrão, o [`.worktreeinclude`](/docs/pt/worktrees#copy-gitignored-files-into-worktrees) não é processado. Se você precisar copiar arquivos de configuração locais como `.env` para o novo worktree, faça isso dentro do seu script de hook.
3216 3218
3217O hook deve retornar o caminho do diretório do worktree criado. O Claude Code usa esse caminho como o diretório de trabalho da sessão isolada. Consulte [Saída do WorktreeCreate](#worktreecreate-output) para ver como cada tipo de hook retorna o caminho.3219O hook deve retornar o caminho para o diretório do worktree criado. O Claude Code usa esse caminho como diretório de trabalho para a sessão isolada. Consulte [Saída de WorktreeCreate](#worktreecreate-output) para ver como cada tipo de hook retorna o caminho.
3218 3220
3219O Claude Code age com base no sucesso do hook e no caminho retornado, e descarta `systemMessage` e `continue`.3221O Claude Code age com base no sucesso do hook e no caminho retornado, e descarta `systemMessage` e `continue`.
3220 3222
3237}3239}
3238```3240```
3239 3241
3240O hook lê o `name` do worktree da entrada JSON no stdin, faz checkout de uma cópia nova em um novo diretório e imprime o caminho do diretório. O `echo` na última linha é o que o Claude Code lê como o caminho do worktree. Redirecione qualquer outra saída para o stderr para que ela não interfira no caminho.3242O hook lê o `name` do worktree a partir da entrada JSON no stdin, faz checkout de uma cópia nova em um novo diretório e imprime o caminho do diretório. O `echo` na última linha é o que o Claude Code lê como o caminho do worktree. Redirecione qualquer outra saída para o stderr para que ela não interfira no caminho.
3241 3243
3242<h4 id="worktreecreate-input">3244<h4 id="worktreecreate-input">
3243 Entrada do WorktreeCreate3245 Entrada de WorktreeCreate
3244</h4>3246</h4>
3245 3247
3246Além dos [campos de entrada comuns](#common-input-fields), os hooks WorktreeCreate recebem o campo `name`. Ele é um identificador slug para o novo worktree, especificado pelo usuário ou gerado automaticamente, por exemplo `bold-oak-a3f2`.3248Além dos [campos de entrada comuns](#common-input-fields), os hooks WorktreeCreate recebem o campo `name`. Este é um identificador slug para o novo worktree, especificado pelo usuário ou gerado automaticamente, por exemplo `bold-oak-a3f2`.
3247 3249
3248```json theme={null}3250```json theme={null}
3249{3251{
3256```3258```
3257 3259
3258<h4 id="worktreecreate-output">3260<h4 id="worktreecreate-output">
3259 Saída do WorktreeCreate3261 Saída de WorktreeCreate
3260</h4>3262</h4>
3261 3263
3262Os hooks WorktreeCreate não usam o modelo padrão de decisão de permitir/bloquear. Em vez disso, o sucesso ou a falha do hook determina o resultado. O hook deve retornar o caminho para o diretório do worktree criado:3264Os hooks WorktreeCreate não usam o modelo padrão de decisão de permitir/bloquear. Em vez disso, o sucesso ou a falha do hook determina o resultado. O hook deve retornar o caminho para o diretório do worktree criado:
3263 3265
3264* **Hooks de comando** (`type: "command"`): imprima o caminho como a última linha não vazia do stdout. O Claude Code remove os códigos de escape ANSI antes de ler essa linha, então os banners de inicialização do shell impressos antes do seu `echo` são ignorados. Redirecione qualquer outra saída do hook para o stderr.3266* **Hooks de comando** (`type: "command"`): imprima o caminho como a última linha não vazia do stdout. O Claude Code remove códigos de escape ANSI antes de ler essa linha, então banners de inicialização do shell impressos antes do seu `echo` são ignorados. Redirecione qualquer outra saída do hook para o stderr.
3265* **Hooks HTTP** (`type: "http"`): retorne `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` no corpo da resposta.3267* **Hooks HTTP** (`type: "http"`): retorne `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` no corpo da resposta.
3266 3268
3267Se o hook falhar ou não produzir nenhum caminho, a criação do worktree falha com um erro.3269Se o hook falhar ou não produzir nenhum caminho, a criação do worktree falha com um erro.
3268 3270
3269O Claude Code resolve um caminho relativo em relação ao diretório em que o hook foi executado, eliminando quaisquer segmentos `.` ou `..` nele. Se o caminho resultante não for um diretório em que o Claude Code possa entrar, a sessão imprime um erro com o nome do caminho e encerra com o código 1.3271O Claude Code resolve um caminho relativo em relação ao diretório em que o hook foi executado, eliminando quaisquer segmentos `.` ou `..` nele. Se o caminho resultante não for um diretório em que o Claude Code possa entrar, a sessão imprime um erro indicando o caminho e encerra com o código 1.
3270 3272
3271O Claude Code recusa um caminho absoluto que contenha segmentos `.` ou `..`, e qualquer caminho que passe por um link simbólico abaixo da raiz do repositório, porque um link simbólico commitado no repositório poderia redirecionar o worktree para fora dele. O erro indica o componente rejeitado. Retorne um caminho normalizado que não passe por um link simbólico dentro do repositório. Antes da v2.1.216, a criação do worktree seguia o caminho do hook sem essa verificação.3273O Claude Code recusa um caminho absoluto que contenha segmentos `.` ou `..`, e qualquer caminho que passe por um link simbólico abaixo da raiz do repositório, porque um link simbólico commitado no repositório poderia redirecionar o worktree para fora dele. O erro indica o componente rejeitado. Retorne um caminho normalizado que não passe por um link simbólico dentro do repositório. Antes da v2.1.216, a criação do worktree seguia o caminho do hook sem essa verificação.
3272 3274
3276 3278
3277É executado quando o Claude Code limpa um worktree que o seu hook [`WorktreeCreate`](#worktreecreate) criou. O evento é disparado quando:3279É executado quando o Claude Code limpa um worktree que o seu hook [`WorktreeCreate`](#worktreecreate) criou. O evento é disparado quando:
3278 3280
3279* Você sai de uma [sessão de worktree](/docs/pt/worktrees#start-claude-in-a-worktree) interativa e escolhe remover o worktree quando o Claude Code solicita3281* Você sai de uma [sessão de worktree](/docs/pt/worktrees#start-claude-in-a-worktree) interativa e opta por remover o worktree quando o Claude Code pergunta
3280* Você sai de uma sessão de worktree interativa que não [nomeou](/docs/pt/sessions#name-your-sessions), o Claude Code não encontra arquivos alterados ou não rastreados e remove o worktree sem solicitar confirmação3282* Você sai de uma sessão de worktree interativa que não [nomeou](/docs/pt/sessions#name-your-sessions), o Claude Code não encontra arquivos alterados ou não rastreados, e remove o worktree sem perguntar
3281* Você exclui uma [sessão em segundo plano](/docs/pt/agent-view#what-deleting-a-session-removes) que é executada no worktree3283* Você exclui uma [sessão em segundo plano](/docs/pt/agent-view#what-deleting-a-session-removes) que é executada no worktree
3282 3284
3283O Claude Code usa o git para procurar arquivos alterados ou não rastreados, então não encontra nenhum em um worktree que não seja um checkout git nem esteja dentro de um, mesmo quando o diretório contém trabalho não commitado. Verifique esse trabalho no seu hook WorktreeRemove antes que ele exclua qualquer coisa.3285O Claude Code usa o git para procurar arquivos alterados ou não rastreados, então não encontra nenhum em um worktree que não seja um checkout git nem esteja dentro de um, mesmo quando o diretório contém trabalho não commitado. Verifique esse trabalho no seu hook WorktreeRemove antes que ele exclua qualquer coisa.
3284 3286
3285Para worktrees baseados em git, o Claude Code lida com a limpeza automaticamente com `git worktree remove`. Se você configurou um hook WorktreeCreate, combine-o com um hook WorktreeRemove para controlar a limpeza dos worktrees que ele cria:3287Para worktrees baseados em git, o Claude Code cuida da limpeza automaticamente com `git worktree remove`. Se você configurou um hook WorktreeCreate, combine-o com um hook WorktreeRemove para controlar a limpeza dos worktrees que ele cria:
3286 3288
3287* **Sem hook WorktreeRemove**: quando o Claude Code remove o worktree ao você sair de uma sessão de worktree, ele recorre a `git worktree remove --force` no caminho que o seu hook WorktreeCreate retornou, então um worktree que o git reconhece é removido. Um worktree que o git não reconhece, por exemplo um que o seu hook criou com um sistema de controle de versão que não seja git, permanece no disco. Para saber o que a exclusão de uma [sessão em segundo plano](/docs/pt/agent-view#what-deleting-a-session-removes) faz com um worktree criado por hook, consulte as regras de exclusão da visualização de agentes.3289* **Sem hook WorktreeRemove**: quando o Claude Code remove o worktree ao sair de uma sessão de worktree, ele recorre a `git worktree remove --force` no caminho que seu hook WorktreeCreate retornou, de modo que um worktree que o git reconhece é removido. Um worktree que o git não reconhece, por exemplo um que seu hook criou com um sistema de controle de versão que não seja git, permanece no disco. Para saber o que a exclusão de uma [sessão em segundo plano](/docs/pt/agent-view#what-deleting-a-session-removes) faz com um worktree criado por hook, consulte as regras de exclusão do agent view.
3288* **O hook encerra com 0**: o worktree é considerado removido. O Claude Code não lê mais nada do hook, então certifique-se de que seu hook excluiu o diretório.3290* **O hook sai com 0**: o worktree conta como removido. O Claude Code não lê mais nada do hook, então certifique-se de que seu hook excluiu o diretório.
3289* **O hook encerra com código diferente de zero**: a remoção falha se o diretório em `worktree_path` ainda existir depois, e o worktree permanece no disco sem fallback do git. Um hook que excluiu o diretório antes de encerrar com código diferente de zero é considerado como tendo removido o worktree. Para saber como a falha é relatada, consulte [Entrada do WorktreeRemove](#worktreeremove-input).3291* **O hook sai com código diferente de zero**: a remoção falha se o diretório em `worktree_path` ainda existir depois, e o worktree permanece no disco sem fallback para o git. Um hook que excluiu o diretório antes de sair com código diferente de zero conta como removido. Para saber como a falha é relatada, consulte [Entrada de WorktreeRemove](#worktreeremove-input).
3290 3292
3291O Claude Code nunca exclui um branch pertencente a um worktree criado por hook, porque ele conhece apenas o caminho que seu hook WorktreeCreate retornou. Se seu hook WorktreeCreate criar um branch, exclua-o no seu hook WorktreeRemove.3293O Claude Code nunca exclui um branch pertencente a um worktree criado por hook, porque ele só conhece o caminho que seu hook WorktreeCreate retornou. Se o seu hook WorktreeCreate cria um branch, exclua-o no seu hook WorktreeRemove.
3292 3294
3293O Claude Code descarta os [campos de saída JSON](#json-output) de um hook WorktreeRemove, como `systemMessage` e `continue`.3295O Claude Code descarta os [campos de saída JSON](#json-output) de um hook WorktreeRemove, como `systemMessage` e `continue`.
3294 3296
3295Para a exclusão de uma sessão em segundo plano, o Claude Code verifica o caminho do worktree armazenado antes de executar o hook e recusa um caminho que seja um link simbólico ou que passe por um abaixo da raiz do repositório. O hook é executado para um worktree que ainda contém arquivos somente quando você confirma a exclusão na [visualização de agentes](/docs/pt/agent-view#what-deleting-a-session-removes); para um worktree assim, [`claude rm`](/docs/pt/agent-view#manage-sessions-from-the-shell) mantém a sessão e o worktree. Antes da v2.1.216, o hook era executado no caminho armazenado sem essas verificações.3297Para a exclusão de uma sessão em segundo plano, o Claude Code verifica o caminho do worktree armazenado antes de executar o hook e recusa um caminho que seja um link simbólico ou que passe por um abaixo da raiz do repositório. O hook é executado para um worktree que ainda contém arquivos somente quando você confirma a exclusão no [agent view](/docs/pt/agent-view#what-deleting-a-session-removes); para esse tipo de worktree, [`claude rm`](/docs/pt/agent-view#manage-sessions-from-the-shell) mantém a sessão e o worktree. Antes da v2.1.216, o hook era executado no caminho armazenado sem essas verificações.
3296 3298
3297O Claude Code passa o caminho retornado pelo WorktreeCreate como `worktree_path` na entrada do hook. Este exemplo lê esse caminho e remove o diretório:3299O Claude Code passa o caminho retornado por WorktreeCreate como `worktree_path` na entrada do hook. Este exemplo lê esse caminho e remove o diretório:
3298 3300
3299```json theme={null}3301```json theme={null}
3300{3302{
3314```3316```
3315 3317
3316<h4 id="worktreeremove-input">3318<h4 id="worktreeremove-input">
3317 Entrada do WorktreeRemove3319 Entrada de WorktreeRemove
3318</h4>3320</h4>
3319 3321
3320Além dos [campos de entrada comuns](#common-input-fields), os hooks WorktreeRemove recebem o campo `worktree_path`, que é o caminho absoluto para o worktree que está sendo removido.3322Além dos [campos de entrada comuns](#common-input-fields), os hooks WorktreeRemove recebem o campo `worktree_path`, que é o caminho absoluto para o worktree que está sendo removido.
3329}3331}
3330```3332```
3331 3333
3332O código de saída de um hook WorktreeRemove decide o resultado. Quando um hook encerra com código diferente de zero e o diretório em `worktree_path` ainda existe depois, a remoção falha:3334O código de saída de um hook WorktreeRemove decide o resultado. Quando um hook sai com código diferente de zero e o diretório em `worktree_path` ainda existe depois, a remoção falha:
3333 3335
3334* O worktree permanece no disco, e o comando e o stderr do hook vão para o [log de depuração](#debug-hooks).3336* O worktree permanece no disco, e o comando do hook e o stderr vão para o [log de depuração](#debug-hooks).
3335* Se você estava excluindo uma sessão em segundo plano, a sessão também permanece. A mensagem de recusa na [visualização de agentes](/docs/pt/agent-view#what-deleting-a-session-removes) informa como o hook terminou, como `exited 1`, cita o início do seu stderr e diz se excluir a sessão novamente remove o diretório mesmo assim.3337* Se você estava excluindo uma sessão em segundo plano, a sessão também permanece. A mensagem de recusa no [agent view](/docs/pt/agent-view#what-deleting-a-session-removes) informa como o hook terminou, como `exited 1`, cita o início do stderr e diz se excluir a sessão novamente remove o diretório mesmo assim.
3336 3338
3337<h3 id="precompact">3339<h3 id="precompact">
3338 PreCompact3340 PreCompact
3347| `manual` | `/compact` |3349| `manual` | `/compact` |
3348| `auto` | Compactação automática quando a conversa atinge a [janela de compactação automática](/docs/pt/model-config#set-the-auto-compact-window) |3350| `auto` | Compactação automática quando a conversa atinge a [janela de compactação automática](/docs/pt/model-config#set-the-auto-compact-window) |
3349 3351
3350Encerre com o código 2 para bloquear a compactação. Para um `/compact` manual, a mensagem do stderr é mostrada ao usuário. Você também pode bloquear retornando JSON com `"decision": "block"`.3352Saia com o código 2 para bloquear a compactação. Para um `/compact` manual, a mensagem do stderr é mostrada ao usuário. Você também pode bloquear retornando JSON com `"decision": "block"`.
3351 3353
3352Bloquear a compactação automática tem efeitos diferentes dependendo de quando ela é disparada. Se a compactação foi acionada proativamente antes do limite de contexto, o Claude Code a ignora e a conversa continua sem compactação. Se a compactação foi acionada para se recuperar de um erro de limite de contexto já retornado pela API, o erro subjacente aparece e a requisição atual falha.3354Bloquear a compactação automática tem efeitos diferentes dependendo de quando ela é disparada. Se a compactação foi acionada proativamente antes do limite de contexto, o Claude Code a ignora e a conversa continua sem compactação. Se a compactação foi acionada para se recuperar de um erro de limite de contexto já retornado pela API, o erro subjacente aparece e a requisição atual falha.
3353 3355
3354O Claude Code descarta os campos `systemMessage` e `continue` de um hook PreCompact.3356O Claude Code descarta os campos `systemMessage` e `continue` de um hook PreCompact.
3355 3357
3356<h4 id="precompact-input">3358<h4 id="precompact-input">
3357 Entrada do PreCompact3359 Entrada de PreCompact
3358</h4>3360</h4>
3359 3361
3360Além dos [campos de entrada comuns](#common-input-fields), os hooks PreCompact recebem `trigger` e `custom_instructions`. Para `manual`, `custom_instructions` contém o que o usuário passa para `/compact` e é `null` quando ele não passa nada. Para `auto`, `custom_instructions` é `null`.3362Além dos [campos de entrada comuns](#common-input-fields), os hooks PreCompact recebem `trigger` e `custom_instructions`. Para `manual`, `custom_instructions` contém o que o usuário passa para `/compact` e é `null` quando ele não passa nada. Para `auto`, `custom_instructions` é `null`.
3374 PostCompact3376 PostCompact
3375</h3>3377</h3>
3376 3378
3377É executado depois que o Claude Code conclui uma operação de compactação. Use este evento para reagir ao novo estado compactado, por exemplo, para registrar em log o resumo gerado ou atualizar um estado externo. O Claude Code descarta os campos `systemMessage` e `continue` de um hook PostCompact.3379É executado após o Claude Code concluir uma operação de compactação. Use este evento para reagir ao novo estado compactado, por exemplo para registrar em log o resumo gerado ou atualizar um estado externo. O Claude Code descarta os campos `systemMessage` e `continue` de um hook PostCompact.
3378 3380
3379Os mesmos valores de matcher do `PreCompact` se aplicam:3381Os mesmos valores de matcher se aplicam como para `PreCompact`:
3380 3382
3381| Matcher | Quando é disparado |3383| Matcher | Quando é disparado |
3382| :- | :- |3384| :- | :- |
3384| `auto` | Após a compactação automática quando a conversa atinge a [janela de compactação automática](/docs/pt/model-config#set-the-auto-compact-window) |3386| `auto` | Após a compactação automática quando a conversa atinge a [janela de compactação automática](/docs/pt/model-config#set-the-auto-compact-window) |
3385 3387
3386<h4 id="postcompact-input">3388<h4 id="postcompact-input">
3387 Entrada do PostCompact3389 Entrada de PostCompact
3388</h4>3390</h4>
3389 3391
3390Além dos [campos de entrada comuns](#common-input-fields), os hooks PostCompact recebem `trigger` e `compact_summary`. O campo `compact_summary` contém o resumo da conversa gerado pela operação de compactação.3392Além dos [campos de entrada comuns](#common-input-fields), os hooks PostCompact recebem `trigger` e `compact_summary`. O campo `compact_summary` contém o resumo da conversa gerado pela operação de compactação.
3406 PreModelSwitch3408 PreModelSwitch
3407</h3>3409</h3>
3408 3410
3409É executado antes de o Claude Code aplicar uma troca de modelo que você ou um cliente solicitou. Use-o para bloquear uma troca, exigir confirmação ou mostrar quanto a troca vai custar antes que ela aconteça.3411É executado antes de o Claude Code aplicar uma troca de modelo que você ou um cliente solicitou. Use-o para bloquear uma troca, exigir confirmação ou mostrar quanto a troca custará antes que ela aconteça.
3410 3412
3411O PreModelSwitch requer o Claude Code v2.1.251 ou posterior. O Claude Code o executa para estas solicitações:3413O PreModelSwitch requer o Claude Code v2.1.251 ou posterior. O Claude Code o executa para estas requisições:
3412 3414
3413* `/model <name>` e o seletor do `/model`3415* `/model <name>` e o seletor do `/model`
3414* O seletor de modelo `Option+P` ou `Alt+P`3416* O seletor de modelo `Option+P` ou `Alt+P`
3415* A configuração Model em `/config`3417* A configuração Model em `/config`
3416* Ativar o [modo rápido](/docs/pt/fast-mode) quando isso altera o modelo da sessão3418* Ativar o [modo rápido](/docs/pt/fast-mode) quando isso altera o modelo da sessão
3417* Uma requisição `set_model`, ou uma mudança de modelo em uma requisição `apply_flag_settings`, de um host do [Agent SDK](/docs/pt/agent-sdk/typescript#query-object) ou do [Remote Control](/docs/pt/remote-control)3419* Uma requisição `set_model`, ou uma alteração de modelo em uma requisição `apply_flag_settings`, de um host do [Agent SDK](/docs/pt/agent-sdk/typescript#query-object) ou do [Remote Control](/docs/pt/remote-control)
3418 3420
3419O Claude Code não executa hooks PreModelSwitch para trocas que ele faz por conta própria, como um [fallback automático de modelo](/docs/pt/model-config#automatic-model-fallback) ou a restauração do modelo quando você retoma uma sessão. Essas mudanças chegam apenas ao [PostModelSwitch](#postmodelswitch).3421O Claude Code não executa hooks PreModelSwitch para trocas que ele faz por conta própria, como um [fallback automático de modelo](/docs/pt/model-config#automatic-model-fallback) ou a restauração do modelo quando você retoma uma sessão. Essas alterações chegam apenas ao [PostModelSwitch](#postmodelswitch).
3420 3422
3421O Claude Code compara o matcher com o nome canônico do modelo para o qual a sessão está trocando, ignorando qualquer sufixo `[1m]`. Um alias como `opus`, um ID de modelo com data e um ID específico de provedor, como um ID de modelo do Amazon Bedrock, correspondem todos ao único nome canônico para o qual são resolvidos, então `claude-opus-5` abrange todas as grafias do Opus 5.3423O Claude Code compara o matcher com o nome canônico do modelo para o qual a sessão está trocando, ignorando qualquer sufixo `[1m]`. Um alias como `opus`, um ID de modelo com data e um ID específico de provedor, como um ID de modelo do Amazon Bedrock, correspondem todos ao único nome canônico para o qual são resolvidos, então `claude-opus-5` cobre todas as grafias do Opus 5.
3422 3424
3423Quando o Claude Code não consegue determinar um nome canônico para o destino, por exemplo, um ID de modelo personalizado que somente o seu [gateway de LLM](/docs/pt/llm-gateway) conhece, ele executa todos os hooks PreModelSwitch independentemente do matcher. Portanto, um hook que bloqueia deve verificar `to_model` em sua entrada em vez de depender apenas do matcher.3425Quando o Claude Code não consegue determinar um nome canônico para o destino, por exemplo um ID de modelo personalizado que só o seu [gateway de LLM](/docs/pt/llm-gateway) conhece, ele executa todos os hooks PreModelSwitch independentemente do matcher. Um hook que bloqueia deve, portanto, verificar `to_model` na sua entrada em vez de depender apenas do matcher.
3424 3426
3425Escreva o matcher como um nome exato, uma lista separada por `|` como `claude-opus-4-6|claude-opus-5`, ou uma expressão regular como `.*opus.*`. Este exemplo usa um matcher de nome exato e também verifica `to_model` na entrada do hook, de modo que recusa uma troca para o Opus 4.6 encerrando com o código 2 e permite qualquer outro destino:3427Escreva o matcher como um nome exato, uma lista separada por `|` como `claude-opus-4-6|claude-opus-5`, ou uma expressão regular como `.*opus.*`. Este exemplo usa um matcher de nome exato e também verifica `to_model` na entrada do hook, de modo que recusa uma troca para o Opus 4.6 saindo com o código 2 e deixa passar qualquer outro destino:
3426 3428
3427<Tabs>3429<Tabs>
3428 <Tab title="macOS/Linux">3430 <Tab title="macOS/Linux">
3448 </Tab>3450 </Tab>
3449 3451
3450 <Tab title="Windows (PowerShell)">3452 <Tab title="Windows (PowerShell)">
3451 Registre um hook de comando que executa um script pelo PowerShell:3453 Registre um hook de comando que executa um script por meio do PowerShell:
3452 3454
3453 ```json theme={null}3455 ```json theme={null}
3454 {3456 {
3488 </Tab>3490 </Tab>
3489</Tabs>3491</Tabs>
3490 3492
3491Para confirmar que o hook funciona, execute `/model claude-opus-4-6` em uma sessão que esteja usando um modelo diferente. O Claude Code mantém o modelo atual e informa que um hook PreModelSwitch bloqueou a troca, com a sua mensagem como motivo.3493Para confirmar que o hook funciona, execute `/model claude-opus-4-6` a partir de uma sessão que esteja usando um modelo diferente. O Claude Code mantém o modelo atual e informa que um hook PreModelSwitch bloqueou a troca, com a sua mensagem como motivo.
3492 3494
3493<h4 id="premodelswitch-input">3495<h4 id="premodelswitch-input">
3494 Entrada do PreModelSwitch3496 Entrada de PreModelSwitch
3495</h4>3497</h4>
3496 3498
3497Além dos [campos de entrada comuns](#common-input-fields), os hooks PreModelSwitch recebem os campos desta tabela. Os cinco últimos descrevem quanto custa reenviar a conversa para o novo modelo, para que um hook possa mostrar esse valor antes que a troca aconteça.3499Além dos [campos de entrada comuns](#common-input-fields), os hooks PreModelSwitch recebem os campos desta tabela. Os últimos cinco descrevem quanto custa reenviar a conversa para o novo modelo, para que um hook possa mostrar esse valor antes que a troca aconteça.
3498 3500
3499| Campo | Tipo | Descrição |3501| Campo | Tipo | Descrição |
3500| :- | :- | :- |3502| :- | :- | :- |
3501| `from_model` | string | ID do modelo de origem da troca |3503| `from_model` | string | ID do modelo do qual a troca parte |
3502| `to_model` | string | ID do modelo de destino da troca. O matcher é comparado com o nome canônico desse modelo |3504| `to_model` | string | ID do modelo para o qual a troca muda. O matcher é comparado com o nome canônico deste modelo |
3503| `requested_model` | string ou `null` | O modelo indicado na solicitação: um alias como `opus`, um ID de modelo completo, ou `null` quando a solicitação foi para o modelo padrão |3505| `requested_model` | string ou `null` | O modelo indicado na requisição: um alias como `opus`, um ID de modelo completo, ou `null` quando a requisição foi para o modelo padrão |
3504| `source` | string | De onde veio a solicitação: `"command"` para `/model <name>`, a configuração Model em `/config` ou a ativação do modo rápido; `"picker"` para um seletor de modelo; `"sdk"` para uma requisição `set_model`, ou uma mudança de modelo em uma requisição `apply_flag_settings`, de um host do Agent SDK ou do Remote Control |3506| `source` | string | De onde veio a requisição: `"command"` para `/model <name>`, a configuração Model em `/config` ou a ativação do modo rápido; `"picker"` para um seletor de modelo; `"sdk"` para uma requisição `set_model`, ou uma alteração de modelo em uma requisição `apply_flag_settings`, de um host do Agent SDK ou do Remote Control |
3505| `context_tokens` | number | Tokens que a próxima requisição reenvia como seu prompt: os tokens de entrada, de leitura de cache, de criação de cache e de saída da última resposta na conversa principal, somados. `0` antes da primeira resposta |3507| `context_tokens` | number | Tokens que a próxima requisição reenvia como seu prompt: os tokens de entrada, de leitura de cache, de criação de cache e de saída da última resposta na conversa principal, somados. `0` antes da primeira resposta |
3506| `prompt_cache_warm` | boolean | Se o cache de prompt do modelo atual provavelmente ainda está aquecido, o que significa que a troca o perde |3508| `prompt_cache_warm` | boolean | Se o cache de prompt do modelo atual provavelmente ainda está aquecido, o que significa que a troca o perde |
3507| `cache_ttl` | string | [Tempo de vida do cache de prompt](/docs/pt/prompt-caching#cache-lifetime) que o Claude Code solicita para esta sessão: `"5m"` ou `"1h"` |3509| `cache_ttl` | string | [Tempo de vida do cache de prompt](/docs/pt/prompt-caching#cache-lifetime) que o Claude Code solicita para esta sessão: `"5m"` ou `"1h"` |
3508| `estimated_cache_write_usd` | number | Custo estimado em dólares americanos de gravar `context_tokens` no cache de prompt em `to_model` à taxa de `cache_ttl`, excluindo a próxima resposta. O servidor pode não precisar refazer o cache de todo o contexto, então trate-o como uma estimativa |3510| `estimated_cache_write_usd` | number | Custo estimado em dólares americanos de gravar `context_tokens` no cache de prompt em `to_model` na tarifa de `cache_ttl`, excluindo a próxima resposta. O servidor pode não precisar armazenar em cache todo o contexto novamente, então trate-o como uma estimativa |
3509| `pricing` | string | Como o Claude Code precificou `estimated_cache_write_usd`: `"configured"` pelas taxas próprias da sua organização quando ela as configurou, `"catalog"` pelo preço de tabela, ou `"default"` quando `to_model` não tem preço conhecido e o Claude Code assumiu uma taxa padrão |3511| `pricing` | string | Como o Claude Code precificou `estimated_cache_write_usd`: `"configured"` nas tarifas próprias da sua organização quando ela as configurou, `"catalog"` no preço de tabela, ou `"default"` quando `to_model` não tem preço conhecido e o Claude Code assumiu uma tarifa padrão |
3510 3512
3511Este exemplo mostra a entrada para `/model opus` em uma sessão usando o Sonnet 5:3513Este exemplo mostra a entrada para `/model opus` em uma sessão que está usando o Sonnet 5:
3512 3514
3513```json theme={null}3515```json theme={null}
3514{3516{
3529```3531```
3530 3532
3531<h4 id="premodelswitch-decision-control">3533<h4 id="premodelswitch-decision-control">
3532 Controle de decisão do PreModelSwitch3534 Controle de decisão de PreModelSwitch
3533</h4>3535</h4>
3534 3536
3535Os hooks `PreModelSwitch` podem cancelar a troca, pedir ao usuário que a confirme ou deixá-la prosseguir. O código de saída 2 ou um `decision: "block"` no nível superior cancela a troca.3537Os hooks `PreModelSwitch` podem cancelar a troca, pedir ao usuário que a confirme ou deixá-la prosseguir. O código de saída 2 ou um `decision: "block"` de nível superior cancela a troca.
3536 3538
3537Para um controle mais refinado, retorne `permissionDecision` e `permissionDecisionReason` em um objeto `hookSpecificOutput`, como no [PreToolUse](#pretooluse-decision-control). O `PreModelSwitch` aceita `"allow"`, `"deny"` e `"ask"`. Ele não aceita `"defer"`, `updatedInput` nem `additionalContext`. A tabela abaixo descreve ambos os campos:3539Para um controle mais refinado, retorne `permissionDecision` e `permissionDecisionReason` em um objeto `hookSpecificOutput`, como no [PreToolUse](#pretooluse-decision-control). O `PreModelSwitch` aceita `"allow"`, `"deny"` e `"ask"`. Ele não aceita `"defer"`, `updatedInput` nem `additionalContext`. A tabela abaixo descreve ambos os campos:
3538 3540
3539| Campo | Descrição |3541| Campo | Descrição |
3540| :- | :- |3542| :- | :- |
3541| `permissionDecision` | `"allow"` prossegue e pula a [confirmação que o Claude Code mostra enquanto o cache de prompt está aquecido](/docs/pt/prompt-caching#switching-models). `"deny"` cancela a troca. `"ask"` pede ao usuário que a confirme |3543| `permissionDecision` | `"allow"` prossegue e pula a [confirmação que o Claude Code mostra enquanto o cache de prompt está aquecido](/docs/pt/prompt-caching#switching-models). `"deny"` cancela a troca. `"ask"` solicita ao usuário que a confirme |
3542| `permissionDecisionReason` | Para `"deny"`, mostrado ao usuário como o motivo pelo qual a troca foi bloqueada, ou retornado como erro para uma requisição `set_model`. Para `"ask"`, mostrado no prompt de confirmação. Ignorado para `"allow"` |3544| `permissionDecisionReason` | Para `"deny"`, mostrado ao usuário como o motivo pelo qual a troca foi bloqueada, ou retornado como o erro de uma requisição `set_model`. Para `"ask"`, mostrado no prompt de confirmação. Ignorado para `"allow"` |
3543 3545
3544Somente o `/model` em uma sessão interativa pode mostrar o prompt de `"ask"`. Em todas as outras superfícies, incluindo o modo não interativo com a flag `-p`, `/config` e requisições `set_model`, o Claude Code trata `"ask"` como uma recusa.3546Somente o `/model` em uma sessão interativa pode mostrar o prompt de `"ask"`. Em todas as outras superfícies, incluindo o modo não interativo com a flag `-p`, `/config` e requisições `set_model`, o Claude Code trata `"ask"` como uma recusa.
3545 3547
3557 3559
3558Quando vários hooks PreModelSwitch retornam decisões diferentes, a precedência é `deny` > `ask` > `allow`.3560Quando vários hooks PreModelSwitch retornam decisões diferentes, a precedência é `deny` > `ask` > `allow`.
3559 3561
3560O Claude Code mostra ao usuário qualquer `systemMessage` que seu hook retornar, independentemente da decisão, então um hook de relatório de custo pode retornar `{"systemMessage": "..."}` e encerrar com 0.3562O Claude Code mostra ao usuário qualquer `systemMessage` que o seu hook retorne, independentemente da decisão, então um hook de relatório de custo pode retornar `{"systemMessage": "..."}` e sair com 0.
3561 3563
3562Um hook PreModelSwitch que não responde antes do seu timeout bloqueia a troca. No [PreToolUse](#timeouts), por outro lado, um hook de comando que atingiu o timeout deixa a chamada de ferramenta continuar. O timeout padrão para este evento é de 30 segundos. O `PreModelSwitch` executa apenas hooks `command`, `http` e `mcp_tool`, então os padrões de `prompt` e `agent` não se aplicam.3564Um hook PreModelSwitch que não responde antes do seu timeout bloqueia a troca. No [PreToolUse](#timeouts), por outro lado, um hook de comando que atinge o timeout deixa a chamada de ferramenta continuar. O timeout padrão para este evento é de 30 segundos. O `PreModelSwitch` executa apenas hooks `command`, `http` e `mcp_tool`, então os padrões de `prompt` e `agent` não se aplicam.
3563 3565
3564Um hook que encerra com um código diferente de 0 ou 2 e não imprime nenhuma decisão JSON não bloqueia: o Claude Code mostra seu stderr e aplica a troca, conforme descrito em [Outros códigos de saída](#other-exit-codes).3566Um hook que sai com um código diferente de 0 ou 2 e não imprime nenhuma decisão JSON não bloqueia: o Claude Code mostra seu stderr e aplica a troca, conforme descrito em [Outros códigos de saída](#other-exit-codes).
3565 3567
3566<h3 id="postmodelswitch">3568<h3 id="postmodelswitch">
3567 PostModelSwitch3569 PostModelSwitch
3568</h3>3570</h3>
3569 3571
3570É executado depois que o modelo da sessão muda. Use-o para dar ao Claude orientações específicas do modelo sem editar cada CLAUDE.md, por exemplo, uma instrução para toda a organização que se aplica a determinados modelos.3572É executado após a alteração do modelo da sessão. Use-o para dar ao Claude orientações específicas do modelo sem editar cada CLAUDE.md, por exemplo uma instrução válida para toda a organização que se aplica a determinados modelos.
3571 3573
3572O PostModelSwitch requer o Claude Code v2.1.251 ou posterior. Ele não pode bloquear, porque o modelo já mudou. O Claude Code executa hooks PostModelSwitch após qualquer uma destas mudanças:3574O PostModelSwitch requer o Claude Code v2.1.251 ou posterior. Ele não pode bloquear, porque o modelo já foi alterado. O Claude Code executa hooks PostModelSwitch após qualquer uma destas alterações:
3573 3575
3574* Uma troca que você ou um cliente solicitou3576* Uma troca que você ou um cliente solicitou
3575* Um [fallback automático de modelo](/docs/pt/model-config#automatic-model-fallback), que altera o modelo da sessão3577* Um [fallback automático de modelo](/docs/pt/model-config#automatic-model-fallback), que altera o modelo da sessão
3576* Uma configuração como [`opusplan`](/docs/pt/model-config#opusplan-model-setting) entrando ou saindo do modo de planejamento3578* Uma configuração como [`opusplan`](/docs/pt/model-config#opusplan-model-setting) entrando ou saindo do modo de planejamento
3577* O Claude Code restaurando o modelo quando você retoma uma sessão3579* O Claude Code restaurando o modelo quando você retoma uma sessão
3578 3580
3579O Claude Code não executa hooks PostModelSwitch quando um modelo de uma [cadeia de modelos de fallback](/docs/pt/model-config#fallback-model-chains) atende a um turno, porque essa substituição dura um turno e mantém o modelo da sessão inalterado.3581O Claude Code não executa hooks PostModelSwitch quando um modelo de uma [cadeia de modelos de fallback](/docs/pt/model-config#fallback-model-chains) atende a um turno, porque essa substituição dura um turno e deixa o modelo da sessão inalterado.
3580 3582
3581O matcher segue as mesmas regras do [PreModelSwitch](#premodelswitch): o Claude Code o compara com o nome canônico do modelo para o qual a sessão trocou.3583O matcher segue as mesmas regras que o [PreModelSwitch](#premodelswitch): o Claude Code o compara com o nome canônico do modelo para o qual a sessão trocou.
3582 3584
3583Este exemplo adiciona orientações sempre que o modelo da sessão muda para qualquer modelo Opus:3585Este exemplo adiciona orientações sempre que o modelo da sessão muda para qualquer modelo Opus:
3584 3586
3600}3602}
3601```3603```
3602 3604
3603Para confirmar que o hook funciona, troque para um modelo Opus a partir de uma sessão que esteja usando um modelo diferente, por exemplo, execute `/model opus` em uma sessão do Sonnet, e depois pergunte ao Claude quais orientações ele tem sobre o modelo atual.3605Para confirmar que o hook funciona, troque para um modelo Opus a partir de uma sessão que esteja usando um modelo diferente, por exemplo execute `/model opus` a partir de uma sessão do Sonnet, e depois pergunte ao Claude que orientações ele tem sobre o modelo atual.
3604 3606
3605<h4 id="postmodelswitch-input">3607<h4 id="postmodelswitch-input">
3606 Entrada do PostModelSwitch3608 Entrada de PostModelSwitch
3607</h4>3609</h4>
3608 3610
3609Os hooks PostModelSwitch recebem os mesmos campos do [PreModelSwitch](#premodelswitch-input), com `hook_event_name` definido como `"PostModelSwitch"` e mais dois valores de `source`: `"auto"` para um fallback automático ou outra mudança que o Claude Code fez por conta própria, e `"resume"` para o modelo restaurado quando você retoma uma sessão.3611Os hooks PostModelSwitch recebem os mesmos campos que o [PreModelSwitch](#premodelswitch-input), com `hook_event_name` definido como `"PostModelSwitch"` e mais dois valores de `source`: `"auto"` para um fallback automático ou outra alteração que o Claude Code fez por conta própria, e `"resume"` para o modelo restaurado quando você retoma uma sessão.
3610 3612
3611`requested_model` é `null` quando `source` é `"auto"`. Quando `source` é `"resume"`, é a configuração de modelo salva que o Claude Code restaurou.3613`requested_model` é `null` quando `source` é `"auto"`. Quando `source` é `"resume"`, ele é a configuração de modelo salva que o Claude Code restaurou.
3612 3614
3613<h4 id="postmodelswitch-decision-control">3615<h4 id="postmodelswitch-decision-control">
3614 Controle de decisão do PostModelSwitch3616 Controle de decisão de PostModelSwitch
3615</h4>3617</h4>
3616 3618
3617O Claude Code pega o [stdout em texto simples](#exit-code-0) do seu hook ao encerrar com 0, ou o `additionalContext` da saída JSON, e o entrega ao Claude com a próxima requisição após a troca. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar:3619O Claude Code pega o [stdout em texto simples](#exit-code-0) do seu hook na saída 0, ou o `additionalContext` da saída JSON, e o entrega ao Claude com a próxima requisição após a troca. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar:
3618 3620
3619| Campo | Descrição |3621| Campo | Descrição |
3620| :- | :- |3622| :- | :- |
3621| `additionalContext` | String adicionada ao contexto do Claude com a próxima requisição. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |3623| `additionalContext` | String adicionada ao contexto do Claude com a próxima requisição. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |
3622 3624
3623Se o hook não tiver terminado dentro de cinco segundos depois que você enviar o próximo prompt, o Claude Code envia essa requisição sem a saída e a anexa à requisição seguinte. Se o modelo mudar várias vezes antes da próxima requisição, o Claude Code entrega apenas a saída referente ao modelo de destino da última troca.3625Se o hook não tiver terminado em até cinco segundos após você enviar o próximo prompt, o Claude Code envia essa requisição sem a saída e a anexa à requisição seguinte. Se o modelo mudar várias vezes antes da próxima requisição, o Claude Code entrega apenas a saída para o modelo de destino da última troca.
3624 3626
3625<h3 id="sessionend">3627<h3 id="sessionend">
3626 SessionEnd3628 SessionEnd
3627</h3>3629</h3>
3628 3630
3629É executado quando uma sessão do Claude Code termina. Útil para tarefas de limpeza, registro em log de estatísticas3631É executado quando uma sessão do Claude Code termina. Útil para tarefas de limpeza, registro de estatísticas
3630da sessão ou salvamento do estado da sessão. Suporta matchers para filtrar pelo motivo de saída.3632da sessão ou salvamento do estado da sessão. Suporta matchers para filtrar pelo motivo de saída.
3631 3633
3632O campo `reason` na entrada do hook indica por que a sessão terminou:3634O campo `reason` na entrada do hook indica por que a sessão terminou:
3641| `bypass_permissions_disabled` | Removido na v2.1.234; o Claude Code não o envia. Remova-o dos seus matchers de `SessionEnd` |3643| `bypass_permissions_disabled` | Removido na v2.1.234; o Claude Code não o envia. Remova-o dos seus matchers de `SessionEnd` |
3642 3644
3643<h4 id="sessionend-input">3645<h4 id="sessionend-input">
3644 Entrada do SessionEnd3646 Entrada de SessionEnd
3645</h4>3647</h4>
3646 3648
3647Além dos [campos de entrada comuns](#common-input-fields), os hooks SessionEnd recebem um campo `reason` indicando por que a sessão terminou. Consulte a [tabela de motivos](#sessionend) acima para ver todos os valores.3649Além dos [campos de entrada comuns](#common-input-fields), os hooks SessionEnd recebem um campo `reason` indicando por que a sessão terminou. Consulte a [tabela de motivos](#sessionend) acima para ver todos os valores.
3675 Elicitation3677 Elicitation
3676</h3>3678</h3>
3677 3679
3678É executado quando um servidor MCP solicita entrada do usuário no meio de uma tarefa. Por padrão, o Claude Code mostra uma caixa de diálogo interativa para o usuário responder. Os hooks podem interceptar essa solicitação e responder programaticamente, pulando totalmente a caixa de diálogo.3680É executado quando um servidor MCP solicita entrada do usuário no meio de uma tarefa. Por padrão, o Claude Code mostra um diálogo interativo para o usuário responder. Os hooks podem interceptar essa solicitação e responder programaticamente, pulando o diálogo completamente.
3681
3682Para um hook completo com sua entrada de configuração e script, consulte [Responder a uma solicitação de formulário a partir de um script](#answer-a-form-request-from-a-script).
3679 3683
3680O campo matcher é comparado com o nome do servidor MCP.3684O campo matcher é comparado com o nome do servidor MCP.
3681 3685
3682<h4 id="elicitation-input">3686<h4 id="elicitation-input">
3683 Entrada do Elicitation3687 Entrada de Elicitation
3684</h4>3688</h4>
3685 3689
3686Além dos [campos de entrada comuns](#common-input-fields), os hooks Elicitation recebem `mcp_server_name`, `message` e os campos opcionais `mode`, `url`, `elicitation_id` e `requested_schema`.3690Além dos [campos de entrada comuns](#common-input-fields), os hooks Elicitation recebem `mcp_server_name`, `message` e os campos opcionais `mode`, `url`, `elicitation_id` e `requested_schema`.
3687 3691
3688Para elicitação no modo de formulário, o caso mais comum:3692Para elicitation no modo formulário, o caso mais comum:
3689 3693
3690```json theme={null}3694```json theme={null}
3691{3695{
3705}3709}
3706```3710```
3707 3711
3708Para elicitação no modo URL, usada para autenticação baseada em navegador:3712Para elicitation no modo URL, usado para autenticação baseada em navegador:
3709 3713
3710```json theme={null}3714```json theme={null}
3711{3715{
3721```3725```
3722 3726
3723<h4 id="elicitation-output">3727<h4 id="elicitation-output">
3724 Saída do Elicitation3728 Saída de Elicitation
3725</h4>3729</h4>
3726 3730
3727Para responder programaticamente sem mostrar a caixa de diálogo, retorne um objeto JSON com `hookSpecificOutput`:3731Um hook Elicitation pode responder à solicitação pelo usuário, recusá-la ou cancelá-la, ou deixá-la para o diálogo. Para responder, recusar ou cancelar, saia com 0 e imprima um objeto `hookSpecificOutput` com uma `action`. O servidor recebe sua resposta e nenhum diálogo aparece. Cada linha desta tabela mostra o que retornar para um resultado e o que o servidor MCP recebe:
3732
3733| Para | Retorne | O servidor recebe |
3734| :- | :- | :- |
3735| Responder pelo usuário | `"action": "accept"`, com os valores dos campos do formulário em `content` | `accept` com o seu `content` |
3736| Recusar a solicitação | `"action": "decline"` | `decline` |
3737| Cancelar a solicitação | `"action": "cancel"` | `cancel` |
3738| Deixar a solicitação para o usuário | Nenhuma saída, com código de saída 0 | A resposta do usuário no [diálogo](/docs/pt/mcp#respond-to-mcp-elicitation-requests) |
3739
3740Esta saída responde à solicitação no modo formulário mostrada em [Entrada de Elicitation](#elicitation-input). As chaves em `content` são os nomes das propriedades do `requested_schema` dessa solicitação:
3728 3741
3729```json theme={null}3742```json theme={null}
3730{3743{
3738}3751}
3739```3752```
3740 3753
3741| Campo | Valores | Descrição |3754Esta saída recusa uma solicitação:
3742| :- | :- | :- |3755
3743| `action` | `accept`, `decline`, `cancel` | Se deve aceitar, recusar ou cancelar a solicitação |3756```json theme={null}
3744| `content` | object | Valores dos campos do formulário a serem enviados. Usado somente quando `action` é `accept` |3757{
3758 "hookSpecificOutput": {
3759 "hookEventName": "Elicitation",
3760 "action": "decline"
3761 }
3762}
3763```
3764
3765No diálogo, selecionar **Decline** envia `decline` e pressionar `Esc` envia `cancel`, então retorne aquele que você quer que o servidor veja.
3766
3767Para uma solicitação no modo URL, um hook que retorna `accept` pula o diálogo, então a URL nunca é aberta.
3768
3769O Claude Code descarta `reason`, `systemMessage` e `continue` da saída JSON de um hook Elicitation, qualquer que seja a `action` que você retorne.
3745 3770
3746O código de saída 2 nega a elicitação. O Claude Code não mostra sua mensagem de stderr em lugar nenhum.3771<h4 id="other-ways-to-decline-an-elicitation">
3772 Outras maneiras de recusar uma elicitation
3773</h4>
3774
3775Seu hook também pode recusar destas maneiras. O servidor recebe o mesmo `decline` que para `"action": "decline"`:
3776
3777* **Sai com o código 2**: o Claude Code ignora um `hookSpecificOutput` impresso pelo mesmo hook
3778* **Imprime um `"decision": "block"` de nível superior**: o bloqueio sobrescreve uma `action` na mesma saída
3779
3780Quando vários hooks correspondem à mesma solicitação, uma recusa de um deles sobrescreve um `accept` ou `cancel` de outro.
3781
3782Este script recusa solicitações no modo URL e deixa as solicitações de formulário para o diálogo:
3783
3784```bash theme={null}
3785#!/bin/bash
3786if [ "$(jq -r '.mode')" = "url" ]; then
3787 exit 2
3788fi
3789```
3790
3791Nem o usuário nem o servidor veem por que seu hook recusou, porque o Claude Code não mostra seu stderr nem seu `reason`.
3792
3793O Claude Code ignorou um `decision` de nível superior de hooks `Elicitation` e `ElicitationResult` desde a v2.1.105 até a correção na v2.1.284.
3794
3795<h4 id="answer-a-form-request-from-a-script">
3796 Responder a uma solicitação de formulário a partir de um script
3797</h4>
3747 3798
3748O Claude Code age com base no `hookSpecificOutput` da saída JSON de um hook Elicitation e descarta `systemMessage` e `continue`.3799Este exemplo responde a uma pergunta recorrente pelo usuário. Um servidor MCP chamado `issue-tracker` pede uma chave de projeto em um formulário, e o hook preenche `DOCS`. O script aceita quando `project_key` é o único campo do formulário. Para qualquer outra solicitação, ele não imprime nada, então o diálogo aparece.
3800
3801<Tabs>
3802 <Tab title="macOS/Linux">
3803 Registre um hook de comando para o evento no seu arquivo de configuração, com o nome do servidor como matcher:
3804
3805 ```json theme={null}
3806 {
3807 "hooks": {
3808 "Elicitation": [
3809 {
3810 "matcher": "issue-tracker",
3811 "hooks": [
3812 {
3813 "type": "command",
3814 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/answer-project-key.sh",
3815 "args": []
3816 }
3817 ]
3818 }
3819 ]
3820 }
3821 }
3822 ```
3823
3824 Salve este script em `.claude/hooks/answer-project-key.sh` no seu projeto e torne-o executável com `chmod +x`:
3825
3826 ```bash theme={null}
3827 #!/bin/bash
3828 input=$(cat)
3829 fields=$(jq -c '.requested_schema.properties // {} | keys' <<<"$input")
3830
3831 if [ "$fields" = '["project_key"]' ]; then
3832 jq -n '{hookSpecificOutput: {hookEventName: "Elicitation", action: "accept", content: {project_key: "DOCS"}}}'
3833 fi
3834 ```
3835 </Tab>
3836
3837 <Tab title="Windows (PowerShell)">
3838 Registre um hook de comando que executa o script por meio do PowerShell, com o nome do servidor como matcher:
3839
3840 ```json theme={null}
3841 {
3842 "hooks": {
3843 "Elicitation": [
3844 {
3845 "matcher": "issue-tracker",
3846 "hooks": [
3847 {
3848 "type": "command",
3849 "command": "powershell.exe",
3850 "args": [
3851 "-NoProfile",
3852 "-ExecutionPolicy",
3853 "Bypass",
3854 "-File",
3855 "${CLAUDE_PROJECT_DIR}/.claude/hooks/answer-project-key.ps1"
3856 ]
3857 }
3858 ]
3859 }
3860 ]
3861 }
3862 }
3863 ```
3864
3865 Salve este script em `.claude/hooks/answer-project-key.ps1` no seu projeto:
3866
3867 ```powershell theme={null}
3868 $request = [Console]::In.ReadToEnd() | ConvertFrom-Json
3869 $fields = @($request.requested_schema.properties.PSObject.Properties.Name)
3870
3871 if ($fields.Count -eq 1 -and $fields[0] -eq 'project_key') {
3872 @{
3873 hookSpecificOutput = @{
3874 hookEventName = "Elicitation"
3875 action = "accept"
3876 content = @{ project_key = "DOCS" }
3877 }
3878 } | ConvertTo-Json -Depth 3
3879 }
3880 ```
3881 </Tab>
3882</Tabs>
3883
3884Para confirmar que o hook funciona, inicie o Claude Code com `claude --debug` e dê ao Claude uma tarefa que faça o servidor pedir a chave do projeto. Nenhum diálogo aparece, e o [log de depuração](#debug-hooks) tem uma linha que termina com `Elicitation resolved by hook: {"action":"accept","content":{"project_key":"DOCS"}}`.
3749 3885
3750<h3 id="elicitationresult">3886<h3 id="elicitationresult">
3751 ElicitationResult3887 ElicitationResult
3752</h3>3888</h3>
3753 3889
3754É executado depois que um usuário responde a uma elicitação MCP. Os hooks podem observar, modificar ou bloquear a resposta antes que ela seja enviada de volta ao servidor MCP.3890É executado depois que um usuário responde a uma elicitation MCP. Os hooks podem observar, modificar ou bloquear a resposta antes que ela seja enviada de volta ao servidor MCP.
3891
3892Quando um hook [Elicitation](#elicitation) responde a uma solicitação, o Claude Code envia essa resposta ao servidor sem executar hooks ElicitationResult.
3755 3893
3756O campo matcher é comparado com o nome do servidor MCP.3894O campo matcher é comparado com o nome do servidor MCP.
3757 3895
3758<h4 id="elicitationresult-input">3896<h4 id="elicitationresult-input">
3759 Entrada do ElicitationResult3897 Entrada de ElicitationResult
3760</h4>3898</h4>
3761 3899
3762Além dos [campos de entrada comuns](#common-input-fields), os hooks ElicitationResult recebem `mcp_server_name`, `action` e os campos opcionais `mode`, `elicitation_id` e `content`.3900Além dos [campos de entrada comuns](#common-input-fields), os hooks ElicitationResult recebem `mcp_server_name`, `action` e os campos opcionais `mode`, `elicitation_id` e `content`.
3770 "mcp_server_name": "my-mcp-server",3908 "mcp_server_name": "my-mcp-server",
3771 "action": "accept",3909 "action": "accept",
3772 "content": { "username": "alice" },3910 "content": { "username": "alice" },
3773 "mode": "form",3911 "mode": "form"
3774 "elicitation_id": "elicit-123"
3775}3912}
3776```3913```
3777 3914
3778<h4 id="elicitationresult-output">3915<h4 id="elicitationresult-output">
3779 Saída do ElicitationResult3916 Saída de ElicitationResult
3780</h4>3917</h4>
3781 3918
3782Para sobrescrever a resposta do usuário, retorne um objeto JSON com `hookSpecificOutput`:3919Um hook ElicitationResult pode deixar a resposta do usuário passar, alterar seus valores ou bloqueá-la. Para alterar ou bloquear a resposta, saia com 0 e imprima um objeto `hookSpecificOutput` com uma `action`. Cada linha desta tabela mostra o que retornar para um resultado e o que o servidor MCP recebe:
3920
3921| Para | Retorne | O servidor recebe |
3922| :- | :- | :- |
3923| Deixar a resposta passar | Nenhuma saída, com código de saída 0 | A resposta do usuário, inalterada |
3924| Alterar os valores enviados | `"action": "accept"`, com os novos valores em `content` | `accept` com o seu `content` no lugar dos valores do usuário |
3925| Bloquear a resposta | `"action": "decline"` | `decline`, sem os valores do usuário |
3926| Cancelar a solicitação | `"action": "cancel"` | `cancel`, junto com os valores que o usuário enviou. Para retê-los, retorne `"decline"` |
3927
3928Esta saída altera a resposta mostrada em [Entrada de ElicitationResult](#elicitationresult-input), de modo que o servidor recebe `alice@example.com` onde o usuário enviou `alice`:
3783 3929
3784```json theme={null}3930```json theme={null}
3785{3931{
3786 "hookSpecificOutput": {3932 "hookSpecificOutput": {
3787 "hookEventName": "ElicitationResult",3933 "hookEventName": "ElicitationResult",
3788 "action": "decline",3934 "action": "accept",
3789 "content": {}3935 "content": {
3936 "username": "alice@example.com"
3937 }
3790 }3938 }
3791}3939}
3792```3940```
3793 3941
3794| Campo | Valores | Descrição |3942Seu `content` substitui todo o objeto `content` do usuário, então inclua os campos que você não está alterando. Retorne `action` junto com ele, porque o Claude Code ignora um `hookSpecificOutput` que não tenha `action`.
3795| :- | :- | :- |3943
3796| `action` | `accept`, `decline`, `cancel` | Sobrescreve a ação do usuário |3944Os hooks ElicitationResult também são executados quando o usuário recusa ou cancela, e sua `action` substitui a dele. Verifique se a `action` da entrada é `accept` antes de retornar `accept`, ou seu hook transformará uma solicitação recusada em uma aceita. Este script faz a mesma alteração quando o usuário aceitou, mantém os outros campos e não imprime nada caso contrário:
3797| `content` | object | Sobrescreve os valores dos campos do formulário. Significativo somente quando `action` é `accept` |3945
3946```bash theme={null}
3947#!/bin/bash
3948input=$(cat)
3798 3949
3799O código de saída 2 bloqueia a resposta, alterando a ação efetiva para `decline`. O Claude Code não mostra sua mensagem de stderr em lugar nenhum.3950if [ "$(jq -r '.action' <<<"$input")" = "accept" ]; then
3951 jq '{hookSpecificOutput: {hookEventName: "ElicitationResult", action: "accept", content: (.content + {username: (.content.username + "@example.com")})}}' <<<"$input"
3952fi
3953```
3800 3954
3801O Claude Code age com base no `hookSpecificOutput` da saída JSON de um hook ElicitationResult e descarta `systemMessage` e `continue`.3955Esta saída bloqueia a resposta:
3956
3957```json theme={null}
3958{
3959 "hookSpecificOutput": {
3960 "hookEventName": "ElicitationResult",
3961 "action": "decline"
3962 }
3963}
3964```
3965
3966O código de saída 2 e um `"decision": "block"` de nível superior também bloqueiam a resposta. [Outras maneiras de recusar uma elicitation](#other-ways-to-decline-an-elicitation) explica qual deles tem efeito quando um hook os combina, o que o usuário vê e quais versões ignoravam `decision`.
3967
3968O Claude Code descarta `reason`, `systemMessage` e `continue` da saída JSON de um hook ElicitationResult, qualquer que seja a `action` que você retorne.
3802 3969
3803<h2 id="prompt-based-hooks">3970<h2 id="prompt-based-hooks">
3804 Hooks baseados em prompt3971 Hooks baseados em prompt
3862 4029
3863Defina `type` para `"prompt"` e forneça uma string `prompt` em vez de um `command`. Use o placeholder `$ARGUMENTS` para injetar dados de entrada do hook em seu texto de prompt.4030Defina `type` para `"prompt"` e forneça uma string `prompt` em vez de um `command`. Use o placeholder `$ARGUMENTS` para injetar dados de entrada do hook em seu texto de prompt.
3864 4031
4032Em um hook de prompt ou [de agente](#agent-based-hooks), você pode escrever o `prompt` como uma regra sobre o que bloquear ou permitir, como "Bloquear qualquer comando Bash que leia arquivos `.env`", ou como uma condição que deve ser verdadeira, como "Todos os testes unitários passam".
4033
3865Este hook `Stop` pede ao LLM para avaliar se todas as tarefas estão completas antes de permitir que Claude termine:4034Este hook `Stop` pede ao LLM para avaliar se todas as tarefas estão completas antes de permitir que Claude termine:
3866 4035
3867```json theme={null}4036```json theme={null}
