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

package/extensions/memory/tui.ts

@@ -26,6 +26,7 @@ import {
 	type TuiMouseEventResult,
 } from "@earendil-works/pi-tui";
 import { sanitizeLine } from "../../lib/format.ts";
+import { ConfirmState } from "../../lib/tui/confirm.ts";
 import { fitRows, formatRange, isCloseKey, ListCursor, navigateList, scrollList } from "../../lib/tui/cursor.ts";
 import { dockListFrame, editorTheme, screenHint, type ViewportRowsSource } from "../../lib/tui/chrome.ts";
 import { clip } from "../../lib/tui/columns.ts";
@@ -91,8 +92,8 @@ export class MemoryPickerComponent implements Component {
 	private mergePair: { first: Note; second: Note } | undefined;
 	/** The note marked with `m`, awaiting a second `m` to merge into it. */
 	private mergeSource: Note | undefined;
-	/** Note awaiting a y/N forget confirmation. */
-	private confirm: Note | undefined;
+	/** The y/N forget confirmation, shared with the other destructive screens. */
+	private readonly confirm = new ConfirmState();
 	/** Transient feedback shown in place of the hint. */
 	private notice: string | undefined;
 	private componentFocused = false;
@@ -355,17 +356,7 @@ export class MemoryPickerComponent implements Component {
 	}
 
 	private handleConfirm(data: string): void {
-		const note = this.confirm;
-		if (!note) return;
-		if (data === "y" || data === "Y" || matchesKey(data, Key.enter)) {
-			this.confirm = undefined;
-			this.forgetNote(note);
-			return;
-		}
-		if (data === "n" || data === "N" || isCloseKey(data) || data === "q") {
-			this.confirm = undefined;
-			this.requestRender();
-		}
+		if (this.confirm.resolve(data) !== undefined) this.requestRender();
 	}
 
 	handleInput(data: string): void {
@@ -378,7 +369,7 @@ export class MemoryPickerComponent implements Component {
 			this.requestRender();
 			return;
 		}
-		if (this.confirm) {
+		if (this.confirm.pending) {
 			this.handleConfirm(data);
 			return;
 		}
@@ -417,14 +408,14 @@ export class MemoryPickerComponent implements Component {
 		else if (data === "p") this.moveNote(focused);
 		else if (data === "d") {
 			if (!focused) return;
-			this.confirm = focused;
+			this.confirm.ask(this.confirmPrompt(focused), () => this.forgetNote(focused));
 			this.requestRender();
 		} else if (data === "r") this.reload();
 	}
 
 	/** Wheel scrolling moves the selection, matching the other list screens. */
 	handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
-		if (this.mode !== "list" || this.confirm) return undefined;
+		if (this.mode !== "list" || this.confirm.pending) return undefined;
 		const notes = this.notes();
 		const handled = scrollList(event, this.cursor, notes.length);
 		if (handled) this.selectedKey = notes[this.cursor.selected] ? noteKey(notes[this.cursor.selected]) : undefined;
@@ -472,9 +463,7 @@ export class MemoryPickerComponent implements Component {
 		});
 	}
 
-	private confirmPrompt(): string {
-		const note = this.confirm;
-		if (!note) return "";
+	private confirmPrompt(note: Note): string {
 		const label = sanitizeLine(note.text);
 		const clipped = label.length > 40 ? `${label.slice(0, 39)}…` : label;
 		return `Forget ${scopeLabel(note.scope)} note "${clipped}"? y/N`;
@@ -519,17 +508,18 @@ export class MemoryPickerComponent implements Component {
 			}
 		}
 
-		const hint = this.confirm
-			? clip(`  ${paint(this.theme, "warn", this.confirmPrompt())}`, w)
+		const pending = this.confirm.pending;
+		const hint = pending
+			? clip(`  ${paint(this.theme, "warn", pending.prompt)}`, w)
 			: this.notice !== undefined
 				? clip(`  ${paint(this.theme, "meta", this.notice)}`, w)
 				: this.mergeSource
 					? screenHint(this.theme, w, ["m merge into the focused note", "Esc cancel merge", "↑/↓"])
 					: screenHint(this.theme, w, [
 							"Esc close",
-							"Enter/e edit",
-							"a add",
-							"d forget",
+							{ text: "Enter/e edit", color: "accent" },
+							{ text: "a add", color: "accent" },
+							{ text: "d forget", color: "warning" },
 							"m merge",
 							"p move",
 							"s/Tab scope",

package/extensions/plan/README.md

@@ -38,6 +38,12 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
   and `ls` tools.
 - **Model entry point.** The model can call `enter_plan_mode` to ask for plan
   mode before a non-trivial task; the user confirms.
+- **AGENTS.md bootstrap.** The packaged `init` skill (`/skill:init`) enters plan
+  mode, reconnoiters the repository, runs one built-in interview of at
+  most four questions, creates or updates `AGENTS.md`, gates the draft through a
+  quality checklist, and writes only after plan approval. It supports existing and
+  empty repositories, and falls back to evidence with recorded assumptions when
+  the interview is unavailable or cancelled; it never invents commands.
 - **Plan files.** The model saves the plan with `write_plan`; the file lands in
   `<repo-root>/.pi/plans/<YYYY-MM-DD-HHmm>-<slug>.md` (or `<agent-dir>/plans`
   outside a repository). The plans directory is self-ignoring, so plan files
@@ -66,8 +72,9 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
   or a `/tree` restore marks only what changed on its own branch.
 - **Kept current.** After approval, `set_plan_steps` flips the checkboxes of
   the steps you name in the file, so the plan mirrors what has actually been
-  done. Pass the step's text as `expected` and an update whose step number moved
-  is refused instead of ticking the wrong line.
+  done, and ticks the todo item approval seeded from that step with it, so the
+  widget and the plan do not drift apart. Pass the step's text as `expected` and
+  an update whose step number moved is refused instead of ticking the wrong line.
 - **Reviewable plan.** `exit_plan_mode` reads the plan file back and presents
   it for approval. The user approves, keeps planning, or asks for a refinement.
   On a remote turn (WeChat) the plan file is sent first, then a digest of its
@@ -98,11 +105,16 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
   against the 50-step cap. A plan without a `Steps` heading keeps the older rule —
   the shallowest list in the document — so prose bullets in a plan that follows the
   outline never become todos, and its verification bullets are already covered.
-- **Goal-aware.** While planning, the injected context restates an active
+  Each seeded item is matched back to its step by text, so ticking a step with
+  `set_plan_steps` completes the item too.
+- **Goal-aware.** While planning, the injected context restates a pursued
   session goal as one bullet, so the plan is designed against the objective
-  instead of beside it. On approval, when the session has no goal at all, the user
-  is offered one confirm to record the plan's title as the goal — never replacing
-  an existing goal, and with no extra model call.
+  instead of beside it. On approval, a goal the goal workflow left as a draft
+  (`planning`) is finalized from the plan's own `## Goal` section — falling back
+  to the title — through the `goal` tool, with no extra dialog, because approving
+  the plan *is* the decision. A session with no goal at all gets one confirm to
+  record the same objective, and an `active` or `achieved` goal is never
+  rewritten: a final objective is the user's. No path spends a model turn.
 - **Branch-aware.** The enabled flag and the review baseline are custom session
   entries, so `/resume` and `/tree` restore the right mode and keep the
   changed-section markers.
@@ -114,7 +126,7 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
 | `enter_plan_mode` | normal mode | Ask to enter plan mode; empty schema, confirmed with `ctx.ui.confirm`. |
 | `write_plan` | plan mode | Save the plan: `title` (file-name slug), `content` (full markdown in the documented outline), optional `plan_path` to overwrite a refinement. Returns the absolute path. A plan with more than 50 top-level steps in its `Steps` section is refused, with the cap and the fix named, and nothing is written. |
 | `exit_plan_mode` | plan mode | Read the plan file (`plan_path`) and present it for approval. Refuses a file whose step list is over the cap, before the review screen. |
-| `set_plan_steps` | normal mode | Keep an approved plan current: set the checkboxes of the given top-level steps (`updates`, each a 1-based `step` in the order `exit_plan_mode` listed, plus `status`, and optionally `expected` — the step's text, so a reordered plan is refused) to `pending` or `completed` in one write. Only the checkboxes change, and a reopened step drops its `[DONE:n]` marker. |
+| `set_plan_steps` | normal mode | Keep an approved plan current: set the checkboxes of the given top-level steps (`updates`, each a 1-based `step` in the order `exit_plan_mode` listed, plus `status`, and `expected` — the step's text, so a reordered plan is refused) to `pending` or `completed` in one write. Only the checkboxes change, and a reopened step drops its `[DONE:n]` marker. The todo item approval seeded from a step is ticked with it: the file is written first and is authoritative, a renamed item is left alone, and a failed todo write is reported in the result. |
 
 ### Commands and flags
 
@@ -125,6 +137,7 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
 | `/plan <prompt>` | the user, with the task | immediate |
 | `/plan list` | the user, browsing the plans directory | immediate |
 | `/plan review [path]` | the user, reviewing a plan in the browser | immediate |
+| `/skill:init` | the user, creating or updating `AGENTS.md` | enters plan mode; write waits for plan approval |
 | `Ctrl+Alt+P` | the user | immediate |
 | `--plan` | the user, at launch | immediate |
 
@@ -139,8 +152,8 @@ already runs read-only:
 `/plan <prompt>` never disables plan mode; only the argument-less `/plan` (or
 `Ctrl+Alt+P`) toggles. Because slash commands go through Pi directly, `/plan` is
 the toggle that works in every terminal (for example Zed's integrated terminal,
-which does not forward `Ctrl+Alt+P`). The footer shows `⋮ plan` while plan mode
-is on, and `⋮ plan · <plan-file>` once the model has written a plan.
+which does not forward `Ctrl+Alt+P`). The footer shows `≡ plan` while plan mode
+is on, and `≡ plan · <plan-file>` once the model has written a plan.
 
 `/plan review` is the one reserved subcommand. Bare `/plan review` reviews the
 plan this session wrote, or, in a later session, the newest plan file in the
@@ -149,6 +162,45 @@ with a separator) reviews that plan. A line that merely starts with the word —
 `review the auth flow` — is still treated as a planning task, so the subcommand
 never swallows one.
 
+### `/skill:init`
+
+`/skill:init` loads the packaged `init` skill. The skill enters plan mode itself
+when it is not active, then decides what to do; nothing is written before
+approval. Its workflow is:
+
+```text
+/skill:init
+  └─> plan mode (read-only)
+        └─> recon: manifests, docs, CI, tests, existing instructions
+        └─> interview: built-in bank, one call of at most 4 questions
+              ├─ answered ───────────────> reconcile with evidence
+              └─ unavailable/cancelled ──> evidence + assumptions
+        └─> draft: new file, exact edits, or an honest no-op
+        └─> quality gate
+        └─> write_plan ──> exit_plan_mode
+                             ├─ not approved ──> refine the same plan
+                             └─ approved ──────> write/edit AGENTS.md
+                                                 └─ read back + quality checklist
+```
+
+The interview comes from a built-in bank in
+[`skills/init/references/interview-questions.md`](../../skills/init/references/interview-questions.md):
+core questions cover purpose, verification, non-obvious rules, isolation,
+completion, sensitive paths, and dependency or network limits, with state-specific
+entries for an existing file, an empty repository, and related instruction files.
+The first call uses a deterministic four-question set for the repository state;
+a second call is allowed only for a material ambiguity. If the tool is inactive,
+there is no UI, or the user cancels, the skill records the gaps as assumptions
+and continues from repository evidence.
+
+The quality reference is
+[`skills/init/references/agents-md-quality.md`](../../skills/init/references/agents-md-quality.md).
+An existing `AGENTS.md` is reviewed and updated only after approval, an accurate
+file can produce a no-op plan, and an empty repository gets only known facts.
+The skill needs the plan extension for its review gate. It also ships with the
+package, so load the whole package (`pi -e .`) or install it; loading only
+`./extensions/plan` leaves `/skill:init` unavailable.
+
 ## Behaviour by mode
 
 The review screen is TUI-only. `exit_plan_mode` opens `PlanViewComponent`: a
@@ -311,6 +363,18 @@ agent file that overrides it.
 - `readOnly` is also a normal `subagent` parameter; outside plan mode a caller
   may set it to run any agent read-only on purpose.
 
+## Review screen
+
+<img src="../../assets/plan.png" alt="The terminal plan review: a Plan Review title rule, a notice that one section changed since the last review, the plan body with its headings and ◼/◻ task checkboxes, a scroll gauge naming the current section and the visible line range, and the Esc/a/r/w, scroll, and section-jump hints" width="100%">
+
+`exit_plan_mode` opens this screen on the plan file it just wrote. The body is
+Pi's Markdown renderer with the active theme, so headings, lists, code, and
+links read as they do in the transcript; the checkboxes in `Steps` use the
+shared `◼`/`◻` vocabulary. A plan taller than the terminal scrolls under a gauge
+that names the section at the top of the viewport and the line range it shows,
+and the footer lists only the keys that apply. `Esc` keeps planning, `a` approves
+and runs, `r` refines inline, and `w` opens the browser review below.
+
 ## Browser review
 
 <img src="../../assets/plan-review.png" alt="The browser-based plan review: a sticky header with the plan title, a status chip, and the Approve & run, Save feedback, and Back to Pi actions, a side panel with step progress and a section outline, and the plan as one measured column with a comment rail and an inline review thread" width="100%">
@@ -414,6 +478,9 @@ file and returns them to the model.
   dropped. A step longer than 200 characters is shortened in the todo list and
   the approval listing — a display rule only, because the plan file always keeps
   the full text.
+- The todo item for a step is matched by its text. An item renamed after
+  approval no longer matches, so `set_plan_steps` leaves it alone and says so in
+  its result; the plan file is still updated.
 - Browser review needs a local browser: the server is loopback-only, so a remote
   turn cannot drive it.
 - A browser that never connects leaves the review waiting until the user
@@ -435,13 +502,23 @@ file and returns them to the model.
 | Integration point | How |
 |---|---|
 | Tools | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, and `set_plan_steps` registered with `executionMode: "sequential"`. `enter_plan_mode` is active normally with `readOnlyHint: true`; `write_plan` (`readOnlyHint: false`) and `exit_plan_mode` (`readOnlyHint: true`) are `defaultActive: false`. `set_plan_steps` is active normally (`readOnlyHint: false`, `idempotentHint: true`); the read-only policy default-denies it in plan mode. Each returns typed `details` (`EnterPlanModeDetails`, `WritePlanDetails`, `ExitPlanModeDetails`, `SetPlanStepsDetails`), and `ExitPlanModeDetails` carries the review's `annotations` when a browser approval or save supplied comments; no `outputSchema`/`structuredContent`. |
-| Commands and flags | `/plan` (toggle, or enter and send a task), `/plan list` (plans index), `/plan review [path]` (browser review), `--plan` launch flag, `Ctrl+Alt+P` shortcut. |
-| State | Enabled flag and the tools it hid persisted with `pi.appendEntry("plan-mode", { enabled, removed })`, and each review's baseline persisted with `pi.appendEntry("plan-baseline", { path, sections })` as one digest per heading section; both rebuilt from `ctx.sessionManager.getBranch()`, so `/resume` and `/tree` restore the mode and the changed markers of the branch they land on. Plan never writes a goal itself: an approval offer records one through `ctx.executeTool("goal", { objective })`. A review that shows the same content appends nothing. The last plan path lives in runtime memory for the footer chip, and a bare `/plan review` falls back to the newest plan file in the directory. |
-| Hooks | `tool_call` blocks non-read-only calls and forces `subagent` read-only; `before_agent_start` injects the hidden `[PLAN MODE ACTIVE]` context, with an active session goal read from the branch through `lib/goal-state.ts`; `context` keeps only the newest plan context while enabled and drops stale ones otherwise. |
+| Commands and flags | `/plan` (toggle, or enter and send a task), `/plan list` (plans index), `/plan review [path]` (browser review), `/skill:init` (skill-backed `AGENTS.md` bootstrap), `--plan` launch flag, `Ctrl+Alt+P` shortcut. |
+| State | Enabled flag and the tools it hid persisted with `pi.appendEntry("plan-mode", { enabled, removed })`, and each review's baseline persisted with `pi.appendEntry("plan-baseline", { path, sections })` as one digest per heading section; both rebuilt from `ctx.sessionManager.getBranch()`, so `/resume` and `/tree` restore the mode and the changed markers of the branch they land on. Plan writes a goal only at approval, through `ctx.executeTool("goal", { objective })`: a `planning` goal is promoted to the plan's `## Goal`, a session with none is offered one, and an `active`/`achieved` goal is left alone. A review that shows the same content appends nothing. The last plan path lives in runtime memory for the footer chip, and a bare `/plan review` falls back to the newest plan file in the directory. |
+| Entry requests | `pi.events` channel `PLAN_ENTER_REQUEST` from `lib/plan-entry.ts`: the `goal` workflow asks, with the shared consent sentence, and plan enables the mode on the caller's context without a second dialog. Subscribed on `session_start`, released on `session_shutdown`. |
+| Hooks | `tool_call` blocks non-read-only calls and forces `subagent` read-only; `before_agent_start` injects the hidden `[PLAN MODE ACTIVE]` context, with a pursued session goal read from the branch through `lib/goal-state.ts`; `context` keeps only the newest plan context while enabled and drops stale ones otherwise. |
 | Lifecycle | `session_start`/`session_tree` restore state; `session_shutdown` clears the footer status and closes any browser review server. |
 
 ## Design notes
 
+- **Consent is one dialog, whichever extension asks.** The goal workflow offers
+  plan mode as a phase of the goal, but a command context cannot call
+  `enter_plan_mode` (`ExtensionCommandContext` has no `executeTool`). So the
+  consent sentence left `policy.ts` for `lib/plan-entry.ts`, and the entry itself
+  is a `pi.events` request: the asker shows the question, plan enables silently
+  with the asker's context. `enter_plan_mode` keeps its own confirm, using the
+  same sentence, so the model-initiated path is unchanged and the two texts
+  cannot drift. A request that nobody answers resolves `false` rather than
+  hanging, so `goal` loaded alone still works.
 - **One review loop owns the human gate.** `review.ts` asks however the session
   is attached — TUI screen, dialog plus editor, remote file plus digest, or
   browser — and returns one `ReviewDecision`, so `exit_plan_mode` and
@@ -476,6 +553,13 @@ file and returns them to the model.
   channel; no import from that extension) and the steps are merged into them.
   A rejected seed reports the nested tool's own reason in the approval message
   instead of failing silently.
+- **Ticking a step ticks its item, through the same channel.** The seed's text is
+  the step's text (`PlanStep.content`, already elided for a long step), so the
+  mirror matches on that text and changes only `status`: an item the user
+  renamed is left alone and reported as unmatched rather than overwritten, and a
+  repeated call writes nothing. The file is written first and stays
+  authoritative, so a failed nested write is reported in the result text — once
+  one artifact has changed there is no previous state to hand back.
 - **A cap is enforced where it can still be fixed.** Both refusal points —
   `write_plan` and `exit_plan_mode` — sit before the write and before the review,
   because those are the moments the model can still regroup the steps. A note on
@@ -504,7 +588,7 @@ file and returns them to the model.
   (`isContainedPlan`), in a single all-or-nothing write — refusing every entry
   if any step is out of range or an entry's `expected` text no longer matches —
   and refuses while plan mode is on, so the read-only guarantee and the path
-  backstop are unchanged. The optional `expected` is what makes an ordinal safe:
+  backstop are unchanged. A required `expected` is what makes an ordinal safe:
   a plan edited between approval and ticking is caught instead of silently
   marking the step that moved into that number.
 - **Direction: enforce capabilities at the tool boundary.** (1) A shared
@@ -543,24 +627,28 @@ file and returns them to the model.
 | `git-bash.ts` | `checkReadOnlyGit`: the pure allowlist that restricts `bash` to read-only git commands. |
 | `plans.ts` | Plan-file store: slug/stamp naming, directory resolution, containment, atomic `write`/`setSteps`/`saveFeedback`, and `read`/`latest`. |
 | `todos.ts` | Approval-time todo merge (pure): the last list replayed from the branch, and the merge of the plan's steps into it with the cap respected. |
-| `steps.ts` | Plan-document structure (pure): the outline, step extraction and the `Steps`-section scope, heading sections, and the checkbox edit. |
+| `steps.ts` | Plan-document structure (pure): the outline, step extraction and the `Steps`-section scope, heading sections, the plan's own goal (`goalSection`), and the checkbox edit. |
+| `format.ts` | Pure result/approval text: the plan preview, the step-cap diagnosis, step labels, the merge summary, and the verification note. |
 | `plan-text.ts` | The plan text a review shows and compares: `sanitizePlanText`, the one normalization both sides use, the per-section `sectionDigests`, and `changedSections`. |
 | `runtime.ts` | Enabled state, tool gating, persistence (mode and review baseline), control-tool identity, footer status. |
-| `tools.ts` | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, and `set_plan_steps`: schemas, results, transcripts, and the approval-time todo seed. |
+| `tools.ts` | Registration entry: composes the four tool registrations in the order the session sees them. |
+| `tools/` | One module per tool (`enter.ts`, `write.ts`, `exit.ts`, `steps.ts`), plus `todo-seed.ts` (the two nested `todo` writes) and `nested.ts` (reading a nested result). |
 | `review.ts` | The review gate: one decision from the TUI screen, a dialog, or the browser, the shared browser lifecycle, and the "mark what was shown" baseline rule. |
 | `commands.ts` | `/plan` (enter, optional task) and the `/plan review [path]` browser subcommand. |
 | `tui.ts` | `PlanViewComponent` (sectioned Markdown body, changed-section summary and marker, section jump, scroll gauge, approve/refine/browser/keep). |
 | `plan-index.ts` | `/plan list`: the notice text and the docked index screen (title, step progress, age, focused path; Enter reviews). |
 | `blocks.ts` | Source-line block model (fence-aware headings, paragraphs, list items, code, quotes, tables, rules, blanks). |
 | `feedback.ts` | Browser-comment codec: `stripFeedback`, `parseFeedback`, `formatFeedback`, `feedbackSummary`, and payload validation. |
-| `web.ts` | `createPlanWebReview`: the loopback server, the section outline (with changed-section flags) and code highlighting, and the save/approve/cancel/abort session. |
-| `web-router.ts` | Pure request handler: token/`Host`/method checks and the review routes. |
+| `web.ts` | `createPlanWebReview`: the review session (SSE close detection, the body cap, settle-after-flush, abort) over the shared loopback bind, writer, and close. |
+| `web-router.ts` | Pure request handler: token/`Host`/method checks and the review routes, over the shared page and JSON header sets. |
 | `web-page.ts` | The review page shell (header, reading progress, review facts, section outline, shortcut sheet), its data island, and inline CSS. |
 | `web-client.ts` | The `/client.js` source (block/thread rendering, the comment rail, outline and facts, inline comments, selection quotes, tables, highlighted code, keyboard nav, save/approve/back). |
 | `path-guard.ts` | Recursive path-argument detection for the read-only backstop. |
 | [`../../lib/browser.ts`](../../lib/browser.ts) | Cross-platform default-browser opener (shared with `file-browse`). |
+| [`../../lib/plan-entry.ts`](../../lib/plan-entry.ts) | Plan-mode entry shared with `goal`: the read-only summary, the consent sentence, and the `pi.events` request `plan` answers by enabling the mode. |
 | [`../../lib/shell.ts`](../../lib/shell.ts) | The shell-escape rule the read-only git guard shares with the worktree isolation guard. |
 | [`../../lib/highlight.ts`](../../lib/highlight.ts) | First-party escape-first syntax tokenizer (shared with `file-browse`). |
-| [`../../lib/web/index.ts`](../../lib/web/index.ts) | Shared Bytefly web brand system: tokens, base rules, `tok-*` colors, layout, the bootstrap, the toggle wiring, and shared markup. |
+| [`../../lib/web/index.ts`](../../lib/web/index.ts) | Shared Bytefly web brand system: tokens, base rules, `tok-*` colors, layout, the bootstrap, the toggle wiring, the shortcut sheet (`keysSheet`, `keysDialogScript`), and shared markup. |
+| [`../../lib/http/index.ts`](../../lib/http/index.ts) | Loopback HTTP layer shared with `file-browse`: the page policy and header sets, `ServeResponse`, the request-envelope helpers, bind/respond/close. |
 | `../../lib/policy.ts` | Shared read-only capability policy (default-deny + `readOnlyHint`). |
 | `../../lib/tui/chrome.ts` | Shared screen header, viewport-row helper, and styled key-hint footer. |

package/extensions/plan/commands.ts

@@ -10,9 +10,9 @@
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isRemoteTurn } from "../../lib/interaction.ts";
+import { READ_ONLY_SUMMARY } from "../../lib/plan-entry.ts";
 import { feedbackSummary } from "./feedback.ts";
 import { PlanIndexComponent, formatPlanIndex } from "./plan-index.ts";
-import { READ_ONLY_SUMMARY } from "./policy.ts";
 import { runBrowserReview } from "./review.ts";
 import type { PlanRuntime } from "./runtime.ts";
 import type { PlanSummary } from "./plans.ts";
@@ -28,6 +28,13 @@ export function planModeNotice(enabled: boolean): string {
 	return enabled ? ENABLED_NOTICE : DISABLED_NOTICE;
 }
 
+/** Enter plan mode when needed, with the same notice `/plan <task>` shows. */
+function ensurePlanMode(runtime: PlanRuntime, ctx: ExtensionContext): void {
+	if (runtime.isEnabled()) return;
+	runtime.enable(ctx);
+	ctx.ui.notify(ENABLED_NOTICE, "info");
+}
+
 /** The plan path a `/plan review` line names, or undefined to review the newest plan. */
 function reviewTarget(args: string): string | undefined {
 	const target = args.slice(REVIEW_PREFIX.length).trim();
@@ -189,10 +196,7 @@ export function registerCommands(
 			}
 
 			// A task always means "plan this": enter if needed, then send.
-			if (!runtime.isEnabled()) {
-				runtime.enable(ctx);
-				ctx.ui.notify(ENABLED_NOTICE, "info");
-			}
+			ensurePlanMode(runtime, ctx);
 			if (ctx.isIdle()) await pi.sendUserMessage(prompt);
 			else await pi.sendUserMessage(prompt, { deliverAs: "followUp" });
 		},

package/extensions/plan/format.ts

@@ -0,0 +1,87 @@
+/**
+ * Pure text for the plan tools' results and approval message.
+ *
+ * No host calls and no theme: the registrations in `tools/` use these to keep
+ * the cap diagnosis, the preview, and the merge summary in one place.
+ */
+
+import { SET_PLAN_STEPS_TOOL } from "./runtime.ts";
+import { MAX_STEP_LENGTH, MAX_STEPS, type PlanStep, type StepUpdate } from "./steps.ts";
+import type { TodoMerge } from "./todos.ts";
+
+/** Lines of plan shown in an unexpanded result. */
+const PREVIEW_LINES = 8;
+
+/** The collapsed view of a plan body and how many lines it hid. */
+export function preview(plan: string): { body: string; more: number } {
+	const lines = plan.split("\n");
+	if (lines.length <= PREVIEW_LINES) return { body: plan, more: 0 };
+	return { body: lines.slice(0, PREVIEW_LINES).join("\n"), more: lines.length - PREVIEW_LINES };
+}
+
+/**
+ * One sentence when a step is longer than the display cap. The text stays in the
+ * plan file either way; only the todo list and the approval listing shorten it.
+ */
+export function stepElisionNote(elided: number): string {
+	if (elided === 0) return "";
+	const plural = elided === 1 ? " is" : "s are";
+	return ` Note: ${elided} step${plural} longer than ${MAX_STEP_LENGTH} characters and will be shortened in the todo list.`;
+}
+
+/**
+ * The diagnosis both cap refusals share: a step list longer than approval can
+ * track. Each caller appends the fix that is available from where it stands.
+ */
+export function overCap(total: number): string {
+	return `The plan has ${total} top-level steps but approval tracks at most ${MAX_STEPS}.`;
+}
+
+/** "Step 2" or "Steps 1, 2" for a set of step numbers. */
+export function stepLabel(steps: number[]): string {
+	return `${steps.length === 1 ? "Step" : "Steps"} ${steps.join(", ")}`;
+}
+
+/** "Steps 1, 2 completed; step 3 reopened" for the tool's text result. */
+export function describeUpdates(updates: StepUpdate[]): string {
+	const completed = updates.filter((update) => update.status === "completed").map((update) => update.step);
+	const pending = updates.filter((update) => update.status === "pending").map((update) => update.step);
+	const parts: string[] = [];
+	if (completed.length > 0) parts.push(`${stepLabel(completed)} completed`);
+	if (pending.length > 0) parts.push(`${stepLabel(pending)} reopened`);
+	return parts.join("; ");
+}
+
+/**
+ * One sentence about the plan's verification item, or "" when the plan has none
+ * (or it was already in the list). The item is a todo, not a plan step, so it is
+ * ticked in the list rather than in the file.
+ */
+export function verificationNote(merged: TodoMerge | undefined): string {
+	if (merged?.trailing === "added") {
+		return "\nThe plan's verification section is the last todo item; tick it in the todo list, not in the file.";
+	}
+	if (merged?.trailing === "deferred") {
+		return "\nThe plan's verification section did not fit in the full todo list; keep it in mind.";
+	}
+	return "";
+}
+
+/** What the merge did, for the approval message; `steps` is the plan's step count. */
+export function mergeSummary(merged: TodoMerge, steps: PlanStep[]): string {
+	const total = steps.length;
+	const counted = `${merged.added + merged.skipped} of ${total} plan step${total === 1 ? "" : "s"}`;
+	const notes = [
+		merged.skipped > 0 ? `${merged.skipped} already present` : "",
+		merged.kept > 0 ? `${merged.kept} existing kept` : "",
+		merged.deferred > 0 ? `${merged.deferred} deferred, list full` : "",
+	].filter(Boolean);
+	const suffix = notes.length > 0 ? ` (${notes.join(", ")})` : "";
+	const tick = `Tick each one off in the file with ${SET_PLAN_STEPS_TOOL} as you finish it, passing the step's text as \`expected\`.`;
+	if (merged.added === 0 && merged.skipped === 0) {
+		return ` The todo list is full, so no plan steps were added${suffix}. Keep these steps in mind. ${tick}`;
+	}
+	if (merged.added === 0)
+		return ` ${total === 1 ? "The plan's step is" : "Every plan step is"} already in the todo list${suffix}. ${tick}`;
+	return ` Merged ${counted} into the todo list${suffix}. ${tick}`;
+}

package/extensions/plan/index.ts

@@ -22,19 +22,14 @@ import { fileURLToPath } from "node:url";
 import { hasPathInput } from "./path-guard.ts";
 import { isExtensionEnabled } from "../../lib/env.ts";
 import { sanitizeLine } from "../../lib/format.ts";
-import { lastGoal, type PublishedGoal } from "../../lib/goal-state.ts";
+import { lastGoal, isPursuedGoal, type PublishedGoal } from "../../lib/goal-state.ts";
+import { READ_ONLY_SUMMARY, PLAN_ENTER_REQUEST, type PlanEnterRequest } from "../../lib/plan-entry.ts";
 import { ASK_USER_QUESTION_TOOL, SUBAGENT_READ_ONLY_PARAM, SUBAGENT_TOOL } from "../../lib/tool-names.ts";
 import { clip } from "../../lib/tui/columns.ts";
 import { STATUS_KEYS } from "../../lib/tui/glyphs.ts";
 import { planModeNotice, registerCommands } from "./commands.ts";
 import { checkReadOnlyGit } from "./git-bash.ts";
-import {
-	createPlanPolicy,
-	BASH_BLOCKED_GUIDANCE,
-	BLOCKED_GUIDANCE,
-	PLAN_SAFE_TOOLS,
-	READ_ONLY_SUMMARY,
-} from "./policy.ts";
+import { createPlanPolicy, BASH_BLOCKED_GUIDANCE, BLOCKED_GUIDANCE, PLAN_SAFE_TOOLS } from "./policy.ts";
 import { createPlanRuntime } from "./runtime.ts";
 import { registerTools } from "./tools.ts";
 import { createPlanWebReview } from "./web.ts";
@@ -51,21 +46,20 @@ const GOAL_CONTEXT_CHARS = 64;
 
 /**
  * Injected each turn while planning: the facts and the next action, not the tool
- * contracts. An active session goal becomes one extra bullet, so a plan is
- * designed against the objective instead of beside it.
+ * contracts. A pursued session goal — being planned or already final — becomes one
+ * extra bullet, so a plan is designed against the objective instead of beside it.
  */
 export function planModeContext(goal?: PublishedGoal | null): string {
 	const lines = [
 		PLAN_MODE_MARKER,
-		"You are in plan mode: read-only exploration for safe code analysis.",
 		"",
 		`- Do not modify anything except the plan file: while planning, ${READ_ONLY_SUMMARY}.`,
-		"- bash is git-only: read-only commands (git status, git diff, git log) may be chained with && or ;, but pipes, substitution, and redirection are blocked and powershell is unavailable. The cwd is already the project root, so do not prefix commands with cd; use read, grep, find, and ls for files.",
+		"- bash is git-only: read-only git commands chain with && or ; — no pipes, redirection, or substitution, and no powershell. The cwd is already the project root, so skip cd, and read files with read, grep, find, and ls.",
 		"- Investigate and design a concrete plan, then save it with write_plan and call exit_plan_mode with the returned plan_path for approval.",
-		"- Delegate broad exploration with subagent; while planning it is forced read-only.",
+		"- Delegate broad exploration with subagent.",
 		`- To choose between approaches, ask with ${ASK_USER_QUESTION_TOOL} before finalizing.`,
 	];
-	if (goal?.status === "active") {
+	if (goal && isPursuedGoal(goal)) {
 		lines.push(`- Current session goal: ${clip(sanitizeLine(goal.objective), GOAL_CONTEXT_CHARS)}`);
 	}
 	return lines.join("\n");
@@ -109,10 +103,32 @@ export default function planMode(pi: ExtensionAPI): void {
 		},
 	});
 
-	pi.on("session_start", (_event, ctx) => runtime.restore(ctx));
+	// Another extension that offers plan mode (the goal workflow) asks on this
+	// channel instead of calling a tool it cannot reach from a command context. It
+	// owns the user's answer; enabling here must therefore not ask again.
+	const unsubscribes: Array<() => void> = [];
+	const listenForEntryRequests = (): void => {
+		for (const unsubscribe of unsubscribes) unsubscribe();
+		unsubscribes.length = 0;
+		unsubscribes.push(
+			pi.events.on(PLAN_ENTER_REQUEST, (data) => {
+				const request = data as Partial<PlanEnterRequest> | undefined;
+				if (!request?.ctx || typeof request.respond !== "function") return;
+				if (!runtime.isEnabled()) runtime.enable(request.ctx);
+				request.respond(true);
+			}),
+		);
+	};
+
+	pi.on("session_start", (_event, ctx) => {
+		listenForEntryRequests();
+		runtime.restore(ctx);
+	});
 	pi.on("session_tree", (_event, ctx) => runtime.restore(ctx));
 	pi.on("session_shutdown", async (_event, ctx) => {
 		await web.closeAll();
+		for (const unsubscribe of unsubscribes) unsubscribe();
+		unsubscribes.length = 0;
 		ctx.ui.setStatus(STATUS_KEYS.planMode, undefined);
 	});
 

package/extensions/plan/plans.ts

@@ -292,10 +292,9 @@ export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date }
 			const range = total === 0 ? "it has no steps" : `valid steps are 1 to ${total}`;
 			throw new Error(`Step ${outOfRange.step} is out of range; ${range}.`);
 		}
