@hank-warren/pi-plan-mode 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @hank-warren/pi-plan-mode
 
+## 1.5.0
+
+### Minor Changes
+
+- c079c51: Keep the completed plan out of model context, stage the Plan tools, and fail honestly when a plan cannot be saved.
+
+  The completed-plan card is a display-only session entry rendered through `registerEntryRenderer` instead of a message, so the plan stays visible and restorable in the transcript while never entering model context or compaction. `plan_mode_complete` returns a one-line `Plan saved to <path>.` pointer; the durable file remains the handoff.
+
+  `plan_mode_complete` now writes the file first and throws when the write fails, rather than reporting success and returning `undefined`. Prior state stays intact and the call is retryable.
+
+  `plan_mode_complete` and the `plan_mode_question` fallback activate when Plan mode is entered or restored, so a session that never plans does not carry their schemas. Ownership of `ask_user_question` is resolved by package directory and read back from the host rather than assumed from the write, and every reconcile is announced on an event, so the fallback no longer depends on hook order between packages. A headless run has no legitimate question tool, so the prompt and the finalize steer switch to a plain-text variant instead of naming a tool that both packages strip.
+
+  `AbortSignal` is wired through the question tool with exactly-once cleanup.
+
+## 1.4.0
+
+### Minor Changes
+
+- 449f989: Ships a companion `pi-plan-mode` skill, making this a hybrid package: the system prompt stays the short enforcement surface and points at the skill for the plan-crafting craft — what decision-complete means, exploring before asking, what separates a question worth asking from one the repository already answers, and what a finished plan contains.
+
+  The footer status and the editor widget now render from one formatter, so they cannot drift, in a glyph vocabulary shared with `pi-loop`: `◆ plan · drafting`, `◆ plan · revising`, `◆ plan · ready → /plan`, `▶ plan · implementing`, each with a dim hint line in the widget. Statuslines that render extension statuses will show the new strings in place of `plan active` / `plan ready` / `plan implementing`.
+
 ## 1.3.0
 
 ### Minor Changes

package/README.md

@@ -17,6 +17,7 @@ The plan is written to a **durable file** that survives compaction, survives res
 - Two ways to implement: continue in this conversation, or open a fresh session that reads the same file.
 - `/plan export [path]` copies the plan anywhere, never overwriting an existing target.
 - Hand-edit the plan file at any time; every command and both implementation paths read from disk.
+- A companion `pi-plan-mode` **skill**, loaded on demand, carrying the plan-crafting craft the prompt only points at.
 
 ## 📦 Install
 
@@ -117,13 +118,22 @@ Detection is by tool name at runtime, re-evaluated every turn — there is no de
 
 A standalone `pi-plan-mode` install loses nothing: `plan_mode_question` stays fully functional and the prompt reads exactly as it always has. It is a **legacy fallback** and is slated for removal in a future major.
 
-## 📊 Statusline
+## 📚 The companion skill
 
-Plan mode publishes a compact status for statuslines that render extension statuses:
+The package ships a `pi-plan-mode` skill (`skills/pi-plan-mode/SKILL.md`) alongside the extension. The system prompt is the enforcement surface and stays deliberately short; the skill is the depth layer it points at — what decision-complete actually means, why exploration comes before questions, what separates a question worth asking from one the repository already answered, and what belongs in a finished plan. One line in the planning prompt names it, and the model loads the body when it judges it needs it.
 
-- `plan active` — planning is under way.
-- `plan ready` — a completed plan is waiting for your choice.
-- `plan implementing` — a plan file is active and guiding implementation.
+Skill and extension version as one artifact: a skill describing a mode the installed extension does not have is a coupling failure waiting to happen.
+
+## 📊 Statusline and widget
+
+The footer status and the widget above the editor render from **one formatter**, so they cannot drift, and they share a glyph vocabulary with the sibling [`pi-loop`](../pi-loop): `◆` for a state wanting a decision, `▶` for work under way.
+
+- `◆ plan · drafting` — planning is under way.
+- `◆ plan · revising` — feedback superseded a completed plan; the stored one is not current.
+- `◆ plan · ready → /plan` — a completed plan is waiting for your choice.
+- `▶ plan · implementing` — a plan file is active and guiding implementation.
+
+The widget adds a dim second line naming what to do next.
 
 ## 🗂️ Package layout
 
@@ -135,6 +145,7 @@ packages/pi-plan-mode/
 │   ├── plan-file.ts      # Durable plan file read/write/delete
 │   ├── interactive-ui.ts # Lazily loaded interactive menus
 │   └── *.ts              # Prompt, question, export, settings modules
