@vellumai/assistant 0.10.2 → 0.10.3-dev.202606252046.9075fd5

package/src/tools/subagent/consult-deadline.ts

@@ -0,0 +1,49 @@
+/**
+ * A progress-aware deadline for the synchronous advisor consult.
+ *
+ * A reasoning advisor profile spends most of its window *thinking*, streaming
+ * reasoning tokens the whole time. A fixed wall-clock ceiling would cut it off
+ * mid-thought, so this aborts only after the consult goes `idleMs` without any
+ * streamed token (thinking or text) — i.e. genuine silence — with an absolute
+ * `maxMs` backstop so a runaway or looping stream can't block the parent
+ * forever.
+ *
+ * Usage: combine `signal` with the caller's own signal, call `recordProgress()`
+ * on every streamed chunk, and `dispose()` once the consult settles.
+ */
+export interface ConsultDeadline {
+  /** Aborts when the idle window lapses or the absolute max elapses. */
+  readonly signal: AbortSignal;
+  /** Reset the idle window — call on every streamed chunk (thinking or text). */
+  recordProgress(): void;
+  /** Clear both timers; call once the consult settles (success or failure). */
+  dispose(): void;
+}
+
+export function createConsultDeadline(opts: {
+  idleMs: number;
+  maxMs: number;
+}): ConsultDeadline {
+  const controller = new AbortController();
+  let idleTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const recordProgress = (): void => {
+    // Once aborted, don't re-arm — the consult is already being torn down.
+    if (controller.signal.aborted) return;
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => controller.abort(), opts.idleMs);
+  };
+
+  // Absolute backstop, independent of streaming progress.
+  const maxTimer = setTimeout(() => controller.abort(), opts.maxMs);
+
+  // Arm the idle window immediately so time-to-first-token is bounded too.
+  recordProgress();
+
+  const dispose = (): void => {
+    if (idleTimer) clearTimeout(idleTimer);
+    clearTimeout(maxTimer);
+  };
+
+  return { signal: controller.signal, recordProgress, dispose };
+}

package/src/tools/subagent/spawn.ts

@@ -2,11 +2,45 @@ import { validateInferenceProfileKey } from "../../config/inference-profile-vali
 import { resolveDefaultProfileKey } from "../../config/llm-resolver.js";
 import { getConfig } from "../../config/loader.js";
 import { findConversation } from "../../daemon/conversation-registry.js";
-import { getConversationOverrideProfile } from "../../memory/conversation-crud.js";
-import type { Message } from "../../providers/types.js";
-import { getSubagentManager } from "../../subagent/index.js";
+import type { ServerMessage } from "../../daemon/message-protocol.js";
+import {
+  getConversationOverrideProfile,
+  getMessages,
+} from "../../memory/conversation-crud.js";
+import type { ContentBlock, Message } from "../../providers/types.js";
+import {
+  advisorRequestText,
+  buildAdvisorSystem,
+} from "../../subagent/consult-prompt.js";
+import { sanitizeConsultTranscript } from "../../subagent/consult-transcript.js";
+import {
+  getSubagentManager,
+  SubagentAbortedError,
+} from "../../subagent/index.js";
 import type { SubagentRole } from "../../subagent/types.js";
+import { getLogger } from "../../util/logger.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
+import { createConsultDeadline } from "./consult-deadline.js";
+
+const log = getLogger("subagent-spawn");
+
+/**
+ * Idle ceiling on a single advisor consult: abort only after this much time
+ * passes with NO streamed token (thinking or text). A reasoning advisor profile
+ * streams its reasoning while it works, so a fixed wall-clock ceiling would kill
+ * it mid-thought; an idle window instead fires only when the consult is
+ * genuinely stalled (or never starts). Generous enough to also span
+ * time-to-first-token over a large inherited transcript.
+ */
+const ADVISOR_IDLE_TIMEOUT_MS = 60_000;
+
+/**
+ * Absolute backstop on a single advisor consult regardless of streaming
+ * progress, so a runaway or looping stream can't block the parent forever.
+ * Either ceiling still yields the partial guidance (recovered in the
+ * `SubagentAbortedError` branch below), not a discard.
+ */
+const ADVISOR_MAX_TIMEOUT_MS = 300_000;
 
 export async function executeSubagentSpawn(
   input: Record<string, unknown>,
@@ -63,6 +97,19 @@ export async function executeSubagentSpawn(
     };
   }
 
