@vellumai/assistant 0.11.2 → 0.11.3-dev.202608080427.92f668a

package/src/__tests__/subagent-manager-notify.test.ts

@@ -52,9 +52,16 @@ interface FakeManagedSubagent {
       estimatedCost: number;
     };
     subagentDeniedToolNames: Set<string>;
+    subagentToolStats: {
+      calls: number;
+      succeeded: number;
+      filesWritten: Set<string>;
+    };
   } | null;
   state: SubagentState;
   parentSendToClient: (msg: AssistantEvent) => void;
+  /** Sticky marker that a follow-up turn was queued during the run. */
+  hadEnqueuedMessages?: boolean;
 }
 
 /** Type-safe accessor for SubagentManager's private internals via bracket notation. */
@@ -62,6 +69,7 @@ interface ManagerInternals {
   subagents: Map<string, FakeManagedSubagent>;
   parentToChildren: Map<string, Set<string>>;
   runSubagent: (subagentId: string, objective: string) => Promise<void>;
+  releaseConversation: (managed: FakeManagedSubagent) => void;
   stopSweep: () => void;
 }
 
@@ -86,6 +94,11 @@ function injectFakeSubagent(
     sendToClient: () => {},
     usageStats: { inputTokens: 100, outputTokens: 50, estimatedCost: 0.005 },
     subagentDeniedToolNames: new Set<string>(),
+    subagentToolStats: {
+      calls: 0,
+      succeeded: 0,
+      filesWritten: new Set<string>(),
+    },
   };
 
   const internals = asInternals(manager);
@@ -359,6 +372,141 @@ describe("SubagentManager notifyParent (via runSubagent)", () => {
     asInternals(manager).stopSweep();
   });
 
