@vellumai/plugin-api 0.8.12-dev.202606151838.c96914b → 0.8.12-dev.202606152157.b1ba560

package/index.d.ts

@@ -2770,8 +2770,11 @@ export declare interface PostCompactContext {
  *   the hook's result as the persisted and streamed message), and
  *   {@link stopReason} carries the provider's stop reason. Fires once per model
  *   call, including tool-bearing turns (a reply can carry both text and
- *   `tool_use`), so a hook should transform only the blocks it owns and leave
- *   others — notably `tool_use` — intact.
+ *   `tool_use`). A hook should leave blocks it does not own untouched, but it
+ *   may **append a `tool_use` block** to invoke a tool as if the model had
+ *   called it — the loop executes whatever the finalized content carries (see
+ *   {@link content}). This is the supported way for a plugin to drive a tool
+ *   (e.g. render a surface via `ui_show`) deterministically after a turn.
  * - **Provider rejection.** The call threw before any reply existed.
  *   {@link error} holds the rejection, {@link content} is empty, and
  *   {@link stopReason} is `null`. A hook that recognizes the rejection may
@@ -2795,8 +2798,17 @@ export declare interface PostModelCallContext {
     /** The call site this message serves — `"mainAgent"` for the user-facing reply; `null` when untagged. */
     readonly callSite: LLMCallSite | null;
     /**
-     * The finalized message content. Mutable — transform the text blocks and leave
-     * `tool_use` (and other non-text blocks) intact. Empty on a provider rejection.
+     * The finalized message content. Mutable, and the source of truth for both
+     * persistence and execution: the loop derives the turn's executable tool
+     * calls from this array *after* the hook chain runs. A hook may transform the
+     * text blocks, **append a `tool_use` block** to invoke a tool as if the model
+     * had called it (executed through the normal tool path — trust rules apply,
+     * and its result/surface is appended after any already-streamed text without
+     * discarding it), or drop a `tool_use` block to suppress a call. The host
+     * assigns an id to any appended `tool_use` block whose `id` is empty or
+     * collides. Empty on a provider rejection. Appended `tool_use` blocks are
+     * dropped on a truncated (max-tokens) turn, which short-circuits before the
+     * executor runs and so cannot pair a tool call with a result.
      */
     content: ContentBlock[];
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.8.12-dev.202606151838.c96914b",
+  "version": "0.8.12-dev.202606152157.b1ba560",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",