@pify/plan-mode 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pifydev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# @pify/plan-mode
+
+Read-only planning mode for [pi](https://github.com/earendil-works/pi) with an explicit approve-then-execute gate — enforced at the tool level, not just prompted.
+
+Part of the [Pify suite](https://github.com/pifydev). Install with [`pify install plan-mode`](https://github.com/pifydev/cli) or `pi install npm:@pify/plan-mode`.
+
+## What it does
+
+- **Two ways in**: you type `/plan` (or `pi --plan`, or `Ctrl+Alt+P`) — or the agent itself calls `enter_plan_mode` before a complex task and tells you.
+- **Real enforcement** via the `tool_call` hook while planning:
+  - `edit`/`write` are blocked — except on the current plan file (guarded plan editing);
+  - `bash` runs through a three-tier classifier: known read-only commands run, known mutators (rm/mv/npm install/git commit/redirects/…) are blocked, unknown commands ask you once;
+  - unknown custom tools need a one-time confirmation; suite read-only tools (memory_read, goal_status, …) pass.
+- **Plans are files**: `write_plan` creates `.pi/plans/YYYY-MM-DD-<slug>.md` — reviewable, editable during planning, committable.
+- **Claude-style exit gate**: `exit_plan_mode` presents up to 3 alternative approaches ("(Recommended)" marked) and an approval menu — implement here, implement in a **fresh session** (handoff message included), revise with feedback, or discard.
+- **Thinking split**: entering plan mode raises the thinking level to `high`; your previous level is restored on exit.
+- **Persistent**: mode and plan file survive `/reload`, resume, and branch switches; a `📋 plan` footer badge shows while active.
+
+> Plan mode is tool-level workflow protection, not a sandbox: a command you confirm can still do anything you can.
+
+## Usage
+
+```
+/plan                      # toggle plan mode
+/plan add oauth login      # enter + start planning this
+/plan off                  # leave without approval
+pi --plan                  # start a session already in plan mode
+```
+
+## Conflicts
+
+`@pify/plan-mode` registers the `--plan` flag and `/plan` command, so it cannot run alongside `@narumitw/pi-plan-mode` or other plan extensions. Remove those first:
+
+```bash
+pi remove npm:@narumitw/pi-plan-mode
+pify install plan-mode
+```
+
+## License
+
+MIT © [Pify maintainers](https://github.com/pifydev)

package/extensions/plan-mode.ts

@@ -0,0 +1,382 @@
+/**
+ * @pify/plan-mode — read-only planning with an explicit approve-then-execute
+ * gate.
+ *
+ * Two ways in: the user types /plan (or starts pi with --plan, or presses
+ * ctrl+alt+p), or the agent calls enter_plan_mode before a complex task
+ * (Kimi/Claude-style). While active, mutations are blocked at the tool_call
+ * hook: edit/write allowed only on the current plan file, bash runs through a
+ * three-tier read-only classifier (safe list → confirm → block), unknown
+ * custom tools need one-time confirmation. Plans are markdown files in
+ * .pi/plans/. exit_plan_mode presents up to 3 alternative approaches and an
+ * approval menu; approval implements here or hands off to a fresh session.
+ *
+ * This is tool-level workflow protection, not a sandbox.
+ *
+ * Design synthesis: tool_call enforcement + review flow (@narumitw/
+ * pi-plan-mode), guarded plan-file editing + fresh-session handoff
+ * (janvitos/pi-plan-build), agent-initiated tools + approach options
+ * (pi-muselinn-harness), three-tier shell policy + thinking split
+ * (@bacnh85/pi-plan), hidden system reminders (juanibiapina/pi-plan).
+ */
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { classifyToolCall } from "../src/policy.ts";
+import { createPlanFile } from "../src/plans.ts";
+import {
+  ENTER_REMINDER,
+  EXIT_REMINDER,
+  buildHandoffMessage,
+  buildImplementHereMessage,
+} from "../src/prompts.ts";
+import { PLAN_STATE, replayBranch } from "../src/state.ts";
+import { INITIAL_STATE, PLAN_THINKING, type PlanState } from "../src/types.ts";
+
+const REMINDER_TYPE = "plan-mode-reminder";
+
+type UiContext = ExtensionContext;
+
+export default function planMode(pi: ExtensionAPI) {
+  let state: PlanState = INITIAL_STATE;
+  const approvedTools = new Set<string>();
+
+  // ── State & UI plumbing ──────────────────────────────────────────────
+
+  function commit(ctx: UiContext, next: PlanState): void {
+    state = next;
+    pi.appendEntry(PLAN_STATE, next);
+    updateBadge(ctx);
+  }
+
+  function updateBadge(ctx: UiContext): void {
+    if (!ctx.hasUI) return;
+    ctx.ui.setStatus("plan", state.active ? "📋 plan" : undefined);
+  }
+
+  function notify(ctx: UiContext, message: string, level: "info" | "warning" | "error"): void {
+    if (ctx.hasUI) ctx.ui.notify(message, level);
+  }
+
+  function sendReminder(content: string): void {
+    pi.sendMessage({ customType: REMINDER_TYPE, content, display: false });
+  }
+
+  // ── Enter / exit ─────────────────────────────────────────────────────
+
+  function enterPlanMode(ctx: UiContext): boolean {
+    if (state.active) return false;
+    const buildThinking = pi.getThinkingLevel();
+    commit(ctx, {
+      active: true,
+      planFile: null,
+      buildThinking,
+      enteredAt: Date.now(),
+    });
+    try {
+      // Planning earns deeper thought (bacnh85); restored on exit.
+      pi.setThinkingLevel(PLAN_THINKING as never);
+    } catch {
+      // model may not support it; fine
+    }
+    sendReminder(ENTER_REMINDER);
+    notify(ctx, "Plan mode ON — read-only. Write the plan with write_plan, submit with exit_plan_mode.", "info");
+    return true;
+  }
+
+  function leavePlanMode(ctx: UiContext): void {
+    if (!state.active) return;
+    const restore = state.buildThinking;
+    commit(ctx, { ...INITIAL_STATE });
+    approvedTools.clear();
+    if (restore) {
+      try {
+        pi.setThinkingLevel(restore as never);
+      } catch {
+        // fine
+      }
+    }
+    sendReminder(EXIT_REMINDER);
+    notify(ctx, "Plan mode OFF.", "info");
+  }
+
+  // ── Enforcement ──────────────────────────────────────────────────────
+
+  pi.on("tool_call", async (event, ctx) => {
+    if (!state.active) return undefined;
+
+    const verdict = classifyToolCall({
+      toolName: event.toolName,
+      input: (event as { input?: unknown }).input,
+      planFile: state.planFile,
+      approvedTools,
+    });
+
+    if (verdict.kind === "allow") return undefined;
+
+    if (verdict.kind === "confirm") {
+      if (!ctx.hasUI) {
+        return { block: true, reason: `Plan mode: ${verdict.reason} (no UI to confirm — blocked).` };
+      }
+      const ok = await ctx.ui.confirm(
+        "Plan mode",
+        `Allow this while planning?\n${verdict.reason}`,
+      );
+      if (ok) {
+        // Bash confirmations are per-command; custom tools are remembered.
+        if (event.toolName !== "bash") approvedTools.add(event.toolName);
+        return undefined;
+      }
+      return { block: true, reason: `Plan mode: the user declined (${verdict.reason}).` };
+    }
+
+    return { block: true, reason: verdict.reason };
+  });
+
+  // ── Lifecycle ────────────────────────────────────────────────────────
+
+  pi.on("session_start", async (_event, ctx) => {
+    state = replayBranch(ctx.sessionManager.getBranch() as never);
+    approvedTools.clear();
+    if (!state.active && pi.getFlag("plan") === true) {
+      enterPlanMode(ctx);
+      return;
+    }
+    updateBadge(ctx);
+  });
+
+  pi.on("session_tree", async (_event, ctx) => {
+    state = replayBranch(ctx.sessionManager.getBranch() as never);
+    approvedTools.clear();
+    updateBadge(ctx);
+  });
+
+  pi.registerFlag("plan", {
+    description: "Start the session in plan mode (read-only planning)",
+    type: "boolean",
+    default: false,
+  });
+
+  // ── Agent tools ──────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: "enter_plan_mode",
+    label: "Enter plan mode",
+    description:
+      "Switch into read-only plan mode before a complex or risky implementation task. Explore with " +
+      "read-only tools, write the plan with write_plan, then submit it with exit_plan_mode. " +
+      "Use when the task spans multiple files, has unclear requirements, or the user asked for a plan.",
+    parameters: Type.Object({}),
+    async execute(_id, _params, _signal, _onUpdate, ctx) {
+      const entered = enterPlanMode(ctx as UiContext);
+      return {
+        content: [
+          {
+            type: "text",
+            text: entered
+              ? "Plan mode activated. Explore read-only, write the plan with write_plan, submit with exit_plan_mode."
+              : "Plan mode is already active.",
+          },
+        ],
+        details: { state },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "write_plan",
+    label: "Write plan",
+    description:
+      "Write the implementation plan to a markdown file under .pi/plans/. Include the goal, concrete " +
+      "steps, files to touch, verification strategy, and open risks. The created file becomes editable " +
+      "(edit/write are unblocked for it) so the plan can be refined before exit_plan_mode.",
+    parameters: Type.Object({
+      title: Type.String({ description: "Short plan title (used for the filename)" }),
+      content: Type.String({ description: "Full plan in markdown" }),
+    }),
+    async execute(_id, params: { title: string; content: string }, _signal, _onUpdate, ctx) {
+      if (!state.active) {
+        throw new Error("write_plan only works in plan mode. Call enter_plan_mode first.");
+      }
+      const file = createPlanFile((ctx as UiContext).cwd, params.title, params.content);
+      commit(ctx as UiContext, { ...state, planFile: file });
+      return {
+        content: [{ type: "text", text: `Plan written to ${file}. Refine it or call exit_plan_mode.` }],
+        details: { file },
+      };
+    },
+  });
+
+  const APPROVE_HERE = "Approve — implement here";
+  const APPROVE_FRESH = "Approve — implement in a fresh session";
+  const REVISE = "Revise the plan";
+  const DISCARD = "Discard and exit plan mode";
+
+  pi.registerTool({
+    name: "exit_plan_mode",
+    label: "Exit plan mode",
+    description:
+      "Submit the plan for user approval. Write the plan with write_plan first. Optionally offer 1-3 " +
+      "alternative approaches (label + description; append '(Recommended)' to your recommended one; " +
+      "labels must not be Approve/Revise/Discard). The user approves, asks for revisions, or discards.",
+    parameters: Type.Object({
+      summary: Type.String({ description: "One-paragraph summary of the plan for the approval dialog" }),
+      options: Type.Optional(
+        Type.Array(
+          Type.Object({
+            label: Type.String({ description: "Approach name, max 80 chars" }),
+            description: Type.String({ description: "Trade-offs of this approach" }),
+          }),
+          { maxItems: 3 },
+        ),
+      ),
+    }),
+    async execute(
+      _id,
+      params: { summary: string; options?: Array<{ label: string; description: string }> },
+      _signal,
+      _onUpdate,
+      ctx,
+    ) {
+      if (!state.active) {
+        throw new Error("Plan mode is not active. Call enter_plan_mode first.");
+      }
+      const uiCtx = ctx as UiContext;
+      if (!uiCtx.hasUI) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "No UI available for the approval dialog. Staying in plan mode — ask the user directly how to proceed.",
+            },
+          ],
+          details: {},
+        };
+      }
+
+      // Step 1: pick an approach when alternatives were offered.
+      let approach: string | null = null;
+      const approaches = (params.options ?? []).filter((o) => o.label.trim());
+      if (approaches.length > 0) {
+        const lines = approaches.map((o) => `${o.label}: ${o.description}`).join("\n");
+        const picked = await uiCtx.ui.select(
+          `Plan approaches\n${params.summary}\n\n${lines}`,
+          [...approaches.map((o) => o.label), REVISE, DISCARD],
+        );
+        if (picked === undefined || picked === REVISE) {
+          const feedback = picked === REVISE ? await uiCtx.ui.input("What should change?") : undefined;
+          return {
+            content: [
+              { type: "text", text: `The user wants revisions.${feedback ? ` Feedback: ${feedback}` : ""} Stay in plan mode and refine the plan.` },
+            ],
+            details: {},
+          };
+        }
+        if (picked === DISCARD) {
+          leavePlanMode(uiCtx);
+          return {
+            content: [{ type: "text", text: "The user discarded the plan. Plan mode is off; await further instructions." }],
+            details: {},
+          };
+        }
+        approach = picked;
+      }
+
+      // Step 2: approve where?
+      const decision = await uiCtx.ui.select(
+        `Approve this plan?\n${params.summary}${state.planFile ? `\n\nPlan file: ${state.planFile}` : ""}`,
+        approaches.length > 0 ? [APPROVE_HERE, APPROVE_FRESH] : [APPROVE_HERE, APPROVE_FRESH, REVISE, DISCARD],
+      );
+
+      if (decision === undefined || decision === REVISE) {
+        const feedback = decision === REVISE ? await uiCtx.ui.input("What should change?") : undefined;
+        return {
+          content: [
+            { type: "text", text: `The user wants revisions.${feedback ? ` Feedback: ${feedback}` : ""} Stay in plan mode and refine the plan.` },
+          ],
+          details: {},
+        };
+      }
+      if (decision === DISCARD) {
+        leavePlanMode(uiCtx);
+        return {
+          content: [{ type: "text", text: "The user discarded the plan. Plan mode is off; await further instructions." }],
+          details: {},
+        };
+      }
+
+      const planFile = state.planFile;
+      leavePlanMode(uiCtx);
+
+      if (decision === APPROVE_FRESH) {
+        try {
+          const handoff = buildHandoffMessage(planFile, approach);
+          // newSession lives on the command context; tool ctx may carry it
+          // too at runtime — probe structurally and fall back if absent.
+          const sessionHost = uiCtx as unknown as {
+            newSession?: (options: {
+              withSession: (ctx: { sendUserMessage: (m: string) => void | Promise<void> }) => Promise<void>;
+            }) => Promise<{ cancelled: boolean }>;
+          };
+          if (!sessionHost.newSession) throw new Error("newSession unavailable in this context");
+          await sessionHost.newSession({
+            withSession: async (replacementCtx) => {
+              await replacementCtx.sendUserMessage(handoff);
+            },
+          });
+          return {
+            content: [{ type: "text", text: "Approved. A fresh session was started with the plan handoff." }],
+            details: { planFile, approach },
+          };
+        } catch (err) {
+          notify(uiCtx, `Fresh session failed (${err instanceof Error ? err.message : String(err)}) — implementing here.`, "warning");
+        }
+      }
+
+      pi.sendUserMessage(buildImplementHereMessage(planFile, approach), { deliverAs: "followUp" });
+      return {
+        content: [{ type: "text", text: "Approved. Implementation instructions were queued — plan mode is off." }],
+        details: { planFile, approach },
+      };
+    },
+  });
+
+  // ── Command & shortcut ───────────────────────────────────────────────
+
+  pi.registerCommand("plan", {
+    description: "Toggle read-only plan mode: /plan [off | <first planning prompt>]",
+    handler: async (args, ctx) => {
+      const text = (args ?? "").trim();
+      if (text.toLowerCase() === "off") {
+        if (!state.active) {
+          notify(ctx, "Plan mode is not active.", "info");
+          return;
+        }
+        leavePlanMode(ctx);
+        return;
+      }
+      if (state.active && !text) {
+        leavePlanMode(ctx);
+        return;
+      }
+      enterPlanMode(ctx);
+      if (text) {
+        pi.sendUserMessage(text);
+      }
+    },
+  });
+
+  pi.registerShortcut("ctrl+alt+p", {
+    description: "Toggle plan mode",
+    handler: async (ctx) => {
+      if (state.active) {
+        leavePlanMode(ctx as UiContext);
+      } else {
+        enterPlanMode(ctx as UiContext);
+      }
+    },
+  });
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@pify/plan-mode",
+  "version": "0.1.0",
+  "description": "Read-only planning mode for pi with an explicit approve-then-execute gate: enforced tool policy, plan files, approach options, fresh-session handoff",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "pify",
+    "plan-mode"
+  ],
+  "homepage": "https://github.com/pifydev/plan-mode#readme",
+  "bugs": {
+    "url": "https://github.com/pifydev/plan-mode/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pifydev/plan-mode.git"
+  },
+  "license": "MIT",
+  "author": "Pify maintainers",
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "extensions",
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": ["./extensions/plan-mode.ts"],
+    "skills": ["./skills"]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": { "optional": true },
+    "typebox": { "optional": true }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@types/node": "^22.10.2",
+    "typebox": "^1.1.38",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/plan-mode/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: plan-mode
+description: Use when a task is complex, risky, spans many files, or the user asks for a plan first - explains the plan-mode workflow (enter_plan_mode, write_plan, exit_plan_mode approval gate) and the read-only discipline
+---
+
+# Plan mode
+
+This project has the `@pify/plan-mode` extension installed. It provides a
+read-only planning phase with an explicit approve-then-execute gate.
+
+## When to enter plan mode yourself (enter_plan_mode)
+
+- The task spans multiple files or subsystems.
+- Requirements are ambiguous and worth clarifying before touching code.
+- The change is risky (migrations, deletions, public APIs).
+- The user says "plan first", "don't code yet", or similar.
+
+Do not enter plan mode for trivial single-file edits.
+
+## The workflow
+
+1. `enter_plan_mode` — switches to read-only; thinking level is raised.
+2. Explore with read, grep, find, ls, and read-only shell commands. Mutating
+   commands are blocked; unknown ones ask the user. Do not fight the policy —
+   fold blocked actions into the plan instead.
+3. Ask the user clarifying questions rather than assuming intent.
+4. `write_plan` — write the full plan (goal, concrete steps, files to touch,
+   verification, risks) to `.pi/plans/`. The plan file itself stays editable.
+5. `exit_plan_mode` — submit with a one-paragraph summary; optionally offer
+   1-3 alternative approaches, marking one "(Recommended)". The user approves
+   (here or in a fresh session), requests revisions, or discards.
+6. After approval, implement the plan exactly; report any deviation.
+
+## While plan mode is active
+
+- Never promise to make changes now; everything lands in the plan.
+- A blocked tool call is a policy decision, not an error to retry.

