⚡ Hooks como interrupts do OS

📋 Catálogo completo de hooks

• •SessionStart — dispara ao iniciar qualquer sessão Claude Code.
• •PreToolUse — antes de cada chamada de ferramenta. Pode bloquear com exit code 2.
• •PostToolUse — após tool executar. Ideal para log e auditoria.
• •PostToolUseFailure — quando tool falha. Alertas e rollback.
• •UserPromptSubmit — quando usuário envia prompt. Enriquecimento automático.
• •Stop / StopFailure — quando Claude acha que terminou. Gate de qualidade.
• •SubagentStop — quando subagente termina. Coordenação multi-agente.
• •PreCompact — antes de compactar contexto. Preservar dados críticos.
• •Notification — Claude envia notificação ao usuário.

💻 Exemplo real: bootstrap de contexto

#!/bin/bash
# .claude/hooks/session-start.sh

# Carrega Silver Platters
cat /workspace/context/company-brief.md >> /tmp/session-context.md
cat /workspace/context/active-projects.md >> /tmp/session-context.md

# Converte planilhas para MD se existirem
find /workspace/data -name "*.xlsx" -newer /tmp/.last-convert \
  | xargs -I{} python3 convert-xlsx.py {}

# Injeta data atual
echo "## Sessão iniciada em: $(date '+%Y-%m-%d %H:%M')" >> /tmp/session-context.md

touch /tmp/.last-convert
exit 0

💻 Exemplo: bloqueio de paths proibidos

#!/bin/bash
# .claude/hooks/pre-tool-use.sh
# Recebe JSON via stdin com tool_name e tool_input

TOOL=$(cat /dev/stdin | jq -r '.tool_name')
INPUT=$(cat /dev/stdin | jq -r '.tool_input // ""')

# Bloqueia acesso a dados financeiros via Bash
if [[ "$TOOL" == "Bash" ]]; then
  if echo "$INPUT" | grep -q "/financials/\|/billing/"; then
    echo "BLOQUEADO: acesso a dados financeiros requer aprovação" >&2
    exit 2
  fi
fi

# Bloqueia git push --force
if [[ "$TOOL" == "Bash" ]] && echo "$INPUT" | grep -q "push --force\|push -f"; then
  echo "BLOQUEADO: force push não permitido" >&2
  exit 2
fi

exit 0

💻 Exemplo: audit trail estruturado

#!/bin/bash
# .claude/hooks/post-tool-use.sh

PAYLOAD=$(cat /dev/stdin)
TOOL=$(echo "$PAYLOAD" | jq -r '.tool_name')
INPUT=$(echo "$PAYLOAD" | jq -r '.tool_input // ""')
OUTPUT=$(echo "$PAYLOAD" | jq -r '.tool_output // ""')
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

# Log estruturado JSONL
echo "{\"ts\":\"$TIMESTAMP\",\"tool\":\"$TOOL\",\"input\":$INPUT,\"status\":\"ok\"}" \
  >> /var/log/agent-audit.jsonl

# Webhook para Slack se foi Write em produção
if [[ "$TOOL" == "Write" ]] && echo "$INPUT" | grep -q "/prod/"; then
  curl -s -X POST "$SLACK_WEBHOOK" \
    -d "{\"text\":\"⚠️ Agente escreveu em /prod/ — ts: $TIMESTAMP\"}" &
fi

exit 0

💻 Stop hook com checklist de qualidade

#!/bin/bash
# .claude/hooks/stop.sh
# Valida se o trabalho atende critérios antes de parar

TRANSCRIPT=$(cat /dev/stdin | jq -r '.transcript // ""')

# Verifica se testes foram rodados
if ! echo "$TRANSCRIPT" | grep -q "npm test\|pytest\|cargo test"; then
  echo "REQUER: rode os testes antes de finalizar" >&2
  exit 2
fi

# Verifica se há arquivos staged mas não commitados
if git diff --cached --quiet 2>/dev/null; then
  : # ok, nada staged
else
  echo "REQUER: commit as mudanças staged antes de finalizar" >&2
  exit 2
fi

exit 0

💻 PreCompact: injeta sticky context

#!/bin/bash
# .claude/hooks/pre-compact.sh
# Injeta contexto que não pode ser perdido na compactação

echo "=== CONTEXTO STICKY — NÃO COMPRIMIR ==="
echo "Projeto: $(cat .claude/project-name 2>/dev/null || echo 'N/A')"
echo "Estado: $(cat /tmp/agent-state.json 2>/dev/null || echo '{}')"
echo "Decisões desta sessão:"
cat /tmp/session-decisions.md 2>/dev/null || echo "(nenhuma)"
echo "Regras ativas:"
cat .claude/CLAUDE.md | head -20
echo "=== FIM CONTEXTO STICKY ==="

exit 0