pi-subagents 0.3.1 → 0.3.3

package/chain-execution.ts

@@ -7,7 +7,7 @@ import * as path from "node:path";
 import type { AgentToolResult } from "@mariozechner/pi-agent-core";
 import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
 import type { AgentConfig } from "./agents.js";
-import { ChainClarifyComponent, type ChainClarifyResult, type BehaviorOverride } from "./chain-clarify.js";
+import { ChainClarifyComponent, type ChainClarifyResult, type BehaviorOverride, type ModelInfo } from "./chain-clarify.js";
 import {
 	resolveChainTemplates,
 	createChainDir,
@@ -36,6 +36,28 @@ import {
 	MAX_CONCURRENCY,
 } from "./types.js";
 
+/** Resolve a model name to its full provider/model format */
+function resolveModelFullId(modelName: string | undefined, availableModels: ModelInfo[]): string | undefined {
+	if (!modelName) return undefined;
+	// If already in provider/model format, return as-is
+	if (modelName.includes("/")) return modelName;
+	
+	// Handle thinking level suffixes (e.g., "claude-sonnet-4-5:high")
+	// Strip the suffix for lookup, then add it back
+	const colonIdx = modelName.lastIndexOf(":");
+	const baseModel = colonIdx !== -1 ? modelName.substring(0, colonIdx) : modelName;
+	const thinkingSuffix = colonIdx !== -1 ? modelName.substring(colonIdx) : "";
+	
+	// Look up base model in available models to find provider
+	const match = availableModels.find(m => m.id === baseModel);
+	if (match) {
+		return thinkingSuffix ? `${match.fullId}${thinkingSuffix}` : match.fullId;
+	}
+	
+	// Fallback: return as-is
+	return modelName;
+}
+
 export interface ChainExecutionParams {
 	chain: ChainStep[];
 	agents: AgentConfig[];
@@ -110,6 +132,13 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 	// Behavior overrides from TUI (set if TUI is shown, undefined otherwise)
 	let tuiBehaviorOverrides: (BehaviorOverride | undefined)[] | undefined;
 
+	// Get available models for model resolution (used in TUI and execution)
+	const availableModels: ModelInfo[] = ctx.modelRegistry.getAvailable().map((m) => ({
+		provider: m.provider,
+		id: m.id,
+		fullId: `${m.provider}/${m.id}`,
+	}));
+
 	if (shouldClarify) {
 		// Sequential-only chain: use existing TUI
 		const seqSteps = chainSteps as SequentialStep[];
@@ -154,6 +183,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					originalTask,
 					chainDir,
 					resolvedBehaviors,
+					availableModels,
 					done,
 				),
 			{
@@ -227,18 +257,31 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 						} as SingleResult;
 					}
 
-					// Build task string
+					// Resolve behavior for this parallel task
+					const behavior = parallelBehaviors[taskIndex]!;
+
+					// Build chain instructions (prefix goes BEFORE task, suffix goes AFTER)
 					const taskTemplate = parallelTemplates[taskIndex] ?? "{previous}";
 					const templateHasPrevious = taskTemplate.includes("{previous}");
+					const { prefix, suffix } = buildChainInstructions(
+						behavior, 
+						chainDir, 
+						false, // parallel tasks don't create progress (pre-created above)
+						templateHasPrevious ? undefined : prev
+					);
+
+					// Build task string with variable substitution
 					let taskStr = taskTemplate;
 					taskStr = taskStr.replace(/\{task\}/g, originalTask);
 					taskStr = taskStr.replace(/\{previous\}/g, prev);
 					taskStr = taskStr.replace(/\{chain_dir\}/g, chainDir);
 
-					// Add chain instructions (include previous summary only if not already in template)
-					const behavior = parallelBehaviors[taskIndex]!;
-					// For parallel, no single "first progress" - each manages independently
-					taskStr += buildChainInstructions(behavior, chainDir, false, templateHasPrevious ? undefined : prev);
+					// Assemble final task: prefix (READ/WRITE instructions) + task + suffix
+					taskStr = prefix + taskStr + suffix;
+
+					// Resolve model to full provider/model format for consistent display
+					const taskAgentConfig = agents.find((a) => a.name === task.agent);
+					const effectiveModel = resolveModelFullId(taskAgentConfig?.model, availableModels);
 
 					const r = await runSync(ctx.cwd, agents, task.agent, taskStr, {
 						cwd: task.cwd ?? cwd,
@@ -249,19 +292,24 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 						share: shareEnabled,
 						artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
 						artifactConfig,
+						modelOverride: effectiveModel,
 						onUpdate: onUpdate
-							? (p) =>
+							? (p) => {
+									// Use concat instead of spread for better performance
+									const stepResults = p.details?.results || [];
+									const stepProgress = p.details?.progress || [];
 									onUpdate({
 										...p,
 										details: {
 											mode: "chain",
-											results: [...results, ...(p.details?.results || [])],
-											progress: [...allProgress, ...(p.details?.progress || [])],
+											results: results.concat(stepResults),
+											progress: allProgress.concat(stepProgress),
 											chainAgents,
 											totalSteps,
 											currentStepIndex: stepIndex,
 										},
-									})
+									});
+								}
 							: undefined,
 					});
 
