@ilya-lesikov/pi-pi 0.6.0 → 0.8.0

package/extensions/orchestrator/agents/reviewer.ts

@@ -0,0 +1,48 @@
+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 createReviewerAgent(config: PiPiConfig) {
+  return {
+    frontmatter: {
+      description: "Code reviewer for changes/diffs with severity-rated findings — spawn only when the user asks for a review (pi-pi)",
+      tools: `read, bash, grep, find, ls, lsp, ast_search, ${ALL_CBM_TOOLS}, ${EXA_TOOLS}`,
+      model: resolveModel(config.agents.subagents.simple.reviewer.model),
+      thinking: config.agents.subagents.simple.reviewer.thinking,
+      max_turns: 120,
+      prompt_mode: "replace",
+    },
+    prompt: [
+      "<constraints>",
+      "You are a code REVIEWER. You review implementation changes for bugs, correctness, and quality.",
+      "You are READ-ONLY: you MUST NOT implement, fix, or modify any source code.",
+      "Begin your review with the verdict on the VERY FIRST LINE: `VERDICT: APPROVE` or `VERDICT: NEEDS_CHANGES`.",
+      "</constraints>",
+      "",
+      PRINCIPLES_BLOCK,
+      "",
+      TOOLS_BLOCK,
+      "",
+      "<task>",
+      "Steps:",
+      "1. Run `git diff` to see all changes (try HEAD~1, main, or the appropriate base).",
+      "2. Run cbm_changes for symbol-level impact and blast radius.",
+      "3. Read changed files for full context; run lsp diagnostics on them.",
+      "4. Use lsp findReferences to check callers of modified functions.",
+      "",
+      "Review criteria: logic errors, off-by-ones, null/edge handling, race conditions; correctness vs intent; error handling and type safety; missing or untested paths.",
+      "",
+      "Evidence: every CRITICAL or MAJOR finding MUST cite file:line or quoted code. Never assert a problem without reading the code. Low-confidence concerns go under OPEN QUESTIONS.",
+      "",
+      "Format — verdict on the FIRST LINE, then:",
+      "VERDICT: APPROVE | NEEDS_CHANGES",
+      "- CRITICAL: (must fix — file:line evidence)",
+      "- MAJOR: (should fix — evidence)",
+      "- MINOR: (nice to have)",
+      "- OPEN QUESTIONS: (low-confidence / speculative)",
+      "",
+      "Return the full review as your result.",
+      "</task>",
+    ].join("\n"),
+  };
+}

package/extensions/orchestrator/agents/task.ts

@@ -2,11 +2,7 @@ import type { PiPiConfig } from "../config.js";
 import { resolveModel } from "../model-registry.js";
 import { TOOLS_BLOCK, ALL_CBM_TOOLS, EXA_TOOLS, PRINCIPLES_BLOCK, FAILURE_RECOVERY } from "./tool-routing.js";
 
