@ilya-lesikov/pi-pi 0.6.0 → 0.8.0

package/3p/pi-subagents/src/agent-runner.ts

@@ -2,6 +2,7 @@
  * agent-runner.ts — Core execution engine: creates sessions, runs agents, collects results.
  */
 
+import { AsyncLocalStorage } from "node:async_hooks";
 import type { Model } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
@@ -27,6 +28,53 @@ const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
 const TRACER_KEY = Symbol.for("pi-pi:tracer");
 const SUBAGENT_SESSION_KEY = Symbol.for("pi-pi:subagent-session");
 
+// Concurrency-safe subagent lineage. The previous approach derived parent/depth
+// from the mutable process-global SUBAGENT_SESSION_KEY, which is racy for
+// CONCURRENT siblings: MAIN spawns opus/gpt/gemini in parallel, each runAgent's
+// synchronous prologue read whatever the *previous sibling* had just written to
+// the global — so gpt recorded opus as its parent, gemini recorded gpt, forming a
+// bogus opus→gpt→gemini chain with depth 3-6 instead of three depth-1 children of
+// MAIN. AsyncLocalStorage instead propagates DOWN the async call chain (a nested
+// spawn inherits its true parent's store) but NOT ACROSS sibling promises (each
+// sibling started from MAIN sees no store → parent=undefined, depth=1).
+interface SubagentLineage {
+  depth: number;
+  subagentId?: string;
+}
+const subagentLineage = new AsyncLocalStorage<SubagentLineage>();
+
+// The process-global SUBAGENT_SESSION_KEY marker is read elsewhere purely for
+// truthiness ("is any subagent running in this process?", e.g. orchestrator nudge
+// gates). Manage it with a ref-count so concurrent in-process siblings set/clear
+// it correctly regardless of completion order (a plain save/restore would leak a
+// stale marker whenever the last sibling to finish wasn't the last to start).
+let activeSubagentRuns = 0;
+let markerBeforeFirstRun: unknown;
+function enterSubagentMarker(): void {
+  if (activeSubagentRuns === 0) {
+    // Snapshot whatever was there before our first concurrent run (undefined in
+    // the main process; the orchestrator's persistent bootstrap { depth: 1 } in a
+    // subagent process) so we can restore it exactly when the last run exits.
+    markerBeforeFirstRun = (globalThis as any)[SUBAGENT_SESSION_KEY];
+  }
+  activeSubagentRuns++;
+  const marker = (globalThis as any)[SUBAGENT_SESSION_KEY];
+  if (typeof marker !== "object" || marker === null) {
+    (globalThis as any)[SUBAGENT_SESSION_KEY] = { depth: 1 };
+  }
+}
+function exitSubagentMarker(): void {
+  activeSubagentRuns = Math.max(0, activeSubagentRuns - 1);
+  if (activeSubagentRuns === 0) {
+    if (markerBeforeFirstRun === undefined) {
+      delete (globalThis as any)[SUBAGENT_SESSION_KEY];
+    } else {
+      (globalThis as any)[SUBAGENT_SESSION_KEY] = markerBeforeFirstRun;
+    }
+    markerBeforeFirstRun = undefined;
+  }
+}
+
 interface PiPiTracer {
   openSubagent(meta: {
     subagentId: string;
@@ -45,11 +93,6 @@ function getTracer(): PiPiTracer | undefined {
   return (globalThis as any)[TRACER_KEY];
 }
 
-function subagentDepth(): number {
-  const marker = (globalThis as any)[SUBAGENT_SESSION_KEY];
-  return typeof marker?.depth === "number" ? marker.depth : 1;
-}
-
 function traceSubagentEvent(subagentId: string | undefined, event: AgentSessionEvent, turnIndex: number): void {
   if (!subagentId) return;
   const tracer = getTracer();
@@ -242,21 +285,22 @@ export async function runAgent(
 
   // Resolve working directory: worktree override > parent cwd
   const effectiveCwd = options.cwd ?? ctx.cwd;
-  // Shared marker with extensions/orchestrator/index.ts (SUBAGENT_SESSION_KEY).
-  // Canonical shape is { depth: number }; a legacy boolean true is tolerated as depth 1.
-  const subagentSessionKey = Symbol.for("pi-pi:subagent-session");
-  const previousSubagentSession = (globalThis as any)[subagentSessionKey];
-  const previousDepth = typeof previousSubagentSession === "object" && previousSubagentSession !== null
-    ? ((previousSubagentSession as { depth?: number }).depth ?? 0)
-    : previousSubagentSession
-      ? 1
-      : 0;
-  const parentSubagentId = typeof previousSubagentSession === "object" && previousSubagentSession !== null
-    ? (previousSubagentSession as { subagentId?: string }).subagentId
-    : undefined;
-  const subagentSessionState = { depth: previousDepth + 1, subagentId: options.subagentId };
-  (globalThis as any)[subagentSessionKey] = subagentSessionState;
 
+  // Derive lineage from the async-context store (see subagentLineage above).
+  // Reading it BEFORE entering the child's own als.run means concurrent siblings
+  // each see their real parent (MAIN → undefined store), not a leaked sibling.
+  const parentLineage = subagentLineage.getStore();
+  const parentSubagentId = parentLineage?.subagentId;
+  const traceDepth = (parentLineage?.depth ?? 0) + 1;
+  const childLineage: SubagentLineage = { depth: traceDepth, subagentId: options.subagentId };
+
+  // Mark the process as "running a subagent" for truthiness readers (see
+  // enter/exitSubagentMarker). Lineage (parent/depth) comes from als above, so
+  // this marker no longer participates in nesting math and its old sibling-race
+  // can no longer corrupt the org chart.
+  enterSubagentMarker();
+
+  return subagentLineage.run(childLineage, async () => {
   try {
     const env = await detectEnv(options.pi, effectiveCwd);
 
@@ -460,7 +504,7 @@ export async function runAgent(
           description: options.subagentDescription,
           parentToolCallId: options.parentToolCallId,
           parentSubagentId,
-          depth: subagentDepth(),
+          depth: traceDepth,
           systemPrompt,
           effectivePrompt,
         });
@@ -496,20 +540,9 @@ export async function runAgent(
     }
     return { responseText, session, aborted, steered: softLimitReached };
   } finally {
-    const currentDepth = typeof (globalThis as any)[subagentSessionKey] === "object" && (globalThis as any)[subagentSessionKey] !== null
-      ? ((((globalThis as any)[subagentSessionKey]) as { depth?: number }).depth ?? subagentSessionState.depth)
-      : subagentSessionState.depth;
-    const nextDepth = Math.max(0, currentDepth - 1);
-    if (nextDepth === 0) {
-      if (previousSubagentSession === undefined) {
-        delete (globalThis as any)[subagentSessionKey];
-      } else {
-        (globalThis as any)[subagentSessionKey] = previousSubagentSession;
-      }
-    } else {
-      (globalThis as any)[subagentSessionKey] = { depth: nextDepth };
-    }
+    exitSubagentMarker();
   }
+  });
 }
 
 /**

package/3p/pi-subagents/src/index.ts

@@ -402,13 +402,7 @@ Use get_subagent_result for full output.`,
   }
 
   // Background completion: route through group join or send individual nudge
-  const firstProgressSeen = new Set<string>();
-  const firstTurnSeen = new Set<string>();
-
   const manager = new AgentManager((record) => {
-    firstProgressSeen.delete(record.id);
-    firstTurnSeen.delete(record.id);
-
     let eventData: ReturnType<typeof buildEventData> | undefined;
     try {
       eventData = buildEventData(record);
@@ -907,36 +901,9 @@ Guidelines:
         const { state: bgState, callbacks: bgCallbacks } = createActivityTracker(effectiveMaxTurns);
 
         let id: string;
-        const emitFirstTool = (toolName: string) => {
-          if (firstProgressSeen.has(id)) return;
-          firstProgressSeen.add(id);
-          pi.events.emit("subagents:first_tool", {
-            id,
-            type: subagentType,
-            description: params.description,
-            toolName,
-          });
-        };
-        const emitFirstTurn = (turnCount: number) => {
-          if (firstTurnSeen.has(id)) return;
-          firstTurnSeen.add(id);
-          pi.events.emit("subagents:first_turn", {
-            id,
-            type: subagentType,
-            description: params.description,
-            turnCount,
-          });
-        };
-        const originalBgToolActivity = bgCallbacks.onToolActivity;
-        bgCallbacks.onToolActivity = (activity) => {
-          originalBgToolActivity(activity);
-          if (activity.type === "start") emitFirstTool(activity.toolName);
-        };
-        const originalBgTurnEnd = bgCallbacks.onTurnEnd;
-        bgCallbacks.onTurnEnd = (turnCount) => {
-          originalBgTurnEnd(turnCount);
-          emitFirstTurn(turnCount);
-        };
+        // first_tool/first_turn are now emitted centrally by AgentManager.startAgent
+        // (the single choke point for ALL spawn paths, including RPC-spawned panels),
+        // so no per-branch wiring is needed here.
 
         // Wrap onSessionCreated to wire output file streaming.
         // The callback lazily reads record.outputFile (set right after spawn)
@@ -944,8 +911,6 @@ Guidelines:
         const origBgOnSession = bgCallbacks.onSessionCreated;
         bgCallbacks.onSessionCreated = (session: any) => {
           origBgOnSession(session);
-          firstProgressSeen.delete(id);
-          firstTurnSeen.delete(id);
           const rec = manager.getRecord(id);
           if (rec?.outputFile) {
             rec.outputCleanup = streamToOutputFile(session, rec.outputFile, id, ctx.cwd);

package/3p/pi-subagents/src/types.ts

@@ -81,6 +81,10 @@ export interface AgentRecord {
   worktreeResult?: { hasChanges: boolean; branch?: string };
   /** The tool_use_id from the original Agent tool call. */
   toolCallId?: string;
+  /** Whether the subagents:first_tool event has been emitted for this run. */
+  firstToolEmitted?: boolean;
+  /** Whether the subagents:first_turn event has been emitted for this run. */
+  firstTurnEmitted?: boolean;
   /** Path to the streaming output transcript file. */
   outputFile?: string;
   /** Cleanup function for the output file stream subscription. */

package/extensions/orchestrator/agents/advisor.ts

@@ -0,0 +1,35 @@
+import type { PiPiConfig } from "../config.js";
+import { resolveModel } from "../model-registry.js";
+import { TOOLS_BLOCK, ALL_CBM_TOOLS, EXA_TOOLS, PRINCIPLES_BLOCK } from "./tool-routing.js";
+
+export function createAdvisorAgent(config: PiPiConfig) {
+  return {
+    frontmatter: {
+      description: "Deep-reasoning advisor for design decisions and 'why is this broken' analysis (pi-pi)",
+      tools: `read, bash, grep, find, ls, lsp, ast_search, ${ALL_CBM_TOOLS}, ${EXA_TOOLS}`,
+      model: resolveModel(config.agents.subagents.simple.advisor.model),
+      thinking: config.agents.subagents.simple.advisor.thinking,
+      max_turns: 120,
+      prompt_mode: "replace",
+    },
+    prompt: [
+      "<constraints>",
+      "You are a deep-reasoning ADVISOR. You investigate one hard question — a design decision, an architecture tradeoff, a \"why is this broken\", or a correctness/soundness judgment — and return a reasoned recommendation backed by evidence.",
+      "These rules override your default helpfulness. Strict compliance is required.",
+      "You are READ-ONLY: you MUST NOT modify any file. Diagnose and advise; do NOT change code.",
+      "</constraints>",
+      "",
+      PRINCIPLES_BLOCK,
+      "",
+      TOOLS_BLOCK,
+      "",
+      "<task>",
+      "- Verify every claim with tool calls — read the actual code. Never reason from memory about this codebase.",
+      "- Generate multiple competing hypotheses or approaches before converging. Surface and question hidden assumptions.",
+      "- Scope recommendations by effort: name the quick fix vs the thorough one.",
+      "- Structure your answer: Diagnosis (what is actually true, with file:line evidence) → Options & tradeoffs → Recommendation.",
+      "- Be honest about uncertainty. If evidence is thin, say so and state what would resolve it.",
+      "</task>",
+    ].join("\n"),
+  };
+}

package/extensions/orchestrator/agents/brainstorm-reviewer.ts

@@ -1,5 +1,5 @@
 import type { VariantConfig } from "../config.js";
-import { loadAllContextFiles } from "../context.js";
+import { loadAllContextFiles, formatManifestBlock } from "../context.js";
 import { resolveModel, getModelInfo } from "../model-registry.js";
 import type { RepoInfo } from "../repo-utils.js";
 import { buildRepoContext } from "./repo-context.js";
@@ -8,7 +8,7 @@ import { TOOLS_BLOCK, ALL_CBM_TOOLS, EXA_TOOLS, PRINCIPLES_BLOCK } from "./tool-
 export function createBrainstormReviewerAgent(
   variant: string,
   variants: Record<string, VariantConfig>,
-  taskArtifacts: { userRequest: string; research: string; artifacts?: { name: string; content: string }[] },
+  taskArtifacts: { userRequest: string; research: string; artifacts?: { name: string; content: string }[]; manifest?: { title: string; path: string }[] },
   outputPath: string,
   contextDirs: string[],
   phase?: string,
@@ -64,10 +64,10 @@ export function createBrainstormReviewerAgent(
       "- INACCURACIES: (claims that don't match the code)",
       "- SUGGESTIONS: (improvements, not required)",
       "",
-      "subagent_type is REQUIRED when spawning subagents — calls without it are rejected:",
-    '- Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
-    '- Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
-    "Spawn multiple Explore agents in parallel for broad searches.",
+      "You may spawn ONLY explore/librarian subagents (subagent_type is REQUIRED — calls without it are rejected):",
+    '- Agent(subagent_type="explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
+    '- Agent(subagent_type="librarian", ...) — external docs, library APIs, web research.',
+    "Spawn multiple explore agents in parallel for broad searches. Do NOT spawn task, advisor, deep-debugger, or reviewer.",
       "</task>",
       "",
       "# MANDATORY: Write your review to this exact file using the write tool:",
@@ -88,7 +88,7 @@ export function createBrainstormReviewerAgent(
         : []),
       ...(repoContext ? [repoContext] : []),
       "",
-      "The artifacts above are already in your context. Do NOT re-read them from disk.",
+      formatManifestBlock(taskArtifacts.manifest ?? []),
     ].join("\n"),
   };
 }

package/extensions/orchestrator/agents/code-reviewer.ts

@@ -1,5 +1,5 @@
 import type { VariantConfig } from "../config.js";
-import { loadAllContextFiles } from "../context.js";
+import { loadAllContextFiles, formatManifestBlock } from "../context.js";
 import { resolveModel, getModelInfo } from "../model-registry.js";
 import type { RepoInfo } from "../repo-utils.js";
 import { buildRepoContext } from "./repo-context.js";
@@ -8,7 +8,7 @@ import { TOOLS_BLOCK, ALL_CBM_TOOLS, EXA_TOOLS, PRINCIPLES_BLOCK } from "./tool-
 export function createCodeReviewerAgent(
   variant: string,
   variants: Record<string, VariantConfig>,
-  taskArtifacts: { userRequest: string; research: string; synthesizedPlan: string },
+  taskArtifacts: { userRequest: string; research: string; synthesizedPlan: string; manifest?: { title: string; path: string }[] },
   outputPath: string,
   contextDirs: string[],
   phase?: string,
@@ -81,10 +81,10 @@ export function createCodeReviewerAgent(
       "- MINOR: (nice to have)",
       "- OPEN QUESTIONS: (low-confidence concerns, speculative follow-ups)",
       "",
-      "subagent_type is REQUIRED when spawning subagents — calls without it are rejected:",
-    '- Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
-    '- Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
-    "Spawn multiple Explore agents in parallel for broad searches.",
+      "You may spawn ONLY explore/librarian subagents (subagent_type is REQUIRED — calls without it are rejected):",
+    '- Agent(subagent_type="explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
+    '- Agent(subagent_type="librarian", ...) — external docs, library APIs, web research.',
+    "Spawn multiple explore agents in parallel for broad searches. Do NOT spawn task, advisor, deep-debugger, or reviewer.",
       "</task>",
       "",
       // --- dynamic suffix ---
@@ -101,7 +101,7 @@ export function createCodeReviewerAgent(
       taskArtifacts.synthesizedPlan,
       ...(repoContext ? [repoContext] : []),
       "",
-      "The artifacts above are already in your context. Do NOT re-read them from disk.",
+      formatManifestBlock(taskArtifacts.manifest ?? []),
     ].join("\n"),
   };
 }

package/extensions/orchestrator/agents/constraints.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import { completionLine, constraintsBlock } from "./constraints.js";
+
+describe("completionLine", () => {
+  it("guided plan and implement instruct calling pp_phase_complete on completion", () => {
+    for (const phase of ["plan", "implement"] as const) {
+      const line = completionLine(phase, "guided");
+      expect(line).toContain("call pp_phase_complete");
+      expect(line).not.toContain("Do NOT advance on your own");
+      expect(line).not.toMatch(/do not.*wait for.*input/i);
+    }
+  });
+
+  it("guided review and debug stay hands-off (no unprompted self-complete)", () => {
+    for (const phase of ["review", "debug"] as const) {
+      const line = completionLine(phase, "guided");
+      expect(line).toContain("Do NOT advance on your own or call pp_phase_complete unprompted");
+    }
+  });
+
+  it("guided brainstorm never self-completes", () => {
+    const line = completionLine("brainstorm", "guided");
+    expect(line).toContain("Do NOT call pp_phase_complete yourself");
+  });
+
+  it("autonomous phases always self-complete regardless of phase", () => {
+    for (const phase of ["plan", "implement", "review", "brainstorm"] as const) {
+      expect(completionLine(phase, "autonomous")).toContain("call pp_phase_complete");
+    }
+  });
+});
+
+describe("constraintsBlock", () => {
+  it("guided implement block tells the agent to self-complete", () => {
+    const block = constraintsBlock("implement", "guided");
+    expect(block).toContain("call pp_phase_complete");
+    expect(block).not.toContain("Do NOT advance on your own");
+  });
+
+  it("guided plan block tells the agent to self-complete", () => {
+    const block = constraintsBlock("plan", "guided");
+    expect(block).toContain("call pp_phase_complete");
+  });
+});

package/extensions/orchestrator/agents/constraints.ts

@@ -29,6 +29,9 @@ export function completionLine(phase: Phase, mode: TaskMode): string {
   if (phase === "brainstorm") {
     return "This is a conversation. Do NOT call pp_phase_complete yourself — keep going until the user ends it or advances via the /pp menu.";
   }
+  if (phase === "plan" || phase === "implement") {
+    return "When you judge this phase complete, call pp_phase_complete — the extension opens the advance gate for the user to review and confirm. Do NOT instead stop and ask the user to run /pp manually.";
+  }
   return "When the work is complete, stop and let the user review and advance it via the /pp menu. Do NOT advance on your own or call pp_phase_complete unprompted.";
 }
 

package/extensions/orchestrator/agents/deep-debugger.ts

@@ -0,0 +1,35 @@
+import type { PiPiConfig } from "../config.js";
+import { resolveModel } from "../model-registry.js";
+import { TOOLS_BLOCK, ALL_CBM_TOOLS, EXA_TOOLS, PRINCIPLES_BLOCK } from "./tool-routing.js";
+
+export function createDeepDebuggerAgent(config: PiPiConfig) {
+  return {
+    frontmatter: {
+      description: "Deep root-cause analysis for HARD, persistent failures — not every error (pi-pi)",
+      tools: `read, write, edit, bash, grep, find, ls, lsp, ast_search, ${ALL_CBM_TOOLS}, ${EXA_TOOLS}`,
+      model: resolveModel(config.agents.subagents.simple["deep-debugger"].model),
+      thinking: config.agents.subagents.simple["deep-debugger"].thinking,
+      max_turns: 120,
+      prompt_mode: "replace",
+    },
+    prompt: [
+      "<constraints>",
+      "You are a DEEP DEBUGGER. You do root-cause analysis on hard, persistent failures — failing tests, build/compile errors, regressions, flaky behavior — that quick attempts have NOT resolved. Do NOT engage for trivial or first-attempt errors.",
+      "These rules override your default helpfulness. Strict compliance is required.",
+      "You have write/edit access for DIAGNOSIS ONLY: creating repro scripts, adding temporary logging, or running experiments. You MUST NOT write the actual fix in the source code — find the root cause and recommend the fix; do NOT apply it. Remove any temporary diagnostic artifacts you create.",
+      "</constraints>",
+      "",
+      PRINCIPLES_BLOCK,
+      "",
+      TOOLS_BLOCK,
+      "",
+      "<task>",
+      "- Reproduce/inspect first: run the failing command, read the actual error and stack trace, check recent changes (git diff, cbm_changes).",
+      "- Form competing hypotheses. For each, gather evidence FOR and AGAINST with tool calls. Do not commit to the first plausible cause.",
+      "- Trace the failure to its true root, not the surface symptom. Use lsp findReferences / cbm_trace to follow the chain.",
+      "- Report: Symptom → Hypotheses considered (with evidence) → Root cause (with file:line proof) → Minimal recommended fix.",
+      "- If you cannot prove the root cause, say so: report the narrowed-down suspects and the single most useful next probe.",
+      "</task>",
+    ].join("\n"),
+  };
+}

package/extensions/orchestrator/agents/plan-reviewer.ts

@@ -1,5 +1,5 @@
 import type { VariantConfig } from "../config.js";
-import { loadAllContextFiles } from "../context.js";
+import { loadAllContextFiles, formatManifestBlock } from "../context.js";
 import { resolveModel, getModelInfo } from "../model-registry.js";
 import type { RepoInfo } from "../repo-utils.js";
 import { buildRepoContext } from "./repo-context.js";
@@ -8,7 +8,7 @@ import { TOOLS_BLOCK, ALL_CBM_TOOLS, EXA_TOOLS, PRINCIPLES_BLOCK } from "./tool-
 export function createPlanReviewerAgent(
   variant: string,
   variants: Record<string, VariantConfig>,
-  taskArtifacts: { userRequest: string; research: string; synthesizedPlan: string },
+  taskArtifacts: { userRequest: string; research: string; synthesizedPlan: string; manifest?: { title: string; path: string }[] },
   outputPath: string,
   contextDirs: string[],
   phase?: string,
@@ -63,10 +63,10 @@ export function createPlanReviewerAgent(
       "- BLOCKERS: (critical issues that must be fixed)",
       "- SUGGESTIONS: (improvements, not required)",
       "",
-      "subagent_type is REQUIRED when spawning subagents — calls without it are rejected:",
-    '- Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
-    '- Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
-    "Spawn multiple Explore agents in parallel for broad searches.",
+      "You may spawn ONLY explore/librarian subagents (subagent_type is REQUIRED — calls without it are rejected):",
+    '- Agent(subagent_type="explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
+    '- Agent(subagent_type="librarian", ...) — external docs, library APIs, web research.',
+    "Spawn multiple explore agents in parallel for broad searches. Do NOT spawn task, advisor, deep-debugger, or reviewer.",
       "</task>",
       "",
       // --- dynamic suffix ---
@@ -87,7 +87,7 @@ export function createPlanReviewerAgent(
       taskArtifacts.synthesizedPlan,
       ...(repoContext ? [repoContext] : []),
       "",
-      "The artifacts above are already in your context. Do NOT re-read them from disk.",
+      formatManifestBlock(taskArtifacts.manifest ?? []),
     ].join("\n"),
   };
 }

package/extensions/orchestrator/agents/planner.ts

@@ -1,5 +1,5 @@
 import type { VariantConfig } from "../config.js";
-import { loadAllContextFiles } from "../context.js";
+import { loadAllContextFiles, formatManifestBlock } from "../context.js";
 import { resolveModel, getModelInfo } from "../model-registry.js";
 import type { RepoInfo } from "../repo-utils.js";
 import { buildRepoContext } from "./repo-context.js";
@@ -8,7 +8,7 @@ import { TOOLS_BLOCK, ALL_CBM_TOOLS, EXA_TOOLS, PRINCIPLES_BLOCK } from "./tool-
 export function createPlannerAgent(
   variant: string,
   variants: Record<string, VariantConfig>,
-  taskArtifacts: { userRequest: string; research: string },
+  taskArtifacts: { userRequest: string; research: string; manifest?: { title: string; path: string }[] },
   outputPath: string,
   contextDirs: string[],
   phase?: string,
@@ -51,14 +51,15 @@ export function createPlannerAgent(
       "- ## Scope: 2-4 lines — what changes, what doesn't, critical constraints",
       "- ## Checklist: each item is - [ ] <outcome> — Done when: <observable condition>",
       "  Each item = one independently verifiable outcome. No code snippets or file-by-file instructions.",
+      "- ## Pattern constraints: include whenever the task adds a type, function, parser, annotation, config key, enum, or user-facing value. For each, name the CLOSEST EXISTING analog (found by behavior, not filename) and the conventions the implementer MUST mirror: data shape (prefer one existing shape over parallel/duplicated state), spelling/casing of user-facing values (match existing — never invent a new casing), and parser/validation/error-handling shape. Acceptance criteria, not suggestions. Omit only if the task adds none of the above.",
       "- ## Blockers: unresolved issues blocking implementation (omit if none)",
       "- No other top-level sections allowed",
-      "- Describe outcomes, not code-level mechanics",
+      "- Describe outcomes, not code-level mechanics, EXCEPT in ## Pattern constraints where the concrete analog and conventions are required",
       "",
-      "subagent_type is REQUIRED when spawning subagents — calls without it are rejected:",
-    '- Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
-    '- Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
-    "Spawn multiple Explore agents in parallel for broad searches.",
+      "You may spawn ONLY explore/librarian subagents (subagent_type is REQUIRED — calls without it are rejected):",
+    '- Agent(subagent_type="explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
+    '- Agent(subagent_type="librarian", ...) — external docs, library APIs, web research.',
+    "Spawn multiple explore agents in parallel for broad searches. Do NOT spawn task, advisor, deep-debugger, or reviewer.",
       "</task>",
       "",
       // --- dynamic suffix ---
@@ -74,7 +75,7 @@ export function createPlannerAgent(
       taskArtifacts.research,
       ...(repoContext ? [repoContext] : []),
       "",
-      "The artifacts above are already in your context. Do NOT re-read them from disk.",
+      formatManifestBlock(taskArtifacts.manifest ?? []),
     ].join("\n"),
   };
 }

package/extensions/orchestrator/agents/prompts.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from "vitest";
+import { getDefaultConfig, resolvePreset } from "../config.js";
+import { DELEGATION_BLOCK } from "./tool-routing.js";
+import { createAdvisorAgent } from "./advisor.js";
+import { createDeepDebuggerAgent } from "./deep-debugger.js";
+import { createReviewerAgent } from "./reviewer.js";
+import { createTaskAgent } from "./task.js";
+import { createPlannerAgent } from "./planner.js";
+import { createPlanReviewerAgent } from "./plan-reviewer.js";
+import { createCodeReviewerAgent } from "./code-reviewer.js";
+import { createBrainstormReviewerAgent } from "./brainstorm-reviewer.js";
+
+const config = getDefaultConfig();
+
+describe("DELEGATION_BLOCK", () => {
+  it("covers all six free-form agents with lowercase registry names", () => {
+    for (const name of ["explore", "librarian", "task", "advisor", "deep-debugger", "reviewer"]) {
+      expect(DELEGATION_BLOCK).toContain(name);
+    }
+  });
+
+  it("states the reviewer and deep-debugger gating explicitly", () => {
+    expect(DELEGATION_BLOCK).toContain("ONLY when the user explicitly asks");
+    expect(DELEGATION_BLOCK).toMatch(/deep-debugger diagnoses/i);
+    expect(DELEGATION_BLOCK).toContain("must NOT write the actual fix");
+  });
+});
+
+describe("new free-form agent factories", () => {
+  it("advisor is read-only (no write/edit) and reasons in Diagnosis/Options/Recommendation", () => {
+    const a = createAdvisorAgent(config);
+    expect(a.frontmatter.tools).not.toContain("write");
+    expect(a.frontmatter.tools).not.toContain("edit");
+    expect(a.prompt).toContain("READ-ONLY");
+    expect(a.prompt).toContain("Diagnosis");
+    expect(a.prompt).toContain("Recommendation");
+  });
+
+  it("deep-debugger has write/edit but restricts writes to diagnosis only", () => {
+    const d = createDeepDebuggerAgent(config);
+    expect(d.frontmatter.tools).toContain("write");
+    expect(d.frontmatter.tools).toContain("edit");
+    expect(d.prompt).toContain("DIAGNOSIS ONLY");
+    expect(d.prompt).toContain("MUST NOT write the actual fix");
+  });
+
+  it("reviewer is read-only, retains bash for git diff, and is verdict-first", () => {
+    const r = createReviewerAgent(config);
+    expect(r.frontmatter.tools).toContain("bash");
+    expect(r.frontmatter.tools).not.toContain("write");
+    expect(r.frontmatter.tools).not.toContain("edit");
+    expect(r.prompt).toContain("git diff");
+    expect(r.prompt).toContain("VERY FIRST LINE");
+    expect(r.frontmatter.description).toContain("only when the user asks");
+  });
+});
+
+describe("task factory no longer bakes artifacts and stays explore/librarian-only", () => {
+  it("takes only config (no baked artifact arg) and does not inline USER REQUEST / SYNTHESIZED PLAN", () => {
+    expect(createTaskAgent.length).toBe(1);
+    const t = createTaskAgent(config);
+    expect(t.prompt).not.toContain("=== USER REQUEST ===");
+    expect(t.prompt).not.toContain("=== SYNTHESIZED PLAN ===");
+    expect(t.prompt).not.toContain("Do NOT re-read them from disk");
+    expect(t.prompt).toContain("ONLY explore/librarian");
+    expect(t.prompt).toContain("Do NOT spawn task, advisor, deep-debugger, or reviewer");
+  });
+});
+
+describe("phased factory prompts: manifest guidance replaces the do-not-re-read trailer", () => {
+  const planners = resolvePreset(config, "planners");
+  const planReviewers = resolvePreset(config, "planReviewers");
+  const codeReviewers = resolvePreset(config, "codeReviewers");
+  const brainstormReviewers = resolvePreset(config, "brainstormReviewers");
+  const manifest = [{ title: "Design Doc", path: "/t/artifacts/design.md" }];
+
+  it("planner lists manifest paths and restricts spawns to explore/librarian", () => {
+    const p = createPlannerAgent("opus", planners, { userRequest: "u", research: "r", manifest }, "/out.md", []);
+    expect(p.prompt).toContain("/t/artifacts/design.md");
+    expect(p.prompt).toContain("read them from disk with the read tool");
+    expect(p.prompt).toContain("Do NOT spawn task, advisor, deep-debugger, or reviewer");
+  });
+
+  it("plan-reviewer lists manifest paths and restricts spawns", () => {
+    const p = createPlanReviewerAgent(
+      "opus",
+      planReviewers,
+      { userRequest: "u", research: "r", synthesizedPlan: "p", manifest },
+      "/out.md",
+      [],
+    );
+    expect(p.prompt).toContain("/t/artifacts/design.md");
+    expect(p.prompt).toContain("Do NOT spawn task, advisor, deep-debugger, or reviewer");
+  });
+
+  it("code-reviewer lists manifest paths and restricts spawns", () => {
+    const c = createCodeReviewerAgent(
+      "opus",
+      codeReviewers,
+      { userRequest: "u", research: "r", synthesizedPlan: "p", manifest },
+      "/out.md",
+      [],
+    );
+    expect(c.prompt).toContain("/t/artifacts/design.md");
+    expect(c.prompt).toContain("Do NOT spawn task, advisor, deep-debugger, or reviewer");
+  });
+
+  it("brainstorm-reviewer restricts spawns and lists manifest paths when provided", () => {
+    const b = createBrainstormReviewerAgent(
+      "opus",
+      brainstormReviewers,
+      { userRequest: "u", research: "r", manifest },
+      "/out.md",
+      [],
+    );
+    expect(b.prompt).toContain("Do NOT spawn task, advisor, deep-debugger, or reviewer");
+    expect(b.prompt).toContain("/t/artifacts/design.md");
+    expect(b.prompt).toContain("read them from disk with the read tool");
+  });
+});