pi-agent-flow 1.1.0 → 1.2.2

package/{index.ts → src/index.ts}

@@ -7,8 +7,15 @@
 
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
-import { type FlowConfig, discoverFlows } from "./agents.js";
-import { loadFlowModels, loadFlowSettings, type FlowModelConfig } from "./config.js";
+import { type FlowConfig, discoverFlows, getFlowTier } from "./agents.js";
+import {
+	loadFlowModelConfigs,
+	loadFlowSettings,
+	resolveFlowModelCandidates,
+	selectFlowModelStrategy,
+	type LoadedFlowModelConfigs,
+} from "./config.js";
+import { parseFlowCliArgs } from "./cli-args.js";
 import { renderFlowCall, renderFlowResult } from "./render.js";
 import { getFlowSummaryText } from "./runner-events.js";
 import { runHooks } from "./hooks.js";
@@ -16,11 +23,16 @@ import { mapFlowConcurrent, runFlow } from "./flow.js";
 import {
 	type SingleResult,
 	type FlowDetails,
+	type CompressedFlowResult,
+	type FileEntry,
+	type CommandEntry,
 	emptyFlowUsage,
 	isFlowError,
 	isFlowSuccess,
+	getFlowOutput,
 } from "./types.js";
-import { createBatchTool } from "./batch.js";
+import { extractStructuredOutput } from "./structured-output.js";
+import { createBatchTool, createBatchReadTool } from "./batch.js";
 import {
 	createWebTool,
 	looksLikeUrlPrompt,
@@ -73,6 +85,8 @@ const FlowParams = Type.Object({
 	),
 });
 
+const inheritedCliArgs = parseFlowCliArgs(process.argv);
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -97,23 +111,8 @@ function buildForkSessionSnapshotJsonl(
 	if (!header || typeof header !== "object") return null;
 
 	const branchEntries = sessionManager.getBranch();
-
-	// Trim the current conversation turn from the fork.
-	let trimFrom = branchEntries.length;
-	for (let i = branchEntries.length - 1; i >= 0; i--) {
-		const entry = branchEntries[i] as Record<string, unknown>;
-		if (entry?.type === "message") {
-			const msg = entry.message as Record<string, unknown> | undefined;
-			if (msg?.role === "user") {
-				trimFrom = i;
-				break;
-			}
-		}
-	}
-
-	const trimmedEntries = branchEntries.slice(0, trimFrom);
 	const lines = [JSON.stringify(header)];
-	for (const entry of trimmedEntries) lines.push(JSON.stringify(entry));
+	for (const entry of branchEntries) lines.push(JSON.stringify(entry));
 	return `${lines.join("\n")}\n`;
 }
 
@@ -335,46 +334,363 @@ async function confirmProjectFlowsIfNeeded(
 }
 
 // ---------------------------------------------------------------------------
-// Reminder flow injection (sliding — always on latest user message)
+// Sliding system prompt (short, inserted before latest user message)
+// Always active for root flows. Appended to the static system prompt in
+// before_agent_start, and inserted as a separate system message immediately
+// before the latest user message by the context handler.
 // ---------------------------------------------------------------------------
 
-const REMINDER_TEXT =
-	"\n\n[reminder_flow: If the answer is in context, reply; otherwise, delegate to the appropriate flow.]";
+const SLIDING_PROMPT_OPEN_TAG = "<pi-flow-sliding-system>";
+const SLIDING_PROMPT_CLOSE_TAG = "</pi-flow-sliding-system>";
+
+const SLIDING_PROMPT =
+	`${SLIDING_PROMPT_OPEN_TAG}\n` +
+	`You are operating with pi-agent-flow routing.\n` +
+	`If the answer is already in context, answer directly; otherwise delegate to the appropriate flow.\n` +
+	`${SLIDING_PROMPT_CLOSE_TAG}`;
+
+const SLIDING_PROMPT_RE = new RegExp(
+	SLIDING_PROMPT_OPEN_TAG.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") +
+	"[\\s\\S]*?" +
+	SLIDING_PROMPT_CLOSE_TAG.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"),
+	"g",
+);
+
+/** Strip any old sliding system prompt tags from a string. */
+function stripSlidingPromptText(text: string): string {
+	return text.replace(SLIDING_PROMPT_RE, "");
+}
 
