@pi-archimedes/subagent 0.3.2 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/subagent",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -11,7 +11,7 @@
   ],
   "main": "./src/index.ts",
   "dependencies": {
-    "@pi-archimedes/core": "0.3.2"
+    "@pi-archimedes/core": "0.5.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.1.0",

package/src/agents.ts

@@ -0,0 +1,113 @@
+/**
+ * Agent discovery and configuration loading.
+ * Reads agent definitions from ~/.pi/agent/agents/*.md and .pi/agents/*.md
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+
+export interface AgentConfig {
+  name: string;
+  description: string;
+  model?: string;
+  thinking?: string;
+  tools?: string[];
+  systemPrompt: string;
+  source: "user" | "project";
+  filePath: string;
+}
+
+function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
+  const agents: AgentConfig[] = [];
+
+  if (!fs.existsSync(dir)) return agents;
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return agents;
+  }
+
+  for (const entry of entries) {
+    if (!entry.name.endsWith(".md")) continue;
+    if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+
+    const filePath = path.join(dir, entry.name);
+    let content: string;
+    try {
+      content = fs.readFileSync(filePath, "utf-8");
+    } catch {
+      continue;
+    }
+
+    const { frontmatter, body } = parseFrontmatter<Record<string, unknown>>(content);
+
+    if (!frontmatter.name || !frontmatter.description) continue;
+
+    const tools = typeof frontmatter.tools === "string"
+      ? frontmatter.tools.split(",").map((t: string) => t.trim()).filter(Boolean)
+      : undefined;
+
+    const config: AgentConfig = {
+      name: frontmatter.name as string,
+      description: frontmatter.description as string,
+      systemPrompt: body,
+      source,
+      filePath,
+    };
+    if (frontmatter.model) config.model = frontmatter.model as string;
+    if (frontmatter.thinking) config.thinking = frontmatter.thinking as string;
+    if (tools && tools.length > 0) config.tools = tools;
+
+    agents.push(config);
+  }
+
+  return agents;
+}
+
+function isDirectory(p: string): boolean {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function findNearestProjectAgentsDir(cwd: string): string | null {
+  let currentDir = cwd;
+  while (true) {
+    const candidate = path.join(currentDir, ".pi", "agents");
+    if (isDirectory(candidate)) return candidate;
+
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) return null;
+    currentDir = parentDir;
+  }
+}
+
+/**
+ * Discover all available agents from user and/or project directories.
+ */
+export function discoverAgents(cwd: string): AgentConfig[] {
+  const userDir = path.join(getAgentDir(), "agents");
+  const projectDir = findNearestProjectAgentsDir(cwd);
+
+  const userAgents = loadAgentsFromDir(userDir, "user");
+  const projectAgents = projectDir ? loadAgentsFromDir(projectDir, "project") : [];
+
+  // Project agents override user agents with the same name
+  const agentMap = new Map<string, AgentConfig>();
+  for (const agent of userAgents) agentMap.set(agent.name, agent);
+  for (const agent of projectAgents) agentMap.set(agent.name, agent);
+
+  return Array.from(agentMap.values());
+}
+
+/**
+ * Look up an agent config by name.
+ */
+export function findAgent(agents: AgentConfig[], name: string): AgentConfig | undefined {
+  return agents.find((a) => a.name === name);
+}

package/src/compact.ts

@@ -1,6 +1,6 @@
 import { Text } from "@earendil-works/pi-tui";
 import type { SubagentDetails, SubagentProgress, SubagentResult, SubagentToolResult } from "./types.js";
-import { SPINNER_FRAMES, formatTokens, formatDuration, formatCost, truncLine, buildStatsLine } from "./format.js";
+import { formatTokens, formatDuration, formatCost, truncLine, buildStatsLine } from "./format.js";
 
 type Theme = { fg: (token: string, text: string) => string; bold: (text: string) => string };
 type RenderContext = { state: Record<string, unknown>; invalidate: () => void };
@@ -9,12 +9,12 @@ type RenderContext = { state: Record<string, unknown>; invalidate: () => void };
 
 export function buildActivityLine(
   progress: {
-    currentTool?: string;
-    currentToolArgs?: string;
-    currentToolStartedAt?: number;
-    finalOutput?: string;
-    status?: "running" | "completed" | "failed";
-    error?: string;
+    currentTool: string | undefined;
+    currentToolArgs: string | undefined;
+    currentToolStartedAt: number | undefined;
+    finalOutput: string | undefined;
+    status: "running" | "completed" | "failed" | undefined;
+    error: string | undefined;
   },
   theme: Theme,
 ): string {
@@ -26,7 +26,7 @@ export function buildActivityLine(
 
   if (progress.currentTool) {
     const argsPreview = progress.currentToolArgs
-      ? truncLine(progress.currentToolArgs, 60)
+      ? truncLine(progress.currentToolArgs ?? "", 60)
       : "";
     const durationPart = progress.currentToolStartedAt
       ? " | " + formatDuration(Date.now() - progress.currentToolStartedAt)
@@ -49,35 +49,13 @@ export function buildActivityLine(
   return "";
 }
 
-// ── Spinner helper ──────────────────────────────────────────────────────────
+// ── Status glyph ────────────────────────────────────────────────────────────
 
-function getSpinnerGlyph(agentName: string, isRunning: boolean, status: string, context: RenderContext): string {
-  if (isRunning) {
-    const timerKey = "_subagentTimer_" + agentName;
-    const frameKey = "_subagentFrame_" + agentName;
-    if (!context.state[timerKey]) {
-      context.state[frameKey] = 0;
-      const timer = setInterval(() => {
-        context.state[frameKey] = ((context.state[frameKey] as number) + 1) % SPINNER_FRAMES.length;
-        context.invalidate();
-      }, 80);
-      context.state[timerKey] = timer;
-    }
-    return SPINNER_FRAMES[context.state[frameKey] as number];
-  }
+function statusGlyph(isRunning: boolean, status: string): string {
+  if (isRunning) return "↳";
   return status === "completed" ? "✓" : "✗";
 }
 
-function cleanupTimer(agentName: string, context: RenderContext) {
-  const timerKey = "_subagentTimer_" + agentName;
-  const frameKey = "_subagentFrame_" + agentName;
-  if (context.state[timerKey]) {
-    clearInterval(context.state[timerKey] as ReturnType<typeof setInterval>);
-    delete context.state[timerKey];
-  }
-  delete context.state[frameKey];
-}
-
 // ── Compact single agent ────────────────────────────────────────────────────
 
 export function renderCompactSingle(
@@ -92,23 +70,13 @@ export function renderCompactSingle(
   const isRunning = progress?.status === "running";
   const status = isRunning ? "running" : (result.exitCode === 0 ? "completed" : "failed");
 
-  // Manage timer for spinner on line 3
-  if (isRunning) {
-    getSpinnerGlyph(agentName, true, "running", context);
-  } else {
-    cleanupTimer(agentName, context);
-  }
-
   // Track start time for live duration
   const timeKey = "_subagentStartTime_" + agentName;
-  if (isRunning && !context.state[timeKey]) {
+  if (isRunning && context.state[timeKey] === undefined) {
     // Estimate start time from current duration
     const currentDuration = summary.durationMs || (progress?.durationMs ?? 0);
     context.state[timeKey] = Date.now() - currentDuration;
   }
-  if (!isRunning) {
-    delete context.state[timeKey];
-  }
   const liveDuration = isRunning && context.state[timeKey]
     ? Date.now() - (context.state[timeKey] as number)
     : summary.durationMs;
@@ -124,14 +92,13 @@ export function renderCompactSingle(
 
   const statsPart = statsLine ?? "";
 
-  // Activity: spinner + current tool if running, status if finished
+  // Activity: arrow + current tool if running, status if finished
   let activityLine: string;
   if (isRunning) {
-    const spinner = SPINNER_FRAMES[(context.state["_subagentFrame_" + agentName] as number) ?? 0];
-    const spinnerColored = theme.fg("muted", spinner);
+    const arrow = theme.fg("muted", "↳ ");
     if (progress?.currentTool) {
       const argsPreview = progress.currentToolArgs
-        ? truncLine(progress.currentToolArgs, 60)
+        ? truncLine(progress.currentToolArgs ?? "", 60)
         : "";
       const durationPart = progress.currentToolStartedAt
         ? " | " + formatDuration(Date.now() - progress.currentToolStartedAt)
@@ -143,10 +110,10 @@ export function renderCompactSingle(
       if (durationPart) {
         line += theme.fg("dim", durationPart);
       }
-      activityLine = spinnerColored + " " + line;
+      activityLine = arrow + line;
     } else if (progress?.toolCalls && progress.toolCalls.length > 0) {
       const lastCall = progress.toolCalls[progress.toolCalls.length - 1];
-      activityLine = theme.fg("dim", "  ⎿  ") + theme.fg("muted", lastCall);
+      activityLine = theme.fg("dim", "  ⎿  ") + theme.fg("muted", lastCall ?? "");
     } else {
       activityLine = theme.fg("muted", "  ⎿  Working...");
     }
@@ -182,9 +149,10 @@ export function renderCompactParallel(
     const progress = details.progress?.[i];
     const agentName = result.agent ?? "agent-" + i;
     const summary = result.progressSummary ?? { toolCount: 0, tokens: 0, durationMs: 0 };
+    const isRunning = progress?.status === "running";
     const status = progress?.status ?? (result.exitCode === 0 ? "completed" : "failed");
 
-    let glyph = status === "completed" ? "✓" : status === "failed" ? "✗" : "⠋";
+    const glyph = statusGlyph(isRunning, status);
     const glyphColored = status === "completed"
       ? theme.fg("success", glyph)
       : status === "failed"
@@ -234,7 +202,7 @@ export function renderCompactProgress(
   const status = progress.status;
   const isRunning = status === "running";
 
-  let glyph = getSpinnerGlyph(agentName, isRunning, status, context);
+  const glyph = statusGlyph(isRunning, status);
   const glyphColored = status === "completed"
     ? theme.fg("success", glyph)
     : status === "failed"
@@ -243,13 +211,10 @@ export function renderCompactProgress(
 
   // Track start time for live duration
   const timeKey = "_subagentStartTime_" + agentName;
-  if (isRunning && !context.state[timeKey]) {
+  if (isRunning && context.state[timeKey] === undefined) {
     context.state[timeKey] = Date.now() - (progress.durationMs ?? 0);
   }
-  if (!isRunning) {
-    delete context.state[timeKey];
-  }
-  const liveDuration = isRunning && context.state[timeKey]
+  const liveDuration = isRunning && context.state[timeKey] !== undefined
     ? Date.now() - (context.state[timeKey] as number)
     : progress.durationMs;
 
@@ -262,14 +227,13 @@ export function renderCompactProgress(
   };
   const statsLine = buildStatsLine(statsData, theme);
 
-  // Activity: current tool if running, status if finished
+  // Activity: arrow + current tool if running, status if finished
   let activityLine: string;
   if (isRunning) {
-    const spinner = SPINNER_FRAMES[(context.state["_subagentFrame_" + agentName] as number) ?? 0];
-    const spinnerColored = theme.fg("muted", spinner);
+    const arrow = theme.fg("muted", "↳ ");
     if (progress.currentTool) {
       const argsPreview = progress.currentToolArgs
-        ? truncLine(progress.currentToolArgs, 60)
+        ? truncLine(progress.currentToolArgs ?? "", 60)
         : "";
       const durationPart = progress.currentToolStartedAt
         ? " | " + formatDuration(Date.now() - progress.currentToolStartedAt)
@@ -281,12 +245,12 @@ export function renderCompactProgress(
       if (durationPart) {
         line += theme.fg("dim", durationPart);
       }
-      activityLine = spinnerColored + " " + line;
+      activityLine = arrow + line;
     } else if (progress.toolCalls && progress.toolCalls.length > 0) {
       const lastCall = progress.toolCalls[progress.toolCalls.length - 1];
-      activityLine = spinnerColored + " " + theme.fg("muted", lastCall);
+      activityLine = arrow + theme.fg("muted", lastCall ?? "");
     } else {
-      activityLine = spinnerColored + " " + theme.fg("muted", "Working...");
+      activityLine = arrow + theme.fg("muted", "Working...");
     }
   } else if (progress.error) {
     activityLine = theme.fg("error", "✗ " + truncLine(progress.error, 80));
@@ -321,7 +285,7 @@ export function renderCompactParallelProgress(
     const status = progress.status;
     const isRunning = status === "running";
 
-    let glyph = getSpinnerGlyph(agentName, isRunning, status, context);
+    const glyph = statusGlyph(isRunning, status);
     const glyphColored = status === "completed"
       ? theme.fg("success", glyph)
       : status === "failed"

package/src/execute.ts

@@ -1,15 +1,17 @@
 import { spawnSubagent } from "./spawn.js";
 import { streamEvents } from "./stream.js";
 import { emitCostUpdate } from "./cost.js";
+import type { AgentConfig } from "./agents.js";
 import type { SubagentProgress, SubagentResult, SubagentUsage } from "./types.js";
 
 export interface ExecuteOptions {
-  agent?: string;
+  agent: string | undefined;
+  agentConfig: AgentConfig | undefined;
   task: string;
-  model?: string;
-  cwd?: string;
-  signal?: AbortSignal;
-  onUpdate?: (progress: SubagentProgress) => void;
+  model: string | undefined;
+  cwd: string | undefined;
+  signal: AbortSignal | undefined;
+  onUpdate: ((progress: SubagentProgress) => void) | undefined;
 }
 
 /**
@@ -24,6 +26,7 @@ export async function executeSubagent(options: ExecuteOptions): Promise<Subagent
     model: options.model,
     cwd: options.cwd,
     signal: options.signal,
+    agent: options.agentConfig,
   });
 
   // Track previously emitted values to only emit deltas
@@ -80,7 +83,10 @@ export async function executeSubagent(options: ExecuteOptions): Promise<Subagent
         cost: 0,
         turns: 0,
       } as SubagentUsage,
+      model: undefined,
+      finalOutput: undefined,
       error: err instanceof Error ? err.message : String(err),
+      progress: undefined,
       progressSummary: { toolCount: 0, tokens: 0, durationMs: Date.now() - startTime },
     };
   }
@@ -90,19 +96,23 @@ export async function executeSubagent(options: ExecuteOptions): Promise<Subagent
  * Execute multiple subagents in parallel.
  */
 export async function executeParallel(options: {
-  tasks: Array<{ agent?: string; task: string; count?: number; model?: string; cwd?: string }>;
-  signal?: AbortSignal;
-  onUpdate?: (progress: SubagentProgress[]) => void;
+  tasks: Array<{ agent: string | undefined; agentConfig: AgentConfig | undefined; task: string; model: string | undefined; cwd: string | undefined }>;
+  signal: AbortSignal | undefined;
+  onUpdate: ((progress: SubagentProgress[]) => void) | undefined;
 }): Promise<SubagentResult[]> {
+  // Collect latest progress per agent for aggregated reporting
+  const latestProgress = new Map<string, SubagentProgress>();
+
   const results = await Promise.all(
     options.tasks.map((taskDef) =>
       executeSubagent({
         ...taskDef,
         signal: options.signal,
         onUpdate: (progress: SubagentProgress) => {
-          // Collect all parallel progress updates
-          // This is a simplified approach — each task fires independently
-          options.onUpdate?.([progress]);
+          // Store latest progress keyed by agent name
+          latestProgress.set(progress.agent, progress);
+          // Emit aggregated progress across ALL agents
+          options.onUpdate?.([...latestProgress.values()]);
         },
       }),
     ),

package/src/expanded.ts

@@ -40,7 +40,7 @@ export function buildExpandedText(
   if (toolCalls && toolCalls.length > 0) {
     lines.push("");
     for (const call of toolCalls) {
-      lines.push(theme.fg("dim", "- " + call));
+      lines.push(theme.fg("dim", "↳ " + call));
     }
   }
 
@@ -88,6 +88,7 @@ export function renderProgressExpanded(
   // Stats line (same as compact view)
   const modelLabel = progress.model ? theme.fg("accent", progress.model) : "";
   const statsLine = buildStatsLine({
+    turns: undefined,
     toolCount: progress.toolCount,
     tokens: progress.tokens,
     durationMs: progress.durationMs,
@@ -109,7 +110,7 @@ export function renderProgressExpanded(
   if (progress.toolCalls && progress.toolCalls.length > 0) {
     lines.push("");
     for (const call of progress.toolCalls) {
-      lines.push(theme.fg("dim", "- " + call));
+      lines.push(theme.fg("dim", "↳ " + call));
     }
   }
 
@@ -160,6 +161,7 @@ export function buildProgressExpandedText(
   // Stats line (same as compact view)
   const modelLabel = progress.model ? theme.fg("accent", progress.model) : "";
   const statsLine = buildStatsLine({
+    turns: undefined,
     toolCount: progress.toolCount,
     tokens: progress.tokens,
     durationMs: progress.durationMs,
@@ -181,7 +183,7 @@ export function buildProgressExpandedText(
   if (progress.toolCalls && progress.toolCalls.length > 0) {
     lines.push("");
     for (const call of progress.toolCalls) {
-      lines.push(theme.fg("dim", "- " + call));
+      lines.push(theme.fg("dim", "↳ " + call));
     }
   }
 

package/src/format.ts

@@ -1,7 +1,5 @@
 import { clampLine } from "@pi-archimedes/core/text";
 
-export const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-
 export function formatTokens(n: number): string {
   if (n >= 1_000_000) return (n / 1_000_000).toFixed(1) + "M";
   if (n >= 1_000) return Math.round(n / 1_000) + "k";
@@ -9,7 +7,8 @@ export function formatTokens(n: number): string {
 }
 
 export function formatDuration(ms: number): string {
-  if (ms < 1000) return "0s";
+  if (ms < 100) return "<0.1s";
+  if (ms < 1000) return (ms / 1000).toFixed(1) + "s";
   const seconds = Math.floor(ms / 1000);
   if (seconds < 60) return seconds + "s";
   const minutes = Math.floor(seconds / 60);
@@ -28,11 +27,11 @@ export function truncLine(text: string, width: number): string {
 }
 
 export interface StatsData {
-  turns?: number;
-  toolCount?: number;
-  tokens?: number;
-  durationMs?: number;
-  cost?: number;
+  turns: number | undefined;
+  toolCount: number | undefined;
+  tokens: number | undefined;
+  durationMs: number | undefined;
+  cost: number | undefined;
 }
 
 export interface StatsTheme {

package/src/handlers.ts

@@ -1,5 +1,10 @@
 import type { StreamState } from "./types.js";
 
+// Truncation limits for previews
+const ARGS_PREVIEW_MAX = 120;
+const TOOL_CALLS_MAX = 50;
+const RECENT_OUTPUT_MAX = 50;
+
 export interface JsonEvent {
   type: string;
   [key: string]: unknown;
@@ -10,14 +15,14 @@ export interface JsonEvent {
  * Generic: no hardcoded tool names.
  */
 export function extractArgsPreview(args: unknown): string {
-  if (typeof args === "string") return args.slice(0, 120);
+  if (typeof args === "string") return args.slice(0, ARGS_PREVIEW_MAX);
   if (args && typeof args === "object" && !Array.isArray(args)) {
     const obj = args as Record<string, unknown>;
     const keys = Object.keys(obj);
     // Single-key object: just show the value
     if (keys.length === 1) {
-      const v = obj[keys[0]];
-      if (typeof v === "string") return v.slice(0, 120);
+      const v = obj[keys[0]!];
+      if (typeof v === "string") return v.slice(0, ARGS_PREVIEW_MAX);
       if (typeof v === "number" || typeof v === "boolean") return String(v);
     }
     // Multi-key: find the longest string value (likely the main payload)
@@ -27,9 +32,10 @@ export function extractArgsPreview(args: unknown): string {
         best = v;
       }
     }
-    if (best) return best.slice(0, 120);
+    if (best) return best.slice(0, ARGS_PREVIEW_MAX);
   }
-  return JSON.stringify(args)?.slice(0, 120) ?? "";
+  const serialized = JSON.stringify(args);
+  return serialized?.slice(0, ARGS_PREVIEW_MAX) ?? "";
 }
 
 /**
@@ -43,8 +49,8 @@ export function handleToolStart(state: StreamState, event: JsonEvent): void {
   // Record tool call with args preview
   const argsPreview = extractArgsPreview(event.args);
   state.toolCalls.push(`${state.currentTool}: ${argsPreview}`);
-  if (state.toolCalls.length > 50) {
-    state.toolCalls.splice(0, state.toolCalls.length - 50);
+  if (state.toolCalls.length > TOOL_CALLS_MAX) {
+    state.toolCalls.splice(0, state.toolCalls.length - TOOL_CALLS_MAX);
   }
 }
 
@@ -69,20 +75,20 @@ export function handleToolResult(state: StreamState, event: JsonEvent): void {
 
   if (typeof toolContent === "string" && toolContent.trim()) {
     const lines = toolContent.split("\n").filter((l) => l.trim());
-    state.recentOutput.push(`[${toolName}] ${lines[0]?.slice(0, 120)}`);
+    state.recentOutput.push(`[${toolName}] ${lines[0]?.slice(0, ARGS_PREVIEW_MAX)}`);
   } else if (Array.isArray(toolContent)) {
     for (const part of toolContent) {
       if (part.type === "text" && (part.text as string)?.trim()) {
         const text = part.text as string;
         const lines = text.split("\n").filter((l) => l.trim());
-        state.recentOutput.push(`[${toolName}] ${lines[0]?.slice(0, 120)}`);
+        state.recentOutput.push(`[${toolName}] ${lines[0]?.slice(0, ARGS_PREVIEW_MAX)}`);
         break;
       }
     }
   }
 
-  if (state.recentOutput.length > 50) {
-    state.recentOutput.splice(0, state.recentOutput.length - 50);
+  if (state.recentOutput.length > RECENT_OUTPUT_MAX) {
+    state.recentOutput.splice(0, state.recentOutput.length - RECENT_OUTPUT_MAX);
   }
 }
 
@@ -115,9 +121,9 @@ export function handleMessageEnd(state: StreamState, event: JsonEvent): void {
     }
   }
 
-  // Cap recentOutput at 50 lines
-  if (state.recentOutput.length > 50) {
-    state.recentOutput.splice(0, state.recentOutput.length - 50);
+  // Cap recentOutput
+  if (state.recentOutput.length > RECENT_OUTPUT_MAX) {
+    state.recentOutput.splice(0, state.recentOutput.length - RECENT_OUTPUT_MAX);
   }
 
   // Extract usage (turnCount tracked via turn_start in stream.ts)

package/src/index.ts

@@ -3,6 +3,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { executeSubagent, executeParallel } from "./execute.js";
 import { renderSubagentResult } from "./render.js";
+import { discoverAgents, findAgent } from "./agents.js";
 import type {
   SubagentDetails,
   SubagentProgress,
@@ -15,7 +16,6 @@ import type {
 const TaskItem = Type.Object({
   agent: Type.Optional(Type.String()),
   task: Type.String(),
-  count: Type.Optional(Type.Number()),
   model: Type.Optional(Type.String()),
   cwd: Type.Optional(Type.String()),
 });
@@ -25,13 +25,13 @@ const SUBAGENT_PARAMS_SCHEMA = Type.Object({
     description: "Agent name/identifier (optional, defaults to 'general')",
   })),
   task: Type.Optional(Type.String({
-    description: "Task description for the subagent",
+    description: "Task description for the subagent. Required when not using 'tasks' array.",
   })),
   tasks: Type.Optional(Type.Array(TaskItem, {
-    description: "Multiple tasks for parallel execution",
+    description: "Multiple tasks for parallel execution. Required when not using 'task'.",
   })),
   model: Type.Optional(Type.String({
-    description: "Model override (e.g. 'anthropic/claude-sonnet-4')",
+    description: "Model override for the subagent",
   })),
   async: Type.Optional(Type.Boolean({
     description: "Run asynchronously (fire-and-forget)",
@@ -55,7 +55,7 @@ export function registerSubagent(pi: ExtensionAPI): void {
     name: "subagent",
     label: "Subagent",
     description:
-      "Delegate tasks to subagents. Single: { agent, task }. Parallel: { tasks: [{ agent, task }] }. Options: model, cwd.",
+      "Delegate tasks to subagents. Provide either 'task' (single) or 'tasks' (parallel). Never omit both. Options: agent, model, cwd.",
     parameters: SUBAGENT_PARAMS_SCHEMA,
 
     async execute(
@@ -70,13 +70,36 @@ export function registerSubagent(pi: ExtensionAPI): void {
       },
       signal: AbortSignal | undefined,
       onUpdate: ((update: SubagentToolResult) => void) | undefined,
-      _ctx: ExtensionContext,
+      ctx: ExtensionContext,
     ): Promise<SubagentToolResult> {
+      // Discover available agents
+      const agents = discoverAgents(ctx.cwd);
+
       // Parallel mode
       if (params.tasks && params.tasks.length > 0) {
+        const missingAgents = params.tasks.filter((t) => t.agent && !findAgent(agents, t.agent));
+        if (missingAgents.length > 0) {
+          const available = agents.map((a) => a.name).join(", ") || "none";
+          const unknown = missingAgents.map((t) => `"${t.agent}"`).join(", ");
+          return {
+            content: [{ type: "text", text: `Unknown agent(s): ${unknown}. Available: ${available}` }],
+            details: {
+              mode: "parallel",
+              results: [],
+              progress: undefined,
+            },
+            isError: true,
+          };
+        }
         const results: SubagentResult[] = await executeParallel({
-          tasks: params.tasks,
-          signal,
+          tasks: params.tasks.map((t) => ({
+            agent: t.agent ?? undefined,
+            agentConfig: t.agent ? findAgent(agents, t.agent) : undefined,
+            task: t.task,
+            model: t.model ?? undefined,
+            cwd: t.cwd ?? undefined,
+          })),
+          signal: signal ?? undefined,
           onUpdate: (progress: SubagentProgress[]) => {
             onUpdate?.({
               content: [],
@@ -101,12 +124,26 @@ export function registerSubagent(pi: ExtensionAPI): void {
 
       // Single mode
       if (params.task) {
+        let agentConfig = params.agent ? findAgent(agents, params.agent) : undefined;
+        if (params.agent && !agentConfig) {
+          const available = agents.map((a) => a.name).join(", ") || "none";
+          return {
+            content: [{ type: "text", text: `Unknown agent: "${params.agent}". Available: ${available}` }],
+            details: {
+              mode: "single",
+              results: [],
+              progress: undefined,
+            },
+            isError: true,
+          };
+        }
         const result: SubagentResult = await executeSubagent({
-          agent: params.agent,
+          agent: params.agent ?? undefined,
+          agentConfig,
           task: params.task,
-          model: params.model,
-          cwd: params.cwd,
-          signal,
+          model: params.model ?? undefined,
+          cwd: params.cwd ?? undefined,
+          signal: signal ?? undefined,
           onUpdate: (progress: SubagentProgress) => {
             onUpdate?.({
               content: [],
@@ -135,6 +172,7 @@ export function registerSubagent(pi: ExtensionAPI): void {
         details: {
           mode: "single",
           results: [],
+          progress: undefined,
         },
         isError: true,
       };

package/src/render.ts

@@ -40,7 +40,7 @@ export function renderSubagentResult(
   // ── Streaming progress (results empty but progress has data) ──────────
   if (details.results.length === 0 && details.progress && details.progress.length > 0) {
     if (details.progress.length === 1) {
-      return renderProgressUpdate(text, details.progress[0], expanded, theme, context);
+      return renderProgressUpdate(text, details.progress[0]!, expanded, theme, context);
     }
     return renderProgressUpdatesParallel(text, details, expanded, theme, context);
   }
@@ -52,7 +52,7 @@ export function renderSubagentResult(
 
   // ── Single agent ────────────────────────────────────────────────────────
   if (details.mode === "single" || details.results.length === 1) {
-    return renderSingleAgent(text, details.results[0], details.progress?.[0], expanded, theme, context);
+    return renderSingleAgent(text, details.results[0]!, details.progress?.[0], expanded, theme, context);
   }
 
   // ── Parallel agents ─────────────────────────────────────────────────────

package/src/spawn.ts

@@ -1,12 +1,16 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import { execSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, writeFileSync, unlinkSync, mkdtempSync, rmdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { AgentConfig } from "./agents.js";
 
 export interface SpawnOptions {
   task: string;
-  model?: string;
-  cwd?: string;
-  signal?: AbortSignal;
+  model: string | undefined;
+  cwd: string | undefined;
+  signal: AbortSignal | undefined;
+  agent: AgentConfig | undefined;
 }
 
 /**
@@ -32,6 +36,29 @@ export function resolvePiCommand(): { command: string; args: string[] } {
   return { command: piPath, args: [] };
 }
 
+/**
+ * Write system prompt to a temp file for --append-system-prompt.
+ */
+function writePromptToFile(agentName: string, prompt: string): { dir: string; filePath: string } {
+  const safeName = agentName.replace(/[^\w.-]+/g, "_");
+  const tmpDir = mkdtempSync(join(tmpdir(), "pi-subagent-"));
+  const filePath = join(tmpDir, `prompt-${safeName}.md`);
+  writeFileSync(filePath, prompt, { encoding: "utf-8" });
+  return { dir: tmpDir, filePath };
+}
+
+/**
+ * Clean up temp prompt file and directory.
+ */
+function cleanupTempFiles(dir: string | null, filePath: string | null): void {
+  if (filePath) {
+    try { unlinkSync(filePath); } catch { /* ignore */ }
+  }
+  if (dir) {
+    try { rmdirSync(dir); } catch { /* ignore */ }
+  }
+}
+
 /**
  * Spawn a child `pi` process in JSON mode.
  */
@@ -40,13 +67,42 @@ export function spawnSubagent(options: SpawnOptions): ChildProcess {
   const args: string[] = [
     ...baseArgs,
     "--mode", "json",
-    "-p", options.task,
+    "-p",
+    "--no-session",
   ];
 
-  if (options.model) {
+  // Use agent config from frontmatter if available
+  if (options.agent) {
+    const agent = options.agent;
+    // Agent's model takes precedence; tool-call model as fallback
+    const modelToUse = agent.model ?? options.model;
+    if (modelToUse) {
+      args.push("--model", modelToUse);
+    }
+    if (agent.thinking) {
+      args.push("--thinking", agent.thinking);
+    }
+    if (agent.tools && agent.tools.length > 0) {
+      args.push("--tools", agent.tools.join(","));
+    }
+  } else if (options.model) {
+    // Fallback: use model from tool call params (legacy)
     args.push("--model", options.model);
   }
 
+  // Temp files for system prompt
+  let tmpDir: string | null = null;
+  let tmpPath: string | null = null;
+
+  if (options.agent && options.agent.systemPrompt.trim()) {
+    const tmp = writePromptToFile(options.agent.name, options.agent.systemPrompt);
+    tmpDir = tmp.dir;
+    tmpPath = tmp.filePath;
+    args.push("--append-system-prompt", tmpPath);
+  }
+
+  args.push(options.task);
+
   const child = spawn(command, args, {
     cwd: options.cwd || process.cwd(),
     stdio: ["ignore", "pipe", "pipe"],
@@ -54,8 +110,9 @@ export function spawnSubagent(options: SpawnOptions): ChildProcess {
   });
 
   // Handle abort signal
+  let abortHandler: (() => void) | undefined;
   if (options.signal) {
-    const cleanup = () => {
+    abortHandler = () => {
       if (child.pid && !child.killed) {
         child.kill("SIGTERM");
         const forceKill = setTimeout(() => {
@@ -66,8 +123,20 @@ export function spawnSubagent(options: SpawnOptions): ChildProcess {
         forceKill.unref();
       }
     };
-    options.signal.addEventListener("abort", cleanup, { once: true });
+    options.signal.addEventListener("abort", abortHandler, { once: true });
   }
 
+  // Clean up temp files and listeners on exit
+  const exitCleanup = (): void => {
+    child.removeListener("exit", exitCleanup);
+    child.removeListener("error", exitCleanup);
+    if (abortHandler && options.signal) {
+      options.signal.removeEventListener("abort", abortHandler);
+    }
+    cleanupTempFiles(tmpDir, tmpPath);
+  };
+  child.on("exit", exitCleanup);
+  child.on("error", exitCleanup);
+
   return child;
 }

package/src/stream.ts

@@ -74,6 +74,9 @@ export function streamEvents(
       callbacks.onProgress?.(buildProgress());
     };
 
+    // Periodic progress updates for live duration display
+    const heartbeat = setInterval(emitProgress, 1000);
+
     // Collect stderr
     const stderrParts: string[] = [];
     child.stderr?.on("data", (data: Buffer) => {
@@ -129,6 +132,7 @@ export function streamEvents(
     // Handle process exit
     child.on("close", (code) => {
       clearTimeout(timeout);
+      clearInterval(heartbeat);
       const durationMs = Date.now() - startTime;
       const exitCode = code ?? 1;
 
@@ -171,6 +175,7 @@ export function streamEvents(
 
     child.on("error", (err) => {
       clearTimeout(timeout);
+      clearInterval(heartbeat);
       reject(err);
     });
   });

package/src/types.ts

@@ -11,24 +11,24 @@ export interface SubagentProgress {
   agent: string;
   status: "running" | "completed" | "failed";
   task: string;
-  currentTool?: string;
-  currentToolArgs?: string;
-  currentToolStartedAt?: number;
+  currentTool: string | undefined;
+  currentToolArgs: string | undefined;
+  currentToolStartedAt: number | undefined;
   toolCount: number;
   inputTokens: number;
   outputTokens: number;
   tokens: number;
   cost: number;
   durationMs: number;
-  error?: string;
+  error: string | undefined;
   /** Model used by the subagent */
-  model?: string;
+  model: string | undefined;
   /** Accumulated assistant text output during streaming */
-  output?: string;
+  output: string | undefined;
   /** Last N lines of assistant text for live display */
-  recentOutput?: string[];
+  recentOutput: string[] | undefined;
   /** History of tool calls: "toolName: args_preview" */
-  toolCalls?: string[];
+  toolCalls: string[] | undefined;
 }
 
 export interface SubagentResult {
@@ -36,11 +36,11 @@ export interface SubagentResult {
   task: string;
   exitCode: number;
   usage: SubagentUsage;
-  model?: string;
-  finalOutput?: string;
-  error?: string;
-  progress?: SubagentProgress;
-  progressSummary?: { toolCount: number; tokens: number; durationMs: number };
+  model: string | undefined;
+  finalOutput: string | undefined;
+  error: string | undefined;
+  progress: SubagentProgress | undefined;
+  progressSummary: { toolCount: number; tokens: number; durationMs: number } | undefined;
 }
 
 export interface SubagentToolResult {
@@ -52,7 +52,7 @@ export interface SubagentToolResult {
 export interface SubagentDetails {
   mode: "single" | "parallel";
   results: SubagentResult[];
-  progress?: SubagentProgress[];
+  progress: SubagentProgress[] | undefined;
 }
 
 /** Mutable state during streaming — shared between stream.ts and handlers.ts */