@gavin-hu/my-pi-agent 0.14.0 → 0.15.0

package/extensions/plan/steps.ts

@@ -281,15 +281,19 @@ export function planStepSummary(plan: string): PlanStepSummary {
 }
 
 /** One checkbox change: a 1-based step number and the state to set. */
-export interface StepUpdate {
+export interface StepEdit {
 	step: number;
 	status: PlanStep["status"];
-	/**
-	 * The step's text when the plan was approved. When given, the update is
-	 * refused if the step at that number no longer carries this text, so a
-	 * reordered or rewritten plan is caught instead of ticking the wrong step.
-	 */
-	expected?: string;
+}
+
+/**
+ * A guarded checkbox change: the edit plus the step's text as it was listed at
+ * approval. The store refuses the batch when the step at that number no longer
+ * carries the text, so a reordered or rewritten plan is caught instead of
+ * ticking the wrong step.
+ */
+export interface StepUpdate extends StepEdit {
+	expected: string;
 }
 
 /** Whether the step text now at a number still matches what the caller expected. */
@@ -308,7 +312,7 @@ export function matchesStepText(actual: string, expected: string): boolean {
  * otherwise left exactly as written. When a step appears twice, the last entry
  * wins.
  */
-export function setStepStatuses(plan: string, updates: StepUpdate[]): string | undefined {
+export function setStepStatuses(plan: string, updates: readonly StepEdit[]): string | undefined {
 	const items = topLevelItems(plan);
 	for (const update of updates) {
 		if (!Number.isInteger(update.step) || update.step < 1 || !items[update.step - 1]) return undefined;
@@ -364,3 +368,28 @@ export function extractPlanSections(plan: string): PlanSection[] {
 	flush();
 	return sections;
 }
+
+/**
+ * The plan's own objective: the first paragraph of its `## Goal` section, with
+ * inline markdown and a leading list marker removed.
+ *
+ * Approval records this as the session goal, so the goal is what the plan says it
+ * achieves rather than the file-name slug. `undefined` when the plan has no
+ * `## Goal` section, so the caller can fall back to the title.
+ */
+export function goalSection(plan: string): string | undefined {
+	const section = extractPlanSections(plan).find(
+		(candidate) => candidate.level === 2 && normalizeHeadingText(candidate.title).toLowerCase() === "goal",
+	);
+	if (section === undefined) return undefined;
+	const paragraph: string[] = [];
+	for (const line of section.text.split("\n").slice(1)) {
+		if (!line.trim()) {
+			if (paragraph.length > 0) break;
+			continue;
+		}
+		paragraph.push(line);
+	}
+	const text = normalizeHeadingText(paragraph.join(" ").replace(/^\s*(?:[-*+]\s+|\d+[.)]\s+)/, ""));
+	return text || undefined;
+}

package/extensions/plan/todos.ts

@@ -1,16 +1,17 @@
 /**
- * Approval-time todo bridge (pure).
+ * The plan↔todo bridge (pure).
  *
  * `todo` is whole-list replacement, so seeding an approved plan straight over
  * the list would discard whatever the user was already tracking. This module
  * merges the plan's steps into the list `lib/todo-state.ts` replays from the
  * session branch: existing items keep their place and status, a step whose text
  * is already present is skipped, and the tool's item cap is respected without
- * dropping anything the user had.
+ * dropping anything the user had. It also mirrors a step's new state back onto
+ * the item it seeded, so ticking the plan file keeps the list honest.
  */
 
 import type { ExistingTodo } from "../../lib/todo-state.ts";
-import type { PlanStep } from "./steps.ts";
+import type { PlanStep, StepUpdate } from "./steps.ts";
 
 /** The merged list plus the counts the approval message reports. */
 export interface TodoMerge {
@@ -33,6 +34,46 @@ export interface TodoMerge {
 /** Fallback list cap when the registered todo tool does not advertise one. */
 export const DEFAULT_TODO_MAX = 50;
 
+/** What the tick-time mirror did for one `set_plan_steps` batch. */
+export interface TodoMirror {
+	/** The list after the matching items were brought in line with the plan. */
+	todos: ExistingTodo[];
+	/** Items whose status the batch changed. */
+	updated: number;
+	/** Steps in the batch with no matching item, so nothing was written for them. */
+	unmatched: number;
+}
+
+/**
+ * Bring the todo items seeded at approval in line with the plan's new step
+ * statuses.
+ *
+ * Matching is on the text the approval seeded, so an item the user renamed is
+ * left alone and counted as unmatched rather than overwritten. Only `status`
+ * changes, and the last update for a step number wins, the same rule the plan
+ * file's own edit follows. An update that changes nothing is not counted, so a
+ * refused or repeated call does not churn the widget.
+ */
+export function mirrorStepStatuses(existing: ExistingTodo[], updates: readonly StepUpdate[]): TodoMirror {
+	const byStep = new Map<number, StepUpdate>();
+	for (const update of updates) byStep.set(update.step, update);
+	const todos = existing.map((todo) => ({ ...todo }));
+	let updated = 0;
+	let unmatched = 0;
+	for (const update of byStep.values()) {
+		const index = todos.findIndex((todo) => contentKey(todo.content) === contentKey(update.expected));
+		if (index === -1) {
+			unmatched += 1;
+			continue;
+		}
+		const todo = todos[index];
+		if (todo === undefined || todo.status === update.status) continue;
+		todos[index] = { ...todo, status: update.status };
+		updated += 1;
+	}
+	return { todos, updated, unmatched };
+}
+
 /** Case- and whitespace-insensitive key for recognizing a repeated item. */
 function contentKey(content: string): string {
 	return content.trim().replace(/\s+/g, " ").toLowerCase();

package/extensions/plan/tools/enter.ts

@@ -0,0 +1,94 @@
+/**
+ * The `enter_plan_mode` tool registration.
+ *
+ * It asks for confirmation, then turns the runtime's enabled flag on; the tool
+ * gating and persistence belong to `runtime.ts`.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { reuseText, toolDetails } from "../../../lib/tui/chrome.ts";
+import { GLYPHS } from "../../../lib/tui/glyphs.ts";
+import { paint } from "../../../lib/tui/tokens.ts";
+import { rejectionLine, reuseCallText, toolCallTitle } from "../../../lib/tui/tool.ts";
+import { PLAN_CONSENT, READ_ONLY_SUMMARY } from "../../../lib/plan-entry.ts";
+import { ENTER_TOOL, type PlanRuntime } from "../runtime.ts";
+import type { EnterPlanModeDetails } from "../types.ts";
+
+const ENTERED_TEXT =
+	"You are now in plan mode. Explore read-only, then save the full plan with write_plan (a short title and the markdown) " +
+	"and call exit_plan_mode with the returned path so the user can read the file and choose. " +
+	`While planning, ${READ_ONLY_SUMMARY}.`;
+
+export function registerEnterTool(pi: ExtensionAPI, runtime: PlanRuntime): void {
+	pi.registerTool({
+		name: ENTER_TOOL,
+		label: "Enter plan mode",
+		description:
+			"Enter read-only plan mode: investigate and design, then save the plan with write_plan and present it with " +
+			"exit_plan_mode. Entering switches the session's active tool set to read-only and requires the user to confirm.",
+		promptSnippet: "Ask the user to enter read-only plan mode.",
+		promptGuidelines: [
+			"Call enter_plan_mode before a non-trivial implementation task; skip it for small, obvious changes.",
+		],
+		parameters: Type.Object({}),
+		executionMode: "sequential",
+		// readOnlyHint stays true: entering plan mode changes only the session's
+		// tool set, never files or system state, so it needs no approval.
+		annotations: { readOnlyHint: true, openWorldHint: false },
+
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+			if (runtime.isEnabled()) {
+				return {
+					content: [{ type: "text", text: "Already in plan mode." }],
+					details: { entered: true, already: true } satisfies EnterPlanModeDetails,
+				};
+			}
+			if (!ctx.hasUI) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: "No interactive UI is available to confirm entering plan mode. Ask the user whether they want a plan.",
+						},
+					],
+					details: { entered: false, unavailable: true } satisfies EnterPlanModeDetails,
+					isError: true,
+				};
+			}
+
+			const approved = await ctx.ui.confirm("Enter plan mode?", PLAN_CONSENT);
+			if (!approved) {
+				return {
+					content: [{ type: "text", text: "Stayed in normal mode. Proceed, or ask the user how to continue." }],
+					details: { entered: false } satisfies EnterPlanModeDetails,
+				};
+			}
+			runtime.enable(ctx);
+			return {
+				content: [{ type: "text", text: ENTERED_TEXT }],
+				details: { entered: true } satisfies EnterPlanModeDetails,
+			};
+		},
+
+		renderCall(_args, theme, context) {
+			const text = reuseCallText(context?.lastComponent);
+			text.setText(toolCallTitle(theme, `${ENTER_TOOL} `) + paint(theme, "meta", "requested plan mode"));
+			return text;
+		},
+
+		renderResult(result, options, theme, context) {
+			const text = reuseText(context?.lastComponent);
+			const details = toolDetails<EnterPlanModeDetails>(result.details);
+			if (!details) {
+				text.setText(rejectionLine(theme, result, options.expanded));
+				return text;
+			}
+			if (details.unavailable) text.setText(paint(theme, "warn", "No UI to confirm plan mode"));
+			else if (details.already) text.setText(paint(theme, "meta", "Already in plan mode"));
+			else if (details.entered) text.setText(paint(theme, "ok", `${GLYPHS.check} Plan mode enabled`));
+			else text.setText(paint(theme, "meta", "Stayed in normal mode"));
+			return text;
+		},
+	});
+}

package/extensions/plan/tools/exit.ts

@@ -0,0 +1,296 @@
+/**
+ * The `exit_plan_mode` tool registration.
+ *
+ * It presents the saved plan for approval, then seeds the approved steps into
+ * the todo list and finalizes the session goal: a `planning` goal becomes the
+ * plan's own `## Goal`, and a session with no goal is offered the same. The
+ * review loop and the browser lifecycle belong to `review.ts`; the nested writes
+ * belong to `todo-seed.ts` and the goal tool.
+ */
+
+import { basename } from "node:path";
+import type { ExtensionAPI, ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import { sanitizeLine } from "../../../lib/format.ts";
+import { lastGoal } from "../../../lib/goal-state.ts";
+import { GOAL_TOOL } from "../../../lib/tool-names.ts";
+import { reuseText, toolDetails } from "../../../lib/tui/chrome.ts";
+import { GLYPHS } from "../../../lib/tui/glyphs.ts";
+import { paint } from "../../../lib/tui/tokens.ts";
+import { moreHint, rejectionLine, reuseCallText, toolCallTitle } from "../../../lib/tui/tool.ts";
+import { feedbackSummary } from "../feedback.ts";
+import { mergeSummary, overCap, preview, verificationNote } from "../format.ts";
+import { sanitizePlanText } from "../plan-text.ts";
+import { planTitle, type StoredPlan } from "../plans.ts";
+import { reviewPlan } from "../review.ts";
+import { EXIT_TOOL, SET_PLAN_STEPS_TOOL, type PlanRuntime } from "../runtime.ts";
+import { goalSection, MAX_STEPS, planStepSummary } from "../steps.ts";
+import type { ExitPlanModeDetails } from "../types.ts";
+import type { PlanWebReview } from "../web.ts";
+import { firstTextLine } from "./nested.ts";
+import { seedTodos } from "./todo-seed.ts";
+
+const ExitPlanModeParams = Type.Object({
+	plan_path: Type.String({
+		description:
+			"Path to the plan file written by write_plan (absolute, or relative to the working directory). The user reviews this file.",
+	}),
+});
+
+type ExitPlanModeArgs = Static<typeof ExitPlanModeParams>;
+
+/** How the goal ended up: no action when it was already final. */
+interface GoalOutcome {
+	objective: string;
+	/** `recorded` for a session with no goal, `promoted` for one that was planning. */
+	action?: "recorded" | "promoted";
+	error?: string;
+}
+
+/**
+ * Finalise the session goal from the approved plan.
+ *
+ * A `planning` goal needs no dialog — approving the plan *is* the decision — and a
+ * session with no goal at all gets one confirm. A final goal (`active` or
+ * `achieved`) is the user's own: approving ordinary work never rewrites it.
+ * Recording runs through the goal tool, so validation and the widget stay goal's,
+ * and no model turn is spent.
+ */
+async function finalizeGoal(ctx: ExtensionToolContext, plan: StoredPlan): Promise<GoalOutcome> {
+	const objective = planObjective(plan);
+	const current = lastGoal(ctx.sessionManager.getBranch());
+	if (current !== null && current.status !== "planning") return { objective };
+	if (current === null) {
+		if (!ctx.hasUI) return { objective };
+		const approved = await ctx.ui.confirm("Record this plan as the session goal?", objective);
+		if (!approved) return { objective };
+	}
+	const outcome = await ctx.executeTool(GOAL_TOOL, { objective, status: "active" });
+	const action = current === null ? "recorded" : "promoted";
+	return outcome.isError ? { objective, action, error: firstTextLine(outcome) } : { objective, action };
+}
+
+/** The plan's own objective: its `## Goal` section, else the `# heading`, else the slug. */
+function planObjective(plan: StoredPlan): string {
+	const stated = goalSection(plan.content);
+	if (stated) return sanitizeLine(stated);
+	const heading = /^ {0,3}#\s+(.+)$/m.exec(plan.content)?.[1];
+	const title = heading === undefined ? "" : sanitizeLine(heading).trim();
+	return title || planTitle(basename(plan.path));
+}
+
+export function registerExitTool(pi: ExtensionAPI, runtime: PlanRuntime, web: PlanWebReview): void {
+	pi.registerTool({
+		name: EXIT_TOOL,
+		label: "Exit plan mode",
+		description:
+			"Present the saved plan and ask the user to approve it. Reads the file written by write_plan, so call it with " +
+			"plan_path. On approval plan mode ends, write access returns, and the plan's steps go into the todo list; the " +
+			"user may instead keep planning or request a refinement. The plan file stays the source of truth.",
+		promptSnippet: "Present the saved plan and ask the user to approve leaving plan mode.",
+		parameters: ExitPlanModeParams,
+		defaultActive: false,
+		executionMode: "sequential",
+		// readOnlyHint stays true: it writes no files, and the review dialog inside
+		// execute is the human gate, so an outer prompt would only double-ask.
+		annotations: { readOnlyHint: true, openWorldHint: false },
+
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const planPath = (params as ExitPlanModeArgs).plan_path.trim();
+
+			if (!runtime.isEnabled()) {
+				return {
+					content: [{ type: "text", text: "Not in plan mode; there is no plan to approve." }],
+					details: { approved: false, plan: "", planPath } satisfies ExitPlanModeDetails,
+					isError: true,
+				};
+			}
+
+			const file = await runtime.plans.read(ctx.cwd, planPath);
+			if (!file) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `No plan file at "${planPath}". Save the plan with write_plan first, then pass the returned path.`,
+						},
+					],
+					details: { approved: false, plan: "", planPath } satisfies ExitPlanModeDetails,
+					isError: true,
+				};
+			}
+
+			const total = planStepSummary(file.content).total;
+			if (total > MAX_STEPS) {
+				// A hand-edited or older plan file can still be over the cap; refuse it here
+				// too, so approval never seeds a list it cannot hold in full.
+				return {
+					content: [
+						{
+							type: "text",
+							text: `${overCap(total)} It was not presented for approval; call write_plan with plan_path to group the steps, then exit_plan_mode again.`,
+						},
+					],
+					details: {
+						approved: false,
+						plan: file.content,
+						planPath: file.path,
+						relativePath: file.relativePath,
+					} satisfies ExitPlanModeDetails,
+					isError: true,
+				};
+			}
+
+			if (!ctx.hasUI) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `No interactive UI is available to approve the plan. It is saved at ${file.relativePath}; present it and ask the user to approve it in their reply.`,
+						},
+					],
+					details: {
+						approved: false,
+						plan: file.content,
+						planPath: file.path,
+						relativePath: file.relativePath,
+						unavailable: true,
+					} satisfies ExitPlanModeDetails,
+					isError: true,
+				};
+			}
+
+			// One decision, however the session is attached; `review.ts` owns the loop,
+			// the baseline, and closing the browser review when the turn is aborted.
+			const decision = await reviewPlan({
+				ctx,
+				web,
+				plans: runtime.plans,
+				baselines: runtime,
+				plan: file,
+				signal,
+			});
+
+			if (decision.action === "refine") {
+				// A browser save already wrote its comments into the file; either way the
+				// model revises the same plan and presents it again.
+				const feedback = decision.fromBrowser
+					? `The user reviewed the plan in the browser and left feedback:\n${decision.refinement}`
+					: `The user asked to refine the plan: ${decision.refinement}`;
+				return {
+					content: [
+						{
+							type: "text",
+							text: `${feedback}\nStay in plan mode, revise the plan (write_plan, reusing plan_path), then call exit_plan_mode again.`,
+						},
+					],
+					details: {
+						approved: false,
+						plan: decision.plan.content,
+						planPath: decision.plan.path,
+						relativePath: decision.plan.relativePath,
+						refined: true,
+						refinement: decision.refinement,
+						annotations: decision.comments.length > 0 ? decision.comments : undefined,
+					} satisfies ExitPlanModeDetails,
+				};
+			}
+			if (decision.action === "keep") {
+				return {
+					content: [
+						{ type: "text", text: "Plan not approved. Stay in plan mode, ask what to change, and revise the plan." },
+					],
+					details: {
+						approved: false,
+						plan: decision.plan.content,
+						planPath: decision.plan.path,
+						relativePath: decision.plan.relativePath,
+					} satisfies ExitPlanModeDetails,
+				};
+			}
+
+			runtime.disable(ctx);
+			const { steps, merged, error } = await seedTodos(pi, ctx, decision.plan.content);
+			const goal = await finalizeGoal(ctx, decision.plan);
+			const listing =
+				steps.length > 0
+					? `\n\n${steps
+							.map((step, index) => `${index + 1}. [${step.status === "completed" ? "x" : " "}] ${step.content}`)
+							.join("\n")}`
+					: "";
+			const tail =
+				steps.length === 0
+					? " The plan has no steps to record."
+					: error
+						? ` Could not record the steps in the todo list: ${error}. Keep these steps in mind and tick them off with ${SET_PLAN_STEPS_TOOL} as you go.`
+						: merged
+							? mergeSummary(merged, steps)
+							: ` Could not read the todo list. Record these steps with the todo tool before you start, and tick them off with ${SET_PLAN_STEPS_TOOL}.`;
+			const verification = verificationNote(merged);
+			const goalNote =
+				goal.action === undefined
+					? ""
+					: goal.error !== undefined
+						? ` Could not ${goal.action === "recorded" ? "record" : "update"} the session goal: ${goal.error}. Use the goal tool to set it.`
+						: goal.action === "recorded"
+							? ` Recorded the session goal: ${goal.objective}.`
+							: ` Set the session goal from the plan: ${goal.objective}.`;
+			const browserNote = decision.comments.length
+				? `\n\nThe user approved from the browser review with these comments:\n${feedbackSummary(decision.comments)}`
+				: "";
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Plan approved. Plan mode is off and write access is restored. The plan file ${decision.plan.relativePath} is the source of truth; follow its steps.${browserNote}${tail}${verification}${goalNote}${listing}`,
+					},
+				],
+				details: {
+					approved: true,
+					plan: decision.plan.content,
+					planPath: decision.plan.path,
+					relativePath: decision.plan.relativePath,
+					annotations: decision.comments.length > 0 ? decision.comments : undefined,
+				} satisfies ExitPlanModeDetails,
+			};
+		},
+
+		renderCall(_args, theme, context) {
+			const text = reuseCallText(context?.lastComponent);
+			text.setText(toolCallTitle(theme, `${EXIT_TOOL} `) + paint(theme, "meta", "submitted a plan"));
+			return text;
+		},
+
+		renderResult(result, { expanded }, theme, context) {
+			const text = reuseText(context?.lastComponent);
+			const details = toolDetails<ExitPlanModeDetails>(result.details);
+			if (!details) {
+				text.setText(rejectionLine(theme, result, expanded));
+				return text;
+			}
+			const heading = details.unavailable
+				? paint(theme, "warn", "No UI to approve the plan")
+				: details.approved
+					? paint(theme, "ok", `${GLYPHS.check} Plan approved`)
+					: details.refined
+						? paint(theme, "accent", "Refining the plan")
+						: paint(theme, "warn", "Plan not approved");
+			const extra =
+				details.refined && details.refinement
+					? `\n${paint(theme, "meta", `↳ ${sanitizePlanText(details.refinement)}`)}`
+					: "";
+			const shown = details.relativePath ?? details.planPath;
+			const path = shown ? `\n${paint(theme, "meta", shown)}` : "";
+			const planText = sanitizePlanText(details.plan);
+			let out = `${heading}${extra}${path}`;
+			if (planText) {
+				const { body, more } = expanded ? { body: planText, more: 0 } : preview(planText);
+				// A blank line separates the header block from the plan body.
+				out += `\n\n${theme.fg("toolOutput", body)}`;
+				if (more > 0) out += `\n${moreHint(theme, more)}`;
+			}
+			text.setText(out);
+			return text;
+		},
+	});
+}

package/extensions/plan/tools/nested.ts

@@ -0,0 +1,21 @@
+/**
+ * Reading a nested `ctx.executeTool` result.
+ *
+ * The plan tools delegate to `todo` and `goal` so their validation and widgets
+ * run normally; when the nested call fails, its first text line is the reason
+ * worth reporting, sanitized because a tool message is untrusted text.
+ */
+
+import { sanitizeLine } from "../../../lib/format.ts";
+
+/** The shape of a nested tool outcome the plan tools read. */
+interface NestedOutcome {
+	result?: { content?: ReadonlyArray<{ type: string; text?: string }> };
+}
+
+/** The first text line of a nested result, sanitized, or undefined. */
+export function firstTextLine(outcome: NestedOutcome): string | undefined {
+	const part = outcome.result?.content?.find((entry) => entry.type === "text");
+	const text = part?.type === "text" && typeof part.text === "string" ? part.text.split("\n", 1)[0] : undefined;
+	return text ? sanitizeLine(text) : undefined;
+}

package/extensions/plan/tools/steps.ts

@@ -0,0 +1,136 @@
+/**
+ * The `set_plan_steps` tool registration.
+ *
+ * It rewrites the plan file's checkboxes in one call, then mirrors the same
+ * batch into the todo items approval seeded. A rejected batch leaves both
+ * artifacts untouched.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type, type Static } from "typebox";
+import { reuseText, toolDetails } from "../../../lib/tui/chrome.ts";
+import { GLYPHS } from "../../../lib/tui/glyphs.ts";
+import { paint } from "../../../lib/tui/tokens.ts";
+import { rejectionLine, reuseCallText, toolCallTitle } from "../../../lib/tui/tool.ts";
+import { describeUpdates, stepLabel } from "../format.ts";
+import { SET_PLAN_STEPS_TOOL, type PlanRuntime } from "../runtime.ts";
+import { extractPlanSteps } from "../steps.ts";
+import type { SetPlanStepsDetails } from "../types.ts";
+import { mirrorTodos } from "./todo-seed.ts";
+
+const StepUpdateParams = Type.Object({
+	step: Type.Integer({
+		minimum: 1,
+		description: "1-based step number, in the order the plan was approved.",
+	}),
+	status: StringEnum(["pending", "completed"] as const, {
+		description: "The step's new state.",
+	}),
+	expected: Type.String({
+		description:
+			"The step's text as it was listed when the plan was approved. A mismatch refuses the whole batch, so a reordered plan is caught instead of mis-ticked.",
+	}),
+});
+
+const SetPlanStepsParams = Type.Object({
+	plan_path: Type.String({
+		description: "Path to the approved plan file, as returned by write_plan or exit_plan_mode.",
+	}),
+	updates: Type.Array(StepUpdateParams, {
+		minItems: 1,
+		description:
+			"The steps to set; each entry sets one step's checkbox, and the last entry wins for a duplicate step. Pass expected as well to refuse a stale step number.",
+	}),
+});
+
+type SetPlanStepsArgs = Static<typeof SetPlanStepsParams>;
+
+export function registerSetPlanStepsTool(pi: ExtensionAPI, runtime: PlanRuntime): void {
+	pi.registerTool({
+		name: SET_PLAN_STEPS_TOOL,
+		label: "Set plan steps",
+		description:
+			"Keep an approved plan file current by setting the checkboxes of the given top-level steps in place. Each step " +
+			"number matches the order the plan was approved in; a step can be marked completed or reopened. Only the " +
+			"checkboxes change; the step text is left as written. The file is rewritten once, and nothing changes when any " +
+			"step is out of range or an entry's expected text no longer matches the file.",
+		promptSnippet: "Tick steps off in the approved plan file.",
+		promptGuidelines: [
+			"After a plan is approved, call set_plan_steps as you complete steps, passing each step's text as expected so a reordered plan is refused instead of mis-ticked.",
+		],
+		parameters: SetPlanStepsParams,
+		executionMode: "sequential",
+		annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const args = params as SetPlanStepsArgs;
+			if (runtime.isEnabled()) {
+				return {
+					content: [{ type: "text", text: "Not while planning; refine the plan with write_plan instead." }],
+					details: undefined,
+					isError: true,
+				};
+			}
+			try {
+				const plan = await runtime.plans.setSteps(ctx.cwd, args.plan_path, args.updates);
+				const steps = extractPlanSteps(plan.content);
+				const done = steps.filter((step) => step.status === "completed").length;
+				const todoNote = await mirrorTodos(ctx, args.updates);
+				return {
+					content: [
+						{
+							type: "text",
+							text: `${describeUpdates(args.updates)} (${done}/${steps.length} done) in ${plan.relativePath}${todoNote}.`,
+						},
+					],
+					details: {
+						path: plan.path,
+						relativePath: plan.relativePath,
+						updates: args.updates,
+						done,
+						total: steps.length,
+					} satisfies SetPlanStepsDetails,
+				};
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return {
+					content: [{ type: "text", text: `Could not update the plan: ${message}` }],
+					details: undefined,
+					isError: true,
+				};
+			}
+		},
+
+		renderCall(args, theme, context) {
+			const text = reuseCallText(context?.lastComponent);
+			const updates = (args as Partial<SetPlanStepsArgs>).updates;
+			const label =
+				updates && updates.length === 1 && updates[0]?.step !== undefined
+					? `step ${updates[0].step}`
+					: updates && updates.length > 1
+						? `${updates.length} steps`
+						: "steps";
+			text.setText(toolCallTitle(theme, `${SET_PLAN_STEPS_TOOL} `) + paint(theme, "meta", label));
+			return text;
+		},
+
+		renderResult(result, options, theme, context) {
+			const text = reuseText(context?.lastComponent);
+			const details = toolDetails<SetPlanStepsDetails>(result.details);
+			if (!details) {
+				text.setText(rejectionLine(theme, result, options.expanded));
+				return text;
+			}
+			const completed = details.updates.filter((update) => update.status === "completed").map((u) => u.step);
+			const pending = details.updates.filter((update) => update.status === "pending").map((u) => u.step);
+			const heading =
+				completed.length > 0
+					? paint(theme, "ok", `${GLYPHS.check} ${stepLabel(completed)} done`) +
+						(pending.length > 0 ? paint(theme, "meta", ` · ${stepLabel(pending)} reopened`) : "")
+					: paint(theme, "meta", `${stepLabel(pending)} reopened`);
+			text.setText(heading + paint(theme, "faint", ` · ${details.done}/${details.total}`));
+			return text;
+		},
+	});
+}