-function stripReminder(
+/** Strip sliding prompt tags from content (string or text-part array). */
+function stripSlidingPromptFromContent(
 	content: string | { type: string; text?: string }[],
 ): string | { type: string; text?: string }[] {
 	if (typeof content === "string") {
-		return content.replace(REMINDER_TEXT, "");
+		return stripSlidingPromptText(content);
 	}
 	return content.map((c) => {
 		if (c.type === "text" && typeof c.text === "string") {
-			return { ...c, text: c.text.replace(REMINDER_TEXT, "") };
+			return { ...c, text: stripSlidingPromptText(c.text) };
 		}
 		return c;
 	});
 }
 
-function appendReminder(
-	content: string | { type: string; text?: string }[],
-): string | { type: string; text?: string }[] {
+/** Check whether content (string or text-part array) contains the sliding tag. */
+function contentContainsSlidingTag(content: any): boolean {
 	if (typeof content === "string") {
-		return content + REMINDER_TEXT;
+		return content.includes(SLIDING_PROMPT_OPEN_TAG);
+	}
+	if (Array.isArray(content)) {
+		return content.some(
+			(part: any) =>
+				part.type === "text" &&
+				typeof part.text === "string" &&
+				part.text.includes(SLIDING_PROMPT_OPEN_TAG),
+		);
+	}
+	return false;
+}
+
+/** Remove any existing sliding-system-prompt system messages and strip tags from user messages.
+ *  Returns the sanitized messages and a flag indicating whether anything changed.
+ */
+function stripSlidingPromptsFromMessages(messages: any[]): { messages: any[]; changed: boolean } {
+	let changed = false;
+	const result = messages
+		.filter((msg) => {
+			// Remove dedicated sliding system prompt messages
+			if (msg.role === "system" && contentContainsSlidingTag(msg.content)) {
+				changed = true;
+				return false;
+			}
+			return true;
+		})
+		.map((msg) => {
+			// Also strip stray tags embedded in user/assistant messages
+			if (!("content" in msg)) return msg;
+			const stripped = stripSlidingPromptFromContent(msg.content);
+			if (isJsonEqual(stripped, msg.content)) return msg;
+			changed = true;
+			return { ...msg, content: stripped };
+		});
+	return { messages: result, changed };
+}
+
+/** Build a system message containing the sliding prompt. */
+function makeSlidingPromptMessage(referenceMessage?: any): any {
+	return {
+		role: "system",
+		content: SLIDING_PROMPT,
+		timestamp: referenceMessage?.timestamp,
+	};
+}
+
+const REASONING_PART_TYPES = new Set([
+	"thinking",
+	"reasoning",
+	"reasoning_content",
+	"reasoningContent",
+]);
+
+const REASONING_FIELDS = [
+	"thinking",
+	"thinkingSignature",
+	"thinking_signature",
+	"reasoning",
+	"reasoningContent",
+	"reasoning_content",
+	"reasoningSignature",
+	"reasoning_signature",
+];
+
+function stripReasoningFromAssistantMessage(message: any): {
+	message: any;
+	changed: boolean;
+} {
+	let next = message;
+	let changed = false;
+
+	for (const field of REASONING_FIELDS) {
+		if (field in next) {
+			if (next === message) next = { ...message };
+			delete next[field];
+			changed = true;
+		}
+	}
+
+	if (Array.isArray(message.content)) {
+		const filteredContent = message.content.filter(
+			(part: any) => !REASONING_PART_TYPES.has(part?.type),
+		);
+		if (filteredContent.length !== message.content.length) {
+			if (next === message) next = { ...message };
+			next.content = filteredContent;
+			changed = true;
+		}
+	}
+
+	return { message: next, changed };
+}
+
+function isJsonEqual(a: any, b: any): boolean {
+	return JSON.stringify(a) === JSON.stringify(b);
+}
+// ---------------------------------------------------------------------------
+// Flow result compression
+// ---------------------------------------------------------------------------
+
+/**
+ * Module-level cache populated after each flow tool execution.
+ * Maps toolCallId → compressed flow result.
+ * Consumed by compressFlowToolResults at fork time.
+ */
+const flowResultCache = new Map<string, CompressedFlowResult[]>();
+
+/**
+ * Build compressed representations of flow results and cache them by toolCallId.
+ */
+function cacheFlowResults(toolCallId: string, results: SingleResult[]): void {
+	for (const result of results) {
+		const so = result.structuredOutput;
+		if (!so) continue;
+		const compressed: CompressedFlowResult = {
+			type: result.type,
+			status: isFlowError(result) ? "failed" : "accomplished",
+		};
+		if (so.files.length > 0) compressed.files = so.files;
+		if (so.commands.length > 0) compressed.commands = so.commands;
+		if (result.errorMessage) compressed.error = result.errorMessage;
+		const existing = flowResultCache.get(toolCallId) ?? [];
+		existing.push(compressed);
+		flowResultCache.set(toolCallId, existing);
+	}
+}
+
+/**
+ * Render a compressed flow result as compact text for child context.
+ */
+function renderCompressedFlowResult(r: CompressedFlowResult): string {
+	const parts: string[] = [`[Flow: ${r.type} ${r.status}]`];
+	if (r.files?.length) {
+		const fileLines = r.files.map((f) => {
+			const role = f.role ? ` (${f.role})` : "";
+			const desc = f.description ? ` — ${f.description}` : "";
+			return `  ${f.path}${role}${desc}`;
+		});
+		parts.push(`Files:\n${fileLines.join("\n")}`);
+	}
+	if (r.commands?.length) {
+		const cmdLines = r.commands.map((c) => {
+			const result = c.result ? ` (${c.result})` : "";
+			const purpose = c.purpose ? ` — ${c.purpose}` : "";
+			return `  ${c.tool ?? "cmd"}: ${c.command}${result}${purpose}`;
+		});
+		parts.push(`Commands:\n${cmdLines.join("\n")}`);
+	}
+	if (r.error) parts.push(`Error: ${r.error}`);
+	return parts.join("\n");
+}
+
+/**
+ * Compress flow tool results in a sanitized session snapshot.
+ *
+ * Scans for tool result messages that correspond to flow invocations
+ * and replaces their content with compact compressed output.
+ */
+export function compressFlowToolResults(snapshot: string, cache: Map<string, CompressedFlowResult[]>): string {
+	if (cache.size === 0) return snapshot;
+
+	const lines = snapshot.trimEnd().split("\n");
+	const result: string[] = [];
+
+	// First pass: map toolCallId → tool name from assistant messages
+	const toolCallIdToName = new Map<string, string>();
+	for (const line of lines) {
+		let entry: any;
+		try { entry = JSON.parse(line); } catch { continue; }
+		if (entry?.type !== "message" || entry.message?.role !== "assistant") continue;
+		const content = entry.message.content;
+		if (!Array.isArray(content)) continue;
+		for (const part of content) {
+			if (part.type === "toolCall" && part.toolCallId && part.name) {
+				toolCallIdToName.set(part.toolCallId, part.name);
+			}
+		}
+	}
+
+	// Second pass: compress flow tool results
+	for (const line of lines) {
+		let entry: any;
+		try { entry = JSON.parse(line); } catch { result.push(line); continue; }
+
+		if (entry?.type !== "message" || entry.message?.role !== "tool") {
+			result.push(line);
+			continue;
+		}
+
+		// Extract toolCallId — either from message-level or content-level toolResult
+		let toolCallId: string | undefined;
+		if (typeof entry.message.toolCallId === "string") {
+			toolCallId = entry.message.toolCallId;
+		} else if (Array.isArray(entry.message.content)) {
+			for (const part of entry.message.content) {
+				if (part.type === "toolResult" && part.toolCallId) {
+					toolCallId = part.toolCallId;
+					break;
+				}
+			}
+		}
+
+		if (!toolCallId) { result.push(line); continue; }
+
+		const toolName = toolCallIdToName.get(toolCallId);
+		if (toolName !== "flow") { result.push(line); continue; }
+
+		const compressed = cache.get(toolCallId);
+		if (!compressed || compressed.length === 0) { result.push(line); continue; }
+
+		const rendered = compressed.map(renderCompressedFlowResult).join("\n\n");
+
+		// Replace content in the tool result message
+		if (typeof entry.message.toolCallId === "string") {
+			// Format 1: toolCallId at message level, content is text array
+			entry = {
+				...entry,
+				message: {
+					...entry.message,
+					content: [{ type: "text", text: rendered }],
+				},
+			};
+		} else {
+			// Format 2: toolCallId inside content array
+			entry = {
+				...entry,
+				message: {
+					...entry.message,
+					content: entry.message.content.map((part: any) =>
+						part.type === "toolResult" && part.toolCallId === toolCallId
+							? { ...part, content: rendered }
+							: part,
+					),
+				},
+			};
+		}
+
+		result.push(JSON.stringify(entry));
 	}
-	const copy = [...content];
-	const lastTextIdx = copy.map((c, i) => (c.type === "text" ? i : -1)).filter((i) => i !== -1).pop();
-	if (lastTextIdx === undefined) {
-		copy.push({ type: "text", text: REMINDER_TEXT });
-	} else {
-		const block = copy[lastTextIdx] as { type: "text"; text: string };
-		copy[lastTextIdx] = { ...block, text: block.text + REMINDER_TEXT };
+
+	return `${result.join("\n")}\n`;
+}
+
+/**
+ * Sanitize a fork session snapshot JSONL to remove only non-inheritable
+ * artifacts before passing full parent context to child flows: sliding system
+ * prompts, legacy reminders, and assistant reasoning/thinking.
+ */
+function sanitizeForkSnapshot(snapshot: string | null): string | null {
+	if (!snapshot) return snapshot;
+
+	const lines = snapshot.trimEnd().split("\n");
+	const sanitizedLines: string[] = [];
+
+	for (const line of lines) {
+		let entry: any;
+		try {
+			entry = JSON.parse(line);
+		} catch {
+			sanitizedLines.push(line);
+			continue;
+		}
+
+		let changed = false;
+
+		// Drop sliding system prompt messages entirely.
+		if (
+			entry?.type === "message" &&
+			entry.message?.role === "system" &&
+			contentContainsSlidingTag(entry.message?.content)
+		) {
+			continue;
+		}
+
+		if (entry?.type === "message" && entry.message) {
+			let message = entry.message;
+
+			if (message.role === "assistant") {
+				const stripped = stripReasoningFromAssistantMessage(message);
+				message = stripped.message;
+				changed ||= stripped.changed;
+			}
+
+			if ("content" in message) {
+				const originalContent = message.content;
+				const strippedContent = stripSlidingPromptFromContent(originalContent);
+
+				if (!isJsonEqual(strippedContent, originalContent)) {
+					message = {
+						...message,
+						content: strippedContent,
+					};
+					changed = true;
+				}
+			}
+
+			if (changed) {
+				entry = { ...entry, message };
+			}
+		}
+
+		sanitizedLines.push(changed ? JSON.stringify(entry) : line);
 	}
-	return copy;
+
+	const sanitized = `${sanitizedLines.join("\n")}\n`;
+	return compressFlowToolResults(sanitized, flowResultCache);
 }
 
 function computeActiveTools(optimize: boolean): string[] {
 	return optimize
-		? ["batch", "bash", "flow", "web"]
+		? ["batch_read", "bash", "flow"]
 		: ["read", "write", "edit", "batch", "bash", "flow", "web"];
 }
 
@@ -391,6 +707,10 @@ export default function (pi: ExtensionAPI) {
 		description: "Block delegating to flows already in the current delegation stack (default: true).",
 		type: "boolean",
 	});
+	pi.registerFlag("flow-model-config", {
+		description: "Named flow model strategy from settings.json flowModelConfigs.",
+		type: "string",
+	});
 	pi.registerFlag("flow-lite-model", {
 		description: "Model for lite-tier flows (scout, debug).",
 		type: "string",
@@ -414,6 +734,8 @@ export default function (pi: ExtensionAPI) {
 
 	// toolOptimize: CLI flag > env var > settings.json > default (true)
 	let toolOptimize = true;
+	// structuredOutput: settings.json > default (true)
+	let structuredOutput = true;
 	const envToolOptimize = process.env[FLOW_TOOL_OPTIMIZE_ENV];
 	if (envToolOptimize !== undefined) {
 		const parsed = parseBoolean(envToolOptimize);
@@ -421,13 +743,17 @@ export default function (pi: ExtensionAPI) {
 	}
 
 	let discoveredFlows: FlowConfig[] = [];
-	let flowModelConfig: FlowModelConfig = {};
+	let loadedFlowModelConfigs: LoadedFlowModelConfigs = {
+		selectedName: "default",
+		configs: { default: {} },
+		strategy: {},
+	};
 
 	// Auto-discover flows on session start
 	pi.on("session_start", async (_event, ctx) => {
 		const discovery = discoverFlows(ctx.cwd, "all");
 		discoveredFlows = discovery.flows;
-		flowModelConfig = loadFlowModels(ctx.cwd);
+		loadedFlowModelConfigs = loadFlowModelConfigs(ctx.cwd);
 
 		// Resolve toolOptimize: CLI flag > env var > settings.json > default
 		const cliFlag = pi.getFlag("tool-optimize");
@@ -441,6 +767,9 @@ export default function (pi: ExtensionAPI) {
 			if (typeof flowSettings.toolOptimize === "boolean") {
 				toolOptimize = flowSettings.toolOptimize;
 			}
+			if (typeof flowSettings.structuredOutput === "boolean") {
+				structuredOutput = flowSettings.structuredOutput;
+			}
 		}
 
 		// Only restrict tools for the main orchestrator (depth 0).
@@ -450,8 +779,9 @@ export default function (pi: ExtensionAPI) {
 			pi.setActiveTools(computeActiveTools(toolOptimize));
 		}
 
-		// Register batch so it is available for both main agent and child flows.
+		// Register batch and batch_read so they are available for main agent and child flows.
 		if (toolOptimize) {
+			pi.registerTool(createBatchReadTool());
 			pi.registerTool(createBatchTool());
 		}
 	});
@@ -486,14 +816,17 @@ export default function (pi: ExtensionAPI) {
 		}
 
 		let systemPrompt = event.systemPrompt;
-		if (webInstructions.length > 0) {
+		if (!toolOptimize && webInstructions.length > 0) {
 			systemPrompt +=
 				"\n\n## pi-web steering\n" +
 				webInstructions.map((line) => `- ${line}`).join("\n");
 		}
 
+		// Append sliding prompt to static system prompt unconditionally.
+		systemPrompt += "\n\n" + SLIDING_PROMPT;
+
 		if (!canDelegate || discoveredFlows.length === 0) {
-			return webInstructions.length > 0 ? { systemPrompt } : undefined;
+			return { systemPrompt };
 		}
 
 		return {
@@ -507,8 +840,8 @@ Before acting, reason about whether to dive into a flow:
 - [debug] — when something is broken. Investigate logs, errors, stack traces to find root cause.
 - [build] — when you are ready to build. Implement features, fix bugs, write tests.
 - [craft] — when you need a plan. Design structure, break down requirements before building.
-- [audit] — when you need to verify. Audit security, quality, correctness.
-- [ideas] — when you need fresh ideas. Start from a clean slate with only the intent.
+- [audit] — when you need to verify and remediate. Audit security, quality, and correctness; fix safe issues directly.
+- [ideas] — when you need fresh ideas. Use inherited context as background while exploring alternatives.
 
 Multiple independent flows? Batch them into one call:
 
@@ -518,16 +851,16 @@ Multiple independent flows? Batch them into one call:
 Each call renders as:
 
 • flow [scout] — Map the full directory structure...
-• flow [audit] — Audit security and quality...
+• flow [audit] — Audit security and quality, then fix safe issues...
 
 Each flow returns:
 
 flow [type] accomplished
 
-[Summary] — what happened
-[Done] — completed with file:line references
-[Not Done] — incomplete items and reasons
-[Next Steps] — recommended follow-up
+[Summary] — what happened and current status
+[Done] — completed work with file:line references and verification results
+[Not Done] — incomplete items, skipped checks, blockers, and reasons
+[Next Steps] — specific recommended follow-up or next flow
 
 ### Guards
 - Depth: ${currentDepth}/${maxDepth} | Cycles: ${preventCycles ? "blocked" : "off"} | Stack: ${ancestorFlowStack.length > 0 ? ancestorFlowStack.join(" -> ") : "(root)"}
@@ -535,32 +868,50 @@ flow [type] accomplished
 		};
 	});
 
-	// Sliding reminder: strip from all earlier user messages, append to latest.
-	// Skip for child flows — they have explicit <mission> instructions and
-	// injecting the reminder is noise.
+	// Sliding system prompt: insert as a separate system message immediately
+	// before the latest user message each turn. Strips from the static
+	// systemPrompt to avoid duplication, then inserts separately.
+	// Skipped for child flows (depth > 0) — they have explicit <mission> directives.
 	pi.on("context", async (event) => {
 		if (currentDepth > 0) return undefined;
 
-		const messages = event.messages;
+		// Always strip old sliding prompt messages to prevent accumulation
+		const { messages, changed: messagesChanged } = stripSlidingPromptsFromMessages(event.messages);
+
+		// Find latest user message
 		const userIndices = messages
 			.map((m: any, i: number) => (m.role === "user" ? i : -1))
 			.filter((i: number) => i !== -1);
 
-		if (userIndices.length === 0) return undefined;
-
-		const lastUserIndex = userIndices[userIndices.length - 1];
-
-		const modified = messages.map((msg: any, idx: number) => {
-			if (msg.role !== "user") return msg;
+		if (userIndices.length === 0) {
+			// No user message yet: keep sliding prompt in the static system prompt only.
+			return messagesChanged ? { messages } : undefined;
+		}
 
-			const content = stripReminder(msg.content);
-			if (idx === lastUserIndex) {
-				return { ...msg, content: appendReminder(content) };
+		// Strip sliding from the static systemPrompt so it only appears once,
+		// as a separate message right before the latest user message.
+		let systemPrompt = event.systemPrompt;
+		let systemPromptChanged = false;
+		if (typeof systemPrompt === "string") {
+			const stripped = stripSlidingPromptText(systemPrompt);
+			if (stripped !== systemPrompt) {
+				systemPrompt = stripped;
+				systemPromptChanged = true;
 			}
-			return { ...msg, content };
-		});
+		}
 
-		return { messages: modified };
+		const lastUserIndex = userIndices[userIndices.length - 1];
+		const modified = [
+			...messages.slice(0, lastUserIndex),
+			makeSlidingPromptMessage(messages[lastUserIndex]),
+			...messages.slice(lastUserIndex),
+		];
+
+		const result: any = { messages: modified };
+		if (systemPromptChanged) {
+			result.systemPrompt = systemPrompt;
+		}
+		return result;
 	});
 
 	// Register the web tool
@@ -577,26 +928,53 @@ flow [type] accomplished
 				"",
 				"Flow states are isolated \u03c0 processes with forked session snapshots. They run in parallel.",
 				'Invoke: { "flow": [{ "type": "scout", "intent": "..." }, ...] }',
-				"States: scout (tanken), debug (kensh\u014d), build (shokunin), craft (keikaku), audit (kanshi), ideas (mushin).",
+				"States: scout, debug, build, craft, audit, ideas.",
 				"Custom states configs in (create if not exists): .md files in .pi/agents/ or ~/.pi/agent/agents/.",
 			].join("\n"),
 			parameters: FlowParams,
 
-			async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			async execute(toolCallId, params, signal, onUpdate, ctx) {
 				const discovery = discoverFlows(ctx.cwd, "all");
+				flowResultCache.clear();
 				const { flows } = discovery;
 				const makeDetails = makeFlowDetailsFactory(discovery.projectFlowsDir);
 
-				// Resolve tiered models: CLI flags override settings.json overrides parent --model
-				const tieredModels = {
-					lite: (pi.getFlag("flow-lite-model") as string | undefined) ?? flowModelConfig.lite,
-					flash: (pi.getFlag("flow-flash-model") as string | undefined) ?? flowModelConfig.flash,
-					full: (pi.getFlag("flow-full-model") as string | undefined) ?? flowModelConfig.full,
+				const cliFlowModelConfig =
+					typeof pi.getFlag("flow-model-config") === "string"
+						? (pi.getFlag("flow-model-config") as string)
+						: inheritedCliArgs.flowModelConfig;
+				const selectedFlowModelConfig = selectFlowModelStrategy(
+					loadedFlowModelConfigs.configs,
+					cliFlowModelConfig ?? loadedFlowModelConfigs.selectedName,
+				);
+
+				const getTierOverride = (tier: "lite" | "flash" | "full"): string | undefined => {
+					const flagName =
+						tier === "lite"
+							? "flow-lite-model"
+							: tier === "flash"
+								? "flow-flash-model"
+								: "flow-full-model";
+					const runtimeValue = pi.getFlag(flagName);
+					if (typeof runtimeValue === "string" && runtimeValue.trim()) return runtimeValue.trim();
+					const inheritedValue = inheritedCliArgs.tieredModels?.[tier];
+					return typeof inheritedValue === "string" && inheritedValue.trim() ? inheritedValue.trim() : undefined;
 				};
 
-				// Build fork session snapshot (shared across all flows that inherit context)
-				const forkSessionSnapshotJsonl = buildForkSessionSnapshotJsonl(
-					ctx.sessionManager,
+				const shouldFailover = (result: SingleResult): boolean => {
+					if (result.stopReason === "aborted") return false;
+					const text = `${result.errorMessage ?? ""}\n${result.stderr ?? ""}`.toLowerCase();
+					if (!text.trim()) return false;
+					if (text.includes("permission") || text.includes("invalid tool") || text.includes("bad settings")) {
+						return false;
+					}
+					return result.exitCode > 0;
+				};
+
+				// Build the full fork session snapshot and sanitize only non-inheritable
+				// artifacts before passing it to child flows.
+				const forkSessionSnapshotJsonl = sanitizeForkSnapshot(
+					buildForkSessionSnapshotJsonl(ctx.sessionManager),
 				);
 
 				// Collect all requested flow names
@@ -661,13 +1039,22 @@ flow [type] accomplished
 				}
 
 				let lastStreamingText = "";
-				let lastEmittedText: string | undefined;
+				let lastEmittedSignature: string | undefined;
 				const emitProgress = (streamingText?: string) => {
 					if (!onUpdate) return;
 					if (streamingText !== undefined) lastStreamingText = streamingText;
 					const text = lastStreamingText || "";
-					if (text === lastEmittedText) return;
-					lastEmittedText = text;
+					const signature =
+						text +
+						"|" +
+						allResults
+							.map(
+								(r) =>
+									`${r.messages.length}:${r.usage.toolCalls}:${r.usage.input}:${r.usage.output}:${r.usage.contextTokens}:${r.usage.smoothedTps ?? 0}:${r.errorMessage ?? ""}`,
+							)
+							.join(";");
+					if (signature === lastEmittedSignature) return;
+					lastEmittedSignature = signature;
 					onUpdate({
 						content: [{ type: "text", text }],
 						details: makeDetails([...allResults]),
@@ -683,34 +1070,66 @@ flow [type] accomplished
 						targetFlow?.maxDepth !== undefined ? targetFlow.maxDepth : maxDepth;
 
 					const shouldInheritContext = targetFlow?.inheritContext !== false;
-					const result = await runFlow({
-						cwd: ctx.cwd,
-						flows,
-						flowName: normalizedType,
-						intent: item.intent,
-						aim: item.aim,
-						taskCwd: item.cwd,
-						forkSessionSnapshotJsonl: shouldInheritContext ? forkSessionSnapshotJsonl : null,
-						parentDepth: currentDepth,
-						parentFlowStack: ancestorFlowStack,
-						maxDepth: effectiveMaxDepth,
-						preventCycles,
-						toolOptimize,
-						tieredModels,
-						signal,
-						onUpdate: (partial) => {
-							if (partial.details?.results[0]) {
-								allResults[index] = partial.details.results[0];
-								emitProgress(partial.content?.[0]?.text);
-							}
-						},
-						makeDetails,
+					const tier = getFlowTier(normalizedType);
+					const { candidates } = resolveFlowModelCandidates({
+						tier,
+						flowModel: targetFlow?.model,
+						cliTierOverride: getTierOverride(tier),
+						strategy: selectedFlowModelConfig.strategy,
+						fallbackModel: inheritedCliArgs.fallbackModel,
 					});
-					allResults[index] = result;
-					emitProgress();
+					const attemptModels = candidates.length > 0 ? candidates : [undefined];
+					const attemptedModels: string[] = [];
+					let result = allResults[index];
+
+					for (let attempt = 0; attempt < attemptModels.length; attempt++) {
+						const candidateModel = attemptModels[attempt];
+						if (candidateModel) attemptedModels.push(candidateModel);
+						result = await runFlow({
+							cwd: ctx.cwd,
+							flows,
+							flowName: normalizedType,
+							intent: item.intent,
+							aim: item.aim,
+							taskCwd: item.cwd,
+							forkSessionSnapshotJsonl: shouldInheritContext ? forkSessionSnapshotJsonl : null,
+							parentDepth: currentDepth,
+							parentFlowStack: ancestorFlowStack,
+							maxDepth: effectiveMaxDepth,
+							preventCycles,
+							toolOptimize,
+							structuredOutput,
+							model: candidateModel,
+							signal,
+							onUpdate: (partial) => {
+								if (partial.details?.results[0]) {
+									allResults[index] = partial.details.results[0];
+									emitProgress(partial.content?.[0]?.text);
+								}
+							},
+							makeDetails,
+						});
+						allResults[index] = result;
+						emitProgress();
+						if (isFlowSuccess(result) || signal?.aborted) break;
+						if (attempt < attemptModels.length - 1 && shouldFailover(result)) {
+							continue;
+						}
+						break;
+					}
+
+					if (result && !isFlowSuccess(result) && attemptedModels.length > 1) {
+						const summary = `Model failover attempts: ${attemptedModels.join(" -> ")}`;
+						const baseStderr = result.stderr.trim();
+						result.stderr = baseStderr ? `${baseStderr}\n\n${summary}` : summary;
+						allResults[index] = result;
+						emitProgress();
+					}
+
 					return result;
 				});
 
+				cacheFlowResults(toolCallId, results);
 				// Build tool result with FULL flow output — no truncation
 				const successCount = results.filter((r) => isFlowSuccess(r)).length;
 				const flowReports = results.map((r) => {