476| `async` | não | Se `true`, executa em background sem bloquear. Consulte [Executar hooks em background](#run-hooks-in-the-background) |476| `async` | não | Se `true`, executa em background sem bloquear. Consulte [Executar hooks em background](#run-hooks-in-the-background) |
477| `asyncRewake` | não | Se `true`, executa em background e acorda Claude na saída do código 2. O stderr do hook, ou stdout se stderr estiver vazio, é mostrado ao Claude como um [lembrete do sistema](/docs/pt/glossary#system-reminder) para que possa reagir a uma falha de background de longa duração |477| `asyncRewake` | não | Se `true`, executa em background e acorda Claude na saída do código 2. O stderr do hook, ou stdout se stderr estiver vazio, é mostrado ao Claude como um [lembrete do sistema](/docs/pt/glossary#system-reminder) para que possa reagir a uma falha de background de longa duração |
478| `shell` | não | Shell a usar para este hook. Aceita `"bash"` ou `"powershell"`. Padrão é `"bash"`, ou `"powershell"` no Windows quando Git Bash não está instalado. Definir `"powershell"` executa o comando via PowerShell no Windows. Não requer `CLAUDE_CODE_USE_POWERSHELL_TOOL` já que hooks geram PowerShell diretamente. Ignorado quando `args` é definido |478| `shell` | não | Shell a usar para este hook. Aceita `"bash"` ou `"powershell"`. Padrão é `"bash"`, ou `"powershell"` no Windows quando Git Bash não está instalado. Definir `"powershell"` executa o comando via PowerShell no Windows. Não requer `CLAUDE_CODE_USE_POWERSHELL_TOOL` já que hooks geram PowerShell diretamente. Ignorado quando `args` é definido |
479| `onFailure` | não | O que acontece com a ação quando o hook falha: `"continue"`, o padrão, ou `"block"`. Consulte [Bloquear a ação quando um hook falha](#block-the-action-when-a-hook-fails). Requer Claude Code v2.1.295 ou posterior |
479 480
480<a id="exec-form-and-shell-form" />481<a id="exec-form-and-shell-form" />
481 482
533| `url` | sim | URL para enviar a solicitação POST |534| `url` | sim | URL para enviar a solicitação POST |
534| `headers` | não | Cabeçalhos HTTP adicionais como pares chave-valor. Valores suportam interpolação de variável de ambiente usando sintaxe `$VAR_NAME` ou `${VAR_NAME}`. Apenas variáveis listadas em `allowedEnvVars` são resolvidas |535| `headers` | não | Cabeçalhos HTTP adicionais como pares chave-valor. Valores suportam interpolação de variável de ambiente usando sintaxe `$VAR_NAME` ou `${VAR_NAME}`. Apenas variáveis listadas em `allowedEnvVars` são resolvidas |
535| `allowedEnvVars` | não | Lista de nomes de variáveis de ambiente que podem ser interpoladas em valores de cabeçalho. Referências a variáveis não listadas são substituídas por strings vazias. Obrigatório para qualquer interpolação de variável de ambiente funcionar |536| `allowedEnvVars` | não | Lista de nomes de variáveis de ambiente que podem ser interpoladas em valores de cabeçalho. Referências a variáveis não listadas são substituídas por strings vazias. Obrigatório para qualquer interpolação de variável de ambiente funcionar |
537| `onFailure` | não | O que acontece com a ação quando o hook falha: `"continue"`, o padrão, ou `"block"`. Consulte [Bloquear a ação quando um hook falha](#block-the-action-when-a-hook-fails). Requer Claude Code v2.1.295 ou posterior |
536 538
537Claude Code envia a [entrada JSON](#hook-input-and-output) do hook como corpo da solicitação POST com `Content-Type: application/json`. O corpo da resposta usa o mesmo [formato de saída JSON](#json-output) que hooks de comando.539Claude Code envia a [entrada JSON](#hook-input-and-output) do hook como corpo da solicitação POST com `Content-Type: application/json`. O corpo da resposta usa o mesmo [formato de saída JSON](#json-output) que hooks de comando.
538 540
821 Saída de código de saída823 Saída de código de saída
822</h3>824</h3>
823 825
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.826O código de saída do seu hook diz ao Claude Code se deve continuar com a ação que disparou o hook, como uma chamada de ferramenta ou um prompt. Uma execução que termina tem um de três resultados:
825 827
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).828* **Sucesso**: seu hook sai com 0. Claude Code aplica quaisquer campos de [saída JSON](#json-output) que seu hook imprimiu, e a ação prossegue, a menos que esses campos a bloqueiem ou neguem.
829* **Erro bloqueador**: seu hook sai com 2. Em [eventos que podem bloquear](#exit-code-2-behavior-per-event), Claude Code interrompe a ação.
830* **Erro não-bloqueador**: seu hook sai com qualquer outro código, ou falha de alguma outra forma, como não iniciar ou imprimir JSON inválido. A ação prossegue, e em eventos como `PreToolUse` você vê um aviso `<hook name> hook error` na transcrição. Se você quiser que um hook com falha bloqueie a ação, defina [`onFailure: "block"`](#block-the-action-when-a-hook-fails).
831
832O que seu hook imprime em stdout pode mudar o resultado. Por exemplo, se um hook `PreToolUse` sai com 1 mas imprime JSON que passa na validação, a execução é um sucesso e os campos JSON decidem o que acontece. Para encontrar o resultado do seu hook em um evento como `PreToolUse`, combine o que ele imprimiu em stdout na primeira coluna com seu código de saída no topo:
833
834| Stdout | Saída 0 | Saída 2 | Qualquer outro código de saída |
835| :- | :- | :- | :- |
836| Objeto JSON que passa na [validação de esquema](#json-output) | Sucesso. Os campos se aplicam | Erro bloqueador. Claude Code ainda lê os campos, mas eles não podem sobrescrever o bloqueio | Sucesso. Claude Code ignora o código de saída, e apenas os campos decidem. Com [`onFailure: "block"`](#block-the-action-when-a-hook-fails), isso conta como uma falha |
837| JSON que [não pode ser analisado](#exit-code-0) ou falha na validação de esquema | Erro não-bloqueador. O aviso carrega a mensagem de análise ou validação | Erro bloqueador. Seu stderr é a razão | Erro não-bloqueador. O aviso carrega a mensagem de análise ou validação |
838| [Texto simples](#exit-code-0), ou nada | Sucesso | Erro bloqueador. Seu stderr é a razão | Erro não-bloqueador. O aviso carrega a primeira linha do seu stderr |
839
840Alguns eventos têm suas próprias regras:
841
842* **`WorktreeCreate`**: qualquer código de saída diferente de zero faz a criação de worktree falhar, não importa o que seu JSON diga.
843* **`WorktreeRemove`**: qualquer código de saída diferente de zero faz a remoção de worktree falhar se o diretório ainda existir depois.
844* **`Stop`, `SubagentStop`, `TaskCompleted` e o hook `UserPromptSubmit` de um plugin**: quando seu hook sai com 2 sem nada em stdout e seu stderr diz que um arquivo está ausente, como `No such file or directory`, Claude Code trata a execução como um erro não-bloqueador.
845* **`Elicitation` e `ElicitationResult`**: Claude Code aplica seu `hookSpecificOutput` quando seu hook sai com 0, e o ignora em qualquer outro código de saída.
846* **Eventos que descartam a saída do hook, como `StopFailure`**: Claude Code ignora seu JSON em qualquer código de saída, exceto campos de efeito colateral como `terminalSequence`, que ainda disparam.
847
848Para verificar o que o código de saída 2 faz no seu evento, consulte [Comportamento de código de saída 2 por evento](#exit-code-2-behavior-per-event). Para verificar quais campos de decisão ele honra, consulte [Controle de decisão](#decision-control).
827 849
828<h4 id="exit-code-0">850<h4 id="exit-code-0">
829 Código de saída 0851 Código de saída 0
835 857
836Se Claude Code lê seu stdout como [saída JSON](#json-output) ou como texto simples depende de como ele começa e termina, ignorando espaço em branco ao redor:858Se Claude Code lê seu stdout como [saída JSON](#json-output) ou como texto simples depende de como ele começa e termina, ignorando espaço em branco ao redor:
837 859
838* **Começa com `{` e termina com `}`**: Claude Code o analisa como JSON. Quando a saída é duas ou mais linhas que cada uma analisa como JSON por conta própria, e nenhuma linha é um objeto [saída JSON](#json-output) que define um campo, Claude Code trata toda a saída como texto simples. Quando uma dessas linhas define um campo, toda a saída é uma falha de análise, descrita abaixo.860* **Começa com `{` e termina com `}`**: Claude Code o analisa como JSON. Quando a saída é duas ou mais linhas que cada uma analisa como JSON por conta própria, e nenhuma linha é um objeto [saída JSON](#json-output) que define um campo, Claude Code trata toda a saída como texto simples. Quando uma dessas linhas define um campo, toda a saída é uma falha de análise.
839* **Começa com `{` mas não termina com `}`**: Claude Code o trata como texto simples.861* **Começa com `{` mas não termina com `}`**: Claude Code o trata como texto simples.
840* **Começa com qualquer outra coisa**: Claude Code o trata como texto simples, um array JSON ou uma string JSON entre aspas incluída.862* **Começa com qualquer outra coisa**: Claude Code o trata como texto simples, um array JSON ou uma string JSON entre aspas incluída.
841 863
842Para eventos que usam o modelo de decisão padrão, saída 0 com um objeto analisado que falha na validação de esquema é um erro não-bloqueador: a ação prossegue, e a transcrição mostra um aviso `<hook name> hook error` com a mensagem de validação. O mesmo acontece em qualquer código de saída diferente de 2, enquanto [saída 2 ainda bloqueia](#exit-code-2).864Quando Claude Code tenta analisar seu stdout como JSON e não consegue, ou o objeto analisado falha na [validação de esquema](#json-output), a execução é um [erro não-bloqueador](#exit-code-output). O aviso `<hook name> hook error` carrega a mensagem de análise ou validação. Nos eventos que adicionam stdout em texto simples como contexto, Claude Code não adiciona stdout que não conseguiu analisar.
843
844Para eventos que usam o modelo de decisão padrão, quando Claude Code tenta analisar seu stdout como JSON e não consegue, ele relata um erro não-bloqueador em cada código de saída diferente de 2. A transcrição mostra um aviso `<hook name> hook error` com a mensagem de análise. Nos eventos que adicionam stdout em texto simples como contexto, Claude Code não adiciona o texto. Antes de v2.1.248, Claude Code tratava esse stdout como texto simples.
845 865
846Stderr de um hook que sai 0 vai apenas para o log de debug, nunca para a transcrição, e Claude nunca vê. Para lê-lo você mesmo, ative [debug logging](#debug-hooks). Para exibir um aviso para Claude de um hook `PostToolUse` ou `PostToolUseFailure`, saia 2 em vez disso para que [Claude veja o stderr](#exit-code-2-behavior-per-event) mesmo que a ferramenta já tenha executado.866Claude nunca vê stderr de um hook que sai com 0. Para lê-lo você mesmo em eventos como `PreToolUse`, ative [debug logging](#debug-hooks). Para exibir um aviso para Claude de um hook `PostToolUse` ou `PostToolUseFailure`, saia com 2 em vez disso para que [Claude veja o stderr](#exit-code-2-behavior-per-event) mesmo que a ferramenta já tenha executado.
847 867
848<h4 id="exit-code-2">868<h4 id="exit-code-2">
849 Código de saída 2869 Código de saída 2
850</h4>870</h4>
851 871
852Saída 2 significa um erro bloqueador. Em [eventos que podem bloquear](#exit-code-2-behavior-per-event), saída 2 bloqueia se você imprime JSON ou não: até mesmo um JSON `permissionDecision` de `"allow"` não pode substituir. Claude Code ainda lê qualquer [saída JSON](#json-output) válida em stdout. Em `Elicitation` e `ElicitationResult`, o `hookSpecificOutput` de um hook exit-2 é ignorado.872Saia com código 2 para bloquear a ação. Em [eventos que podem bloquear](#exit-code-2-behavior-per-event), Claude Code interrompe a ação: um hook `PreToolUse` bloqueia a chamada de ferramenta, por exemplo, e um hook `UserPromptSubmit` rejeita o prompt.
853 873
854A mensagem de bloqueio é a razão da decisão de bloqueio do seu JSON quando faz uma, e seu texto stderr caso contrário. O que o bloqueio faz varia por evento: `PreToolUse` bloqueia a chamada da ferramenta, `UserPromptSubmit` rejeita o prompt, e assim por diante. [Comportamento de código de saída 2 por evento](#exit-code-2-behavior-per-event) lista o efeito para cada evento, e cada seção de evento diz onde a mensagem vai.874A mensagem que acompanha o bloqueio é o stderr do seu hook. Se seu hook também imprimiu JSON que toma uma decisão de bloqueio, Claude Code usa a razão dessa decisão em vez disso.
855 875
856Um hook que sai 2 enquanto imprime JSON que falha na validação de esquema [saída JSON](#json-output) ainda bloqueia: Claude Code usa stderr como a razão de bloqueio e registra a falha de validação no log de debug. Antes de v2.1.214, Claude Code tratava essa combinação como um erro não-bloqueador e a ação prosseguia.876A saída 2 bloqueia mesmo quando seu hook imprime JSON:
877
878* **JSON que passa na validação de esquema**: Claude Code ainda lê os campos de [saída JSON](#json-output), mas eles não podem sobrescrever o bloqueio. Nem mesmo um `permissionDecision` de `"allow"` deixa a ação passar. Em `Elicitation` e `ElicitationResult`, o `hookSpecificOutput` de um hook exit-2 é ignorado.
879* **JSON que falha na validação de esquema**: o hook ainda bloqueia. Claude Code usa seu stderr como a razão de bloqueio e registra a falha de validação no log de debug.
857 880
858Este script bloqueia comandos `rm` saindo 2 e deixa cada outro comando para o fluxo de permissão normal:881Este script bloqueia comandos `rm` saindo 2 e deixa cada outro comando para o fluxo de permissão normal:
859 882
871exit 0 # Sem decisão: o fluxo de permissão normal se aplica894exit 0 # Sem decisão: o fluxo de permissão normal se aplica
872```895```
873 896
897Com este script registrado como um hook `PreToolUse` em `Bash`, um comando que começa com `rm` é bloqueado, e Claude recebe o stderr do hook como o erro da ferramenta, prefixado com o nome do evento, o nome da ferramenta e o comando do hook:
898
899```text theme={null}
900PreToolUse:Bash hook error: [${CLAUDE_PROJECT_DIR}/.claude/hooks/no-rm.sh]: Blocked: rm commands are not allowed
901```
902
874<h4 id="other-exit-codes">903<h4 id="other-exit-codes">
875 Outros códigos de saída904 Outros códigos de saída
876</h4>905</h4>
877 906
878Qualquer outro código de saída não bloqueia por conta própria para a maioria dos eventos de hook. O que acontece depende de seu stdout:907Quando seu hook sai com um código diferente de 0 ou 2 e imprime texto simples ou nada em stdout, a execução é um [erro não-bloqueador](#exit-code-output). Você vê um aviso `<hook name> hook error` na transcrição com `Failed with non-blocking status code:` e a primeira linha do stderr do seu hook. Por exemplo, quando um hook `PreToolUse` em `Bash` imprime `something broke` em stderr e sai com 1, o aviso `PreToolUse:Bash hook error` carrega esta linha:
879 908
880* Com um objeto analisado que passa na validação de esquema, para eventos que usam o modelo de decisão padrão, Claude Code ignora o código de saída e apenas o JSON decide o resultado:909```text theme={null}
881 * Cada campo que o evento suporta é honrado, incluindo `permissionDecision`, `additionalContext`, `updatedInput` e `systemMessage`, e o hook não é relatado como um erro.910Failed with non-blocking status code: something broke
882 * [Controle de decisão](#decision-control) lista os campos de decisão por evento; campos universais como `systemMessage` seguem a tabela [Saída JSON](#json-output).911```
883* Com um objeto analisado que falha na validação de esquema, para eventos que usam o modelo de decisão padrão, é o mesmo erro não-bloqueador que [na saída 0](#exit-code-0): a ação prossegue, e o aviso `<hook name> hook error` carrega a mensagem de validação.
884* Com stdout que Claude Code [tenta analisar como JSON](#exit-code-0) e não consegue, Claude Code relata o mesmo erro não-bloqueador que na saída 0 para eventos que usam o modelo de decisão padrão. A ação prossegue, e o aviso carrega a mensagem de análise.
885* Com stdout que Claude Code [trata como texto simples](#exit-code-0), ou com stdout vazio, é um erro não-bloqueador para a maioria dos eventos de hook: a ação prossegue, e a transcrição mostra um aviso `<hook name> hook error` seguido pela primeira linha de stderr, prefixado com `Failed with non-blocking status code:`. Para capturar o stderr completo, ative [debug logging](#debug-hooks).
886 912
887Eventos fora do modelo de decisão padrão mantêm suas próprias linhas na [tabela por evento](#exit-code-2-behavior-per-event): `WorktreeCreate` falha na criação em qualquer saída não-zero não importa o que seu JSON diz, e eventos que descartam saída de hook inteiramente, como `StopFailure`, ignoram seu JSON em cada código de saída, além de campos de efeito colateral como `terminalSequence`, que ainda disparam.913Para capturar o stderr completo em vez de sua primeira linha, ative [debug logging](#debug-hooks).
888 914
889Um hook que não consegue iniciar cai no mesmo balde não-bloqueador. Quando o caminho do script não existe ou não é executável, o shell sai com um código como 127 e você vê o mesmo aviso com a mensagem do interpretador, por exemplo `Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory`. Para a maioria dos eventos de hook, a ação prossegue. Quando você configura um hook de política, observe este aviso em sua primeira execução: um caminho digitado incorretamente em `settings.json` deixa o portão silenciosamente desabilitado.915Um hook que não consegue iniciar também é um erro não-bloqueador. Na forma shell, quando o caminho do script não existe ou não é executável, o shell sai com um código como 127 e o aviso carrega a mensagem do interpretador, por exemplo `Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory`. Quando você configura um hook de política, observe este aviso em sua primeira execução, porque um caminho digitado incorretamente em `settings.json` significa que o hook nunca executa. Para bloquear a ação em vez disso, defina [`onFailure: "block"`](#block-the-action-when-a-hook-fails).
890 916
891<Warning>917<Warning>
892 Para a maioria dos eventos de hook, código de saída 2 é o único código de saída que bloqueia apenas através do código. Sem JSON válido em stdout, Claude Code trata código de saída 1 como um erro não-bloqueador e prossegue com a ação, mesmo que 1 seja o código de falha Unix convencional. Se seu hook se destina a impor uma política, use `exit 2`. Os eventos de worktree diferem: qualquer código de saída não-zero de `WorktreeCreate` aborta a criação de worktree, e qualquer código de saída não-zero de `WorktreeRemove` faz a remoção de worktree falhar se o diretório ainda existir depois.918 Sem JSON válido em stdout, Claude Code trata código de saída 1 como um erro não-bloqueador, mesmo que 1 seja o código de falha Unix convencional. Se seu hook se destina a impor uma política, use `exit 2`.
893</Warning>919</Warning>
894 920
895<h4 id="timeouts">921<h4 id="timeouts">
900 926
901Em [`PreModelSwitch`](#premodelswitch), um hook cancelado em seu timeout bloqueia a mudança de modelo. Em `PreToolUse`, as duas famílias de hook diferem:927Em [`PreModelSwitch`](#premodelswitch), um hook cancelado em seu timeout bloqueia a mudança de modelo. Em `PreToolUse`, as duas famílias de hook diferem:
902 928
903* Um hook `command`, `http` ou `mcp_tool` expirado não bloqueia a chamada da ferramenta. A chamada continua através do [fluxo de permissão](/docs/pt/permissions) normal, portanto não conte com um hook travado para agir como um portão.929* Um hook `command`, `http` ou `mcp_tool` expirado não bloqueia a chamada da ferramenta. A chamada continua através do [fluxo de permissão](/docs/pt/permissions) normal, portanto não conte com um hook travado para agir como um portão. Para bloquear a chamada quando um hook `command` ou `http` atinge o timeout, defina [`onFailure: "block"`](#block-the-action-when-a-hook-fails).
904* Um hook de callback [Agent SDK](/docs/pt/agent-sdk/hooks) que excede seu timeout [bloqueia a chamada da ferramenta](#pretooluse).930* Um hook de callback [Agent SDK](/docs/pt/agent-sdk/hooks) que excede seu timeout [bloqueia a chamada da ferramenta](#pretooluse).
905 931
932<h4 id="block-the-action-when-a-hook-fails">
933 Bloquear a ação quando um hook falha
934</h4>
935
936Na maioria dos eventos, quando um hook falha ou atinge o timeout, Claude Code ainda executa a ação, portanto um hook de política com um caminho errado ou um script que trava deixa tudo passar. Para bloquear a ação em vez disso, defina `"onFailure": "block"` em um hook `command` ou `http`. O valor padrão é `"continue"`. Requer Claude Code v2.1.295 ou posterior.
937
938Este hook `PreToolUse` em `.claude/settings.json` executa um script do projeto antes de cada comando Bash, e bloqueia o comando se o script falhar:
939
940```json theme={null}
941{
942 "hooks": {
943 "PreToolUse": [
944 {
945 "matcher": "Bash",
946 "hooks": [
947 {
948 "type": "command",
949 "command": "node",
950 "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js"],
951 "onFailure": "block"
952 }
953 ]
954 }
955 ]
956 }
957}
958```
959
960Para testá-lo, deixe `check-command.js` ausente e peça a Claude para executar um comando Bash como `ls`. Claude Code bloqueia a chamada, e o erro inclui `failed; blocking because onFailure is "block"` seguido pela própria saída de erro do node, reduzida aqui a uma linha:
961
962```text theme={null}
963PreToolUse:Bash hook error: [node ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js]: failed; blocking because onFailure is "block"
964Error: Cannot find module '/path/to/project/.claude/hooks/check-command.js'
965```
966
967Após um timeout, a mensagem diz `timed out` em vez de `failed`. Sem `onFailure` definido, o mesmo script ausente é um erro não-bloqueador e `ls` é executado.
968
969Cada um destes conta como uma falha:
970
971* **Não consegue iniciar**: um hook de comando falha ao iniciar, por exemplo porque o script ou executável não existe
972* **Código de saída diferente de 0 ou 2**: conta para um hook de comando mesmo que ele tenha impresso JSON que permite a ação, como `permissionDecision: "allow"`. Para retornar uma decisão JSON, saia com 0
973* **Erro HTTP**: a conexão de um hook HTTP falha, ou o status da resposta não é 2xx
974* **Timeout**: o hook atinge seu [`timeout`](#common-fields)
975* **Saída inválida**: a saída JSON [não pode ser analisada](#exit-code-0) ou falha na [validação de esquema](#json-output). Para um hook HTTP, um corpo 2xx que não é vazio nem um objeto JSON também conta. Stdout em texto simples de um hook de comando não é uma falha
976
977Com `"block"` definido, uma falha faz o que o [código de saída 2 faz nesse evento](#exit-code-2-behavior-per-event), exceto em `PermissionRequest`, onde ela nega a solicitação. Por exemplo, uma falha em `PreToolUse` bloqueia a chamada de ferramenta e uma falha em `UserPromptSubmit` bloqueia o prompt.
978
979O campo não tem efeito nestes hooks:
980
981* **Hooks `Stop`, `SubagentStop`, `TaskCompleted` e `TeammateIdle`**: o código de saída 2 nesses eventos manda Claude de volta para continuar trabalhando, e Claude não consegue reparar um hook que não executa
982* **Hooks de comando em segundo plano**: hooks de comando que definem [`async` ou `asyncRewake`](#run-hooks-in-the-background)
983
906<h4 id="exit-code-2-behavior-per-event">984<h4 id="exit-code-2-behavior-per-event">
907 Comportamento de código de saída 2 por evento985 Comportamento de código de saída 2 por evento
908</h4>986</h4>
960* **Falha de conexão**: erro não-bloqueador, execução continua1038* **Falha de conexão**: erro não-bloqueador, execução continua
961* **Timeout**: o hook é cancelado, conforme descrito em [Timeouts](#timeouts)1039* **Timeout**: o hook é cancelado, conforme descrito em [Timeouts](#timeouts)
962 1040
963Diferentemente de hooks de comando, hooks HTTP não podem sinalizar um erro bloqueador apenas através de códigos de status. Para bloquear uma chamada de ferramenta ou negar uma permissão, retorne uma resposta 2xx com um corpo JSON contendo os campos de decisão apropriados.1041Hooks HTTP não podem sinalizar um erro bloqueador apenas através do código de status: um status não-2xx ou uma conexão com falha é um [erro não-bloqueador](#exit-code-output). Para bloquear uma chamada de ferramenta ou negar uma permissão, retorne uma resposta 2xx com um corpo JSON contendo os campos de decisão apropriados. Para bloquear a ação quando a requisição falha ou retorna um status não-2xx, defina [`onFailure: "block"`](#block-the-action-when-a-hook-fails).
964 1042
965<h3 id="json-output">1043<h3 id="json-output">
966 Saída JSON1044 Saída JSON
1237 Controle de decisão do SessionStart1315 Controle de decisão do SessionStart
1238</h4>1316</h4>
1239 1317
1240O Claude Code adiciona ao contexto do Claude o stdout que ele [trata como texto simples](#exit-code-0). Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar estes campos específicos do evento:1318Um hook SessionStart pode adicionar contexto para o Claude, fornecer a primeira mensagem do usuário, definir o título da sessão, observar arquivos e recarregar skills. Retorne o campo correspondente a cada um, além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks:
1241 1319
1242| Campo | Descrição |1320| Campo | Descrição |
1243| :- | :- |1321| :- | :- |
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 |1322| `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 |
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 |1323| `initialUserMessage` | String usada como a primeira mensagem do usuário da sessão, no [modo não interativo](/docs/pt/headless) com a flag `-p`. Ela se torna o primeiro turno mesmo que você não passe nenhum prompt. Um prompt que você passar vem em seguida como o próximo turno |
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"` |1324| `sessionTitle` | Define o título da sessão, com o mesmo efeito de `/rename`. Aplica-se quando `source` é `"startup"`, `"resume"` ou `"fork"` |
1247| `watchPaths` | Array de caminhos absolutos a observar para eventos [FileChanged](#filechanged) durante esta sessão |1325| `watchPaths` | Array de caminhos absolutos a observar para eventos [FileChanged](#filechanged) durante esta sessão |
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 |1326| `reloadSkills` | Booleano. Quando `true`, o Claude Code verifica novamente os diretórios de [skills](/docs/pt/skills) e comandos após a conclusão dos hooks SessionStart. Consulte [Recarregar skills que um hook instala](#reload-skills-that-a-hook-installs) |
1327
1328Esta saída adiciona contexto e nomeia a sessão:
1249 1329
1250```json theme={null}1330```json theme={null}
1251{1331{
1257}1337}
1258```1338```
1259 1339
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`.1340Um hook que apenas adiciona contexto pode imprimi-lo sem construir JSON, porque o Claude Code adiciona o [stdout em texto simples](#exit-code-0) de um hook SessionStart ao contexto do Claude.
1341
1342Se o hook SessionStart do seu plugin fornecer `initialUserMessage` ou `sessionTitle`, instale o plugin antes de a sessão começar. O Claude Code ignora ambos os campos de um plugin cuja instalação termina depois que os hooks SessionStart já foram executados.
1343
1344<h4 id="reload-skills-that-a-hook-installs">
1345 Recarregar skills que um hook instala
1346</h4>
1347
1348Para disponibilizar na mesma sessão as skills que um hook SessionStart instala, retorne `reloadSkills`. A descoberta de skills normalmente é executada antes de os hooks SessionStart terminarem, então, sem isso, arquivos que um hook grava em `~/.claude/skills/` ou `.claude/skills/` podem estar ausentes quando o primeiro prompt for executado.
1261 1349
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:1350Este exemplo sincroniza um repositório compartilhado de skills e solicita a nova verificação:
1263 1351
1264```bash theme={null}1352```bash theme={null}
1265#!/bin/bash1353#!/bin/bash
1270echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1358echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'
1271```1359```
1272 1360
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.1361A URL do repositório é um espaço reservado. Substitua-a pelo seu próprio repositório de skills.
1274 1362
1275<h4 id="persist-environment-variables">1363<h4 id="persist-environment-variables">
1276 Persistir variáveis de ambiente1364 Persistir variáveis de ambiente
1419 1507
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.1508Os 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.
1421 1509
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.1510Com exceção de um hook de comando que você executa com [`async: true`](#run-hooks-in-the-background), um hook `UserPromptSubmit` de comando, HTTP ou ferramenta MCP que atinge seu timeout é cancelado e sua saída, incluindo qualquer `additionalContext`, é descartada. O prompt ainda chega ao Claude sem esse contexto. Para bloquear o prompt em vez disso, defina [`onFailure: "block"`](#block-the-action-when-a-hook-fails) em um hook de comando ou HTTP. A transcrição mostra um aviso nomeando o hook, o timeout que foi atingido e que a saída foi descartada.
1423 1511
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.1512Um [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.
1425 1513
1860| :- | :- | :- | :- |1948| :- | :- | :- | :- |
1861| `url` | string | `"https://example.com/api"` | URL de onde buscar o conteúdo |1949| `url` | string | `"https://example.com/api"` | URL de onde buscar o conteúdo |
1862| `prompt` | string | `"Extract the API endpoints"` | Prompt a ser executado sobre o conteúdo buscado |1950| `prompt` | string | `"Extract the API endpoints"` | Prompt a ser executado sobre o conteúdo buscado |
1951| `offset` | number | `100000` | Número opcional de caracteres a pular a partir do início da página. O Claude o define para continuar lendo uma página longa. Exige o Claude Code v2.1.290 ou posterior |
1863 1952
1864<h5 id="websearch">1953<h5 id="websearch">
1865 WebSearch1954 WebSearch
2112| `message` | Apenas para `"deny"`: informa ao Claude por que a permissão foi negada |2201| `message` | Apenas para `"deny"`: informa ao Claude por que a permissão foi negada |
2113| `interrupt` | Apenas para `"deny"`: se `true`, interrompe o Claude |2202| `interrupt` | Apenas para `"deny"`: se `true`, interrompe o Claude |
2114 2203
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.2204Um hook que sai com código 2 sem um objeto `decision` deixa o fluxo de permissão inalterado, e seu stderr é descartado. Para conceder ou negar a solicitação, retorne o objeto `decision`.
2116 2205
2117```json theme={null}2206```json theme={null}
2118{2207{
2678 Controle de decisão de TaskCreated2767 Controle de decisão de TaskCreated
2679</h4>2768</h4>
2680 2769
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.2770Um hook TaskCreated pode bloquear a criação com o código de saída 2 ou com uma decisão JSON. De qualquer forma, o Claude Code exclui a tarefa e retorna sua mensagem ao Claude como o erro da ferramenta. O Claude Code ignora `continue: false` deste evento e o Claude continua trabalhando.
2682 2771
2683* **Código de saída 2**: o Claude Code retorna o texto do stderr como a mensagem.2772* **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.2773* **JSON `{"decision": "block", "reason": "..."}`**: o Claude Code retorna `reason` como a mensagem.
3561 3650
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.3651O 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.
3563 3652
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.3653Um hook PreModelSwitch que não responde antes do seu timeout bloqueia a troca. Para saber o que um timeout faz em outros eventos, consulte [Timeouts](#timeouts). O timeout padrão para este evento é de 30 segundos. O `PreModelSwitch` executa apenas hooks `command`, `http` e `mcp_tool`, portanto os padrões de `prompt` e `agent` não se aplicam.
3565 3654
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).3655Um hook que sai com um código diferente de 0 ou 2 e não imprime nenhuma decisão JSON é um erro não bloqueante, conforme descrito em [Outros códigos de saída](#other-exit-codes).
3567 3656
3568<h3 id="postmodelswitch">3657<h3 id="postmodelswitch">
3569 PostModelSwitch3658 PostModelSwitch
4279Hooks assíncronos têm restrições adicionais comparados a hooks síncronos:4368Hooks assíncronos têm restrições adicionais comparados a hooks síncronos:
4280 4369
4281* Saída de hook é entregue no próximo turno de conversa. Se a sessão está ociosa, a resposta espera até a próxima interação do usuário. Exceção: um hook `asyncRewake` que sai com código 2 acorda Claude imediatamente mesmo quando a sessão está ociosa.4370* Saída de hook é entregue no próximo turno de conversa. Se a sessão está ociosa, a resposta espera até a próxima interação do usuário. Exceção: um hook `asyncRewake` que sai com código 2 acorda Claude imediatamente mesmo quando a sessão está ociosa.
4282* Cada execução cria um processo em background separado. Não há desduplicação através de múltiplos disparos do mesmo hook assíncrono.4371* Cada execução cria um processo em background separado.
4283 4372
4284<h2 id="security-considerations">4373<h2 id="security-considerations">
4285 Considerações de segurança4374 Considerações de segurança
