@underactive/pi-topping-moa-fusion 0.1.0

package/src/planning/tools/enterPlanMode.ts

@@ -0,0 +1,165 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isKeyRelease, Key, matchesKey } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+import { installShippedAgents } from "../../agents/authoritative.ts";
+import { loadMoaConfig, saveMoaConfig } from "../../config/settings.ts";
+import { runMoaOrchestration } from "../../moa/orchestration.ts";
+import type { MfPlanInfo } from "../../moa/planInfo.ts";
+import type { MoaRunHost } from "../../moa/runContext.ts";
+import type { CancelSession } from "../../runtime/cancelRun.ts";
+import { modelRefLabel, TRIGGER_TURN, type ModelRef, type ThinkingLevel } from "../../shared/modelRefs.ts";
+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 { isAskUserQuestionInstalled } from "../askUserQuestion.ts";
+import { buildPlanModeInstructions, buildPlanModeReentryInstructions } from "../instructions.ts";
+
+export interface InteractivePlanModeHost {
+	beginInteractive(ctx: ExtensionContext): void;
+	abortPlanMode(ctx: ExtensionContext): void;
+	currentThinkingLevel(): ThinkingLevel;
+	getLastReentryState(): boolean;
+	getActiveObserveSession(): { overlayOpen: boolean } | undefined;
+	openCancelOverlayIfActive(ctx: ExtensionContext): boolean;
+	setActiveCancelSession(session: CancelSession | undefined): void;
+	saveSubmittedPlanPrompt(ctx: ExtensionContext, prompt: string): Promise<void>;
+	clearActiveRunMoaInfo(): void;
+	setActiveRunMoaInfo(info: MfPlanInfo | undefined): void;
+	applyImplementingSelection(ctx: ExtensionContext, selection: { ref: ModelRef; thinking: ThinkingLevel }, notice: string): Promise<void>;
+	moaRunHost: MoaRunHost;
+}
+
+export async function runInteractivePlanMode(
+	pi: ExtensionAPI,
+	host: InteractivePlanModeHost,
+	ctx: ExtensionContext,
+	initialPrompt?: string,
+): Promise<void> {
+	host.beginInteractive(ctx);
+	if (!ctx.hasUI) {
+		ctx.ui.notify("Plan mode enabled. Read-only exploration with parallel subagents.");
+		return;
+	}
+	if (!loadMoaConfig().agentDefaultsConfigured) {
+		installShippedAgents();
+		if (!await showMoaSetup(ctx, host.currentThinkingLevel(), { firstRun: true })) {
+			host.abortPlanMode(ctx);
+			ctx.ui.notify("Setup cancelled — plan mode not started. Run /mf-plan-settings to configure agents and rosters.", "warning");
+			return;
+		}
+	}
+
+	// While the plan-prompt flow is live, ESC opens the cancel overlay —
+	// but only while subagent processes are actually in flight
+	// (session.run is set during MoA fan-out/synthesis).
+	// Whenever nothing is running the listener passes ESC through, so the
+	// editor, the model pickers and the review overlay keep their normal
+	// ESC behavior.
+	const session: CancelSession = { title: "Plan agents", run: undefined, overlayOpen: false };
+	host.setActiveCancelSession(session);
+	const unsubscribeEsc = ctx.mode === "tui"
+		? ctx.ui.onTerminalInput((data) => {
+			// Terminal input listeners run ahead of pi's key-release filter, so under
+			// the Kitty keyboard protocol the ESC *release* arrives here a tick after
+			// the press closed an overlay and cleared `overlayOpen` — reopening it
+			// instantly. Only a key press may open the overlay.
+			if (isKeyRelease(data) || !matchesKey(data, Key.escape)) return undefined;
+			if (host.getActiveObserveSession()?.overlayOpen) return undefined;
+			if (session.overlayOpen) return undefined;
+			if (!session.run) return undefined;
+			return host.openCancelOverlayIfActive(ctx) ? { consume: true } : undefined;
+		})
+		: undefined;
+	try {
+		let prefill = host.getLastReentryState() ? getPlan() ?? "" : "";
+		let skipEditorOnce = Boolean(initialPrompt?.trim());
+		while (true) {
+			let prompt: string | undefined;
+			if (skipEditorOnce) {
+				prompt = initialPrompt!.trim();
+				skipEditorOnce = false;
+				initialPrompt = undefined;
+			} else prompt = await showPromptEditor(ctx, "Plan Mode — describe what you want to plan", prefill);
+			if (!prompt || !prompt.trim()) {
+				host.abortPlanMode(ctx);
+				ctx.ui.notify("Plan mode cancelled.");
+				return;
+			}
+			const trimmedPrompt = prompt.trim();
+			prefill = trimmedPrompt;
+			await host.saveSubmittedPlanPrompt(ctx, trimmedPrompt);
+			const pickerResult = await showMoaModelPicker(ctx, host.currentThinkingLevel());
+			if (!pickerResult || pickerResult.mode === "single") {
+				host.clearActiveRunMoaInfo();
+				if (pickerResult) {
+					const selection = await showImplementingModelPicker(ctx, host.currentThinkingLevel(), "Single model — choose the model and thinking level");
+					if (selection) await host.applyImplementingSelection(ctx, selection, `Using ${modelRefLabel(selection.ref)} for this plan.`);
+				}
+				ctx.ui.notify("Plan mode enabled. Processing your prompt...");
+				pi.sendUserMessage(trimmedPrompt, TRIGGER_TURN);
+				return;
+			}
+			const settings = loadMoaConfig();
+			const { proposers, synthesizer, implementer, verifier, proposerThinking, synthesizerThinking, implementerThinking, verifierThinking, thinkingSelections } = pickerResult;
+			saveMoaConfig({ ...settings, mode: "moa", proposers, synthesizer, implementer, verifier, thinkingOverrides: { ...settings.thinkingOverrides, ...thinkingSelections } });
+			host.setActiveRunMoaInfo({ proposers, synthesizer });
+			const outcome = await runMoaOrchestration(host.moaRunHost, ctx, trimmedPrompt, proposers, synthesizer, proposerThinking, synthesizerThinking, session, { implementer, implementerThinking, verifier, verifierThinking });
+			if (outcome === "cancelled") { session.closeOverlay?.(); continue; }
+			return;
+		}
+	} finally {
+		unsubscribeEsc?.();
+		host.setActiveCancelSession(undefined);
+	}
+}
+
+export interface EnterPlanModeHost {
+	isEnabled(): boolean;
+	enterFromTool(ctx: ExtensionContext, prompt: string | undefined): Promise<boolean>;
+}
+
+export function registerEnterPlanModeTool(pi: ExtensionAPI, host: EnterPlanModeHost): void {
+	pi.registerTool({
+		name: "enter_plan_mode",
+		label: "Enter Plan Mode",
+		description: [
+			"Enter plan mode to design an implementation before writing code.",
+			"Switches the session to read-only tools and runs the single-model planning workflow on the current session model.",
+			"Write the plan with write_plan, then call exit_plan_mode for user approval.",
+			"Use when the user asks for a plan, design, or implementation approach.",
+			"Mixture-of-Agents planning is not available through this tool — the user starts that with /mf-plan.",
+		].join(" "),
+		parameters: Type.Object({
+			plan_prompt: Type.Optional(
+				Type.String({ description: "Short description of what is being planned (used to name the plan file)" }),
+			),
+		}),
+		// 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.
+		executionMode: "sequential",
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			if (host.isEnabled()) {
+				return {
+					details: undefined,
+					content: [{ type: "text", text: "Already in plan mode. Continue planning and call exit_plan_mode when your plan is ready." }],
+					isError: true,
+				};
+			}
+
+			const reentry = await host.enterFromTool(ctx, params.plan_prompt?.trim());
+			ctx.ui.notify("Plan mode enabled by the agent (single model). Read-only until the plan is approved.");
+			const instructions = reentry ? buildPlanModeReentryInstructions() : buildPlanModeInstructions(isAskUserQuestionInstalled(pi));
+			return {
+				details: undefined,
+				content: [{
+					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}`,
+				}],
+			};
+		},
+	});
+}

package/src/planning/tools/exitPlanMode.ts

@@ -0,0 +1,159 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { summarizePlanPromptName } from "../../config/planName.ts";
+import { buildImplementationKickoffMessage } from "../../moa/implementationRetry.ts";
+import { stripSynthSections } from "../../moa/verdicts.ts";
+import { FOLLOW_UP } from "../../shared/modelRefs.ts";
+import type { MfPlanInfo, PlanReviewDecision } from "../../moa/planInfo.ts";
+import { showPlanReview } from "../../ui/planReviewOverlay.ts";
+import { ASK_USER_QUESTION_PENDING_MESSAGE } from "../askUserQuestion.ts";
+import { getPlan, getPlanFilePath, saveRepoPlanFile, writePlan } from "../planFile.ts";
+
+import type { ImplementationHandoff } from "../../moa/implementationRetry.ts";
+
+export interface ExitPlanModeHost {
+	pi: ExtensionAPI;
+	isEnabled(): boolean;
+	/** True while an ask_user_question questionnaire is waiting for the user. */
+	isAskUserQuestionActive(): boolean;
+	exitPlanMode(ctx: ExtensionContext): void;
+	getPlanRepoSlug(): string | undefined;
+	setPlanRepoSlug(slug: string): void;
+	persistState(): void;
+	getActiveRunMoaInfo(): MfPlanInfo | undefined;
+	saveApprovedPlanToRepo(ctx: ExtensionContext, plan: string): void;
+	getImplementationHandoff(): ImplementationHandoff | undefined;
+	setImplementationHandoff(handoff: ImplementationHandoff | undefined): void;
+	markImplementationPending(): void;
+}
+
+export function registerExitPlanModeTool(pi: ExtensionAPI, host: ExitPlanModeHost): void {
+	pi.registerTool({
+		name: "exit_plan_mode",
+		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({}),
+		// 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
+		// answers.
+		executionMode: "sequential",
+
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+			if (!host.isEnabled()) {
+				return {
+					details: undefined,
+					content: [{ type: "text", text: "You are not in plan mode. This tool is only for exiting plan mode after writing a plan. If your plan was already approved, continue with implementation." }],
+					isError: true,
+				};
+			}
+
+			const plan = getPlan();
+			const filePath = getPlanFilePath();
+
+			if (!plan || plan.trim() === "") {
+				return {
+					details: undefined,
+					content: [{ type: "text", text: `No plan content found at ${filePath}. Please write your plan to this file using the write_plan tool before calling exit_plan_mode.` }],
+					isError: true,
+				};
+			}
+
+			// A waiting questionnaire must be answered before the plan is approved.
+			// Placed before summarization and the UI branch so it never triggers a
+			// plan-name model call and cannot fire in headless runs (rpiv strips its
+			// tool there, so the flag stays false).
+			if (host.isAskUserQuestionActive()) {
+				return { details: undefined, content: [{ type: "text", text: ASK_USER_QUESTION_PENDING_MESSAGE }], isError: true };
+			}
+
+			// Non-interactive mode: auto-approve requires explicit opt-in
+			if (!ctx.hasUI) {
+				if (process.env.MOA_PLAN_AUTO_APPROVE !== "1") {
+					return {
+						details: undefined,
+						content: [{ type: "text", text: "Auto-approve is disabled in headless mode. Set MOA_PLAN_AUTO_APPROVE=1 to enable, or refine the plan further and try again." }],
+						isError: true,
+					};
+				}
+				host.exitPlanMode(ctx);
+				host.setImplementationHandoff({
+					plan,
+					planFilePath: filePath,
+					repoPlanSlug: host.getPlanRepoSlug(),
+					model: ctx.model,
+					timestamp: Date.now(),
+				});
+				host.markImplementationPending();
+				return {
+					details: undefined,
+					content: [
+						{
+							type: "text",
+							text: buildImplementationKickoffMessage(plan, filePath),
+						},
+					],
+				};
+			}
+
+			if (!host.getPlanRepoSlug()) {
+				host.setPlanRepoSlug(await summarizePlanPromptName(ctx, plan));
+				host.persistState();
+			}
+
+			// Interactive TUI: show the proposed plan in a scrollable review overlay.
+			// RPC has UI primitives but no terminal custom component, so keep the select fallback there.
+			let currentPlan = plan;
+			while (true) {
+				let decision: PlanReviewDecision;
+				if (ctx.mode === "tui") {
+					decision = await showPlanReview(ctx, currentPlan, host.getActiveRunMoaInfo(), host.getPlanRepoSlug());
+				} else {
+					const choice = await ctx.ui.select("Exit plan mode?", ["Approve — start implementing", "Keep planning", "Edit plan"]);
+					decision = choice?.startsWith("Approve") ? "approve" : choice?.startsWith("Edit") ? "edit" : "keep";
+				}
+
+				if (decision === "edit") {
+					const edited = await ctx.ui.editor("Edit Plan", currentPlan);
+					if (edited?.trim()) {
+						currentPlan = stripSynthSections(edited.trim());
+						writePlan(currentPlan);
+						const repoPlanSlug = host.getPlanRepoSlug();
+						if (repoPlanSlug) saveRepoPlanFile(currentPlan, ctx.cwd, repoPlanSlug, "plan");
+					}
+					continue;
+				}
+				if (decision === "approve") {
+					if (ctx.mode !== "tui") host.saveApprovedPlanToRepo(ctx, currentPlan);
+					host.exitPlanMode(ctx);
+					host.setImplementationHandoff({
+						plan: currentPlan,
+						planFilePath: filePath,
+						repoPlanSlug: host.getPlanRepoSlug(),
+						model: ctx.model,
+						timestamp: Date.now(),
+					});
+					host.markImplementationPending();
+					// Deliver the go-ahead as a follow-up (a fresh turn) rather than in this
+					// tool result. An agentic-bridge query is created read-only for the whole
+					// planning turn; returning "start coding" here just resumes that read-only
+					// query. Instead we tell the model to STOP so the read-only query ends,
+					// then the queued follow-up runs as a new, full-access query that re-reads
+					// the restored env. (terminate:true is worse: the bridge replays the
+					// trailing tool result as a continuation that inherits the read-only tools.)
+					host.pi.sendUserMessage(
+						buildImplementationKickoffMessage(currentPlan, filePath),
+						FOLLOW_UP,
+					);
+					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." }],
+					};
+				}
+
+				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 };
+			}
+		},
+	});
+}

package/src/planning/tools/mfPlanSubagent.ts

@@ -0,0 +1,311 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { isKeyRelease, Key, matchesKey } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import * as path from "node:path";
+
+import { installShippedAgents, shippedAgentsDir, withAuthoritativeMoaAgents } from "../../agents/authoritative.ts";
+import { discoverAgents, parseAgentFile } from "../../agents/discovery.ts";
+import { modelExtensionOptions } from "../../moa/modelRuntime.ts";
+import { CancelRun, type CancelRowExtras, type CancelSession } from "../../runtime/cancelRun.ts";
+import { MutationTripwire, formatMutationWarning } from "../../runtime/mutationTripwire.ts";
+import { getFinalOutput, getResultOutput, isFailedResult, truncateOutput } from "../../runtime/results.ts";
+import { runParallelAgents, runSingleAgent } from "../../runtime/runner.ts";
+import { parseRef as parseModelRefLabel, type ThinkingLevel } from "../../shared/modelRefs.ts";
+import { activityLoopCount } from "../../ui/agentStatus.ts";
+import { showCancelOverlay } from "../../ui/cancelOverlay.ts";
+import { PLAN_SUBAGENT_NAMES } from "./shared.ts";
+
+const CANCEL_HINT_WIDGET_KEY = "mf-plan-cancel";
+
+/** Mount the F4 cancel hint above the editor while subagents are in flight; pass undefined to clear. */
+function setCancelHint(ctx: ExtensionContext, text: string | undefined): void {
+	ctx.ui.setWidget(
+		CANCEL_HINT_WIDGET_KEY,
+		text ? [ctx.ui.theme.fg("dim", text)] : undefined,
+		{ placement: "aboveEditor" },
+	);
+}
+
+export interface MfPlanSubagentHost {
+	isEnabled(): boolean;
+	/** True while an ask_user_question questionnaire is waiting for the user. */
+	isAskUserQuestionActive(): boolean;
+	currentThinkingLevel(): ThinkingLevel;
+	getActiveCancelSession(): CancelSession | undefined;
+	setActiveCancelSession(session: CancelSession | undefined): void;
+}
+
+export function registerMfPlanSubagentTool(pi: ExtensionAPI, host: MfPlanSubagentHost): void {
+	pi.registerTool({
+		name: "mf_plan_subagent",
+		label: "Moa Plan Subagent",
+		description: [
+			"ONLY usable inside /mf-plan plan mode — errors in any other context.",
+			"For general-purpose delegation outside plan mode, use the subagent tool instead.",
+			"Delegate exploration and planning tasks to specialized subagents with isolated context.",
+			"Modes: single (agent + task), parallel (tasks array).",
+			"Agents: moa-explore (fast codebase recon), mf-plan (implementation planning).",
+			`Default scope is "user" (from ${path.join(getAgentDir(), "agents")}).`,
+		].join(" "),
+
+		// 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.
+		executionMode: "sequential",
+		parameters: Type.Object({
+			agent: Type.Optional(Type.String({ description: "Name of the agent to invoke (for single mode)" })),
+			task: Type.Optional(Type.String({ description: "Task to delegate (for single mode)" })),
+			tasks: Type.Optional(
+				Type.Array(
+					Type.Object({
+						agent: Type.String({ description: "Name of the agent to invoke" }),
+						task: Type.String({ description: "Task to delegate to the agent" }),
+					}),
+					{ description: "Array of {agent, task} for parallel execution" },
+				),
+			),
+			agentScope: Type.Optional(
+				StringEnum(["user", "project", "both"] as const, {
+					description: 'Which agent directories to use. Default: "user".',
+					default: "user",
+				}),
+			),
+		}),
+
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			if (!host.isEnabled()) {
+				return {
+					details: undefined,
+					content: [{ type: "text", text: "Error: mf_plan_subagent is only available in plan mode." }],
+					isError: true,
+				};
+			}
+
+			const requestedAgents = params.tasks?.length
+				? params.tasks.map((task) => task.agent)
+				: params.agent ? [params.agent] : [];
+			const unsupportedAgent = requestedAgents.find((name) => !PLAN_SUBAGENT_NAMES.has(name));
+			if (unsupportedAgent) {
+				return {
+					details: undefined,
+					content: [{ type: "text", text: `Agent "${unsupportedAgent}" is not allowed in plan mode. Use only moa-explore or mf-plan.` }],
+					isError: true,
+				};
+			}
+
+			const agentScope = (params.agentScope ?? "user") as "user" | "project" | "both";
+			// Defensive re-install (matches runMoaOrchestration): guarantees
+			// moa-explore.md/mf-plan.md exist on disk even right after an in-session update.
+			installShippedAgents();
+			const discovery = discoverAgents(ctx.cwd, agentScope);
+			const agents = withAuthoritativeMoaAgents(discovery.agents, shippedAgentsDir());
+
+			// Guard moa-explore and mf-plan from repo-discoverable overrides:
+			// a committed agents/moa-explore.md can carry a malicious prompt.
+			// User-installed copies (source: "user") are untouched.
+			for (const name of PLAN_SUBAGENT_NAMES) {
+				const index = agents.findIndex((a) => a.name === name);
+				if (index >= 0 && agents[index]!.source === "project") {
+					const shipped = parseAgentFile(path.join(shippedAgentsDir(), `${name}.md`), "user");
+					if (shipped) agents[index] = shipped;
+					else agents.splice(index, 1);
+				}
+			}
+
+			// mf-plan follows the session model the user picked (both the
+			// single-model picker and the MoA implementing picker route through
+			// pi.setModel), so planning quality tracks that choice. Frontmatter is
+			// only a fallback; moa-explore stays on its own configured model.
+			const sessionModel = ctx.model;
+			const planOverride = sessionModel
+				? { model: `${sessionModel.provider}/${sessionModel.id}`, thinking: host.currentThinkingLevel() }
+				: undefined;
+			const overrideFor = (agentName: string) => (agentName === "mf-plan" ? planOverride : undefined);
+
+			// An agent whose effective model belongs to an extension-registered
+			// provider (claude-bridge, cursor-bridge) cannot resolve in a child that
+			// spawns with --no-extensions. Same opt-in the MoA fan-out already does;
+			// built-in and bare ids fall through to no extension loading.
+			const agentExtensionOptions = (agentName: string): { loadExtensions?: boolean; extensionPath?: string } => {
+				const model = overrideFor(agentName)?.model ?? agents.find((agent) => agent.name === agentName)?.model;
+				return model ? modelExtensionOptions(ctx, parseModelRefLabel(model)) : {};
+			};
+
+			// Same cooperative-boundary tripwire as the MoA orchestration: explore/
+			// plan children are spawned read-only, but agentic provider bridges can
+			// bypass pi's tool loop — detect and surface any working-tree change.
+			const tripwire = new MutationTripwire();
+			await tripwire.arm(ctx.cwd);
+			const warnIfMutated = async (): Promise<void> => {
+				const changed = await tripwire.check(ctx.cwd);
+				if (changed.length > 0) ctx.ui.notify(formatMutationWarning("plan-mode subagents", changed), "error");
+			};
+
+			const hasTasks = (params.tasks?.length ?? 0) > 0;
+			const hasSingle = Boolean(params.agent && params.task);
+
+			if (hasTasks) {
+				// Parallel mode — each task gets its own abort signal (combined
+				// with pi's turn signal) so F4 can kill one stuck agent
+				// while its siblings keep working.
+				const tasks = params.tasks!;
+				const run = new CancelRun();
+				const extras: CancelRowExtras[] = tasks.map(() => ({}));
+				const histories: string[][] = tasks.map(() => []);
+				const toolSession: CancelSession = {
+					title: "Plan subagents",
+					run,
+					getExtras: (i) => extras[i],
+					overlayOpen: false,
+				};
+				const prevSession = host.getActiveCancelSession();
+				host.setActiveCancelSession(toolSession);
+				const unsubscribeF4 = ctx.mode === "tui"
+					? ctx.ui.onTerminalInput((data) => {
+						if (isKeyRelease(data) || !matchesKey(data, Key.f4)) return undefined;
+						// A live questionnaire owns F4; pass the key through to it.
+						if (host.isAskUserQuestionActive()) return undefined;
+						if (toolSession.overlayOpen || !toolSession.run) return undefined;
+						toolSession.overlayOpen = true;
+						void showCancelOverlay(ctx, toolSession).finally(() => { toolSession.overlayOpen = false; });
+						return { consume: true };
+					})
+					: undefined;
+				setCancelHint(ctx, "f4: cancel mf-plan agents");
+				try {
+					const taskList = tasks.map((t, i) => ({
+						agent: t.agent,
+						task: t.task,
+						...overrideFor(t.agent),
+						...agentExtensionOptions(t.agent),
+						signal: run.add(`${t.agent} #${i + 1}`, signal).signal,
+					}));
+					const results = await runParallelAgents(
+						ctx.cwd,
+						agents,
+						taskList,
+						signal,
+						onUpdate,
+						(index, result) => {
+							run.settle(index, result.cancelled ? "cancelled" : isFailedResult(result) ? "error" : "done");
+						},
+						(index, result) => {
+							if (result.activity) {
+								histories[index].push(result.activity);
+								while (histories[index].length > 8) histories[index].shift();
+							}
+							extras[index] = {
+								contextTokens: result.usage.contextTokens,
+								activity: result.activity,
+								loopCount: activityLoopCount(result.activity, histories[index]),
+							};
+						},
+					);
+
+					// resolveOnAbort makes the runner resolve on abort; rethrow so a
+					// whole-turn abort (pi's ESC) keeps its original semantics.
+					if (signal?.aborted) throw new Error("Subagent was aborted");
+
+					const successCount = results.filter((r) => !isFailedResult(r)).length;
+					const cancelledCount = results.filter((r) => r.cancelled).length;
+					const summaries = results.map((r) => {
+						if (r.cancelled) {
+							return `### [${r.agent}] cancelled by user\n\nThe user cancelled this subagent before it finished. Do not retry it; proceed with the results from the other agents.`;
+						}
+						const output = truncateOutput(getResultOutput(r));
+						const status = isFailedResult(r) ? "failed" : "completed";
+						return `### [${r.agent}] ${status}\n\n${output}`;
+					});
+
+					const header = `Parallel: ${successCount}/${results.length} succeeded${cancelledCount > 0 ? `, ${cancelledCount} cancelled by user` : ""}`;
+					return {
+						details: undefined,
+						content: [
+							{
+								type: "text",
+								text: `${header}\n\n${summaries.join("\n\n---\n\n")}`,
+							},
+						],
+					};
+				} finally {
+					unsubscribeF4?.();
+					toolSession.closeOverlay?.();
+					host.setActiveCancelSession(prevSession);
+					setCancelHint(ctx, undefined);
+					await warnIfMutated();
+				}
+			}
+
+			if (hasSingle) {
+				// Single mode — one cancellable slot.
+				const run = new CancelRun();
+				const slot = run.add(params.agent!, signal);
+				const toolSession: CancelSession = { title: "Plan subagent", run, overlayOpen: false };
+				const prevSession = host.getActiveCancelSession();
+				host.setActiveCancelSession(toolSession);
+				const unsubscribeF4 = ctx.mode === "tui"
+					? ctx.ui.onTerminalInput((data) => {
+						if (isKeyRelease(data) || !matchesKey(data, Key.f4)) return undefined;
+						// A live questionnaire owns F4; pass the key through to it.
+						if (host.isAskUserQuestionActive()) return undefined;
+						if (toolSession.overlayOpen || !toolSession.run) return undefined;
+						toolSession.overlayOpen = true;
+						void showCancelOverlay(ctx, toolSession).finally(() => { toolSession.overlayOpen = false; });
+						return { consume: true };
+					})
+					: undefined;
+				setCancelHint(ctx, "f4: cancel mf-plan agent");
+				try {
+					const result = await runSingleAgent(
+						ctx.cwd,
+						agents,
+						params.agent!,
+						params.task!,
+						undefined,
+						slot.signal,
+						onUpdate,
+						overrideFor(params.agent!)?.model,
+						overrideFor(params.agent!)?.thinking,
+						{ ...agentExtensionOptions(params.agent!), resolveOnAbort: true },
+					);
+					run.settle(0, result.cancelled ? "cancelled" : isFailedResult(result) ? "error" : "done");
+
+					if (signal?.aborted) throw new Error("Subagent was aborted");
+
+					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." }],
+						};
+					}
+					if (isFailedResult(result)) {
+						return {
+							details: undefined,
+							content: [{ type: "text", text: `Agent failed: ${getResultOutput(result)}` }],
+							isError: true,
+						};
+					}
+					return {
+						details: undefined,
+						content: [{ type: "text", text: getFinalOutput(result.messages) || "(no output)" }],
+					};
+				} finally {
+					unsubscribeF4?.();
+					toolSession.closeOverlay?.();
+					host.setActiveCancelSession(prevSession);
+					setCancelHint(ctx, undefined);
+					await warnIfMutated();
+				}
+			}
+
+			const available = agents.map((a) => `${a.name} (${a.source})`).join(", ") || "none";
+			return {
+				details: undefined,
+				content: [{ type: "text", text: `Invalid parameters. Provide agent+task or tasks array. Available agents: ${available}` }],
+				isError: true,
+			};
+		},
+	});
+}

package/src/planning/tools/shared.ts

@@ -0,0 +1,19 @@
+export const PLAN_MODE_READ_ONLY_TOOLS = new Set<string>([
+	"read",
+	"grep",
+	"find",
+	"ls",
+	"fetch_markdown",
+	"lsp",
+	"memory_read",
+	"memory_search",
+	"memory_list",
+	"web_search",
+	"web_fetch",
+]);
+
+export const PLAN_MODE_CUSTOM_TOOLS = ["write_plan", "exit_plan_mode", "mf_plan_subagent", "ask_user_question"];
+export const PLAN_ONLY_REGISTERED_TOOLS = ["write_plan", "exit_plan_mode", "mf_plan_subagent"];
+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";