@jaybeeuu/agent-cortex 1.20.0 → 1.38.1

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/session-start.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { loadSessionContext } from "./context-loader.js";
+import { loadSessionContext } from "./lib/context-loader.js";
 
 /**
  * Session-start extension.

package/extensions/skill-stats/context-loader.test.ts

@@ -7,7 +7,7 @@ import { tmpdir } from "node:os";
 import {
   loadContextFile,
   loadSessionContext,
-} from "../context-loader.ts";
+} from "../lib/context-loader.ts";
 
 // ─── loadContextFile ─────────────────────────────────────────────────────────
 

package/extensions/skill-stats/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/skill-stats/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/skill-stats/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/skill-stats/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/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):