@tt-a1i/openpi 0.2.0 → 0.3.1

package/README.md

@@ -5,12 +5,12 @@
 <h1 align="center">OpenPI</h1>
 
 <p align="center">
-  <strong>Small harness. Deep extensions. Clean context.</strong>
+  <strong>Pi at the core. Power on demand.</strong>
 </p>
 
 <p align="center">
-  给 <a href="https://pi.dev">Pi</a> 加一层可靠运行时：后台执行、隔离 Subagent、可恢复 Workflow、持续任务与可观测终端。<br />
-  不替换 Pi，不替你选模型，也不把另一套 Agent 平台塞进来。
+  默认像 <a href="https://pi.dev">Pi</a> 一样轻；任务需要时，一句话展开后台执行、隔离 Subagent、可恢复 Workflow 与持续任务。<br />
+  不替换 Pi，不重写 Agent loop，不让高级能力长期占据每一次对话。
 </p>
 
 <p align="center">
@@ -23,6 +23,7 @@
 
 <p align="center">
   <a href="#30-秒开始"><strong>30 秒开始</strong></a> ·
+  <a href="#默认轻按需强">设计</a> ·
   <a href="#openpi-解决什么">解决什么</a> ·
   <a href="#能力地图">能力地图</a> ·
   <a href="#运行模型">运行模型</a> ·
@@ -38,6 +39,27 @@
 
 ---
 
+## 默认轻，按需强
+
+**OpenPI 最强的地方，不是工具多，而是复杂度只在值得的时候出现。**
+
+普通编码任务继续走 Pi 原生路径：`read`、`bash`、`edit`、`write`，完整历史、Session compaction、工具输出边界、显式 Bash timeout 与 Provider loop。OpenPI 不额外投影历史，不改写测试超时，也不向模型塞恢复提示；只保留独立的工作区删除保护。
+
+任务一旦需要长期进程、并行调研、隔离实现、多阶段协作或跨回合推进，高级能力仍然完整存在。用户直接提出需求，OpenPI 就在当轮加载对应能力；没用到的能力不会常驻模型工具面。
+
+> **轻路径不缴复杂度税，重任务不缺工程能力。** 这不是一套替代 Pi 的 Agent Runtime，而是一组遵守 Pi 生命周期、Session、Provider、模型与 Trust 边界的 Pi-native 深扩展。
+
+| 使用场景                     | 模型看到什么                                      | OpenPI 的行为                                     |
+| ---------------------------- | ------------------------------------------------- | ------------------------------------------------- |
+| 普通编码任务                 | Pi 原生 `read` / `bash` / `edit` / `write`        | 默认不常驻任何 OpenPI 模型工具                    |
+| 用户明确要求委派或高级能力   | 仅与意图匹配的能力组                              | 在当轮开始前直接加载，不要求用户记住工具名        |
+| 用户主动开启 `adaptive`      | 一个小型 `openpi_load_tools` 网关                 | 主模型判断确有收益时，可自主加载一个能力组        |
+| 后台任务或子 Agent 已经运行  | 对应的状态、等待、继续与停止工具                  | 管理面随真实资源出现，资源结束后按生命周期收敛    |
+
+这套设计保住了两件通常很难同时拥有的东西：Pi 的清爽基本面，以及完整工程工作台的能力上限。
+
+---
+
 ## 30 秒开始
 
 ```bash
@@ -310,7 +332,7 @@ cwd  model  thinking  context  cache  cost  throughput   git  PR
 - 支持 `powerline`、`powerline-mono`、`compact`，也支持自定义多行布局；
 - 终端变窄时按优先级隐藏次要指标，不机械截断尾部；
 - Subagent 与 Workflow 活动时自动出现，空闲时不占空间；
-- Bash、Write/Edit 与 Subagent 结果可独立选择 `full` 或 `compact`；
+- Bash、Write/Edit 与 Subagent 结果可独立选择 `full` 或 `compact`；Subagent 的 compact 模式只显示状态摘要，不暴露原始子 Agent 正文；
 - 折叠内容用 Pi 的 `app.tools.expand` 快捷键临时展开，默认 `Ctrl+O`；
 - Git 状态本地刷新；只有显式运行 `/pr` 才查询 GitHub PR。
 
@@ -375,7 +397,7 @@ macOS/Linux arm64 与 x64 缺少二进制时，OpenPI 会从官方 Release 下
 | Next-action Suggestion       | 关闭；启用时显式选择 Registry 模型与 reasoning |
 | Workflow 并发 / 总调用       | 8 / 128；硬上限 64 / 1024                      |
 | 大型 Header                  | 关闭                                           |
-| Dashboard Footer             | 开启；单行 `powerline`                         |
+| Dashboard Footer             | 开启；单行 `plain`                           |
 | Subagent / Bash / Write/Edit | `full` / `compact` / `compact`                 |
 | Post-edit 命令               | 关闭；单条命令最多 500 字符                    |
 | 内置角色模型                 | 全部继承父模型                                 |
@@ -469,7 +491,7 @@ Capability discovery 默认是 `explicit`：普通父 Session 不常驻任何 Op
 <details>
 <summary><strong>Subagent 会阻塞主 Agent 吗？</strong></summary>
 
-`subagent_spawn` 立即返回，结束后自动回传。只有显式调用 `subagent_wait` 才会等待；它只适合下一步确实依赖结果的场景。
+`subagent_spawn` 立即返回，结束后自动回传并重新唤醒主 Agent。交互会话没有其他工作时，主 Agent 应结束当前轮、让用户继续交互；“下一步依赖结果”本身不是阻塞理由。只有用户明确要求当前回复等完，或非交互自动化必须在同一次调用中返回完整结果时，才应调用 `subagent_wait`。
 
 </details>
 

package/SETUP.md

@@ -54,7 +54,7 @@ Use the single canonical package-owned command. `/my-pi-setup` remains a compati
 /openpi-setup 清除 explorer 的模型，让它继承父模型
 ```
 
