@tt-a1i/openpi 0.1.0 → 0.2.0

package/SETUP.md

@@ -9,14 +9,14 @@ pi install npm:@tt-a1i/openpi
 To inspect the current source before loading it, install directly from GitHub instead:
 
 ```sh
-pi install git:github.com/tt-a1i/my-pi-setup
+pi install git:github.com/tt-a1i/openpi
 ```
 
 Pi installs the package dependencies automatically. Restart Pi or run `/reload` after installation.
 
 ## fd and rg tools
 
-The `file-search` extension registers `fd` and `rg` as model tools. No setup is normally needed: at startup it silently uses a system-installed `fd` (or `fdfind` on Debian/Ubuntu) and `rg` when available, or an existing fallback binary in `~/.pi/agent/bin/`. Only when neither exists does it download an official release binary (macOS/Linux, arm64/x64, over HTTPS) into `~/.pi/agent/bin/` and show a one-time notification. If your platform is unsupported, install `fd` and `rg` with your package manager and restart pi.
+The `file-search` extension registers `fd` and `rg` as model tools. They stay outside an ordinary parent turn until the user explicitly asks to use `fd`/`rg` or structured file search, or the model loads the `search` group through `openpi_load_tools`. The gateway is shown after an explicit OpenPI-capability request, or remains visible when the user opts into adaptive discovery; child sessions may still receive `fd` and `rg` through the reviewed child-safe allowlist. No setup is normally needed: at startup it silently uses a system-installed `fd` (or `fdfind` on Debian/Ubuntu) and `rg` when available, or an existing fallback in this package's private `bin/` directory. Only when neither exists does it download an official release binary (macOS/Linux, arm64/x64, over HTTPS) into that package-local directory and show a one-time notification. If your platform is unsupported, install `fd` and `rg` with your package manager and restart Pi.
 
 ## Theme
 
@@ -28,31 +28,33 @@ Add the included theme to `~/.pi/agent/settings.json` while keeping your existin
 }
 ```
 
-Pi will load the extensions, skills, and theme from their directories the next time it starts.
+Pi will load the extensions and theme the next time it starts. OpenPI's Background, Subagent, and Workflow Skill files remain in the package, but ordinary turns do not advertise them in the system prompt; the matching path is disclosed only after explicit capability intent or after the model loads that group through the opt-in adaptive gateway.
 
 ## Configure this package
 
-Use the single package-owned command. With no arguments, the current model explains the configurable areas and their impact, then uses `ask_user`: first run initializes them; later runs explain the saved state and ask whether to keep it, change one area, or review everything. With arguments, it treats the rest as a targeted natural-language request:
+Use the single canonical package-owned command. `/my-pi-setup` remains a compatibility alias. With no arguments, when optional pi-intercom is absent, the interactive TUI first offers a reviewed global installation; declining changes nothing. Acceptance installs the fixed `npm:pi-intercom` source through Pi's package manager. A new private config receives `confirmSend: true` and `inboundTrigger: "replies"`; an existing preference file is never rewritten and must already define both fields. Package download failure writes no config, while uncertain activation retains the safe new config. Setup asks for `/reload` instead of loading a new broker into the running Session. The current model then explains the remaining configurable areas and uses `ask_user`: first run initializes them; later runs explain the saved state and ask whether to keep it, change one area, or review everything. With arguments, it treats the rest as a targeted natural-language request. Persist still goes through the typed `configure_my_pi_setup` tool, which is exposed only while that `/openpi-setup` episode is in flight and is hidden again afterward. One successful apply completes the episode; a later configuration change starts a new one with `/openpi-setup <request>` rather than reusing the hidden tool:
 
 ```text
