@openlines/opl-pi-sht 0.1.21 → 0.2.0

package/extensions/opl-init/index.ts

@@ -22,22 +22,6 @@ const MAX_MEMBER_DEPTH = 3;
 const MAX_TREE_LINES = 300;
 const MAX_MANIFEST_BYTES = 2048;
 const MAX_DIR_ENTRIES = 40;
-const MAX_RULE_SOURCE_BYTES = 2048;
-
-// Instruction sources other coding agents use (see research/harness-init-comparison.md).
-// AGENTS.md is deliberately absent — it is this command's output.
-const RULE_SOURCES = [
-  ".cursorrules",
-  ".cursor/rules",
-  ".github/copilot-instructions.md",
-  "CLAUDE.md",
-  "CLAUDE.local.md",
-  ".claude/rules",
-  ".windsurfrules",
-  ".windsurf/rules",
-  ".clinerules",
-  ".devin/rules",
-];
 
 type Crawl = {
   tree: string[];
@@ -307,109 +291,41 @@ function packageScripts(content: string): string | null {
   }
 }
 
-function findRuleSources(root: string): { path: string; detail: string }[] {
-  const found: { path: string; detail: string }[] = [];
-  for (const name of RULE_SOURCES) {
-    const path = join(root, name);
-    let stats;
-    try {
-      stats = statSync(path);
-    } catch {
-      continue;
-    }
-    if (stats.isDirectory()) {
-      // ponytail: filenames only for rule dirs; model can read entries itself.
-      let entries: string[] = [];
-      try {
-        entries = readdirSync(path).slice(0, 20);
-      } catch {
-        continue;
-      }
-      found.push({ path: `${name}/ (${entries.length} file${entries.length === 1 ? "" : "s"})`, detail: entries.join(", ") });
-    } else {
-      try {
-        found.push({ path: name, detail: readFileSync(path, "utf8").slice(0, MAX_RULE_SOURCE_BYTES) });
-      } catch {
-        found.push({ path: name, detail: "(unreadable)" });
-      }
-    }
-  }
-  return found;
-}
-
-function buildContext(root: string, crawlResult: Crawl): string {
-  const extensions = [...crawlResult.extCounts.entries()]
-    .sort((a, b) => b[1] - a[1])
-    .map(([extension, count]) => `${extension} (${count})`)
-    .join(", ");
-  const sections = [
-    `## Repository crawl for: ${root}`,
-    `### Directory tree (depth ${MAX_DEPTH}; declared workspace members get their own depth-${MAX_MEMBER_DEPTH} walk; per-directory entries capped at ${MAX_DIR_ENTRIES})\n\`\`\`\n${crawlResult.tree.join("\n")}\n\`\`\``,
-    `### File counts by extension\n${extensions || "(none)"}`,
-  ];
-
-  if (crawlResult.workspaceMembers.length) {
-    sections.push(`### Declared workspace members (expanded above)\n${crawlResult.workspaceMembers.join(", ")}`);
-  }
-
-  if (crawlResult.manifests.length) {
-    // ponytail: send paths + package.json scripts only; the model can read a
-    // manifest itself if it needs the raw body. Keeps the prompt small and stable.
-    sections.push("### Manifests (read these files directly if you need more detail)");
-    for (const manifest of crawlResult.manifests) {
-      sections.push(`**${manifest.path}**`);
-      if (manifest.path.endsWith("package.json")) {
-        const scripts = packageScripts(manifest.content);
-        if (scripts) sections.push(`Scripts:\n\`\`\`\n${scripts}\n\`\`\``);
-      }
-    }
-  }
-
-  const ruleSources = findRuleSources(root);
-  if (ruleSources.length) {
-    sections.push("### Existing agent rule sources (from other coding agents)");
-    for (const source of ruleSources) {
-      sections.push(`**${source.path}**\n\`\`\`\n${source.detail}\n\`\`\``);
-    }
-  }
-
-  return sections.join("\n\n");
-}
-
-function fallbackGuide(root: string, crawlResult: Crawl, marker: string): string {
+function buildGuide(root: string, crawlResult: Crawl, marker: string): string {
   const topLevel = crawlResult.tree.filter(line => !line.startsWith("  ")).slice(0, 30).join(", ");
   const scripts = crawlResult.manifests
     .map(manifest => manifest.path.endsWith("package.json") ? packageScripts(manifest.content) : null)
     .find(Boolean);
   const commandBlock = scripts ? "Package scripts:\n```\n" + scripts + "\n```" : "No package scripts were detected by the repository crawl.";
-  return `# Repository Guide\n\n## What this is\n\nRepository at \`${root}\`. Use the repository files as the source of truth; the top-level inventory includes ${topLevel || "(not available)"}.\n\n## Commands\n\n${commandBlock}\n\n## Repository inventory\n\n- File types: ${[...crawlResult.extCounts.entries()].map(([extension, count]) => `${extension} (${count})`).join(", ") || "none detected"}.\n- The full crawl is available in the init task context. Inspect specific files before changing behavior.\n\n## Agent workflow\n\nKeep changes focused on the requested behavior, preserve existing interfaces, and run the narrowest relevant test before the full suite. Keep secrets and generated output out of tracked configuration.\n${marker}\n`;
+  return `# Repository Guide\n\n## What this is\n\nRepository at \`${root}\`. Use the repository files as the source of truth; the top-level inventory includes ${topLevel || "(not available)"}.\n\n## Commands\n\n${commandBlock}\n\n## Repository inventory\n\n- File types: ${[...crawlResult.extCounts.entries()].map(([extension, count]) => `${extension} (${count})`).join(", ") || "none detected"}.\n- Inspect specific files before changing behavior; this guide is a starting point, not a substitute for reading the code.\n\n## Agent workflow\n\nKeep changes focused on the requested behavior, preserve existing interfaces, and run the narrowest relevant test before the full suite. Keep secrets and generated output out of tracked configuration.\n${marker}\n`;
 }
 
-const PROMPT = `Generate or update AGENTS.md as an agent guide for this repository. This is an execution task, not a request for prose in chat. You MUST use the write tool to write the guide to the repository's AGENTS.md path; a response containing Markdown without writing the file is a failure. After writing, use the read tool to verify the file exists and ends with the exact fingerprint marker. Do not modify, refactor, or create any other file.
-If AGENTS.md already exists and the repository crawl below says it is current, do not overwrite or modify it. If it is marked stale, update it. If it does not exist, create it.
-
-The repository crawl below (directory tree, file counts, manifests, and any existing rule sources) is the primary source of truth. It was produced for you, so do not re-crawl, re-list, or re-scan the tree, and do not spawn subagents or task lists for this. Read a small number of specific files directly only when you must confirm a repository-specific fact the crawl does not already answer.
-
-Produce a concise, useful Markdown guide, usually 250-700 words:
-- Start with a project-specific title such as "# Repository Guide" or "# <project>".
-- Prefer these sections when supported by evidence: "## What this is", "## Commands", "## Architecture", "## Configuration and installation", "## Testing and operational quirks", and "## Key files".
-- State meaningful absences when known, such as no build, lint, or typecheck command.
-- Capture non-obvious constraints, state, deployment, security, or test-order invariants when they materially affect contributors.
-- Avoid generic contribution, Git, or pull-request advice unless the repository supplies specific facts for it.
-- Omit unsupported sections rather than inventing details.
-- If existing agent rule sources are listed below, incorporate their relevant project-specific content into the guide. Do not copy them verbatim and do not treat them as authoritative over evidence from this repository.
-- IMPORTANT: when you write or update AGENTS.md, make the very last line exactly the fingerprint marker given below (verbatim, no changes). This lets future runs detect staleness.
-
----
-`;
+/**
+ * Opt-in refinement request for `/init --refine`. Deliberately small: the crawl inventory is
+ * already in the guide, so the model reads the file instead of receiving a second copy of the
+ * tree. This is the only injected user turn in the extension, and it never fires on its own.
+ */
+function refinePrompt(agentsPath: string, marker: string): string {
+  return [
+    `Refine the repository guide at ${agentsPath}, which /init generated from a repository crawl.`,
+    "Read the guide first, then open only the specific files you need to confirm repository-specific facts. Do not re-crawl the tree, spawn subagents, or create task lists.",
+    "Rewrite the guide in place with the write tool, concise and evidence-based (usually 250-700 words):",
+    '- Prefer these sections when evidence supports them: "## What this is", "## Commands", "## Architecture", "## Configuration and installation", "## Testing and operational quirks", "## Key files". Omit unsupported sections instead of inventing them, and state meaningful absences such as no build, lint, or typecheck command.',
+    "- Keep the crawl's factual inventory (commands, file types, workspace members) and avoid generic contribution, Git, or pull-request advice.",
+    "- Do not modify, create, or delete any other file.",
+    `- Make the very last line exactly: ${marker}`,
+    "A response containing Markdown without writing the file is a failure.",
+  ].join("\n");
+}
 
 // Named export for fixture tests (tests/opl-init-crawl.test.mjs).
 export { crawl };
 
 export default function (pi: ExtensionAPI) {
   pi.registerCommand("init", {
-    description: "[opl-init] Crawl the repository and generate an AGENTS.md contributor guide",
-    handler: async (_args, ctx) => {
+    description: "[opl-init] Crawl the repository and write an AGENTS.md guide (--refine also asks the model to expand it)",
+    handler: async (args, ctx) => {
+      const refine = /(?:^|\s)--refine(?:\s|$)/.test(args.trim());
       const root = ctx.cwd;
       const agentsPath = join(root, "AGENTS.md");
       const currentFp = fingerprint(root);
@@ -424,28 +340,26 @@ export default function (pi: ExtensionAPI) {
         }
       }
 
+      const marker = `<!-- opl-init:fp ${currentFp} -->`;
+
       if (exists && storedFp === currentFp) {
         ctx.ui.notify("AGENTS.md is current; /init will not modify it.", "info");
-        return;
-      }
-
-      const status = !exists
-        ? "AGENTS.md status: missing; create it."
-        : storedFp === null
-          ? "AGENTS.md status: no fingerprint marker found; treat as stale and update it."
-          : "AGENTS.md status: stale (fingerprint mismatch); update it.";
-      const marker = `<!-- opl-init:fp ${currentFp} -->`;
-      const crawlResult = crawl(root);
-      try {
-        writeFileSync(agentsPath, fallbackGuide(root, crawlResult, marker), "utf8");
-        ctx.ui.notify("AGENTS.md baseline written; the agent will refine it from the crawl.", "info");
-      } catch (error: any) {
-        ctx.ui.notify(`Could not write AGENTS.md baseline: ${error?.message || error}`, "error");
+      } else {
+        // Regenerating replaces the whole file, including hand-edited prose; the repository's
+        // version control is the recovery path.
+        const crawlResult = crawl(root);
+        try {
+          writeFileSync(agentsPath, buildGuide(root, crawlResult, marker), "utf8");
+          ctx.ui.notify(exists ? "AGENTS.md overwritten from the repository crawl." : "AGENTS.md created.", "info");
+        } catch (error: any) {
+          ctx.ui.notify(`Could not write AGENTS.md: ${error?.message || error}`, "error");
+          return;
+        }
       }
 
-      pi.sendUserMessage(
-        `${PROMPT}\n${status}\nFingerprint marker to append as the last line: ${marker}\n\n${buildContext(root, crawlResult)}`,
-      );
+      // Queue, never steer: Pi throws "Agent is already processing" for an injection with no
+      // deliverAs while a turn is streaming, and steering would hijack the task in flight.
+      if (refine) pi.sendUserMessage(refinePrompt(agentsPath, marker), { deliverAs: "followUp" });
     },
   });
 }

package/extensions/opl-input/README.md

@@ -15,11 +15,12 @@ No commands, flags, or shortcuts. It replaces the standard editor at session sta
 - **Scroll-aware borders**: Editor scroll indicators are embedded in the top or bottom border when the input has more content than fits.
 - **Slash-menu placement**: The slash menu is rendered below the input with configurable gap and indentation.
 - **Responsive rendering**: Narrow terminals fall back to the native editor rendering; the companion is hidden below 40 columns.
+- **Shared idle heartbeat**: this component owns the bundle's only render timer. With the companion disabled it slows to one repaint per second instead of ten, which still advances the footer's elapsed/time-per-second cells while Pi is idle.
 - **Hex and theme colors**: Color settings accept Pi theme tokens or six-digit hex colors.
 
 ## Mode styling precedence
 
-Exactly one style applies at a time, in this order: Bash (`!` input) > active `opl-modes` appearance > hardcoded mode fallback. The compiled fallbacks are normal: `❯`/`accent`/`border`; chat: `»`/`chatModeBorder`; and plan/execute: `⏸`/`customMessageLabel`.
+Exactly one style applies at a time, in this order: Bash (`!` input) > active `opl-modes` appearance > hardcoded mode fallback. The compiled fallbacks are normal: `❯`/`accent`/`border`; chat: `»`/`borderAccent`; and plan/execute: `⏸`/`customMessageLabel`.
 
 ## Configuration
 
@@ -54,7 +55,7 @@ Create `~/.pi/agent/configs/opl-input.json` or copy [`configs/opl-input.json.sam
 
 | Field | Type | Default | Description |
 |---|---|---:|---|
-| `companion.enabled` | boolean | `false` | Show the animated companion above the input. |
+| `companion.enabled` | boolean | `false` | Show the animated companion above the input. The idle repaint that drives it runs every 100 ms when enabled and every 1 s when disabled (the footer's time-based cells ride the same tick). |
 | `companion.color` | color | `"accent"` | Companion color. |
 | `companion.type` | string | unset | Select a named entry from `companion.types`; built-in `dog` also has a fallback shape (`"cat"` uses the default ears). |
 | `companion.ears` | string | cat ears | Directly override the companion's top line; wins over `type`. |
@@ -74,9 +75,10 @@ Every color option accepts either:
   - Syntax: `syntaxComment`, `syntaxKeyword`, `syntaxFunction`, `syntaxVariable`, `syntaxString`, `syntaxNumber`, `syntaxType`, `syntaxOperator`, `syntaxPunctuation`
   - Thinking borders: `thinkingOff`, `thinkingMinimal`, `thinkingLow`, `thinkingMedium`, `thinkingHigh`, `thinkingXhigh`, `thinkingMax`
   - Special: `bashMode`
-- **A six-digit hex color** — e.g. `"#c07898"` (rendered as ANSI truecolor, downgraded automatically on 256-color terminals).
+- **A hex color** — `"#c07898"`, or the three-digit shorthand `"#abc"` (expanded to `#aabbcc`; rendered as ANSI truecolor, downgraded automatically on 256-color terminals).
 
 Invalid theme tokens fall back to the theme's `border` token; invalid hex renders uncolored rather than crashing.
+- A mode `prefix` is clamped to one terminal cell (continuation lines reserve a single space), so a wide or multi-character `appearance.prefix` such as `👀` is truncated to one cell rather than pushing the box border past the editor width.
 
 ## Architecture
 

package/extensions/opl-input/index.ts

@@ -1,10 +1,10 @@
 import { CustomEditor, type ExtensionAPI, type Theme } from "@earendil-works/pi-coding-agent";
 import type { TUI, EditorTheme } from "@earendil-works/pi-tui";
 import type { KeybindingsManager } from "@earendil-works/pi-coding-agent";
-import { visibleWidth } from "@earendil-works/pi-tui";
+import { visibleWidth, truncateToWidth } from "@earendil-works/pi-tui";
 import { CONFIG, COMPANION_PADDING, MIN_WIDTH_FOR_COMPANION } from "./config.js";
 import { resolveModeStyle, type ModeAppearance } from "./mode-style.js";
-import { applyColor, CompanionAnimator, startRenderTimer } from "./utils.js";
+import { applyColor, CompanionAnimator, COMPANION_TICK_MS, IDLE_REPAINT_MS, startRenderTimer } from "./utils.js";
 
 // ─── Helpers ──────────────────────────────────────────────────────────────
 const ANSI_RE = /\x1b\[[0-9;]*m|\x1b\[0?m/g;
@@ -43,10 +43,15 @@ class ChatInput extends CustomEditor {
 		this.inputTheme = theme;
 
 		// Animate companion even when idle — tick drives state machine
-		this.stopCompanionTimer = startRenderTimer(() => {
-			this.animator.tick(Date.now());
-			this.tui.requestRender();
-		});
+		// With the companion hidden this component still owns the only idle repaint in the
+		// bundle (footer time-based cells read it), so the tick slows down instead of stopping.
+		this.stopCompanionTimer = startRenderTimer(
+			() => {
+				this.animator.tick(Date.now());
+				this.tui.requestRender();
+			},
+			CONFIG.COMPANION_ENABLED ? COMPANION_TICK_MS : IDLE_REPAINT_MS,
+		);
 	}
 
 	dispose(): void {
@@ -74,7 +79,9 @@ class ChatInput extends CustomEditor {
 		const style = resolveModeStyle({ bash: isBash, mode: mode.mode, appearance: mode.appearance });
 		const border = (s: string) => applyColor(this.uiTheme, style.borderColor, s);
 		const accent = (s: string) => applyColor(this.uiTheme, style.prefixColor, s);
-		const prefix = style.prefix;
+		// The layout reserves exactly one cell for the prefix (continuation lines pad with " "),
+		// so a wider configured prefix would push the box border past `width`.
+		const prefix = truncateToWidth(style.prefix, 1);
 
 		if (CONFIG.BOXED_VIEW) {
 			return this.renderBoxed(stock, contentWidth, width, border, accent, prefix);

package/extensions/opl-input/mode-style.ts

@@ -21,7 +21,7 @@ export interface ResolvedModeStyle {
 
 const MODE_DEFAULTS: Record<string, Required<ModeAppearance>> = {
 	off: { prefix: "❯", prefixColor: "accent", borderColor: "border" },
-	chat: { prefix: "»", prefixColor: "chatModeBorder", borderColor: "chatModeBorder" },
+	chat: { prefix: "»", prefixColor: "borderAccent", borderColor: "borderAccent" },
 	plan: { prefix: "⏸", prefixColor: "customMessageLabel", borderColor: "customMessageLabel" },
 	execute: { prefix: "⏸", prefixColor: "customMessageLabel", borderColor: "customMessageLabel" },
 };

package/extensions/opl-input/utils.ts

@@ -48,7 +48,9 @@ function isHexColor(color: string): boolean {
 }
 
 function hexToAnsi(hex: string): string {
-	const h = hex.replace("#", "");
+	// Accept the #abc shorthand so a three-digit value renders the same as #aabbcc.
+	let h = hex.replace("#", "");
+	if (/^[0-9a-fA-F]{3}$/.test(h)) h = h.split("").map((c) => c + c).join("");
 	if (!/^[0-9a-fA-F]{6}$/.test(h)) return "";
 	const r = parseInt(h.slice(0, 2), 16);
 	const g = parseInt(h.slice(2, 4), 16);
@@ -56,14 +58,23 @@ function hexToAnsi(hex: string): string {
 	return `\x1b[38;2;${r};${g};${b}m`;
 }
 
-export function startRenderTimer(render: () => void): () => void {
-	const timer = setInterval(render, 100);
+/** Animation cadence while the companion is visible. */
+export const COMPANION_TICK_MS = 100;
+/** Idle repaint cadence with the companion off: keeps time-based footer cells advancing without 10 repaints/second. */
+export const IDLE_REPAINT_MS = 1000;
+
+export function startRenderTimer(render: () => void, periodMs: number = COMPANION_TICK_MS): () => void {
+	const timer = setInterval(render, periodMs);
 	return () => clearInterval(timer);
 }
 
 export function applyColor(theme: Theme, color: string, text: string): string {
 	if (isHexColor(color)) {
-		return `${hexToAnsi(color)}${text}\x1b[0m`;
+		// A malformed hex yields "": render the text with no escape rather than an empty
+		// color plus a stray reset.
+		const ansi = hexToAnsi(color);
+		if (!ansi) return text;
+		return `${ansi}${text}\x1b[0m`;
 	}
 	try {
 		return theme.fg(color as ThemeColor, text);
@@ -86,7 +97,7 @@ export interface CompanionState {
 
 type Phase = "face" | "ears" | "full" | "none";
 
-const TICK_MS = 100; // matches setInterval in ChatInput
+const TICK_MS = COMPANION_TICK_MS; // companion animation frame budget
 const R = (min: number, max: number) => min + Math.random() * (max - min);
 
 export class CompanionAnimator {

package/extensions/opl-modes/README.md

@@ -4,36 +4,40 @@ Unified mode manager for Pi. It provides normal, read-only chat, read-only plann
 
 ## Commands, flags, and shortcuts
 
-- `/mode` opens the picker; `/mode chat`, `/mode plan`, and `/mode normal` select built-in modes.
+- `/mode` opens the picker; `/mode chat`, `/mode plan`, and `/mode normal` select built-in modes, and `/mode <name>` selects any registered custom mode (for example `/mode review`). `execute` is excluded because it needs an active plan; use `/execute`.
 - `/chat` toggles chat mode; `/chat off` exits it.
 - `/plan` toggles plan mode, creates or loads a named plan, or accepts `/plan off`.
 - `/execute` selects or executes an existing plan; `/execute <name>` runs a named plan.
 - `--chat` and `--plan` start Pi in the corresponding read-only mode.
-- The configured cycle shortcut rotates through enabled visible modes. Execute mode is excluded from cycling because it requires an active plan.
+- The configured cycle shortcut rotates through enabled visible modes. Execute mode is excluded from cycling because it requires an active plan. The default `shift+tab` is also Pi's built-in `app.thinking.cycle`, so both fire on one press; rebind either action in `~/.pi/agent/keybindings.json` (or pick another `shortcuts.cycleMode`) if you want them separate.
 
-Plans are Markdown files under `.pi/plans/` with the `plan-` filename prefix. `plan_complete` is available only in execute mode. On completion, the plan file is deleted when `cleanup.cleanupOnComplete` is enabled. If execution ends without `plan_complete`, execute mode is exited automatically.
+Plans are Markdown files under `.pi/plans/` with the `plan-` filename prefix. A plan name must contain at least one letter or digit, so `/plan .` or `/plan --` is rejected instead of producing an untitled `plan-.md`. `plan_complete` is available in execute mode and in any mode that sets `allowPlanComplete`. On completion, the plan file is deleted when `cleanup.cleanupOnComplete` is enabled. If execution ends without `plan_complete`, execute mode is exited automatically — but only when a turn actually finished: an aborted (ESC) or errored turn keeps execute mode active so the plan can be resumed.
 
 ## Extension features
 
 ### Mode behavior
 
-Chat and plan modes replace the active tools with configurable read-only tool lists and restrict Bash to safe inspection patterns. Destructive patterns are checked even when a command matches a safe pattern. Valid user-provided safe and destructive pattern arrays replace the built-in lists, rather than extending them. An explicit empty per-mode array replaces that policy with none; a malformed non-empty per-mode array is ignored and inherits the existing policy.
+Chat and plan modes replace the active tools with configurable read-only tool lists and restrict Bash to safe inspection patterns. The allowlist is checked **per shell segment**, not just at the start of the command line: `&&`, `||`, a lone `&` (backgrounding), `|`, `;`, newlines, `$(...)`, backticks, and `<(`/`>(` each begin a segment, and every segment must match a safe pattern. Segment scanning is quote-aware, so `grep "a|b"` is one command, but a `$(...)` or backtick payload still runs inside double quotes and is split out and checked, so `echo "$(node -e ...)"` cannot hide behind the quoted argument. `cat f && node -e '...'`, `ls; python -c '...'`, and `cat x & rm -rf /` are blocked because their second segment is not safe-listed. Destructive patterns are still checked even when a command matches a safe pattern. The allowlist covers read-only inspection and text filters only: `awk`, `sed`, `xargs`, `perl`, `python`, and `env` are deliberately absent because they can write files, exec programs from their arguments, or dump API keys. Valid user-provided safe and destructive pattern arrays replace the built-in lists, rather than extending them. An explicit empty per-mode array replaces that policy with none; a malformed non-empty per-mode array is ignored and inherits the existing policy.
 
-The shared destructive base also blocks file mutation primitives (`rm`, `find -delete`/`-exec`, `truncate`, `git clean`/`update-ref`/`tag -d`, `sudo`, shell spawns, and output redirects). `env` and `printenv` are no longer safe-listed, since they could dump provider API keys into the model context. Destructive matching also runs against a quote/backslash-stripped command skeleton, so `r"m"` cannot dodge `\brm\b`; this is still a heuristic backstop, not a process-isolation boundary.
+The shared destructive base blocks file mutation primitives (`rm`, `rmdir`, `mv`, `cp`, `mkdir`, `touch`, `chmod`, `chown`, `tee`, `dd`, `shred`, `truncate`), `find -delete`/`-exec`/`-execdir`/`--exec-batch` and find's file-writing predicates (`-fprint`, `-fprint0`, `-fprintf`, `-fls`), any `--output` file (`sort --output`, `git log/diff/show --output`), `sort -o`/`tree -o` in any argument position, `fd -x`/`-X` (and clusters like `-Hx`), `rg --pre`, `jq`'s environment access (`jq -n env`, `$ENV`), `npm`/`yarn`/`pip` install and update forms including `npm audit fix`, state-changing `git` subcommands (including `branch -d`/`-D`/`-m`/`-M`/`-c`/`-C`/`--delete`/`--unset-upstream` and the writing `git remote` subcommands), `sudo`/`su`, `kill`/`pkill`, shell spawns, editors, `uniq`'s output operand (`uniq -c in.txt out.txt`; flags are not operands, so `uniq -c sorted.txt` stays a read), and every redirect that names a file - while descriptor duplication (`2>&1`, `>&2`, `>&-`) and a redirect whose target is exactly `/dev/null` are not writes and stay allowed (`> /dev/null/../tmp/x` is a write, so a path that merely starts with that prefix is blocked). `env` and `printenv` are not safe-listed, since they could dump provider API keys into the model context. Program-name entries are anchored to command position and matched per segment, so a read-only command that merely *mentions* a dangerous word in an argument (`du -sh`, `find . -name '*.sh'`, `ls cp/`, `cat mv.sh`, `git log --grep=rm`, `grep -rn 'touch' src`) stays allowed, and descriptor duplication (`2>&1`, `>&2`, `>&-`) is not mistaken for a file write. Every destructive pattern is tested against the command and each of its segments, with and without quotes/backslashes stripped, so `r"m"` and `-del"ete"` cannot dodge the list. That blocklist split deliberately ignores quotes, so an operator inside a quoted string (`echo "a > b"`) is over-blocked rather than trusted. This is still a heuristic backstop, not a process-isolation boundary: `npx` and any command whose *name* comes from an expansion are outside what a pattern list can catch.
 
-Custom modes can add or override modes with prompts, tool lists, Bash patterns, model overrides, visibility, enabled state, `plan_complete` permission, execute-handoff permission, labels, and `appearance`. Appearance is published to `opl-input` and `opl-footer`, so every mode owns its input prefix/border and footer identity color. A custom mode that omits its own `safePatterns`/`destructivePatterns` inherits the whole shared base; a mode overrides a component with its own array or disables all gating with `unrestrictedBash: true`. Built-in `off` and `execute` stay unrestricted.
+Custom modes can add or override modes with prompts, tool lists, Bash patterns, model overrides, visibility, enabled state, `plan_complete` permission, execute-handoff permission, labels, and `appearance`. `visible: false` hides a mode from the picker and the cycle list but leaves it reachable through `/mode <name>`, on purpose: it is the escape hatch for a mode you want available without cluttering the menu. Appearance is published to `opl-input` and `opl-footer`, so every mode owns its input prefix/border and footer identity color. A mode that omits its own `safePatterns`/`destructivePatterns` inherits the whole shared base; a mode overrides a component with its own array or disables all gating with `unrestrictedBash: true` — which works for built-in overrides (`modes.chat`, `modes.plan`, ...) as well as new custom modes. Built-in `off` and `execute` stay unrestricted unless you give them their own `tools` list.
 
 ### Execute handoff
 
-Any mode can start plan execution via the mode picker's `Execute:` entries or `/execute`, unless it sets `allowExecute: false`. When blocked, the picker hides the `Execute:` entries and `/execute` reports that execution is unavailable from the current mode. The plan-mode action menu (`Execute / Refine / Save & Exit / Discard & Exit`) is the designed plan-to-execute pipeline and is always available in plan mode regardless of this flag.
+Any mode can start plan execution via the mode picker's `Execute:` entries or `/execute`, unless it sets `allowExecute: false`. When blocked, the picker hides the `Execute:` entries and `/execute` reports that execution is unavailable from the current mode. The plan-mode action menu (`Execute / Refine / Save & Exit / Discard & Exit`) is the designed plan-to-execute pipeline and is always available in plan mode regardless of this flag. The Refine entry counts cycles (`Refine (3 cycles so far)`) as information only; nothing caps how often you refine.
 
-`allowPlanComplete: true` on a custom mode appends the `plan_complete` tool to that mode's tool list, letting a custom mode finish and exit through the same completion path as execute mode (the `tool_call` gate enforces the flag).
+`allowPlanComplete: true` on a custom mode appends the `plan_complete` tool to that mode's tool list, letting a custom mode finish and exit through the same completion path as execute mode: the `tool_call` gate, the tool body, and the result handler all use one `planCompleteAllowed()` predicate, so calling it from such a mode deletes the plan file (when cleanup is enabled) and reports `Plan implemented. Plan mode OFF.` exactly like execute mode.
 
 ### Tool inheritance warning
 
 A custom mode with no `tools` array inherits **all** tools, including `write` and `edit` — it is write-capable by default. Always specify an explicit read-only tool list for restrictive modes.
 
-Mode state is persisted in session entries and restored on session resume or branch changes. The `mode-switcher` entry type and legacy chat/plan event identifiers are compatibility contracts. On resume, an unknown mode name in a session entry is ignored (falling back to normal), and plan filenames containing path separators or `..` are dropped, so a stale or foreign branch cannot leave the session unrestricted or point plan reads outside `.pi/plans/`.
+`off` behaves the same way: it restores the tools that were active before the mode (never a wider set). Set `modes.off.tools` to pin the resting tool set instead — for example to keep `subagent`/`browser` out of normal mode entirely. Pinning replaces the snapshot taken on mode entry, so a later mode that lists no `tools` inherits the pinned set rather than the older, wider one. `load_tools` is offered in `off` because withheld lazy tools are otherwise unreachable there.
+
+Model overrides are resolved through Pi's model registry when entering a mode. A blank or partial `model` (for example `{ "provider": "", "id": "" }`) is treated as **no override**, so the mode keeps the current model instead of warning `Model not found: /`. The previously active model is captured once per mode and restored on exit; the restore point is persisted in the mode session entry, so `/reload` and `/resume` inside a mode no longer lose it. If the restore target is gone from the registry it is dropped immediately; if it exists but has no credentials (before `/login`, say) the restore is retried once and then released, so a stale point cannot block future captures indefinitely. `Pi.setModel` is session-scoped: it never rewrites your configured `defaultProvider`/`defaultModel`, but it does append a model change to the session transcript, which is why the restore point is persisted alongside the mode. Changes are serialized, so a rapid mode exit cannot leave a superseded mode model active. Note that setting `modes.off.model` makes OFF a pinned baseline: it is applied on every mode exit *and* at session start, overriding `--model` and the configured default. Use Pi theme color tokens for widget label colors.
+
+Mode state is persisted in session entries and restored on session resume or branch changes. Pi ignores tool names it does not know, so a `tools` list with a typo would silently lose tools: every mode entry checks the list against the registered tools and warns once per unknown name per session. The `mode-switcher` entry type and legacy chat/plan event identifiers are compatibility contracts. On resume, an unknown mode name in a session entry is ignored (falling back to normal), and plan filenames containing path separators or `..` are dropped, so a stale or foreign branch cannot leave the session unrestricted or point plan reads outside `.pi/plans/`.
 
 ## Configuration
 
@@ -82,8 +86,9 @@ Create `~/.pi/agent/configs/opl-modes.json` or copy [`configs/opl-modes.json.sam
 | `defaultNotifyTemplate` | Notification template for custom modes; `{Name}` is capitalized mode name. |
 | `modes.chat.tools` / `modes.plan.tools` | Replace the respective built-in read-only tool lists. |
 | `chatAllowedTools` / `planAllowedTools` | **Deprecated compatibility aliases** for the built-in tool lists. They are used only when the corresponding `modes.<name>.tools` is omitted; migrate to `modes.chat.tools` or `modes.plan.tools`. |
-| `bashPatterns.safePatterns` / `bashPatterns.destructivePatterns` | Shared Bash policy applied to every mode by default; a mode overrides with its own `modes.<name>.safePatterns`/`destructivePatterns` or disables gating with `modes.<name>.unrestrictedBash: true`. |
-| `modes.<name>.unrestrictedBash` | Set `true` to exempt a custom mode from the Bash policy entirely (no safe/destructive patterns). |
+| `bashPatterns.safePatterns` / `bashPatterns.destructivePatterns` | Shared Bash policy applied to every mode by default; a mode overrides with its own `modes.<name>.safePatterns`/`destructivePatterns` or disables gating with `modes.<name>.unrestrictedBash: true`. Every segment of a command must satisfy the allowlist. |
+| `modes.<name>.unrestrictedBash` | Set `true` to exempt a mode from the Bash policy entirely (no safe/destructive patterns). Works for custom modes and built-in overrides. |
+| `modes.off.tools` | Optional: pin the resting tool set for OFF mode. Omit to restore whatever was active before the mode. |
 | `lazyTools` | Tool names withheld from the active set at rest and enabled on demand (see Lazy tool loading below). |
 | `modes.<name>` | Add or override a mode, including `model`, `tools`, patterns, `allowPlanComplete`, `allowExecute`, `visible`, `enabled`, `prompt`, `labels`, and `appearance`. |
 
@@ -106,7 +111,7 @@ Use `modes.<name>.appearance` to keep any mode's visual identity with its defini
 }
 ```
 
-`prefix`, `prefixColor`, and `borderColor` style `opl-input`; omitted fields use its compiled mode defaults. `modeColor` styles the value in `opl-footer`'s `mode_switcher` segment; if omitted, the footer uses hardcoded `muted`. Colors accept Pi theme tokens or six-digit hex strings.
+`prefix`, `prefixColor`, and `borderColor` style `opl-input`; omitted fields use its compiled mode defaults. `modeColor` styles the value in `opl-footer`'s `mode_switcher` segment; if omitted, the footer uses hardcoded `muted`. Colors accept Pi theme tokens, six-digit hex, or the three-digit `#abc` shorthand (expanded to `#aabbcc`).
 
 Model overrides are resolved through Pi's model registry when entering a mode and the previously active model is restored on exit when applicable. Changes are serialized, so a rapid mode exit cannot leave a superseded mode model active. Use Pi theme color tokens for widget label colors.
 
@@ -127,9 +132,10 @@ Behavior:
 - `load_tools` is bounded by the current mode's tool policy: it can only enable a lazy tool the active mode already permits, so a read-only mode cannot enable a write-capable tool.
 - Core built-ins (`read`, `edit`, `write`, `bash`, `powershell`, `grep`, `find`, `ls`), `plan_complete`, and `load_tools` itself are protected and silently ignored if listed in `lazyTools`.
 - Switching modes re-applies the policy, so a lazy tool enabled earlier returns to inactive on the next mode change and must be re-enabled.
+- A mode `prompt` that instructs the model to use a lazy tool must also tell it to call `load_tools` first, otherwise the instruction names a tool the model cannot see. The bundled `research` mode does exactly that.
 
 Caching note: activating a lazy tool mid-session preserves the cached prefix on models with native deferred tool loading (Anthropic 4.5+, OpenAI gpt-5.4+) and otherwise triggers one prompt-cache rewrite from that point. It is most effective for tools you use occasionally (delegation, browser automation, benchmarking).
 
 ## Architecture
 
-`config.ts` registers built-in modes, merges configured overrides, compiles Bash patterns, and publishes the registry. `state.ts` persists and restores mode/plan state and is the single publisher of `globalThis.__agentMode`. `index.ts` wires commands, picker, lifecycle hooks, tool replacement, Bash interception, and `plan_complete`; `utils.ts` handles plan files and shared helpers.
+`config.ts` registers built-in modes, merges configured overrides, compiles Bash patterns, and publishes the registry. `state.ts` persists and restores mode/plan state (including the persisted model restore point) and is the single publisher of `globalThis.__agentMode`. `index.ts` wires commands, picker, lifecycle hooks, tool replacement, Bash interception, and `plan_complete`; `utils.ts` handles plan files, the per-segment Bash gate, and shared helpers.

package/extensions/opl-modes/config.ts

@@ -3,7 +3,7 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import type { ModeSwitcherUserConfig, ModeDefinition, PartialModeDefinition } from "./types.js";
+import type { ModeSwitcherUserConfig, ModeDefinition, PartialModeDefinition, ModeModelConfig } from "./types.js";
 
 // ─── Plan File Constants ────────────────────────────────────────────────────
 
@@ -50,32 +50,56 @@ export const DEFAULT_SAFE_PATTERNS: RegExp[] = [
   /^\s*cat\b/, /^\s*head\b/, /^\s*tail\b/, /^\s*less\b/, /^\s*more\b/,
   /^\s*grep\b/, /^\s*find\b/, /^\s*ls\b/, /^\s*pwd\b/, /^\s*cd\b/,
   /^\s*echo\b/, /^\s*printf\b/, /^\s*wc\b/, /^\s*sort\b/,
+  // Pure stdout filters. uniq can write its second operand, so it is gated in the blocklist.
+  /^\s*uniq\b/, /^\s*tr\b/, /^\s*cut\b/,
   /^\s*diff\b/, /^\s*file\b/, /^\s*stat\b/, /^\s*du\b/, /^\s*df\b/,
   /^\s*tree\b/, /^\s*which\b/, /^\s*whereis\b/, /^\s*type\b/,
   /^\s*uname\b/, /^\s*whoami\b/,
   /^\s*date\b/, /^\s*uptime\b/, /^\s*ps\b/, /^\s*free\b/,
   /^\s*rg\b/, /^\s*fd\b/, /^\s*bat\b/, /^\s*jq\b/,
-  /^\s*git\s+(status|log|diff|show|branch|remote)/i,
+  /^\s*git\s+(status|log|diff|show|branch|remote|rev-parse)/i,
   /^\s*node\s+--version/i, /^\s*python\s+--version/i,
   /^\s*(npx\s+)?tsc\b.*--noEmit/i,
   /^\s*npm\s+(list|ls|view|info|outdated|audit)/i,
   /^\s*yarn\s+(list|info|why|audit)/i,
 ];
 
-/** Default destructive command patterns — always blocked in read-only modes, even if matching a safe pattern. */
+/** Destructive command patterns — always blocked in read-only modes, even if matching a safe pattern.
+ *  Program names are anchored to command position (`^\s*`) and matched per shell segment, so a
+ *  read-only command that merely mentions `rm`/`cp`/`sh` in an argument (`du -sh`, `ls cp/`,
+ *  `git log --grep=rm`) stays allowed. Flag and redirect patterns stay unanchored on purpose. */
 export const DEFAULT_DESTRUCTIVE_PATTERNS: RegExp[] = [
-  /\brm\b/i, /\brmdir\b/i, /\bmv\b/i, /\bcp\b/i,
-  /\bmkdir\b/i, /\btouch\b/i, /\bchmod\b/i, /\bchown\b/i,
-  /\btee\b/i, /\bdd\b/i, /\bshred\b/i, /\btruncate\b/i,
-  /\s-(delete|exec|execdir)\b/i,
-  /(^|[^<])>(?!>|&)/, />>/,
-  /\bnpm\s+(install|uninstall|update|ci)/i,
+  /^\s*(rm|rmdir|mv|cp|mkdir|touch|chmod|chown|tee|dd|shred|truncate)\b/i,
+  // Write flags that ride a safe-listed command: find's file-writing predicates and --output
+  // on sort/git log/git diff/git show. `-print`/`-printf` stay allowed (they go to stdout).
+  /\s-{1,2}(delete|exec|execdir|exec-batch|fprint0?|fprintf|fls|output)\b/i,
+  // `fd -x`/`-X` (also inside a short-flag cluster like `-Hx`) execute a command per match.
+  // The long forms are already caught above; the anchor keeps `grep -x` and `cut -d` legal.
+  /^\s*fd\b[^\n]*\s-[A-Za-z]*[xX]\b/,
+  // `rg --pre CMD` runs CMD on every file before searching.
+  /^\s*rg\b[^\n]*\s--pre\b/,
+  // `sort -o`/`tree -o` write their output operand in any argument position.
+  /^\s*(sort|tree)\b[^\n]*\s-[A-Za-z]*o\b/i,
+  // jq can read the process environment, which is why `env`/`printenv` are not safe-listed.
+  // Over-blocks a JSON key literally named `env`; a leaked API key costs more.
+  /^\s*jq\b[^\n]*(\$ENV|\benv\b)/i,
+  // Any redirect that names a file. `>&<fd>`/`>&-` duplication is not a write, so 2>&1 survives.
+  // The /dev/null exception needs a token boundary: `> /dev/null/../tmp/pwn` and `> /dev/nullfoo`
+  // are writes to real paths that merely start with that prefix.
+  /(^|[^<])>(?!>)(?!&[0-9-])(?! *\/dev\/null(?![^\s;&|)]))/, />>(?! *\/dev\/null(?![^\s;&|)]))/,
+  // uniq writes its second operand (`uniq -c in.txt out.txt`); flags don't count, so
+  // `uniq -c sorted.txt` stays a read.
+  /^\s*uniq\b(?:\s+-\S+)*\s+[^-\s]\S*(?:\s+[^-\s]\S*)+/,
+  /\bnpm\s+(install|uninstall|update|upgrade|ci)/i,
+  /\bnpm\s+audit\b.*\bfix\b/i,
   /\byarn\s+(add|remove|install)/i,
   /\bpip\s+(install|uninstall)/i,
-  /\bgit\s+(add|commit|push|merge|rebase|reset|checkout|branch\s+-|clean|update-ref|tag\s+-|cherry-pick|revert|am|apply)/i,
-  /\bsudo\b/i, /\bsu\b/i, /\bkill\b/i, /\bpkill\b/i,
-  /\b(sh|bash|zsh)\b/i,
-  /\b(vim?|nano|emacs|code|subl)\b/i,
+  /\bgit\s+(add|commit|push|merge|rebase|reset|checkout|clean|update-ref|cherry-pick|revert|am|apply|branch\s+(-{1,2}[dDmMcC]|--(unset-upstream|edit-description))|tag\s+-)/i,
+  // Subcommands that hide behind the safe `git remote` prefix and still write .git.
+  /\bgit\s+remote\s+(add|remove|rename|set-url|set-head|setbranches|prune|update)\b/i,
+  /^\s*(sudo|su|kill|pkill)\b/i,
+  /^\s*(sh|bash|zsh)\b/i,
+  /^\s*(vim?|nano|emacs|code|subl)\b/i,
 ];
 
 // ─── Prompt Templates ────────────────────────────────────────────────────────
@@ -394,13 +418,29 @@ export function resolveCustomPatterns(def: {
   };
 }
 
+/**
+ * Normalize a configured model reference. A blank or partial `{ provider, id }` means
+ * "no override" — Pi's registry cannot resolve empty strings, so passing one through
+ * would only warn "Model not found: /" and leave the model untouched. Treating it as
+ * unset makes the mode keep (and later restore) the current model instead.
+ */
+export function resolveModeModel(model: unknown): ModeModelConfig | undefined {
+  if (!isRecord(model)) return undefined;
+  const provider = typeof model.provider === "string" ? model.provider.trim() : "";
+  const id = typeof model.id === "string" ? model.id.trim() : "";
+  return provider && id ? { provider, id } : undefined;
+}
+
 export function mergeModeDefinition(existing: ModeDefinition, def: PartialModeDefinition): ModeDefinition {
+  // unrestrictedBash is an opt-out for built-in overrides too, not just new modes.
+  const unrestricted = def.unrestrictedBash === true;
   return {
     ...existing,
     ...def,
     tools: def.tools ?? existing.tools,
-    safePatterns: compilePatterns(def.safePatterns) ?? existing.safePatterns,
-    destructivePatterns: compilePatterns(def.destructivePatterns) ?? existing.destructivePatterns,
+    model: "model" in def ? resolveModeModel(def.model) : existing.model,
+    safePatterns: unrestricted ? undefined : (compilePatterns(def.safePatterns) ?? existing.safePatterns),
+    destructivePatterns: unrestricted ? undefined : (compilePatterns(def.destructivePatterns) ?? existing.destructivePatterns),
     labels: { ...existing.labels, ...def.labels },
     appearance: def.appearance ?? existing.appearance,
   };
@@ -429,6 +469,14 @@ export function withPlanComplete(mode: string, tools: string[], registry: Map<st
   return tools;
 }
 
+/**
+ * Whether `plan_complete` may be called while `mode` is active: execute mode and any mode
+ * with allowPlanComplete. Same predicate that decides the tool's presence in the tool list.
+ */
+export function planCompleteAllowed(mode: string, registry: Map<string, ModeDefinition> = MODE_REGISTRY): boolean {
+  return registry.get(mode)?.allowPlanComplete === true;
+}
+
 /** Initialize MODE_REGISTRY with built-in defaults, then merge user-defined modes. */
 function initModeRegistry(): void {
   const customNotifyTemplate = userConfig.defaultNotifyTemplate ?? "✓ {Name} mode ON";
@@ -495,7 +543,7 @@ function initModeRegistry(): void {
           allowExecute: def.allowExecute ?? true,
           visible: def.visible ?? true,
           enabled: def.enabled ?? true,
-          model: def.model,
+          model: resolveModeModel(def.model),
           labels: {
             notify: def.labels?.notify ?? customNotifyTemplate.replace("{Name}", name.charAt(0).toUpperCase() + name.slice(1)),
             notifyType: def.labels?.notifyType ?? "info",