one-code-extension 0.4.0 → 0.5.0

package/extensions/plan-mode/index.ts

@@ -13,31 +13,53 @@
  * turn puts the block on the queue before the turn's next request — until
  * 2026-09-05 the mid-turn requests ran with no plan reminder while every edit
  * was denied "see the plan-mode reminder" (STEERING-REVIEW-2026-09-05 M3) —
- * and on before_agent_start, which covers a session that STARTS in plan mode
- * before this extension has seen a context (defaultMode: "plan"; permissions'
- * session_start runs first) and runs after every extension's session_start,
- * so restoring a previous path from the session branch never races a fresh
- * allocation.
+ * and on session_start, after restoring a previous path and its baseline.
+ * A session that STARTS in plan mode must install the block before the first
+ * prompt is stamped: before_agent_start is already too late to anchor it to
+ * that prompt. before_agent_start also re-announces the existing state.
  */
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { registerFormTool } from "../lib/tool-variants.ts";
 import { Type } from "typebox";
 import { DEFER_CHANNEL } from "../lib/deferred.ts";
 import { oneCodeStateDir } from "../lib/paths.ts";
 import { REMINDER_CHANNEL } from "../lib/reminders.ts";
+import { CONTEXT_BASELINE_CHANNEL, restoredContext } from "../lib/context-stack.ts";
+import { canShowCustomUi } from "../lib/headless-output.ts";
 import { ccToolRenderers, safeThemePaint } from "../lib/tui-render.ts";
+import { userDenialText } from "../lib/user-denial.ts";
 import type { PermissionMode } from "../permissions/matcher.ts";
 import { PERMISSION_STATUS_CHANNEL, type PermissionStatus } from "../permissions/modes.ts";
 import { buildPlanModeReminder } from "./reminder.ts";
 import { randomSlug } from "./slug.ts";
-import { clampOffset, decodeViewerKey, initialPlanChoice, type PlanChoice, renderPlanViewer, wrapPlanText } from "./viewer.ts";
+import {
+	approvedPlanText,
+	ENTER_PLAN_MODE_DESCRIPTION,
+	enteredPlanModeText,
+	enterPlanModeDescription,
+	EXIT_PLAN_MODE_DESCRIPTION,
+	exitedPlanModeText,
+} from "./texts.ts";
+import { createMarkdownProse } from "../subagents/prose.ts";
+import type { ProseRenderer } from "../subagents/panel-render.ts";
+import {
+	clampOffset,
+	decodeViewerKey,
+	initialPlanChoice,
+	KEEP_PLANNING_QUESTION,
+	type PlanChoice,
+	planLines,
+	renderPlanViewer,
+	runPlanApproval,
+	selectPlanChoice,
+} from "./viewer.ts";
 
-import { MODE_CHANNEL, PLAN_FILE_CHANNEL } from "../lib/plan-mode-channels.ts";
+import { MODE_CHANNEL, PLAN_FILE_CHANNEL, PLAN_FILE_ENTRY, planFileOnBranch } from "../lib/plan-mode-channels.ts";
+import { panelUi } from "../lib/panel-focus.ts";
 export { MODE_CHANNEL, PLAN_FILE_CHANNEL };
-/** Session entry type persisting the allocated path across resume/branch. */
-const PLAN_FILE_ENTRY = "one-code:plan-mode-file";
 
 const PLANS_DIR = () => join(oneCodeStateDir(), "plans");
 
