pi-subagents 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## [0.3.3] - 2026-01-25
+
+### Added
+- **Thinking level selector in chain TUI** - Press `[t]` to set thinking level for any step
+  - Options: off, minimal, low, medium, high, xhigh (ultrathink)
+  - Appends to model as suffix (e.g., `anthropic/claude-sonnet-4-5:high`)
+  - Pre-selects current thinking level if already set
+- **Model selector in chain TUI** - Press `[m]` to select a different model for any step
+  - Fuzzy search through all available models
+  - Shows current model with ✓ indicator
+  - Provider/model format (e.g., `anthropic/claude-haiku-4-5`)
+  - Override indicator (✎) when model differs from agent default
+- **Model visibility in chain execution** - Shows which model each step is using
+  - Display format: `Step 1: scout (claude-haiku-4-5) | 3 tools, 16.8s`
+  - Model shown in both running and completed steps
+- **Auto-propagate output changes to reads** - When you change a step's output filename,
+  downstream steps that read from it are automatically updated to use the new filename
+  - Maintains chain dependencies without manual updates
+  - Example: Change scout's output from `context.md` to `summary.md`, planner's reads updates automatically
+
+### Changed
+- **Progress is now chain-level** - `[p]` toggles progress for ALL steps at once
+  - Progress setting shown at chain level (not per-step)
+  - Chains share a single progress.md, so chain-wide toggle is more intuitive
+- **Clearer output/writes labeling** - Renamed `output:` to `writes:` to clarify it's a file
+  - Hotkey changed from `[o]` to `[w]` for consistency
+- **{previous} data flow indicator** - Shows on the PRODUCING step (not receiving):
+  - `↳ response → {previous}` appears after scout's reads line
+  - Only shows when next step's template uses `{previous}`
+  - Clearer mental model: output flows DOWN the chain
+- Chain TUI footer updated: `[e]dit [m]odel [t]hinking [w]rites [r]eads [p]rogress`
+
+### Fixed
+- **Chain READ/WRITE instructions now prepended** - Instructions restructured:
+  - `[Read from: /path/file.md]` and `[Write to: /path/file.md]` prepended BEFORE task
+  - Overrides any hardcoded filenames in task text from parent agent
+  - Previously: instructions were appended at end and could be overlooked
+- **Output file validation** - After each step, validates expected file was created:
+  - If missing, warns: "Agent wrote to different file(s): X instead of Y"
+  - Helps diagnose when agents don't create expected outputs
+- **Root cause: agents need `write` tool** - Agents without `write` in their tools list
+  cannot create output files (they tried MCP workarounds which failed)
+- **Thinking level suffixes now preserved** - Models with thinking levels (e.g., `claude-sonnet-4-5:high`)
+  now correctly resolve to `anthropic/claude-sonnet-4-5:high` instead of losing the provider prefix
+
+### Improved
+- **Per-step progress indicators** - When progress is enabled, each step shows its role:
+  - Step 1: `● creates & updates progress.md`
+  - Step 2+: `↔ reads & updates progress.md`
+  - Clear visualization of progress.md data flow through the chain
+- **Comprehensive tool descriptions** - Better documentation of chain variables:
+  - Tool description now explains `{task}`, `{previous}`, `{chain_dir}` in detail
+  - Schema descriptions clarify what each variable means and when to use them
+  - Helps agents construct proper chain queries for any use case
+
 ## [0.3.2] - 2026-01-25
 
 ### Performance

package/README.md

@@ -50,9 +50,22 @@ npx pi-subagents --remove
 - `Esc` - Cancel
 - `↑↓` - Navigate between steps
 - `e` - Edit task/template
-- `o` - Edit output path
+- `m` - Select model (fuzzy search with all available models)
+- `t` - Select thinking level (off, minimal, low, medium, high, xhigh)
+- `w` - Edit writes (output file path)
 - `r` - Edit reads list
-- `p` - Toggle progress tracking on/off
+- `p` - Toggle progress tracking for ALL steps (chains share one progress.md)
+
+*Model selector mode:*
+- `↑↓` - Navigate model list
+- `Enter` - Select model
+- `Esc` - Cancel (keep current model)
+- Type to filter (fuzzy search by model name or provider)
+
+*Thinking level selector mode:*
+- `↑↓` - Navigate level list
+- `Enter` - Select level
+- `Esc` - Cancel (keep current level)
 
 *Edit mode (full-screen editor with word wrapping):*
 - `Esc` - Save changes and exit

