@hank-warren/pi-plan-mode 0.1.0

package/src/completion-tool.ts

@@ -0,0 +1,91 @@
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { Markdown } from "@earendil-works/pi-tui";
+
+export const PLAN_MODE_COMPLETE_TOOL_NAME = "plan_mode_complete";
+export const PLAN_MODE_COMPLETE_VERSION = 1;
+export const PLAN_MODE_MAX_CHARS = 50_000;
+
+export type PlanModeCompletionDetails = {
+	version: typeof PLAN_MODE_COMPLETE_VERSION;
+	source: typeof PLAN_MODE_COMPLETE_TOOL_NAME;
+	plan: string;
+};
+
+export const PLAN_MODE_COMPLETE_PARAMS = {
+	type: "object",
+	additionalProperties: false,
+	required: ["plan"],
+	properties: {
+		plan: {
+			type: "string",
+			minLength: 1,
+			maxLength: PLAN_MODE_MAX_CHARS,
+			description: "The complete decision-ready implementation plan in Markdown.",
+		},
+	},
+} as const;
+
+type NormalizePlanModeCompletionResult = { ok: true; plan: string } | { ok: false; error: string };
+
+export function normalizePlanModeCompletion(input: unknown): NormalizePlanModeCompletionResult {
+	if (!isRecord(input) || typeof input.plan !== "string") {
+		return { ok: false, error: "plan must be a string" };
+	}
+	const plan = input.plan.trim();
+	if (!plan) return { ok: false, error: "plan must not be empty" };
+	if (plan.length > PLAN_MODE_MAX_CHARS) {
+		return {
+			ok: false,
+			error: `plan must not exceed ${PLAN_MODE_MAX_CHARS} characters`,
+		};
+	}
+	return { ok: true, plan };
+}
+
+export function planFromCompletionDetails(value: unknown) {
+	if (!isRecord(value)) return undefined;
+	if (
+		value.version !== PLAN_MODE_COMPLETE_VERSION ||
+		value.source !== PLAN_MODE_COMPLETE_TOOL_NAME
+	) {
+		return undefined;
+	}
+	const normalized = normalizePlanModeCompletion({ plan: value.plan });
+	return normalized.ok ? normalized.plan : undefined;
+}
+
+export function planModeCompleted(plan: string) {
+	return {
+		content: [{ type: "text" as const, text: `**Proposed Plan**\n\n${plan}` }],
+		details: {
+			version: PLAN_MODE_COMPLETE_VERSION,
+			source: PLAN_MODE_COMPLETE_TOOL_NAME,
+			plan,
+		} satisfies PlanModeCompletionDetails,
+		terminate: true,
+	};
+}
+
+type PlanModeCompletionRenderResult = {
+	content: Array<{ type: string; text?: string }>;
+	details?: unknown;
+};
+
+export function planModeCompletionMarkdown(result: PlanModeCompletionRenderResult) {
+	const content = result.content
+		.filter((block) => block.type === "text" && typeof block.text === "string")
+		.map((block) => block.text)
+		.join("\n")
+		.trim();
+	if (content) return content;
+	const plan = planFromCompletionDetails(result.details);
+	return plan ? `**Proposed Plan**\n\n${plan}` : "";
+}
+
+export function renderPlanModeCompletion(result: PlanModeCompletionRenderResult) {
+	return new Markdown(planModeCompletionMarkdown(result), 0, 0, getMarkdownTheme());
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/extension-runtime.ts

@@ -0,0 +1,24 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { PlanModeFixedThinkingLevel } from "./settings.js";
+
+type AgentSettledHandler = (event: unknown, ctx: ExtensionContext) => unknown;
+
+export function onAgentSettled(pi: ExtensionAPI, handler: AgentSettledHandler) {
+	(
+		pi as unknown as {
+			on(event: "agent_settled", callback: AgentSettledHandler): void;
+		}
+	).on("agent_settled", handler);
+}
+
+export function setPlanThinkingLevel(pi: ExtensionAPI, level: PlanModeFixedThinkingLevel) {
+	(pi.setThinkingLevel as unknown as (level: PlanModeFixedThinkingLevel) => void)(level);
+}
+
+export function isStaleExtensionContextError(error: unknown) {
+	return (
+		error instanceof Error &&
+		(error.message.includes("This extension ctx is stale after session replacement or reload") ||
+			error.message.includes("Extension context is no longer active"))
+	);
+}

package/src/fresh-implementation.ts

@@ -0,0 +1,213 @@
+import { randomUUID } from "node:crypto";
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ImplementationPlanRetention } from "./settings.js";
+import type { PlanCompletionSource, PlanModeState } from "./state.js";
+
+type NewSessionOptions = Exclude<Parameters<ExtensionCommandContext["newSession"]>[0], undefined>;
+type ReplacementContext = Parameters<NonNullable<NewSessionOptions["withSession"]>>[0];
+
+export interface FreshImplementationRequest {
+	plan: string;
+	source: PlanCompletionSource;
+	retention: ImplementationPlanRetention;
+	stateEntryType: string;
+	isCurrent(): boolean;
+}
+
+interface FreshImplementationFromStateOptions {
+	getState(): PlanModeState;
+	menuIsCurrent(): boolean;
+	retention: ImplementationPlanRetention;
+	stateEntryType: string;
+}
+
+export type FreshImplementationResult =
+	| { kind: "started" }
+	| { kind: "cancelled" }
+	| { kind: "partial" }
+	| { kind: "rejected" }
+	| { kind: "stale" };
+
+export function formatImplementationHandoff(plan: string) {
+	return `Plan mode is now disabled. Full tool access is restored. Implement this proposed plan now:\n\n${plan}`;
+}
+
+export async function startFreshImplementationFromState(
+	ctx: ExtensionContext,
+	options: FreshImplementationFromStateOptions,
+) {
+	if (!isCommandContext(ctx)) {
+		ctx.ui.notify(
+			"Fresh implementation requires the interactive /plan command. Reopen /plan and try again.",
+			"warning",
+		);
+		return { kind: "rejected" } as const;
+	}
+	const initialState = options.getState();
+	const savedPlan = initialState.enabled ? undefined : initialState.savedPlan;
+	const plan = (initialState.enabled ? initialState.latestPlan : savedPlan?.plan)?.trim();
+	const source = initialState.enabled ? initialState.latestPlanSource : savedPlan?.source;
+	if (!plan || !source) {
+		ctx.ui.notify("No completed plan is available to implement.", "warning");
+		return { kind: "rejected" } as const;
+	}
+	const wasEnabled = initialState.enabled;
+	const isCurrent = () => {
+		const current = options.getState();
+		return (
+			options.menuIsCurrent() &&
+			current.enabled === wasEnabled &&
+			(wasEnabled
+				? current.latestPlan === plan && current.latestPlanSource === source
+				: current.savedPlan === savedPlan)
+		);
+	};
+	return startFreshImplementationSession(ctx, {
+		plan,
+		source,
+		retention: options.retention,
+		stateEntryType: options.stateEntryType,
+		isCurrent,
+	});
+}
+
+export async function startFreshImplementationSession(
+	ctx: ExtensionCommandContext,
+	request: FreshImplementationRequest,
+): Promise<FreshImplementationResult> {
+	if (ctx.mode === "print" || ctx.mode === "json") {
+		throw new Error("Fresh plan implementation is unavailable in print/JSON mode. Use TUI or RPC.");
+	}
+
+	await ctx.waitForIdle();
+	if (!request.isCurrent()) return { kind: "stale" };
+	if (!(await preflightModel(ctx, request.isCurrent))) return { kind: "rejected" };
+	if (!request.isCurrent()) return { kind: "stale" };
+
+	const activeImplementation = {
+		id: randomUUID(),
+		plan: request.plan,
+		source: request.source,
+		startedAt: Date.now(),
+		retention: request.retention,
+	};
+	const destinationState: PlanModeState = {
+		enabled: false,
+		awaitingAction: false,
+		activeImplementation,
+	};
+	const handoff = formatImplementationHandoff(request.plan);
+	const parentSession = ctx.sessionManager.getSessionFile();
+	let setupError: string | undefined;
+	let kickoffError: string | undefined;
+
+	if (ctx.mode === "rpc") ctx.ui.notify("Starting fresh implementation session…", "info");
+
+	let result: Awaited<ReturnType<ExtensionCommandContext["newSession"]>>;
+	try {
+		result = await ctx.newSession({
+			...(parentSession ? { parentSession } : {}),
+			setup: async (sessionManager) => {
+				try {
+					sessionManager.appendCustomEntry(request.stateEntryType, destinationState);
+				} catch (error: unknown) {
+					setupError = safeErrorDetail(error);
+				}
+			},
+			withSession: async (replacementCtx) => {
+				if (setupError) {
+					recoverSetupFailure(replacementCtx, handoff, setupError);
+					return;
+				}
+				try {
+					await replacementCtx.sendUserMessage(handoff);
+					replacementCtx.ui.notify(
+						"Fresh implementation session started. Only the approved plan was transferred.",
+						"info",
+					);
+				} catch (error: unknown) {
+					kickoffError = safeErrorDetail(error);
+					replacementCtx.ui.notify(
+						`Fresh session created, but implementation did not start: ${kickoffError}. Send a message to continue, use /plan exit to clear the active plan, or resume the parent planning session.`,
+						"error",
+					);
+				}
+			},
+		});
+	} catch (error: unknown) {
+		safeNotify(
+			ctx,
+			`Unable to start a fresh implementation session: ${safeErrorDetail(error)}. The source plan remains available; retry or resume the planning session.`,
+			"error",
+		);
+		return { kind: "rejected" };
+	}
+
+	if (result.cancelled) {
+		ctx.ui.notify("Fresh implementation cancelled. The plan remains available.", "info");
+		return { kind: "cancelled" };
+	}
+	return setupError || kickoffError ? { kind: "partial" } : { kind: "started" };
+}
+
+async function preflightModel(ctx: ExtensionCommandContext, isCurrent: () => boolean) {
+	const model = ctx.model;
+	if (!model) {
+		ctx.ui.notify("Unable to implement the plan: no model is selected.", "warning");
+		return false;
+	}
+	let auth: Awaited<ReturnType<ExtensionCommandContext["modelRegistry"]["getApiKeyAndHeaders"]>>;
+	try {
+		auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	} catch (error: unknown) {
+		if (isCurrent()) {
+			ctx.ui.notify(`Unable to implement the plan: ${safeErrorDetail(error)}`, "error");
+		}
+		return false;
+	}
+	if (!isCurrent()) return false;
+	if (!auth.ok) {
+		ctx.ui.notify(`Unable to implement the plan: ${safeErrorDetail(auth.error)}`, "warning");
+		return false;
+	}
+	return true;
+}
+
+function recoverSetupFailure(ctx: ReplacementContext, handoff: string, setupError: string) {
+	ctx.ui.setEditorText(handoff);
+	ctx.ui.notify(
+		`Fresh session created, but the active plan could not be saved: ${setupError}. The implementation request is in the editor; submit it to continue or resume the parent planning session.`,
+		"error",
+	);
+}
+
+function safeNotify(
+	ctx: ExtensionCommandContext,
+	message: string,
+	level: "info" | "warning" | "error",
+) {
+	try {
+		ctx.ui.notify(message, level);
+	} catch {
+		// The source context can become stale if Pi fails after replacement teardown.
+	}
+}
+
+function isCommandContext(ctx: ExtensionContext): ctx is ExtensionCommandContext {
+	return typeof (ctx as Partial<ExtensionCommandContext>).newSession === "function";
+}
+
+function safeErrorDetail(error: unknown) {
+	const detail = error instanceof Error ? error.message : String(error);
+	const normalized =
+		[...detail]
+			.map((character) => {
+				const codePoint = character.codePointAt(0) ?? 0;
+				return codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f) ? " " : character;
+			})
+			.join("")
+			.replace(/\s+/gu, " ")
+			.trim() || "unknown error";
+	const characters = [...normalized];
+	return characters.length > 500 ? `${characters.slice(0, 499).join("")}…` : normalized;
+}

