Hooks

Hooks

Hooks are registered through the phase-based HookRegistry. The old single-slot AgentHooks dataclass is no longer part of the public API.

Quick start

from agiwo.agent import (
    Agent,
    AgentConfig,
    HookPhase,
    HookRegistry,
    observe,
    transform,
)


async def add_prelude(payload: dict) -> dict:
    return {"prelude_text": "Please be concise."}


async def log_step(payload: dict) -> None:
    step = payload["step"]
    print(f"{step.role.value} step committed: {step.sequence}")


hooks = HookRegistry(
    [
        transform(HookPhase.PREPARE, "add_prelude", add_prelude),
        observe(HookPhase.AFTER_STEP_COMMIT, "log_step", log_step),
    ]
)

agent = Agent(
    AgentConfig(name="assistant", description="Helpful assistant"),
    model=model,
    hooks=hooks,
)

Core types

• HookPhase: lifecycle phase enum
• HookCapability: observe_only, transform, decision_support
• HookGroup: execution group ordering
• HookRegistration: one registered phase handler
• HookRegistry: ordered collection of registrations

Ordering and failures

• Execution order is group -> order -> registration order
• Only early phases may be marked critical=True
• Non-critical hook failures are isolated, logged, and recorded as HookFailed run-log facts
• Critical hook failures are re-raised and fail the run

Public phases

• prepare
• assemble_context
• before_llm
• after_llm
• before_tool_call
• after_tool_call
• before_compaction
• after_compaction
• before_retrospect
• after_retrospect
• before_termination
• after_termination
• after_step_commit
• run_finalized
• memory_persist
• compaction_failed

Payload model

Every handler receives a single payload: dict[str, Any].

• Transform phases may return a partial dict that only changes allowlisted fields
• Decision-support phases may only write the phase-specific *_advice field
• Observe-only phases should not return anything meaningful

Good uses for hooks

• logging and tracing
• message rewrites before LLM calls
• lightweight guardrails
• external memory integration
• debugging committed step flow

Prefer observe(...), transform(...), and decision_support(...) over constructing HookRegistration directly.