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

package/src/plan.ts

@@ -1,28 +1,47 @@
-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 { createRequire } from 'node:module';
 import { join, resolve, sep } from 'node:path';
 
-import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext, stripFrontmatter } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
+import type * as YAML from 'yaml';
+import { canAsk } from './modes.ts';
 import { plansDir } from './paths.ts';
 import { createReadonlyBashTool, releaseReadonlySandbox } from './readonly-shell.ts';
+import type { TodoItem } from './todo.ts';
 
 export const PLAN_ENTRY = 'pstack/plan';
 const STATUS_KEY = 'pstack-plan';
 
+// Pi's local package installer does not install dependencies, so missing YAML must not block unrelated tools.
+let yaml: typeof YAML | undefined;
+try {
+  yaml = createRequire(import.meta.url)('yaml') as typeof YAML;
+} catch (error) {
+  if ((error as NodeJS.ErrnoException).code !== 'MODULE_NOT_FOUND') throw error;
+}
+
 /**
  * Pi's `bash` cannot be swapped for the sandboxed shell by name without replacing it for the whole session, so plan
  * mode offers the sandboxed shell under its own name and makes it the only shell while plan mode is on.
  */
 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 +93,218 @@ 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;
+  dependencies?: string[];
+}
+
+export interface PlanProject {
+  is_project?: boolean;
+  phases?: { name: string; todos?: PlanTodo[] }[];
+}
+
+/** 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')}"`;
+
+function planTodoLines(todo: PlanTodo): string[] {
+  const lines = [`  - id: ${yamlString(todo.id)}`, `    content: ${yamlString(todo.content)}`, '    status: pending'];
+  if (todo.dependencies !== undefined && todo.dependencies.length > 0) lines.push('    dependencies:', ...todo.dependencies.map((id) => `      - ${yamlString(id)}`));
+  return lines;
+}
+
+/** 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[], project: PlanProject = {}): string {
+  const lines = [`<!-- ${sessionId} -->`];
+  if (todos.length > 0 || project.is_project === true) {
+    lines.push('---');
+    if (todos.length > 0) lines.push('todos:', ...todos.flatMap(planTodoLines));
+    lines.push(`isProject: ${project.is_project === true}`);
+    if (project.is_project === true && project.phases !== undefined && project.phases.length > 0) {
+      lines.push('phases:');
+      for (const phase of project.phases) lines.push(`  - name: ${yamlString(phase.name)}`, '    todos:', ...(phase.todos ?? []).flatMap((todo) => planTodoLines(todo).map((line) => `    ${line}`)));
+    }
+    lines.push('---');
+  }
+  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(), project: PlanProject = {}): 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, project), { 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 stripFrontmatter(readFileSync(file, 'utf8').replace(/^<!-- [^\n]*-->\r?\n/, '')).trim();
+}
+
+function planMetadata(file: string) {
+  const source = readFileSync(file, 'utf8');
+  const comment = /^<!-- [^\n]*-->\r?\n/.exec(source)?.[0] ?? '';
+  const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(source.slice(comment.length));
+  if (frontmatter === null) return undefined;
+  if (yaml === undefined) throw new Error('Plan metadata needs the yaml dependency. Run bun install in the pi-pstack package directory, then reload Pi.');
+  const document = yaml.parseDocument(frontmatter[1] ?? '');
+  if (document.errors.length > 0) throw new Error(`Invalid plan metadata in ${file}: ${document.errors[0]?.message}`);
+  return { source, offset: comment.length + frontmatter[0].indexOf('\n') + 1, document, yaml };
+}
+
+export function planTodos(file: string): TodoItem[] {
+  const metadata = planMetadata(file);
+  if (metadata === undefined) return [];
+  const { isSeq, isMap, isScalar } = metadata.yaml;
+  const field = metadata.document.get('todos');
+  if (field === undefined || field === null) return [];
+  if (!isSeq(field)) throw new Error(`Plan todos in ${file} must be a list.`);
+  return field.items.map((todo) => {
+    if (!isMap(todo)) throw new Error(`Each plan todo in ${file} must have an id, content, and status.`);
+    const id = todo.get('id');
+    const content = todo.get('content');
+    const status = todo.get('status') ?? 'pending';
+    const dependencies = todo.get('dependencies');
+    if (typeof id !== 'string' || typeof content !== 'string' || !(status === 'pending' || status === 'in_progress' || status === 'completed' || status === 'cancelled')) throw new Error(`Invalid plan todo in ${file}.`);
+    if (dependencies !== undefined && (!isSeq(dependencies) || dependencies.items.some((dependency) => !isScalar(dependency) || typeof dependency.value !== 'string'))) throw new Error(`Invalid todo dependencies in ${file}.`);
+    return { id, content, status, ...(isSeq(dependencies) ? { dependencies: dependencies.toJSON() as string[] } : {}) };
+  });
+}
+
+export function syncPlanTodoStatuses(file: string, todos: readonly TodoItem[]): void {
+  const metadata = planMetadata(file);
+  if (metadata === undefined) return;
+  const { source, offset, document, yaml: parser } = metadata;
+  const { isSeq, isMap, isScalar } = parser;
+  const field = document.get('todos');
+  if (!isSeq(field)) return;
+  const statuses = new Map(todos.map((todo) => [todo.id, todo.status]));
+  const edits: { start: number; end: number; text: string }[] = [];
+  for (const todo of field.items) {
+    if (!isMap(todo)) continue;
+    const status = statuses.get(String(todo.get('id')));
+    const node = todo.get('status', true);
+    if (status === undefined || (node === undefined && status === 'pending')) continue;
+    if (node === undefined && todo.range != null) {
+      const start = offset + todo.range[0] + (todo.flow ? 1 : 0);
+      const indent = start - source.lastIndexOf('\n', start) - 1;
+      const newline = source.includes('\r\n') ? '\r\n' : '\n';
+      const text = todo.flow ? `status: ${status}, ` : `status: ${status}${newline}${' '.repeat(indent)}`;
+      edits.push({ start, end: start, text });
+      continue;
+    }
+    if (!isScalar(node) || node.range == null || node.value === status) continue;
+    const value = node.type === 'QUOTE_DOUBLE' ? JSON.stringify(status) : node.type === 'QUOTE_SINGLE' ? `'${status}'` : status;
+    edits.push({ start: offset + node.range[0], end: offset + node.range[1], text: value });
+  }
+  if (edits.length === 0) return;
+  let updated = source;
+  for (const edit of edits.sort((a, b) => b.start - a.start)) updated = updated.slice(0, edit.start) + edit.text + updated.slice(edit.end);
+  writeFileSync(file, updated);
+}
+
+const PlanTodoParams = Type.Object({
+  id: Type.String({ description: 'Unique identifier for the todo' }),
+  content: Type.String({ description: 'Description of the todo task' }),
+  dependencies: Type.Optional(Type.Array(Type.String(), { description: 'IDs of todos that must finish before this todo' })),
+});
+
+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(PlanTodoParams, { description: 'Array of implementation todos' })),
+  is_project: Type.Optional(Type.Boolean({ description: 'Whether the plan is a project organized into phases' })),
+  phases: Type.Optional(Type.Array(Type.Object({ name: Type.String(), todos: Type.Optional(Type.Array(PlanTodoParams)) }), { description: 'Named project phases and their todos, saved when is_project is true' })),
+});
+
+// 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 +319,48 @@ 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 {
+  buildPlan?: string;
+  setTodos?: (todos: TodoItem[], ctx: ExtensionContext) => void;
+  /** 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 = {}) {
   let state: PlanState = { enabled: false };
+  let buildPlan = options.buildPlan;
+  // 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 ?? [], undefined, params);
       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);
@@ -169,13 +380,29 @@ export function registerPlanMode(pi: ExtensionAPI): { section: () => string | un
   };
 
   const restore = (ctx: ExtensionContext) => {
-    const stored = planFromBranch(ctx.sessionManager.getBranch());
+    const branch = ctx.sessionManager.getBranch();
+    const stored = planFromBranch(branch);
+    // Pi replays tools from system messages before session_tree. A branch without one has no loadout to restore.
+    if (!stored.enabled && state.enabled && !branch.some((entry) => entry.type === 'message' && entry.message.role === 'system')) disable();
     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));
+  pi.on('session_start', (_event, ctx) => {
+    restore(ctx);
+    const initialPlan = buildPlan;
+    buildPlan = undefined;
+    if (initialPlan === undefined) return;
+    const planFile = storedPlanFile(initialPlan, plansDir());
+    if (planFile === undefined) throw new Error('The plan build must use a file inside the pi-pstack plans directory.');
+    prepareBuild(ctx, planFile);
+    state = { enabled: false, planFile };
+    pi.appendEntry(PLAN_ENTRY, state);
+  });
   pi.on('session_tree', (_event, ctx) => restore(ctx));
 
   // Active tools decide what the model is offered; this decides what may run, including names the model
@@ -183,24 +410,83 @@ 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 prepareBuild = (ctx: ExtensionContext, planFile: string) => {
+    const todos = planTodos(planFile).filter((todo) => todo.status !== 'completed' && todo.status !== 'cancelled');
+    options.setTodos?.(todos, ctx);
+  };
+
+  const build = (ctx: ExtensionContext, planFile: string) => {
+    prepareBuild(ctx, planFile);
+    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) {
+      prepareBuild(ctx, planFile);
+      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,12 +501,18 @@ 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);
     },
   });
 
-  return { section: () => (state.enabled ? planSection(state.planFile) : undefined), enabled: () => state.enabled };
+  return {
+    section: () => (state.enabled ? planSection(state.planFile) : undefined),
+    enabled: () => state.enabled,
+    syncTodos: (todos: readonly TodoItem[]) => {
+      if (state.planFile !== undefined && existsSync(state.planFile)) syncPlanTodoStatuses(state.planFile, todos);
+    },
+  };
 }

package/src/process-lock.ts

@@ -0,0 +1,76 @@
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+function zombie(pid: number): boolean {
+  if (process.platform !== 'linux') return false;
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+    const close = stat.lastIndexOf(')');
+    return close !== -1 && stat.slice(close + 2, close + 3) === 'Z';
+  } catch {
+    return false;
+  }
+}
+
+export function alive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return !zombie(pid);
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+export type Lease = { token: string; release: () => void };
+
+/** A holder token keeps a stale reaper from unlinking a replacement owner's lease. */
+export function acquireLease(path: string): Lease | undefined {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const token = `${process.pid}-${randomUUID()}`;
+  const temporary = `${path}.${token}.tmp`;
+  mkdirSync(temporary, { mode: 0o700 });
+  try {
+    writeFileSync(join(temporary, token), '', { mode: 0o600 });
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+      try {
+        renameSync(temporary, path);
+        return {
+          token,
+          release: () => {
+            rmSync(join(path, token), { force: true });
+            try {
+              rmdirSync(path);
+            } catch (error) {
+              if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
+            }
+          },
+        };
+      } catch (error) {
+        if (!['ENOTEMPTY', 'EEXIST'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
+      }
+      let holders: string[];
+      try {
+        holders = readdirSync(path);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+        throw error;
+      }
+      for (const holder of holders) {
+        const pid = Number(/^(\d+)-[a-f0-9-]+$/.exec(holder)?.[1]);
+        if (!Number.isInteger(pid)) throw new Error(`Invalid process lock ${path}. Retain it for diagnosis.`);
+        if (alive(pid)) return undefined;
+        rmSync(join(path, holder), { force: true });
+      }
+      try {
+        rmdirSync(path);
+      } catch (error) {
+        if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
+      }
+    }
+    return undefined;
+  } finally {
+    rmSync(temporary, { recursive: true, force: true });
+  }
+}

package/src/readonly-shell.ts

@@ -8,11 +8,9 @@ import { type BashSpawnContext, createBashTool, type ExtensionAPI, type Extensio
 // denyWrite names the paths the sandbox makes writable for itself (/tmp/claude is a dependency default), and
 // denyRead drops the dependency's writable home defaults (~/.npm/_logs, ~/.claude/debug). Seatbelt is
 // last-match-wins with deny emitted after allow; on Linux bubblewrap binds deny last the same way.
-// allowAllUnixSockets skips apply-seccomp: on GitHub-hosted runners (and other nested-userns hosts) that
-// helper fails writing /proc/self/setgroups even with setuid bwrap. Write and network denial still come
-// from bubblewrap / sandbox-exec; only AF_UNIX blocking is dropped.
+// Unix sockets must stay blocked too: a host service can mutate files on a command's behalf.
 const READ_ONLY_POLICY: SandboxRuntimeConfig = {
-  network: { allowedDomains: [], deniedDomains: [], allowAllUnixSockets: true },
+  network: { allowedDomains: [], deniedDomains: [], allowAllUnixSockets: false },
   filesystem: {
     denyRead: ['~/.npm/_logs', '~/.claude/debug'],
     allowWrite: [],
@@ -40,10 +38,10 @@ function sandboxReady(): Promise<Sandbox> {
     try {
       const { SandboxManager } = await import('@anthropic-ai/sandbox-runtime');
       if (!SandboxManager.isSupportedPlatform()) throw new Error(`${process.platform} is not supported`);
-      // initialize verifies the sandbox dependencies (bubblewrap, socat, sandbox-exec) before it starts.
-      // A second initialize is a no-op once another consumer has started the manager, and several
-      // Linux flags (notably allowAllUnixSockets) are read from the manager config, not the per-call
-      // wrap override — so updateConfig installs our policy even when we lost the initialize race.
+      const socketWarning = SandboxManager.checkDependencies().warnings.find((warning) => warning.includes('unix socket access not restricted'));
+      if (socketWarning !== undefined) throw new Error(socketWarning);
+      // initialize is a no-op if another consumer started the manager. Linux socket isolation also
+      // reads the shared config, so both it and the per-command override must carry this policy.
       await SandboxManager.initialize(READ_ONLY_POLICY);
       SandboxManager.updateConfig(READ_ONLY_POLICY);
       return SandboxManager;

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');
 }