Claude Hooks: 7 Configuraciones para Equipos Seguros

¿Has escrito reglas en CLAUDE.md y notado que la IA a veces simplemente las ignora? En equipos de desarrollo, esa inconsistencia puede convertirse en un problema real. En mi experiencia implementando hooks en equipos, este fue el punto de quiebre que nos llevó a adoptar Claude Hooks.

📑Índice

1. ¿Qué son los Claude Hooks? La diferencia clave con CLAUDE.md
2. Referencia completa de eventos de Claude Hooks【2026】
3. 8 ejemplos prácticos de Utilización de Hooks
4. Mejores prácticas para adoptar Claude Hooks en equipo
5. Limitaciones y advertencias de Claude Hooks
6. Preguntas frecuentes sobre Claude Hooks
7. Conclusión

A diferencia de CLAUDE.md, que funciona como una «petición» al modelo, los Claude Hooks son manejadores deterministas que siempre se ejecutan, sin excepción. Bloquean comandos peligrosos, automatizan el formateo de código, registran auditorías y mucho más, todo de forma garantizada.

En este artículo explico qué son los Claude Hooks, repaso todos los eventos disponibles y presento 8 ejemplos prácticos que puedes copiar y usar de inmediato en tu flujo de trabajo o equipo.

Tipo de handler	Comportamiento
command	Ejecuta un comando de shell; lee JSON desde stdin y escribe JSON en stdout
http	Hace un POST JSON a un endpoint externo (ideal para auditorías)
prompt	Envía un prompt al modelo Claude para evaluación sí/no
agent	Lanza un subagente con herramientas para validar condiciones complejas

Fuente: Documentación oficial de Claude Hooks (marzo 2026)

¿Qué son los Claude Hooks? La diferencia clave con CLAUDE.md

Los Claude Hooks son manejadores definidos por el usuario que se ejecutan automáticamente en puntos específicos del ciclo de vida de Claude Code. La palabra clave es «determinista»: no importa qué respuesta genere el modelo, el hook siempre corre.

CLAUDE.md es útil para dar contexto e instrucciones al modelo, pero no garantiza cumplimiento. Un agente distraído o una sesión larga puede saltarse esas reglas. Los hooks no tienen ese problema: se interponen en el pipeline de ejecución y no hay manera de evitarlos.

En mi equipo, antes de adoptar la Utilización de Hooks, teníamos variaciones entre miembros: algunos olvidaban formatear el código, otros dejaban credenciales en archivos temporales. Después de implementar Claude Hooks, esos problemas desaparecieron por completo.

Dónde se configuran los hooks

Archivo	Alcance
~/.claude/settings.json	Global — aplica a todos los proyectos del usuario
.claude/settings.json	Proyecto — se puede compartir con el equipo vía Git
.claude/settings.local.json	Local personal — excluido de Git, para ajustes individuales
Managed policy settings	Organización — el administrador lo impone, el usuario no puede desactivarlo

Fuente: Documentación oficial de Claude Code (marzo 2026)

Para equipos, la clave es commitear .claude/settings.json al repositorio. Así, todos los miembros comparten exactamente los mismos hooks sin configuración adicional. Los ajustes personales van en settings.local.json, que queda fuera de Git.

Si quieres entender mejor cómo proteger tu entorno más allá de los hooks, revisa nuestra guía de Seguridad de Claude Code.

Referencia completa de eventos de Claude Hooks【2026】

Existen más de 20 eventos disponibles. Conocerlos te permite elegir el punto exacto del ciclo de vida donde insertar tu lógica. La columna más importante es «¿Bloqueable?»: solo los eventos marcados como Sí pueden detener la ejecución del agente.