-/my-pi-setup
-/my-pi-setup 开启下一步预测，使用 seal/deepseek-v4-flash，关闭推理
-/my-pi-setup 关闭下一步预测
-/my-pi-setup workflow 同时跑 16 个 agent，总任务最多 256 个
-/my-pi-setup 显示大标题
-/my-pi-setup 切换 Footer 为 powerline
-/my-pi-setup 用 mono powerline Footer
-/my-pi-setup Footer 用 compact
-/my-pi-setup Footer 两行：cwd flex model / context cost flex git
-/my-pi-setup Footer 只显示 model、thinking、context、cache 和 git
-/my-pi-setup 关闭自定义状态栏
-/my-pi-setup 编辑后自动跑 npm run format
-/my-pi-setup 关闭 post-edit 命令
-/my-pi-setup 给 explorer 指定当前 Registry 中可用的模型
-/my-pi-setup 清除 explorer 的模型，让它继承父模型
+/openpi-setup
+/openpi-setup 让模型在合适时自主发现并采用 OpenPI 能力
+/openpi-setup 只在我明确要求时加载 OpenPI 能力
+/openpi-setup 开启下一步预测，使用 seal/deepseek-v4-flash，关闭推理
+/openpi-setup 关闭下一步预测
+/openpi-setup workflow 同时跑 16 个 agent，总任务最多 256 个
+/openpi-setup 显示大标题
+/openpi-setup 切换 Footer 为 powerline
+/openpi-setup 用 mono powerline Footer
+/openpi-setup Footer 用 compact
+/openpi-setup Footer 两行：cwd flex model / context cost flex git
+/openpi-setup Footer 只显示 model、thinking、context、cache 和 git
+/openpi-setup 关闭自定义状态栏
+/openpi-setup 编辑后自动跑 npm run format
+/openpi-setup 关闭 post-edit 命令
+/openpi-setup 给 explorer 指定当前 Registry 中可用的模型
+/openpi-setup 清除 explorer 的模型，让它继承父模型
 ```
 
-Next-action suggestions default to off. Run `/my-pi-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. `/my-pi-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; 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`.
 
 ## Session Goal and Tasks
 
@@ -62,7 +64,7 @@ Model callers use `get_goal`, `create_goal`, and `update_goal`. `create_goal` is
 
 There are no normal user-facing Turn, no-progress, or wall-clock caps; a hidden 1000-continuation circuit breaker exists only to stop runaway automation. An optional `token_budget` must only be positive. Goal non-cached Assistant input-plus-output Token and elapsed-time usage are persisted; crossing the budget marks `budget_limited` and queues one wrap-up Turn. Active goals continue after reload/resume. Fork and tree navigation defer inherited active continuation until the first explicit user input; paused, blocked, and usage-limited goals remain stopped and can prompt for Resume. A v1 active/waiting goal migrates once to paused. Assistant aborts pause an active goal and Assistant errors block it. Print/json automation is inert. Footer text mirrors Codex (`Pursuing goal (…)`, resume hints, `Goal unmet`, `Goal achieved`) without showing the objective or legacy Turn counts. An achieved Footer remains visible until the next explicit interactive/RPC input, then a branch-persisted acknowledgement hides only the Footer while `/goal` retains the completed record.
 
-Session Tasks remain advisory multi-item work intent and do not determine Goal completion. They are scoped to the current request batch: once every item is done or dropped, the batch closes and the next `tasks_add` starts again at T1. Active items persist in a polished Claude Code-style panel above the editor; `Ctrl+Shift+T` or `/tasks hide|show|toggle` controls visibility, while `/tasks` opens the full list. No `/my-pi-setup` setting or secondary judge model is required.
+Session Tasks remain advisory multi-item work intent and do not determine Goal completion. They are scoped to the current request batch: once every item is done or dropped, the batch closes and the next `tasks_add` starts again at T1. The model marks a tracked item `in_progress` before starting it, records `done`, `blocked`, or `dropped` immediately after that item reaches a real outcome, and reconciles touched items before its final answer. Every add/update result returns the complete bounded current snapshot so the next item is explicit and the panel refreshes on each persisted transition. Commit, test, and authorization signals are only task-scoped evidence candidates; OpenPI never infers completion or mutates a task from those signals. Active items persist in a polished Claude Code-style panel above the editor; `Ctrl+Shift+T` or `/tasks hide|show|toggle` controls visibility, while `/tasks` opens the full list. No `/openpi-setup` setting or secondary judge model is required.
 
 ## Other commands added by this fork
 
