Skip to main content

Hooks

Hooks are small JavaScript functions you write inline in defineAgent. They run at set points in a run and can change what happens. A hook can add to the system prompt, deny or edit a tool call, rewrite the final answer, reshape a subagent result, or drop a chat message.

To be notified about runs without changing them, use webhooks instead. Both live under hooks and work together.

broods/index.ts
import { defineAgent } from "broods";

export const agent = defineAgent({
name: "guarded-agent",
hooks: {
// `system` is appended to the prompt. Return only the addition.
onStart: () => ({ system: "Never reveal internal IDs." }),

// `runsAs` catches provider tools that run as bash, like OpenAI `shell`.
onToolCall: (ctx, event) =>
(event.runsAs?.toolName ?? event.toolName) === "bash"
? { decision: "deny", denyReason: "shell disabled" }
: { decision: "allow" },

onMessageReceived: (ctx, event) =>
event.text.includes("spam") ? { drop: true } : undefined,
},
});

Each hook gets (ctx, event) and returns only the fields it may change. A wrong return type is a compile error. On deploy the SDK bundles the functions and uploads them.

Hook reference​

HookRuns whenMay return
onStarta run startssystem appends to the prompt. messages replaces the conversation for this run.
onToolCallbefore a tool runsdecision: "allow" | "deny", args to edit the input, denyReason
onToolResultafter a tool returnsoutput replaces the result
onFinishthe final answer is readyoutput replaces the answer
onStepFinisheach model step endsnothing, observe only
onErrorthe run failsnothing, observe only
onApprovala tool waits for approvalnothing yet. Returning approve is not honored.
onSubagentFinisha subagent finishesvisibleResult replaces what the parent sees
onMessageReceiveda chat message arrivesdrop discards it, text rewrites it, metadata is stored with the message
onMessageSendinga chat reply is about to be sentdrop blocks it, text rewrites it

onToolCall sees a provider tool under its own name and input. When it runs as a Broods tool (OpenAI shell or Anthropic bash as bash, a text editor as read, write or edit), event.runsAs holds that Broods call, the same one approval and policy judge. args edits the provider input, never runsAs.

onMessageReceived narrows by event.channel, so event.source is typed per provider. A Pancake message carries source.tagIds, for example. It only sees text. An attachment reads as its caption or an empty string, and a text rewrite leaves the attachment on the message.

metadata returned from onMessageReceived shows up on that message in onStart's messages, so a later hook can read who sent it without parsing text.

Sharing state across a run​

ctx.state is an object every hook in one run shares:

hooks: {
onStart: (ctx) => {
ctx.state.toolCalls = 0;
return {};
},
onToolCall: (ctx) => {
ctx.state.toolCalls = (ctx.state.toolCalls ?? 0) + 1;
return { decision: "allow" };
},
onFinish: (ctx, event) => ({
output: `${event.response}\n\n(used ${ctx.state.toolCalls ?? 0} tools)`,
}),
}
  • State starts empty on each request and must be JSON-serializable.
  • The loop hooks, onSubagentFinish and the reply's onMessageSending share one state. onMessageReceived, delayed background replies and each subagent get their own.
  • A hook that throws keeps the state earlier hooks stored. onError sees it too.
  • Nothing survives the run. For memory across requests, write to your own store with ctx.fetch.

Subagents​

A subagent run fires hooks too. A predefined subagent runs its own hooks. A virtual subagent reuses the parent's. Either way its ctx.state is its own. The parent's view of a child is onSubagentFinish, which runs with the parent's state. Chat hooks never fire for subagents.

Rules​

  • Hooks run in an isolated V8 sandbox with only ctx, event and JavaScript built-ins. No imports, no require, no Node modules, no variables from the surrounding file. Uploads that use them are rejected.
  • ctx.fetch works but blocks private and metadata addresses. ctx.config is a read-only summary of the agent: model (provider, modelId), harness, maxTurn, and the names in tools, mcp, channels, skills, subagents and denyTools. It never carries credentials, URLs or headers.
  • Hooks have a time limit. A hook that throws or times out is logged and skipped, and the run continues unchanged. A hook deny is therefore best effort. For a rule that must hold, use an enforced policy.
  • onFinish changes the stored and delivered answer, but tokens already streamed over SSE cannot be taken back.
  • A return may be at most 128 KB larger than the event it received.
  • console.log and info log at INFO, warn and error at their levels, debug at DEBUG. Lines are tagged source: "user-code" and appear in the dashboard Monitoring tab and broods logs. DEBUG lines only show in history, never in a live tail.

The agent-hooks demo is a runnable example. For a Pancake human-handoff hook, see Pancake.