Claude Code Hooks: guía para evitar comandos destructivos en producción

Si ya usas Claude Code en proyectos reales, en algún momento te cruzaste con este pensamiento: "¿y si el agente ejecuta algo que no debería?"

No es paranoia. Es una pregunta válida. Claude Code tiene acceso a terminales, sistemas de archivos, comandos de Git, scripts de base de datos y prácticamente cualquier herramienta que le configures. Eso es exactamente lo que lo hace poderoso, y también lo que lo hace potencialmente peligroso si no se configura con cuidado.

Los hooks de Claude Code existen exactamente para resolver ese problema. Esta guía explica qué son, cómo funcionan y cómo usarlos para que tu agente opere con autonomía real pero dentro de límites seguros.

Qué son los hooks de Claude Code

Los hooks son scripts que se ejecutan automáticamente en puntos específicos del ciclo de vida del agente. Piénsalos como guardianes que interceptan la actividad de Claude Code antes o después de que ocurra algo importante.

La idea es sencilla: en lugar de supervisar manualmente cada acción del agente, defines reglas que se ejecutan de forma automática en cada sesión. El agente trabaja con autonomía. Tú defines los límites.

Claude Code actualmente soporta cuatro tipos de hooks:

• PreToolUse — se ejecuta antes de que Claude use cualquier herramienta
• PostToolUse — se ejecuta después de que Claude usa una herramienta
• Notification — se activa cuando el agente genera una notificación
• Stop — se ejecuta cuando el agente termina su tarea

Para la mayoría de los casos de protección de codebase, los hooks PreToolUse y PostToolUse son los que más importan.

Por qué los hooks importan en producción

Durante el Claude Code Meetup Monterrey 2026, Erick Siller, Software Engineer en Salesforce, fue directo al respecto:

"Claude tiene acceso a muchas herramientas, incluyendo comandos potencialmente destructivos o irreversibles. Los hooks pre-tool permiten crear validaciones antes de ejecutar esos comandos."

No es un caso hipotético. En proyectos reales, Claude Code puede ejecutar comandos como git push --force, DROP TABLE, rm -rf, o hacer un PR directo a main sin que nadie lo revise. Individualmente, cada uno tiene un caso de uso legítimo. En el contexto equivocado, pueden arruinar un deployment o perder datos.

Los hooks te dan control granular sobre qué puede y qué no puede ejecutar el agente, sin quitarle su utilidad.

Cómo se configuran los hooks

Los hooks se definen en el archivo de configuración de Claude Code, ya sea en .claude/settings.json dentro de tu proyecto o en la configuración global del usuario.

La estructura básica es la siguiente:

      {
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "ruta/a/tu/script-validacion.sh"
          }
        ]
      }
    ]
  }
}
    

El campo matcher indica a qué herramienta aplica el hook. Los valores más comunes son Bash, Write, Edit, Read, WebFetch y Mcp. También puedes usar .* para que aplique a todas las herramientas.

El script de validación recibe el contexto de la herramienta por stdin en formato JSON. Si el script termina con código de salida distinto de cero, Claude Code bloquea la acción. Si termina en cero, la deja pasar.

Hook pre-tool: bloquear comandos destructivos en bash

Este es el caso de uso más importante. Antes de que Claude ejecute cualquier comando en la terminal, puedes validar que no sea una operación irreversible.

Aquí un script de ejemplo en bash:

      #!/bin/bash
# hooks/pre-bash-safety.sh
# Bloquea comandos destructivos antes de ejecutarse
 
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_input',{}).get('command',''))")
 
# Lista de patrones prohibidos
BLOCKED_PATTERNS=(
  "rm -rf"
  "git push --force"
  "git push -f"
  "DROP TABLE"
  "DROP DATABASE"
  "truncate"
  "git reset --hard HEAD~"
  "> /dev/sda"
  "mkfs"
)
 
for pattern in "${BLOCKED_PATTERNS[@]}"; do
  if echo "$COMMAND" | grep -qi "$pattern"; then
    echo "BLOQUEADO: El comando contiene una operación destructiva: '$pattern'" >&2
    echo "Si necesitas ejecutar este comando, hazlo manualmente fuera del agente." >&2
    exit 1
  fi
done
 
exit 0
    

Con este hook activo, si Claude intenta ejecutar git push --force origin main, el script lo intercepta, imprime un mensaje explicativo y cancela la acción. Claude recibe el mensaje de error y puede reportártelo o buscar una alternativa.

