@hank-warren/pi-plan-mode 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# @hank-warren/pi-plan-mode
+
+## 1.1.0
+
+### Minor Changes
+
+- c40a48d: prefer `ask_user_question` for Plan-mode decision questions when it is installed
+
+  `plan_mode_question` renders through plain `ctx.ui.select` + `ctx.ui.editor`: no
+  previews, no notes, no tabs, no digit hotkeys. When
+  `@hank-warren/pi-ask-user-question` is present, Plan mode now asks through that
+  tool instead, which has all of them plus checkbox multi-select.
+
+  Detection is a runtime check for a tool named `ask_user_question` in the active
+  tool set, re-evaluated every turn — there is no dependency between the two
+  packages. When it is found, `plan_mode_question` is removed from the **active**
+  tool set so the model never sees two overlapping question tools, and the
+  Plan-mode system prompt names `ask_user_question` with its own bounds (1-4
+  questions, 2-4 options, 2-6 when `multiSelect`) and its own decline signal. The
+  tool stays _registered_ either way, so a historical transcript still resolves
+  it.
+
+  A standalone `pi-plan-mode` install is unchanged: `plan_mode_question` remains
+  fully functional and the prompt reads exactly as before. It is now a legacy
+  fallback, slated for removal in a future major.
+
+## 1.0.1
+
+### Patch Changes
+
+- cf12677: ship CHANGELOG.md in the published tarball
+
+## 1.0.0
+
+### Major Changes
+
+- 88572fe: Rewrite Plan mode around a durable plan file and stop managing tool permissions.
+
+  Plan mode is now a mode of intent rather than a permission system. It blocks exactly `edit`, `write`, and `update_plan` while planning and leaves every other tool as configured, so Bash and extension-tool safety stays with your permission layer (for example `@hank-warren/pi-auto-permissions`).
+
+  **Plan mode no longer calls `setActiveTools`.** It previously rewrote the session's active tool set on every turn, which stripped tools other extensions had registered — lazily connected MCP tools and on-demand channels such as pi-subagents' supervisor tool were removed mid-session and never reactivated, and extensions that manage their own tools on `before_agent_start` fought Plan mode for control. None of that can happen now.
+
+  Completed plans are written to `<agent dir>/plans/<session-id>.md`. The plan file is the plan: session state stores only its path, the file can be hand-edited, and both implementation paths read it from disk. While a plan is active the model receives a one-line pointer to the file instead of the plan body, so plans survive compaction at negligible context cost regardless of size, replacing the previous reinjection of up to 50,000 characters.
+
+  Breaking changes:
+
+  - Removed settings `defaultPlanTools`, `bashPolicy`, `safeSubcommands`, and `implementationPlanRetention`. They are now ignored rather than rejected, so existing settings files keep loading. `thinkingLevel` and `defaultPlanExportPath` are unchanged.
+  - Removed the pre-start tool selector and `/plan tools`.
+  - Removed the separate saved-plan state and `/plan save`; there is one plan per session, and `/plan exit` deletes it.
+  - Removed the legacy `<proposed_plan>` XML completion path; use `plan_mode_complete`.
+  - The implementation handoff and fresh-session transfer now reference the plan file instead of inlining the plan text.

package/README.md

@@ -4,14 +4,14 @@
 
 `@hank-warren/pi-plan-mode` adds a `/plan` mode to Pi for research and design. You gather information, ask questions, and land on a plan — then implement it, either in the same conversation or in a fresh one.
 
-**Plan mode is a mode of intent, not a permission system.** It blocks `edit`, `write`, and `update_plan` while planning and leaves every other tool exactly as you configured it. Command safety stays with your permission extension (for example [`@hank-warren/pi-auto-permissions`](../pi-auto-permissions)), which already reviews Bash. Plan mode never touches the session's active tool set, so it cannot break other extensions.
+**Plan mode is a mode of intent, not a permission system.** It blocks `edit`, `write`, and `update_plan` while planning and leaves every other tool exactly as you configured it. Command safety stays with your permission extension (for example [`@hank-warren/pi-auto-permissions`](../pi-auto-permissions)), which already reviews Bash. The only tool Plan mode ever removes from the active set is its own `plan_mode_question`, and only when a better questionnaire is installed (see below), so it cannot break other extensions.
 
 The plan is written to a **durable file** that survives compaction, survives resume, and can be hand-edited.
 
 ## ✨ Features
 
 - `/plan` mode with a planning system prompt: explore first, ask decision questions, do not implement.
