Hooks de Claude Code: por qué existe cada uno de mis 95 hooks
Construí 95 hooks para Claude Code. Cada uno existe porque algo salió mal primero. El git-safety-guardian existe porque Claude hizo force-push a main. El recursion-guard existe porque un subagente generó hijos infinitos. El blog-quality-gate existe porque publiqué un artículo con 7 frases en voz pasiva y una nota al pie huérfana.1
Los hooks de Claude Code son comandos de shell que se ejecutan en puntos específicos del ciclo de vida (inicio de sesión, antes/después del uso de herramientas, envío de prompt y finalización de respuesta), proporcionando barreras de protección deterministas sobre el comportamiento probabilístico del LLM. Los hooks reciben JSON por stdin y devuelven decisiones (bloquear, permitir o modificar) por stdout y códigos de salida. Aplican políticas como bloquear force-pushes a main, prevenir generaciones recursivas de agentes, inyectar contexto por sesión y controlar la calidad de salida que el LLM por sí solo no puede garantizar.
TL;DR
Los hooks de Claude Code ejecutan comandos de shell en puntos específicos del ciclo de vida durante el desarrollo asistido por IA. Los hooks proporcionan garantías deterministas (bloqueando comandos de git peligrosos, inyectando contexto, aplicando calidad) sobre un sistema probabilístico (el LLM). Tras construir 95 hooks en mi infraestructura, descubrí que los mejores hooks surgen de incidentes, no de la planificación. Este artículo cubre la arquitectura, las historias de origen detrás de mis hooks más críticos y los patrones que aprendí tras 9 meses de desarrollo de hooks.
Actualizado el 21 de octubre de 2026. Corregí los ejemplos de PreToolUse de más abajo, que ahora usan hookSpecificOutput.permissionDecision, las frases sobre los códigos de salida y el ejemplo de configuración, que ahora sigue el esquema de configuración actual. Los campos de nivel superior decision y reason que mostraban antes los ejemplos están obsoletos para ese evento. El reporte de un lector motivó la corrección.
La arquitectura
Claude Code expone 26 eventos del ciclo de vida donde los hooks pueden interceptar, modificar o bloquear el comportamiento (a partir de v2.1.116, abril de 2026).2 Mis hooks se dirigen a seis de los más comunes:
Eventos de sesión
| Evento | Cuándo se dispara | Mis hooks |
|---|---|---|
| SessionStart | Comienza una nueva sesión | session-start.sh: inyecta la fecha, valida venv, inicializa el estado de recursión |
| SessionEnd | La sesión termina | Limpia archivos temporales |
Eventos de ejecución de herramientas
| Evento | Cuándo se dispara | Mis hooks |
|---|---|---|
| PreToolUse | Antes de que se ejecute cualquier herramienta | git-safety-guardian.sh, recursion-guard.sh, credentials-check.sh |
| PostToolUse | Después de que la herramienta termina | post-deliberation.sh, log-bash.sh |
Eventos de respuesta
| Evento | Cuándo se dispara | Mis hooks |
|---|---|---|
| UserPromptSubmit | El usuario envía un prompt | Inyectores de contexto (fecha, rama, info del modelo) |
| Stop | Claude termina de responder | deliberation-pride-check.sh, reviewer-stop-gate.sh |
Cada hook de comando recibe JSON por stdin y responde mediante su código de salida, stdout y stderr. Un hook PreToolUse bloquea la llamada imprimiendo esto y saliendo con código 0:
{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Force push to main is prohibited"}}
O no reporta ninguna decisión: no imprime nada, sale con código 0 y la llamada continúa por el flujo normal de permisos; quedarse en silencio no la aprueba. El código de salida 2 también bloquea, con el stderr del hook como motivo, salvo que el hook también haya impreso JSON con una decisión de bloqueo, cuyo motivo prevalece. La forma de nivel superior {"decision": "block", "reason": "..."} que usaban antes los hooks PreToolUse está obsoleta para este evento: Claude Code convierte los antiguos valores "block" y "approve" en "deny" y "allow", así que escribe los hooks nuevos con hookSpecificOutput. Otros eventos, entre ellos PostToolUse y Stop, siguen usando decision y reason de nivel superior como su formato actual.3
En este artículo, PreToolUse:Bash y PreToolUse:Task son mis etiquetas para un grupo de matcher de PreToolUse sobre la herramienta Bash y sobre la herramienta de subagentes, que se llamaba Task cuando se publicó este artículo y se llama Agent desde v2.1.63.9 No son claves de configuración; la sección de configuración muestra la forma real.7
Historias de origen: los hooks que más importan
Hook 1: git-safety-guardian.sh (PreToolUse:Bash)
El incidente: durante una sesión temprana de Claude Code, le pedí al agente que “limpiara el historial de git”. El agente ejecutó git push --force origin main. El force push sobrescribió tres días de commits en una rama compartida. Recuperé desde una copia de seguridad local, pero el proceso de recuperación de 4 horas me convenció de que el juicio probabilístico nunca debe controlar operaciones destructivas de git.
El hook:
#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
# Only check git commands
echo "$COMMAND" | grep -qE '\bgit\b' || exit 0
# Block force push to main/master
if echo "$COMMAND" | grep -qiE 'git\s+push\s+.*--force.*\b(main|master)\b'; then
cat << EOF
{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Force push to main/master blocked by safety hook"}}
EOF
fi
La lección: el hook no intenta entender la intención. Hace pattern-matching sobre la cadena del comando. Simple, determinista, imposible de eludir mediante prompting ingenioso. El agente todavía puede hacer force-push a ramas de funciones (a veces legítimo), pero main/master están permanentemente protegidas.4
Salvamentos totales: 8 intentos de force-push interceptados en 9 meses.
Hook 2: recursion-guard.sh (PreToolUse:Task)
El incidente: mientras construía el sistema de deliberación, ejecuté una sesión que generó 3 subagentes de exploración. Cada subagente, al carecer de límites de generación, generó sus propios subagentes. La recursión consumió tokens de API a 10 veces la tasa normal. Maté la sesión manualmente tras notar la quema acelerada de tokens.
El hook:
#!/bin/bash
CONFIG_FILE="${HOME}/.claude/configs/recursion-limits.json"
STATE_FILE="${HOME}/.claude/state/recursion-depth.json"
MAX_DEPTH=2
MAX_CHILDREN=5
DELIB_SPAWN_BUDGET=2
DELIB_MAX_AGENTS=12
# Validate integers safely (((VAR++)) crashes with set -e when VAR=0)
is_positive_int() {
[[ "$1" =~ ^[0-9]+$ ]] && [[ "$1" -gt 0 ]]
}
La decisión de diseño clave: los agentes heredan un presupuesto de generación de su padre en lugar de incrementar la profundidad. Un agente raíz con budget=12 puede distribuir ese presupuesto a través de cualquier forma de árbol. Los límites basados en profundidad son demasiado rígidos (impiden cadenas profundas pero estrechas que son perfectamente seguras).5
Bloqueos totales: 23 intentos de generación descontrolada.
Hook 3: blog-quality-gate.sh (Stop)
El incidente: publiqué un artículo de blog con 7 frases en voz pasiva, una nota al pie referenciada en el texto pero ausente de la sección de referencias, y “was implemented by the team” como frase de apertura. El artículo lucía pulido en mi editor pero no superaba controles básicos de calidad que cualquier revisor humano captaría.
El hook: ejecuta mi linter de blog de 12 módulos sobre cualquier archivo de contenido de blog modificado. Revisa voz pasiva, notas al pie huérfanas, meta descripciones faltantes, bloques de código sin etiquetar e integridad de citas. Cada hallazgo es específico: “Línea 47: voz pasiva detectada en ‘was implemented by the team.’ Sugerencia: ‘the team implemented.’”
El paralelo con la retroalimentación humana: el hook critica el trabajo, no al operador. Dice “la línea 47 tiene voz pasiva”, no “escribes mal”. El mismo principio que hace constructiva la retroalimentación humana hace útil la retroalimentación automatizada.
El patrón detrás de 95 hooks
La arquitectura impulsada por configuración
Mis hooks evolucionaron de valores codificados a comportamiento impulsado por configuración:
~/.claude/configs/
├── recursion-limits.json # Depth, spawn budgets, timeouts
├── deliberation-config.json # Consensus thresholds per task type
├── consensus-profiles.json # security=85%, docs=50%
├── circuit-breaker.json # Failure mode configurations
└── file-scope-rules.json # Path-scoped hook application
Mover los umbrales a configuraciones JSON significó que podía ajustar el comportamiento sin editar scripts de bash. Cuando necesité consenso relacionado con seguridad al 85% pero documentación al 50%, el cambio de configuración tomó 30 segundos. Un cambio de código habría requerido editar, probar y volver a desplegar.6
El patrón de capas del ciclo de vida
Mis 95 hooks forman una red de seguridad con cuatro capas:
Capa 1: Prevención (PreToolUse): detener cosas malas antes de que sucedan. git-safety-guardian, credentials-check, recursion-guard.
Capa 2: Contexto (UserPromptSubmit, SessionStart): inyectar la información que el agente necesita. Fecha, rama, contexto del proyecto, entradas de memoria, principios de filosofía.
Capa 3: Validación (PostToolUse): verificar que las acciones completadas cumplan con los estándares. Verificación de consenso post-deliberación, registro de salida.
Capa 4: Calidad (Stop): controlar la salida final. Pride check, quality gate, reviewer stop gate. Esta capa implementa la monitorización metacognitiva donde el agente evalúa la calidad de su propio razonamiento, no solo su salida.
Cada capa es independiente. Si un hook de PreToolUse falla silenciosamente, el hook Stop aún captura problemas de calidad. Defensa en profundidad, aplicada al comportamiento del agente de IA.
Configuración
Los hooks viven en .claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "~/.claude/hooks/git-safety-guardian.sh", "timeout": 5 }
]
},
{
"matcher": "Agent",
"hooks": [
{ "type": "command", "command": "~/.claude/hooks/recursion-guard.sh" }
]
}
]
}
}
La configuración tiene tres niveles: el evento, un grupo de matcher que filtra en qué llamadas a herramientas se dispara y los handlers que se ejecutan cuando coincide. timeout se expresa en segundos, con 600 por defecto para un hook de comando en la mayoría de los eventos, PreToolUse incluido. PreToolUse:Task, la etiqueta de la sección de arquitectura, es aquí el segundo grupo: un grupo PreToolUse con matcher en Agent. Los hooks asíncronos ("async": true) se ejecutan en segundo plano sin bloquear, lo que también significa que no pueden bloquear ni decidir nada.7
Jerarquía de ámbito
- Nivel de usuario (
~/.claude/settings.json): se aplica a todos los proyectos. Mis 95 hooks viven aquí. - Nivel de proyecto (
.claude/settings.json): añade hooks específicos del proyecto. - Frontmatter de Skill/Subagente: limitado al ciclo de vida de un componente específico.8
Qué haría diferente
Empieza con 3 hooks, no 25. Mi primer mes produjo 25 hooks, muchos de los cuales añadían contexto que el agente ya tenía. La sobrecarga de cargar 25 hooks en cada llamada a herramienta era medible. Finalmente los reduje a los hooks que producían valor real (prevenían incidentes reales, capturaban problemas de calidad reales).
Impulsado por configuración desde el día uno. Pasé dos semanas refactorizando umbrales codificados en configuraciones JSON. Esa refactorización habría sido gratuita si hubiera empezado con configuraciones.
Infraestructura de pruebas temprano. Los primeros 20 hooks no tenían pruebas. Cuando añadí el arnés de pruebas (48 pruebas de integración bash), encontré 3 hooks que fallaban silenciosamente en casos extremos. Las pruebas deberían haber salido con el hook #1.
Puntos clave
Para desarrolladores que comienzan con hooks: - Empieza con tres hooks: seguridad de git (PreToolUse:Bash), inyección de contexto (UserPromptSubmit) y control de calidad (Stop); añade más solo cuando tengas incidentes que los justifiquen - Usa el marco de tiempo de decisión: la arquitectura de hooks es irreversible (95 hooks dependen de ella), así que invierte en el modelo del ciclo de vida antes de escribir hooks
Para equipos que estandarizan hooks: - Estandariza los hooks a nivel de usuario para que cada miembro del equipo obtenga las mismas barreras de seguridad - Rastrea las métricas de hooks (operaciones bloqueadas, incidentes interceptados) para justificar el costo de mantenimiento - Revisa los registros de hooks mensualmente para identificar nuevos patrones que valga la pena automatizar
Preguntas frecuentes
¿Qué son los hooks de Claude Code?
Los hooks son scripts de shell que se ejecutan en puntos específicos del ciclo de vida durante las sesiones de Claude Code. Se disparan deterministamente en momentos específicos: antes de que se ejecute una herramienta (PreToolUse), después de que se complete (PostToolUse), cuando envías un prompt (UserPromptSubmit), cuando comienza una sesión (SessionStart) y cuando Claude termina de responder (Stop). Los hooks reciben JSON por stdin con contexto completo (nombre de la herramienta, entrada, ID de sesión) y pueden bloquear operaciones, inyectar contexto o aplicar controles de calidad. Proporcionan garantías deterministas sobre un LLM probabilístico.
¿Cuántos hooks puede ejecutar Claude Code y hay un costo de rendimiento?
No hay un límite estricto en el número de hooks. Ejecuto 95 hooks en 6 de los 26 eventos del ciclo de vida disponibles (a partir de v2.1.116, abril de 2026), con aproximadamente 200ms de sobrecarga total por evento. El límite práctico es la latencia: cada hook añade tiempo de ejecución antes o después de las llamadas a herramientas. La optimización clave es usar dispatchers (uno por evento, que ejecutan hooks secuencialmente desde stdin cacheado) en lugar de hooks independientes que cada uno lee stdin por separado. Las escrituras concurrentes desde hooks independientes causaron corrupción de JSON en mi configuración inicial; los dispatchers eliminaron ese modo de fallo por completo.
¿En qué eventos se disparan los hooks de Claude Code?
Claude Code expone 26 eventos del ciclo de vida para hooks a partir de v2.1.116 (abril de 2026). Los seis más comunes a los que se dirigen mis hooks son: SessionStart (comienza una nueva sesión), SessionEnd (la sesión termina), PreToolUse (antes de que se ejecute cualquier herramienta), PostToolUse (después de que la herramienta se complete), UserPromptSubmit (el usuario envía un prompt) y Stop (Claude termina de responder). Otros incluyen SubagentStart, PermissionRequest, PermissionDenied, TaskCreated, CwdChanged, FileChanged, PreCompact y más. PreToolUse y PostToolUse pueden acotarse aún más con un matcher sobre el nombre de la herramienta, por ejemplo Bash o Agent; PreToolUse:Bash y PreToolUse:Task son la abreviación que usa este artículo para esos grupos. Cada evento recibe JSON por stdin con el contexto relevante.
¿Los hooks de Claude Code pueden bloquear llamadas a herramientas?
Sí. Un hook PreToolUse que imprime {"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "explanation"}} por stdout y sale con código 0 impide que la llamada a la herramienta se ejecute, y el código de salida 2 también la bloquea, con stderr como motivo salvo que el hook también haya impreso JSON con una decisión de bloqueo. La forma anterior de nivel superior {"decision": "block", "reason": "explanation"} está obsoleta para PreToolUse; Claude Code la convierte en "deny", y otros eventos como PostToolUse y Stop todavía la usan como su formato actual. Este es el mecanismo central para los hooks de seguridad: mi git-safety-guardian bloquea los force pushes a main, mi credentials-check bloquea lecturas de archivos .env y mi recursion-guard bloquea la generación excesiva de agentes. El bloqueo es determinista y no puede eludirse mediante prompting. Un hook que sale con código 0 y sin salida no tiene ninguna decisión que reportar, así que la operación continúa por el flujo normal de permisos.
¿Cuál es la diferencia entre los hooks PreToolUse y PostToolUse?
PreToolUse se dispara antes de que se ejecute una herramienta y puede bloquear la operación por completo. Úsalo para puertas de seguridad: bloquear comandos peligrosos, verificar credenciales, aplicar presupuestos de generación. PostToolUse se dispara después de que una herramienta se complete y puede proporcionar retroalimentación o desencadenar acciones de seguimiento. Úsalo para validación: verificar la calidad de la salida, registrar actividad, verificar consenso. Juntos forman la primera y tercera capas de una red de seguridad de cuatro capas: prevención (PreToolUse), inyección de contexto (UserPromptSubmit), validación (PostToolUse) y control de calidad (Stop).
Referencias
-
Infraestructura de hooks del autor. 95 hooks en 6 de los 26 eventos del ciclo de vida disponibles (v2.1.116, abril de 2026), desarrollados durante 9 meses (2025-2026). ↩
-
Anthropic, “Claude Code Hooks Reference,” 2026. 26 tipos de eventos del ciclo de vida a partir de v2.1.116 (abril de 2026). ↩
-
Anthropic, “Hooks reference,” documentación de Claude Code, consultada el 21 de octubre de 2026. Control de decisiones de PreToolUse: “PreToolUse previously used top-level
decisionandreasonfields, but these are deprecated for this event. UsehookSpecificOutput.permissionDecisionandhookSpecificOutput.permissionDecisionReasoninstead. The deprecated values"approve"and"block"map to"allow"and"deny"respectively. Other events like PostToolUse and Stop continue to use top-leveldecisionandreasonas their current format.” Sobre el código de salida 2 en PreToolUse: “Blocks the tool call”; “The message that comes with the block is your hook’s stderr.” Código de salida 0: “Exit code 0 with no output means the hook has no decision to report, so the tool call continues through the normal permission flow. The hook can deny the call, but staying silent doesn’t approve it.” Código de salida 2 con JSON: “If your hook also printed JSON that makes a blocking decision, Claude Code uses that decision’s reason instead.” ↩ -
git-safety-guardian.sh del autor. 8 intentos de force-push interceptados rastreados en
~/.claude/state/. ↩ -
recursion-guard.sh del autor. Modelo de herencia de presupuesto documentado en
~/.claude/configs/recursion-limits.json. ↩ -
Arquitectura impulsada por configuración del autor. 14 archivos de configuración JSON que codifican todos los umbrales y reglas de los hooks. ↩
-
Anthropic, “Hooks reference,” documentación de Claude Code, consultada el 21 de octubre de 2026. Configuración: “The configuration has three levels of nesting”, enumerados como “Choose a hook event to respond to, like PreToolUse or Stop”, “Add a matcher group to filter when it fires, like “only for the Bash tool”” y “Define one or more hook handlers to run when matched”. Campos comunes:
typees “command”, “http”, “mcp_tool”, “prompt” o “agent”;timeoutes “Seconds before canceling. Claude Code doesn’t enforce it on a command hook you run with async: true. Defaults: 600 for command, http, and mcp_tool; 30 for prompt; 60 for agent. Claude Code lowers the command, http, and mcp_tool default to 30 on UserPromptSubmit, PreModelSwitch, and PostModelSwitch, and to 10 on MessageDisplay.” Campoasyncdel hook de comando: “If true, runs in the background without blocking.” Hooks en segundo plano: “Async hooks can’t block or control Claude’s behavior: response fields like decision, permissionDecision, and continue have no effect, because the action they would have controlled has already completed.” Matcher de PreToolUse: “Matches on any tool name except EndConversation: built-in tools such as Bash, PowerShell, Edit, Write, Read, Glob, Grep, Agent, Workflow, WebFetch, WebSearch, AskUserQuestion, and ExitPlanMode, and any MCP tool names.” ↩↩ -
Anthropic, “Claude Code Documentation,” 2025. Jerarquía de ámbito de hooks. ↩
-
Anthropic, “Create custom subagents,” documentación de Claude Code, consultada el 21 de octubre de 2026: “In version 2.1.63, the Task tool was renamed to Agent. Existing
Task(...)references in settings and agent definitions still work as aliases.” ↩