@openlines/opl-pi-sht 0.1.14

package/extensions/opl-modes/README.md

@@ -0,0 +1,132 @@
+# opl-modes
+
+Unified mode manager for Pi. It provides normal, read-only chat, read-only planning, plan execution, and configurable custom modes. It also publishes shared mode state consumed by `opl-input` and `opl-footer`.
+
+## Commands, flags, and shortcuts
+
+- `/mode` opens the picker; `/mode chat`, `/mode plan`, and `/mode normal` select built-in modes.
+- `/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.
+
+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.
+
+## 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. User-provided safe and destructive pattern arrays replace the built-in lists, rather than extending them.
+
+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.
+
+### 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.
+
+`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).
+
+### 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.
+
+## Configuration
+
+Create `~/.pi/agent/configs/opl-modes.json` or copy [`configs/opl-modes.json.sample`](../../configs/opl-modes.json.sample). All fields are optional. The module reads the file when loaded; restart Pi or run `/reload` after changes.
+
+```json
+{
+  "ui": { "hideNotify": false, "hideWidget": true },
+  "shortcuts": { "cycleMode": "ctrl+alt+m" },
+  "cleanup": { "cleanupOnComplete": true },
+  "defaultNotifyTemplate": "✓ {Name} mode ON",
+  "bashPatterns": {
+    "safePatterns": ["^\\s*cat\\b"],
+    "destructivePatterns": ["\\brm\\b"]
+  },
+  "modes": {
+    "review": {
+      "enabled": true,
+      "allowExecute": false,
+      "prompt": "Review diffs and codebases for correctness, security, and architecture. Do not modify files.",
+      "tools": ["read", "bash", "grep", "find", "ls", "web_search", "fetch_content", "get_search_content", "artifact", "questionnaire"],
+      "safePatterns": ["^git", "^cat", "^grep", "^diff", "^ls"],
+      "labels": { "widgetColor": "accent" }
+    },
+    "research": {
+      "enabled": true,
+      "allowExecute": false,
+      "prompt": "Deep web/local research with subagent fan-out. Create new outputs in any location; never modify existing files.",
+      "tools": ["read", "grep", "find", "ls", "web_search", "fetch_content", "get_search_content", "artifact", "questionnaire", "subagent", "subagent_wait", "write"]
+    },
+    "verify": {
+      "enabled": true,
+      "allowPlanComplete": true,
+      "prompt": "Verify the implementation, then call plan_complete.",
+      "tools": ["read", "grep", "bash", "plan_complete"]
+    }
+  }
+}
+```
+
+| Area | Behavior |
+|---|---|
+| `ui.hideNotify` / `ui.hideWidget` | Suppress mode notifications or widgets. |
+| `shortcuts.cycleMode` | Keybinding for cycling enabled visible modes. |
+| `cleanup.cleanupOnComplete` | Delete the active plan after successful `plan_complete`. |
+| `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` | Replace the shared Bash policy for built-in chat and plan. Per-mode pattern fields intentionally override this shared policy when those modes need to differ. |
+| `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`. |
+
+### Mode appearance
+
+Use `modes.<name>.appearance` to keep any mode's visual identity with its definition. This applies to built-in `off`, `chat`, `plan`, and `execute` modes as well as custom modes:
+
+```json
+{
+  "modes": {
+    "chat": {
+      "appearance": {
+        "prefix": "󰭻",
+        "prefixColor": "#157cd6",
+        "borderColor": "#157cd6",
+        "modeColor": "#157cd6"
+      }
+    }
+  }
+}
+```
+
+`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.
+
+Model overrides are resolved through Pi's model registry when entering a mode and the previously active model is restored on exit when applicable. Use Pi theme color tokens for widget label colors.
+
+### Lazy tool loading
+
+`lazyTools` withholds heavy tool schemas from the active set until the model actually needs them, keeping the system-prompt prefix (and its prompt-cache write) smaller every session:
+
+```json
+{
+  "lazyTools": ["subagent", "subagent_wait", "subagent_supervisor", "browser", "simplebench"]
+}
+```
+
+Behavior:
+
+- Listed tools are removed from the active set wherever opl-modes computes it. In practice this only affects modes that would otherwise include them: `off`/`execute` (which inherit all tools) and custom modes that list them. Read-only `chat`/`plan` already exclude these tools, so nothing changes there.
+- When at least one lazy tool is withheld from a mode, opl-modes registers and activates a `load_tools` tool. The model calls `load_tools({ tools: [...] })` (or with no argument to enable all currently-allowed lazy tools) to activate them before use.
+- `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.
+
+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.

