pi-subagents 0.3.2 → 0.4.1

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,6 +292,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 						share: shareEnabled,
 						artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
 						artifactConfig,
+						modelOverride: effectiveModel,
 						onUpdate: onUpdate
 							? (p) => {
 									// Use concat instead of spread for better performance
@@ -340,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,
@@ -362,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, {
@@ -375,6 +430,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				share: shareEnabled,
 				artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
 				artifactConfig,
+				modelOverride: effectiveModel,
 				onUpdate: onUpdate
 					? (p) => {
 							// Use concat instead of spread for better performance
@@ -400,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 = {

package/index.ts

@@ -19,7 +19,8 @@ import * as path from "node:path";
 import { type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
 import { type AgentConfig, type AgentScope, discoverAgents } from "./agents.js";
-import { cleanupOldChainDirs, getStepAgents, isParallelStep, type ChainStep, type SequentialStep } from "./settings.js";
+import { cleanupOldChainDirs, getStepAgents, isParallelStep, resolveStepBehavior, type ChainStep, type SequentialStep } from "./settings.js";
+import { ChainClarifyComponent, type ChainClarifyResult, type ModelInfo } from "./chain-clarify.js";
 import { cleanupOldArtifacts, getArtifactsDir } from "./artifacts.js";
 import {
 	type AgentProgress,
@@ -144,9 +145,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) {
@@ -177,8 +189,13 @@ For "scout → planner" or multi-step flows, use chain (not multiple single call
 			const requestedAsync = params.async ?? asyncByDefault;
 			const parallelDowngraded = hasTasks && requestedAsync;
 			// clarify implies sync mode (TUI is blocking)
-			// If user requested async without explicit clarify: false, downgrade to sync for chains
-			const effectiveAsync = requestedAsync && !hasTasks && (hasChain ? params.clarify === false : true);
+			// - Chains default to TUI (clarify: true), so async requires explicit clarify: false
+			// - Single defaults to no TUI, so async is allowed unless clarify: true is passed
+			const effectiveAsync = requestedAsync && !hasTasks && (
+				hasChain 
+					? params.clarify === false    // chains: only async if TUI explicitly disabled
+					: params.clarify !== true     // single: async unless TUI explicitly enabled
+			);
 
 			const artifactConfig: ArtifactConfig = {
 				...DEFAULT_ARTIFACT_CONFIG,
@@ -325,14 +342,74 @@ For "scout → planner" or multi-step flows, use chain (not multiple single call
 			}
 
 			if (hasTasks && params.tasks) {
+				// MAX_PARALLEL check first (fail fast before TUI)
 				if (params.tasks.length > MAX_PARALLEL)
 					return {
 						content: [{ type: "text", text: `Max ${MAX_PARALLEL} tasks` }],
 						isError: true,
-						details: { mode: "single" as const, results: [] },
+						details: { mode: "parallel" as const, results: [] },
 					};
+
+				// Validate all agents exist
+				const agentConfigs: AgentConfig[] = [];
+				for (const t of params.tasks) {
+					const config = agents.find(a => a.name === t.agent);
+					if (!config) {
+						return {
+							content: [{ type: "text", text: `Unknown agent: ${t.agent}` }],
+							isError: true,
+							details: { mode: "parallel" as const, results: [] },
+						};
+					}
+					agentConfigs.push(config);
+				}
+
+				// Mutable copies for TUI modifications
+				let tasks = params.tasks.map(t => t.task);
+				const modelOverrides: (string | undefined)[] = new Array(params.tasks.length).fill(undefined);
+
+				// Show clarify TUI if requested
+				if (params.clarify === true && ctx.hasUI) {
+					// Get available models (same pattern as chain-execution.ts)
+					const availableModels: ModelInfo[] = ctx.modelRegistry.getAvailable().map((m) => ({
+						provider: m.provider,
+						id: m.id,
+						fullId: `${m.provider}/${m.id}`,
+					}));
+
+					const behaviors = agentConfigs.map(c => resolveStepBehavior(c, {}));
+
+					const result = await ctx.ui.custom<ChainClarifyResult>(
+						(tui, theme, _kb, done) =>
+							new ChainClarifyComponent(
+								tui, theme,
+								agentConfigs,
+								tasks,
+								'',          // no originalTask for parallel (each task is independent)
+								undefined,   // no chainDir for parallel
+								behaviors,
+								availableModels,
+								done,
+								'parallel',  // mode
+							),
+						{ overlay: true, overlayOptions: { anchor: 'center', width: 84, maxHeight: '80%' } },
+					);
+
+					if (!result || !result.confirmed) {
+						return { content: [{ type: 'text', text: 'Cancelled' }], details: { mode: 'parallel', results: [] } };
+					}
+
+					// Apply TUI overrides
+					tasks = result.templates;
+					for (let i = 0; i < result.behaviorOverrides.length; i++) {
+						const override = result.behaviorOverrides[i];
+						if (override?.model) modelOverrides[i] = override.model;
+					}
+				}
+
+				// Execute with overrides (tasks array has same length as params.tasks)
 				const results = await mapConcurrent(params.tasks, MAX_CONCURRENCY, async (t, i) =>
-					runSync(ctx.cwd, agents, t.agent, t.task, {
+					runSync(ctx.cwd, agents, t.agent, tasks[i]!, {
 						cwd: t.cwd ?? params.cwd,
 						signal,
 						runId,
@@ -342,6 +419,7 @@ For "scout → planner" or multi-step flows, use chain (not multiple single call
 						artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
 						artifactConfig,
 						maxOutput: params.maxOutput,
+						modelOverride: modelOverrides[i],
 					}),
 				);
 
@@ -366,24 +444,67 @@ For "scout → planner" or multi-step flows, use chain (not multiple single call
 			if (hasSingle) {
 				// Look up agent config for output handling
 				const agentConfig = agents.find((a) => a.name === params.agent);
-				// Note: runSync already handles unknown agent, but we need config for output
+				if (!agentConfig) {
+					return {
+						content: [{ type: 'text', text: `Unknown agent: ${params.agent}` }],
+						isError: true,
+						details: { mode: 'single', results: [] },
+					};
+				}
 
 				let task = params.task!;
-				let outputPath: string | undefined;
+				let modelOverride: string | undefined;
+				// Normalize output: true means "use default" (same as undefined), false means disable
+				const rawOutput = params.output !== undefined ? params.output : agentConfig.output;
+				let effectiveOutput: string | false | undefined = rawOutput === true ? agentConfig.output : rawOutput;
+
+				// Show clarify TUI if requested
+				if (params.clarify === true && ctx.hasUI) {
+					// Get available models (same pattern as chain-execution.ts)
+					const availableModels: ModelInfo[] = ctx.modelRegistry.getAvailable().map((m) => ({
+						provider: m.provider,
+						id: m.id,
+						fullId: `${m.provider}/${m.id}`,
+					}));
+
+					const behavior = resolveStepBehavior(agentConfig, { output: effectiveOutput });
+
+					const result = await ctx.ui.custom<ChainClarifyResult>(
+						(tui, theme, _kb, done) =>
+							new ChainClarifyComponent(
+								tui, theme,
+								[agentConfig],
+								[task],
+								task,
+								undefined,  // no chainDir for single
+								[behavior],
+								availableModels,
+								done,
+								'single',   // mode
+							),
+						{ overlay: true, overlayOptions: { anchor: 'center', width: 84, maxHeight: '80%' } },
+					);
+
+					if (!result || !result.confirmed) {
+						return { content: [{ type: 'text', text: 'Cancelled' }], details: { mode: 'single', results: [] } };
+					}
 
-				// Check if agent has output and it's not disabled
-				if (agentConfig) {
-					const effectiveOutput =
-						params.output !== undefined ? params.output : agentConfig.output;
+					// Apply TUI overrides
+					task = result.templates[0]!;
+					const override = result.behaviorOverrides[0];
+					if (override?.model) modelOverride = override.model;
+					if (override?.output !== undefined) effectiveOutput = override.output;
+				}
 
-					if (effectiveOutput && effectiveOutput !== false) {
-						const outputDir = `/tmp/pi-${agentConfig.name}-${runId}`;
-						fs.mkdirSync(outputDir, { recursive: true });
-						outputPath = `${outputDir}/${effectiveOutput}`;
+				// Compute output path at runtime (uses effectiveOutput which may be TUI-modified)
+				let outputPath: string | undefined;
+				if (effectiveOutput && effectiveOutput !== false) {
+					const outputDir = `/tmp/pi-${agentConfig.name}-${runId}`;
+					fs.mkdirSync(outputDir, { recursive: true });
+					outputPath = `${outputDir}/${effectiveOutput}`;
 
-						// Inject output instruction into task
-						task += `\n\n---\n**Output:** Write your findings to: ${outputPath}`;
-					}
+					// Inject output instruction into task
+					task += `\n\n---\n**Output:** Write your findings to: ${outputPath}`;
 				}
 
 				const r = await runSync(ctx.cwd, agents, params.agent!, task, {
@@ -396,6 +517,7 @@ For "scout → planner" or multi-step flows, use chain (not multiple single call
 					artifactConfig,
 					maxOutput: params.maxOutput,
 					onUpdate,
+					modelOverride,
 				});
 
 				if (r.progress) allProgress.push(r.progress);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",
@@ -13,6 +13,7 @@
     "url": "https://github.com/nicobailon/pi-subagents/issues"
   },
   "keywords": [
+    "pi-package",
     "pi",
     "pi-coding-agent",
     "subagents",

package/render.ts

@@ -260,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()),
@@ -75,8 +77,8 @@ export const SubagentParams = Type.Object({
 	sessionDir: Type.Optional(
 		Type.String({ description: "Directory to store session logs (default: temp; enables sessions even if share=false)" }),
 	),
-	// Chain clarification TUI
-	clarify: Type.Optional(Type.Boolean({ description: "Show TUI to clarify chain templates (default: true for chains). Implies sync mode." })),
+	// Clarification TUI
+	clarify: Type.Optional(Type.Boolean({ description: "Show TUI to preview/edit before execution (default: true for chains, false for single/parallel). Implies sync mode." })),
 	// Solo agent output override
 	output: Type.Optional(Type.Union([
 		Type.String(),

package/settings.ts

@@ -198,42 +198,46 @@ export function buildChainInstructions(
 	chainDir: string,
 	isFirstProgressAgent: boolean,
 	previousSummary?: string,
-): string {
-	const instructions: string[] = [];
+): { prefix: string; suffix: string } {
+	const prefixParts: string[] = [];
+	const suffixParts: string[] = [];
 
-	// Include previous step's summary if available (prose output from prior agent)
-	if (previousSummary && previousSummary.trim()) {
-		instructions.push(`Previous step summary:\n\n${previousSummary.trim()}`);
-	}
-
-	// Reads (supports both absolute and relative paths)
+	// READS - prepend to override any hardcoded filenames in task text
 	if (behavior.reads && behavior.reads.length > 0) {
-		const files = behavior.reads.map((f) => resolveChainPath(f, chainDir)).join(", ");
-		instructions.push(`Read these files: ${files}`);
+		const files = behavior.reads.map((f) => resolveChainPath(f, chainDir));
+		prefixParts.push(`[Read from: ${files.join(", ")}]`);
 	}
 
-	// Output (supports both absolute and relative paths)
+	// OUTPUT - prepend so agent knows where to write
 	if (behavior.output) {
 		const outputPath = resolveChainPath(behavior.output, chainDir);
-		instructions.push(`Write your output to: ${outputPath}`);
+		prefixParts.push(`[Write to: ${outputPath}]`);
 	}
 
-	// Progress
+	// Progress instructions in suffix (less critical)
 	if (behavior.progress) {
 		const progressPath = `${chainDir}/progress.md`;
 		if (isFirstProgressAgent) {
-			instructions.push(`Create and maintain: ${progressPath}`);
-			instructions.push("Format: Status, Tasks (checkboxes), Files Changed, Notes");
+			suffixParts.push(`Create and maintain progress at: ${progressPath}`);
 		} else {
-			instructions.push(`Read and update: ${progressPath}`);
+			suffixParts.push(`Update progress at: ${progressPath}`);
 		}
 	}
 
-	if (instructions.length === 0) return "";
+	// Include previous step's summary in suffix if available
+	if (previousSummary && previousSummary.trim()) {
+		suffixParts.push(`Previous step output:\n${previousSummary.trim()}`);
+	}
+
+	const prefix = prefixParts.length > 0 
+		? prefixParts.join("\n") + "\n\n"
+		: "";
+	
+	const suffix = suffixParts.length > 0
+		? "\n\n---\n" + suffixParts.join("\n")
+		: "";
 
-	return (
-		"\n\n---\n**Chain Instructions:**\n" + instructions.map((i) => `- ${i}`).join("\n")
-	);
+	return { prefix, suffix };
 }
 
 // =============================================================================

package/types.ts

@@ -193,6 +193,8 @@ export interface RunSyncOptions {
 	index?: number;
 	sessionDir?: string;
 	share?: boolean;
+	/** Override the agent's default model (format: "provider/id" or just "id") */
+	modelOverride?: string;
 }
 
 export interface ExtensionConfig {