@jaybeeuu/agent-cortex 1.37.1 → 1.39.0

package/extensions/agent-modes/index.ts

@@ -1,7 +1,7 @@
 /**
  * Agent Modes Extension
  *
- * Makes the agent-cortex agents (ralph, ralph-plan, strategy) available as
+ * Makes the agent-cortex agents (ralph, ralph-plan, plan, strategy) available as
  * switchable PI modes. Each mode:
  *   - Injects the agent's full system prompt into the running context
  *   - Restricts tools based on the agent's declared tool set
@@ -9,6 +9,10 @@
  *
  * Modeled on Pi's built-in preset.ts example and R-Dson/pi-modes.
  *
+ * Agents are discovered from the composable source format (`agents/<name>/` +
+ * `agents/<name>/pi/frontmatter.json`) — see agents/README.md. Discovery and
+ * PI-prompt composition live in discover.ts.
+ *
  * Commands:
  *   /agent         — show mode selector
  *   /agent <name>  — switch to agent mode directly
@@ -16,242 +20,27 @@
  *   --agent <name> — start in a specific agent mode
  */
 
-import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Key } from "@earendil-works/pi-tui";
-
-// ─── Types ───────────────────────────────────────────────────────────────────
-
-interface AgentDef {
-  /** Lowercase id derived from filename (e.g. "ralph", "ralph-plan") */
-  id: string;
-  /** Display name from frontmatter or prettified id */
-  name: string;
-  /** Description from frontmatter */
-  description: string;
-  /** Colour for status indicator */
-  color: string;
-  /** PI tool names to enable (empty = all tools) */
-  tools: string[];
-  /** Full agent body (the system prompt to inject) */
-  prompt: string;
-}
-
-interface OriginalState {
-  tools: string[];
-}
-
-// ─── Discovery ───────────────────────────────────────────────────────────────
+import { discoverAgents, DEFAULT_TOOLS, type AgentDef } from "./discover.ts";
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // Agents dir is <extension-root>/../../agents/ — two levels up from extensions/agent-modes/
 const AGENTS_DIR = join(__dirname, "..", "..", "agents");
 
