@vellumai/assistant 0.8.7 → 0.8.8

package/src/memory/v3/selector.ts

@@ -14,11 +14,18 @@
  * turn after turn. The trailing recent-context / current-message block changes
  * every turn and carries no breakpoint. This mirrors `./router.ts`.
  *
- * Recall-safe fallbacks. Like the router, the selector exists to widen recall,
- * so every failure degrades toward selecting MORE pages, never fewer:
- *   - omitted `ids` → select ALL members of the leaf,
- *   - missing/failed tool_use, provider unavailable, or any throw → ALL members.
- * Only an explicit empty `ids: []` returns nothing (deliberate abstention).
+ * Failure handling. A deliberate "select everything" and a model-call failure
+ * are different events with different outcomes:
+ *   - explicit `ids` → select exactly those pages,
+ *   - explicit empty `ids: []` → select nothing (deliberate abstention),
+ *   - omitted `ids` → select ALL members of the leaf (the recall-safe "this
+ *     whole leaf is relevant" signal, e.g. "give me all of X"); bounded to one
+ *     leaf, so unlike the router this stays a select-all,
+ *   - infrastructure failure (provider unavailable, a throw that survived the
+ *     provider's own retries, no usable `tool_use`, or a schema mismatch) →
+ *     select nothing after a short re-prompt retry, degrading to the
+ *     deterministic recall lanes (core, needle, carry-forward working set) the
+ *     orchestrator unions in regardless.
  */
 
 import { z } from "zod";
@@ -30,6 +37,7 @@ import {
 import type { Message, ToolDefinition } from "../../providers/types.js";
 import { getLogger } from "../../util/logger.js";
 import { mapLimit } from "../../util/map-limit.js";
+import { retryForResult } from "./llm-retry.js";
 import { cachedTextBlock } from "./provider-blocks.js";
 import { membersOf } from "./tree.js";
 import type { LeafPath, LeafTree, Slug, TurnContext } from "./types.js";
@@ -55,11 +63,13 @@ const SelectPagesSchema = z.object({
 const SELECT_PAGES_TOOL: ToolDefinition = {
   name: SELECT_PAGES_TOOL_NAME,
   description:
-    "Select the pages in this leaf whose content is relevant or useful for " +
-    "the next reply. Lean toward inclusion — a missed relevant page is a " +
-    "worse error than an unused one. Pass `pinned_ids` for pages the " +
-    "conversation is centrally about. Omit `ids` entirely to select every " +
-    "page; return `[]` only when none of the pages could possibly help.",
+    "Select the pages in this leaf whose content the reply would directly " +
+    "draw on. Be selective — prefer a few precisely-relevant pages over many " +
+    "loosely-related ones; a leaf opened on a weak signal may yield none. " +
+    "Pass `pinned_ids` for pages the conversation is centrally about. Omit " +
+    "`ids` only as a recall-safe fallback when you cannot judge the leaf " +
+    "(selects every page); return `[]` when pages are present but none are " +
+    "directly relevant.",
   input_schema: {
     type: "object",
     properties: {
@@ -75,11 +85,13 @@ const SELECT_PAGES_TOOL: ToolDefinition = {
   },
 };
 
-const SYSTEM_PROMPT = `This leaf of the topic tree is potentially relevant to the conversation. Select the pages whose content is relevant or useful for responding.
+const SYSTEM_PROMPT = `This leaf of the topic tree is potentially relevant to the conversation. Select ONLY the pages whose content the reply to THIS message would directly draw on.
 
-Be inclusive — include frame and affect matches, not just literal-topic matches. A page that shares the conversation's mode or register can be as useful as one that names the same entity. Missing a relevant page is a worse error than selecting an unused one.
+Be selective: exclude pages that are merely topically adjacent, part of the ever-present background, or only loosely related. Most opened leaves should contribute a few precisely-relevant pages, not most of their contents — a leaf opened on a weak signal may yield none.
 
-If the conversation is centrally ABOUT a page (rather than only peripherally relevant to it), mark that page as pinned. Call \`select_pages\` with the chosen IDs. Omit \`ids\` to select every page; return \`[]\` only when none of the pages could possibly help.`;
+A page can also be directly relevant because of the current situation — the date or the live scratchpad — not only the message: keep a page the situation makes pertinent (e.g. a person whose anniversary is today).
+
+If the conversation is centrally ABOUT a page (rather than only peripherally relevant to it), mark that page as pinned. Call \`select_pages\` with the chosen IDs. Omit \`ids\` only as a recall-safe fallback when you cannot judge the leaf (selects every page); return \`[]\` when the pages are present but none are directly relevant.`;
 
 /**
  * Render the STATIC numbered `<pages>` block for a leaf from its member slugs.
@@ -103,8 +115,10 @@ async function renderPagesBlock(
 /**
  * Run the L2 selector for a single opened leaf. Returns the pages to inject.
  *
- * Recall-safe: any failure to obtain an explicit selection returns ALL members
- * of the leaf. Only an explicit empty `ids` array returns no pages.
+ * An omitted `ids` selects ALL members (the recall-safe "whole leaf is
+ * relevant" signal); an explicit `[]` selects none; an infrastructure failure
+ * (after a short re-prompt retry) selects none, degrading to the deterministic
+ * recall lanes the orchestrator unions in.
  */
 export async function selectFromLeaf(
   leaf: LeafPath,
@@ -120,8 +134,11 @@ export async function selectFromLeaf(
 
   const provider = await getConfiguredProvider("memoryV3SelectL2");
   if (!provider) {
-    log.warn({ leaf }, "memoryV3SelectL2 provider unavailable; selecting all");
-    return allMembers();
+    log.warn(
+      { leaf },
+      "L2 selector provider unavailable; degrading to deterministic lanes",
+    );
+    return [];
   }
 
   const userMsg: Message = {
@@ -134,15 +151,21 @@ export async function selectFromLeaf(
       {
         type: "text",
         text:
+          (turn.situationalContext
+            ? `<situation>${turn.situationalContext}</situation>\n`
+            : "") +
           `<recent_context>${turn.recentContext}</recent_context>\n` +
           `<current_message>${turn.currentMessage}</current_message>`,
       },
     ],
   };
 
-  let response;
-  try {
-    response = await provider.sendMessage([userMsg], {
+  // One forced-tool call, retried a few times so a transient malformed response
+  // (no usable tool_use, or tool input that fails the schema) re-prompts before
+  // we give up. `null` from an attempt means "unusable, retry"; the provider
+  // layer already backs off transient throws, so this loop adds no delay.
+  const parsed = await retryForResult(async () => {
+    const response = await provider.sendMessage([userMsg], {
       tools: [SELECT_PAGES_TOOL],
       systemPrompt: SYSTEM_PROMPT,
       config: {
@@ -150,39 +173,31 @@ export async function selectFromLeaf(
         tool_choice: { type: "tool" as const, name: SELECT_PAGES_TOOL_NAME },
       },
     });
-  } catch (err) {
-    log.warn({ err, leaf }, "L2 selector call threw; selecting all");
-    return allMembers();
-  }
-
-  const toolBlock = extractToolUse(response);
-  if (!toolBlock || toolBlock.name !== SELECT_PAGES_TOOL_NAME) {
-    log.warn(
-      { stopReason: response.stopReason, leaf },
-      "L2 selector returned no select_pages tool_use; selecting all",
-    );
-    return allMembers();
-  }
+    const toolBlock = extractToolUse(response);
+    if (!toolBlock || toolBlock.name !== SELECT_PAGES_TOOL_NAME) return null;
+    const result = SelectPagesSchema.safeParse(toolBlock.input);
+    return result.success ? result.data : null;
+  });
 
-  const parsed = SelectPagesSchema.safeParse(toolBlock.input);
-  if (!parsed.success) {
+  if (parsed === null) {
     log.warn(
-      { error: parsed.error.message, leaf },
-      "L2 selector tool input did not match schema; selecting all",
+      { leaf },
+      "L2 selector could not obtain a selection after retries; degrading to deterministic lanes",
     );
-    return allMembers();
+    return [];
   }
 
-  // Omitted `ids` is the recall-safe "select everything" signal.
-  if (parsed.data.ids === undefined) return allMembers();
+  // Omitted `ids` is the recall-safe "this whole leaf is relevant" signal.
+  // Bounded to one leaf, so it stays a select-all (unlike the L1 router).
+  if (parsed.ids === undefined) return allMembers();
 
-  const pinned = new Set(parsed.data.pinned_ids ?? []);
+  const pinned = new Set(parsed.pinned_ids ?? []);
 
   // Map 1-based IDs back to member slugs, dropping out-of-range IDs without
   // throwing. De-duplicate while preserving model-returned order.
   const seen = new Set<number>();
   const selected: SelectedPage[] = [];
-  for (const id of parsed.data.ids) {
+  for (const id of parsed.ids) {
     if (id < 1 || id > members.length || seen.has(id)) continue;
     seen.add(id);
     selected.push({ slug: members[id - 1]!, pinned: pinned.has(id) });

package/src/memory/v3/shadow-plugin.ts

@@ -1,7 +1,7 @@
 /**
- * Memory v3 — flag-gated shadow/live plugin.
+ * Memory v3 — flag-gated shadow/live injector.
  *
- * Registered as an {@link Injector} that runs the v3 orchestrator each turn and
+ * An {@link Injector} that runs the v3 orchestrator each turn and
  * records its selection set to `memory_v3_selections`. Two flags gate its
  * injection behavior:
  *
@@ -29,6 +29,8 @@
  * empty selection) falls back to v2 memory rather than dropping all memory.
  */
 
+import { existsSync, readFileSync } from "node:fs";
+
 import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
 import { getConfig } from "../../config/loader.js";
 import type { AssistantConfig } from "../../config/schema.js";
@@ -38,11 +40,14 @@ import { stringifyMessageContent } from "../../memory/message-content.js";
 import {
   type InjectionBlock,
   type Injector,
-  type Plugin,
   type TurnContext as PluginTurnContext,
 } from "../../plugins/types.js";
 import { getLogger } from "../../util/logger.js";
-import { getWorkspaceDir } from "../../util/platform.js";
+import {
+  getWorkspaceDir,
+  getWorkspacePromptPath,
+} from "../../util/platform.js";
+import { stripCommentLines } from "../../util/strip-comment-lines.js";
 import { getPageIndex } from "../v2/page-index.js";
 import { injectCapabilitiesLeaf, isCapabilitySlug } from "./capabilities.js";
 import { loadCore } from "./core.js";
@@ -165,10 +170,42 @@ function getLanes(config: AssistantConfig): Promise<ShadowLanes> {
   return lanesPromise;
 }
 
+/**
+ * Read the live NOW.md scratchpad (the user's short "what's salient right now"
+ * file), stripped of its comment lines. Mirrors `readNowScratchpad` but reads
+ * through the light platform / strip utilities directly, keeping the v3
+ * plugin's load (and its test) free of heavier module graphs. Returns `null`
+ * when absent, empty, or unreadable.
+ */
+function readNowContext(): string | null {
+  const nowPath = getWorkspacePromptPath("NOW.md");
+  if (!existsSync(nowPath)) return null;
+  try {
+    const stripped = stripCommentLines(readFileSync(nowPath, "utf-8")).trim();
+    return stripped.length > 0 ? stripped : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compose the situational signal threaded into L1 routing and L2 selection: the
+ * current date plus the live NOW.md scratchpad. The date alone is a weak signal,
+ * but together with the scratchpad it lets retrieval surface a leaf the message
+ * never names (e.g. an anniversary that falls today). Always returns at least
+ * the date line — this mirrors the `c_now`/NOW.md signal the v2 retriever uses.
+ */
+function buildSituationalContext(): string {
+  const now = readNowContext();
+  const today = `Today is ${new Date().toDateString()}.`;
+  return now ? `${today}\n\n${now}` : today;
+}
+
 /**
  * Build a v3 {@link TurnContext} from the conversation's persisted messages.
  * `currentMessage` is the latest user message; `recentContext` is the tail of
- * the recent transcript. Returns `null` when there is no user message to route
+ * the recent transcript; `situationalContext` carries the current date and the
+ * live NOW.md scratchpad. Returns `null` when there is no user message to route
  * on (nothing to shadow this turn).
  */
 function buildShadowTurn(
@@ -198,6 +235,7 @@ function buildShadowTurn(
     turnNumber: turnIndex,
     currentMessage,
     recentContext,
+    situationalContext: buildSituationalContext(),
   };
 }
 
@@ -280,13 +318,15 @@ async function observeTurn(
     const turn = buildShadowTurn(conversationId, turnIndex);
     if (!turn) return null;
 
-    const lanes = await getLanes(getConfig());
+    const cfg = getConfig();
+    const lanes = await getLanes(cfg);
     const result = await orchestrate(turn, {
       tree: lanes.tree,
       core: lanes.core,
       needle: lanes.needle,
       workingSet: lanes.workingSet,
       pageSummary,
+      l2Concurrency: cfg.memory.v3.l2Concurrency,
     });
 
     const rows = attributeSelections(lanes.tree, lanes.core, result);
@@ -329,7 +369,7 @@ export async function runShadowObservation(
  * (failure or empty selection) falls back to v2 memory rather than dropping all
  * memory.
  */
-const memoryV3Injector: Injector = {
+export const memoryV3Injector: Injector = {
   name: "memory-v3-shadow",
   // High order so it sorts last; the live `<memory>` block uses the
   // after-memory-prefix placement so it lands at the memory boundary regardless
@@ -369,11 +409,3 @@ const memoryV3Injector: Injector = {
     }
   },
 };
-
-export const memoryV3ShadowPlugin: Plugin = {
-  manifest: {
-    name: "memory-v3-shadow",
-    version: "0.0.1",
-  },
-  injectors: [memoryV3Injector],
-};

package/src/memory/v3/types.ts

@@ -46,6 +46,14 @@ export interface TurnContext {
   turnNumber: number;
   currentMessage: string;
   recentContext: string;
+  /**
+   * Optional situational signal — the current date plus the live NOW.md
+   * scratchpad — so a leaf or page can be routed/selected on a date or
+   * live-state cue the message itself never names (e.g. a person whose
+   * anniversary is today). Omitted when unavailable; the router and selector
+   * render nothing for an undefined value.
+   */
+  situationalContext?: string;
 }
 
 export type SelectionSource = "l1+l2" | "core+l2" | "needle" | "carry-forward";

package/src/notifications/conversation-pairing.ts

@@ -21,7 +21,6 @@
 import type { ConversationStrategy } from "../channels/config.js";
 import { getConversationStrategy } from "../channels/config.js";
 import type { ChannelId } from "../channels/types.js";
-import { isHomePageEnabled } from "../home/feature-gate.js";
 import {
   addMessage,
   createConversation,
@@ -120,20 +119,14 @@ export async function pairDeliveryWithConversation(
     // Passive vellum notifications surface via the home feed alone and link
     // back to the originating conversation via `signal.sourceContextId`.
     // Materializing a fresh per-notification conversation just to host the
-    // seed message leaves a graveyard entry in the sidebar; skip it unless
-    // the producer opted in via `requiresConversation` or the decision engine
-    // requested explicit reuse of a target conversation.
-    //
-    // Gated on `home-page`: the home feed is the surface that hosts passive
-    // notifications, so when the flag is off there is nowhere for them to
-    // land — fall through and create a conversation (the pre-home-feed
-    // behavior) to preserve the notification's only surface.
-    if (
-      strategy === "start_new_conversation" &&
-      !signal.requiresConversation &&
-      conversationAction?.action !== "reuse_existing" &&
-      isHomePageEnabled()
-    ) {
+    // seed message leaves a graveyard entry in the sidebar; skip it
+    // unconditionally when the producer did not opt in via
+    // `requiresConversation`. The decision engine's `reuse_existing` hint is
+    // also ignored here: even a successful reuse would append a seed message
+    // to a conversation that the user didn't ask for, and a failed reuse
+    // (stale target / source mismatch) falls through to `createConversation`
+    // — producing exactly the graveyard entry we want to avoid.
+    if (strategy === "start_new_conversation" && !signal.requiresConversation) {
       return {
         conversationId: null,
         messageId: null,

package/src/notifications/decision-engine.ts

@@ -149,8 +149,8 @@ function buildSystemPrompt(
     `  - Avoid meta-send phrasing (e.g. "I'd like to send a notification", "May I go ahead with that?"). Write the recipient-facing message directly.`,
     `  - Avoid intermediary-instruction phrasing like "consider telling the guardian", "ask the recipient to", or "the assistant should remind them". Rewrite it as final copy the recipient can act on directly.`,
     `  - For telegram: 1-2 concise sentences.`,
-    `- \`conversationSeedMessage\` is the opening message in the internal notification conversation — it can be richer and more contextual.`,
-    `  - For vellum (desktop): 2-4 short sentences with useful context and clear next step if action is required.`,
+    `- \`conversationSeedMessage\` is the opening message in the internal notification conversation and also the expanded detail shown in the home feed. It should be richer and more contextual than the popup body.`,
+    `  - For vellum (desktop): use structured markdown for readability. Break content into bullet points, numbered lists, or short sections with **bold** labels. Avoid long unbroken paragraphs — scan-friendly formatting is preferred.`,
     `  - Never dump raw JSON. Include only human-readable context.`,
     ``,
     `Conversation reuse guidelines:`,
@@ -838,7 +838,10 @@ export async function evaluateSignal(
       selectedChannels,
       reasoningSummary: "assistant_tool pass-through",
       renderedCopy: Object.fromEntries(
-        availableChannels.map((ch) => [ch, { title, body }]),
+        availableChannels.map((ch) => [
+          ch,
+          { title, body, conversationSeedMessage: body },
+        ]),
       ) as NotificationDecision["renderedCopy"],
       conversationActions: Object.fromEntries(
         availableChannels.map((ch) => [ch, { action: "start_new" as const }]),

package/src/notifications/home-feed-side-effect.ts

@@ -21,6 +21,7 @@ import { appendFeedItem } from "../home/feed-writer.js";
 import { getConversation } from "../memory/conversation-crud.js";
 import { isBackgroundConversationType } from "../memory/conversation-types.js";
 import { getLogger } from "../util/logger.js";
+import { isConversationSeedSane } from "./conversation-seed-composer.js";
 import type { NotificationSignal } from "./signal.js";
 import type { NotificationDecision, RenderedChannelCopy } from "./types.js";
 
@@ -77,8 +78,18 @@ export async function writeHomeFeedItemForSignal(
   // against `summary` in the row. Leave undefined when absent; renderers
   // fall back to `summary`.
   const resolvedTitle = payloadTitle?.trim() || undefined;
+  // Prefer conversationSeedMessage over body for the home feed: the seed
+  // message is richer and may contain structured markdown (lists, headers,
+  // bold) that the detail panel renders. The popup-oriented `body` is
+  // intentionally short (≤ 2 sentences) and loses formatting.
+  const seedCandidate = renderedCopy?.conversationSeedMessage;
   const resolvedSummary =
-    renderedCopy?.body?.trim() || payloadBody?.trim() || "";
+    (isConversationSeedSane(seedCandidate)
+      ? seedCandidate.trim()
+      : undefined) ||
+    renderedCopy?.body?.trim() ||
+    payloadBody?.trim() ||
+    "";
   if (!resolvedSummary) {
     log.warn(
       { signalId: signal.signalId, sourceEventName: signal.sourceEventName },

package/src/permissions/prompter.ts

@@ -118,6 +118,10 @@ export class PermissionPrompter {
             label: o.label,
             scope: o.scope,
           })),
+          directoryScopeOptions: directoryScopeOptions?.map((o) => ({
+            label: o.label,
+            scope: o.scope,
+          })),
           persistentDecisionsAllowed: persistentDecisionsAllowed ?? true,
         },
         rpcResolve: resolve as (value: unknown) => void,

package/src/plugin-api/constants.ts

@@ -20,6 +20,10 @@ export const HOOKS = {
   SHUTDOWN: "shutdown",
   /** Fires once per user turn, immediately before the agent loop receives `runMessages`. */
   USER_PROMPT_SUBMIT: "user-prompt-submit",
+  /** Fires once per tool result, after the tool returns and before the result is sent to the provider. */
+  POST_TOOL_USE: "post-tool-use",
+  /** Fires when the model yields a response with no tool calls — the run's stop boundary. Decides whether to stop or continue with a follow-up turn. */
+  STOP: "stop",
 } as const;
 
 /** Union of every hook name declared in {@link HOOKS}. */

package/src/plugin-api/index.ts

@@ -24,6 +24,10 @@
  * - {@link PluginShutdownContext} — passed to `shutdown` hook at teardown
  * - {@link UserPromptSubmitContext} — passed to `user-prompt-submit` hook,
  *   fired immediately before the agent loop receives a user's prompt
+ * - {@link PostToolUseContext} — passed to `post-tool-use` hook, fired once
+ *   per tool result before it joins the provider-bound history
+ * - {@link StopContext} — passed to `stop` hook, fired when the model yields
+ *   a response with no tool calls
  * - {@link PluginHookFn} — signature every lifecycle hook implements
  * - {@link PluginLogger} — pino-compatible logger shape on the contexts
  * - {@link ToolDefinition} — author-facing tool spec (default-export shape
@@ -31,7 +35,7 @@
  * - {@link ToolContext} — passed to a plugin tool's `execute` method
  * - {@link ToolExecutionResult} — return shape of a plugin tool's `execute`
  *
- * Pipeline-argument types (`LLMCallArgs`, `MemoryArgs`, etc.) currently
+ * Pipeline-argument types (`MemoryArgs`, `CompactionArgs`, etc.) currently
  * live in `assistant/src/plugins/types.ts` and have not yet migrated into
  * this package. A follow-up PR will move them into this surface as the
  * per-pipeline schemas stabilize.
@@ -44,6 +48,9 @@ export type {
   PluginInitContext,
   PluginLogger,
   PluginShutdownContext,
+  PostToolUseContext,
+  StopContext,
+  StopDecision,
   ToolContext,
   ToolDefinition,
   ToolExecutionResult,

package/src/plugin-api/types.ts

@@ -4,7 +4,11 @@
  * removing is breaking and gated on a major bump.
  */
 
-import type { Message } from "../providers/types.js";
+import type {
+  ContentBlock,
+  Message,
+  ToolResultContent,
+} from "../providers/types.js";
 
 export type {
   ToolContext,
@@ -47,6 +51,8 @@ export interface PluginLogger {
  *   - `init` — {@link PluginInitContext}
  *   - `shutdown` — {@link PluginShutdownContext}
  *   - `user-prompt-submit` — {@link UserPromptSubmitContext}
+ *   - `post-tool-use` — {@link PostToolUseContext}
+ *   - `stop` — {@link StopContext}
  */
 export type PluginHookFn<TCtx = unknown> = (ctx: TCtx) => Promise<TCtx | void>;
 
@@ -121,6 +127,16 @@ export interface PluginShutdownContext {
 export interface UserPromptSubmitContext {
   /** Conversation ID the user prompt was submitted on. */
   readonly conversationId: string;
+  /**
+   * The text of the user prompt that triggered this turn — the resolved
+   * user message (after slash-command expansion), independent of any
+   * internal rewriting applied to the message that flows into the model.
+   * Mirrors the `prompt` field Claude Code / Codex pass to their
+   * `UserPromptSubmit` hooks, so hooks that key off the submitted text
+   * (e.g. title generation) read it directly rather than reconstructing
+   * it from the message arrays.
+   */
+  readonly prompt: string;
   /**
    * The user's original message list, immutable for the hook. Plugins
    * may snapshot or compare against this but MUST NOT mutate it.
@@ -138,3 +154,137 @@ export interface UserPromptSubmitContext {
    */
   readonly logger: PluginLogger;
 }
+
+// ─── Post-tool-use hook context ──────────────────────────────────────────────
+
+/**
+ * Context passed to the `post-tool-use` hook. Fires once per tool result —
+ * after the tool returns and before the result is appended to the message
+ * history sent to the provider. With several tools dispatched in a single
+ * turn, the hook fires once per result, in tool-use order.
+ *
+ * The hook may transform the result either by mutating `toolResponse` in
+ * place (e.g. reassigning `toolResponse.content`) or by returning a new
+ * context with a fresh `toolResponse` — see {@link PluginHookFn}'s
+ * polymorphic return shape. The daemon threads the final `toolResponse`
+ * into the provider-bound history.
+ *
+ * Multiple plugins' hooks chain in registration order — each plugin's hook
+ * sees the previous plugin's mutations. The default tool-result-truncate
+ * plugin contributes a hook here that tail-drops oversized output to fit the
+ * model's context window; the default tool-error plugin sets
+ * {@link additionalContext} with retry coaching for failed results. User hooks
+ * can swap in a smarter strategy (e.g. a summarizer) or observe results for
+ * side effects.
+ */
+export interface PostToolUseContext {
+  /** Conversation ID the tool ran on. */
+  readonly conversationId: string;
+  /**
+   * The tool result block. Plugins may mutate its `content` in place or
+   * replace the block by returning a new context.
+   */
+  toolResponse: ToolResultContent;
+  /**
+   * Conversation history up to and including the assistant turn that issued
+   * this tool call. The current result is not in it yet — it lives in
+   * {@link toolResponse}. A hook reasoning about prior tool outcomes (e.g.
+   * how many times a tool has failed in a row) derives that from the history
+   * content rather than a precomputed counter, so the signal survives mid-run
+   * compaction rewriting the array. Read-only: hooks transform the result via
+   * {@link toolResponse}, not by mutating history.
+   */
+  readonly messages: ReadonlyArray<Message>;
+  /**
+   * Extra guidance for the model that is not part of the tool's output. A hook
+   * sets this to surface provider-only context — e.g. retry coaching for a
+   * failed result — and the daemon appends it to the provider-bound history as
+   * a separate block *after* emitting the tool_result, so it reaches the model
+   * without polluting the client-facing or persisted tool output. Mirrors
+   * Claude Code's PostToolUse `hookSpecificOutput.additionalContext` and the
+   * singular of Codex's `additional_contexts`. Unset means no extra context.
+   */
+  additionalContext?: string;
+  /**
+   * The model's context-window size in tokens. Plugins derive their own
+   * character budget from this (e.g. a share of the window) rather than
+   * receiving a precomputed limit.
+   */
+  readonly maxInputTokens: number;
+  /**
+   * Logger scoped to the current turn. The same instance is shared by
+   * every hook in the chain, so plugins should tag their structured log
+   * fields (e.g. `{ plugin: "<name>" }`) for attribution.
+   */
+  readonly logger: PluginLogger;
+}
+
+// ─── Stop hook context ───────────────────────────────────────────────────────
+
+/**
+ * Binary outcome of the `stop` hook. The agent loop seeds it to `"stop"`
+ * and acts on the value the chain settles on:
+ *
+ * - `"stop"`     — let the turn end; the loop yields the assistant response
+ *                  to the user. This is the default.
+ * - `"continue"` — re-query the model. The hook is responsible for appending
+ *                  the follow-up turn it wants the model to see to
+ *                  {@link StopContext.messages} before returning.
+ *
+ * To abort with an error a hook should throw — the loop's error handler
+ * surfaces it. There is intentionally no error decision value.
+ */
+export type StopDecision = "continue" | "stop";
+
+/**
+ * Context passed to the `stop` hook. Fires when the model yields a response
+ * with no tool calls — the run's stop boundary, where the loop is about to
+ * hand the turn back to the user. The default empty-response plugin uses it
+ * to re-query the model when a turn came back empty or as a provider refusal.
+ *
+ * The hook decides the outcome by setting {@link decision}. When it sets
+ * `"continue"` it must also append the follow-up turn (e.g. a nudge `user`
+ * message) to {@link messages}; the loop threads those messages into the next
+ * iteration. {@link messages} is the full conversation history, carried back
+ * verbatim. A hook that needs to reason about just the current response cycle
+ * (e.g. whether an earlier turn already delivered visible text) derives that
+ * boundary from the history itself — the messages after the last genuine user
+ * prompt — rather than an index, since mid-run compaction can rewrite the
+ * array.
+ *
+ * Multiple plugins' hooks chain in registration order — each sees the
+ * previous hook's `decision` and `messages` mutations.
+ */
+export interface StopContext {
+  /** Conversation ID the run belongs to. */
+  readonly conversationId: string;
+  /**
+   * Full conversation history: the inbound conversation followed by every
+   * message produced this run. A hook that sets `decision` to `"continue"`
+   * appends its follow-up turn here; the loop carries the result into the
+   * next iteration.
+   */
+  messages: Message[];
+  /**
+   * Content blocks of the assistant turn that triggered the stop. Guaranteed
+   * to contain no `tool_use` blocks — the hook only fires at the boundary
+   * where the model stopped requesting tools.
+   */
+  readonly responseContent: ReadonlyArray<ContentBlock>;
+  /**
+   * Provider-reported stop reason for the assistant turn (e.g. `"refusal"`,
+   * `"end_turn"`). `null`/`undefined` when the provider didn't report one.
+   */
+  readonly stopReason: string | null | undefined;
+  /**
+   * Seeded to `"stop"`. A hook sets it to `"continue"` to force another loop
+   * iteration; later hooks in the chain may override it.
+   */
+  decision: StopDecision;
+  /**
+   * Logger scoped to the current turn. The same instance is shared by
+   * every hook in the chain, so plugins should tag their structured log
+   * fields (e.g. `{ plugin: "<name>" }`) for attribution.
+   */
+  readonly logger: PluginLogger;
+}