Domingo, 22 de noviembre de 2026  ·  Español
Avanzado 45 min en total 6 pasos

Cómo crear un hook en Claude Code paso a paso

Bloquea comandos peligrosos, formatea código y controla permisos con hooks deterministas en Claude Code.

Daniel Puentes Prias
Consultor de IA · Actualizado el 21 de noviembre de 2026
Requisitos
  • Claude Code instalado con el instalador nativo (en macOS/Linux: curl -fsSL https://claude.ai/install.sh | bash) y con la sesión iniciada
  • Un repositorio Git de prueba donde puedas romper cosas sin miedo
  • Python 3.9+ y jq instalados en el PATH
  • Opcional: ruff o prettier para el hook de formateo
  • Soltura con la terminal, JSON y scripts de shell
Lo que vas a aprender
  • Qué eventos de hook existen en Claude Code y cuándo se dispara cada uno
  • Cómo leer el JSON que Claude Code envía por stdin a tu script
  • Cómo bloquear una acción con exit code 2 y devolverle el motivo a Claude
  • Cómo devolver JSON estructurado para pedir confirmación en lugar de bloquear
  • Cómo probar y depurar hooks sin depender de que el modelo los dispare
PASO 1 · ~5 min

Entender el modelo de hooks y preparar la estructura

Un hook es un comando de shell que Claude Code ejecuta de forma determinista en un punto concreto del ciclo de vida del agente. No depende de que el modelo se acuerde de algo: si el evento ocurre, el hook se ejecuta. Los eventos que más vas a usar son PreToolUse (antes de que se ejecute una herramienta, y puede bloquearla), PostToolUse (después de que termine con éxito), UserPromptSubmit (al enviar un prompt), Stop (cuando Claude termina de responder), SessionStart y Notification. Los hooks se declaran en ficheros de configuración JSON con tres niveles: ~/.claude/settings.json (todos tus proyectos), .claude/settings.json (el proyecto, se commitea y lo comparte el equipo) y .claude/settings.local.json (el proyecto, solo para ti, ignorado por Git). En este tutorial vas a trabajar a nivel de proyecto para que el equipo herede las reglas. Empieza creando una carpeta dedicada a los scripts dentro del repo, así quedan versionados junto al código que protegen.

bash
cd ~/mi-proyecto
mkdir -p .claude/hooks
touch .claude/settings.json
# Si el fichero estaba vacío, inicialízalo con un objeto JSON válido
[ -s .claude/settings.json ] || echo '{}' > .claude/settings.json
ConsejoUsa .claude/settings.json para las reglas de seguridad del equipo y .claude/settings.local.json para experimentos personales: así no impones tus manías a nadie.
Error comúnUn settings.json con JSON inválido (una coma de más) hace que la configuración no se cargue. Valídalo siempre con jq . .claude/settings.json antes de abrir Claude Code.
PASO 2 · ~10 min

Escribir un hook PreToolUse que bloquee comandos peligrosos

Vamos a crear un guardián para la herramienta Bash. Claude Code envía por stdin un JSON con campos como session_id, cwd, hook_event_name, tool_name y tool_input. En el caso de Bash, tool_input.command contiene el comando exacto que Claude quiere lanzar. La regla clave de los exit codes: 0 significa todo bien y la acción continúa; 2 significa bloqueo, y lo que escribas en stderr se le devuelve a Claude como motivo para que corrija su plan; cualquier otro código es un error no bloqueante que solo verás tú. El script de abajo bloquea rm -rf, pushes directos a main o master y lecturas de ficheros .env, algo especialmente sensible si trabajas con credenciales de clientes o datos personales sujetos al RGPD en España o a las leyes de protección de datos en LATAM. Escribir el motivo en stderr de forma clara no es cosmético: Claude lo lee y suele proponer una alternativa segura en el siguiente turno.

bash
cat > .claude/hooks/guardia_bash.py << 'EOF'
#!/usr/bin/env python3
import json
import re
import sys

try:
    data = json.load(sys.stdin)
except json.JSONDecodeError:
    sys.exit(0)  # No bloqueamos si el input es raro

if data.get("tool_name") != "Bash":
    sys.exit(0)

cmd = data.get("tool_input", {}).get("command", "")

REGLAS = [
    (r"\brm\s+-[a-zA-Z]*(rf|fr)", "rm -rf no está permitido. Borra ficheros concretos o pide confirmación al usuario."),
    (r"\bgit\s+push\b.*\b(main|master)\b", "Nada de push directo a main/master. Crea una rama y abre una PR."),
    (r"\b(cat|less|more|head|tail)\b[^|;]*\.env\b", "No leas ficheros .env: contienen secretos."),
]

for patron, motivo in REGLAS:
    if re.search(patron, cmd):
        print(f"Bloqueado por hook guardia_bash: {motivo}", file=sys.stderr)
        sys.exit(2)

sys.exit(0)
EOF
chmod +x .claude/hooks/guardia_bash.py
ConsejoHaz que el script falle en abierto (exit 0) ante input inesperado solo si es un hook de comodidad; para hooks de seguridad estrictos puede tener más sentido fallar en cerrado con exit 2.
Error comúnSi usas exit 1 pensando que bloquea, te equivocas: solo el exit code 2 bloquea la herramienta. Con 1 el comando peligroso se ejecuta igualmente.
PASO 3 · ~7 min

Registrar el hook en settings.json con un matcher

Ahora conecta el script al evento. La estructura es: hooks → nombre del evento → lista de bloques, cada uno con un matcher y una lista de hooks de tipo command. El matcher filtra por nombre de herramienta y acepta expresiones regulares: Bash, Edit|Write, o mcp__.* para todas las herramientas de servidores MCP. Si lo omites o lo dejas vacío, el hook aplica a todas las herramientas del evento. Usa la variable de entorno CLAUDE_PROJECT_DIR para construir rutas absolutas: Claude Code puede cambiar de directorio durante la sesión y una ruta relativa dejaría de resolverse. El campo timeout, en segundos, evita que un script colgado bloquee la sesión. Ya de paso, deja registrado el hook PostToolUse que crearás en el paso 4, con matcher Edit|Write|MultiEdit. Las comillas escapadas alrededor de la variable protegen rutas con espacios, algo habitual en carpetas como Mis Documentos en equipos con Windows en español.

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guardia_bash.py",
            "timeout": 10
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/formatear.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}
ConsejoDentro de Claude Code, el comando /hooks muestra los hooks cargados y su origen (usuario, proyecto o local). Úsalo para confirmar que tu configuración se ha leído.
Error comúnClaude Code toma una instantánea de los hooks al arrancar la sesión. Si editas settings.json con la sesión abierta, los cambios no se aplican hasta que los revises en /hooks o reinicies Claude Code.
PASO 4 · ~7 min

