oira666_pi-subagent 0.1.0

package/index.ts

@@ -0,0 +1,865 @@
+/**
+ * Pi Subagent Extension
+ *
+ * Delegates tasks to specialized subagents, each running as an isolated `pi`
+ * process.
+ *
+ * The tool always accepts a `tasks` array:
+ *   - One task: treated as a single-agent delegation.
+ *   - Multiple tasks: treated as a parallel delegation.
+ *
+ * And two context modes:
+ *   - spawn (default): child gets only the task prompt.
+ *   - fork: child gets a forked snapshot of current session context + task prompt.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { type AgentConfig, discoverAgents } from "./agents.js";
+import { renderCall, renderResult } from "./render.js";
+import { mapConcurrent, runAgent } from "./runner.js";
+import {
+  type DelegationMode,
+  type SingleResult,
+  type SubagentDetails,
+  DEFAULT_DELEGATION_MODE,
+  emptyUsage,
+  getFinalOutput,
+  isResultError,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Limits
+// ---------------------------------------------------------------------------
+
+const DEFAULT_MAX_PARALLEL_TASKS = 16;
+const DEFAULT_MAX_CONCURRENCY = 8;
+const PARALLEL_HEARTBEAT_MS = 1000;
+const DEFAULT_MAX_DELEGATION_DEPTH = 3;
+const DEFAULT_PREVENT_CYCLE_DELEGATION = false;
+const DEFAULT_PROJECT_AGENT_CONFIRMATION = "ask";
+const SUBAGENT_DEPTH_ENV = "PI_SUBAGENT_DEPTH";
+const SUBAGENT_MAX_DEPTH_ENV = "PI_SUBAGENT_MAX_DEPTH";
+const SUBAGENT_STACK_ENV = "PI_SUBAGENT_STACK";
+const SUBAGENT_PREVENT_CYCLES_ENV = "PI_SUBAGENT_PREVENT_CYCLES";
+const SUBAGENT_MAX_PARALLEL_TASKS_ENV = "PI_SUBAGENT_MAX_PARALLEL_TASKS";
+const SUBAGENT_MAX_CONCURRENCY_ENV = "PI_SUBAGENT_MAX_CONCURRENCY";
+const SUBAGENT_CONFIRM_PROJECT_AGENTS_ENV = "PI_SUBAGENT_CONFIRM_PROJECT_AGENTS";
+
+type ProjectAgentConfirmationSetting = "ask" | "never" | "session";
+type ProjectAgentApproval = "once" | "session" | "no";
+
+// ---------------------------------------------------------------------------
+// Tool parameter schema
+// ---------------------------------------------------------------------------
+
+const TaskItem = Type.Object({
+  agent: Type.String({
+    description: "Name of an available agent (must match exactly)",
+  }),
+  task: Type.String({
+    description:
+      "Task description for this delegated run. In spawn mode include all required context; in fork mode the subagent also sees your current session context.",
+  }),
+  cwd: Type.Optional(
+    Type.String({ description: "Working directory for this agent's process" }),
+  ),
+});
+
+const SubagentParams = Type.Object({
+  tasks: Type.Array(TaskItem, {
+    minItems: 1,
+    description:
+      "Array of {agent, task} objects. One task behaves like a single-agent delegation; multiple tasks run concurrently.",
+  }),
+  mode: Type.Optional(
+    Type.String({
+      description:
+        "Context mode for delegated runs. 'spawn' (default) sends only the task prompt (best for isolated, reproducible runs with lower token/cost and less context leakage). 'fork' adds a snapshot of current session context plus task prompt (best for follow-up work, but usually higher token/cost and may include sensitive context).",
+      default: DEFAULT_DELEGATION_MODE,
+    }),
+  ),
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+interface DelegationDepthConfig {
+  currentDepth: number;
+  maxDepth: number;
+  canDelegate: boolean;
+  ancestorAgentStack: string[];
+  preventCycles: boolean;
+}
+
+interface SessionSnapshotSource {
+  getHeader: () => unknown;
+  getBranch: () => unknown[];
+}
+
+function parseDelegationMode(raw: unknown): DelegationMode | null {
+  if (raw === undefined) return DEFAULT_DELEGATION_MODE;
+  if (typeof raw !== "string") return null;
+  const normalized = raw.trim().toLowerCase();
+  if (normalized === "spawn" || normalized === "fork") {
+    return normalized;
+  }
+  return null;
+}
+
+function buildForkSessionSnapshotJsonl(
+  sessionManager: SessionSnapshotSource,
+): string | null {
+  const header = sessionManager.getHeader();
+  if (!header || typeof header !== "object") return null;
+
+  const branchEntries = sessionManager.getBranch();
+  const lines = [JSON.stringify(header)];
+  for (const entry of branchEntries) lines.push(JSON.stringify(entry));
+  return `${lines.join("\n")}\n`;
+}
+
+function parseNonNegativeInt(raw: unknown): number | null {
+  if (typeof raw !== "string") return null;
+  const trimmed = raw.trim();
+  if (!/^\d+$/.test(trimmed)) return null;
+  const parsed = Number(trimmed);
+  return Number.isSafeInteger(parsed) ? parsed : null;
+}
+
+function parseBoolean(raw: unknown): boolean | null {
+  if (typeof raw === "boolean") return raw;
+  if (typeof raw !== "string") return null;
+  const normalized = raw.trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "off"].includes(normalized)) return false;
+  return null;
+}
+
+function parseProjectAgentConfirmationSetting(
+  raw: unknown,
+): ProjectAgentConfirmationSetting | null {
+  if (raw === undefined) return DEFAULT_PROJECT_AGENT_CONFIRMATION;
+
+  const parsedBoolean = parseBoolean(raw);
+  if (parsedBoolean === true) return "ask";
+  if (parsedBoolean === false) return "never";
+
+  if (typeof raw !== "string") return null;
+  const normalized = raw.trim().toLowerCase();
+  if (["ask", "prompt", "once"].includes(normalized)) return "ask";
+  if (["never", "allow", "skip"].includes(normalized)) return "never";
+  if (["session", "remember", "yes-for-session"].includes(normalized)) {
+    return "session";
+  }
+  return null;
+}
+
+function resolveProjectAgentConfirmationSetting(
+  raw: unknown,
+): ProjectAgentConfirmationSetting {
+  const parsed = parseProjectAgentConfirmationSetting(raw);
+  if (raw !== undefined && parsed === null) {
+    console.warn(
+      `[pi-subagent] Ignoring invalid ${SUBAGENT_CONFIRM_PROJECT_AGENTS_ENV}="${String(raw)}". Expected one of: true, false, ask, never, session.`,
+    );
+  }
+  return parsed ?? DEFAULT_PROJECT_AGENT_CONFIRMATION;
+}
+
+function getProjectAgentConfirmationSetting(): ProjectAgentConfirmationSetting {
+  return resolveProjectAgentConfirmationSetting(
+    process.env[SUBAGENT_CONFIRM_PROJECT_AGENTS_ENV],
+  );
+}
+
+function parseAgentStack(raw: unknown): string[] | null {
+  if (raw === undefined) return [];
+  if (typeof raw !== "string") return null;
+  if (!raw.trim()) return [];
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  if (!Array.isArray(parsed)) return null;
+  if (!parsed.every((value) => typeof value === "string")) return null;
+  return parsed
+    .map((value) => value.trim())
+    .filter((value) => value.length > 0);
+}
+
+function getMaxDepthFlagFromArgv(argv: string[]): string | null {
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--subagent-max-depth") {
+      return argv[i + 1] ?? "";
+    }
+    if (arg.startsWith("--subagent-max-depth=")) {
+      return arg.slice("--subagent-max-depth=".length);
+    }
+  }
+  return null;
+}
+
+function getPreventCyclesFlagFromArgv(
+  argv: string[],
+): string | boolean | null {
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--subagent-prevent-cycles") {
+      const maybeValue = argv[i + 1];
+      if (maybeValue !== undefined && !maybeValue.startsWith("--")) {
+        return maybeValue;
+      }
+      return true;
+    }
+    if (arg === "--no-subagent-prevent-cycles") return false;
+    if (arg.startsWith("--subagent-prevent-cycles=")) {
+      return arg.slice("--subagent-prevent-cycles=".length);
+    }
+  }
+  return null;
+}
+
+function resolveDelegationDepthConfig(pi: ExtensionAPI): DelegationDepthConfig {
+  const depthRaw = process.env[SUBAGENT_DEPTH_ENV];
+  const parsedDepth = parseNonNegativeInt(depthRaw);
+  if (depthRaw !== undefined && parsedDepth === null) {
+    console.warn(
+      `[pi-subagent] Ignoring invalid ${SUBAGENT_DEPTH_ENV}="${depthRaw}". Expected a non-negative integer.`,
+    );
+  }
+  const currentDepth = parsedDepth ?? 0;
+
+  const stackRaw = process.env[SUBAGENT_STACK_ENV];
+  const ancestorAgentStack = parseAgentStack(stackRaw);
+  if (stackRaw !== undefined && ancestorAgentStack === null) {
+    console.warn(
+      `[pi-subagent] Ignoring invalid ${SUBAGENT_STACK_ENV} value. Expected a JSON array of agent names.`,
+    );
+  }
+
+  const envMaxDepthRaw = process.env[SUBAGENT_MAX_DEPTH_ENV];
+  const envMaxDepth = parseNonNegativeInt(envMaxDepthRaw);
+  if (envMaxDepthRaw !== undefined && envMaxDepth === null) {
+    console.warn(
+      `[pi-subagent] Ignoring invalid ${SUBAGENT_MAX_DEPTH_ENV}="${envMaxDepthRaw}". Expected a non-negative integer.`,
+    );
+  }
+
+  const argvFlagRaw = getMaxDepthFlagFromArgv(process.argv);
+  const argvFlagMaxDepth =
+    argvFlagRaw !== null ? parseNonNegativeInt(argvFlagRaw) : null;
+  if (argvFlagRaw !== null && argvFlagMaxDepth === null) {
+    console.warn(
+      `[pi-subagent] Ignoring invalid --subagent-max-depth value "${argvFlagRaw}". Expected a non-negative integer.`,
+    );
+  }
+
+  const runtimeFlagValue = pi.getFlag("subagent-max-depth");
+  const runtimeFlagMaxDepth =
+    typeof runtimeFlagValue === "string"
+      ? parseNonNegativeInt(runtimeFlagValue)
+      : null;
+  if (
+    argvFlagRaw === null &&
+    typeof runtimeFlagValue === "string" &&
+    runtimeFlagMaxDepth === null
+  ) {
+    console.warn(
+      `[pi-subagent] Ignoring invalid --subagent-max-depth value "${runtimeFlagValue}". Expected a non-negative integer.`,
+    );
+  }
+
+  const envPreventCyclesRaw = process.env[SUBAGENT_PREVENT_CYCLES_ENV];
+  const envPreventCycles = parseBoolean(envPreventCyclesRaw);
+  if (envPreventCyclesRaw !== undefined && envPreventCycles === null) {
+    console.warn(
+      `[pi-subagent] Ignoring invalid ${SUBAGENT_PREVENT_CYCLES_ENV}="${envPreventCyclesRaw}". Expected true/false.`,
+    );
+  }
+
+  const argvPreventCyclesRaw = getPreventCyclesFlagFromArgv(process.argv);
+  const argvPreventCycles =
+    typeof argvPreventCyclesRaw === "boolean"
+      ? argvPreventCyclesRaw
+      : parseBoolean(argvPreventCyclesRaw);
+  if (
+    typeof argvPreventCyclesRaw === "string" &&
+    argvPreventCycles === null
+  ) {
+    console.warn(
+      `[pi-subagent] Ignoring invalid --subagent-prevent-cycles value "${argvPreventCyclesRaw}". Expected true/false.`,
+    );
+  }
+
+  const runtimePreventCyclesRaw = pi.getFlag("subagent-prevent-cycles");
+  const runtimePreventCycles = parseBoolean(runtimePreventCyclesRaw);
+  if (
+    argvPreventCyclesRaw === null &&
+    runtimePreventCyclesRaw !== undefined &&
+    runtimePreventCycles === null
+  ) {
+    console.warn(
+      `[pi-subagent] Ignoring invalid --subagent-prevent-cycles value "${String(runtimePreventCyclesRaw)}". Expected true/false.`,
+    );
+  }
+
+  const flagMaxDepth = argvFlagMaxDepth ?? runtimeFlagMaxDepth;
+  const maxDepth = flagMaxDepth ?? envMaxDepth ?? DEFAULT_MAX_DELEGATION_DEPTH;
+  const preventCycles =
+    argvPreventCycles ??
+    runtimePreventCycles ??
+    envPreventCycles ??
+    DEFAULT_PREVENT_CYCLE_DELEGATION;
+
+  return {
+    currentDepth,
+    maxDepth,
+    canDelegate: currentDepth < maxDepth,
+    ancestorAgentStack: ancestorAgentStack ?? [],
+    preventCycles,
+  };
+}
+
+function makeDetailsFactory(
+  projectAgentsDir: string | null,
+  delegationMode: DelegationMode,
+) {
+  return (mode: "single" | "parallel") =>
+    (results: SingleResult[]): SubagentDetails => ({
+      mode,
+      delegationMode,
+      projectAgentsDir,
+      results,
+    });
+}
+
+function formatAgentNames(agents: AgentConfig[]): string {
+  return agents.map((a) => `${a.name} (${a.source})`).join(", ") || "none";
+}
+
+function getCycleViolations(
+  requestedNames: Set<string>,
+  ancestorAgentStack: string[],
+): string[] {
+  if (requestedNames.size === 0 || ancestorAgentStack.length === 0) return [];
+  const stackSet = new Set(ancestorAgentStack);
+  return Array.from(requestedNames).filter((name) => stackSet.has(name));
+}
+
+/** Get project-local agents referenced by the current request. */
+function getRequestedProjectAgents(
+  agents: AgentConfig[],
+  requestedNames: Set<string>,
+): AgentConfig[] {
+  return Array.from(requestedNames)
+    .map((name) => agents.find((a) => a.name === name))
+    .filter((a): a is AgentConfig => a?.source === "project");
+}
+
+/**
+ * Prompt the user to confirm project-local agents if needed.
+ */
+async function confirmProjectAgentsIfNeeded(
+  projectAgents: AgentConfig[],
+  projectAgentsDir: string | null,
+  ctx: { ui: { select: (title: string, options: string[]) => Promise<string | undefined> } },
+): Promise<ProjectAgentApproval> {
+  if (projectAgents.length === 0) return "once";
+
+  const names = projectAgents.map((a) => a.name).join(", ");
+  const dir = projectAgentsDir ?? "(unknown)";
+  const selection = await ctx.ui.select(
+    `Run project-local agents?\nAgents: ${names}\nSource: ${dir}\n\nProject agents are repo-controlled. Only continue for trusted repositories.`,
+    ["Yes once", "Yes for this session", "No"],
+  );
+
+  if (selection === "Yes once") return "once";
+  if (selection === "Yes for this session") return "session";
+  return "no";
+}
+
+function getProjectAgentSessionKey(projectAgentsDir: string | null): string {
+  return projectAgentsDir ?? "(unknown-project-agents-dir)";
+}
+
+// ---------------------------------------------------------------------------
+// Extension entry point
+// ---------------------------------------------------------------------------
+
+export default function (pi: ExtensionAPI) {
+  pi.registerFlag("subagent-max-depth", {
+    description: "Maximum allowed subagent delegation depth (default: 3).",
+    type: "string",
+  });
+  pi.registerFlag("subagent-prevent-cycles", {
+    description:
+      "Block delegating to agents already in the current delegation stack (default: true).",
+    type: "boolean",
+  });
+
+  const depthConfig = resolveDelegationDepthConfig(pi);
+  const { currentDepth, maxDepth, canDelegate, ancestorAgentStack, preventCycles } =
+    depthConfig;
+
+  let discoveredAgents: AgentConfig[] = [];
+  const approvedProjectAgentDirsForSession = new Set<string>();
+
+  // Auto-discover agents on session start
+  pi.on("session_start", async (_event, ctx) => {
+    if (!canDelegate) return;
+
+    const discovery = discoverAgents(ctx.cwd, "both");
+    discoveredAgents = discovery.agents;
+
+    if (discoveredAgents.length > 0 && ctx.hasUI) {
+      const list = discoveredAgents
+        .map((a) => `  - ${a.name} (${a.source})`)
+        .join("\n");
+      ctx.ui.notify(
+        `Found ${discoveredAgents.length} subagent(s):\n${list}`,
+        "info",
+      );
+    }
+  });
+
+  // Inject available agents into the system prompt
+  pi.on("before_agent_start", async (event) => {
+    if (!canDelegate) return;
+    if (discoveredAgents.length === 0) return;
+
+    const agentList = discoveredAgents
+      .map((a) => `- **${a.name}**: ${a.description}`)
+      .join("\n");
+    return {
+      systemPrompt:
+        event.systemPrompt +
+        `\n\n## Available Subagents
+
+The following subagents are available via the \`subagent\` tool:
+
+${agentList}
+
+### How to call the subagent tool
+
+Each subagent runs in an **isolated process**.
+
+Context behavior is controlled by optional 'mode':
+- 'spawn' (default): child receives only the provided task prompt. Best for isolated, reproducible tasks with lower token/cost and less context leakage.
+- 'fork': child receives a forked snapshot of current session context plus the task prompt. Best for follow-up tasks that rely on prior context; usually higher token/cost and may include sensitive context.
+
+The tool always accepts a \`tasks\` array:
+- one item = single-agent delegation
+- multiple items = parallel delegation
+
+**Single-task delegation**:
+\`\`\`json
+{ "tasks": [{ "agent": "agent-name", "task": "Detailed task..." }], "mode": "spawn" }
+\`\`\`
+
+**Multi-task delegation**:
+\`\`\`json
+{ "tasks": [{ "agent": "agent-name", "task": "..." }, { "agent": "other-agent", "task": "..." }], "mode": "fork" }
+\`\`\`
+
+### Runtime delegation guards
+
+- Max depth: current depth ${currentDepth}, max depth ${maxDepth}
+- Cycle prevention: ${preventCycles ? "enabled" : "disabled"}
+- Current delegation stack: ${ancestorAgentStack.length > 0 ? ancestorAgentStack.join(" -> ") : "(root)"}
+`,
+    };
+  });
+
+  // Register the subagent tool
+  if (canDelegate) {
+    pi.registerTool({
+      name: "subagent",
+      label: "Subagent",
+      description: [
+        "Delegate work to specialized subagents running in isolated pi processes.",
+        "",
+        "The tool always accepts a `tasks` array:",
+        "  - one task: single-agent delegation",
+        "  - multiple tasks: parallel delegation",
+        "",
+        "Optional context mode switch:",
+        "  mode: \"spawn\" (default) -> child gets only your task prompt.",
+        "                             Best for isolated/reproducible work; lower token/cost and less context leakage.",
+        "  mode: \"fork\"            -> child gets current session context + your task prompt.",
+        "                             Best for follow-up work that depends on prior context; higher token/cost and may include sensitive context.",
+        "",
+        'Example single:   { tasks: [{ agent: "writer", task: "Rewrite README.md" }], mode: "spawn" }',
+        'Example parallel: { tasks: [{ agent: "writer", task: "..." }, { agent: "tester", task: "..." }], mode: "fork" }',
+      ].join("\n"),
+      parameters: SubagentParams,
+
+      async execute(_toolCallId, params, signal, onUpdate, ctx) {
+        const discovery = discoverAgents(ctx.cwd, "both");
+        const { agents } = discovery;
+
+        const delegationMode = parseDelegationMode(params.mode);
+        if (!delegationMode) {
+          const fallbackDetails = makeDetailsFactory(
+            discovery.projectAgentsDir,
+            DEFAULT_DELEGATION_MODE,
+          );
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Invalid mode \"${String(params.mode)}\". Expected \"spawn\" or \"fork\".\nAvailable agents: ${formatAgentNames(agents)}`,
+              },
+            ],
+            details: fallbackDetails("single")([]),
+            isError: true,
+          };
+        }
+
+        const makeDetails = makeDetailsFactory(
+          discovery.projectAgentsDir,
+          delegationMode,
+        );
+
+        let forkSessionSnapshotJsonl: string | undefined;
+        if (delegationMode === "fork") {
+          forkSessionSnapshotJsonl = buildForkSessionSnapshotJsonl(
+            ctx.sessionManager,
+          );
+          if (!forkSessionSnapshotJsonl) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: "Cannot use mode=\"fork\": failed to snapshot current session context.",
+                },
+              ],
+              details: makeDetails("single")([]),
+              isError: true,
+            };
+          }
+        }
+
+        const tasks = params.tasks ?? [];
+        if (tasks.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Invalid parameters. Provide a non-empty tasks array.\nAvailable agents: ${formatAgentNames(agents)}`,
+              },
+            ],
+            details: makeDetails("single")([]),
+          };
+        }
+
+        const executionMode = tasks.length === 1 ? "single" : "parallel";
+
+        // Security: guard project-local agents before running
+        const requested = new Set<string>();
+        for (const t of tasks) requested.add(t.agent);
+
+        if (preventCycles) {
+          const cycleViolations = getCycleViolations(
+            requested,
+            ancestorAgentStack,
+          );
+          if (cycleViolations.length > 0) {
+            const stackText =
+              ancestorAgentStack.length > 0
+                ? ancestorAgentStack.join(" -> ")
+                : "(root)";
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Blocked: delegation cycle detected. Requested agent(s) already in the delegation stack: ${cycleViolations.join(", ")}.
+Current stack: ${stackText}
+
+This guard prevents self-recursion and cyclic handoffs (for example A -> B -> A).`,
+                },
+              ],
+              details: makeDetails(executionMode)([]),
+              isError: true,
+            };
+          }
+        }
+
+        const requestedProjectAgents = getRequestedProjectAgents(
+          agents,
+          requested,
+        );
+        const projectAgentConfirmationSetting =
+          getProjectAgentConfirmationSetting();
+        const projectAgentSessionKey = getProjectAgentSessionKey(
+          discovery.projectAgentsDir,
+        );
+        const shouldConfirmProjectAgents =
+          requestedProjectAgents.length > 0 &&
+          projectAgentConfirmationSetting === "ask" &&
+          !approvedProjectAgentDirsForSession.has(projectAgentSessionKey);
+        if (shouldConfirmProjectAgents) {
+          if (ctx.hasUI) {
+            const approval = await confirmProjectAgentsIfNeeded(
+              requestedProjectAgents,
+              discovery.projectAgentsDir,
+              ctx,
+            );
+            if (approval === "no") {
+              return {
+                content: [
+                  {
+                    type: "text",
+                    text: "Canceled: project-local agents not approved.",
+                  },
+                ],
+                details: makeDetails(executionMode)([]),
+              };
+            }
+            if (approval === "session") {
+              approvedProjectAgentDirsForSession.add(projectAgentSessionKey);
+            }
+          } else {
+            const names = requestedProjectAgents.map((a) => a.name).join(", ");
+            const dir = discovery.projectAgentsDir ?? "(unknown)";
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Blocked: project-local agent confirmation is required in non-UI mode.\nAgents: ${names}\nSource: ${dir}\n\nSet ${SUBAGENT_CONFIRM_PROJECT_AGENTS_ENV}=false or =session only if this repository is trusted.`,
+                },
+              ],
+              details: makeDetails(executionMode)([]),
+              isError: true,
+            };
+          }
+        }
+
+        if (tasks.length === 1) {
+          const [task] = tasks;
+          return executeSingle(
+            task.agent,
+            task.task,
+            task.cwd,
+            delegationMode,
+            forkSessionSnapshotJsonl,
+            agents,
+            ctx.cwd,
+            signal,
+            onUpdate,
+            makeDetails,
+          );
+        }
+
+        return executeParallel(
+          tasks,
+          delegationMode,
+          forkSessionSnapshotJsonl,
+          agents,
+          ctx.cwd,
+          signal,
+          onUpdate,
+          makeDetails,
+        );
+      },
+
+      renderCall: (args, theme) => renderCall(args, theme),
+      renderResult: (result, { expanded }, theme) =>
+        renderResult(result, expanded, theme),
+    });
+  }
+
+  // -----------------------------------------------------------------------
+  // Mode implementations
+  // -----------------------------------------------------------------------
+
+  async function executeSingle(
+    agentName: string,
+    task: string,
+    cwd: string | undefined,
+    delegationMode: DelegationMode,
+    forkSessionSnapshotJsonl: string | undefined,
+    agents: AgentConfig[],
+    defaultCwd: string,
+    signal: AbortSignal | undefined,
+    onUpdate: ((partial: any) => void) | undefined,
+    makeDetails: ReturnType<typeof makeDetailsFactory>,
+  ) {
+    const result = await runAgent({
+      cwd: defaultCwd,
+      agents,
+      agentName,
+      task,
+      taskCwd: cwd,
+      delegationMode,
+      forkSessionSnapshotJsonl,
+      parentDepth: currentDepth,
+      parentAgentStack: ancestorAgentStack,
+      maxDepth,
+      preventCycles,
+      signal,
+      onUpdate,
+      makeDetails: makeDetails("single"),
+    });
+
+    if (isResultError(result)) {
+      const errorMsg =
+        result.errorMessage ||
+        result.stderr ||
+        getFinalOutput(result.messages) ||
+        "(no output)";
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Agent ${result.stopReason || "failed"}: ${errorMsg}`,
+          },
+        ],
+        details: makeDetails("single")([result]),
+        isError: true,
+      };
+    }
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: getFinalOutput(result.messages) || "(no output)",
+        },
+      ],
+      details: makeDetails("single")([result]),
+    };
+  }
+
+  async function executeParallel(
+    tasks: Array<{ agent: string; task: string; cwd?: string }>,
+    delegationMode: DelegationMode,
+    forkSessionSnapshotJsonl: string | undefined,
+    agents: AgentConfig[],
+    defaultCwd: string,
+    signal: AbortSignal | undefined,
+    onUpdate: ((partial: any) => void) | undefined,
+    makeDetails: ReturnType<typeof makeDetailsFactory>,
+  ) {
+    const maxParallelTasksRaw = process.env[SUBAGENT_MAX_PARALLEL_TASKS_ENV];
+    const maxParallelTasksParsed = parseNonNegativeInt(maxParallelTasksRaw);
+    if (maxParallelTasksRaw !== undefined && maxParallelTasksParsed === null) {
+      console.warn(
+        `[pi-subagent] Ignoring invalid ${SUBAGENT_MAX_PARALLEL_TASKS_ENV}="${maxParallelTasksRaw}". Expected a non-negative integer.`
+      );
+    }
+    const maxParallelTasks = maxParallelTasksParsed ?? DEFAULT_MAX_PARALLEL_TASKS;
+
+    const maxConcurrencyRaw = process.env[SUBAGENT_MAX_CONCURRENCY_ENV];
+    const maxConcurrencyParsed = parseNonNegativeInt(maxConcurrencyRaw);
+    if (maxConcurrencyRaw !== undefined && maxConcurrencyParsed === null) {
+      console.warn(
+        `[pi-subagent] Ignoring invalid ${SUBAGENT_MAX_CONCURRENCY_ENV}="${maxConcurrencyRaw}". Expected a non-negative integer.`
+      );
+    }
+    const maxConcurrency = maxConcurrencyParsed ?? DEFAULT_MAX_CONCURRENCY;
+
+    if (tasks.length > maxParallelTasks) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Too many parallel tasks (${tasks.length}). Max is ${maxParallelTasks}.`,
+          },
+        ],
+        details: makeDetails("parallel")([]),
+      };
+    }
+
+    // Initialize placeholder results for streaming
+    const allResults: SingleResult[] = tasks.map((t) => ({
+      agent: t.agent,
+      agentSource: "unknown" as const,
+      task: t.task,
+      exitCode: -1,
+      messages: [],
+      stderr: "",
+      usage: emptyUsage(),
+    }));
+
+    const emitProgress = () => {
+      if (!onUpdate) return;
+      const running = allResults.filter((r) => r.exitCode === -1).length;
+      const done = allResults.filter((r) => r.exitCode !== -1).length;
+      onUpdate({
+        content: [
+          {
+            type: "text",
+            text: `Parallel: ${done}/${allResults.length} done, ${running} running...`,
+          },
+        ],
+        details: makeDetails("parallel")([...allResults]),
+      });
+    };
+
+    let heartbeat: NodeJS.Timeout | undefined;
+    if (onUpdate) {
+      emitProgress();
+      heartbeat = setInterval(() => {
+        if (allResults.some((r) => r.exitCode === -1)) emitProgress();
+      }, PARALLEL_HEARTBEAT_MS);
+    }
+
+    let results: SingleResult[];
+    try {
+      results = await mapConcurrent(
+        tasks,
+        maxConcurrency,
+        async (t, index) => {
+          const result = await runAgent({
+            cwd: defaultCwd,
+            agents,
+            agentName: t.agent,
+            task: t.task,
+            taskCwd: t.cwd,
+            delegationMode,
+            forkSessionSnapshotJsonl,
+            parentDepth: currentDepth,
+            parentAgentStack: ancestorAgentStack,
+            maxDepth,
+            preventCycles,
+            signal,
+            onUpdate: (partial) => {
+              if (partial.details?.results[0]) {
+                allResults[index] = partial.details.results[0];
+                emitProgress();
+              }
+            },
+            makeDetails: makeDetails("parallel"),
+          });
+          allResults[index] = result;
+          emitProgress();
+          return result;
+        },
+      );
+    } finally {
+      if (heartbeat) clearInterval(heartbeat);
+    }
+
+    const successCount = results.filter((r) => r.exitCode === 0).length;
+    const summaries = results.map((r) => {
+      const output = getFinalOutput(r.messages);
+      return `[${r.agent}] ${r.exitCode === 0 ? "completed" : "failed"}: ${output || "(no output)"}`;
+    });
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `Parallel: ${successCount}/${results.length} succeeded\n\n${summaries.join("\n\n")}`,
+        },
+      ],
+      details: makeDetails("parallel")(results),
+    };
+  }
+}