Hooks do Claude Code: eventos, exemplos e como funcionam

Eventos de hooks do Claude Code

A referência lista mais de trinta eventos. Estes são os que a maioria dos hooks usa; um matcher restringe um hook a certas ferramentas, arquivos ou origens.

Onde colocar os hooks

Exemplos de hooks do Claude Code, passo a passo

Adicione cada bloco sob a chave hooks de um arquivo de configuração; se o arquivo já tiver um objeto hooks, adicione o evento como uma chave irmã em vez de substituí-lo. Rode /hooks para confirmar que o Claude Code carregou o hook. Você também pode pedir para o Claude escrever o hook por você.

1. Receba uma notificação na área de trabalho quando o Claude precisar de você

   Um hook Notification em ~/.claude/settings.json. Este usa osascript no macOS; use notify-send no Linux ou PowerShell no Windows.

   {
     "hooks": {
       "Notification": [
         {
           "matcher": "",
           "hooks": [
             {
               "type": "command",
               "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
             }
           ]
         }
       ]
     }
   }

2. Formate automaticamente cada arquivo que o Claude editar

   Um hook PostToolUse com o matcher Edit|Write lê o caminho editado do JSON recebido no stdin com jq e roda o Prettier nele. Coloque em .claude/settings.json para o time todo compartilhar.

   {
     "hooks": {
       "PostToolUse": [
         {
           "matcher": "Edit|Write",
           "hooks": [
             { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
           ]
         }
       ]
     }
   }

3. Bloqueie um comando perigoso

   Um hook PreToolUse no Bash roda este script. O código de saída 2 bloqueia a chamada, e o que você escrever no stderr vira o feedback para o Claude, que assim pode mudar de rumo. Sair com 0 significa nenhuma decisão, então as permissões normais continuam valendo.

   #!/bin/bash
   # .claude/hooks/block-drop-table.sh, executado como hook PreToolUse no Bash
   INPUT=$(cat)
   COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
   
   if echo "$COMMAND" | grep -q "drop table"; then
     echo "Blocked: dropping tables is not allowed" >&2  # vira o feedback para o Claude
     exit 2                                               # 2 = bloquear a ação
   fi
   
   exit 0  # sem decisão: vale o fluxo normal de permissões

4. Mantenha o Claude trabalhando até a tarefa terminar

   Um hook Stop do tipo prompt pergunta a um modelo se tudo está concluído. Se a resposta for ok: false, o Claude continua trabalhando com o reason como próxima instrução. É o exemplo clássico de hook Stop.

   {
     "hooks": {
       "Stop": [
         {
           "hooks": [
             {
               "type": "prompt",
               "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
             }
           ]
         }
       ]
     }
   }

Fonte: documentação do Claude Code, Automate actions with hooks

Como os hooks decidem o que acontece

• Entrada: cada hook recebe o evento como JSON no stdin, como o nome da ferramenta e tool_input, o ID da sessão e cwd.
• Saída 0: nenhuma objeção. Em alguns eventos, como SessionStart e UserPromptSubmit, o stdout em texto puro é adicionado ao contexto do Claude.
• Saída 2: bloquear, quando o evento permite. O stderr volta para o Claude ou para você, dependendo do evento.
• JSON no stdout: controle mais fino, como hookSpecificOutput com uma decisão de permissão, updatedInput para reescrever a entrada de uma ferramenta, ou additionalContext.
• Outros códigos de saída: em geral um erro que não bloqueia, a menos que o hook defina onFailure: "block".
• Os hooks que casam com o mesmo evento rodam em paralelo.

Hooks do tipo command, prompt, agent e HTTP

Hooks vs. skills vs. CLAUDE.md, e outras pegadinhas

• O CLAUDE.md e as skills são instruções que o Claude costuma seguir; os hooks rodam sempre. Coloque num hook tudo o que nunca pode ser pulado.
• O PostToolUse não desfaz uma ação que já rodou; use o PreToolUse para impedi-la.
• O Stop dispara sempre que o Claude termina uma resposta, não só no fim de uma tarefa, e não quando o usuário interrompe.
• Os hooks não conseguem rodar slash commands nem chamar ferramentas por conta própria; eles só respondem por códigos de saída, stdout, stderr ou JSON.
• "disableAllHooks": true desliga os hooks; os hooks gerenciados continuam rodando, a menos que as configurações gerenciadas também os desliguem.
• Os hooks são locais à sua configuração do Claude Code. Verificações para a organização inteira em todos os produtos Claude são outro recurso: os inference hooks do Claude.
• Um hook PreToolUse que filtra a saída dos testes também é uma das melhores formas de reduzir o uso de tokens.

Os hooks mantêm o Claude Code na linha. O Crewmark mantém ele trabalhando.

Os hooks são o que deixa seguro um agente sem supervisão: formatação, testes e proteções rodam sempre. O Crewmark transforma uma sessão do Claude Code, Codex, DeepSeek Harness ou OpenCode em um funcionário de IA com um papel, uma meta e um horário de trabalho, e a acorda com um heartbeat para pegar a próxima issue de um quadro, com os hooks do seu projeto no lugar.

1. Faça commit dos seus hooks

   Os hooks de .claude/settings.json carregam na sessão do funcionário como na sua, então as edições dele são formatadas e os comandos arriscados, bloqueados.

2. Deixe o heartbeat iniciar o trabalho

   Durante o horário de trabalho, o funcionário acorda a cada 15, 30 ou 60 minutos na mesma conversa; veja como deixar o Claude Code proativo.

3. Responda só ao que precisa de você

   Ele comenta nas issues dele e manda mensagem quando precisa de uma decisão. Leia o que é um funcionário de IA.

Perguntas frequentes sobre hooks do Claude Code