Lifecycle Hooks
Qué es un hook
Un Lifecycle Hook es un mecanismo del runtime que asocia comportamiento configurado con un evento o punto del ciclo de ejecución. El evento dispara o habilita un handler bajo las condiciones que implemente el sistema. Esta definición de trabajo del Atlas separa el punto de integración del comportamiento que se ejecuta; no presupone un script, una lista universal de eventos ni una política de bloqueo común.
El problema aparece cuando una acción debe acompañar una fase de trabajo sin depender de que el agente la recuerde como próximo paso. Puede interesar preparar contexto al iniciar una sesión, observar una herramienta o comprobar una condición antes de cerrar. El hook permite integrar ese comportamiento con el ciclo del runtime. Su cobertura y sus garantías deben examinarse explícitamente.
Un evento reconocible no garantiza un resultado determinista. El handler puede ejecutar una regla programada, consultar un servicio o pedir una evaluación a un modelo, si la implementación lo admite. Incluso un script puede depender de red, tiempo o estado externo. Determinismo del disparador, del handler y de sus efectos son preguntas diferentes.
Lifecycle Events
Inicio de sesión, antes de una herramienta, después de una operación, cambio de archivos o terminación de tarea son ejemplos de puntos posibles. No constituyen un catálogo obligatorio. Cada runtime define nombres, payloads, filtros y qué acciones atraviesan cada punto. Un evento puede no existir en otro cliente o cubrir solamente una parte de las operaciones.
Conviene distinguir intención, intento y efecto. Un evento previo puede observar argumentos propuestos sin saber si la operación finalmente tendrá éxito. Un evento posterior puede recibir un error o una respuesta incompleta. «La herramienta terminó» no demuestra que el resultado de negocio sea correcto. El handler necesita interpretar el contrato del evento, no inferirlo de un nombre familiar.
El ciclo de vida de un coding agent tampoco es el de CI o Git. Un hook del runtime, un hook del repositorio y una etapa de pipeline pueden ejecutar scripts, pero se activan en momentos distintos y observan contextos diferentes. La similitud del mecanismo no hace equivalentes sus coberturas ni permite sustituir una verificación posterior por otra anterior.
Hook vs Skill, Tool y Workflow
agent-skills ofrece un procedimiento seleccionado por pertinencia a una tarea. El hook responde a un evento configurado. Una skill puede indicar que se ejecute una comprobación y un hook puede automatizarla en cierto punto, pero no son dos nombres para el mismo artefacto. El procedimiento puede usarse sin hooks y el hook sin conocimiento especializado empaquetado.
Una herramienta expone una capacidad invocable. El hook establece cuándo se ejecuta un comportamiento que puede utilizar esa capacidad. Una llamada de shell puede ser herramienta del agente o handler de un evento según su integración. La operación subyacente puede coincidir mientras cambian quién la inicia, qué datos recibe y cómo afecta la continuación.
workflows-vs-agents distingue formas de conducir progreso. Un hook puede participar en un workflow, pero no representa el proceso completo. agentic-workflow-patterns organiza secuencias, rutas y feedback; un evento aislado no expresa necesariamente esas relaciones. Encadenar handlers sin un contrato claro de continuación puede introducir un workflow accidental difícil de observar y mantener.
Hook vs Guardrail y Plugin
Un guardrail es un control sobre entradas, salidas o acciones en puntos cubiertos. Puede implementarse mediante un hook que evalúe y bloquee una operación. Sin embargo, un hook que solo registra información no es un control preventivo. Tampoco todo control del runtime necesita estar expuesto como hook configurable.
La diferencia importa ante una afirmación de seguridad. Un handler que avisa después de una escritura no impidió la escritura. Uno previo que se omite en determinadas rutas no cubre esas rutas. El nombre «guardrail» necesita respaldo en enforcement, alcance y comportamiento ante fallos, sin prometer protección perfecta por tener una integración de eventos.
agent-extension-packages puede distribuir handlers o su configuración. El paquete no es el hook y su instalación no prueba que el host lo haya habilitado o confiado. Un plugin puede contener skills sin hooks; un hook puede configurarse sin plugin. Separar distribución, carga y ejecución permite revisar cada responsabilidad sin atribuir efectos al mero inventario de archivos.
| Comparación | Diferencia decisiva |
|---|---|
| Hook / Skill | Evento de runtime frente a procedimiento seleccionado para una tarea. |
| Hook / Tool | Punto que dispara comportamiento frente a capacidad invocable. |
| Hook / Workflow | Integración en un evento frente a coordinación del proceso. |
| Hook / Guardrail | Mecanismo de integración frente a propósito de control efectivo. |
| Hook / Plugin | Comportamiento por evento frente a unidad de distribución. |
Las combinaciones son posibles: un paquete puede entregar un hook que utiliza una herramienta para aplicar un control. La combinación conserva esas responsabilidades y necesita verificar cada contrato, en lugar de atribuir todas las garantías al nombre hook.
Tipos de handler y continuación
Los handlers pueden ser comandos, llamadas a servicios o evaluaciones asistidas por modelos, según soporte. Un handler basado en prompt puede interpretar una condición, mientras otro ejecuta una comparación programada. Sus errores y variabilidad son diferentes. Que una evaluación devuelva una decisión estructurada no demuestra que haya comprendido correctamente el requisito.
La continuación también varía. Un handler síncrono puede hacer esperar a la operación; uno asíncrono puede observarla sin poder detenerla. Bloquear, modificar argumentos, agregar contexto o notificar son capacidades distintas que requieren un contrato específico. No todos los eventos admiten todos los efectos ni todos los tipos de handler.
| Aspecto | Pregunta que necesita respuesta |
|---|---|
| Momento | ¿Se ejecuta antes, después o alrededor de qué operación? |
| Entrada | ¿Qué observación recibe y qué información falta? |
| Continuación | ¿Puede bloquear, modificar o solamente observar? |
| Fallo | ¿Qué ocurre ante error, timeout o respuesta inválida? |
| Concurrencia | ¿Hay orden garantizado entre handlers coincidentes? |
No existe una elección universal entre continuar o bloquear ante un fallo. Si el hook es solo telemetría, detener toda tarea puede resultar desproporcionado. Si aplica una condición necesaria para una operación sensible, continuar silenciosamente puede invalidar el control. La política debe corresponder al propósito y a garantías reales del runtime.
Modelos de producto
Los ejemplos se consultaron el 2026-10-26. Claude Code documenta distintos tipos de handler, incluidos comandos y evaluaciones por prompt o agente, con soporte dependiente del evento. Eso permite distinguir un disparador de ciclo de vida de una evaluación que puede ser probabilística. No se reproduce su catálogo como contrato general del Atlas.
Codex documenta hooks síncronos y asíncronos, con diferencias sobre lo que pueden hacer antes de continuar. Gemini CLI documenta su propio sistema de hooks. Nombres similares no aseguran iguales payloads, capacidad de bloqueo, timeouts o tratamiento de errores. La compatibilidad debe comprobarse en el host efectivo.
En la documentación consultada de Gemini CLI, el loop espera que terminen los hooks coincidentes antes de continuar. En Codex, un handler asíncrono no puede bloquear o reescribir la operación desde el background. Esa diferencia concreta impide trasladar un supuesto de control previo basándose solo en que ambos productos ofrecen hooks.
Estas diferencias también pueden existir entre superficies de un mismo producto. Una configuración local no demuestra que funcione igual en cloud o dentro de un IDE. Copiar un handler entre clientes exige revisar su contrato y capacidades, sin asumir que adaptar el nombre del evento alcanza para conservar las garantías.
Seguridad y permisos
Los hooks pueden ejecutar código con autoridad significativa del entorno. agent-permissions-and-approval-boundaries y agent-sandboxing conservan la distinción entre autorización y restricción técnica. Un handler no debe considerarse confiable por venir de una extensión conocida ni por ejecutarse fuera de la selección directa del modelo. Importan procedencia, código, credenciales y efectos accesibles.
El evento puede contener contenido no confiable: argumentos de herramientas, rutas, respuestas externas o texto del usuario. Construir comandos a partir de esos datos introduce riesgos de interpretación. Registrar payloads completos puede conservar secretos innecesarios. Estas observaciones sitúan el hook como input de supply chain y ejecución, sin convertir este canonical en una política completa de AI Security.
El alcance efectivo del entorno también importa. Un hook que llama a un servicio remoto introduce una frontera distinta de uno que revisa archivos locales. El sandbox del agente no demuestra por sí solo restricción sobre todo componente externo. Las aprobaciones y controles deben examinarse donde ocurre el efecto, no solamente donde se origina el evento.
Failure Modes
Un handler puede fallar, exceder su tiempo o agregar latencia significativa. Puede observar un archivo mientras otra operación lo modifica y evaluar un estado que dejó de ser actual. Varios handlers pueden asumir un orden inexistente. El runtime necesita hacer visibles esas condiciones para evitar que una aparente comprobación exitosa oculte una ejecución parcial.
La reentrada puede producir loops: un hook modifica un archivo, esa modificación dispara otro evento y se repite el comportamiento. Los efectos repetidos merecen examinar idempotency; una notificación duplicada y una mutación repetida pueden tener consecuencias muy distintas. Agregar retries sin entender el efecto puede agravar el problema en vez de recuperar la ejecución.
Otra falla es cobertura incompleta. Un control sobre una herramienta puede dejar otras rutas capaces del mismo efecto. Un evento de finalización puede no ejecutarse si la sesión se interrumpe. No debe concluirse que «todo está verificado» cuando solo se observó un punto particular. La ausencia de un aviso tampoco demuestra que el hook haya estado activo.
Ejemplo de comprobación acotada
En Commerce.Api, un handler posterior a un cambio podría registrar qué archivos se tocaron y proponer una comprobación pertinente. Ese registro no demuestra que las pruebas se ejecutaron. Un handler previo a una acción sensible podría evaluar una condición si el runtime permite bloquearla. Son finalidades diferentes: evidencia posterior y control previo no se sustituyen.
Si la comprobación depende de un servicio indisponible, interesa registrar el resultado como no verificado o fallido según el contrato, en vez de declarar éxito. Si la tarea termina, development-context-and-execution-records puede conservar el evento observado, la comprobación efectiva y su límite. El ejemplo no crea un hook real ni prescribe automatizar cada cambio.
Relaciones y fuentes
agent-harness puede implementar eventos, despacho y continuación; agent-execution-environment sitúa los recursos del handler. ai-assisted-software-engineering permite llegar a skills, perfiles y paquetes. Los hooks son una posibilidad de extensibilidad, sin ser un requisito universal para utilizar agentes de desarrollo.
Fuentes primarias consultadas el 2026-10-26. La definición, preguntas de revisión y ejemplos son síntesis editorial; las capacidades actuales pertenecen a cada producto.