@hank-warren/pi-plan-mode 1.1.1 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @hank-warren/pi-plan-mode
 
+## 1.2.1
+
+### Patch Changes
+
+- 3fbf632: Persist the thinking-level capture taken while restoring plan mode. The two restore paths applied the configured level without writing the captured previous one, and Pi's `setThinkingLevel` writes the new level into the user's settings — so a session that ended without `session_shutdown` lost the only record of the original level and the next restore captured the plan level as "previous", permanently raising the user's default. An unchanged restore still writes nothing.
+
+## 1.2.0
+
+### Minor Changes
+
+- 358aa1f: re-read `pi-plan-mode.json` when it changes instead of only at session start
+
+  The settings file was read once per session, so a hand-edit — or a Settings save
+  from another session — did nothing until the next restart. That sat badly next to
+  the plan file, which has been hand-editable and read from disk since 1.0.
+
+  Plan mode now watches the settings file's directory (not the file: saves land
+  through a temp file and an atomic rename, which replaces the inode) and re-reads
+  on a 75 ms debounce, so one save costs one load.
+
+  An unparseable file is still reported and replaced by the defaults at session
+  start. Mid-session it is ignored and the last good settings stay in place: a
+  reload sees the file the moment an editor touches it, so an invalid read is
+  usually a partial write, and there is no context to report it through anyway.
+  Deleting the file mid-session does restore the defaults.
+
+  Session start now also honours the injected `settingsPath` dependency when
+  reading, which previously only the Settings menu used — the two could disagree
+  about which file they were looking at.
+
 ## 1.1.1
 
 ### Patch Changes

package/README.md