package/chain-clarify.ts

@@ -11,11 +11,19 @@ import { matchesKey, visibleWidth, truncateToWidth } from "@mariozechner/pi-tui"
 import type { AgentConfig } from "./agents.js";
 import type { ResolvedStepBehavior } from "./settings.js";
 
+/** Model info for display */
+export interface ModelInfo {
+	provider: string;
+	id: string;
+	fullId: string;  // "provider/id"
+}
+
 /** Modified behavior overrides from TUI editing */
 export interface BehaviorOverride {
 	output?: string | false;
 	reads?: string[] | false;
 	progress?: boolean;
+	model?: string;  // Override agent's default model (format: "provider/id")
 }
 
 export interface ChainClarifyResult {
@@ -25,7 +33,11 @@ export interface ChainClarifyResult {
 	behaviorOverrides: (BehaviorOverride | undefined)[];
 }
 
-type EditMode = "template" | "output" | "reads";
+type EditMode = "template" | "output" | "reads" | "model" | "thinking";
+
+/** Valid thinking levels */
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+type ThinkingLevel = typeof THINKING_LEVELS[number];
 
 /**
  * TUI component for chain clarification.
@@ -47,6 +59,17 @@ export class ChainClarifyComponent implements Component {
 	/** Track user modifications to behaviors (sparse - only stores changes) */
 	private behaviorOverrides: Map<number, BehaviorOverride> = new Map();
 
+	/** Model selector state */
+	private modelSearchQuery: string = "";
+	private modelSelectedIndex: number = 0;
+	private filteredModels: ModelInfo[] = [];
+
+	/** Max models visible in selector */
+	private readonly MODEL_SELECTOR_HEIGHT = 10;
+
+	/** Thinking level selector state */
+	private thinkingSelectedIndex: number = 0;
+
 	constructor(
 		private tui: TUI,
 		private theme: Theme,
@@ -55,8 +78,12 @@ export class ChainClarifyComponent implements Component {
 		private originalTask: string,
 		private chainDir: string,
 		private resolvedBehaviors: ResolvedStepBehavior[],
+		private availableModels: ModelInfo[],
 		private done: (result: ChainClarifyResult) => void,
-	) {}
+	) {
+		// Initialize filtered models
+		this.filteredModels = [...availableModels];
+	}
 
 	// ─────────────────────────────────────────────────────────────────────────────
 	// Helper methods for rendering
@@ -244,7 +271,7 @@ export class ChainClarifyComponent implements Component {
 	// ─────────────────────────────────────────────────────────────────────────────
 
 	/** Get effective behavior for a step (with user overrides applied) */
-	private getEffectiveBehavior(stepIndex: number): ResolvedStepBehavior {
+	private getEffectiveBehavior(stepIndex: number): ResolvedStepBehavior & { model?: string } {
 		const base = this.resolvedBehaviors[stepIndex]!;
 		const override = this.behaviorOverrides.get(stepIndex);
 		if (!override) return base;
@@ -253,9 +280,44 @@ export class ChainClarifyComponent implements Component {
 			output: override.output !== undefined ? override.output : base.output,
 			reads: override.reads !== undefined ? override.reads : base.reads,
 			progress: override.progress !== undefined ? override.progress : base.progress,
+			model: override.model,
 		};
 	}
 
+	/** Get the effective model for a step (override or agent default) */
+	private getEffectiveModel(stepIndex: number): string {
+		const override = this.behaviorOverrides.get(stepIndex);
+		if (override?.model) return override.model;  // Override is already in provider/model format
+		
+		// Use agent's configured model or "default"
+		const agentModel = this.agentConfigs[stepIndex]?.model;
+		if (!agentModel) return "default";
+		
+		// Resolve model name to full provider/model format
+		return this.resolveModelFullId(agentModel);
+	}
+
+	/** Resolve a model name to its full provider/model format */
+	private resolveModelFullId(modelName: string): string {
+		// 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 = this.availableModels.find(m => m.id === baseModel);
+		if (match) {
+			return thinkingSuffix ? `${match.fullId}${thinkingSuffix}` : match.fullId;
+		}
+		
+		// Fallback to just the model name if not found
+		return modelName;
+	}
+
 	/** Update a behavior override for a step */
 	private updateBehavior(stepIndex: number, field: keyof BehaviorOverride, value: string | boolean | string[] | false): void {
 		const existing = this.behaviorOverrides.get(stepIndex) ?? {};
@@ -264,7 +326,13 @@ export class ChainClarifyComponent implements Component {
 
 	handleInput(data: string): void {
 		if (this.editingStep !== null) {
-			this.handleEditInput(data);
+			if (this.editMode === "model") {
+				this.handleModelSelectorInput(data);
+			} else if (this.editMode === "thinking") {
+				this.handleThinkingSelectorInput(data);
+			} else {
+				this.handleEditInput(data);
+			}
 			return;
 		}
 
@@ -303,8 +371,8 @@ export class ChainClarifyComponent implements Component {
 			return;
 		}
 
-		// 'o' to edit output
-		if (data === "o") {
+		// 'w' to edit writes (output file)
+		if (data === "w") {
 			this.enterEditMode("output");
 			return;
 		}
@@ -315,13 +383,30 @@ export class ChainClarifyComponent implements Component {
 			return;
 		}
 
-		// 'p' to toggle progress
+		// 'p' to toggle progress for ALL steps (chains share a single progress.md)
 		if (data === "p") {
-			const current = this.getEffectiveBehavior(this.selectedStep);
-			this.updateBehavior(this.selectedStep, "progress", !current.progress);
+			// Check if any step has progress enabled
+			const anyEnabled = this.agentConfigs.some((_, i) => this.getEffectiveBehavior(i).progress);
+			// Toggle all steps to the opposite state
+			const newState = !anyEnabled;
+			for (let i = 0; i < this.agentConfigs.length; i++) {
+				this.updateBehavior(i, "progress", newState);
+			}
 			this.tui.requestRender();
 			return;
 		}
+
+		// 'm' to select model
+		if (data === "m") {
+			this.enterModelSelector();
+			return;
+		}
+
+		// 't' to select thinking level
+		if (data === "t") {
+			this.enterThinkingSelector();
+			return;
+		}
 	}
 
 	private enterEditMode(mode: EditMode): void {
@@ -345,6 +430,173 @@ export class ChainClarifyComponent implements Component {
 		this.tui.requestRender();
 	}
 
+	/** Enter model selector mode */
+	private enterModelSelector(): void {
+		this.editingStep = this.selectedStep;
+		this.editMode = "model";
+		this.modelSearchQuery = "";
+		this.modelSelectedIndex = 0;
+		this.filteredModels = [...this.availableModels];
+		
+		// Pre-select current model if it exists in the list
+		const currentModel = this.getEffectiveModel(this.selectedStep);
+		const currentIndex = this.filteredModels.findIndex(m => m.fullId === currentModel || m.id === currentModel);
+		if (currentIndex >= 0) {
+			this.modelSelectedIndex = currentIndex;
+		}
+		
+		this.tui.requestRender();
+	}
+
+	/** Filter models based on search query (fuzzy match) */
+	private filterModels(): void {
+		const query = this.modelSearchQuery.toLowerCase();
+		if (!query) {
+			this.filteredModels = [...this.availableModels];
+		} else {
+			this.filteredModels = this.availableModels.filter(m => 
+				m.fullId.toLowerCase().includes(query) ||
+				m.id.toLowerCase().includes(query) ||
+				m.provider.toLowerCase().includes(query)
+			);
+		}
+		// Clamp selected index
+		this.modelSelectedIndex = Math.min(this.modelSelectedIndex, Math.max(0, this.filteredModels.length - 1));
+	}
+
+	/** Handle input in model selector mode */
+	private handleModelSelectorInput(data: string): void {
+		// Escape or Ctrl+C - cancel and exit
+		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
+			this.exitEditMode();
+			return;
+		}
+
+		// Enter - select current model
+		if (matchesKey(data, "return")) {
+			const selected = this.filteredModels[this.modelSelectedIndex];
+			if (selected) {
+				this.updateBehavior(this.editingStep!, "model", selected.fullId);
+			}
+			this.exitEditMode();
+			return;
+		}
+
+		// Up arrow - move selection up
+		if (matchesKey(data, "up")) {
+			if (this.filteredModels.length > 0) {
+				this.modelSelectedIndex = this.modelSelectedIndex === 0 
+					? this.filteredModels.length - 1 
+					: this.modelSelectedIndex - 1;
+			}
+			this.tui.requestRender();
+			return;
+		}
+
+		// Down arrow - move selection down
+		if (matchesKey(data, "down")) {
+			if (this.filteredModels.length > 0) {
+				this.modelSelectedIndex = this.modelSelectedIndex === this.filteredModels.length - 1 
+					? 0 
+					: this.modelSelectedIndex + 1;
+			}
+			this.tui.requestRender();
+			return;
+		}
+
+		// Backspace - delete last character from search
+		if (matchesKey(data, "backspace")) {
+			if (this.modelSearchQuery.length > 0) {
+				this.modelSearchQuery = this.modelSearchQuery.slice(0, -1);
+				this.filterModels();
+			}
+			this.tui.requestRender();
+			return;
+		}
+
+		// Printable character - add to search query
+		if (data.length === 1 && data.charCodeAt(0) >= 32) {
+			this.modelSearchQuery += data;
+			this.filterModels();
+			this.tui.requestRender();
+			return;
+		}
+	}
+
+	/** Enter thinking level selector mode */
+	private enterThinkingSelector(): void {
+		this.editingStep = this.selectedStep;
+		this.editMode = "thinking";
+		
+		// Pre-select current thinking level if set
+		const currentModel = this.getEffectiveModel(this.selectedStep);
+		const colonIdx = currentModel.lastIndexOf(":");
+		if (colonIdx !== -1) {
+			const suffix = currentModel.substring(colonIdx + 1);
+			const levelIdx = THINKING_LEVELS.indexOf(suffix as ThinkingLevel);
+			this.thinkingSelectedIndex = levelIdx >= 0 ? levelIdx : 0;
+		} else {
+			this.thinkingSelectedIndex = 0; // Default to "off"
+		}
+		
+		this.tui.requestRender();
+	}
+
+	/** Handle input in thinking level selector mode */
+	private handleThinkingSelectorInput(data: string): void {
+		// Escape or Ctrl+C - cancel and exit
+		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
+			this.exitEditMode();
+			return;
+		}
+
+		// Enter - select current thinking level
+		if (matchesKey(data, "return")) {
+			const selectedLevel = THINKING_LEVELS[this.thinkingSelectedIndex];
+			this.applyThinkingLevel(selectedLevel);
+			this.exitEditMode();
+			return;
+		}
+
+		// Up arrow - move selection up
+		if (matchesKey(data, "up")) {
+			this.thinkingSelectedIndex = this.thinkingSelectedIndex === 0 
+				? THINKING_LEVELS.length - 1 
+				: this.thinkingSelectedIndex - 1;
+			this.tui.requestRender();
+			return;
+		}
+
+		// Down arrow - move selection down
+		if (matchesKey(data, "down")) {
+			this.thinkingSelectedIndex = this.thinkingSelectedIndex === THINKING_LEVELS.length - 1 
+				? 0 
+				: this.thinkingSelectedIndex + 1;
+			this.tui.requestRender();
+			return;
+		}
+	}
+
+	/** Apply thinking level to the current step's model */
+	private applyThinkingLevel(level: ThinkingLevel): void {
+		const stepIndex = this.editingStep!;
+		const currentModel = this.getEffectiveModel(stepIndex);
+		
+		// Strip any existing thinking level suffix
+		const colonIdx = currentModel.lastIndexOf(":");
+		let baseModel = currentModel;
+		if (colonIdx !== -1) {
+			const suffix = currentModel.substring(colonIdx + 1);
+			if (THINKING_LEVELS.includes(suffix as ThinkingLevel)) {
+				baseModel = currentModel.substring(0, colonIdx);
+			}
+		}
+		
+		// Apply new thinking level (don't add suffix for "off")
+		const newModel = level === "off" ? baseModel : `${baseModel}:${level}`;
+		this.updateBehavior(stepIndex, "model", newModel);
+	}
+
 	private handleEditInput(data: string): void {
 		const textWidth = this.width - 4; // Must match render: innerW - 2 = (width - 2) - 2
 		const { lines: wrapped, starts } = this.wrapText(this.editBuffer, textWidth);
@@ -495,9 +747,19 @@ export class ChainClarifyComponent implements Component {
 			originalLines[0] = this.editBuffer;
 			this.templates[stepIndex] = originalLines.join("\n");
 		} else if (this.editMode === "output") {
+			// Capture OLD output before updating (for downstream propagation)
+			const oldBehavior = this.getEffectiveBehavior(stepIndex);
+			const oldOutput = typeof oldBehavior.output === "string" ? oldBehavior.output : null;
+
 			// Empty string or whitespace means disable output
 			const trimmed = this.editBuffer.trim();
-			this.updateBehavior(stepIndex, "output", trimmed === "" ? false : trimmed);
+			const newOutput = trimmed === "" ? false : trimmed;
+			this.updateBehavior(stepIndex, "output", newOutput);
+
+			// Propagate output filename change to downstream steps' reads
+			if (oldOutput && typeof newOutput === "string" && oldOutput !== newOutput) {
+				this.propagateOutputChange(stepIndex, oldOutput, newOutput);
+			}
 		} else if (this.editMode === "reads") {
 			// Parse comma-separated list, empty means disable reads
 			const trimmed = this.editBuffer.trim();
@@ -510,13 +772,181 @@ export class ChainClarifyComponent implements Component {
 		}
 	}
 
+	/**
+	 * When a step's output filename changes, update downstream steps that read from it.
+	 * This maintains the chain dependency automatically.
+	 */
+	private propagateOutputChange(changedStepIndex: number, oldOutput: string, newOutput: string): void {
+		// Check all downstream steps (steps that come after the changed step)
+		for (let i = changedStepIndex + 1; i < this.agentConfigs.length; i++) {
+			const behavior = this.getEffectiveBehavior(i);
+			
+			// Skip if reads is disabled or empty
+			if (behavior.reads === false || !behavior.reads || behavior.reads.length === 0) {
+				continue;
+			}
+
+			// Check if this step reads the old output file
+			const readsArray = behavior.reads;
+			const oldIndex = readsArray.indexOf(oldOutput);
+			
+			if (oldIndex !== -1) {
+				// Replace old filename with new filename in reads
+				const newReads = [...readsArray];
+				newReads[oldIndex] = newOutput;
+				this.updateBehavior(i, "reads", newReads);
+			}
+		}
+	}
+
 	render(_width: number): string[] {
 		if (this.editingStep !== null) {
+			if (this.editMode === "model") {
+				return this.renderModelSelector();
+			}
+			if (this.editMode === "thinking") {
+				return this.renderThinkingSelector();
+			}
 			return this.renderFullEditMode();
 		}
 		return this.renderNavigationMode();
 	}
 
+	/** Render the model selector view */
+	private renderModelSelector(): string[] {
+		const innerW = this.width - 2;
+		const th = this.theme;
+		const lines: string[] = [];
+
+		// Header
+		const agentName = this.agentConfigs[this.editingStep!]?.name ?? "unknown";
+		const headerText = ` Select Model (Step ${this.editingStep! + 1}: ${agentName}) `;
+		lines.push(this.renderHeader(headerText));
+		lines.push(this.row(""));
+
+		// Search input
+		const searchPrefix = th.fg("dim", "Search: ");
+		const cursor = "\x1b[7m \x1b[27m"; // Reverse video space for cursor
+		const searchDisplay = this.modelSearchQuery + cursor;
+		lines.push(this.row(` ${searchPrefix}${searchDisplay}`));
+		lines.push(this.row(""));
+
+		// Current model info
+		const currentModel = this.getEffectiveModel(this.editingStep!);
+		const currentLabel = th.fg("dim", "Current: ");
+		lines.push(this.row(` ${currentLabel}${th.fg("warning", currentModel)}`));
+		lines.push(this.row(""));
+
+		// Model list with scroll
+		if (this.filteredModels.length === 0) {
+			lines.push(this.row(` ${th.fg("dim", "No matching models")}`));
+		} else {
+			// Calculate visible range (scroll to keep selection visible)
+			const maxVisible = this.MODEL_SELECTOR_HEIGHT;
+			let startIdx = 0;
+			
+			// Keep selection centered if possible
+			if (this.filteredModels.length > maxVisible) {
+				startIdx = Math.max(0, this.modelSelectedIndex - Math.floor(maxVisible / 2));
+				startIdx = Math.min(startIdx, this.filteredModels.length - maxVisible);
+			}
+			
+			const endIdx = Math.min(startIdx + maxVisible, this.filteredModels.length);
+
+			// Show scroll indicator if needed
+			if (startIdx > 0) {
+				lines.push(this.row(` ${th.fg("dim", `  ↑ ${startIdx} more`)}`));
+			}
+
+			for (let i = startIdx; i < endIdx; i++) {
+				const model = this.filteredModels[i]!;
+				const isSelected = i === this.modelSelectedIndex;
+				const isCurrent = model.fullId === currentModel || model.id === currentModel;
+				
+				const prefix = isSelected ? th.fg("accent", "→ ") : "  ";
+				const modelText = isSelected ? th.fg("accent", model.id) : model.id;
+				const providerBadge = th.fg("dim", ` [${model.provider}]`);
+				const currentBadge = isCurrent ? th.fg("success", " ✓") : "";
+				
+				lines.push(this.row(` ${prefix}${modelText}${providerBadge}${currentBadge}`));
+			}
+
+			// Show scroll indicator if needed
+			const remaining = this.filteredModels.length - endIdx;
+			if (remaining > 0) {
+				lines.push(this.row(` ${th.fg("dim", `  ↓ ${remaining} more`)}`));
+			}
+		}
+
+		// Pad to consistent height
+		const contentLines = lines.length;
+		const targetHeight = 18; // Consistent height
+		for (let i = contentLines; i < targetHeight; i++) {
+			lines.push(this.row(""));
+		}
+
+		// Footer
+		const footerText = " [Enter] Select • [Esc] Cancel • Type to search ";
+		lines.push(this.renderFooter(footerText));
+
+		return lines;
+	}
+
+	/** Render the thinking level selector view */
+	private renderThinkingSelector(): string[] {
+		const innerW = this.width - 2;
+		const th = this.theme;
+		const lines: string[] = [];
+
+		// Header
+		const agentName = this.agentConfigs[this.editingStep!]?.name ?? "unknown";
+		const headerText = ` Thinking Level (Step ${this.editingStep! + 1}: ${agentName}) `;
+		lines.push(this.renderHeader(headerText));
+		lines.push(this.row(""));
+
+		// Current model info
+		const currentModel = this.getEffectiveModel(this.editingStep!);
+		const currentLabel = th.fg("dim", "Model: ");
+		lines.push(this.row(` ${currentLabel}${th.fg("accent", currentModel)}`));
+		lines.push(this.row(""));
+
+		// Description
+		lines.push(this.row(` ${th.fg("dim", "Select thinking level (extended thinking budget):")}`));
+		lines.push(this.row(""));
+
+		// Thinking level options
+		const levelDescriptions: Record<ThinkingLevel, string> = {
+			"off": "No extended thinking",
+			"minimal": "Brief reasoning",
+			"low": "Light reasoning",
+			"medium": "Moderate reasoning",
+			"high": "Deep reasoning",
+			"xhigh": "Maximum reasoning (ultrathink)",
+		};
+
+		for (let i = 0; i < THINKING_LEVELS.length; i++) {
+			const level = THINKING_LEVELS[i];
+			const isSelected = i === this.thinkingSelectedIndex;
+			const prefix = isSelected ? th.fg("accent", "→ ") : "  ";
+			const levelText = isSelected ? th.fg("accent", level) : level;
+			const desc = th.fg("dim", ` - ${levelDescriptions[level]}`);
+			lines.push(this.row(` ${prefix}${levelText}${desc}`));
+		}
+
+		// Pad to consistent height
+		const contentLines = lines.length;
+		const targetHeight = 16;
+		for (let i = contentLines; i < targetHeight; i++) {
+			lines.push(this.row(""));
+		}
+
+		// Footer
+		const footerText = " [Enter] Select • [Esc] Cancel • ↑↓ Navigate ";
+		lines.push(this.renderFooter(footerText));
+
+		return lines;
+	}
+
 	/** Render navigation mode (step selection, preview) */
 	private renderNavigationMode(): string[] {
 		const innerW = this.width - 2;
@@ -536,6 +966,11 @@ export class ChainClarifyComponent implements Component {
 		lines.push(this.row(` Original Task: ${taskPreview}`));
 		const chainDirPreview = truncateToWidth(this.chainDir, innerW - 12);
 		lines.push(this.row(` Chain Dir: ${th.fg("dim", chainDirPreview)}`));
+
+		// Chain-wide progress setting
+		const progressEnabled = this.agentConfigs.some((_, i) => this.getEffectiveBehavior(i).progress);
+		const progressValue = progressEnabled ? th.fg("success", "✓ enabled") : th.fg("dim", "✗ disabled");
+		lines.push(this.row(` Progress: ${progressValue} ${th.fg("dim", "(press [p] to toggle)")}`));
 		lines.push(this.row(""));
 
 		// Each step
@@ -567,12 +1002,22 @@ export class ChainClarifyComponent implements Component {
 			const templateLabel = th.fg("dim", "task: ");
 			lines.push(this.row(`     ${templateLabel}${truncateToWidth(highlighted, innerW - 12)}`));
 
-			// Output line
-			const outputValue = behavior.output === false
+			// Model line (show override indicator if modified)
+			const effectiveModel = this.getEffectiveModel(i);
+			const override = this.behaviorOverrides.get(i);
+			const isOverridden = override?.model !== undefined;
+			const modelValue = isOverridden
+				? th.fg("warning", effectiveModel) + th.fg("dim", " ✎")
+				: effectiveModel;
+			const modelLabel = th.fg("dim", "model: ");
+			lines.push(this.row(`     ${modelLabel}${truncateToWidth(modelValue, innerW - 13)}`));
+
+			// Writes line (output file) - renamed from "output" for clarity
+			const writesValue = behavior.output === false
 				? th.fg("dim", "(disabled)")
 				: (behavior.output || th.fg("dim", "(none)"));
-			const outputLabel = th.fg("dim", "output: ");
-			lines.push(this.row(`     ${outputLabel}${truncateToWidth(outputValue, innerW - 14)}`));
+			const writesLabel = th.fg("dim", "writes: ");
+			lines.push(this.row(`     ${writesLabel}${truncateToWidth(writesValue, innerW - 14)}`));
 
 			// Reads line
 			const readsValue = behavior.reads === false
@@ -583,16 +1028,32 @@ export class ChainClarifyComponent implements Component {
 			const readsLabel = th.fg("dim", "reads: ");
 			lines.push(this.row(`     ${readsLabel}${truncateToWidth(readsValue, innerW - 13)}`));
 
-			// Progress line
-			const progressValue = behavior.progress ? th.fg("success", "✓ enabled") : th.fg("dim", "✗ disabled");
-			const progressLabel = th.fg("dim", "progress: ");
-			lines.push(this.row(`     ${progressLabel}${progressValue}`));
+			// Progress line - show when chain-wide progress is enabled
+			// First step creates & updates, subsequent steps read & update
+			if (progressEnabled) {
+				const isFirstStep = i === 0;
+				const progressAction = isFirstStep 
+					? th.fg("success", "●") + th.fg("dim", " creates & updates progress.md")
+					: th.fg("accent", "↔") + th.fg("dim", " reads & updates progress.md");
+				const progressLabel = th.fg("dim", "progress: ");
+				lines.push(this.row(`     ${progressLabel}${progressAction}`));
+			}
+
+			// Show {previous} indicator for all steps except the last
+			// This shows that this step's text response becomes {previous} for the next step
+			if (i < this.agentConfigs.length - 1) {
+				const nextStepUsePrevious = (this.templates[i + 1] ?? "").includes("{previous}");
+				if (nextStepUsePrevious) {
+					const indicator = th.fg("dim", "     ↳ response → ") + th.fg("warning", "{previous}");
+					lines.push(this.row(indicator));
+				}
+			}
 
 			lines.push(this.row(""));
 		}
 
 		// Footer with keybindings
-		const footerText = " [Enter] Run • [Esc] Cancel • [e]dit [o]utput [r]eads [p]rogress ";
+		const footerText = " [Enter] Run • [Esc] Cancel • [e]dit [m]odel [t]hinking [w]rites [r]eads [p]rogress ";
 		lines.push(this.renderFooter(footerText));
 
 		return lines;

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

@@ -144,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.3.2",
+  "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

@@ -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()),

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 {