Hook pre-tool: proteger ramas críticas en Git

Un caso específico muy útil es evitar que el agente haga push o cree PRs directamente a main o production.

      #!/bin/bash
# hooks/protect-main-branch.sh
 
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_input',{}).get('command',''))")
 
# Bloquear push directo a ramas protegidas
PROTECTED_BRANCHES=("main" "master" "production" "prod")
 
for branch in "${PROTECTED_BRANCHES[@]}"; do
  if echo "$COMMAND" | grep -qP "git push.*\b$branch\b"; then
    echo "BLOQUEADO: No se permite push directo a '$branch' desde el agente." >&2
    echo "Crea un PR desde una rama de feature." >&2
    exit 1
  fi
done
 
exit 0
    

Esto te da exactamente el control que necesitas: el agente puede trabajar en ramas de feature con total autonomía, pero no puede tocar las ramas protegidas.

Hook post-bash: registro de auditoría

El hook PostToolUse es ideal para construir un log de todo lo que ejecuta el agente. Útil para debugging, auditorías de equipo o simplemente para entender qué hizo Claude durante una sesión larga.

      #!/bin/bash
# hooks/audit-log.sh
 
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_input',{}).get('command',''))" 2>/dev/null)
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
LOG_FILE="$HOME/.claude/audit.log"
 
mkdir -p "$(dirname $LOG_FILE)"
echo "$TIMESTAMP | CMD: $COMMAND" >> "$LOG_FILE"
 
exit 0
    

La configuración correspondiente en settings.json:

      {
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "hooks/audit-log.sh"
          }
        ]
      }
    ]
  }
}
    

Este log te da visibilidad completa de cada comando ejecutado por el agente, con timestamp. Puedes extenderlo fácilmente para incluir el directorio de trabajo, el nombre del proyecto o notificaciones por Slack.

Hook pre-tool: validación antes de escribir archivos

No solo los comandos de bash pueden ser problemáticos. La herramienta Write también puede sobrescribir archivos críticos. Aquí un hook que protege archivos de configuración sensibles:

      #!/bin/bash
# hooks/protect-config-files.sh
 
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_input',{}).get('path',''))" 2>/dev/null)
 
# Archivos que nunca deben modificarse desde el agente
PROTECTED_FILES=(
  ".env"
  ".env.production"
  ".env.local"
  "docker-compose.prod.yml"
  "prisma/migrations"
  "package-lock.json"
)
 
for protected in "${PROTECTED_FILES[@]}"; do
  if echo "$FILE_PATH" | grep -q "$protected"; then
    echo "BLOQUEADO: No se permite modificar '$FILE_PATH' desde el agente." >&2
    exit 1
  fi
done
 
exit 0
    

La configuración para que aplique a la herramienta Write:

      {
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "hooks/protect-config-files.sh"
          }
        ]
      }
    ]
  }
}
    

Hook con confirmación interactiva para operaciones de riesgo medio

Algunos comandos no son definitivamente peligrosos, pero merecen una pausa. En lugar de bloquearlos completamente, puedes pedir confirmación al usuario:

      #!/bin/bash
# hooks/confirm-risky-operations.sh
 
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_input',{}).get('command',''))")
 
RISKY_PATTERNS=(
  "npm run migrate"
  "prisma migrate deploy"
  "kubectl apply"
  "terraform apply"
)
 
for pattern in "${RISKY_PATTERNS[@]}"; do
  if echo "$COMMAND" | grep -qi "$pattern"; then
    echo "ADVERTENCIA: El agente quiere ejecutar: $COMMAND" >&2
    echo "Este comando puede tener efectos en producción." >&2
    read -p "¿Continuar? (s/N): " -r REPLY >&2
    if [[ ! $REPLY =~ ^[Ss]$ ]]; then
      echo "Operación cancelada por el usuario." >&2
      exit 1
    fi
  fi
done
 
exit 0
    

Este hook es útil en flujos donde trabajas activamente con el agente y quieres aprobar manualmente ciertos pasos antes de que procedan.

Hooks globales vs hooks de proyecto

Claude Code permite configurar hooks en dos niveles:

Hooks globales se definen en ~/.claude/settings.json y aplican a todas las sesiones de todos los proyectos. Son ideales para reglas de seguridad universales, como bloquear rm -rf o proteger ramas principales.