+  test("a settled run's notification carries what it actually ran", async () => {
+    clearCaptured();
+    const manager = new SubagentManager();
+    const subagentId = "sub-stats";
+    const state = makeState(subagentId);
+    injectFakeSubagent(manager, subagentId, state);
+
+    const managed = asInternals(manager).subagents.get(subagentId)!;
+    managed.conversation!.persistUserMessage = () => ({
+      id: "msg-1",
+      deduplicated: false,
+    });
+    managed.conversation!.runAgentLoop = async () => {
+      const counters = managed.conversation!.subagentToolStats;
+      counters.calls += 2;
+      counters.succeeded += 2;
+      counters.filesWritten.add("/report.md");
+    };
+
+    await asInternals(manager).runSubagent(subagentId, "Do something");
+
+    expect(capturedNotifications[0].message).toContain(
+      "[stats: 2 tool calls, 2 succeeded, files written via file_write/file_edit: 1]",
+    );
+
+    asInternals(manager).stopSweep();
+  });
+
+  test("a queued follow-up turn's tool calls reach the reported stats", async () => {
+    clearCaptured();
+    const manager = new SubagentManager();
+    const subagentId = "sub-queued-stats";
+    const state = makeState(subagentId);
+    injectFakeSubagent(manager, subagentId, state);
+
+    const managed = asInternals(manager).subagents.get(subagentId)!;
+    managed.conversation!.persistUserMessage = () => ({
+      id: "msg-1",
+      deduplicated: false,
+    });
+    managed.conversation!.runAgentLoop = async () => {
+      const counters = managed.conversation!.subagentToolStats;
+      counters.calls += 2;
+      counters.succeeded += 2;
+    };
+    // Guidance arrived while the run was processing: the conversation is
+    // retained past the run so it can drain that turn afterwards.
+    managed.hadEnqueuedMessages = true;
+
+    await asInternals(manager).runSubagent(subagentId, "Do something");
+
+    // The run's own harvest only ever sees its own calls.
+    expect(state.stats).toEqual({ calls: 2, succeeded: 2, filesWritten: 0 });
+    // Quoting it in a message that is never rewritten would under-report the
+    // queued turn permanently, so the deferred notification quotes nothing and
+    // sends the parent to subagent_read instead.
+    expect(capturedNotifications[0].message).toContain(
+      "Queued follow-up guidance is still being processed",
+    );
+    expect(capturedNotifications[0].message).not.toContain("[stats:");
+
+    // The queued turn now drains, into the same retained conversation.
+    const counters = managed.conversation!.subagentToolStats;
+    counters.calls += 3;
+    counters.succeeded += 2;
+    counters.filesWritten.add("/queued-turn.md");
+
+    expect(manager.currentToolStats(subagentId)).toEqual({
+      kind: "counted",
+      stats: { calls: 5, succeeded: 4, filesWritten: 1 },
+    });
+
+    asInternals(manager).stopSweep();
+  });
+
+  test("releasing the conversation freezes the settled counters", async () => {
+    clearCaptured();
+    const manager = new SubagentManager();
+    const subagentId = "sub-release-stats";
+    const state = makeState(subagentId);
+    injectFakeSubagent(manager, subagentId, state);
+
+    const managed = asInternals(manager).subagents.get(subagentId)!;
+    managed.conversation!.persistUserMessage = () => ({
+      id: "msg-1",
+      deduplicated: false,
+    });
+    managed.conversation!.runAgentLoop = async () => {
+      managed.conversation!.subagentToolStats.calls += 1;
+      managed.conversation!.subagentToolStats.succeeded += 1;
+    };
+    managed.hadEnqueuedMessages = true;
+
+    await asInternals(manager).runSubagent(subagentId, "Do something");
+
+    const counters = managed.conversation!.subagentToolStats;
+    counters.calls += 4;
+    counters.succeeded += 3;
+
+    // The sweep releases the retained conversation once the drain has had its
+    // window; the last reading is taken on the way out and stands afterwards.
+    asInternals(manager).releaseConversation(managed);
+
+    expect(managed.conversation).toBeNull();
+    expect(manager.currentToolStats(subagentId)).toEqual({
+      kind: "counted",
+      stats: { calls: 5, succeeded: 4, filesWritten: 0 },
+    });
+
+    asInternals(manager).stopSweep();
+  });
+
+  test("a run that never harvested reports nothing rather than a zero", () => {
+    const manager = new SubagentManager();
+    const subagentId = "sub-unharvested";
+    injectFakeSubagent(manager, subagentId, makeState(subagentId));
+
+    // Still running: its counters are mid-flight, and a zero read off them now
+    // would read as "this subagent used no tools".
+    expect(manager.currentToolStats(subagentId)).toEqual({
+      kind: "unmeasured",
+    });
+  });
+
+  test("an id the manager never held reports its counters unrecoverable", () => {
+    const manager = new SubagentManager();
+
+    // The counters exist nowhere but memory, so a caller holding a
+    // record-derived state for this id can never get them, and reporting zero
+    // calls would read as "this subagent did nothing".
+    expect(manager.currentToolStats("sub-not-in-manager")).toEqual({
+      kind: "unrecoverable",
+    });
+  });
+
   test("failed subagent does not notify if already aborted", async () => {
     clearCaptured();
     const manager = new SubagentManager();

package/src/__tests__/subagent-notify-parent.test.ts

@@ -113,7 +113,7 @@ function seedSubagent(
     conversationId,
     label: "Test",
     objective: "test",
-    role: "general",
+    role: "builder",
     isFork: false,
     sendResultToUser: null,
     parentToolUseId: null,

package/src/__tests__/subagent-persistence.test.ts

@@ -5,10 +5,12 @@ import { migrateCreateSubagentsTable } from "../persistence/migrations/311-creat
 import { migrateAddSubagentParentToolUseId } from "../persistence/migrations/356-add-subagent-parent-tool-use-id.js";
 import { resetTestTables } from "../persistence/raw-query.js";
 import {
+  countRecentSimilarSpawns,
   deleteSubagentRecordsByParent,
   getSubagentRecordById,
   getSubagentRecordByLabel,
   loadAllSubagentRecords,
+  normalizeSpawnObjective,
   type SubagentRecord,
   upsertSubagentRecord,
 } from "../persistence/subagent-store.js";
@@ -134,6 +136,145 @@ describe("subagent-store", () => {
   });
 });
 
+describe("recent similar spawn tallies", () => {
+  const OBJECTIVE = "Audit the billing pipeline for drift";
+
+  /** A completed row for `OBJECTIVE`, spelled however the caller wants it. */
+  function spawn(
+    id: string,
+    over: Partial<SubagentRecord> = {},
+  ): SubagentRecord {
+    return record({
+      id,
+      conversationId: `conv-${id}`,
+      objective: OBJECTIVE,
+      status: "completed",
+      createdAt: Date.now(),
+      completedAt: Date.now(),
+      estimatedCost: 0.5,
+      ...over,
+    });
+  }
+
+  function tally(parentConversationId = "parent-1") {
+    return countRecentSimilarSpawns({
+      parentConversationId,
+      normalizedObjective: normalizeSpawnObjective(OBJECTIVE),
+      sinceMs: Date.now() - 24 * 60 * 60 * 1000,
+    });
+  }
+
+  test("normalization folds case and whitespace over the whole objective", () => {
+    expect(normalizeSpawnObjective("  Audit   the\nBILLING pipeline ")).toBe(
+      "audit the billing pipeline",
+    );
+    expect(normalizeSpawnObjective("x".repeat(200))).toHaveLength(200);
+  });
+
+  test("counts both scopes and sums their cost", () => {
+    upsertSubagentRecord(spawn("a"));
+    upsertSubagentRecord(
+      spawn("b", { objective: "  AUDIT the Billing\tpipeline for drift  " }),
+    );
+    upsertSubagentRecord(spawn("c", { parentConversationId: "parent-2" }));
+
+    expect(tally()).toEqual({
+      conversation: { count: 2, estimatedCost: 1, inFlight: 0 },
+      assistant: { count: 3, estimatedCost: 1.5, inFlight: 0 },
+    });
+  });
+
+  test("a genuinely different objective is not a match", () => {
+    upsertSubagentRecord(spawn("a"));
+    upsertSubagentRecord(
+      spawn("b", { objective: "Audit the payouts pipeline for drift" }),
+    );
+
+    expect(tally().conversation.count).toBe(1);
+  });
+
+  test("a shared boilerplate prefix does not fold distinct objectives together", () => {
+    const preamble =
+      "Follow the audit checklist to the letter and report ".repeat(3);
+    upsertSubagentRecord(
+      spawn("a", { objective: `${preamble} on the billing service` }),
+    );
+    upsertSubagentRecord(
+      spawn("b", { objective: `${preamble} on the payouts service` }),
+    );
+
+    const forBilling = countRecentSimilarSpawns({
+      parentConversationId: "parent-1",
+      normalizedObjective: normalizeSpawnObjective(
+        `${preamble} on the billing service`,
+      ),
+      sinceMs: Date.now() - 24 * 60 * 60 * 1000,
+    });
+
+    expect(forBilling.conversation.count).toBe(1);
+  });
+
+  test("the same objective still matches however long its preamble", () => {
+    const objective = `${"e".repeat(200)} tail`;
+    upsertSubagentRecord(spawn("a", { objective }));
+    upsertSubagentRecord(spawn("b", { objective: `  ${objective}  ` }));
+
+    expect(
+      countRecentSimilarSpawns({
+        parentConversationId: "parent-1",
+        normalizedObjective: normalizeSpawnObjective(objective),
+        sinceMs: Date.now() - 24 * 60 * 60 * 1000,
+      }).conversation.count,
+    ).toBe(2);
+  });
+
+  test("spawns older than the cutoff and advisor consults are left out", () => {
+    upsertSubagentRecord(spawn("fresh"));
+    upsertSubagentRecord(
+      spawn("stale", { createdAt: Date.now() - 90_000_000 }),
+    );
+    upsertSubagentRecord(spawn("consult", { role: "advisor" }));
+
+    expect(tally().assistant.count).toBe(1);
+  });
+
+  test("runs that ended without an answer are left out of both scopes", () => {
+    upsertSubagentRecord(spawn("done"));
+    for (const status of ["failed", "aborted", "interrupted"]) {
+      upsertSubagentRecord(
+        spawn(`ended-${status}`, { status, completedAt: Date.now() }),
+      );
+    }
+
+    expect(tally()).toEqual({
+      conversation: { count: 1, estimatedCost: 0.5, inFlight: 0 },
+      assistant: { count: 1, estimatedCost: 0.5, inFlight: 0 },
+    });
+  });
+
+  test("runs still under way are tallied apart from completed ones", () => {
+    // The burst shape the loop guard exists for: copies fired faster than any
+    // of them can finish are invisible to a completed-only count.
+    upsertSubagentRecord(spawn("done"));
+    upsertSubagentRecord(spawn("running", { status: "running" }));
+    upsertSubagentRecord(spawn("queued", { status: "pending" }));
+    upsertSubagentRecord(spawn("asking", { status: "awaiting_input" }));
+    upsertSubagentRecord(
+      spawn("running-elsewhere", {
+        status: "running",
+        parentConversationId: "parent-2",
+      }),
+    );
+
+    expect(tally()).toEqual({
+      // An unfinished run has no cost recorded yet, so it adds nothing to the
+      // completed tally's spend.
+      conversation: { count: 1, estimatedCost: 0.5, inFlight: 3 },
+      assistant: { count: 1, estimatedCost: 0.5, inFlight: 4 },
+    });
+  });
+});
+
 describe("subagentStateFromRecord", () => {
   test("maps the recorded status verbatim, leaving the settle to the caller", () => {
     upsertSubagentRecord(record({ id: "active", status: "running" }));

package/src/__tests__/subagent-role-registry.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
+import { READ_ONLY_ALLOWED_TOOLS } from "../daemon/conversation-tool-setup.js";
 import {
   mergeSkillIds,
   SUBAGENT_ROLE_REGISTRY,
@@ -9,14 +10,7 @@ import { buildSubagentSystemPrompt } from "../subagent/manager.js";
 import type { SubagentConfig } from "../subagent/types.js";
 
 /** All roles defined in the SubagentRole union. */
-const ALL_ROLES: SubagentRole[] = [
-  "general",
-  "researcher",
-  "coder",
-  "planner",
-  "investigator",
-  "advisor",
-];
+const ALL_ROLES: SubagentRole[] = ["researcher", "builder", "advisor"];
 
 describe("SUBAGENT_ROLE_REGISTRY", () => {
   test("covers all values in the SubagentRole union", () => {
@@ -31,25 +25,84 @@ describe("SUBAGENT_ROLE_REGISTRY", () => {
     }
   });
 
-  test("general has allowedTools: undefined", () => {
-    expect(SUBAGENT_ROLE_REGISTRY.general.allowedTools).toBeUndefined();
+  test("the read-only roles declare an explicit allowlist", () => {
+    for (const role of ["researcher", "advisor"] as const) {
+      expect(Array.isArray(SUBAGENT_ROLE_REGISTRY[role].allowedTools)).toBe(
+        true,
+      );
+    }
+    expect(
+      SUBAGENT_ROLE_REGISTRY.researcher.allowedTools!.length,
+    ).toBeGreaterThan(0);
   });
 
-  test("all scoped tool-using roles have allowedTools as a non-empty array", () => {
-    for (const role of ALL_ROLES) {
-      // 'general' has no filter (undefined); 'advisor' is tool-less (empty).
-      if (role === "general" || role === "advisor") {
-        continue;
-      }
-      const config = SUBAGENT_ROLE_REGISTRY[role];
-      expect(Array.isArray(config.allowedTools)).toBe(true);
-      expect(config.allowedTools!.length).toBeGreaterThan(0);
+  test("builder declares no allowlist, so it keeps the parent's whole tool surface", () => {
+    // The regression this guards: an explicit list is a ceiling. A builder
+    // scoped to file/shell/web tools silently loses connectors, MCP tools,
+    // browser and computer use, and everything else the parent can reach.
+    expect(SUBAGENT_ROLE_REGISTRY.builder.allowedTools).toBeUndefined();
+  });
+
+  test("advisor is scoped to exactly the three read-only fact-checking tools", () => {
+    expect(SUBAGENT_ROLE_REGISTRY.advisor.allowedTools).toEqual([
+      "file_read",
+      "file_list",
+      "code_search",
+    ]);
+  });
+
+  test("advisor cannot search memory or other conversations", () => {
+    // `recall` searches memory, the personal knowledge base, and prior
+    // conversations. The consult's documented contract is this conversation
+    // plus what the advisor reads in the workspace, so the one tool that
+    // reaches past it stays out.
+    expect(SUBAGENT_ROLE_REGISTRY.advisor.allowedTools).not.toContain("recall");
+    expect(SUBAGENT_ROLE_REGISTRY.advisor.systemPromptPreamble).toContain(
+      "cannot see other conversations",
+    );
+  });
+
+  test("every advisor tool is inside the runtime's owner-gated read-only set", () => {
+    // The advisor spawn sets `denySideEffectTools`, so a name outside
+    // READ_ONLY_ALLOWED_TOOLS is admitted by the role and then refused at
+    // dispatch: the model would be shown a tool it cannot run. Keeping the
+    // allowlist a subset is what makes the two gates agree.
+    for (const name of SUBAGENT_ROLE_REGISTRY.advisor.allowedTools!) {
+      expect(READ_ONLY_ALLOWED_TOOLS.has(name)).toBe(true);
     }
   });
 
-  test("advisor is tool-less with an empty allowedTools array", () => {
-    const config = SUBAGENT_ROLE_REGISTRY.advisor;
-    expect(config.allowedTools).toEqual([]);
+  test("advisor is read-only: nothing write-capable, no shell, no skill execution", () => {
+    // The consult is a judgment call the parent blocks on, so the advisor must
+    // never be able to act on the workspace or persist output of its own.
+    const tools = SUBAGENT_ROLE_REGISTRY.advisor.allowedTools!;
+    for (const forbidden of [
+      "bash",
+      "host_bash",
+      "file_write",
+      "file_edit",
+      "skill_execute",
+      "web_fetch",
+      "recall",
+    ]) {
+      expect(tools).not.toContain(forbidden);
+    }
+  });
+
+  test("researcher preamble discourages slicing without instructing whole-file reads", () => {
+    const preamble = SUBAGENT_ROLE_REGISTRY.researcher.systemPromptPreamble;
+    // `file_read` takes no default line limit and its results skip result-time
+    // spooling, so a whole-file instruction puts full bodies on every LLM call
+    // for the rest of the turn. Keep the anti-slicing guidance without it.
+    expect(preamble.toLowerCase()).not.toContain("read whole files");
+    expect(preamble).toContain("one pass rather than many small slices");
+  });
+
+  test("advisor preamble states it can verify facts but cannot change anything", () => {
+    const preamble = SUBAGENT_ROLE_REGISTRY.advisor.systemPromptPreamble;
+    expect(preamble).toContain("read and search the files");
+    expect(preamble).toContain("cannot change anything");
+    expect(preamble).not.toContain("no tools");
   });
 
   test("SubagentRole type includes advisor", () => {
@@ -57,21 +110,25 @@ describe("SUBAGENT_ROLE_REGISTRY", () => {
     expect(SUBAGENT_ROLE_REGISTRY[advisor]).toBeDefined();
   });
 
-  test('every role with a non-empty allowlist includes "notify_parent"', () => {
-    for (const [_role, config] of Object.entries(SUBAGENT_ROLE_REGISTRY)) {
-      // 'advisor' is tool-less (empty allowlist) and intentionally has none.
-      if (config.allowedTools !== undefined && config.allowedTools.length > 0) {
-        expect(config.allowedTools).toContain("notify_parent");
-      }
-    }
+  test('every allowlisted background role includes "notify_parent"', () => {
+    // Mid-run reporting only means something for a role the parent does not
+    // wait on. The advisor blocks the parent turn and returns its guidance as
+    // the tool result, so it intentionally has no notify_parent.
+    expect(SUBAGENT_ROLE_REGISTRY.researcher.allowedTools).toContain(
+      "notify_parent",
+    );
+    expect(SUBAGENT_ROLE_REGISTRY.advisor.allowedTools).not.toContain(
+      "notify_parent",
+    );
   });
 
-  test('no role includes "skill_execute" (replaced by core tools)', () => {
-    for (const [_role, config] of Object.entries(SUBAGENT_ROLE_REGISTRY)) {
-      if (config.allowedTools !== undefined) {
-        expect(config.allowedTools).not.toContain("skill_execute");
-      }
-    }
+  test('the scoped tool-using role includes "skill_execute" so preactivated skills work', () => {
+    // Without it, `preactivatedSkillIds` is a silent no-op for the role: the
+    // skill loads and none of its tools can be reached. Only an allowlisted
+    // role can lose it.
+    expect(SUBAGENT_ROLE_REGISTRY.researcher.allowedTools).toContain(
+      "skill_execute",
+    );
   });
 
   test('researcher includes "recall" for local information access', () => {
@@ -79,34 +136,42 @@ describe("SUBAGENT_ROLE_REGISTRY", () => {
     expect(tools).toContain("recall");
   });
 
-  test('coder includes "recall" for local information access', () => {
-    expect(SUBAGENT_ROLE_REGISTRY.coder.allowedTools!).toContain("recall");
-  });
-
-  test('planner includes "recall" for local information access', () => {
-    expect(SUBAGENT_ROLE_REGISTRY.planner.allowedTools!).toContain("recall");
-  });
-
-  test("investigator is shell-free and uses code_search for code/log investigation", () => {
-    const tools = SUBAGENT_ROLE_REGISTRY.investigator.allowedTools!;
+  test("researcher is read-only: no shell, no file writes", () => {
+    const tools = SUBAGENT_ROLE_REGISTRY.researcher.allowedTools!;
     expect(tools).not.toContain("bash");
     expect(tools).not.toContain("host_bash");
-    expect(tools).toContain("code_search");
-  });
-
-  test("investigator excludes file write tools (read-only investigation)", () => {
-    const tools = SUBAGENT_ROLE_REGISTRY.investigator.allowedTools!;
     expect(tools).not.toContain("file_write");
     expect(tools).not.toContain("file_edit");
   });
 
-  test("investigator preamble defines the root-cause report contract", () => {
-    const preamble = SUBAGENT_ROLE_REGISTRY.investigator.systemPromptPreamble;
+  test("researcher can search and enumerate as well as read", () => {
+    const tools = SUBAGENT_ROLE_REGISTRY.researcher.allowedTools!;
+    expect(tools).toContain("code_search");
+    expect(tools).toContain("file_list");
+    expect(tools).toContain("web_search");
+    expect(tools).toContain("web_fetch");
+  });
+
+  test("researcher preamble carries the read-only investigation contract", () => {
+    const preamble = SUBAGENT_ROLE_REGISTRY.researcher.systemPromptPreamble;
     expect(preamble).toContain("Root cause");
     expect(preamble).toContain("Evidence");
     expect(preamble).toContain("notify_parent");
-    expect(preamble).not.toContain("shell access");
     expect(preamble).toContain("code_search");
+    expect(preamble).toContain("no shell");
+  });
+
+  test("builder preamble states it can write, run commands, and reach the parent's other tools", () => {
+    const preamble = SUBAGENT_ROLE_REGISTRY.builder.systemPromptPreamble;
+    expect(preamble).toContain("edit files");
+    expect(preamble).toContain("shell commands");
+    expect(preamble).toContain("any other tool the parent conversation can");
+  });
+
+  test("builder preamble requires self-verification and a change report", () => {
+    const preamble = SUBAGENT_ROLE_REGISTRY.builder.systemPromptPreamble;
+    expect(preamble).toContain("verify");
+    expect(preamble).toContain("files you touched");
   });
 
   test("no role references the old memory_recall tool name", () => {
@@ -122,21 +187,18 @@ describe("SUBAGENT_ROLE_REGISTRY", () => {
       expect(config.skillIds).toEqual([]);
     }
   });
-
-  test('researcher and planner include "file_list"', () => {
-    expect(SUBAGENT_ROLE_REGISTRY.researcher.allowedTools).toContain(
-      "file_list",
-    );
-    expect(SUBAGENT_ROLE_REGISTRY.planner.allowedTools).toContain("file_list");
-  });
 });
 
-describe("buildSubagentSystemPrompt — blocked-signal constraint", () => {
-  const cfg = (objective: string): SubagentConfig => ({
+describe("buildSubagentSystemPrompt: framing and constraints", () => {
+  const cfg = (
+    objective: string,
+    extra: Partial<SubagentConfig> = {},
+  ): SubagentConfig => ({
     id: "sub-1",
     parentConversationId: "conv-1",
     label: "task",
     objective,
+    ...extra,
   });
 
   test("every role's constructed prompt tells it to signal blocked instead of fabricating a result", () => {
@@ -156,7 +218,7 @@ describe("buildSubagentSystemPrompt — blocked-signal constraint", () => {
     expect(
       buildSubagentSystemPrompt(cfg("save output"), "researcher"),
     ).toContain("do NOT fabricate");
-    expect(buildSubagentSystemPrompt(cfg("save output"), "coder")).toContain(
+    expect(buildSubagentSystemPrompt(cfg("save output"), "builder")).toContain(
       "do NOT fabricate",
     );
     // It is NOT duplicated into the researcher role's own preamble.
@@ -164,6 +226,53 @@ describe("buildSubagentSystemPrompt — blocked-signal constraint", () => {
       SUBAGENT_ROLE_REGISTRY.researcher.systemPromptPreamble,
     ).not.toContain("do NOT fabricate");
   });
+
+  test("every role is also told not to invent output for a tool that failed or was missing", () => {
+    // The blocked-signal line above only covers a capability the ROLE lacks.
+    // This one covers the runtime cases: the call failed, or the tool was not
+    // there at all.
+    for (const role of ALL_ROLES) {
+      const prompt = buildSubagentSystemPrompt(cfg("run the build"), role);
+      expect(prompt).toContain(
+        "If a tool call fails, or a tool you expected is unavailable, report the failure verbatim and stop that line of work.",
+      );
+      expect(prompt).toContain(
+        "Never simulate, reconstruct, or invent tool output you did not actually receive.",
+      );
+    }
+  });
+
+  test("a persona renders as a line under the role preamble", () => {
+    const prompt = buildSubagentSystemPrompt(
+      cfg("assess the filing", { persona: "financial journalist" }),
+      "researcher",
+    );
+    expect(prompt).toContain(
+      "- Persona: act as financial journalist for this task.",
+    );
+    // Under the preamble, above the task.
+    expect(prompt.indexOf("- Persona:")).toBeGreaterThan(
+      prompt.indexOf(SUBAGENT_ROLE_REGISTRY.researcher.systemPromptPreamble),
+    );
+    expect(prompt.indexOf("- Persona:")).toBeLessThan(
+      prompt.indexOf("## Your Task"),
+    );
+  });
+
+  test("no persona line when the spawn carried none", () => {
+    expect(
+      buildSubagentSystemPrompt(cfg("do the work"), "builder"),
+    ).not.toContain("- Persona:");
+  });
+
+  test("the prompt names the type that ran", () => {
+    const prompt = buildSubagentSystemPrompt(
+      cfg("continue the work"),
+      "builder",
+    );
+    expect(prompt).toContain("## Your Task");
+    expect(prompt).toContain("- Role: builder");
+  });
 });
 
 describe("mergeSkillIds", () => {