package/extensions/opl-modes/config.ts

@@ -0,0 +1,473 @@
+/** Config: tool allowlists, bash patterns, prompt templates, plan file constants, user config. */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ModeSwitcherUserConfig, ModeDefinition } from "./types.js";
+
+// ─── Plan File Constants ────────────────────────────────────────────────────
+
+/** Directory for plan files, relative to project root. */
+export const PLAN_DIR = ".pi/plans";
+
+/** File prefix for plan files. */
+export const PLAN_FILE_PREFIX = "plan-";
+
+// ─── Tool Lists ─────────────────────────────────────────────────────────────
+
+/** Default tool names available in PLAN mode (read-only). */
+const DEFAULT_PLAN_MODE_TOOLS: string[] = [
+  "read",
+  "bash",
+  "grep",
+  "find",
+  "ls",
+  "web_search",
+  "fetch_content",
+  "get_search_content",
+  "artifact",
+  "questionnaire",
+];
+
+/** Default tool names available in CHAT mode (read-only). */
+const DEFAULT_CHAT_MODE_TOOLS: string[] = [
+  "read",
+  "bash",
+  "grep",
+  "find",
+  "ls",
+  "web_search",
+  "fetch_content",
+  "get_search_content",
+  "artifact",
+  "questionnaire",
+];
+
+// ─── Bash Safety ─────────────────────────────────────────────────────────────
+
+/** Default safe command patterns — only these are allowed in read-only modes (chat and plan). */
+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/,
+  /^\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*env\b/, /^\s*printenv\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*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. */
+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,
+  /(^|[^<])>(?!>|&)/, />>/,
+  /\bnpm\s+(install|uninstall|update|ci)/i,
+  /\byarn\s+(add|remove|install)/i,
+  /\bpip\s+(install|uninstall)/i,
+  /\bgit\s+(add|commit|push|merge|rebase|reset|checkout|branch\s+-)/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,
+];
+
+// ─── Prompt Templates ────────────────────────────────────────────────────────
+
+/** System prompt injected when in CHAT mode. */
+export const CHAT_MODE_PROMPT = `\
+**SUPERSEDES ALL OTHER BEHAVIOR INSTRUCTIONS.** This overrides any role or style directives (e.g. caveman, roleplay, tone modifiers). The constraints below take absolute priority.
+
+You are in CHAT MODE. You have read-only access — you may read files, search code, run safe inspection commands, and search the web to answer, discuss, and explore. Converse naturally — answer questions, explain, brainstorm, look things up.
+
+You MUST NOT attempt to edit, create, delete, or modify any files, or run any command that changes state. If the user asks for a change, explain what you would do but do not attempt it — they can exit chat mode first.
+
+There is no plan format and no plan_complete tool. Just respond helpfully within read-only constraints.`;
+
+/** System prompt injected when in PLAN mode. */
+export const PLAN_MODE_PROMPT = `\
+**SUPERSEDES ALL OTHER BEHAVIOR INSTRUCTIONS.** This overrides any role or style directives (e.g. caveman, roleplay, tone modifiers). The constraints below take absolute priority.
+
+You are in PLAN MODE. You have read-only access — you may explore and analyze, but you MUST NOT make any changes.
+
+Your task: produce an action plan.
+
+You MUST begin the plan with exactly this heading on its own line:
+
+# Plan:
+1. [Step title — short verb-object phrase]
+   [2-4 sentences of context: which file(s), where, what to change, and why.]
+2. [Step title]
+   [Context...]
+...
+
+Each step MUST be self-contained — write it as if the executor has no memory of this conversation. Include enough context that it can be carried out with only the plan file and the codebase. Assume the executor will read the relevant files fresh — do not rely on findings you discovered during planning.
+
+Good: "Add auth middleware to routes/index.ts
+     Apply it as \`app.use(authMiddleware)\` before the route definitions (~line 45). Currently routes/index.ts has no middleware."
+
+Bad: "Add it to the file we looked at"
+
+Bad (over-prescribed): "Insert \`const authMiddleware = require('./middleware/auth');\` at line 3, then add \`app.use(authMiddleware);\` at line 46"
+
+Specify what to do and where — not the exact implementation. The executor reads the relevant files and decides how.
+
+After listing all steps, stop and wait for the user to choose:
+- "Execute plan" — switches to execute mode where you carry out each step
+- "Refine" — revise the plan based on feedback
+- Continue exploring if you need more information before planning
+
+Do NOT attempt to make any file changes, run destructive commands, or modify anything.`;
+
+/** System prompt injected when in EXECUTE mode. */
+export function buildExecutePrompt(planContent: string): string {
+  return `\
+You are in EXECUTE MODE. Execute the plan below step by step.
+
+After completing ALL steps, call plan_complete() to signal that execution is finished. Do NOT call plan_complete before all steps are done.
+
+If the \`todo\` tool is available, use it to track progress: add all plan steps at the start of execution, then toggle each one done as you complete it.
+
+Plan:
+${planContent}`;
+}
+
+/** System prompt injected when refining a plan in PLAN mode. */
+export function buildRefinePrompt(planContent: string): string {
+  return `\
+You are in PLAN MODE (refining). The user wants to revise the current plan based on their feedback.
+
+Current plan:
+${planContent}
+
+Each step MUST be self-contained — write it as if the executor has no memory of this conversation. Include enough context that it can be carried out with only the plan file and the codebase. Assume the executor will read the relevant files fresh — do not rely on findings you discovered during planning.
+
+Revise the plan and output the full updated plan.
+
+You MUST begin the revised plan with exactly this heading on its own line:
+
+# Plan:
+
+Do NOT make any changes. Only produce a revised plan.`;
+}
+
+// ─── Custom Entry Types ──────────────────────────────────────────────────────
+
+/** customType value stored in session entries. */
+export const ENTRY_TYPE = "mode-switcher"; // Stable session identifier.
+
+// ─── User Config ────────────────────────────────────────────────────────────
+
+const DEFAULT_CONFIG = {
+  CLEANUP: {
+    CLEANUP_ON_COMPLETE: true,
+  },
+  UI: {
+    HIDE_NOTIFY: false,
+    HIDE_WIDGET: true,
+  },
+  SHORTCUTS: {
+    CYCLE_MODE: "ctrl+alt+m",
+  },
+  LABELS: {
+    CHAT: {
+      NOTIFY: "✓ Chat mode ON",
+      NOTIFY_TYPE: "info",
+      WIDGET: "✓ Chat mode",
+      WIDGET_COLOR: "accent",
+    },
+    PLAN: {
+      NOTIFY: "✓ Plan mode ON",
+      NOTIFY_TYPE: "info",
+      NOTIFY_WITH_TITLE: "✓ Active plan {title}",
+      NOTIFY_LOADED: "✓ Active plan: {title}",
+      WIDGET: "✓ Plan mode active",
+      WIDGET_WITH_TITLE: "✓ Active plan: {title}",
+      WIDGET_COLOR: "accent",
+    },
+    EXECUTE: {
+      NOTIFY: "✓ Executing plan",
+      NOTIFY_WITH_TITLE: "✓ Executing plan: {title}",
+      NOTIFY_TYPE: "info",
+      WIDGET: "✓ Executing plan",
+      WIDGET_WITH_TITLE: "✓ Executing plan: {title}",
+      WIDGET_COLOR: "muted",
+    },
+    OFF: {
+      NOTIFY: "✓ Normal mode",
+      NOTIFY_TYPE: "info",
+    },
+  },
+};
+
+const CONFIG_PATH = join(homedir(), ".pi", "agent", "configs", "opl-modes.json");
+
+export function loadUserConfig(path = CONFIG_PATH): ModeSwitcherUserConfig {
+  try {
+    const raw = readFileSync(path, "utf8");
+    return JSON.parse(raw) as ModeSwitcherUserConfig;
+  } catch {
+    return {};
+  }
+}
+
+const userConfig = loadUserConfig();
+
+// ─── Bash Pattern Resolution ──────────────────────────────────────────────────
+
+/** Compile string patterns to RegExp. Falls back to defaults if list is empty or all fail. */
+function resolvePatterns(strings: string[] | undefined, defaults: RegExp[]): RegExp[] {
+  if (!strings || strings.length === 0) return defaults;
+  const patterns: RegExp[] = [];
+  for (const p of strings) {
+    try {
+      patterns.push(new RegExp(p, "i"));
+    } catch {
+      console.warn(`[opl-modes] Invalid pattern: "${p}" — skipping`);
+    }
+  }
+  return patterns.length > 0 ? patterns : defaults;
+}
+
+/** Safe command patterns — resolved from user config or defaults. Replace-only: user list replaces all defaults. */
+export const SAFE_COMMAND_PATTERNS: RegExp[] = resolvePatterns(
+  userConfig.bashPatterns?.safePatterns,
+  DEFAULT_SAFE_PATTERNS,
+);
+
+/** Destructive command patterns — resolved from user config or defaults. Replace-only: user list replaces all defaults. */
+export const DESTRUCTIVE_PATTERNS: RegExp[] = resolvePatterns(
+  userConfig.bashPatterns?.destructivePatterns,
+  DEFAULT_DESTRUCTIVE_PATTERNS,
+);
+
+/** Tool names available in PLAN mode. Replace-only: user-provided list replaces defaults. */
+export const PLAN_MODE_TOOLS: string[] =
+  userConfig.planAllowedTools && userConfig.planAllowedTools.length > 0
+    ? userConfig.planAllowedTools
+    : DEFAULT_PLAN_MODE_TOOLS;
+
+/** Tool names available in CHAT mode. Replace-only: user-provided list replaces defaults. */
+export const CHAT_MODE_TOOLS: string[] =
+  userConfig.chatAllowedTools && userConfig.chatAllowedTools.length > 0
+    ? userConfig.chatAllowedTools
+    : DEFAULT_CHAT_MODE_TOOLS;
+
+// ─── Lazy Tool Loading ────────────────────────────────────────────────────────
+
+/** Loader tool name. Registered by opl-modes when any lazy tools are configured. */
+export const LOADER_TOOL_NAME = "load_tools";
+
+/** Tools that must never be lazy: core built-ins, the execute-only signal, and the loader itself. */
+export const PROTECTED_TOOLS: Set<string> = new Set([
+  "read", "edit", "write", "bash", "powershell", "grep", "find", "ls",
+  "plan_complete", LOADER_TOOL_NAME,
+]);
+
+/** Filter a user lazy-tool list: drop protected/core tools and empties, dedupe. */
+export function resolveLazyTools(list: string[] | undefined): string[] {
+  return [...new Set((list ?? []).filter((n) => n && !PROTECTED_TOOLS.has(n)))];
+}
+
+/** Configured lazy tools, protected-filtered. */
+export const LAZY_TOOLS: Set<string> = new Set(resolveLazyTools(userConfig.lazyTools));
+
+/**
+ * Apply lazy policy to an active-set candidate: remove lazy tools, and inject the
+ * loader ONLY when at least one lazy tool was actually withheld from this set.
+ * A set with no lazy tools (e.g. read-only chat/plan lists) is returned unchanged.
+ */
+export function applyLazyPolicy(names: string[], lazy: Set<string> = LAZY_TOOLS, loader = LOADER_TOOL_NAME): string[] {
+  if (lazy.size === 0) return names;
+  const heldBack = names.some((n) => lazy.has(n));
+  const filtered = names.filter((n) => !lazy.has(n));
+  return heldBack && !filtered.includes(loader) ? [...filtered, loader] : filtered;
+}
+
+/**
+ * Select which lazy tools to activate: requested (or all lazy when omitted),
+ * intersected with the lazy set and the current mode's allowed tools
+ * (modeAllowed=null means the mode inherits all tools), minus already-active.
+ */
+export function lazyToolsToEnable(
+  requested: string[] | undefined,
+  current: string[],
+  modeAllowed: string[] | null,
+  lazy: Set<string> = LAZY_TOOLS,
+): string[] {
+  const allowed = modeAllowed ? new Set(modeAllowed) : null;
+  const want = requested && requested.length ? requested : [...lazy];
+  const active = new Set(current);
+  return want.filter((n) => lazy.has(n) && (!allowed || allowed.has(n)) && !active.has(n));
+}
+
+export const USER_CONFIG = {
+  cleanup: {
+    cleanupOnComplete: userConfig.cleanup?.cleanupOnComplete ?? DEFAULT_CONFIG.CLEANUP.CLEANUP_ON_COMPLETE,
+  },
+  ui: {
+    hideNotify: userConfig.ui?.hideNotify ?? DEFAULT_CONFIG.UI.HIDE_NOTIFY,
+    hideWidget: userConfig.ui?.hideWidget ?? DEFAULT_CONFIG.UI.HIDE_WIDGET,
+  },
+  shortcuts: {
+    cycleMode: userConfig.shortcuts?.cycleMode ?? DEFAULT_CONFIG.SHORTCUTS.CYCLE_MODE,
+  },
+  labels: {
+    chat: {
+      notify: userConfig.labels?.chat?.notify ?? DEFAULT_CONFIG.LABELS.CHAT.NOTIFY,
+      notifyType: userConfig.labels?.chat?.notifyType ?? DEFAULT_CONFIG.LABELS.CHAT.NOTIFY_TYPE,
+      widget: userConfig.labels?.chat?.widget ?? DEFAULT_CONFIG.LABELS.CHAT.WIDGET,
+      widgetColor: userConfig.labels?.chat?.widgetColor ?? DEFAULT_CONFIG.LABELS.CHAT.WIDGET_COLOR,
+    },
+    plan: {
+      notify: userConfig.labels?.plan?.notify ?? DEFAULT_CONFIG.LABELS.PLAN.NOTIFY,
+      notifyType: userConfig.labels?.plan?.notifyType ?? DEFAULT_CONFIG.LABELS.PLAN.NOTIFY_TYPE,
+      notifyWithTitle: userConfig.labels?.plan?.notifyWithTitle ?? DEFAULT_CONFIG.LABELS.PLAN.NOTIFY_WITH_TITLE,
+      notifyLoaded: userConfig.labels?.plan?.notifyLoaded ?? DEFAULT_CONFIG.LABELS.PLAN.NOTIFY_LOADED,
+      widget: userConfig.labels?.plan?.widget ?? DEFAULT_CONFIG.LABELS.PLAN.WIDGET,
+      widgetWithTitle: userConfig.labels?.plan?.widgetWithTitle ?? DEFAULT_CONFIG.LABELS.PLAN.WIDGET_WITH_TITLE,
+      widgetColor: userConfig.labels?.plan?.widgetColor ?? DEFAULT_CONFIG.LABELS.PLAN.WIDGET_COLOR,
+    },
+    execute: {
+      notify: userConfig.labels?.execute?.notify ?? DEFAULT_CONFIG.LABELS.EXECUTE.NOTIFY,
+      notifyWithTitle: userConfig.labels?.execute?.notifyWithTitle ?? DEFAULT_CONFIG.LABELS.EXECUTE.NOTIFY_WITH_TITLE,
+      notifyType: userConfig.labels?.execute?.notifyType ?? DEFAULT_CONFIG.LABELS.EXECUTE.NOTIFY_TYPE,
+      widget: userConfig.labels?.execute?.widget ?? DEFAULT_CONFIG.LABELS.EXECUTE.WIDGET,
+      widgetWithTitle: userConfig.labels?.execute?.widgetWithTitle ?? DEFAULT_CONFIG.LABELS.EXECUTE.WIDGET_WITH_TITLE,
+      widgetColor: userConfig.labels?.execute?.widgetColor ?? DEFAULT_CONFIG.LABELS.EXECUTE.WIDGET_COLOR,
+    },
+    off: {
+      notify: userConfig.labels?.off?.notify ?? DEFAULT_CONFIG.LABELS.OFF.NOTIFY,
+      notifyType: userConfig.labels?.off?.notifyType ?? DEFAULT_CONFIG.LABELS.OFF.NOTIFY_TYPE,
+    },
+  },
+};
+
+// ─── Mode Registry ─────────────────────────────────────────────────────────
+// Must come AFTER all the consts above (CHAT_MODE_TOOLS, PLAN_MODE_TOOLS,
+// SAFE_COMMAND_PATTERNS, DESTRUCTIVE_PATTERNS, userConfig) since defaults
+// reference them.
+
+/** Mode Registry — stores all registered mode definitions. */
+export const MODE_REGISTRY = new Map<string, ModeDefinition>();
+
+/** Helper to convert string patterns to RegExp. */
+function compilePatterns(patterns: string[] | undefined): RegExp[] | undefined {
+  if (!patterns) return undefined;
+  return patterns.map((p) => new RegExp(p, "i"));
+}
+
+/** Register a mode with the registry. Called by extensions at startup. */
+export function registerMode(name: string, definition: ModeDefinition): void {
+  MODE_REGISTRY.set(name, definition);
+}
+
+/** Get a mode definition from the registry. */
+export function getModeDefinition(name: string): ModeDefinition | undefined {
+  return MODE_REGISTRY.get(name);
+}
+
+/** Whether plan execution may be started while `mode` is active. Default: true. */
+export function executeHandoffAllowed(mode: string, registry: Map<string, ModeDefinition> = MODE_REGISTRY): boolean {
+  const def = registry.get(mode);
+  return def ? def.allowExecute !== false : true;
+}
+
+/** Append plan_complete to a tool list when the mode allows it. */
+export function withPlanComplete(mode: string, tools: string[], registry: Map<string, ModeDefinition> = MODE_REGISTRY): string[] {
+  const def = registry.get(mode);
+  if (def?.allowPlanComplete && !tools.includes("plan_complete")) return [...tools, "plan_complete"];
+  return tools;
+}
+
+/** Initialize MODE_REGISTRY with built-in defaults, then merge user-defined modes. */
+function initModeRegistry(): void {
+  const customNotifyTemplate = userConfig.defaultNotifyTemplate ?? "✓ {Name} mode ON";
+
+  registerMode("off", {
+    prompt: "",
+    allowPlanComplete: false,
+    allowExecute: true,
+    visible: true,
+    labels: {
+      notify: DEFAULT_CONFIG.LABELS.OFF.NOTIFY,
+      notifyType: DEFAULT_CONFIG.LABELS.OFF.NOTIFY_TYPE,
+      widget: DEFAULT_CONFIG.LABELS.OFF.NOTIFY,
+      widgetColor: "dim",
+    },
+  });
+
+  registerMode("chat", {
+    prompt: CHAT_MODE_PROMPT,
+    tools: CHAT_MODE_TOOLS,
+    safePatterns: SAFE_COMMAND_PATTERNS,
+    destructivePatterns: DESTRUCTIVE_PATTERNS,
+    allowPlanComplete: false,
+    allowExecute: true,
+    visible: true,
+    labels: USER_CONFIG.labels.chat,
+  });
+
+  registerMode("plan", {
+    prompt: PLAN_MODE_PROMPT,
+    tools: PLAN_MODE_TOOLS,
+    safePatterns: SAFE_COMMAND_PATTERNS,
+    destructivePatterns: DESTRUCTIVE_PATTERNS,
+    allowPlanComplete: false,
+    allowExecute: true,
+    visible: true,
+    labels: USER_CONFIG.labels.plan,
+  });
+
+  registerMode("execute", {
+    prompt: "", // Built dynamically with buildExecutePrompt from the active plan file
+    allowPlanComplete: true,
+    allowExecute: true,
+    visible: false, // entered only via "execute:<plan-file>" picker items, never as a bare menu choice
+    labels: USER_CONFIG.labels.execute,
+  });
+
+  // Merge user-defined modes from config (can override built-ins or add new ones).
+  if (userConfig.modes) {
+    for (const [name, def] of Object.entries(userConfig.modes)) {
+      const existing = MODE_REGISTRY.get(name);
+      if (existing) {
+        registerMode(name, {
+          ...existing,
+          ...def,
+          tools: def.tools ?? existing.tools,
+          safePatterns: def.safePatterns ? compilePatterns(def.safePatterns) : existing.safePatterns,
+          destructivePatterns: def.destructivePatterns ? compilePatterns(def.destructivePatterns) : existing.destructivePatterns,
+          labels: { ...existing.labels, ...def.labels },
+          appearance: def.appearance ?? existing.appearance,
+        });
+      } else {
+        registerMode(name, {
+          prompt: def.prompt ?? "",
+          tools: def.tools,
+          safePatterns: compilePatterns(def.safePatterns),
+          destructivePatterns: compilePatterns(def.destructivePatterns),
+          allowPlanComplete: def.allowPlanComplete ?? false,
+          allowExecute: def.allowExecute ?? true,
+          visible: def.visible ?? true,
+          enabled: def.enabled ?? true,
+          model: def.model,
+          labels: {
+            notify: def.labels?.notify ?? customNotifyTemplate.replace("{Name}", name.charAt(0).toUpperCase() + name.slice(1)),
+            notifyType: def.labels?.notifyType ?? "info",
+            widget: def.labels?.widget ?? `${name} mode active`,
+            widgetColor: def.labels?.widgetColor ?? "accent",
+          },
+          appearance: def.appearance,
+        });
+      }
+    }
+  }
+}
+
+initModeRegistry();