Hooks

defineHook — run code at points in the agent lifecycle, like before a turn or after a tool call.

Hooks let you run code at lifecycle points — logging, metrics, validation, or side effects. Each file in agent/hooks/ default-exports a hook.

// agent/hooks/log_tools.ts
import { defineHook } from "arcie/hooks";
 
export default defineHook({
  name: "log_tools",
  event: "afterToolCall",
  handler: ({ toolCall }) => {
    console.log(`${toolCall?.tool} took ${toolCall?.durationMs}ms`);
  },
});

defineHook requires name, event, and handler — omitting any throws Hook must have name, event, and handler.

`HookConfig`

interface HookConfig {
  name: string;
  event: HookEvent;
  handler: (payload: HookPayload) => void | Promise<void>;
}

Lifecycle events

type HookEvent =
  | "beforeTurn"
  | "afterTurn"
  | "beforeToolCall"
  | "afterToolCall"
  | "onError"
  | "onStart"
  | "onEnd";

Event	Fires
`onStart`	When the agent starts.
`beforeTurn`	Before each turn is processed.
`beforeToolCall`	Before a tool executes.
`afterToolCall`	After a tool returns.
`afterTurn`	After each turn completes.
`onError`	When an error is raised.
`onEnd`	When the agent shuts down.

`HookPayload`

The handler receives a payload scoped to the event:

interface HookPayload {
  turn?: TurnContext;          // turn events
  toolCall?: ToolCallContext;  // tool events
  error?: Error;               // onError
}
 
interface ToolCallContext {
  tool: string;
  input: unknown;
  output?: unknown;
  durationMs?: number;
  error?: Error;
}

Hooks are for observation and side effects. To change what the agent can do, use tools; to change what's allowed, use policies.

PreviousSkills

Next Channels