@@ -70,5 +72,5 @@ Session Tasks remain advisory multi-item work intent and do not determine Goal c
 - `/tasks` inspects branch-scoped advisory work items.
 - `/goal ...` controls the persistent autonomous session objective.
 - `/context-pivot <next phase>` deliberately compacts a long current session into a next-phase brief. It requires at least 30,000 context tokens and is rejected below that; use the separate `/handoff` skill when work should move to a genuinely new session.
-- `/cron every <5m> <prompt>`, `/cron in <30s> <prompt>`, `/cron list`, and `/cron remove <id>` schedule a prompt for this session. Jobs are in-memory and session-scoped (cleared on shutdown), fire only while the session is idle, and use a duration grammar (`30s`/`5m`/`2h`, minimum 30s) rather than crontab fields, because the scheduler polls about every 30 seconds.
+- `/cron every <5m> <prompt>`, `/cron in <30s> <prompt>`, `/cron list`, and `/cron remove <id>` schedule a prompt for this session. Jobs are in-memory and session-scoped (cleared on shutdown), fire only while the session is idle, and use a duration grammar (`30s`/`5m`/`2h`, minimum 30s) rather than crontab fields, because the scheduler polls about every 30 seconds. Jobs due in the same poll are delivered as one triggered turn while retaining each job's id and recurrence metadata; if that atomic delivery fails, every due job remains pending for retry.
 - `/plan [objective]` explores read-only before changing anything: while armed it blocks `edit`, `write`, mutating Bash, `subagent_send`, `workflow`, and `bg_start`, while read/grep/find/ls/fd/rg and verified read-only Git/GitHub commands stay available. It permits `subagent_spawn`, but the harness narrows every newly spawned planning child to investigation-only tools; agent types can narrow that list further, never widen it. The model must submit the complete plan through parent-only `plan_ready`; the write gate stays closed until `/plan` prepares an editable implementation prompt for the current or a fresh Session. `/plan off` cancels.

package/THIRD_PARTY_NOTICES.md

@@ -10,7 +10,6 @@ The upstream project is distributed under the MIT License. Its notice states
 `Copyright (c) 2026`; the complete license text is included at
 [`extensions/sessions/LICENSE.upstream`](extensions/sessions/LICENSE.upstream).
 
-The remainder of this repository retains its upstream licensing status; no
-project-wide license is asserted here. The npm package therefore declares
-`UNLICENSED`; publication does not grant permission to copy, modify, or
-redistribute code beyond rights supplied by an applicable upstream license.
+OpenPI is distributed under the MIT License; see [`LICENSE`](LICENSE). Portions
+identified in this notice retain their original copyright notices and license
+terms. The project-wide MIT license does not replace or remove those notices.

package/assets/readme-hero-mobile.svg

@@ -1,6 +1,6 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="720" height="900" viewBox="0 0 720 900" role="img" aria-labelledby="title desc">
   <title id="title">OpenPI</title>
-  <desc id="desc">A mobile-readable overview of the Pi-native multi-agent runtime.</desc>
+  <desc id="desc">OpenPI — small harness, deep extensions, clean context.</desc>
   <defs>
     <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
       <stop stop-color="#0d1117"/>
@@ -21,7 +21,7 @@
     <text x="42" y="28" fill="#a5d6ff" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="18" font-weight="700" letter-spacing="1">PI NATIVE</text>
 
     <text x="0" y="122" fill="#f0f6fc" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="66" font-weight="760" letter-spacing="-2">OpenPI</text>
-    <text x="0" y="168" fill="#8b949e" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="24">Small harness. Real runtime.</text>
+    <text x="0" y="168" fill="#8b949e" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="24">Small harness. Deep extensions. Clean context.</text>
   </g>
 
   <g transform="translate(48 250)" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="23" font-weight="600">

package/assets/readme-hero.svg

@@ -1,6 +1,6 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="1200" height="500" viewBox="0 0 1200 500" role="img" aria-labelledby="title desc">
   <title id="title">OpenPI</title>
