@justjoshn/pi-pstack 0.0.0-stage → 0.15.36-pi.1

package/src/loop.ts

@@ -0,0 +1,189 @@
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import { isOneShot } from './modes.ts';
+
+const DAY_MS = 86_400_000;
+const UNIT_MS: Record<string, number> = { s: 1_000, m: 60_000, h: 3_600_000, d: DAY_MS };
+const DURATION = /^(?:\d+[smhd])+$/;
+// setTimeout fires at once for delays past 2^31-1 ms (about 24.8 days), which would turn a long loop into a runaway.
+const MAX_DELAY_MS = 24 * DAY_MS;
+const TOO_LONG = 'Loop intervals can be at most 24d.';
+
+/** Milliseconds for a duration such as 30s, 5m, 1h30m; undefined when the text is not a duration. */
+export function parseDuration(text: string): number | undefined {
+  if (!DURATION.test(text)) return undefined;
+  const total = [...text.matchAll(/(\d+)([smhd])/g)].reduce((sum, [, count, unit]) => sum + Number(count) * (UNIT_MS[unit ?? 's'] ?? 0), 0);
+  return total > 0 ? total : undefined;
+}
+
+function delayOf(text: string): number {
+  const ms = parseDuration(text);
+  if (ms === undefined) throw new Error(`"${text}" is not a duration such as 30s, 10m, or 1h.`);
+  if (ms > MAX_DELAY_MS) throw new Error(TOO_LONG);
+  return ms;
+}
+
+export type LoopCommand = { kind: 'status' } | { kind: 'stop' } | { kind: 'start'; prompt: string; intervalMs?: number } | { kind: 'error'; message: string };
+
+export function parseLoopArgs(args: string): LoopCommand {
+  const trimmed = args.trim();
+  if (trimmed === '') return { kind: 'status' };
+  if (trimmed === 'stop' || trimmed === 'off') return { kind: 'stop' };
+  const [, first = '', rest = ''] = /^(\S+)\s*([\s\S]*)$/.exec(trimmed) ?? [];
+  const intervalMs = parseDuration(first);
+  if (intervalMs === undefined) return { kind: 'start', prompt: trimmed };
+  if (intervalMs > MAX_DELAY_MS) return { kind: 'error', message: TOO_LONG };
+  return rest.trim() === '' ? { kind: 'error', message: '/loop needs a prompt: /loop [interval] <prompt>' } : { kind: 'start', prompt: rest.trim(), intervalMs };
+}
+
+interface Loop {
+  prompt: string;
+  intervalMs?: number;
+  iteration: number;
+  nextWakeMs?: number;
+  timer?: ReturnType<typeof setTimeout>;
+}
+
+const formatMs = (ms: number) => (ms % 86_400_000 === 0 ? `${ms / 86_400_000}d` : ms % 3_600_000 === 0 ? `${ms / 3_600_000}h` : ms % 60_000 === 0 ? `${ms / 60_000}m` : `${Math.round(ms / 1_000)}s`);
+
+/** Loop state rides in the system prompt, so the prompt itself stays verbatim and a template prompt keeps it too. */
+function loopSection(loop: Loop): string {
+  if (loop.intervalMs !== undefined) {
+    return `A /loop is running: iteration ${loop.iteration}, every ${formatMs(loop.intervalMs)}. The user ends it with /loop stop; call the Loop tool with stop: true once the goal is met.`;
+  }
+  return `A /loop is running: iteration ${loop.iteration}, agent-paced. Call the Loop tool with wake_in (like 10m) to schedule the next run, or stop: true to end it. Without a wake_in call the loop ends after this turn.`;
+}
+
+export interface LoopOptions {
+  /** True while this session waits on work that will wake the agent, such as background subagents. */
+  hasPendingWork: () => boolean;
+}
+
+function createLoopController(pi: ExtensionAPI, options: LoopOptions) {
+  let loop: Loop | undefined;
+  let lastCtx: ExtensionContext | undefined;
+
+  const notify = (ctx: ExtensionContext | undefined, message: string) => {
+    if (ctx?.hasUI) ctx.ui.notify(message, 'info');
+  };
+  const clear = () => {
+    if (loop?.timer !== undefined) clearTimeout(loop.timer);
+    loop = undefined;
+  };
+  const stop = (ctx: ExtensionContext | undefined, reason: string) => {
+    clear();
+    notify(ctx, `Loop stopped: ${reason}`);
+  };
+  const fire = () => {
+    if (loop === undefined) return;
+    const { timer: _timer, nextWakeMs: _wake, ...rest } = loop;
+    loop = { ...rest, iteration: rest.iteration + 1 };
+    // Expansion lets a loop run a skill or template each time.
+    pi.sendUserMessage(loop.prompt, { expandPromptTemplates: true, ...(lastCtx === undefined || lastCtx.isIdle() ? {} : { deliverAs: 'followUp' as const }) });
+  };
+  const settled = (ctx: ExtensionContext, aborted: boolean) => {
+    lastCtx = ctx;
+    if (loop === undefined || loop.timer !== undefined) return;
+    if (aborted) return stop(ctx, 'the run was aborted.');
+    const delay = loop.intervalMs ?? loop.nextWakeMs;
+    if (delay !== undefined) loop = { ...loop, timer: setTimeout(fire, delay) };
+    else if (!options.hasPendingWork()) stop(ctx, 'the agent scheduled no next wake.');
+  };
+  const start = (ctx: ExtensionContext, prompt: string, intervalMs: number | undefined) => {
+    if (loop !== undefined) stop(ctx, 'replaced by a new /loop.');
+    lastCtx = ctx;
+    loop = { prompt, iteration: 0, ...(intervalMs === undefined ? {} : { intervalMs }) };
+    fire();
+  };
+  /** An agent arms a loop mid-turn, so its first run waits for this turn to settle and then for the first delay. */
+  const arm = (ctx: ExtensionContext, prompt: string, schedule: { intervalMs: number } | { firstWakeMs: number }) => {
+    if (loop !== undefined) stop(ctx, 'replaced by a new loop.');
+    loop = 'intervalMs' in schedule ? { prompt, iteration: 0, intervalMs: schedule.intervalMs } : { prompt, iteration: 0, nextWakeMs: schedule.firstWakeMs };
+  };
+  const status = () => (loop === undefined ? 'No loop is running.' : `Loop: "${loop.prompt}" (iteration ${loop.iteration}${loop.intervalMs === undefined ? ', agent-paced' : `, every ${formatMs(loop.intervalMs)}`})`);
+  const wake = (delayMs: number) => {
+    if (loop === undefined) throw new Error('No loop is running. Start one with prompt plus interval or wake_in, or ask the user to run /loop.');
+    if (loop.intervalMs !== undefined) throw new Error(`This loop runs every ${formatMs(loop.intervalMs)}; only the user can change its interval. Pass stop: true to end it.`);
+    // A wake already scheduled is replaced, so the new delay counts from the end of this turn.
+    if (loop.timer !== undefined) clearTimeout(loop.timer);
+    const { timer: _timer, ...rest } = loop;
+    loop = { ...rest, nextWakeMs: delayMs };
+  };
+  const section = () => (loop === undefined ? undefined : loopSection(loop));
+  return { notify, stop, settled, start, arm, status, wake, clear, section, active: () => loop !== undefined };
+}
+
+type LoopController = ReturnType<typeof createLoopController>;
+
+const ONE_SHOT = '/loop needs an interactive or RPC session; print and JSON runs exit when the agent settles.';
+
+function handleLoopCommand(controller: LoopController, args: string, ctx: ExtensionCommandContext): void {
+  const command = parseLoopArgs(args);
+  if (command.kind === 'status') controller.notify(ctx, controller.status());
+  else if (command.kind === 'stop') controller.stop(ctx, 'stopped by /loop stop.');
+  else if (command.kind === 'error') controller.notify(ctx, command.message);
+  else if (isOneShot(ctx.mode)) process.stderr.write(`${ONE_SHOT}\n`);
+  else controller.start(ctx, command.prompt, command.intervalMs);
+}
+
+const LoopParams = Type.Object({
+  prompt: Type.Optional(Type.String({ description: 'Start (or replace) a loop that sends this prompt each run. It may be a skill or template command such as /poteto-mode <task>.' })),
+  interval: Type.Optional(Type.String({ description: 'With prompt: a fixed cadence such as 30m or 1h; the first run starts that long after this turn ends.' })),
+  wake_in: Type.Optional(Type.String({ description: 'With prompt: the first run of an agent-paced loop. Alone: the next run of the running agent-paced loop. A duration such as 10m, at most 24d.' })),
+  stop: Type.Optional(Type.Boolean({ description: 'End the loop once its goal is met.' })),
+});
+
+function loopToolText(controller: LoopController, params: { prompt?: string; interval?: string; wake_in?: string; stop?: boolean }, ctx: ExtensionContext): string {
+  if (isOneShot(ctx.mode)) throw new Error(`${ONE_SHOT} Do the work now instead of scheduling it.`);
+  if (params.stop === true) {
+    if (!controller.active()) throw new Error('No loop is running.');
+    controller.stop(ctx, 'the agent ended it.');
+    return 'Loop stopped.';
+  }
+  if (params.prompt !== undefined) {
+    if (params.interval !== undefined) {
+      const intervalMs = delayOf(params.interval);
+      controller.arm(ctx, params.prompt, { intervalMs });
+      return `Loop armed: "${params.prompt}" every ${formatMs(intervalMs)}; the first run starts ${formatMs(intervalMs)} after this turn ends.`;
+    }
+    if (params.wake_in === undefined) throw new Error('To start a loop, pass interval for a fixed cadence or wake_in for the first run of an agent-paced loop.');
+    const firstWakeMs = delayOf(params.wake_in);
+    controller.arm(ctx, params.prompt, { firstWakeMs });
+    return `Loop armed: "${params.prompt}", agent-paced; the first run starts ${formatMs(firstWakeMs)} after this turn ends.`;
+  }
+  if (params.interval !== undefined) throw new Error('interval applies only when starting a loop with prompt.');
+  if (params.wake_in === undefined) throw new Error('Pass prompt with interval or wake_in to start a loop, wake_in to schedule the next run, or stop: true.');
+  const delay = delayOf(params.wake_in);
+  controller.wake(delay);
+  return `Next loop run in ${formatMs(delay)}, after this turn ends.`;
+}
+
+function registerLoopTool(pi: ExtensionAPI, controller: LoopController): void {
+  pi.registerTool({
+    name: 'Loop',
+    label: 'Loop',
+    description: '/loop for you: start a loop that re-sends a prompt at a fixed interval or at wakes you pick, schedule the next wake of an agent-paced loop, or stop the loop once its goal is met. Use it when a playbook says to arm /loop.',
+    promptSnippet: 'Start a /loop, schedule its next wake, or stop it',
+    parameters: LoopParams,
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      return { content: [{ type: 'text', text: loopToolText(controller, params, ctx) }], details: undefined };
+    },
+  });
+}
+
+/** /loop: run a prompt at a fixed interval, or at wakes the agent picks, until stopped. */
+export function registerLoop(pi: ExtensionAPI, options: LoopOptions): { section: () => string | undefined } {
+  const controller = createLoopController(pi, options);
+  pi.on('session_start', (_event, ctx) => {
+    if (isOneShot(ctx.mode)) pi.setActiveTools(pi.getActiveTools().filter((name) => name !== 'Loop'));
+  });
+  pi.on('agent_settled', (event, ctx) => controller.settled(ctx, event.aborted));
+  pi.on('session_shutdown', () => controller.clear());
+  pi.registerCommand('loop', {
+    description: 'Run a prompt repeatedly: /loop [interval] <prompt> (interval like 30s, 5m, 1h, at most 24d); /loop stop',
+    handler: async (args, ctx) => handleLoopCommand(controller, args, ctx),
+  });
+  registerLoopTool(pi, controller);
+  return { section: controller.section };
+}

