@d3ara1n/pi-subagent 0.4.0 → 0.5.0

package/README.md

@@ -17,7 +17,7 @@ This means:
 - **Multiple subagents can run in parallel** — emit multiple `delegate` calls in one turn; pi executes them concurrently
 - **Subagents can nest subagents** — a `worker` can delegate exploration to `explorer` without returning to the main model
 
-> This design intentionally excludes chain pipelines and context-forking — those patterns are better suited when subagents act as advisors (planner, oracle), not executors.
+> This design currently focuses on single-task delegation rather than chain pipelines or context-forking — those patterns fit better when subagents act as advisors (planner, oracle) rather than executors.
 
 ## How it works
 
@@ -61,65 +61,44 @@ pi install @d3ara1n/pi-subagent
 
 Edit `~/.pi/agent/settings.json`:
 
-```jsonc
+```json
 {
   "subagent": {
-    // Default timeout per subagent (10 minutes)
-    "timeoutMs": 600000,
-
-    // Max subagents running at once; extras queue with a "queued" TUI hint
+    "timeout": 600,
     "maxConcurrency": 4,
-
-    // Max subagent nesting depth (the main session is depth 0).
-    // Default 3 covers worker → researcher → explorer chains.
     "maxDepth": 3,
-
-    // Turn / cost budgets (0 = unlimited). A run is killed once either is hit;
-    // partial output is returned with stopReason "budget_exceeded".
     "maxTurns": 0,
     "maxCost": 0,
-
-    // Audit log: one JSON per delegate run under
-    // ~/.pi/subagent/history/{sessionId}/{toolCallId}.json
     "history": {
       "enabled": true
     },
-
-    // Summary generation — uses a lightweight model to create
-    // a one-line summary for the TUI display.
-    // Outputs ≤ 150 chars skip the API call and reuse the text directly.
     "summary": {
-      "role": "utility",    // pi-model-roles role for summarization
-      "enabled": true        // set false to disable
+      "role": "utility",
+      "enabled": true
     }
   }
 }
 ```
 
-All fields are optional. Defaults: `timeoutMs: 600000` (10 min; roles that can `delegate` get 2× automatically when no per-role timeout is set), `maxConcurrency: 4`, `maxDepth: 3`, `maxTurns: 0` (unlimited), `maxCost: 0` (unlimited), `history.enabled: true`, `summary.role: "utility"`, `summary.enabled: true`.
+All fields are optional. Defaults: `timeout: 600` (seconds; 10 min; roles that can `delegate` get 2× automatically when no per-role timeout is set), `maxConcurrency: 4`, `maxDepth: 3`, `maxTurns: 0` (unlimited), `maxCost: 0` (unlimited), `history.enabled: true`, `summary.role: "utility"`, `summary.enabled: true`.
 
 ### Agent Overrides
 
 Override, disable, or add subagent roles via `agentOverrides`. Built-in and custom roles are treated equally — all descriptions, examples, and decision triggers feed into the LLM's prompt dynamically.
 
-```jsonc
+```json
 {
   "subagent": {
     "agentOverrides": {
-      // ── Override a built-in role (only specify changed fields) ──
       "worker": {
-        "role": "heavy",              // use a stronger model
-        "timeoutMs": 600000,          // per-role timeout (overrides global)
-        "maxTurns": 50,               // per-role turn budget (0 = unlimited)
-        "maxCost": 1.0                // per-role cost ceiling in USD (0 = unlimited)
+        "role": "heavy",
+        "timeout": 600,
+        "maxTurns": 50,
+        "maxCost": 1.0
       },
-
-      // ── Disable a built-in role ──
       "reviewer": {
         "disabled": true
       },
-
-      // ── Add a custom role (all required fields must be provided) ──
       "tester": {
         "role": "default",
         "description": "Test automation & QA — write and run tests, validate fixes. Tools: read, bash, edit, write, grep. Can delegate to explorer.",
@@ -138,7 +117,7 @@ Override, disable, or add subagent roles via `agentOverrides`. Built-in and cust
 
 **Required fields for custom roles:** `role`, `description`, `examples`, `decisionTrigger`, `tools`, `systemPrompt`.
 
-**Optional fields:** `subagentRoles` (roles this role can spawn via delegate), `timeoutMs` (per-role timeout override; when unset, delegate-capable roles get 2× the global default automatically), `maxTurns` / `maxCost` (per-role budget overrides; 0 = unlimited), `fallbackRole` (backup pi-model-roles role on provider errors).
+**Optional fields:** `subagentRoles` (roles this role can spawn via delegate), `timeout` (per-role timeout override in seconds; when unset, delegate-capable roles get 2× the global default automatically), `maxTurns` / `maxCost` (per-role budget overrides; 0 = unlimited), `fallbackRole` (backup pi-model-roles role on provider errors).
 
 Invalid custom roles (missing required fields) are silently skipped with an error notification at session start.
 
@@ -171,9 +150,13 @@ Delegate tasks that would generate many tool calls or verbose output to keep you
 ]
 ```
 
-### Passing extra context
+### Passing context and reference files
 
-The optional `context` field lets you hand a subagent precise context — selected code, a prior delegate's result, a file list, a git diff — without inflating the `task` string. It's prepended before the task:
+pi-subagent delivers context to the child as **independent channels**, never fused into the task string. This keeps the task an unambiguous directive and lets each channel be sized independently.
+
+#### `context` (inline text)
+
+Hand the subagent precise context — selected code, a prior delegate's result, a file list, a git diff — without inflating the `task` string. It's delivered as a separate channel:
 
 ```json
 {
@@ -183,7 +166,19 @@ The optional `context` field lets you hand a subagent precise context — select
 }
 ```
 