-  <desc id="desc">A Pi-native runtime layer for background terminals, isolated subagents, dynamic workflows, and clean context.</desc>
+  <desc id="desc">OpenPI — small harness, deep extensions, clean context.</desc>
 
   <defs>
     <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
@@ -34,11 +34,11 @@
     <g>
       <rect width="112" height="34" rx="17" fill="#12233d" stroke="#2f81f7"/>
       <circle cx="18" cy="17" r="5" fill="#3fb950"/>
-      <text x="33" y="22" fill="#a5d6ff" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="13" font-weight="700" letter-spacing="1">PI NATIVE</text>
+      <text x="33" y="22" fill="#a5d6ff" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="14" font-weight="700" letter-spacing="0.7">PI NATIVE</text>
     </g>
 
     <text x="0" y="112" fill="#f0f6fc" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="64" font-weight="760" letter-spacing="-2">OpenPI</text>
-    <text x="0" y="155" fill="#8b949e" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="21">Keep the harness small. Give it a real runtime.</text>
+    <text x="0" y="155" fill="#8b949e" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="20">Small harness. Deep extensions. Clean context.</text>
 
     <g transform="translate(0 198)" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16">
       <path d="M5 9h14M12 2l7 7-7 7" fill="none" stroke="#58a6ff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
@@ -62,14 +62,14 @@
     <circle cx="22" cy="22" r="5" fill="#f85149"/>
     <circle cx="40" cy="22" r="5" fill="#d29922"/>
     <circle cx="58" cy="22" r="5" fill="#3fb950"/>
-    <text x="229" y="27" text-anchor="middle" fill="#7d8590" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="13">pi · main</text>
+    <text x="229" y="27" text-anchor="middle" fill="#7d8590" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="15">pi · main</text>
 
-    <g font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="14">
+    <g font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16">
       <text x="24" y="78" fill="#7d8590">$ pi</text>
       <rect x="24" y="92" width="410" height="44" rx="9" fill="#0d1117" stroke="#21262d"/>
       <circle cx="44" cy="114" r="5" fill="#58a6ff"/>
       <text x="59" y="119" fill="#f0f6fc">main agent</text>
-      <text x="320" y="119" fill="#7d8590">orchestrating</text>
+      <text x="320" y="119" fill="#7d8590" font-size="14">orchestrating</text>
 
       <path d="M47 136V155M47 155H379" fill="none" stroke="#30363d" stroke-width="2"/>
       <path d="M90 155V169M229 155V169M379 155V169" stroke="#30363d" stroke-width="2"/>
@@ -91,18 +91,18 @@
 
       <rect x="24" y="256" width="410" height="34" rx="8" fill="#0d1117" stroke="#21262d"/>
       <text x="38" y="278" fill="#7d8590">context</text>
-      <rect x="104" y="268" width="166" height="10" rx="5" fill="#21262d"/>
-      <rect x="104" y="268" width="61" height="10" rx="5" fill="#2f81f7"/>
+      <rect x="115" y="268" width="155" height="10" rx="5" fill="#21262d"/>
+      <rect x="115" y="268" width="57" height="10" rx="5" fill="#2f81f7"/>
       <text x="285" y="278" fill="#c9d1d9">37%</text>
       <text x="338" y="278" fill="#3fb950">settled</text>
 
       <path d="M24 308H434" stroke="#21262d"/>
       <rect x="24" y="318" width="410" height="18" rx="4" fill="#0b1720"/>
-      <text x="34" y="332" fill="#39c5cf" font-size="13">run tests and open the PR</text>
+      <text x="34" y="332" fill="#39c5cf" font-size="15">run tests and open the PR</text>
     </g>
   </g>
 
-  <g transform="translate(70 444)" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="13" font-weight="600" letter-spacing="0.4">
+  <g transform="translate(70 444)" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="14" font-weight="600" letter-spacing="0.25">
     <text fill="#58a6ff">BACKGROUND</text>
     <circle cx="110" cy="-4" r="2" fill="#30363d"/>
     <text x="126" fill="#3fb950">SUBAGENTS</text>

