Loop Hooks - Agentium

In plain terms

hooks watch a run from outside. loopHooks sit inside the tool loop. Use them to skip a tool, rewrite a result, or stop early. That is steering. The event bus cannot do this.

loopHooks: {
  beforeToolExec: async (name) => {
    if (name === "drop_database") return { skip: true, result: "nope" };
  },
}

Hook Interface

interface LoopHooks {
  beforeLLMCall?: (messages: ChatMessage[], roundtrip: number) => Promise<ChatMessage[] | void>;
  afterLLMCall?: (response: { finishReason: string; usage: TokenUsage }, roundtrip: number) => Promise<void>;
  beforeToolExec?: (toolName: string, args: unknown) => Promise<{ skip?: boolean; result?: string } | void>;
  afterToolExec?: (toolName: string, result: string) => Promise<string | void>;
  onRoundtripComplete?: (roundtrip: number, tokensSoFar: TokenUsage) => Promise<{ stop?: boolean } | void>;
}

Usage

import { Agent, openai } from "@agentium/core";

const agent = new Agent({
  name: "monitored-agent",
  model: openai(process.env.OPENAI_MODEL ?? "gpt-6.1-sol"),
  loopHooks: {
    beforeLLMCall: async (messages, roundtrip) => {
      console.log(`Roundtrip ${roundtrip}: ${messages.length} messages`);
    },
    afterToolExec: async (toolName, result) => {
      console.log(`Tool ${toolName} returned ${result.length} chars`);
    },
    onRoundtripComplete: async (roundtrip, tokens) => {
      if (tokens.totalTokens > 50000) {
        return { stop: true }; // graceful early exit
      }
    },
  },
});

Hook Points

Hook	When	Can Modify
`beforeLLMCall`	Before each LLM API call	Return new messages array
`afterLLMCall`	After LLM response	Read-only
`beforeToolExec`	Before each tool execution	Skip tool, provide mock result
`afterToolExec`	After each tool execution	Transform the result string
`onRoundtripComplete`	After all tools in a roundtrip	Stop the loop early

These hooks are the foundation for context compaction, cost auto-stop, PII scrubbing, and checkpointing.