-- `plan_mode_question` for structured 1-3 question decision points with options and a free-form path.
+- `plan_mode_question` for structured 1-3 question decision points with options and a free-form path — or `ask_user_question` when that is installed (see below).
 - `plan_mode_complete({ plan })` writes the plan to `<agent dir>/plans/<session-id>.md`.
 - **Pointer, not payload.** An active plan adds one line to the system prompt naming the file. The plan body is never injected into context, so a 50-page plan costs the same as a one-liner and survives compaction for free.
 - Two ways to implement: continue in this conversation, or open a fresh session that reads the same file.
@@ -95,7 +95,24 @@ Plan mode blocks exactly three tools while planning: `edit`, `write`, and `updat
 
 It deliberately does **not** police Bash, subagents, MCP tools, or any other extension tool. Those decisions belong to your permission layer, which can see the whole session and judge each call. Pair Plan mode with a permission extension such as `@hank-warren/pi-auto-permissions` if you want command review during planning.
 
-Plan mode also never calls `setActiveTools`. Extensions that register tools lazily (MCP connections, subagent supervision channels) keep working normally, and nothing needs to be restored when Plan mode exits.
+The one exception is `plan_mode_question`, which Plan mode hides from the model when a better questionnaire is installed — see below. No other tool is ever added to or removed from the active set, so extensions that register tools lazily (MCP connections, subagent supervision channels) keep working normally and nothing needs to be restored when Plan mode exits.
+
+## 🤝 Better questions with `pi-ask-user-question`
+
+With [`@hank-warren/pi-ask-user-question`](../pi-ask-user-question) installed, Plan mode asks its decision questions through that tool instead:
+
+```bash
+pi install npm:@hank-warren/pi-ask-user-question
+```
+
+`plan_mode_question` renders through plain `ctx.ui.select` + `ctx.ui.editor`. `ask_user_question` gives the same decision points a real dialog: markdown **previews** on options, **notes** attached to a choice, several questions as **tabs** you cycle with Tab, **digit hotkeys**, and **checkbox multi-select**. It also allows 1-4 questions instead of 1-3, and 2-6 options on a multi-select question.
+
+Detection is by tool name at runtime, re-evaluated every turn — there is no dependency between the two packages, and installing or removing one never requires touching the other. When `ask_user_question` is present:
+
+- `plan_mode_question` is removed from the **active** tool set, so the model never sees two overlapping question tools and cannot call the weaker one. It stays *registered*, so a historical transcript still resolves it.
+- The Plan-mode system prompt names `ask_user_question` and quotes its bounds and its decline signal.
+
+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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-plan-mode",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Plan mode for Pi: research and design with a durable plan file that survives compaction.",
   "type": "module",
   "keywords": [
@@ -34,7 +34,8 @@
     "src",
     "README.md",
     "NOTICE.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/src/plan-mode.ts

@@ -29,7 +29,12 @@ import {
 	showStoredPlan,
 	updatePlanModeUi,
 } from "./presentation.js";
-import { buildActivePlanPointer, buildPlanModePrompt } from "./prompt.js";
+import {
+	ASK_USER_QUESTION_TOOL,
+	buildActivePlanPointer,
+	buildPlanModePrompt,
+	PLAN_MODE_QUESTION_TOOL,
+} from "./prompt.js";
 import {
 	answerPlanModeQuestions,
 	normalizePlanModeQuestionParams,
@@ -54,6 +59,41 @@ const STATE_ENTRY_TYPE = "plan-mode-state";
  */
 const BLOCKED_TOOLS = new Set(["edit", "write", "update_plan"]);
 
+/**
+ * Which question tool the prompt should name this turn.
+ *
+ * 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.
+ */
+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;
+	const active = pi.getActiveTools();
+	if (!active.includes(PLAN_MODE_QUESTION_TOOL)) return;
+	pi.setActiveTools(active.filter((name) => name !== PLAN_MODE_QUESTION_TOOL));
+}
+
 type InteractiveUi = typeof import("./interactive-ui.js");
 
 interface PlanModeDependencies {
@@ -338,8 +378,13 @@ 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) {
-			return { systemPrompt: `${event.systemPrompt}\n\n${buildPlanModePrompt()}` };
+			return { systemPrompt: `${event.systemPrompt}\n\n${buildPlanModePrompt(questionTool)}` };
 		}
 		// Pointer, not payload: an active plan costs one line of context no matter
 		// how large the plan is, and survives compaction for free.
@@ -450,7 +495,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 			return;
 		}
 		sendPlanModeUserMessage(
-			"Finalize the current implementation plan now. If any material decision remains, use plan_mode_question 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, use ${preferredQuestionTool(pi)} instead. Otherwise call plan_mode_complete alone as your final action with the complete decision-ready plan.`,
 			ctx,
 		);
 	}

