Qué son los hooks de Claude Code y cuándo usarlos

Hola, bienvenido. La skill personal para los mensajes de commit de la lección anterior cerró la sección de comandos y skills, y en esta lección empezamos la de hooks. Vamos a ver qué es un hook, los 5 tipos que existen, en qué punto del agentic loop se ejecuta cada evento y, sobre todo, cuándo un problema se resuelve con un hook y cuándo va antes un permiso, una rule o una skill. Es una lección de conceptos: en las 4 siguientes vamos a configurar los hooks de claude-tasks uno a uno.

¿Qué tienen de distinto los hooks? Piensa en todo lo que le hemos dado a Claude hasta ahora para que trabaje bien en el proyecto: el CLAUDE.md, las rules de modelos y tests y las 3 skills. Todo eso son instrucciones que Claude lee y decide cómo aplicar. Funcionan muy bien la mayor parte del tiempo, pero la documentación es muy clara: una instrucción como «nunca edites el .env» en CLAUDE.md o en una skill es una petición, y lo que la convierte en una garantía es un hook PreToolUse que bloquea la edición. Un hook no depende de lo que decida Claude: Claude Code lo ejecuta siempre, en un momento concreto del ciclo.

Ya hemos visto una pieza que funciona así, las reglas de permisos, que Claude Code aplica sin que el modelo pueda saltárselas. La diferencia es que una regla solo sabe comparar el nombre de una herramienta y un patrón, y un hook ejecuta tu propia lógica. Con esa idea en la cabeza vamos a ver qué es exactamente un hook, y al final de la lección tendrás un criterio para decidir qué pieza usar en cada caso.

Para seguir esta lección no necesitas cambiar nada en claude-tasks: basta con que tengas claro lo que hemos montado hasta aquí, sobre todo las reglas de permisos, el sandbox y las skills.

Un hook es una acción que defines tú y que Claude Code ejecuta de forma automática en un punto concreto de su ciclo de trabajo, como antes de que Claude use una herramienta, después de que la use o cuando envías un prompt. La documentación lo describe como un control determinista: ciertas acciones ocurren siempre, en lugar de depender de que el modelo decida hacerlas.

Cuando llega ese punto, Claude Code le pasa al hook los datos del evento en JSON, por ejemplo qué herramienta va a usar Claude y con qué argumentos, y el hook puede hacer 3 cosas con ellos: actuar por su cuenta, como formatear un archivo o enviar una notificación, devolver contexto para Claude o devolver una decisión, como bloquear una llamada a una herramienta. Todo eso ocurre fuera del razonamiento del modelo. Los hooks funcionan igual en la terminal, en las extensiones de los IDE, en la aplicación de escritorio y en las sesiones en la nube.

Los hooks se configuran en los mismos archivos de configuración que ya conoces, dentro de una clave hooks, con 3 niveles: el evento al que respondes, un filtro para decidir cuándo se dispara y la acción que se ejecuta. Este es un ejemplo de la documentación, con 2 hooks que se ejecutan antes de cada comando de Bash, uno que apunta el comando en un log y otro que lanza un script para bloquear los rm -rf:

No lo copies en claude-tasks: la estructura, los eventos y los filtros los vemos con calma en la siguiente lección. Fíjate solo en la forma: el evento es PreToolUse, el filtro dice que solo le interesan las llamadas a Bash y dentro van los 2 hooks, que Claude Code ejecuta en paralelo.