Extensibility

Hooks

Run your own code at fixed points in a turn. Hooks let a plugin read or transform what flows through the Assistant without forking the core loop.

Plugins are in beta. The plugin API (@vellumai/plugin-api) is not yet stable and can change between releases. Pin the peerDependencies range your plugin declares, and expect breaking changes until we cut a 1.0. Hook names and context shapes can change with it.

A hook is a function that the Assistant calls at a known boundary in their lifecycle. The harness owns the loop, and your Assistant's code runs at named points along the way. Each hook lives in its own file under hooks/<name>.ts, and the filename is the hook name.

The hook lifecycle

The diagram below maps what we call the Agent Loop. The nodes are lifecycle events: the points in time a turn passes through. The connecting hooks are the places your code can run as the turn moves from one event to the next.

The Agent LoopA turn flows from the user prompt through a context check, model call, and model response to the assistant reply, with tool results and a compaction branch looping back. The hooks user-prompt-submit, pre-model-call, post-model-call, post-tool-use, and stop fire on the transitions. post-compact is drawn as a reserved branch off the compaction step that is not yet dispatched through the plugin chain.user-prompt-submitpost-tool-usepre-model-callpost-compactpost-model-calltool_usestopcontinueUser promptContext checkModel callModel responseAssistant replyCompactionTool result
Hook (fires on this transition)Control flowReserved (not yet dispatched)

The loop can iterate several times within a single user turn: every tool result returns to a fresh model call, and a stop hook can choose to continue rather than end the turn. Because of this, pre-model-call, post-model-call, and post-tool-use can each fire more than once per turn.

The Assistant Lifecycle

init and shutdown sit outside the loop. They bracket the whole session and fire once each: when the plugin is first registered, and when the Assistant tears it down. The Agent Loop runs each turn during the active session in between.

The Assistant LifecycleA plugin wakes, runs while the Run Server is up, then sleeps. The init and shutdown hooks fire once each on those boundaries. The Run Server exchanges conversations with the Agent Loop, which persists to the Workspace.initshutdownConversationspersistenceWakeRun ServerSleepAgent LoopWorkspace
Hook (fires on this transition)

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.

initPluginInitContext

When: Once, when the plugin is first registered (on boot or install).

Use it to: Validate config and credentials and open resources. Throwing aborts the plugin's load.

FieldTypeAccessDescription
configunknownRead-onlyParsed config for this plugin, validated against the manifest.
credentialsRecord<string, string>Read-onlyResolved credential values, keyed by the plugin's requiresCredential entries.
pluginStorageDirstringRead-onlyAbsolute path to the plugin's writable data directory, created during bootstrap.
assistantVersionstringRead-onlyAssistant semver, for defensive runtime checks.
loggerPluginLoggerRead-onlyPino-compatible logger scoped to the plugin.
user-prompt-submitUserPromptSubmitContext

When: Once per user turn, after messages are assembled and before the agent loop runs.

Use it to: Read or rewrite the message list the model is about to see.

FieldTypeAccessDescription
conversationIdstringRead-onlyConversation the prompt was submitted on.
userMessageIdstringRead-onlyPersisted id of the user message that triggered the turn.
requestIdstringRead-onlyStable id for the request driving this turn.
modelProfileKeystring | nullRead-onlyActive inference profile key, or null when unchanged since last announced.
isNonInteractivebooleanRead-onlyTrue when no human is present to answer clarifications (scheduled or headless runs).
promptstringRead-onlyResolved text of the user prompt, after slash-command expansion.
originalMessagesReadonlyArray<Message>Read-onlyThe user's original message list. Snapshot only, never mutate.
latestMessagesMessage[]MutableThe working list that flows into the agent loop. Mutate in place or replace via the return value.
loggerPluginLoggerRead-onlyLogger scoped to the current turn.
post-compactPostCompactContext

When: After the loop compacts a conversation mid-turn, before the turn resumes. It fires on a compaction event rather than a fixed turn boundary, so it sits off to the side of the loop.