-/**
- * Copilot CLI tool names to PI built-in tool names.
- * Tools not in this map are left as-is (they may be custom tools).
- */
-const COPILOT_TO_PI: Record<string, string[]> = {
-  bash: ["bash"],
-  view: ["read"],
-  read: ["read"],
-  edit: ["edit"],
-  create: ["write"],
-  write: ["write"],
-  grep: ["grep"],
-  rg: ["grep", "find"],
-  glob: ["find", "ls"],
-  find: ["find"],
-  ls: ["ls"],
-};
-
-/**
- * Mapping from agent id → colour for the status indicator.
- */
-const AGENT_COLORS: Record<string, string> = {
-  ralph: "accent",
-  "ralph-plan": "warning",
-  strategy: "accent",
-};
-
-const PERSIST_KEY = "agent-modes-state";
-
-/** Modes with no tool restriction gets the full default set. */
-const DEFAULT_TOOLS = ["read", "bash", "edit", "write", "grep", "find", "ls"];
-
-// ─── Agent file parsing ──────────────────────────────────────────────────────
-
-function parseFrontmatter(raw: string): {
-  name?: string;
-  description?: string;
-  tools?: string[];
-  prompt: string;
-} {
-  const lines = raw.split(/\r?\n/);
-  if (lines[0] !== "---") return { prompt: raw };
-
-  // Find closing ---
-  let sep = -1;
-  for (let i = 1; i < lines.length; i++) {
-    if (lines[i].trim() === "---") {
-      sep = i;
-      break;
-    }
-  }
-  if (sep === -1) return { prompt: raw };
-
-  const yamlLines = lines.slice(1, sep);
-  const prompt = lines.slice(sep + 1).join("\n").trim();
-
-  let name: string | undefined;
-  let description: string | undefined;
-  let tools: string[] | undefined;
-
-  for (const line of yamlLines) {
-    const trimmed = line.trim();
-    const colonIdx = trimmed.indexOf(":");
-    if (colonIdx === -1) continue;
-
-    const key = trimmed.slice(0, colonIdx).trim().toLowerCase();
-    const val = trimmed.slice(colonIdx + 1).trim();
-
-    if (key === "name") {
-      // Strip surrounding quotes
-      name = val.replace(/^["']|["']$/g, "");
-    } else if (key === "description") {
-      description = val.replace(/^["']|["']$/g, "");
-    }
-  }
-
-  // Parse tools from the tools frontmatter.
-  // Supports two formats:
-  //   tools: ["bash", "view"]        (JSON array, single line)
-  //   tools:                         (YAML list, subsequent lines)
-  //     - bash
-  //     - view
-  let inToolsBlock = false;
-  for (const line of yamlLines) {
-    const trimmed = line.trim();
-
-    // Check for inline JSON array: tools: ["foo", "bar"]
-    const colonIdx = trimmed.indexOf(":");
-    if (colonIdx !== -1) {
-      const key = trimmed.slice(0, colonIdx).trim().toLowerCase();
-      const val = trimmed.slice(colonIdx + 1).trim();
-      if (key === "tools") {
-        if (val.startsWith("[")) {
-          // Inline JSON array
-          try {
-            tools = JSON.parse(val);
-          } catch {
-            // Malformed JSON — fall through
-          }
-          continue;
-        }
-        if (val === "[]" || val === "") {
-          // Empty tools — explicit
-          tools = [];
-          continue;
-        }
-      }
-    }
-
-    // YAML block format: "tools:" on its own line, items on subsequent lines
-    if (trimmed === "tools:") {
-      inToolsBlock = true;
-      if (!tools) tools = [];
-      continue;
-    }
-    if (inToolsBlock) {
-      // Check if this line is still part of the tools block (indented or starts with -)
-      if (line.startsWith("  ") || line.startsWith("\t") || trimmed.startsWith("- ")) {
-        const item = trimmed.replace(/^- /, "").trim().replace(/^["']|["']$/g, "");
-        if (item) {
-          if (!tools) tools = [];
-          tools.push(item);
-        }
-      } else if (trimmed !== "") {
-        // Non-empty, non-indented line → tools block ended
-        inToolsBlock = false;
-      }
-    }
-  }
-
-  return { name, description, tools, prompt };
-}
-
-function mapCopilotToolsToPi(copilotTools: string[] | undefined): string[] | undefined {
-  if (!copilotTools || copilotTools.length === 0) return undefined;
-
-  const piTools = new Set<string>();
-  for (const ct of copilotTools) {
-    const mapped = COPILOT_TO_PI[ct];
-    if (mapped) {
-      for (const t of mapped) piTools.add(t);
-    } else {
-      // Pass through unknown tool names (could be custom tools)
-      piTools.add(ct);
-    }
-  }
-  return [...piTools].sort();
-}
-
-function discoverAgents(): AgentDef[] {
-  if (!existsSync(AGENTS_DIR)) {
-    console.warn(`[agent-modes] Agents directory not found: ${AGENTS_DIR}`);
-    return [];
-  }
-
-  const files = readdirSync(AGENTS_DIR)
-    .filter((f) => f.endsWith(".agent.md"))
-    .sort();
-
-  const agents: AgentDef[] = [];
-
-  for (const file of files) {
-    const filePath = join(AGENTS_DIR, file);
-    if (!statSync(filePath).isFile()) continue;
-
-    let raw: string;
-    try {
-      raw = readFileSync(filePath, "utf-8");
-    } catch (err) {
-      console.warn(`[agent-modes] Failed to read ${file}: ${err}`);
-      continue;
-    }
-
-    const parsed = parseFrontmatter(raw);
-    const id = file.replace(/\.agent\.md$/i, "").toLowerCase();
-    const name = parsed.name || prettifyId(id);
-    const tools = mapCopilotToolsToPi(parsed.tools);
-    const color = AGENT_COLORS[id] || "accent";
-
-    agents.push({
-      id,
-      name,
-      description: parsed.description || "",
-      color,
-      tools: tools || [...DEFAULT_TOOLS],
-      prompt: parsed.prompt || `You are ${name}. ${parsed.description || ""}`,
-    });
-  }
-
-  return agents;
+interface OriginalState {
+  tools: string[];
 }
 
-function prettifyId(id: string): string {
-  return id
-    .split("-")
-    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
-    .join(" ");
-}
+const PERSIST_KEY = "agent-modes-state";
 
 // ─── Extension ───────────────────────────────────────────────────────────────
 
 export default function agentModesExtension(pi: ExtensionAPI): void {
-  const agents = discoverAgents();
+  const agents = discoverAgents(AGENTS_DIR);
 
   if (agents.length === 0) {
     console.warn("[agent-modes] No agents found. Extension disabled.");
@@ -270,7 +59,7 @@ export default function agentModesExtension(pi: ExtensionAPI): void {
     return agents[activeAgentIndex].name;
   }
 
-  function getActiveColor(): string {
+  function getActiveColor(): ThemeColor {
     if (activeAgentIndex >= agents.length || activeAgentIndex < 0) return "accent";
     return agents[activeAgentIndex].color;
   }
@@ -504,4 +293,4 @@ export default function agentModesExtension(pi: ExtensionAPI): void {
       }
     }
   });
-}
+}

package/extensions/agent-modes/node_modules/.bin/pi

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules/@earendil-works/pi-coding-agent/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules/@earendil-works/pi-coding-agent/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../@earendil-works/pi-coding-agent/dist/cli.js" "$@"
+else
+  exec node  "$basedir/../@earendil-works/pi-coding-agent/dist/cli.js" "$@"
+fi

package/extensions/agent-modes/node_modules/.bin/tsc

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsc" "$@"
+fi

package/extensions/agent-modes/node_modules/.bin/tsserver

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsserver" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsserver" "$@"
+fi

package/extensions/agent-modes/node_modules/.bin/tsx

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules/tsx/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules/tsx/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../tsx/dist/cli.mjs" "$@"
+else
+  exec node  "$basedir/../tsx/dist/cli.mjs" "$@"
+fi

package/extensions/agent-modes/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@agent-cortex/agent-modes",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "node --test --import tsx/esm discover.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-tui": "^0.78.1",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.78.1"
+  }
+}

package/extensions/agent-modes/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true
+  },
+  "include": ["*.ts"]
+}

package/extensions/subagent/README.md

@@ -96,6 +96,25 @@ Use a chain: first have scout find the read tool, then have planner suggest impr
 | Parallel | `{ tasks: [...] }` | Multiple agents run concurrently (max 8, 4 concurrent) |
 | Chain | `{ chain: [...] }` | Sequential with `{previous}` placeholder |
 
+## Background subagents (task / wait_for_agents / read_agent)
+
+Beyond the all-in-one `subagent` tool, the extension ships three bottom-up tools for
+fire-and-forget orchestration:
+
+- **`task`** — spawn a background sub-agent and return its agent ID immediately. The
+  agent runs detached from the current tool call.
+- **`wait_for_agents`** — block until at least one background sub-agent completes.
+  Pass the `agentIds` (plus optional `timeout` in seconds, default 120); it returns the
+  results of every agent that has finished and `STILL RUNNING` for the rest. This is the
+  event-driven way to run parallel orchestration: dispatch 5 tasks, then one
+  `wait_for_agents` call returns as soon as any of them finishes.
+- **`read_agent`** — fallback: read one specific agent's output once you know it has
+  finished (or query its `STILL RUNNING` state directly).
+
+These mirror Copilot CLI's `task`/`read_agent` model; `wait_for_agents` adds the
+blocking wait that Copilot's poll loop does manually. Abort (Ctrl+C) propagates: a
+pending `wait_for_agents` returns immediately with whatever is known so far.
+
 ## Output Display
 
 **Collapsed view** (default):

package/extensions/subagent/index.ts

@@ -20,6 +20,7 @@ import * as path from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { Message } from "@earendil-works/pi-ai";
 import { type AgentConfig, type AgentScope, discoverAgents } from "./agents.ts";
+import { waitForAgents } from "./wait.ts";
 import { type ExtensionAPI, getMarkdownTheme, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
@@ -1019,6 +1020,16 @@ export default function (pi: ExtensionAPI) {
 		cwd: string;
 	}
 
+	interface ReadAgentDetails {
+		agentId: string;
+		error?: string;
+		status?: string;
+		exitCode?: number;
+		usage?: UsageStats;
+		model?: string;
+		stopReason?: string;
+	}
+
 	const backgroundRuns = new Map<string, BackgroundRun>();
 
 	pi.registerTool({
@@ -1027,7 +1038,7 @@ export default function (pi: ExtensionAPI) {
 		description:
 			"Spawn a background sub-agent with the given prompt and return an agent ID immediately. " +
 			"This is the ONLY tool for spawning subagents — do not use bash or any other tool. " +
-			"Use the read_agent tool to retrieve the result when ready. " +
+			"Use wait_for_agents to block until results are ready, or read_agent to check a specific agent. " +
 			"Compatible with Copilot CLI's task/read_agent subagent model.",
 		parameters: Type.Object({
 			prompt: Type.String({ description: "Task prompt for the sub-agent to execute" }),
@@ -1050,43 +1061,48 @@ export default function (pi: ExtensionAPI) {
 
 			const entry: BackgroundRun = {
 				result: null,
-				promise: (async () => {
-					try {
-						const agents = [backgroundAgent, ...discoverAgents(ctx.cwd, "user").agents];
-						const result = await runSingleAgent(
-							cwd,
-							agents,
-							"background-agent",
-							params.prompt,
-							cwd,
-							undefined,
-							signal,
-							undefined,
-							(results: SingleResult[]) => ({
-								mode: "single" as const,
-								agentScope: "user" as AgentScope,
-								projectAgentsDir: null,
-								results,
-							}),
-						);
-						entry.result = result;
-					} catch (err) {
-						entry.result = {
-							agent: "background-agent",
-							agentSource: "user",
-							task: params.prompt,
-							exitCode: 1,
-							messages: [],
-							stderr: String(err),
-							usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
-						};
-					}
-				})(),
+				promise: Promise.resolve(),
 				startTime: Date.now(),
 				prompt: params.prompt,
 				cwd,
 			};
 
+			const run = (async () => {
+				try {
+					const agents = [backgroundAgent, ...discoverAgents(ctx.cwd, "user").agents];
+					const result = await runSingleAgent(
+						cwd,
+						agents,
+						"background-agent",
+						params.prompt,
+						cwd,
+						undefined,
+						signal,
+						undefined,
+						(results: SingleResult[]) => ({
+							mode: "single" as const,
+							agentScope: "user" as AgentScope,
+							projectAgentsDir: null,
+							results,
+						}),
+					);
+					entry.result = result;
+				} catch (err) {
+					entry.result = {
+						agent: "background-agent",
+						agentSource: "user",
+						task: params.prompt,
+						exitCode: 1,
+						messages: [],
+						stderr: String(err),
+						usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+					};
+				}
+			})();
+			// Attach the real run promise after construction so the run's completion
+			// (entry.result committed before the promise settles) is what waiters race on.
+			entry.promise = run;
+
 			backgroundRuns.set(agentId, entry);
 
 			return {
@@ -1096,6 +1112,73 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	pi.registerTool({
+		name: "wait_for_agents",
+		label: "Wait for Background Agents",
+		description:
+			"Block until at least one background sub-agent spawned with the task tool completes. " +
+			"Takes an array of agentIds and an optional timeout; returns the results of every agent " +
+			"that has completed, and STILL RUNNING for agents that have not. " +
+			"Preserves parallelism: dispatch several tasks, then wait_for_agents returns as soon as " +
+			"any of them finishes. Use read_agent as a fallback to re-read a specific result.",
+		parameters: Type.Object({
+			agentIds: Type.Array(Type.String({ description: "Agent IDs returned by the task tool to wait on" })),
+			timeout: Type.Optional(
+				Type.Number({
+					description:
+						"Maximum seconds to block (default 120) before returning STILL RUNNING for unfinished agents",
+				}),
+			),
+		}),
+		async execute(_toolCallId, params, signal) {
+			const timeoutSeconds = params.timeout ?? 120;
+			const outcome = await waitForAgents(
+				(agentId) => backgroundRuns.get(agentId),
+				params.agentIds,
+				{ timeoutMs: timeoutSeconds * 1000, signal },
+			);
+
+			const lines: string[] = [];
+			if (outcome.aborted) lines.push("(aborted)");
+			if (outcome.timedOut) lines.push(`(timed out after ${timeoutSeconds}s)`);
+			if (lines.length > 0) lines.push("");
+
+			for (const { agentId, result } of outcome.completed) {
+				lines.push(`### ${agentId} — completed`);
+				lines.push(truncateParallelOutput(getResultOutput(result)));
+				lines.push("");
+			}
+			if (outcome.running.length > 0) {
+				lines.push(`### STILL RUNNING (${outcome.running.length})`);
+				lines.push(outcome.running.map((id) => `- ${id}`).join("\n"));
+				lines.push("");
+			}
+			if (outcome.notFound.length > 0) {
+				lines.push(`### NOT FOUND (${outcome.notFound.length})`);
+				lines.push(outcome.notFound.map((id) => `- ${id}`).join("\n"));
+			}
+
+			const summary = `completed: ${outcome.completed.length}, still running: ${outcome.running.length}, not found: ${outcome.notFound.length}`;
+			const body = lines.join("\n").trim();
+			return {
+				content: [{ type: "text", text: body ? `${summary}\n\n${body}` : summary }],
+				details: {
+					agentIds: params.agentIds,
+					completed: outcome.completed.map(({ agentId, result }) => ({
+						agentId,
+						exitCode: result.exitCode,
+						stopReason: result.stopReason,
+						output: truncateParallelOutput(getResultOutput(result)),
+					})),
+					running: outcome.running,
+					notFound: outcome.notFound,
+					timedOut: outcome.timedOut,
+					aborted: outcome.aborted,
+				},
+			};
+		},
+	});
+
 	pi.registerTool({
 		name: "read_agent",
 		label: "Read Background Agent Output",
@@ -1107,31 +1190,34 @@ export default function (pi: ExtensionAPI) {
 		}),
 		async execute(_toolCallId, params) {
 			const entry = backgroundRuns.get(params.agentId);
+			const details: ReadAgentDetails = {
+				agentId: params.agentId,
+				error: !entry ? "not found" : undefined,
+				status: entry && !entry.result ? "running" : undefined,
+				exitCode: entry?.result?.exitCode,
+				usage: entry?.result?.usage,
+				model: entry?.result?.model,
+				stopReason: entry?.result?.stopReason,
+			};
+
 			if (!entry) {
 				return {
 					content: [{ type: "text", text: `ERROR: No agent found with ID "${params.agentId}"` }],
-					details: { error: "not found", agentId: params.agentId },
+					details,
 				};
 			}
 
 			if (entry.result) {
-				const output = getResultOutput(entry.result);
 				return {
-					content: [{ type: "text", text: output }],
-					details: {
-						agentId: params.agentId,
-						exitCode: entry.result.exitCode,
-						usage: entry.result.usage,
-						model: entry.result.model,
-						stopReason: entry.result.stopReason,
-					},
+					content: [{ type: "text", text: getResultOutput(entry.result) }],
+					details,
 				};
 			}
 
-			// Still running — check if the promise is still active
+			// Still running — the wait_for_agents tool can block until it finishes.
 			return {
 				content: [{ type: "text", text: "STILL RUNNING" }],
-				details: { status: "running", agentId: params.agentId },
+				details,
 			};
 		},
 	});