Crear un hook PostToolUse que formatee cada fichero editado

El caso de uso más rentable de PostToolUse es formatear automáticamente lo que Claude acaba de escribir: dejas de pedirlo en el prompt y dejas de gastar tokens en ello. Para Edit, Write y MultiEdit, el JSON de entrada incluye tool_input.file_path con la ruta del fichero tocado. El script extrae esa ruta con jq y aplica ruff para Python o prettier para el ecosistema JavaScript. Fíjate en dos decisiones de diseño. Primero, el hook nunca devuelve exit 2: un fallo del formateador no debe interrumpir el trabajo de Claude, así que los errores se silencian con || true. Segundo, se usa npx --no-install para que no intente descargar prettier en mitad de la sesión si no está en el proyecto, lo que podría dejar el hook colgado hasta el timeout. Si en tu equipo usáis otro formateador (gofmt, rustfmt, black), añade una rama más al case.

bash
cat > .claude/hooks/formatear.sh << 'EOF'
#!/usr/bin/env bash
set -uo pipefail

FILE=$(jq -r '.tool_input.file_path // empty')
[ -z "$FILE" ] && exit 0
[ -f "$FILE" ] || exit 0

case "$FILE" in
  *.py)
    command -v ruff >/dev/null && ruff format "$FILE" >/dev/null 2>&1 || true
    ;;
  *.ts|*.tsx|*.js|*.jsx|*.json|*.css|*.md)
    npx --no-install prettier --write "$FILE" >/dev/null 2>&1 || true
    ;;
esac

exit 0
EOF
chmod +x .claude/hooks/formatear.sh
ConsejoSi el formateo cambia el fichero, Claude Code detecta la modificación y trabajará sobre la versión formateada en las siguientes ediciones, así que no hay conflicto.
Error comúnOlvidar el chmod +x es el error número uno: el hook falla con permiso denegado y, al no ser exit 2, solo lo verás en modo debug. Parece que no hace nada.
PASO 5 · ~8 min

Devolver JSON estructurado para pedir confirmación en vez de bloquear

