Hooks: el comportamiento que no decide el modelo
Guía interna de IAcademy. Acompaña al módulo ADE17 · Hooks.
La idea, en una frase
Un hook es código que se ejecuta en un momento fijo de la vida del agente, sin que el modelo opine. Si algo tiene que pasar siempre, no lo pidas en el prompt: lo pides en un hook. El prompt persuade; el hook obliga.
El calendario de eventos
Los eventos se agrupan por cadencia, y esa agrupación importa más que la lista:
| Cadencia | Eventos | Para qué sirve |
|---|---|---|
| Una vez por sesión | SessionStart, SessionEnd | Preparar entorno, registrar, recoger métricas |
| Una vez por turno | UserPromptSubmit, Stop | Inyectar contexto al empezar; validar al terminar |
| En cada llamada a herramienta | PreToolUse, PostToolUse | Bloquear, auditar, formatear, ejecutar pruebas |
PreToolUse recibe el nombre de la herramienta y sus argumentos completos; PostToolUse recibe además la salida. Eso es lo que permite decidir con información real y no con una intuición del modelo.
Códigos de salida: aquí está la diferencia
No todos los eventos pueden vetar. Confundirlo es el error más común:
PreToolUsecon código 2 bloquea la llamada, y es el único caso limpio de veto: la herramienta no llega a ejecutarse.PostToolUsecon código 2 no deshace nada: la herramienta ya corrió. Solo envía tu mensaje de error al modelo para que reaccione.- Los eventos informativos (
SessionStart,SessionEnd, notificaciones) muestran el código 2 al usuario o lo ignoran: no bloquean nada.
De ahí la regla de diseño: lo que no debe ocurrir se impide antes; lo que ya ocurrió se detecta después. Un hook que pretende prohibir algo desde PostToolUse llega tarde siempre.
Lo que inyecta contexto
La salida por stdout de UserPromptSubmit y SessionStart se añade al contexto del modelo: son los dos puntos naturales para meter estado real (rama actual, versión, incidencias abiertas). En el resto, la salida es para el usuario o para el log. Si metes contexto en un evento que no lo inyecta, no pasa nada visible — y creerás que tu hook no funciona.
La trampa de reanudar una sesión
Cuando se reanuda una conversación, los eventos de mitad de sesión no se vuelven a ejecutar: se reproduce el texto guardado del turno original. Un hook que inyectaba la hora, el SHA del commit o el estado del despliegue devolverá el valor de entonces. Si ese dato decide algo, vuelve a comprobarlo en vez de confiar en el texto guardado.
Lo que merece un hook
- Impedir un acceso: que no se lean ficheros de secretos ni se escriba fuera del repositorio.
- Formatear o validar sin preguntar después de cada edición: así el formato no depende de que el modelo se acuerde.
- Auditar: registrar qué herramienta, con qué argumentos y cuándo. Es la traza que después te salva en una revisión.
- Preparar el terreno al arrancar: dependencias, variables, estado del entorno.
Lo que no merece un hook
- Decidir cosas de negocio. Un hook es un guardarraíl, no un orquestador.
- Trabajo lento. Corre en cada llamada: si tarda, lo notas en todo el bucle.
- Efectos difíciles de deshacer. Un hook con código 2 en un evento informativo no bloquea, así que cualquier acción irreversible que dispares ahí, ya está disparada.
Probarlos antes de confiar en ellos
Los hooks se declaran en la configuración del agente y se pueden ejecutar a mano: pásales el JSON del evento y comprueba el código de salida antes de confiar en ellos. Tres comprobaciones bastan: que dispara cuando debe, que el código de salida es el que crees, y que el mensaje de error dice qué hacer y no solo que algo falló.
Seguir
- Módulo ADE17 · Hooks y ADE16 · Agent Skills, para la parte de procedimiento.
- AFE19 · Guardrails, autorización y seguridad del agente, para el diseño de controles.
- MED02 · Telemetría de una llamada a modelo, si el hook es para observar.