@underactive/pi-topping-moa-fusion 0.2.0 → 0.4.1

package/src/planning/planMode.ts

@@ -1,7 +1,8 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import type { Message, TextContent } from "@earendil-works/pi-ai";
+import type { Message } from "@earendil-works/pi-ai";
 import { Key } from "@earendil-works/pi-tui";
 import type {
+	AgentBeforeSettleEvent,
 	AgentSettledEvent,
 	AgentStartEvent,
 	ExtensionAPI,
@@ -9,6 +10,7 @@ import type {
 	MessageEndEvent,
 	MessageStartEvent,
 	MessageUpdateEvent,
+	SessionBoundaryDraft,
 	ThemeColor,
 	ToolExecutionStartEvent,
 } from "@earendil-works/pi-coding-agent";
@@ -39,10 +41,18 @@ import { MoaProgressWidget } from "../ui/moaProgressWidget.ts";
 import { showObserveOverlay, type ObserveSession } from "../ui/observeOverlay.ts";
 import { planNamingOverlay, withWorkingOverlay } from "../ui/workingOverlay.ts";
 import { ASK_USER_QUESTION_TOOL_NAME, createAskUserQuestionTracker, isAskUserQuestionInstalled } from "./askUserQuestion.ts";
+import {
+	buildVerificationPendingMessage,
+	collectOmissionDrafts,
+	isPlanInstructionEntry,
+	isPlanModeInstructionText,
+	isVerificationPendingEntry,
+	type ScannedEntry,
+} from "./contextEdits.ts";
 import { buildPlanModeExitInstructions, buildPlanModeInstructions, buildPlanModeReentryInstructions } from "./instructions.ts";
 import { latestPlanModeStateEntry, PlanModeStatePersistence, validateToolLoadoutSnapshot } from "./modeState.ts";
 import { getPlan, getPlanSlug, isValidPlanSlug, resetPlanSlug, saveRepoPlanFile, setPlanSlug, slugifyPlanName } from "./planFile.ts";
-import { PLAN_EXIT_CONTEXT_TYPE, PLAN_MODE_CONTEXT_TYPE, PLAN_MODE_CUSTOM_TOOLS, PLAN_MODE_READ_ONLY_TOOLS, PLAN_ONLY_REGISTERED_TOOLS } from "./tools/shared.ts";
+import { PLAN_EXIT_CONTEXT_TYPE, PLAN_MODE_CONTEXT_TYPE, PLAN_MODE_CUSTOM_TOOLS, PLAN_MODE_READ_ONLY_TOOLS, PLAN_ONLY_REGISTERED_TOOLS, VERIFICATION_PENDING_CONTEXT_TYPE } from "./tools/shared.ts";
 
 /** Trailing chars of the implementer report kept for the verifier's evidence. */
 const IMPLEMENTATION_REPORT_MAX_CHARS = 8000;
@@ -86,6 +96,17 @@ function extractAssistantText(content: unknown): string {
 	return "";
 }
 
+// Existing tests and stale post-reload contexts may not expose getBranch;
+// boundary handlers should become inert rather than throw in that case.
+function readBranchEntries(ctx: ExtensionContext): readonly ScannedEntry[] {
+	try {
+		const manager = ctx.sessionManager as { getBranch?: () => readonly ScannedEntry[] };
+		return typeof manager.getBranch === "function" ? manager.getBranch() : [];
+	} catch {
+		return [];
+	}
+}
+
 export function createPlanModeController(pi: ExtensionAPI) {
 	let planModeEnabled = false;
 	let toolsBeforePlanMode: string[] | undefined;
@@ -99,6 +120,8 @@ export function createPlanModeController(pi: ExtensionAPI) {
 	let activeRunMoaInfo: MfPlanInfo | undefined;
 	let implementationHandoff: ImplementationHandoff | undefined;
 	let implementationPending = false;
+	let verificationInFlight = false;
+	const omittedEntryIds = new Set<string>();
 	let lastImplementationStopReason: string | undefined;
 	// The implementer's final assistant text, captured while pending so the
 	// verifier can be handed the implementer's own (untrusted) report. Capped to
@@ -263,6 +286,32 @@ export function createPlanModeController(pi: ExtensionAPI) {
 		applyReadOnlyProviderEnv();
 		pi.setActiveTools(getPlanModeTools(toolsBeforePlanMode));
 	};
+	/**
+	 * Plan-only tools are kept out of normal mode by removing them from the
+	 * active set, not with pi 0.99's `prepareLoadout` / `hiddenDeclarations`:
+	 * - Hidden tools stay active. `getActiveTools()` would always list
+	 *   write_plan, exit_plan_mode, and mf_plan_subagent, so the contamination
+	 *   checks in `enablePlanModeTools` and `validateToolLoadoutSnapshot` would
+	 *   treat every loadout as poisoned and swap the user's real one for
+	 *   `fullLoadoutFallback()` on every entry and resume, contradicting
+	 *   plan-tool-leak and plan-resume-tool-restore.
+	 * - Hidden tools stay callable. pi rejects calls to inactive tools; a hidden
+	 *   one would run with only its `isEnabled` guard in the way. It cannot
+	 *   replace the plan-mode read-only narrowing either: hidden bash/edit/write
+	 *   would still run.
+	 * - The hook runs only while its host tool is active. Outside plan mode that
+	 *   is enter_plan_mode alone; drop it via --tools or the tool picker and all
+	 *   three declarations leak.
+	 * - After resume or /tree, 0.99.2 strips the hidden declarations only while
+	 *   the host tool is active. The model still sees the plan-only tools when
+	 *   the host is inactive, on pre-0.99 hosts (peerDependencies are "*" and
+	 *   they ignore the hook), and through earlier tool calls in history, which
+	 *   the projection does not filter.
+	 * - A capability gate would only add surface: older hosts still need this
+	 *   path, so both mechanisms would ship.
+	 * - The saving is two tool-change deltas per planning round, and this is
+	 *   already a no-op when the set is clean.
+	 */
 	const deactivatePlanOnlyTools = (): void => {
 		const active = pi.getActiveTools();
 		const filtered = active.filter((name) => !PLAN_ONLY_REGISTERED_TOOLS.includes(name));
@@ -548,6 +597,63 @@ export function createPlanModeController(pi: ExtensionAPI) {
 				activeProgressWidget?.updateRoleTranscript("Implement", implementationMessages);
 			}
 		},
+		onAgentBeforeSettle: (event: AgentBeforeSettleEvent, ctx: ExtensionContext) => {
+			try {
+				const branch = readBranchEntries(ctx);
+				const persistedOmissions = new Set(
+					branch
+						.filter((entry) => entry.type === "context_edit" && entry.replacement === null && typeof entry.targetId === "string")
+						.map((entry) => entry.targetId as string),
+				);
+				// A different extension can invalidate the combined boundary proposal.
+				// Forget locally proposed edits that did not reach the branch so they are
+				// retried rather than suppressed for the rest of this process.
+				for (const id of omittedEntryIds) {
+					if (!persistedOmissions.has(id)) omittedEntryIds.delete(id);
+				}
+				const drafts: SessionBoundaryDraft[] = [];
+
+				// Persist plan-instruction omissions after plan mode exits. This is
+				// additive to onContext's per-request filter and repairs older sessions.
+				if (!planModeEnabled) {
+					drafts.push(...collectOmissionDrafts(branch, isPlanInstructionEntry, omittedEntryIds));
+				}
+				if (!verificationInFlight) {
+					drafts.push(...collectOmissionDrafts(branch, isVerificationPendingEntry, omittedEntryIds));
+				}
+
+				const stopReason = lastImplementationStopReason;
+				// KEEP IN LOCKSTEP with onAgentSettled's verification branch below.
+				// exit_plan_mode marks implementation pending before the follow-up has
+				// run, so implementationTurns distinguishes that planning boundary.
+				const verificationWillDispatch = implementationPending
+					&& implementationTurns > 0
+					&& event.context.pendingMessages.length === 0
+					&& event.outcome !== "aborted"
+					&& event.outcome !== "error"
+					&& !implementationTurnFailed(stopReason)
+					&& stopReason !== "aborted"
+					&& implementationHandoff !== undefined
+					&& (implementationHandoff.verifier ?? loadMoaConfig().verifier) !== undefined;
+				if (verificationWillDispatch) {
+					drafts.push({
+						type: "custom_message",
+						customType: VERIFICATION_PENDING_CONTEXT_TYPE,
+						content: buildVerificationPendingMessage(implementationHandoff?.planFilePath),
+						display: false,
+					});
+				}
+
+				if (drafts.length === 0) return undefined;
+				for (const draft of drafts) {
+					if (draft.type === "context_edit") omittedEntryIds.add(draft.targetId);
+				}
+				return { entries: [...event.entries, ...drafts] };
+			} catch {
+				// A thrown boundary handler could reject every proposed entry.
+				return undefined;
+			}
+		},
 		onAgentSettled: (_event: AgentSettledEvent, ctx: ExtensionContext) => {
 			updateStatus(ctx);
 			if (!implementationPending) return;
@@ -595,10 +701,13 @@ export function createPlanModeController(pi: ExtensionAPI) {
 			// explicit guard is required before the verification branch.
 			if (stopReason === "aborted") return;
 			if (!implementationHandoff) return;
+			// KEEP IN LOCKSTEP with verificationWillDispatch in onAgentBeforeSettle.
 			const verifier = implementationHandoff.verifier ?? loadMoaConfig().verifier;
 			if (verifier) {
+				verificationInFlight = true;
 				void runImplementationVerification(ctx, moaRunHost, { ...implementationHandoff, verifier }, report)
-					.catch(reportFlowFailure("Verification"));
+					.catch(reportFlowFailure("Verification"))
+					.finally(() => { verificationInFlight = false; });
 			}
 		},
 		onContext: async (event: { messages: AgentMessage[] }) => {
@@ -607,14 +716,15 @@ export function createPlanModeController(pi: ExtensionAPI) {
 				const msg = message as AgentMessage & { customType?: string };
 				if (msg.customType === PLAN_MODE_CONTEXT_TYPE || msg.customType === PLAN_EXIT_CONTEXT_TYPE) return false;
 				if (msg.role !== "user") return true;
-				if (typeof msg.content === "string") return !msg.content.startsWith("[PLAN MODE ACTIVE]") && !msg.content.startsWith("[PLAN MODE RE-ENTRY]");
-				if (Array.isArray(msg.content)) return !msg.content.some((part) => part.type === "text" && ((part as TextContent).text?.startsWith("[PLAN MODE ACTIVE]") || (part as TextContent).text?.startsWith("[PLAN MODE RE-ENTRY]")));
-				return true;
+				return !isPlanModeInstructionText(msg.content);
 			}) };
 		},
 		onBeforeAgentStart: async () => {
 			if (needsExitReminder) {
 				needsExitReminder = false;
+				// The reminder turn is also the first normal-mode turn: repair a
+				// leaked plan-only loadout here too, not from the next turn on.
+				if (!planModeEnabled) deactivatePlanOnlyTools();
 				persistState();
 				return { message: { customType: PLAN_EXIT_CONTEXT_TYPE, content: buildPlanModeExitInstructions(), display: false } };
 			}
@@ -641,6 +751,8 @@ export function createPlanModeController(pi: ExtensionAPI) {
 			activeCancelSession = undefined;
 			activeObserveSession = undefined;
 			implementationHandoff = undefined;
+			verificationInFlight = false;
+			omittedEntryIds.clear();
 			footerError = undefined;
 			lastRenderedFooter = undefined;
 			lastFooterCtx = undefined;
@@ -680,6 +792,13 @@ export function createPlanModeController(pi: ExtensionAPI) {
 			} else {
 				deactivatePlanOnlyTools();
 			}
+			try {
+				if (collectOmissionDrafts(readBranchEntries(ctx), isVerificationPendingEntry, new Set()).length > 0) {
+					ctx.ui.notify("The previous session ended before plan verification finished — the last implementation is unverified. Run /mf-plan-implement to verify it.", "warning");
+				}
+			} catch {
+				// A stale session-start context cannot be notified safely.
+			}
 			updateStatus(ctx);
 			startFooterTicker(ctx);
 			if (ctx.mode === "tui" && typeof ctx.ui.onTerminalInput === "function") {
@@ -694,6 +813,8 @@ export function createPlanModeController(pi: ExtensionAPI) {
 		},
 		onSessionShutdown: (_event: { reason: string }) => {
 			implementationPending = false;
+			verificationInFlight = false;
+			omittedEntryIds.clear();
 			lastImplementationStopReason = undefined;
 			lastImplementationReport = undefined;
 			resetImplementationTranscript();

package/src/planning/tools/enterPlanMode.ts

@@ -12,9 +12,10 @@ import { modelRefLabel, TRIGGER_TURN, type ModelRef, type ThinkingLevel } from "
 import { showMoaModelPicker, showImplementingModelPicker } from "../../ui/moaModelPicker.ts";
 import { showMoaSetup } from "../../ui/moaSetupOverlay.ts";
 import { showPromptEditor } from "../../ui/promptEditor.ts";
-import { getPlan } from "../planFile.ts";
+import { getPlan, getPlanFilePath } from "../planFile.ts";
 import { isAskUserQuestionInstalled } from "../askUserQuestion.ts";
 import { buildPlanModeInstructions, buildPlanModeReentryInstructions } from "../instructions.ts";
+import { ENTER_PLAN_MODE_OUTPUT_SCHEMA } from "./structuredResults.ts";
 
 export interface InteractivePlanModeHost {
 	beginInteractive(ctx: ExtensionContext): void;
@@ -136,6 +137,11 @@ export function registerEnterPlanModeTool(pi: ExtensionAPI, host: EnterPlanModeH
 				Type.String({ description: "Short description of what is being planned (used to name the plan file)" }),
 			),
 		}),
+		outputSchema: ENTER_PLAN_MODE_OUTPUT_SCHEMA,
+		// Swaps the active tools and provider env, persists state, and with a
+		// plan_prompt writes the prompt record under .pi/mf-plan/. Not read-only;
+		// destructive is left at the default because that write can overwrite.
+		annotations: { readOnlyHint: false },
 		// enter_plan_mode is paired with a same-message ask_user_question only in
 		// the single-model path; marking it sequential means the questionnaire
 		// resolves first, so mf-plan's own overlays never draw over it.
@@ -159,6 +165,7 @@ export function registerEnterPlanModeTool(pi: ExtensionAPI, host: EnterPlanModeH
 					type: "text",
 					text: `Plan mode enabled (single model — the current session model). Mutating tools are disabled until your plan is approved via exit_plan_mode.\n\n${instructions}`,
 				}],
+				structuredContent: { status: "entered", mode: "single", reentry, planFilePath: getPlanFilePath() },
 			};
 		},
 	});

