@henryqw/pi-subagent 4.1.1 → 5.0.0

package/extensions/delegation.ts

@@ -0,0 +1,9 @@
+import type { EphemeralSubagentExecutor, EphemeralSubagentResult, EphemeralSubagentRunInput } from "@henryqw/pi-subagent";
+
+/** Runs one caller-prepared child launch without making lifecycle decisions. */
+export function runDelegation(
+	executor: EphemeralSubagentExecutor,
+	input: EphemeralSubagentRunInput,
+): Promise<EphemeralSubagentResult> {
+	return executor.run(input);
+}

package/extensions/result-transport.ts

@@ -35,6 +35,7 @@ export type WorkflowTransportEntryDetails = {
 	index: number;
 	role: string;
 	status: WorkflowTransportStatus;
+	summary?: string;
 	model?: string;
 	thinkingLevel?: string;
 	worktree?: WorktreePayload;
@@ -71,6 +72,11 @@ function label(kind: TransportKind, failed: boolean): string {
 	return `Workflow ${failed ? "failed" : "succeeded"}.`;
 }
 
+export function displaySummary(text: string): string {
+	const line = text.split(/\r?\n/).find((candidate) => candidate.trim()) ?? "";
+	return Array.from(line.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").trim().split(/\s+/).join(" ")).slice(0, 160).join("");
+}
+
 function evidenceFor(entry: WorkflowTransportEntry): Evidence | undefined {
 	if (entry.status === "pending" || entry.status === "skipped") return;
 	const source = entry.status === "failed" || entry.status === "rejected" ? entry.failure : entry.assistantOutput;
@@ -123,15 +129,20 @@ function formatWorkflowTransport(
 		text: capEphemeralSubagentOutput(lines.join("\n")),
 		details: {
 			mode,
-			entries: ordered.map((entry) => ({
-				id: entry.id,
-				index: entry.index,
-				role: entry.role,
-				status: entry.status,
-				...(entry.model === undefined ? {} : { model: entry.model }),
-				...(entry.thinkingLevel === undefined ? {} : { thinkingLevel: entry.thinkingLevel }),
-				...(entry.worktreePayload === undefined ? {} : { worktree: { ...entry.worktreePayload } }),
-			})),
+			entries: ordered.map((entry) => {
+				const source = entry.status === "failed" || entry.status === "rejected" ? entry.failure
+					: entry.status === "running" || entry.status === "succeeded" ? entry.assistantOutput : undefined;
+				return {
+					id: entry.id,
+					index: entry.index,
+					role: entry.role,
+					status: entry.status,
+					...(source === undefined ? {} : { summary: displaySummary(source) }),
+					...(entry.model === undefined ? {} : { model: entry.model }),
+					...(entry.thinkingLevel === undefined ? {} : { thinkingLevel: entry.thinkingLevel }),
+					...(entry.worktreePayload === undefined ? {} : { worktree: { ...entry.worktreePayload } }),
+				};
+			}),
 		},
 		...(usage === undefined ? {} : { usage }),
 		failed,

package/extensions/role-tools.ts

@@ -1,10 +1,9 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { CHILD_EXCLUDED_TOOLS, ROLE_TOOL_POLICY_FLAG } from "@henryqw/pi-subagent";
+import { CHILD_EXCLUDED_TOOL_NAMES, ROLE_TOOL_POLICY_FLAG } from "@henryqw/pi-subagent";
 
-const childExcludedTools = new Set(CHILD_EXCLUDED_TOOLS.split(","));
+const childExcludedTools: ReadonlySet<string> = new Set(CHILD_EXCLUDED_TOOL_NAMES);
 
-function configuredTools(value: unknown): string[] | undefined {
-	if (value === undefined) return;
+function configuredTools(value: unknown): string[] {
 	if (typeof value !== "string") throw new Error(`${ROLE_TOOL_POLICY_FLAG} must be JSON tool names.`);
 	let parsed: unknown;
 	try {
@@ -25,10 +24,16 @@ export default function roleTools(pi: ExtensionAPI): void {
 	});
 	pi.on("session_start", () => {
 		const selected = configuredTools(pi.getFlag(ROLE_TOOL_POLICY_FLAG));
-		if (!selected) return;
-		const extensionTools = pi.getAllTools()
+		const allTools = pi.getAllTools();
+		const registeredTools = new Set(allTools.map((tool) => tool.name));
+		const extensionTools = allTools
 			.filter((tool) => !["builtin", "sdk", "inline"].includes(tool.sourceInfo.source))
 			.map((tool) => tool.name);
 		pi.setActiveTools([...new Set([...selected, ...extensionTools])].filter((name) => !childExcludedTools.has(name)));
+		const activeTools = new Set(pi.getActiveTools().filter((name) => registeredTools.has(name) && !childExcludedTools.has(name)));
+		const unavailable = selected.filter((name) => !activeTools.has(name));
+		if (unavailable.length) {
+			throw new Error(`Subagent requested unavailable tools: ${unavailable.join(", ")}. Check spelling and load the provider extension that registers them.`);
+		}
 	});
 }

package/extensions/subagent.ts

@@ -1,6 +1,6 @@
 import type { Usage } from "@earendil-works/pi-ai";
 import { type ExtensionAPI, type ExtensionContext, type Theme } from "@earendil-works/pi-coding-agent";
-import { type Component, truncateToWidth, type TUI, visibleWidth } from "@earendil-works/pi-tui";
+import { type Component, type TUI, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import {
 	availableTaskModels,
 	type ThinkingLevel,
@@ -28,16 +28,21 @@ import {
 	type WorktreePayload,
 } from "@henryqw/pi-subagent";
 import { DEFAULT_TIMEOUT_CONFIG, readSubagentConfig, type SubagentTimeoutConfig } from "./config.ts";
+import { registerDelegateFlow } from "./delegate-flow.ts";
+import { runDelegation } from "./delegation.ts";
 import {
 	formatBackgroundWorkflowResult,
 	formatWorkflowResult,
 	formatWorkflowUpdate,
 	WorkflowAbortedError,
 	WorkflowFailureError,
+	displaySummary,
 	type WorkflowTransportEntry,
+	type WorkflowTransportDetails,
 } from "./result-transport.ts";
 import {
 	identifyWorkflowEntries,
+	MAX_WORKFLOW_ENTRIES,
 	parseWorkflow,
 	runForegroundWorkflow,
 	WorkflowSchema,
@@ -49,7 +54,6 @@ import {
 const SUBAGENT_TASK = "pi-subagent/delegateTask";
 const WIDGET_KEY = "subagent-status";
 const WIDGET_INTERVAL_MS = 80;
-const TERMINAL_DISPLAY_MS = 1_000;
 const MAX_WIDGET_ROWS = 8;
 const DEFAULT_TIMEOUT_POLICY = {
 	idleMs: DEFAULT_TIMEOUT_CONFIG.idleMinutes * 60_000,
@@ -68,17 +72,18 @@ export function resolveTimeoutPolicy(partial: SubagentTimeoutConfig | undefined)
 }
 type WidgetStatus = "working" | "success" | "failure" | "aborted";
 type WidgetItem = {
-	roleRoute: string;
+	role: string;
+	model: string;
+	thinkingLevel: string;
 	task: string;
 	tokens: number;
 	startedAt: number;
 	status: WidgetStatus;
 	finishedAt?: number;
-	removeAt?: number;
 };
 
 function taskSummary(task: string): string {
-	return task.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").trim().split(/\s+/).slice(0, 4).join(" ");
+	return Array.from(task.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").trim().split(/\s+/).slice(0, 4).join(" ")).slice(0, 160).join("");
 }
 
 function formatTokens(tokens: number): string {
@@ -97,12 +102,51 @@ function statusGlyph(status: WidgetStatus, spinnerIndex: number, theme: Theme):
 	}
 }
 
-function leftColumn(value: string, width: number): string {
-	return truncateToWidth(value, width, "…", true);
+function statusLabel(status: WidgetStatus): string {
+	switch (status) {
+		case "working": return "working";
+		case "success": return "complete";
+		case "failure": return "failed";
+		case "aborted": return "stopped";
+	}
+}
+
+function isWorkflowTransportDetails(value: unknown): value is WorkflowTransportDetails {
+	const isRecord = (candidate: unknown): candidate is Record<string, unknown> => typeof candidate === "object" && candidate !== null && !Array.isArray(candidate);
+	const isOptionalString = (candidate: unknown) => candidate === undefined || typeof candidate === "string";
+	if (!isRecord(value) || !(value.mode === "single" || value.mode === "parallel" || value.mode === "chain") || !Array.isArray(value.entries)) return false;
+	const entries = value.entries;
+	return entries.length >= 1 && entries.length <= MAX_WORKFLOW_ENTRIES
+		&& (value.mode !== "single" || entries.length === 1)
+		&& entries.every((entry) => isRecord(entry)
+			&& typeof entry.id === "string" && typeof entry.index === "number" && Number.isFinite(entry.index) && Number.isInteger(entry.index) && entry.index >= 0
+			&& typeof entry.role === "string" && ["pending", "running", "succeeded", "failed", "rejected", "skipped"].includes(entry.status as string)
+			&& (["running", "succeeded", "failed", "rejected"].includes(entry.status as string)
+				? typeof entry.summary === "string" && entry.summary === displaySummary(entry.summary)
+				: entry.summary === undefined)
+			&& isOptionalString(entry.model) && isOptionalString(entry.thinkingLevel)
+			&& (entry.worktree === undefined || isRecord(entry.worktree)
+				&& typeof entry.worktree.path === "string" && typeof entry.worktree.branch === "string"
+				&& typeof entry.worktree.commits === "number" && Number.isFinite(entry.worktree.commits) && Number.isInteger(entry.worktree.commits) && entry.worktree.commits >= 0
+				&& typeof entry.worktree.dirty === "boolean" && typeof entry.worktree.pruned === "boolean"
+				&& (entry.worktree.inspection_failed === undefined || typeof entry.worktree.inspection_failed === "boolean")
+				&& (entry.worktree.note === undefined || typeof entry.worktree.note === "string")))
+		&& entries.every((entry, index) => index === 0 || (entry as { index: number }).index > (entries[index - 1] as { index: number }).index);
 }
 
-function rightColumn(value: string, width: number): string {
-	return " ".repeat(Math.max(0, width - visibleWidth(value))) + value;
+function renderWorkflowResult(details: WorkflowTransportDetails, width: number, theme: Theme): string[] {
+	if (details.entries.some(({ status }) => status === "pending" || status === "running")) return [];
+	return details.entries.flatMap((entry) => {
+		if (entry.status === "skipped") return [];
+		const summary = entry.summary || "(no output)";
+		const text = details.mode === "single" ? summary : `${entry.role}: ${summary}`;
+		const style = entry.status === "failed" || entry.status === "rejected" ? "error" : "text";
+		const recovery = entry.worktree && !entry.worktree.pruned ? `Recovery: ${entry.worktree.path}` : undefined;
+		return [
+			...wrapTextWithAnsi(theme.fg(style, text), Math.max(1, width)),
+			...(recovery ? wrapTextWithAnsi(theme.fg("warning", recovery), Math.max(1, width)) : []),
+		];
+	});
 }
 
 function renderWidgetRows(
@@ -114,30 +158,14 @@ function renderWidgetRows(
 ): string[] {
 	const visible = items.slice(0, MAX_WIDGET_ROWS);
 	if (!visible.length) return [];
-	const tokens = visible.map((item) => formatTokens(item.tokens));
-	const elapsed = visible.map((item) => formatDuration((item.finishedAt ?? now) - item.startedAt));
-	const tokenWidth = Math.max(...tokens.map(visibleWidth));
-	const elapsedWidth = Math.max(...elapsed.map(visibleWidth));
-	const fixedWidth = 1 + 8 + tokenWidth + elapsedWidth;
-	if (width < fixedWidth) {
-		return visible.map((item, index) => truncateToWidth(
-			`${statusGlyph(item.status, spinnerIndex, theme)} ${tokens[index]} ${elapsed[index]}`,
-			width,
-			"",
-		));
-	}
-	const contentWidth = width - fixedWidth;
-	const naturalRoleWidth = Math.min(32, Math.max(...visible.map((item) => visibleWidth(item.roleRoute))));
-	const roleWidth = Math.min(naturalRoleWidth, contentWidth);
-	const taskWidth = contentWidth - roleWidth;
-	const lines = visible.map((item, index) => [
-		statusGlyph(item.status, spinnerIndex, theme),
-		theme.fg("accent", leftColumn(item.roleRoute, roleWidth)),
-		theme.fg("text", leftColumn(item.task, taskWidth)),
-		theme.fg("muted", rightColumn(tokens[index]!, tokenWidth)),
-		theme.fg("dim", rightColumn(elapsed[index]!, elapsedWidth)),
-	].join("  "));
-	if (items.length > visible.length) lines.push(theme.fg("muted", `… ${items.length - visible.length} more`));
+	const indent = " ".repeat(Math.min(2, Math.max(0, width - 1)));
+	const contentWidth = Math.max(1, width - indent.length);
+	const lines = visible.flatMap((item) => [
+		...wrapTextWithAnsi(`${statusGlyph(item.status, spinnerIndex, theme)} ${theme.fg("accent", item.role)} · ${statusLabel(item.status)}`, Math.max(1, width)),
+		...wrapTextWithAnsi(theme.fg("text", item.task), contentWidth).map((line) => `${indent}${line}`),
+		...wrapTextWithAnsi(theme.fg("muted", `${item.model} · ${item.thinkingLevel} · ${formatTokens(item.tokens)} tok · ${formatDuration((item.finishedAt ?? now) - item.startedAt)}`), contentWidth).map((line) => `${indent}${line}`),
+	]);
+	if (items.length > visible.length) lines.push(...wrapTextWithAnsi(theme.fg("muted", `… ${items.length - visible.length} more`), Math.max(1, width)));
 	return lines;
 }
 
@@ -224,6 +252,7 @@ export default function subagentExtension(
 	// Bumped by session_start and session_shutdown; background tasks may only
 	// deliver into the exact session that launched them.
 	let sessionEpoch = 0;
+	let invalidateDelegateFlow = () => {};
 	let widgetInstalled = false;
 	let widgetTimer: ReturnType<typeof setInterval> | undefined;
 	let spinnerIndex = 0;
@@ -240,12 +269,7 @@ export default function subagentExtension(
 		if (widgetTimer) return;
 		widgetTimer = setInterval(() => {
 			spinnerIndex = (spinnerIndex + 1) % SPINNER_FRAMES.length;
-			const now = Date.now();
-			for (const [id, item] of widgetItems) {
-				if (item.removeAt !== undefined && item.removeAt <= now) widgetItems.delete(id);
-			}
 			requestWidgetRender();
-			if (!widgetItems.size) stopWidgetTimer();
 		}, WIDGET_INTERVAL_MS);
 		widgetTimer.unref();
 	};
@@ -272,8 +296,17 @@ export default function subagentExtension(
 	) => {
 		if (!ctx.hasUI) return;
 		ensureWidget(ctx);
+		if (!widgetItems.has(id) && widgetItems.size >= MAX_WIDGET_ROWS) {
+			for (const [oldestId, item] of widgetItems) {
+				if (item.status === "working") continue;
+				widgetItems.delete(oldestId);
+				if (widgetItems.size < MAX_WIDGET_ROWS) break;
+			}
+		}
 		widgetItems.set(id, {
-			roleRoute: `${role}[${model}:${thinkingLevel ?? "default"}]`,
+			role,
+			model,
+			thinkingLevel: thinkingLevel ?? "default",
 			task: taskSummary(task),
 			tokens: 0,
 			startedAt: Date.now(),
@@ -295,13 +328,13 @@ export default function subagentExtension(
 		if (!item) return;
 		item.status = status;
 		item.finishedAt = Date.now();
-		item.removeAt = item.finishedAt + TERMINAL_DISPLAY_MS;
-		startWidgetTimer();
+		if (![...widgetItems.values()].some(({ status }) => status === "working")) stopWidgetTimer();
 		requestWidgetRender();
 	};
 
 	pi.on("session_start", (_event, ctx) => {
 		sessionEpoch += 1;
+		invalidateDelegateFlow();
 		latestCtx = ctx;
 		ensureWidget(ctx);
 		for (const warning of startupWarnings.splice(0)) ctx.ui.notify(warning, "warning");
@@ -316,6 +349,7 @@ export default function subagentExtension(
 		// Invalidate ordinary outcomes, abort children, then let preserved isolated
 		// work report into the outgoing session before Pi tears it down.
 		sessionEpoch += 1;
+		invalidateDelegateFlow();
 		const tasks = [...backgroundTasks.values()];
 		for (const { controller } of tasks) controller.abort();
 		await Promise.allSettled(tasks.map(({ settled }) => settled));
@@ -323,6 +357,13 @@ export default function subagentExtension(
 	});
 	// btw-style context refresh: model_select carries the new model on the event,
 	// agent_settled delivers the freshest full context after each turn.
+	pi.on("input", (event) => {
+		if (event.source === "extension") return;
+		for (const [id, item] of widgetItems) {
+			if (item.status !== "working") widgetItems.delete(id);
+		}
+		requestWidgetRender();
+	});
 	pi.on("model_select", (event, ctx) => {
 		latestCtx = { ...ctx, model: event.model } as ExtensionContext;
 	});
@@ -397,6 +438,23 @@ export default function subagentExtension(
 		}
 	};
 
+	invalidateDelegateFlow = registerDelegateFlow(pi, {
+		executor,
+		maxRuntimeMs: timeoutPolicy.maxMs,
+		getSessionGeneration: () => sessionEpoch,
+		loadRoles,
+		resolveLaunch: (role, ctx) => {
+			const launchCtx = latestCtx ?? ctx;
+			return createRoleLaunch(pi, launchCtx, {
+				role,
+				route: resolveConfiguredTaskRoute(launchCtx, SUBAGENT_TASK),
+			});
+		},
+		startWidget: startWidgetItem,
+		updateWidgetTokens,
+		finishWidget: finishWidgetItem,
+	});
+
 	pi.registerTool({
 		name: "delegate_task",
 		label: "Subagent",
@@ -410,6 +468,20 @@ export default function subagentExtension(
 			"delegate_task background applies to the whole selected workflow and returns before results exist; use it only when the user explicitly asks for non-blocking work.",
 		],
 		parameters: WorkflowSchema,
+		renderResult(result, _options, theme, _context) {
+			const details = result.details;
+			if (isWorkflowTransportDetails(details)) {
+				return {
+					invalidate() {},
+					render: (width) => renderWorkflowResult(details, width, theme),
+				};
+			}
+			if (typeof details === "object" && details !== null && (details as { background?: unknown }).background === true) {
+				return { invalidate() {}, render: (width) => wrapTextWithAnsi(theme.fg("muted", "Background workflow accepted."), Math.max(1, width)) };
+			}
+			const text = result.content.find((part) => part.type === "text")?.text ?? "(no output)";
+			return { invalidate() {}, render: (width) => wrapTextWithAnsi(theme.fg("muted", text), Math.max(1, width)) };
+		},
 		prepareArguments(args) {
 			try {
 				const workflow = parseWorkflow(args);
@@ -512,7 +584,7 @@ export default function subagentExtension(
 							: { ...base, status: nextStatus, assistantOutput: nextText });
 					};
 					try {
-						child = await executor.run({
+						child = await runDelegation(executor, {
 							signal: workflowSignal,
 							onUpdate: (output) => {
 								setState("running", output);
@@ -586,7 +658,6 @@ export default function subagentExtension(
 					setState(status, text);
 					try {
 						finishWidgetItem(entry.id, aborted ? "aborted" : status === "succeeded" ? "success" : "failure");
-						emitUpdate(emitToolUpdates);
 					} catch (error) {
 						rejected = error;
 						status = "rejected";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "4.1.1",
+  "version": "5.0.0",
   "description": "Delegate bounded single, parallel, or chained tasks to isolated Pi roles.",
   "keywords": [
     "pi-package",

package/skills/pi-subagent-delegated-development/SKILL.md

@@ -1,54 +1,32 @@
 ---
 name: pi-subagent-delegated-development
-description: Orchestrate delegated development with pi-subagent delegate_task. Use when splitting implementation work into bounded units for isolated implementer children reviewed by a read-only reviewer before merging.
+description: Run bounded independent implementation through the runtime-managed Delegate Flow.
 ---
 
 # Delegated Development
 
-You are Main. Decompose work into bounded units and coordinate; never edit files yourself.
+You are Main: slice work and call `delegate_flow`. Do not implement child work yourself or use external model tools, push, publish, or release.
 
-All model and agent work in this workflow goes through Pi's `delegate_task` and Pi-managed children. Do not invoke external LLM APIs, SDKs, agent harnesses, or model CLIs; ordinary deterministic developer tools such as `git`, npm, test runners, and compilers remain allowed.
+## Slice
 
-## Required preflight
+Use the fewest cohesive units. `delegate_flow` is for independent units expected to commute; combine or sequence work that overlaps files, APIs, schemas, generated output, package metadata, lockfiles, or invariants. Dependent work remains outside Flow, in one task or ordinary caller-controlled sequencing.
 
-Before any delegation, require that Main's cwd is a Git working tree with a committed `HEAD`:
+Give every unit a bounded objective, owned scope and exclusions, acceptance criteria, and its direct validation command/argument array. Do not pass the parent request unchanged. Call `delegate_flow` with 1–8 units; the runtime supplies the effective Implementer and Reviewer Roles.
 
-```bash
-test "$(git rev-parse --is-inside-work-tree)" = true &&
-git rev-parse --verify -q HEAD^{commit} >/dev/null
-```
-
-If this fails, stop before delegation and report that this Skill requires a Git repository with a committed `HEAD`; do not rely on the generic worktree fallback to Main's cwd.
-
-Before recording each unit's `base=$(git rev-parse HEAD)`, and again immediately before integration and validation, require `git status --porcelain=v1 --untracked-files=all` to be empty. If Git cannot inspect status or any tracked or untracked change is present, stop and ask the user to preserve the changes; never stash, discard, hide, or work around them.
-
-## Roles
-
-The package-shipped built-in Roles `implementer` (`isolation: worktree`) and `reviewer` (read-only patch-and-file review) are always available; no installation step is required. A same-name user override replaces the built-in entirely. Before using this workflow, Main must verify that each override preserves implementer worktree isolation and reviewer read-only patch-and-file constraints; fail clearly if it does not. Do not invent substitute Roles.
+## Runtime Flow
 
-## Per-unit loop
+The runtime owns the unit worktrees and all Git identity, rebasing, declared validation, exact read-only review, fast-forward integration, and cleanup. It records the clean committed Main state, runs independent Implementers in isolated unit worktrees, processes units in declared order, and integrates only the exact reviewed tip OID.
 
-For each bounded unit:
+Trust the structured Flow outcome. Never edit a child worktree, manage its branches, prepare review evidence, reimplement Flow, or manually integrate its changes. Do not repeat Flow validation after it has completed or integrated a unit.
 
-1. **Implement** — one `delegate_task` single call to `implementer`. The packet states the objective, touched scope, required validation, and recorded base commit. Require its output to identify the retained worktree path, branch, base commit, tip commit, changed files from the base-to-tip committed diff, and clean `git status --porcelain=v1 --untracked-files=all` result.
-2. **Verify and review** — refuse review or merge unless Main independently verifies that the worktree was retained and is clean (including untracked files), the reported base/branch/tip identities are complete and match Git, the tip is descended from the recorded base, and the reported changed files equal `git diff --name-only "$base" "$tip"`. All intended changes must be in that committed base-to-tip diff. If any evidence is missing or any check fails, send the work to a fresh implementer repair; never review dirty or uncommitted work.
+A successful Flow owns integration and cleanup. A blocked outcome is repairable: provide one explicit continuation and no more:
 
-   Create a private temporary exact-patch artifact outside the repository from `git diff --no-textconv --no-ext-diff --ignore-submodules=none --binary "$base" "$tip"`. Independently regenerate that same diff and byte-compare it with the artifact, then record its path, byte count, and SHA-256. If creation, regeneration, comparison, byte count, or checksum fails, stop and report the artifact failure clearly; do not review or merge. Do not put any complete patch content in `delegate_task` text or argv.
-
-   Make one `delegate_task` single call to `reviewer` with only a bounded metadata packet: base, tip, review context `{type:'child_branch', branch}`, the verified complete patch file reference (`path`, `bytes`, `sha256`), and the verified changed paths. If that complete metadata cannot fit the task transport bound, stop and report it rather than truncating or inlining patch content. Chain entries do not share files: `{previous}` passes text only.
-3. **Merge** — only after an approving review, re-check Main's clean status, verify the branch tip still equals the reviewed tip commit, then merge that exact commit (not the branch name) into Main's current worktree and run focused validation there. Never merge on unresolved findings.
-4. **Clean up after success** — only after the exact reviewed tip is integrated and focused validation passes, remove each reported retained worktree, then safely delete its task branch. Include a superseded repair-round worktree only when its exact tip is an ancestor of integrated `HEAD`. For each candidate, verify ancestry first, use non-forced worktree removal followed by `git branch -d`, and stop/report cleanup failure without deleting later evidence. On any integration or validation failure, preserve every temporary patch artifact, retained worktree, and task branch for recovery. After integration and validation succeed, remove the temporary reviewer patch artifacts.
-
-## Findings
-
-Any reviewer finding goes back as a **fresh** `implementer` delegation containing the findings plus the reviewed base/branch/tip identities and complete exact patch file reference, followed by a fresh review of the new state. A fresh repair implementer starts in a new worktree from Main HEAD and does not contain the prior unit commit: the repair packet must first bring the whole reviewed `$base..$tip` range into its fresh worktree by merging the exact `$tip`, or cherry-picking every range commit in order. Cherry-pick `$tip` alone only after `git rev-list --count "$base..$tip"` verifies the range is exactly one commit; then address the findings. Dirty or uncommitted work also goes only to this fresh repair path. Bound the loop (e.g. three rounds); past the bound, stop and report to the user instead of merging.
-
-## Parallelism
+```ts
+delegate_flow_continue({ guidance: "Address the reported block and complete the bounded unit." })
+```
 
-Independent units may run concurrently via one `delegate_task` parallel call (max 8 entries) or concurrent single calls, each still following its own implement → review cycle. Never parallelize a unit's review ahead of its implementation. Each child gets its own deterministic worktree; they never share files implicitly.
+Make the guidance specific to the reported implementation, validation, or review failure. Do not call continuation unless Flow reports a repairable block. If continuation or Flow returns a terminal failure, inspect every retained path reported by the runtime, then reslice or manually recover from Main; do not retry the Flow or guess a rebase resolution. A cleanup warning does not undo successful integration.
 
-## Boundaries
+## Ordinary delegation
 
-- Never bypass review, edit inside a child's worktree, or re-implement a child's work yourself.
-- On child failure, recover from the reported preserved-worktree evidence; retry at most once per unit before escalating to the user.
-- Do not push, publish, release, or open PRs without explicit user authorization.
+Use `delegate_task` for a single bounded task, independent parallel tasks, or dependent chain work that is not a Flow. Give each entry its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and focused validation. Preserve ordinary Role selection and isolation behavior. Keep integration and cross-cutting decisions in Main, and use the minimum number of Subagents needed.