-Capability discovery defaults to `explicit`, preserving the zero-resident OpenPI tool surface until the user asks for a capability. `adaptive` is an explicit opt-in that keeps only `openpi_load_tools` visible and allows the model to load a useful group on its own; because this can start Subagents, Workflows, or background processes, normal permission and configured concurrency/call limits still apply. Changing the setting updates the current Session immediately, while already loaded groups remain stable for that Session. Next-action suggestions default to off. Run `/openpi-setup` to explicitly choose an available model and reasoning level. After a fully settled main-agent run, one suggestion may appear as dim inline text on the first row of an empty editor; reserved cells at the row end keep CJK IME preedit from overwriting it. `Right` accepts it into the editor without submitting, while any other editor input dismisses it. Suggestions are ephemeral and never enter session history or model context. Workflows default to 8 concurrent agents and 128 total agent calls per run; configurable hard maxima are 64 and 1024. The large decorative header defaults off and the custom dashboard footer defaults on with a one-line Powerline layout (`cwd model thinking context cache cost throughput |flex| git pr`). Footer presets are `powerline`, `powerline-mono`, and `compact`; style can also be set independently to `plain`, `powerline`, or `powerline-mono`. Custom layouts use a 2D `footerLines` array with at most one `flex` per row for left/right alignment. Nerd Font only affects powerline separator glyphs (``); metric text stays readable without it. Footer changes apply immediately in the active TUI session. Subagent results default to the existing full display; users who do not usually inspect implementation detail can select compact previews. Bash defaults to a folded one-line command with bounded output and a hidden-line count. Write/Edit defaults to an extra-short folded preview capped at three rendered lines including the operation header; its hidden-line hint remains inside the operation's status background. Select full independently for any category to keep it expanded. Compact views temporarily expand with `app.tools.expand` (`Ctrl+O` by default). An optional post-edit command is off by default: set one (for example `npm run format`, maximum 500 characters) and it runs once in the background after each interactive-TUI turn with successful Write/Edit operations, with failures reported as a notification. It deliberately does not guess whether arbitrary Bash commands changed files. Built-in Agent roles `explorer`, `implementer`, `reviewer`, and `advisor` are shared by `subagent_spawn.agent_type` and Workflow `agent(..., { agent_type })`; all inherit the parent model by default. `/openpi-setup` may assign a currently available Registry model to any subset; clearing one returns it to inheritance and omitted roles stay unchanged. Model precedence is explicit call > selected role-file model > setup assignment > parent inheritance; effort is explicit call > selected role > parent. A trusted project `.pi/agents/<role>.md` overrides global `~/.pi/agent/agents/<role>.md`, which overrides the complete built-in role definition; overrides are diagnosed. Role-model changes apply to the next spawn or Workflow agent call without reload. Configuration is stored privately at `~/.pi/agent/my-pi-setup.json`.
+Capability discovery defaults to `explicit`, preserving the zero-resident OpenPI tool surface until the user asks for a capability. `adaptive` is an explicit opt-in that keeps only `openpi_load_tools` visible and allows the model to load a useful group on its own; because this can start Subagents, Workflows, or background processes, normal permission and configured concurrency/call limits still apply. Changing the setting updates the current Session immediately, while already loaded groups remain stable for that Session. Next-action suggestions default to off. Run `/openpi-setup` to explicitly choose an available model and reasoning level. After a fully settled main-agent run, one suggestion may appear as dim inline text on the first row of an empty editor; reserved cells at the row end keep CJK IME preedit from overwriting it. `Right` accepts it into the editor without submitting, while any other editor input dismisses it. Suggestions are ephemeral and never enter session history or model context. Workflows default to 8 concurrent agents and 128 total agent calls per run; configurable hard maxima are 64 and 1024. The large decorative header defaults off and the custom dashboard footer defaults on with a one-line Powerline layout (`cwd model thinking context cache cost throughput |flex| git pr`). Footer presets are `powerline`, `powerline-mono`, and `compact`; style can also be set independently to `plain`, `powerline`, or `powerline-mono`. Custom layouts use a 2D `footerLines` array with at most one `flex` per row for left/right alignment. Nerd Font only affects powerline separator glyphs (``); metric text stays readable without it. Footer changes apply immediately in the active TUI session. Subagent results default to the existing full display; compact mode shows only bounded status rows and keeps raw child reports behind `app.tools.expand` (`Ctrl+O` by default). Bash defaults to a folded one-line command with bounded output and a hidden-line count. Write/Edit defaults to an extra-short folded preview capped at three rendered lines including the operation header; its hidden-line hint remains inside the operation's status background. Select full independently for any category to keep it expanded. Compact views temporarily expand with `app.tools.expand`. An optional post-edit command is off by default: set one (for example `npm run format`, maximum 500 characters) and it runs once in the background after each interactive-TUI turn with successful Write/Edit operations, with failures reported as a notification. It deliberately does not guess whether arbitrary Bash commands changed files. Built-in Agent roles `explorer`, `implementer`, `reviewer`, and `advisor` are shared by `subagent_spawn.agent_type` and Workflow `agent(..., { agent_type })`; all inherit the parent model by default. `/openpi-setup` may assign a currently available Registry model to any subset; clearing one returns it to inheritance and omitted roles stay unchanged. Model precedence is explicit call > selected role-file model > setup assignment > parent inheritance; effort is explicit call > selected role > parent. A trusted project `.pi/agents/<role>.md` overrides global `~/.pi/agent/agents/<role>.md`, which overrides the complete built-in role definition; overrides are diagnosed. Role-model changes apply to the next spawn or Workflow agent call without reload. Configuration is stored privately at `~/.pi/agent/my-pi-setup.json`.
 
 ## Session Goal and Tasks
 

