Conectar un Hook

Los hooks de ciclo de vida permiten reaccionar a eventos de RaiSE — inicio de sesión, construcción del graph, patrón agregado, ciclo de vida de trabajo, y más. Siguen el mismo modelo de extensión que los adaptadores: un contrato Python Protocol descubierto via entry points.

El Protocol LifecycleHook¶

Cada hook implementa este contrato:

from typing import ClassVar, Protocol, runtime_checkable
from rai_cli.hooks.events import HookEvent
from rai_cli.hooks.protocol import HookResult

@runtime_checkable
class LifecycleHook(Protocol):
    events: ClassVar[list[str]]   # Eventos a suscribir
    priority: ClassVar[int]       # Mayor número = ejecuta primero (default 0)

    def handle(self, event: HookEvent) -> HookResult: ...

Los hooks son @runtime_checkable — no se necesita herencia explícita, solo implementa la interfaz.

Eventos Disponibles¶

RaiSE emite 18 eventos tipados como dataclasses frozen:

Evento	Se dispara cuando
`session:start`	Comienza la sesión
`session:close`	Termina la sesión
`graph:build`	Se reconstruye el knowledge graph
`pattern:added`	Se registra un nuevo patrón
`discover:scan`	Completa el escaneo del código
`init:complete`	Proyecto inicializado
`adapter:loaded` / `adapter:failed`	Descubrimiento de adaptadores
`release:publish`	Release publicado
`work:start` / `work:close`	Ciclo de vida de story/epic
`mcp:call`	Invocación de herramienta MCP
`before:session:close`	Antes del cierre de sesión (puede abortar)
`before:release:publish`	Antes del release (puede abortar)

Los eventos before: pueden retornar HookResult.abort("reason") para cancelar la operación.

Ejemplo: Un Hook Personalizado¶

# my_package/hooks.py
from typing import ClassVar
from rai_cli.hooks.events import HookEvent, PatternAddedEvent
from rai_cli.hooks.protocol import HookResult

class NotifyOnPatternHook:
    """Envía una notificación cuando se agrega un nuevo patrón."""

    events: ClassVar[list[str]] = ["pattern:added"]
    priority: ClassVar[int] = 0

    def handle(self, event: HookEvent) -> HookResult:
        if isinstance(event, PatternAddedEvent):
            print(f"Nuevo patrón: {event.pattern_id}")
        return HookResult.ok()

Registro por Entry Points¶

Registra tu hook en pyproject.toml:

[project.entry-points."rai.hooks"]
my-notify = "my_package.hooks:NotifyOnPatternHook"

RaiSE descubre hooks en tiempo de ejecución desde el grupo de entry points rai.hooks — el mismo mecanismo usado para adaptadores.

Hooks Built-in¶

RaiSE incluye 5 hooks built-in:

Hook	Eventos	Propósito
`TelemetryHook`	Todos los 9 eventos post-acción	Registra señales `CommandUsage`
`MemoryMdSyncHook`	`graph:build`	Regenera MEMORY.md
`JiraSyncHook`	`work:start`, `work:close`	Transiciona issues de Jira automáticamente
`BacklogHook`	Ciclo de vida de trabajo	Crea/transiciona ítems del backlog
`GateBridgeHook`	`before:release:publish`	Ejecuta quality gates antes del release

Aislamiento de Errores¶

Los hooks siguen aislamiento estricto de errores:

Un hook que falla nunca hace crashear el CLI
Las excepciones se capturan, registran y omiten
Cada hook tiene un timeout de 5 segundos (configurable)
Aunque un hook aborte, todos los demás siguen ejecutándose (semántica all-notify)

Validación¶

Verifica que tu hook es descubierto:

rai adapter list    # los hooks aparecen en el grupo de entry points rai.hooks

Ver también: rai adapter check, Crear un Adaptador Personalizado