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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @hank-warren/pi-plan-mode
 
+## 1.3.0
+
+### Minor Changes
+
+- 9dd9833: Remove the plan-mode thinking level. Plan mode no longer mutates session-global state: `pi.setThinkingLevel` writes through to the user's real settings, so the "temporary" level was a durable change that needed three shadow state fields, a `thinking_level_select` listener and restore logic on every exit path to undo. Thinking level and model are session settings now, and whatever you choose while planning carries into implementation. The `thinkingLevel` setting is gone and `/plan settings` drops its row; an existing key in `pi-plan-mode.json` is ignored rather than rejected — preserved verbatim on save, and no longer validated, so even a garbage value keeps the file loading. A one-shot migration restores the level an interrupted pre-1.3.0 session left raised, but only while the live level still matches what plan mode applied.
+
 ## 1.2.1
 
 ### Patch Changes

package/README.md

@@ -78,20 +78,17 @@ The file is read at session start and **re-read whenever it changes**, so a hand
 
 ```json
 {
-  "thinkingLevel": "inherit",
   "defaultPlanExportPath": "PLAN.md"
 }
 ```
 
-### Plan thinking
-
-`thinkingLevel` requests a fixed thinking level while Plan mode is active. Supported values are `inherit`, `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. The extension restores your previous level on exit unless you changed it manually during Plan mode. Saving applies to the next Plan workflow, never one already running.
-
 ### Export destination
 
 `defaultPlanExportPath` controls only exports that omit a path, and defaults to `PLAN.md`. Relative values resolve against the current working directory at export time. An explicit `/plan export <path>` always wins. Export never overwrites an existing file, directory, or symbolic link.
 
-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.
+Unknown keys are preserved. Settings removed in 1.0 (`defaultPlanTools`, `bashPolicy`, `safeSubcommands`, `implementationPlanRetention`) and in 1.3 (`thinkingLevel`) are ignored rather than treated as errors, so an existing settings file keeps working.
+
+Thinking level and model are **session** settings, and Plan mode never changes either one. Set them with Pi's own controls; whatever you choose while planning carries into implementation, because that is what session state does.
 
 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.
 

package/package.json

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

package/src/extension-runtime.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { PlanModeFixedThinkingLevel } from "./settings.js";
+import type { LegacyThinkingCapture } from "./state.js";
 
 type AgentSettledHandler = (event: unknown, ctx: ExtensionContext) => unknown;
 
@@ -11,8 +11,14 @@ export function onAgentSettled(pi: ExtensionAPI, handler: AgentSettledHandler) {
 	).on("agent_settled", handler);
 }
 
-export function setPlanThinkingLevel(pi: ExtensionAPI, level: PlanModeFixedThinkingLevel) {
-	(pi.setThinkingLevel as unknown as (level: PlanModeFixedThinkingLevel) => void)(level);
+/**
+ * Only the one-shot migration that undoes a pre-1.3.0 thinking-level change
+ * still calls this. Plan mode never sets the thinking level otherwise.
+ *
+ * legacy: delete in 1.4.0
+ */
+export function setPlanThinkingLevel(pi: ExtensionAPI, level: LegacyThinkingCapture["previous"]) {
+	(pi.setThinkingLevel as unknown as (level: string) => void)(level);
 }
 
 export function isStaleExtensionContextError(error: unknown) {

package/src/plan-mode.ts

@@ -46,12 +46,11 @@ import {
 } from "./question-tool.js";
 import {
 	awaitPlanModeSettingsWrites,
-	configuredThinkingLevel,
 	type PlanModeSettings,
 	planModeSettingsPath,
 	readPlanModeSettings,
 } from "./settings.js";
-import { type PlanModeState, restorePlanModeState } from "./state.js";
+import { type PlanModeState, readLegacyThinkingCapture, restorePlanModeState } from "./state.js";
 
 const STATE_ENTRY_TYPE = "plan-mode-state";
 /**
@@ -128,7 +127,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		return interactiveUiPromise;
 	};
 	let state: PlanModeState = { enabled: false, awaitingAction: false };
-	let settings: PlanModeSettings = { thinkingLevel: "inherit" };
+	let settings: PlanModeSettings = {};
 	let sessionPlanPath: string | undefined;
 	let readyPresentationNonce = 0;
 	let pendingReadyNonce: number | undefined;
@@ -334,7 +333,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		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" };
+		settings = loaded.kind === "loaded" ? loaded.settings : {};
 		if (!ctx) return;
 		if (loaded.kind === "invalid") {
 			ctx.ui.notify(`pi-plan-mode settings ignored: ${loaded.reason}`, "warning");
@@ -390,9 +389,10 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		menuController = new AbortController();
 		pendingReadyNonce = undefined;
 		latestCommandContext = undefined;
-		settings = { thinkingLevel: "inherit" };
+		settings = {};
 		sessionPlanPath = resolveSessionPlanPath(ctx);
 		restoreState(ctx);
+		repairLegacyThinkingLevel(ctx);
 		await loadPlanModeSettings(generation, ctx);
 		if (generation !== menuGeneration || menuController.signal.aborted) return;
 		startPlanModeSettingsWatch(generation);
@@ -400,24 +400,10 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		if (persistFlagActivation) {
 			state = { ...state, enabled: true, awaitingAction: state.planPath !== undefined };
 		}
-		const capturedThinkingLevel = state.enabled ? applyPlanThinkingLevel() : false;
-		if (persistFlagActivation || capturedThinkingLevel) persistState();
+		if (persistFlagActivation) persistState();
 		updateUi(ctx);
 	});
 
-	pi.on("thinking_level_select", (event) => {
-		if (!state.enabled || !state.appliedThinkingLevel) return;
-		if (event.level !== state.appliedThinkingLevel) {
-			state = {
-				...state,
-				manualThinkingLevel: event.level,
-				previousThinkingLevel: undefined,
-				appliedThinkingLevel: undefined,
-			};
-			persistState();
-		}
-	});
-
 	pi.on("session_shutdown", async (_event, ctx) => {
 		menuGeneration += 1;
 		stopPlanModeSettingsWatch();
@@ -426,9 +412,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		latestCommandContext = undefined;
 		refreshStateBeforeFirstAgentStart = false;
 		await awaitPlanModeSettingsWrites(dependencies.settingsPath);
-		captureManualThinkingLevel();
 		persistState();
-		if (state.enabled) restoreThinkingLevel();
 		clearUi(ctx);
 	});
 
@@ -449,7 +433,6 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		if (refreshStateBeforeFirstAgentStart) {
 			refreshStateBeforeFirstAgentStart = false;
 			restoreState(ctx);
-			if (state.enabled && applyPlanThinkingLevel()) persistState();
 			updateUi(ctx);
 		}
 		if (state.enabled && state.awaitingAction) {
@@ -494,7 +477,6 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 	function enterPlanMode(ctx: ExtensionContext) {
 		workflowGeneration += 1;
 		state = { ...state, enabled: true, awaitingAction: false };
-		applyPlanThinkingLevel();
 		persistState();
 		updateUi(ctx);
 	}
@@ -507,7 +489,6 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 			ctx.ui.notify("Plan mode enabled. I will explore and plan, but not modify files.", "info");
 		}
 		if (sendPlanModeUserMessage(prompt, ctx)) return;
-		if (!wasEnabled) restoreThinkingLevel();
 		state = previousState;
 		persistState();
 		updateUi(ctx);
@@ -515,7 +496,6 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 
 	async function exitPlanMode(ctx: ExtensionContext, options: { keepPlanFile?: boolean } = {}) {
 		workflowGeneration += 1;
-		const wasEnabled = state.enabled;
 		const planPath = state.planPath;
 		pendingReadyNonce = undefined;
 		state = {
@@ -523,12 +503,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 			enabled: false,
 			planPath: undefined,
 			awaitingAction: false,
-			manualThinkingLevel: undefined,
 		};
-		if (wasEnabled) {
-			restoreThinkingLevel();
-			state = { ...state, manualThinkingLevel: undefined };
-		}
 		persistState();
 		updateUi(ctx);
 		if (planPath && !options.keepPlanFile) await deletePlanFile(planPath);
@@ -600,25 +575,18 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 
 		workflowGeneration += 1;
 		const previousState = state;
-		const wasEnabled = state.enabled;
 		pendingReadyNonce = undefined;
 		state = {
 			...state,
 			enabled: false,
 			awaitingAction: false,
 			planPath,
-			manualThinkingLevel: undefined,
 		};
-		if (wasEnabled) {
-			restoreThinkingLevel();
-			state = { ...state, manualThinkingLevel: undefined };
-		}
 		persistState();
 		updateUi(ctx);
 
 		if (!sendPlanModeUserMessage(formatImplementationHandoff(planPath), ctx)) {
 			state = previousState;
-			if (wasEnabled) applyPlanThinkingLevel();
 			persistState();
 			updateUi(ctx);
 		}
@@ -707,66 +675,21 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 	}
 
 	/**
-	 * 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`.
+	 * pi-plan-mode <= 1.2.1 raised the thinking level while planning, and because
+	 * `pi.setThinkingLevel` writes through to the user's real settings, a session
+	 * that died before its restore left that change durable. If the newest state
+	 * entry still carries the capture and the live level still equals what Plan
+	 * mode applied, put the user's level back — once. Persisting state in the new
+	 * shape drops the capture, so the next session finds nothing to repair. A
+	 * user who has already moved the level themselves is left alone.
+	 *
+	 * legacy: delete in 1.4.0
 	 */