package/src/mode.ts

@@ -0,0 +1,156 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, ThemeColor } from '@earendil-works/pi-coding-agent';
+import { parseFrontmatter } from '@earendil-works/pi-coding-agent';
+
+export const MODE_ENTRY = 'pstack/mode';
+const STATUS_KEY = 'pstack-mode';
+
+/** The mode on the branch. `path` is the loaded skill's file; absent when no loaded skill has the name. */
+export interface ActiveMode {
+  skill: string;
+  path?: string;
+}
+
+export type ModeCommand = { kind: 'status' } | { kind: 'off' } | { kind: 'set'; skill: string; task: string };
+
+export function parseModeArgs(args: string): ModeCommand {
+  const trimmed = args.trim();
+  if (trimmed === '') return { kind: 'status' };
+  if (trimmed === 'off') return { kind: 'off' };
+  const match = /^\/?(\S+)(?:\s([\s\S]*))?$/.exec(trimmed);
+  return { kind: 'set', skill: match?.[1] ?? trimmed, task: (match?.[2] ?? '').trim() };
+}
+
+interface BranchEntry {
+  type: string;
+  customType?: string;
+  data?: unknown;
+}
+
+const SKILL_NAME = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/;
+
+/**
+ * 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.
+ */
+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;
+  }
+  return undefined;
+}
+
+/**
+ * The mode text for every request: the skill block in the same shape as Pi's own
+ * `/skill:name` expansion (agent-session.js `_expandSkillCommand`), which Pi does not export as a function.
+ */
+export function modeSection(mode: ActiveMode): 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>.`;
+  // The frontmatter, including `reminder`, stays out of the model's context in a mode (MODE-004).
+  const { body } = parseFrontmatter(readFileSync(mode.path, 'utf8'));
+  return [`Mode ${mode.skill} is on for every turn until the user runs /mode off.`, `<skill name="${mode.skill}" location="${mode.path}">`, `References are relative to ${dirname(mode.path)}.`, '', body.trim(), '</skill>'].join('\n');
+}
+
+// A mode's badge shows the skill's `icon` (default: lightning) and `color`. Icon names map to terminal glyphs and
+// color names to the nearest theme color.
+const BADGE_ICONS: Record<string, string> = {
+  crown: '♛',
+  lightning: '⚡',
+  code: '</>',
+  terminal: '>_',
+  bug: '✱',
+  'git-branch': '⎇',
+  'book-open': '❐',
+  beaker: '⚗',
+  shield: '⛨',
+  rocket: '➶',
+};
+const BADGE_COLORS: Record<string, ThemeColor> = { green: 'success', red: 'error', yellow: 'warning', orange: 'warning', cyan: 'accent', blue: 'accent', purple: 'accent', magenta: 'accent', brand: 'accent' };
+
+/** A skill carries `icon` and `color` under `metadata`, or at the top level of its frontmatter. */
+function skillMetadata(mode: ActiveMode): Record<string, unknown> {
+  if (mode.path === undefined || !existsSync(mode.path)) return {};
+  const { frontmatter } = parseFrontmatter(readFileSync(mode.path, 'utf8'));
+  const metadata = typeof frontmatter['metadata'] === 'object' && frontmatter['metadata'] !== null ? (frontmatter['metadata'] as Record<string, unknown>) : {};
+  return { icon: frontmatter['icon'], color: frontmatter['color'], ...metadata };
+}
+
+export function modeBadge(mode: ActiveMode, metadata: Record<string, unknown> = skillMetadata(mode)): { text: string; color?: ThemeColor } {
+  const iconName = String(metadata['icon']);
+  const colorName = String(metadata['color']);
+  const icon = Object.hasOwn(BADGE_ICONS, iconName) ? BADGE_ICONS[iconName] : BADGE_ICONS['lightning'];
+  const color = Object.hasOwn(BADGE_COLORS, colorName) ? BADGE_COLORS[colorName] : undefined;
+  return { text: `${icon} mode: ${mode.skill}`, ...(color === undefined ? {} : { color }) };
+}
+
+function loadedSkills(pi: ExtensionAPI): Map<string, string> {
+  const skills = new Map<string, string>();
+  for (const command of pi.getCommands()) {
+    if (command.source === 'skill' && command.name.startsWith('skill:')) skills.set(command.name.slice('skill:'.length), command.sourceInfo.path);
+  }
+  return skills;
+}
+
+export function registerMode(pi: ExtensionAPI): { section: () => string | undefined } {
+  let active: ActiveMode | undefined;
+  const show = (ctx: ExtensionContext) => {
+    if (!ctx.hasUI) return;
+    const badge = active === undefined ? undefined : modeBadge(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 });
+    show(ctx);
+  };
+  pi.on('session_start', (_event, ctx) => restore(ctx));
+  pi.on('session_tree', (_event, ctx) => restore(ctx));
+
+  const resolveSkill = (name: string): ActiveMode => {
+    const skills = loadedSkills(pi);
+    const path = skills.get(name);
+    if (path === undefined) throw new Error(`No skill named "${name}". Skills that can back a mode: ${[...skills.keys()].toSorted().join(', ')}.`);
+    return { skill: name, path };
+  };
+
+  function tryResolve(name: string): ActiveMode | undefined {
+    try {
+      return resolveSkill(name);
+    } catch (error) {
+      if (error instanceof Error && error.message.startsWith('No skill named')) return undefined;
+      throw error;
+    }
+  }
+
+  const handle = (args: string, ctx: ExtensionCommandContext) => {
+    const command = parseModeArgs(args);
+    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);
+    pi.appendEntry(MODE_ENTRY, active === undefined ? null : { skill: active.skill });
+    show(ctx);
+    ctx.ui.notify(active === undefined ? 'Mode off.' : `Mode on: ${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;
+  };
+
+  pi.registerCommand('mode', {
+    description: 'Keep a skill on every turn: /mode <skill> [task], /mode off, /mode',
+    getArgumentCompletions: (prefix) => ['off', ...[...loadedSkills(pi).keys()].toSorted()].filter((name) => name.startsWith(prefix.trim())).map((name) => ({ value: name, label: name })),
+    handler: async (args, ctx) => {
+      try {
+        handle(args, ctx);
+      } catch (error) {
+        ctx.ui.notify((error as Error).message, 'error');
+      }
+    },
+  });
+
+  return { section: () => (active === undefined ? undefined : modeSection(active)) };
+}

