pi-plan-task 1.1.0 → 3.0.1

package/extensions/index.ts

@@ -1,21 +1,19 @@
+import { createHash } from "node:crypto";
 import { StringEnum } from "@earendil-works/pi-ai";
 import {
 	type ExtensionAPI,
 	type ExtensionCommandContext,
 	type ExtensionContext,
-	isToolCallEventType,
 } from "@earendil-works/pi-coding-agent";
-import { matchesKey, Text, truncateToWidth } from "@earendil-works/pi-tui";
+import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-import { isSafePlanCommand } from "./bash-guard.ts";
-import { parseBuildPlacement, parseGoalMode, type BuildPlacement } from "./build-session.ts";
-import { ensureDefaultGlobalConfig, loadConfig } from "./config.ts";
+import { buildHandoffCommand, parseBuildOptions, type BuildPlacement } from "./build-session.ts";
+import { ensureDefaultGlobalConfig, isAllowedPlanTool, loadConfig } from "./config.ts";
 import {
 	ensurePlanDir,
 	formatProgress,
+	hasPendingTasks,
 	loadTaskFile,
-	markTaskComplete,
-	nextPendingTask,
 	readOptionalFile,
 } from "./files.ts";
 import {
@@ -29,28 +27,40 @@ import {
 	type FramingState,
 } from "./framing.ts";
 import { EMPTY_PLAN_SOURCE, loadPlanSource, type PlanSource } from "./plan-input.ts";
-import { isPlanArtifactPath, planFilePath, taskFilePath } from "./paths.ts";
+import { markTaskPendingInMarkdown, parseTaskMarkdown } from "./parse.ts";
+import { draftPlanFilePath, draftTaskFilePath, isPlanArtifactPath, planFilePath, taskFilePath } from "./paths.ts";
 import { buildPrompt, buildRequest, buildStatus, buildStatusKey, planPrompt, planRequest } from "./prompts.ts";
-import type { TaskItem } from "./types.ts";
+import type { PlanState, TaskItem } from "./types.ts";
+import { formatTaskList, TaskListComponent } from "./task-ui.ts";
+import { initialState, structureHash, transition, updateTaskState } from "./state.ts";
+import { normalizeReviewResult, validatePlan, textDiff } from "./review.ts";
+import { listPlanSnapshots } from "./history.ts";
+import { addTools, removeAddedTools, type ToolDelta } from "./tools.ts";
+import { assertApprovedStructure, blockCurrentTask, completeCurrentTask, reworkFromTask, unblockTask, verifyCurrentTask, classifyQueue } from "./workflow-policy.ts";
+import { commitDraft, initializeDraftWithState, loadStateLocked, mutateWorkflow, readCurrentArtifacts, readDraftArtifacts, saveStateLocked } from "./workflow-store.ts";
 
 type Mode = "idle" | "plan" | "build";
 
 const CONTINUE_THIS = "Continue in this session";
 const CONTINUE_NEW = "Continue in a new session";
-const BUILD_HERE_COMMAND = "/build here";
-const GOAL_CONTINUE_COMMAND = "/goal continue";
+const BUILD_ONE_HERE_COMMAND = "/build";
 
-async function startBuildInNewSession(ctx: ExtensionCommandContext, command = BUILD_HERE_COMMAND): Promise<void> {
+function contentKey(content: string): string {
+	return createHash("sha256").update(content).digest("hex");
+}
+async function startBuildInNewSession(ctx: ExtensionCommandContext, command = BUILD_ONE_HERE_COMMAND, clean = false): Promise<boolean> {
 	const parentSession = ctx.sessionManager.getSessionFile();
 	const result = await ctx.newSession({
-		parentSession,
+		parentSession: clean ? undefined : parentSession,
 		withSession: async (nextCtx) => {
 			await nextCtx.sendUserMessage(command, { expandPromptTemplates: true });
 		},
 	});
 	if (result.cancelled) {
-		ctx.ui.notify("New session cancelled.", "info");
+		ctx.ui.notify("New session cancelled; the plan remains approved.", "info");
+		return false;
 	}
+	return true;
 }
 
 const ALWAYS_ON_TOOLS = ["plan_task", "ask_user_question"] as const;
@@ -69,75 +79,30 @@ function pathFromInput(input: unknown): string | undefined {
 	return typeof path === "string" ? path : undefined;
 }
 
-function formatTaskList(tasks: TaskItem[]): string {
-	if (tasks.length === 0) return "No tasks found in .plan_task/task.md.";
-	const lines = tasks.map((task) => {
-		const mark = task.done ? "[x]" : "[ ]";
-		return `${mark} ${task.id}. ${task.title}`;
-	});
-	return `Progress ${formatProgress(tasks)}\n${lines.join("\n")}`;
+function assertApprovedWorkflow(state: PlanState, plan: string, task: string): void {
+	assertApprovedStructure(state, plan, task, structureHash);
+	let tasks: TaskItem[];
+	try { tasks = parseTaskMarkdown(task); } catch (error) { throw new Error(`Invalid approved task file: ${String(error)}`); }
+	const validation = validatePlan(plan, task, tasks);
+	if (!validation.valid) throw new Error(`Approved plan contract is invalid: ${validation.errors.join("; ")}`);
 }
 
-class TaskListComponent {
-	private readonly tasks: TaskItem[];
-	private readonly theme: { fg: (name: string, text: string) => string };
-	private readonly onClose: () => void;
-	private cachedWidth?: number;
-	private cachedLines?: string[];
-
-	constructor(
-		tasks: TaskItem[],
-		theme: { fg: (name: string, text: string) => string },
-		onClose: () => void,
-	) {
-		this.tasks = tasks;
-		this.theme = theme;
-		this.onClose = onClose;
-	}
-
-	handleInput(data: string): void {
-		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
-			this.onClose();
-		}
-	}
-
-	render(width: number): string[] {
-		if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
-		const th = this.theme;
-		const lines = ["", truncateToWidth(`  ${th.fg("accent", "Plan tasks")}  ${th.fg("muted", formatProgress(this.tasks))}`, width), ""];
-		if (this.tasks.length === 0) {
-			lines.push(truncateToWidth(`  ${th.fg("dim", "No tasks found. Run /plan first.")}`, width));
-		} else {
-			for (const task of this.tasks) {
-				const check = task.done ? th.fg("success", "x") : th.fg("dim", " ");
-				const title = task.done ? th.fg("dim", task.title) : th.fg("text", task.title);
-				lines.push(truncateToWidth(`  [${check}] ${th.fg("accent", String(task.id))}. ${title}`, width));
-			}
-		}
-		lines.push("", truncateToWidth(`  ${th.fg("dim", "Press Escape to close")}`, width), "");
-		this.cachedWidth = width;
-		this.cachedLines = lines;
-		return lines;
-	}
-
-	invalidate(): void {
-		this.cachedWidth = undefined;
-		this.cachedLines = undefined;
-	}
-}
 
 export default async function planTaskExtension(pi: ExtensionAPI): Promise<void> {
 	await ensureDefaultGlobalConfig();
 
 	let mode: Mode = "idle";
 	let continueAll = false;
+	let approvalEachTask = false;
 	let continueNew = false;
 	let currentTaskId: number | undefined;
-	let toolsBeforePlan: string[] | undefined;
+	let planToolsDelta: ToolDelta | undefined;
 	let awaitingChoice = false;
 	let planReadyNotified = false;
 	let planSource: PlanSource = EMPTY_PLAN_SOURCE;
 	let framing: FramingState = { ...INITIAL_FRAMING_STATE };
+	let planState = initialState();
+	let stateRestorable = true;
 
 	function resetFraming(): void {
 		framing = { ...INITIAL_FRAMING_STATE };
@@ -168,24 +133,24 @@ export default async function planTaskExtension(pi: ExtensionAPI): Promise<void>
 	}
 
 	async function applyPlanTools(ctx: ExtensionContext): Promise<void> {
-		if (toolsBeforePlan === undefined) {
-			toolsBeforePlan = pi.getActiveTools();
-		}
+		if (planToolsDelta) return;
 		const config = await loadConfig(ctx.cwd);
-		pi.setActiveTools(withAlwaysOnTools([...config.planTools, "write", "edit"]));
+		const required = withAlwaysOnTools([...config.planTools, "write", "edit"]);
+		planToolsDelta = addTools(pi.getActiveTools(), required);
+		pi.setActiveTools(unique([...pi.getActiveTools(), ...required]));
 	}
 
+
 	function restoreTools(): void {
-		if (toolsBeforePlan) {
-			pi.setActiveTools(withAlwaysOnTools(toolsBeforePlan));
-			toolsBeforePlan = undefined;
-			return;
+		if (planToolsDelta) {
+			pi.setActiveTools(removeAddedTools(pi.getActiveTools(), planToolsDelta));
+			planToolsDelta = undefined;
 		}
-		pi.setActiveTools(withAlwaysOnTools(pi.getActiveTools()));
 	}
 
 	async function enterPlanMode(ctx: ExtensionContext): Promise<void> {
 		mode = "plan";
+		if (planState.status !== "planning") planState = transition(planState, "planning");
 		continueAll = false;
 		continueNew = false;
 		currentTaskId = undefined;
@@ -221,13 +186,50 @@ export default async function planTaskExtension(pi: ExtensionAPI): Promise<void>
 			leaveModes(ctx);
 			return false;
 		}
-		const next = nextPendingTask(file.tasks);
-		if (!next) {
-			ctx.ui.notify("All tasks are complete.", "info");
+		try {
+			const current = await readCurrentArtifacts(ctx.cwd);
+			assertApprovedWorkflow(planState, current.plan, current.task);
+		} catch (error) {
+			if (planState.status !== "ready") planState = transition(planState, "ready");
+			planState = { ...planState, approvedStructureHash: undefined, currentTaskId: undefined, failureReason: error instanceof Error ? error.message : String(error) };
+			await saveStateLocked(ctx.cwd, planState);
+			ctx.ui.notify(planState.failureReason ?? "Plan approval is no longer valid.", "error");
+			leaveModes(ctx);
+			return false;
+		}
+		const decision = classifyQueue(file, planState);
+		if (decision.kind === "all-complete") {
+			const allVerified = file.tasks.every((task) => planState.tasks?.[String(task.id)]?.status === "verified");
+			if (!allVerified) {
+				ctx.ui.notify("Checklist is complete but task verification state is inconsistent. Execution stopped.", "error");
+				leaveModes(ctx);
+				return false;
+			}
+			if (planState.status === "approved") planState = transition(planState, "executing");
+			planState = transition(planState, "completed");
+			planState = { ...planState, currentTaskId: undefined };
+			await saveStateLocked(ctx.cwd, planState);
+			pi.events.emit("pi-plan-task:execution-finished", { version: 1, cwd: ctx.cwd, planPath: planFilePath(ctx.cwd), taskPath: taskFilePath(ctx.cwd), planHash: planState.approvedStructureHash, sessionFile: ctx.sessionManager.getSessionFile() });
+			ctx.ui.notify("All tasks are verified and complete.", "info");
+			leaveModes(ctx);
+			return false;
+		}
+		if (decision.kind === "all-remaining-blocked") {
+			if (planState.status !== "blocked") planState = transition(planState, "blocked");
+			planState = { ...planState, currentTaskId: undefined };
+			await saveStateLocked(ctx.cwd, planState);
+			const reasons = decision.taskIds.map((id) => `${id}: ${planState.tasks?.[String(id)]?.reason ?? "blocked"}`).join("; ");
+			ctx.ui.notify(`Execution blocked. ${reasons}`, "warning");
 			leaveModes(ctx);
 			return false;
 		}
+		const next = decision.task;
 		currentTaskId = next.id;
+		const existing = planState.tasks?.[String(next.id)];
+		planState = updateTaskState(planState, next.id, existing?.status === "implementation-complete" ? "implementation-complete" : "pending", { startedAt: new Date().toISOString() });
+		planState = { ...planState, currentTaskId: next.id };
+		await saveStateLocked(ctx.cwd, planState);
+		pi.events.emit("pi-plan-task:task-started", { version: 1, cwd: ctx.cwd, planPath: planFilePath(ctx.cwd), taskPath: taskFilePath(ctx.cwd), planHash: planState.approvedStructureHash, taskId: next.id, sessionFile: ctx.sessionManager.getSessionFile() });
 		updateStatus(ctx, file.tasks);
 		pi.sendUserMessage(buildRequest(next));
 		return true;
@@ -243,18 +245,57 @@ export default async function planTaskExtension(pi: ExtensionAPI): Promise<void>
 		}
 		const current = file.tasks.find((task) => task.id === currentTaskId);
 		updateStatus(ctx, file.tasks);
+		const runtime = planState.tasks?.[String(currentTaskId)];
+		if (runtime?.status === "blocked") {
+			if (continueAll) { await startNextTask(ctx); return; }
+			if (continueNew) {
+				const decision = classifyQueue(file, planState);
+				if (decision.kind === "runnable") {
+					mode = "idle"; currentTaskId = undefined; resetFraming(); updateStatus(ctx);
+					pi.sendUserMessage("/build new", { expandPromptTemplates: true });
+					return;
+				}
+				await startNextTask(ctx);
+				return;
+			}
+			ctx.ui.notify(`Task ${currentTaskId} is blocked: ${runtime.reason ?? "no reason provided"}`, "warning");
+			leaveModes(ctx);
+			return;
+		}
 		if (!current?.done) {
-			ctx.ui.notify(
-				`Task ${currentTaskId} is not marked complete. Update .plan_task/task.md or call plan_task, then run /build again.`,
-				"warning",
-			);
+			const message = runtime?.status === "implementation-complete"
+				? `Task ${currentTaskId} implementation is complete but verification is pending. Call plan_task verify with the verification result.`
+				: `Task ${currentTaskId} is still pending. Complete the implementation before continuing.`;
+			ctx.ui.notify(message, "warning");
+			return;
+		}
+		if (runtime?.status !== "verified") {
+			ctx.ui.notify(`Task ${currentTaskId} checklist/state mismatch: task is checked but not verified.`, "error");
+			leaveModes(ctx);
 			return;
 		}
 		if (file.tasks.every((task) => task.done)) {
-			ctx.ui.notify("All tasks are complete.", "info");
+			const allVerified = file.tasks.every((task) => planState.tasks?.[String(task.id)]?.status === "verified");
+			if (!allVerified) { ctx.ui.notify("Not all completed tasks are verified.", "error"); leaveModes(ctx); return; }
+			ctx.ui.notify("All tasks are verified and complete.", "info");
+			planState = transition(planState, "completed");
+			planState = { ...planState, currentTaskId: undefined };
+			await saveStateLocked(ctx.cwd, planState);
+			pi.events.emit("pi-plan-task:execution-finished", { version: 1, cwd: ctx.cwd, planPath: planFilePath(ctx.cwd), taskPath: taskFilePath(ctx.cwd), planHash: planState.approvedStructureHash, sessionFile: ctx.sessionManager.getSessionFile() });
 			leaveModes(ctx);
 			return;
 		}
+		if (approvalEachTask) {
+			if (!ctx.hasUI) {
+				ctx.ui.notify("Task complete. Per-task approval requires UI; run /build to continue.", "info");
+				leaveModes(ctx);
+				return;
+			}
+			awaitingChoice = true;
+			const review = await ctx.ui.select(`Task ${currentTaskId} verified. What next?`, ["Continue to next task", "Stop execution"]);
+			awaitingChoice = false;
+			if (review !== "Continue to next task") { leaveModes(ctx); return; }
+		}
 		if (continueAll) {
 			await startNextTask(ctx);
 			return;
@@ -265,15 +306,12 @@ export default async function planTaskExtension(pi: ExtensionAPI): Promise<void>
 			resetFraming();
 			updateStatus(ctx);
 			ctx.ui.notify("Task complete. Opening a new session for the next task.", "info");
-			pi.sendUserMessage("/goal-next-session", { expandPromptTemplates: true });
+			pi.sendUserMessage("/build new", { expandPromptTemplates: true });
 			return;
 		}
 		if (!ctx.hasUI) {
 			ctx.ui.notify("Task complete. Run /build for the next task.", "info");
-			mode = "idle";
-			currentTaskId = undefined;
-			resetFraming();
-			updateStatus(ctx);
+			leaveModes(ctx);
 			return;
 		}
 		awaitingChoice = true;
@@ -288,7 +326,7 @@ export default async function planTaskExtension(pi: ExtensionAPI): Promise<void>
 			currentTaskId = undefined;
 			resetFraming();
 			updateStatus(ctx);
-			pi.sendUserMessage("/build-next-session", { expandPromptTemplates: true });
+			pi.sendUserMessage("/build new", { expandPromptTemplates: true });
 			return;
 		}
 		mode = "idle";
@@ -303,37 +341,60 @@ export default async function planTaskExtension(pi: ExtensionAPI): Promise<void>
 		description: "Read plan progress or mark a planned task complete in .plan_task/task.md",
 		promptSnippet: "Mark planned tasks complete and read .plan_task progress",
 		parameters: Type.Object({
-			action: StringEnum(["status", "complete"] as const),
-			id: Type.Optional(Type.Number({ description: "Task id to mark complete" })),
-		}),
+			 action: StringEnum(["status", "complete", "verify", "block", "unblock"] as const),
+			 id: Type.Optional(Type.Number({ description: "Task id to update" })),
+			 reason: Type.Optional(Type.String({ description: "Reason for blocking or verification result" })),
+ 		}),
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			const file = await loadTaskFile(ctx.cwd);
-			if (!file) {
-				return { content: [{ type: "text", text: "No .plan_task/task.md found. Run /plan first." }] };
-			}
-			if (params.action === "status") {
-				return { content: [{ type: "text", text: formatTaskList(file.tasks) }], details: { tasks: file.tasks } };
-			}
-			if (params.id === undefined) {
-				return { content: [{ type: "text", text: "id is required for complete" }] };
-			}
-			const next = await markTaskComplete(ctx.cwd, params.id);
-			if (!next) {
-				return { content: [{ type: "text", text: "Could not update .plan_task/task.md" }] };
+			if (!file) return { content: [{ type: "text", text: "No .plan_task/task.md found. Run /plan first." }], details: {} };
+			if (params.action === "status") return { content: [{ type: "text", text: formatTaskList(file.tasks) }], details: { tasks: file.tasks } };
+			if (params.id === undefined) return { content: [{ type: "text", text: "id is required" }], details: {} };
+			const id = params.id;
+			let eventName: string | undefined;
+			let resultText = "";
+			let approvalRevoked = false;
+			try {
+				const result = await mutateWorkflow(ctx.cwd, ({ state, plan, task }) => {
+					try { assertApprovedWorkflow(state, plan, task); } catch (error) {
+						approvalRevoked = true;
+						const ready = transition(state, "ready");
+						return { state: { ...ready, approvedStructureHash: undefined, currentTaskId: undefined, failureReason: error instanceof Error ? error.message : String(error) } };
+					}
+					const parsed = { raw: task, tasks: parseTaskMarkdown(task) };
+					let mutation;
+					if (params.action === "complete") {
+						mutation = completeCurrentTask(state, parsed, id);
+						eventName = "pi-plan-task:task-completed";
+						resultText = `Task ${id} implementation complete. Verification is required before it can advance.`;
+					} else if (params.action === "verify") {
+						mutation = verifyCurrentTask(state, parsed, id, params.reason);
+						eventName = "pi-plan-task:task-verified";
+					} else if (params.action === "block") {
+						mutation = blockCurrentTask(state, parsed, id, params.reason);
+						eventName = "pi-plan-task:task-blocked";
+						resultText = `Task ${id} blocked: ${params.reason?.trim() ?? ""}`;
+					} else {
+						mutation = unblockTask(state, parsed, id);
+					}
+					if (!mutation.ok) throw new Error(mutation.error);
+					if (params.action === "verify") resultText = `Task ${id} verified. Progress ${formatProgress(parseTaskMarkdown(mutation.value.task))}.`;
+					if (params.action === "unblock") resultText = `Task ${id} unblocked and restored to ${mutation.value.state.tasks?.[String(id)]?.status}.`;
+					return { state: mutation.value.state, task: mutation.value.task };
+				});
+				planState = result.state;
+				if (approvalRevoked) {
+					currentTaskId = undefined;
+					leaveModes(ctx);
+					throw new Error(planState.failureReason ?? "Plan approval was revoked.");
+				}
+				const nextTasks = parseTaskMarkdown(result.task);
+				updateStatus(ctx, nextTasks);
+				if (eventName) pi.events.emit(eventName, { version: 1, cwd: ctx.cwd, planPath: planFilePath(ctx.cwd), taskPath: taskFilePath(ctx.cwd), planHash: planState.approvedStructureHash, taskId: id, reason: params.reason, sessionFile: ctx.sessionManager.getSessionFile() });
+				return { content: [{ type: "text", text: resultText }], details: { taskId: id, status: planState.tasks?.[String(id)]?.status, tasks: nextTasks } };
+			} catch (error) {
+				throw error instanceof Error ? error : new Error(String(error));
 			}
-			const task = next.tasks.find((item) => item.id === params.id);
-			updateStatus(ctx, next.tasks);
-			return {
-				content: [
-					{
-						type: "text",
-						text: task?.done
-							? `Marked task ${params.id} complete. Progress ${formatProgress(next.tasks)}.`
-							: `Task ${params.id} was not found.`,
-					},
-				],
-				details: { tasks: next.tasks, completedId: params.id },
-			};
 		},
 		renderCall(args, theme) {
 			const suffix = args.id === undefined ? "" : ` #${args.id}`;
@@ -341,33 +402,178 @@ export default async function planTaskExtension(pi: ExtensionAPI): Promise<void>
 		},
 	});
 