@@ -336,14 +384,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				};
 			}
 
-			// Build task string (check if template has {previous} before replacement)
-			const templateHasPrevious = stepTemplate.includes("{previous}");
-			let stepTask = stepTemplate;
-			stepTask = stepTask.replace(/\{task\}/g, originalTask);
-			stepTask = stepTask.replace(/\{previous\}/g, prev);
-			stepTask = stepTask.replace(/\{chain_dir\}/g, chainDir);
-
-			// Resolve behavior (TUI overrides take precedence over step config)
+			// Resolve behavior first (TUI overrides take precedence over step config)
 			const tuiOverride = tuiBehaviorOverrides?.[stepIndex];
 			const stepOverride: StepOverrides = {
 				output: tuiOverride?.output !== undefined ? tuiOverride.output : seqStep.output,
@@ -358,8 +399,26 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				progressCreated = true;
 			}
 
-			// Add chain instructions (include previous summary only if not already in template)
-			stepTask += buildChainInstructions(behavior, chainDir, isFirstProgress, templateHasPrevious ? undefined : prev);
+			// Build chain instructions (prefix goes BEFORE task, suffix goes AFTER)
+			const templateHasPrevious = stepTemplate.includes("{previous}");
+			const { prefix, suffix } = buildChainInstructions(
+				behavior, 
+				chainDir, 
+				isFirstProgress, 
+				templateHasPrevious ? undefined : prev
+			);
+
+			// Build task string with variable substitution
+			let stepTask = stepTemplate;
+			stepTask = stepTask.replace(/\{task\}/g, originalTask);
+			stepTask = stepTask.replace(/\{previous\}/g, prev);
+			stepTask = stepTask.replace(/\{chain_dir\}/g, chainDir);
+
+			// Assemble final task: prefix (READ/WRITE instructions) + task + suffix (progress, previous summary)
+			stepTask = prefix + stepTask + suffix;
+
+			// Resolve model: TUI override (already full format) or agent's model resolved to full format
+			const effectiveModel = tuiOverride?.model ?? resolveModelFullId(agentConfig.model, availableModels);
 
 			// Run step
 			const r = await runSync(ctx.cwd, agents, seqStep.agent, stepTask, {
@@ -371,19 +430,24 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				share: shareEnabled,
 				artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
 				artifactConfig,
+				modelOverride: effectiveModel,
 				onUpdate: onUpdate
-					? (p) =>
+					? (p) => {
+							// Use concat instead of spread for better performance
+							const stepResults = p.details?.results || [];
+							const stepProgress = p.details?.progress || [];
 							onUpdate({
 								...p,
 								details: {
 									mode: "chain",
-									results: [...results, ...(p.details?.results || [])],
-									progress: [...allProgress, ...(p.details?.progress || [])],
+									results: results.concat(stepResults),
+									progress: allProgress.concat(stepProgress),
 									chainAgents,
 									totalSteps,
 									currentStepIndex: stepIndex,
 								},
-							})
+							});
+						}
 					: undefined,
 			});
 
