killeros 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to KillerOS are documented here.
 
+## [1.4.0] - 2026-08-01
+
+### Added
+
+- Pi-native `subagent` tool with isolated JSONL child processes, single/parallel/chain modes, streamed TUI status, aggregate usage, and abort propagation.
+- Bundled Markdown roles for read-only scouting, planning, and review plus one serialized write-capable worker.
+- Strict role, tool, model, trust, precedence, concurrency, turn, timeout, trace, stderr, and output enforcement.
+
 ## [1.3.0] - 2026-07-31
 
 ### Added

package/Killeros.ts

@@ -31,6 +31,7 @@ import {
   type TUI,
 } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
+import { registerSubagentTool } from "./subagents.ts";
 
 const COMMAND_BLUE_RGB = "120;169;255";
 const FOOTER_REFRESH_INTERVAL_MS = 1_000;
@@ -2541,6 +2542,7 @@ export default function Killeros(pi: ExtensionAPI): void {
   registerGoal(pi, goalRuntime, initState);
   registerPersonalInstructions(pi, initState);
   registerQuestionTool(pi);
+  registerSubagentTool(pi);
   registerAliases(pi);
   registerSlashAutocomplete(pi);
   registerFooter(pi, goalRuntime);

package/README.md

@@ -1,6 +1,6 @@
 # KillerOS
 
-A production-hardened Pi extension that combines a custom TUI, repository initialization, long-running goals, reasoning controls, interactive questions, command aliases, and concise-response guidance.
+A production-hardened Pi extension that combines a custom TUI, isolated subagents, repository initialization, long-running goals, reasoning controls, interactive questions, command aliases, and concise-response guidance.
 
 ## Requirements
 
@@ -29,7 +29,7 @@ pi install git:github.com/KyrosHendrix/pi-KillerOS
 Pin an install to a release:
 
 ```bash
-pi install git:github.com/KyrosHendrix/pi-KillerOS@v1.3.0
+pi install git:github.com/KyrosHendrix/pi-KillerOS@v1.4.0
 ```
 
 Add `-l` to either command for a project-only install. Restart Pi after installing.
@@ -43,6 +43,7 @@ Add `-l` to either command for a project-only install. Restart Pi after installi
 - Responsive footer with polished model/provider identity, plain-language context, and active goal state remaining; reasoning, Git branch, elapsed time, cost, and path cut down by available width
 - `/variants` selector and direct reasoning-level arguments
 - Codex-style `/goal` for durable long-running objectives with pause, resume, edit, clear, automatic continuation, and explicit completion
+- Pi-native `subagent` tool with isolated child processes, Markdown roles, explicit read/write boundaries, parallel readers, one serialized writer, bounded output, and cancellation propagation
 - Claude Code-style `/init` that scans the repository and generates a concise root `AGENTS.md` without setup questions
 - `question` tool with filtering, proposal previews, keyboard selection, custom answers, history, cancellation, and resize-safe rendering
 - Mid-prompt slash completion with current Pi `0.82.1` commands, extensions, prompts, and skills
@@ -71,6 +72,18 @@ Add `-l` to either command for a project-only install. Restart Pi after installi
 
 Supported reasoning levels are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. KillerOS limits choices to levels supported by the current model.
 
+## Subagents
+
+KillerOS ships `scout`, `planner`, and `reviewer` as read-only roles and `worker` as the only write-capable default. Each invocation rediscovers Markdown roles with this precedence:
+
+1. Bundled: `<killeros>/agents/*.md`
+2. Personal: `~/.pi/agent/agents/*.md`
+3. Trusted project: `<repo>/.pi/agents/*.md`
+
+The default `agentScope: "user"` uses bundled and personal roles. Use `"project"` or `"both"` to opt into trusted project roles; a selected project override requires interactive confirmation. Role frontmatter requires `name`, `description`, `access`, and an explicit `tools` list. Optional fields are `model`, `maxTurns`, and `timeoutMs`.
+
+The tool supports a single `agent` + `task`, parallel `tasks`, or a sequential `chain` whose task text may include `{previous}`. Children run as ephemeral `pi --mode json -p --no-session` processes with extension, skill, and prompt-template discovery disabled. KillerOS allows at most eight tasks, four parallel readers, one serialized writer, 12 turns, ten minutes, 2 MiB retained trace, 64 KiB stderr, and 50 KiB returned output per task. Esc cancellation terminates active children and escalates after five seconds.
+
 ## Configuration
 
 KillerOS activates its packaged `killeros` theme when a TUI session starts. Tool-call backgrounds stay neutral across pending, successful, and failed states; restrained text and icons preserve status visibility.
@@ -85,9 +98,9 @@ Lifecycle hooks are loaded from `.pi/killeros-hooks.json` at session start. Supp
 
 | Mode | Behavior |
 |---|---|
-| TUI | All features are available |
-| RPC | Goal set/view/pause/resume/clear and concise prompt guidance work; TUI components, `/goal edit`, and `/init` are disabled |
-| Print/JSON | Concise prompt guidance works; interactive questions, `/goal`, and `/init` fail explicitly |
+| TUI | All features are available, including confirmation for trusted project subagents |
+| RPC | Goal set/view/pause/resume/clear, subagents, and concise prompt guidance work; TUI components, `/goal edit`, and `/init` are disabled |
+| Print/JSON | Concise prompt guidance works; interactive questions, `/goal`, `/init`, and project-role confirmation fail explicitly |
 
 ## Validation
 
@@ -118,7 +131,7 @@ git push origin main --follow-tags
 
 ## Security
 
-Pi extensions run with your user permissions. Review the source before installing it globally. KillerOS executes lifecycle hook commands only for projects Pi marks as trusted; review `.pi/killeros-hooks.json` before enabling project trust.
+Pi extensions and write-capable subagents run with your user permissions. Review the source before installing it globally. KillerOS executes lifecycle hook commands and reads project agent roles only for projects Pi marks as trusted; review `.pi/killeros-hooks.json` and `.pi/agents/*.md` before enabling project trust.
 
 ## License
 

package/agents/planner.md

@@ -0,0 +1,10 @@
+---
+name: planner
+description: Produce a bounded implementation plan from verified repository evidence
+access: read
+tools: read, grep, find, ls
+maxTurns: 8
+timeoutMs: 300000
+---
+
+Analyze the requested change and produce the smallest implementation plan that satisfies it. Verify relevant architecture, contracts, and tests in the repository. Name files and ordered validation steps. Surface unresolved decisions instead of silently assuming them. Do not modify files.

package/agents/reviewer.md

@@ -0,0 +1,10 @@
+---
+name: reviewer
+description: Review code for proven correctness, security, and regression risks without modifying files
+access: read
+tools: read, grep, find, ls
+maxTurns: 8
+timeoutMs: 300000
+---
+
+Review the requested scope using repository evidence. Report only issues with a concrete trigger, resulting harm, and smallest safe correction. Check existing protections and tests before making a claim. Include exact paths and locations. Do not edit files and do not report stylistic preferences as defects.

package/agents/scout.md

@@ -0,0 +1,10 @@
+---
+name: scout
+description: Map a codebase, locate relevant files, and return evidence without modifying the checkout
+access: read
+tools: read, grep, find, ls
+maxTurns: 8
+timeoutMs: 300000
+---
+
+Explore the requested area efficiently. Identify the smallest relevant set of files, trace important control and data flow, and return concise findings with exact paths and symbols. Do not edit files or propose speculative changes unsupported by repository evidence.

package/agents/worker.md

@@ -0,0 +1,10 @@
+---
+name: worker
+description: Implement one bounded repository change after requirements and evidence are clear
+access: write
+tools: read, grep, find, ls, edit, write, bash
+maxTurns: 8
+timeoutMs: 300000
+---
+
+Implement only the requested bounded change. Re-check relevant files before editing, preserve unrelated work, and match existing conventions. Use the smallest safe edits and run focused verification required by the change. Report modified paths, checks, and any failures with their recovery action.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "killeros",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "A production-hardened TUI and workflow extension for the Pi coding agent.",
   "type": "module",
   "keywords": [
@@ -21,6 +21,8 @@
   },
   "files": [
     "Killeros.ts",
+    "subagents.ts",
+    "agents/*.md",
     "themes/killeros.json",
     "README.md",
     "CHANGELOG.md"
@@ -41,6 +43,7 @@
     ]
   },
   "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"