Evento	¿Bloqueable?	Descripción
SessionStart	No	Inicio o reanudación de sesión
UserPromptSubmit	Sí	El usuario envía un prompt
PreToolUse	Sí	Antes de ejecutar cualquier herramienta
PermissionRequest	Sí	Antes de mostrar diálogo de permiso al usuario
PostToolUse	No	Tras ejecución exitosa de herramienta
PostToolUseFailure	No	Tras fallo de herramienta
Notification	No	Claude envía una notificación
SubagentStart	No	Se crea un subagente
SubagentStop	Sí	El subagente termina su turno
Stop	Sí	El agente principal termina su turno
StopFailure	No	Turno terminado por error de API
TaskCreated	Sí	Se crea una tarea con TaskCreate
TaskCompleted	Sí	Tarea marcada como completada
ConfigChange	Sí	Se modifica un archivo de configuración
CwdChanged	No	Cambio de directorio de trabajo
FileChanged	No	Cambio en archivo monitoreado
PreCompact / PostCompact	No	Antes/después de compactar el contexto
InstructionsLoaded	No	CLAUDE.md o reglas cargadas
Elicitation	Sí	Herramienta MCP solicita entrada del usuario
ElicitationResult	Sí	El usuario responde al prompt MCP
WorktreeCreate	Sí	Se crea un worktree de Git
WorktreeRemove	No	Se elimina un worktree
TeammateIdle	Sí	Un compañero de equipo está inactivo
SessionEnd	No	La sesión termina

Fuente: Documentación oficial de Claude Hooks (marzo 2026)

Los códigos de salida determinan qué hace Claude con el resultado del hook: 0 indica éxito y Claude lee el JSON de stdout; 2 bloquea la acción (solo en eventos bloqueables); cualquier otro valor genera un error no bloqueante.

El campo matcher acepta expresiones regulares. Puedes usar Bash, Write|Edit|MultiEdit, o patrones como mcp__.* para cubrir todos los servidores MCP a la vez.

8 ejemplos prácticos de Utilización de Hooks

A continuación presento los casos de uso más valiosos que he implementado en proyectos reales. Cada ejemplo incluye la configuración completa lista para usar. Para sacar aún más partido a Claude Code, también puedes revisar las 15 técnicas de productividad para Claude Code.

Ejemplo 1 — Bloquear comandos destructivos (PreToolUse)

Este es el hook más importante para cualquier equipo. Intercepta cada llamada a Bash antes de ejecutarse y bloquea patrones peligrosos como rm -rf o git push --force.

Primero, agrega la configuración en .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

Luego crea el script .claude/hooks/validate-bash.sh:

#!/bin/bash
COMMAND=$(cat | jq -r '.tool_input.command')

# Bloquear comandos destructivos
if echo "$COMMAND" | grep -qE 'rm\s+-rf|drop\s+table|truncate\s+table'; then
  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Comando destructivo bloqueado por política del equipo"}}'
  exit 0
fi

# Bloquear envío de datos al exterior
if echo "$COMMAND" | grep -qE 'curl.*-d|wget.*--post'; then
  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Transmisión de datos externos bloqueada"}}'
  exit 0
fi

En mi experiencia implementando hooks en equipos, este script por sí solo ha evitado varios incidentes con datos de producción.

Ejemplo 2 — Forzar el uso de variables de entorno para secretos (PreToolUse)

Uno de los errores más comunes, especialmente entre desarrolladores con menos experiencia, es escribir credenciales directamente en archivos. Este hook bloquea cualquier intento de escribir patrones que parezcan claves API o contraseñas en texto plano.

#!/bin/bash
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name')
CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // ""')

# Detectar escritura de secretos en texto plano
if [[ "$TOOL" =~ ^(Write|Edit|MultiEdit)$ ]]; then
  if echo "$CONTENT" | grep -qE '(api_key|secret|password|token)\s*=\s*["\x27][A-Za-z0-9_\-]{10,}'; then
    echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"No escribas secretos en texto plano. Usa variables de entorno (process.env.API_KEY)"}}'
    exit 0
  fi
fi

Recomiendo aplicar este hook incluso en equipos donde todos son ingenieros. Las prisas llevan a malos hábitos, y este hook actúa como red de seguridad automática. La correcta Utilización de Hooks para gestión de secretos es una de las mejores inversiones de tiempo en seguridad.

Ejemplo 3 — Formateo automático tras editar archivos (PostToolUse)

Con PostToolUse puedes ejecutar Prettier, ESLint, Black u otro formateador cada vez que Claude modifica un archivo. El campo if permite condicionarlo al tipo de archivo.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/autoformat.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')

# Solo formatear TypeScript y JavaScript
if [[ "$FILE" =~ \.(ts|tsx|js|jsx)$ ]]; then
  npx prettier --write "$FILE" 2>/dev/null
fi