package/src/planning/tools/exitPlanMode.ts

@@ -10,6 +10,7 @@ import { showPlanReview } from "../../ui/planReviewOverlay.ts";
 import { planNamingOverlay, withWorkingOverlay } from "../../ui/workingOverlay.ts";
 import { ASK_USER_QUESTION_PENDING_MESSAGE } from "../askUserQuestion.ts";
 import { getPlan, getPlanFilePath, saveRepoPlanFile, slugifyPlanName, writePlan } from "../planFile.ts";
+import { EXIT_PLAN_MODE_OUTPUT_SCHEMA, type ExitPlanModeStructuredResult } from "./structuredResults.ts";
 
 import type { ImplementationHandoff } from "../../moa/implementationRetry.ts";
 
@@ -35,6 +36,10 @@ export function registerExitPlanModeTool(pi: ExtensionAPI, host: ExitPlanModeHos
 		label: "Exit Plan Mode",
 		description: "Use when you are in plan mode and have finished writing your plan to the plan file and are ready for user approval. Reads the plan from the plan file — does NOT take plan content as a parameter. Only use for tasks that require writing code; not for pure research.",
 		parameters: Type.Object({}),
+		outputSchema: EXIT_PLAN_MODE_OUTPUT_SCHEMA,
+		// Restores tools and env and queues implementation; the edit branch and the
+		// non-TUI approve overwrite plan files, and every call reopens approval.
+		annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
 		// exit_plan_mode opens a model/UI surface the model may not have asked
 		// the user about yet; marking it sequential means a same-message
 		// ask_user_question resolves first, so approval never lands on unread
@@ -52,6 +57,14 @@ export function registerExitPlanModeTool(pi: ExtensionAPI, host: ExitPlanModeHos
 
 			const plan = getPlan();
 			const filePath = getPlanFilePath();
+			// Read at return time: the slug may be named during this call.
+			const structuredResult = (
+				status: ExitPlanModeStructuredResult["status"],
+				kickoff: ExitPlanModeStructuredResult["kickoff"],
+			): ExitPlanModeStructuredResult => {
+				const repoPlanSlug = host.getPlanRepoSlug();
+				return { status, planFilePath: filePath, headless: !ctx.hasUI, kickoff, ...(repoPlanSlug ? { repoPlanSlug } : {}) };
+			};
 
 			if (!plan || plan.trim() === "") {
 				return {
@@ -95,6 +108,7 @@ export function registerExitPlanModeTool(pi: ExtensionAPI, host: ExitPlanModeHos
 							text: buildImplementationKickoffMessage(plan, filePath),
 						},
 					],
+					structuredContent: structuredResult("approved", "inline"),
 				};
 			}
 
@@ -154,10 +168,15 @@ export function registerExitPlanModeTool(pi: ExtensionAPI, host: ExitPlanModeHos
 					return {
 						details: undefined,
 						content: [{ type: "text", text: "Plan approved and saved. Plan mode has exited. Stop here — do not write files, run commands, or call any tools in this turn. A follow-up message will tell you to begin implementation." }],
+						structuredContent: structuredResult("approved", "follow_up"),
 					};
 				}
 
-				return { content: [{ type: "text", text: "User wants to keep refining the plan. Continue working on the plan file and call exit_plan_mode when ready." }], details: undefined };
+				return {
+					content: [{ type: "text", text: "User wants to keep refining the plan. Continue working on the plan file and call exit_plan_mode when ready." }],
+					details: undefined,
+					structuredContent: structuredResult("keep_planning", "none"),
+				};
 			}
 		},
 	});

