@vellumai/assistant 0.11.2 → 0.11.3-staging.2

package/src/tools/subagent/spawn.ts

@@ -2,13 +2,16 @@ import { z } from "zod";
 
 import type { AssistantEvent } from "../../api/index.js";
 import { validateInferenceProfileKey } from "../../config/inference-profile-validation.js";
-import { resolveDefaultProfileKey } from "../../config/llm-resolver.js";
 import { getConfig } from "../../config/loader.js";
+import { profileSupportsTools } from "../../config/profile-tool-support.js";
 import { findConversation } from "../../daemon/conversation-registry.js";
+import { getMessages } from "../../persistence/conversation-crud.js";
 import {
-  getConversationOverrideProfile,
-  getMessages,
-} from "../../persistence/conversation-crud.js";
+  countRecentSimilarSpawns,
+  normalizeSpawnObjective,
+  type RecentSimilarSpawns,
+  type SimilarSpawnTally,
+} from "../../persistence/subagent-store.js";
 import type { ContentBlock, Message } from "../../providers/types.js";
 import { buildAdvisorContext } from "../../subagent/consult-context.js";
 import {
@@ -20,7 +23,15 @@ import {
   getSubagentManager,
   SubagentAbortedError,
 } from "../../subagent/index.js";
-import type { SubagentRole } from "../../subagent/types.js";
+import {
+  type ResolvedSubagentRole,
+  resolveSubagentRole,
+} from "../../subagent/role-resolution.js";
+import {
+  SUBAGENT_OUTPUT_CONTRACTS,
+  type SubagentOutputContract,
+  type SubagentRole,
+} from "../../subagent/types.js";
 import { getLogger } from "../../util/logger.js";
 import {
   invalidToolInputResult,
@@ -33,11 +44,12 @@ 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.
+ * passes with NO sign of forward progress, meaning neither a streamed token
+ * (thinking or text) nor tool activity. 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;
 
@@ -49,6 +61,62 @@ const ADVISOR_IDLE_TIMEOUT_MS = 60_000;
  */
 const ADVISOR_MAX_TIMEOUT_MS = 300_000;
 
+/**
+ * Tool calls a single advisor consult may make before it is stopped and asked
+ * to answer with what it has.
+ *
+ * The consult BLOCKS the user-facing turn, and every tool call it makes
+ * re-arms the idle window, so a reading advisor is otherwise bounded only by
+ * the absolute backstop: five minutes of silence in the chat. A consult is
+ * meant to check a decisive fact or two, not to survey a codebase, so a handful
+ * of reads is the whole budget; past it the guidance written so far is worth
+ * more to the caller than the reads it was still queuing.
+ */
+const ADVISOR_MAX_TOOL_CALLS = 8;
+
+/** How far back the repeat-spawn guard looks for near-identical runs. */
+const LOOP_GUARD_WINDOW_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Near-identical runs one conversation may complete inside the window before
+ * the next spawn is held for confirmation. A couple of repeats is normal work;
+ * a fourth completed run of one objective in a single conversation is a loop.
+ * Runs that failed, were aborted, or were interrupted never count, so a retry
+ * after a bad run is not what trips this.
+ */
+const LOOP_GUARD_CONVERSATION_LIMIT = 3;
+
+/**
+ * Near-identical runs the whole assistant may complete inside the window,
+ * counted the same way. Higher than the per-conversation limit so the same
+ * audit asked for in a few separate chats still goes through, while a standing
+ * re-run of one objective does not.
+ */
+const LOOP_GUARD_ASSISTANT_LIMIT = 10;
+
+/**
+ * Near-identical runs one conversation may have IN FLIGHT before the next
+ * spawn is held. Lower than the completed limits because nothing has come back
+ * yet: a burst of copies fired before any of them finishes is the runaway shape
+ * the guard exists for, and the completed counts are blind to it for as long as
+ * the burst lasts.
+ */
+const LOOP_GUARD_IN_FLIGHT_CONVERSATION_LIMIT = 2;
+
+/** The same ceiling assistant-wide, scaled like the completed limits. */
+const LOOP_GUARD_IN_FLIGHT_ASSISTANT_LIMIT = 4;
+
+/**
+ * The tier a `verdict` spawn runs on when it names no `inference_profile`.
+ *
+ * Checking a criterion against evidence that already exists is mechanical:
+ * find the file, read the value, say PASS or FAIL. A premium model buys
+ * nothing there, and completion checks are frequent enough that paying
+ * investigation rates for them dominates delegated spend, so the contract that
+ * makes a spawn a check also picks the tier the check is worth.
+ */
+const VERDICT_PROFILE_KEY = "cost-optimized";
+
 /**
  * Model-input schema, `safeParse`d at the top of {@link executeSubagentSpawn}.
  * Same in-tool pattern and TOOLS.json drift guard as the other bundled-skill
@@ -56,15 +124,16 @@ const ADVISOR_MAX_TIMEOUT_MS = 300_000;
  * framework.
  *
  * `fork` / `send_result_to_user` (deliberate `=== true` / `!== false`
- * coercions) and `role` (SubagentManager.spawn's "Invalid subagent role"
- * error, asserted by tests, owns non-enum values) are deliberately
- * UNDECLARED — loose passthrough.
+ * coercions) and `role` (any string resolves, see `resolveSubagentRole`) are
+ * deliberately UNDECLARED: loose passthrough.
  */
 export const subagentSpawnInputSchema = z.looseObject({
   label: nullAsOmitted(z.string()),
   objective: nullAsOmitted(z.string()),
   context: nullAsOmitted(z.string()),
   inference_profile: z.string().optional(),
+  confirm_repeat: nullAsOmitted(z.boolean()),
+  output_contract: nullAsOmitted(z.enum(SUBAGENT_OUTPUT_CONTRACTS)),
 });
 
 export async function executeSubagentSpawn(
@@ -81,8 +150,13 @@ export async function executeSubagentSpawn(
   const objective = parsed.objective;
   const extraContext = parsed.context;
   const fork = input.fork === true;
-  const role = (input.role as string | undefined) ?? undefined;
+  const requestedRole =
+    typeof input.role === "string" && input.role.trim().length > 0
+      ? input.role
+      : undefined;
+  const resolvedRole = resolveSubagentRole(requestedRole);
   const inferenceProfile = parsed.inference_profile;
+  const outputContract = parsed.output_contract;
 
   // For fork mode, sendResultToUser defaults to false unless explicitly set to true.
   // For regular mode, sendResultToUser defaults to true (existing behavior).
@@ -97,6 +171,11 @@ export async function executeSubagentSpawn(
     };
   }
 
+  const contractError = outputContractError(outputContract, resolvedRole.role);
+  if (contractError) {
+    return { content: contractError, isError: true };
+  }
+
   let requestedOverrideProfile: string | undefined;
   let forceOverrideProfile = false;
   if (inferenceProfile !== undefined) {
@@ -122,10 +201,10 @@ export async function executeSubagentSpawn(
     };
   }
 
-  // ── Advisor role: synchronous, tool-less, stronger-model consult ──
+  // ── Advisor role: synchronous, read-only, 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") {
+  if (resolvedRole.role === "advisor") {
     return runAdvisorConsult({
       context,
       label,
@@ -135,6 +214,21 @@ export async function executeSubagentSpawn(
     });
   }
 
+  // ── Repeat-spawn guard ───────────────────────────────────────────
+  // Re-running an objective that already completed several times in the last
+  // day buys the same answer twice, so the guard hands the repetition back to
+  // the caller with what it has already cost. It never blocks: `confirm_repeat`
+  // always spawns, and the advisor consult returned above is never guarded.
+  if (parsed.confirm_repeat !== true) {
+    const guardResult = repeatSpawnGuardResult(
+      context.conversationId,
+      objective,
+    );
+    if (guardResult) {
+      return guardResult;
+    }
+  }
+
   // ── Fork mode: resolve parent context ────────────────────────────
   let forkFields:
     | {
@@ -165,43 +259,52 @@ export async function executeSubagentSpawn(
     };
   }
 
-  // The subagent runs as its own background conversation, so the agent
-  // loop's background-skip rule would zero out any inherited profile.
-  // Forward the invoker's profile explicitly via `SubagentConfig` so
-  // `SubagentManager.spawn` passes it into the subagent's `runAgentLoop` as
-  // `options.overrideProfile`.
+  // A subagent resolves the `subagentSpawn` call site's own default profile.
+  // A profile pinned on a conversation is a choice about that conversation,
+  // not about the work it delegates, and carrying it into a child would apply
+  // the pinned model's price and its tool-calling reliability to every spawn
+  // the turn makes.
   //
-  // Resolution order: an explicit spawn-time profile, then the per-turn
-  // `context.overrideProfile` (populated by `runAgentLoopImpl` from its
-  // resolved `turnOverrideProfile`, covering per-conversation overrides and
-  // tool-routed switches), then a row read, and finally the resolved DEFAULT
-  // profile of the call site that invoked us. That last fallback is what makes
-  // a subagent match its invoker when the invoking turn ran purely on its
-  // call-site default — the workspace `activeProfile` for `mainAgent`, or the
-  // call site's own winning default (a `llm.callSites.<callSite>` pin or the
-  // catalog intent, e.g. `cost-optimized`) for a heartbeat/background
-  // invoker (`resolveDefaultProfileKey` runs the same winner selection as
-  // dispatch, minus a per-turn override).
+  // Landing on the call site's own profile means passing NO override: the
+  // child already runs its loop under `callSite: "subagentSpawn"`, so the
+  // resolver picks that profile on its own. Passing it explicitly would select
+  // the same model but register as an override, and `resolveUsageAttribution`
+  // classifies an override winner as `conversation`, which would file every
+  // subagent's spend under a pin the caller never set and break the call-site
+  // breakdown this telemetry exists for.
   //
-  // An explicit `llm.callSites.subagentSpawn` profile must still win over
-  // the invoker-default tier: that tier is a matching heuristic, not a user
-  // choice, and any override outranks the call-site pin under single-winner
-  // resolution — so the heuristic is only forwarded when no explicit pin
-  // exists. An explicit `inference_profile` argument keeps
-  // `forceOverrideProfile` and wins outright; the row read short-circuits
-  // to `undefined` for the background subagent conversation and for tool
-  // calls outside an agent-loop turn.
+  // An explicit `inference_profile` argument keeps `forceOverrideProfile` and
+  // wins outright, unless the catalog states it cannot call tools, in which
+  // case it falls back to the same default with a note on the result.
+  const config = getConfig();
+  const llm = config.llm;
+
+  let profileNote: string | undefined;
   let inheritedOverrideProfile = requestedOverrideProfile;
   if (inheritedOverrideProfile === undefined) {
-    const llm = getConfig().llm;
-    inheritedOverrideProfile =
-      context.overrideProfile ??
-      getConversationOverrideProfile(context.conversationId) ??
-      (llm.callSites?.subagentSpawn?.profile == null
-        ? resolveDefaultProfileKey(context.invokingCallSite ?? "mainAgent", llm)
-        : undefined);
+    if (outputContract === "verdict") {
+      // A verdict is a check rather than an investigation, so it takes the
+      // cheap tier. The tier is this tool's preset, not a caller's choice, and
+      // an override outranks a call site's own profile under single-winner
+      // resolution, so the preset is only applied when the user pinned
+      // nothing: with an explicit `llm.callSites.subagentSpawn` profile the
+      // field is left unset and that pin wins. An `inference_profile` argument
+      // beats both and never enters this branch at all.
+      inheritedOverrideProfile =
+        llm.callSites?.subagentSpawn?.profile == null
+          ? VERDICT_PROFILE_KEY
+          : undefined;
+    }
+    // Every other spawn leaves this unset, which is what lands it on the
+    // subagentSpawn default rather than anything the parent turn was pinned to.
+  } else if (profileSupportsTools(inheritedOverrideProfile, config) === false) {
+    profileNote = `requested profile "${inheritedOverrideProfile}" is not verified for tool calling; ran on the default profile instead.`;
+    inheritedOverrideProfile = undefined;
+    forceOverrideProfile = false;
   }
 
+  const roleNote = resolvedRoleNote(resolvedRole);
+
   try {
     const subagentId = await manager.spawn(
       {
@@ -210,13 +313,28 @@ export async function executeSubagentSpawn(
         objective,
         context: extraContext,
         sendResultToUser,
-        // 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 } : {}),
+        // The resolved type is passed for every spawn, fork included: a fork
+        // that named no role resolves to `builder`, which imposes no
+        // allowlist, so it keeps the parent's tool surface, which is what the
+        // system prompt it inherits describes. The advisor is special-cased
+        // earlier via runAdvisorConsult, not here.
+        role: resolvedRole.role,
+        ...(resolvedRole.personaText
+          ? { persona: resolvedRole.personaText }
+          : {}),
+        ...(outputContract ? { outputContract } : {}),
+        // Declare the spawn mode so delegated LLM spend is separable in
+        // telemetry: every variety shares `llm_call_site = "subagentSpawn"`,
+        // and a fork's inherited transcript costs very differently from a
+        // fresh objective-only spawn.
+        spawnMode: fork ? "fork" : "regular",
         ...(inheritedOverrideProfile
           ? { overrideProfile: inheritedOverrideProfile }
           : {}),
         ...(forceOverrideProfile ? { forceOverrideProfile: true } : {}),
+        // Delegated work belongs to the firing that triggered the invoking
+        // turn, so the child's usage rows carry the parent's stamp.
+        ...(context.cronRunId ? { cronRunId: context.cronRunId } : {}),
         ...(context.toolUseId ? { parentToolUseId: context.toolUseId } : {}),
         ...forkFields,
       },
@@ -228,7 +346,10 @@ export async function executeSubagentSpawn(
         subagentId,
         label,
         status: "pending",
+        role: resolvedRole.role,
         ...(fork ? { isFork: true } : {}),
+        ...(profileNote ? { note: profileNote } : {}),
+        ...(roleNote ? { roleNote } : {}),
         message: fork
           ? `Forked subagent "${label}" spawned with full parent context. You will be notified automatically when it completes or fails - do NOT poll subagent_status. Continue the conversation normally.`
           : `Subagent "${label}" spawned. You will be notified automatically when it completes or fails - do NOT poll subagent_status. Continue the conversation normally.`,
@@ -241,6 +362,181 @@ export async function executeSubagentSpawn(
   }
 }
 
+// ── Output contract ──────────────────────────────────────────────────
+
+/**
+ * Why the requested `output_contract` cannot run under the type this spawn
+ * resolved to, or `undefined` when the pairing is fine.
+ *
+ * The two non-default contracts each need a capability only one type has: a
+ * verdict is a claim about what already exists, which is the read-only
+ * researcher's job, and an artifact has to be written, which only a builder
+ * can do. The advisor takes no contract at all: it is a blocking consult that
+ * returns guidance in its own framing, and its child never sees a built system
+ * prompt or fork framing to render one into. That includes an explicit
+ * `report`, which is checked against the advisor before it is waved through as
+ * the default everywhere else: the caller asked for a shape the consult cannot
+ * produce, and only an omitted contract means it never asked.
+ *
+ * Mismatches are rejected rather than coerced. Silently promoting a verdict
+ * spawn to a builder would hand out write access the caller never asked for,
+ * and silently demoting one to a report would return prose where the caller
+ * expected pass/fail. Either way the caller is the only one who can say which
+ * half of its request was the mistake.
+ */
+function outputContractError(
+  contract: SubagentOutputContract | undefined,
+  role: SubagentRole,
+): string | undefined {
+  if (contract === undefined) {
+    return undefined;
+  }
+  if (role === "advisor") {
+    return (
+      `output_contract "${contract}" does not apply to the advisor: it is a blocking consult that returns guidance in its own shape. ` +
+      'Drop output_contract, or spawn role "researcher" with output_contract "verdict" to have work checked.'
+    );
+  }
+  if (contract === "report") {
+    return undefined;
+  }
+  if (contract === "verdict" && role !== "researcher") {
+    return (
+      `output_contract "verdict" is only available to researcher-typed subagents, and this spawn resolved to "${role}". ` +
+      'Spawn it with role "researcher" to get an evidence-backed PASS/FAIL check, or drop output_contract to get a report.'
+    );
+  }
+  if (contract === "artifact" && role !== "builder") {
+    return (
+      `output_contract "artifact" is only available to builder-typed subagents, and this spawn resolved to "${role}". ` +
+      'Spawn it with role "builder" so it can actually produce the artifact, or drop output_contract to get a report.'
+    );
+  }
+  return undefined;
+}
+
+// ── Role resolution ──────────────────────────────────────────────────
+
+/**
+ * What to tell the parent about how its `role` was read, or `undefined` when
+ * the requested role was a type name and nothing needs saying.
+ *
+ * The parent chose the role, so a silent substitution is the one outcome to
+ * avoid: an alias and a persona fallback both change what the child can do,
+ * and only the parent can decide whether that is what it wanted.
+ */
+function resolvedRoleNote(resolved: ResolvedSubagentRole): string | undefined {
+  if (resolved.alias) {
+    return `Role "${resolved.alias}" is an older name for "${resolved.role}"; the subagent runs with the ${resolved.role} toolset.`;
+  }
+  if (resolved.personaText) {
+    return (
+      `Role "${resolved.personaText}" is not a subagent type, so it was used as a persona and the subagent runs as a researcher: ` +
+      'read-only, no shell. If the task has to write files or run commands, re-spawn it with role "builder".'
+    );
+  }
+  return undefined;
+}
+
+// ── Repeat-spawn guard ───────────────────────────────────────────────
+
+/**
+ * The result to return instead of spawning when this objective has already run
+ * too often inside {@link LOOP_GUARD_WINDOW_MS}, or `undefined` when the spawn
+ * should proceed.
+ *
+ * Two shapes of repetition are held, and they are told apart because the caller
+ * has to do something different about each. Completed runs mean an answer
+ * exists, so the caller is pointed at it. In-flight runs mean copies of this
+ * work are executing right now with nothing to show yet, which is the runaway
+ * loop the guard is for: a burst issued faster than anything can finish is
+ * invisible to the completed counts for its whole duration. Runs that ended
+ * without an answer count as neither, so a retry after a failure is never held.
+ *
+ * Not an error: the caller is being handed what its earlier runs produced and
+ * cost, and can still spawn by passing `confirm_repeat: true`. The spawn
+ * history can only advise, so a failed read lets the spawn through.
+ */
+function repeatSpawnGuardResult(
+  parentConversationId: string,
+  objective: string,
+): ToolExecutionResult | undefined {
+  let recent: RecentSimilarSpawns;
+  try {
+    recent = countRecentSimilarSpawns({
+      parentConversationId,
+      normalizedObjective: normalizeSpawnObjective(objective),
+      sinceMs: Date.now() - LOOP_GUARD_WINDOW_MS,
+    });
+  } catch (err) {
+    log.warn(
+      { err, conversationId: parentConversationId },
+      "Repeat-spawn guard could not read spawn history",
+    );
+    return undefined;
+  }
+
+  // The spawn being asked for is itself part of the limit, so a window whose
+  // runs already fill the allowance is what trips the guard. Completed runs are
+  // checked first: when both shapes are present, an answer that already exists
+  // is the more actionable thing to hand back.
+  let scope: string;
+  let tally: SimilarSpawnTally;
+  if (recent.conversation.count >= LOOP_GUARD_CONVERSATION_LIMIT) {
+    scope = "in this conversation";
+    tally = recent.conversation;
+  } else if (recent.assistant.count >= LOOP_GUARD_ASSISTANT_LIMIT) {
+    scope = "across this assistant";
+    tally = recent.assistant;
+  } else if (
+    recent.conversation.inFlight >= LOOP_GUARD_IN_FLIGHT_CONVERSATION_LIMIT
+  ) {
+    return inFlightGuardResult(
+      recent.conversation.inFlight,
+      "this conversation",
+    );
+  } else if (
+    recent.assistant.inFlight >= LOOP_GUARD_IN_FLIGHT_ASSISTANT_LIMIT
+  ) {
+    return inFlightGuardResult(recent.assistant.inFlight, "this assistant");
+  } else {
+    return undefined;
+  }
+
+  const hours = LOOP_GUARD_WINDOW_MS / 3_600_000;
+  const cost =
+    tally.estimatedCost > 0
+      ? `, at a total cost of about $${tally.estimatedCost.toFixed(2)}`
+      : "";
+  return {
+    content:
+      `${tally.count} near-identical subagents already completed ${scope} in the last ${hours} hours${cost}. ` +
+      "Repeating an objective rarely returns a different answer: read what the earlier run produced with subagent_read, " +
+      "or narrow the objective to what is actually still missing. " +
+      "If the repetition is intentional, call subagent_spawn again with confirm_repeat: true.",
+    isError: false,
+  };
+}
+
+/**
+ * The result handed back when copies of this objective are still executing.
+ * Says explicitly that there is nothing to read yet, so the caller waits for
+ * the running work instead of being sent after results that do not exist.
+ */
+function inFlightGuardResult(
+  inFlight: number,
+  scope: string,
+): ToolExecutionResult {
+  return {
+    content:
+      `${inFlight} near-identical subagents are already running in ${scope}, and none of them has returned yet. ` +
+      "Another copy would repeat work that is in progress: wait for the running ones to report back, " +
+      "or narrow the objective to the part they are not covering. " +
+      "If the repetition is intentional, call subagent_spawn again with confirm_repeat: true.",
+    isError: false,
+  };
+}
+
 // ── Advisor consult ──────────────────────────────────────────────────
 
 /**
@@ -248,15 +544,20 @@ export async function executeSubagentSpawn(
  * 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).
+ * `buildAdvisorSystem`, and runs on `llm.advisorProfile` (unless the caller
+ * passed an explicit `inference_profile`) under both the advisor role allowlist
+ * and `denySideEffectTools`, so the only tools it can reach are the first-party
+ * built-in readers. It is bounded on two axes, because the consult holds up the
+ * user-facing turn while it runs: a progress-aware deadline (an idle window,
+ * `ADVISOR_IDLE_TIMEOUT_MS`, reset on every streamed token and every tool event
+ * so a reasoning or reading model isn't killed mid-consult, plus an absolute
+ * `ADVISOR_MAX_TIMEOUT_MS` backstop), and a ceiling of `ADVISOR_MAX_TOOL_CALLS`
+ * tool calls, since tool activity re-arms the idle window and a reading consult
+ * would otherwise be bounded only by the backstop. Whichever ceiling is hit, the
+ * partial guidance produced so far is recovered and returned with a note saying
+ * what cut it short, 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;
@@ -269,6 +570,11 @@ async function runAdvisorConsult(args: {
   const { context, label, objective, sendToClient, requestedOverrideProfile } =
     args;
 
+  /** Set when the consult is stopped for reading past its tool ceiling. */
+  let stoppedForToolCap = false;
+  /** Appended to the guidance when the consult did not run as asked for. */
+  let profileNote: string | undefined;
+
   try {
     const parentConversation = findConversation(context.conversationId);
     if (!parentConversation) {
@@ -313,24 +619,76 @@ async function runAdvisorConsult(args: {
 
     // 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 config = getConfig();
+    let overrideProfile = requestedOverrideProfile ?? config.llm.advisorProfile;
+    // The advisor carries read tools, so a profile the catalog states cannot
+    // call them is handed a surface it can never use and answers from the
+    // transcript alone. Fall back to the call site's own default and say so
+    // alongside the guidance, the way a regular spawn reports it. The check is
+    // unconditional, matching the tools it protects, and only a catalog `false`
+    // redirects, so a model the catalog has never heard of is left alone.
+    if (
+      overrideProfile !== undefined &&
+      profileSupportsTools(overrideProfile, config) === false
+    ) {
+      profileNote = `profile "${overrideProfile}" is not verified for tool calling; the advisor ran on the default profile instead.`;
+      // Clearing this is what lands the consult on the subagentSpawn default:
+      // the child runs under that call site, so the resolver picks it anyway.
+      // Naming it would select the same model but register as an override,
+      // which usage attribution reports as a conversation pin, filing a consult
+      // that merely fell back against a pin nobody set.
+      overrideProfile = undefined;
+    }
     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.
+    // Progress-aware deadline: reset on every sign of forward progress so the
+    // consult isn't killed mid-thought or mid-read, 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 => {
+    // Tool ceiling, on its own controller so the abort is attributable: the
+    // consult is stopped for reading too much, which reads back to the caller
+    // differently from running out of time.
+    const toolCap = new AbortController();
+    const signal = AbortSignal.any(
+      context.signal
+        ? [context.signal, deadline.signal, toolCap.signal]
+        : [deadline.signal, toolCap.signal],
+    );
+    // Count the child's tool calls off its own event stream. Each executed call
+    // emits exactly one `tool_use_start`, enveloped by the manager as a
+    // `subagent_event` on its way to the parent's client. The budget is spent
+    // in full before the abort fires: the call that trips it is the one past
+    // `ADVISOR_MAX_TOOL_CALLS`, so the consult keeps every result inside the
+    // budget and loses only the call it was starting.
+    let toolCalls = 0;
+    const countingSendToClient = (msg: AssistantEvent): void => {
+      sendToClient(msg);
+      if (!isAdvisorToolCallEvent(msg) || toolCap.signal.aborted) {
+        return;
+      }
+      toolCalls += 1;
+      if (toolCalls > ADVISOR_MAX_TOOL_CALLS) {
+        stoppedForToolCap = true;
+        log.warn(
+          { conversationId: context.conversationId, toolCalls },
+          "Advisor consult exceeded its tool ceiling; returning guidance so far",
+        );
+        toolCap.abort();
+      }
+    };
+    // Streamed tokens AND tool activity both count as progress. A consult that
+    // opens a file emits no token while the read runs, so token-only progress
+    // would let the idle window lapse on a healthy advisor and abort it before
+    // the model ever sees its tool result. The absolute backstop is untouched,
+    // so a stalled tool cannot extend the consult past `ADVISOR_MAX_TIMEOUT_MS`.
+    const onProgress = (): void => {
       deadline.recordProgress();
+    };
+    // Streamed chunks additionally forward to the caller's stream sink.
+    const onText = (chunk: string): void => {
       context.onOutput?.(chunk);
     };
 
@@ -349,39 +707,74 @@ async function runAdvisorConsult(args: {
           sendResultToUser: false,
           role: "advisor",
           fork: true,
+          // The advisor's read-only guarantee cannot rest on tool NAMES. A
+          // workspace tool may register under `file_read` (registerWorkspaceTools
+          // stashes the built-in and installs its own implementation), and a
+          // name-only role allowlist would hand the advisor that implementation
+          // to execute. The owner-aware read-only gate that closes this comes
+          // from `denySideEffects` on the advisor's registry entry, so every
+          // path that projects the role applies it, this spawn and the
+          // `tools list --agent advisor` preview alike.
+          //
+          // The advisor is a ROLE, not an `LLMCallSiteEnum` value, so its usage
+          // lands under `subagentSpawn` like any other subagent. This is what
+          // makes advisor consults separable from regular forks in telemetry.
+          spawnMode: "advisor_consult",
           parentMessages: sanitizedMessages,
           systemPromptOverride: buildAdvisorSystem(parentSystemPrompt),
           ...(overrideProfile ? { overrideProfile } : {}),
           ...(forceOverrideProfile ? { forceOverrideProfile: true } : {}),
+          // A consult is delegated work of the invoking turn, so its spend
+          // attributes to the same firing.
+          ...(context.cronRunId ? { cronRunId: context.cronRunId } : {}),
           ...(context.toolUseId ? { parentToolUseId: context.toolUseId } : {}),
         },
-        sendToClient,
-        { signal, onText },
+        countingSendToClient,
+        { signal, onText, onProgress },
       );
 
       const trimmed = advice.trim();
       return {
-        content:
+        content: withAdvisorNote(
           trimmed.length > 0 ? trimmed : "(advisor returned no guidance)",
+          profileNote,
+        ),
         isError: false,
       };
     } finally {
       deadline.dispose();
     }
   } catch (err) {
-    // Timed out mid-generation: salvage whatever guidance the advisor had
+    // Cut short 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.
+    // slow reasoning profile that needs most of the window to think. The note
+    // names which ceiling stopped it, because "it ran out of time" and "it was
+    // still reading" call for different follow-ups from the caller.
     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",
+          { conversationId: context.conversationId, stoppedForToolCap },
+          "Advisor consult was cut short; returning partial guidance",
         );
         return {
-          content: `${partial}\n\n_(The advisor reached its time limit while still writing — the guidance above may be cut off.)_`,
+          content: withAdvisorNote(
+            partial,
+            stoppedForToolCap
+              ? `The advisor used its full budget of ${ADVISOR_MAX_TOOL_CALLS} tool calls and answered with what it had read, so the guidance above may be incomplete.`
+              : "The advisor reached its time limit while still writing, so the guidance above may be cut off.",
+            profileNote,
+          ),
+          isError: false,
+        };
+      }
+      if (stoppedForToolCap) {
+        return {
+          content: withAdvisorNote(
+            `(advisor used its full budget of ${ADVISOR_MAX_TOOL_CALLS} tool calls without writing any guidance: narrow the question, or point it at the specific file or decision you want checked)`,
+            profileNote,
+          ),
           isError: false,
         };
       }
@@ -396,6 +789,35 @@ async function runAdvisorConsult(args: {
   }
 }
 
+/**
+ * Whether a parent-bound event is a child tool call starting. The manager
+ * envelopes every child event as `subagent_event`, so the consult reads the
+ * inner event to see what the advisor is doing.
+ */
+function isAdvisorToolCallEvent(msg: AssistantEvent): boolean {
+  if (msg.type !== "subagent_event") {
+    return false;
+  }
+  const inner = (msg as { event?: { type?: string } }).event;
+  return inner?.type === "tool_use_start";
+}
+
+/**
+ * The guidance with any notes about how the consult actually ran appended
+ * below it. Notes are italicized asides so the guidance itself stays the
+ * result; nothing is appended when there is nothing to say.
+ */
+function withAdvisorNote(
+  guidance: string,
+  ...notes: (string | undefined)[]
+): string {
+  const present = notes.filter((note): note is string => Boolean(note));
+  if (present.length === 0) {
+    return guidance;
+  }
+  return `${guidance}\n\n${present.map((note) => `_(${note})_`).join("\n")}`;
+}
+
 /**
  * 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