@gavin-hu/my-pi-agent 0.21.0 → 0.22.0

package/extensions/plan/runtime.ts

@@ -2,18 +2,18 @@
  * Session-scoped state and tool gating for plan mode.
  *
  * Enabling plan mode removes every tool the policy does not consider read-only
- * from the active set and activates the plan-mode control tools: `exit_plan_mode`
- * (present the plan for approval) and `write_plan` (save the plan artifact under
- * the plans directory). Disabling restores exactly what it hid. The enabled flag is
- * persisted as a custom session entry so `/resume` and `/tree` follow the
- * branch, and it is also mirrored into the footer status. The review baseline
- * travels the same way, as one digest per heading section, so the changed-section
- * markers survive a resume too.
+ * from the active set, and keeps the one `plan` tool active in both modes: its
+ * actions are what ask to enter, save the artifact under the plans directory,
+ * present it, tick it, and leave. Disabling restores exactly what it hid. The
+ * enabled flag is persisted as a custom session entry so `/resume` and `/tree`
+ * follow the branch, and it is also mirrored into the footer status. The review
+ * baseline travels the same way, as one digest per heading section, so the
+ * changed-section markers survive a resume too.
  *
- * `write_plan` is the one sanctioned write while planning. The read-only guard
- * in `index.ts` permits plan's own tools only when the registered tool is this
- * extension's (matched by source path), so a same-named tool from another
- * extension cannot borrow the exemption.
+ * The `plan` tool's `write` action is the one sanctioned write while planning. The
+ * read-only guard in `index.ts` permits that tool only when the registered one is
+ * this extension's (matched by source path), so a same-named tool from another
+ * extension cannot borrow the exemption, and each action refuses outside its mode.
  */
 
 import { basename, resolve } from "node:path";
@@ -23,23 +23,25 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { sanitizeLine } from "../../lib/format.ts";
 import { PLAN_MODE_ENTRY_TYPE } from "../../lib/plan-state.ts";
 import type { ReadOnlyPolicy } from "../../lib/policy.ts";
-import { PLAN_ENTER_TOOL } from "../../lib/tool-names.ts";
+import { PLAN_TOOL as PLAN_TOOL_NAME } from "../../lib/tool-names.ts";
 import { GLYPHS, STATUS_KEYS } from "../../lib/tui/glyphs.ts";
-import { paint } from "../../lib/tui/tokens.ts";
 import { createPlanStore, type PlanStore } from "./plans.ts";
 import { sameSections, sectionDigests, type SectionDigest } from "./plan-text.ts";
 import type { PlanModeEntry, ReviewBaselineEntry, SeededStepsEntry } from "./types.ts";
 
-/** Tool the model calls to leave plan mode after approval. */
-export const EXIT_TOOL = "exit_plan_mode";
-/** Tool the model calls to leave plan mode without approving. */
-export const CANCEL_TOOL = "cancel_plan_mode";
-/** Tool the model calls to ask to enter plan mode. */
-export const ENTER_TOOL = PLAN_ENTER_TOOL;
-/** Tool the model calls to save the plan artifact. */
-export const WRITE_PLAN_TOOL = "write_plan";
-/** Tool the model calls to keep an approved plan's steps current. */
-export const SET_PLAN_STEPS_TOOL = "set_plan_steps";
+/** The one model-facing tool: every planning verb is one of its actions. */
+export const PLAN_TOOL = PLAN_TOOL_NAME;
+
+/**
+ * The verbs of the one `plan` tool, in the order the schema offers them.
+ *
+ * One action tool rather than five tools, so every verb shares a name and a
+ * registration; the order is the one the description walks them in.
+ */
+export const PLAN_ACTIONS = ["enter", "write", "exit", "steps", "cancel"] as const;
+
+/** One verb of the `plan` tool. */
+export type PlanAction = (typeof PLAN_ACTIONS)[number];
 /** Custom-entry type used for plan-mode state. */
 export const STATE_TYPE = PLAN_MODE_ENTRY_TYPE;
 /** Custom-entry type used for a plan's review baseline. */
@@ -50,16 +52,13 @@ export const SEEDED_TYPE = "plan-seeded";
 /** Longest plan-file basename shown in the footer chip. */
 const STATUS_NAME_LENGTH = 28;
 
