Hooks: automatizar revisões, validações e ações customizadas

# Estrutura: hooks ficam em .claude/hooks/ (por projeto) ou ~/.claude/hooks/ (global)

# Nomeação: <evento>/<nome-do-hook>.sh
# Exemplos:
.claude/hooks/
├── PostToolUse/
│   ├── auto-lint.sh          # roda lint depois de qualquer Edit
│   ├── auto-format.sh        # formata o arquivo editado
│   └── notify-edit.sh        # loga edições em audit log
├── PreToolUse/
│   ├── protect-prod.sh       # bloqueia edição em arquivos de config de produção
│   └── require-tests.sh      # bloqueia Bash(npm deploy) sem testes passando
├── Stop/
│   └── slack-notify.sh       # posta no Slack quando Claude termina uma tarefa
└── Notification/
    └── desktop-alert.sh      # notificação macOS quando Claude precisa de input

# Cada hook recebe via stdin um JSON com contexto:
# Para PostToolUse/PreToolUse:
# {
#   "tool_name": "Edit",
#   "tool_input": {
#     "file_path": "/path/to/arquivo.ts",
#     "old_string": "...",
#     "new_string": "..."
#   }
# }

#!/bin/bash
# .claude/hooks/PostToolUse/auto-lint.sh
# Roda lint automaticamente quando Claude edita arquivos de código

# Ler o JSON do stdin
INPUT=$(cat)

# Extrair nome da ferramenta e path do arquivo
TOOL_NAME=$(echo "$INPUT" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('tool_name', ''))")
FILE_PATH=$(echo "$INPUT" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('tool_input', {}).get('file_path', ''))")

# Só agir em edições de arquivo (Edit ou Write)
if [[ "$TOOL_NAME" != "Edit" && "$TOOL_NAME" != "Write" ]]; then
  exit 0
fi

# Sem arquivo? Sai silenciosamente
if [[ -z "$FILE_PATH" ]]; then
  exit 0
fi

# Rodar o linter adequado por extensão
case "$FILE_PATH" in
  *.ts|*.tsx)
    cd "$(dirname "$FILE_PATH")/.."
    npx eslint "$FILE_PATH" --fix --quiet 2>&1
    ;;
  *.py)
    ruff check "$FILE_PATH" --fix --quiet 2>&1
    ;;
  *.go)
    gofmt -w "$FILE_PATH" 2>&1
    ;;
esac

# Hooks PostToolUse: exit code não afeta Claude — é apenas notificação
exit 0

#!/bin/bash
# .claude/hooks/PreToolUse/protect-prod-config.sh
# Bloqueia edições em arquivos de configuração de produção

INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('tool_name', ''))")
FILE_PATH=$(echo "$INPUT" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('tool_input', {}).get('file_path', ''), 2>'/dev/null')" 2>/dev/null)

# Só verificar edições de arquivo
if [[ "$TOOL_NAME" != "Edit" && "$TOOL_NAME" != "Write" ]]; then
  exit 0
fi

# Verificar se o arquivo é de configuração de produção
PROTECTED_PATTERNS=(
  "config/production.json"
  ".env.production"
  "terraform/prod/"
  "k8s/production/"
)

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "BLOQUEADO: $FILE_PATH é um arquivo de configuração de produção." >&2
    echo "Para editar arquivos de produção, faça manualmente com revisão do time." >&2
    exit 1  # Exit não-zero BLOQUEIA a ação de ferramenta
  fi
done

exit 0  # Permitido

# O que Claude vê quando um PreToolUse bloqueia:
# "Hook de segurança bloqueou a edição. Mensagem: BLOQUEADO: config/production.json
#  é um arquivo de configuração de produção. Para editar arquivos de produção..."
# Claude então tenta outra abordagem ou pede confirmação explícita do usuário

#!/bin/bash
# .claude/hooks/Stop/notify-completion.sh
# Notifica quando Claude completa uma tarefa (útil para tarefas longas em background)

INPUT=$(cat)
SESSION_ID=$(echo "$INPUT" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('session_id', 'unknown'))")
STOP_REASON=$(echo "$INPUT" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('stop_reason', 'end_turn'))")

# Notificação macOS
if [[ "$OSTYPE" == "darwin"* ]]; then
  osascript -e "display notification "Claude Code finalizou a tarefa"     with title "Claude Code"     subtitle "Sessão: $SESSION_ID"     sound name "Glass""
fi

# Notificação Linux (notify-send)
if command -v notify-send &>/dev/null; then
  notify-send "Claude Code" "Tarefa finalizada (sessão $SESSION_ID)"
fi