package/src/modes.ts

@@ -0,0 +1,8 @@
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { childIdentity } from './child-env.ts';
+
+/** Print and JSON runs exit once the agent settles, and so does every subagent, an RPC child that its owner closes then. */
+export const isOneShot = (mode: ExtensionContext['mode']): boolean => mode === 'print' || mode === 'json' || childIdentity.depth > 0;
+
+/** Whether a user can answer a dialog. A subagent's owner dismisses every dialog, so a subagent has nobody to ask. */
+export const canAsk = (ctx: Pick<ExtensionContext, 'hasUI'>): boolean => ctx.hasUI && childIdentity.depth === 0;

package/src/paths.ts

@@ -0,0 +1,72 @@
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { getAgentDir } from '@earendil-works/pi-coding-agent';
+import { childIdentity } from './child-env.ts';
+
+export const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+export const SKILLS_DIR = join(PACKAGE_ROOT, 'skills');
+export const AGENTS_DIR = join(PACKAGE_ROOT, 'agents');
+
+/** Pi-owned state for this package. Follows PI_CODING_AGENT_DIR, so tests and users can relocate it. */
+export function stateDir(): string {
+  return join(getAgentDir(), 'pstack');
+}
+
+/** The model rule: pstack's per-role model choices, added to every request's system prompt. */
+export function rulePath(): string {
+  return join(stateDir(), 'pstack-models.md');
+}
+
+/** Webhook routines' sender keys, one `<slug>/credentials.json` each. */
+export function routinesDir(): string {
+  return join(stateDir(), 'routines');
+}
+
+/**
+ * Pi's rule for a session folder name, so per-workspace state lines up with `<agentDir>/sessions/<slug>`. The live
+ * `sessionManager.getSessionDir()` needs a session and names the current one, which is `<workspace>/subagents` in a
+ * subagent, so the rule stays here for a working directory (docs/native-gaps.md).
+ */
+export function workspaceSlug(cwd: string): string {
+  return `--${resolve(cwd)
+    .replace(/^[/\\]/, '')
+    .replace(/[/\\:]/g, '-')}--`;
+}
+
+/**
+ * State for one working directory, so transcripts and stores never cross workspaces (pstack's own rule). A subagent
+ * uses its main chat's, so an isolated worker in its own worktree shares the tree's Projects, records, and transcripts.
+ */
+export function workspaceStateDir(cwd: string, inherited: string | undefined = childIdentity.workspaceState): string {
+  return inherited ?? join(stateDir(), 'workspaces', workspaceSlug(cwd));
+}
+
+/** Subagent transcripts, records, and run locks for this workspace. */
+export function subagentDir(cwd: string): string {
+  return join(workspaceStateDir(cwd), 'subagents');
+}
+
+/** Projects of this workspace: `<slug>/notes.md` is a project's tracker and `<slug>/store/` its store. */
+export function projectsDir(cwd: string): string {
+  return join(workspaceStateDir(cwd), 'projects');
+}
+
+/** Files a session's tools produce for the user, such as visualize's SVG charts. */
+export function artifactsDir(cwd: string, sessionId: string): string {
+  return join(workspaceStateDir(cwd), 'artifacts', sessionId);
+}
+
+export function worktreesDir(cwd: string): string {
+  return join(workspaceStateDir(cwd), 'worktrees');
+}
+
+/** The store of the main chat that started this subagent tree, which autopilot owners write their trails into. */
+export function rootStoreDir(cwd: string, sessionId: string, inherited: string | undefined): string {
+  return inherited ?? storeDir(cwd, sessionId);
+}
+
+/** "The current agent's store" that orchestrate's store layout writes into: one directory per session. */
+export function storeDir(cwd: string, sessionId: string): string {
+  return join(workspaceStateDir(cwd), 'store', sessionId);
+}