Use it to: Re-apply context that compaction dropped (for example memory injections) onto the compacted history before the next model call.

Note: post-compact is reserved. The name lives in the HOOKS constant and the built-in re-injection runs on every compaction, but it is not yet dispatched through the plugin hook chain, and PostCompactContext is not yet exported from @vellumai/plugin-api. Treat it as the least stable part of this beta surface.

pre-model-callPreModelCallContext

When: Immediately before every provider call within a turn, including tool-result follow-ups.

Use it to: Edit the outbound request (for example the system prompt), or defer this turn's live output stream.

FieldTypeAccessDescription
conversationIdstringRead-onlyConversation the call belongs to.
callSite?LLMCallSiteRead-onlyWhich call site this serves (mainAgent for the user-facing reply). Self-gate on it before acting.
systemPromptstring | undefinedMutableThe system prompt about to be sent. Replace it to edit the request; guard the undefined case.
deferAssistantOutputbooleanMutableSet true to suppress the live token stream so a post-model-call hook can emit the final text instead.
loggerPluginLoggerRead-onlyLogger scoped to the current turn.
post-model-callPostModelCallContext

When: After each finalized assistant message, before it is persisted and streamed.

Use it to: Transform the text blocks of the reply. Leave tool_use and other non-text blocks intact.

FieldTypeAccessDescription
conversationIdstringRead-onlyConversation the message belongs to.
callSite?LLMCallSiteRead-onlyWhich call site this message serves. Self-gate before acting.
contentContentBlock[]MutableThe finalized message content. Transform text blocks and leave tool_use intact.
stopReasonstring | null | undefinedRead-onlyProvider-reported stop reason, when reported.
loggerPluginLoggerRead-onlyLogger scoped to the current turn.
post-tool-usePostToolUseContext

When: After each tool returns, before the result rejoins the history sent to the provider.

Use it to: Transform the tool result, for example truncating oversized output to fit the context window.

FieldTypeAccessDescription
conversationIdstringRead-onlyConversation the tool ran on.
toolResponseToolResultContentMutableThe tool result block. Mutate its content in place or replace the block.
messagesReadonlyArray<Message>Read-onlyHistory up to and including the assistant turn that issued the call. The result is not in it yet.
additionalContext?stringMutableExtra model-only guidance appended after the tool result, for example retry coaching.
maxInputTokensnumberRead-onlyThe model's context-window size in tokens, for deriving a character budget.
loggerPluginLoggerRead-onlyLogger scoped to the current turn.
stopStopContext

When: At the stop boundary, when the model returns a response with no tool calls.

Use it to: Decide whether to stop or continue. To continue, append a follow-up turn and the loop re-queries the model.

FieldTypeAccessDescription
conversationIdstringRead-onlyConversation the run belongs to.
messagesMessage[]MutableFull conversation history. Append a follow-up turn here when continuing.
responseContentReadonlyArray<ContentBlock>Read-onlyContent blocks of the assistant turn that triggered the stop (no tool_use).
stopReasonstring | null | undefinedRead-onlyProvider-reported stop reason (for example refusal, end_turn).
decisionStopDecisionMutableSeeded to 'stop'. Set it to 'continue' to force another loop iteration.
loggerPluginLoggerRead-onlyLogger scoped to the current turn.
shutdownPluginShutdownContext

When: Once, when the Assistant tears down the plugin (process exit, unload).

Use it to: Best-effort cleanup. Do not rely on it for critical writes; persist durably during normal operation instead.

FieldTypeAccessDescription
assistantVersionstringRead-onlyAssistant semver, for version-conditional cleanup.

When several plugins register hooks for the same boundary, they chain in registration order, each one seeing the previous plugin's changes. Built-in defaults register first, so they run ahead of your hooks.

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 new context. The runtime forwards whichever the chain settles on to the next plugin and then to the Assistant.

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

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.

The Personal AI you were promised

GET STARTED