Hooks en Claude Code: control determinístico del ciclo de vida
Un hook es un punto de inyección en el ciclo de vida de Claude Code. Cada vez que el agente va a hacer algo importante (usar una herramienta, terminar una respuesta, recibir un prompt), Claude Code emite un evento; si declaraste un hook para ese evento en settings.json, lo ejecuta y respeta su decisión. Donde una regla en CLAUDE.md es un recordatorio amable que el modelo cumple casi siempre, un hook es un guardia obligatorio que se cumple siempre.
La diferencia clave: una instrucción en
CLAUDE.mdes probabilística (el modelo la cumple el 90% del tiempo). Un hook es determinístico: no depende del criterio del modelo, es una llamada directa del runtime. Para reglas críticas que no admiten ese 10% de fallo, usa un hook.
¿Por qué existen los hooks?
Escribes en CLAUDE.md: "nunca toques este directorio", "corre el formatter después de editar". El modelo lo cumple casi siempre. El problema es el otro 10%: una sesión larga, el agente distraído entre tareas, y de pronto edita el archivo que dijiste que no. Un fallo en cincuenta basta para romper algo en producción.
Los hooks suben esas reglas del plano del prompt al plano del runtime. Sirven para tres cosas: bloquear acciones peligrosas con certeza, automatizar pasos repetitivos sin depender de la memoria del modelo, y reaccionar a eventos del ciclo de vida con tus propios scripts.
Los eventos del ciclo de vida
Claude Code expone más de dos docenas de eventos. Los cuatro más usados:
| Evento | Cuándo dispara | Para qué sirve |
|---|---|---|
PreToolUse |
Antes de invocar una herramienta | Aprobar, modificar o bloquear la acción |
PostToolUse |
Después de que la herramienta terminó | Encadenar acciones (formatear tras editar) |
Stop |
Cuando el modelo va a terminar el turno | Dejarlo cerrar o forzarlo a continuar |
UserPromptSubmit |
Cuando envías un prompt, antes de que el modelo lo lea | Validar convenciones del prompt |
Hay muchos más para puntos específicos: SessionStart, SessionEnd, PreCompact, SubagentStart, SubagentStop, PermissionRequest, FileChanged, entre otros. La referencia oficial tiene la lista completa.
Anatomía de un hook
Un hook se declara en settings.json (de proyecto, usuario o local) bajo la clave hooks, con tres partes:
- Evento: cuál del ciclo lo dispara (
PreToolUse,PostToolUse, etc.). - Matcher: filtro que decide si aplica a este disparo. Para hooks de herramientas, se compara con el nombre de la tool (
Edit,Write,Bash, oEdit|Writepara varias). - Acción: lo que el hook hace. Hay dos tipos:
- Command hook: corre un script del sistema, que recibe el contexto del evento como JSON por stdin.
- Prompt hook: manda un prompt corto a un modelo liviano (Haiku) que evalúa la situación. Más lento, pero entiende contexto que un regex no puede.
La regla técnica que importa: exit codes
En un command hook, los códigos de salida deciden el flujo:
- Exit code 2: bloquea la acción. Su
stderrvuelve al modelo como error. - Exit code 0: NO significa "aprobar". Significa que el hook no tiene decisión que reportar, así que el flujo de permisos normal continúa. El hook puede denegar, pero quedarse callado no aprueba.
- Cualquier otro código se trata como error no bloqueante.
Para enriquecer la respuesta (modificar la invocación, dar feedback al modelo), el script imprime JSON estructurado por stdout con exit 0.
Hook vs CLAUDE.md vs permisos
CLAUDE.md: para guías y preferencias que el modelo debe tener en cuenta. Probabilístico.- Permisos: para aprobar o vetar comandos de forma interactiva o por allowlist.
- Hook: para reglas que se deben cumplir SIEMPRE, sin excepción, y para automatizar pasos en eventos concretos. Determinístico.
Si una regla es crítica y no admite fallo, no la dejes en CLAUDE.md: hazla un hook.
Preguntas frecuentes
¿Qué es un hook en Claude Code?
Un hook es un punto de inyección en el ciclo de vida de Claude Code: cuando el agente va a usar una herramienta, terminar una respuesta o recibir un prompt, emite un evento, y si declaraste un hook para ese evento en settings.json, Claude Code lo ejecuta y respeta su decisión. Es control determinístico, no depende del criterio del modelo.
¿Cuál es la diferencia entre un hook y una regla en CLAUDE.md?
Una regla en CLAUDE.md es un recordatorio que el modelo cumple casi siempre, pero no garantizado. Un hook es un guardia obligatorio del runtime: se cumple siempre. Para reglas críticas que no admiten fallo, usa un hook.
¿Qué hace el exit code 2 en un hook de Claude Code?
Bloquea la acción que iba a ejecutar el modelo, y su stderr vuelve al modelo como error. Importante: el exit code 0 NO aprueba; solo indica que el hook no tiene decisión que reportar y el flujo de permisos normal continúa.
¿Cuáles son los eventos de hook más usados en Claude Code?
PreToolUse (antes de usar una herramienta, puede bloquear), PostToolUse (después, para encadenar acciones), Stop (cuando el modelo va a terminar) y UserPromptSubmit (cuando envías un prompt). Hay más de dos docenas en total.
Recursos relacionados
- Skills, hooks y MCP: las tres capas para extender Claude Code, en contexto.
- Cómo dominar Claude Code: la guía completa.
- Permisos en Claude Code: la otra forma de controlar qué puede hacer el agente.
Tu siguiente paso
Los eventos de hook y decenas de comandos más están en la Cheat Sheet de Claude Code: una hoja imprimible, en español.
Descargar la Cheat Sheet gratis
Es el resumen de Ship with Claude Code, la guía de Takren (14 módulos, 190 capítulos, actualizaciones gratuitas).