package/src/plan.ts

@@ -0,0 +1,141 @@
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { createReadonlyBashTool, releaseReadonlySandbox } from './readonly-shell.ts';
+
+export const PLAN_ENTRY = 'pstack/plan';
+const STATUS_KEY = 'pstack-plan';
+
+/**
+ * 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 tools plan mode keeps active. Names that are not registered are ignored by `setActiveTools`. */
+export const PLAN_TOOLS = ['read', 'grep', 'find', 'ls', PLAN_BASH, 'AskQuestion', 'TodoWrite', 'agent_status', 'Task'] as const;
+const ALLOWED = new Set<string>(PLAN_TOOLS);
+
+export type PlanCommand = { kind: 'status' } | { kind: 'off' } | { kind: 'on'; task: string };
+
+export function parsePlanArgs(args: string): PlanCommand {
+  const trimmed = args.trim();
+  if (trimmed === '') return { kind: 'status' };
+  if (trimmed === 'off') return { kind: 'off' };
+  if (trimmed === 'on') return { kind: 'on', task: '' };
+  return { kind: 'on', task: trimmed };
+}
+
+/** What a session entry stores: whether plan mode is on, and the tools to restore when it ends. */
+export interface PlanState {
+  enabled: boolean;
+  toolsBefore?: string[];
+}
+
+interface BranchEntry {
+  type: string;
+  customType?: string;
+  data?: unknown;
+}
+
+/** The last plan entry on the branch; anything malformed counts as off. */
+export function planFromBranch(entries: readonly BranchEntry[]): PlanState {
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index];
+    if (entry?.type !== 'custom' || entry.customType !== PLAN_ENTRY) continue;
+    const data = entry.data as { enabled?: unknown; toolsBefore?: unknown } | null;
+    if (data?.enabled !== true) return { enabled: false };
+    const tools = data.toolsBefore;
+    return Array.isArray(tools) && tools.every((name) => typeof name === 'string') ? { enabled: true, toolsBefore: tools as string[] } : { enabled: true };
+  }
+  return { enabled: false };
+}
+
+/** Why a call is refused in plan mode, or undefined when it may run. */
+export function planBlockReason(toolName: string): string | undefined {
+  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(', ')}.`;
+}
+
+export function planSection(): 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), AskQuestion, TodoWrite, agent_status, and 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. 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.',
+    'The user leaves plan mode with /plan off to execute the plan.',
+  ].join('\n');
+}
+
+// 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];
+
+/** The tools plan mode activates, given the tools active before it. */
+export function planTools(before: readonly string[]): string[] {
+  return [...new Set([...ALWAYS, ...before.filter((name) => ALLOWED.has(name))])];
+}
+
+export function registerPlanMode(pi: ExtensionAPI): { section: () => string | undefined; enabled: () => boolean } {
+  let state: PlanState = { enabled: false };
+
+  // Inactive until plan mode turns it on.
+  pi.registerTool({ ...createReadonlyBashTool(PLAN_BASH), defaultActive: false });
+  pi.on('session_shutdown', releaseReadonlySandbox);
+
+  const show = (ctx: ExtensionContext) => {
+    if (ctx.hasUI) ctx.ui.setStatus(STATUS_KEY, state.enabled ? ctx.ui.theme.fg('warning', 'plan') : undefined);
+  };
+
+  const enable = (toolsBefore: string[]) => {
+    state = { enabled: true, toolsBefore };
+    pi.setActiveTools(planTools(toolsBefore));
+  };
+  const disable = () => {
+    const before = state.toolsBefore ?? pi.getActiveTools();
+    state = { enabled: false };
+    pi.setActiveTools(before.filter((name) => name !== PLAN_BASH));
+  };
+
+  const restore = (ctx: ExtensionContext) => {
+    const stored = planFromBranch(ctx.sessionManager.getBranch());
+    if (stored.enabled) enable(stored.toolsBefore ?? state.toolsBefore ?? pi.getActiveTools());
+    else if (state.enabled) disable();
+    else if (pi.getActiveTools().includes(PLAN_BASH)) pi.setActiveTools(pi.getActiveTools().filter((name) => name !== PLAN_BASH));
+    show(ctx);
+  };
+  pi.on('session_start', (_event, ctx) => restore(ctx));
+  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
+  // invents. Task runs: it reads `enabled` and makes each launch readonly and local without changing its input,
+  // so the restriction never reaches an agent's record.
+  pi.on('tool_call', (event) => {
+    if (!state.enabled) return undefined;
+    const reason = planBlockReason(event.toolName);
+    return reason === undefined ? undefined : { block: true, reason };
+  });
+
+  const handle = (args: string, ctx: ExtensionCommandContext) => {
+    const command = parsePlanArgs(args);
+    if (command.kind === 'status') return ctx.ui.notify(state.enabled ? 'Plan mode is on. /plan off exits.' : 'Plan mode is off. /plan [task] turns it on.', 'info');
+    if (command.kind === 'off') {
+      if (state.enabled) disable();
+    } else if (!state.enabled) enable(pi.getActiveTools());
+    pi.appendEntry(PLAN_ENTRY, state);
+    show(ctx);
+    ctx.ui.notify(state.enabled ? 'Plan mode on: read-only tools only. /plan off exits.' : 'Plan mode off: tools restored.', 'info');
+    if (command.kind === 'on' && command.task !== '') pi.sendUserMessage(command.task, { expandPromptTemplates: true, ...(ctx.isIdle() ? {} : { deliverAs: 'followUp' as const }) });
+    return undefined;
+  };
+
+  pi.registerCommand('plan', {
+    description: 'Plan mode: read-only tools, investigate and produce a plan. /plan [task], /plan off, /plan',
+    getArgumentCompletions: (prefix) => ['off'].filter((name) => name.startsWith(prefix.trim())).map((name) => ({ value: name, label: name })),
+    handler: async (args, ctx) => {
+      handle(args, ctx);
+    },
+  });
+
+  return { section: () => (state.enabled ? planSection() : undefined), enabled: () => state.enabled };
+}