@@ -392,6 +456,27 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 			if (r.progress) allProgress.push(r.progress);
 			if (r.artifactPaths) allArtifactPaths.push(r.artifactPaths);
 
+			// Validate expected output file was created
+			if (behavior.output && r.exitCode === 0) {
+				try {
+					const expectedPath = behavior.output.startsWith("/") 
+						? behavior.output 
+						: path.join(chainDir, behavior.output);
+					if (!fs.existsSync(expectedPath)) {
+						// Look for similar files that might have been created instead
+						const dirFiles = fs.readdirSync(chainDir);
+						const mdFiles = dirFiles.filter(f => f.endsWith(".md") && f !== "progress.md");
+						const warning = mdFiles.length > 0 
+							? `Agent wrote to different file(s): ${mdFiles.join(", ")} instead of ${behavior.output}`
+							: `Agent did not create expected output file: ${behavior.output}`;
+						// Add warning to result but don't fail
+						r.error = r.error ? `${r.error}\n⚠️ ${warning}` : `⚠️ ${warning}`;
+					}
+				} catch {
+					// Ignore validation errors - this is just a diagnostic
+				}
+			}
+
 			// On failure, leave chain_dir for debugging
 			if (r.exitCode !== 0) {
 				const summary = buildChainSummary(chainSteps, results, chainDir, "failed", {

package/execution.ts

@@ -43,7 +43,7 @@ export async function runSync(
 	task: string,
 	options: RunSyncOptions,
 ): Promise<SingleResult> {
-	const { cwd, signal, onUpdate, maxOutput, artifactsDir, artifactConfig, runId, index } = options;
+	const { cwd, signal, onUpdate, maxOutput, artifactsDir, artifactConfig, runId, index, modelOverride } = options;
 	const agent = agents.find((a) => a.name === agentName);
 	if (!agent) {
 		return {
@@ -68,7 +68,9 @@ export async function runSync(
 		} catch {}
 		args.push("--session-dir", options.sessionDir);
 	}
-	if (agent.model) args.push("--model", agent.model);
+	// Use model override if provided, otherwise use agent's default model
+	const effectiveModel = modelOverride ?? agent.model;
+	if (effectiveModel) args.push("--model", effectiveModel);
 	if (agent.tools?.length) {
 		const builtinTools: string[] = [];
 		const extensionPaths: string[] = [];
@@ -101,6 +103,7 @@ export async function runSync(
 		exitCode: 0,
 		messages: [],
 		usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
+		model: effectiveModel,  // Initialize with the model we're using
 	};
 
 	const progress: AgentProgress = {
@@ -132,6 +135,50 @@ export async function runSync(
 		const proc = spawn("pi", args, { cwd: cwd ?? runtimeCwd, stdio: ["ignore", "pipe", "pipe"] });
 		let buf = "";
 
+		// Throttled update mechanism - consolidates all updates
+		let lastUpdateTime = 0;
+		let updatePending = false;
+		let pendingTimer: ReturnType<typeof setTimeout> | null = null;
+		let processClosed = false;
+		const UPDATE_THROTTLE_MS = 50; // Reduced from 75ms for faster responsiveness
+
+		const scheduleUpdate = () => {
+			if (!onUpdate || processClosed) return;
+			const now = Date.now();
+			const elapsed = now - lastUpdateTime;
+
+			if (elapsed >= UPDATE_THROTTLE_MS) {
+				// Enough time passed, update immediately
+				// Clear any pending timer to avoid double-updates
+				if (pendingTimer) {
+					clearTimeout(pendingTimer);
+					pendingTimer = null;
+				}
+				lastUpdateTime = now;
+				updatePending = false;
+				progress.durationMs = now - startTime;
+				onUpdate({
+					content: [{ type: "text", text: getFinalOutput(result.messages) || "(running...)" }],
+					details: { mode: "single", results: [result], progress: [progress] },
+				});
+			} else if (!updatePending) {
+				// Schedule update for later
+				updatePending = true;
+				pendingTimer = setTimeout(() => {
+					pendingTimer = null;
+					if (updatePending && !processClosed) {
+						updatePending = false;
+						lastUpdateTime = Date.now();
+						progress.durationMs = Date.now() - startTime;
+						onUpdate({
+							content: [{ type: "text", text: getFinalOutput(result.messages) || "(running...)" }],
+							details: { mode: "single", results: [result], progress: [progress] },
+						});
+					}
+				}, UPDATE_THROTTLE_MS - elapsed);
+			}
+		};
+
 		const processLine = (line: string) => {
 			if (!line.trim()) return;
 			jsonlLines.push(line);
@@ -144,11 +191,9 @@ export async function runSync(
 					progress.toolCount++;
 					progress.currentTool = evt.toolName;
 					progress.currentToolArgs = extractToolArgsPreview((evt.args || {}) as Record<string, unknown>);
-					if (onUpdate)
-						onUpdate({
-							content: [{ type: "text", text: getFinalOutput(result.messages) || "(running...)" }],
-							details: { mode: "single", results: [result], progress: [progress] },
-						});
+					// Tool start is important - update immediately by forcing throttle reset
+					lastUpdateTime = 0;
+					scheduleUpdate();
 				}
 
 				if (evt.type === "tool_execution_end") {
@@ -164,11 +209,7 @@ export async function runSync(
 					}
 					progress.currentTool = undefined;
 					progress.currentToolArgs = undefined;
-					if (onUpdate)
-						onUpdate({
-							content: [{ type: "text", text: getFinalOutput(result.messages) || "(running...)" }],
-							details: { mode: "single", results: [result], progress: [progress] },
-						});
+					scheduleUpdate();
 				}
 
 				if (evt.type === "message_end" && evt.message) {
@@ -193,15 +234,14 @@ export async function runSync(
 								.split("\n")
 								.filter((l) => l.trim())
 								.slice(-10);
-							// Append to existing recentOutput (keep last 50 total)
-							progress.recentOutput = [...progress.recentOutput, ...lines].slice(-50);
+							// Append to existing recentOutput (keep last 50 total) - mutate in place for efficiency
+							progress.recentOutput.push(...lines);
+							if (progress.recentOutput.length > 50) {
+								progress.recentOutput.splice(0, progress.recentOutput.length - 50);
+							}
 						}
 					}
-					if (onUpdate)
-						onUpdate({
-							content: [{ type: "text", text: getFinalOutput(result.messages) || "(running...)" }],
-							details: { mode: "single", results: [result], progress: [progress] },
-						});
+					scheduleUpdate();
 				}
 				if (evt.type === "tool_result_end" && evt.message) {
 					result.messages.push(evt.message);
@@ -212,21 +252,18 @@ export async function runSync(
 							.split("\n")
 							.filter((l) => l.trim())
 							.slice(-10);
-						// Append to existing recentOutput (keep last 50 total)
-						progress.recentOutput = [...progress.recentOutput, ...toolLines].slice(-50);
+						// Append to existing recentOutput (keep last 50 total) - mutate in place for efficiency
+						progress.recentOutput.push(...toolLines);
+						if (progress.recentOutput.length > 50) {
+							progress.recentOutput.splice(0, progress.recentOutput.length - 50);
+						}
 					}
-					if (onUpdate)
-						onUpdate({
-							content: [{ type: "text", text: getFinalOutput(result.messages) || "(running...)" }],
-							details: { mode: "single", results: [result], progress: [progress] },
-						});
+					scheduleUpdate();
 				}
 			} catch {}
 		};
 
 		let stderrBuf = "";
-		let lastUpdateTime = 0;
-		const UPDATE_THROTTLE_MS = 75;
 
 		proc.stdout.on("data", (d) => {
 			buf += d.toString();
@@ -234,21 +271,18 @@ export async function runSync(
 			buf = lines.pop() || "";
 			lines.forEach(processLine);
 
-			// Throttled periodic update for smoother progress display
-			const now = Date.now();
-			if (onUpdate && now - lastUpdateTime > UPDATE_THROTTLE_MS) {
-				lastUpdateTime = now;
-				progress.durationMs = now - startTime;
-				onUpdate({
-					content: [{ type: "text", text: getFinalOutput(result.messages) || "(running...)" }],
-					details: { mode: "single", results: [result], progress: [progress] },
-				});
-			}
+			// Also schedule an update on data received (handles streaming output)
+			scheduleUpdate();
 		});
 		proc.stderr.on("data", (d) => {
 			stderrBuf += d.toString();
 		});
 		proc.on("close", (code) => {
+			processClosed = true;
+			if (pendingTimer) {
+				clearTimeout(pendingTimer);
+				pendingTimer = null;
+			}
 			if (buf.trim()) processLine(buf);
 			if (code !== 0 && stderrBuf.trim() && !result.error) {
 				result.error = stderrBuf.trim();

package/index.ts

@@ -73,6 +73,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	let baseCwd = process.cwd();
 	let currentSessionId: string | null = null;
 	const asyncJobs = new Map<string, AsyncJobState>();
+	const cleanupTimers = new Map<string, ReturnType<typeof setTimeout>>(); // Track cleanup timeouts
 	let lastUiContext: ExtensionContext | null = null;
 	let poller: NodeJS.Timeout | null = null;
 
@@ -88,6 +89,10 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			}
 
 			for (const job of asyncJobs.values()) {
+				// Skip status reads for finished jobs - they won't change
+				if (job.status === "complete" || job.status === "failed") {
+					continue;
+				}
 				const status = readStatus(job.asyncDir);
 				if (status) {
 					job.status = status.state;
@@ -139,9 +144,20 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		label: "Subagent",
 		description: `Delegate to subagents. Use exactly ONE mode:
 • SINGLE: { agent, task } - one task
-• CHAIN: { chain: [{agent:"scout"}, {agent:"planner"}] } - sequential, {previous} passes output
-• PARALLEL: { tasks: [{agent,task}, ...] } - concurrent
-For "scout → planner" or multi-step flows, use chain (not multiple single calls).`,
+• CHAIN: { chain: [{agent:"scout"}, {agent:"planner"}] } - sequential pipeline
+• PARALLEL: { tasks: [{agent,task}, ...] } - concurrent execution
+
+CHAIN TEMPLATE VARIABLES (use in task strings):
+• {task} - The original task/request from the user
+• {previous} - Text response from the previous step (empty for first step)
+• {chain_dir} - Shared directory for chain files (e.g., /tmp/pi-chain-runs/abc123/)
+
+CHAIN DATA FLOW:
+1. Each step's text response automatically becomes {previous} for the next step
+2. Steps can also write files to {chain_dir} (via agent's "output" config)
+3. Later steps can read those files (via agent's "reads" config)
+
+Example: { chain: [{agent:"scout", task:"Analyze {task}"}, {agent:"planner", task:"Plan based on {previous}"}] }`,
 		parameters: SubagentParams,
 
 		async execute(_id, params, onUpdate, ctx, signal) {
@@ -589,10 +605,13 @@ For "scout → planner" or multi-step flows, use chain (not multiple single call
 		if (lastUiContext) {
 			renderWidget(lastUiContext, Array.from(asyncJobs.values()));
 		}
-		setTimeout(() => {
+		// Schedule cleanup after 10 seconds (track timer for cleanup on shutdown)
+		const timer = setTimeout(() => {
+			cleanupTimers.delete(asyncId);
 			asyncJobs.delete(asyncId);
 			if (lastUiContext) renderWidget(lastUiContext, Array.from(asyncJobs.values()));
 		}, 10000);
+		cleanupTimers.set(asyncId, timer);
 	});
 
 	pi.on("tool_result", (event, ctx) => {
@@ -608,6 +627,8 @@ For "scout → planner" or multi-step flows, use chain (not multiple single call
 	pi.on("session_start", (_event, ctx) => {
 		baseCwd = ctx.cwd;
 		currentSessionId = ctx.sessionManager.getSessionFile() ?? `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+		for (const timer of cleanupTimers.values()) clearTimeout(timer);
+		cleanupTimers.clear();
 		asyncJobs.clear();
 		if (ctx.hasUI) {
 			lastUiContext = ctx;
@@ -617,6 +638,8 @@ For "scout → planner" or multi-step flows, use chain (not multiple single call
 	pi.on("session_switch", (_event, ctx) => {
 		baseCwd = ctx.cwd;
 		currentSessionId = ctx.sessionManager.getSessionFile() ?? `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+		for (const timer of cleanupTimers.values()) clearTimeout(timer);
+		cleanupTimers.clear();
 		asyncJobs.clear();
 		if (ctx.hasUI) {
 			lastUiContext = ctx;
@@ -626,6 +649,8 @@ For "scout → planner" or multi-step flows, use chain (not multiple single call
 	pi.on("session_branch", (_event, ctx) => {
 		baseCwd = ctx.cwd;
 		currentSessionId = ctx.sessionManager.getSessionFile() ?? `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+		for (const timer of cleanupTimers.values()) clearTimeout(timer);
+		cleanupTimers.clear();
 		asyncJobs.clear();
 		if (ctx.hasUI) {
 			lastUiContext = ctx;
@@ -636,6 +661,11 @@ For "scout → planner" or multi-step flows, use chain (not multiple single call
 		watcher.close();
 		if (poller) clearInterval(poller);
 		poller = null;
+		// Clear all pending cleanup timers
+		for (const timer of cleanupTimers.values()) {
+			clearTimeout(timer);
+		}
+		cleanupTimers.clear();
 		asyncJobs.clear();
 		if (lastUiContext?.hasUI) {
 			lastUiContext.ui.setWidget(WIDGET_KEY, undefined);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",

package/render.ts

@@ -16,21 +16,46 @@ import { getFinalOutput, getDisplayItems, getOutputTail, getLastActivity } from
 
 type Theme = ExtensionContext["ui"]["theme"];
 
+// Track last rendered widget state to avoid no-op re-renders
+let lastWidgetHash = "";
+
+/**
+ * Compute a simple hash of job states for change detection
+ */
+function computeWidgetHash(jobs: AsyncJobState[]): string {
+	return jobs.slice(0, MAX_WIDGET_JOBS).map(job =>
+		`${job.asyncId}:${job.status}:${job.currentStep}:${job.updatedAt}:${job.totalTokens?.total ?? 0}`
+	).join("|");
+}
+
 /**
  * Render the async jobs widget
  */
 export function renderWidget(ctx: ExtensionContext, jobs: AsyncJobState[]): void {
 	if (!ctx.hasUI) return;
 	if (jobs.length === 0) {
-		ctx.ui.setWidget(WIDGET_KEY, undefined);
+		if (lastWidgetHash !== "") {
+			lastWidgetHash = "";
+			ctx.ui.setWidget(WIDGET_KEY, undefined);
+		}
 		return;
 	}
 
+	// Check if anything changed since last render
+	// Always re-render if any displayed job is running (output tail updates constantly)
+	const displayedJobs = jobs.slice(0, MAX_WIDGET_JOBS);
+	const hasRunningJobs = displayedJobs.some(job => job.status === "running");
+	const newHash = computeWidgetHash(jobs);
+	if (!hasRunningJobs && newHash === lastWidgetHash) {
+		return; // Skip re-render, nothing changed
+	}
+	lastWidgetHash = newHash;
+
 	const theme = ctx.ui.theme;
 	const lines: string[] = [];
 	lines.push(theme.fg("accent", "Async subagents"));
 
-	for (const job of jobs.slice(0, MAX_WIDGET_JOBS)) {
+	for (const job of displayedJobs) {
 		const id = job.asyncId.slice(0, 6);
 		const status =
 			job.status === "complete"
@@ -235,9 +260,11 @@ export function renderSubagentResult(
 				? theme.fg("success", "✓")
 				: theme.fg("error", "✗");
 		const stats = rProg ? ` | ${rProg.toolCount} tools, ${formatDuration(rProg.durationMs)}` : "";
+		// Show model if available (full provider/model format)
+		const modelDisplay = r.model ? theme.fg("dim", ` (${r.model})`) : "";
 		const stepHeader = rRunning
-			? `${statusIcon} Step ${i + 1}: ${theme.bold(theme.fg("warning", r.agent))}${stats}`
-			: `${statusIcon} Step ${i + 1}: ${theme.bold(r.agent)}${stats}`;
+			? `${statusIcon} Step ${i + 1}: ${theme.bold(theme.fg("warning", r.agent))}${modelDisplay}${stats}`
+			: `${statusIcon} Step ${i + 1}: ${theme.bold(r.agent)}${modelDisplay}${stats}`;
 		c.addChild(new Text(stepHeader, 0, 0));
 
 		// Task (truncated)

package/schemas.ts

@@ -13,34 +13,36 @@ export const TaskItem = Type.Object({
 // Sequential chain step (single agent)
 export const SequentialStepSchema = Type.Object({
 	agent: Type.String(),
-	task: Type.Optional(Type.String({ description: "Task template. Use {task}, {previous}, {chain_dir}. Required for first step." })),
+	task: Type.Optional(Type.String({ 
+		description: "Task template with variables: {task}=original request, {previous}=prior step's text response, {chain_dir}=shared folder. Required for first step, defaults to '{previous}' for subsequent steps." 
+	})),
 	cwd: Type.Optional(Type.String()),
 	// Chain behavior overrides
 	output: Type.Optional(Type.Union([
 		Type.String(),
 		Type.Boolean(),
-	], { description: "Override output filename (string), or false for text-only" })),
+	], { description: "Output filename to write in {chain_dir} (string), or false to disable file output" })),
 	reads: Type.Optional(Type.Union([
 		Type.Array(Type.String()),
 		Type.Boolean(),
-	], { description: "Override files to read from {chain_dir} (array), or false to disable" })),
-	progress: Type.Optional(Type.Boolean({ description: "Override progress tracking" })),
+	], { description: "Files to read from {chain_dir} before running (array of filenames), or false to disable" })),
+	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
 });
 
 // Parallel task item (within a parallel step)
 export const ParallelTaskSchema = Type.Object({
 	agent: Type.String(),
-	task: Type.Optional(Type.String({ description: "Task template. Defaults to {previous}." })),
+	task: Type.Optional(Type.String({ description: "Task template with {task}, {previous}, {chain_dir} variables. Defaults to {previous}." })),
 	cwd: Type.Optional(Type.String()),
 	output: Type.Optional(Type.Union([
 		Type.String(),
 		Type.Boolean(),
-	], { description: "Override output filename (string), or false for text-only" })),
+	], { description: "Output filename to write in {chain_dir} (string), or false to disable file output" })),
 	reads: Type.Optional(Type.Union([
 		Type.Array(Type.String()),
 		Type.Boolean(),
-	], { description: "Override files to read from {chain_dir} (array), or false to disable" })),
-	progress: Type.Optional(Type.Boolean({ description: "Override progress tracking" })),
+	], { description: "Files to read from {chain_dir} before running (array of filenames), or false to disable" })),
+	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
 });
 
 // Parallel chain step (multiple agents running concurrently)
@@ -64,7 +66,7 @@ export const SubagentParams = Type.Object({
 	agent: Type.Optional(Type.String({ description: "Agent name (SINGLE mode)" })),
 	task: Type.Optional(Type.String({ description: "Task (SINGLE mode)" })),
 	tasks: Type.Optional(Type.Array(TaskItem, { description: "PARALLEL mode: [{agent, task}, ...]" })),
-	chain: Type.Optional(Type.Array(ChainItem, { description: "CHAIN mode: [{agent}, {agent, task:'{previous}'}] - sequential pipeline" })),
+	chain: Type.Optional(Type.Array(ChainItem, { description: "CHAIN mode: sequential pipeline where each step's response becomes {previous} for the next. Use {task}, {previous}, {chain_dir} in task templates." })),
 	async: Type.Optional(Type.Boolean({ description: "Run in background (default: false, or per config)" })),
 	agentScope: Type.Optional(Type.String({ description: "Agent discovery scope: 'user', 'project', or 'both' (default: 'user')" })),
 	cwd: Type.Optional(Type.String()),