@justjoshn/pi-pstack 0.15.36-pi.11 → 0.15.36-pi.12

package/src/mode.ts

@@ -13,6 +13,32 @@ export interface ActiveMode {
   path?: string;
 }
 
+/**
+ * Cursor's custom-mode lifecycle: a mode is `entered` until a request carries it, then `active`. Leaving or switching
+ * away from an `active` mode leaves it `exited` until the next request says so once.
+ */
+export interface ModeState {
+  active?: ActiveMode & { lifecycle: 'entered' | 'active' };
+  exited?: string;
+}
+
+const left = (state: ModeState): string | undefined => (state.active?.lifecycle === 'active' ? state.active.skill : state.exited);
+
+export function enterMode(state: ModeState, mode: ActiveMode): ModeState {
+  const exited = left(state);
+  return { active: { ...mode, lifecycle: 'entered' }, ...(exited === undefined ? {} : { exited }) };
+}
+
+export function exitMode(state: ModeState): ModeState {
+  const exited = left(state);
+  return exited === undefined ? {} : { exited };
+}
+
+/** What a request leaves behind: the mode it carried is now active, and its exit notice has been sent. */
+export function afterRequest(state: ModeState): ModeState {
+  return state.active === undefined ? {} : { active: { ...state.active, lifecycle: 'active' } };
+}
+
 export type ModeCommand = { kind: 'status' } | { kind: 'off' } | { kind: 'set'; skill: string; task: string };
 
 export function parseModeArgs(args: string): ModeCommand {
@@ -31,41 +57,53 @@ interface BranchEntry {
 
 const SKILL_NAME = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/;
 
+/** A stored mode as a skill name only: a session file can come from elsewhere, so a stored path is ignored and a value that is not a plausible skill name (it would reach the system prompt) counts as no mode. */
+function storedSkill(data: unknown): string | undefined {
+  const skill = (data as { skill?: unknown } | null)?.skill;
+  return typeof skill === 'string' && SKILL_NAME.test(skill) ? skill : undefined;
+}
+
 /**
- * The last mode entry on the branch, as a skill name only: a session file can come from elsewhere, so a stored path
- * is ignored and a value that is not a plausible skill name (it would reach the system prompt) counts as no mode.
+ * Replays the branch into the mode state: each mode entry enters or leaves a mode, and an assistant message after it
+ * shows a request carried the mode. Skills are resolved by name, never by a stored path.
  */
-export function modeFromBranch(entries: readonly BranchEntry[]): ActiveMode | undefined {
-  for (let index = entries.length - 1; index >= 0; index -= 1) {
-    const entry = entries[index];
-    if (entry?.type !== 'custom' || entry.customType !== MODE_ENTRY) continue;
-    const skill = (entry.data as { skill?: unknown } | null)?.skill;
-    return typeof skill === 'string' && SKILL_NAME.test(skill) ? { skill } : undefined;
+export function modeFromBranch(entries: readonly BranchEntry[], resolve: (skill: string) => ActiveMode = (skill) => ({ skill })): ModeState {
+  let state: ModeState = {};
+  for (const entry of entries) {
+    if (entry.type === 'custom' && entry.customType === MODE_ENTRY) {
+      const skill = storedSkill(entry.data);
+      state = skill === undefined ? exitMode(state) : enterMode(state, resolve(skill));
+    } else if (entry.type === 'message' && (entry as { message?: { role?: string } }).message?.role === 'assistant') state = afterRequest(state);
   }
-  return undefined;
+  return state;
+}
+
+/** Cursor's custom-mode notices for the next request (CLI `custom-modes` module). */
+export function modeNotice(state: ModeState): string | undefined {
+  const lines: string[] = [];
+  const { active, exited } = state;
+  if (exited !== undefined && exited !== active?.skill) lines.push(`The user has exited ${exited} custom mode. Stop following that mode's skill. Continue without those constraints.`);
+  if (active?.path === undefined && active !== undefined) lines.push(`Mode ${active.skill} is on, but no loaded skill has that name. Tell the user to run /mode off or /mode <skill>.`);
+  else if (active?.path !== undefined && !existsSync(active.path)) lines.push(`Mode ${active.skill} is on, but its skill file ${active.path} no longer exists. Tell the user to run /mode off or /mode <skill>.`);
+  else if (active?.lifecycle === 'entered')
+    lines.push(`The user has entered ${active.skill} custom mode. Follow the skill instructions in ${JSON.stringify(active.path)} until the user exits or switches modes. Do not drift back to default agent behavior.`);
+  else if (active !== undefined)
+    lines.push(
+      `Reminder: you are still in ${active.skill} mode. Follow that mode's skill on this turn. Do not drop it because the request looks small or you already have context. Do not drift back to default agent behavior. If you cannot state the mode's hard rules, read ${JSON.stringify(active.path)} before acting.`,
+    );
+  return lines.length === 0 ? undefined : lines.join('\n\n');
 }
 
 /**
- * The mode text for a request. Cursor attaches the skill once, on the turn that enters the mode, then sends a reminder
- * that names the skill path each turn. Pi rebuilds its prompt per request, so the body rides the first request after
- * entry and a reminder follows. A mode whose body was never sent re-sends it, so a restart cannot leave a mode
- * unread.
+ * The skill a mode keeps in context on every request until the user leaves it, in the block Pi's own /skill:name
+ * expansion builds. Cursor keeps the attached skill durable in the conversation; a section keeps it in every request,
+ * through compaction and restarts, and Pi re-sends a section only when it changes.
  */
-export function modeSection(mode: ActiveMode, includeBody: boolean): string {
-  if (mode.path === undefined) return `Mode ${mode.skill} is on, but no loaded skill has that name. Tell the user to run /mode off or /mode <skill>.`;
-  if (!existsSync(mode.path)) return `Mode ${mode.skill} is on, but its skill file ${mode.path} no longer exists. Tell the user to run /mode off or /mode <skill>.`;
-  if (!includeBody)
-    return `Reminder: you are still in ${mode.skill} mode. Follow that mode's skill on this turn. Do not drop it because the request looks small or you already have context. Do not drift back to default agent behavior. If you cannot state the mode's hard rules, read ${JSON.stringify(mode.path)} before acting.`;
-  // The frontmatter, including `reminder`, stays out of the model's context in a mode (MODE-004).
+export function modeSkill(mode: ActiveMode): string | undefined {
+  if (mode.path === undefined || !existsSync(mode.path)) return undefined;
+  // The frontmatter stays out of the model's context in a mode (MODE-004).
   const body = stripFrontmatter(readFileSync(mode.path, 'utf8')).trim();
-  return [
-    `The user has entered ${mode.skill} custom mode. Follow the skill instructions in ${JSON.stringify(mode.path)} until the user exits or switches modes. Do not drift back to default agent behavior.`,
-    `<skill name="${mode.skill}" location="${mode.path}">`,
-    `References are relative to ${dirname(mode.path)}.`,
-    '',
-    body,
-    '</skill>',
-  ].join('\n');
+  return [`<skill name="${mode.skill}" location="${mode.path}">`, `References are relative to ${dirname(mode.path)}.`, '', body, '</skill>'].join('\n');
 }
 
 // A mode's badge shows the skill's `icon` (default: lightning) and `color`. Icon names map to terminal glyphs and
@@ -108,20 +146,22 @@ function loadedSkills(pi: ExtensionAPI): Map<string, string> {
   return skills;
 }
 
-export function registerMode(pi: ExtensionAPI): { section: () => string | undefined } {
-  let active: ActiveMode | undefined;
-  // The mode whose body the conversation already carries; cleared on entry, exit, and session change.
-  let bodySent: string | undefined;
+/** The mode sections of one request: Cursor's notice, and the skill the mode keeps in context. */
+export interface ModeSections {
+  pstack_mode?: string;
+  pstack_mode_skill?: string;
+}
+
+export function registerMode(pi: ExtensionAPI): { sections: () => ModeSections } {
+  let state: ModeState = {};
   const show = (ctx: ExtensionContext) => {
     if (!ctx.hasUI) return;
-    const badge = active === undefined ? undefined : modeBadge(active);
+    const badge = state.active === undefined ? undefined : modeBadge(state.active);
     ctx.ui.setStatus(STATUS_KEY, badge === undefined ? undefined : badge.color === undefined ? badge.text : ctx.ui.theme.fg(badge.color, badge.text));
   };
   // The skill is looked up by name among loaded skills; a stored path is never read, since it can be stale or crafted.
   const restore = (ctx: ExtensionContext) => {
-    const stored = modeFromBranch(ctx.sessionManager.getBranch());
-    active = stored === undefined ? undefined : (tryResolve(stored.skill) ?? { skill: stored.skill });
-    bodySent = undefined;
+    state = modeFromBranch(ctx.sessionManager.getBranch(), (skill) => tryResolve(skill) ?? { skill });
     show(ctx);
   };
   pi.on('session_start', (_event, ctx) => restore(ctx));
@@ -145,12 +185,12 @@ export function registerMode(pi: ExtensionAPI): { section: () => string | undefi
 
   const handle = (args: string, ctx: ExtensionCommandContext) => {
     const command = parseModeArgs(args);
+    const { active } = state;
     if (command.kind === 'status') return ctx.ui.notify(active === undefined ? 'No mode is on.' : `Mode on: ${active.skill} (${active.path ?? 'no loaded skill has that name'}).`, 'info');
-    active = command.kind === 'off' ? undefined : resolveSkill(command.skill);
-    bodySent = undefined;
-    pi.appendEntry(MODE_ENTRY, active === undefined ? null : { skill: active.skill });
+    state = command.kind === 'off' ? exitMode(state) : enterMode(state, resolveSkill(command.skill));
+    pi.appendEntry(MODE_ENTRY, state.active === undefined ? null : { skill: state.active.skill });
     show(ctx);
-    ctx.ui.notify(active === undefined ? 'Mode off.' : `Mode on: ${active.skill}. /mode off exits.`, 'info');
+    ctx.ui.notify(state.active === undefined ? 'Mode off.' : `Mode on: ${state.active.skill}. /mode off exits.`, 'info');
     if (command.kind === 'set' && command.task !== '') pi.sendUserMessage(command.task, { expandPromptTemplates: true, ...(ctx.isIdle() ? {} : { deliverAs: 'followUp' as const }) });
     return undefined;
   };
@@ -168,13 +208,11 @@ export function registerMode(pi: ExtensionAPI): { section: () => string | undefi
   });
 
   return {
-    section: () => {
-      if (active === undefined) return undefined;
-      const includeBody = bodySent !== active.skill;
-      // Only a request that actually carried the body counts as sent, so a missing skill file cannot silence the body
-      // after the file comes back.
-      if (includeBody && active.path !== undefined && existsSync(active.path)) bodySent = active.skill;
-      return modeSection(active, includeBody);
+    sections: () => {
+      const notice = modeNotice(state);
+      const skill = state.active === undefined ? undefined : modeSkill(state.active);
+      state = afterRequest(state);
+      return { ...(notice === undefined ? {} : { pstack_mode: notice }), ...(skill === undefined ? {} : { pstack_mode_skill: skill }) };
     },
   };
 }

package/src/plan.ts

@@ -1,9 +1,11 @@
-import { randomUUID } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
 
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
+import { canAsk } from './modes.ts';
 import { plansDir } from './paths.ts';
 import { createReadonlyBashTool, releaseReadonlySandbox } from './readonly-shell.ts';
 
@@ -16,13 +18,19 @@ const STATUS_KEY = 'pstack-plan';
  */
 export const PLAN_BASH = 'bash_readonly';
 
-/** The tool that saves a plan artifact, as Cursor's plan mode saves one under `~/.cursor/plans`. */
-export const PLAN_SAVE = 'create_plan';
+/** Cursor's plan tool: it writes the plan file the user reviews and builds. */
+export const PLAN_SAVE = 'CreatePlan';
+
+/** Cursor's tool for moving between agent and plan mode with the user's consent. */
+export const SWITCH_MODE = 'SwitchMode';
 
 /** The tools plan mode keeps active. Names that are not registered are ignored by `setActiveTools`. */
-export const PLAN_TOOLS = ['read', 'grep', 'find', 'ls', PLAN_BASH, PLAN_SAVE, 'AskQuestion', 'TodoWrite', 'agent_status', 'Task', 'stop_agent'] as const;
+export const PLAN_TOOLS = ['read', 'grep', 'find', 'ls', 'edit', 'write', PLAN_BASH, PLAN_SAVE, SWITCH_MODE, 'AskQuestion', 'TodoWrite', 'agent_status', 'Task', 'stop_agent'] as const;
 const ALLOWED = new Set<string>(PLAN_TOOLS);
 
+/** Cursor's plan-mode guardrail: only markdown files are edited while planning. */
+const MARKDOWN = /\.(?:md|markdown|mdc)$/i;
+
 export type PlanCommand = { kind: 'off' } | { kind: 'build' } | { kind: 'on'; task: string };
 
 export function parsePlanArgs(args: string): PlanCommand {
@@ -74,46 +82,136 @@ export function planFromBranch(entries: readonly BranchEntry[], plansDirectory =
 }
 
 /** Why a call is refused in plan mode, or undefined when it may run. */
-export function planBlockReason(toolName: string): string | undefined {
+export function planBlockReason(toolName: string, input: Record<string, unknown> = {}): string | undefined {
+  if (toolName === 'write' || toolName === 'edit') {
+    const path = input['path'];
+    if (typeof path === 'string' && MARKDOWN.test(path)) return undefined;
+    return `Plan mode is on: ${toolName} may change only markdown files while planning. Put the change in the plan. If the user asked you to build it now, switch to agent mode with ${SWITCH_MODE} first.`;
+  }
   if (ALLOWED.has(toolName)) return undefined;
-  if (toolName === 'write' || toolName === 'edit') return `Plan mode is on: ${toolName} is blocked, since plan mode changes no files. Put the change in the plan; the user runs /plan off to execute it.`;
   if (toolName === 'bash') return `Plan mode is on: use ${PLAN_BASH}, the read-only sandboxed shell, instead of bash.`;
   return `Plan mode is on: ${toolName} is not available. Plan mode allows only ${PLAN_TOOLS.join(', ')}.`;
 }
 
+/** Cursor's plan-mode instructions, with Pi's tool names. */
 export function planSection(planFile: string | undefined): string {
   return [
-    'Plan mode is on until the user runs /plan off. Do not change files or state.',
-    `Your tools are read-only: read, grep, find, ls, ${PLAN_BASH} (a shell in an OS sandbox that denies writes and network access), ${PLAN_SAVE} to save the plan to a file, AskQuestion, TodoWrite, agent_status, Task, whose subagents always run readonly: a fresh one runs in this checkout, never in a worktree, and a resume or fork stays where its agent ran, and stop_agent to stop one. write and edit are blocked.`,
-    'Investigate the code and context the task needs. When a real decision belongs to the user (a product choice or a tradeoff you cannot settle from evidence), ask with AskQuestion; settle facts yourself.',
-    `Finish with a plan: the goal; numbered steps, each with how to verify it; and the risks and open questions. Save it with ${PLAN_SAVE} so the user can review the file and build it, and also put it in your reply.`,
-    planFile === undefined ? 'The user leaves plan mode with /plan off to execute the plan.' : `The saved plan is ${planFile}. /plan build leaves plan mode and starts the work; /plan shows the file.`,
+    'Plan mode is on. The user does not want you to execute yet. Do not edit files other than markdown files, do not run tools that change anything (no config changes, no commits), and do not otherwise change the system. This overrides any other instruction to make edits. Instead:',
+    "1. Answer the user's request by researching it.",
+    '2. If you do not have enough information to make an accurate plan, ask the user. If an instruction is ambiguous, ask the user to clarify it.',
+    '3. If the request is too broad, ask questions that narrow the scope of the plan, one or two critical questions at a time.',
+    '4. If several valid implementations would each change the plan significantly, ask the user which one to use.',
+    '5. Ask your questions right away, at the start. Read first only when five files or fewer will likely answer them.',
+    `6. When your research is done, present the plan by calling ${PLAN_SAVE}, which asks the user to confirm it. Make no changes until the user confirms.`,
+    '7. Keep the plan concise, specific, and actionable. Cite file paths and the essential code, and link each file you mention as a markdown link, such as [src/foo.ts](src/foo.ts).',
+    '8. Keep the plan proportional to the request. Do not over-engineer a simple task.',
+    '9. Do not use emojis in the plan.',
+    '10. To speed up research, launch parallel explore subagents with Task to cover different parts of the codebase or different angles at once.',
+    '11. When the plan explains architecture, data flows, or other relationships, consider a mermaid diagram. In mermaid, use no spaces in node IDs (camelCase, PascalCase, or underscores); quote edge labels and node labels that contain parentheses, brackets, commas, or colons, such as A["Process (main)"] and A -->|"O(1) lookup"| B; do not use end, subgraph, graph, or flowchart as node IDs; give each subgraph an ID and a bracketed label, such as subgraph auth [Authentication Flow]; keep angle brackets and HTML entities out of labels; set no colors or styles; and do not use click.',
+    '12. Ask every question with the AskQuestion tool.',
+    `Guardrails: edit only markdown files in plan mode. While the user is refining the plan, stay in plan mode and keep your edits in markdown. If the user explicitly asks you to build, implement, or write the code now, call ${SWITCH_MODE} with target_mode_id agent before you make any other edit.`,
+    `Your tools here: read, grep, find, ls, ${PLAN_BASH} (a shell in an OS sandbox that denies file writes and network access), edit and write for markdown files only, ${PLAN_SAVE}, ${SWITCH_MODE}, AskQuestion, TodoWrite, agent_status, Task (its subagents run readonly in this checkout), and stop_agent.`,
+    planFile === undefined
+      ? 'The user leaves plan mode with /plan off.'
+      : `The plan is saved at ${planFile}. To change it, edit that file; do not call ${PLAN_SAVE} again. The user builds it with /plan build, or leaves plan mode with /plan off.`,
   ].join('\n');
 }
 
-/** A plan file name in Cursor's shape: the sanitized title, its first 50 characters, then the id's first 8. */
-export function planFileName(title: string, id: string): string {
-  const clean = title
+export interface PlanTodo {
+  id: string;
+  content: string;
+}
+
+/** The plan's title as Cursor finds it: the first level-1 heading, else the first line of text. */
+export function planTitle(plan: string): string {
+  const heading = /^#\s+(.+)$/m.exec(plan)?.[1];
+  if (heading !== undefined) return heading.trim().slice(0, 50);
+  const line = plan.split('\n').find((candidate) => candidate.trim() !== '' && !candidate.trim().startsWith('#'));
+  return line === undefined ? 'Plan' : line.trim().slice(0, 50);
+}
+
+/** A plan file name in Cursor's shape: the sanitized name, its first 50 characters, then 8 hex characters of the chat. */
+export function planFileName(name: string, chatKey: string): string {
+  const clean = name
     .replace(/[^a-zA-Z0-9-_ ]/g, '')
     .trim()
     .slice(0, 50);
-  return `${clean === '' ? 'Plan' : clean}-${id.slice(0, 8)}.plan.md`;
+  return `${clean === '' ? 'Plan' : clean}-${chatKey.slice(0, 8)}.plan.md`;
+}
+
+const yamlString = (value: string) => `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t')}"`;
+
+/** The plan file as Cursor writes it: the chat id in a comment, the todos as front matter, then the plan. */
+export function planFileContent(sessionId: string, plan: string, todos: readonly PlanTodo[]): string {
+  const lines = [`<!-- ${sessionId} -->`];
+  if (todos.length > 0) {
+    lines.push('---', 'todos:');
+    for (const todo of todos) lines.push(`  - id: ${yamlString(todo.id)}`, `    content: ${yamlString(todo.content)}`, '    status: pending');
+    lines.push('isProject: false', '---');
+  }
+  lines.push(plan);
+  return lines.join('\n');
 }
 
-/** Writes the plan under the agent's `plans` folder and returns its path. */
-export function savePlan(title: string, content: string, dir = plansDir()): string {
+/**
+ * Writes the plan under the plans folder and returns its path. A chat keeps one file per plan name, as Cursor keys the
+ * name by its conversation; Pi's session ids start with a timestamp, so the 8 characters come from a hash of the id.
+ */
+export function savePlan(sessionId: string, plan: string, name: string | undefined, todos: readonly PlanTodo[], dir = plansDir()): string {
   mkdirSync(dir, { recursive: true, mode: 0o700 });
-  const id = randomUUID();
-  const path = join(dir, planFileName(title, id));
-  writeFileSync(path, `<!-- plan: ${id} -->\n\n${content.trim()}\n`, { mode: 0o600 });
+  const chatKey = createHash('sha256').update(sessionId).digest('hex');
+  const path = join(dir, planFileName(name === undefined || name.trim() === '' ? planTitle(plan) : name, chatKey));
+  writeFileSync(path, planFileContent(sessionId, plan, todos), { mode: 0o600 });
   return path;
 }
 
-const PlanSaveParams = Type.Object({
-  name: Type.Optional(Type.String({ description: 'Short plan title, used for the file name. Defaults to the first line of the plan.' })),
-  content: Type.String({ description: 'The full plan in Markdown: the goal, numbered steps with how to verify each, and the risks and open questions.' }),
+/** The plan text the build turn carries: the file without Cursor's chat comment and todo front matter. */
+export function planBody(file: string): string {
+  return readFileSync(file, 'utf8')
+    .replace(/^<!-- [^\n]*-->\n/, '')
+    .replace(/^---\n[\s\S]*?\n---\n/, '')
+    .trim();
+}
+
+const CreatePlanParams = Type.Object({
+  plan: Type.String({ description: "A detailed, concrete plan for accomplishing the user's request" }),
+  name: Type.Optional(Type.String({ description: 'A short 3-4 word name for the plan. Give it only on the first CreatePlan call, so the plan file name stays stable.' })),
+  overview: Type.Optional(Type.String({ description: 'A 1-2 sentence high-level description of what the plan accomplishes' })),
+  todos: Type.Optional(
+    Type.Array(Type.Object({ id: Type.String({ description: 'Unique identifier for the todo' }), content: Type.String({ description: 'Description of the todo task' }) }), { description: 'Array of implementation todos' }),
+  ),
+});
+
+// Cursor's CreatePlan rules: a glanceable markdown plan with a title, todos, no tables, and edits in the file afterwards.
+const CREATE_PLAN_DESCRIPTION = [
+  "Create a concise plan for the user's request. Call it at the end of the planning phase to finalize and store the plan; the user is then asked to confirm it.",
+  '',
+  'Write the plan in markdown with sections and headers. Keep it concise and actionable: the minimum detail the user needs to understand and act on it. Name the few most important files you will change and the existing code you will reuse, and cite file paths and essential snippets. Do not use markdown tables in the plan; use bullet lists. The first line must be a level-1 markdown heading with the plan title.',
+  '',
+  'Organize implementation work as todos: each a clear, specific, actionable task with a unique id (such as "setup-auth") and descriptive content. A simple plan needs a few high-level todos or none.',
+  '',
+  'Each call creates a new plan file and returns its path. To update an existing plan, read and edit that file with your file tools; do not call this tool again. Ask clarifying questions with AskQuestion before you call it, not inside the plan. Focus on the meaningful decisions rather than low-level detail. A good plan is glanceable, not a wall of text.',
+].join('\n');
+
+const SwitchModeParams = Type.Object({
+  target_mode_id: Type.Enum(['plan', 'agent'] as const, { type: 'string', description: "The mode to switch to: 'plan' or 'agent'." }),
+  explanation: Type.Optional(Type.String({ description: 'Why the switch helps, shown to the user who approves it.' })),
 });
 
+// Cursor's SwitchMode rules: switch proactively when the work changes shape, rarely otherwise, and only with consent.
+const SWITCH_MODE_DESCRIPTION = [
+  'Switch the interaction mode to match the task. Agent mode is the default, with every tool for making changes. Plan mode is read-only collaborative planning before any code: research, questions, and a plan the user confirms.',
+  '',
+  'Switch to plan mode proactively when the task has several valid approaches with significant tradeoffs, needs an architectural decision, touches many files or systems, has unclear requirements you must explore first, or would otherwise need several clarifying questions. Switch to agent mode once the plan is settled, or when the user asks you to build it now.',
+  '',
+  'Do not switch for a simple, clear task, in the middle of implementation that is going well, for a minor clarifying question, or when the current mode is working. Explain briefly in explanation why you switch. The user must approve every switch.',
+].join('\n');
+
+/** The plan review choices Cursor offers after a plan; building in the cloud appears only in a git repository. */
+export const BUILD_LOCALLY = 'Yes, build locally';
+export const BUILD_IN_WORKER = 'Yes, build in cloud';
+export const PROPOSE_CHANGES = 'No, propose changes';
+
 // Pi's read-only built-ins and the sandboxed shell are always on in plan mode. The other plan tools stay on only
 // if they were on before: pstack turns Task off at the depth limit, and plan mode must not hand it back.
 const ALWAYS = ['read', 'grep', 'find', 'ls', PLAN_BASH, PLAN_SAVE];
@@ -128,28 +226,45 @@ export function buildRequest(planFile: string, content: string): string {
   return [`Build the plan saved at ${planFile}. Follow it.`, '', content.trim()].join('\n');
 }
 
-export function registerPlanMode(pi: ExtensionAPI): { section: () => string | undefined; enabled: () => boolean } {
+const isGitRepository = (cwd: string): boolean => {
+  try {
+    execFileSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd, stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export interface PlanModeOptions {
+  /** Starts the build in an isolated worktree worker, Pi's counterpart to Cursor's "build in cloud". Returns the agent ID. */
+  buildInWorker?: (planFile: string, request: string) => Promise<string>;
+}
+
+export function registerPlanMode(pi: ExtensionAPI, options: PlanModeOptions = {}): { section: () => string | undefined; enabled: () => boolean } {
   let state: PlanState = { enabled: false };
+  // A plan saved during the current run, which the user reviews once the run settles.
+  let review: string | undefined;
 
   // Inactive until plan mode turns it on.
   pi.registerTool({ ...createReadonlyBashTool(PLAN_BASH), defaultActive: false });
   pi.registerTool({
     name: PLAN_SAVE,
-    label: 'Save plan',
-    description: 'Save the plan to a file so the user can review it and build it. Available only in plan mode. Returns the file path.',
-    promptSnippet: 'Save the plan to a file',
-    parameters: PlanSaveParams,
+    label: 'Create plan',
+    description: CREATE_PLAN_DESCRIPTION,
+    promptSnippet: 'Save the plan to a file the user reviews and builds',
+    parameters: CreatePlanParams,
     exposure: 'model-only',
     executionMode: 'sequential',
     defaultActive: false,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-    async execute(_id, params) {
+    async execute(_id, params, _signal, _onUpdate, ctx) {
       if (!state.enabled) throw new Error(`${PLAN_SAVE} is available only in plan mode. Enter it with /plan.`);
-      const title = params.name ?? params.content.trim().split('\n')[0] ?? '';
-      const planFile = savePlan(title.replace(/^#+\s*/, ''), params.content);
+      const planFile = savePlan(ctx.sessionManager.getSessionId(), params.plan, params.name, params.todos ?? []);
       state = { ...state, planFile };
-      pi.appendEntry(PLAN_ENTRY, { ...state, planFile });
-      return { content: [{ type: 'text' as const, text: `Plan saved to ${planFile}. /plan build starts the work.` }], details: { planFile } };
+      review = planFile;
+      pi.appendEntry(PLAN_ENTRY, state);
+      const overview = params.overview === undefined || params.overview.trim() === '' ? '' : `\n${params.overview.trim()}`;
+      return { content: [{ type: 'text' as const, text: `Created the plan file ${planFile}.${overview}\nTo change the plan, edit that file; do not call ${PLAN_SAVE} again.` }], details: { planFile } };
     },
   });
   pi.on('session_shutdown', releaseReadonlySandbox);
@@ -171,8 +286,11 @@ export function registerPlanMode(pi: ExtensionAPI): { section: () => string | un
   const restore = (ctx: ExtensionContext) => {
     const stored = planFromBranch(ctx.sessionManager.getBranch());
     state = { ...stored };
+    review = undefined;
     if (stored.enabled) enable(stored.toolsBefore ?? state.toolsBefore ?? pi.getActiveTools());
     else if (pi.getActiveTools().some((name) => name === PLAN_BASH || name === PLAN_SAVE)) pi.setActiveTools(pi.getActiveTools().filter((name) => name !== PLAN_BASH && name !== PLAN_SAVE));
+    // SwitchMode needs someone to approve the switch, so a run nobody watches does not get it.
+    if (!canAsk(ctx) && pi.getActiveTools().includes(SWITCH_MODE)) pi.setActiveTools(pi.getActiveTools().filter((name) => name !== SWITCH_MODE));
     show(ctx);
   };
   pi.on('session_start', (_event, ctx) => restore(ctx));
@@ -183,24 +301,76 @@ export function registerPlanMode(pi: ExtensionAPI): { section: () => string | un
   // so the restriction never reaches an agent's record.
   pi.on('tool_call', (event) => {
     if (!state.enabled) return undefined;
-    const reason = planBlockReason(event.toolName);
+    const reason = planBlockReason(event.toolName, event.input as Record<string, unknown>);
     return reason === undefined ? undefined : { block: true, reason };
   });
 
+  const build = (ctx: ExtensionContext, planFile: string) => {
+    if (state.enabled) disable();
+    pi.appendEntry(PLAN_ENTRY, state);
+    show(ctx);
+    ctx.ui.notify(`Building ${planFile}.`, 'info');
+    pi.sendUserMessage(buildRequest(planFile, planBody(planFile)), { expandPromptTemplates: true, ...(ctx.isIdle() ? {} : { deliverAs: 'followUp' as const }) });
+  };
+
+  const reviewPlan = async (ctx: ExtensionContext, planFile: string) => {
+    const worker = options.buildInWorker !== undefined && isGitRepository(ctx.cwd);
+    const choice = await ctx.ui.select(`Plan saved at ${planFile}. Build it?`, worker ? [BUILD_LOCALLY, BUILD_IN_WORKER, PROPOSE_CHANGES] : [BUILD_LOCALLY, PROPOSE_CHANGES]);
+    if (!state.enabled || state.planFile !== planFile) return;
+    if (choice === BUILD_LOCALLY) build(ctx, planFile);
+    else if (choice === BUILD_IN_WORKER && options.buildInWorker !== undefined) {
+      disable();
+      pi.appendEntry(PLAN_ENTRY, state);
+      show(ctx);
+      const agentId = await options.buildInWorker(planFile, buildRequest(planFile, planBody(planFile)));
+      ctx.ui.notify(`Building ${planFile} in an isolated worker (agent ${agentId}). Its result arrives as a Task notification.`, 'info');
+    }
+  };
+
+  // After a run that saved a plan, the user picks what happens next, as Cursor's plan card asks. The dialog runs on
+  // its own so that other settle handlers, such as a loop's next tick, do not wait for the user's answer.
+  pi.on('agent_settled', (event, ctx) => {
+    const planFile = review;
+    review = undefined;
+    if (event.aborted || planFile === undefined || !state.enabled || !canAsk(ctx) || !existsSync(planFile)) return;
+    reviewPlan(ctx, planFile).catch((error: Error) => ctx.ui.notify(`Could not start the plan build: ${error.message}`, 'error'));
+  });
+
+  pi.registerTool({
+    name: SWITCH_MODE,
+    label: 'Switch mode',
+    description: SWITCH_MODE_DESCRIPTION,
+    promptSnippet: 'Switch between agent mode and plan mode, with the user approving',
+    parameters: SwitchModeParams,
+    exposure: 'model-only',
+    executionMode: 'sequential',
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const current = state.enabled ? 'plan' : 'agent';
+      if (params.target_mode_id === current) return { content: [{ type: 'text' as const, text: `Already in ${current} mode.` }], details: { mode: current, switched: false } };
+      if (!canAsk(ctx)) throw new Error('A mode switch needs the user to approve it, and nobody can approve one in this run.');
+      const label = params.target_mode_id === 'plan' ? 'Plan' : 'Agent';
+      const approved = await ctx.ui.confirm(`Switch to ${label} mode?`, params.explanation?.trim() ?? '');
+      if (!approved) return { content: [{ type: 'text' as const, text: `The user declined the switch to ${params.target_mode_id} mode. Stay in ${current} mode.` }], details: { mode: current, switched: false } };
+      if (params.target_mode_id === 'plan') enable(pi.getActiveTools());
+      else disable();
+      pi.appendEntry(PLAN_ENTRY, state);
+      show(ctx);
+      const text =
+        params.target_mode_id === 'plan' ? `Switched to plan mode. Follow these instructions from now on:\n${planSection(state.planFile)}` : 'Switched to agent mode. Plan mode restrictions no longer apply, and every tool is back.';
+      return { content: [{ type: 'text' as const, text }], details: { mode: params.target_mode_id, switched: true } };
+    },
+  });
+
   const handle = (args: string, ctx: ExtensionCommandContext) => {
     const command = parsePlanArgs(args);
     if (command.kind === 'build') {
       const planFile = state.planFile;
       if (planFile === undefined || !existsSync(planFile)) {
-        ctx.ui.notify('No saved plan to build. Run /plan, then have the agent save the plan with create_plan. /plan off leaves plan mode.', 'error');
+        ctx.ui.notify(`No saved plan to build. Run /plan, then have the agent save the plan with ${PLAN_SAVE}. /plan off leaves plan mode.`, 'error');
         return undefined;
       }
-      const content = readFileSync(planFile, 'utf8').replace(/^<!-- plan: [^>]*-->\n\n/, '');
-      if (state.enabled) disable();
-      pi.appendEntry(PLAN_ENTRY, state);
-      show(ctx);
-      ctx.ui.notify(`Building ${planFile}.`, 'info');
-      pi.sendUserMessage(buildRequest(planFile, content), { expandPromptTemplates: true, ...(ctx.isIdle() ? {} : { deliverAs: 'followUp' as const }) });
+      build(ctx, planFile);
       return undefined;
     }
     if (command.kind === 'off') {
@@ -215,7 +385,7 @@ export function registerPlanMode(pi: ExtensionAPI): { section: () => string | un
   };
 
   pi.registerCommand('plan', {
-    description: 'Plan mode: read-only tools, investigate and save a plan. /plan [task] turns it on; /plan build starts the saved plan; /plan off exits; the footer shows plan',
+    description: 'Plan mode: read-only research, then a plan to review. /plan [task] turns it on; /plan build starts the saved plan; /plan off exits; the footer shows plan',
     getArgumentCompletions: (prefix) => ['off', 'build'].filter((name) => name.startsWith(prefix.trim())).map((name) => ({ value: name, label: name })),
     handler: async (args, ctx) => {
       handle(args, ctx);

package/src/sections.ts

@@ -96,7 +96,9 @@ export function hostSection(facts: HostFacts): string {
     facts.loopAvailable ? SUBSCRIPTIONS_LINE : NO_SUBSCRIPTIONS_LINE,
     ...agentToolsLine(facts.activeTools),
     facts.loopAvailable ? LOOP_LINE : NO_LOOP_LINE,
-    "- Image generation: codemode's models.generateImages() when codemode is on and an image model is configured. Otherwise say no image tool is available and use a mermaid diagram or a table.",
+    facts.activeTools.includes('GenerateImage')
+      ? '- Image generation: the GenerateImage tool, which saves each image to the artifacts folder below and shows it in its result.'
+      : '- Image generation: no image model is configured, so this session has no GenerateImage tool. Say so and use a mermaid diagram or a table instead.',
     '- The user keeps a skill on every turn with `/mode <skill>` (exit `/mode off`) and plans without edits with `/plan` (exit `/plan off`).',
     '- PR operations use the forge command the step gives, such as `gh pr create`. Bugbot comments on a GitHub PR are ordinary review threads; skip a step that starts, waits for, or configures Bugbot when the PR has no Bugbot check or comment.',
     '- MCP tools are named mcp__<server>__<tool>; `pi mcp list` shows the servers.',
@@ -132,5 +134,8 @@ export function subagentsSection(agents: readonly AgentDefinition[], models: rea
     '- A Pi model <provider>/<model-id> or <model-id>, optionally with :<level> from the thinking levels the model lists below. A level the model does not list is rejected.',
     "- Model parameters: <model>[effort=<level>,fast=true|false]. effort is the thinking level, fast=true picks the model's -fast id when one is listed, and [] or fast=false keeps the standard model.",
     `Available models: ${shown.join(', ') || 'none with configured credentials'}${more}`,
+    'Use inherit unless the user or a skill asks for another model. When the user names a model family without a version, use the newest listed version of that family.',
+    'If the user asks for a model that is not listed, do not substitute another model or guess: skip launching that subagent and tell the user which model was unavailable and which models are available.',
+    'When you tell the user which model a subagent used, name it the way the user named it, not by its model ID, unless the user used the ID.',
   ].join('\n');
 }