297| :-------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |297| :-------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
298| `type` | sim | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` ou `"agent"` |298| `type` | sim | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` ou `"agent"` |
299| `if` | não | Sintaxe de regra de permissão para filtrar quando este hook executa, como `"Bash(git *)"` ou `"Edit(*.ts)"`. O hook apenas é gerado se a chamada de ferramenta corresponde ao padrão, ou se um comando Bash é muito complexo para analisar. Apenas avaliado em eventos de ferramenta: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` e `PermissionDenied`. Em outros eventos, um hook com `if` definido nunca executa. Usa a mesma sintaxe que [regras de permissão](/pt/permissions) |299| `if` | não | Sintaxe de regra de permissão para filtrar quando este hook executa, como `"Bash(git *)"` ou `"Edit(*.ts)"`. O hook apenas é gerado se a chamada de ferramenta corresponde ao padrão, ou se um comando Bash é muito complexo para analisar. Apenas avaliado em eventos de ferramenta: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` e `PermissionDenied`. Em outros eventos, um hook com `if` definido nunca executa. Usa a mesma sintaxe que [regras de permissão](/pt/permissions) |
300| `timeout` | não | Segundos antes de cancelar. Padrões: 600 para comando, 30 para prompt, 60 para agente |300| `timeout` | não | Segundos antes de cancelar. Padrões: 600 para `command`, `http` e `mcp_tool`; 30 para `prompt`; 60 para `agent`. [`UserPromptSubmit`](#userpromptsubmit) reduz o padrão de `command`, `http` e `mcp_tool` para 30 |
301| `statusMessage` | não | Mensagem de spinner personalizada exibida enquanto o hook executa |301| `statusMessage` | não | Mensagem de spinner personalizada exibida enquanto o hook executa |
302| `once` | não | Se `true`, executa apenas uma vez por sessão e depois é removido. Apenas honrado para hooks declarados em [frontmatter de skill](#hooks-in-skills-and-agents); ignorado em arquivos de configurações e frontmatter de agente |302| `once` | não | Se `true`, executa apenas uma vez por sessão e depois é removido. Apenas honrado para hooks declarados em [frontmatter de skill](#hooks-in-skills-and-agents); ignorado em arquivos de configurações e frontmatter de agente |
303 303
558 558
559Hooks 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.559Hooks 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.
560 560
561No macOS e Linux, hooks de comando executam em sua própria sessão sem um terminal controlador a partir de v2.1.139. 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`. Para exibir uma mensagem ao usuário em qualquer plataforma, retorne [`systemMessage`](#json-output) na saída JSON. Para disparar uma notificação de desktop, definir um título de janela ou tocar o sino, retorne [`terminalSequence`](#emit-terminal-notifications) em vez disso.
562
561### Campos de entrada comuns563### Campos de entrada comuns
562 564
563Eventos 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.565Eventos 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.
694* **`hookSpecificOutput`** é um objeto aninhado para eventos que precisam de controle mais rico. Requer um campo `hookEventName` definido para o nome do evento.696* **`hookSpecificOutput`** é um objeto aninhado para eventos que precisam de controle mais rico. Requer um campo `hookEventName` definido para o nome do evento.
695 697
696| Campo | Padrão | Descrição |698| Campo | Padrão | Descrição |
697| :--------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------- |699| :----------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
698| `continue` | `true` | Se `false`, Claude para de processar inteiramente após o hook executar. Tem precedência sobre qualquer campo de decisão específico do evento |700| `continue` | `true` | Se `false`, Claude para de processar inteiramente após o hook executar. Tem precedência sobre qualquer campo de decisão específico do evento |
699| `stopReason` | nenhum | Mensagem mostrada ao usuário quando `continue` é `false`. Não mostrada ao Claude |701| `stopReason` | nenhum | Mensagem mostrada ao usuário quando `continue` é `false`. Não mostrada ao Claude |
700| `suppressOutput` | `false` | Se `true`, oculta stdout do log de debug |702| `suppressOutput` | `false` | Se `true`, oculta stdout do log de debug |
701| `systemMessage` | nenhum | Mensagem de aviso mostrada ao usuário |703| `systemMessage` | nenhum | Mensagem de aviso mostrada ao usuário |
704| `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 |
702 705
703Para parar Claude inteiramente independentemente do tipo de evento:706Para parar Claude inteiramente independentemente do tipo de evento:
704 707
706{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }709{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }
707```710```
708 711
712#### Emitir notificações de terminal
713
714O campo `terminalSequence` requer Claude Code v2.1.141 ou posterior.
715
716Hooks executam sem um terminal controlador, então 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`.
717
718O campo aceita uma string de uma ou mais sequências de escape na lista de permissões:
719
720* OSC `0`, `1`, `2`: títulos de janela e ícone
721* OSC `9`: notificações iTerm2, ConEmu, Windows Terminal e WezTerm, incluindo progresso de barra de tarefas `9;4`
722* OSC `99`: notificações Kitty
723* OSC `777`: notificações urxvt, Ghostty e Warp
724* BEL simples
725
726Sequê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.
727
728O 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:
729
730```bash theme={null}
731#!/bin/bash
732# Hook de notificação: ping no desktop quando Claude Code precisa de atenção.
733input=$(cat)
734title="Claude Code'
735body=$(jq -r '.message // "Needs your attention"' <<<"$input")
736seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")
737jq -nc --arg seq "$seq" '{terminalSequence: $seq}'
738```
739
740A forma `{ "terminalSequence": "..." }` é a mesma de qualquer shell ou linguagem. No Windows, construa a string de escape em PowerShell ou um script e emita o mesmo objeto JSON.
741
742<Note>
743 `terminalSequence` é a substituição suportada para hooks que anteriormente escreviam sequências de escape diretamente para `/dev/tty`. A lista de permissões é restrita a sequências que não podem mover o cursor ou alterar cores, para que um hook nunca possa corromper um prompt na tela.
744</Note>
745
709#### Adicionar contexto para Claude746#### Adicionar contexto para Claude
710 747
711O campo `additionalContext` passa uma string do seu hook para a janela de contexto do Claude. O Claude Code envolve a string em um lembrete do sistema 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.748O campo `additionalContext` passa uma string do seu hook para a janela de contexto do Claude. O Claude Code envolve a string em um lembrete do sistema 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.
989 1026
990Executa quando o usuário submete um prompt, antes do Claude processá-lo. Isso permite que você adicione contexto adicional baseado no prompt/conversa, valide prompts ou bloqueie certos tipos de prompts.1027Executa quando o usuário submete um prompt, antes do Claude processá-lo. Isso permite que você adicione contexto adicional baseado no prompt/conversa, valide prompts ou bloqueie certos tipos de prompts.
991 1028
1029Hooks `UserPromptSubmit` têm um timeout padrão de 30 segundos para tipos `command`, `http` e `mcp_tool`, mais curto que o padrão de 600 segundos para esses tipos em outros eventos. Porque este hook executa antes de cada prompt e bloqueia processamento do modelo até que seja concluído, um hook travado paralisa a sessão. Se seu hook precisa de mais tempo, defina o campo `timeout` na entrada do hook.
1030
992#### Entrada de UserPromptSubmit1031#### Entrada de UserPromptSubmit
993 1032
994Além dos [campos de entrada comuns](#common-input-fields), hooks UserPromptSubmit recebem o campo `prompt` contendo o texto que o usuário submeteu.1033Além dos [campos de entrada comuns](#common-input-fields), hooks UserPromptSubmit recebem o campo `prompt` contendo o texto que o usuário submeteu.
2598 2637
2599Quando um hook assíncrono dispara, Claude Code inicia o processo do hook e imediatamente continua sem esperar que termine. O hook recebe a mesma entrada JSON via stdin que um hook síncrono.2638Quando um hook assíncrono dispara, Claude Code inicia o processo do hook e imediatamente continua sem esperar que termine. O hook recebe a mesma entrada JSON via stdin que um hook síncrono.
2600 2639
2601Após o processo em background sair, se o hook produziu uma resposta JSON com um campo `systemMessage` ou `additionalContext`, esse conteúdo é entregue ao Claude como contexto no próximo turno de conversa.2640Após o processo em background sair, se o hook produziu uma resposta JSON com um campo `additionalContext`, esse conteúdo é entregue ao Claude como contexto no próximo turno de conversa. Um campo `systemMessage` é mostrado para você, não para Claude.
2602 2641
2603Notificações de conclusão de hook assíncrono são suprimidas por padrão. Para vê-las, ative modo verbose com `Ctrl+O` ou inicie Claude Code com `--verbose`.2642Notificações de conclusão de hook assíncrono são suprimidas por padrão. Para vê-las, ative modo verbose com `Ctrl+O` ou inicie Claude Code com `--verbose`.
2604 2643
2619 exit 02658 exit 0
2620fi2659fi
2621 2660
2622# Execute testes e relate resultados via systemMessage2661# Execute testes e relate resultados ao Claude via additionalContext
2623RESULT=$(npm test 2>&1)2662RESULT=$(npm test 2>&1)
2624EXIT_CODE=$?2663EXIT_CODE=$?
2625 2664
2626if [ $EXIT_CODE -eq 0 ]; then2665if [ $EXIT_CODE -eq 0 ]; then
2627 echo "{\"systemMessage\": \"Tests passed after editing $FILE_PATH\"}"2666 MSG="Tests passed after editing $FILE_PATH"
2628else2667else
2629 echo "{\"systemMessage\": \"Tests failed after editing $FILE_PATH: $RESULT\"}"2668 MSG="Tests failed after editing $FILE_PATH: $RESULT"
2630fi2669fi
2670jq -nc --arg msg "$MSG" '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $msg}}'
2631```2671```
2632 2672
2633Então adicione esta configuração a `.claude/settings.json` na raiz do seu projeto. A flag `async: true` permite que Claude continue trabalhando enquanto testes executam:2673Então adicione esta configuração a `.claude/settings.json` na raiz do seu projeto. A flag `async: true` permite que Claude continue trabalhando enquanto testes executam:
