ultimate-pi 0.23.0 → 0.25.0

package/.pi/extensions/agt-prompt-guard.ts

@@ -4,21 +4,35 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { PromptDefenseEvaluator } from "@microsoft/agent-governance-sdk";
+import { isHarnessNonInteractive } from "../lib/ask-user/policy.js";
 import { isHarnessProjectEnabled } from "../lib/harness-project-config.js";
-import { userVisiblePromptSlice } from "../lib/harness-run-context.js";
+import { harnessSlashCommandLineForPolicy } from "../lib/harness-run-context.js";
 
 const evaluator = new PromptDefenseEvaluator({ minGrade: "D" });
 
 export default function agtPromptGuard(pi: ExtensionAPI) {
 	if (!isHarnessProjectEnabled()) return;
 
-	pi.on("before_agent_start", async (event) => {
-		const prompt = userVisiblePromptSlice(event.prompt);
-		if (!prompt.trim()) return undefined;
-		if (!/\/harness-/.test(prompt)) return undefined;
+	pi.on("before_agent_start", async (event, ctx) => {
+		const commandLine = harnessSlashCommandLineForPolicy(
+			event.prompt,
+			ctx.sessionManager.getEntries(),
+		);
+		if (!commandLine) return undefined;
 
-		const report = evaluator.evaluate(prompt);
+		const report = evaluator.evaluate(commandLine);
 		if (report.isBlocking("D")) {
+			if (isHarnessNonInteractive()) {
+				pi.appendEntry("harness-policy-violation", {
+					source: "agt-prompt-guard",
+					display: false,
+					grade: report.grade,
+					score: report.score,
+					missing: report.missing,
+					advisory: true,
+				});
+				return undefined;
+			}
 			return {
 				message: {
 					customType: "harness-policy-violation",

package/.pi/extensions/harness-ask-user.ts

@@ -12,6 +12,7 @@ import {
 } from "../lib/ask-user/schema.js";
 import type { AskUserParams } from "../lib/ask-user/types.js";
 import { claimHarnessGovernanceLoad } from "../lib/extension-load-guard.js";
+import { setHarnessWaitingForUser } from "../lib/harness-subagent-progress.js";
 
 // @ts-expect-error pi extensions run as ESM
 const MODULE_URL = import.meta.url;
@@ -28,11 +29,19 @@ export default function harnessAskUser(pi: ExtensionAPI) {
 		parameters: AskUserParamsSchema,
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const result = await runAskUser(params as AskUserParams, {
-				ui: ctx.ui,
-				hasUI: ctx.hasUI,
-				sessionName: undefined,
-			});
+			setHarnessWaitingForUser("ask_user");
+			pi.events.emit("harness-waiting-for-user", { gate: "ask_user" });
+			let result: Awaited<ReturnType<typeof runAskUser>>;
+			try {
+				result = await runAskUser(params as AskUserParams, {
+					ui: ctx.ui,
+					hasUI: ctx.hasUI,
+					sessionName: undefined,
+				});
+			} finally {
+				setHarnessWaitingForUser(null);
+				pi.events.emit("harness-waiting-for-user", { gate: null });
+			}
 
 			if ("error" in result) {
 				return {

package/.pi/extensions/harness-auto-compact.ts

@@ -0,0 +1,94 @@
+/**
+ * Harness auto-compact at 50% context usage (VCC-backed).
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { claimExtensionLoad } from "../lib/extension-load-guard.js";
+import {
+	type CompactGateState,
+	createCompactGateState,
+	evaluateAutoCompactGate,
+	onCompactCancel,
+	onSessionCompact,
+} from "../lib/harness-auto-compact-policy.js";
+import { captureHarnessEvent } from "../lib/harness-debate-core-deps.js";
+
+// @ts-expect-error pi extensions run as ESM
+const MODULE_URL = import.meta.url;
+
+const gateBySession = new Map<string, CompactGateState>();
+
+function gateForSession(sessionId: string): CompactGateState {
+	let state = gateBySession.get(sessionId);
+	if (!state) {
+		state = createCompactGateState();
+		gateBySession.set(sessionId, state);
+	}
+	return state;
+}
+
+export default function harnessAutoCompact(pi: ExtensionAPI): void {
+	if (!claimExtensionLoad("harness-auto-compact", MODULE_URL)) return;
+
+	pi.on("tool_execution_start", (event, ctx) => {
+		if (event.toolName !== "subagent") return;
+		const sessionId = ctx?.sessionManager?.getSessionId?.();
+		if (!sessionId) return;
+		gateForSession(sessionId).subagentSpawnPending = true;
+	});
+
+	pi.on("tool_execution_end", (event, ctx) => {
+		if (event.toolName !== "subagent") return;
+		const sessionId = ctx?.sessionManager?.getSessionId?.();
+		if (!sessionId) return;
+		gateForSession(sessionId).subagentSpawnPending = false;
+	});
+
+	pi.on("session_compact", (_event, ctx) => {
+		const sessionId = ctx?.sessionManager?.getSessionId?.();
+		if (!sessionId) return;
+		onSessionCompact(gateForSession(sessionId));
+	});
+
+	pi.on("agent_end", async (_message, ctx) => {
+		const sessionId = ctx.sessionManager.getSessionId();
+		const state = gateForSession(sessionId);
+		if (state.cooldownTurns > 0) {
+			state.cooldownTurns -= 1;
+		}
+		const usage = ctx.getContextUsage();
+		if (!usage) return;
+		const isSubagent = process.env.PI_HARNESS_SUBPROCESS === "1";
+		const decision = evaluateAutoCompactGate(
+			{
+				percent: usage.percent ?? 0,
+				tokens: usage.tokens ?? undefined,
+				contextWindow: usage.contextWindow ?? undefined,
+			},
+			state,
+			{ isSubagent },
+		);
+		if (!decision.shouldCompact) return;
+		state.inFlight = true;
+		try {
+			await ctx.compact({
+				onComplete: (result) => {
+					const cancelled =
+						(result as { cancel?: boolean } | undefined)?.cancel === true;
+					if (cancelled) {
+						onCompactCancel(state);
+					}
+					captureHarnessEvent(sessionId, "harness_auto_compact", {
+						percent: usage.percent ?? 0,
+						tokens_before: usage.tokens ?? undefined,
+						context_window: usage.contextWindow ?? undefined,
+						compactor: "ultimate-pi-vcc",
+						cancelled,
+					});
+				},
+			});
+		} catch {
+			state.inFlight = false;
+		}
+	});
+}

package/.pi/extensions/harness-debate-tools.ts

@@ -5,6 +5,7 @@
 import { mkdir, readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isHarnessNonInteractive } from "../lib/ask-user/policy.js";
 import { claimHarnessGovernanceLoad } from "../lib/extension-load-guard.js";
 import {
 	captureHarnessEvent,
@@ -50,7 +51,20 @@ import {
 	validateIntegratorDraft,
 	withReviewRoundYamlWrite,
 } from "../lib/harness-debate-workflow-deps.js";
+import {
+	loadPlanDebateEligibilitySnapshot,
+	writePlanDebateEligibilitySnapshot,
+} from "../lib/plan-debate-eligibility-snapshot.js";
+import {
+	checkDebateWallClock,
+	debateWallClockRecoveryHint,
+} from "../lib/plan-debate-wall-clock.js";
+import {
+	planReviewGateModeForProfile,
+	planReviewGateStrategyFromEligibility,
+} from "../lib/plan-review-gate.js";
 
+// @ts-expect-error pi extensions run as ESM
 const MODULE_URL = import.meta.url;
 
 function getRunId(ctx: {
@@ -231,6 +245,7 @@ function registerHarnessDebateHandler2(pi: ExtensionAPI) {
 				),
 			};
 			const result = harnessPlanDebateEligibility(input);
+			await writePlanDebateEligibilitySnapshot(rd, result);
 			const lines = [
 				`profile: ${result.profile}`,
 				`review_gate_mode: ${result.review_gate_strategy.mode}`,
@@ -266,6 +281,11 @@ function registerHarnessDebateHandler3(pi: ExtensionAPI) {
 					Type.String({ description: "spec | wbs | schedule | quality" }),
 				),
 			),
+			review_gate_mode: Type.Optional(
+				Type.String({
+					description: "consolidated | threaded | parallel_probes",
+				}),
+			),
 		}),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			const runId = getRunId(ctx);
@@ -274,6 +294,7 @@ function registerHarnessDebateHandler3(pi: ExtensionAPI) {
 				debate_id?: string;
 				debate_profile?: string;
 				required_focuses?: string[];
+				review_gate_mode?: string;
 			};
 			const raw = String(p.debate_id ?? "");
 			const { debateId, corrected, warning } = normalizePlanDebateId(
@@ -290,14 +311,23 @@ function registerHarnessDebateHandler3(pi: ExtensionAPI) {
 			const required_focuses = (p.required_focuses ?? []).filter((f) =>
 				["spec", "wbs", "schedule", "quality"].includes(f),
 			) as Array<"spec" | "wbs" | "schedule" | "quality">;
+			const rd = runDir(projectRoot, runId);
+			const eligibilitySnapshot = await loadPlanDebateEligibilitySnapshot(rd);
 			const opened = await openDebateBus(runId, debateId, debateHooks(pi), {
 				debate_profile: profile,
 				required_focuses:
 					required_focuses.length > 0 ? required_focuses : undefined,
 			});
+			const explicitMode = p.review_gate_mode;
 			const review_gate_mode =
-				profile === "fast" ? ("consolidated" as const) : ("threaded" as const);
-			await initPlanMessenger(runDir(projectRoot, runId), {
+				explicitMode === "consolidated" ||
+				explicitMode === "threaded" ||
+				explicitMode === "parallel_probes"
+					? explicitMode
+					: eligibilitySnapshot
+						? planReviewGateStrategyFromEligibility(eligibilitySnapshot).mode
+						: planReviewGateModeForProfile(profile);
+			await initPlanMessenger(rd, {
 				runId,
 				debateId,
 				debate_profile: profile,
@@ -444,6 +474,24 @@ function registerHarnessDebateHandler6(pi: ExtensionAPI) {
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			const runId = getRunId(ctx);
 			const projectRoot = process.cwd();
+			const rd = runDir(projectRoot, runId);
+			const messenger = await loadMessengerState(rd);
+			const wall = checkDebateWallClock({
+				opened_at: messenger?.opened_at,
+				debate_profile: messenger?.debate_profile,
+			});
+			if (wall.exceeded && !isHarnessNonInteractive()) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: debateWallClockRecoveryHint(wall),
+						},
+					],
+					details: { wall_clock: wall },
+					isError: true,
+				};
+			}
 			const roundIndex = Number(
 				(params as { round_index: number }).round_index,
 			);
@@ -452,7 +500,6 @@ function registerHarnessDebateHandler6(pi: ExtensionAPI) {
 			draft.round_index = roundIndex;
 			if (!draft.schema_version) draft.schema_version = "1.0.0";
 			const debateId = planDebateIdForRun(runId);
-			const rd = runDir(projectRoot, runId);
 			const integratorBody =
 				(typeof draft.round_summary === "string" && draft.round_summary) ||
 				"Review integrator synthesis for this round.";
@@ -571,9 +618,17 @@ function registerHarnessDebateHandler7(pi: ExtensionAPI) {
 		}),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			const runId = getRunId(ctx);
+			const projectRoot = process.cwd();
+			const messenger = await loadMessengerState(runDir(projectRoot, runId));
+			const wall = checkDebateWallClock({
+				opened_at: messenger?.opened_at,
+				debate_profile: messenger?.debate_profile,
+			});
 			const rationale =
 				String((params as { rationale?: string }).rationale ?? "").trim() ||
-				"Plan Review Gate consensus after focus coverage and messenger-backed rounds.";
+				(wall.exceeded && isHarnessNonInteractive()
+					? "Debate truncated at wall-clock cap (non-interactive conditional_pass)."
+					: "Plan Review Gate consensus after focus coverage and messenger-backed rounds.");
 			const decision = await finalizeDebateConsensus(
 				rationale,
 				debateHooks(pi),

package/.pi/extensions/harness-live-widget.ts

@@ -4,6 +4,7 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { isHarnessProjectEnabled } from "../lib/harness-project-config.js";
 import { evaluateCrossSessionResume } from "../lib/harness-run-context.js";
+import { buildHarnessProgressStatusLine } from "../lib/harness-subagent-progress.js";
 import {
 	deriveHarnessStatusHint,
 	formatHarnessPhaseLabel,
@@ -311,6 +312,14 @@ export default function harnessLiveWidget(pi: ExtensionAPI) {
 		if (mountCtx) scheduleRefresh(mountCtx);
 	});
 
+	pi.events.on("harness-progress:updated", () => {
+		if (mountCtx) scheduleProgressRefresh(mountCtx);
+	});
+
+	pi.events.on("harness-waiting-for-user", () => {
+		if (mountCtx) scheduleProgressRefresh(mountCtx);
+	});
+
 	pi.events.on("harness-cross-session-resume", (payload: unknown) => {
 		const data =
 			payload && typeof payload === "object"
@@ -358,9 +367,25 @@ export default function harnessLiveWidget(pi: ExtensionAPI) {
 			flowSubstate: state.flowSubstate,
 			nextRecommendedCommand: state.nextRecommendedCommand,
 			crossSessionResumeCommand: state.crossSessionResumeCommand,
+			progressLine: buildHarnessProgressStatusLine(),
 		});
 	}
 
+	/** Re-render widget when elapsed-time progress changes (bypasses hash short-circuit). */
+	function scheduleProgressRefresh(ctx: ExtensionContext): void {
+		if (!isHarnessProjectEnabled()) {
+			clearHarnessWidget(ctx);
+			return;
+		}
+		const state = stateStore.refresh(ctx);
+		const hash = computeRenderHash(state);
+		updateStatusFallback(ctx, state);
+		lastRenderHash = hash;
+		if (component) component.setData(state);
+		component?.invalidate();
+		tuiHandle?.requestRender();
+	}
+
 	function scheduleRefresh(ctx: ExtensionContext): void {
 		if (refreshQueued) return;
 		refreshQueued = true;

package/.pi/extensions/harness-plan-approval.ts

@@ -2,9 +2,11 @@
  * harness-plan-approval — PlanPacket approval UI and transcript renderer for parent sessions.
  */
 
+import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { claimHarnessGovernanceLoad } from "../lib/extension-load-guard.js";
+import { tryAutoApprovePlan } from "../lib/harness-auto-approve.js";
 import type { PlanPacketLike } from "../lib/harness-run-context.js";
 import {
 	appendPlanApprovalIfNew,
@@ -13,6 +15,7 @@ import {
 	parsePlanApprovalFromMessage,
 	planPacketSummary,
 } from "../lib/harness-run-context.js";
+import { setHarnessWaitingForUser } from "../lib/harness-subagent-progress.js";
 import {
 	CREATE_PLAN_GUIDELINES,
 	CREATE_PLAN_SNIPPET,
@@ -46,6 +49,7 @@ import {
 	validateApprovePlanParams,
 } from "../lib/plan-approval/validate.js";
 import { validatePlanApprovalReadiness } from "../lib/plan-approval-readiness.js";
+import { loadPlanDebateEligibilitySnapshot } from "../lib/plan-debate-eligibility-snapshot.js";
 import { validatePlanDebateGate } from "../lib/plan-debate-gate.js";
 
 // @ts-expect-error pi extensions run as ESM
@@ -165,40 +169,58 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 			const risk = String(
 				validated.plan_packet.risk_level ?? "med",
 			).toLowerCase();
+			let readinessResult: Awaited<
+				ReturnType<typeof validatePlanApprovalReadiness>
+			> | null = null;
+			let debateGateResult: Awaited<
+				ReturnType<typeof validatePlanDebateGate>
+			> | null = null;
 			if (runCtx?.run_id) {
-				const readiness = await validatePlanApprovalReadiness(
+				readinessResult = await validatePlanApprovalReadiness(
 					projectRoot,
 					runCtx.run_id,
 					{ risk_level: risk },
 				);
-				if (!readiness.ok) {
+				if (!readinessResult.ok) {
 					return {
 						content: [
 							{
 								type: "text",
-								text: `approve_plan blocked — plan phase not ready:\n- ${readiness.errors.join("\n- ")}`,
+								text: `approve_plan blocked — plan phase not ready:\n- ${readinessResult.errors.join("\n- ")}`,
 							},
 						],
 						details: {
 							plan_packet: validated.plan_packet,
-							readiness,
+							readiness: readinessResult,
 							cancelled: true,
 						},
 						isError: true,
 					};
 				}
-				implWarnings.push(...readiness.warnings);
+				implWarnings.push(...readinessResult.warnings);
 			}
 			if (runCtx?.run_id) {
-				const gate = await validatePlanDebateGate(projectRoot, runCtx.run_id);
-				if (!gate.ok) {
+				const runDir = join(
+					projectRoot,
+					".pi",
+					"harness",
+					"runs",
+					runCtx.run_id,
+				);
+				const eligibility = await loadPlanDebateEligibilitySnapshot(runDir);
+				debateGateResult = await validatePlanDebateGate(
+					projectRoot,
+					runCtx.run_id,
+					eligibility ?? undefined,
+				);
+				if (!debateGateResult.ok) {
 					const { buildPlanDebateGateRecovery } = await import(
 						"../lib/plan-debate-gate.js"
 					);
 					const recovery = await buildPlanDebateGateRecovery(
 						projectRoot,
 						runCtx.run_id,
-						gate,
+						debateGateResult,
 					);
 					return {
 						content: [
@@ -209,13 +231,24 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 						],
 						details: {
 							plan_packet: validated.plan_packet,
-							debate_gate: gate,
+							debate_gate: debateGateResult,
 							cancelled: true,
 						},
 						isError: true,
 					};
 				}
 			}
+			const autoOutcome =
+				runCtx?.run_id && readinessResult && debateGateResult
+					? await tryAutoApprovePlan({
+							projectRoot,
+							runId: runCtx.run_id,
+							riskLevel: risk,
+							readiness: readinessResult,
+							debateGate: debateGateResult,
+						})
+					: { approved: false, reasons: [] };
+
 			const reviewPath = await writePlanReviewMarkdown(
 				projectRoot,
 				runCtx,
@@ -223,7 +256,7 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 				{
 					human_summary: validated.human_summary,
 					research_brief: validated.research_brief,
-					status: "draft",
+					status: autoOutcome.approved ? "approved" : "draft",
 				},
 			);
 			const planMarkdown = buildPlanApprovalMarkdown(validated);
@@ -246,11 +279,28 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 				},
 			});
 
-			const outcome: PlanApprovalDialogResult = await runPlanApprovalDialog(
-				ctx.ui,
-				validated,
-				{ hasUI: ctx.hasUI },
-			);
+			let outcome: PlanApprovalDialogResult;
+			if (autoOutcome.approved) {
+				outcome = {
+					response: {
+						kind: "selection",
+						selections: ["Approve"],
+					},
+					cancelled: false,
+					ui_backend: "headless",
+				};
+			} else {
+				setHarnessWaitingForUser("approve_plan");
+				pi.events.emit("harness-waiting-for-user", { gate: "approve_plan" });
+				try {
+					outcome = await runPlanApprovalDialog(ctx.ui, validated, {
+						hasUI: ctx.hasUI,
+					});
+				} finally {
+					setHarnessWaitingForUser(null);
+					pi.events.emit("harness-waiting-for-user", { gate: null });
+				}
+			}
 
 			const details = toApprovePlanToolDetails(
 				validated,

package/.pi/extensions/harness-plan-orchestration.ts

@@ -0,0 +1,140 @@
+/**
+ * Plan orchestration tools — FSM next action + synthesis route.
+ */
+
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { claimHarnessGovernanceLoad } from "../lib/extension-load-guard.js";
+import {
+	captureHarnessEvent,
+	getRunIdFromSession,
+	Type,
+} from "../lib/harness-debate-core-deps.js";
+import { derivePlanNextAction } from "../lib/harness-plan-fsm.js";
+import {
+	derivePlanRouteSpawns,
+	planSynthesisPath,
+} from "../lib/harness-plan-route.js";
+
+// @ts-expect-error pi extensions run as ESM
+const MODULE_URL = import.meta.url;
+
+function getRunId(ctx: {
+	sessionManager: { getEntries(): unknown[]; getSessionId(): string };
+}): string {
+	return (
+		getRunIdFromSession(
+			ctx.sessionManager.getEntries(),
+			ctx.sessionManager.getSessionId(),
+		) ?? ctx.sessionManager.getSessionId()
+	);
+}
+
+function runDir(projectRoot: string, runId: string): string {
+	return join(projectRoot, ".pi", "harness", "runs", runId);
+}
+
+export default function harnessPlanOrchestration(pi: ExtensionAPI) {
+	if (!claimHarnessGovernanceLoad("harness-plan-orchestration", MODULE_URL))
+		return;
+
+	pi.registerTool({
+		name: "harness_plan_next_action",
+		label: "Plan Next Action",
+		description:
+			"Deterministic plan-phase FSM: returns the next spawn, tool, gate, or wait_user action. Call before improvising orchestration steps.",
+		parameters: Type.Object({
+			quick: Type.Optional(Type.Boolean()),
+			task_summary: Type.Optional(Type.String()),
+			last_outcome: Type.Optional(Type.String()),
+		}),
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const runId = getRunId(ctx);
+			const projectRoot = process.cwd();
+			const p = params as {
+				quick?: boolean;
+				task_summary?: string;
+				last_outcome?: string | null;
+			};
+			const entries = ctx.sessionManager.getEntries();
+			const next = await derivePlanNextAction({
+				projectRoot,
+				runId,
+				entries,
+				quick: p.quick,
+				taskSummary: p.task_summary,
+				lastOutcome: p.last_outcome,
+			});
+			const sessionId = ctx.sessionManager.getSessionId();
+			captureHarnessEvent(sessionId, "harness_plan_fsm", {
+				run_id: runId,
+				phase: next.phase,
+				action: next.action,
+				review_gate_mode: next.review_gate_mode,
+				synthesis_route: next.synthesis_route,
+			});
+			const lines = [
+				`phase: ${next.phase}`,
+				`action: ${next.action}`,
+				next.tool ? `tool: ${next.tool}` : null,
+				next.agents?.length ? `agents: ${next.agents.join(", ")}` : null,
+				next.review_gate_mode
+					? `review_gate_mode: ${next.review_gate_mode}`
+					: null,
+				next.synthesis_route
+					? `synthesis_route: ${next.synthesis_route}`
+					: null,
+				...next.rationale.map((r) => `- ${r}`),
+			].filter(Boolean);
+			return {
+				content: [{ type: "text", text: lines.join("\n") }],
+				details: next,
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "harness_plan_route",
+		label: "Plan Synthesis Route",
+		description:
+			"Returns sequential vs plan-synthesizer routing and next planning spawns from disk artifacts.",
+		parameters: Type.Object({
+			risk_level: Type.Optional(Type.String()),
+			material_fork: Type.Optional(Type.Boolean()),
+		}),
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const runId = getRunId(ctx);
+			const rd = runDir(process.cwd(), runId);
+			const p = params as { risk_level?: string; material_fork?: boolean };
+			const route = await planSynthesisPath(rd, {
+				risk_level: p.risk_level,
+				material_fork: p.material_fork,
+			});
+			const spawns = await derivePlanRouteSpawns(rd, {
+				risk_level: p.risk_level,
+				material_fork: p.material_fork,
+			});
+			const sessionId = ctx.sessionManager.getSessionId();
+			captureHarnessEvent(sessionId, "harness_plan_route", {
+				run_id: runId,
+				route,
+				agents: spawns.agents,
+			});
+			return {
+				content: [
+					{
+						type: "text",
+						text: [
+							`route: ${route}`,
+							spawns.agents.length
+								? `next_agents: ${spawns.agents.join(", ")}`
+								: "next_agents: (none — advance to debate or approval)",
+							...spawns.rationale.map((r) => `- ${r}`),
+						].join("\n"),
+					},
+				],
+				details: spawns,
+			};
+		},
+	});
+}