@vellumai/assistant 0.10.2-dev.202606251104.36cd100 → 0.10.2-dev.202606251257.2eba8a4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.10.2-dev.202606251104.36cd100",
+  "version": "0.10.2-dev.202606251257.2eba8a4",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/plugin-bootstrap.test.ts

@@ -2,7 +2,7 @@
  * Tests for plugin bootstrap (PR 14).
  *
  * Covers:
- * - A noop `init()` fires with a valid `PluginInitContext` that exposes every
+ * - A noop `init()` fires with a valid `InitContext` that exposes every
  *   documented field.
  * - Version-mismatch registration fails with an error that names the plugin
  *   (the registry enforces this at `registerPlugin` time, so bootstrap never
@@ -29,7 +29,7 @@ import {
   registerPlugin,
   resetPluginRegistryForTests,
 } from "../plugins/registry.js";
-import { type Plugin, type PluginInitContext } from "../plugins/types.js";
+import { type InitContext, type Plugin } from "../plugins/types.js";
 import { APP_VERSION } from "../version.js";
 import { setOverridesForTesting } from "./feature-flag-test-helpers.js";
 
@@ -51,7 +51,7 @@ function buildPlugin(
   name: string,
   extras: Partial<Omit<Plugin, "manifest" | "hooks">> & {
     hooks?: Plugin["hooks"];
-    init?: (ctx: PluginInitContext) => Promise<void>;
+    init?: (ctx: InitContext) => Promise<void>;
     onShutdown?: () => Promise<void>;
   } = {},
   options: {
@@ -98,8 +98,8 @@ describe("plugin bootstrap", () => {
     await rm(TEST_WORKSPACE_DIR, { recursive: true, force: true });
   });
 
-  test("noop plugin: init fires with a fully-populated PluginInitContext", async () => {
-    let received: PluginInitContext | undefined;
+  test("noop plugin: init fires with a fully-populated InitContext", async () => {
+    let received: InitContext | undefined;
     const plugin: Plugin = buildPlugin("alpha", {
       async init(ctx) {
         received = ctx;

package/src/__tests__/plugin-route-contribution.test.ts

@@ -38,7 +38,7 @@ import {
   registerPlugin,
   resetPluginRegistryForTests,
 } from "../plugins/registry.js";
-import type { Plugin, PluginInitContext } from "../plugins/types.js";
+import type { InitContext, Plugin } from "../plugins/types.js";
 import {
   matchSkillRoute,
   resetSkillRoutesForTests,
@@ -64,7 +64,7 @@ function buildPlugin(
   name: string,
   extras: Partial<Omit<Plugin, "manifest" | "hooks">> & {
     hooks?: Plugin["hooks"];
-    init?: (ctx: PluginInitContext) => Promise<void>;
+    init?: (ctx: InitContext) => Promise<void>;
     onShutdown?: () => Promise<void>;
   } = {},
 ): Plugin {

package/src/__tests__/plugin-tool-contribution.test.ts

@@ -33,7 +33,7 @@ import {
   registerPlugin,
   resetPluginRegistryForTests,
 } from "../plugins/registry.js";
-import type { Plugin, PluginInitContext } from "../plugins/types.js";
+import type { InitContext, Plugin } from "../plugins/types.js";
 import {
   __clearRegistryForTesting,
   __resetRegistryForTesting,
@@ -82,7 +82,7 @@ function buildPlugin(
   name: string,
   extras: Partial<Omit<Plugin, "manifest" | "hooks">> & {
     hooks?: Plugin["hooks"];
-    init?: (ctx: PluginInitContext) => Promise<void>;
+    init?: (ctx: InitContext) => Promise<void>;
     onShutdown?: () => Promise<void>;
   } = {},
 ): Plugin {

package/src/__tests__/plugin-types.test.ts

@@ -13,9 +13,9 @@ import { describe, expect, test } from "bun:test";
 import type { TrustContext } from "../daemon/trust-context.js";
 import { RiskLevel } from "../permissions/types.js";
 import {
+  type InitContext,
   type Plugin,
   PluginExecutionError,
-  type PluginInitContext,
   type PluginManifest,
   type TurnContext,
 } from "../plugins/types.js";
@@ -57,7 +57,7 @@ describe("plugin core types", () => {
     const plugin = {
       manifest,
       hooks: {
-        async init(ctx: PluginInitContext) {
+        async init(ctx: InitContext) {
           // Touch every field so refactors that rename any of them break here.
           void ctx.config;
           void ctx.logger;

package/src/daemon/external-plugins-bootstrap.ts

@@ -24,7 +24,7 @@
  *    (Zod schemas with `.parse()` are supported; anything else is passed
  *    through untouched).
  * 5. Creates `<workspaceDir>/plugins-data/<plugin>/` on demand for per-plugin
- *    writable state and exposes it via {@link PluginInitContext.pluginStorageDir}.
+ *    writable state and exposes it via {@link InitContext.pluginStorageDir}.
  * 6. For each surviving plugin, registers its contributed tools and routes
  *    into their global registries via {@link registerPluginTools} and
  *    {@link registerSkillRoute}. Contributions land BEFORE `init()` so
@@ -64,7 +64,7 @@ import { getRegisteredPlugins, unregisterPlugin } from "../plugins/registry.js";
 import {
   type Plugin,
   PluginExecutionError,
-  type PluginShutdownContext,
+  type ShutdownContext,
 } from "../plugins/types.js";
 import { loadUserPlugins } from "../plugins/user-loader.js";
 import {
@@ -222,8 +222,8 @@ export async function bootstrapPlugins(): Promise<void> {
   // Shutdown context is identical for every plugin in this boot — construct
   // once and reuse across the per-plugin teardown and the normal shutdown
   // hook below. Only `assistantVersion` is exposed today; future additions
-  // live on {@link PluginShutdownContext}.
-  const shutdownContext: PluginShutdownContext = {
+  // live on {@link ShutdownContext}.
+  const shutdownContext: ShutdownContext = {
     assistantVersion: APP_VERSION,
   };
 
@@ -407,7 +407,7 @@ async function initializePlugin(
 async function teardownPlugin(
   active: ActivePlugin,
   reason: string,
-  shutdownContext: PluginShutdownContext,
+  shutdownContext: ShutdownContext,
 ): Promise<void> {
   const { plugin, routeHandles } = active;
   const name = plugin.manifest.name;

package/src/hooks/hook-loader.ts

@@ -25,9 +25,9 @@ import { join } from "node:path";
 import { getConfig } from "../config/loader.js";
 import { HOOKS } from "../plugin-api/constants.js";
 import type {
-  PluginHookFn,
-  PluginInitContext,
-  PluginShutdownContext,
+  HookFunction,
+  InitContext,
+  ShutdownContext,
 } from "../plugin-api/types.js";
 import { listSurfaceDir } from "../plugins/external-plugin-loader.js";
 import { getMtime, importWithTimeout } from "../plugins/surface-import.js";
@@ -53,7 +53,7 @@ export const WORKSPACE_HOOKS_OWNER = "__workspace__";
  * mtime changes, the hook is re-imported and the entry is replaced.
  */
 interface CachedHook {
-  readonly hook: PluginHookFn;
+  readonly hook: HookFunction;
   /** mtimeMs of the source file this hook was imported from. */
   readonly sourceMtime: number;
 }
@@ -83,7 +83,7 @@ async function resolveCachedHook<TCtx>(
   ownerName: string,
   hookName: string,
   filePath: string,
-): Promise<PluginHookFn<TCtx> | undefined> {
+): Promise<HookFunction<TCtx> | undefined> {
   const key = hookKey(ownerName, hookName);
   const currentMtime = getMtime(filePath);
 
@@ -94,7 +94,7 @@ async function resolveCachedHook<TCtx>(
     cached.sourceMtime === currentMtime &&
     currentMtime > 0
   ) {
-    return cached.hook as PluginHookFn<TCtx>;
+    return cached.hook as HookFunction<TCtx>;
   }
 
   // Cache miss — re-import.
@@ -105,7 +105,7 @@ async function resolveCachedHook<TCtx>(
   }
 
   try {
-    const hook = await importWithTimeout<PluginHookFn>(filePath);
+    const hook = await importWithTimeout<HookFunction>(filePath);
     if (hook === undefined || typeof hook !== "function") {
       log.error(
         { plugin: ownerName, hook: hookName, path: filePath },
@@ -114,7 +114,7 @@ async function resolveCachedHook<TCtx>(
       return undefined;
     }
     hookCache.set(key, { hook, sourceMtime: currentMtime });
-    return hook as PluginHookFn<TCtx>;
+    return hook as HookFunction<TCtx>;
   } catch (err) {
     log.error(
       { err, plugin: ownerName, hook: hookName, path: filePath },
@@ -141,8 +141,8 @@ async function resolveCachedHook<TCtx>(
 export async function collectUserHooks<TCtx = unknown>(
   hookName: string,
   pluginDirs: Iterable<readonly [string, string]>,
-): Promise<PluginHookFn<TCtx>[]> {
-  const out: PluginHookFn<TCtx>[] = [];
+): Promise<HookFunction<TCtx>[]> {
+  const out: HookFunction<TCtx>[] = [];
 
   for (const [pluginDir, pluginName] of pluginDirs) {
     const hookFile = listSurfaceDir(join(pluginDir, "hooks")).find(
@@ -191,7 +191,7 @@ export async function preImportHooksDir(
     if (currentMtime === 0) continue;
 
     try {
-      const hook = await importWithTimeout<PluginHookFn>(file.path);
+      const hook = await importWithTimeout<HookFunction>(file.path);
       if (hook !== undefined && typeof hook === "function") {
         hookCache.set(key, { hook, sourceMtime: currentMtime });
       }
@@ -233,7 +233,7 @@ export async function runInitHook(ownerName: string): Promise<void> {
   if (initHookEntry === undefined) return;
 
   try {
-    const initContext: PluginInitContext = {
+    const initContext: InitContext = {
       config: getConfig().plugins?.[ownerName],
       logger: log.child({ plugin: ownerName }),
       pluginStorageDir: ensureHookStorageDir(ownerName),
@@ -256,7 +256,7 @@ export async function runInitHook(ownerName: string): Promise<void> {
  */
 export async function runShutdownHook(
   ownerName: string,
-  context: PluginShutdownContext,
+  context: ShutdownContext,
   reason: string,
 ): Promise<void> {
   const shutdownHookEntry = hookCache.get(hookKey(ownerName, HOOKS.SHUTDOWN));

package/src/plugin-api/index.ts

@@ -37,8 +37,8 @@
  *   (optionally overriding the profile) and run inference through the
  *   workspace's configured profiles and credentials — no plugin-supplied API key
  *
- * - {@link PluginInitContext} — passed to `init` hook at bootstrap
- * - {@link PluginShutdownContext} — passed to `shutdown` hook at teardown
+ * - {@link InitContext} — passed to `init` hook at bootstrap
+ * - {@link ShutdownContext} — 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 PostCompactContext} — passed to `post-compact` hook, fired after
@@ -55,7 +55,7 @@
  * - {@link PostModelCallContext} — passed to `post-model-call` hook, fired at
  *   every model-call outcome (a finalized reply or a provider rejection) to
  *   transform content and decide whether to retry
- * - {@link PluginHookFn} — signature every lifecycle hook implements
+ * - {@link HookFunction} — signature every lifecycle hook implements
  * - {@link PluginLogger} — pino-compatible logger shape on the contexts
  * - {@link ToolDefinition} — author-facing tool spec (default-export shape
  *   for both plugin tool files and workspace tool files)
@@ -98,16 +98,16 @@ export type {
 export type { LLMCallSite } from "../config/schemas/llm.js";
 export type {
   AgentLoopExitReason,
+  HookFunction,
+  InitContext,
   ModelProfileInfo,
-  PluginHookFn,
-  PluginInitContext,
   PluginLogger,
-  PluginShutdownContext,
   PostCompactContext,
   PostModelCallContext,
   PostModelCallDecision,
   PostToolUseContext,
   PreModelCallContext,
+  ShutdownContext,
   StopContext,
   ToolContext,
   ToolDefinition,

package/src/plugin-api/types.ts

@@ -57,15 +57,15 @@ export interface PluginLogger {
  * empty model that with `| null`, not `| undefined`.
  *
  * Each known hook key has a documented context shape:
- *   - `init` — {@link PluginInitContext}
- *   - `shutdown` — {@link PluginShutdownContext}
+ *   - `init` — {@link InitContext}
+ *   - `shutdown` — {@link ShutdownContext}
  *   - `user-prompt-submit` — {@link UserPromptSubmitContext}
  *   - `pre-model-call` — {@link PreModelCallContext}
  *   - `post-tool-use` — {@link PostToolUseContext}
  *   - `stop` — {@link StopContext}
  *   - `post-model-call` — {@link PostModelCallContext}
  */
-export type PluginHookFn<TCtx = unknown> = (
+export type HookFunction<TCtx = unknown> = (
   ctx: TCtx,
 ) => Promise<Partial<TCtx> | void>;
 
@@ -76,7 +76,7 @@ export type PluginHookFn<TCtx = unknown> = (
  * config, a pino-compatible logger scoped to the plugin, a per-plugin
  * writable data directory, and the assistant's version metadata.
  */
-export interface PluginInitContext {
+export interface InitContext {
   /** Parsed config for this plugin (may be `unknown` until the manifest validates). */
   config: unknown;
   /** Pino-compatible child logger bound to `{ plugin: <name> }`. */
@@ -125,7 +125,7 @@ export interface ModelProfileInfo {
 
 /**
  * Context passed to the `shutdown` hook during daemon teardown. Kept
- * intentionally narrower than {@link PluginInitContext} — most teardown
+ * intentionally narrower than {@link InitContext} — most teardown
  * paths only need to know which assistant version they're shutting
  * down against (e.g. for version-conditional cleanup of state files
  * written by a previous boot).
@@ -135,7 +135,7 @@ export interface ModelProfileInfo {
  * stash a version stamp at init can compare against the same name on
  * tear-down without keeping their own copy.
  */
-export interface PluginShutdownContext {
+export interface ShutdownContext {
   /** Assistant semver for compatibility checks inside the plugin. */
   assistantVersion: string;
 }
@@ -151,7 +151,7 @@ export interface PluginShutdownContext {
  *
  * The hook may transform `latestMessages` either by mutating it in place
  * (`push` / `splice` / `length = 0`) or by returning a new context with
- * a fresh `latestMessages` array — see {@link PluginHookFn}'s polymorphic
+ * a fresh `latestMessages` array — see {@link HookFunction}'s polymorphic
  * return shape. The daemon threads the final `latestMessages` value into
  * `agentLoop.run()` as the run-messages argument.
  *
@@ -244,7 +244,7 @@ export interface UserPromptSubmitContext {
  * their own injected context the same way.
  *
  * The hook re-injects by mutating `history` in place (or returning a new
- * context with a replacement `history`) — see {@link PluginHookFn}'s
+ * context with a replacement `history`) — see {@link HookFunction}'s
  * polymorphic return shape. The agent loop reads the settled `history` back off
  * the context and resumes the turn from it. Multiple plugins' hooks chain in
  * registration order, each seeing the previous plugin's edits.
@@ -301,7 +301,7 @@ export interface PostCompactContext {
  *
  * 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
+ * context with a fresh `toolResponse` — see {@link HookFunction}'s
  * polymorphic return shape. The daemon threads the final `toolResponse`
  * into the provider-bound history.
  *

package/src/plugins/defaults/advisor/hooks/post-model-call.ts

@@ -9,11 +9,11 @@
  * advisor's own `inference`-call-site sub-call — are ignored.
  */
 
-import type { PluginHookFn, PostModelCallContext } from "@vellumai/plugin-api";
+import type { HookFunction, PostModelCallContext } from "@vellumai/plugin-api";
 
 import { recordMessages } from "../advisor-state-store.js";
 
-const postModelCall: PluginHookFn<PostModelCallContext> = async (ctx) => {
+const postModelCall: HookFunction<PostModelCallContext> = async (ctx) => {
   if (ctx.callSite !== "mainAgent") return;
   if (ctx.error) return;
   // `ctx.messages` is the pre-reply history; the turn the model just produced —

package/src/plugins/defaults/advisor/hooks/pre-model-call.ts

@@ -5,14 +5,14 @@
  * tool. Idempotent via the steering marker.
  */
 
-import type { PluginHookFn, PreModelCallContext } from "@vellumai/plugin-api";
+import type { HookFunction, PreModelCallContext } from "@vellumai/plugin-api";
 
 import { advisorEnabledForProfile } from "../advisor-gate.js";
 import { recordSystemPrompt } from "../advisor-state-store.js";
 import { ADVISOR_CONFIG } from "../config.js";
 import { appendSteering, stripSteering } from "../steering.js";
 
-const preModelCall: PluginHookFn<PreModelCallContext> = async (ctx) => {
+const preModelCall: HookFunction<PreModelCallContext> = async (ctx) => {
   if (ctx.callSite !== "mainAgent") return;
 
   recordSystemPrompt(ctx.conversationId, stripSteering(ctx.systemPrompt));

package/src/plugins/defaults/advisor/hooks/user-prompt-submit.ts

@@ -6,13 +6,13 @@
  */
 
 import type {
-  PluginHookFn,
+  HookFunction,
   UserPromptSubmitContext,
 } from "@vellumai/plugin-api";
 
 import { seedCapture } from "../advisor-state-store.js";
 
-const userPromptSubmit: PluginHookFn<UserPromptSubmitContext> = async (ctx) => {
+const userPromptSubmit: HookFunction<UserPromptSubmitContext> = async (ctx) => {
   seedCapture(ctx.conversationId, ctx.latestMessages);
 };
 

package/src/plugins/defaults/empty-response/hooks/post-model-call.ts

@@ -46,7 +46,7 @@
  * ignores the decision — so the hook returns early for both.
  */
 
-import type { PluginHookFn, PostModelCallContext } from "@vellumai/plugin-api";
+import type { HookFunction, PostModelCallContext } from "@vellumai/plugin-api";
 
 import type { ContentBlock, Message } from "../../../../providers/types.js";
 import {
@@ -112,7 +112,7 @@ function currentCycleMessages(
   return messages;
 }
 
-const postModelCall: PluginHookFn<PostModelCallContext> = async (ctx) => {
+const postModelCall: HookFunction<PostModelCallContext> = async (ctx) => {
   // A provider rejection carries no turn content to assess (a recovery hook
   // owns the rejection); the sibling `stop` hook clears the mark when the turn
   // terminates.

package/src/plugins/defaults/empty-response/hooks/stop.ts

@@ -11,11 +11,11 @@
  * refused).
  */
 
-import type { PluginHookFn, StopContext } from "@vellumai/plugin-api";
+import type { HookFunction, StopContext } from "@vellumai/plugin-api";
 
 import { clearEmptyResponseNudged } from "../nudge-state-store.js";
 
-const stop: PluginHookFn<StopContext> = async (ctx) => {
+const stop: HookFunction<StopContext> = async (ctx) => {
   clearEmptyResponseNudged(ctx.conversationId);
 };
 

package/src/plugins/defaults/exploration-drift/hooks/post-tool-use.ts

@@ -55,7 +55,7 @@
  * per-tool-result hot path.
  */
 
-import type { PluginHookFn, PostToolUseContext } from "@vellumai/plugin-api";
+import type { HookFunction, PostToolUseContext } from "@vellumai/plugin-api";
 
 import type { Message } from "../../../../providers/types.js";
 
@@ -233,7 +233,7 @@ function currentCallRepeatCount(
   return count;
 }
 
-const postToolUse: PluginHookFn<PostToolUseContext> = async (ctx) => {
+const postToolUse: HookFunction<PostToolUseContext> = async (ctx) => {
   const usesById = toolUsesById(ctx.messages);
   const currentUse = usesById.get(ctx.toolResponse.tool_use_id);
   if (currentUse === undefined || !EXPLORATION_TOOL_NAMES.has(currentUse.name))

package/src/plugins/defaults/history-repair/hooks/post-model-call.ts

@@ -23,7 +23,7 @@
  * empty-response hook; only a provider rejection is this hook's to act on.
  */
 
-import type { PluginHookFn, PostModelCallContext } from "@vellumai/plugin-api";
+import type { HookFunction, PostModelCallContext } from "@vellumai/plugin-api";
 
 import {
   isOrderingRepairAttempted,
@@ -31,7 +31,7 @@ import {
 } from "../repair-state-store.js";
 import { deepRepairHistory, isRepairableOrderingError } from "../terminal.js";
 
-const postModelCall: PluginHookFn<PostModelCallContext> = async (ctx) => {
+const postModelCall: HookFunction<PostModelCallContext> = async (ctx) => {
   if (
     ctx.error &&
     isRepairableOrderingError(ctx.error.message) &&

package/src/plugins/defaults/history-repair/hooks/stop.ts

@@ -11,11 +11,11 @@
  * retry the loop's per-run backstop refused).
  */
 
-import type { PluginHookFn, StopContext } from "@vellumai/plugin-api";
+import type { HookFunction, StopContext } from "@vellumai/plugin-api";
 
 import { clearOrderingRepairAttempted } from "../repair-state-store.js";
 
-const stop: PluginHookFn<StopContext> = async (ctx) => {
+const stop: HookFunction<StopContext> = async (ctx) => {
   clearOrderingRepairAttempted(ctx.conversationId);
 };
 

package/src/plugins/defaults/history-repair/hooks/user-prompt-submit.ts

@@ -10,13 +10,13 @@
  */
 
 import type {
-  PluginHookFn,
+  HookFunction,
   UserPromptSubmitContext,
 } from "@vellumai/plugin-api";
 
 import { repairHistory } from "../terminal.js";
 
-const userPromptSubmit: PluginHookFn<UserPromptSubmitContext> = async (ctx) => {
+const userPromptSubmit: HookFunction<UserPromptSubmitContext> = async (ctx) => {
   const { messages, stats } = repairHistory(ctx.latestMessages);
   ctx.latestMessages = messages;
   if (

package/src/plugins/defaults/image-fallback/hooks/post-tool-use.ts

@@ -17,14 +17,14 @@
 
 import {
   doesSupportVision,
-  type PluginHookFn,
+  type HookFunction,
   type PostToolUseContext,
 } from "@vellumai/plugin-api";
 
 import { captionImageBlocks } from "../src/caption-blocks.js";
 import { findVisionProfile } from "../src/vision-caption.js";
 
-const postToolUse: PluginHookFn<PostToolUseContext> = async (ctx) => {
+const postToolUse: HookFunction<PostToolUseContext> = async (ctx) => {
   // Cheapest gate first: bail unless the tool actually returned an image,
   // before touching the model catalog or resolving a vision profile.
   const blocks = ctx.toolResponse.contentBlocks;

package/src/plugins/defaults/image-fallback/hooks/user-prompt-submit.ts

@@ -23,7 +23,7 @@
  */
 
 import {
-  type PluginHookFn,
+  type HookFunction,
   type UserPromptSubmitContext,
 } from "@vellumai/plugin-api";
 
@@ -33,7 +33,7 @@ import {
 } from "../src/caption-blocks.js";
 import { findVisionProfile } from "../src/vision-caption.js";
 
-const userPromptSubmit: PluginHookFn<UserPromptSubmitContext> = async (ctx) => {
+const userPromptSubmit: HookFunction<UserPromptSubmitContext> = async (ctx) => {
   // If the turn's model already supports vision, nothing to do.
   if (!needsImageFallback(ctx.modelProfileKey)) return;
 

package/src/plugins/defaults/image-recovery/hooks/post-model-call.ts

@@ -24,7 +24,7 @@
  * empty-response hook; only a provider rejection is this hook's to act on.
  */
 
-import type { PluginHookFn, PostModelCallContext } from "@vellumai/plugin-api";
+import type { HookFunction, PostModelCallContext } from "@vellumai/plugin-api";
 
 import { isImageDimensionsTooLargeError } from "../detect.js";
 import {
@@ -36,7 +36,7 @@ import {
   recoverOversizedImages,
 } from "../recover.js";
 
-const postModelCall: PluginHookFn<PostModelCallContext> = async (ctx) => {
+const postModelCall: HookFunction<PostModelCallContext> = async (ctx) => {
   if (
     ctx.error &&
     isImageDimensionsTooLargeError(ctx.error.message) &&

package/src/plugins/defaults/image-recovery/hooks/stop.ts

@@ -11,11 +11,11 @@
  * retry the loop's per-run backstop refused).
  */
 
-import type { PluginHookFn, StopContext } from "@vellumai/plugin-api";
+import type { HookFunction, StopContext } from "@vellumai/plugin-api";
 
 import { clearImageRecoveryAttempted } from "../image-recovery-state-store.js";
 
-const stop: PluginHookFn<StopContext> = async (ctx) => {
+const stop: HookFunction<StopContext> = async (ctx) => {
   clearImageRecoveryAttempted(ctx.conversationId);
 };
 

package/src/plugins/defaults/max-tokens-continue/hooks/post-model-call.ts

@@ -30,7 +30,7 @@
  *   reject.
  */
 
-import type { PluginHookFn, PostModelCallContext } from "@vellumai/plugin-api";
+import type { HookFunction, PostModelCallContext } from "@vellumai/plugin-api";
 
 import { isMaxTokensStopReason } from "../../../../agent/loop.js";
 import {
@@ -45,7 +45,7 @@ import {
 export const MAX_TOKENS_CONTINUE_NUDGE_TEXT =
   "<system_notice>Your previous response was cut off because it reached the maximum output length. Continue exactly where you stopped — do not repeat content you already sent and do not start over.</system_notice>";
 
-const postModelCall: PluginHookFn<PostModelCallContext> = async (ctx) => {
+const postModelCall: HookFunction<PostModelCallContext> = async (ctx) => {
   if (ctx.error) return;
   if (!isMaxTokensStopReason(ctx.stopReason)) return;
   if (ctx.callSite !== "mainAgent") return;

package/src/plugins/defaults/max-tokens-continue/hooks/stop.ts

@@ -9,11 +9,11 @@
  * budget, no matter how the turn ended.
  */
 
-import type { PluginHookFn, StopContext } from "@vellumai/plugin-api";
+import type { HookFunction, StopContext } from "@vellumai/plugin-api";
 
 import { clearMaxTokensContinueBudget } from "../continue-state-store.js";
 
-const stop: PluginHookFn<StopContext> = async (ctx) => {
+const stop: HookFunction<StopContext> = async (ctx) => {
   clearMaxTokensContinueBudget(ctx.conversationId);
 };
 

package/src/plugins/defaults/memory-retrieval/hooks/post-compact.ts

@@ -38,7 +38,7 @@
  * {@link PostCompactContext}.
  */
 
-import type { PluginHookFn, PostCompactContext } from "@vellumai/plugin-api";
+import type { HookFunction, PostCompactContext } from "@vellumai/plugin-api";
 
 import { getConfig } from "../../../../config/loader.js";
 import { findConversationOrSubagent } from "../../../../daemon/conversation-registry.js";
@@ -53,7 +53,7 @@ import {
 import { getLiveGraphMemory } from "../../../../memory/graph/conversation-graph-memory.js";
 import { stripTailInjectionsForReinjection } from "../tail-reinjection-strip.js";
 
-const postCompact: PluginHookFn<PostCompactContext> = async (ctx) => {
+const postCompact: HookFunction<PostCompactContext> = async (ctx) => {
   const {
     history,
     requestId,

package/src/plugins/defaults/memory-retrieval/hooks/user-prompt-submit.ts

@@ -28,7 +28,7 @@
  */
 
 import type {
-  PluginHookFn,
+  HookFunction,
   UserPromptSubmitContext,
 } from "@vellumai/plugin-api";
 
@@ -264,7 +264,7 @@ function persistInjectionBlocks(
  * slower turn. Cancellation still works via `ctx.signal`, which is threaded
  * into `prepareMemory`.
  */
-const userPromptSubmitMemoryRetrieval: PluginHookFn<
+const userPromptSubmitMemoryRetrieval: HookFunction<
   UserPromptSubmitContext
 > = async (ctx) => {
   // The conversation-scoped retrieval state — graph handle, abort signal, and

package/src/plugins/defaults/memory-v3-shadow/hooks/post-compact.ts

@@ -7,8 +7,8 @@
  * `../injector.js` and re-apply it here. Until then this hook does nothing.
  */
 
-import type { PluginHookFn } from "@vellumai/plugin-api";
+import type { HookFunction } from "@vellumai/plugin-api";
 
-const postCompact: PluginHookFn = async () => {};
+const postCompact: HookFunction = async () => {};
 
 export default postCompact;

package/src/plugins/defaults/memory-v3-shadow/hooks/user-prompt-submit.ts

@@ -10,10 +10,10 @@
  */
 
 import type {
-  PluginHookFn,
+  HookFunction,
   UserPromptSubmitContext,
 } from "@vellumai/plugin-api";
 
-const userPromptSubmit: PluginHookFn<UserPromptSubmitContext> = async () => {};
+const userPromptSubmit: HookFunction<UserPromptSubmitContext> = async () => {};
 
 export default userPromptSubmit;

package/src/plugins/defaults/surface-completion-nudge/hooks/post-model-call.ts

@@ -45,7 +45,7 @@
  * the `post-model-call` chain — later hooks see (and may override) its decision.
  */
 
-import type { PluginHookFn, PostModelCallContext } from "@vellumai/plugin-api";
+import type { HookFunction, PostModelCallContext } from "@vellumai/plugin-api";
 
 import type { ContentBlock, Message } from "../../../../providers/types.js";
 import {
@@ -246,7 +246,7 @@ function hasDanglingProgressSurface(messages: ReadonlyArray<Message>): boolean {
   return false;
 }
 
-const postModelCall: PluginHookFn<PostModelCallContext> = async (ctx) => {
+const postModelCall: HookFunction<PostModelCallContext> = async (ctx) => {
   // A provider rejection carries no turn content to assess (a recovery hook
   // owns the rejection).
   if (ctx.error) return;

package/src/plugins/defaults/surface-completion-nudge/hooks/stop.ts

@@ -11,11 +11,11 @@
  * refused).
  */
 
-import type { PluginHookFn, StopContext } from "@vellumai/plugin-api";
+import type { HookFunction, StopContext } from "@vellumai/plugin-api";
 
 import { clearSurfaceCompletionNudged } from "../nudge-state-store.js";
 
-const stop: PluginHookFn<StopContext> = async (ctx) => {
+const stop: HookFunction<StopContext> = async (ctx) => {
   clearSurfaceCompletionNudged(ctx.conversationId);
 };
 

package/src/plugins/defaults/task-progress-nudge/hooks/post-tool-use.ts

@@ -45,7 +45,7 @@
  * below it (a new turn restarts counting low).
  */
 
-import type { PluginHookFn, PostToolUseContext } from "@vellumai/plugin-api";
+import type { HookFunction, PostToolUseContext } from "@vellumai/plugin-api";
 
 import type { ContentBlock, Message } from "../../../../providers/types.js";
 import { isWeakOpenModel } from "../../../../providers/weak-open-model.js";
@@ -134,7 +134,7 @@ function scanTurn(messages: ReadonlyArray<Message>): {
   return { rounds, taskProgressShown };
 }
 
-const postToolUse: PluginHookFn<PostToolUseContext> = async (ctx) => {
+const postToolUse: HookFunction<PostToolUseContext> = async (ctx) => {
   if (!isWeakOpenModel(ctx.model)) return;
 
   const { rounds, taskProgressShown } = scanTurn(ctx.messages);

package/src/plugins/defaults/title-generate/hooks/stop.ts

@@ -18,7 +18,7 @@
  * stateless and means a mid-run array rewrite (compaction) can't invalidate it.
  */
 
-import type { PluginHookFn, StopContext } from "@vellumai/plugin-api";
+import type { HookFunction, StopContext } from "@vellumai/plugin-api";
 
 import { getConfig } from "../../../../config/loader.js";
 import { getConversation } from "../../../../memory/conversation-crud.js";
@@ -65,7 +65,7 @@ function shouldRetryFallbackTitle(conversation: {
   );
 }
 
-const stop: PluginHookFn<StopContext> = async (ctx) => {
+const stop: HookFunction<StopContext> = async (ctx) => {
   // Re-title only at a genuine successful turn end (the model returned a reply
   // with no tool calls). Any other terminal — a provider rejection, abort, or
   // an output-limit cutoff — produced no new topic to re-title from.

package/src/plugins/defaults/title-generate/hooks/user-prompt-submit.ts

@@ -11,14 +11,14 @@
  */
 
 import type {
-  PluginHookFn,
+  HookFunction,
   UserPromptSubmitContext,
 } from "@vellumai/plugin-api";
 
 import { getConversation } from "../../../../memory/conversation-crud.js";
 import { queueGenerateConversationTitle } from "../../../../memory/conversation-title-service.js";
 
-const userPromptSubmit: PluginHookFn<UserPromptSubmitContext> = async (ctx) => {
+const userPromptSubmit: HookFunction<UserPromptSubmitContext> = async (ctx) => {
   // System conversations (background/scheduled) carry a deterministic title
   // from bootstrap. Their own job prompts arrive as non-interactive turns and
   // must not spend an LLM call on a title nobody reads — only a genuine user

package/src/plugins/defaults/tool-error/hooks/post-tool-use.ts

@@ -22,7 +22,7 @@
  * result for the tool resets its streak.
  */
 
-import type { PluginHookFn, PostToolUseContext } from "@vellumai/plugin-api";
+import type { HookFunction, PostToolUseContext } from "@vellumai/plugin-api";
 
 import type { Message } from "../../../../providers/types.js";
 
@@ -85,7 +85,7 @@ function priorConsecutiveErrors(
   return streak;
 }
 
-const postToolUse: PluginHookFn<PostToolUseContext> = async (ctx) => {
+const postToolUse: HookFunction<PostToolUseContext> = async (ctx) => {
   if (ctx.toolResponse.is_error !== true) return;
 
   const namesById = toolNamesById(ctx.messages);

package/src/plugins/defaults/tool-result-truncate/hooks/post-tool-use.ts

@@ -8,11 +8,11 @@
  * The hook mutates `toolResponse.content` in place.
  */
 
-import type { PluginHookFn, PostToolUseContext } from "@vellumai/plugin-api";
+import type { HookFunction, PostToolUseContext } from "@vellumai/plugin-api";
 
 import { truncateToolResult } from "../terminal.js";
 
-const postToolUse: PluginHookFn<PostToolUseContext> = async (ctx) => {
+const postToolUse: HookFunction<PostToolUseContext> = async (ctx) => {
   const { content, truncated } = truncateToolResult(
     ctx.toolResponse.content,
     ctx.maxInputTokens,

package/src/plugins/external-plugin-loader.ts

@@ -54,8 +54,8 @@ import type { Tool, ToolDefinition } from "../tools/types.js";
 import { getLogger } from "../util/logger.js";
 import { registerPlugin } from "./registry.js";
 import type {
+  HookFunction,
   Plugin,
-  PluginHookFn,
   PluginHooks,
   PluginManifest,
 } from "./types.js";
@@ -195,7 +195,7 @@ async function loadHooks(
   if (files.length === 0) return undefined;
   const hooks: PluginHooks = {};
   for (const { name, path } of files) {
-    const fn = await importDefault<PluginHookFn>(path);
+    const fn = await importDefault<HookFunction>(path);
     if (typeof fn !== "function") {
       throw new Error(
         `external plugin ${pluginName}: hooks/${name} default export must be a function (got ${typeof fn})`,

package/src/plugins/mtime-cache.ts

@@ -35,10 +35,7 @@ import {
   runShutdownHook,
   WORKSPACE_HOOKS_OWNER,
 } from "../hooks/hook-loader.js";
-import type {
-  PluginHookFn,
-  PluginShutdownContext,
-} from "../plugin-api/types.js";
+import type { HookFunction, ShutdownContext } from "../plugin-api/types.js";
 import {
   registerPluginTools,
   unregisterPluginTools,
@@ -60,9 +57,9 @@ import {
   setSurfaceImportTimeout,
 } from "./surface-import.js";
 
-// Re-export for type compat — consumers that import PluginHookFn from
+// Re-export for type compat — consumers that import HookFunction from
 // the mtime cache module still resolve.
-export type { PluginHookFn } from "./types.js";
+export type { HookFunction } from "./types.js";
 
 const log = getLogger("plugin-mtime-cache");
 
@@ -184,7 +181,7 @@ const disabledPluginDirs = new Set<string>();
  */
 export async function getUserHooksFor<TCtx = unknown>(
   hookName: string,
-): Promise<PluginHookFn<TCtx>[]> {
+): Promise<HookFunction<TCtx>[]> {
   await scanPlugins();
   return collectUserHooks<TCtx>(hookName, discoveredPluginDirs);
 }
@@ -439,7 +436,7 @@ const activatedPlugins: Array<{ name: string }> = [];
  */
 const activatedNames = new Set<string>();
 
-const shutdownContext: PluginShutdownContext = {
+const shutdownContext: ShutdownContext = {
   assistantVersion: APP_VERSION,
 };
 

package/src/plugins/pipeline.ts

@@ -19,7 +19,7 @@
 import type { HookName } from "../plugin-api/constants.js";
 import { getLogger } from "../util/logger.js";
 import { getHooksFor } from "./registry.js";
-import type { PluginHookFn } from "./types.js";
+import type { HookFunction } from "./types.js";
 
 // ─── Hook runner ────────────────────────────────────────────────────────────
 
@@ -116,7 +116,7 @@ export async function runHook<TCtx>(
   name: HookName,
   initialCtx: TCtx,
 ): Promise<TCtx> {
-  let hooks: PluginHookFn<TCtx>[];
+  let hooks: HookFunction<TCtx>[];
   try {
     hooks = await getHooksFor<TCtx>(name);
   } catch (err) {

package/src/plugins/registry.ts

@@ -21,9 +21,9 @@
 
 import { getUserHooksFor } from "./mtime-cache.js";
 import {
+  type HookFunction,
   type Plugin,
   PluginExecutionError,
-  type PluginHookFn,
 } from "./types.js";
 
 // ─── Internal state ──────────────────────────────────────────────────────────
@@ -151,20 +151,20 @@ export function getRegisteredPlugins(): Plugin[] {
  * files. First-party default plugin hooks are read synchronously from the
  * registry and prepended.
  *
- * The `TCtx` generic mirrors {@link PluginHookFn}'s — callers parameterize
+ * The `TCtx` generic mirrors {@link HookFunction}'s — callers parameterize
  * over the concrete context type their hook receives. Hooks that mutate
  * the context in place return `void`; hooks that return a new context
  * replace the threaded value for the next hook in the chain.
  */
 export async function getHooksFor<TCtx = unknown>(
   name: string,
-): Promise<PluginHookFn<TCtx>[]> {
+): Promise<HookFunction<TCtx>[]> {
   // First-party defaults from the registry (synchronous).
-  const defaultHooks: PluginHookFn<TCtx>[] = [];
+  const defaultHooks: HookFunction<TCtx>[] = [];
   for (const plugin of registeredPlugins.values()) {
     const hook = plugin.hooks?.[name];
     if (hook) {
-      defaultHooks.push(hook as PluginHookFn<TCtx>);
+      defaultHooks.push(hook as HookFunction<TCtx>);
     }
   }
 

package/src/plugins/types.ts

@@ -19,7 +19,7 @@ import type {
 } from "../daemon/conversation-runtime-assembly.js";
 import type { TrustContext } from "../daemon/trust-context.js";
 import type { ConversationGraphMemory } from "../memory/graph/conversation-graph-memory.js";
-import type { PluginHookFn } from "../plugin-api/types.js";
+import type { HookFunction } from "../plugin-api/types.js";
 import type { Message } from "../providers/types.js";
 import type { SkillRoute } from "../runtime/skill-route-registry.js";
 import type { Tool } from "../tools/types.js";
@@ -67,9 +67,9 @@ export interface PluginManifest {
 // existing internal call sites keep working. Plugin authors import these from
 // `@vellumai/plugin-api`.
 export type {
-  PluginHookFn,
-  PluginInitContext,
-  PluginShutdownContext,
+  HookFunction,
+  InitContext,
+  ShutdownContext,
 } from "../plugin-api/types.js";
 
 // ─── Memory-graph result ─────────────────────────────────────────────────────
@@ -343,14 +343,14 @@ export type PluginRouteRegistration = SkillRoute;
  * unknown keys are forward-compat scaffolding.
  *
  * See `assistant/src/daemon/external-plugins-bootstrap.ts` for the
- * full lifecycle, and {@link PluginHookFn} for the per-entry signature.
+ * full lifecycle, and {@link HookFunction} for the per-entry signature.
  */
 // The map stores hooks for arbitrary keys with arbitrary context shapes.
 // `any` (rather than `unknown`) is required so concrete plugin signatures
-// like `(ctx: PluginInitContext) => Promise<void>` and `() => Promise<void>`
+// like `(ctx: InitContext) => Promise<void>` and `() => Promise<void>`
 // both assign in/out of slot entries under strict-function-types contravariance.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type PluginHooks = Record<string, PluginHookFn<any>>;
+export type PluginHooks = Record<string, HookFunction<any>>;
 
 /**
  * A registered plugin. Every field besides `manifest` is optional — a plugin

package/src/tools/types.ts

@@ -249,6 +249,26 @@ export function stringifyToolInput(input: Record<string, unknown>): string {
   }
 }
 
+/**
+ * Runtime context passed as the second argument to every tool's `execute`.
+ *
+ * The fields fall into two groups:
+ *
+ * - A small, stable core that we are comfortable exposing to any tool —
+ *   including workspace- and plugin-authored tools via `@vellumai/plugin-api`:
+ *   `conversationId`, `workingDir`, `requestId`, `signal`, `onOutput`,
+ *   `assistantId`, `isInteractive`.
+ * - Everything tagged `@legacy` below: host-internal routing, permission,
+ *   trust, requester-identity, proxy, and telemetry metadata that historically
+ *   accreted on this single context. These are NOT a surface we want third-party
+ *   tools to depend on; we are triaging them post-launch with the goal of
+ *   moving them off the public context (or removing them) over time. Grep for
+ *   `@legacy` to enumerate the set. Do not add new fields here — extend the
+ *   stable core only when a field is genuinely safe and stable to expose.
+ *
+ * The daemon constructs and passes the full object to every tool at runtime; a
+ * tool that only reads the stable core is unaffected by the eventual cleanup.
+ */
 export interface ToolContext {
   /** Identifier of the conversation this tool invocation belongs to. */
   conversationId: string;
@@ -262,23 +282,44 @@ export interface ToolContext {
   onOutput?: (chunk: string) => void;
   /** Logical assistant scope for multi-assistant routing. */
   assistantId?: string;
-  /** When set, the tool execution is part of a task run. Used to retrieve ephemeral permission rules. */
+  /** True when an interactive client is connected (not just a no-op callback). */
+  isInteractive?: boolean;
+  /**
+   * When set, the tool execution is part of a task run. Used to retrieve ephemeral permission rules.
+   * @legacy
+   */
   taskRunId?: string;
   /**
    * Model attribution snapshot for the conversation at invocation time
    * (provider/model/profile that issued this tool call). Used by tool
    * telemetry; never sent to the tool itself.
+   * @legacy
    */
   attribution?: UsageAttributionSnapshot | null;
-  /** Optional callback for tool lifecycle events (start/prompt/deny/execute/error). */
+  /**
+   * Optional callback for tool lifecycle events (start/prompt/deny/execute/error).
+   * @legacy
+   */
   onToolLifecycleEvent?: ToolLifecycleEventHandler;
-  /** Optional resolver for proxy tools - delegates execution to an external client. */
+  /**
+   * Optional resolver for proxy tools - delegates execution to an external client.
+   * @legacy
+   */
   proxyToolResolver?: ProxyToolResolver;
-  /** When set, only tools in this set may execute. Tools outside the set are blocked with an error. */
+  /**
+   * When set, only tools in this set may execute. Tools outside the set are blocked with an error.
+   * @legacy
+   */
   allowedToolNames?: Set<string>;
-  /** True when this turn is restricted to storage cleanup-safe tools. */
+  /**
+   * True when this turn is restricted to storage cleanup-safe tools.
+   * @legacy
+   */
   diskPressureCleanupModeActive?: boolean;
-  /** Prompt the user for a secret value via native SecureField UI. */
+  /**
+   * Prompt the user for a secret value via native SecureField UI.
+   * @legacy
+   */
   requestSecret?: (params: {
     service: string;
     field: string;
@@ -289,11 +330,15 @@ export interface ToolContext {
     allowedTools?: string[];
     allowedDomains?: string[];
   }) => Promise<SecretPromptResult>;
-  /** Optional callback to send a message to the connected client (e.g. open_url). */
+  /**
+   * Optional callback to send a message to the connected client (e.g. open_url).
+   * @legacy
+   */
   sendToClient?: (msg: { type: string; [key: string]: unknown }) => void;
-  /** True when an interactive client is connected (not just a no-op callback). */
-  isInteractive?: boolean;
-  /** When true, tools with side effects should always prompt for confirmation. */
+  /**
+   * When true, tools with side effects should always prompt for confirmation.
+   * @legacy
+   */
   forcePromptSideEffects?: boolean;
   /**
    * When true, the tool requires a fresh interactive approval for every
@@ -304,26 +349,46 @@ export interface ToolContext {
    * temporary override options in the prompt UI. Used by
    * `manage_secure_command_tool` to ensure a human reviews each secure
    * bundle installation.
+   * @legacy
    */
   requireFreshApproval?: boolean;
-  /** Approval callback for proxy policy decisions that require user confirmation. */
+  /**
+   * Approval callback for proxy policy decisions that require user confirmation.
+   * @legacy
+   */
   proxyApprovalCallback?: ProxyApprovalCallback;
-  /** Optional principal identifier propagated to sub-tool confirmation flows. */
+  /**
+   * Optional principal identifier propagated to sub-tool confirmation flows.
+   * @legacy
+   */
   principal?: string;
   /**
    * Trust classification of the actor who initiated this tool invocation.
    * Determines permission level: guardians self-approve, trusted contacts
    * may escalate to guardian for approval, unknown actors are fail-closed.
    * See {@link TrustClass} in actor-trust-resolver.ts for value semantics.
+   * @legacy
    */
   trustClass: TrustClass;
-  /** Channel through which the tool invocation originates (e.g. 'telegram', 'phone'). Used for scoped grant consumption. */
+  /**
+   * Channel through which the tool invocation originates (e.g. 'telegram', 'phone'). Used for scoped grant consumption.
+   * @legacy
+   */
   executionChannel?: string;
-  /** Voice/call session ID, if the invocation originates from a call. Used for scoped grant consumption. */
+  /**
+   * Voice/call session ID, if the invocation originates from a call. Used for scoped grant consumption.
+   * @legacy
+   */
   callSessionId?: string;
-  /** True when the tool invocation was triggered by a user clicking a surface action button (not a regular message). */
+  /**
+   * True when the tool invocation was triggered by a user clicking a surface action button (not a regular message).
+   * @legacy
+   */
   triggeredBySurfaceAction?: boolean;
-  /** True when the user explicitly approved this tool invocation via the interactive permission prompt (not auto-approved by trust rules or temporary overrides). */
+  /**
+   * True when the user explicitly approved this tool invocation via the interactive permission prompt (not auto-approved by trust rules or temporary overrides).
+   * @legacy
+   */
   approvedViaPrompt?: boolean;
   /**
    * True when the invocation is inside a scheduled task run whose
@@ -331,21 +396,43 @@ export interface ToolContext {
    * Tools that normally require a surface-action click (e.g. bulk archive,
    * unsubscribe) may treat this as equivalent consent, since the user
    * already reviewed the tool list when the task was saved.
+   * @legacy
    */
   batchAuthorizedByTask?: boolean;
-  /** External user ID of the requester (non-guardian actor). Used for scoped grant consumption. */
+  /**
+   * External user ID of the requester (non-guardian actor). Used for scoped grant consumption.
+   * @legacy
+   */
   requesterExternalUserId?: string;
-  /** Chat ID of the requester (non-guardian actor). Used for tool grant request escalation notifications. */
+  /**
+   * Chat ID of the requester (non-guardian actor). Used for tool grant request escalation notifications.
+   * @legacy
+   */
   requesterChatId?: string;
-  /** Human-readable identifier for the requester (e.g., @username). */
+  /**
+   * Human-readable identifier for the requester (e.g., @username).
+   * @legacy
+   */
   requesterIdentifier?: string;
-  /** Preferred display name for the requester. */
+  /**
+   * Preferred display name for the requester.
+   * @legacy
+   */
   requesterDisplayName?: string;
-  /** Slack channel ID for channel-scoped permission enforcement. When set, tools are checked against the channel's permission profile. */
+  /**
+   * Slack channel ID for channel-scoped permission enforcement. When set, tools are checked against the channel's permission profile.
+   * @legacy
+   */
   channelPermissionChannelId?: string;
-  /** The tool_use block ID from the LLM response, used to correlate confirmation prompts with specific tool invocations. */
+  /**
+   * The tool_use block ID from the LLM response, used to correlate confirmation prompts with specific tool invocations.
+   * @legacy
+   */
   toolUseId?: string;
-  /** True when the assistant is running as a platform-managed remote instance. Used to auto-approve sandboxed bash tools. */
+  /**
+   * True when the assistant is running as a platform-managed remote instance. Used to auto-approve sandboxed bash tools.
+   * @legacy
+   */
   isPlatformHosted?: boolean;
   /**
    * The interface ID of the connected client driving the current turn (e.g.
@@ -353,6 +440,7 @@ export interface ToolContext {
    * transport preference — for example, macOS-originated turns prefer the
    * user's real Chrome session via the paired extension before falling back
    * to cdp-inspect or local Playwright.
+   * @legacy
    */
   transportInterface?: InterfaceId;
   /**
@@ -363,6 +451,7 @@ export interface ToolContext {
    * has `inferenceProfile` set — the override only flows through the
    * in-memory `SubagentConfig.overrideProfile` chain. See
    * `executeSubagentSpawn` in tools/subagent/spawn.ts.
+   * @legacy
    */
   overrideProfile?: string;
   /**
@@ -371,6 +460,7 @@ export interface ToolContext {
    * default a spawned subagent's inference profile to the profile the invoking
    * turn resolved to, so subagents match whatever agent invoked them rather
    * than always falling back to the static `subagentSpawn` call-site default.
+   * @legacy
    */
   invokingCallSite?: LLMCallSite;
   /**
@@ -379,6 +469,7 @@ export interface ToolContext {
    * Used by host proxies to bind cross-client targeted execution to the same
    * authenticated user identity. May be undefined for legacy/internal flows
    * with no resolved actor identity.
+   * @legacy
    */
   sourceActorPrincipalId?: string;
 }