package/extensions/ask-user/handoff.ts

@@ -33,7 +33,11 @@ const HumanHandoffParams = Type.Object({
 
 export type HumanHandoffInput = Static<typeof HumanHandoffParams>;
 export type HumanHandoffStatus =
-  "completed" | "unable" | "dismissed" | "cancelled" | "unavailable";
+  | "completed"
+  | "unable"
+  | "dismissed"
+  | "cancelled"
+  | "unavailable";
 
 export interface HumanHandoffDetails {
   status: HumanHandoffStatus;

package/extensions/ask-user/index.ts

@@ -25,6 +25,18 @@ import {
 import { Cause, Effect, Exit } from "effect";
 import { Type, type Static } from "typebox";
 import { sanitizeTerminalText } from "../shared/terminal-text.ts";
+import {
+  PLAN_MODE_CHANNEL,
+  type PlanModeState,
+} from "../shared/plan-mode-state.ts";
+import {
+  OPENPI_SETUP_EPISODE_CHANNEL,
+  type OpenPiSetupEpisodeState,
+} from "../shared/setup-episode-state.ts";
+import {
+  OPENPI_TOOL_SURFACE,
+  patchOwnedTools,
+} from "../shared/tool-surface.ts";
 import { createHumanHandoffToolDefinition } from "./handoff.ts";
 import {
   BRACKETED_PASTE_END,
@@ -355,6 +367,38 @@ export async function showQuestionsWithDialogs(
 }
 
 export default function askUser(pi: ExtensionAPI) {
+  let planning = false;
+  let setupActive = false;
+  const syncInteractionTools = () =>
+    patchOwnedTools(pi, "interaction", {
+      ...(planning || setupActive
+        ? { enable: OPENPI_TOOL_SURFACE.interaction.deferred }
+        : { disable: OPENPI_TOOL_SURFACE.interaction.deferred }),
+    });
+
+  pi.events.on(PLAN_MODE_CHANNEL, (state: unknown) => {
+    planning =
+      typeof state === "object" &&
+      state !== null &&
+      (state as PlanModeState).planning === true;
+    syncInteractionTools();
+  });
+  pi.events.on(OPENPI_SETUP_EPISODE_CHANNEL, (state: unknown) => {
+    setupActive =
+      typeof state === "object" &&
+      state !== null &&
+      (state as OpenPiSetupEpisodeState).active === true;
+    syncInteractionTools();
+  });
+  pi.on("session_shutdown", () => {
+    planning = false;
+    setupActive = false;
+    syncInteractionTools();
+  });
+  pi.on("session_start", () => {
+    syncInteractionTools();
+  });
+
   pi.registerTool({
     name: "ask_user",
     label: "Ask User",

package/extensions/background-terminals/index.ts

@@ -28,8 +28,16 @@ import type {
 import { Type } from "typebox";
 import { loadSetupConfig } from "../shared/setup-config.ts";
 import { sanitizeTerminalText } from "../shared/terminal-text.ts";
+import {
+  OPENPI_TOOL_SURFACE,
+  patchOwnedTools,
+} from "../shared/tool-surface.ts";
 import type { TerminalSnapshot } from "./src/domain.ts";
-import { TerminalManager, type TerminalManagerShape } from "./src/manager.ts";
+import {
+  MAX_RUNNING,
+  TerminalManager,
+  type TerminalManagerShape,
+} from "./src/manager.ts";
 import {
   BG_KILL_PARAMETER_DESCRIPTIONS,
   BG_KILL_TOOL_DESCRIPTION,
@@ -45,6 +53,7 @@ import {
   buildKillReport,
   buildStartResult,
   buildStatusResult,
+  buildTerminalBatchResultMessage,
   buildTerminalResultMessage,
   buildWatchArmedResult,
   buildWatchMatchMessage,
@@ -52,23 +61,29 @@ import {
 } from "./src/prompt.ts";
 import {
   createDeferredResultDelivery,
+  createIdleResultBatcher,
+  hasTerminalCapacity,
   resultDeliveryOptions,
 } from "./src/result-delivery.ts";
-import {
-  assertWatchableOutput,
-  compileWatchPattern,
-  createChunkMatcher,
-  matchCapturedOutput,
-} from "./src/watch.ts";
 import {
   createTerminalRuntime,
   runTool,
   type TerminalRuntime,
 } from "./src/runtime.ts";
 import { openTerminalPicker } from "./src/ui/ps.ts";
-import { renderTerminalResult } from "./src/ui/tool-result.ts";
+import {
+  renderTerminalBatchResult,
+  renderTerminalResult,
+} from "./src/ui/tool-result.ts";
+import {
+  assertWatchableOutput,
+  compileWatchPattern,
+  createChunkMatcher,
+  matchCapturedOutput,
+} from "./src/watch.ts";
 
 const WIDGET_KEY = "background-terminals";
+const IDLE_RESULT_BATCH_MS = 200;
 
 interface WatchToolDetails {
   id: string;
@@ -83,7 +98,16 @@ export default function (pi: ExtensionAPI) {
   let sessionContext: ExtensionContext | undefined;
   let ui: ExtensionUIContext | undefined;
   let unsubStatus: (() => void) | undefined;
+  let startReservations = 0;
   const resultDelivery = createDeferredResultDelivery<TerminalSnapshot>();
+  const hideLifecycleTools = () =>
+    patchOwnedTools(pi, "background", {
+      disable: OPENPI_TOOL_SURFACE.background.deferred,
+    });
+  const showLifecycleTools = () =>
+    patchOwnedTools(pi, "background", {
+      enable: OPENPI_TOOL_SURFACE.background.deferred,
+    });
   /** Active bg_watch disarm callbacks, keyed by terminal id (one per id). */
   const watchers = new Map<string, () => void>();
 
@@ -160,7 +184,9 @@ export default function (pi: ExtensionAPI) {
           customType: "background-terminal-result",
           // One message per flush, not per terminal: five processes exiting
           // together are one event to react to, not five.
-          content: snaps.map(buildTerminalResultMessage).join("\n\n"),
+          content: buildTerminalBatchResultMessage(
+            snaps.map(buildTerminalResultMessage),
+          ),
           display: true,
           details:
             snaps.length === 1
@@ -198,12 +224,18 @@ export default function (pi: ExtensionAPI) {
   };
 
   const flushResults = (wake: boolean) => {
-    const snaps = resultDelivery.drain();
-    if (!deliverResults(snaps, wake)) {
-      for (const snap of snaps) resultDelivery.defer(snap);
-    }
+    const snaps = resultDelivery.drain(MAX_RUNNING);
+    if (!deliverResults(snaps, wake)) resultDelivery.restore(snaps);
   };
 
+  const idleResultBatcher = createIdleResultBatcher({
+    delayMs: IDLE_RESULT_BATCH_MS,
+    isIdle: () => sessionContext?.isIdle() === true,
+    flush: flushResults,
+    startTimer: (callback, delayMs) => setTimeout(callback, delayMs),
+    clearTimer: (timer) => clearTimeout(timer),
+  });
+
   const onSettled = (snap: TerminalSnapshot, consumed: boolean) => {
     // A settled terminal has delivered its final result and will emit no more
     // output, so any watch armed on it can never match — disarm it now instead
@@ -216,17 +248,27 @@ export default function (pi: ExtensionAPI) {
     }
     // Defer a deep-enough copy: the live snapshot's output views keep
     // mutating (late flushes) after settle.
-    resultDelivery.defer({
+    const pending = resultDelivery.defer({
       ...snap,
       stdout: { ...snap.stdout },
       stderr: { ...snap.stderr },
     });
-    // Settled while the model sits idle: it has nothing else in flight, so
-    // this is the result it is waiting on — wake it.
-    if (sessionContext?.isIdle()) flushResults(true);
+    // Pending settlements remain retractable while busy, so bg_status/bg_kill
+    // can consume them before they are committed to context. bg_start applies
+    // backpressure across running + pending + reserved work, keeping this map
+    // bounded without dropping or prematurely queueing any result.
+    if (pending >= MAX_RUNNING && sessionContext?.isIdle()) {
+      idleResultBatcher.flushNow();
+      return;
+    }
+    // Give near-simultaneous idle settlements one fixed, bounded window to
+    // join this result. This costs one model turn for a batch instead of one
+    // turn per process, while preserving the immediate path after 200 ms.
+    if (sessionContext?.isIdle()) idleResultBatcher.schedule();
   };
 
   pi.on("session_start", (_event, ctx) => {
+    hideLifecycleTools();
     sessionContext = ctx;
     if (ctx.hasUI) ui = ctx.ui;
   });
@@ -236,7 +278,14 @@ export default function (pi: ExtensionAPI) {
   // double delivery is structurally impossible — whoever drains first wins.
   // These finished while the model was working on something else, so they go
   // into context without forcing a turn per stale process.
-  pi.on("agent_settled", () => flushResults(false));
+  pi.on("agent_settled", () => {
+    idleResultBatcher.flushWithoutWake();
+    // A failed send is restored exactly. Drain it in bounded chunks on later
+    // settled turns rather than growing a single unbounded message.
+    if (sessionContext?.isIdle() && resultDelivery.size() > 0) {
+      idleResultBatcher.schedule();
+    }
+  });
 
   // /new, /resume, /fork, /reload, and quit all emit session_shutdown for
   // the old extension instance. Processes never survive a session
@@ -245,6 +294,7 @@ export default function (pi: ExtensionAPI) {
   // bounded so a wedged process cannot hang shutdown.
   pi.on("session_shutdown", async () => {
     sessionContext = undefined;
+    idleResultBatcher.clear();
     resultDelivery.clear();
     for (const disarm of [...watchers.values()]) disarm();
     watchers.clear();
@@ -256,6 +306,7 @@ export default function (pi: ExtensionAPI) {
       // UI may already be gone.
     }
     widgetRunning = 0;
+    startReservations = 0;
     ui = undefined;
     const closing = runtime;
     runtime = undefined;
@@ -309,15 +360,38 @@ export default function (pi: ExtensionAPI) {
           .replace(/\s+/g, " ")
           .trim()
           .slice(0, 80) || "terminal";
-      const snap = await runTool(
-        getRuntime(),
-        manager.start({
-          command,
-          title,
-          cwd,
-          timeoutSeconds: params.timeout_seconds,
-        }),
-      );
+      const running = manager.view
+        .list()
+        .filter((entry) => entry.status === "running").length;
+      if (
+        !hasTerminalCapacity({
+          running,
+          pending: resultDelivery.size(),
+          reserved: startReservations,
+          maximum: MAX_RUNNING,
+        })
+      ) {
+        throw new Error(
+          `Max ${MAX_RUNNING} background terminals may be running or awaiting delivery. Let the current turn settle, or inspect a finished terminal with bg_status before starting another.`,
+        );
+      }
+      startReservations++;
+      let snap: TerminalSnapshot;
+      try {
+        snap = await runTool(
+          getRuntime(),
+          manager.start({
+            command,
+            title,
+            cwd,
+            timeoutSeconds: params.timeout_seconds,
+          }),
+        );
+      } finally {
+        startReservations--;
+      }
+
+      showLifecycleTools();
 
       return {
         content: [{ type: "text", text: buildStartResult(snap) }],
@@ -591,7 +665,24 @@ export default function (pi: ExtensionAPI) {
         status?: string;
         exitCode?: number;
         signal?: string;
+        results?: Array<{
+          id: string;
+          title: string;
+          status: string;
+          exitCode?: number;
+          signal?: string;
+        }>;
       };
+      const content =
+        typeof message.content === "string" ? message.content : "";
+      if (details.results && details.results.length > 1) {
+        return renderTerminalBatchResult(
+          content,
+          expanded || loadSetupConfig().ui.bashToolDisplay === "full",
+          theme,
+          details.results,
+        );
+      }
       const failed = details.status === "failed";
       const killed = details.status === "killed";
       const timedOut = details.status === "timed_out";
@@ -611,8 +702,6 @@ export default function (pi: ExtensionAPI) {
         theme.fg("accent", theme.bold(`terminal ${details.id ?? "?"}`)) +
         theme.fg("muted", ` · ${details.title ?? ""} · ${how}`);
 
-      const content =
-        typeof message.content === "string" ? message.content : "";
       return renderTerminalResult(
         content,
         expanded || loadSetupConfig().ui.bashToolDisplay === "full",

package/extensions/background-terminals/src/domain.ts

@@ -9,7 +9,11 @@
 import { Data } from "effect";
 
 export type TerminalStatus =
-  "running" | "done" | "failed" | "killed" | "timed_out";
+  | "running"
+  | "done"
+  | "failed"
+  | "killed"
+  | "timed_out";
 // "done"      = exited with code 0
 // "failed"    = exited non-zero, or a spawn-level runtime error after start
 // "killed"    = terminated by bg_kill, the /ps UI, or session teardown

package/extensions/background-terminals/src/manager.ts

@@ -313,7 +313,8 @@ const makeManager = Effect.gen(function* () {
   let disposed = false;
   let spillDir: string | undefined | null;
   let onSettled:
-    ((snap: TerminalSnapshot, consumed: boolean) => void) | undefined;
+    | ((snap: TerminalSnapshot, consumed: boolean) => void)
+    | undefined;
 
   const notify = (id?: string) => {
     for (const listener of [...listeners]) {

package/extensions/background-terminals/src/prompt.ts

@@ -22,6 +22,8 @@ export const STATUS_STDERR_MAX = 8 * 1024;
 export const RESULT_STDOUT_MAX = 8 * 1024;
 /** Completion follow-up stderr tail. Keep this concise; /ps has the detailed view. */
 export const RESULT_STDERR_MAX = 4 * 1024;
+/** Global model-facing cap for one batched completion message. */
+export const RESULT_BATCH_MAX = 48 * 1024;
 const STATUS_STDOUT_MAX_LINES = 400;
 const STATUS_STDERR_MAX_LINES = 200;
 const RESULT_STDOUT_MAX_LINES = 40;
@@ -179,6 +181,39 @@ export function buildTerminalResultMessage(snap: TerminalSnapshot) {
   return text;
 }
 
+/** Preserve every retained terminal identity while globally bounding batch logs. */
+export function buildTerminalBatchResultMessage(
+  messages: readonly string[],
+  omitted = 0,
+) {
+  if (messages.length === 1 && omitted === 0) return messages[0]!;
+  const summaries = messages.map(
+    (message) => message.split("\n", 1)[0] || "Background terminal result",
+  );
+  const header = [
+    `${messages.length} background terminal result${messages.length === 1 ? "" : "s"}:`,
+    ...summaries.map((summary) => `- ${summary}`),
+    omitted > 0
+      ? `- ${omitted} older result${omitted === 1 ? "" : "s"} omitted from this bounded batch; use bg_list/bg_status for retained details.`
+      : "",
+  ]
+    .filter(Boolean)
+    .join("\n");
+  const logsHeader = "\n\nLogs (newest tail):\n";
+  const truncationMarker =
+    "\n[batch logs truncated at the 48 KiB model-context limit; use bg_status or /ps for retained details.]";
+  const fixedBytes = Buffer.byteLength(
+    `${header}${logsHeader}${truncationMarker}`,
+    "utf8",
+  );
+  const logs = truncateTail(messages.join("\n\n"), {
+    maxBytes: Math.max(1, RESULT_BATCH_MAX - fixedBytes),
+    maxLines: DEFAULT_MAX_LINES,
+  });
+  const text = `${header}${logsHeader}${logs.content}${logs.truncated ? truncationMarker : ""}`;
+  return text;
+}
+
 export function buildKillReport(results: ReadonlyArray<KillResult>) {
   return results
     .map((entry) => {