@@ -64,16 +86,19 @@ export default function planModeExtension(pi: ExtensionAPI) {
 	 */
 	let modeBeforePlan: PermissionMode | undefined;
 	let planFilePath: string | undefined;
+	/**
+	 * Whether the plan file existed when plan mode came on, which picks Claude
+	 * Code's "Plan File Info" line. Fixed for the mode's whole run, so the sticky
+	 * block stays byte-identical turn after turn (plan-mode/reminder.ts);
+	 * cleared when the mode ends.
+	 */
+	let planExistedAtEntry: boolean | undefined;
 
 	/** Restore the branch's plan file, else allocate a fresh slug. */
 	const ensurePlanFile = (ctx: ExtensionContext): string => {
 		if (planFilePath) return planFilePath;
 
-		for (const entry of ctx.sessionManager.getBranch()) {
-			if (entry.type !== "custom" || entry.customType !== PLAN_FILE_ENTRY) continue;
-			const path = (entry.data as { path?: unknown } | undefined)?.path;
-			if (typeof path === "string") planFilePath = path;
-		}
+		planFilePath = planFileOnBranch(ctx.sessionManager.getBranch());
 		if (planFilePath) return planFilePath;
 
 		let path = join(PLANS_DIR(), `${randomSlug()}.md`);
@@ -86,17 +111,38 @@ export default function planModeExtension(pi: ExtensionAPI) {
 	};
 
 	/** Re-announce path + reminder; every-turn re-emits replace by key. */
-	const refresh = (ctx: ExtensionContext) => {
+	const refresh = (ctx: ExtensionContext, toolCallId?: string) => {
 		const path = ensurePlanFile(ctx);
+		planExistedAtEntry ??= existsSync(path);
+		pi.events.emit(CONTEXT_BASELINE_CHANNEL, { key: "plan-mode", value: { path, existed: planExistedAtEntry } });
 		pi.events.emit(PLAN_FILE_CHANNEL, { path });
 		pi.events.emit(REMINDER_CHANNEL, {
-			text: buildPlanModeReminder(path),
+			text: buildPlanModeReminder(path, planExistedAtEntry),
 			scope: "every-turn",
 			key: "permission-mode",
 			placement: "sticky-append",
+			toolCallId,
 		});
 	};
 
+	/**
+	 * pi-tui's Markdown renderer for the approval dialog, loaded on first use.
+	 * A failed load is not cached (the theme may not be ready yet); the dialog
+	 * then wraps the plan as plain text.
+	 */
+	let markdownLoad: Promise<ProseRenderer | undefined> | undefined;
+	const planMarkdown = (): Promise<ProseRenderer | undefined> =>
+		(markdownLoad ??= createMarkdownProse().catch(() => {
+			markdownLoad = undefined;
+			return undefined;
+		}));
+
+	/** Plan approvals the user dismissed without words: the turn stops once pi records their result. */
+	const abortAfterResult = new Set<string>();
+	pi.on("tool_execution_end", (event, ctx) => {
+		if (abortAfterResult.delete(event.toolCallId)) ctx.abort();
+	});
+
 	/** The last context seen, for a refresh triggered off the bus (no ctx of its own). */
 	let lastCtx: ExtensionContext | undefined;
 
@@ -106,17 +152,27 @@ export default function planModeExtension(pi: ExtensionAPI) {
 		const previous = currentMode;
 		currentMode = status.mode;
 		if (currentMode === "plan" && previous !== "plan") modeBeforePlan = previous as PermissionMode | undefined;
-		// Entering plan mode mid-turn: permissions' setMode has just dropped the
+		if (currentMode !== "plan") planExistedAtEntry = undefined;
+		// Entering plan mode mid-turn: permissions' setMode has just closed the
 		// shared "permission-mode" key (before broadcasting this status, so this
 		// re-add is not undone) and will announce the change on the next tool
 		// result; the standing block has to be back on the queue for that same
 		// request. The path is announced over PLAN_FILE_CHANNEL inside refresh,
 		// synchronously, so setMode's announcement can name it.
-		if (currentMode === "plan" && previous !== "plan" && lastCtx) refresh(lastCtx);
+		if (currentMode === "plan" && previous !== "plan" && lastCtx) refresh(lastCtx, status.toolCallId);
 	});
 
 	pi.on("session_start", (_event, ctx) => {
 		lastCtx = ctx;
+		const restored = restoredContext(pi.events);
+		const baseline = restored?.baselines["plan-mode"] as { path?: unknown; existed?: unknown } | undefined;
+		const path = planFileOnBranch(ctx.sessionManager.getBranch());
+		if (currentMode === "plan" && restored?.baselines["permission-mode"] === "plan" &&
+			path && baseline?.path === path && typeof baseline.existed === "boolean") {
+			planFilePath = path;
+			planExistedAtEntry = baseline.existed;
+		}
+		if (currentMode === "plan") refresh(ctx);
 	});
 
 	pi.on("before_agent_start", (_event, ctx) => {
@@ -124,42 +180,45 @@ export default function planModeExtension(pi: ExtensionAPI) {
 		if (currentMode === "plan") refresh(ctx);
 	});
 
-	pi.registerTool({
-		name: "enter_plan_mode",
-		label: "Enter plan mode",
-		...ccToolRenderers("Enter plan mode"),
-		description:
-			"Enter plan mode: read-only investigation to design an approach before changing anything. Most tasks do not need it.\n" +
-			"For a small or clearly-scoped change, act directly instead. Enter plan mode only for multi-file work whose design is genuinely unclear, or when the user asks for a plan. In plan mode only read-only tools are available, plus one writable file: the plan file whose path you are told, where you build the plan incrementally.",
-		parameters: Type.Object({}),
-		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
-			pi.events.emit(MODE_CHANNEL, { mode: "plan" });
-			// setMode broadcasts synchronously over the status channel, so the
-			// listener above has already installed the block and announced the
-			// path (or the mode was plan already and both stand); name the file in
-			// the tool result too so the model can start writing this same turn.
-			const path = ensurePlanFile(ctx);
-			return {
-				content: [
-					{
-						type: "text",
-						text: `Entered plan mode. Only read-only tools are available, except for your plan file at ${path} — build your plan there incrementally, then call exit_plan_mode to request approval.`,
-					},
-				],
-				details: { planFilePath: path },
-			};
-		},
-	});
+	/**
+	 * enter_plan_mode's description follows the model's tier: Claude Code's,
+	 * which prefers plan mode, on frontier and workhorse, and One Code's, which
+	 * says most tasks do not need it, on cheap and tiny (`texts.ts`, through the
+	 * shared lib/tool-variants.ts). A re-registration keeps the tool's active
+	 * state, so the deferred tool stays deferred, and it sets no prompt snippet,
+	 * so the system prompt never moves with it.
+	 */
+	registerFormTool(
+		pi,
+		defineTool({
+			name: "enter_plan_mode",
+			label: "Enter plan mode",
+			...ccToolRenderers("Enter plan mode"),
+			description: ENTER_PLAN_MODE_DESCRIPTION,
+			parameters: Type.Object({}),
+			async execute(toolCallId, _params, _signal, _onUpdate, ctx) {
+				pi.events.emit(MODE_CHANNEL, { mode: "plan", toolCallId });
+				// setMode broadcasts synchronously over the status channel, so the
+				// listener above has already installed the block and announced the
+				// path (or the mode was plan already and both stand); name the file in
+				// the tool result too so the model can start writing this same turn.
+				const path = ensurePlanFile(ctx);
+				return {
+					content: [{ type: "text", text: enteredPlanModeText(path) }],
+					details: { planFilePath: path },
+				};
+			},
+		}),
+		enterPlanModeDescription,
+	);
 
 	pi.registerTool({
 		name: "exit_plan_mode",
 		label: "Exit plan mode",
 		...ccToolRenderers("Exit plan mode"),
-		description:
-			"Signal that planning is complete and ask the user to approve the plan.\n" +
-			"Takes no parameters: the plan is read from the plan file named in the plan-mode reminder, which you must have written before calling this. The user reviews that file's contents.",
+		description: EXIT_PLAN_MODE_DESCRIPTION,
 		parameters: Type.Object({}),
-		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+		async execute(toolCallId, _params, signal, _onUpdate, ctx) {
 			// Guard the out-of-sequence call: without this, a cold exit_plan_mode
 			// (never entered plan mode) allocates a fresh empty plan file and blames
 			// "the plan file is empty" — a plausible but wrong cause a weak model
@@ -226,11 +285,30 @@ export default function planModeExtension(pi: ExtensionAPI) {
 			];
 			const choices = options.map((o) => o.label);
 
-			const choice = await ctx.ui.custom<PlanChoice | null>((tui, theme, _keybindings, done) => {
+			// The plan renders as Markdown, like assistant text in the transcript.
+			const prose = canShowCustomUi(ctx) ? await planMarkdown() : undefined;
+			const planRef = {};
+			const markdown = prose ? (text: string, width: number) => prose(planRef, text, width) : undefined;
+
+			// The scroll position and the highlighted choice outlive one showing: a
+			// blank keep-planning answer reopens the dialog where the user left it.
+			const maxVisible = 12;
+			let offset = 0;
+			let selected: PlanChoice = initialPlanChoice(options);
+			const showDialog = (): Promise<PlanChoice | null> => !canShowCustomUi(ctx) ? selectPlanChoice(ctx.ui, plan, path, choices, signal) : panelUi(pi.events, ctx.ui).custom<PlanChoice | null>((tui, theme, _keybindings, close) => {
+				// An aborted turn closes the dialog as a cancel; a choice or a cancel
+				// drops the abort listener. Either way the dialog settles once.
+				let settled = false;
+				const onAbort = () => done(null);
+				const done = (choice: PlanChoice | null) => {
+					if (settled) return;
+					settled = true;
+					signal?.removeEventListener("abort", onAbort);
+					close(choice);
+				};
+				if (signal?.aborted) queueMicrotask(onAbort);
+				else signal?.addEventListener("abort", onAbort, { once: true });
 				const paint = safeThemePaint(theme);
-				const maxVisible = 12;
-				let offset = 0;
-				let selected: PlanChoice = initialPlanChoice(options);
 				let lineCount = 0;
 				// The dialog stays open while exit_plan_mode runs, so pi's working
 				// spinner drives ~8 frames a second — and re-wrapping the whole plan
@@ -243,7 +321,7 @@ export default function planModeExtension(pi: ExtensionAPI) {
 				let wrapped: { width: number; lines: string[] } | undefined;
 				let frame: { key: string; lines: string[] } | undefined;
 				const wrapAt = (wrapWidth: number): string[] => {
-					if (wrapped?.width !== wrapWidth) wrapped = { width: wrapWidth, lines: wrapPlanText(plan, wrapWidth) };
+					if (wrapped?.width !== wrapWidth) wrapped = { width: wrapWidth, lines: planLines(plan, wrapWidth, markdown) };
 					return wrapped.lines;
 				};
 				return {
@@ -274,29 +352,38 @@ export default function planModeExtension(pi: ExtensionAPI) {
 					},
 				};
 			});
+			const decision = await runPlanApproval(
+				options,
+				showDialog,
+				() => ctx.ui.input(KEEP_PLANNING_QUESTION, undefined, { signal }),
+				signal,
+			);
 
-			const picked = choice != null ? options[choice] : undefined;
+			const picked = decision.kind === "approve" ? options[decision.index] : undefined;
 			if (picked?.mode) {
-				pi.events.emit(MODE_CHANNEL, { mode: picked.mode });
+				pi.events.emit(MODE_CHANNEL, { mode: picked.mode, toolCallId });
+				// Claude Code's exit reminder, queued from execute so it is written
+				// into this result after the mode notice.
+				pi.events.emit(REMINDER_CHANNEL, { text: exitedPlanModeText(path), toolCallId });
 				return {
-					content: [
-						{
-							type: "text",
-							text: `Plan approved by the user. You may now implement it. The approved plan stays at ${path} for reference.`,
-						},
-					],
+					content: [{ type: "text", text: approvedPlanText(path, plan) }],
 					details: { plan, approved: true },
 				};
 			}
 
+			// Rejected: Claude Code's rejection text. With the user's words the model
+			// acts on them and keeps planning; without (Esc) the turn stops, as a
+			// reasonless permission rejection does (permissions/index.ts): `terminate`
+			// ends pi's loop after the batch, and the abort waits for the recorded
+			// result so the run ends as the user's interrupt.
+			const feedback = decision.kind === "reject" ? decision.feedback : undefined;
+			const stop = !feedback;
+			if (stop) abortAfterResult.add(toolCallId);
 			return {
-				content: [
-					{
-						type: "text",
-						text: "The user did not approve the plan. Stay in plan mode; refine the plan file based on their feedback.",
-					},
-				],
-				details: { plan, approved: false },
+				content: [{ type: "text", text: userDenialText(feedback) }],
+				details: { plan, approved: false, ...(feedback ? { feedback } : {}) },
+				isError: true,
+				...(stop ? { terminate: true } : {}),
 			};
 		},
 	});

package/extensions/plan-mode/reminder.ts

@@ -1,30 +1,98 @@
 /**
- * Plan-mode reminder text (pure). Byte-identical for a given plan-file path,
- * whether or not the file exists yet: the block is a sticky-append reminder
- * carried by every user message since plan mode came on, and the queue keeps
- * that anchor only while the re-emitted text is unchanged. A text that flipped
- * when the file appeared re-anchored the block and re-cached every message
- * between entering plan mode and the first write (CACHE-REVIEW-2026-09-04 M2).
+ * Plan-mode reminder text (pure): Claude Code's plan-mode instructions, the
+ * five-phase workflow, with One Code's tool and agent names. The block is a
+ * sticky-append reminder carried by every user message since plan mode came
+ * on, and the queue keeps that anchor only while the re-emitted text is
+ * unchanged, so the text must not flip while the mode lasts: a text that
+ * flipped when the file appeared re-anchored the block and re-cached every
+ * message between entering plan mode and the first write
+ * (CACHE-REVIEW-2026-09-04 M2). Claude Code's own "Plan File Info" line
+ * depends on whether the plan file exists; the caller decides that once, when
+ * plan mode comes on (`planExists`), and keeps it until the mode ends.
  *
- * Adapted from Claude Code's plan-mode system message: the plan lives in a
- * file the model builds incrementally — the one writable path in plan mode —
- * and exit_plan_mode reads that file rather than taking the plan as a
- * parameter. Claude Code's own text does vary with the file's existence; ours
- * folds both states into one sentence so the cached prefix survives.
+ * Claude Code puts this text in a system message on the models that take one
+ * and in a reminder elsewhere; One Code delivers it through the reminder
+ * queue's plan-mode placement either way.
  */
 
-export function buildPlanModeReminder(filePath: string): string {
-	const fileLine = `Build your plan at ${filePath} with the write/edit tools — create it if it does not exist yet, then edit it incrementally rather than rewriting it from scratch. Do not present the plan as chat text.`;
+/** Claude Code's "Plan File Info" line, for a plan file that exists or not yet. */
+export function planFileInfo(filePath: string, planExists: boolean): string {
+	return planExists
+		? `A plan file already exists at ${filePath}. You can read it and make incremental edits using the edit tool.`
+		: `No plan file exists yet. You should create your plan at ${filePath} using the write tool.`;
+}
+
+export function buildPlanModeReminder(filePath: string, planExists = false): string {
+	const fileInfo = planFileInfo(filePath, planExists);
 	return [
-		`Plan mode is active. You may only use read-only tools; edit and write are blocked everywhere except one file. ${fileLine}`,
+		"Plan mode is active. The user indicated that they do not want you to execute yet -- you MUST NOT make any edits (with the exception of the plan file mentioned below), run any non-readonly tools (including changing configs or making commits), or otherwise make any changes to the system. This supercedes any other instructions you have received.",
+		"",
+		"## Plan File Info:",
+		fileInfo,
+		"You should build your plan incrementally by writing to or editing this file. NOTE that this is the only file you are allowed to edit - other than this you are only allowed to take READ-ONLY actions.",
+		"",
+		"## Plan Workflow",
+		"",
+		"### Phase 1: Initial Understanding",
+		"Goal: Gain a comprehensive understanding of the user's request by reading through code and asking them questions. Critical: In this phase you should only use the explore subagent type.",
+		"",
+		"1. Focus on understanding the user's request and the code associated with their request. Actively search for existing functions, utilities, and patterns that can be reused — avoid proposing new code when suitable implementations already exist.",
+		"",
+		"2. **Launch up to 3 explore agents IN PARALLEL** (single message, multiple tool calls) to efficiently explore the codebase.",
+		"   - Use 1 agent when the task is isolated to known files, the user provided specific file paths, or you're making a small targeted change.",
+		"   - Use multiple agents when: the scope is uncertain, multiple areas of the codebase are involved, or you need to understand existing patterns before planning.",
+		"   - Quality over quantity - 3 agents maximum, but you should try to use the minimum number of agents necessary (usually just 1)",
+		"   - If using multiple agents: Provide each agent with a specific search focus or area to explore. Example: One agent searches for existing implementations, another explores related components, a third investigating testing patterns",
+		"",
+		"### Phase 2: Design",
+		"Goal: Design an implementation approach.",
+		"",
+		"Launch plan agent(s) to design the implementation based on the user's intent and your exploration results from Phase 1.",
+		"",
+		"You can launch up to 3 agent(s) in parallel.",
+		"",
+		"**Guidelines:**",
+		"- **Default**: Launch at least 1 plan agent for most tasks - it helps validate your understanding and consider alternatives",
+		"- **Skip agents**: Only for truly trivial tasks (typo fixes, single-line changes, simple renames)",
+		"- **Multiple agents**: Use up to 3 agents for complex tasks that benefit from different perspectives",
+		"",
+		"Examples of when to use multiple agents:",
+		"- The task touches multiple parts of the codebase",
+		"- It's a large refactor or architectural change",
+		"- There are many edge cases to consider",
+		"- You'd benefit from exploring different approaches",
+		"",
+		"Example perspectives by task type:",
+		"- New feature: simplicity vs performance vs maintainability",
+		"- Bug fix: root cause vs workaround vs prevention",
+		"- Refactoring: minimal change vs clean architecture",
+		"",
+		"In the agent prompt:",
+		"- Provide comprehensive background context from Phase 1 exploration including filenames and code path traces",
+		"- Describe requirements and constraints",
+		"- Request a detailed implementation plan",
+		"",
+		"### Phase 3: Review",
+		"Goal: Review the plan(s) from Phase 2 and ensure alignment with the user's intentions.",
+		"1. Read the critical files you identified during exploration to deepen your understanding",
+		"2. Ensure that the plans align with the user's original request",
+		"3. Use ask_user_question to clarify any remaining questions with the user",
+		"",
+		"### Phase 4: Final Plan",
+		"Goal: Write your final plan to the plan file (the only file you can edit).",
+		"- Begin with a **Context** section: explain why this change is being made — the problem or need it addresses, what prompted it, and the intended outcome",
+		"- Include only your recommended approach, not all alternatives",
+		"- Ensure that the plan file is concise enough to scan quickly, but detailed enough to execute effectively",
+		"- Name the critical files to be modified. For changes that repeat a pattern across many files, describe the pattern once and list a few representative paths — do not enumerate every file or line number",
+		"- Reference existing functions and utilities you found that should be reused, with their file paths",
+		"- Include a verification section describing how to test the changes end-to-end (run the code, use MCP tools, run tests)",
+		"",
+		"### Phase 5: Call exit_plan_mode",
+		"At the very end of your turn, once you have asked the user questions and are happy with your final plan file - you should always call exit_plan_mode to indicate to the user that you are done planning.",
+		"This is critical - your turn should only end with either using the ask_user_question tool OR calling exit_plan_mode. Do not stop unless it's for these 2 reasons",
 		"",
-		"Workflow:",
-		'1. Explore: delegate broad reconnaissance to the `Agent` tool with `subagent_type: "explore"` (up to 3 in parallel) rather than reading everything yourself.',
-		'2. Design: delegate the implementation strategy to the `Agent` tool with `subagent_type: "plan"` once exploration has mapped the ground.',
-		"3. Review the critical files yourself, and call `ask_user_question` for any decision you cannot make on the user's behalf.",
-		`4. Write the final plan to ${filePath}: a Context section explaining why, your recommended approach (not several options), the critical files named, existing utilities to reuse, and a verification section.`,
-		"5. Call `exit_plan_mode` to ask the user to approve the plan. It reads the plan file directly — you do not pass the plan as a parameter. If `exit_plan_mode` is not in your active tools, load it first with tool_search (`select:exit_plan_mode`).",
+		"**Important:** Use ask_user_question ONLY to clarify requirements or choose between approaches. Use exit_plan_mode to request plan approval. Do NOT ask about plan approval in any other way - no text questions, no ask_user_question. Phrases like \"Is this plan okay?\", \"Should I proceed?\", \"How does this plan look?\", \"Any changes before we start?\", or similar MUST use exit_plan_mode.",
 		"",
-		"End every plan-mode turn with either `ask_user_question` or `exit_plan_mode`. Never ask for plan approval in chat text.",
+		"NOTE: At any point in time through this workflow you should feel free to ask the user questions or clarifications using the ask_user_question tool. Don't make large assumptions about user intent. The goal is to present a well researched plan to the user, and tie any loose ends before implementation begins.",
 	].join("\n");
 }

package/extensions/plan-mode/texts.ts

@@ -0,0 +1,177 @@
+/**
+ * The plan-mode tools' model-facing texts (pure): Claude Code's EnterPlanMode
+ * and ExitPlanMode descriptions and results, with One Code's snake_case tool
+ * names. The plan stays file-based (decisions/modes.md, "Plan mode is
+ * file-based"); only the wording follows Claude Code.
+ */
+
+import type { DescriptionForm } from "../lib/tool-variants.ts";
+
+/**
+ * Claude Code's EnterPlanMode description, which prefers plan mode for any
+ * non-trivial implementation task. Frontier and workhorse models get it.
+ */
+export const ENTER_PLAN_MODE_DESCRIPTION = [
+	"Use this tool proactively when you're about to start a non-trivial implementation task. Getting user sign-off on your approach before writing code prevents wasted effort and ensures alignment. This tool transitions you into plan mode where you can explore the codebase and design an implementation approach for user approval.",
+	"",
+	"## When to Use This Tool",
+	"",
+	"**Prefer using enter_plan_mode** for implementation tasks unless they're simple. Use it when ANY of these conditions apply:",
+	"",
+	"1. **New Feature Implementation**: Adding meaningful new functionality",
+	"   - Example: \"Add a logout button\" - where should it go? What should happen on click?",
+	"   - Example: \"Add form validation\" - what rules? What error messages?",
+	"",
+	"2. **Multiple Valid Approaches**: The task can be solved in several different ways",
+	"   - Example: \"Add caching to the API\" - could use Redis, in-memory, file-based, etc.",
+	"   - Example: \"Improve performance\" - many optimization strategies possible",
+	"",
+	"3. **Code Modifications**: Changes that affect existing behavior or structure",
+	"   - Example: \"Update the login flow\" - what exactly should change?",
+	"   - Example: \"Refactor this component\" - what's the target architecture?",
+	"",
+	"4. **Architectural Decisions**: The task requires choosing between patterns or technologies",
+	"   - Example: \"Add real-time updates\" - WebSockets vs SSE vs polling",
+	"   - Example: \"Implement state management\" - Redux vs Context vs custom solution",
+	"",
+	"5. **Multi-File Changes**: The task will likely touch more than 2-3 files",
+	"   - Example: \"Refactor the authentication system\"",
+	"   - Example: \"Add a new API endpoint with tests\"",
+	"",
+	"6. **Unclear Requirements**: You need to explore before understanding the full scope",
+	"   - Example: \"Make the app faster\" - need to profile and identify bottlenecks",
+	"   - Example: \"Fix the bug in checkout\" - need to investigate root cause",
+	"",
+	"7. **User Preferences Matter**: The implementation could reasonably go multiple ways",
+	"   - If you would use ask_user_question to clarify the approach, use enter_plan_mode instead",
+	"   - Plan mode lets you explore first, then present options with context",
+	"",
+	"## When NOT to Use This Tool",
+	"",
+	"Only skip enter_plan_mode for simple tasks:",
+	"- Single-line or few-line fixes (typos, obvious bugs, small tweaks)",
+	"- Adding a single function with clear requirements",
+	"- Tasks where the user has given very specific, detailed instructions",
+	"- Pure research/exploration tasks (use the Agent tool instead)",
+	"",
+	"## What Happens in Plan Mode",
+	"",
+	"In plan mode, you'll:",
+	"1. Thoroughly explore the codebase using `find`, `grep`, and read",
+	"2. Understand existing patterns and architecture",
+	"3. Design an implementation approach",
+	"4. Present your plan to the user for approval",
+	"5. Use ask_user_question if you need to clarify approaches",
+	"6. Exit plan mode with exit_plan_mode when ready to implement",
+	"",
+	"## Examples",
+	"",
+	"### GOOD - Use enter_plan_mode:",
+	"User: \"Add user authentication to the app\"",
+	"- Requires architectural decisions (session vs JWT, where to store tokens, middleware structure)",
+	"",
+	"User: \"Optimize the database queries\"",
+	"- Multiple approaches possible, need to profile first, significant impact",
+	"",
+	"User: \"Implement dark mode\"",
+	"- Architectural decision on theme system, affects many components",
+	"",
+	"User: \"Add a delete button to the user profile\"",
+	"- Seems simple but involves: where to place it, confirmation dialog, API call, error handling, state updates",
+	"",
+	"User: \"Update the error handling in the API\"",
+	"- Affects multiple files, user should approve the approach",
+	"",
+	"### BAD - Don't use enter_plan_mode:",
+	"User: \"Fix the typo in the README\"",
+	"- Straightforward, no planning needed",
+	"",
+	"User: \"Add a console.log to debug this function\"",
+	"- Simple, obvious implementation",
+	"",
+	"User: \"What files handle routing?\"",
+	"- Research task, not implementation planning",
+	"",
+	"## Important Notes",
+	"",
+	"- This tool REQUIRES user approval - they must consent to entering plan mode",
+	"- If unsure whether to use it, err on the side of planning - it's better to get alignment upfront than to redo work",
+	"- Users appreciate being consulted before significant changes are made to their codebase",
+	"",
+].join("\n");
+
+/**
+ * One Code's own description for the cheap and tiny tiers. Weak models read a
+ * "prefer plan mode" description as standing policy and planned trivial tasks
+ * (decisions/tools.md, "Weak-model steering"), so this one says most tasks do
+ * not need it.
+ */
+export const ENTER_PLAN_MODE_DESCRIPTION_WEAK =
+	"Enter plan mode: read-only investigation to design an approach before changing anything. Most tasks do not need it.\n" +
+	"For a small or clearly-scoped change, act directly instead. Enter plan mode only for multi-file work whose design is genuinely unclear, or when the user asks for a plan. In plan mode only read-only tools are available, plus one writable file: the plan file whose path you are told, where you build the plan incrementally.";
+
+/** The enter_plan_mode description for a description form: Claude Code's short form, ours as the long one. */
+export function enterPlanModeDescription(form: DescriptionForm): string {
+	return form === "long" ? ENTER_PLAN_MODE_DESCRIPTION_WEAK : ENTER_PLAN_MODE_DESCRIPTION;
+}
+
+/** Claude Code's ExitPlanMode description. */
+export const EXIT_PLAN_MODE_DESCRIPTION = [
+	"Use this tool when you are in plan mode and have finished writing your plan to the plan file and are ready for user approval.",
+	"",
+	"## How This Tool Works",
+	"- You should have already written your plan to the plan file specified in the plan mode system message",
+	"- This tool does NOT take the plan content as a parameter - it will read the plan from the file you wrote",
+	"- This tool simply signals that you're done planning and ready for the user to review and approve",
+	"- The user will see the contents of your plan file when they review it",
+	"",
+	"## When to Use This Tool",
+	"IMPORTANT: Only use this tool when the task requires planning the implementation steps of a task that requires writing code. For research tasks where you're gathering information, searching files, reading files or in general trying to understand the codebase - do NOT use this tool.",
+	"",
+	"## Before Using This Tool",
+	"Ensure your plan is complete and unambiguous:",
+	"- If you have unresolved questions about requirements or approach, use ask_user_question first (in earlier phases)",
+	"- Once your plan is finalized, use THIS tool to request approval",
+	"",
+	"**Important:** Do NOT use ask_user_question to ask \"Is this plan okay?\" or \"Should I proceed?\" - that's exactly what THIS tool does. exit_plan_mode inherently requests user approval of your plan.",
+	"",
+	"## Examples",
+	"",
+	"1. Initial task: \"Search for and understand the implementation of vim mode in the codebase\" - Do not use the exit plan mode tool because you are not planning the implementation steps of a task.",
+	"2. Initial task: \"Help me implement yank mode for vim\" - Use the exit plan mode tool after you have finished planning the implementation steps of the task.",
+	"3. Initial task: \"Add a new feature to handle user authentication\" - If unsure about auth method (OAuth, JWT, etc.), use ask_user_question first, then use exit plan mode tool after clarifying the approach.",
+	"",
+].join("\n");
+
+/** Claude Code's EnterPlanMode result. */
+const ENTERED_PLAN_MODE = [
+	"Entered plan mode. You should now focus on exploring the codebase and designing an implementation approach.",
+	"",
+	"In plan mode, you should:",
+	"1. Thoroughly explore the codebase to understand existing patterns",
+	"2. Identify similar features and architectural approaches",
+	"3. Consider multiple approaches and their trade-offs",
+	"4. Use ask_user_question if you need to clarify the approach",
+	"5. Design a concrete implementation strategy",
+	"6. When ready, use exit_plan_mode to present your plan for approval",
+	"",
+	"Remember: DO NOT write or edit any files yet. This is a read-only exploration and planning phase.",
+].join("\n");
+
+/**
+ * enter_plan_mode's result: Claude Code's text, then the plan file's path so
+ * the model can start writing the plan in the same turn.
+ */
+export function enteredPlanModeText(planFilePath: string): string {
+	return `${ENTERED_PLAN_MODE}\n\nYour plan file is ${planFilePath}, the one file you may write: build your plan there.`;
+}
+
+/** exit_plan_mode's result when the user approves: Claude Code's text, with the plan file's contents. */
+export function approvedPlanText(planFilePath: string, plan: string): string {
+	return `User has approved your plan. You can now start coding. Start with updating your todo list if applicable\n\nYour plan has been saved to: ${planFilePath}\nYou can refer back to it if needed during implementation.\n\n## Approved Plan:\n${plan}`;
+}
+
+/** Claude Code's reminder after the approval: plan mode is over and the plan file stays readable. */
+export function exitedPlanModeText(planFilePath: string): string {
+	return `## Exited Plan Mode\n\nYou have exited plan mode. You can now make edits, run tools, and take actions. The plan file is located at ${planFilePath} if you need to reference it.`;
+}