package/src/planning/tools/mfPlanSubagent.ts

@@ -17,6 +17,7 @@ import { parseRef as parseModelRefLabel, type ThinkingLevel } from "../../shared
 import { activityLoopCount } from "../../ui/agentStatus.ts";
 import { showCancelOverlay } from "../../ui/cancelOverlay.ts";
 import { PLAN_SUBAGENT_NAMES } from "./shared.ts";
+import { buildSubagentStructuredResult, MF_PLAN_SUBAGENT_OUTPUT_SCHEMA } from "./structuredResults.ts";
 
 const CANCEL_HINT_WIDGET_KEY = "mf-plan-cancel";
 
@@ -38,7 +39,18 @@ export interface MfPlanSubagentHost {
 	setActiveCancelSession(session: CancelSession | undefined): void;
 }
 
-export function registerMfPlanSubagentTool(pi: ExtensionAPI, host: MfPlanSubagentHost): void {
+/**
+ * Test-only runner seam. The defaults are the real subprocess runners, which
+ * apply the read-only --tools allowlist and the provider env handshake.
+ */
+export type MfPlanSubagentDeps = {
+	runSingleAgent?: typeof runSingleAgent;
+	runParallelAgents?: typeof runParallelAgents;
+};
+
+export function registerMfPlanSubagentTool(pi: ExtensionAPI, host: MfPlanSubagentHost, deps: MfPlanSubagentDeps = {}): void {
+	const runSingle = deps.runSingleAgent ?? runSingleAgent;
+	const runParallel = deps.runParallelAgents ?? runParallelAgents;
 	pi.registerTool({
 		name: "mf_plan_subagent",
 		label: "Moa Plan Subagent",
@@ -51,6 +63,11 @@ export function registerMfPlanSubagentTool(pi: ExtensionAPI, host: MfPlanSubagen
 			`Default scope is "user" (from ${path.join(getAgentDir(), "agents")}).`,
 		].join(" "),
 
+		outputSchema: MF_PLAN_SUBAGENT_OUTPUT_SCHEMA,
+		// Installs agent files, writes temp prompts, and spawns paid subprocesses
+		// whose read-only boundary is cooperative (hence the tripwire), so no
+		// read-only claim; every call starts new, nondeterministic runs.
+		annotations: { readOnlyHint: false, idempotentHint: false },
 		// mf_plan_subagent can share a message with ask_user_question; marking it
 		// sequential means the questionnaire resolves first so its overlay never
 		// draws over a live questionnaire.
@@ -184,7 +201,7 @@ export function registerMfPlanSubagentTool(pi: ExtensionAPI, host: MfPlanSubagen
 						...agentExtensionOptions(t.agent),
 						signal: run.add(`${t.agent} #${i + 1}`, signal).signal,
 					}));
-					const results = await runParallelAgents(
+					const results = await runParallel(
 						ctx.cwd,
 						agents,
 						taskList,
@@ -208,7 +225,9 @@ export function registerMfPlanSubagentTool(pi: ExtensionAPI, host: MfPlanSubagen
 					);
 
 					// resolveOnAbort makes the runner resolve on abort; rethrow so a
-					// whole-turn abort (pi's ESC) keeps its original semantics.
+					// whole-turn abort (pi's ESC) keeps its original semantics, which also
+					// means it carries no structured result. A child abort the user did not
+					// ask for is reported per agent as "aborted".
 					if (signal?.aborted) throw new Error("Subagent was aborted");
 
 					const successCount = results.filter((r) => !isFailedResult(r)).length;
@@ -223,6 +242,8 @@ export function registerMfPlanSubagentTool(pi: ExtensionAPI, host: MfPlanSubagen
 					});
 
 					const header = `Parallel: ${successCount}/${results.length} succeeded${cancelledCount > 0 ? `, ${cancelledCount} cancelled by user` : ""}`;
+					// Subagent usage stays out of the tool result's `usage` so session
+					// token accounting is unchanged; it is reported per agent instead.
 					return {
 						details: undefined,
 						content: [
@@ -231,6 +252,7 @@ export function registerMfPlanSubagentTool(pi: ExtensionAPI, host: MfPlanSubagen
 								text: `${header}\n\n${summaries.join("\n\n---\n\n")}`,
 							},
 						],
+						structuredContent: buildSubagentStructuredResult("parallel", results),
 					};
 				} finally {
 					unsubscribeF4?.();
@@ -261,7 +283,7 @@ export function registerMfPlanSubagentTool(pi: ExtensionAPI, host: MfPlanSubagen
 					: undefined;
 				setCancelHint(ctx, "f4: cancel mf-plan agent");
 				try {
-					const result = await runSingleAgent(
+					const result = await runSingle(
 						ctx.cwd,
 						agents,
 						params.agent!,
@@ -277,22 +299,26 @@ export function registerMfPlanSubagentTool(pi: ExtensionAPI, host: MfPlanSubagen
 
 					if (signal?.aborted) throw new Error("Subagent was aborted");
 
+					const structuredContent = buildSubagentStructuredResult("single", [result]);
 					if (result.cancelled) {
 						return {
 							details: undefined,
 							content: [{ type: "text", text: "The user cancelled this subagent. Do not retry; continue planning with the information you already have." }],
+							structuredContent,
 						};
 					}
 					if (isFailedResult(result)) {
 						return {
 							details: undefined,
 							content: [{ type: "text", text: `Agent failed: ${getResultOutput(result)}` }],
+							structuredContent,
 							isError: true,
 						};
 					}
 					return {
 						details: undefined,
 						content: [{ type: "text", text: getFinalOutput(result.messages) || "(no output)" }],
+						structuredContent,
 					};
 				} finally {
 					unsubscribeF4?.();

package/src/planning/tools/shared.ts

@@ -17,3 +17,4 @@ export const PLAN_ONLY_REGISTERED_TOOLS = ["write_plan", "exit_plan_mode", "mf_p
 export const PLAN_SUBAGENT_NAMES = new Set(["moa-explore", "mf-plan"]);
 export const PLAN_MODE_CONTEXT_TYPE = "mf-plan-context";
 export const PLAN_EXIT_CONTEXT_TYPE = "mf-plan-exit";
+export const VERIFICATION_PENDING_CONTEXT_TYPE = "mf-plan-verification-pending";

package/src/planning/tools/structuredResults.ts

@@ -0,0 +1,161 @@
+/**
+ * Output schemas and structured results for the plan-mode tools (pi 0.99
+ * `outputSchema` / `structuredContent`).
+ *
+ * These values are not model-facing and are not saved in the session: pi sends
+ * only `content` to the model and leaves `structuredContent` out of the
+ * persisted tool-result message. They reach live programmatic consumers only —
+ * `tool_execution_end` events (RPC/JSON harnesses), `tool_result` handlers, and
+ * codemode scripts. Each tool's text `content` is unchanged and comes from the
+ * same `isFailedResult` / `getResultOutput` / `truncateOutput` calls as the
+ * values here, so the two cannot disagree.
+ *
+ * `classifySubagentResult` is the one status derivation over `SingleResult`;
+ * any other consumer of runner results can import it.
+ */
+
+import { Type, type Static } from "typebox";
+
+import { getResultOutput, isFailedResult, truncateOutput, type SingleResult } from "../../runtime/results.ts";
+
+const SubagentUsageSchema = Type.Object({
+	input: Type.Number({ description: "Input tokens" }),
+	output: Type.Number({ description: "Output tokens" }),
+	cacheRead: Type.Number({ description: "Cache-read tokens" }),
+	cacheWrite: Type.Number({ description: "Cache-write tokens" }),
+	cacheWrite1h: Type.Number({ description: "One-hour cache-write tokens" }),
+	cost: Type.Number({ description: "Total cost reported by the provider" }),
+	turns: Type.Number({ description: "Assistant turns" }),
+	toolCalls: Type.Number({ description: "Tool calls the agent made" }),
+	contextTokens: Type.Optional(Type.Number({ description: "Context size of the latest turn, when reported" })),
+}, { additionalProperties: false, description: "Token usage and cost the runner recorded for the agent" });
+
+const SubagentAgentResultSchema = Type.Object({
+	agent: Type.String({ description: "Agent name" }),
+	status: Type.Union([
+		Type.Literal("completed"),
+		Type.Literal("failed"),
+		Type.Literal("cancelled"),
+		Type.Literal("aborted"),
+	], { description: "cancelled: stopped by the user; aborted: the child stopped without a user cancel; failed: nonzero exit, provider error, or no messages" }),
+	exitCode: Type.Number({ description: "Child process exit code" }),
+	stopReason: Type.Optional(Type.String({ description: "Stop reason of the agent's last assistant message" })),
+	model: Type.Optional(Type.String({ description: "Model the agent ran on" })),
+	output: Type.String({ description: "Final answer, or the error for an agent that did not complete, capped at 50 KB" }),
+	truncated: Type.Boolean({ description: "Whether `output` was cut at the 50 KB cap" }),
+	usage: SubagentUsageSchema,
+}, { additionalProperties: false });
+
+export const MF_PLAN_SUBAGENT_OUTPUT_SCHEMA = Type.Object({
+	mode: Type.Union([Type.Literal("single"), Type.Literal("parallel")], { description: "single: one agent from agent + task; parallel: the tasks array" }),
+	status: Type.Union([
+		Type.Literal("completed"),
+		Type.Literal("partial"),
+		Type.Literal("failed"),
+		Type.Literal("cancelled"),
+		Type.Literal("aborted"),
+	], { description: "completed: every agent completed; partial: some did; otherwise failed, aborted, or cancelled, in that order of precedence" }),
+	total: Type.Number({ description: "Agents requested" }),
+	succeeded: Type.Number({ description: "Agents that completed" }),
+	failed: Type.Number({ description: "Agents that failed" }),
+	cancelled: Type.Number({ description: "Agents the user cancelled" }),
+	aborted: Type.Number({ description: "Agents that stopped without a user cancel" }),
+	results: Type.Array(SubagentAgentResultSchema, { description: "One entry per requested agent, in request order" }),
+}, { additionalProperties: false });
+
+export const WRITE_PLAN_OUTPUT_SCHEMA = Type.Object({
+	status: Type.Literal("written", { description: "The plan file was written" }),
+	filePath: Type.String({ description: "Plan file whose content was replaced" }),
+	length: Type.Number({ description: "Length of the written plan in characters" }),
+}, { additionalProperties: false });
+
+export const ENTER_PLAN_MODE_OUTPUT_SCHEMA = Type.Object({
+	status: Type.Literal("entered", { description: "Plan mode is now on" }),
+	mode: Type.Literal("single", { description: "The tool always starts single-model planning; MoA planning starts from /mf-plan" }),
+	reentry: Type.Boolean({ description: "Whether a plan file already existed, so planning continues it" }),
+	planFilePath: Type.String({ description: "Plan file write_plan writes to" }),
+}, { additionalProperties: false });
+
+export const EXIT_PLAN_MODE_OUTPUT_SCHEMA = Type.Object({
+	status: Type.Union([Type.Literal("approved"), Type.Literal("keep_planning")], { description: "approved: plan mode has exited; keep_planning: the user sent the plan back and plan mode is still on" }),
+	planFilePath: Type.String({ description: "Plan file that was reviewed" }),
+	headless: Type.Boolean({ description: "Whether the plan was auto-approved without a UI (MOA_PLAN_AUTO_APPROVE=1)" }),
+	kickoff: Type.Union([
+		Type.Literal("inline"),
+		Type.Literal("follow_up"),
+		Type.Literal("none"),
+	], { description: "inline: this result is the implementation kickoff; follow_up: the kickoff is queued as the next user message; none: no implementation was started" }),
+	repoPlanSlug: Type.Optional(Type.String({ description: "Name of the plan's copies under .pi/mf-plan/" })),
+}, { additionalProperties: false });
+
+export type MfPlanSubagentStructuredResult = Static<typeof MF_PLAN_SUBAGENT_OUTPUT_SCHEMA>;
+export type SubagentAgentResult = Static<typeof SubagentAgentResultSchema>;
+export type SubagentAgentStatus = SubagentAgentResult["status"];
+export type WritePlanStructuredResult = Static<typeof WRITE_PLAN_OUTPUT_SCHEMA>;
+export type EnterPlanModeStructuredResult = Static<typeof ENTER_PLAN_MODE_OUTPUT_SCHEMA>;
+export type ExitPlanModeStructuredResult = Static<typeof EXIT_PLAN_MODE_OUTPUT_SCHEMA>;
+
+/**
+ * A user cancel wins over the stop reason it produces; an `aborted` stop
+ * without one is a child abort nobody asked for. The runner marks every
+ * cancelled result failed, so `completed` is exactly `!isFailedResult`.
+ */
+export function classifySubagentResult(result: SingleResult): SubagentAgentStatus {
+	if (result.cancelled) return "cancelled";
+	if (result.stopReason === "aborted") return "aborted";
+	return isFailedResult(result) ? "failed" : "completed";
+}
+
+function aggregateStatus(statuses: readonly SubagentAgentStatus[]): MfPlanSubagentStructuredResult["status"] {
+	const completed = statuses.filter((status) => status === "completed").length;
+	if (completed === statuses.length) return "completed";
+	if (completed > 0) return "partial";
+	if (statuses.includes("failed")) return "failed";
+	if (statuses.includes("aborted")) return "aborted";
+	return "cancelled";
+}
+
+function toAgentResult(result: SingleResult): SubagentAgentResult {
+	const fullOutput = getResultOutput(result);
+	const output = truncateOutput(fullOutput);
+	const { usage } = result;
+	return {
+		agent: result.agent,
+		status: classifySubagentResult(result),
+		exitCode: result.exitCode,
+		...(result.stopReason ? { stopReason: result.stopReason } : {}),
+		...(result.model ? { model: result.model } : {}),
+		output,
+		truncated: output !== fullOutput,
+		usage: {
+			input: usage.input,
+			output: usage.output,
+			cacheRead: usage.cacheRead,
+			cacheWrite: usage.cacheWrite,
+			cacheWrite1h: usage.cacheWrite1h,
+			cost: usage.cost,
+			turns: usage.turns,
+			toolCalls: usage.toolCalls,
+			...(usage.contextTokens !== undefined ? { contextTokens: usage.contextTokens } : {}),
+		},
+	};
+}
+
+/** Results stay in request order; a single-mode run's status is its agent's status. */
+export function buildSubagentStructuredResult(
+	mode: MfPlanSubagentStructuredResult["mode"],
+	results: readonly SingleResult[],
+): MfPlanSubagentStructuredResult {
+	const entries = results.map(toAgentResult);
+	const count = (status: SubagentAgentStatus): number => entries.filter((entry) => entry.status === status).length;
+	return {
+		mode,
+		status: aggregateStatus(entries.map((entry) => entry.status)),
+		total: entries.length,
+		succeeded: count("completed"),
+		failed: count("failed"),
+		cancelled: count("cancelled"),
+		aborted: count("aborted"),
+		results: entries,
+	};
+}

package/src/planning/tools/writePlan.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
 import { getPlanFilePath, writePlan } from "../planFile.ts";
+import { WRITE_PLAN_OUTPUT_SCHEMA } from "./structuredResults.ts";
 
 export function registerWritePlanTool(pi: ExtensionAPI, isEnabled: () => boolean): void {
 	pi.registerTool({
@@ -11,6 +12,9 @@ export function registerWritePlanTool(pi: ExtensionAPI, isEnabled: () => boolean
 		parameters: Type.Object({
 			content: Type.String({ description: "The full content to write to the plan file (replaces existing content)" }),
 		}),
+		outputSchema: WRITE_PLAN_OUTPUT_SCHEMA,
+		// Replaces the whole plan file; the same content yields a byte-identical file.
+		annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
 
 		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
 			if (!isEnabled()) {
@@ -27,6 +31,7 @@ export function registerWritePlanTool(pi: ExtensionAPI, isEnabled: () => boolean
 			return {
 				content: [{ type: "text", text: `Plan written to ${filePath} (${params.content.length} chars)` }],
 				details: { filePath, length: params.content.length },
+				structuredContent: { status: "written", filePath, length: params.content.length },
 			};
 		},
 	});

package/src/runtime/results.ts

@@ -92,6 +92,24 @@ export function getResultOutput(result: { exitCode: number; stopReason?: string;
 	return getFinalOutput(result.messages) || "(no output)";
 }
 
+/**
+ * Longest failure message kept for a status row. Generous enough that a
+ * provider's JSON error payload survives whole for a progress table to wrap
+ * across several lines, bounded so a multi-KB stderr dump cannot crowd out the
+ * table it renders in.
+ */
+const MAX_STATUS_DETAIL_CHARS = 500;
+
+/**
+ * Collapse an agent failure into one bounded line for a progress row. Runs of
+ * whitespace — newlines included — are flattened because the row is laid out as
+ * a single line before its surface wraps it to the available width.
+ */
+export function statusDetail(output: string): string {
+	const collapsed = output.replace(/\s+/g, " ").trim();
+	return collapsed.length <= MAX_STATUS_DETAIL_CHARS ? collapsed : `${collapsed.slice(0, MAX_STATUS_DETAIL_CHARS - 1)}…`;
+}
+
 export function truncateOutput(output: string): string {
 	const maxBytes = 50 * 1024;
 	const bytes = Buffer.from(output, "utf8");