package/subagents.ts

@@ -0,0 +1,1027 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { closeSync, openSync, readSync, readdirSync, statSync } from "node:fs";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { StringDecoder } from "node:string_decoder";
+import { StringEnum } from "@earendil-works/pi-ai";
+import {
+  CONFIG_DIR_NAME,
+  getAgentDir,
+  getMarkdownTheme,
+  parseFrontmatter,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+export const SUBAGENT_LIMITS = {
+  maxTasks: 8,
+  maxReadConcurrency: 4,
+  defaultTurns: 8,
+  maxTurns: 12,
+  defaultTimeoutMs: 300_000,
+  maxTimeoutMs: 600_000,
+  traceBytes: 2 * 1024 * 1024,
+  stderrBytes: 64 * 1024,
+  taskOutputBytes: 50 * 1024,
+  toolOutputBytes: 50 * 1024,
+  roleFileBytes: 64 * 1024,
+  taskCharacters: 20_000,
+  killGraceMs: 5_000,
+} as const;
+
+const READ_TOOLS = new Set(["read", "grep", "find", "ls"]);
+const WRITE_TOOLS = new Set(["bash", "edit", "write"]);
+const KNOWN_TOOLS = new Set([...READ_TOOLS, ...WRITE_TOOLS]);
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+const ROLE_FIELDS = new Set(["name", "description", "access", "tools", "model", "maxTurns", "timeoutMs"]);
+
+type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+export type AgentAccess = "read" | "write";
+export type AgentSource = "bundled" | "personal" | "project";
+export type AgentScope = "user" | "project" | "both";
+export type SubagentStatus = "queued" | "running" | "complete" | "failed" | "cancelled" | "limited";
+
+export interface AgentRole {
+  name: string;
+  description: string;
+  access: AgentAccess;
+  tools: string[];
+  model?: string;
+  maxTurns: number;
+  timeoutMs: number;
+  prompt: string;
+  source: AgentSource;
+  filePath: string;
+}
+
+export interface AgentDiscoveryResult {
+  agents: AgentRole[];
+  projectAgentsDir: string | null;
+}
+
+export interface SubagentUsage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  totalTokens: number;
+  cost: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+  };
+  turns: number;
+}
+
+export interface SubagentTaskResult {
+  id: string;
+  agent: string;
+  agentSource: AgentSource | "unknown";
+  sourcePath?: string;
+  task: string;
+  access?: AgentAccess;
+  status: SubagentStatus;
+  model?: string;
+  thinking?: ThinkingLevel;
+  tools: string[];
+  trace: string[];
+  traceBytes: number;
+  traceTruncatedBytes: number;
+  stderr: string;
+  stderrTruncatedBytes: number;
+  output: string;
+  outputTruncatedBytes: number;
+  usage: SubagentUsage;
+  durationMs: number;
+  exitCode: number | null;
+  terminationReason?: string;
+  errorMessage?: string;
+  step?: number;
+}
+
+export interface SubagentDetails {
+  mode: "single" | "parallel" | "chain";
+  agentScope: AgentScope;
+  projectAgentsDir: string | null;
+  results: SubagentTaskResult[];
+  aggregateUsage: SubagentUsage;
+}
+
+interface ModelLike {
+  provider: string;
+  id: string;
+  reasoning?: boolean;
+  thinkingLevelMap?: Partial<Record<ThinkingLevel, unknown>>;
+}
+
+interface ModelContext {
+  model?: ModelLike;
+  thinkingLevel?: ThinkingLevel;
+  modelRegistry: {
+    getAvailable(): ModelLike[];
+  };
+}
+
+interface ResolvedModel {
+  model: string;
+  thinking: ThinkingLevel;
+  definition: ModelLike;
+}
+
+interface SpawnedProcess {
+  stdout: NodeJS.ReadableStream;
+  stderr: NodeJS.ReadableStream;
+  pid?: number;
+  kill(signal?: NodeJS.Signals | number): boolean;
+  on(event: "error", listener: (error: Error) => void): this;
+  once(event: "close", listener: (code: number | null) => void): this;
+}
+
+type SubagentLimits = { [Key in keyof typeof SUBAGENT_LIMITS]: number };
+
+export interface SubagentRuntimeOptions {
+  bundledAgentsDir?: string;
+  userAgentsDir?: string;
+  spawnProcess?: (args: string[], cwd: string) => SpawnedProcess;
+  createTaskId?: (index: number) => string;
+  limits?: Partial<SubagentLimits>;
+}
+
+class AgentConfigurationError extends Error {
+  constructor(filePath: string, field: string, message: string) {
+    super(`${filePath} [${field}]: ${message}`);
+    this.name = "AgentConfigurationError";
+  }
+}
+
+function emptyUsage(): SubagentUsage {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    turns: 0,
+  };
+}
+
+function addUsage(target: SubagentUsage, source: Partial<SubagentUsage> | undefined): void {
+  if (!source) return;
+  target.input += source.input ?? 0;
+  target.output += source.output ?? 0;
+  target.cacheRead += source.cacheRead ?? 0;
+  target.cacheWrite += source.cacheWrite ?? 0;
+  target.totalTokens += source.totalTokens ?? 0;
+  target.cost.input += source.cost?.input ?? 0;
+  target.cost.output += source.cost?.output ?? 0;
+  target.cost.cacheRead += source.cost?.cacheRead ?? 0;
+  target.cost.cacheWrite += source.cost?.cacheWrite ?? 0;
+  target.cost.total += source.cost?.total ?? 0;
+  target.turns += source.turns ?? 0;
+}
+
+function aggregateUsage(results: SubagentTaskResult[]): SubagentUsage {
+  const total = emptyUsage();
+  for (const result of results) addUsage(total, result.usage);
+  return total;
+}
+
+function readBoundedFile(filePath: string, maxBytes: number): string {
+  let descriptor: number | undefined;
+  try {
+    descriptor = openSync(filePath, "r");
+    const buffer = Buffer.alloc(maxBytes + 1);
+    const bytesRead = readSync(descriptor, buffer, 0, buffer.length, 0);
+    if (bytesRead > maxBytes) throw new AgentConfigurationError(filePath, "file", `exceeds ${maxBytes} bytes`);
+    return buffer.toString("utf8", 0, bytesRead);
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+  }
+}
+
+function requiredString(frontmatter: Record<string, unknown>, filePath: string, field: string): string {
+  const value = frontmatter[field];
+  if (typeof value !== "string" || !value.trim()) {
+    throw new AgentConfigurationError(filePath, field, "must be a non-empty string");
+  }
+  return value.trim();
+}
+
+function optionalPositiveInteger(
+  frontmatter: Record<string, unknown>,
+  filePath: string,
+  field: string,
+  fallback: number,
+  maximum: number,
+): number {
+  const value = frontmatter[field];
+  if (value === undefined || value === "") return fallback;
+  const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
+  if (!Number.isInteger(parsed) || parsed <= 0 || parsed > maximum) {
+    throw new AgentConfigurationError(filePath, field, `must be a positive integer no greater than ${maximum}`);
+  }
+  return parsed;
+}
+
+function parseAgentFile(filePath: string, source: AgentSource, limits: SubagentLimits): AgentRole {
+  const content = readBoundedFile(filePath, limits.roleFileBytes);
+  let parsed: { frontmatter: Record<string, unknown>; body: string };
+  try {
+    parsed = parseFrontmatter<Record<string, unknown>>(content);
+  } catch (error) {
+    throw new AgentConfigurationError(filePath, "frontmatter", error instanceof Error ? error.message : String(error));
+  }
+  const frontmatter = parsed.frontmatter;
+  for (const field of Object.keys(frontmatter)) {
+    if (!ROLE_FIELDS.has(field)) throw new AgentConfigurationError(filePath, field, "unknown role field");
+  }
+
+  const name = requiredString(frontmatter, filePath, "name");
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/u.test(name)) {
+    throw new AgentConfigurationError(filePath, "name", "must use 1-64 letters, numbers, dots, underscores, or hyphens");
+  }
+  const description = requiredString(frontmatter, filePath, "description");
+  if (description.length > 500) throw new AgentConfigurationError(filePath, "description", "must not exceed 500 characters");
+
+  const accessValue = requiredString(frontmatter, filePath, "access");
+  if (accessValue !== "read" && accessValue !== "write") {
+    throw new AgentConfigurationError(filePath, "access", 'must be "read" or "write"');
+  }
+  const toolsValue = requiredString(frontmatter, filePath, "tools");
+  const tools = [...new Set(toolsValue.split(",").map((tool) => tool.trim()).filter(Boolean))];
+  if (tools.length === 0) throw new AgentConfigurationError(filePath, "tools", "must contain at least one tool");
+  for (const tool of tools) {
+    if (!KNOWN_TOOLS.has(tool)) throw new AgentConfigurationError(filePath, "tools", `unknown child tool ${JSON.stringify(tool)}`);
+    if (accessValue === "read" && WRITE_TOOLS.has(tool)) {
+      throw new AgentConfigurationError(filePath, "tools", `read-only roles cannot use ${tool}`);
+    }
+  }
+
+  const prompt = parsed.body.trim();
+  if (!prompt) throw new AgentConfigurationError(filePath, "prompt", "Markdown body must be non-empty");
+  const modelValue = frontmatter.model;
+  if (modelValue !== undefined && (typeof modelValue !== "string" || !modelValue.trim())) {
+    throw new AgentConfigurationError(filePath, "model", "must be a non-empty string when provided");
+  }
+
+  return {
+    name,
+    description,
+    access: accessValue,
+    tools,
+    model: typeof modelValue === "string" ? modelValue.trim() : undefined,
+    maxTurns: optionalPositiveInteger(frontmatter, filePath, "maxTurns", limits.defaultTurns, limits.maxTurns),
+    timeoutMs: optionalPositiveInteger(frontmatter, filePath, "timeoutMs", limits.defaultTimeoutMs, limits.maxTimeoutMs),
+    prompt,
+    source,
+    filePath,
+  };
+}
+
+function loadAgentDirectory(dir: string, source: AgentSource, limits: SubagentLimits): AgentRole[] {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw new Error(`Could not read ${source} agent directory ${dir}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const agents: AgentRole[] = [];
+  const names = new Set<string>();
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+    const agent = parseAgentFile(path.join(dir, entry.name), source, limits);
+    if (names.has(agent.name)) throw new AgentConfigurationError(agent.filePath, "name", `duplicate ${source} role ${JSON.stringify(agent.name)}`);
+    names.add(agent.name);
+    agents.push(agent);
+  }
+  return agents;
+}
+
+function isDirectory(candidate: string): boolean {
+  try {
+    return statSync(candidate).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function findProjectAgentsDir(cwd: string): string | null {
+  let current = path.resolve(cwd);
+  while (true) {
+    const candidate = path.join(current, CONFIG_DIR_NAME, "agents");
+    if (isDirectory(candidate)) return candidate;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+export function discoverAgentRoles(
+  cwd: string,
+  scope: AgentScope,
+  projectTrusted: boolean,
+  options: Pick<SubagentRuntimeOptions, "bundledAgentsDir" | "userAgentsDir" | "limits"> = {},
+): AgentDiscoveryResult {
+  const limits = { ...SUBAGENT_LIMITS, ...options.limits };
+  const bundledDir = options.bundledAgentsDir ?? fileURLToPath(new URL("./agents/", import.meta.url));
+  const userDir = options.userAgentsDir ?? path.join(getAgentDir(), "agents");
+  const wantsProject = scope === "project" || scope === "both";
+  if (wantsProject && !projectTrusted) throw new Error("Project agents require a trusted project");
+  const projectAgentsDir = wantsProject ? findProjectAgentsDir(cwd) : null;
+
+  const layers: Array<{ dir: string; source: AgentSource }> = [{ dir: bundledDir, source: "bundled" }];
+  if (scope === "user" || scope === "both") layers.push({ dir: userDir, source: "personal" });
+  if (wantsProject && projectAgentsDir) layers.push({ dir: projectAgentsDir, source: "project" });
+
+  const byName = new Map<string, AgentRole>();
+  for (const layer of layers) {
+    for (const agent of loadAgentDirectory(layer.dir, layer.source, limits)) byName.set(agent.name, agent);
+  }
+  return {
+    agents: [...byName.values()].sort((left, right) => left.name.localeCompare(right.name)),
+    projectAgentsDir,
+  };
+}
+
+function splitModelAndThinking(value: string, filePath: string): { model: string; thinking?: ThinkingLevel } {
+  const colon = value.lastIndexOf(":");
+  if (colon < 0) return { model: value };
+  const suffix = value.slice(colon + 1);
+  if (!(THINKING_LEVELS as readonly string[]).includes(suffix)) {
+    throw new AgentConfigurationError(filePath, "model", `unknown thinking level ${JSON.stringify(suffix)}`);
+  }
+  const model = value.slice(0, colon);
+  if (!model) throw new AgentConfigurationError(filePath, "model", "model identifier is missing");
+  return { model, thinking: suffix as ThinkingLevel };
+}
+
+function modelSupportsThinking(model: ModelLike, thinking: ThinkingLevel): boolean {
+  if (thinking === "off") return true;
+  if (model.reasoning === false) return false;
+  if (model.thinkingLevelMap?.[thinking] === null) return false;
+  if ((thinking === "xhigh" || thinking === "max") && model.thinkingLevelMap?.[thinking] === undefined) return false;
+  return true;
+}
+
+export function resolveAgentModel(agent: AgentRole, ctx: ModelContext): ResolvedModel {
+  const inheritedThinking = ctx.thinkingLevel ?? "off";
+  let definition: ModelLike | undefined;
+  let thinking = inheritedThinking;
+
+  if (agent.model) {
+    const requested = splitModelAndThinking(agent.model, agent.filePath);
+    thinking = requested.thinking ?? inheritedThinking;
+    const available = ctx.modelRegistry.getAvailable();
+    const slash = requested.model.indexOf("/");
+    if (slash >= 1 && slash < requested.model.length - 1) {
+      definition = available.find((model) => model.provider === requested.model.slice(0, slash) && model.id === requested.model.slice(slash + 1));
+      if (!definition) throw new AgentConfigurationError(agent.filePath, "model", `unavailable model ${JSON.stringify(requested.model)}`);
+    } else {
+      const matches = available.filter((model) => model.id === requested.model);
+      if (matches.length === 0) throw new AgentConfigurationError(agent.filePath, "model", `unavailable model ${JSON.stringify(requested.model)}`);
+      if (matches.length > 1) throw new AgentConfigurationError(agent.filePath, "model", `ambiguous model ${JSON.stringify(requested.model)}; use provider/model`);
+      definition = matches[0];
+    }
+  } else {
+    definition = ctx.model;
+    if (!definition) throw new AgentConfigurationError(agent.filePath, "model", "no active parent model is available to inherit");
+  }
+
+  if (!modelSupportsThinking(definition, thinking)) {
+    throw new AgentConfigurationError(agent.filePath, "model", `${definition.provider}/${definition.id} does not support thinking level ${thinking}`);
+  }
+  return { model: `${definition.provider}/${definition.id}`, thinking, definition };
+}
+
+function getPiInvocation(args: string[]): { command: string; args: string[] } {
+  const currentScript = process.argv[1];
+  const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
+  if (currentScript && !isBunVirtualScript) {
+    try {
+      if (statSync(currentScript).isFile()) return { command: process.execPath, args: [currentScript, ...args] };
+    } catch {
+      // Fall through to the installed pi command.
+    }
+  }
+  const executable = path.basename(process.execPath).toLocaleLowerCase();
+  return /^(node|bun)(\.exe)?$/u.test(executable)
+    ? { command: "pi", args }
+    : { command: process.execPath, args };
+}
+
+export function childProcessEnvironment(environment: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  const childEnvironment = { ...environment };
+  delete childEnvironment.PI_SESSION_FILE;
+  delete childEnvironment.PI_SESSION_ID;
+  return childEnvironment;
+}
+
+function defaultSpawnProcess(args: string[], cwd: string): SpawnedProcess {
+  const invocation = getPiInvocation(args);
+  return spawn(invocation.command, invocation.args, {
+    cwd,
+    detached: process.platform !== "win32",
+    env: childProcessEnvironment(),
+    shell: false,
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+  }) as unknown as SpawnedProcess;
+}
+
+function terminateProcess(child: SpawnedProcess, force: boolean): void {
+  if (process.platform === "win32" && force && child.pid) {
+    const killer = spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
+      shell: false,
+      stdio: "ignore",
+      windowsHide: true,
+    });
+    killer.unref();
+    return;
+  }
+  if (process.platform !== "win32" && child.pid) {
+    try {
+      process.kill(-child.pid, force ? "SIGKILL" : "SIGTERM");
+      return;
+    } catch {
+      // Fall back to the direct child when process-group signaling is unavailable.
+    }
+  }
+  try {
+    child.kill(force ? "SIGKILL" : "SIGTERM");
+  } catch {
+    // The process may already have exited.
+  }
+}
+
+function truncateUtf8(text: string, maxBytes: number): { text: string; omittedBytes: number } {
+  const bytes = Buffer.from(text, "utf8");
+  if (bytes.length <= maxBytes) return { text, omittedBytes: 0 };
+  let truncated = bytes.subarray(0, maxBytes).toString("utf8");
+  if (truncated.endsWith("�")) truncated = truncated.slice(0, -1);
+  return { text: truncated, omittedBytes: bytes.length - Buffer.byteLength(truncated, "utf8") };
+}
+
+function textContent(message: any): string {
+  if (!Array.isArray(message?.content)) return "";
+  return message.content.filter((part: any) => part?.type === "text" && typeof part.text === "string").map((part: any) => part.text).join("\n");
+}
+
+function traceMessage(message: any): string[] {
+  if (!Array.isArray(message?.content)) return [];
+  const entries: string[] = [];
+  for (const part of message.content) {
+    if (part?.type !== "toolCall" || typeof part.name !== "string") continue;
+    const args = truncateUtf8(JSON.stringify(part.arguments ?? {}), 2_000).text;
+    entries.push(`${part.name} ${args}`);
+  }
+  return entries;
+}
+
+function makeQueuedResult(id: string, agent: string, task: string, step?: number): SubagentTaskResult {
+  return {
+    id,
+    agent,
+    agentSource: "unknown",
+    task,
+    status: "queued",
+    tools: [],
+    trace: [],
+    traceBytes: 0,
+    traceTruncatedBytes: 0,
+    stderr: "",
+    stderrTruncatedBytes: 0,
+    output: "",
+    outputTruncatedBytes: 0,
+    usage: emptyUsage(),
+    durationMs: 0,
+    exitCode: null,
+    step,
+  };
+}
+
+function cloneResult(result: SubagentTaskResult): SubagentTaskResult {
+  return {
+    ...result,
+    tools: [...result.tools],
+    trace: [...result.trace],
+    usage: { ...result.usage, cost: { ...result.usage.cost } },
+  };
+}
+
+function cloneDetails(mode: SubagentDetails["mode"], scope: AgentScope, projectAgentsDir: string | null, results: SubagentTaskResult[]): SubagentDetails {
+  const cloned = results.map(cloneResult);
+  return { mode, agentScope: scope, projectAgentsDir, results: cloned, aggregateUsage: aggregateUsage(cloned) };
+}
+
+async function writeRolePrompt(agent: AgentRole): Promise<{ directory: string; filePath: string }> {
+  const directory = await mkdtemp(path.join(os.tmpdir(), "killeros-subagent-"));
+  const filePath = path.join(directory, `${agent.name.replace(/[^A-Za-z0-9_.-]/gu, "_")}.md`);
+  await writeFile(filePath, agent.prompt, { encoding: "utf8", mode: 0o600 });
+  return { directory, filePath };
+}
+
+interface RunTaskOptions {
+  cwd: string;
+  agent: AgentRole;
+  task: string;
+  id: string;
+  step?: number;
+  model: ResolvedModel;
+  signal?: AbortSignal;
+  spawnProcess: (args: string[], cwd: string) => SpawnedProcess;
+  limits: SubagentLimits;
+  onChange: (result: SubagentTaskResult) => void;
+}
+
+async function runTask(options: RunTaskOptions): Promise<SubagentTaskResult> {
+  const { agent, limits } = options;
+  const result = makeQueuedResult(options.id, agent.name, options.task, options.step);
+  result.agentSource = agent.source;
+  result.sourcePath = agent.filePath;
+  result.access = agent.access;
+  result.tools = [...agent.tools];
+  result.model = options.model.model;
+  result.thinking = options.model.thinking;
+  result.status = "running";
+  const startedAt = Date.now();
+  options.onChange(result);
+
+  if (options.signal?.aborted) {
+    result.status = "cancelled";
+    result.terminationReason = "abort";
+    result.durationMs = Date.now() - startedAt;
+    options.onChange(result);
+    return result;
+  }
+
+  let promptDirectory: string | undefined;
+  let child: SpawnedProcess | undefined;
+  try {
+    const prompt = await writeRolePrompt(agent);
+    promptDirectory = prompt.directory;
+    if (options.signal?.aborted) {
+      result.status = "cancelled";
+      result.terminationReason = "abort";
+      result.durationMs = Date.now() - startedAt;
+      options.onChange(result);
+      return result;
+    }
+    const args = [
+      "--mode", "json",
+      "-p",
+      "--no-session",
+      "--no-extensions",
+      "--no-skills",
+      "--no-prompt-templates",
+      "--model", options.model.model,
+      "--thinking", options.model.thinking,
+      "--tools", agent.tools.join(","),
+      "--append-system-prompt", prompt.filePath,
+      `Task: ${options.task}`,
+    ];
+    child = options.spawnProcess(args, options.cwd);
+
+    const decoder = new StringDecoder("utf8");
+    let lineBuffer = "";
+    let rawTraceBytes = 0;
+    let rawStderrBytes = 0;
+    let requestedStatus: SubagentStatus | undefined;
+    let requestedReason: string | undefined;
+    let closed = false;
+    let malformedError: string | undefined;
+    let forceTimer: NodeJS.Timeout | undefined;
+    let settleTimer: NodeJS.Timeout | undefined;
+
+    const requestTermination = (status: "failed" | "cancelled" | "limited", reason: string, errorMessage?: string): void => {
+      if (requestedStatus) return;
+      requestedStatus = status;
+      requestedReason = reason;
+      if (errorMessage) result.errorMessage = errorMessage;
+      terminateProcess(child!, false);
+      forceTimer = setTimeout(() => {
+        if (closed) return;
+        terminateProcess(child!, true);
+        settleTimer = setTimeout(() => {
+          if (!closed) finish(null);
+        }, 1_000);
+        settleTimer.unref?.();
+      }, limits.killGraceMs);
+      forceTimer.unref?.();
+    };
+
+    const processLine = (line: string): void => {
+      if (!line.trim() || requestedStatus) return;
+      let event: any;
+      try {
+        event = JSON.parse(line);
+      } catch (error) {
+        malformedError = error instanceof Error ? error.message : String(error);
+        requestTermination("failed", "malformed_jsonl", `Malformed child JSONL: ${malformedError}`);
+        return;
+      }
+      if (event?.type === "message_end" && event.message?.role === "assistant") {
+        const message = event.message;
+        result.usage.turns += 1;
+        addUsage(result.usage, { ...message.usage, turns: 0 });
+        result.trace.push(...traceMessage(message));
+        const output = textContent(message);
+        if (output) {
+          const capped = truncateUtf8(output, limits.taskOutputBytes);
+          result.output = capped.text;
+          result.outputTruncatedBytes = capped.omittedBytes;
+        }
+        if (typeof message.model === "string") result.model = message.provider ? `${message.provider}/${message.model}` : message.model;
+        const stopReason = typeof message.stopReason === "string" ? message.stopReason : undefined;
+        if (stopReason === "stop" || stopReason === "toolUse") {
+          result.terminationReason = undefined;
+          result.errorMessage = undefined;
+        } else if (stopReason) {
+          result.terminationReason = stopReason;
+        }
+        if (typeof message.errorMessage === "string") result.errorMessage = message.errorMessage;
+        if (stopReason === "length") requestTermination("limited", "model_output_limit");
+        if (result.usage.turns > agent.maxTurns || result.usage.turns >= agent.maxTurns && stopReason === "toolUse") {
+          requestTermination("limited", "turn_limit");
+        }
+        options.onChange(result);
+      } else if (event?.type === "agent_end" && event.willRetry === true) {
+        if (result.usage.turns >= agent.maxTurns) {
+          requestTermination("limited", "turn_limit");
+          options.onChange(result);
+        }
+      } else if (event?.type === "tool_result_end" && event.message) {
+        const toolName = typeof event.message.toolName === "string" ? event.message.toolName : "tool";
+        result.trace.push(`${toolName} result${event.message.isError ? " (error)" : ""}`);
+        options.onChange(result);
+      }
+    };
+
+    let finish!: (code: number | null) => void;
+    const closedPromise = new Promise<void>((resolve) => {
+      finish = (code: number | null): void => {
+        if (closed) return;
+        closed = true;
+        if (forceTimer) clearTimeout(forceTimer);
+        if (settleTimer) clearTimeout(settleTimer);
+        const tail = decoder.end();
+        if (tail) lineBuffer += tail;
+        if (lineBuffer.trim() && !requestedStatus) processLine(lineBuffer);
+        result.exitCode = code;
+        if (requestedStatus) {
+          result.status = requestedStatus;
+          result.terminationReason = requestedReason;
+        } else if (result.terminationReason === "length") {
+          result.status = "limited";
+          result.terminationReason = "model_output_limit";
+        } else if (code !== 0 || result.errorMessage || result.terminationReason) {
+          result.status = "failed";
+          result.terminationReason ??= code === null ? "process_closed" : `exit_${code}`;
+        } else if (result.usage.turns === 0) {
+          result.status = "failed";
+          result.terminationReason = "missing_assistant_message";
+          result.errorMessage = "Child exited without an assistant response";
+        } else {
+          result.status = "complete";
+          result.terminationReason = "completed";
+        }
+        result.durationMs = Date.now() - startedAt;
+        options.onChange(result);
+        resolve();
+      };
+    });
+
+    child.stdout.on("data", (chunk: Buffer | string) => {
+      if (requestedStatus) return;
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      const remaining = Math.max(0, limits.traceBytes - rawTraceBytes);
+      rawTraceBytes += buffer.length;
+      const accepted = buffer.subarray(0, remaining);
+      if (accepted.length) {
+        lineBuffer += decoder.write(accepted);
+        const lines = lineBuffer.split(/\r?\n/u);
+        lineBuffer = lines.pop() ?? "";
+        for (const line of lines) processLine(line);
+      }
+      result.traceBytes = Math.min(rawTraceBytes, limits.traceBytes);
+      result.traceTruncatedBytes = Math.max(0, rawTraceBytes - limits.traceBytes);
+      if (rawTraceBytes > limits.traceBytes) requestTermination("limited", "trace_limit");
+    });
+    child.stderr.on("data", (chunk: Buffer | string) => {
+      if (requestedStatus) return;
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      const remaining = Math.max(0, limits.stderrBytes - rawStderrBytes);
+      rawStderrBytes += buffer.length;
+      if (remaining > 0) result.stderr += buffer.subarray(0, remaining).toString("utf8");
+      result.stderrTruncatedBytes = Math.max(0, rawStderrBytes - limits.stderrBytes);
+      if (rawStderrBytes > limits.stderrBytes) requestTermination("limited", "stderr_limit");
+    });
+    child.on("error", (error) => requestTermination("failed", "spawn_error", error.message));
+    child.once("close", finish);
+
+    const timeoutTimer = setTimeout(() => requestTermination("limited", "timeout"), agent.timeoutMs);
+    timeoutTimer.unref?.();
+    const abortHandler = (): void => requestTermination("cancelled", "abort");
+    if (options.signal?.aborted) abortHandler();
+    else options.signal?.addEventListener("abort", abortHandler, { once: true });
+
+    try {
+      await closedPromise;
+    } finally {
+      clearTimeout(timeoutTimer);
+      options.signal?.removeEventListener("abort", abortHandler);
+    }
+    if (!result.output && result.stderr && (result.status as SubagentStatus) !== "complete") {
+      result.errorMessage ??= result.stderr.trim();
+    }
+    return result;
+  } catch (error) {
+    result.status = options.signal?.aborted ? "cancelled" : "failed";
+    result.terminationReason = options.signal?.aborted ? "abort" : "spawn_error";
+    result.errorMessage = error instanceof Error ? error.message : String(error);
+    result.durationMs = Date.now() - startedAt;
+    options.onChange(result);
+    return result;
+  } finally {
+    if (promptDirectory) {
+      try {
+        await rm(promptDirectory, { recursive: true, force: true });
+      } catch {
+        // Temporary prompt cleanup is best effort after child termination.
+      }
+    }
+  }
+}
+
+async function mapReadTasks<T>(items: T[], concurrency: number, run: (item: T, index: number) => Promise<void>): Promise<void> {
+  let next = 0;
+  const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+    while (true) {
+      const index = next;
+      next += 1;
+      if (index >= items.length) return;
+      await run(items[index]!, index);
+    }
+  });
+  await Promise.all(workers);
+}
+
+const TaskSchema = Type.Object({
+  agent: Type.String({ minLength: 1, maxLength: 64, description: "Agent role name" }),
+  task: Type.String({ minLength: 1, maxLength: SUBAGENT_LIMITS.taskCharacters, description: "Bounded task for the role" }),
+});
+
+const ChainTaskSchema = Type.Object({
+  agent: Type.String({ minLength: 1, maxLength: 64, description: "Agent role name" }),
+  task: Type.String({ minLength: 1, maxLength: SUBAGENT_LIMITS.taskCharacters, description: "Task with optional {previous} handoff placeholder" }),
+});
+
+const SubagentParams = Type.Object({
+  agent: Type.Optional(Type.String({ minLength: 1, maxLength: 64, description: "Agent role for single mode" })),
+  task: Type.Optional(Type.String({ minLength: 1, maxLength: SUBAGENT_LIMITS.taskCharacters, description: "Task for single mode" })),
+  tasks: Type.Optional(Type.Array(TaskSchema, { minItems: 1, maxItems: SUBAGENT_LIMITS.maxTasks, description: "Parallel role tasks" })),
+  chain: Type.Optional(Type.Array(ChainTaskSchema, { minItems: 1, maxItems: SUBAGENT_LIMITS.maxTasks, description: "Sequential role tasks; {previous} inserts the prior result" })),
+  agentScope: Type.Optional(StringEnum(["user", "project", "both"] as const, {
+    default: "user",
+    description: "Role sources: user includes bundled and personal; project includes bundled and trusted project; both includes all",
+  })),
+});
+
+type TaskInput = { agent: string; task: string };
+
+type ToolUpdate = (partial: { content: Array<{ type: "text"; text: string }>; details: SubagentDetails }) => void;
+
+function requestedAgents(params: { agent?: string; tasks?: TaskInput[]; chain?: TaskInput[] }): string[] {
+  if (params.agent) return [params.agent];
+  return (params.tasks ?? params.chain ?? []).map((task) => task.agent);
+}
+
+function formatUsage(usage: SubagentUsage): string {
+  const parts = [`${usage.turns} turn${usage.turns === 1 ? "" : "s"}`, `${usage.totalTokens} tokens`];
+  if (usage.cost.total) parts.push(`$${usage.cost.total.toFixed(4)}`);
+  return parts.join(" · ");
+}
+
+function taskSummary(result: SubagentTaskResult): string {
+  return `${result.id} · ${result.agent} · ${result.status} · ${formatUsage(result.usage)}`;
+}
+
+function buildToolContent(mode: SubagentDetails["mode"], results: SubagentTaskResult[], maxBytes: number): string {
+  const sections = results.map((result) => {
+    const heading = `### ${result.id} · ${result.agent} · ${result.status}`;
+    const reason = result.terminationReason && result.terminationReason !== "completed" ? `\nReason: ${result.terminationReason}` : "";
+    const body = result.output || result.errorMessage || result.stderr.trim() || "(no output)";
+    const truncation = result.outputTruncatedBytes ? `\n\n[Task output truncated: ${result.outputTruncatedBytes} bytes omitted; bounded detail is available when expanded.]` : "";
+    return `${heading}${reason}\n\n${body}${truncation}`;
+  });
+  const complete = results.filter((result) => result.status === "complete").length;
+  const text = `${mode}: ${complete}/${results.length} complete · ${formatUsage(aggregateUsage(results))}\n\n${sections.join("\n\n---\n\n")}`;
+  const marker = "\n\n[Combined subagent output truncated to 50 KiB; inspect the expanded tool result for bounded per-task details.]";
+  const capped = truncateUtf8(text, Math.max(0, maxBytes - Buffer.byteLength(marker)));
+  return capped.omittedBytes ? `${capped.text}${marker}` : text;
+}
+
+function statusColor(status: SubagentStatus): "accent" | "success" | "error" | "warning" | "muted" {
+  if (status === "running") return "accent";
+  if (status === "complete") return "success";
+  if (status === "failed") return "error";
+  if (status === "limited" || status === "cancelled") return "warning";
+  return "muted";
+}
+
+function statusIcon(status: SubagentStatus): string {
+  if (status === "running") return "✻";
+  if (status === "complete") return "✓";
+  if (status === "failed") return "✗";
+  if (status === "queued") return "○";
+  return "!";
+}
+
+export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeOptions = {}): void {
+  const limits = { ...SUBAGENT_LIMITS, ...options.limits };
+  const spawnProcess = options.spawnProcess ?? defaultSpawnProcess;
+
+  pi.registerTool({
+    name: "subagent",
+    label: "Subagents",
+    description: "Delegate one task, up to eight parallel tasks, or a sequential chain to isolated Pi child roles. Bundled and personal roles are available by default; trusted project roles require project/both scope and confirmation. Children have explicit tools, no extension/skill/template discovery, at most 12 turns, ten minutes, 2 MiB trace, 64 KiB stderr, and 50 KiB returned output per task.",
+    promptSnippet: "Delegate bounded specialist work to isolated KillerOS subagents",
+    promptGuidelines: [
+      "Use subagent for clearly separable specialist work; prefer read-only scout, planner, or reviewer roles before the sequential writer.",
+      "Do not request multiple write-capable subagents in one parallel batch.",
+    ],
+    parameters: SubagentParams,
+    executionMode: "sequential",
+
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      const scope: AgentScope = params.agentScope ?? "user";
+      const hasSingleFields = params.agent !== undefined || params.task !== undefined;
+      const hasParallel = params.tasks !== undefined;
+      const hasChain = params.chain !== undefined;
+      const hasSingle = hasSingleFields && Boolean(params.agent && params.task);
+      if (Number(hasSingleFields) + Number(hasParallel) + Number(hasChain) !== 1
+        || hasSingleFields && !hasSingle
+        || hasParallel && params.tasks!.length === 0
+        || hasChain && params.chain!.length === 0) {
+        throw new Error("Provide exactly one subagent mode: agent + task, tasks, or chain");
+      }
+
+      const discovery = discoverAgentRoles(ctx.cwd, scope, ctx.isProjectTrusted(), options);
+      const roles = new Map(discovery.agents.map((agent) => [agent.name, agent]));
+      const requested = requestedAgents(params);
+      for (const name of requested) {
+        if (!roles.has(name)) {
+          const available = discovery.agents.map((agent) => `${agent.name} (${agent.source})`).join(", ") || "none";
+          throw new Error(`Unknown subagent ${JSON.stringify(name)}. Available: ${available}`);
+        }
+      }
+
+      const projectRoles = [...new Set(requested.map((name) => roles.get(name)!).filter((role) => role.source === "project"))];
+      if (projectRoles.length) {
+        if (!ctx.hasUI) throw new Error("Project-local subagents require interactive confirmation");
+        const approved = await ctx.ui.confirm(
+          "Run project-local subagents?",
+          `Roles: ${projectRoles.map((role) => role.name).join(", ")}\nSources:\n${projectRoles.map((role) => role.filePath).join("\n")}\n\nThese trusted repository files control child prompts and tools.`,
+        );
+        if (!approved) throw new Error("Project-local subagents were not approved");
+      }
+
+      const resolvedModels = new Map<string, ResolvedModel>();
+      for (const name of new Set(requested)) resolvedModels.set(name, resolveAgentModel(roles.get(name)!, ctx));
+
+      const mode: SubagentDetails["mode"] = hasParallel ? "parallel" : hasChain ? "chain" : "single";
+      const inputs: TaskInput[] = hasSingle
+        ? [{ agent: params.agent!, task: params.task! }]
+        : hasParallel ? params.tasks! : params.chain!;
+      if (inputs.length > limits.maxTasks) throw new Error(`At most ${limits.maxTasks} subagent tasks are allowed`);
+      if (hasParallel) {
+        const writers = inputs.filter((input) => roles.get(input.agent)!.access === "write");
+        if (writers.length > 1) throw new Error("Parallel batches may contain at most one write-capable subagent; writers are serialized");
+      }
+
+      const invocationPrefix = randomUUID().slice(0, 8);
+      const createTaskId = options.createTaskId ?? ((index: number) => `${invocationPrefix}-${index + 1}`);
+      const results = inputs.map((input, index) => makeQueuedResult(createTaskId(index), input.agent, input.task, hasChain ? index + 1 : undefined));
+      const emit = (message = `${mode}: ${results.filter((result) => !["queued", "running"].includes(result.status)).length}/${results.length} settled`): void => {
+        (onUpdate as ToolUpdate | undefined)?.({
+          content: [{ type: "text", text: message }],
+          details: cloneDetails(mode, scope, discovery.projectAgentsDir, results),
+        });
+      };
+      const runAt = async (index: number, task: string): Promise<void> => {
+        if (signal?.aborted) {
+          results[index] = { ...results[index]!, status: "cancelled", terminationReason: "abort" };
+          emit();
+          return;
+        }
+        const input = inputs[index]!;
+        if ([...task].length > limits.taskCharacters) {
+          results[index] = {
+            ...results[index]!,
+            status: "failed",
+            terminationReason: "task_limit",
+            errorMessage: `Expanded task exceeds ${limits.taskCharacters} characters`,
+          };
+          emit();
+          return;
+        }
+        results[index] = await runTask({
+          cwd: ctx.cwd,
+          agent: roles.get(input.agent)!,
+          task,
+          id: results[index]!.id,
+          step: results[index]!.step,
+          model: resolvedModels.get(input.agent)!,
+          signal,
+          spawnProcess,
+          limits,
+          onChange: (next) => {
+            results[index] = cloneResult(next);
+            emit();
+          },
+        });
+      };
+
+      emit(`${mode}: ${results.length} queued`);
+      if (hasChain) {
+        let previous = "";
+        for (let index = 0; index < inputs.length; index += 1) {
+          const task = inputs[index]!.task.replaceAll("{previous}", previous);
+          await runAt(index, task);
+          if (results[index]!.status !== "complete") break;
+          previous = results[index]!.output;
+        }
+        for (const result of results) {
+          if (result.status === "queued") {
+            result.status = signal?.aborted ? "cancelled" : "failed";
+            result.terminationReason = signal?.aborted ? "abort" : "chain_stopped";
+          }
+        }
+      } else if (hasParallel) {
+        const readIndexes = inputs.map((input, index) => ({ input, index })).filter(({ input }) => roles.get(input.agent)!.access === "read");
+        const writerIndex = inputs.findIndex((input) => roles.get(input.agent)!.access === "write");
+        await mapReadTasks(readIndexes, limits.maxReadConcurrency, async ({ index }) => runAt(index, inputs[index]!.task));
+        if (writerIndex >= 0) await runAt(writerIndex, inputs[writerIndex]!.task);
+      } else {
+        await runAt(0, inputs[0]!.task);
+      }
+
+      const details = cloneDetails(mode, scope, discovery.projectAgentsDir, results);
+      return {
+        content: [{ type: "text", text: buildToolContent(mode, details.results, limits.toolOutputBytes) }],
+        details,
+        usage: details.aggregateUsage,
+      };
+    },
+
+    renderCall(args, theme) {
+      const scope = args.agentScope ?? "user";
+      if (args.tasks?.length) return new Text(`${theme.fg("toolTitle", theme.bold("subagents "))}${theme.fg("accent", `parallel ${args.tasks.length}`)}${theme.fg("dim", ` · ${scope}`)}`, 0, 0);
+      if (args.chain?.length) return new Text(`${theme.fg("toolTitle", theme.bold("subagents "))}${theme.fg("accent", `chain ${args.chain.length}`)}${theme.fg("dim", ` · ${scope}`)}`, 0, 0);
+      return new Text(`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", args.agent ?? "…")}${theme.fg("dim", ` · ${scope}`)}`, 0, 0);
+    },
+
+    renderResult(result, { expanded }, theme) {
+      const details = result.details as SubagentDetails | undefined;
+      if (!details?.results.length) {
+        const first = result.content[0];
+        return new Text(first?.type === "text" ? first.text : "(no output)", 0, 0);
+      }
+      if (!expanded) {
+        const lines = details.results.map((task) => {
+          const status = theme.fg(statusColor(task.status), `${statusIcon(task.status)} ${task.status}`);
+          return `${status} ${theme.fg("toolTitle", theme.bold(task.agent))}${theme.fg("dim", ` · ${task.id} · ${formatUsage(task.usage)}`)}`;
+        });
+        lines.push(theme.fg("dim", `Total · ${formatUsage(details.aggregateUsage)} · Ctrl+O to expand`));
+        return new Text(lines.join("\n"), 0, 0);
+      }
+
+      const container = new Container();
+      container.addChild(new Text(theme.fg("toolTitle", theme.bold(`Subagents · ${details.mode}`)), 0, 0));
+      for (const task of details.results) {
+        container.addChild(new Spacer(1));
+        const status = theme.fg(statusColor(task.status), `${statusIcon(task.status)} ${task.status}`);
+        container.addChild(new Text(`${status} ${theme.fg("accent", task.agent)}${theme.fg("dim", ` · ${task.id} · ${task.agentSource}`)}`, 0, 0));
+        container.addChild(new Text(theme.fg("dim", `${task.model ?? "no model"} · ${task.thinking ?? "off"} · ${task.tools.join(", ")} · ${formatUsage(task.usage)} · ${task.durationMs}ms`), 0, 0));
+        container.addChild(new Text(theme.fg("muted", `Task: ${task.task}`), 0, 0));
+        for (const entry of task.trace) container.addChild(new Text(`${theme.fg("muted", "→ ")}${theme.fg("toolOutput", entry)}`, 0, 0));
+        if (task.traceTruncatedBytes || task.stderrTruncatedBytes || task.outputTruncatedBytes) {
+          container.addChild(new Text(theme.fg("warning", `Truncated · trace ${task.traceTruncatedBytes} B · stderr ${task.stderrTruncatedBytes} B · output ${task.outputTruncatedBytes} B`), 0, 0));
+        }
+        if (task.output) container.addChild(new Markdown(task.output, 0, 0, getMarkdownTheme()));
+        else if (task.errorMessage || task.stderr) container.addChild(new Text(theme.fg("error", task.errorMessage || task.stderr), 0, 0));
+      }
+      container.addChild(new Spacer(1));
+      container.addChild(new Text(theme.fg("dim", `Total · ${formatUsage(details.aggregateUsage)}`), 0, 0));
+      return container;
+    },
+  });
+}