# Python
if [[ "$FILE" =~ \.py$ ]]; then
  black "$FILE" 2>/dev/null
fi

El formateo automático elimina el debate sobre estilo de código en los code reviews. El equipo puede centrarse en lógica en lugar de discutir espacios o comas.

Ejemplo 4 — Checkpoint automático de Git (PostToolUse)

Este hook crea un commit automático cada vez que Claude modifica archivos, generando un historial granular que facilita deshacer cambios no deseados.

#!/bin/bash
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name')

if [[ "$TOOL" =~ ^(Write|Edit|MultiEdit)$ ]]; then
  cd "$CLAUDE_PROJECT_DIR" || exit 0

if ! git diff --quiet HEAD 2>/dev/null; then
    TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
    git add -A
    git commit -m "chore: checkpoint automático [$TIMESTAMP] via Claude Hooks" \
      --no-verify -q 2>/dev/null || true
  fi
fi

Este checkpoint es especialmente valioso en sesiones largas de refactorización. Si algo sale mal, git log --oneline muestra exactamente qué cambió en cada paso y puedes revertir con precisión.

Ejemplo 5 — Registro de auditoría por HTTP (PostToolUse + http)

Para equipos con requisitos de cumplimiento normativo (SOC 2, auditorías internas), este hook envía cada llamada a herramienta a un endpoint de registro. Con async: true el impacto en rendimiento es mínimo.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "http",
            "url": "https://tu-servidor.com/api/audit-log",
            "headers": {
              "Authorization": "Bearer $AUDIT_TOKEN"
            },
            "allowedEnvVars": ["AUDIT_TOKEN"],
            "async": true
          }
        ]
      }
    ]
  }
}

El payload que recibe el endpoint incluye el nombre de la herramienta, los inputs y el resultado, todo con timestamp. allowedEnvVars permite pasar el token de autenticación de forma segura sin hardcodearlo en la configuración.

Ejemplo 6 — Inyección de contexto al iniciar sesión (SessionStart)

Este hook lee archivos de contexto del proyecto (TODOs, guías de contribución, arquitectura) y los inyecta automáticamente al inicio de cada sesión, sin que tengas que recordar hacerlo manualmente cada vez.

#!/bin/bash
CONTEXT_FILE="$CLAUDE_PROJECT_DIR/docs/CONTEXT.md"

if [ -f "$CONTEXT_FILE" ]; then
  CONTENT=$(cat "$CONTEXT_FILE")
  jq -n --arg ctx "$CONTENT" \
    '{"additionalContext": $ctx}'
fi

Ten en cuenta que los hooks de SessionStart bloquean el inicio de sesión mientras se ejecutan. Mantenlos rápidos o usa async: true si el contenido no es crítico para el arranque.

Ejemplo 7 — Notificaciones de escritorio (Notification + async)

Cuando Claude necesita aprobación o termina una tarea larga, este hook muestra una notificación nativa en macOS para que no tengas que mantener la ventana en foco constantemente.

#!/bin/bash
INPUT=$(cat)
MESSAGE=$(echo "$INPUT" | jq -r '.message // "Claude requiere tu atención"')

osascript -e "display notification \"$MESSAGE\" with title \"Claude Code\" sound name \"default\""

En el settings.json, márcalo como async para que no bloquee el flujo:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/notify.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

Ejemplo 8 — Forzar ejecución de tests antes de cerrar (Stop + agent)

Este es el hook más avanzado: usa el evento Stop para lanzar un subagente que verifica que los tests pasen antes de permitir que el agente principal termine su turno.

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "agent",
            "prompt": "Revisa si hay archivos TypeScript o Python modificados en este turno. Si los hay, ejecuta los tests correspondientes. Si algún test falla, reporta el error y devuelve permissionDecision: deny para que el agente principal corrija antes de terminar.",
            "tools": ["Bash", "Read"]
          }
        ]
      }
    ]
  }
}

En mi experiencia implementando hooks en equipos con CI/CD estricto, este patrón garantiza que Claude nunca termine una tarea dejando tests rotos. Es el equivalente a un «gate de calidad» automático al final de cada turno.

Mejores prácticas para adoptar Claude Hooks en equipo

La correcta Utilización de Hooks en un equipo requiere una estrategia de adopción gradual. Imponer demasiadas restricciones de golpe genera fricción. La clave es empezar con hooks de valor claro y bajo impacto, y escalar desde ahí.

