1. ¿Qué son los Hooks y para qué sirven?
2. Ciclo de vida y eventos
3. Input y Output
4. Tipos de hooks
5. Cómo crear un Hook en Claude Code
6. Conclusiones
¿Qué son los Hooks y para qué sirven?
Los hooks son comandos shell, endpoints HTTP o prompts LLM definidos por el usuario que se ejecutan automáticamente en puntos específicos del ciclo de vida de Claude Code. Permiten interceptar, modificar o reaccionar a las acciones del agente sin necesidad de modificar su código fuente.
En términos prácticos, un hook es un mecanismo de extensión que transforma Claude Code en una plataforma programable: puedes añadir validaciones, registrar actividad, bloquear operaciones peligrosas o enriquecer el contexto del agente de forma transparente.
Casos de uso principales
- Seguridad: bloquear comandos destructivos o ediciones de ficheros sensibles
- Observabilidad: registrar cada prompt, herramienta usada y tokens consumidos
- Integración CI/CD: ejecutar linters o tests automáticamente después de cada escritura
- Control de acceso: gestionar permisos de forma programática
- Contexto dinámico: inyectar información relevante al inicio de cada sesión
- Automatización: responder a cambios en ficheros o directorios
Ciclo de vida y eventos
Claude Code define un conjunto de eventos que cubren todo el ciclo de vida de una sesión, desde el inicio hasta el cierre, pasando por cada turno de conversación y cada llamada a herramienta dentro del bucle agéntico.
Los tres ritmos del ciclo de vida
- Una vez por sesión: SessionStart y SessionEnd enmarcan toda la sesión.
- Una vez por turno: UserPromptSubmit, Stop y StopFailure se disparan en cada respuesta de Claude.
- Por cada herramienta: PreToolUse y PostToolUse se ejecutan dentro del bucle agéntico, potencialmente docenas de veces por sesión.
Input y Output
Cada hook recibe un objeto JSON con información contextual sobre el evento. Para hooks de tipo command, este JSON llega por stdin; para hooks HTTP, llega como body del POST.
JSON Output
Con exit code 0 puedes devolver JSON por stdout para un control más granular. Campos universales:
Tipos de hooks
Claude Code soporta cuatro tipos de handlers, cada uno con un caso de uso óptimo:
Hook tipo command: el más común.
Es el tipo más flexible. Tu script recibe el JSON del evento por stdin, puede inspeccionarlo, tomar acción (log, API call, validación…) y comunicar la decisión mediante exit code o JSON en stdout.
Hook tipo prompt: decisiones semánticas
Envía el contexto del evento a un modelo Claude para que tome una decisión en lenguaje natural. Ideal para políticas complejas que son difíciles de expresar con código.
Hook tipo http: integraciones externas
Perfecto para conectar Claude Code con sistemas externos: webhooks, APIs de auditoría, servicios de seguridad corporativos o sistemas SIEM.
Cómo crear un Hook en Claude Code
La configuración de hooks sigue una jerarquía de tres niveles: primero eliges el evento del ciclo de vida, luego defines un matcher para filtrar cuándo debe dispararse, y finalmente especificas el handler que se ejecutará.
Estructura del fichero de configuración
El JSON de configuración tiene tres niveles de anidamiento:
Matchers — filtrar cuándo se dispara
El campo matcher determina para qué herramientas o eventos específicos se ejecuta el hook:
Campos del handler
Campos disponibles para todos los tipos de hook:
Variables de entorno útiles
Ejemplo: Bloquear ediciones de ficheros sensibles
Un caso de uso crítico es proteger ficheros que nunca deben ser modificados por el agente: secretos, certificados, configuraciones de producción, etc.
Estrategia con PreToolUse (hook tipo command)
Usamos el evento PreToolUse para interceptar cualquier operación de escritura (Edit o Write) antes de que se ejecute. Si el fichero destino está en una lista negra, devolvemos una decisión de denegación.
Paso 1 — Configurar el hook en .claude/settings.json
Paso 2 — Crear el script .claude/hooks/block-sensitive.sh
Paso 3 — Dar permisos de ejecución
Alternativa con hook tipo prompt
Para casos donde la política de seguridad es más compleja y difícil de expresar con patrones, puedes usar un hook de tipo prompt que delega la decisión a un modelo Claude más pequeño y rápido:
Conclusiones
Los hooks representan un cambio de paradigma: pasan de ser una herramienta de IA que el usuario guía manualmente, a una plataforma de automatización programable e integrable en cualquier flujo de trabajo existente. Esto permite darnos
Puntos clave
- Los hooks son deterministas: se ejecutan siempre en los mismos puntos del ciclo de vida, garantizando consistencia.
- El modelo de exit codes es simple pero potente: exit 0 permite, exit 2 bloquea, cualquier otro es un error no bloqueante.
- La jerarquía de scope (usuario → proyecto → local → managed) permite una gobernanza granular, especialmente útil en entornos empresariales.
- Los hooks async permiten ejecutar tareas lentas (tests, linting, notificaciones) sin bloquear al agente.
- Los hooks de tipo prompt habilitan políticas de seguridad expresadas en lenguaje natural, no en código.
Buenas prácticas
- Mantén los hooks rápidos: los hooks síncronos bloquean al agente. Para tareas largas usa async: true.
- Valida siempre la entrada con jq: no asumas la estructura del JSON, puede variar entre versiones.
- Usa $CLAUDE_PROJECT_DIR para rutas: evita rutas absolutas que rompan en otros sistemas.
- Registra errores en stderr: solo stderr se muestra en el transcript cuando hay un error no bloqueante.
- Versiona tus hooks en .claude/: son parte del proyecto y deben tener el mismo ciclo de vida que el código.