Hooks

Hooks reference

These are the lifecycle hooks this guide covers. The full set of wired hook names lives in the HOOKS constant. Expand a hook to see its Context API contract.

When several plugins register hooks for the same boundary, they chain: each hook sees the previous hook's changes, and the merged result flows into the next. The order is deterministic.

Resolution order

When multiple plugins define the same hook, they execute in a fixed order so the chain is predictable:

1. Built-in default plugins. Registered explicitly at startup. They always run first, so their context transformations are visible to every user plugin after them.
2. User plugins. Ordered by the plugin's original install date, the installedAt timestamp from the install-meta.json sidecar written at install time. Plugins installed earlier run first. Plugins without a sidecar fall back to the directory creation time and sort after dated ones.

Within a single plugin, hooks for the same name are not duplicated: each plugin contributes at most one hook per boundary. The chain is linear: the output of hook N is the input of hook N+1, and the final output is what the Assistant acts on.

Anatomy of a hook

Every hook has the same shape: it receives a typed context and either mutates it in place and returns nothing, or returns a partialcontext. A returned partial is merged onto the threaded context — only the keys it includes are overwritten, every other field is preserved — so a hook can edit just the subset of fields it cares about without re-specifying the rest. The runtime threads the merged context to the next plugin and then to the Assistant.

type PluginHookFn<TCtx> = (ctx: TCtx) => Promise<Partial<TCtx> | void>;

Because an omitted key means “keep the existing value”, every context field is required and uses | null rather than ? or | undefined: a present key always carries a concrete value, so a field absent from a returned partial is never ambiguous with one a hook meant to clear.

One hook per file, default-exported. The filename becomes the hook key, so a pre-model-call hook is hooks/pre-model-call.ts:

// hooks/pre-model-call.ts
import type { PreModelCallContext } from "@vellumai/plugin-api";

export default async function preModelCall(
  ctx: PreModelCallContext,
): Promise<void> {
  // Only touch the user-facing reply, not background or subagent calls.
  if (ctx.callSite !== "mainAgent") {
    return;
  }
  ctx.systemPrompt = (ctx.systemPrompt ?? "") + "\nBe concise.";
}

Context types and constants come from @vellumai/plugin-api, the only supported contract.

When should my assistant write a Hook?

Reach for a hook when you need to read or transform what flows through a turn at a fixed point in the loop, regardless of what the model decides. Hooks are unconditional: rewrite the prompt before the model sees it, route a call to a different model, truncate an oversized tool result, re-inject context after compaction. If the behavior has to happen every time the loop reaches that boundary, it is a hook.