package/src/plans.ts

@@ -0,0 +1,41 @@
+import { mkdirSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+/** Plan files live in .pi/plans/, reviewable and committable. */
+export function plansDir(cwd: string): string {
+  return join(cwd, ".pi", "plans");
+}
+
+export function slugify(title: string): string {
+  const slug = title
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[̀-ͯ]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+  return slug || "plan";
+}
+
+function pad2(n: number): string {
+  return String(n).padStart(2, "0");
+}
+
+export function localDateStr(d: Date = new Date()): string {
+  return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
+}
+
+/** Create the plan file, uniquified when the slug collides on the same day. */
+export function createPlanFile(cwd: string, title: string, content: string): string {
+  const dir = plansDir(cwd);
+  mkdirSync(dir, { recursive: true });
+  const base = `${localDateStr()}-${slugify(title)}`;
+  let file = join(dir, `${base}.md`);
+  let counter = 2;
+  while (existsSync(file)) {
+    file = join(dir, `${base}-${counter}.md`);
+    counter++;
+  }
+  writeFileSync(file, content.endsWith("\n") ? content : `${content}\n`);
+  return file;
+}

package/src/policy.ts

@@ -0,0 +1,75 @@
+import { resolve } from "node:path";
+import { classifyShellCommand } from "./shell.ts";
+import type { PolicyVerdict } from "./types.ts";
+
+/**
+ * Tool-call policy while plan mode is active (enforced via the tool_call
+ * block hook — the lesson from juanibiapina's deprecation is that an
+ * extension earns its existence through real enforcement, not prompts).
+ */
+
+const READ_ONLY_BUILTINS = new Set(["read", "grep", "find", "ls"]);
+
+/** Suite tools that are read-only by design and safe during planning. */
+const SAFE_TOOL_PREFIXES = ["memory_read", "memory_search", "goal_status", "write_plan", "exit_plan_mode", "enter_plan_mode"];
+
+export interface PolicyInput {
+  toolName: string;
+  input: unknown;
+  planFile: string | null;
+  /** Custom tool names the user already confirmed this session. */
+  approvedTools: ReadonlySet<string>;
+}
+
+function samePath(a: string, b: string): boolean {
+  const norm = (p: string) => resolve(p).replaceAll("\\", "/").toLowerCase();
+  return norm(a) === norm(b);
+}
+
+export function classifyToolCall(call: PolicyInput): PolicyVerdict {
+  const { toolName } = call;
+
+  if (READ_ONLY_BUILTINS.has(toolName)) return { kind: "allow" };
+
+  if (toolName === "edit" || toolName === "write") {
+    const path = (call.input as { path?: unknown })?.path;
+    if (typeof path === "string" && call.planFile && samePath(path, call.planFile)) {
+      // Guarded plan-file editing (janvitos): the plan itself is writable.
+      return { kind: "allow" };
+    }
+    return {
+      kind: "block",
+      reason: call.planFile
+        ? `Plan mode blocks '${toolName}' except on the current plan file (${call.planFile}). Use write_plan first if you have no plan file.`
+        : `Plan mode blocks '${toolName}'. Create a plan with write_plan; implementation starts after exit_plan_mode is approved.`,
+    };
+  }
+
+  if (toolName === "bash") {
+    const command = (call.input as { command?: unknown })?.command;
+    if (typeof command !== "string") return { kind: "block", reason: "bash call without a command" };
+    const verdict = classifyShellCommand(command);
+    if (verdict.kind === "block") {
+      return { kind: "block", reason: `Plan mode blocks this command: ${verdict.reason}.` };
+    }
+    return verdict;
+  }
+
+  if (toolName === "powershell") {
+    return {
+      kind: "block",
+      reason: "Plan mode blocks powershell (no read-only classifier). Use the bash tool for read-only inspection.",
+    };
+  }
+
+  if (SAFE_TOOL_PREFIXES.some((p) => toolName === p || toolName.startsWith(`${p}:`))) {
+    return { kind: "allow" };
+  }
+
+  if (call.approvedTools.has(toolName)) return { kind: "allow" };
+
+  return {
+    kind: "confirm",
+    reason: `custom tool '${toolName}' is not known to be read-only`,
+  };
+}

package/src/prompts.ts

@@ -0,0 +1,43 @@
+/**
+ * Plan-mode system reminders, delivered as hidden custom messages (model
+ * sees them, TUI does not). Adapted from juanibiapina's pi-plan text with
+ * the write_plan / exit_plan_mode workflow added.
+ */
+
+export const ENTER_REMINDER = `<system-reminder>
+Plan mode is ACTIVE — you are in a READ-ONLY planning phase.
+
+STRICTLY FORBIDDEN: any file edits, modifications, or system changes. Mutating
+shell commands are blocked; unknown commands need user confirmation. This
+constraint overrides all other instructions, including direct user requests to
+edit — acknowledge such requests and fold them into the plan instead.
+
+Your responsibility now: think, read, search, and discuss to construct a
+well-formed implementation plan. Ask clarifying questions rather than assuming
+intent. When the plan is ready:
+1. Write it to a file with write_plan (goal first, then concrete steps,
+   files to touch, verification strategy, open risks).
+2. Call exit_plan_mode — optionally with 1-3 alternative approaches — to
+   submit it for user approval. Implementation begins only after approval.
+</system-reminder>`;
+
+export const EXIT_REMINDER = `<system-reminder>
+Plan mode is OFF. You are no longer read-only: file edits, shell commands,
+and the full tool set are available again.
+</system-reminder>`;
+
+/** Follow-up sent after the user approves implementing in this session. */
+export function buildImplementHereMessage(planFile: string | null, approach: string | null): string {
+  const approachLine = approach ? ` using the approved approach: ${approach}` : "";
+  return planFile
+    ? `The plan was approved${approachLine}. Read ${planFile} and implement it fully. Verify as you go; report deviations from the plan.`
+    : `The plan was approved${approachLine}. Implement it fully as discussed. Verify as you go.`;
+}
+
+/** First message of a fresh implementation session (janvitos-style handoff). */
+export function buildHandoffMessage(planFile: string | null, approach: string | null): string {
+  const approachLine = approach ? `\nApproved approach: ${approach}` : "";
+  return planFile
+    ? `Implement the approved plan in ${planFile}.${approachLine}\nRead the plan file first, then execute it fully. Verify as you go; report deviations.`
+    : `Implement the plan we agreed on.${approachLine}`;
+}

package/src/shell.ts

@@ -0,0 +1,101 @@
+import type { PolicyVerdict } from "./types.ts";
+
+/**
+ * Three-tier shell policy for plan mode (bacnh85's design):
+ * known read-only commands run automatically, known mutators are blocked
+ * outright, and everything else needs a one-time user confirmation.
+ *
+ * This is tool-level workflow protection, NOT a sandbox (doompi's honest
+ * caveat): a confirmed command can still do anything the user can.
+ */
+
+const SAFE_COMMANDS = new Set([
+  "ls", "cat", "head", "tail", "less", "more", "wc", "file", "stat", "du", "df",
+  "grep", "egrep", "fgrep", "rg", "find", "fd", "tree", "dirname", "basename",
+  "pwd", "whoami", "which", "where", "type", "env", "printenv", "date", "uname",
+  "echo", "printf", "sort", "uniq", "cut", "tr", "diff", "cmp", "md5sum",
+  "sha256sum", "readlink", "realpath", "jq", "yq", "column", "nl", "strings",
+  "node", "python", "python3", "bun", "deno",
+]);
+
+/** git subcommands that only read. Everything else confirms/blocks. */
+const SAFE_GIT_SUBCOMMANDS = new Set([
+  "status", "log", "diff", "show", "branch", "tag", "remote", "blame",
+  "shortlog", "describe", "rev-parse", "rev-list", "ls-files", "ls-remote",
+  "ls-tree", "cat-file", "reflog", "stash list", "config --get", "grep",
+]);
+
+const MUTATOR_COMMANDS = new Set([
+  "rm", "rmdir", "mv", "cp", "mkdir", "touch", "tee", "chmod", "chown", "ln",
+  "dd", "truncate", "shred", "install", "patch", "rsync", "curl", "wget",
+  "npm", "npx", "yarn", "pnpm", "pip", "pip3", "cargo", "gem", "brew", "apt",
+  "apt-get", "yum", "dnf", "choco", "winget", "scoop", "sudo", "kill",
+  "killall", "shutdown", "reboot",
+]);
+
+const MUTATOR_GIT_SUBCOMMANDS = [
+  "commit", "push", "add", "rm", "mv", "reset", "checkout", "switch", "merge",
+  "rebase", "cherry-pick", "revert", "clean", "stash push", "stash pop",
+  "stash drop", "apply", "am", "fetch", "pull", "clone", "init", "restore",
+  "config --set", "config --global", "config --local",
+];
+
+/** Split a shell line on operators; each segment is judged independently. */
+export function splitSegments(command: string): string[] {
+  return command
+    .split(/(?:\|\||&&|;|\|)/)
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/** Strip leading VAR=value assignments so env prefixes cannot mask commands. */
+function stripEnvPrefix(segment: string): string {
+  return segment.replace(/^(?:[A-Za-z_][A-Za-z0-9_]*=\S*\s+)+/, "");
+}
+
+function leadingCommand(segment: string): string {
+  const first = stripEnvPrefix(segment).split(/\s+/)[0] ?? "";
+  return first.replace(/^["']|["']$/g, "").split(/[\\/]/).pop()?.toLowerCase() ?? "";
+}
+
+/** Redirects can write files; only /dev/null and stderr merges are harmless. */
+export function hasWritingRedirect(command: string): boolean {
+  const cleaned = command
+    .replace(/2>&1/g, "")
+    .replace(/[0-9]?>>?\s*\/dev\/null/g, "")
+    .replace(/[0-9]?>\s*&[0-9]/g, "");
+  return />/.test(cleaned);
+}
+
+export function classifyShellCommand(command: string): PolicyVerdict {
+  const trimmed = command.trim();
+  if (!trimmed) return { kind: "allow" };
+
+  if (hasWritingRedirect(trimmed)) {
+    return { kind: "block", reason: "output redirection writes files" };
+  }
+
+  for (const segment of splitSegments(trimmed)) {
+    const cmd = leadingCommand(segment);
+    if (cmd === "git") {
+      const rest = stripEnvPrefix(segment).replace(/^\S+\s*/, "").trim();
+      if (MUTATOR_GIT_SUBCOMMANDS.some((m) => rest.startsWith(m))) {
+        return { kind: "block", reason: `git ${rest.split(/\s+/)[0]} mutates the repository` };
+      }
+      const safe = [...SAFE_GIT_SUBCOMMANDS].some((s) => rest.startsWith(s));
+      if (!safe) return { kind: "confirm", reason: `unrecognized git subcommand: ${rest.split(/\s+/)[0] ?? ""}` };
+      continue;
+    }
+    if (MUTATOR_COMMANDS.has(cmd)) {
+      return { kind: "block", reason: `'${cmd}' modifies the system` };
+    }
+    if (!SAFE_COMMANDS.has(cmd)) {
+      return { kind: "confirm", reason: `unrecognized command: '${cmd}'` };
+    }
+    // Safe interpreters running inline code can still write files.
+    if (["node", "python", "python3", "bun", "deno"].includes(cmd) && /\s-(e|c|p|-eval)\b/.test(segment)) {
+      return { kind: "confirm", reason: `inline ${cmd} code can modify files` };
+    }
+  }
+  return { kind: "allow" };
+}

package/src/state.ts

@@ -0,0 +1,20 @@
+import { INITIAL_STATE, isRecord, type BranchEntryLike, type PlanState } from "./types.ts";
+
+export const PLAN_STATE = "plan-mode-state";
+
+/** Snapshot-based replay: the last plan-mode-state entry on the branch wins. */
+export function replayBranch(entries: BranchEntryLike[]): PlanState {
+  let state: PlanState = INITIAL_STATE;
+  for (const entry of entries) {
+    if (entry.type !== "custom" || entry.customType !== PLAN_STATE) continue;
+    const data = entry.data;
+    if (!isRecord(data) || typeof data.active !== "boolean") continue;
+    state = {
+      active: data.active,
+      planFile: typeof data.planFile === "string" ? data.planFile : null,
+      buildThinking: typeof data.buildThinking === "string" ? data.buildThinking : null,
+      enteredAt: typeof data.enteredAt === "number" ? data.enteredAt : null,
+    };
+  }
+  return state;
+}

package/src/types.ts

@@ -0,0 +1,40 @@
+/**
+ * Local structural types for @pify/plan-mode.
+ * No imports from pi packages: src/ typechecks and runs standalone.
+ */
+
+export interface PlanState {
+  active: boolean;
+  /** Absolute path of the current plan file; edit/write to it is allowed. */
+  planFile: string | null;
+  /** Thinking level to restore when leaving plan mode. */
+  buildThinking: string | null;
+  enteredAt: number | null;
+}
+
+export const INITIAL_STATE: PlanState = {
+  active: false,
+  planFile: null,
+  buildThinking: null,
+  enteredAt: null,
+};
+
+/** Verdict for one tool call while plan mode is active. */
+export type PolicyVerdict =
+  | { kind: "allow" }
+  | { kind: "confirm"; reason: string }
+  | { kind: "block"; reason: string };
+
+/** Thinking level plan mode switches to (planning earns deeper thought). */
+export const PLAN_THINKING = "high";
+
+export interface BranchEntryLike {
+  type?: string;
+  customType?: string;
+  data?: unknown;
+  [key: string]: unknown;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}