-/** Tools plan mode activates itself. */
-const CONTROL_TOOLS = [EXIT_TOOL, CANCEL_TOOL, WRITE_PLAN_TOOL];
-
 /**
- * Tools the read-only guard exempts when this extension registered them.
- * `enter_plan_mode` is here only so a call already in flight when plan mode came on
- * is answered by the tool ("already in plan mode"); the policy still denies it, so
- * it stays hidden while planning.
+ * The one tool plan mode keeps in the active set in both modes. Every other tool
+ * follows the policy, which is about writing files and cannot answer for a tool
+ * whose actions are the mode's own verbs: hiding it while planning would hide the
+ * way to write the plan and the way out.
  */
-const OWNED_TOOLS = [...CONTROL_TOOLS, ENTER_TOOL];
+const MODE_TOOLS = [PLAN_TOOL];
 
 export interface PlanRuntime {
 	/** Whether plan mode is currently on. */
@@ -69,9 +68,9 @@ export interface PlanRuntime {
 	toggle(ctx: ExtensionContext): void;
 	/** Restore state from the branch and the `--plan` flag. */
 	restore(ctx: ExtensionContext): void;
-	/** Plan-file storage for `write_plan` and `exit_plan_mode`. */
+	/** Plan-file storage for the `write` and `exit` actions. */
 	plans: PlanStore;
-	/** Whether `toolName` is one of plan's own tools (not a same-named impostor) the read-only guard exempts. */
+	/** Whether `toolName` is the `plan` tool (not a same-named impostor) the read-only guard exempts. */
 	isOwnTool(toolName: string): boolean;
 	/** Path of the most recently written plan, for the footer chip. */
 	lastPlanPath(): string | undefined;
@@ -195,6 +194,9 @@ export function createPlanRuntime(
 	// Tools plan mode deactivated, so disabling restores exactly those and does
 	// not re-activate a tool another extension intentionally hid.
 	let removedForPlan: string[] = [];
+	// Mode tools this enable had to activate, so disabling puts the user's own
+	// active set back instead of widening it.
+	let addedForPlan: string[] = [];
 
 	const plans = createPlanStore(pi);
 
@@ -204,7 +206,7 @@ export function createPlanRuntime(
 	 * is rejected.
 	 */
 	const isOwnTool = (toolName: string): boolean => {
-		if (!OWNED_TOOLS.includes(toolName)) return false;
+		if (toolName !== PLAN_TOOL) return false;
 		const info = pi.getAllTools().find((tool) => tool.name === toolName);
 		const source = info?.sourceInfo?.path;
 		return source === undefined || options.entryPath === undefined || samePath(source, options.entryPath);
@@ -212,7 +214,7 @@ export function createPlanRuntime(
 
 	/** Tools plan mode would hide from the current active set. */
 	const captureHidden = (): string[] => [
-		...new Set(pi.getActiveTools().filter((name) => !policy.isAllowed(name) && !CONTROL_TOOLS.includes(name))),
+		...new Set(pi.getActiveTools().filter((name) => !policy.isAllowed(name) && !MODE_TOOLS.includes(name))),
 	];
 
 	/**
@@ -224,12 +226,18 @@ export function createPlanRuntime(
 		const active = pi.getActiveTools();
 		if (enabled) {
 			// Keep only tools the policy considers safe to expose while read-only
-			// (structured readers and the plan/goal trackers) plus the control tools.
-			pi.setActiveTools([...new Set([...active.filter((name) => policy.isAllowed(name)), ...CONTROL_TOOLS])]);
+			// (structured readers and the plan/goal trackers), plus the `plan` tool
+			// itself, whose actions are the mode's own vocabulary.
+			addedForPlan = MODE_TOOLS.filter((name) => !active.includes(name));
+			pi.setActiveTools([...new Set([...active.filter((name) => policy.isAllowed(name)), ...MODE_TOOLS])]);
 			return;
 		}
+		// A mode tool this enable had to activate goes back to how the user left it,
+		// rather than staying active because the mode needed it for a while.
+		const kept = active.filter((name) => !addedForPlan.includes(name));
+		addedForPlan = [];
 		const restored = addHidden ? removedForPlan : [];
-		pi.setActiveTools([...new Set([...active.filter((name) => !CONTROL_TOOLS.includes(name)), ...restored])]);
+		pi.setActiveTools([...new Set([...kept, ...restored])]);
 		removedForPlan = [];
 	};
 
@@ -237,7 +245,9 @@ export function createPlanRuntime(
 		lastPlanPath ? `${GLYPHS.plan} plan · ${statusName(lastPlanPath)}` : `${GLYPHS.plan} plan`;
 
 	const setStatus = (ctx: ExtensionContext): void => {
-		ctx.ui.setStatus(STATUS_KEYS.planMode, enabled ? paint(ctx.ui.theme, "warn", statusText()) : undefined);
+		// Published unstyled: the chip's text is what a footer without bytefly shows, and
+		// bytefly's mode segment paints the mode by role instead of reading this pill.
+		ctx.ui.setStatus(STATUS_KEYS.planMode, enabled ? statusText() : undefined);
 	};
 
 	const setEnabled = (next: boolean, ctx: ExtensionContext | undefined, persist: boolean): void => {

package/extensions/plan/sections.ts

@@ -2,7 +2,7 @@
  * Plan-document sections (pure).
  *
  * One fence-aware scan of a plan's markdown: the review screen navigates by
- * section, `set_plan_steps` looks up `## Steps`, a carried comment finds the
+ * section, the `plan` tool's `steps` action looks up `## Steps`, a carried comment finds the
  * block it belongs to, and the browser outline lists the same headings. A second
  * scanner would disagree about a heading inside a fence, so every reader goes
  * through this module.

package/extensions/plan/steps.ts

@@ -31,7 +31,7 @@ export const MAX_STEP_LENGTH = 200;
  * section that carries the end state — the same surface before and after when the
  * change alters one that already exists, one frame when it is new — in a fence
  * that stays untagged unless every line is code, so the reviewer sees the result
- * before the steps that build it. Guidance only: `write_plan` never rejects or
+ * before the steps that build it. Guidance only: the `write` action never rejects or
  * rewrites a plan that omits a section, and a change with no visible surface drops
  * `Visual`.
  */
@@ -268,7 +268,7 @@ const LIST_PREFIX = /^\s*(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s*)?/;
  * list markers and inline emphasis, and the lines are joined with `; `, prefixed
  * with `Verify:` and elided like a long step. The item is deliberately *not* a
  * plan step: it is not in the `Steps` section, so it must not count against the
- * step cap or appear in `set_plan_steps` numbering.
+ * step cap or appear in the `steps` action's numbering.
  *
  * A plan with no `Steps` heading feeds its shallowest list as steps (the older
  * rule), so that list already covers the verification bullets; appending a
@@ -297,7 +297,7 @@ export function extractPlanSteps(plan: string): PlanStep[] {
 	return topLevelItems(plan).map((item) => ({ content: elide(item.step.content), status: item.step.status }));
 }
 
-/** The full cost of a plan's step list, for the warning `write_plan` reports. */
+/** The full cost of a plan's step list, for the warning the `write` action reports. */
 export interface PlanStepSummary {
 	/** Top-level items in the step list, before the {@link MAX_STEPS} cap. */
 	total: number;

package/extensions/plan/todos.ts

@@ -44,7 +44,7 @@ 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. */
+/** What the tick-time mirror did for one `steps` batch. */
 export interface TodoMirror {
 	/** The list after the matching items were brought in line with the plan. */
 	todos: ExistingTodo[];

package/extensions/plan/tools/cancel.ts

@@ -1,5 +1,5 @@
 /**
- * The `cancel_plan_mode` tool registration.
+ * The `cancel` action of the `plan` tool.
  *
  * This is the escape hatch that does not need a plan file or a review dialog:
  * when the user asks to leave planning, the model can restore write access
@@ -7,73 +7,38 @@
  * still review the saved artifact.
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-import { reuseText, toolDetails } from "../../../lib/tui/chrome.ts";
+import type { AgentToolResult, ExtensionToolContext, Theme } from "@earendil-works/pi-coding-agent";
 import { paint } from "../../../lib/tui/tokens.ts";
-import { callLine, detailsOrLine } from "../../../lib/tui/tool.ts";
-import { failedResult } from "../../../lib/tool-result.ts";
-import { CANCEL_TOOL, type PlanRuntime } from "../runtime.ts";
-import type { CancelPlanModeDetails } from "../types.ts";
+import { callLine, type ToolCallText } from "../../../lib/tui/tool.ts";
+import { planRefusal } from "./refusal.ts";
+import { PLAN_TOOL, type PlanRuntime } from "../runtime.ts";
+import type { CancelPlanModeDetails, PlanDetails } from "../types.ts";
 
 const CANCELLED_TEXT =
 	"Plan mode is off and write access is restored. The plan was not approved; no todo items or goal were recorded. " +
 	"Any saved plan file remains for a later review.";
 
-export function registerCancelTool(pi: ExtensionAPI, runtime: PlanRuntime): void {
-	pi.registerTool({
-		name: CANCEL_TOOL,
-		label: "Cancel plan mode",
-		description:
-			"Leave plan mode without approving a plan. Restores write access; no todo items or goal are recorded. " +
-			"Use when the user asks to exit, cancel, or abandon planning.",
-		promptSnippet: "Leave plan mode without approving the plan.",
-		promptGuidelines: [
-			"Call cancel_plan_mode when the user asks to leave or abandon planning without approving a plan.",
-		],
-		parameters: Type.Object({}),
-		defaultActive: false,
-		executionMode: "sequential",
-		// The mode change touches no files; like enter_plan_mode, it needs no
-		// destructive annotation.
-		annotations: { readOnlyHint: true, openWorldHint: false },
-
-		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
-			if (!runtime.isEnabled()) {
-				return failedResult("Not in plan mode; there is nothing to cancel.", {
-					cancelled: false,
-				} satisfies CancelPlanModeDetails);
-			}
-			runtime.disable(ctx);
-			ctx.ui.notify("Plan mode off — full access restored. The plan was not approved.", "info");
-			return {
-				content: [{ type: "text", text: CANCELLED_TEXT }],
-				details: { cancelled: true } satisfies CancelPlanModeDetails,
-			};
-		},
+export async function executeCancel(
+	runtime: PlanRuntime,
+	ctx: ExtensionToolContext,
+): Promise<AgentToolResult<PlanDetails>> {
+	if (!runtime.isEnabled()) {
+		return planRefusal("cancel", "Not in plan mode; there is nothing to cancel.");
+	}
+	runtime.disable(ctx);
+	ctx.ui.notify("Plan mode off — full access restored. The plan was not approved.", "info");
+	return {
+		content: [{ type: "text", text: CANCELLED_TEXT }],
+		details: { action: "cancel", cancelled: true } satisfies CancelPlanModeDetails,
+	};
+}
 
-		renderCall(_args, theme, context) {
-			return callLine(theme, context?.lastComponent, CANCEL_TOOL, "left plan mode");
-		},
+export function callCancel(theme: Theme, last: unknown): ToolCallText {
+	return callLine(theme, last, PLAN_TOOL, "cancel");
+}
 
-		renderResult(result, options, theme, context) {
-			const text = reuseText(context?.lastComponent);
-			const outcome = detailsOrLine(
-				theme,
-				result,
-				options.expanded,
-				toolDetails<CancelPlanModeDetails>(result.details),
-			);
-			if ("line" in outcome) {
-				text.setText(outcome.line);
-				return text;
-			}
-			text.setText(
-				outcome.details.cancelled
-					? paint(theme, "warn", "Plan mode off — plan not approved")
-					: paint(theme, "meta", "Not in plan mode"),
-			);
-			return text;
-		},
-	});
+export function textCancel(details: CancelPlanModeDetails, theme: Theme): string {
+	return details.cancelled
+		? paint(theme, "warn", "Plan mode off — plan not approved")
+		: paint(theme, "meta", "Not in plan mode");
 }

package/extensions/plan/tools/enter.ts

@@ -1,98 +1,72 @@
 /**
- * The `enter_plan_mode` tool registration.
+ * The `enter` action of the `plan` tool.
  *
  * 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 { callLine, detailsOrLine } from "../../../lib/tui/tool.ts";
-import { failedResult } from "../../../lib/tool-result.ts";
+import type { AgentToolResult, ExtensionToolContext, Theme } from "@earendil-works/pi-coding-agent";
 import { isRemoteTurn, remoteLanguage } from "../../../lib/interaction.ts";
 import { PLAN_CONSENT, PLAN_CONSENT_SHORT, PLAN_CONSENT_SHORT_ZH, READ_ONLY_SUMMARY } from "../../../lib/plan-entry.ts";
-import { ENTER_TOOL, type PlanRuntime } from "../runtime.ts";
+import { failedResult } from "../../../lib/tool-result.ts";
+import { GLYPHS } from "../../../lib/tui/glyphs.ts";
+import { paint } from "../../../lib/tui/tokens.ts";
+import { callLine, type ToolCallText } from "../../../lib/tui/tool.ts";
+import { PLAN_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. " +
+	"You are now in plan mode. Explore read-only, then save the full plan with `plan` action `write` (a short title and the " +
+	"markdown) and call `plan` action `exit` with the returned plan_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 failedResult(
-					"No interactive UI is available to confirm entering plan mode. Ask the user whether they want a plan.",
-					{ entered: false, unavailable: true } satisfies EnterPlanModeDetails,
-				);
-			}
+export async function executeEnter(
+	runtime: PlanRuntime,
+	ctx: ExtensionToolContext,
+): Promise<AgentToolResult<EnterPlanModeDetails>> {
+	if (runtime.isEnabled()) {
+		return {
+			content: [{ type: "text", text: "Already in plan mode." }],
+			details: { action: "enter", entered: true, already: true } satisfies EnterPlanModeDetails,
+		};
+	}
+	if (!ctx.hasUI) {
+		return failedResult(
+			"No interactive UI is available to confirm entering plan mode. Ask the user whether they want a plan.",
+			{ action: "enter", entered: false, unavailable: true } satisfies EnterPlanModeDetails,
+		);
+	}
 
-			const consent = isRemoteTurn(ctx)
-				? remoteLanguage(ctx) === "zh"
-					? PLAN_CONSENT_SHORT_ZH
-					: PLAN_CONSENT_SHORT
-				: PLAN_CONSENT;
-			const approved = await ctx.ui.confirm("Enter plan mode?", 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);
-			if (isRemoteTurn(ctx)) {
-				// The peer UI has no footer chip; say the mode and its exit in the chat.
-				ctx.ui.notify("Plan mode on — write access is off. Say “exit plan mode” to leave without approving.", "info");
-			}
-			return {
-				content: [{ type: "text", text: ENTERED_TEXT }],
-				details: { entered: true } satisfies EnterPlanModeDetails,
-			};
-		},
+	const consent = isRemoteTurn(ctx)
+		? remoteLanguage(ctx) === "zh"
+			? PLAN_CONSENT_SHORT_ZH
+			: PLAN_CONSENT_SHORT
+		: PLAN_CONSENT;
+	const approved = await ctx.ui.confirm("Enter plan mode?", consent);
+	if (!approved) {
+		return {
+			content: [{ type: "text", text: "Stayed in normal mode. Proceed, or ask the user how to continue." }],
+			details: { action: "enter", entered: false } satisfies EnterPlanModeDetails,
+		};
+	}
+	runtime.enable(ctx);
+	if (isRemoteTurn(ctx)) {
+		// The peer UI has no footer chip; say the mode and its exit in the chat.
+		ctx.ui.notify("Plan mode on — write access is off. Say “exit plan mode” to leave without approving.", "info");
+	}
+	return {
+		content: [{ type: "text", text: ENTERED_TEXT }],
+		details: { action: "enter", entered: true } satisfies EnterPlanModeDetails,
+	};
+}
 
-		renderCall(_args, theme, context) {
-			return callLine(theme, context?.lastComponent, ENTER_TOOL, "requested plan mode");
-		},
+export function callEnter(theme: Theme, last: unknown): ToolCallText {
+	return callLine(theme, last, PLAN_TOOL, "enter");
+}
 
-		renderResult(result, options, theme, context) {
-			const text = reuseText(context?.lastComponent);
-			const outcome = detailsOrLine(theme, result, options.expanded, toolDetails<EnterPlanModeDetails>(result.details));
-			if ("line" in outcome) {
-				text.setText(outcome.line);
-				return text;
-			}
-			const details = outcome.details;
-			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;
-		},
-	});
+export function textEnter(details: EnterPlanModeDetails, theme: Theme): string {
+	if (details.unavailable) return paint(theme, "warn", "No UI to confirm plan mode");
+	if (details.already) return paint(theme, "meta", "Already in plan mode");
+	if (details.entered) return paint(theme, "ok", `${GLYPHS.check} Plan mode enabled`);
+	return paint(theme, "meta", "Stayed in normal mode");
 }