Mi recomendación de orden de adopción: primero PostToolUse para formateo automático (beneficio inmediato, sin fricción), luego PreToolUse para seguridad (bloquear comandos peligrosos), y finalmente hooks de auditoría via HTTP para equipos con requisitos de compliance.

Para proyectos que requieren automatización avanzada más allá de hooks individuales, considera explorar los agentes autónomos de Claude con Dispatch y Computer Use.

Limitaciones y advertencias de Claude Hooks

Claude Hooks es una herramienta poderosa, pero tiene restricciones importantes que conviene conocer antes de diseñar tu arquitectura de hooks.

La limitación más notable es que no existe desactivación por hook individual: solo hay un flag global disableAllHooks: true que los desactiva todos a la vez. Esto es intencional por razones de seguridad, pero puede ser limitante si necesitas desactivar temporalmente uno solo.

Los Managed Policy hooks configurados por la organización son inmutables para el usuario final. No aparecen en la salida de /hooks del usuario y no pueden sobreescribirse ni desactivarse localmente. Esto es una ventaja para administradores, pero conviene saberlo si trabajas en un entorno corporativo.

Para complementar los Claude Hooks con otras herramientas de productividad, también puede interesarte revisar los 3 plugins recomendados para Claude Code.

Preguntas frecuentes sobre Claude Hooks

¿Los Claude Hooks están disponibles en el plan gratuito?▼

No. Claude Code en sí requiere al menos el plan Pro de Claude. El plan gratuito no incluye acceso a Claude Code y, por lo tanto, tampoco a Claude Hooks.

¿Cuál es la diferencia práctica entre CLAUDE.md y los hooks?▼

CLAUDE.md contiene instrucciones para el modelo: es flexible y contextual, pero el modelo puede ignorarlas o interpretarlas de forma diferente según la sesión. Los Claude Hooks son código que se ejecuta en el sistema operativo: son deterministas y no dependen del modelo para funcionar. La recomendación es usar ambos — CLAUDE.md para guiar el razonamiento, hooks para garantizar comportamientos críticos.

¿Puedo modificar la entrada de una herramienta desde un hook?▼

Sí, pero solo desde PreToolUse. El hook puede devolver un campo updatedInput en el JSON de respuesta para modificar los parámetros antes de que la herramienta se ejecute. No es posible modificar la salida de una herramienta ya ejecutada.

¿Los hooks funcionan en Windows?▼

Claude Code es compatible con macOS y Linux de forma nativa. En Windows funciona a través de WSL (Windows Subsystem for Linux). Los hooks de tipo command ejecutan scripts de shell y requieren un entorno Unix/Linux, ya sea nativo o mediante WSL.

¿Qué hago si un hook falla y bloquea mi sesión?▼

Revisa stderr en modo verbose con claude --verbose. Si el problema es el JSON de stdout, verifica que tu .bashrc o .zshrc no imprima nada al arrancar (es un problema frecuente). Para desbloquear temporalmente, usa disableAllHooks: true en settings.local.json, corrige el script y luego elimina esa línea.

¿Cómo evito que los miembros del equipo desactiven los hooks de seguridad?▼

Configura los hooks críticos en Managed Policy settings. En macOS: /Library/Application Support/ClaudeCode/managed-settings.json; en Linux: /etc/claude-code/managed-settings.json. Las políticas administradas tienen prioridad máxima y el usuario no puede sobreescribirlas ni desactivarlas. En Claude.ai Enterprise también se pueden gestionar desde la consola de administración.

Conclusión

Los Claude Hooks resuelven el problema fundamental de la IA en entornos colaborativos: la inconsistencia. CLAUDE.md es útil pero no garantizable. Un hook de PreToolUse que bloquea rm -rf nunca falla, sin importar qué modelo esté corriendo o qué tan larga sea la sesión.

Mi recomendación para empezar: agrega un único hook de PostToolUse para formateo automático esta semana. Es el de menor riesgo, el de mayor valor visible inmediato, y te dará confianza para avanzar hacia hooks de seguridad más complejos.

La documentación oficial de Claude Hooks en Anthropic Docs incluye ejemplos adicionales y la referencia completa de los campos disponibles en cada evento.