# Opcional: postar no Slack (se SLACK_WEBHOOK configurado)
if [[ -n "$SLACK_WEBHOOK_URL" && "$STOP_REASON" == "end_turn" ]]; then
  PROJECT=$(basename "$PWD")
  curl -s -X POST "$SLACK_WEBHOOK_URL"     -H "Content-Type: application/json"     -d "{"text": "✅ Claude Code finalizou tarefa em *$PROJECT*"}"
fi

exit 0

# Habilitar hooks em .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",          # filtro de evento (regex)
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/PostToolUse/auto-lint.sh"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Edit|Write|Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/PreToolUse/protect-prod-config.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": ".*",                  # roda sempre que Claude para
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/Stop/notify-completion.sh"
          }
        ]
      }
    ]
  }
}

# Debugging: testar um hook manualmente
echo '{"tool_name": "Edit", "tool_input": {"file_path": "/path/arquivo.ts"}}'   | bash .claude/hooks/PostToolUse/auto-lint.sh

# Ver logs de hooks durante sessão:
# Claude Code exibe output do hook no terminal se ele escreve em stderr
# Saída em stdout é silenciosa (não mostrada ao usuário)
# Use stderr para mensagens de debug/status

# Timeout padrão: 60 segundos por hook
# Para hooks lentos (testes), configure timeout maior no settings:
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{ "type": "command", "command": "...", "timeout": 120 }]
    }]
  }
}

#!/bin/bash
# .claude/hooks/PreToolUse/smart-rm-guard.sh
# Bloqueia rm -rf em paths críticos, pede confirmação em outros

INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // ""')

if [[ "$CMD" =~ rm[[:space:]]+-rf[[:space:]]+/ ]]; then
  # Path absoluto crítico → bloqueia DIRETO
  cat <<'JSON'
{
  "decision": "block",
  "reason": "rm -rf em path absoluto é proibido",
  "systemMessage": "🚨 Tentativa de rm -rf em path absoluto bloqueada",
  "hookSpecificOutput": {
    "PreToolUse": {
      "permissionDecision": "deny"
    }
  }
}
JSON
  exit 0
fi

if [[ "$CMD" =~ rm[[:space:]]+-rf ]]; then
  # rm -rf relativo → pede confirmação extra
  cat <<'JSON'
{
  "decision": "ask",
  "reason": "rm -rf detectado — confirme antes de continuar",
  "hookSpecificOutput": {
    "PreToolUse": {
      "permissionDecision": "ask"
    }
  }
}
JSON
  exit 0
fi

# OK, passa
echo '{"decision":"allow"}'
exit 0

{
  "decision": "block|allow|ask",         // decisão principal
  "reason": "texto visível ao usuário",  // exibido no TUI
  "continue": true,                      // se false, Claude para a turn
  "stopReason": "mensagem ao parar",     // combinado com continue:false
  "suppressOutput": false,               // esconde output do hook
  "systemMessage": "aviso do sistema",   // banner na sessão
  "hookSpecificOutput": {
    "PreToolUse": {
      "permissionDecision": "deny"       // override do permission system
    }
  }
}

// Exit codes também continuam funcionando:
// 0 → success (parse JSON)
// 2 → block error (stderr vai pra Claude como feedback)
// outros → non-blocking warning

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "./check.sh", "timeout": 30 }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "http",
            "url": "https://hooks.slack.com/services/T00/B00/XXX",
            "headers": { "Content-Type": "application/json" },
            "allowedEnvVars": ["SLACK_CHANNEL"],
            "timeout": 10
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Gere um resumo em 2 frases do que foi feito nesta sessão, destacando arquivos modificados e próximos passos.",
            "model": "claude-haiku-4-5",
            "timeout": 30
          }
        ]
      }
    ],
    "SubagentStop": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "agent",
            "agent": "results-consolidator",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

# .claude/skills/deploy/SKILL.md
---
name: deploy
description: Deploy seguro com validação automática
allowed-tools: Bash, Read
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/pre-deploy-check.sh"
          timeout: 60
  PostToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/post-deploy-verify.sh"
  Stop:
    - matcher: ".*"
      hooks:
        - type: http
          url: "${SLACK_WEBHOOK}"
          allowedEnvVars: ["SLACK_WEBHOOK"]
---

# Deploy

Execute o deploy para o ambiente: $ARGUMENTS

1. Pré-verificação: testes passando, sem mudanças não commitadas
2. Execute ./scripts/deploy.sh $ARGUMENTS
3. Pós-verificação: health checks, métricas de latência
4. Notificação no Slack automática via hook

# Os hooks definidos aqui só rodam DURANTE a execução desta skill.
# Quando /deploy termina, os hooks somem.
# Hooks globais em settings.json continuam ativos normalmente.