package/extensions/capabilities/index.ts

@@ -17,7 +17,10 @@ import {
   resetOpenPiToolSurface,
 } from "../shared/tool-surface.ts";
 
-const CapabilitySchema = Type.Enum(OPENPI_CAPABILITY_NAMES);
+const CapabilitySchema = Type.Unsafe<OpenPiCapability>({
+  type: "string",
+  enum: OPENPI_CAPABILITY_NAMES,
+});
 
 const OpenPiLoadToolsParameters = Type.Object({
   groups: Type.Optional(

package/extensions/plan-mode/bash-policy.ts

@@ -25,24 +25,22 @@
  */
 
 /**
- * Any of these means the text is more than one plain command — a pipeline, a
- * sequence, a redirect, a substitution, a glob, or a background job. Rather
- * than parse shell (where every parser bug is a bypass), refuse outright.
- *
- * `\` is here because a line continuation splices in the next line; `$` covers
- * both `$(...)` and a `$VAR` that expands into arguments never inspected here.
+ * This module does not parse shell or admit shell composition. Its small
+ * tokenizer only recognizes words and quoted literal spans. `$`, backticks
+ * and `\` are refused everywhere; shell metacharacters are refused outside
+ * quotes. Globs are also refused outside quotes because the shell would expand
+ * them before the allowlisted program sees them, while a quoted glob is a
+ * literal pattern interpreted by that read-only program itself.
  */
-const SHELL_METACHARACTERS = /[;&|<>$`\\!*?{}()[\]\n\r#]/;
+const UNQUOTED_SHELL_METACHARACTERS = /[;&|<>(){}\n\r#]/;
+const EXPANSION_CHARACTERS = /[$`\\]/;
+const UNQUOTED_GLOB_CHARACTERS = new Set(["*", "?", "[", "]"]);
 
 /**
- * Tilde expansion, but only where a shell would actually expand it: at the
- * start of a word. `HEAD~3` is ordinary revision syntax and must survive,
- * while `~/notes` and `~user/x` resolve to a path this module never sees.
+ * Tilde expansion is refused only at the start of an unquoted word. `HEAD~3`
+ * is ordinary revision syntax and must survive, while `~/notes` and
+ * `~user/x` resolve to a path this module never sees.
  */
-const TILDE_EXPANSION = /(^|\s)~/;
-
-/** Quotes hide word boundaries from the tokenizer below, so they are refused too. */
-const QUOTES = /["']/;
 
 /**
  * Read-only git subcommands. Absent on purpose: `config`, `stash`, `tag`,
@@ -194,6 +192,94 @@ const GH_FLAGS = new Set([
   "--comments",
 ]);
 
+const RG_FLAGS = new Set([
+  "-n",
+  "--line-number",
+  "-i",
+  "--ignore-case",
+  "-l",
+  "--files-with-matches",
+  "-c",
+  "--count",
+  "-w",
+  "-F",
+  "--fixed-strings",
+  "-e",
+  "--regexp",
+  "-g",
+  "--glob",
+  "-t",
+  "--type",
+  "--files",
+  "--hidden",
+  "--no-ignore",
+  "-A",
+  "-B",
+  "-C",
+  "--after-context",
+  "--before-context",
+  "--context",
+  "-m",
+  "--max-count",
+  "-o",
+  "--only-matching",
+  "--sort",
+  "--json",
+  "--color",
+  "-H",
+  "-N",
+  "--no-filename",
+  "-v",
+  "--invert-match",
+  "-u",
+  "-uu",
+]);
+
+const FD_FLAGS = new Set([
+  "-e",
+  "--extension",
+  "-t",
+  "--type",
+  "-d",
+  "--max-depth",
+  "--min-depth",
+  "-H",
+  "--hidden",
+  "-I",
+  "--no-ignore",
+  "-g",
+  "--glob",
+  "-F",
+  "--fixed-strings",
+  "-p",
+  "--full-path",
+  "-a",
+  "--absolute-path",
+  "-l",
+  "--list-details",
+  "--color",
+  "-0",
+  "-S",
+  "--size",
+]);
+
+const LS_FLAGS = new Set([
+  "-l",
+  "-a",
+  "-A",
+  "-h",
+  "-t",
+  "-r",
+  "-R",
+  "-d",
+  "-1",
+  "-S",
+  "-F",
+  "--color",
+]);
+const WC_FLAGS = new Set(["-l", "-w", "-c", "-m"]);
+const HEAD_TAIL_FLAGS = new Set(["-n", "-c", "--lines", "--bytes"]);
+
 /** `-5`, `-20`: git's count shorthand, which is a number rather than a flag. */
 const NUMERIC_SHORTHAND = /^-\d+$/;
 
@@ -208,6 +294,83 @@ const refuse = (reason: string): BashPlanDecision => ({
   reason,
 });
 
+/**
+ * Tokenize words without pretending to be a shell parser. Quoted spans are
+ * removed and become literal text; no expansion or command composition is
+ * supported. The validation happens while tokenizing so an unquoted glob can
+ * never be mistaken for a literal program argument.
+ */
+function tokenize(command: string) {
+  const words: string[] = [];
+  let word = "";
+  let inWord = false;
+  let quote: "'" | '"' | undefined;
+  let wordStartsUnquoted = false;
+
+  for (const character of command) {
+    if (quote) {
+      if (character === quote) {
+        quote = undefined;
+      } else if (EXPANSION_CHARACTERS.test(character)) {
+        return refuse(
+          `plan mode rejected expansion character ${JSON.stringify(character)} — remove expansion syntax and pass literal arguments instead`,
+        );
+      } else {
+        word += character;
+      }
+      inWord = true;
+      continue;
+    }
+
+    if (EXPANSION_CHARACTERS.test(character)) {
+      return refuse(
+        `plan mode rejected expansion character ${JSON.stringify(character)} — remove expansion syntax and pass literal arguments instead`,
+      );
+    }
+    if (UNQUOTED_SHELL_METACHARACTERS.test(character)) {
+      return refuse(
+        `plan mode rejected unquoted shell metacharacter ${JSON.stringify(character)} — run a single plain command without shell composition`,
+      );
+    }
+    if (UNQUOTED_GLOB_CHARACTERS.has(character)) {
+      return refuse(
+        "plan mode will not run an unquoted glob because the shell would expand it — quote it instead, e.g. --glob '*.ts'",
+      );
+    }
+    if (character === "'" || character === '"') {
+      quote = character;
+      inWord = true;
+      if (!word) wordStartsUnquoted = false;
+      continue;
+    }
+    if (/\s/.test(character)) {
+      if (inWord) {
+        words.push(word);
+        word = "";
+        inWord = false;
+        wordStartsUnquoted = false;
+      }
+      continue;
+    }
+    if (!inWord) wordStartsUnquoted = true;
+    if (wordStartsUnquoted && word.length === 0 && character === "~") {
+      return refuse(
+        "plan mode does not run tilde-expanded paths — use a path relative to the project instead",
+      );
+    }
+    word += character;
+    inWord = true;
+  }
+
+  if (quote) {
+    return refuse(
+      `plan mode rejected an unterminated ${quote === "'" ? "single" : "double"} quote — close the quote or pass a literal argument instead`,
+    );
+  }
+  if (inWord) words.push(word);
+  return { allowed: true as const, words };
+}
+
 /** Split `--flag=value` into the flag part the allowlists are keyed on. */
 function flagName(word: string) {
   const eq = word.indexOf("=");
@@ -223,16 +386,27 @@ function scanArguments(
   words: readonly string[],
   allowed: ReadonlySet<string>,
   program: string,
+  /**
+   * Whether `-la` may stand for `-l -a`. Only the file-inspection programs opt
+   * in: git and gh keep their historical one-flag-per-word rule, so widening
+   * the tokenizer cannot quietly widen their surface too.
+   */
+  allowShortClusters = false,
 ): BashPlanDecision {
   for (const word of words) {
     if (word === "--") break;
     if (!word.startsWith("-")) continue;
     if (NUMERIC_SHORTHAND.test(word)) continue;
-    if (!allowed.has(flagName(word))) {
-      return refuse(
-        `plan mode does not recognize "${word}" as a read-only ${program} option, so it will not run this command`,
-      );
-    }
+    if (allowed.has(flagName(word))) continue;
+    const isAllowedCluster =
+      allowShortClusters &&
+      !word.startsWith("--") &&
+      word.length > 2 &&
+      [...word.slice(1)].every((character) => allowed.has(`-${character}`));
+    if (isAllowedCluster) continue;
+    return refuse(
+      `plan mode does not recognize "${word}" as a read-only ${program} option — use only the allowlisted ${program} flags`,
+    );
   }
   return { allowed: true };
 }
@@ -249,21 +423,10 @@ export function planBashDecision(command: unknown): BashPlanDecision {
   const text = command.trim();
   if (!text) return refuse("plan mode received an empty command");
 
-  if (SHELL_METACHARACTERS.test(text)) {
-    return refuse(
-      "plan mode only runs a single plain command — no pipes, redirects, substitutions, globs, or chained commands",
-    );
-  }
-  if (QUOTES.test(text)) {
-    return refuse("plan mode only runs unquoted commands while planning");
-  }
-  if (TILDE_EXPANSION.test(text)) {
-    return refuse(
-      "plan mode does not run commands with `~` paths — give a path relative to the project instead",
-    );
-  }
-
-  const [program, ...rest] = text.split(/\s+/);
+  const tokenized = tokenize(text);
+  if (!("words" in tokenized)) return tokenized;
+  const [program, ...rest] = tokenized.words;
+  if (!program) return refuse("plan mode received an empty command");
 
   /*
    * The subcommand must be the FIRST word, never "the first word that is not a
@@ -300,14 +463,28 @@ export function planBashDecision(command: unknown): BashPlanDecision {
     return scanArguments(args, GH_FLAGS, "gh");
   }
 
-  /*
-   * Nothing else is admitted. `ls`, `cat`, `head`, `tail` and `wc` were on an
-   * earlier version of this list and are gone: plan mode already grants the
-   * `ls`, `read`, `grep` and `fd`/`rg` TOOLS, so those shell forms added no
-   * capability while each contributed its own flag grammar to get wrong
-   * (`file --compile` and `tree -ao` both write files).
-   */
+  const readOnlyPrograms = new Map([
+    ["rg", RG_FLAGS],
+    ["fd", FD_FLAGS],
+    ["ls", LS_FLAGS],
+    ["wc", WC_FLAGS],
+    ["head", HEAD_TAIL_FLAGS],
+    ["tail", HEAD_TAIL_FLAGS],
+  ]);
+  const flags = readOnlyPrograms.get(program);
+  if (flags) {
+    if (
+      program === "tail" &&
+      rest.some((word) => word === "-f" || word === "--follow")
+    ) {
+      return refuse(
+        'plan mode refuses "tail -f/--follow" because it can block forever — use a finite tail command instead',
+      );
+    }
+    return scanArguments(rest, flags, program, true);
+  }
+
   return refuse(
-    `plan mode runs only read-only git and gh investigation commands while planning, not "${program}" — use the read, ls, grep or fd tools for files`,
+    `plan mode does not allow "${program}" — use read-only git and gh investigation commands; available commands are git, gh, rg, fd, ls, wc, head or tail, plus the read/grep/fd tools`,
   );
 }

package/extensions/plan-mode/index.ts

@@ -142,8 +142,12 @@ export const PLAN_READY_ACTIONS = {
   continue: "Continue planning",
   current: "Implement in this session",
   fresh: "Start a fresh session",
+  off: "Turn plan mode off",
 } as const;
 
+/** Menu label for the same effect as `/plan done`. */
+const FINALIZE_NOW = "Finalize now";
+
 export function buildPlanImplementationPrompt(plan: string) {
   return [
     "Implement the approved plan below. Re-check the repository state before editing, follow the project instructions, and verify the finished change.",
@@ -257,11 +261,7 @@ export default function planMode(pi: ExtensionAPI) {
     if (!ctx.hasUI) return;
     ctx.ui.setStatus(
       "plan-mode",
-      readyPlan
-        ? "plan mode · ready"
-        : planning
-          ? "plan mode · read-only"
-          : undefined,
+      readyPlan ? "plan ready" : planning ? "plan mode" : undefined,
     );
   };
 
@@ -371,9 +371,25 @@ export default function planMode(pi: ExtensionAPI) {
       implementHere(ctx);
     } else if (choice === PLAN_READY_ACTIONS.fresh) {
       await implementFresh(ctx);
+    } else if (choice === PLAN_READY_ACTIONS.off) {
+      clearPlan(ctx);
+      ctx.ui.notify("Plan mode is off.", "info");
     }
   };
 
+  const requestPlanFinalization = () => {
+    pi.sendMessage(
+      {
+        customType: "plan-finalize-requested",
+        content:
+          "Finalize the plan now. Resolve any remaining material ambiguity with ask_user; otherwise call plan_ready alone with the complete implementation-ready Markdown plan. Do not implement it.",
+        display: true,
+        details: {},
+      },
+      { deliverAs: "followUp", triggerTurn: true },
+    );
+  };
+
   pi.registerTool({
     name: "plan_ready",
     label: "Plan Ready",
@@ -462,16 +478,7 @@ export default function planMode(pi: ExtensionAPI) {
           ctx.ui.notify("Plan mode is not active.", "warning");
           return;
         }
-        pi.sendMessage(
-          {
-            customType: "plan-finalize-requested",
-            content:
-              "Finalize the plan now. Resolve any remaining material ambiguity with ask_user; otherwise call plan_ready alone with the complete implementation-ready Markdown plan. Do not implement it.",
-            display: true,
-            details: {},
-          },
-          { deliverAs: "followUp", triggerTurn: true },
-        );
+        requestPlanFinalization();
         return;
       }
 
@@ -481,10 +488,28 @@ export default function planMode(pi: ExtensionAPI) {
       }
 
       if (planning) {
-        ctx.ui.notify(
-          "Plan mode is already active. `/plan done` requests completion; `/plan off` cancels.",
-          "info",
+        if (!ctx.hasUI) {
+          ctx.ui.notify(
+            "Plan mode is already active. `/plan done` requests completion; `/plan off` cancels.",
+            "info",
+          );
+          return;
+        }
+        const choice = await ctx.ui.select(
+          "Plan Mode — choose what happens next",
+          [PLAN_READY_ACTIONS.continue, FINALIZE_NOW, PLAN_READY_ACTIONS.off],
         );
+        if (choice === PLAN_READY_ACTIONS.continue) {
+          ctx.ui.notify(
+            "Plan mode is already active. `/plan done` requests completion; `/plan off` cancels.",
+            "info",
+          );
+        } else if (choice === FINALIZE_NOW) {
+          requestPlanFinalization();
+        } else if (choice === PLAN_READY_ACTIONS.off) {
+          clearPlan(ctx);
+          ctx.ui.notify("Plan mode is off.", "info");
+        }
         return;
       }
 
@@ -510,7 +535,7 @@ export default function planMode(pi: ExtensionAPI) {
       return {
         block: true as const,
         reason:
-          "The plan is ready and the write gate remains closed. Wait for the user to choose the next action with `/plan`; do not call more tools.",
+          "The plan is ready and the write gate remains closed. Wait for the user to choose the next action with `/plan` or turn it off with `/plan off`; do not call more tools.",
       };
     }
     const batchDecision =

package/extensions/setup/index.ts

@@ -132,10 +132,10 @@ export function buildInteractiveSetupPrompt(options: {
     "- Capability discovery: explicit is the safe default and keeps OpenPI model tools absent until the user asks for a capability. adaptive is opt-in and keeps only the small openpi_load_tools gateway visible, allowing the model to load Subagents, Workflows, background terminals, structured search, or Session tracking when it judges them useful. Loaded groups remain session-stable, and normal permission, concurrency, and workflow limits still apply.",
     "- Next-action suggestions: disabled, or model-generated after a fully settled main-agent run. A suggestion appears as dim inline text on the first row of an empty editor; reserved cells at the row end keep CJK IME preedit from overwriting it. Right accepts it without submitting, and any other editor input dismisses it. Enabling requires an available provider/model and reasoning level and adds one small model call per settled run.",
     "- Workflow fan-out: concurrency controls simultaneous agents and resource pressure; max agent calls controls the total capacity of one workflow. Valid ranges are 1-64 and 1-1024.",
-    "- UI: the large header costs vertical space; the custom footer is a declarative dashboard. Presets: powerline (default one-line ANSI256 blocks), powerline-mono (one-line high-contrast gray powerline), and compact (one-line plain text). Style can also be set independently: plain, powerline, powerline-mono. Custom lines are a 2D layout of cwd/model/thinking/context/cache/cost/throughput/git/pr plus at most one flex per line for left/right alignment. Nerd Font only affects powerline separator glyphs; text stays readable without it. Changes apply immediately in the active TUI session.",
+    "- UI: the large header costs vertical space; the custom footer is a declarative dashboard. Presets: powerline (one-line ANSI256 blocks), powerline-mono (one-line high-contrast gray powerline), and compact (one-line plain text); the default is plain with cwd/git/pr on the left and model/context/cost on the right. Style can also be set independently: plain, powerline, powerline-mono. Custom lines are a 2D layout of cwd/model/thinking/context/cache/cost/throughput/git/pr plus at most one flex per line for left/right alignment. Nerd Font only affects powerline separator glyphs; text stays readable without it. Changes apply immediately in the active TUI session.",
     "- Operational activity for Subagents, Workflows, and background terminals is core status and always remains visible whenever the custom footer is enabled.",
     "- Post-edit command: one optional shell command (maximum 500 characters) run in the background after a turn with successful Write/Edit operations (e.g. `npm run format`). Off by default, interactive TUI sessions only, failures surface as a notification. This is a single command, not an event-hook system.",
-    "- Result detail display: Subagent results, Bash operations, and Write/Edit operations can each default to full (always expanded) or compact (Claude Code-style folded preview with a hidden-line count). Compact output can still be temporarily expanded with the configured app.tools.expand key (Ctrl+O by default). Bash and Write/Edit default to compact. Recommend compact for users who do not usually inspect implementation details.",
+    "- Result detail display: Subagent results, Bash operations, and Write/Edit operations can each default to full or compact. Compact Subagent results show only bounded status rows and keep raw child reports behind app.tools.expand; compact Bash and Write/Edit operations use folded previews. Ctrl+O expands compact output by default. Bash and Write/Edit default to compact. Recommend compact for users who do not usually inspect implementation details.",
     "- Agent role models: built-in explorer, implementer, reviewer, and advisor roles are shared by subagent_spawn and workflow agent_type, and inherit the parent model by default. Assign only an available registry model to an individual role when needed; clearing that role returns it to inheritance. Custom agent-type files still override a built-in role's complete definition.",
     "- Intercom: optional cross-session messaging is installed only after a native setup confirmation. It stays parent-only; Direct/Workflow children and Replay cannot use it. The status above is informational for this model-guided step—do not install packages or edit its config yourself.",
     "",
@@ -395,7 +395,7 @@ export default function openPiSetup(pi: ExtensionAPI) {
       subagent_result_display: Type.Optional(
         StringEnum(DETAIL_DISPLAYS, {
           description:
-            "How completed Subagent results render by default: full preserves complete output; compact shows a bounded preview that can be expanded with app.tools.expand. Omit to preserve the current value.",
+            "How completed Subagent results render by default: full shows complete output; compact shows only bounded status rows while app.tools.expand reveals the full child report. Omit to preserve the current value.",
         }),
       ),
       bash_tool_display: Type.Optional(