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.
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
| Hook | Runs when | May return |
|---|---|---|
onStart | a run starts | system appends to the prompt. messages replaces the conversation for this run. |
onToolCall | before a tool runs | decision: "allow" | "deny", args to edit the input, denyReason |
onToolResult | after a tool returns | output replaces the result |
onFinish | the final answer is ready | output replaces the answer |
onStepFinish | each model step ends | nothing, observe only |
onError | the run fails | nothing, observe only |
onApproval | a tool waits for approval | nothing yet. Returning approve is not honored. |
onSubagentFinish | a subagent finishes | visibleResult replaces what the parent sees |
onMessageReceived | a chat message arrives | drop discards it, text rewrites it, metadata is stored with the message |
onMessageSending | a chat reply is about to be sent | drop 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,
onSubagentFinishand the reply'sonMessageSendingshare one state.onMessageReceived, delayed background replies and each subagent get their own. - A hook that throws keeps the state earlier hooks stored.
onErrorsees 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,eventand JavaScript built-ins. No imports, norequire, no Node modules, no variables from the surrounding file. Uploads that use them are rejected. ctx.fetchworks but blocks private and metadata addresses.ctx.configis a read-only summary of the agent:model(provider,modelId),harness,maxTurn, and the names intools,mcp,channels,skills,subagentsanddenyTools. 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.
onFinishchanges 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.logandinfolog at INFO,warnanderrorat their levels,debugat DEBUG. Lines are taggedsource: "user-code"and appear in the dashboard Monitoring tab andbroods 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.