@tt-a1i/openpi 0.1.1 → 0.3.0

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

@@ -36,6 +36,10 @@ import {
   PLAN_MODE_CHANNEL,
   type PlanModeState,
 } from "../shared/plan-mode-state.ts";
+import {
+  OPENPI_TOOL_SURFACE,
+  patchOwnedTools,
+} from "../shared/tool-surface.ts";
 import { sanitizeTerminalText } from "../shared/terminal-text.ts";
 import { planBashDecision } from "./bash-policy.ts";
 
@@ -138,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.",
@@ -231,6 +239,12 @@ export function planToolCallDecision(
 export default function planMode(pi: ExtensionAPI) {
   let planning = false;
   let readyPlan: string | undefined;
+  const syncPlanTool = () =>
+    patchOwnedTools(pi, "plan", {
+      ...(planning && !readyPlan
+        ? { enable: OPENPI_TOOL_SURFACE.plan.deferred }
+        : { disable: OPENPI_TOOL_SURFACE.plan.deferred }),
+    });
 
   /**
    * Publish the stance and reflect it in the footer. Every place `planning`
@@ -242,15 +256,12 @@ export default function planMode(pi: ExtensionAPI) {
     hasUI: boolean;
     ui: { setStatus: (key: string, value?: string) => void };
   }) => {
+    syncPlanTool();
     pi.events.emit(PLAN_MODE_CHANNEL, { planning } satisfies PlanModeState);
     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,
     );
   };
 
@@ -360,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",
@@ -451,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;
       }
 
@@ -470,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;
       }
 
@@ -499,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 =
@@ -532,6 +568,7 @@ export default function planMode(pi: ExtensionAPI) {
   pi.on("session_shutdown", () => {
     planning = false;
     readyPlan = undefined;
+    syncPlanTool();
     // Broadcast without a ctx: subagents keeps its own copy of the stance, and
     // leaving it armed would restrict children in whatever session comes next.
     pi.events.emit(PLAN_MODE_CHANNEL, { planning } satisfies PlanModeState);

package/extensions/setup/index.ts

@@ -10,6 +10,11 @@ import {
   type SubagentRoleModels,
 } from "../shared/subagent-roles.ts";
 import { sanitizeTerminalText } from "../shared/terminal-text.ts";
+import {
+  OPENPI_SETUP_EPISODE_CHANNEL,
+  type OpenPiSetupEpisodeState,
+} from "../shared/setup-episode-state.ts";
+import { patchOwnedTools } from "../shared/tool-surface.ts";
 import {
   formatPiIntercomStatus,
   inspectPiIntercom,
@@ -18,6 +23,7 @@ import {
 } from "./intercom.ts";
 import {
   applyFooterConfig,
+  CAPABILITY_DISCOVERY_MODES,
   DETAIL_DISPLAYS,
   FOOTER_ITEMS,
   FOOTER_LAYOUT_ITEMS,
@@ -33,6 +39,7 @@ import {
   REASONING_LEVELS,
   SETUP_CONFIG_CHANGED_CHANNEL,
   type FooterLayoutItem,
+  type CapabilityDiscoveryMode,
   type FooterPreset,
   type FooterStyle,
   type MyPiSetupConfig,
@@ -102,12 +109,12 @@ export function buildInteractiveSetupPrompt(options: {
 }) {
   const configurationState = options.savedConfigExists
     ? [
-        "This package has already been configured. Explain the current settings in the user's language, then ask whether they want to keep them or change Next-action suggestions, Workflow limits, UI/Footer, result detail display, Post-edit, Agent role models, or review everything.",
+        "This package has already been configured. Explain the current settings in the user's language, then ask whether they want to keep them or change Capability discovery, Next-action suggestions, Workflow limits, UI/Footer, result detail display, Post-edit, Agent role models, or review everything.",
         "If the user keeps the current settings, do not call configure_my_pi_setup. If they choose a category, ask only the follow-up needed for that category.",
       ]
     : [
         "This is the first setup. Explain the available choices and their impact in the user's language, then collect the initial preferences.",
-        "Prefer one ask_user call with up to three independent questions covering Next-action suggestions, Workflow limits, and UI/Footer/result display. Explain that Post-edit defaults off; keep it off unless the user opts in, then ask only for the command. Explain that built-in Agent roles used by subagent_spawn and workflow agent_type inherit the parent model unless the user assigns an available model to a role.",
+        "Prefer one ask_user call with up to three independent questions covering Capability discovery plus Workflow limits, Next-action suggestions, and UI/Footer/result display. Explain that Post-edit defaults off; keep it off unless the user opts in, then ask only for the command. Explain that built-in Agent roles used by subagent_spawn and workflow agent_type inherit the parent model unless the user assigns an available model to a role.",
       ];
 
   return [
@@ -122,16 +129,19 @@ export function buildInteractiveSetupPrompt(options: {
     ...configurationState,
     "",
     "Before asking, briefly explain what can be configured and the practical impact:",
+    "- 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.",
     "",
     "Natural-language configuration examples the user might ask for:",
+    '- "let the model discover OpenPI capabilities when useful" → capability_discovery=adaptive',
+    '- "only use OpenPI capabilities when I ask" → capability_discovery=explicit',
     '- "switch footer to powerline" → ui_footer_preset=powerline',
     '- "use mono powerline" → ui_footer_preset=powerline-mono',
     '- "compact footer" → ui_footer_preset=compact',
@@ -151,6 +161,16 @@ const safeSetupNotice = (value: unknown, maximum = 500) =>
     .trim()
     .slice(0, maximum);
 
+export function buildSetupSuccessText(
+  currentConfiguration: string,
+  normalizationNote = "",
+) {
+  return [
+    `Updated OpenPI setup. ${currentConfiguration}${normalizationNote}`,
+    "This setup episode is complete; configure_my_pi_setup is now hidden. Do not call it again. Do not edit configuration files directly. If the user requests another configuration change, tell them to run /openpi-setup <request> to start a new setup episode.",
+  ].join(" ");
+}
+
 export function shouldOfferPiIntercom(options: {
   readonly request: string;
   readonly status: PiIntercomStatus;
@@ -231,13 +251,72 @@ async function maybeOfferPiIntercom(
   }
 }
 
+export const CONFIGURE_MY_PI_SETUP_TOOL_NAME = "configure_my_pi_setup";
+
+type SetupEpisode = "idle" | "armed" | "active";
+
+function showConfigureTool(pi: ExtensionAPI) {
+  patchOwnedTools(pi, "setup", {
+    enable: [CONFIGURE_MY_PI_SETUP_TOOL_NAME],
+  });
+}
+
+function hideConfigureTool(pi: ExtensionAPI) {
+  patchOwnedTools(pi, "setup", {
+    disable: [CONFIGURE_MY_PI_SETUP_TOOL_NAME],
+  });
+}
+
 export default function openPiSetup(pi: ExtensionAPI) {
+  let episode: SetupEpisode = "idle";
+  const publishEpisode = () =>
+    pi.events.emit(OPENPI_SETUP_EPISODE_CHANNEL, {
+      active: episode !== "idle",
+    } satisfies OpenPiSetupEpisodeState);
+
+  const endEpisode = () => {
+    episode = "idle";
+    hideConfigureTool(pi);
+    publishEpisode();
+  };
+
+  pi.on("session_start", () => {
+    endEpisode();
+  });
+
+  pi.on("agent_start", () => {
+    if (episode === "armed") {
+      episode = "active";
+      publishEpisode();
+    }
+  });
+
+  pi.on("tool_execution_end", (event) => {
+    if (
+      episode === "active" &&
+      event.toolName === CONFIGURE_MY_PI_SETUP_TOOL_NAME &&
+      !event.isError
+    ) {
+      endEpisode();
+    }
+  });
+
+  pi.on("agent_settled", () => {
+    if (episode === "active") endEpisode();
+  });
+
   pi.registerTool({
     name: "configure_my_pi_setup",
     label: "Configure OpenPI",
     description:
-      "Apply a user-requested configuration change for this Pi setup. Configures next-action suggestions, workflow fan-out, UI/Footer (presets, style, multi-line layout), result detail display, optional Post-edit, and built-in Agent-role model assignments shared by subagent_spawn and workflow agent_type. Role models must be available in the Pi registry; null clears a role back to parent-model inheritance. Footer examples: powerline preset, powerline-mono, compact, or custom ui_footer_lines with flex. Preserve current values for settings the user did not ask to change. Changes apply immediately to an active TUI footer.",
+      "Apply a user-requested configuration change for this Pi setup. Configures capability discovery (explicit or opt-in adaptive), next-action suggestions, workflow fan-out, UI/Footer (presets, style, multi-line layout), result detail display, optional Post-edit, and built-in Agent-role model assignments shared by subagent_spawn and workflow agent_type. Role models must be available in the Pi registry; null clears a role back to parent-model inheritance. Footer examples: powerline preset, powerline-mono, compact, or custom ui_footer_lines with flex. Preserve current values for settings the user did not ask to change. Changes apply immediately to the capability gateway and active TUI footer.",
     parameters: Type.Object({
+      capability_discovery: Type.Optional(
+        StringEnum(CAPABILITY_DISCOVERY_MODES, {
+          description:
+            "Capability adoption policy. explicit keeps OpenPI tools absent until the user asks for a capability; adaptive keeps only the small openpi_load_tools gateway visible so the model may load a useful group on its own. Adaptive can start expensive work such as Subagents or Workflows, so it is opt-in. Omit to preserve the current value.",
+        }),
+      ),
       suggestions_enabled: Type.Optional(
         Type.Boolean({
           description:
@@ -316,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(
@@ -406,6 +485,12 @@ export default function openPiSetup(pi: ExtensionAPI) {
         );
 
         const config: MyPiSetupConfig = {
+          capabilities: {
+            discovery:
+              (params.capability_discovery as
+                | CapabilityDiscoveryMode
+                | undefined) ?? current.capabilities.discovery,
+          },
           suggestions: {
             enabled: suggestionsEnabled,
             ...(model ? { model } : {}),
@@ -457,9 +542,7 @@ export default function openPiSetup(pi: ExtensionAPI) {
           : "";
       if (ctx.hasUI) ctx.ui.notify(`${text}${note}`, "info");
       return {
-        content: [
-          { type: "text", text: `Updated OpenPI setup. ${text}${note}` },
-        ],
+        content: [{ type: "text", text: buildSetupSuccessText(text, note) }],
         details: config,
       };
     },
@@ -490,7 +573,7 @@ export default function openPiSetup(pi: ExtensionAPI) {
           "Current configuration:",
           currentConfiguration,
           "",
-          "Footer tips: presets are powerline, powerline-mono, compact; style is plain/powerline/powerline-mono; custom layouts use ui_footer_lines (2D enum arrays with optional flex). Do not use ui_footer_items together with ui_footer_lines. Built-in Agent role models (explorer, implementer, reviewer, advisor) are shared by subagent_spawn and workflow agent_type; they inherit the parent unless assigned an available registry model, and clearing an assignment restores inheritance. Custom agent-type files still override built-in role definitions. Nerd Font only affects powerline separator glyphs. Changes apply immediately in the active TUI session. Intercom installation is handled only by the native setup confirmation; do not install packages or edit its config yourself.",
+          "Capability discovery is explicit by default; adaptive is an opt-in that keeps only openpi_load_tools visible so the model may load useful groups. Footer tips: presets are powerline, powerline-mono, compact; style is plain/powerline/powerline-mono; custom layouts use ui_footer_lines (2D enum arrays with optional flex). Do not use ui_footer_items together with ui_footer_lines. Built-in Agent role models (explorer, implementer, reviewer, advisor) are shared by subagent_spawn and workflow agent_type; they inherit the parent unless assigned an available registry model, and clearing an assignment restores inheritance. Custom agent-type files still override built-in role definitions. Nerd Font only affects powerline separator glyphs. Changes apply immediately in the active TUI session. Intercom installation is handled only by the native setup confirmation; do not install packages or edit its config yourself.",
           "",
           "Use configure_my_pi_setup to apply only the requested OpenPI-owned changes and preserve everything else. Interpret model names from the available Pi registry. Do not edit configuration files directly.",
         ]
@@ -501,6 +584,9 @@ export default function openPiSetup(pi: ExtensionAPI) {
           savedConfigExists,
         });
 
+    episode = "armed";
+    showConfigureTool(pi);
+    publishEpisode();
     pi.sendUserMessage(
       prompt.join("\n"),
       ctx.isIdle() ? undefined : { deliverAs: "followUp" },