Hooks

Hooks let you intercept and transform agent, tool, and flow behavior at various lifecycle points. There are two kinds:

• Side-effect hooks — observe values without modifying them (logging, metrics, etc.).
• Transform hooks — modify values in the pipeline (altering messages, responses, etc.).

Hooks are always attached after creation using hookIntoAgent or hookIntoFlow:

import { createAgent, hookIntoAgent } from "@comma-agents/core";

const agent = createAgent({
  name: "assistant",
  model: "openai/gpt-4o",
});

hookIntoAgent(agent, {
  beforeCall: [async (message) => console.log("Sending:", message)],
  afterCallResult: [async (result) => console.log("Tokens:", result.usage.promptTokens)],
});

Multiple hook calls stack — each call appends to the existing hooks rather than replacing them.

Domain-specific Hooks

Hook interfaces are co-located with their domain. See the dedicated pages for the full APIs:

• Agent Hooks — hookIntoAgent, AgentHooks, ToolHooks
• Flow Hooks — hookIntoFlow, FlowHooks, CycleFlowHooks

Hook Primitives

The two base hook types that all domain-specific hooks are built on are documented in Hook Primitives.

Built-in Hooks

Comma Agents ships with built-in hooks for common cross-cutting concerns:

• Token Tracking — accumulate real token usage, monitor context window budget