-		// A caller-supplied text is the guard against a reordered plan: refuse the
-		// whole batch rather than tick the step that moved into that number.
+		// The expected text is the guard against a reordered plan: refuse the whole
+		// batch rather than tick the step that moved into that number.
 		const stale = updates.find((update) => {
-			if (update.expected === undefined) return false;
 			const step = steps[update.step - 1];
 			return step === undefined || !matchesStepText(step.content, update.expected);
 		});

package/extensions/plan/policy.ts

@@ -46,12 +46,6 @@ export const PLAN_ALLOWED_TOOLS = [...PLAN_SAFE_TOOLS, SUBAGENT_TOOL];
 /** Tools always blocked while planning, even when annotated read-only. */
 const ALWAYS_BLOCKED_TOOLS = ["write", "edit", ENTER_TOOL];
 
-/** One-clause description of the read-only guarantee, reused across prompts. */
-export const READ_ONLY_SUMMARY =
-	"write and edit are disabled, bash is limited to read-only git commands, and other mutating tools are blocked; " +
-	"subagent delegation is forced read-only, and the only file write is write_plan (under .pi/plans, or the agent " +
-	"directory outside a repository)";
-
 /** Shown when a tool call is refused while planning. */
 export const BLOCKED_GUIDANCE = "Call exit_plan_mode and get approval before using it.";
 

package/extensions/plan/runtime.ts

@@ -21,7 +21,9 @@ import { realpathSync } from "node:fs";
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 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 { GLYPHS, STATUS_KEYS } from "../../lib/tui/glyphs.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import { createPlanStore, type PlanStore } from "./plans.ts";
@@ -31,13 +33,13 @@ import type { PlanModeEntry, ReviewBaselineEntry } 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 ask to enter plan mode. */
-export const ENTER_TOOL = "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";
 /** Custom-entry type used for plan-mode state. */
-export const STATE_TYPE = "plan-mode";
+export const STATE_TYPE = PLAN_MODE_ENTRY_TYPE;
 /** Custom-entry type used for a plan's review baseline. */
 export const BASELINE_TYPE = "plan-baseline";