Los exit codes son binarios. Cuando necesitas matices, el hook puede imprimir un JSON en stdin de salida (stdout) con exit 0 y Claude Code lo interpreta. Para PreToolUse, el objeto hookSpecificOutput admite permissionDecision con valores allow (aprueba sin preguntar), deny (bloquea y explica a Claude el motivo) o ask (fuerza el diálogo de confirmación al usuario). Esto es perfecto para ficheros delicados que sí se pueden tocar, pero no sin que un humano lo vea: migraciones de base de datos, workflows de CI o configuración de infraestructura. Crea este segundo hook y añádelo al bloque PreToolUse con un matcher Edit|Write|MultiEdit, igual que hiciste en el paso 3. Puedes tener varios bloques para el mismo evento; Claude Code ejecuta en paralelo todos los hooks cuyo matcher coincida.

bash
cat > .claude/hooks/ficheros_sensibles.py << 'EOF'
#!/usr/bin/env python3
import json
import sys

data = json.load(sys.stdin)
ruta = data.get("tool_input", {}).get("file_path", "")

SENSIBLES = ("migrations/", ".github/workflows/", "terraform/", "docker-compose")

if any(s in ruta for s in SENSIBLES):
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "ask",
            "permissionDecisionReason": f"{ruta} es un fichero sensible: revisa el cambio antes de aceptarlo."
        }
    }))

sys.exit(0)
EOF
chmod +x .claude/hooks/ficheros_sensibles.py
ConsejoUsa allow con muchísima cautela: aprueba automáticamente y se salta el sistema de permisos. Para la mayoría de equipos, deny y ask cubren el 95 % de los casos.
Error comúnSi imprimes cualquier otra cosa en stdout además del JSON (un print de depuración, por ejemplo), Claude Code no podrá parsearlo y tu decisión se ignorará. Manda los logs a stderr.
PASO 6 · ~8 min

Probar y depurar los hooks antes de confiar en ellos

No esperes a que Claude decida lanzar un rm -rf para saber si tu guardián funciona. Como los hooks son simples scripts que leen JSON por stdin, puedes simular la entrada desde la terminal y comprobar el exit code. Después, valida dentro de Claude Code: arranca con claude --debug para ver en la salida qué hooks se ejecutan, con qué comando y qué devuelven. Una prueba end-to-end rápida es pedirle a Claude algo como borra la carpeta build con rm -rf y comprobar que se bloquea, que te muestra el motivo y que propone una alternativa. Finalmente, commitea la carpeta .claude/hooks y el settings.json: cualquier compañero que clone el repo tendrá las mismas protecciones. Recuerda que los hooks se ejecutan con tus permisos de usuario, así que revisa los scripts de proyectos ajenos antes de abrirlos con Claude Code.

bash
# 1. Debe bloquear (exit 2) y mostrar el motivo por stderr
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf ./build"}}' \
  | python3 .claude/hooks/guardia_bash.py; echo "exit: $?"

# 2. Debe permitir (exit 0)
echo '{"tool_name":"Bash","tool_input":{"command":"ls -la"}}' \
  | python3 .claude/hooks/guardia_bash.py; echo "exit: $?"

# 3. Debe devolver JSON con permissionDecision ask
echo '{"tool_input":{"file_path":"db/migrations/001_init.sql"}}' \
  | python3 .claude/hooks/ficheros_sensibles.py

# 4. Validar la configuración y arrancar en modo debug
jq . .claude/settings.json > /dev/null && echo 'settings.json OK'
claude --debug
ConsejoGuarda estos echo como tests en un script o en tu CI. Un hook de seguridad sin tests es una falsa sensación de seguridad.
Error comúnLas expresiones regulares sobre comandos de shell son eludibles (por ejemplo, con alias o variables). Trata estos hooks como una red de seguridad, no como un sandbox: para aislamiento real combínalos con las reglas de permisos de Claude Code.
Resultado

Has montado un sistema de hooks de nivel de producción en Claude Code: un guardián PreToolUse que bloquea comandos destructivos y le explica a Claude por qué, un formateador PostToolUse que deja cada fichero limpio sin gastar un solo token, y un hook con salida JSON que exige confirmación humana sobre ficheros críticos. Además sabes probarlos de forma aislada y depurarlos con claude --debug, y los has versionado para que todo tu equipo herede las mismas reglas. Si quieres ir más allá y convertir esto en un flujo de trabajo completo con subagentes, comandos personalizados y CLAUDE.md, te conviene profundizar en el desarrollo asistido por IA con Claude Code de forma estructurada.

PRÓXIMOS PASOS
TÉRMINOS DE ESTE TUTORIAL
MÁS DE CLAUDE CODE