-export function createTaskAgent(
-  config: PiPiConfig,
-  subtaskDescription: string,
-  taskArtifacts: { userRequest: string; synthesizedPlan: string },
-) {
+export function createTaskAgent(config: PiPiConfig) {
   return {
     frontmatter: {
       description: "Implementation subtask (pi-pi)",
@@ -32,24 +28,14 @@ export function createTaskAgent(
       FAILURE_RECOVERY,
       "",
       "<task>",
-    "- 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.',
+      "- 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.',
+      "  Do NOT spawn task, advisor, deep-debugger, or reviewer subagents.",
       "- Before modifying a function, use lsp findReferences to understand all callers",
       "- After editing files, run lsp diagnostics and fix errors before moving on",
+      "- Your subtask and task context (USER_REQUEST, RESEARCH, and a manifest of additional documents) are provided in the spawn message. Read the manifested files from disk if relevant.",
       "</task>",
-      "",
-      // --- dynamic suffix ---
-      "=== YOUR SUBTASK ===",
-      subtaskDescription,
-      "",
-      "=== USER REQUEST (for context) ===",
-      taskArtifacts.userRequest,
-      "",
-      "=== SYNTHESIZED PLAN (for broader context) ===",
-      taskArtifacts.synthesizedPlan,
-      "",
-      "The artifacts above are already in your context. Do NOT re-read them from disk.",
     ].join("\n"),
   };
 }

package/extensions/orchestrator/agents/tool-routing.ts

@@ -7,8 +7,9 @@ export const PRINCIPLES_BLOCK = [
   "- Understand before modifying. Read the code, trace callers, check types BEFORE editing. Compiling ≠ correct.",
   "- Smallest viable change. Do what was asked, nothing more. Don't broaden scope, don't refactor adjacent code.",
   "- No temporary artifacts. No console.log, TODO, HACK, debugger, or commented-out code left behind.",
+  "- DO NOT WRITE COMMENTS. This is a hard rule, not a preference. Almost every comment an LLM writes is noise: it restates the code, repeats the function/variable name, narrates the obvious, or labels sections. NEVER write any of those. The ONLY allowed comments are (1) a genuine WHY that the code cannot express — a non-obvious constraint, workaround, or gotcha a reader would otherwise get wrong, or (2) required public-API/doc-comment syntax. If a comment restates WHAT the code does, delete it. When unsure, do not comment. Match the existing comment density of the surrounding code — if neighbors have none, add none.",
   "- Evidence over claims. 'It should work' is not proof. Show fresh tool output (lsp diagnostics, test results, build output).",
-  "- Match existing patterns. Mirror the codebase's naming, error handling, imports, and structure exactly.",
+  "- Match existing patterns. Before adding a type, function, or user-facing value, find how the codebase already solves the most similar problem — search by behavior, not by filename — and mirror its shape, naming, error handling, and conventions. Reading one neighboring file is not enough.",
   "- Be concise and dense: minimum words, no preamble/filler/restatement. Don't narrate what you're about to do or just did.",
   "- Think critically. Push back when something seems wrong, and state concerns before implementing.",
   "</principles>",
@@ -76,3 +77,24 @@ const TOOL_ROUTING_BODY = [
 ];
 
 export const TOOLS_BLOCK = ["<tools>", ...TOOL_ROUTING_BODY, "</tools>"].join("\n");
+
+// Single source of truth for main-agent delegation guidance. Injected into the MAIN
+// agent prompt in every phase. Registry-consistent lowercase agent names.
+export const DELEGATION_BLOCK = [
+  "<delegation>",
+  "Prefer delegating over doing wide or deep work yourself — subagents run in parallel, dig",
+  "deeper, and preserve your context. subagent_type is REQUIRED (calls without it are rejected).",
+  "",
+  '- Find or locate code ("where is X", "how does Y connect", map a flow)      → explore',
+  "- External library / API / documentation knowledge                          → librarian",
+  '- Judgment call (design tradeoff, "is this correct", "why is this broken")   → advisor',
+  "- Root-cause a test or build that keeps failing after a quick attempt        → deep-debugger",
+  "- A parallel, self-contained implementation subtask                          → task",
+  "- A code review of your changes — ONLY when the user explicitly asks for one → reviewer",
+  "",
+  "explore FINDS; advisor JUDGES. Spawn several explores in parallel for broad searches.",
+  "Don't use advisor for lookups, or deep-debugger for trivial errors. deep-debugger diagnoses",
+  "only — it must NOT write the actual fix. Do NOT spawn reviewer unless the user explicitly",
+  "asks for a review (the automatic review panel already covers implement/review phases).",
+  "</delegation>",
+].join("\n");

package/extensions/orchestrator/command-handlers.ts

@@ -151,7 +151,7 @@ export function registerCommandHandlers(orchestrator: Orchestrator): void {
       const { showPpMenu } = await import("./pp-menu.js");
       const text = await showPpMenu(orchestrator, ctx, "command");
       if (text) {
-        orchestrator.safeSendUserMessage(`[PI-PI] ${text}`);
+        orchestrator.safeSendUserMessage(text.startsWith("[PI-PI]") ? text : `[PI-PI] ${text}`);
       }
     },
   });

package/extensions/orchestrator/config.ts

@@ -6,8 +6,8 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { isValidLogLevel, getLogger, type LogLevel } from "./log.js";
 
 export type DurationValue = string | number;
-export type OrchestratorRole = "implement" | "plan" | "debug" | "brainstorm" | "review";
-export type SimpleSubagentRole = "explore" | "librarian" | "task";
+export type OrchestratorRole = "implement" | "plan" | "debug" | "brainstorm" | "review" | "quick";
+export type SimpleSubagentRole = "explore" | "librarian" | "task" | "advisor" | "deep-debugger" | "reviewer";
 export type PresetGroupKey = "planners" | "codeReviewers" | "planReviewers" | "brainstormReviewers";
 
 export interface AgentConfig {
@@ -91,8 +91,8 @@ export type TimeoutConfig = NormalizedPiPiConfig["performance"]["internals"];
 
 export const PRESET_GROUPS = ["planners", "codeReviewers", "planReviewers", "brainstormReviewers"] as const;
 
-const ORCHESTRATOR_ROLES: OrchestratorRole[] = ["implement", "plan", "debug", "brainstorm", "review"];
-const SIMPLE_SUBAGENT_ROLES: SimpleSubagentRole[] = ["explore", "librarian", "task"];
+const ORCHESTRATOR_ROLES: OrchestratorRole[] = ["implement", "plan", "debug", "brainstorm", "review", "quick"];
+const SIMPLE_SUBAGENT_ROLES: SimpleSubagentRole[] = ["explore", "librarian", "task", "advisor", "deep-debugger", "reviewer"];
 
 const DEFAULT_CONFIG: PiPiConfig = {
   general: {
@@ -108,12 +108,16 @@ const DEFAULT_CONFIG: PiPiConfig = {
       debug: { model: "openai/gpt-latest", thinking: "high" },
       brainstorm: { model: "anthropic/claude-opus-latest", thinking: "high" },
       review: { model: "anthropic/claude-opus-latest", thinking: "high" },
+      quick: { model: "anthropic/claude-opus-latest", thinking: "high" },
     },
     subagents: {
       simple: {
         explore: { model: "google/gemini-flash-latest", thinking: "low" },
         librarian: { model: "google/gemini-flash-latest", thinking: "medium" },
         task: { model: "anthropic/claude-opus-latest", thinking: "medium" },
+        advisor: { model: "openai/gpt-latest", thinking: "high" },
+        "deep-debugger": { model: "openai/gpt-latest", thinking: "high" },
+        reviewer: { model: "openai/gpt-latest", thinking: "high" },
       },
       presetGroups: {
         planners: {

package/extensions/orchestrator/context.test.ts

@@ -14,6 +14,8 @@ vi.mock("@earendil-works/pi-coding-agent", () => ({
 import {
   getContextDirs,
   getLatestSynthesizedPlan,
+  getArtifactManifest,
+  formatManifestBlock,
   getPhaseArtifacts,
   loadAllContextFiles,
   loadContextFiles,
@@ -377,6 +379,58 @@ describe("getLatestSynthesizedPlan", () => {
   });
 });
 
+describe("getArtifactManifest", () => {
+  it("returns empty when no artifacts or plan exist", () => {
+    const taskDir = makeTempDir();
+    expect(getArtifactManifest(taskDir)).toEqual([]);
+  });
+
+  it("extracts titles from artifact headings with a filename fallback", () => {
+    const taskDir = makeTempDir();
+    const artifactsDir = join(taskDir, "artifacts");
+    mkdirSync(artifactsDir, { recursive: true });
+    writeFileSync(join(artifactsDir, "design.md"), "# My Design\n\nbody", "utf-8");
+    writeFileSync(join(artifactsDir, "notitle.md"), "no heading here", "utf-8");
+
+    const manifest = getArtifactManifest(taskDir);
+    expect(manifest).toEqual([
+      { title: "My Design", path: join(artifactsDir, "design.md") },
+      { title: "artifacts/notitle.md", path: join(artifactsDir, "notitle.md") },
+    ]);
+  });
+
+  it("includes the latest synthesized plan with its REAL path, regardless of phase", () => {
+    const taskDir = makeTempDir();
+    const plansDir = join(taskDir, "plans");
+    mkdirSync(plansDir, { recursive: true });
+    writeFileSync(join(plansDir, "001_synthesized.md"), "old", "utf-8");
+    writeFileSync(join(plansDir, "010_synthesized.md"), "new", "utf-8");
+
+    const manifest = getArtifactManifest(taskDir);
+    expect(manifest).toEqual([
+      { title: "Synthesized implementation plan", path: join(plansDir, "010_synthesized.md") },
+    ]);
+  });
+});
+
+describe("formatManifestBlock", () => {
+  it("emits the do-not-re-read line only when the manifest is empty", () => {
+    const block = formatManifestBlock([]);
+    expect(block).toContain("Do NOT re-read them from disk");
+    expect(block).not.toContain("read them from disk with the read tool");
+  });
+
+  it("lists each manifest entry's path and title for on-demand reading", () => {
+    const block = formatManifestBlock([
+      { title: "Design", path: "/t/artifacts/design.md" },
+      { title: "Synthesized implementation plan", path: "/t/plans/1_synthesized.md" },
+    ]);
+    expect(block).toContain("do NOT re-read them from disk");
+    expect(block).toContain("- /t/artifacts/design.md  — Design");
+    expect(block).toContain("- /t/plans/1_synthesized.md  — Synthesized implementation plan");
+  });
+});
+
 describe("context regressions", () => {
   it("parses bracket array values without truncation when closing bracket is missing", () => {
     const cwd = makeTempDir();

package/extensions/orchestrator/context.ts

@@ -5,7 +5,7 @@ import type { RepoInfo } from "./repo-utils.js";
 import type { Phase } from "./state.js";
 import { getLogger } from "./log.js";
 
-type AgentType = "main" | "explore" | "librarian" | "planner" | "planReviewer" | "task" | "codeReviewer" | "brainstormReviewer";
+type AgentType = "main" | "explore" | "librarian" | "planner" | "planReviewer" | "task" | "codeReviewer" | "brainstormReviewer" | "advisor" | "deep-debugger" | "reviewer";
 type AgentGroup = "all" | "subagents";
 type InjectMode = "system" | "context";
 type PhaseFilter = "brainstorm" | "debug" | "plan" | "implement" | "review";
@@ -30,7 +30,7 @@ interface Frontmatter {
 }
 
 const VALID_INJECT_MODES: readonly string[] = ["system", "context"];
-const VALID_AGENTS: readonly string[] = ["main", "explore", "librarian", "planner", "planReviewer", "task", "codeReviewer", "brainstormReviewer"];
+const VALID_AGENTS: readonly string[] = ["main", "explore", "librarian", "planner", "planReviewer", "task", "codeReviewer", "brainstormReviewer", "advisor", "deep-debugger", "reviewer"];
 const VALID_AGENT_GROUPS: readonly string[] = ["all", "subagents"];
 const VALID_PHASES: readonly string[] = ["brainstorm", "debug", "plan", "implement", "review"];
 const VALID_VENDORS: readonly string[] = ["anthropic", "openai", "google", "unknown"];
@@ -279,6 +279,69 @@ export function getLatestSynthesizedPlan(taskDir: string): string | null {
   return readFileSync(join(plansDir, synthFiles[synthFiles.length - 1]), "utf-8");
 }
 
+function getLatestSynthesizedPlanPath(taskDir: string): string | null {
+  const plansDir = join(taskDir, "plans");
+  if (!existsSync(plansDir)) return null;
+
+  const synthFiles = readdirSync(plansDir)
+    .filter((f) => f.includes("synthesized"))
+    .sort(sortByTimestampPrefix);
+  if (synthFiles.length === 0) return null;
+
+  return join(plansDir, synthFiles[synthFiles.length - 1]);
+}
+
+function extractTitle(path: string, fallback: string): string {
+  try {
+    const content = readFileSync(path, "utf-8");
+    for (const line of content.split("\n")) {
+      const m = line.match(/^#\s+(.+?)\s*$/);
+      if (m) return m[1];
+    }
+  } catch {
+    // fall through to filename fallback
+  }
+  return fallback;
+}
+
+// Path-aware manifest of on-demand task documents (artifacts/*.md + the synthesized
+// plan when present) — each entry carries a REAL filesystem path an agent can read.
+// Unlike getPhaseArtifacts, the plan is included whenever it exists (not phase-gated),
+// so a reviewer spawned in the review phase still gets the plan path.
+export function getArtifactManifest(taskDir: string): { title: string; path: string }[] {
+  const manifest: { title: string; path: string }[] = [];
+
+  const artifactsDir = join(taskDir, "artifacts");
+  if (existsSync(artifactsDir)) {
+    for (const file of readdirSync(artifactsDir).filter((f) => f.endsWith(".md")).sort()) {
+      const path = join(artifactsDir, file);
+      manifest.push({ title: extractTitle(path, `artifacts/${file}`), path });
+    }
+  }
+
+  const planPath = getLatestSynthesizedPlanPath(taskDir);
+  if (planPath) {
+    manifest.push({ title: "Synthesized implementation plan", path: planPath });
+  }
+
+  return manifest;
+}
+
+// Renders a manifest into the trailing prompt block shared by phased panels.
+// Replaces the old "Do NOT re-read them from disk" line: USER_REQUEST/RESEARCH
+// (and the inlined plan) stay in context, while additional artifacts are offered
+// for on-demand reading from disk.
+export function formatManifestBlock(manifest: { title: string; path: string }[]): string {
+  if (manifest.length === 0) {
+    return "The USER REQUEST and RESEARCH above are already in your context. Do NOT re-read them from disk.";
+  }
+  return [
+    "The USER REQUEST and RESEARCH above are already in your context — do NOT re-read them from disk.",
+    "Additional analysis artifacts and the plan are listed below; read them from disk with the read tool if relevant:",
+    ...manifest.map((m) => `- ${m.path}  — ${m.title}`),
+  ].join("\n");
+}
+
 export function loadBrainstormReviewOutputs(taskDir: string, pass: number): { name: string; content: string }[] {
   const dir = join(taskDir, "brainstorm-reviews");
   if (!existsSync(dir)) return [];

package/extensions/orchestrator/custom-footer.ts

@@ -58,7 +58,9 @@ function renderStatsLine(width: number, theme: Theme): string {
   const ctx = footerCtx;
   const tracker = footerTracker;
 
-  const inputTokens = tracker?.getTotalInputTokens() ?? 0;
+  // ↑ is the total input the model actually processed (uncached + cache read +
+  // cache write) across main + subagents — not just the tiny uncached sliver.
+  const inputTokens = tracker?.getTotalProcessedInputTokens() ?? 0;
   const outputTokens = tracker?.getTotalOutputTokens() ?? 0;
   const cacheRate = tracker?.getCacheHitRate() ?? 0;
   const totalCost = tracker?.getTotalCost() ?? 0;
@@ -66,7 +68,8 @@ function renderStatsLine(width: number, theme: Theme): string {
   const cacheSupported = tracker?.isCacheSupported() ?? false;
   const leftParts: string[] = [`↑${formatTokens(inputTokens)}`, `↓${formatTokens(outputTokens)}`];
   if (cacheSupported) leftParts.push(`⚡${Math.round(cacheRate * 100)}%`);
-  if (totalCost > 0) leftParts.push(`$${totalCost.toFixed(2)}`);
+  // Always show cost, even $0.00 (subscription/flat-rate sessions).
+  leftParts.push(`$${totalCost.toFixed(2)}`);
   leftParts.push(toContextUsagePart(ctx, theme));
   let left = leftParts.join(" ");
 

package/extensions/orchestrator/doctor.test.ts

@@ -58,6 +58,7 @@ function createConfig() {
         debug: { model: "openai/gpt-latest", thinking: "high" },
         brainstorm: { model: "anthropic/claude-opus-latest", thinking: "high" },
         review: { model: "anthropic/claude-opus-latest", thinking: "high" },
+        quick: { model: "anthropic/claude-opus-latest", thinking: "high" },
       },
       subagents: {
         simple: {
@@ -143,6 +144,7 @@ function createCtx() {
     },
     modelRegistry: {
       getAvailable: vi.fn(() => [
+        { provider: "anthropic", id: "claude-opus-latest" },
         { provider: "anthropic", id: "claude-opus-4-6" },
         { provider: "openai", id: "gpt-5.4" },
         { provider: "google", id: "gemini-3.1-flash" },
@@ -154,7 +156,7 @@ function createCtx() {
 
 beforeEach(() => {
   const aliasMap: Record<string, string> = {
-    "anthropic/claude-opus-latest": "anthropic/claude-opus-4-6",
+    "anthropic/claude-opus-latest": "anthropic/claude-opus-latest",
     "openai/gpt-latest": "openai/gpt-5.4",
     "google/gemini-flash-latest": "google/gemini-3.1-flash",
     "google/gemini-pro-latest": "google/gemini-3.1-pro",

package/extensions/orchestrator/doctor.ts

@@ -12,7 +12,7 @@ import {
   PRESET_GROUPS,
 } from "./config.js";
 import { resolveModel, getAllAliases } from "./model-registry.js";
-import { loadFlantSettings } from "./flant-infra.js";
+import { loadFlantSettings, readClaudeOAuthToken, readGatewayApiKey, refreshClaudeOAuthToken } from "./flant-infra.js";
 import type { Orchestrator } from "./orchestrator.js";
 
 type Severity = "pass" | "warning" | "failure";
@@ -470,7 +470,7 @@ export async function runDoctor(orchestrator: Orchestrator, ctx: any): Promise<v
 
   await safeCheck(async () => {
     const settings = loadFlantSettings();
-    const shouldCheck = Boolean(process.env.FLANT_API_KEY) || settings.enabled || !!settings.cachedFlantModels || !!settings.cachedOpenRouterData;
+    const shouldCheck = Boolean(process.env.FLANT_API_KEY) || settings.enabled || settings.subscription || !!settings.cachedFlantModels || !!settings.cachedOpenRouterData;
     if (!shouldCheck) {
       addLine({ severity: "pass", text: "Skipped: FLANT_API_KEY not set and no Flant configuration detected" });
       return;
@@ -526,6 +526,44 @@ export async function runDoctor(orchestrator: Orchestrator, ctx: any): Promise<v
     } catch (error) {
       addLine({ severity: "failure", text: `OpenRouter probe failed: ${toErrorMessage(error)}` });
     }
+
+    if (settings.subscription) {
+      const oauthToken = (await refreshClaudeOAuthToken()) ?? readClaudeOAuthToken();
+      const gatewayKey = readGatewayApiKey();
+      if (!oauthToken) {
+        addLine({ severity: "warning", text: "Personal subscription enabled, but no valid Claude OAuth token found (log in to your subscription in pi)" });
+      } else if (!gatewayKey) {
+        addLine({ severity: "warning", text: "Personal subscription enabled, but no gateway key (LLM_API_KEY / FLANT_API_KEY)" });
+      } else {
+        const started = Date.now();
+        try {
+          const response = await timedFetch("https://llm-api.flant.ru/v1/messages", {
+            method: "POST",
+            headers: {
+              "content-type": "application/json",
+              "anthropic-version": "2023-06-01",
+              "anthropic-beta": "claude-code-20250219,oauth-2025-04-20",
+              "user-agent": "claude-cli/1.0.0",
+              "x-app": "cli",
+              Authorization: `Bearer ${oauthToken}`,
+              "x-litellm-api-key": `Bearer ${gatewayKey}`,
+            },
+            body: JSON.stringify({
+              model: "sub/claude-haiku-4-5",
+              max_tokens: 4,
+              messages: [{ role: "user", content: "ping" }],
+            }),
+          }, 15000);
+          if (!response.ok) {
+            addLine({ severity: "failure", text: `Personal subscription probe failed with HTTP ${response.status}` });
+          } else {
+            addLine({ severity: "pass", text: `Personal subscription reachable (sub/claude-*, ${Date.now() - started}ms)` });
+          }
+        } catch (error) {
+          addLine({ severity: "failure", text: `Personal subscription probe failed: ${toErrorMessage(error)}` });
+        }
+      }
+    }
   }, "Flant checks failed");
 
   addCategory("LSP");

package/extensions/orchestrator/event-handlers.test.ts

@@ -1,4 +1,7 @@
-import { describe, expect, it, vi, beforeEach } from "vitest";
+import { afterEach, describe, expect, it, vi, beforeEach } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
 import { registerEventHandlers } from "./event-handlers.js";
 import { Orchestrator, type ActiveTask } from "./orchestrator.js";
 import { getDefaultConfig } from "./config.js";
@@ -251,3 +254,96 @@ describe("ask_user ESC aborts the turn", () => {
     expect(ctx.abort).not.toHaveBeenCalled();
   });
 });
+
+describe("tool_call Agent routing and spawn-time context injection", () => {
+  const tempDirs: string[] = [];
+
+  function makeTaskDir(): string {
+    const dir = mkdtempSync(join(tmpdir(), "pi-pi-agent-hook-test-"));
+    tempDirs.push(dir);
+    writeFileSync(join(dir, "USER_REQUEST.md"), "the user request body", "utf-8");
+    writeFileSync(join(dir, "RESEARCH.md"), "the research body", "utf-8");
+    const artifactsDir = join(dir, "artifacts");
+    mkdirSync(artifactsDir, { recursive: true });
+    writeFileSync(join(artifactsDir, "design.md"), "# Design Doc\n\nstuff", "utf-8");
+    const plansDir = join(dir, "plans");
+    mkdirSync(plansDir, { recursive: true });
+    writeFileSync(join(plansDir, "1_synthesized.md"), "the plan", "utf-8");
+    return dir;
+  }
+
+  function activeWith(dir: string): ActiveTask {
+    const task = makeActiveTask();
+    task.dir = dir;
+    return task;
+  }
+
+  afterEach(() => {
+    for (const dir of tempDirs.splice(0)) {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("blocks a missing subagent_type with a valid-types message", async () => {
+    orchestrator.active = makeActiveTask();
+    const handler = getHandler("tool_call");
+    const result = await handler({ toolName: "Agent", input: { prompt: "do a thing" } }, {});
+    expect(result?.block).toBe(true);
+    expect(result?.reason).toContain("subagent_type is required");
+  });
+
+  it("blocks an unknown subagent_type instead of collapsing to task", async () => {
+    orchestrator.active = makeActiveTask();
+    const handler = getHandler("tool_call");
+    const input: Record<string, unknown> = { subagent_type: "wizard", prompt: "x" };
+    const result = await handler({ toolName: "Agent", input }, {});
+    expect(result?.block).toBe(true);
+    expect(result?.reason).toContain('Unknown subagent_type "wizard"');
+    expect(result?.reason).toContain("deep-debugger");
+    // must NOT have been rewritten to task
+    expect(input.subagent_type).toBe("wizard");
+  });
+
+  it("routes advisor to its own model/thinking and injects context into the prompt", async () => {
+    const dir = makeTaskDir();
+    orchestrator.active = activeWith(dir);
+    const handler = getHandler("tool_call");
+    const input: Record<string, unknown> = { subagent_type: "advisor", prompt: "why is this broken" };
+    const result = await handler({ toolName: "Agent", input }, {});
+    expect(result).toBeUndefined();
+    expect(input.subagent_type).toBe("advisor");
+    expect(input.thinking).toBe("high");
+    const prompt = input.prompt as string;
+    expect(prompt).toContain("why is this broken");
+    expect(prompt).toContain("=== USER REQUEST ===");
+    expect(prompt).toContain("the user request body");
+    expect(prompt).toContain("=== RESEARCH ===");
+    expect(prompt).toContain("the research body");
+    // manifest lists real paths, not inlined content
+    expect(prompt).toContain(join(dir, "artifacts", "design.md"));
+    expect(prompt).toContain(join(dir, "plans", "1_synthesized.md"));
+    expect(prompt).not.toContain("the plan");
+  });
+
+  it("maps deep-debugger via bracket-notation config", async () => {
+    const dir = makeTaskDir();
+    orchestrator.active = activeWith(dir);
+    const handler = getHandler("tool_call");
+    const input: Record<string, unknown> = { subagent_type: "deep-debugger", prompt: "trace it" };
+    const result = await handler({ toolName: "Agent", input }, {});
+    expect(result).toBeUndefined();
+    expect(input.subagent_type).toBe("deep-debugger");
+    expect(input.thinking).toBe("high");
+  });
+
+  it("does NOT inject task context into explore spawns", async () => {
+    const dir = makeTaskDir();
+    orchestrator.active = activeWith(dir);
+    const handler = getHandler("tool_call");
+    const input: Record<string, unknown> = { subagent_type: "explore", prompt: "find X" };
+    const result = await handler({ toolName: "Agent", input }, {});
+    expect(result).toBeUndefined();
+    expect(input.subagent_type).toBe("explore");
+    expect(input.prompt).toBe("find X");
+  });
+});