-	function applyPlanThinkingLevel(): boolean {
-		if (state.manualThinkingLevel) {
-			if (pi.getThinkingLevel() !== state.manualThinkingLevel) {
-				setPlanThinkingLevel(pi, state.manualThinkingLevel);
-			}
-			return false;
-		}
-		const configured = configuredThinkingLevel(settings);
-		if (!configured) {
-			if (state.previousThinkingLevel === undefined && state.appliedThinkingLevel === undefined) {
-				return false;
-			}
-			state = {
-				...state,
-				previousThinkingLevel: undefined,
-				appliedThinkingLevel: undefined,
-			};
-			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() {
-		if (!state.appliedThinkingLevel) return;
-		const current = pi.getThinkingLevel();
-		if (current === state.appliedThinkingLevel) return;
-		state = {
-			...state,
-			manualThinkingLevel: current,
-			previousThinkingLevel: undefined,
-			appliedThinkingLevel: undefined,
-		};
-	}
-
-	function restoreThinkingLevel() {
-		captureManualThinkingLevel();
-		const { appliedThinkingLevel, previousThinkingLevel } = state;
-		if (
-			appliedThinkingLevel &&
-			previousThinkingLevel &&
-			pi.getThinkingLevel() === appliedThinkingLevel
-		) {
-			setPlanThinkingLevel(pi, previousThinkingLevel);
-		}
-		state = { ...state, appliedThinkingLevel: undefined, previousThinkingLevel: undefined };
+	function repairLegacyThinkingLevel(ctx: ExtensionContext) {
+		const legacy = readLegacyThinkingCapture(ctx.sessionManager.getBranch(), STATE_ENTRY_TYPE);
+		if (!legacy || pi.getThinkingLevel() !== legacy.applied) return;
+		setPlanThinkingLevel(pi, legacy.previous);
+		persistState();
 	}
 
 	function resolveSessionPlanPath(ctx: ExtensionContext) {

package/src/settings-menu.ts

@@ -1,9 +1,9 @@
+import { readFile } from "node:fs/promises";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { defineMenu, type RunMenuResult, runMenu } from "@narumitw/pi-tui-kit";
 import { planExportDestination } from "./plan-export.js";
 import {
 	configuredPlanExportPath,
-	PLAN_MODE_THINKING_LEVELS,
 	type PlanModeSettings,
 	type PlanModeSettingsLoadResult,
 	type PlanModeSettingsPatch,
@@ -18,6 +18,8 @@ interface SettingsMenuState {
 	settings: PlanModeSettings;
 	notice?: string;
 	reason?: string;
+	/** The removed `thinkingLevel` key is still in the file. legacy: delete in 1.4.0 */
+	hasLegacyThinkingLevel?: boolean;
 }
 
 export interface PlanModeSettingsMenuOptions {
@@ -34,7 +36,7 @@ export interface PlanModeSettingsMenuOptions {
 }
 
 type Screen = "settings" | "export";
-type Action = "set-thinking" | "open-export" | "set-export";
+type Action = "open-export" | "set-export";
 
 export async function showPlanModeSettings(
 	ctx: ExtensionContext,
@@ -49,15 +51,16 @@ export async function showPlanModeSettings(
 		if (loaded.kind === "invalid") {
 			return {
 				kind: "invalid",
-				settings: { thinkingLevel: "inherit" },
+				settings: {},
 				notice: loaded.notice,
 				reason: loaded.reason,
 			};
 		}
 		return {
 			kind: "valid",
-			settings: loaded.kind === "loaded" ? loaded.settings : { thinkingLevel: "inherit" },
+			settings: loaded.kind === "loaded" ? loaded.settings : {},
 			notice: loaded.notice,
+			hasLegacyThinkingLevel: await hasLegacyThinkingLevel(settingsPath),
 		};
 	};
 
@@ -70,16 +73,8 @@ export async function showPlanModeSettings(
 					: {
 							kind: "settings",
 							title: "Plan Mode Settings",
-							lines: settingsLines(settingsPath, state.notice),
+							lines: settingsLines(settingsPath, state),
 							items: [
-								{
-									id: "thinkingLevel",
-									label: "Plan thinking",
-									description: "Set the thinking level when the next Plan workflow starts.",
-									currentValue: state.settings.thinkingLevel,
-									values: PLAN_MODE_THINKING_LEVELS,
-									action: "set-thinking",
-								},
 								{
 									id: "defaultPlanExportPath",
 									label: "Export destination",
@@ -107,19 +102,6 @@ export async function showPlanModeSettings(
 			},
 		},
 		actions: {
-			"set-thinking": async ({ ctx: actionCtx, value, signal }) => {
-				if (
-					!PLAN_MODE_THINKING_LEVELS.includes(value as (typeof PLAN_MODE_THINKING_LEVELS)[number])
-				) {
-					return { kind: "rejected" };
-				}
-				return savePatch(
-					actionCtx,
-					{ thinkingLevel: value as PlanModeSettings["thinkingLevel"] },
-					signal,
-					`Plan mode thinking level: ${value}. Applies to the next Plan workflow.`,
-				);
-			},
 			"open-export": async () => ({ kind: "to", screen: "export" }),
 			"set-export": async ({ ctx: actionCtx, value, signal }) => {
 				const defaultPlanExportPath = value?.trim() || null;
@@ -171,14 +153,35 @@ export async function showPlanModeSettings(
 	}
 }
 
-function settingsLines(settingsPath: string, notice: string | undefined) {
+function settingsLines(settingsPath: string, state: SettingsMenuState) {
 	return [
 		`User settings · ${safeTerminalText(settingsPath)}`,
-		"Plan thinking applies to the next workflow; the export destination applies to its next action.",
-		...(notice ? [safeTerminalText(notice)] : []),
+		"The export destination applies to its next action.",
+		// legacy: delete in 1.4.0
+		...(state.hasLegacyThinkingLevel
+			? [
+					"thinkingLevel is no longer used — thinking is a session setting and Plan mode never changes it.",
+				]
+			: []),
+		...(state.notice ? [safeTerminalText(state.notice)] : []),
 	];
 }
 
+/**
+ * The removed key is preserved verbatim on save, so the only way to know it is
+ * still there is to look at the file. A read failure simply hides the notice.
+ *
+ * legacy: delete in 1.4.0
+ */
+async function hasLegacyThinkingLevel(settingsPath: string) {
+	try {
+		const parsed: unknown = JSON.parse(await readFile(settingsPath, "utf8"));
+		return typeof parsed === "object" && parsed !== null && Object.hasOwn(parsed, "thinkingLevel");
+	} catch {
+		return false;
+	}
+}
+
 function invalidScreen(settingsPath: string, state: SettingsMenuState) {
 	return {
 		kind: "detail" as const,

package/src/settings.ts

@@ -7,27 +7,13 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 export const PLAN_MODE_SETTINGS_FILE = "pi-plan-mode.json";
 const LEGACY_PLAN_MODE_SETTINGS_FILE = "plan-mode.json";
 const MAX_SETTINGS_BYTES = 64 * 1024;
-export const PLAN_MODE_THINKING_LEVELS = [
-	"inherit",
-	"off",
-	"minimal",
-	"low",
-	"medium",
-	"high",
-	"xhigh",
-	"max",
-] as const;
 export const DEFAULT_PLAN_EXPORT_PATH = "PLAN.md";
 const MAX_PLAN_EXPORT_PATH_LENGTH = 4096;
 
-export type PlanModeThinkingLevel = (typeof PLAN_MODE_THINKING_LEVELS)[number];
-export type PlanModeFixedThinkingLevel = Exclude<PlanModeThinkingLevel, "inherit">;
 export interface PlanModeSettings {
-	thinkingLevel: PlanModeThinkingLevel;
 	defaultPlanExportPath?: string;
 }
 export interface PlanModeSettingsPatch {
-	thinkingLevel?: PlanModeThinkingLevel;
 	defaultPlanExportPath?: string | null;
 }
 export interface UpdatePlanModeSettingsOptions {
@@ -59,21 +45,13 @@ function legacyPlanModeSettingsPath() {
 
 /**
  * Unknown top-level keys are tolerated and preserved on save. Settings removed
- * in the plan-file rewrite (defaultPlanTools, bashPolicy, safeSubcommands,
- * implementationPlanRetention) therefore keep an existing file valid instead of
- * failing it closed on upgrade.
+ * over time (defaultPlanTools, bashPolicy, safeSubcommands,
+ * implementationPlanRetention, thinkingLevel) therefore keep an existing file
+ * valid instead of failing it closed on upgrade.
  */
 export function normalizePlanModeSettings(value: unknown): PlanModeSettings | undefined {
 	if (!isSettingsDocument(value)) return undefined;
-	const thinkingLevel = Object.hasOwn(value, "thinkingLevel")
-		? Reflect.get(value, "thinkingLevel")
-		: "inherit";
-	if (!PLAN_MODE_THINKING_LEVELS.includes(thinkingLevel as PlanModeThinkingLevel)) {
-		return undefined;
-	}
-	const settings: PlanModeSettings = {
-		thinkingLevel: thinkingLevel as PlanModeThinkingLevel,
-	};
+	const settings: PlanModeSettings = {};
 	if (Object.hasOwn(value, "defaultPlanExportPath")) {
 		const defaultPlanExportPath = normalizePlanExportPath(
 			Reflect.get(value, "defaultPlanExportPath"),
@@ -143,7 +121,6 @@ export function updatePlanModeSettings(
 		options.signal?.throwIfAborted();
 		const current = await readSettingsDocumentForUpdate(settingsPath, legacySettingsPath);
 		const updated: SettingsDocument = { ...current };
-		if (patch.thinkingLevel !== undefined) updated.thinkingLevel = patch.thinkingLevel;
 		if (patch.defaultPlanExportPath === null) delete updated.defaultPlanExportPath;
 		else if (patch.defaultPlanExportPath !== undefined) {
 			updated.defaultPlanExportPath = patch.defaultPlanExportPath;
@@ -310,12 +287,6 @@ function safeReadError(error: unknown) {
 	return error instanceof Error ? error.message : String(error);
 }
 
-export function configuredThinkingLevel(
-	settings: PlanModeSettings,
-): PlanModeFixedThinkingLevel | undefined {
-	return settings.thinkingLevel === "inherit" ? undefined : settings.thinkingLevel;
-}
-
 export function configuredPlanExportPath(settings: PlanModeSettings) {
 	return settings.defaultPlanExportPath ?? DEFAULT_PLAN_EXPORT_PATH;
 }

package/src/state.ts

@@ -1,8 +1,7 @@
-import { PLAN_MODE_THINKING_LEVELS, type PlanModeFixedThinkingLevel } from "./settings.js";
-
 /**
- * The plan lives on disk, so session state carries only a pointer to it plus
- * the thinking-level bookkeeping needed to restore the user's level on exit.
+ * The plan lives on disk, so session state carries only a pointer to it and
+ * the ready-for-action flag. Plan mode holds no session-global state of its
+ * own: thinking level and model are session settings it never touches.
  */
 export interface PlanModeState {
 	enabled: boolean;
@@ -10,9 +9,6 @@ export interface PlanModeState {
 	planPath?: string;
 	/** A completed plan is waiting for the user to choose how to proceed. */
 	awaitingAction: boolean;
-	previousThinkingLevel?: PlanModeFixedThinkingLevel;
-	appliedThinkingLevel?: PlanModeFixedThinkingLevel;
-	manualThinkingLevel?: PlanModeFixedThinkingLevel;
 }
 
 type SessionEntry = {
@@ -22,15 +18,7 @@ type SessionEntry = {
 };
 
 export function restorePlanModeState(entries: unknown[], stateEntryType: string): PlanModeState {
-	const branch = entries as SessionEntry[];
-	let entry: SessionEntry | undefined;
-	for (let index = branch.length - 1; index >= 0; index -= 1) {
-		const candidate = branch[index];
-		if (candidate?.type === "custom" && candidate.customType === stateEntryType) {
-			entry = candidate;
-			break;
-		}
-	}
+	const entry = newestStateEntry(entries, stateEntryType);
 	if (!isRecord(entry?.data)) return { enabled: false, awaitingAction: false };
 
 	const enabled = entry.data.enabled === true;
@@ -39,14 +27,54 @@ export function restorePlanModeState(entries: unknown[], stateEntryType: string)
 		enabled,
 		planPath,
 		awaitingAction: enabled && entry.data.awaitingAction === true && planPath !== undefined,
-		previousThinkingLevel: enabled
-			? fixedThinkingLevel(entry.data.previousThinkingLevel)
-			: undefined,
-		appliedThinkingLevel: enabled ? fixedThinkingLevel(entry.data.appliedThinkingLevel) : undefined,
-		manualThinkingLevel: enabled ? fixedThinkingLevel(entry.data.manualThinkingLevel) : undefined,
 	};
 }
 
+function newestStateEntry(entries: unknown[], stateEntryType: string): SessionEntry | undefined {
+	const branch = entries as SessionEntry[];
+	for (let index = branch.length - 1; index >= 0; index -= 1) {
+		const candidate = branch[index];
+		if (candidate?.type === "custom" && candidate.customType === stateEntryType) return candidate;
+	}
+	return undefined;
+}
+
+// legacy: delete in 1.4.0
+const LEGACY_THINKING_LEVELS = [
+	"off",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max",
+] as const;
+
+// legacy: delete in 1.4.0
+export type LegacyThinkingCapture = {
+	previous: (typeof LEGACY_THINKING_LEVELS)[number];
+	applied: (typeof LEGACY_THINKING_LEVELS)[number];
+};
+
+/**
+ * Reads the thinking-level capture written by pi-plan-mode <= 1.2.1, so a
+ * session interrupted while Plan mode held a raised level can have the user's
+ * level put back once. Both halves must be present and valid: a partial or
+ * absent capture is nothing to repair.
+ *
+ * legacy: delete in 1.4.0
+ */
+export function readLegacyThinkingCapture(
+	entries: unknown[],
+	stateEntryType: string,
+): LegacyThinkingCapture | undefined {
+	const entry = newestStateEntry(entries, stateEntryType);
+	if (!isRecord(entry?.data)) return undefined;
+	const previous = legacyThinkingLevel(entry.data.previousThinkingLevel);
+	const applied = legacyThinkingLevel(entry.data.appliedThinkingLevel);
+	return previous && applied ? { previous, applied } : undefined;
+}
+
 /**
  * Persisted paths are only trusted when they are absolute and free of NUL, so
  * malformed state can never redirect a read or a delete to a relative target.
@@ -58,11 +86,11 @@ function absolutePath(value: unknown) {
 	return normalized;
 }
 
-function fixedThinkingLevel(value: unknown): PlanModeFixedThinkingLevel | undefined {
+// legacy: delete in 1.4.0
+function legacyThinkingLevel(value: unknown): (typeof LEGACY_THINKING_LEVELS)[number] | undefined {
 	return typeof value === "string" &&
-		value !== "inherit" &&
-		PLAN_MODE_THINKING_LEVELS.includes(value as (typeof PLAN_MODE_THINKING_LEVELS)[number])
-		? (value as PlanModeFixedThinkingLevel)
+		LEGACY_THINKING_LEVELS.includes(value as (typeof LEGACY_THINKING_LEVELS)[number])
+		? (value as (typeof LEGACY_THINKING_LEVELS)[number])
 		: undefined;
 }