+  // ── Advisor role: synchronous, tool-less, stronger-model consult ──
+  // Branch before the fire-and-forget path: the advisor blocks on the run and
+  // returns its guidance as the tool result in the same turn.
+  if (role === "advisor") {
+    return runAdvisorConsult({
+      context,
+      label,
+      objective,
+      sendToClient: sendToClient as (msg: ServerMessage) => void,
+      requestedOverrideProfile,
+    });
+  }
+
   // ── Fork mode: resolve parent context ────────────────────────────
   let forkFields:
     | {
@@ -138,8 +185,8 @@ export async function executeSubagentSpawn(
         objective,
         context: extraContext,
         sendResultToUser,
-        // For fork mode, role is ignored by the manager (forced to general),
-        // but we still omit it from the config to signal intent.
+        // Regular forks omit the role so they default to general; the advisor
+        // role is special-cased earlier via runAdvisorConsult, not here.
         ...(!fork && role ? { role: role as SubagentRole } : {}),
         ...(inheritedOverrideProfile
           ? { overrideProfile: inheritedOverrideProfile }
@@ -168,3 +215,185 @@ export async function executeSubagentSpawn(
     return { content: `Failed to spawn subagent: ${msg}`, isError: true };
   }
 }
+
+// ── Advisor consult ──────────────────────────────────────────────────
+
+/**
+ * Run the `advisor` role as a synchronous, context-inheriting, stronger-model
+ * consult and return its guidance as the tool result.
+ *
+ * Inherits the parent transcript (sanitized), frames it as advice via
+ * `buildAdvisorSystem`, runs tool-less on `llm.advisorProfile` (unless the
+ * caller passed an explicit `inference_profile`), and is bounded by a
+ * progress-aware deadline: an idle window (`ADVISOR_IDLE_TIMEOUT_MS`) reset on
+ * every streamed token so a reasoning model isn't killed mid-thought, plus an
+ * absolute `ADVISOR_MAX_TIMEOUT_MS` backstop. If either ceiling is hit, the
+ * partial guidance produced so far is recovered and returned with a "may be cut
+ * off" note rather than discarded. Degrades to a benign non-error notice on any
+ * other failure (including the depth-limit rejection when a subagent itself
+ * calls the advisor).
+ */
+async function runAdvisorConsult(args: {
+  context: ToolContext;
+  label: string;
+  /** The agent's own `objective` — its framing of what it wants advised on. */
+  objective: string;
+  sendToClient: (msg: ServerMessage) => void;
+  requestedOverrideProfile: string | undefined;
+}): Promise<ToolExecutionResult> {
+  const { context, label, objective, sendToClient, requestedOverrideProfile } =
+    args;
+
+  try {
+    const parentConversation = findConversation(context.conversationId);
+    if (!parentConversation) {
+      return {
+        content:
+          "(advisor unavailable: parent conversation could not be resolved)",
+        isError: false,
+      };
+    }
+
+    // Snapshot the parent's in-memory transcript and system prompt, then append
+    // the in-flight assistant turn (the plan/text the model wrote THIS turn,
+    // before calling the advisor). The in-memory array does not yet hold that
+    // turn — the agent loop only writes it back to `conversation.messages` after
+    // the turn settles — but it is already persisted to the DB (the assistant
+    // row is finalized at `message_complete`, which fires before tool execution).
+    // `sanitizeConsultTranscript` then strips the dangling advisor `tool_use`
+    // off that final assistant turn so the inherited transcript is provider-safe.
+    const parentSystemPrompt = parentConversation.getCurrentSystemPrompt();
+    const withInFlight = appendInFlightAssistantTurn(
+      [...parentConversation.messages],
+      context.conversationId,
+    );
+    const sanitizedMessages = sanitizeConsultTranscript(withInFlight);
+
+    // Default to the stronger advisor profile when the caller did not pin one;
+    // an explicit `inference_profile` wins (already forced upstream).
+    const advisorProfile = getConfig().llm.advisorProfile;
+    const overrideProfile = requestedOverrideProfile ?? advisorProfile;
+    const forceOverrideProfile = overrideProfile !== undefined;
+
+    // Progress-aware deadline: reset on every streamed token so the consult
+    // isn't killed mid-thought, with an absolute backstop. Combine it with the
+    // caller's own signal.
+    const deadline = createConsultDeadline({
+      idleMs: ADVISOR_IDLE_TIMEOUT_MS,
+      maxMs: ADVISOR_MAX_TIMEOUT_MS,
+    });
+    const signal = context.signal
+      ? AbortSignal.any([context.signal, deadline.signal])
+      : deadline.signal;
+    // Every streamed chunk (thinking or text) counts as progress and resets the
+    // idle window, then forwards to the caller's stream sink if one is present.
+    const onText = (chunk: string): void => {
+      deadline.recordProgress();
+      context.onOutput?.(chunk);
+    };
+
+    try {
+      const advice = await getSubagentManager().spawnAndAwait(
+        {
+          parentConversationId: context.conversationId,
+          label,
+          // Carry the agent's own objective into the consult request — the
+          // agent states the task here, and the inherited transcript can be thin.
+          objective: advisorRequestText(objective),
+          sendResultToUser: false,
+          role: "advisor",
+          fork: true,
+          parentMessages: sanitizedMessages,
+          systemPromptOverride: buildAdvisorSystem(parentSystemPrompt),
+          ...(overrideProfile ? { overrideProfile } : {}),
+          ...(forceOverrideProfile ? { forceOverrideProfile: true } : {}),
+          ...(context.toolUseId ? { parentToolUseId: context.toolUseId } : {}),
+        },
+        sendToClient,
+        { signal, onText },
+      );
+
+      const trimmed = advice.trim();
+      return {
+        content:
+          trimmed.length > 0 ? trimmed : "(advisor returned no guidance)",
+        isError: false,
+      };
+    } finally {
+      deadline.dispose();
+    }
+  } catch (err) {
+    // Timed out mid-generation: salvage whatever guidance the advisor had
+    // written rather than throwing it away. Partial strategic advice is far
+    // more useful to the agent than an "unavailable" notice — especially on a
+    // slow reasoning profile that needs most of the window to think.
+    if (err instanceof SubagentAbortedError) {
+      const partial = err.partialText.trim();
+      if (partial.length > 0) {
+        log.warn(
+          { conversationId: context.conversationId },
+          "Advisor consult timed out; returning partial guidance",
+        );
+        return {
+          content: `${partial}\n\n_(The advisor reached its time limit while still writing — the guidance above may be cut off.)_`,
+          isError: false,
+        };
+      }
+    }
+    const reason = err instanceof Error ? err.message : String(err);
+    log.warn(
+      { err, conversationId: context.conversationId },
+      "Advisor consult failed",
+    );
+    // Never fail the turn — the advisor is advice, not a blocker.
+    return { content: `(advisor unavailable: ${reason})`, isError: false };
+  }
+}
+
+/**
+ * Append the in-flight assistant turn (persisted this turn before the advisor
+ * tool ran) to an in-memory message snapshot, unless the snapshot already ends
+ * with it. The latest persisted assistant row carries the plan/text the model
+ * wrote immediately before calling the advisor plus the dangling advisor
+ * `tool_use`; `sanitizeConsultTranscript` strips the dangling call.
+ *
+ * Best-effort: a malformed or missing row leaves the snapshot unchanged so the
+ * consult still runs over the in-memory history.
+ */
+function appendInFlightAssistantTurn(
+  messages: Message[],
+  conversationId: string,
+): Message[] {
+  // When the snapshot already ends on an assistant turn, the in-flight turn is
+  // present (or there is none to add) — appending the latest row would duplicate it.
+  if (messages[messages.length - 1]?.role === "assistant") return messages;
+
+  let rows;
+  try {
+    rows = getMessages(conversationId);
+  } catch {
+    return messages;
+  }
+  if (!rows || rows.length === 0) return messages;
+
+  const lastRow = rows[rows.length - 1];
+  if (lastRow.role !== "assistant") return messages;
+
+  let blocks: ContentBlock[];
+  try {
+    const parsed = JSON.parse(lastRow.content);
+    if (Array.isArray(parsed)) {
+      blocks = parsed as ContentBlock[];
+    } else if (typeof parsed === "string") {
+      blocks = [{ type: "text", text: parsed }];
+    } else {
+      return messages;
+    }
+  } catch {
+    // Plain-text content (no JSON envelope).
+    blocks = [{ type: "text", text: lastRow.content }];
+  }
+
+  if (blocks.length === 0) return messages;
+  return [...messages, { role: "assistant", content: blocks }];
+}

package/src/tools/tool-approval-handler.ts

@@ -553,7 +553,7 @@ export class ToolApprovalHandler {
         const inputDigest =
           deferredConsumeParams?.inputDigest ??
           computeToolApprovalDigest(name, input);
-        const escalation = createOrReuseToolGrantRequest({
+        const escalation = await createOrReuseToolGrantRequest({
           assistantId: context.assistantId,
           sourceChannel: context.executionChannel as ChannelId,
           conversationId: context.conversationId,

package/src/tools/tool-defaults.ts

@@ -10,6 +10,7 @@
  * is a `Tool` (`Required<ToolDefinition>`).
  */
 
+import { resolveExecutionTarget } from "./execution-target.js";
 import type {
   RiskLevel,
   Tool,
@@ -30,7 +31,10 @@ import type {
  *   are rejected at the JSON-schema layer.
  * - `executionTarget` defaults to `sandbox` — author-supplied tool code
  *   runs in the assistant container by default; opt in to `host` when
- *   the tool proxies work to the connected client.
+ *   the tool proxies work to the connected client. The name-prefix
+ *   heuristic (`host_*` / `computer_use_*` resolves to host) is applied
+ *   by `resolveExecutionTarget` in `finalizeTool`, so a tool named
+ *   `host_my_thing` defaults to host even without an explicit field.
  * - `category` defaults to empty — Slack channel `allowedToolCategories`
  *   policy denies uncategorized tools when a category allow-list is set,
  *   which is the correct deny-by-default for tools the author didn't
@@ -90,8 +94,10 @@ export function finalizeTool(tool: ToolDefinition, defaultName = ""): Tool {
           content: `tool ${name} has no execute implementation`,
           isError: true,
         });
-  const executionTarget = tool.executionTarget ?? TOOL_DEFAULTS.executionTarget;
+  const executionTarget =
+    tool.executionTarget ?? resolveExecutionTarget({ name });
   const category = tool.category ?? TOOL_DEFAULTS.category;
+  const exclusive = tool.exclusive ?? false;
   return {
     ...tool,
     name,
@@ -101,5 +107,6 @@ export function finalizeTool(tool: ToolDefinition, defaultName = ""): Tool {
     executionTarget,
     execute,
     category,
+    exclusive,
   };
 }

package/src/tools/tool-manifest.ts

@@ -18,6 +18,7 @@ import { runAuthenticatedCommandTool } from "./credential-execution/run-authenti
 import { fileEditTool } from "./filesystem/edit.js";
 import { fileListTool } from "./filesystem/list.js";
 import { fileReadTool } from "./filesystem/read.js";
+import { codeSearchTool } from "./filesystem/search.js";
 import { fileWriteTool } from "./filesystem/write.js";
 import { recallTool, rememberTool } from "./memory/register.js";
 import { webFetchTool } from "./network/web-fetch.js";
@@ -59,6 +60,7 @@ export const eagerModuleToolNames: string[] = [
   "file_write",
   "file_edit",
   "file_list",
+  "code_search",
   "web_search",
   "web_fetch",
   "skill_execute",
@@ -81,6 +83,7 @@ export const explicitTools: ToolDefinition[] = [
   fileWriteTool,
   fileEditTool,
   fileListTool,
+  codeSearchTool,
   webFetchTool,
   webSearchTool,
   skillExecuteTool,

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;
 }
@@ -449,6 +540,15 @@ export const ToolDefinitionSchema = z.object({
       ) => Promise<ToolExecutionResult>
     >()
     .optional(),
+  /**
+   * When true, this tool runs alone in its turn. If the model emits it
+   * alongside other tool calls, the agent loop executes only this one and
+   * defers the siblings — returning them un-run with a benign notice — so the
+   * model incorporates this tool's output before acting on anything else. The
+   * `advisor` tool sets this so its guidance lands before the agent commits to
+   * a path. Default false (the loop runs sibling calls concurrently as usual).
+   */
+  exclusive: z.boolean().optional(),
 });
 
 /**
@@ -460,8 +560,14 @@ export const ToolDefinitionSchema = z.object({
  */
 export type ToolDefinition = z.infer<typeof ToolDefinitionSchema>;
 
-/** Tool after the loader has derived its name and filled defaults. */
-export type Tool = Required<ToolDefinition>;
+/**
+ * Tool after the loader has derived its name and filled defaults. Every field
+ * is required except `exclusive`, which stays optional — most tools never set
+ * it, and the agent loop reads it as `?.exclusive === true`, so forcing every
+ * hand-built `Tool` (MCP/meet/test fixtures) to carry it would be noise.
+ */
+export type Tool = Required<Omit<ToolDefinition, "exclusive">> &
+  Pick<ToolDefinition, "exclusive">;
 
 /** The kind of extension that owns a tool. Core tools have no owner. */
 export type OwnerKind = "skill" | "mcp" | "plugin" | "workspace";