+├── skills/pi-plan-mode/  # Companion plan-crafting skill
 ├── test/
 ├── README.md
 ├── NOTICE.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-plan-mode",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Plan mode for Pi: research and design with a durable plan file that survives compaction.",
   "type": "module",
   "keywords": [
@@ -27,11 +27,15 @@
   "pi": {
     "extensions": [
       "./index.ts"
+    ],
+    "skills": [
+      "./skills/pi-plan-mode"
     ]
   },
   "files": [
     "index.ts",
     "src",
+    "skills",
     "README.md",
     "NOTICE.md",
     "LICENSE",

package/skills/pi-plan-mode/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: pi-plan-mode
+description: Craft decision-complete implementation plans in Plan mode — explore before asking, ask questions worth answering, and write a plan another agent can execute without guessing. Use while Plan mode is active, before calling plan_mode_complete, and when deciding whether a request needs a plan at all.
+license: MIT
+---
+
+# pi-plan-mode
+
+The extension enforces the mechanics: `edit` and `write` are blocked, the plan is written to a durable file, and `plan_mode_complete` is the only way out. It cannot enforce the thing that decides whether the plan was worth making: **whether a competent implementer could execute it without asking you anything.** That is this file.
+
+## What "decision-complete" means
+
+A plan is finished when every decision it depends on has been made — by discovery, by the user, or by an explicitly recorded assumption. It is not finished when it is long, well organised, or reads confidently.
+
+The test: hand the plan to someone who was not in the conversation. Every place they would have to stop and ask "which one?" is an unresolved decision, and every one of those is a defect. That includes:
+
+- which of two plausible approaches is being taken, and why the other was rejected;
+- the names and shapes of anything new — files, functions, types, settings keys, tool parameters;
+- what happens on failure, and what happens to state that already exists;
+- how the change is verified, in the form of the commands to run and what they should print;
+- what deliberately stays out of scope.
+
+An unresolved decision hidden behind a confident sentence is worse than an open question, because nobody will notice it until implementation stalls.
+
+## Phase 1: explore before asking
+
+Read the repository first, every time. Questions are expensive — they cost the user's attention and they interrupt — so spend them only on what the code cannot tell you.
+
+Facts the environment owns: what already exists, how the neighbours solve the same problem, what the tests cover, what conventions the repo files and `AGENTS.md` impose, what versions are pinned, what a command actually prints. **Never ask about any of them.** A question whose answer was one `rg` away tells the user you did not look, and it trains them to stop answering carefully.
+
+Facts the environment does not own, and only the user does: product intent, priorities and tradeoffs, what "good enough" means here, which of two acceptable designs they want to live with, whether a breaking change is acceptable, deadlines and blast-radius tolerance.
+
+Exploration also earns the right to disagree. A plan that says "this repo already does X three times, so the fourth should match" is grounded; one that invents a new pattern in a codebase that already has one is a plan the reviewer has to fight.
+
+## Phase 2: ask questions worth answering
+
+Use the question tool for the decisions that are genuinely the user's. Good questions share a shape:
+
+- **The options are real and mutually exclusive.** If one option is obviously right, it is not a question — it is a decision, and you should state it and move on.
+- **Each option says what happens if it is chosen**, not just what it is called. "Store it in the session entry (survives restart, costs a write per turn)" is a choice; "session entry" is a label.
+- **The recommendation comes first and is marked**, so a user who trusts you can answer in one keystroke and one who does not has the alternatives in front of them.
+- **The question is answerable without reading the codebase.** If answering it requires knowing what a function currently does, that is your job, not theirs.
+
+Batch decisions that belong to one choice into one call rather than dripping them out over several turns, and stop asking as soon as the remaining ambiguity is low-impact. When the user declines to answer, do not silently pick: state the default you are taking, mark it as an assumption in the plan, and keep the alternative visible.
+
+A high-impact ambiguity is a reason to keep planning, never a reason to write a plan that hedges. A plan with two branches in it is two plans and nobody's decision.
+
+## Phase 3: write the plan
+
+The plan is read by a human deciding whether to approve it and by an agent executing it. Both want the same thing: grouped, behaviour-level changes with the reasoning attached.
+
+Structure that works:
+
+- **Title and a short summary** — what changes and why, in a few sentences.
+- **The approach**, including the alternatives considered and why they lost. This is the part that survives contact with the implementation; the file list is not.
+- **Behaviour, interface, and data changes** — what a caller or user sees differently, and what the new names and shapes are.
+- **Edge cases and failure modes**, including what happens to existing state and how the change behaves on a host that has the old version.
+- **Verification** — the commands to run and what they should print, plus the manual checks that no command covers.
+- **Assumptions and defaults chosen** — every place you decided rather than asked, stated plainly so it can be corrected.
+
+What to leave out: file-by-file or symbol-by-symbol inventories, restatements of the conversation, and speculative future work. A plan is a decision record, not a diff written in prose.
+
+Prefer specifics over adjectives. "Add a `groundRules?: string[]` to the persisted state, normalized on read, dropped when empty" is a plan; "improve state handling" is a mood.
+
+## Ending a turn, and ending the mode
+
+Every planning turn ends in exactly one of two ways: a question, or `plan_mode_complete` called alone as the final action with the whole plan. Never end with prose announcing that a plan is coming — that costs a whole turn and produces nothing.
+
+On revision, the next `plan_mode_complete` carries a **complete replacement**, not a delta. If you cannot write a complete replacement yet, keep planning and ask instead.
+
+Once the plan is completed the user chooses what happens from the `/plan` menu: implement here, implement in a fresh session that reads the same file, export it, or discard it. The file is the source of truth from then on — it survives compaction, and the user may have hand-edited it, so re-read it before implementing rather than working from memory of what you wrote.
+
+## When a plan is the wrong tool
+
+Plan mode is for work whose *shape* is uncertain. It is overhead when it is not:
+
+- **A single obvious change** — make it. A plan for a one-line fix costs more than the fix.
+- **Pure investigation with no change in view** — investigate in the conversation. Plan mode blocks the tools that would let you experiment, and there is nothing to decide yet.
+- **Work whose difficulty is execution, not design** ("run this migration on 40 hosts") → the interesting part is a runbook and a rollout order, not a design decision.
+
+Say so in one line and offer the alternative rather than producing a plan nobody needed.

package/src/completion-tool.ts

@@ -57,7 +57,12 @@ export function planFromCompletionDetails(value: unknown) {
 
 export function planModeCompleted(plan: string, planPath?: string) {
 	return {
-		content: [{ type: "text" as const, text: `**Proposed Plan**\n\n${plan}` }],
+		content: [
+			{
+				type: "text" as const,
+				text: planPath ? `Plan saved to ${planPath}.` : "Plan saved.",
+			},
+		],
 		details: {
 			version: PLAN_MODE_COMPLETE_VERSION,
 			source: PLAN_MODE_COMPLETE_TOOL_NAME,

package/src/plan-mode.ts

@@ -28,6 +28,8 @@ import { createPlanExportController } from "./plan-export-controller.js";
 import {
 	clearPlanModeUi,
 	planModeStatusText as formatPlanModeStatusText,
+	registerPlanModeCardRenderer,
+	showPlanModePlan,
 	showStoredPlan,
 	updatePlanModeUi,
 } from "./presentation.js";
@@ -53,6 +55,7 @@ import {
 import { type PlanModeState, readLegacyThinkingCapture, restorePlanModeState } from "./state.js";
 
 const STATE_ENTRY_TYPE = "plan-mode-state";
+const ASK_USER_AVAILABILITY_EVENT = "hank:ask-user:availability";
 /**
  * Plan mode's entire enforcement surface. Everything else — bash, subagents,
  * MCP, and other extension tools — is left to the session's normal permission
@@ -72,38 +75,18 @@ const BLOCKED_TOOLS = new Set(["edit", "write"]);
 const SETTINGS_RELOAD_DEBOUNCE_MS = 75;
 
 /**
- * Which question tool the prompt should name this turn.
+ * Which question tool the prompt may name this turn, read from the tool set
+ * the model will actually see.
  *
- * Detection is by tool NAME only, with no dependency on
- * `@hank-warren/pi-ask-user-question`: any extension registering
- * `ask_user_question` is treated as the preferred implementation. It offers
- * previews, notes, question tabs, digit hotkeys and checkbox multi-select;
- * `plan_mode_question` renders through plain `ctx.ui.select` + `ctx.ui.editor`
- * and has none of them.
- *
- * Evaluated per turn rather than once at mode entry, so the prompt cannot go
- * stale if the tool set changes mid-session.
+ * `null` means neither is active — a headless run, where both interactive
+ * tools are deliberately stripped. Naming one there would send the model after
+ * a tool it cannot call, so the prompt switches to asking in plain text.
  */
-function preferredQuestionTool(pi: ExtensionAPI): string {
-	return pi.getActiveTools().includes(ASK_USER_QUESTION_TOOL)
-		? ASK_USER_QUESTION_TOOL
-		: PLAN_MODE_QUESTION_TOOL;
-}
-
-/**
- * Hide `plan_mode_question` from the model whenever the better tool is present,
- * so it never sees two overlapping question tools and cannot call the weaker
- * one. The tool stays *registered* either way, so a historical transcript still
- * resolves it, and a host without `ask_user_question` keeps it fully functional.
- *
- * Idempotent, and writes only when something actually changes: siblings are
- * untouched, and repeated `before_agent_start` events are free.
- */
-function reconcileQuestionTool(pi: ExtensionAPI, preferred: string): void {
-	if (preferred === PLAN_MODE_QUESTION_TOOL) return;
+function preferredQuestionTool(pi: ExtensionAPI): string | null {
 	const active = pi.getActiveTools();
-	if (!active.includes(PLAN_MODE_QUESTION_TOOL)) return;
-	pi.setActiveTools(active.filter((name) => name !== PLAN_MODE_QUESTION_TOOL));
+	if (active.includes(ASK_USER_QUESTION_TOOL)) return ASK_USER_QUESTION_TOOL;
+	if (active.includes(PLAN_MODE_QUESTION_TOOL)) return PLAN_MODE_QUESTION_TOOL;
+	return null;
 }
 
 type InteractiveUi = typeof import("./interactive-ui.js");
@@ -138,7 +121,41 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 	let menuController = new AbortController();
 	let settingsWatch: ReturnType<typeof watch> | undefined;
 	let settingsReloadTimer: ReturnType<typeof setTimeout> | undefined;
+	let planToolsActivated = false;
+	let currentHasUI = false;
+	let globalQuestionAvailable = false;
 	const persistState = () => pi.appendEntry<PlanModeState>(STATE_ENTRY_TYPE, state);
+
+	const reconcilePlanToolSurface = (hasUI: boolean, availability?: boolean) => {
+		currentHasUI = hasUI;
+		const active = pi.getActiveTools();
+		globalQuestionAvailable = availability ?? (hasUI && active.includes(ASK_USER_QUESTION_TOOL));
+		const wanted = new Set(active);
+		const completeWanted = planToolsActivated;
+		const fallbackWanted = planToolsActivated && hasUI && !globalQuestionAvailable;
+		if (completeWanted) wanted.add(PLAN_MODE_COMPLETE_TOOL_NAME);
+		else wanted.delete(PLAN_MODE_COMPLETE_TOOL_NAME);
+		if (fallbackWanted) wanted.add(PLAN_MODE_QUESTION_TOOL);
+		else wanted.delete(PLAN_MODE_QUESTION_TOOL);
+		const next = [...wanted];
+		if (next.length !== active.length || next.some((name, index) => name !== active[index])) {
+			pi.setActiveTools(next);
+		}
+	};
+	const activatePlanTools = (hasUI: boolean) => {
+		planToolsActivated = true;
+		reconcilePlanToolSurface(hasUI);
+	};
+
+	registerPlanModeCardRenderer(pi);
+	pi.events.on(ASK_USER_AVAILABILITY_EVENT, (payload: unknown) => {
+		const available =
+			typeof payload === "object" && payload !== null &&
+			typeof (payload as { available?: unknown }).available === "boolean"
+				? (payload as { available: boolean }).available
+				: undefined;
+		if (available !== undefined) reconcilePlanToolSurface(currentHasUI, available);
+	});
 	const planExports = createPlanExportController({
 		getState: () => state,
 		getSettings: () => settings,
@@ -183,12 +200,14 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		label: "Plan question",
 		description:
 			"Ask the user one to three Plan-mode clarification questions with meaningful options, then wait for the answer. Only available while Plan mode is active.",
+		// Kept, now that the tool is staged: this guidance reaches the model only
+		// in a session that has actually entered Plan mode.
 		promptSnippet: "Ask user decision questions while Plan mode is active",
 		promptGuidelines: [
 			"In Plan mode, use plan_mode_question for important preferences, tradeoffs, or assumptions that cannot be discovered from read-only exploration.",
 		],
 		parameters: PLAN_MODE_QUESTION_PARAMS,
-		async execute(_toolCallId, params: unknown, _signal, _onUpdate, ctx) {
+		async execute(_toolCallId, params: unknown, signal, _onUpdate, ctx) {
 			if (!state.enabled) {
 				return planModeQuestionCancelled(
 					[],
@@ -212,11 +231,20 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 
 			const sessionGeneration = menuGeneration;
 			const questionWorkflowGeneration = workflowGeneration;
-			return answerPlanModeQuestions(parsed.questions, ctx, {
-				isCurrent: () =>
-					sessionGeneration === menuGeneration && questionWorkflowGeneration === workflowGeneration,
-				isEnabled: () => state.enabled,
-			});
+			const questionSignal = signal
+				? AbortSignal.any([signal, menuController.signal])
+				: menuController.signal;
+			return answerPlanModeQuestions(
+				parsed.questions,
+				ctx,
+				{
+					isCurrent: () =>
+						sessionGeneration === menuGeneration &&
+						questionWorkflowGeneration === workflowGeneration,
+					isEnabled: () => state.enabled,
+				},
+				questionSignal,
+			);
 		},
 	});
 
@@ -243,6 +271,10 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		},
 	});
 
+	// Registered tools remain available for transcript replay; the active set is
+	// narrowed at session_start rather than here, because Pi refuses action
+	// methods (getActiveTools/setActiveTools) during extension loading.
+
 	pi.registerCommand("plan", {
 		description: "Enter or manage Plan mode",
 		getArgumentCompletions: completePlanArguments,
@@ -384,6 +416,9 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 
 	pi.on("session_start", async (event, ctx) => {
 		const generation = ++menuGeneration;
+		planToolsActivated = false;
+		currentHasUI = ctx.hasUI;
+		reconcilePlanToolSurface(ctx.hasUI);
 		refreshStateBeforeFirstAgentStart = event.reason === "new";
 		menuController.abort(new DOMException("Plan-mode session replaced", "AbortError"));
 		menuController = new AbortController();
@@ -401,6 +436,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 			state = { ...state, enabled: true, awaitingAction: state.planPath !== undefined };
 		}
 		if (persistFlagActivation) persistState();
+		if (state.enabled) activatePlanTools(ctx.hasUI);
 		updateUi(ctx);
 	});
 
@@ -430,6 +466,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 	});
 
 	pi.on("before_agent_start", (event, ctx) => {
+		currentHasUI = ctx.hasUI;
 		if (refreshStateBeforeFirstAgentStart) {
 			refreshStateBeforeFirstAgentStart = false;
 			restoreState(ctx);
@@ -443,11 +480,12 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 			persistState();
 			updateUi(ctx);
 		}
-		// Read fresh and write immediately, exactly like pi-ask-user-question's own
-		// reconciler, so the two hooks converge on the same result in either
-		// execution order.
-		const questionTool = preferredQuestionTool(pi);
-		reconcileQuestionTool(pi, questionTool);
+		if (state.enabled && !planToolsActivated) activatePlanTools(ctx.hasUI);
+		else reconcilePlanToolSurface(ctx.hasUI);
+		// A headless run has no legitimate question tool, whatever the active set
+		// still says: pi-ask-user-question strips its own tool on this same hook,
+		// and hook order between the two packages is not ours to depend on.
+		const questionTool = ctx.hasUI ? preferredQuestionTool(pi) : null;
 		if (state.enabled) {
 			return { systemPrompt: `${event.systemPrompt}\n\n${buildPlanModePrompt(questionTool)}` };
 		}
@@ -476,6 +514,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 
 	function enterPlanMode(ctx: ExtensionContext) {
 		workflowGeneration += 1;
+		activatePlanTools(ctx.hasUI);
 		state = { ...state, enabled: true, awaitingAction: false };
 		persistState();
 		updateUi(ctx);
@@ -525,20 +564,20 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 	 * Writes the durable plan file and marks the plan ready. A write failure
 	 * keeps Plan mode active rather than silently losing the plan.
 	 */
-	async function acceptCompletedPlan(plan: string, ctx: ExtensionContext) {
+	async function acceptCompletedPlan(plan: string, ctx: ExtensionContext): Promise<string> {
 		const planPath = sessionPlanPath ?? resolveSessionPlanPath(ctx);
-		sessionPlanPath = planPath;
 		try {
 			await writePlanFile(planPath, plan);
 		} catch (error: unknown) {
 			const detail = error instanceof Error ? error.message : String(error);
-			ctx.ui.notify(`Unable to save the plan to ${planPath}: ${detail}`, "error");
-			return undefined;
+			throw new Error(`Unable to save the plan to ${planPath}: ${detail}`);
 		}
+		sessionPlanPath = planPath;
 		state = { ...state, planPath, awaitingAction: true };
 		pendingReadyNonce = ++readyPresentationNonce;
 		persistState();
 		updateUi(ctx);
+		showPlanModePlan(pi, ctx, "Proposed Plan", plan);
 		return planPath;
 	}
 
@@ -551,8 +590,12 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 			ctx.ui.notify("Plan mode is not active. Use /plan first.", "warning");
 			return;
 		}
+		// Same rule as the prompt: a headless run has no question tool to name.
+		const questionTool = ctx.hasUI ? preferredQuestionTool(pi) : null;
 		sendPlanModeUserMessage(
-			`Finalize the current implementation plan now. If any material decision remains, use ${preferredQuestionTool(pi)} instead. Otherwise call plan_mode_complete alone as your final action with the complete decision-ready plan.`,
+			`Finalize the current implementation plan now. If any material decision remains, ${
+				questionTool === null ? "ask it in plain text" : `use ${questionTool}`
+			} instead. Otherwise call plan_mode_complete alone as your final action with the complete decision-ready plan.`,
 			ctx,
 		);
 	}

package/src/presentation.ts

@@ -1,29 +1,165 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Markdown, Text } from "@earendil-works/pi-tui";
+import {
+	getMarkdownTheme,
+	type ExtensionAPI,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
 import { readPlanFile } from "./plan-file.js";
 import type { PlanModeState } from "./state.js";
 
 const STATUS_KEY = "plan-mode";
 const PLAN_WIDGET_KEY = "plan-mode-plan";
+export const PLAN_CARD_ENTRY_TYPE = "plan-mode-card";
+
+type PlanCardData = { title: string; plan: string };
+
+/**
+ * Persisted entry data is input, not a guarantee.
+ *
+ * The renderer runs against whatever is on disk, which may predate a field, be
+ * truncated by a partial write, or have been hand-edited. Pi contains a
+ * renderer throw as an inline `[plan-mode-card] renderer failed: …` box —
+ * survivable, but a needlessly ugly way to say "this card is old".
+ */
+function planCardData(value: unknown): PlanCardData | undefined {
+	if (typeof value !== "object" || value === null) return undefined;
+	const { title, plan } = value as { title?: unknown; plan?: unknown };
+	return typeof title === "string" && typeof plan === "string"
+		? (value as PlanCardData)
+		: undefined;
+}
+
+/**
+ * The completed-plan card, as a display-only session entry.
+ *
+ * A custom *entry* rather than a message, which is what buys the property a
+ * message could not: Pi maps a `custom` entry to no context messages at all
+ * and skips it during compaction, so the plan stays visible and restorable in
+ * the transcript while never entering model context and never costing a
+ * compaction budget. The model gets a one-line `Plan saved to <path>.` from
+ * `plan_mode_complete` instead, and reads the durable file when it implements.
+ *
+ * pi-loop's approval card is the same mechanism for the same reason
+ * (`packages/pi-loop/src/presentation.ts`).
+ */
+export function registerPlanModeCardRenderer(pi: ExtensionAPI): void {
+	pi.registerEntryRenderer(PLAN_CARD_ENTRY_TYPE, (entry) => {
+		const data = planCardData(entry.data);
+		if (!data) return new Text("Plan card unavailable.", 0, 0);
+		return new Markdown(
+			`**${data.title}**\n\n${data.plan}`,
+			0,
+			0,
+			getMarkdownTheme(),
+		);
+	});
+}
+
+/**
+ * The one thing both surfaces render.
+ *
+ * The footer and the widget say the same thing in two sizes, so they are
+ * formatted once. When each formatted its own they drifted — the sibling
+ * pi-loop shipped a loop that read as "waiting" in the footer and "running"
+ * above the editor for exactly that reason, and this is the same shape of
+ * bug waiting to happen with "ready" and "implementing".
+ *
+ * The glyphs are the family vocabulary shared with pi-loop by convention
+ * rather than by import: `◆` planning or ready, `▶` implementing. Six
+ * characters do not justify a shared package; a user reading a footer
+ * justifies the consistency.
+ */
+export type PlanModePhase = "drafting" | "revising" | "ready" | "implementing";
+
+export interface PlanModeView {
+	phase: PlanModePhase;
+	/** The footer line: plain text with a glyph, no colour. */
+	footer: string;
+	/** The widget's headline, rendered bold and themed. */
+	headline: string;
+	/** The dim second line: what to do next. */
+	hint: string;
+	/** Accent while the plan wants a decision; normal once it is being built. */
+	tone: "accent" | "normal";
+}
+
+export function planModeView(state: PlanModeState): PlanModeView | undefined {
+	if (state.enabled) {
+		if (state.awaitingAction) {
+			return {
+				phase: "ready",
+				footer: "◆ plan · ready → /plan",
+				headline: "◆ plan · proposed plan ready",
+				hint: "/plan to implement, export, or exit — or type feedback to revise.",
+				tone: "accent",
+			};
+		}
+		// A stored plan with no pending action means feedback superseded it: the
+		// plan on disk is no longer what is being offered, and saying "drafting"
+		// would hide that a completed plan is being replaced.
+		if (state.planPath) {
+			return {
+				phase: "revising",
+				footer: "◆ plan · revising",
+				headline: "◆ plan · revising the proposed plan",
+				hint: "The stored plan is superseded until the next plan_mode_complete.",
+				tone: "accent",
+			};
+		}
+		return {
+			phase: "drafting",
+			footer: "◆ plan · drafting",
+			headline: "◆ plan · drafting",
+			hint: "Explore and ask; finish with plan_mode_complete when decision-ready.",
+			tone: "accent",
+		};
+	}
+	if (state.planPath) {
+		return {
+			phase: "implementing",
+			footer: "▶ plan · implementing",
+			headline: "▶ plan · implementing",
+			hint: "/plan to show, replace, or clear the active plan.",
+			tone: "normal",
+		};
+	}
+	return undefined;
+}
+
+/**
+ * The slice of Pi's theme this widget uses. Structural rather than imported so
+ * the renderer keeps working against a host whose theme carries neither
+ * helper: both are optional, and an absent one degrades to plain text.
+ */
+interface WidgetTheme {
+	bold?: (text: string) => string;
+	fg?: (color: string, text: string) => string;
+}
+
+type WidgetFactory = Parameters<ExtensionContext["ui"]["setWidget"]>[1];
 
 export function updatePlanModeUi(ctx: ExtensionContext, state: PlanModeState) {
-	ctx.ui.setStatus(STATUS_KEY, formatStatus(state));
-	if (state.enabled && state.awaitingAction) {
-		ctx.ui.setWidget(PLAN_WIDGET_KEY, [
-			"Proposed plan ready",
-			"Use /plan to implement, export, or exit — or type feedback to revise.",
-		]);
-	} else if (state.enabled) {
-		ctx.ui.setWidget(PLAN_WIDGET_KEY, [
-			"Plan mode: planning",
-			"Finish with plan_mode_complete when decision-ready.",
-		]);
-	} else if (state.planPath) {
-		ctx.ui.setWidget(PLAN_WIDGET_KEY, [
-			"Implementation plan active",
-			"Use /plan to show, replace, or clear it.",
-		]);
-	} else {
+	const view = planModeView(state);
+	ctx.ui.setStatus(STATUS_KEY, view?.footer);
+	if (!view) {
 		ctx.ui.setWidget(PLAN_WIDGET_KEY, undefined);
+		return;
+	}
+	try {
+		const render = (_tui: unknown, rawTheme: unknown) => {
+			const theme = (rawTheme ?? {}) as WidgetTheme;
+			const bold = theme.bold ?? ((text: string) => text);
+			const headline =
+				view.tone === "accent"
+					? (theme.fg?.("accent", bold(view.headline)) ?? bold(view.headline))
+					: bold(view.headline);
+			const hint = theme.fg?.("dim", `  ${view.hint}`) ?? `  ${view.hint}`;
+			return new Text(`${headline}\n${hint}`);
+		};
+		ctx.ui.setWidget(PLAN_WIDGET_KEY, render as WidgetFactory);
+	} catch {
+		// Presentation only: a host without the component form of setWidget (or a
+		// render failure) must never take Plan mode's state transitions with it.
 	}
 }
 
@@ -65,20 +201,14 @@ export function showPlanModePlan(
 	plan: string,
 ) {
 	try {
-		pi.sendMessage(
-			{
-				customType: "proposed-plan",
-				content: `**${title}**\n\n${plan}`,
-				display: true,
-			},
-			{ triggerTurn: false },
-		);
+		pi.appendEntry<PlanCardData>(PLAN_CARD_ENTRY_TYPE, { title, plan });
 	} catch (error: unknown) {
 		const detail = error instanceof Error ? error.message : String(error);
 		ctx.ui.notify(`Unable to show completed plan: ${detail}`, "error");
 	}
 }
 
+/** The sentence form, for menus, notifications, and non-TUI modes. */
 export function planModeStatusText(state: PlanModeState) {
 	if (state.enabled) {
 		if (state.awaitingAction) return "Plan mode is active and a proposed plan is ready.";
@@ -90,9 +220,3 @@ export function planModeStatusText(state: PlanModeState) {
 	if (state.planPath) return "An implementation plan is active.";
 	return "Plan mode is off.";
 }
-
-function formatStatus(state: PlanModeState) {
-	if (state.enabled) return state.awaitingAction ? "plan ready" : "plan active";
-	if (state.planPath) return "plan implementing";
-	return undefined;
-}

package/src/prompt.ts

@@ -41,9 +41,29 @@ const QUESTION_TOOL_PROFILES: Record<string, QuestionToolProfile> = {
  *
  * The default keeps the exported function callable with no arguments and keeps
  * a standalone `pi-plan-mode` install reading exactly as it did before.
+ *
+ * Passing `null` builds the headless variant: no interactive question tool is
+ * active in that session, so naming one would tell the model to call a tool it
+ * cannot see. It asks in plain text instead.
  */
-export function buildPlanModePrompt(questionTool: string = PLAN_MODE_QUESTION_TOOL) {
-	const tool = QUESTION_TOOL_PROFILES[questionTool] ?? QUESTION_TOOL_PROFILES[PLAN_MODE_QUESTION_TOOL];
+export function buildPlanModePrompt(questionTool: string | null = PLAN_MODE_QUESTION_TOOL) {
+	const tool =
+		questionTool === null
+			? undefined
+			: (QUESTION_TOOL_PROFILES[questionTool] ??
+				QUESTION_TOOL_PROFILES[PLAN_MODE_QUESTION_TOOL]);
+	const askBullet = tool
+		? `Use ${tool.name} for important preferences, tradeoffs, or assumption locks that cannot be discovered by non-mutating exploration. ${tool.bounds} Do not include filler options.`
+		: "This session has no interactive question tool, so ask in plain text: put important preferences, tradeoffs, or assumption locks that non-mutating exploration cannot settle in your reply as 1-3 concise questions with 2-4 meaningful options each. Do not include filler options, and never call a question tool that is not in your tool set.";
+	const declineBullet = tool
+		? `${tool.decline}, do not jump straight to a final plan when the missing answer is high impact. Ask one concise plain-text question or proceed only with a clearly stated low-risk assumption.`
+		: "If the question goes unanswered, do not jump straight to a final plan when the missing answer is high impact. Ask it again more concisely, or proceed only with a clearly stated low-risk assumption recorded in the plan.";
+	const endingBullet = tool
+		? `If a material decision remains, use ${tool.name}. If interactive UI is unavailable, ask one concise plain-text question instead.`
+		: "If a material decision remains, ask one concise plain-text question instead.";
+	const revisionClause = tool
+		? `continue planning with ${tool.name} instead of calling plan_mode_complete`
+		: "continue planning with a plain-text question instead of calling plan_mode_complete";
 	return `${PLAN_CONTEXT_MARKER}
 # Plan Mode (Conversational)
 
@@ -51,6 +71,7 @@ You are in Plan Mode, a collaboration mode for producing a decision-complete imp
 
 ## Mode rules
 
+- Read the pi-plan-mode skill before planning if it is available: it carries the plan-crafting craft — decision-completeness, exploring before asking, question quality, and what a finished plan contains.
 - Stay in Plan Mode until a developer or extension explicitly exits it.
 - Treat requests to implement as requests to plan the implementation; do not edit files or carry out the plan.
 - Do not use todo/checklist tooling to track execution progress in Plan Mode; Plan Mode is conversational planning, and the plan itself belongs in plan_mode_complete.
@@ -72,14 +93,14 @@ You are in Plan Mode, a collaboration mode for producing a decision-complete imp
 ## Phase 3 — Implementation chat
 
 - Once intent is stable, keep asking until the spec is decision-complete: approach, interfaces, data flow, edge cases/failure modes, testing and acceptance criteria, and any migration or compatibility constraints.
-- Use ${tool.name} for important preferences, tradeoffs, or assumption locks that cannot be discovered by non-mutating exploration. ${tool.bounds} Do not include filler options.
-- ${tool.decline}, do not jump straight to a final plan when the missing answer is high impact. Ask one concise plain-text question or proceed only with a clearly stated low-risk assumption.
+- ${askBullet}
+- ${declineBullet}
 
 ## Ending each turn
 
 Every Plan-mode turn that advances or finalizes the plan must end in exactly one of these ways:
 
-- If a material decision remains, use ${tool.name}. If interactive UI is unavailable, ask one concise plain-text question instead.
+- ${endingBullet}
 - If the implementation plan is decision-complete, call plan_mode_complete alone as your final action. Do not call other tools in the same batch and do not emit a normal assistant response after it.
 
 If a follow-up asks only for clarification and does not change or challenge the plan, answer it directly, then call plan_mode_complete alone as the final action with the complete unchanged plan so it remains available for implementation.
@@ -100,7 +121,7 @@ Keep the plan concise, human and agent digestible, and free of open decisions. P
 
 The plan is saved to a durable file, so it survives compaction and can be re-read at any time.
 
-If the user requests revisions after a completed plan, the next plan_mode_complete call must contain a complete replacement, not a delta. If there is not enough information for a complete replacement, continue planning with ${tool.name} instead of calling plan_mode_complete.`;
+If the user requests revisions after a completed plan, the next plan_mode_complete call must contain a complete replacement, not a delta. If there is not enough information for a complete replacement, ${revisionClause}.`;
 }
 
 /**

package/src/question-tool.ts

@@ -152,11 +152,13 @@ export async function answerPlanModeQuestions(
 	questions: PlanModeQuestion[],
 	ctx: ExtensionContext,
 	lifecycle: { isCurrent(): boolean; isEnabled(): boolean },
+	signal?: AbortSignal,
 ) {
 	const answers = await askPlanModeQuestions(
 		questions,
 		ctx,
-		() => lifecycle.isCurrent() && lifecycle.isEnabled(),
+		() => lifecycle.isCurrent() && lifecycle.isEnabled() && !signal?.aborted,
+		signal,
 	);
 	if (!lifecycle.isCurrent()) {
 		return planModeQuestionCancelled(
@@ -186,18 +188,22 @@ export async function askPlanModeQuestions(
 	questions: PlanModeQuestion[],
 	ctx: ExtensionContext,
 	shouldContinue: () => boolean = () => true,
+	signal?: AbortSignal,
 ): Promise<PlanModeQuestionAnswer[] | undefined> {
 	const answers: PlanModeQuestionAnswer[] = [];
 	for (const question of questions) {
+		if (!shouldContinue() || signal?.aborted) return undefined;
 		const choices = question.options.map(formatPlanModeQuestionChoice);
 		const otherChoice = `${question.options.length + 1}. Other (free-form)`;
-		const choice = await ctx.ui.select(`${question.header}: ${question.question}`, [
-			...choices,
-			otherChoice,
-		]);
+		const choice = await raceWithAbort(
+			ctx.ui.select(`${question.header}: ${question.question}`, [...choices, otherChoice]),
+			signal,
+		);
 		if (!shouldContinue() || !choice) return undefined;
 		if (choice === otherChoice) {
-			const customAnswer = (await ctx.ui.editor(question.question, ""))?.trim();
+			const customAnswer = (
+				await raceWithAbort(ctx.ui.editor(question.question, ""), signal)
+			)?.trim();
 			if (!shouldContinue() || !customAnswer) return undefined;
 			answers.push({
 				id: question.id,
@@ -223,6 +229,16 @@ export async function askPlanModeQuestions(
 	return answers;
 }
 
+async function raceWithAbort<T>(operation: Promise<T>, signal?: AbortSignal): Promise<T | undefined> {
+	if (!signal) return operation;
+	if (signal.aborted) return undefined;
+	return new Promise<T | undefined>((resolve, reject) => {
+		const abort = () => resolve(undefined);
+		signal.addEventListener("abort", abort, { once: true });
+		operation.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+	});
+}
+
 function formatPlanModeQuestionChoice(option: PlanModeQuestionOption, index: number) {
 	return `${index + 1}. ${option.label}${option.description ? ` — ${option.description}` : ""}`;
 }