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

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [0.4.1]
+
+### Added
+
+- `write_plan`, `enter_plan_mode`, `exit_plan_mode`, and `mf_plan_subagent` now declare a pi 0.99 `outputSchema` and return matching `structuredContent` for RPC/JSON consumers, `tool_result` handlers, and codemode scripts: per-agent status, exit code, stop reason, usage, and capped output for subagent runs, and the approval outcome and kickoff route for plan exit. Model-facing text is unchanged.
+- The same four tools now declare MCP-style `annotations`, so permission extensions see accurate destructive and idempotent hints. None claims to be read-only.
+
+### Changed
+
+- Updated all four pi development dependencies from 0.87.0 to 0.99.2.
+- Plan-only tools stay out of normal mode by being removed from the active tool set, not through pi 0.99's `prepareLoadout`, which leaves hidden tools active and callable.
+
+### Fixed
+
+- Plan-only tools are now also removed on the first turn after leaving plan mode. Previously the exit-reminder turn skipped the leak repair, so a leaked `write_plan`, `exit_plan_mode`, or `mf_plan_subagent` stayed declared for that turn.
+
 ## [0.3.0]
 
 ### Added

package/README.md

@@ -230,6 +230,8 @@ Outside plan mode, one additional tool is exposed:
 |------|-------------|
 | `enter_plan_mode` | Lets the agent enter plan mode itself when asked for a design or plan. Takes the single-model path on the current session model — no pickers, no MoA. Exit and approval work exactly as if the user had invoked `/mf-plan`. |
 
+All four tools declare pi 0.99 `annotations`, and none claims to be read-only: `write_plan` is `destructiveHint: true, idempotentHint: true`, `exit_plan_mode` is `destructiveHint: true, idempotentHint: false`, `mf_plan_subagent` is `idempotentHint: false`, and `enter_plan_mode` sets only `readOnlyHint: false`. Under the example permission policy in pi's extension docs they are confirmed exactly as before. Each also declares an `outputSchema` and returns matching `structuredContent` for programmatic consumers (RPC/JSON `tool_execution_end` events, `tool_result` handlers, and codemode scripts); for `mf_plan_subagent` that is each agent's status, exit code, stop reason, usage, and output capped at 50 KB. The model-facing text is unchanged, and pi does not save structured values in the session.
+
 ## Subagents
 
 Seven agent definitions are auto-installed to `~/.pi/agent/agents/` on first run (won't overwrite existing files). Two belong to the single-model workflow, three to MoA planning, one to the independent opinion flow, and one to the debate flow:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@underactive/pi-topping-moa-fusion",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Pi extension implementing /mf-plan — Claude Code-style 5-phase plan mode with a Mixture-of-Agents proposer/synthesizer pipeline.",
   "keywords": [
     "pi-package",
@@ -50,10 +50,10 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.87.0",
-    "@earendil-works/pi-ai": "0.87.0",
-    "@earendil-works/pi-coding-agent": "0.87.0",
-    "@earendil-works/pi-tui": "0.87.0",
+    "@earendil-works/pi-agent-core": "0.99.2",
+    "@earendil-works/pi-ai": "0.99.2",
+    "@earendil-works/pi-coding-agent": "0.99.2",
+    "@earendil-works/pi-tui": "0.99.2",
     "@types/node": "^24.0.0",
     "typebox": "^1.3.3",
     "typescript": "^5.8.0"

package/src/planning/planMode.ts

@@ -286,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));
@@ -696,6 +722,9 @@ export function createPlanModeController(pi: ExtensionAPI) {
 		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 } };
 			}

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/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 },
 			};
 		},
 	});