+	async function startPlanRequest(args: string, ctx: ExtensionCommandContext): Promise<void> {
+		if (mode === "build") {
+			const ok = ctx.hasUI
+				? await ctx.ui.confirm("Switch to plan mode?", "A build is in progress. Stop it and start planning?")
+				: true;
+			if (!ok) return;
+		}
+		const loaded = await loadPlanSource(args, ctx.cwd);
+		if (!loaded.ok) {
+			ctx.ui.notify(loaded.error, "error");
+			return;
+		}
+		let existingTask: string | undefined;
+		let existingPlan: string | undefined;
+		try {
+			existingTask = await readOptionalFile(taskFilePath(ctx.cwd));
+			existingPlan = await readOptionalFile(planFilePath(ctx.cwd));
+		} catch (error) {
+			ctx.ui.notify(`Could not inspect existing plan files: ${String(error)}`, "error");
+			return;
+		}
+		const hasExistingWork = (existingTask !== undefined && hasPendingTasks(existingTask, true)) || (existingPlan !== undefined && hasPendingTasks(existingPlan, false));
+		if (hasExistingWork) {
+			if (!ctx.hasUI) { ctx.ui.notify("An incomplete plan already exists. Refusing to replace it in non-interactive mode.", "error"); return; }
+			const ok = await ctx.ui.confirm("Start a different plan?", "The current work is incomplete. It will be snapshotted only when the new draft validates successfully.");
+			if (!ok) return;
+		}
+		stateRestorable = true;
+		const config = await loadConfig(ctx.cwd);
+		planState = {
+			...initialState(config.executionMode),
+			status: "planning",
+			workId: contentKey(`${ctx.cwd}:${planRequest(loaded.source)}:${Date.now()}`).slice(0, 16),
+			planningRequest: planRequest(loaded.source),
+			planningBaselineHash: structureHash("", ""),
+		};
+		planState = await initializeDraftWithState(ctx.cwd, planState);
+		planSource = loaded.source;
+		await enterPlanMode(ctx);
+		const message = loaded.source.kind === "file"
+			? `Planning from ${loaded.source.displayPath}. Only draft plan files are writable.`
+			: "Plan mode enabled. Only draft plan files are writable.";
+		ctx.ui.notify(message, "info");
+		pi.sendUserMessage(planRequest(loaded.source));
+	}
+
+	async function approvePlan(args: string, ctx: ExtensionCommandContext): Promise<void> {
+		const persisted = await loadStateLocked(ctx.cwd);
+		if (persisted) planState = persisted;
+		const selected = args.trim() || (ctx.hasUI ? ((await ctx.ui.select("Approve plan: choose next action", ["current", "new", "fresh", "revise", "cancel"])) ?? "cancel") : "current");
+		const choice = selected.toLowerCase();
+		const revisionAllowed = choice === "revise" && ["ready", "approved", "blocked", "completed"].includes(planState.status);
+		if (planState.status !== "ready" && !revisionAllowed) { ctx.ui.notify(`Plan is not awaiting approval (status: ${planState.status}).`, "warning"); return; }
+		if (!["current", "new", "fresh", "revise", "cancel"].includes(choice)) {
+			ctx.ui.notify("Usage: /plan approve [current|new|fresh]", "error");
+			return;
+		}
+		const approvalConfig = await loadConfig(ctx.cwd);
+		if (approvalConfig.executionMode === "external" && (choice === "new" || choice === "fresh")) {
+			ctx.ui.notify("External execution mode does not start local sessions.", "warning");
+			return;
+		}
+		if (choice === "cancel") {
+			planState = transition(planState, "idle");
+			await saveStateLocked(ctx.cwd, planState);
+			leaveModes(ctx);
+			ctx.ui.notify("Plan approval cancelled.", "info");
+			return;
+		}
+		if (choice === "revise") {
+			const feedback = ctx.hasUI ? await ctx.ui.input("Revision feedback", "Explain what should change") : "";
+			if (!feedback?.trim()) { ctx.ui.notify("Revision cancelled; current plan is unchanged.", "info"); return; }
+			const current = await readCurrentArtifacts(ctx.cwd);
+			planState = transition(planState, "planning");
+			planState = { ...planState, planningRequest: `Revise the current plan: ${feedback.trim()}`, planningBaselineHash: structureHash(current.plan, current.task), approvedStructureHash: undefined, failureReason: feedback.trim() };
+			planState = await initializeDraftWithState(ctx.cwd, planState, current);
+			await enterPlanMode(ctx);
+			pi.sendUserMessage(`Revise the current draft with this feedback:\n${feedback.trim()}`);
+			return;
+		}
+		const current = await readCurrentArtifacts(ctx.cwd);
+		const parsed = parseTaskMarkdown(current.task);
+		const validation = validatePlan(current.plan, current.task, parsed);
+		if (!validation.valid) { ctx.ui.notify(`Plan validation failed: ${validation.errors.join("; ")}`, "error"); return; }
+		const approvedStructureHash = structureHash(current.plan, current.task);
+		planState = transition(planState, "approved");
+		planState = { ...planState, approvedStructureHash, draftStructureHash: approvedStructureHash, executionMode: approvalConfig.executionMode, failureReason: undefined };
+		await saveStateLocked(ctx.cwd, planState);
+		const payload = { version: 1, cwd: ctx.cwd, planPath: planFilePath(ctx.cwd), taskPath: taskFilePath(ctx.cwd), planHash: approvedStructureHash, sessionFile: ctx.sessionManager.getSessionFile() };
+		pi.events.emit("pi-plan-task:plan-approved", payload);
+		if (approvalConfig.executionMode === "external") {
+			leaveModes(ctx);
+			ctx.ui.notify("Plan approved. External execution event emitted.", "info");
+			return;
+		}
+		if (choice === "new" || choice === "fresh") {
+			await startBuildInNewSession(ctx, BUILD_ONE_HERE_COMMAND, choice === "fresh");
+			return;
+		}
+		await beginBuild(ctx, false, "here");
+	}
+
+	async function rejectPlan(args: string, ctx: ExtensionCommandContext): Promise<void> {
+		const persisted = await loadStateLocked(ctx.cwd);
+		if (persisted) planState = persisted;
+		if (planState.status !== "ready") { ctx.ui.notify(`Plan is not awaiting review (status: ${planState.status}).`, "warning"); return; }
+		const feedback = args.trim() || (ctx.hasUI ? await ctx.ui.input("Plan feedback", "Explain what should change") : "");
+		const current = await readCurrentArtifacts(ctx.cwd);
+		planState = transition(planState, "planning");
+		planState = { ...planState, planningRequest: `Revise the current plan: ${feedback || "Plan rejected without feedback."}`, planningBaselineHash: structureHash(current.plan, current.task), approvedStructureHash: undefined, failureReason: feedback || "Plan rejected without feedback." };
+		planState = await initializeDraftWithState(ctx.cwd, planState, current);
+		pi.events.emit("pi-plan-task:plan-rejected", { version: 1, cwd: ctx.cwd, planPath: planFilePath(ctx.cwd), taskPath: taskFilePath(ctx.cwd), planHash: planState.draftStructureHash, feedback, sessionFile: ctx.sessionManager.getSessionFile() });
+		await enterPlanMode(ctx);
+		ctx.ui.notify("Plan rejected. Revise the draft and submit it again.", "info");
+		if (feedback) pi.sendUserMessage(`Revise the current draft with this review feedback:\n${feedback}`);
+	}
+
+	async function showPlanStatus(ctx: ExtensionCommandContext): Promise<void> {
+		const persisted = await loadStateLocked(ctx.cwd);
+		const file = await loadTaskFile(ctx.cwd);
+		ctx.ui.notify(`Plan status: ${persisted?.status ?? "idle"}\nApproved hash: ${persisted?.approvedStructureHash ?? "none"}\nWork id: ${persisted?.workId ?? "none"}\nProgress: ${file ? formatProgress(file.tasks) : "0/0"}\nCurrent task: ${persisted?.currentTaskId ?? "none"}`, "info");
+	}
+
+	async function showPlanHistory(ctx: ExtensionCommandContext): Promise<void> {
+		const items = await listPlanSnapshots(ctx.cwd);
+		ctx.ui.notify(items.length ? items.map((item) => `v${item.version} ${item.createdAt}`).join("\n") : "No plan history.", "info");
+	}
+
+	async function showPlanDiff(ctx: ExtensionCommandContext): Promise<void> {
+		const items = await listPlanSnapshots(ctx.cwd);
+		if (!items.length) { ctx.ui.notify("No plan history.", "info"); return; }
+		const currentPlan = (await readOptionalFile(planFilePath(ctx.cwd))) ?? "";
+		const currentTask = (await readOptionalFile(taskFilePath(ctx.cwd))) ?? "";
+		ctx.ui.notify(textDiff(`${items.at(-1)!.plan}\n${items.at(-1)!.task}`, `${currentPlan}\n${currentTask}`) || "No changes.", "info");
+	}
+
+	async function reviewPlan(ctx: ExtensionCommandContext): Promise<void> {
+		try {
+			const result = await pi.exec("plannotator", ["annotate", planFilePath(ctx.cwd), "--markdown", "--json"]);
+			const review = normalizeReviewResult(result.stdout.trim());
+			if (review?.decision === "approved") { pi.sendUserMessage("/plan approve current", { expandPromptTemplates: true }); return; }
+			if (review?.decision === "rejected" && review.feedback) { pi.sendUserMessage(`/plan reject ${review.feedback}`, { expandPromptTemplates: true }); return; }
+			if (result.code !== 0) ctx.ui.notify("Plannotator is unavailable or review failed; use /plan approve or /plan reject.", "warning");
+		} catch {
+			ctx.ui.notify("Plannotator is unavailable; use /plan approve or /plan reject.", "warning");
+		}
+	}
+
+	const planSubcommands = ["review", "approve", "reject", "revise", "status", "history", "diff", "request"];
 	pi.registerCommand("plan", {
-		description: "Write .plan_task/plan.md and .plan_task/task.md from a file path or prompt",
+		description: "Create, review, approve, reject, or inspect a plan",
+		getArgumentCompletions: (prefix) => {
+			const items = planSubcommands.map((name) => ({ value: name, label: name }));
+			const filtered = items.filter((item) => item.value.startsWith(prefix.trim().toLowerCase()));
+			return filtered.length ? filtered : null;
+		},
 		handler: async (args, ctx) => {
-			if (mode === "build") {
-				const ok = ctx.hasUI
-					? await ctx.ui.confirm("Switch to plan mode?", "A build is in progress. Stop it and start planning?")
-					: true;
-				if (!ok) return;
-			}
-			const loaded = await loadPlanSource(args, ctx.cwd);
-			if (!loaded.ok) {
-				ctx.ui.notify(loaded.error, "error");
-				return;
+			const trimmed = args.trim();
+			const [rawAction = "", ...rest] = trimmed.split(/\s+/);
+			const action = rawAction.toLowerCase();
+			const actionArgs = rest.join(" ");
+			switch (action) {
+				case "review": await reviewPlan(ctx); return;
+				case "approve": await approvePlan(actionArgs, ctx); return;
+				case "reject": await rejectPlan(actionArgs, ctx); return;
+				case "revise": await approvePlan("revise", ctx); return;
+				case "status": await showPlanStatus(ctx); return;
+				case "history": await showPlanHistory(ctx); return;
+				case "diff": await showPlanDiff(ctx); return;
+				case "request": await startPlanRequest(actionArgs, ctx); return;
+				default: await startPlanRequest(args, ctx);
 			}
-			const existing = await readOptionalFile(taskFilePath(ctx.cwd));
-			if (existing && ctx.hasUI) {
-				const ok = await ctx.ui.confirm("Overwrite existing plan?", ".plan_task already has a task list. Overwrite it?");
-				if (!ok) return;
-			}
-			planSource = loaded.source;
-			await enterPlanMode(ctx);
-			const message =
-				loaded.source.kind === "file"
-					? `Planning from ${loaded.source.displayPath}. Project writes are blocked.`
-					: "Plan mode enabled. Project writes are blocked.";
-			ctx.ui.notify(message, "info");
-			pi.sendUserMessage(planRequest(loaded.source));
 		},
 	});
 
@@ -375,67 +581,147 @@ export default async function planTaskExtension(pi: ExtensionAPI): Promise<void>
 		ctx: ExtensionCommandContext,
 		runAll: boolean,
 		placement: BuildPlacement = "here",
-		options: { chainNew?: boolean; forkCommand?: string } = {},
+		options: { chainNew?: boolean; approvalEachTask?: boolean } = {},
 	): Promise<void> {
-		const chainNew = options.chainNew === true;
-		const forkCommand = options.forkCommand ?? BUILD_HERE_COMMAND;
-		const file = await loadTaskFile(ctx.cwd);
-		if (!file) {
-			ctx.ui.notify("No plan found. Run /plan first.", "error");
-			return;
-		}
-		if (file.tasks.length === 0) {
-			ctx.ui.notify("task.md has no checklist items.", "error");
+		const persisted = await loadStateLocked(ctx.cwd);
+		if (!persisted) { ctx.ui.notify("No plan state found. Run /plan first.", "error"); return; }
+		planState = persisted;
+		const executionConfig = await loadConfig(ctx.cwd);
+		if (executionConfig.executionMode === "external") { ctx.ui.notify("External execution mode is enabled; waiting for an external executor.", "info"); return; }
+		if (planState.status !== "approved" && planState.status !== "executing") {
+			ctx.ui.notify(`Plan must be approved before execution (status: ${planState.status}). Use /plan approve.`, "error");
 			return;
 		}
-		if (!nextPendingTask(file.tasks)) {
-			ctx.ui.notify("All tasks are complete.", "info");
+		const file = await loadTaskFile(ctx.cwd);
+		if (!file || file.tasks.length === 0) { ctx.ui.notify("A valid task.md with checklist tasks is required.", "error"); return; }
+		if (!planState.approvedStructureHash) { ctx.ui.notify("Plan has no approved structure hash. Re-approve it.", "error"); return; }
+		try {
+			const current = await readCurrentArtifacts(ctx.cwd);
+			assertApprovedWorkflow(planState, current.plan, current.task);
+		} catch (error) {
+			planState = transition(planState, "ready");
+			planState = { ...planState, approvedStructureHash: undefined, currentTaskId: undefined, failureReason: error instanceof Error ? error.message : String(error) };
+			await saveStateLocked(ctx.cwd, planState);
+			ctx.ui.notify("Plan files or contract changed after approval. Review and approve again.", "error");
 			return;
 		}
-		if (!runAll && !chainNew && placement === "new") {
-			await startBuildInNewSession(ctx, forkCommand);
+		const queue = classifyQueue(file, planState);
+		if (queue.kind === "all-complete") { await enterBuildMode(ctx); await startNextTask(ctx); return; }
+		if (queue.kind === "all-remaining-blocked") { await enterBuildMode(ctx); await startNextTask(ctx); return; }
+
+		const continuingAllNew = planState.continueMode === "all-new";
+		const persistedAllNew = continuingAllNew && placement === "here" && !runAll;
+		const chainNew = options.chainNew === true || persistedAllNew;
+		const approval = options.approvalEachTask === true || (continuingAllNew && planState.approvalEachTask === true);
+		const continueMode: PlanState["continueMode"] = chainNew ? "all-new" : runAll ? "all-here" : "single";
+
+		if (placement === "new" || placement === "fresh") {
+			const command = buildHandoffCommand({ scope: runAll ? "all" : "one", placement, approval });
+			const pendingState: PlanState = { ...planState, continueMode: continuingAllNew || (runAll && placement === "new") ? "all-new" : runAll ? "all-here" : "single", approvalEachTask: approval, currentTaskId: undefined };
+			planState = pendingState;
+			currentTaskId = undefined;
+			await saveStateLocked(ctx.cwd, pendingState);
+			const started = await startBuildInNewSession(ctx, command, placement === "fresh");
+			if (!started) { planState = { ...pendingState, continueMode: undefined, approvalEachTask: false }; await saveStateLocked(ctx.cwd, planState); }
 			return;
 		}
-		continueAll = runAll;
+		if (planState.status === "approved") planState = transition(planState, "executing");
+		planState = { ...planState, currentTaskId: undefined, approvalEachTask: approval, continueMode };
+		await saveStateLocked(ctx.cwd, planState);
+		continueAll = runAll && !chainNew;
+		approvalEachTask = approval;
 		continueNew = chainNew;
 		await enterBuildMode(ctx);
-		ctx.ui.notify(
-			runAll
-				? "Building remaining tasks."
-				: chainNew
-					? "Building the next task. Remaining tasks will each start in a new session."
-					: "Building the next task.",
-			"info",
-		);
+		ctx.ui.notify(chainNew ? "Building the next task; remaining tasks will use new sessions." : runAll ? "Building remaining tasks." : "Building the next task.", "info");
 		await startNextTask(ctx);
 	}
 
+	const buildSubcommands = ["all", "new", "fresh", "--approval"];
 	pi.registerCommand("build", {
-		description: "Execute the next planned task in this session. Use /build new to start it in a new session",
-		handler: async (args, ctx) => {
-			await beginBuild(ctx, false, parseBuildPlacement(args));
+		description: "Execute one task or all remaining tasks, here or in a new session",
+		getArgumentCompletions: (prefix) => {
+			const token = prefix.trim().split(/\s+/).at(-1)?.toLowerCase() ?? "";
+			const items = buildSubcommands.map((name) => ({ value: name, label: name }));
+			const filtered = items.filter((item) => item.value.startsWith(token));
+			return filtered.length ? filtered : null;
 		},
-	});
-
-	pi.registerCommand("goal", {
-		description: "Execute remaining planned tasks until complete. Use /goal new for one new session per task",
 		handler: async (args, ctx) => {
-			const goalMode = parseGoalMode(args);
-			if (goalMode === "all-new") {
-				await beginBuild(ctx, false, "new", { forkCommand: GOAL_CONTINUE_COMMAND });
-				return;
-			}
-			if (goalMode === "chain-here") {
-				await beginBuild(ctx, false, "here", { chainNew: true });
-				return;
-			}
-			await beginBuild(ctx, true);
+			const parsed = parseBuildOptions(args);
+			if (!parsed.ok) { ctx.ui.notify(parsed.error, "error"); return; }
+			const options = parsed.options;
+			await beginBuild(
+				ctx,
+				options.scope === "all",
+				options.placement,
+				{
+					chainNew: options.scope === "all" && options.placement === "new",
+					approvalEachTask: options.scope === "all" && options.approval,
+				},
+			);
 		},
 	});
 
+	async function reviewTask(args: string, ctx: ExtensionCommandContext): Promise<void> {
+		const file = await loadTaskFile(ctx.cwd);
+		const requestedId = Number(args.trim());
+		const task = Number.isFinite(requestedId) && requestedId > 0
+			? file?.tasks.find((item) => item.id === requestedId)
+			: currentTaskId === undefined
+				? file?.tasks.find((item) => !item.done)
+				: file?.tasks.find((item) => item.id === currentTaskId);
+		if (!task) { ctx.ui.notify("No matching task to review.", "info"); return; }
+		const sections: string[] = [];
+		try {
+			const [unstaged, staged, status] = await Promise.all([
+				pi.exec("git", ["diff", "--", "."]),
+				pi.exec("git", ["diff", "--cached", "--", "."]),
+				pi.exec("git", ["status", "--short"]),
+			]);
+			if (unstaged.stdout.trim()) sections.push(`Unstaged:\n${unstaged.stdout}`);
+			if (staged.stdout.trim()) sections.push(`Staged:\n${staged.stdout}`);
+			const untracked = status.stdout.split(/\r?\n/).filter((line) => line.startsWith("??")).join("\n");
+			if (untracked) sections.push(`Untracked:\n${untracked}`);
+		} catch { sections.push("(no git diff available)"); }
+		const full = `Task ${task.id}: ${task.title}\n\n${task.body}\n\nWorking tree:\n${sections.join("\n\n") || "(clean)"}`;
+		const lines = full.split(/\r?\n/);
+		let output = lines.slice(0, 2000).join("\n");
+		if (Buffer.byteLength(output, "utf8") > 50_000) output = Buffer.from(output, "utf8").subarray(0, 50_000).toString("utf8");
+		if (output.length < full.length) output += "\n\n[Output truncated. Use git diff, git diff --cached, and git status --short for full details.]";
+		ctx.ui.notify(output, "info");
+	}
+
+	async function reworkTask(args: string, ctx: ExtensionCommandContext): Promise<void> {
+		const id = Number(args.trim());
+		if (!Number.isInteger(id) || id <= 0) { ctx.ui.notify("Provide a positive task id.", "error"); return; }
+		try {
+			const result = await mutateWorkflow(ctx.cwd, ({ state, task }) => {
+				const file = { raw: task, tasks: parseTaskMarkdown(task) };
+				const mutation = reworkFromTask(state, file, id);
+				if (!mutation.ok) throw new Error(mutation.error);
+				return { state: mutation.value.state, task: mutation.value.task };
+			});
+			planState = result.state;
+			leaveModes(ctx);
+			ctx.ui.notify(`Task ${id} and all later tasks reopened. Run /plan approve before building.`, "info");
+		} catch (error) {
+			ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+		}
+	}
+
 	pi.registerCommand("tasks", {
-		description: "Show current plan tasks and progress",
-		handler: async (_args, ctx) => {
+		description: "Show tasks, review a task, or reopen a task for rework",
+		getArgumentCompletions: (prefix) => {
+			const items = ["review", "rework"].map((name) => ({ value: name, label: name }));
+			const filtered = items.filter((item) => item.value.startsWith(prefix.trim().toLowerCase()));
+			return filtered.length ? filtered : null;
+		},
+		handler: async (args, ctx) => {
+			const [rawAction = "", ...rest] = args.trim().split(/\s+/);
+			const action = rawAction.toLowerCase();
+			const actionArgs = rest.join(" ");
+			if (action === "review") { await reviewTask(actionArgs, ctx); return; }
+			if (action === "rework") { await reworkTask(actionArgs, ctx); return; }
+			if (action) { ctx.ui.notify("Usage: /tasks [review [id]|rework <id>]", "error"); return; }
 			const file = await loadTaskFile(ctx.cwd);
 			const tasks = file?.tasks ?? [];
 			if (ctx.mode !== "tui") {
@@ -446,45 +732,67 @@ export default async function planTaskExtension(pi: ExtensionAPI): Promise<void>
 		},
 	});
 
-	pi.registerCommand("build-next-session", {
-		description: "Continue the next planned task in a new session",
-		handler: async (_args, ctx) => {
-			await startBuildInNewSession(ctx);
-		},
-	});
-
-	pi.registerCommand("goal-next-session", {
-		description: "Continue the next planned task in a new session, then keep chaining new sessions",
-		handler: async (_args, ctx) => {
-			await startBuildInNewSession(ctx, GOAL_CONTINUE_COMMAND);
-		},
-	});
-
 	pi.on("session_start", async (_event, ctx) => {
 		mode = "idle";
 		continueAll = false;
 		continueNew = false;
 		currentTaskId = undefined;
-		toolsBeforePlan = undefined;
+		planToolsDelta = undefined;
 		awaitingChoice = false;
 		planReadyNotified = false;
 		planSource = EMPTY_PLAN_SOURCE;
 		resetFraming();
-		pi.setActiveTools(withAlwaysOnTools(pi.getActiveTools()));
-		if (!pi.getAllTools().some((tool) => tool.name === "ask_user_question")) {
-			ctx.ui.notify(
-				"ask_user_question is missing. Install npm:@juicesharp/rpiv-ask-user-question.",
-				"warning",
-			);
+		stateRestorable = true;
+		try {
+			const persisted = await loadStateLocked(ctx.cwd);
+			if (persisted) {
+				planState = persisted;
+				currentTaskId = persisted.currentTaskId;
+				approvalEachTask = persisted.approvalEachTask === true;
+				continueAll = persisted.continueMode === "all-here";
+				continueNew = persisted.continueMode === "all-new";
+				if (["approved", "executing", "blocked"].includes(persisted.status) && persisted.approvedStructureHash) {
+					try {
+						const current = await readCurrentArtifacts(ctx.cwd);
+						assertApprovedWorkflow(persisted, current.plan, current.task);
+						if (persisted.status === "executing" && persisted.currentTaskId !== undefined) await enterBuildMode(ctx);
+					} catch (error) {
+						planState = transition(persisted, "ready");
+						planState = { ...planState, approvedStructureHash: undefined, currentTaskId: undefined, failureReason: error instanceof Error ? error.message : String(error) };
+						currentTaskId = undefined;
+						await saveStateLocked(ctx.cwd, planState);
+						ctx.ui.notify("Plan files or contract changed after approval; approval was revoked.", "warning");
+					}
+				} else if (persisted.status === "planning") {
+					planSource = persisted.planningRequest ? { kind: "prompt", prompt: persisted.planningRequest } : EMPTY_PLAN_SOURCE;
+					await enterPlanMode(ctx);
+				}
+			}
+		} catch (error) {
+			planState = initialState();
+			stateRestorable = false;
+			ctx.ui.notify(`Workflow state could not be restored; execution is disabled: ${String(error)}`, "error");
 		}
-		updateStatus(ctx);
+		pi.setActiveTools(withAlwaysOnTools(pi.getActiveTools()));
+		if (!pi.getAllTools().some((tool) => tool.name === "ask_user_question")) ctx.ui.notify("ask_user_question is missing. Install npm:@juicesharp/rpiv-ask-user-question.", "warning");
+		const file = await loadTaskFile(ctx.cwd).catch(() => undefined);
+		updateStatus(ctx, file?.tasks);
 	});
+	async function persistSession(ctx: ExtensionContext): Promise<void> {
+		if (!stateRestorable) return;
+		await saveStateLocked(ctx.cwd, { ...planState, currentTaskId, sessionFile: ctx.sessionManager.getSessionFile() });
+	}
+	pi.on("session_shutdown", async (_event, ctx) => persistSession(ctx));
+	pi.on("session_before_switch", async (_event, ctx) => persistSession(ctx));
+	pi.on("session_before_fork", async (_event, ctx) => persistSession(ctx));
 
 	pi.on("before_agent_start", async (_event, ctx) => {
 		let statusKey: string | undefined;
 		let task: TaskItem | undefined;
 		let tasks: TaskItem[] | undefined;
 		let remaining = 0;
+		let planContent = "";
+		let planKey = "";
 		if (mode === "build" && currentTaskId !== undefined) {
 			const file = await loadTaskFile(ctx.cwd);
 			task = file?.tasks.find((item) => item.id === currentTaskId);
@@ -492,9 +800,15 @@ export default async function planTaskExtension(pi: ExtensionAPI): Promise<void>
 				tasks = file.tasks;
 				statusKey = buildStatusKey(file.tasks, currentTaskId);
 				remaining = file.tasks.filter((item) => !item.done).length;
+				try {
+					planContent = (await readOptionalFile(planFilePath(ctx.cwd))) ?? "";
+				} catch (error) {
+					ctx.ui.notify(`Could not read ${planFilePath(ctx.cwd)}: ${String(error)}`, "warning");
+				}
+				planKey = contentKey(planContent);
 			}
 		}
-		const kind = nextInjection(mode, framing, currentTaskId, statusKey);
+		const kind = nextInjection(mode, framing, currentTaskId, statusKey, planKey);
 		if (!kind) return;
 		if (kind === "plan-framing") {
 			framing = rememberInjection(framing, kind);
@@ -508,12 +822,12 @@ export default async function planTaskExtension(pi: ExtensionAPI): Promise<void>
 			};
 		}
 		if (!task || !tasks || currentTaskId === undefined) return;
-		framing = rememberInjection(framing, kind, currentTaskId, statusKey);
+		framing = rememberInjection(framing, kind, currentTaskId, statusKey, planKey);
 		if (kind === "build-framing") {
 			return {
 				message: {
 					customType: BUILD_FRAMING_TYPE,
-					content: buildPrompt(task, remaining, continueAll),
+					content: buildPrompt(task, remaining, continueAll, planContent, planState.tasks?.[String(currentTaskId)]?.status === "implementation-complete"),
 					display: false,
 					details: { phase: "build", taskId: currentTaskId },
 				},
@@ -535,35 +849,80 @@ export default async function planTaskExtension(pi: ExtensionAPI): Promise<void>
 
 	pi.on("tool_call", async (event, ctx) => {
 		if (mode !== "plan") return;
-		if (isToolCallEventType("bash", event)) {
-			if (!isSafePlanCommand(event.input.command)) {
-				return {
-					block: true,
-					reason: `Plan mode blocked this command. Use /build to implement.\nCommand: ${event.input.command}`,
-				};
-			}
-			return;
+		if (event.toolName === "plan_task" && (event.input as { action?: unknown }).action === "complete") {
+			return {
+				block: true,
+				reason: "Plan mode cannot mark implementation tasks complete. Use /build after the plan is approved.",
+			};
 		}
 		if (event.toolName === "write" || event.toolName === "edit") {
 			const path = pathFromInput(event.input);
 			if (!path || !isPlanArtifactPath(ctx.cwd, path)) {
 				return {
 					block: true,
-					reason: `Plan mode can only write ${planFilePath(ctx.cwd)} and ${taskFilePath(ctx.cwd)}.`,
+					reason: `Plan mode can only write ${draftPlanFilePath(ctx.cwd)} and ${draftTaskFilePath(ctx.cwd)}.`,
 				};
 			}
+			return;
+		}
+		if (!isAllowedPlanTool(event.toolName)) {
+			return {
+				block: true,
+				reason: `Plan mode blocked non-read-only tool: ${event.toolName}. Use /build to implement.`,
+			};
 		}
 	});
 
 	pi.on("agent_settled", async (_event, ctx) => {
 		if (mode === "plan") {
-			const file = await loadTaskFile(ctx.cwd);
-			if (file && file.tasks.length > 0 && !planReadyNotified) {
-				planReadyNotified = true;
-				ctx.ui.notify(`Plan written. ${formatProgress(file.tasks)} tasks ready. Run /build to start.`, "info");
+			if (planReadyNotified) return;
+			let draft: { plan: string; task: string };
+			try { draft = await readDraftArtifacts(ctx.cwd); } catch { return; }
+			if (!draft.plan.trim() || !draft.task.trim()) return;
+			const draftHash = structureHash(draft.plan, draft.task);
+			if (draftHash === planState.planningBaselineHash) {
+				ctx.ui.notify("Draft is unchanged; update both draft files before submission.", "warning");
+				return;
+			}
+			let tasks: TaskItem[];
+			try { tasks = parseTaskMarkdown(draft.task); } catch (error) { ctx.ui.notify(`Draft task file is invalid: ${String(error)}`, "error"); return; }
+			const previous = await loadTaskFile(ctx.cwd).catch(() => undefined);
+			let submittedTask = draft.task;
+			const runtimeTasks: NonNullable<PlanState["tasks"]> = {};
+			for (const task of tasks) {
+				const old = previous?.tasks.find((item) => item.id === task.id);
+				const oldRuntime = planState.tasks?.[String(task.id)];
+				const canPreserveVerified = task.done && old?.done && old.title === task.title && old.body === task.body && oldRuntime?.status === "verified" && Boolean(oldRuntime.verification?.trim());
+				if (canPreserveVerified) runtimeTasks[String(task.id)] = oldRuntime!;
+				else {
+					if (task.done) submittedTask = markTaskPendingInMarkdown(submittedTask, task.id);
+					runtimeTasks[String(task.id)] = { status: "pending" };
+				}
 			}
+			tasks = parseTaskMarkdown(submittedTask);
+			const validation = validatePlan(draft.plan, submittedTask, tasks);
+			if (!validation.valid) { ctx.ui.notify(`Plan validation failed: ${validation.errors.join("; ")}`, "error"); return; }
+			planState = transition(planState, "ready");
+			planState = { ...planState, planningBaselineHash: undefined, tasks: runtimeTasks, currentTaskId: undefined, approvedStructureHash: undefined, failureReason: undefined };
+			planState = await commitDraft(ctx.cwd, planState, { plan: draft.plan, task: submittedTask });
+			planReadyNotified = true;
+			pi.events.emit("pi-plan-task:plan-ready", { version: 1, cwd: ctx.cwd, planPath: planFilePath(ctx.cwd), taskPath: taskFilePath(ctx.cwd), planHash: planState.draftStructureHash, sessionFile: ctx.sessionManager.getSessionFile() });
+			if (!ctx.hasUI) {
+				ctx.ui.notify(`Plan written. ${formatProgress(tasks)} tasks ready. Run /plan approve.`, "info");
+				return;
+			}
+			awaitingChoice = true;
+			const choice = await ctx.ui.select(`Plan ready (${formatProgress(tasks)}). What next?`, [
+				"current", "new", "fresh", "review", "revise", "reject", "later",
+			]);
+			awaitingChoice = false;
+			if (choice === "current" || choice === "new" || choice === "fresh") pi.sendUserMessage(`/plan approve ${choice}`, { expandPromptTemplates: true });
+			else if (choice === "review" || choice === "revise" || choice === "reject") pi.sendUserMessage(`/plan ${choice}`, { expandPromptTemplates: true });
+			else ctx.ui.notify("Plan is ready. Run /plan approve when you want to execute it.", "info");
 			return;
 		}
 		await afterBuildSettled(ctx);
 	});
 }
+
+