@@ -4,7 +4,7 @@
 
 `@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. 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.
+**Plan mode is a mode of intent, not a permission system.** It blocks `edit` and `write` 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.
 
@@ -45,7 +45,9 @@ pi -e npm:@hank-warren/pi-plan-mode
 
 `--plan` starts a session directly in Plan mode.
 
-While Plan mode is active, ask the agent to design the change. It can read, search, and run commands, but `edit`, `write`, and `update_plan` are blocked. When the plan is decision-complete, the agent calls `plan_mode_complete` and the plan is written to disk.
+While Plan mode is active, ask the agent to design the change. It can read, search, and run commands, but `edit` and `write` are blocked. When the plan is decision-complete, the agent calls `plan_mode_complete` and the plan is written to disk.
+
+A completed plan is not final until you act on it: just type feedback to revise — the next planning turn supersedes the proposed plan, and the next `plan_mode_complete` replaces it.
 
 From a completed plan you can:
 
@@ -72,6 +74,8 @@ Writes are atomic (temp file plus rename), so a reader never sees a partial plan
 
 Open **Settings** from the `/plan` menu, or edit `$PI_CODING_AGENT_DIR/pi-plan-mode.json` (normally `~/.pi/agent/pi-plan-mode.json`). The file is optional.
 
+The file is read at session start and **re-read whenever it changes**, so a hand-edit — or a save from another session — applies without restarting. Like the plan file itself, it is edited on disk and read from disk.
+
 ```json
 {
   "thinkingLevel": "inherit",
@@ -89,9 +93,11 @@ Open **Settings** from the `/plan` menu, or edit `$PI_CODING_AGENT_DIR/pi-plan-m
 
 Unknown keys are preserved. Settings removed in 1.0 (`defaultPlanTools`, `bashPolicy`, `safeSubcommands`, `implementationPlanRetention`) are ignored rather than treated as errors, so an existing settings file keeps working.
 
+A settings file that does not parse is reported at session start and the defaults are used. Mid-session it is ignored instead, leaving the last good settings in place: an edit is seen the moment your editor touches the file, so an unreadable one is usually a half-finished save rather than what you meant.
+
 ## 🔐 What Plan mode does and does not enforce
 
-Plan mode blocks exactly three tools while planning: `edit`, `write`, and `update_plan`. That is the whole enforcement surface.
+Plan mode blocks exactly two tools while planning: `edit` and `write`. That is the whole enforcement surface. Checklist tools (a `todo` extension, for example) are deliberately not blocked — a task list is ephemeral planning scratch, and the planning prompt steers the model away from execution-progress tracking.
 
 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-plan-mode",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "Plan mode for Pi: research and design with a durable plan file that survives compaction.",
   "type": "module",
   "keywords": [

package/src/plan-action-menus.ts

@@ -10,6 +10,7 @@ interface MenuLifecycle {
 const IMPLEMENTATION_CONTEXT_LINES = [
 	"Implement here keeps this planning conversation.",
 	"Start fresh opens a new session that reads the same plan file.",
+	"Or just type feedback to revise — the next completed plan supersedes this one.",
 ] as const;
 
 interface PlanMenuOptions extends MenuLifecycle {

package/src/plan-launch-menu.ts

@@ -13,7 +13,7 @@ const HOW_IT_WORKS_LINES = [
 	"Plan mode is for research and design, not implementation.",
 	"Explore the codebase, ask decision questions, then finish with plan_mode_complete.",
 	"The plan is written to a durable file that survives compaction and can be hand-edited.",
-	"Built-in edit, write, and update_plan are blocked while planning.",
+	"Built-in edit and write are blocked while planning.",
 	"All other tools stay exactly as configured; command safety is left to your permission extension.",
 	"When the plan is ready: implement here, or start a fresh session that reads the same file.",
 ] as const;

package/src/plan-mode.ts

@@ -1,3 +1,5 @@
+import { watch } from "node:fs";
+import { basename, dirname } from "node:path";
 import type {
 	ExtensionAPI,
 	ExtensionCommandContext,
@@ -46,6 +48,7 @@ import {
 	awaitPlanModeSettingsWrites,
 	configuredThinkingLevel,
 	type PlanModeSettings,
+	planModeSettingsPath,
 	readPlanModeSettings,
 } from "./settings.js";
 import { type PlanModeState, restorePlanModeState } from "./state.js";
@@ -56,8 +59,18 @@ const STATE_ENTRY_TYPE = "plan-mode-state";
  * MCP, and other extension tools — is left to the session's normal permission
  * layer (for example @hank-warren/pi-auto-permissions), so Plan mode never
  * mutates the active tool set and never fights other extensions for it.
+ * Checklist tools (a `todo` extension, for example) are deliberately not
+ * blocked: a task list is ephemeral planning scratch, and the planning prompt
+ * already steers the model away from execution-progress tooling. (`update_plan`
+ * was once listed here; it was a pre-1.0 upstream tool that no longer exists.)
  */
-const BLOCKED_TOOLS = new Set(["edit", "write", "update_plan"]);
+const BLOCKED_TOOLS = new Set(["edit", "write"]);
+/**
+ * One hand-edit or menu save fans out into several filesystem events (temp file
+ * created, renamed into place). Collapsing them into one re-read keeps a save
+ * to a single load.
+ */
+const SETTINGS_RELOAD_DEBOUNCE_MS = 75;
 
 /**
  * Which question tool the prompt should name this turn.
@@ -124,6 +137,8 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 	let workflowGeneration = 0;
 	let refreshStateBeforeFirstAgentStart = false;
 	let menuController = new AbortController();
+	let settingsWatch: ReturnType<typeof watch> | undefined;
+	let settingsReloadTimer: ReturnType<typeof setTimeout> | undefined;
 	const persistState = () => pi.appendEntry<PlanModeState>(STATE_ENTRY_TYPE, state);
 	const planExports = createPlanExportController({
 		getState: () => state,
@@ -146,8 +161,14 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		exportPlan: (ctx, path, signal, isCurrent) => planExports.export(path, ctx, signal, isCurrent),
 		stay: updateUi,
 		exitReady: (ctx) => {
+			// Same had-plan branching as the /plan exit command: the menu must not
+			// claim a plan was discarded when none was ever completed.
+			const hadPlan = state.planPath !== undefined;
 			void exitPlanMode(ctx).then(() => {
-				ctx.ui.notify("Plan mode disabled. Proposed plan discarded.", "info");
+				ctx.ui.notify(
+					hadPlan ? "Plan mode disabled. Proposed plan discarded." : "Plan mode disabled.",
+					"info",
+				);
 			});
 		},
 	});
@@ -295,6 +316,73 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		},
 	});
 
+	const readRuntimeSettings = () =>
+		dependencies.readSettings?.() ?? readPlanModeSettings(dependencies.settingsPath);
+
+	/**
+	 * `ctx` present means this is the session-start load: problems are reported
+	 * and anything unusable falls back to defaults.
+	 *
+	 * `ctx` absent means a watch-triggered reload, which keeps the last good
+	 * settings when the file no longer parses. A hand-edit is observed the moment
+	 * the editor touches the file, so an invalid read is usually a half-written
+	 * save rather than intent — discarding a working export path for it, with no
+	 * `ctx` to explain why, would be worse than waiting for the next write. A
+	 * genuinely broken file is still reported at the next session start.
+	 */
+	const loadPlanModeSettings = async (generation: number, ctx?: ExtensionContext) => {
+		const loaded = await readRuntimeSettings();
+		if (generation !== menuGeneration || menuController.signal.aborted) return;
+		if (loaded.kind === "invalid" && !ctx) return;
+		settings = loaded.kind === "loaded" ? loaded.settings : { thinkingLevel: "inherit" };
+		if (!ctx) return;
+		if (loaded.kind === "invalid") {
+			ctx.ui.notify(`pi-plan-mode settings ignored: ${loaded.reason}`, "warning");
+		}
+		if (loaded.notice) ctx.ui.notify(loaded.notice, "warning");
+	};
+
+	const stopPlanModeSettingsWatch = () => {
+		if (settingsReloadTimer) {
+			clearTimeout(settingsReloadTimer);
+			settingsReloadTimer = undefined;
+		}
+		settingsWatch?.close();
+		settingsWatch = undefined;
+	};
+
+	/**
+	 * Watches the settings file's directory rather than the file itself: saves go
+	 * through a temp file and an atomic rename, and a watch bound to the old inode
+	 * would go deaf after the first one.
+	 */
+	const startPlanModeSettingsWatch = (generation: number) => {
+		stopPlanModeSettingsWatch();
+		if (dependencies.readSettings) return;
+		const watchedPath = dependencies.settingsPath ?? planModeSettingsPath();
+		const watchedFile = basename(watchedPath);
+		try {
+			const watcher = watch(dirname(watchedPath), { persistent: false }, (event, changedFile) => {
+				if (event !== "rename" && event !== "change") return;
+				// A null filename means the platform could not name the entry; reload
+				// rather than miss the edit. The agent directory holds other churn, so
+				// a named entry that is not ours is ignored.
+				if (changedFile && changedFile.toString() !== watchedFile) return;
+				if (settingsReloadTimer) clearTimeout(settingsReloadTimer);
+				settingsReloadTimer = setTimeout(() => {
+					settingsReloadTimer = undefined;
+					void loadPlanModeSettings(generation);
+				}, SETTINGS_RELOAD_DEBOUNCE_MS);
+			});
+			watcher.on("error", stopPlanModeSettingsWatch);
+			settingsWatch = watcher;
+		} catch {
+			// An unwatchable directory only costs the live reload; settings still
+			// load at session start.
+			stopPlanModeSettingsWatch();
+		}
+	};
+
 	pi.on("session_start", async (event, ctx) => {
 		const generation = ++menuGeneration;
 		refreshStateBeforeFirstAgentStart = event.reason === "new";
@@ -305,19 +393,15 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		settings = { thinkingLevel: "inherit" };
 		sessionPlanPath = resolveSessionPlanPath(ctx);
 		restoreState(ctx);
-		const loadedSettings = await (dependencies.readSettings?.() ?? readPlanModeSettings());
+		await loadPlanModeSettings(generation, ctx);
 		if (generation !== menuGeneration || menuController.signal.aborted) return;
-		if (loadedSettings.kind === "loaded") settings = loadedSettings.settings;
-		else if (loadedSettings.kind === "invalid") {
-			ctx.ui.notify(`pi-plan-mode settings ignored: ${loadedSettings.reason}`, "warning");
-		}
-		if (loadedSettings.notice) ctx.ui.notify(loadedSettings.notice, "warning");
+		startPlanModeSettingsWatch(generation);
 		const persistFlagActivation = pi.getFlag("plan") === true && !state.enabled;
 		if (persistFlagActivation) {
 			state = { ...state, enabled: true, awaitingAction: state.planPath !== undefined };
 		}
-		if (state.enabled) applyPlanThinkingLevel();
-		if (persistFlagActivation) persistState();
+		const capturedThinkingLevel = state.enabled ? applyPlanThinkingLevel() : false;
+		if (persistFlagActivation || capturedThinkingLevel) persistState();
 		updateUi(ctx);
 	});
 
@@ -336,6 +420,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 
 	pi.on("session_shutdown", async (_event, ctx) => {
 		menuGeneration += 1;
+		stopPlanModeSettingsWatch();
 		menuController.abort(new DOMException("Plan-mode session shut down", "AbortError"));
 		pendingReadyNonce = undefined;
 		latestCommandContext = undefined;
@@ -348,7 +433,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 	});
 
 	/**
-	 * The complete enforcement surface: three static built-in names. Plan mode
+	 * The complete enforcement surface: two static built-in names. Plan mode
 	 * does not classify, inspect, or filter any other tool.
 	 */
 	pi.on("tool_call", async (event) => {
@@ -356,10 +441,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		if (!BLOCKED_TOOLS.has(event.toolName)) return;
 		return {
 			block: true,
-			reason:
-				event.toolName === "update_plan"
-					? "Plan mode blocks update_plan because it tracks execution progress rather than conversational planning."
-					: `Plan mode blocks '${event.toolName}' because planning must not mutate files. Finish the plan with plan_mode_complete, then implement.`,
+			reason: `Plan mode blocks '${event.toolName}' because planning must not mutate files. Finish the plan with plan_mode_complete, then implement.`,
 		};
 	});
 
@@ -367,7 +449,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		if (refreshStateBeforeFirstAgentStart) {
 			refreshStateBeforeFirstAgentStart = false;
 			restoreState(ctx);
-			if (state.enabled) applyPlanThinkingLevel();
+			if (state.enabled && applyPlanThinkingLevel()) persistState();
 			updateUi(ctx);
 		}
 		if (state.enabled && state.awaitingAction) {
@@ -624,26 +706,42 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		};
 	}
 
-	function applyPlanThinkingLevel() {
+	/**
+	 * Returns true when the captured thinking levels changed, so the restore
+	 * paths can persist that capture. It is the only record of the user's level:
+	 * `setPlanThinkingLevel` goes through Pi's `setThinkingLevel`, which writes
+	 * the new level into the user's settings, so a capture left only in memory is
+	 * lost if the session ends without `session_shutdown`.
+	 */
+	function applyPlanThinkingLevel(): boolean {
 		if (state.manualThinkingLevel) {
 			if (pi.getThinkingLevel() !== state.manualThinkingLevel) {
 				setPlanThinkingLevel(pi, state.manualThinkingLevel);
 			}
-			return;
+			return false;
 		}
 		const configured = configuredThinkingLevel(settings);
 		if (!configured) {
+			if (state.previousThinkingLevel === undefined && state.appliedThinkingLevel === undefined) {
+				return false;
+			}
 			state = {
 				...state,
 				previousThinkingLevel: undefined,
 				appliedThinkingLevel: undefined,
 			};
-			return;
+			return true;
 		}
 		const current = pi.getThinkingLevel();
+		const capturedPrevious = state.previousThinkingLevel;
+		const capturedApplied = state.appliedThinkingLevel;
 		if (!state.appliedThinkingLevel) state.previousThinkingLevel = current;
 		if (current !== configured) setPlanThinkingLevel(pi, configured);
 		state.appliedThinkingLevel = pi.getThinkingLevel();
+		return (
+			state.previousThinkingLevel !== capturedPrevious ||
+			state.appliedThinkingLevel !== capturedApplied
+		);
 	}
 
 	function captureManualThinkingLevel() {

package/src/presentation.ts

@@ -10,7 +10,7 @@ export function updatePlanModeUi(ctx: ExtensionContext, state: PlanModeState) {
 	if (state.enabled && state.awaitingAction) {
 		ctx.ui.setWidget(PLAN_WIDGET_KEY, [
 			"Proposed plan ready",
-			"Use /plan to implement, export, revise, or exit Plan mode.",
+			"Use /plan to implement, export, or exit — or type feedback to revise.",
 		]);
 	} else if (state.enabled) {
 		ctx.ui.setWidget(PLAN_WIDGET_KEY, [
@@ -48,7 +48,13 @@ export async function showStoredPlan(
 		);
 		return;
 	}
-	const title = state.enabled ? "Proposed Plan" : "Active Implementation Plan";
+	// enabled without awaitingAction but with a stored plan means revision
+	// feedback superseded the completed plan: show it, but never as current.
+	const title = state.enabled
+		? state.awaitingAction
+			? "Proposed Plan"
+			: "Superseded Proposed Plan (revision in progress — awaiting a new plan_mode_complete)"
+		: "Active Implementation Plan";
 	showPlanModePlan(pi, ctx, title, plan);
 }
 
@@ -76,6 +82,9 @@ export function showPlanModePlan(
 export function planModeStatusText(state: PlanModeState) {
 	if (state.enabled) {
 		if (state.awaitingAction) return "Plan mode is active and a proposed plan is ready.";
+		if (state.planPath) {
+			return "Plan mode is active; revision in progress. The stored plan is superseded until the next plan_mode_complete.";
+		}
 		return "Plan mode is active. Explore, ask, and finish with plan_mode_complete when decision-ready.";
 	}
 	if (state.planPath) return "An implementation plan is active.";

package/src/prompt.ts

@@ -53,7 +53,7 @@ You are in Plan Mode, a collaboration mode for producing a decision-complete imp
 
 - 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 update_plan/TODO tooling in Plan Mode; Plan Mode is conversational planning, not execution progress tracking.
+- 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.
 - Do not perform mutating actions: no edit/write tools, no patching, no formatting that rewrites files, no dependency installation, no commits, no migrations.
 - Gather information freely: read files, search, inspect configuration, and run read-only commands.