package/src/prompt.ts

@@ -1,6 +1,49 @@
 const PLAN_CONTEXT_MARKER = "[PLAN MODE ACTIVE]";
 
-export function buildPlanModePrompt() {
+/** The built-in question tool. Used whenever nothing better is installed. */
+export const PLAN_MODE_QUESTION_TOOL = "plan_mode_question";
+/**
+ * `@hank-warren/pi-ask-user-question`'s tool. Detected by name at runtime, with
+ * no dependency on that package: previews, notes, tabs, digit hotkeys and
+ * checkbox multi-select are all things `plan_mode_question` cannot offer.
+ */
+export const ASK_USER_QUESTION_TOOL = "ask_user_question";
+
+/**
+ * The bits of prompt text that differ between the two question tools. Every
+ * reference to a question tool in the prompt is built from one of these, so the
+ * prompt can never name one tool's bounds beside the other tool's name.
+ */
+interface QuestionToolProfile {
+	name: string;
+	/** How many questions and options the tool actually accepts. */
+	bounds: string;
+	/** What the model sees when the user does not answer. */
+	decline: string;
+}
+
+const QUESTION_TOOL_PROFILES: Record<string, QuestionToolProfile> = {
+	[PLAN_MODE_QUESTION_TOOL]: {
+		name: PLAN_MODE_QUESTION_TOOL,
+		bounds: "Ask 1-3 concise questions with 2-4 meaningful options.",
+		decline: `If ${PLAN_MODE_QUESTION_TOOL} returns cancelled or ui_unavailable`,
+	},
+	[ASK_USER_QUESTION_TOOL]: {
+		name: ASK_USER_QUESTION_TOOL,
+		bounds:
+			"Ask 1-4 concise questions with 2-4 meaningful options each, or 2-6 options when the question sets multiSelect.",
+		decline: `If ${ASK_USER_QUESTION_TOOL} reports that the user declined to answer`,
+	},
+};
+
+/**
+ * Build the Plan-mode prompt around whichever question tool is available.
+ *
+ * The default keeps the exported function callable with no arguments and keeps
+ * a standalone `pi-plan-mode` install reading exactly as it did before.
+ */
+export function buildPlanModePrompt(questionTool: string = PLAN_MODE_QUESTION_TOOL) {
+	const tool = QUESTION_TOOL_PROFILES[questionTool] ?? QUESTION_TOOL_PROFILES[PLAN_MODE_QUESTION_TOOL];
 	return `${PLAN_CONTEXT_MARKER}
 # Plan Mode (Conversational)
 
@@ -29,14 +72,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 plan_mode_question for important preferences, tradeoffs, or assumption locks that cannot be discovered by non-mutating exploration. Ask 1-3 concise questions with 2-4 meaningful options. Do not include filler options.
-- If plan_mode_question returns cancelled or ui_unavailable, 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.
+- 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.
 
 ## 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 plan_mode_question. If interactive UI is unavailable, ask one concise plain-text question instead.
+- If a material decision remains, use ${tool.name}. If interactive UI is unavailable, ask one concise plain-text question instead.
 - 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.
@@ -57,7 +100,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 plan_mode_question 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, continue planning with ${tool.name} instead of calling plan_mode_complete.`;
 }
 
 /**