package/src/implementation-retention.ts

@@ -0,0 +1,122 @@
+import {
+	injectActiveImplementationContext,
+	isEmptyAssistantMessage,
+	messageContainsExactPlanModeImplementationHandoff,
+	messageContainsInactivePlanModeArtifact,
+	messageContainsLegacyPlanModeContextArtifact,
+	messageContainsPlanModeImplementationContextArtifact,
+	messageContainsPlanModeImplementationHandoff,
+	stripPlanModeCompletionCallsFromMessage,
+	stripProposedPlanBlocksFromMessage,
+} from "./message-transform.js";
+import type { ImplementationPlanRetention } from "./settings.js";
+import type { ActiveImplementationPlan, PlanModeState } from "./state.js";
+
+export function retentionLabel(retention: ImplementationPlanRetention) {
+	return {
+		keep: "Keep plan active",
+		"clear-on-start": "Use plan for handoff only",
+		"clear-after-first-run": "Clear after first implementation run",
+	}[retention];
+}
+
+export function implementationRetentionPreview(retention: ImplementationPlanRetention) {
+	return {
+		keep: "After Implement: Keep plan active until /plan exit.",
+		"clear-on-start":
+			"After Implement: Use the plan for the implementation handoff only, then clear it.",
+		"clear-after-first-run": "After Implement: Clear after the first implementation run settles.",
+	}[retention];
+}
+
+export interface ImplementationContextResult {
+	messages: unknown[];
+	clearActiveImplementationId?: string;
+}
+
+export interface ImplementationRetentionCoordinator {
+	restore(activeImplementation: ActiveImplementationPlan | undefined): void;
+	transformContext(messages: unknown[], state: PlanModeState): ImplementationContextResult;
+	implementationSettled(
+		activeImplementation: ActiveImplementationPlan | undefined,
+	): string | undefined;
+	reset(): void;
+}
+
+export function createImplementationRetentionCoordinator(): ImplementationRetentionCoordinator {
+	let implementationWithDeliveredContext: string | undefined;
+	let restoredImplementationAwaitingContext: string | undefined;
+
+	return {
+		restore(activeImplementation) {
+			restoredImplementationAwaitingContext =
+				activeImplementation && activeImplementation.retention !== "keep"
+					? activeImplementation.id
+					: undefined;
+		},
+		transformContext(messages, state) {
+			const messagesWithoutPlanContext = messages.filter(
+				(message) =>
+					!messageContainsLegacyPlanModeContextArtifact(message) &&
+					!messageContainsPlanModeImplementationContextArtifact(message),
+			);
+			if (state.enabled) {
+				return {
+					messages: messagesWithoutPlanContext.filter(
+						(message) => !messageContainsPlanModeImplementationHandoff(message),
+					),
+				};
+			}
+
+			const activeImplementation = state.activeImplementation;
+			const inactiveMessages = activeImplementation
+				? messagesWithoutPlanContext
+				: messagesWithoutPlanContext.filter(
+						(message) => !messageContainsPlanModeImplementationHandoff(message),
+					);
+			const filteredMessages = inactiveMessages
+				.filter((message) => !messageContainsInactivePlanModeArtifact(message))
+				.map(stripProposedPlanBlocksFromMessage)
+				.map(stripPlanModeCompletionCallsFromMessage)
+				.filter((message) => !isEmptyAssistantMessage(message));
+			if (!activeImplementation) return { messages: filteredMessages };
+
+			const contextualMessages = injectActiveImplementationContext(
+				filteredMessages,
+				activeImplementation,
+			);
+			// A busy /plan implement queues its handoff behind an older run. Do not arm cleanup
+			// until that exact handoff reaches context; a restored session has no older run to drain.
+			const deliveredCurrentHandoff =
+				restoredImplementationAwaitingContext === activeImplementation.id ||
+				filteredMessages.some((message) =>
+					messageContainsExactPlanModeImplementationHandoff(message, activeImplementation.plan),
+				);
+			if (!deliveredCurrentHandoff) return { messages: contextualMessages };
+			restoredImplementationAwaitingContext = undefined;
+
+			if (activeImplementation.retention === "clear-after-first-run") {
+				implementationWithDeliveredContext = activeImplementation.id;
+			}
+			return {
+				messages: contextualMessages,
+				clearActiveImplementationId:
+					activeImplementation.retention === "clear-on-start" ? activeImplementation.id : undefined,
+			};
+		},
+		implementationSettled(activeImplementation) {
+			if (
+				activeImplementation?.retention !== "clear-after-first-run" ||
+				implementationWithDeliveredContext !== activeImplementation.id
+			) {
+				return undefined;
+			}
+			implementationWithDeliveredContext = undefined;
+			return activeImplementation.id;
+		},
+		reset() {
+			implementationWithDeliveredContext = undefined;
+			restoredImplementationAwaitingContext = undefined;
+		},
+	};
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { default } from "./plan-mode.js";

package/src/interactive-ui.ts

@@ -0,0 +1,5 @@
+export { showActiveImplementationMenu } from "./active-implementation-menu.js";
+export { showPlanModeMenu, showReadyPlanMenu } from "./plan-action-menus.js";
+export { showPlanLaunchMenu } from "./plan-launch-menu.js";
+export { showSavedPlanMenu } from "./saved-plan-menu.js";
+export { showPlanModeSettings } from "./settings-menu.js";

package/src/message-transform.ts

@@ -0,0 +1,232 @@
+import { PLAN_MODE_COMPLETE_TOOL_NAME } from "./completion-tool.js";
+import type { ActiveImplementationPlan } from "./state.js";
+
+const PLAN_CONTEXT_MESSAGE_TYPE = "plan-mode-context";
+export const PLAN_IMPLEMENTATION_CONTEXT_MESSAGE_TYPE = "plan-mode-implementation-context";
+const PROPOSED_PLAN_MESSAGE_TYPE = "proposed-plan";
+const PLAN_IMPLEMENTATION_HANDOFF_PREFIX =
+	"Plan mode is now disabled. Full tool access is restored. Implement this proposed plan now:";
+const PROPOSED_PLAN_PATTERN =
+	/^<proposed_plan>[\t ]*\r?\n([\s\S]*?)\r?\n<\/proposed_plan>[\t ]*$/gm;
+const PROPOSED_PLAN_BLOCK_PATTERN =
+	/^<proposed_plan>[\t ]*\r?\n[\s\S]*?\r?\n<\/proposed_plan>[\t ]*$/gm;
+
+export type ProposedPlanParseResult =
+	| { kind: "absent" }
+	| { kind: "valid"; plan: string }
+	| { kind: "empty" }
+	| { kind: "multiple" }
+	| { kind: "malformed" }
+	| { kind: "unclosed" };
+
+type SessionMessage = {
+	role?: string;
+	content?: unknown;
+};
+
+type TextBlock = {
+	type?: string;
+	text?: string;
+};
+
+export function parseProposedPlan(text: string): ProposedPlanParseResult {
+	const openingCount = text.match(/<proposed_plan>/gi)?.length ?? 0;
+	const closingCount = text.match(/<\/proposed_plan>/gi)?.length ?? 0;
+	if (openingCount === 0 && closingCount === 0) return { kind: "absent" };
+	if (openingCount > 1 || closingCount > 1) return { kind: "multiple" };
+	if (openingCount === 1 && closingCount === 0) return { kind: "unclosed" };
+	if (openingCount !== 1 || closingCount !== 1) return { kind: "malformed" };
+
+	const matches = Array.from(text.matchAll(PROPOSED_PLAN_PATTERN));
+	if (matches.length !== 1) return { kind: "malformed" };
+	const plan = matches[0]?.[1]?.trim() ?? "";
+	return plan ? { kind: "valid", plan } : { kind: "empty" };
+}
+
+export function extractProposedPlan(text: string) {
+	const result = parseProposedPlan(text);
+	return result.kind === "valid" ? result.plan : undefined;
+}
+
+export function invalidPlanMessage(kind: "empty" | "multiple" | "malformed" | "unclosed") {
+	const detail = {
+		empty: "the block is empty",
+		multiple: "more than one plan block was produced",
+		malformed: "the tags must be on their own lines",
+		unclosed: "the closing tag is missing",
+	}[kind];
+	return `Proposed plan is not ready: ${detail}. Continue Plan mode and produce one complete non-empty <proposed_plan> block.`;
+}
+
+export function latestAssistantText(messages: unknown) {
+	if (!Array.isArray(messages)) return "";
+	for (const entry of [...messages].reverse()) {
+		const message = (entry as { message?: SessionMessage })?.message ?? (entry as SessionMessage);
+		if (message?.role !== "assistant") continue;
+		const text = messageText(message);
+		if (text) return text;
+	}
+	return "";
+}
+
+export function messageContainsLegacyPlanModeContextArtifact(message: unknown) {
+	return unwrapSessionMessage(message).customType === PLAN_CONTEXT_MESSAGE_TYPE;
+}
+
+export function messageContainsPlanModeImplementationContextArtifact(message: unknown) {
+	return unwrapSessionMessage(message).customType === PLAN_IMPLEMENTATION_CONTEXT_MESSAGE_TYPE;
+}
+
+export function injectActiveImplementationContext(
+	messages: unknown[],
+	activeImplementation: ActiveImplementationPlan,
+) {
+	let foundCurrentHandoff = false;
+	const messagesWithoutStaleContext = messages.filter((message) => {
+		if (messageContainsPlanModeImplementationContextArtifact(message)) return false;
+		if (!messageContainsPlanModeImplementationHandoff(message)) return true;
+		if (
+			!foundCurrentHandoff &&
+			messageContainsExactPlanModeImplementationHandoff(message, activeImplementation.plan)
+		) {
+			foundCurrentHandoff = true;
+			return true;
+		}
+		return false;
+	});
+	if (foundCurrentHandoff) return messagesWithoutStaleContext;
+
+	let insertionIndex = 0;
+	while (isSummaryMessage(messagesWithoutStaleContext[insertionIndex])) insertionIndex += 1;
+	const contextMessage = {
+		role: "custom" as const,
+		customType: PLAN_IMPLEMENTATION_CONTEXT_MESSAGE_TYPE,
+		content: `[ACTIVE IMPLEMENTATION PLAN]\n\nThe user approved the exact implementation plan below. Continue following it until the user explicitly clears or supersedes it. The exact plan is the remainder of this message:\n\n${activeImplementation.plan}`,
+		display: false,
+		timestamp: activeImplementation.startedAt,
+	};
+	return [
+		...messagesWithoutStaleContext.slice(0, insertionIndex),
+		contextMessage,
+		...messagesWithoutStaleContext.slice(insertionIndex),
+	];
+}
+
+export function messageContainsInactivePlanModeArtifact(message: unknown) {
+	const candidate = unwrapSessionMessage(message);
+	return (
+		candidate.customType === PROPOSED_PLAN_MESSAGE_TYPE ||
+		(candidate.role === "toolResult" && candidate.toolName === PLAN_MODE_COMPLETE_TOOL_NAME)
+	);
+}
+
+export function messageContainsPlanModeImplementationHandoff(message: unknown) {
+	const candidate = unwrapSessionMessage(message);
+	return (
+		candidate.role === "user" &&
+		contentText(candidate.content).trimStart().startsWith(PLAN_IMPLEMENTATION_HANDOFF_PREFIX)
+	);
+}
+
+export function messageContainsExactPlanModeImplementationHandoff(message: unknown, plan: string) {
+	const candidate = unwrapSessionMessage(message);
+	if (candidate.role !== "user") return false;
+	return (
+		contentText(candidate.content).trim() ===
+		`${PLAN_IMPLEMENTATION_HANDOFF_PREFIX}\n\n${plan}`.trim()
+	);
+}
+
+function isSummaryMessage(message: unknown) {
+	const role = unwrapSessionMessage(message)?.role;
+	return role === "compactionSummary" || role === "branchSummary";
+}
+
+export function stripProposedPlanBlocksFromMessage<T>(message: T): T {
+	return replaceAssistantContent(message, stripProposedPlanBlocksFromContent);
+}
+
+export function stripPlanModeCompletionCallsFromMessage<T>(message: T): T {
+	return replaceAssistantContent(message, (content) => {
+		if (!Array.isArray(content)) return content;
+		const nextContent = content.filter((block) => {
+			const candidate = block as { type?: string; name?: string };
+			return !(candidate.type === "toolCall" && candidate.name === PLAN_MODE_COMPLETE_TOOL_NAME);
+		});
+		return nextContent.length === content.length ? content : nextContent;
+	});
+}
+
+export function isEmptyAssistantMessage(message: unknown) {
+	const candidate = unwrapSessionMessage(message);
+	return (
+		candidate.role === "assistant" &&
+		Array.isArray(candidate.content) &&
+		candidate.content.length === 0
+	);
+}
+
+function replaceAssistantContent<T>(message: T, transform: (content: unknown) => unknown): T {
+	const candidate = unwrapSessionMessage(message);
+	if (candidate.role !== "assistant") return message;
+
+	const content = transform(candidate.content);
+	if (content === candidate.content) return message;
+
+	if (isSessionMessageEntry(message)) {
+		return { ...message, message: { ...candidate, content } };
+	}
+	return { ...candidate, content } as T;
+}
+
+function unwrapSessionMessage(message: unknown) {
+	const entry = message as { message?: unknown } | null | undefined;
+	return (entry?.message ?? message ?? {}) as {
+		role?: string;
+		customType?: string;
+		toolName?: string;
+		content?: unknown;
+	};
+}
+
+function isSessionMessageEntry<T>(message: T): message is T & { message: SessionMessage } {
+	return typeof message === "object" && message !== null && "message" in message;
+}
+
+function stripProposedPlanBlocksFromContent(content: unknown) {
+	if (typeof content === "string") return stripProposedPlanBlocks(content);
+	if (!Array.isArray(content)) return content;
+
+	let changed = false;
+	const nextContent = content.map((block) => {
+		const textBlock = block as TextBlock;
+		if (textBlock.type !== "text" || typeof textBlock.text !== "string") return block;
+
+		const text = stripProposedPlanBlocks(textBlock.text);
+		if (text === textBlock.text) return block;
+
+		changed = true;
+		return { ...textBlock, text };
+	});
+	return changed ? nextContent : content;
+}
+
+export function stripProposedPlanBlocks(text: string) {
+	return text.replace(PROPOSED_PLAN_BLOCK_PATTERN, "");
+}
+
+function messageText(message: SessionMessage) {
+	return contentText(message.content);
+}
+
+function contentText(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.map((block) => {
+			const textBlock = block as TextBlock;
+			return textBlock.type === "text" && typeof textBlock.text === "string" ? textBlock.text : "";
+		})
+		.filter(Boolean)
+		.join("\n");
+}