-The stored/displayed task stays as the original `task`; the `context` is merged into the prompt the subagent receives.
+The stored/displayed task stays as the original `task`. When small, `context` inlines as a `<context>` block; when large (over 8,000 chars) it spills to a temp file injected via `@file`, so a large context never drags a short task into a spill.
+
+#### `files` (reference paths)
+
+```json
+{
+  "role": "explorer",
+  "task": "Report the public API of the auth module",
+  "files": ["src/auth.ts", "src/auth.types.ts"]
+}
+```
+
+Each path is injected as an independent `@file` attachment the subagent reads directly. **File contents stay out of your context window** — you pass only the paths. Prefer this over pasting file contents into `context`, since the child receives the content on its first turn without spending a tool call to read it.
 
 ### Budget enforcement
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-subagent",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Role-based subagent orchestration for pi — delegates tasks to specialized pi child processes with configurable model roles",
   "main": "src/index.ts",

package/src/config.ts

@@ -54,7 +54,7 @@ export function loadSubagentConfig(cwd?: string): SubagentConfig {
 	const rawSummary = raw?.summary;
 	const rawHistory = raw?.history;
 	return {
-		timeoutMs: raw.timeoutMs ?? DEFAULT_CONFIG.timeoutMs,
+		timeout: raw.timeout ?? DEFAULT_CONFIG.timeout,
 		maxConcurrency: raw.maxConcurrency ?? DEFAULT_CONFIG.maxConcurrency,
 		maxDepth: raw.maxDepth ?? DEFAULT_CONFIG.maxDepth,
 		maxTurns: raw.maxTurns ?? DEFAULT_CONFIG.maxTurns,

package/src/index.ts

@@ -9,7 +9,7 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { getMarkdownTheme, type ThemeColor } from "@earendil-works/pi-coding-agent";
 import { complete } from "@earendil-works/pi-ai";
 import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
@@ -27,6 +27,7 @@ import {
 	AsyncSemaphore,
 	buildDisplayItems,
 	formatUsageStats,
+	elapsedSeconds,
 	formatToolCall,
 	statusStyle,
 	formatThinking,
@@ -34,7 +35,7 @@ import {
 	isFailedResult,
 	sanitizeFilename,
 	isProviderError,
-	effectiveTimeoutMs,
+	effectiveTimeout,
 	type DisplayItem,
 } from "./utils.ts";
 import * as os from "node:os";
@@ -127,10 +128,10 @@ async function compressOutput(
 		);
 
 		const compressed =
-			result.content
-				?.filter((block: any) => block.type === "text")
-				?.map((block: any) => block.text)
-				?.join("") ?? "";
+			(result.content as Array<{ type: string; text?: string }> | undefined)
+				?.filter((block) => block.type === "text")
+				.map((block) => block.text ?? "")
+				.join("") || "";
 
 		if (!compressed.trim()) return { text: truncateOutput(text), method: "truncated" };
 		// Model may not compress enough — fall back to truncation so we stay within budget
@@ -183,11 +184,11 @@ async function generateSummary(
 			},
 		);
 
-		const text = result.content
-			?.filter((block: any) => block.type === "text")
-			?.map((block: any) => block.text)
-			?.join("")
-			?.trim();
+		const text = (result.content as Array<{ type: string; text?: string }> | undefined)
+			?.filter((block) => block.type === "text")
+			.map((block) => block.text ?? "")
+			.join("")
+			.trim();
 
 		return text || undefined;
 	} catch {
@@ -269,11 +270,12 @@ export default function subagentExtension(pi: ExtensionAPI) {
 			"",
 			"For multiple independent substantial tasks, emit multiple delegate calls in one turn — they run in parallel.",
 			"Include ALL necessary context — subagents have no access to this conversation.",
+			"Pass reference files via the `files` parameter (e.g. files: [\"src/auth.ts\"]) instead of pasting their contents into `context` — the subagent reads them directly without consuming your context window.",
 		);
 	}
 
 	// Apply agent overrides on top of built-in roles
-	function applyAgentOverrides(roles: Record<string, SubagentRole>, overrides: Record<string, any>): void {
+	function applyAgentOverrides(roles: Record<string, SubagentRole>, overrides: Record<string, Partial<SubagentRole> & { disabled?: boolean }>): void {
 		for (const [name, override] of Object.entries(overrides)) {
 			if (override.disabled) {
 				delete roles[name];
@@ -292,6 +294,16 @@ export default function subagentExtension(pi: ExtensionAPI) {
 	pi.on("session_start", async (_event, ctx) => {
 		config = loadSubagentConfig(ctx.cwd);
 		concurrencyGate = new AsyncSemaphore(config.maxConcurrency);
+
+		// Rebuild from BUILTIN_ROLES (respecting ALLOWLIST) so repeated
+		// session_start is idempotent — overrides from prior sessions don't accumulate.
+		for (const key of Object.keys(availableRoles)) delete availableRoles[key];
+		for (const [name, role] of Object.entries(BUILTIN_ROLES)) {
+			if (!ALLOWLIST || ALLOWLIST.includes(name)) {
+				availableRoles[name] = role;
+			}
+		}
+
 		applyAgentOverrides(availableRoles, config.agentOverrides);
 
 		// Validate custom roles (skip built-in roles — they already have all fields)
@@ -321,11 +333,13 @@ export default function subagentExtension(pi: ExtensionAPI) {
 		parameters: Type.Object({
 			role: Type.String({ description: "Subagent role to use" }),
 			task: Type.String({ description: "Specific task for the subagent" }),
-			context: Type.Optional(Type.String({ description: "Extra context to give the subagent (selected code, prior results, file list, etc.). Prepended before the task. Omit if the task alone is enough." })),
+			context: Type.Optional(Type.String({ description: "Extra context to give the subagent (selected code, prior results, file list, etc.). Delivered as a separate channel from the task. Omit if the task alone is enough." })),
+			files: Type.Optional(Type.Array(Type.String(), { description: "Reference file paths for the subagent to read directly (e.g. [\"src/auth.ts\", \"docs/api.md\"]). Injected as @file attachments — content stays out of your context window. Prefer this over pasting file contents into context." })),
 			cwd: Type.Optional(Type.String({ description: "Working directory (defaults to current)" })),
 		}),
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			const gate = concurrencyGate;
 			const roleDef = availableRoles[params.role];
 			if (!roleDef) {
 				return {
@@ -353,12 +367,6 @@ export default function subagentExtension(pi: ExtensionAPI) {
 				};
 			}
 
-			// #12: prepend optional extra context so the subagent gets precise info
-			// without cramming everything into the task string.
-			const effectiveTask = params.context
-				? `## Context\n\n${params.context}\n\n---\n\n## Task\n\n${params.task}`
-				: params.task;
-
 			// Throttle state hoisted to the execute scope so the finally block can clear it.
 			// (try-body `let` is invisible to catch/finally — JS gives each its own block scope.)
 			let pendingPartial: Partial<SubagentResult> | undefined;
@@ -393,6 +401,8 @@ export default function subagentExtension(pi: ExtensionAPI) {
 					stderr: "",
 					usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
 					activityLog: [],
+					files: params.files,
+					context: params.context,
 				};
 				onUpdate({
 					content: [{ type: "text", text: `${params.role}: queued...` }],
@@ -402,7 +412,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
 
 			// Acquire a concurrency slot (abortable while queued)
 			try {
-				await concurrencyGate.acquire(signal);
+				await gate.acquire(signal);
 			} catch {
 				return {
 					content: [{ type: "text", text: `Subagent (${params.role}) was cancelled while queued.` }],
@@ -457,6 +467,9 @@ export default function subagentExtension(pi: ExtensionAPI) {
 						model: partial.model,
 						stopReason: partial.stopReason,
 						activityLog: partial.activityLog ?? [],
+						startTime,
+						files: params.files,
+						context: params.context,
 					};
 					const statusText = `${params.role}  ${elapsed}s  ${liveResult.usage.turns} turn${liveResult.usage.turns !== 1 ? "s" : ""}`;
 					onUpdate!({
@@ -487,6 +500,9 @@ export default function subagentExtension(pi: ExtensionAPI) {
 						stderr: "",
 						usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
 						activityLog: [],
+						startTime,
+						files: params.files,
+						context: params.context,
 					};
 					onUpdate({
 						content: [{ type: "text", text: `${params.role}: running...` }],
@@ -494,12 +510,14 @@ export default function subagentExtension(pi: ExtensionAPI) {
 					});
 				}
 
-				let result = await spawnSubagent(modelRef, effectiveTask, {
+				let result = await spawnSubagent(modelRef, params.task, {
 					cwd: params.cwd ?? ctx.cwd,
 					tools: roleDef.tools,
 					systemPrompt: roleDef.systemPrompt,
+					context: params.context,
+					contextFiles: params.files,
 					subagentRoles: roleDef.subagentRoles,
-					timeoutMs: effectiveTimeoutMs(roleDef, config.timeoutMs),
+					timeoutMs: effectiveTimeout(roleDef, config.timeout) * 1000,
 					maxTurns: roleDef.maxTurns ?? config.maxTurns,
 					maxCost: roleDef.maxCost ?? config.maxCost,
 					depth: CURRENT_DEPTH + 1,
@@ -514,12 +532,14 @@ export default function subagentExtension(pi: ExtensionAPI) {
 					const fallback = await rolesApi.resolveRoleAsync(roleDef.fallbackRole);
 					if (fallback.model) {
 						const fbRef = `${fallback.model.provider}/${fallback.model.id}`;
-						result = await spawnSubagent(fbRef, effectiveTask, {
+						result = await spawnSubagent(fbRef, params.task, {
 							cwd: params.cwd ?? ctx.cwd,
 							tools: roleDef.tools,
 							systemPrompt: roleDef.systemPrompt,
+							context: params.context,
+							contextFiles: params.files,
 							subagentRoles: roleDef.subagentRoles,
-							timeoutMs: effectiveTimeoutMs(roleDef, config.timeoutMs),
+							timeoutMs: effectiveTimeout(roleDef, config.timeout) * 1000,
 							maxTurns: roleDef.maxTurns ?? config.maxTurns,
 							maxCost: roleDef.maxCost ?? config.maxCost,
 							depth: CURRENT_DEPTH + 1,
@@ -530,6 +550,12 @@ export default function subagentExtension(pi: ExtensionAPI) {
 					}
 				}
 
+				// Stamp terminal fields once, after any fallback retry: elapsedMs covers
+				// the whole delegate span (incl. retry); files/context mirror params for the TUI.
+				result.files = params.files;
+				result.context = params.context;
+				result.elapsedMs = Date.now() - startTime;
+
 				// Compress/truncate oversized output before it reaches the main model or TUI.
 				// Keep the raw original for the history file (audit), feed the prepared text to LLM + expanded view.
 				const rawOutput = result.output;
@@ -595,25 +621,21 @@ export default function subagentExtension(pi: ExtensionAPI) {
 				// delegates (worker → explorer): the inner crash surfaces as TUI escapes.
 				if (throttleHandle !== undefined) clearTimeout(throttleHandle);
 				pendingPartial = undefined;
-				concurrencyGate.release();
+				gate.release();
 			}
 		},
 
-		// ── renderCall: what the user sees when the tool is invoked ──────
+		// ── renderCall: what the user sees when the tool is invoked ─────
 
 		renderCall(args, theme, _context) {
 			const roleName = (args as any).role || "...";
-			const task = (args as any).task || "";
-			const preview = task.length > 60 ? `${task.slice(0, 60)}...` : task;
 			const text =
-				theme.fg("toolTitle", theme.bold("subagent ")) +
-				theme.fg("accent", roleName) +
-				"\n  " +
-				theme.fg("dim", preview);
+				theme.fg("toolTitle", theme.bold("delegate ")) +
+				theme.fg("accent", roleName);
 			return new Text(text, 0, 0);
 		},
 
-		// ── renderResult: TUI display when the tool finishes ─────────────
+		// ── renderResult: TUI display when the tool finishes ────────
 
 		renderResult(result, { expanded }, theme, _context) {
 			const details = result.details as SubagentDetails | undefined;
@@ -627,52 +649,90 @@ export default function subagentExtension(pi: ExtensionAPI) {
 			const isError = !isRunning && isFailedResult(r);
 			const isTimeout = !isRunning && r.stopReason === "timeout";
 			const isBudget = !isRunning && r.stopReason === "budget_exceeded";
+			const isFailedState = isError || isTimeout || isBudget;
+
+			// Status icon. ⏳ running / ⏸ queued (pause) / ⏱ timeout / ⏲ budget / ✗ error / ✓ ok
 			let icon: string;
 			if (isRunning) {
-				icon = theme.fg("warning", "\u23F3"); // ⏳ hourglass — time flowing
+				icon = r.queued ? theme.fg("warning", "\u23F8") : theme.fg("warning", "\u23F3");
 			} else if (isTimeout) {
-				icon = theme.fg("warning", "\u23F1"); // ⏱ stopwatch — time ran out
+				icon = theme.fg("warning", "\u23F1");
 			} else if (isBudget) {
-				icon = theme.fg("warning", "\u23F2"); // ⏲ timer — budget exhausted
+				icon = theme.fg("warning", "\u23F2");
 			} else if (isError) {
-				icon = theme.fg("error", "\u2717"); // ✗
+				icon = theme.fg("error", "\u2717");
 			} else {
 				icon = theme.fg("success", "\u2713");
 			}
+
 			const displayItems = buildDisplayItems(r.activityLog);
 			const mdTheme = getMarkdownTheme();
+			const fg = theme.fg.bind(theme) as (color: string, text: string) => string;
+
+			// Task preview: first line, truncated to one row (always-visible anchor).
+			const firstLine = r.task.split("\n")[0];
+			const taskPreview = firstLine.length > 70 ? `${firstLine.slice(0, 70)}...` : firstLine;
+			// taskline: indicator prefix while running/queued; bare text once finished.
+			let taskline: string;
+			if (isRunning) {
+				const label = r.queued ? "(queued)" : "(running)";
+				taskline = `${icon} ${theme.fg("dim", label)} ${theme.fg("text", taskPreview)}`;
+			} else {
+				taskline = theme.fg("text", taskPreview);
+			}
+
+			// usage line: elapsed/live prefix + existing stats.
+			const secs = elapsedSeconds(r);
+			const stats = formatUsageStats(r.usage, r.model);
+			const usageLine = [secs != null ? `${secs}s` : null, stats].filter(Boolean).join(" \u00b7 ");
+
+			// Result line content (shared between collapsed and expanded).
+			let resultContent: string | undefined;
+			let resultCol: ThemeColor | undefined;
+			if (!isRunning) {
+				if (isFailedState) {
+					resultContent = r.errorMessage || (isTimeout ? "Timed out" : isBudget ? "Budget exceeded" : "failed");
+					resultCol = isTimeout || isBudget ? "warning" : "error";
+				} else {
+					resultContent = r.summary || undefined;
+					resultCol = "text";
+				}
+			}
 
 			if (expanded) {
 				const container = new Container();
 
-				// Header
-				let header = `${icon} ${theme.fg("toolTitle", theme.bold(r.role))}`;
-				if (isError && r.stopReason) header += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
-				container.addChild(new Text(header, 0, 0));
-				if (isTimeout && r.errorMessage)
-					container.addChild(new Text(theme.fg("warning", `\u23F1 ${r.errorMessage}`), 0, 0));
-				else if (isBudget && r.errorMessage)
-					container.addChild(new Text(theme.fg("warning", `\u23F2 ${r.errorMessage}`), 0, 0));
-				else if (isError && r.errorMessage)
-					container.addChild(new Text(theme.fg("error", `Error: ${r.errorMessage}`), 0, 0));
-
-				if (!isRunning) {
-					container.addChild(new Spacer(1));
-					container.addChild(new Text(theme.fg("muted", "\u2500\u2500\u2500 Task \u2500\u2500\u2500"), 0, 0));
-					container.addChild(new Text(theme.fg("dim", r.task), 0, 0));
+				// Header: taskline (+ error line on failure; success has no summary line here
+				// — full output below makes it redundant).
+				container.addChild(new Text(taskline, 0, 0));
+				if (resultContent) {
+					container.addChild(new Text(`${icon} ${theme.fg(resultCol!, resultContent)}`, 0, 0));
+				}
+
+				// Input block: reference files + context char count + task full text,
+				// grouped without inner spacing (they are all subagent input).
+				container.addChild(new Spacer(1));
+				if (r.files) {
+					for (const f of r.files) {
+						container.addChild(new Text(theme.fg("dim", `@${f}`), 0, 0));
+					}
+				}
+				if (r.context) {
+					container.addChild(new Text(theme.fg("dim", `ctx ${r.context.length} chars`), 0, 0));
 				}
+				container.addChild(new Text(theme.fg("dim", r.task), 0, 0));
 
+				// Activity stream (shown while running and after completion).
 				container.addChild(new Spacer(1));
 				const activity = displayItems.filter((item) => item.type === "toolCall" || item.type === "thinking");
 				if (activity.length === 0) {
 					const runningLabel = isRunning
 						? r.queued
-							? "(queued — waiting for a concurrency slot...)"
+							? "(queued \u2014 waiting for a concurrency slot...)"
 							: "(waiting for first event...)"
 						: "(none)";
 					container.addChild(new Text(theme.fg("muted", runningLabel), 0, 0));
 				} else {
-					const fg = theme.fg.bind(theme) as (color: string, text: string) => string;
 					for (const item of activity) {
 						if (item.type === "thinking") {
 							container.addChild(new Text(formatThinking(item.status, fg), 0, 0));
@@ -685,9 +745,9 @@ export default function subagentExtension(pi: ExtensionAPI) {
 					}
 				}
 
+				// Full output (terminal runs only).
 				if (!isRunning && r.output.trim()) {
 					container.addChild(new Spacer(1));
-					container.addChild(new Text(theme.fg("muted", "\u2500\u2500\u2500 Output \u2500\u2500\u2500"), 0, 0));
 					container.addChild(new Markdown(r.output.trim(), 0, 0, mdTheme));
 					if (r.outputMethod === "compressed") {
 						container.addChild(new Text(theme.fg("muted", "(output compressed by summary model \u2014 full text in history)"), 0, 0));
@@ -696,53 +756,34 @@ export default function subagentExtension(pi: ExtensionAPI) {
 					}
 				}
 
-				const usageStr = formatUsageStats(r.usage, r.model);
-				if (usageStr) {
+				// Usage (with elapsed).
+				if (usageLine) {
 					container.addChild(new Spacer(1));
-					container.addChild(new Text(theme.fg("dim", usageStr), 0, 0));
+					container.addChild(new Text(theme.fg("dim", usageLine), 0, 0));
 				}
 
 				return container;
 			}
 
-			// Collapsed view
-			let text = `${icon} ${theme.fg("toolTitle", theme.bold(r.role))}`;
-
-			if (isRunning) {
-				if (r.queued) {
-					text += `\n${theme.fg("muted", "(queued — waiting for a concurrency slot...)")}`;
+			// Collapsed view.
+			let text = taskline;
+			if (!isRunning) {
+				// Result line (shared computation above).
+				if (resultContent) text += `\n${icon} ${theme.fg(resultCol!, resultContent)}`;
+			} else if (!r.queued) {
+				// Running (not queued): show recent activity only.
+				const activity = displayItems.filter((item) => item.type === "toolCall" || item.type === "thinking");
+				if (activity.length === 0) {
+					text += `\n${theme.fg("muted", "(running...)")}`;
 				} else {
-					// Running: show recent tool calls only
-					const activity = displayItems.filter((item) => item.type === "toolCall" || item.type === "thinking");
-					if (activity.length === 0) {
-						text += `\n${theme.fg("muted", "(running...)")}`;
-					} else {
-						const rendered = renderDisplayItems(activity, 5, theme.fg.bind(theme) as (color: string, text: string) => string);
-						if (rendered) text += `\n${rendered}`;
-					}
+					const rendered = renderDisplayItems(activity, 5, fg);
+					if (rendered) text += `\n${rendered}`;
 				}
-			} else {
-				// Finished: summary + usage, no tool calls
-				if (r.summary) {
-					text += ` ${theme.fg("dim", "\u00b7")} ${theme.fg("text", r.summary)}`;
-				}
-				if (isTimeout) {
-					const msg = r.errorMessage || "Timed out";
-					text += `\n${theme.fg("warning", `\u23F1 ${msg}`)}`;
-				} else if (isBudget) {
-					const msg = r.errorMessage || "Budget exceeded";
-					text += `\n${theme.fg("warning", `\u23F2 ${msg}`)}`;
-				} else if (isError) {
-					const errMsg = r.errorMessage || (r.stderr ? r.stderr.trim().split("\n")[0].slice(0, 80) : r.stopReason);
-					if (errMsg) text += `\n${theme.fg("error", `Error: ${errMsg}`)}`;
-				}
-				const usageStr = formatUsageStats(r.usage, r.model);
-				if (usageStr) text += `\n${theme.fg("dim", usageStr)}`;
 			}
+			if (usageLine) text += `\n${theme.fg("dim", usageLine)}`;
 			return new Text(text, 0, 0);
 		},
 	});
-
 	pi.registerCommand("subagent:doctor", {
 		description: "Diagnose pi-subagent configuration and dependencies",
 		handler: async (_args, ctx) => {
@@ -761,7 +802,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
 				// 3. config
 				try {
 					const cfg = loadSubagentConfig(ctx.cwd);
-					lines.push(`[\u2713] config: timeout=${cfg.timeoutMs}ms concurrency=${cfg.maxConcurrency} depth=${cfg.maxDepth} turns=${cfg.maxTurns || "∞"} cost=$${cfg.maxCost || "∞"} summary=${cfg.summary.enabled ? cfg.summary.role : "off"} history=${cfg.history.enabled}`);
+					lines.push(`[\u2713] config: timeout=${cfg.timeout}s concurrency=${cfg.maxConcurrency} depth=${cfg.maxDepth} turns=${cfg.maxTurns || "∞"} cost=$${cfg.maxCost || "∞"} summary=${cfg.summary.enabled ? cfg.summary.role : "off"} history=${cfg.history.enabled}`);
 				} catch {
 					lines.push("[\u2717] config: failed to load");
 					allOk = false;

package/src/spawn.ts

@@ -6,15 +6,15 @@
  * Fires onProgress on each event for streaming updates.
  */
 
-	import { spawn, type ChildProcess } from "node:child_process";
+import { spawn, type ChildProcess } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { SubagentMessage, SubagentResult } from "./types.ts";
 
-/** Maximum task length before writing to a temp file (avoids CLI arg limits). */
-const TASK_CHAR_LIMIT = 8000;
+/** Max chars for an inline channel block (context or task) before it spills to a temp @file. */
+const INLINE_LIMIT = 8000;
 
 
 const PI_CODING_AGENT_PACKAGE = "@earendil-works/pi-coding-agent";
@@ -124,6 +124,10 @@ export async function spawnSubagent(
 		cwd?: string;
 		tools?: string[];
 		systemPrompt?: string;
+		/** Extra context delivered as a separate channel from the task. */
+		context?: string;
+		/** Reference file paths injected as independent @file args (child reads them directly). */
+		contextFiles?: string[];
 		subagentRoles?: string[];
 		timeoutMs?: number;
 		depth?: number;
@@ -145,7 +149,6 @@ export async function spawnSubagent(
 	};
 
 	let tmpDir: string | null = null;
-	let tmpFile: string | null = null;
 
 	try {
 		// Build CLI args
@@ -155,24 +158,72 @@ export async function spawnSubagent(
 			args.push("--tools", options.tools.join(","));
 		}
 
-		// Always create temp dir — used for prompt file, long task file, and as PI_SUBAGENT_TMPDIR for subagent work (e.g. git clone)
+		// Temp dir for: large-context/task spill files, and as PI_SUBAGENT_TMPDIR
+		// for subagent bash work (e.g. git clone). The system prompt no longer uses it.
 		tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-subagent-"));
 
-		const promptContent = options.systemPrompt?.trim()
-			? options.systemPrompt + `\n\nPI_SUBAGENT_TMPDIR=${tmpDir}`
-			: `PI_SUBAGENT_TMPDIR=${tmpDir}`;
-		tmpFile = path.join(tmpDir, "prompt.md");
-		await fs.promises.writeFile(tmpFile, promptContent, { encoding: "utf-8", mode: 0o600 });
-		args.push("--append-system-prompt", tmpFile);
+		// ── System prompt channel: inline text via --append-system-prompt ──
+		// pi's resolvePromptInput treats an existing path as a file to read and any
+		// non-path string as literal text, so we pass structured blocks directly —
+		// no temp file, zero disk I/O. Multiple flags are joined with "\n\n".
+		if (options.systemPrompt?.trim()) {
+			args.push(
+				"--append-system-prompt",
+				`<subagent_role>\n${options.systemPrompt.trim()}\n</subagent_role>`,
+			);
+		}
+		args.push(
+			"--append-system-prompt",
+			`<subagent_env>\nPI_SUBAGENT_TMPDIR=${tmpDir}\nAvailable as $PI_SUBAGENT_TMPDIR in bash. Use for git clone and scratch files.\n</subagent_env>`,
+		);
+
+		// ── Context channel: independent size gate ──
+		// Large context spills to @ctx.md (pi auto-wraps in <file>); small context
+		// inlines as a structured <context> tag. Decoupled from the task gate so a
+		// large context never drags a short task into a spill file.
+		let contextInline = false;
+		if (options.context && options.context.trim()) {
+			if (options.context.length > INLINE_LIMIT) {
+				const ctxPath = path.join(tmpDir, "context.md");
+				await fs.promises.writeFile(ctxPath, options.context, { encoding: "utf-8", mode: 0o600 });
+				args.push(`@${ctxPath}`);
+			} else {
+				contextInline = true;
+			}
+		}
+
+		// ── Reference files channel: each as an independent @ argument ──
+		// pi reads each and wraps in <file name="...">. Content never enters the
+		// parent model's context — the child reads it directly.
+		if (options.contextFiles) {
+			for (const f of options.contextFiles) {
+				args.push(`@${f}`);
+			}
+		}
 
-		if (task.length > TASK_CHAR_LIMIT) {
+		// ── Task channel: always inline, always the final block ──
+		// The task is an instruction, not reference material — it stays inline so the
+		// child sees it as the primary directive. A pathologically long task spills.
+		let taskInline = true;
+		if (task.length > INLINE_LIMIT) {
 			const taskPath = path.join(tmpDir, "task.md");
 			await fs.promises.writeFile(taskPath, task, { encoding: "utf-8", mode: 0o600 });
 			args.push(`@${taskPath}`);
-		} else {
-			args.push(`Task: ${task}`);
+			taskInline = false;
 		}
 
+		// ── Compose the message body (inline context + task) ──
+		// @file args are injected by pi BEFORE this message (buildInitialMessage),
+		// so the final shape the child sees is:
+		//   [<file>...spilled context / reference files...</file>]
+		//   [<context>...inline context...</context>]
+		//   [<task>...task...</task>]
+		const messageParts: string[] = [];
+		if (contextInline) messageParts.push(`<context>\n${options.context}\n</context>`);
+		if (taskInline) messageParts.push(`<task>\n${task}\n</task>`);
+		const message = messageParts.join("\n\n");
+		if (message) args.push(message);
+
 		// Spawn process
 		const invocation = getPiInvocation(args);
 		let wasAborted = false;
@@ -361,14 +412,24 @@ export async function spawnSubagent(
 				result.stderr += data.toString();
 			});
 
-			p.on("close", (code) => {
+			p.on("close", (code, signal) => {
 				if (timeoutHandle) clearTimeout(timeoutHandle);
 				for (const t of escalationTimers) clearTimeout(t);
 				if (onAbort && options.signal) options.signal.removeEventListener("abort", onAbort);
 				if (buffer.trim()) processLine(buffer);
-				// Budget stops are intentional (success); timeouts are failures (exit 124, Unix convention);
-				// otherwise use the real exit code (signal kills yield null → 0).
-				resolve(budgetExceeded ? 0 : (wasTimeout ? 124 : (code ?? 0)));
+
+				// External signal death (OOM killer, segfault, kill -9 from elsewhere)
+				// that we didn't trigger. Distinguish from our own budget/timeout/abort kills
+				// which set the flags before we send the signal.
+				const externalKill = signal !== null && !budgetExceeded && !wasTimeout && !wasAborted;
+				if (externalKill) {
+					result.errorMessage = result.errorMessage || `Subagent killed by signal ${signal}`;
+					result.stopReason = "error";
+				}
+
+				// Budget stops are intentional (success); timeouts and external kills
+				// are failures (non-zero); otherwise use the real exit code.
+				resolve(budgetExceeded ? 0 : (wasTimeout || externalKill ? (code ?? 128) : (code ?? 0)));
 			});
 
 			p.on("error", (err) => {

package/src/types.ts

@@ -4,7 +4,8 @@
 
 /** Configuration for the subagent extension. */
 export interface SubagentConfig {
-  timeoutMs: number;
+  /** Per-subagent timeout in seconds. Roles that can `delegate` get 2× automatically when no per-role timeout is set. */
+  timeout: number;
   /** Max number of subagents allowed to run concurrently. Extras queue with a TUI hint. */
   maxConcurrency: number;
   /** Max subagent nesting depth (the top-level session is depth 0). */
@@ -34,7 +35,7 @@ export interface SubagentSummaryConfig {
 }
 
 export const DEFAULT_CONFIG: SubagentConfig = {
-  timeoutMs: 600_000,
+  timeout: 600,
   maxConcurrency: 4,
   maxDepth: 3,
   maxTurns: 0,
@@ -60,8 +61,8 @@ export interface SubagentRole {
   tools: string[];
   /** If this role has `delegate`, restrict which roles it may spawn. undefined = no restriction. */
   subagentRoles?: string[];
-  /** Per-role timeout override (ms). Falls back to config.timeoutMs when unset. */
-  timeoutMs?: number;
+  /** Per-role timeout override in seconds. Falls back to config.timeout when unset. */
+  timeout?: number;
   /** Max assistant turns before the run is killed (0 = use config default; unset = unlimited). */
   maxTurns?: number;
   /** Max cumulative cost (USD) before the run is killed (0 = use config default; unset = unlimited). */
@@ -149,6 +150,16 @@ export interface SubagentResult {
   errorMessage?: string;
   /** Real-time activity log: thinking blocks and tool calls in arrival order. */
   activityLog: ActivityEntry[];
+
+  // ── TUI 渲染辅助字段（非子进程产出，由 execute 层填入）──────────
+  /** 运行开始墙钟时间；仅 queued/running 帧存在，供 TUI 实时算耗时。终态帧无此字段。 */
+  startTime?: number;
+  /** 终态总耗时(ms)，由 execute 在结束时写入；覆盖整个 delegate 区间（含 fallback 重试）。 */
+  elapsedMs?: number;
+  /** delegate 传入的引用文件路径（params.files），展开视图渲染用。 */
+  files?: string[];
+  /** delegate 传入的额外上下文（params.context），展开视图渲染用。 */
+  context?: string;
 }
 
 /** TUI details structure passed via tool result details. */

package/src/utils.test.ts

@@ -19,7 +19,8 @@ import {
 	previewArgs,
 	truncateOutput,
 	formatTokens,
-	effectiveTimeoutMs,
+	effectiveTimeout,
+	elapsedSeconds,
 } from "./utils.ts";
 import type { SubagentResult, SubagentRole } from "./types.ts";
 
@@ -192,22 +193,22 @@ describe("previewArgs", () => {
 	});
 });
 
-// ── effectiveTimeoutMs: guards delegate-role auto-widening ──
-describe("effectiveTimeoutMs", () => {
-	const role = (tools: string[], timeoutMs?: number): SubagentRole =>
-		({ role: "default", description: "", examples: [], decisionTrigger: "", tools, systemPrompt: "", timeoutMs }) as unknown as SubagentRole;
+// ── effectiveTimeout: guards delegate-role auto-widening (seconds) ──
+describe("effectiveTimeout", () => {
+	const role = (tools: string[], timeout?: number): SubagentRole =>
+		({ role: "default", description: "", examples: [], decisionTrigger: "", tools, systemPrompt: "", timeout }) as unknown as SubagentRole;
 
 	test("non-delegate role uses base timeout", () => {
-		assert.equal(effectiveTimeoutMs(role(["read", "grep"]), 600000), 600000);
+		assert.equal(effectiveTimeout(role(["read", "grep"]), 600), 600);
 	});
 	test("delegate role doubles base when no explicit timeout", () => {
-		assert.equal(effectiveTimeoutMs(role(["read", "delegate"]), 600000), 1200000);
+		assert.equal(effectiveTimeout(role(["read", "delegate"]), 600), 1200);
 	});
-	test("explicit roleDef.timeoutMs is always honored (no widening)", () => {
-		assert.equal(effectiveTimeoutMs(role(["read", "delegate"], 300000), 600000), 300000);
+	test("explicit roleDef.timeout is always honored (no widening)", () => {
+		assert.equal(effectiveTimeout(role(["read", "delegate"], 300), 600), 300);
 	});
 	test("explicit timeout on non-delegate also honored", () => {
-		assert.equal(effectiveTimeoutMs(role(["read"]), 600000), 600000);
+		assert.equal(effectiveTimeout(role(["read"]), 600), 600);
 	});
 });
 
@@ -250,3 +251,28 @@ describe("formatTokens", () => {
 		assert.equal(formatTokens(1000000), "1.0M");
 	});
 });
+
+// ── elapsedSeconds: live/terminal time derivation ──
+describe("elapsedSeconds", () => {
+	test("terminal state: rounds elapsedMs to whole seconds", () => {
+		assert.equal(elapsedSeconds({ exitCode: 0, elapsedMs: 12345 }), 12);
+		assert.equal(elapsedSeconds({ exitCode: 0, elapsedMs: 400 }), 0);
+		assert.equal(elapsedSeconds({ exitCode: 1, elapsedMs: 59999 }), 60);
+	});
+	test("terminal state without elapsedMs -> undefined", () => {
+		assert.equal(elapsedSeconds({ exitCode: 0 }), undefined);
+	});
+	test("queued (running sentinel, no startTime) -> undefined", () => {
+		assert.equal(elapsedSeconds({ exitCode: -1 }), undefined);
+	});
+	test("running: live seconds from startTime (within ~1s drift)", () => {
+		const start = Date.now() - 3500;
+		const s = elapsedSeconds({ exitCode: -1, startTime: start });
+		assert.ok(s !== undefined, "should be defined while running");
+		assert.ok(s >= 3 && s <= 4, `expected ~3s, got ${s}`);
+	});
+	test("running: clamps negative drift (future startTime) to 0", () => {
+		const start = Date.now() + 10000; // 10s in the future
+		assert.equal(elapsedSeconds({ exitCode: -1, startTime: start }), 0);
+	});
+});

package/src/utils.ts

@@ -31,6 +31,28 @@ export function formatUsageStats(usage: SubagentResult["usage"], model?: string)
 	return parts.join(" ");
 }
 
+/**
+ * 计算用于展示的运行耗时（秒）。
+ * - 运行中（exitCode === -1 且有 startTime）：基于墙钟实时计算；
+ * - 终态（exitCode !== -1 且有 elapsedMs）：冻结值；
+ * - queued 或字段缺失：undefined（调用方应跳过耗时展示）。
+ *
+ * 用结构子集而非 SubagentResult，便于在无需引入完整类型的纯工具上下文中复用与测试。
+ */
+export function elapsedSeconds(r: {
+	exitCode: number;
+	startTime?: number;
+	elapsedMs?: number;
+}): number | undefined {
+	if (r.exitCode === -1 && typeof r.startTime === "number") {
+		return Math.max(0, Math.round((Date.now() - r.startTime) / 1000));
+	}
+	if (r.exitCode !== -1 && typeof r.elapsedMs === "number") {
+		return Math.round(r.elapsedMs / 1000);
+	}
+	return undefined;
+}
+
 export type DisplayItem =
 	| { type: "toolCall"; name: string; args: Record<string, any>; status?: ToolStatus }
 	| { type: "thinking"; status?: ToolStatus };
@@ -238,14 +260,15 @@ export class AsyncSemaphore {
 /**
  * Effective per-role timeout. Roles that can `delegate` need headroom for
  * nested runs to complete, so when no explicit per-role timeout is set we
- * double the base. An explicit roleDef.timeoutMs is always honored as-is.
+ * double the base. An explicit roleDef.timeout (seconds) is always honored as-is.
+ * All inputs/outputs are in SECONDS — convert to ms at the spawn boundary.
  */
-export function effectiveTimeoutMs(roleDef: SubagentRole, baseTimeoutMs: number): number {
+export function effectiveTimeout(roleDef: SubagentRole, baseTimeoutSec: number): number {
 	const canDelegate = (roleDef.tools ?? []).includes("delegate");
-	if (canDelegate && roleDef.timeoutMs == null) {
-		return baseTimeoutMs * 2;
+	if (canDelegate && roleDef.timeout == null) {
+		return baseTimeoutSec * 2;
 	}
-	return roleDef.timeoutMs ?? baseTimeoutMs;
+	return roleDef.timeout ?? baseTimeoutSec;
 }
 
 // ── Output truncation ────────────────────────────────────────