@huseynsnmz/pi-modes 0.0.0-stage → 0.1.4

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## [0.1.4]
+
+### Fixed
+
+- Fixed a false "Auto has no permission judge" warning when `pi-permission-classifier` loads after `pi-permission-system`, where it only registers during the first prompt.
+- Moved the "could not take control" check to after every extension has had the chance to register.
+
+## [0.1.3]
+
+### Changed
+
+- Published to npm as `@huseynsnmz/pi-modes`.
+- Added a quick start to the README.
+
+## [0.1.2]
+
+### Changed
+
+- Warns at startup if this extension loads after `pi-permission-system`, which causes needless approval prompts in `plan` and `read-only`.
+
+## [0.1.1]
+
+### Security
+
+- Fixed read-only bash bypasses that could write files or run code in `plan` and `read-only`. These used bundled, attached or abbreviated options (`sort -uo`, `sort --outp`, `fd -Hx`, `tree -ao`, `file -bC`), `uniq - file`, extra options on `git stash list`, and unquoted globs that expand into flags. Upgrade from 0.1.0.
+- Plan-mode prompts now show control and bidirectional characters as visible escapes, so a command can't hide part of itself.
+
+### Changed
+
+- `fd`, `tree` and `file` are no longer treated as read-only. `sort`, `uniq`, `date` and `printf` accept fewer options. These now ask in `plan` and are blocked in `read-only`.
+
+## [0.1.0]
+
+- Added `normal`, `auto`, `plan` and `read-only` modes, switched with `Shift+Tab` or `/mode`.
+- Added plan approval through the `submit_plan` tool.
+- Added per-session control of the `pi-permission-classifier` judge.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hüseyin Sönmez
+
+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

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# pi-modes
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Switch [Pi](https://pi.dev) between permission modes with `Shift+Tab`.
+
+| Mode | What the agent can do | Who approves |
+|---|---|---|
+| `normal` | Anything your permission rules allow | You |
+| `auto` | Anything your permission rules allow | Your permission judge first, then you if it defers |
+| `plan` | Read and research, then submit a plan. No edits | You, for any non-read-only command |
+| `read-only` | Read and research only | Nobody. Everything else is blocked |
+
+`Shift+Tab` cycles `normal → auto → plan → read-only → normal`. The footer shows the current mode.
+
+The mode is saved per session and survives `--continue`. A new session always starts in `normal`, and nothing in a project can change that.
+
+## Quick start
+
+Requires Pi 1.5 or newer.
+
+1. Install it:
+
+   ```bash
+   pi install npm:@huseynsnmz/pi-modes@0.1.4
+   ```
+
+2. Move it above `@gotgenes/pi-permission-system`, because `pi install` adds packages last. Otherwise, in `plan` and `read-only` you may be asked to approve an action that is then blocked anyway. It stays blocked either way, and the extension warns you at startup. Skip this step if you don't use that package.
+
+   ```bash
+   f=~/.pi/agent/settings.json
+   jq '.packages |= (map(select(tostring | contains("pi-modes"))) + map(select(tostring | contains("pi-modes") | not)))' "$f" > "$f.tmp" && mv "$f.tmp" "$f"
+   ```
+
+3. If you use `pi-permission-system`, allow plans so you aren't asked twice:
+
+   ```bash
+   f=~/.pi/agent/extensions/pi-permission-system/config.json
+   jq '.permission.submit_plan = "allow"' "$f" > "$f.tmp" && mv "$f.tmp" "$f"
+   ```
+
+4. Restart Pi. The footer shows `mode: normal`, and `Shift+Tab` changes the mode.
+
+To install from git instead, use `pi install git:github.com/huseynsnmz/pi-modes@v0.1.4`.
+
+## Commands
+
+| Input | What it does |
+|---|---|
+| `Shift+Tab` | Next mode |
+| `/mode` | Pick a mode from a list |
+| `/mode plan` | Switch directly to a mode |
+
+`Shift+Tab` normally cycles the thinking level, and this extension takes it over. To keep that action on another key, add this to `~/.pi/agent/keybindings.json`:
+
+```json
+{ "app.thinking.cycle": "alt+t" }
+```
+
+## How plan mode ends
+
+In plan mode the agent calls the `submit_plan` tool. You then choose one of:
+
+- **Approve, normal:** switches to `normal` and the agent starts implementing.
+- **Approve, auto:** switches to `auto` and the agent starts implementing.
+- **Keep planning:** stays in `plan` and sends your feedback to the agent.
+
+## Using it with other extensions
+
+**`@gotgenes/pi-permission-system`:** still runs in every mode. This extension only adds restrictions, so a `deny` rule always wins.
+
+**`pi-permission-classifier`:** runs only in `auto`. In every other mode it defers, and the request goes to your normal prompt. Set it up as its README describes, with `permission-judge` in `authorizerChain`. Its `perm-judge:` footer entry stays visible in all modes, so go by the `mode:` entry. If the classifier is listed after `pi-permission-system`, it only registers during your first prompt, and `auto` starts working from then on.
+
+Without a classifier, `auto` behaves like `normal`, and the extension warns you when you switch to it.
+
+**`pi-subagents`:** blocked in `plan` and `read-only`, because a child agent could write files. In `normal` and `auto` it is unchanged.
+
+**`pi-look` and `pi-claude-code-ui`:** no conflicts are expected, as neither uses `Shift+Tab`. The mode appears through Pi's standard status API.
+
+## What plan and read-only allow
+
+- **Allowed tools:** `read`, `grep`, `find`, `ls`, read-only `bash`, and `submit_plan` in plan mode.
+- **Blocked tools:** `write`, `edit`, subagents, MCP tools and every other tool, including ones added later.
+- **Read-only bash:** a fixed list of commands, such as `ls`, `cat`, `rg` and `git status`. A command is refused if it uses `$`, backticks, redirects, subshells, background jobs, unquoted globs, control characters or a path to a binary. Options that write or run code are refused too, including bundled and abbreviated forms such as `sort -uo` and `sort --outp`. Quote a glob you mean literally, as in `find . -name '*.ts'`.
+
+Any other command asks you in `plan` and is blocked in `read-only`.
+
+## Security limits
+
+These modes keep an honest agent on track. They are not a sandbox.
+
+- **Reads are not restricted by this extension.** A read-only command can still read secrets, so keep `deny` rules for them in your permission system.
+- **A repo can already be malicious.** Commands like `git status` can run code from an existing `.git/config`, such as `core.fsmonitor`. Use a container for repos you don't trust.
+- **Child agents started earlier keep running.** Switching mode doesn't stop a subagent that is already running.
+- **The classifier hook relies on an internal detail.** There is no public way to switch a registered judge on and off, so this extension wraps it when it registers. It uses the global key that `pi-permission-system` documents for its service map. If that breaks, you get a warning on your first prompt that the judge may auto-approve outside `auto`.
+
+## Development
+
+```bash
+npm install --ignore-scripts
+npm run check
+npm test
+```
+
+The end-to-end test drives real Pi in a real terminal against a fake model, using a throwaway home directory:
+
+```bash
+npm run e2e:solo   # only this extension
+npm run e2e        # with the five packages it was built for, in three load orders
+```
+
+`npm run e2e` installs those packages from npm with scripts disabled, then starts them.
+
+## Contributing
+
+Issues are welcome, and pull requests are turned off. See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@huseynsnmz/pi-modes",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.4",
+  "description": "Shift+Tab permission modes for Pi: normal, auto, plan and read-only",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "permissions",
+    "plan-mode"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/huseynsnmz/pi-modes.git"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "node --test test/*.test.ts",
+    "e2e:solo": "python3 test/e2e/run.py solo",
+    "e2e": "python3 test/e2e/run.py modes-first && python3 test/e2e/run.py modes-last && python3 test/e2e/run.py classifier-last"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.5.0",
+    "@earendil-works/pi-tui": "1.5.0",
+    "@types/node": "24.13.3",
+    "typebox": "1.1.38",
+    "typescript": "6.0.3"
+  }
+}

package/src/bash.ts

@@ -0,0 +1,211 @@
+/**
+ * Decides whether a bash command is safe to run in a restricted mode.
+ *
+ * This is an allowlist that fails closed. Anything the parser cannot prove
+ * read-only is rejected, including shell expansion, globs, redirects, subshells
+ * and background jobs, so a false "no" costs a prompt and never a write. Globs
+ * count because a file named -exec could turn a pattern into a dangerous flag.
+ */
+
+export type BashVerdict = { readOnly: true } | { readOnly: false; reason: string };
+
+const no = (reason: string): BashVerdict => ({ readOnly: false, reason });
+const YES: BashVerdict = { readOnly: true };
+
+type ArgCheck = (args: readonly string[]) => string | null;
+
+const noArgs: ArgCheck = (args) => (args.length === 0 ? null : "takes no arguments here");
+const anyArgs: ArgCheck = () => null;
+
+/**
+ * Rejects a long option if its name could abbreviate a forbidden one, because
+ * getopt_long and git both accept unique prefixes such as --outp for --output.
+ */
+function isForbiddenLong(arg: string, forbidden: readonly string[]): boolean {
+  if (!arg.startsWith("--")) return false;
+  const name = arg.slice(2).split("=", 1)[0] as string;
+  return name !== "" && forbidden.some((flag) => flag.startsWith(name));
+}
+
+function rejectLong(...forbidden: readonly string[]): ArgCheck {
+  return (args) => {
+    const hit = args.find((arg) => isForbiddenLong(arg, forbidden));
+    return hit === undefined ? null : `${hit} can write or run code`;
+  };
+}
+
+/**
+ * Only these flags are allowed. A denylist can't model parsers that accept
+ * bundles and attached values, such as -uo or -ofile.
+ */
+function onlyFlags(allowed: RegExp, maxOperands = Number.POSITIVE_INFINITY): ArgCheck {
+  return (args) => {
+    let operands = 0;
+    for (const arg of args) {
+      if (arg.startsWith("-")) {
+        if (!allowed.test(arg)) return `${arg} is not an allowed option`;
+      } else {
+        operands += 1;
+      }
+    }
+    return operands > maxOperands ? "too many file arguments" : null;
+  };
+}
+
+const FIND_UNSAFE = new Set(["-exec", "-execdir", "-ok", "-okdir", "-delete", "-fprint", "-fprint0", "-fprintf", "-fls"]);
+
+const COMMANDS: Readonly<Record<string, ArgCheck>> = {
+  basename: anyArgs,
+  cat: anyArgs,
+  cd: anyArgs,
+  cut: anyArgs,
+  df: anyArgs,
+  diff: anyArgs,
+  dirname: anyArgs,
+  du: anyArgs,
+  echo: anyArgs,
+  grep: anyArgs,
+  head: anyArgs,
+  id: anyArgs,
+  jq: anyArgs,
+  ls: anyArgs,
+  pwd: noArgs,
+  readlink: anyArgs,
+  realpath: anyArgs,
+  stat: anyArgs,
+  tail: anyArgs,
+  tr: anyArgs,
+  type: anyArgs,
+  uname: anyArgs,
+  wc: anyArgs,
+  which: anyArgs,
+  whoami: noArgs,
+  date: (args) => (args.every((arg) => arg === "-u" || arg.startsWith("+")) ? null : "can only print the date"),
+  printf: (args) => (args[0]?.startsWith("-") ? "options are not allowed" : null),
+  sort: onlyFlags(/^-(?:[bdfghinrsuVM]+|k[\w.,]*|t.?)$/),
+  uniq: onlyFlags(/^-[cdui]+$/, 1),
+  rg: rejectLong("pre", "pre-glob", "hostname-bin"),
+  find: (args) => {
+    const hit = args.find((arg) => FIND_UNSAFE.has(arg));
+    return hit === undefined ? null : `${hit} can write or run code`;
+  },
+  git: gitCheck,
+};
+
+const GIT_READ_ONLY = new Set(["status", "diff", "log", "show", "blame", "rev-parse", "ls-files", "describe", "shortlog"]);
+const GIT_UNSAFE_LONG = ["output", "ext-diff", "textconv", "open-files-in-pager"];
+const GIT_LIST_FLAGS: Readonly<Record<string, ReadonlySet<string>>> = {
+  branch: new Set(["-a", "-r", "-v", "-vv", "--all", "--remotes", "--list", "-l", "--show-current"]),
+  remote: new Set(["-v", "--verbose"]),
+  tag: new Set(["-l", "--list"]),
+};
+
+function gitCheck(args: readonly string[]): string | null {
+  const [sub, ...rest] = args;
+  if (sub === undefined) return "needs a subcommand";
+  if (sub.startsWith("-")) return `global option ${sub} is not allowed`;
+  if (GIT_READ_ONLY.has(sub)) {
+    const hit = rest.find((arg) => arg.startsWith("-O") || isForbiddenLong(arg, GIT_UNSAFE_LONG));
+    return hit === undefined ? null : `${hit} can write or run code`;
+  }
+  const listFlags = GIT_LIST_FLAGS[sub];
+  if (listFlags) {
+    const bad = rest.find((arg) => !listFlags.has(arg));
+    return bad === undefined ? null : `git ${sub} ${bad} is not a listing`;
+  }
+  const exact = rest.join(" ");
+  if ((sub === "stash" || sub === "worktree") && exact === "list") return null;
+  if (sub === "config") {
+    if (exact === "--list" || exact === "-l") return null;
+    if (rest.length === 2 && rest[0] === "--get" && !rest[1]?.startsWith("-")) return null;
+  }
+  return `git ${sub} is not on the read-only list`;
+}
+
+interface Parsed {
+  commands: string[][];
+  error?: string;
+}
+
+/** Splits a command line into argv lists, refusing anything that needs a real shell. */
+function parse(input: string): Parsed {
+  // Includes quoted text: these bytes can disguise a command in a terminal.
+  if (/[\x00-\x08\x0b-\x1f\x7f-\x9f]/.test(input)) return { commands: [], error: "control character" };
+
+  const commands: string[][] = [];
+  let argv: string[] = [];
+  let word = "";
+  let inWord = false;
+  let quote: "'" | '"' | null = null;
+
+  const endWord = () => {
+    if (inWord) argv.push(word);
+    word = "";
+    inWord = false;
+  };
+  const endCommand = () => {
+    endWord();
+    if (argv.length > 0) commands.push(argv);
+    argv = [];
+  };
+
+  for (let i = 0; i < input.length; i += 1) {
+    const ch = input[i] as string;
+    if (quote === "'") {
+      if (ch === "'") quote = null;
+      else word += ch;
+      continue;
+    }
+    if (quote === '"') {
+      if (ch === '"') quote = null;
+      else if (ch === "$" || ch === "`" || ch === "\\") return { commands, error: `${ch} inside double quotes` };
+      else word += ch;
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch;
+      inWord = true;
+      continue;
+    }
+    if (ch === " " || ch === "\t") {
+      endWord();
+      continue;
+    }
+    if (ch === "\n" || ch === ";") {
+      endCommand();
+      continue;
+    }
+    if (ch === "|") {
+      endCommand();
+      if (input[i + 1] === "|") i += 1;
+      continue;
+    }
+    if (ch === "&") {
+      if (input[i + 1] !== "&") return { commands, error: "background job" };
+      endCommand();
+      i += 1;
+      continue;
+    }
+    if ("$`\\<>(){}#!*?[]".includes(ch)) return { commands, error: `shell syntax ${ch}` };
+    word += ch;
+    inWord = true;
+  }
+  if (quote !== null) return { commands, error: "unbalanced quote" };
+  endCommand();
+  return { commands };
+}
+
+export function classifyBash(input: string): BashVerdict {
+  const { commands, error } = parse(input);
+  if (error) return no(error);
+  if (commands.length === 0) return no("empty command");
+
+  for (const [name, ...args] of commands) {
+    if (name === undefined) return no("empty command");
+    if (name.includes("/")) return no(`${name} is run by path`);
+    if (!Object.hasOwn(COMMANDS, name)) return no(`${name} is not on the read-only list`);
+    const problem = (COMMANDS[name] as ArgCheck)(args);
+    if (problem) return no(`${name}: ${problem}`);
+  }
+  return YES;
+}

package/src/index.ts

@@ -0,0 +1,175 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { type ExtensionAPI, type ExtensionContext, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { isKeyRelease, matchesKey, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { clearGate, installJudgeGate, JUDGE_NAMES, judgeGated, setGateMode } from "./judge-gate.ts";
+import { decideToolCall, displayCommand, isMode, loadsAfterPermissionSystem, type Mode, MODES, modePrompt, nextMode, SUBMIT_PLAN_TOOL } from "./modes.ts";
+
+const STATUS_KEY = "pi-modes";
+const ENTRY_TYPE = "pi-modes";
+const CYCLE_KEY = "shift+tab";
+
+const STATUS_COLOR = { normal: "dim", auto: "warning", plan: "accent", "read-only": "success" } as const;
+
+function chainNamesJudge(): boolean {
+  try {
+    const path = join(getAgentDir(), "extensions", "pi-permission-system", "config.json");
+    const chain: unknown = JSON.parse(readFileSync(path, "utf8")).authorizerChain;
+    return Array.isArray(chain) && chain.some((name) => JUDGE_NAMES.has(name));
+  } catch {
+    return false;
+  }
+}
+
+function loadOrderIsLate(): boolean {
+  try {
+    return loadsAfterPermissionSystem(JSON.parse(readFileSync(join(getAgentDir(), "settings.json"), "utf8")).packages);
+  } catch {
+    return false;
+  }
+}
+
+function restoredMode(ctx: ExtensionContext): Mode {
+  let mode: Mode = "normal";
+  for (const entry of ctx.sessionManager.getBranch()) {
+    if (entry.type !== "custom" || entry.customType !== ENTRY_TYPE) continue;
+    const saved: unknown = (entry.data as { mode?: unknown } | undefined)?.mode;
+    if (isMode(saved)) mode = saved;
+  }
+  return mode;
+}
+
+export default function piModes(pi: ExtensionAPI): void {
+  installJudgeGate();
+
+  let mode: Mode = "normal";
+  let stopListening: (() => void) | undefined;
+  let warnedUngated = false;
+
+  function apply(next: Mode, ctx: ExtensionContext): void {
+    mode = next;
+    setGateMode(ctx.sessionManager.getSessionId(), next);
+    const others = pi.getActiveTools().filter((name) => name !== SUBMIT_PLAN_TOOL);
+    pi.setActiveTools(next === "plan" ? [...others, SUBMIT_PLAN_TOOL] : others);
+    if (ctx.hasUI) ctx.ui.setStatus(STATUS_KEY, ctx.ui.theme.fg(STATUS_COLOR[next], `mode: ${next}`));
+  }
+
+  function warnIfJudgeUncontrolled(ctx: ExtensionContext): void {
+    if (warnedUngated || !ctx.hasUI || judgeGated(ctx.sessionManager.getSessionId()) || !chainNamesJudge()) return;
+    warnedUngated = true;
+    ctx.ui.notify(
+      "pi-modes could not take control of the permission judge. It may still auto-approve outside auto mode. See the README.",
+      "warning",
+    );
+  }
+
+  function change(next: Mode, ctx: ExtensionContext): void {
+    if (next === mode) return;
+    apply(next, ctx);
+    pi.appendEntry(ENTRY_TYPE, { mode: next });
+    if (!ctx.hasUI) return;
+    // A judge named in the chain may not have registered yet: some load orders
+    // only register it during the first prompt. agent_start checks that case.
+    if (next === "auto" && !judgeGated(ctx.sessionManager.getSessionId()) && !chainNamesJudge()) {
+      ctx.ui.notify(
+        "Auto has no permission judge, so it behaves like normal. Set up pi-permission-classifier to use it.",
+        "warning",
+      );
+    }
+  }
+
+  pi.on("session_start", (_event, ctx) => {
+    apply(restoredMode(ctx), ctx);
+    if (ctx.mode === "tui") {
+      if (loadOrderIsLate()) {
+        ctx.ui.notify(
+          "pi-modes loads after pi-permission-system, so you may be asked to approve actions that are then blocked. Move it first in packages in settings.json.",
+          "warning",
+        );
+      }
+      stopListening = ctx.ui.onTerminalInput((data) => {
+        if (!matchesKey(data, CYCLE_KEY)) return undefined;
+        if (!isKeyRelease(data)) change(nextMode(mode), ctx);
+        return { consume: true };
+      });
+    }
+  });
+
+  pi.on("session_tree", (_event, ctx) => apply(restoredMode(ctx), ctx));
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    stopListening?.();
+    stopListening = undefined;
+    clearGate(ctx.sessionManager.getSessionId());
+  });
+
+  // Runs after every before_agent_start handler, which is the judge's last chance to register.
+  pi.on("agent_start", (_event, ctx) => warnIfJudgeUncontrolled(ctx));
+
+  pi.on("before_agent_start", (event) => {
+    const prompt = modePrompt(mode);
+    return prompt ? { systemPrompt: `${event.systemPrompt}\n\n${prompt}` } : undefined;
+  });
+
+  pi.on("tool_call", async (event, ctx) => {
+    const decision = decideToolCall(mode, event.toolName, event.input);
+    if (decision.action === "allow") return undefined;
+    if (decision.action === "block") return { block: true, reason: decision.reason };
+
+    const denied = `Plan mode blocked this command: ${decision.reason}.`;
+    if (!ctx.hasUI) return { block: true, reason: denied };
+    const command = (event.input as { command: string }).command;
+    const approved = await ctx.ui.confirm("Plan mode: run this command?", `${decision.reason}\n\n${displayCommand(command)}`);
+    return approved ? undefined : { block: true, reason: denied };
+  });
+
+  pi.registerTool({
+    name: SUBMIT_PLAN_TOOL,
+    label: "Submit plan",
+    description: "Show the finished plan to the user for approval. Only available in plan mode.",
+    parameters: Type.Object({
+      plan: Type.String({ description: "The complete plan, as markdown" }),
+    }),
+    renderCall: (args, theme) => new Text(`${theme.bold("Plan")}\n${args.plan ?? ""}`, 0, 0),
+    async execute(_id, _params, _signal, _onUpdate, ctx) {
+      const reply = (text: string) => ({ content: [{ type: "text" as const, text }], details: {} });
+      if (mode !== "plan") return reply("Plan mode is off, so there is nothing to approve.");
+      if (!ctx.hasUI) return reply("Nobody can approve a plan here. Stay in plan mode.");
+
+      const NORMAL = "Approve, and ask before risky actions (normal)";
+      const AUTO = "Approve, and let the judge approve actions (auto)";
+      const KEEP = "Keep planning";
+      const choice = await ctx.ui.select("Approve this plan?", [NORMAL, AUTO, KEEP]);
+
+      if (choice === NORMAL || choice === AUTO) {
+        const next: Mode = choice === AUTO ? "auto" : "normal";
+        change(next, ctx);
+        return reply(`The user approved the plan and switched to ${next} mode. Implement it now.`);
+      }
+      const feedback = await ctx.ui.input("What should change?", "");
+      return reply(`The user did not approve the plan. Stay in plan mode. ${feedback ? `Feedback: ${feedback}` : "Ask what to change."}`);
+    },
+  });
+
+  pi.registerCommand("mode", {
+    description: `Show or set the mode: ${MODES.join(", ")}`,
+    getArgumentCompletions: (prefix) => {
+      const items = MODES.filter((name) => name.startsWith(prefix.trim())).map((value) => ({ value, label: value }));
+      return items.length > 0 ? items : null;
+    },
+    handler: async (args, ctx) => {
+      const requested = args.trim();
+      if (requested === "") {
+        const picked = ctx.hasUI ? await ctx.ui.select(`Mode (now ${mode})`, [...MODES]) : undefined;
+        if (isMode(picked)) change(picked, ctx);
+        return;
+      }
+      if (!isMode(requested)) {
+        ctx.ui.notify(`Unknown mode ${requested}. Use one of: ${MODES.join(", ")}.`, "error");
+        return;
+      }
+      change(requested, ctx);
+    },
+  });
+}

package/src/judge-gate.ts

@@ -0,0 +1,93 @@
+/**
+ * Lets the permission judge run only in auto mode, per session.
+ *
+ * pi-permission-system reads `authorizerChain` from a config file shared by
+ * every Pi process, so editing it would flip auto for all open sessions. It
+ * also has no API to read or disable a registered link. Instead this wraps the
+ * judge at registration: outside auto the wrapper defers, which sends the ask
+ * on to the normal prompt.
+ *
+ * Package load order must not matter, so the wrap is installed where each
+ * session's service is published, which happens before any extension can
+ * register on it. This depends on the service map's documented global key. If
+ * that changes, `judgeGated` stays false and the extension warns.
+ */
+
+import type { Mode } from "./modes.ts";
+
+export const JUDGE_NAMES: ReadonlySet<string> = new Set(["permission-judge", "classifier"]);
+
+const SERVICES_KEY = Symbol.for("@gotgenes/pi-permission-system:session-services");
+const STATE_KEY = Symbol.for("pi-modes:session-state");
+const PATCHED = Symbol.for("pi-modes:patched");
+
+type Authorize = (details: unknown, query: unknown, log: unknown) => Promise<unknown>;
+
+interface ServiceLike {
+  registerAuthorizer?: (name: string, authorize: Authorize) => () => void;
+  [PATCHED]?: true;
+}
+
+type ServiceMap = Map<string, ServiceLike> & { [PATCHED]?: true };
+
+interface SessionState {
+  mode: Mode;
+  judgeGated: boolean;
+}
+
+type Store = Record<symbol, unknown>;
+
+function sessionStates(store: Store): Map<string, SessionState> {
+  store[STATE_KEY] ??= new Map<string, SessionState>();
+  return store[STATE_KEY] as Map<string, SessionState>;
+}
+
+function stateFor(store: Store, sessionId: string): SessionState {
+  const states = sessionStates(store);
+  let state = states.get(sessionId);
+  if (!state) {
+    state = { mode: "normal", judgeGated: false };
+    states.set(sessionId, state);
+  }
+  return state;
+}
+
+function gateService(store: Store, sessionId: string, service: ServiceLike): void {
+  if (service[PATCHED] || typeof service.registerAuthorizer !== "function") return;
+  service[PATCHED] = true;
+  const register = service.registerAuthorizer.bind(service);
+  service.registerAuthorizer = (name, authorize) => {
+    if (!JUDGE_NAMES.has(name)) return register(name, authorize);
+    stateFor(store, sessionId).judgeGated = true;
+    return register(name, async (details, query, log) =>
+      stateFor(store, sessionId).mode === "auto" ? authorize(details, query, log) : { kind: "defer" },
+    );
+  };
+}
+
+/** Safe to call from every extension instance: the map is patched once per process. */
+export function installJudgeGate(store: Store = globalThis as unknown as Store): void {
+  store[SERVICES_KEY] ??= new Map<string, ServiceLike>();
+  const services = store[SERVICES_KEY] as ServiceMap;
+  if (services[PATCHED]) return;
+  services[PATCHED] = true;
+
+  for (const [sessionId, service] of services) gateService(store, sessionId, service);
+  const set = services.set.bind(services);
+  services.set = (sessionId, service) => {
+    gateService(store, sessionId, service);
+    return set(sessionId, service);
+  };
+}
+
+export function setGateMode(sessionId: string, mode: Mode, store: Store = globalThis as unknown as Store): void {
+  stateFor(store, sessionId).mode = mode;
+}
+
+export function judgeGated(sessionId: string, store: Store = globalThis as unknown as Store): boolean {
+  return stateFor(store, sessionId).judgeGated;
+}
+
+export function clearGate(sessionId: string, store: Store = globalThis as unknown as Store): void {
+  sessionStates(store).delete(sessionId);
+}

package/src/modes.ts

@@ -0,0 +1,81 @@
+import { classifyBash } from "./bash.ts";
+
+export const MODES = ["normal", "auto", "plan", "read-only"] as const;
+export type Mode = (typeof MODES)[number];
+
+export const SUBMIT_PLAN_TOOL = "submit_plan";
+
+const READ_TOOLS = new Set(["read", "grep", "find", "ls"]);
+
+export function isMode(value: unknown): value is Mode {
+  return (MODES as readonly unknown[]).includes(value);
+}
+
+export function nextMode(mode: Mode): Mode {
+  return MODES[(MODES.indexOf(mode) + 1) % MODES.length] as Mode;
+}
+
+export type ToolDecision =
+  | { action: "allow" }
+  | { action: "ask"; reason: string }
+  | { action: "block"; reason: string };
+
+const ALLOW: ToolDecision = { action: "allow" };
+
+/**
+ * What a mode does to one tool call, before the permission system's own rules.
+ * Unknown tools are blocked in restricted modes, because an MCP tool or a
+ * subagent could write without this extension seeing how.
+ */
+export function decideToolCall(mode: Mode, toolName: string, input: unknown): ToolDecision {
+  if (mode === "normal" || mode === "auto") return ALLOW;
+  const leave = "Press Shift+Tab to change mode.";
+  if (READ_TOOLS.has(toolName)) return ALLOW;
+  if (toolName === SUBMIT_PLAN_TOOL && mode === "plan") return ALLOW;
+
+  if (toolName === "bash") {
+    const command = (input as { command?: unknown } | null)?.command;
+    if (typeof command !== "string") return { action: "block", reason: `${mode} mode: bash needs a command.` };
+    const verdict = classifyBash(command);
+    if (verdict.readOnly) return ALLOW;
+    if (mode === "plan") return { action: "ask", reason: verdict.reason };
+    return { action: "block", reason: `read-only mode blocked this command: ${verdict.reason}. ${leave}` };
+  }
+
+  return { action: "block", reason: `${mode} mode blocks ${toolName}. ${leave}` };
+}
+
+/**
+ * Makes a command safe to show in a dialog. Control and bidirectional characters
+ * become visible escapes, so a command can't hide or reorder what the user sees.
+ */
+export function displayCommand(command: string): string {
+  return command.replace(
+    /[\x00-\x08\x0b-\x1f\x7f-\x9f\u200b-\u200f\u202a-\u202e\u2060-\u2069\ufeff]/g,
+    (ch) => `\\u${(ch.codePointAt(0) as number).toString(16).padStart(4, "0")}`,
+  );
+}
+
+/** True when Pi will run the permission system's dialog before this extension's check. */
+export function loadsAfterPermissionSystem(packages: unknown): boolean {
+  if (!Array.isArray(packages)) return false;
+  const names = packages.map((entry) => String((entry as { source?: unknown } | null)?.source ?? entry));
+  const self = names.findIndex((name) => name.includes("pi-modes"));
+  const gate = names.findIndex((name) => name.includes("pi-permission-system"));
+  return self !== -1 && gate !== -1 && self > gate;
+}
+
+const PLAN_PROMPT = `Plan mode is on. Research and propose, but do not implement.
+- Do not edit files or change any state. write, edit, subagents and MCP tools are blocked.
+- Read-only shell commands run freely. Any other command asks the user first, so run one only if the plan depends on its result.
+- When the plan is ready, call ${SUBMIT_PLAN_TOOL} with the full plan. Do not start implementing until it is approved.`;
+
+const READ_ONLY_PROMPT = `Read-only mode is on. Answer from what you can read.
+- Do not edit files or change any state. write, edit, subagents and MCP tools are blocked.
+- Only read-only shell commands run. Do not try to work around a blocked command.`;
+
+export function modePrompt(mode: Mode): string | undefined {
+  if (mode === "plan") return PLAN_PROMPT;
+  if (mode === "read-only") return READ_ONLY_PROMPT;
+  return undefined;
+}