🎣 Anatomia de um hook
Hook = evento + matcher + handler. Configurado em settings.json. Hooks são determinísticos — onde prompt pode falhar, hook bloqueia com certeza.
📌 3 partes de um hook
Estrutura repetível.
- •Evento: PreToolUse, TaskCompleted, etc
- •Matcher: regex/literal de tool name
- •Handler: command/http/mcp_tool/agent
- •Exit 2 = bloqueia + envia stderr ao agente
💡 Localização
Hooks em .claude/settings.json (projeto) ou ~/.claude/settings.json (user).
📝 TaskCreated
Dispara antes da task entrar na lista. Pode bloquear com exit 2 + motivo no stderr. Útil para vetar tasks ambíguas, com escopo grande, ou que extrapolam orçamento.
📌 Casos típicos
Onde TaskCreated brilha.
- •Task sem path concreto
- •Task descrita em > X palavras
- •Task que envolve produção
- •Task com tool name suspeito
📊 Formato JSON
- Recebe title/description na stdin
- Stdout JSON ou exit 2
- Feedback no stderr volta ao agente
- Pode reescrever task com updatedInput
✅ TaskCompleted: rodar testes
Hook que roda pytest/npm test e bloqueia o 'completed' se algo falha. Transforma a task list em garantia de qualidade.
📌 Script típico
.claude/hooks/task-completed-tests.sh
- •Roda subset de testes relevantes
- •Exit 2 com saída do test runner
- •Stderr volta ao teammate
- •Teammate corrige e tenta de novo
💡 Subset vs full suite
Quick subset na task local; full suite no shutdown do team.
😴 TeammateIdle: bloquear idle
Quando teammate vai dormir, hook pode dizer 'ainda não, faltam estes deliverables' e devolvê-lo ao trabalho. Evita 'idle prematuro'.
📌 Validações úteis
Verificar antes de deixar dormir.
- •Arquivos requeridos existem?
- •Testes verdes?
- •Mensagens pendentes ao destinatário?
- •Resumo final escrito?
🛡️ PreToolUse: bloquear comandos
Hook inspeciona parâmetros do tool antes de rodar. Bloqueia padrões perigosos. É a sua rede de segurança — mesmo com permissões liberadas, hook protege contra acidentes.
📌 Padrões para bloquear
Comandos típicos perigosos.
- •
rm -rf - •
git push --forceem main - •
DROP TABLE - •
kubectl deleteem prod - •Edit em
.env
📊 Decisão JSON
- permissionDecision: deny|allow|ask|defer
- permissionDecisionReason: string
- updatedInput: pode reescrever
- additionalContext: avisa o agente
📈 Stop e PostToolUse: telemetria
Stop dispara ao fim de cada turno; PostToolUse após cada tool. Sem telemetria você não otimiza. Hooks de log dão dados para decidir tamanhos e modelos.
📌 O que logar
Métricas que viram decisão.
- •Tokens por papel
- •Latência por tool
- •Taxa de erro por papel
- •Tools mais usados
- •Tasks bloqueadas por hook
⚠️ Cuidado com Stop bloqueando
Hook Stop com block pode fazer agente nunca terminar. Use com extrema cautela.
📌 Resumo do Módulo
Próximo módulo:
3.5 — Display: tmux, iTerm2, split-pane