Hooks de proyecto se definen en .claude/settings.json dentro del repositorio y aplican solo a ese proyecto. Son ideales para reglas específicas del contexto, como proteger archivos de configuración particulares o validar convenciones de nomenclatura propias del equipo.

La recomendación es usar ambos: reglas generales a nivel global y reglas específicas a nivel de proyecto. Los hooks de proyecto sobreescriben o complementan los globales según el matcher que uses.

Combinar hooks con skills y MCP

Como mostró Erick Siller en el meetup, los hooks no trabajan solos. Se vuelven mucho más potentes cuando los combinas con el resto del sistema de extensión de Claude Code:

• Skills: archivos CLAUDE.md con instrucciones específicas que el agente carga cuando las necesita. Si tienes una skill para deploys, puedes acompañarla con hooks que validen el entorno antes de ejecutar.
• MCP (Model Context Protocol): los hooks pueden validar o registrar las llamadas a servidores MCP, igual que lo hacen con Bash. Si tienes un MCP conectado a tu base de datos de producción, un hook pre-tool puede verificar que el agente no intente operaciones de escritura directa.
• Plugins: la combinación de skills + hooks + MCPs empaquetados como una unidad instalable. Los hooks son la capa de seguridad de cualquier plugin bien construido.

Buenas prácticas para hooks en equipos

Si trabajas en equipo y quieres que todos usen los mismos hooks, estas son las recomendaciones:

Versiona tus hooks junto al proyecto. Guarda los scripts en una carpeta hooks/ dentro del repositorio y referencia esa ruta en .claude/settings.json. Así todos los miembros del equipo trabajan con las mismas reglas.

Documenta cada hook con un comentario claro. El script debe explicar qué bloquea y por qué, para que cualquier persona del equipo pueda entenderlo y ajustarlo.

Empieza en modo logging antes de bloquear. Antes de activar un hook que cancela acciones, actívalo primero solo en modo registro. Observa qué comandos captura durante una semana real de trabajo y ajusta los patrones antes de que empiece a bloquear activamente.

Ten un mecanismo de override documentado. Para casos legítimos donde sí necesitas ejecutar un comando bloqueado, define un proceso claro: salir del agente, ejecutar el comando manualmente y documentar por qué fue necesario.

Conclusión

Los hooks de Claude Code son la diferencia entre un agente que usas con confianza en proyectos reales y uno que supervisas con ansiedad en cada acción.

No necesitas bloquear todo. La idea no es crear un agente paranoico que pida permiso para cada línea. La idea es definir los límites específicos donde el costo de un error es alto, y dejar al agente operar con autonomía en todo lo demás.

Empieza con tres hooks básicos: bloqueo de comandos destructivos en bash, protección de ramas principales en Git y log de auditoría. Con eso cubierto, tienes la base para confiar en el agente en entornos de producción real.

Si quieres profundizar en cómo combinar hooks con skills y MCP para construir workflows completos, nuestro equipo en Fencode trabaja con estas herramientas en proyectos reales. Contáctanos y conversamos.

Artículos relacionados

Si este artículo te fue útil, estos otros te van a interesar:

• Claude Code Meetup Monterrey 2026: así están construyendo los builders de la ciudad — El resumen completo del evento donde Erick Siller presentó los hooks en vivo, junto con los workflows de multi-agentes, Spec Driven Development y Claude en la nube.
• ¿Qué es MCP (Model Context Protocol) y por qué va a cambiar cómo construyes software en 2026? — Los hooks y los servidores MCP trabajan juntos. Este artículo explica qué es MCP, cómo conecta a los agentes con tus sistemas reales y por qué es la pieza que le faltaba al stack de IA.
• MCP vs LangChain vs Vercel AI SDK: cuál usar en 2026 — Comparativa con código real entre los tres frameworks más usados para construir agentes. Útil si estás decidiendo con qué stack rodear a Claude Code en tu proyecto.
• Las 6 mejores herramientas de AI coding en 2026: comparativa con benchmarks reales — Claude Code no es la única opción. Este artículo compara las principales herramientas de coding con IA del mercado con benchmarks reales para que elijas la combinación que mejor se adapta a tu flujo de trabajo.
• Cómo crear tu primer servidor MCP con TypeScript desde cero (y hostearlo gratis) — Tutorial paso a paso para construir tu propio servidor MCP. Si quieres extender Claude Code con herramientas propias, este es el punto de partida.