@ian-pascoe/pi-termctrl 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ian Pascoe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# @ian-pascoe/pi-termctrl
+
+Interactive Terminals, Background jobs, and a `/ps` panel for
+[Pi](https://github.com/earendil-works/pi). It is a minimal alternative to
+`pi-interactive-shell`.
+
+- **Terminals** are PTY programs, such as REPLs, TUIs and prompts, that the agent
+  drives by sending input and reading the screen. They run through
+  [`@kitlangton/terminal-control`](https://www.npmjs.com/package/@kitlangton/terminal-control).
+- **Background jobs** are `bash` commands that keep running after their tool
+  call returns.
+- **`/ps`** lists both, previews them live, and stops them.
+
+## Install
+
+```bash
+pi install npm:@ian-pascoe/pi-termctrl
+# or
+pi install git:github.com/ian-pascoe/pi-extensions
+```
+
+For a local checkout, run `pi -e ./packages/pi-termctrl/src/index.ts`.
+
+## Terminal tools
+
+| Tool             | Parameters                                                |
+| ---------------- | --------------------------------------------------------- |
+| `terminal_start` | `command`, `cwd?`, `wait_ms?`, `notify?` (default `true`) |
+| `terminal_send`  | `id`, `text?`, `keys?`, `wait_for_text?`, `wait_ms?`      |
+| `terminal_stop`  | `id`: a Terminal id (`t1`) or Background job id (`b1`)    |
+| `terminal_list`  | none                                                      |
+
+`terminal_start` runs `command` through the shell Pi's `bash` uses (the
+`shellPath` setting, otherwise Pi's default bash), applies `shellCommandPrefix`,
+and opens a PTY sized by `termctrl.defaultViewport`.
+
+`terminal_start` and `terminal_send` wait until the Terminal **settles**: at the
+first of 250 ms of screen quiet, a `wait_for_text` match, process exit, or
+`wait_ms` running out. `wait_for_text` is a literal substring, or a regex when
+written as `/source/flags`; with `wait_for_text`, quiet alone does not end the
+wait, and text already on the screen before `terminal_send` counts only after
+the screen changes. Default waits are 2 s for `terminal_start`, 500 ms for `terminal_send`
+with input, and 30 s for a `terminal_send` with neither `text` nor `keys` (a
+poll, which settles on quiet only after new output). Every `wait_ms` clamps to
+5 minutes.
+
+Results contain the visible screen, the log lines that scrolled off since the
+agent's previous result, `state`, `exit_code` or `signal` once exited, and
+`changed: false` when the screen matches the previous result. Scrolled-off lines
+include lines the agent saw on an earlier screen, so a line rewritten in place,
+such as a progress line, arrives in its final form. Tools that declare
+structured output give `codemode` scripts typed values.
+
+Scrolled-off lines are best effort: they come from termctrl's scrollback, which
+is limited (several hundred lines; fewer when lines are long) and drops its
+oldest lines first. Reading a Terminal before its scrollback fills loses
+nothing. When lines the agent never received were dropped, or the screen was
+cleared, the result reports every line termctrl still holds, sets
+`output_missing: true`, and says that earlier output is missing. A Terminal's
+first result cannot detect dropped lines: when a program prints more than the
+scrollback holds before that result, its oldest lines are lost without
+`output_missing`, because termctrl does not report the trimming. Run commands
+whose complete output matters with `bash`, or redirect their output to a file.
+
+A result is limited to Pi's 2000 lines or 50 KB. The screen is kept first, from
+its bottom, and the newest scrolled-off lines fill the rest. When anything is
+cut, every line of the result goes to
+`$TMPDIR/pi-termctrl/<pid>-<id>-output-<n>.log`, named in the result's notice
+and `full_output_path`.
+
+`keys` are termctrl key names: `Enter`, `Escape`, `ArrowUp`, `ArrowDown`,
+`ArrowLeft`, `ArrowRight`, `Tab`, `Shift+Tab`, `Backspace`, `Delete`, `Home`,
+`End`, `PageUp`, `PageDown`, and `Control+A` to `Control+Z`. Text is typed
+before keys.
+
+Terminal ids are `t1`, `t2`, … and Background job ids are `b1`, `b2`, …; ids are
+never reused in a Pi process, including across `/reload`. At most 16 running
+Terminals and Background jobs may exist across the whole process; starting
+another fails and lists the caller's live entries.
+
+`terminal_stop` stops a running entry (termctrl stop, then `SIGKILL` of the
+Terminal's process group if it is still alive after 3 s) and forgets it. For a
+Terminal it returns the final screen and scrolled-off lines; for a Background
+job, its recent output. Exited entries stay
+readable and listed until the agent stops them, the user removes them in `/ps`,
+or their session shuts down. `terminal_list` lists the caller's Terminals and,
+in a separate `background_jobs` section, its Background jobs with their log
+paths.
+
+## `bash` replacement
+
+With `termctrl.replaceBash` (default `true`), Pi Termctrl replaces Pi's `bash`
+tool with Pi's own definition plus one parameter, `background?: boolean`.
+Commands still run on pipes through Pi's local `exec`, so Pi keeps spawning,
+process-tree kills, truncation and rendering, and foreground results are
+unchanged. A command becomes a Background job in two ways:
+
+- **`background: true`** waits 2 s. A command that finishes first returns an
+  ordinary result; otherwise the call returns a background result. If the cap
+  is reached during those 2 s, the command stays in the foreground.
+- **Ctrl+B** while an agent `bash` call runs moves every running call to the
+  background. At other times Ctrl+B stays the editor's cursor-left.
+
+Up to 16 MiB of a command's output is kept in memory until it is backgrounded;
+older output becomes an omission line in the log. Once backgrounded, a
+command's `timeout` is cleared, Esc and turn aborts no
+longer reach it, and its output so far and all later output go to
+`$TMPDIR/pi-termctrl/<pid>-<id>.log`. The result says
+`Command moved to the background as b<n>`, includes the output so far, and
+gives the log path; read the log with `read` and stop the job with
+`terminal_stop`. Its structured result follows Pi's `bash` output schema, except
+that `exit_code` is absent and `background: { id, log_path }` is present.
+
+A Background job's log is deleted when the job is stopped, when the user
+removes it in `/ps`, or when its session shuts down for any reason except
+reload. `bash` calls from `codemode` scripts behave the same. User `!` commands
+are not affected.
+
+**Conflict:** only one extension can own `bash`. Set `"replaceBash": false` when
+another extension registers `bash`; Pi's `bash` is then untouched and the
+backgrounding paths do not exist.
+
+## Exit notifications
+
+When a Terminal or Background job exits and the agent has neither seen the exit
+in a `terminal_*` result nor stopped it, Pi Termctrl sends an Exit notification:
+the id, command, exit code or signal, duration, and the last
+`termctrl.exitTailLines` lines of the final screen or log. Exits in the same tick
+share one message. It steers a working agent and starts a turn when the agent is
+idle. `terminal_start {notify: false}` opts a Terminal out. Notifications go
+only to the session that started the entry, and wait across `/reload`.
+
+## `/ps` and footer
+
+`/ps` opens an overlay listing every entry in the Pi process, including those of
+in-process child agents, with kind, id, owner (`root` or `child`), state and
+age, plus a live preview of the selected Terminal's screen or Background job's
+log tail. Keys: `↑`/`↓` select, `k` stops without confirmation (the agent gets an
+Exit notification), `x` removes an exited entry, `Esc` closes. The footer shows
+`N running` while anything is live. In RPC mode `/ps` sends a one-line summary;
+print mode has no UI but keeps the tools and notifications.
+
+## Lifecycle
+
+Terminals and Background jobs live in the Pi process
+([ADR-0001](docs/adr/0001-terminals-live-in-the-pi-process.md)). They survive
+`/reload`; every other session shutdown (quit, new, resume, fork) stops the
+session's own entries. Nothing persists across Pi restarts. Besides Background
+job logs and full output files, the only file written is a short-lived pid
+handoff file per Terminal launch in `$TMPDIR/pi-termctrl`, deleted as soon as
+it is read. Full output files outlive their Terminal, so a `terminal_stop`
+result can name one, and are deleted when their session shuts down for any
+reason except reload.
+
+## Settings
+
+Pi Termctrl reads the `termctrl` key from Pi's global `settings.json` and
+trusted project `.pi/settings.json`; project values override global ones field
+by field:
+
+```json
+{
+  "termctrl": {
+    "replaceBash": true,
+    "defaultViewport": { "cols": 120, "rows": 40 },
+    "exitTailLines": 20
+  }
+}
+```
+
+| Setting           | Default                   | Meaning                                         |
+| ----------------- | ------------------------- | ----------------------------------------------- |
+| `replaceBash`     | `true`                    | Replace `bash` to enable Background jobs        |
+| `defaultViewport` | `{ cols: 120, rows: 40 }` | Terminal size; each dimension 1 to 1000         |
+| `exitTailLines`   | `20`                      | Lines of output in an Exit notification, 0–1000 |
+
+Invalid values keep the lower layer and unknown keys produce warnings at session
+start. Use `/reload` after editing settings.
+
+## Platform
+
+`@kitlangton/terminal-control` installs a `termctrl` binary for macOS and
+GNU/Linux on arm64 or x64 through optional dependencies. Set `TERMCTRL_BINARY`
+to use another binary. Where no binary resolves (Windows, musl, or
+`--omit=optional`), Pi Termctrl shows one diagnostic and registers no
+`terminal_start` or `terminal_send`; the `bash` replacement, Background jobs,
+`terminal_stop` and `terminal_list` keep working wherever Pi's `bash` does.
+
+Not supported: attaching to or taking over a Terminal, recordings, mouse input,
+resize, raw bytes, persistence across Pi restarts, and graceful `SIGTERM`
+stopping of Background jobs.

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@ian-pascoe/pi-termctrl",
+  "version": "0.0.0",
+  "private": false,
+  "description": "Interactive Terminals, Background jobs, and a /ps panel for Pi.",
+  "keywords": [
+    "background-jobs",
+    "pi",
+    "pi-extension",
+    "pi-package",
+    "pty",
+    "terminal"
+  ],
+  "homepage": "https://github.com/ian-pascoe/pi-extensions/tree/main/packages/pi-termctrl",
+  "bugs": {
+    "url": "https://github.com/ian-pascoe/pi-extensions/issues"
+  },
+  "license": "MIT",
+  "author": "Ian Pascoe <ian.g.pascoe@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ian-pascoe/pi-extensions.git",
+    "directory": "packages/pi-termctrl"
+  },
+  "files": [
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "test": "vitest run --config ../../vitest.config.ts --root .",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@kitlangton/terminal-control": "^1.2.1"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  }
+}

package/skills/pi-termctrl/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: pi-termctrl
+description: Configure or diagnose Pi Termctrl when Terminal tools are missing, the bash replacement conflicts with another extension, Background jobs misbehave, or termctrl settings need changing.
+license: MIT
+---
+
+# Pi Termctrl
+
+1. Read [`../../README.md`](../../README.md)'s Settings and Platform sections, then identify the effective `termctrl` settings scope.
+2. If `terminal_start` is missing, check the startup diagnostic. Confirm the platform has a packaged `termctrl` binary or that `TERMCTRL_BINARY` names an executable one.
+3. If `bash` lacks the `background` parameter, check `termctrl.replaceBash` and look for another extension that also registers `bash`.
+4. Call `terminal_list` to inspect live and exited Terminals and Background jobs. Ask the user to open `/ps` for a live preview.
+5. Classify the failure as settings, binary resolution, `bash` conflict, cap, or process behaviour.
+6. For a requested change, edit one settings layer, validate its JSON, and reload Pi. Finish when the expected tools appear or one exact cause remains.
+
+Ask before stopping a Terminal or Background job you did not start.

package/src/bash-replacement.ts

@@ -0,0 +1,369 @@
+import { createWriteStream, mkdirSync, openSync, type WriteStream } from "node:fs";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  createBashToolDefinition,
+  createLocalBashOperations,
+  formatSize,
+  truncateTail,
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  type BashOperations,
+  type BashToolOptions,
+  type ExtensionToolContext,
+  type ExtensionUIContext,
+} from "@earendil-works/pi-coding-agent";
+import { matchesKey } from "@earendil-works/pi-tui";
+import { Type, type TSchema } from "typebox";
+import { KILLED_EXIT, TermctrlRegistry } from "./termctrl-registry.js";
+import { termctrlTemporaryDirectory } from "./termctrl-driver.js";
+import type { TerminalExit } from "./terminal-driver.js";
+
+/** How long `background: true` waits before moving a still-running command to the background. */
+export const BACKGROUND_YIELD_MS = 2_000;
+const MAX_TIMEOUT_MS = 2_147_483_647;
+/** Output kept in memory before backgrounding; older output is dropped from the log's head. */
+const BUFFER_LIMIT_BYTES = 16 * 1024 * 1024;
+/** Recent output kept for previews and Exit notifications. */
+const TAIL_LIMIT_CHARS = 64 * 1024;
+
+type ExecOptions = Parameters<BashOperations["exec"]>[2];
+
+/** Path of a Background job's log. The pid keeps concurrent Pi processes apart. */
+export function backgroundLogPath(id: string): string {
+  return join(termctrlTemporaryDirectory(), `${process.pid}-${id}.log`);
+}
+
+/** What a backgrounded call reports to the agent. */
+interface BackgroundOutcome {
+  readonly id: string;
+  readonly logPath: string;
+  readonly output: string;
+}
+
+/**
+ * One agent `bash` call. Wraps Pi's local `exec` so the call can leave the tool call: it owns the
+ * abort controller and the timeout, and tees output into a buffer and, after backgrounding, a log.
+ */
+class BashCall {
+  private readonly controller = new AbortController();
+  private readonly chunks: Buffer[] = [];
+  private bufferedBytes = 0;
+  private droppedBytes = 0;
+  private recent = "";
+  private readonly decoder = new TextDecoder();
+  private log: WriteStream | undefined;
+  private timer: ReturnType<typeof setTimeout> | undefined;
+  private timedOut = false;
+  private started = false;
+  private startedAt = Date.now();
+  private settled = false;
+  private jobId: string | undefined;
+  private forwardData: ((data: Buffer) => void) | undefined;
+  private resolveBackground!: (outcome: BackgroundOutcome) => void;
+  readonly backgrounded: Promise<BackgroundOutcome>;
+  private isBackgrounded = false;
+
+  constructor(
+    private readonly owner: string,
+    private readonly command: string,
+    private readonly local: BashOperations,
+  ) {
+    this.backgrounded = new Promise((resolve) => {
+      this.resolveBackground = resolve;
+    });
+  }
+
+  /** The `BashOperations.exec` Pi's `execute` calls. */
+  async exec(
+    command: string,
+    cwd: string,
+    options: ExecOptions,
+  ): Promise<{ exitCode: number | null }> {
+    const { timeout, signal, onData, env } = options;
+    if (timeout !== undefined) {
+      if (!Number.isFinite(timeout) || timeout <= 0) {
+        throw new Error("Invalid timeout: must be a finite number of seconds");
+      }
+      if (timeout * 1000 > MAX_TIMEOUT_MS) {
+        throw new Error(`Invalid timeout: maximum is ${MAX_TIMEOUT_MS / 1000} seconds`);
+      }
+    }
+    if (signal?.aborted) throw new Error("aborted");
+    this.forwardData = onData;
+    const forwardAbort = () => {
+      if (!this.isBackgrounded) this.controller.abort();
+    };
+    signal?.addEventListener("abort", forwardAbort, { once: true });
+    if (timeout !== undefined) {
+      this.timer = setTimeout(() => {
+        this.timedOut = true;
+        this.controller.abort();
+      }, timeout * 1000);
+    }
+    this.started = true;
+    this.startedAt = Date.now();
+    try {
+      const localOptions: ExecOptions = {
+        onData: (data) => this.receive(data),
+        signal: this.controller.signal,
+      };
+      if (env !== undefined) localOptions.env = env;
+      const result = await this.local.exec(command, cwd, localOptions);
+      this.finish({ code: result.exitCode, signal: null });
+      return result;
+    } catch (error) {
+      this.finish(this.controller.signal.aborted ? KILLED_EXIT : { code: null, signal: null });
+      if (this.timedOut && !this.isBackgrounded)
+        throw new Error(`timeout:${timeout}`, { cause: error });
+      throw error;
+    } finally {
+      this.settled = true;
+      clearTimeout(this.timer);
+      signal?.removeEventListener("abort", forwardAbort);
+    }
+  }
+
+  private receive(data: Buffer): void {
+    if (this.isBackgrounded) {
+      this.log?.write(data);
+      this.remember(this.decoder.decode(data, { stream: true }));
+      return;
+    }
+    this.chunks.push(data);
+    this.bufferedBytes += data.length;
+    while (this.bufferedBytes > BUFFER_LIMIT_BYTES && this.chunks.length > 1) {
+      const dropped = this.chunks.shift();
+      this.bufferedBytes -= dropped?.length ?? 0;
+      this.droppedBytes += dropped?.length ?? 0;
+    }
+    this.forwardData?.(data);
+  }
+
+  private remember(text: string): void {
+    this.recent = (this.recent + text).slice(-TAIL_LIMIT_CHARS);
+  }
+
+  private finish(exit: TerminalExit): void {
+    if (this.jobId === undefined) return;
+    this.remember(this.decoder.decode());
+    const log = this.log;
+    this.log = undefined;
+    log?.end();
+    TermctrlRegistry.current()?.jobExited(this.jobId, exit);
+  }
+
+  /** Move the running command to the background. Returns false when it already finished. */
+  background(registry: TermctrlRegistry): boolean {
+    if (this.isBackgrounded || this.settled || !this.started) return false;
+    // An aborted or timed-out command is already dying; let Pi report it.
+    if (this.controller.signal.aborted) return false;
+    const entry = registry.createJob(
+      this.owner,
+      this.command,
+      (id) => {
+        const logPath = backgroundLogPath(id);
+        mkdirSync(termctrlTemporaryDirectory(), { recursive: true });
+        this.log = createWriteStream(logPath, { fd: openSync(logPath, "w") });
+        this.log.on("error", () => {});
+        return {
+          logPath,
+          stop: () => this.controller.abort(),
+          tail: () => this.recent,
+          removeLog: async () => {
+            this.log?.end();
+            await rm(logPath, { force: true });
+          },
+        };
+      },
+      this.startedAt,
+    );
+    this.jobId = entry.id;
+    this.isBackgrounded = true;
+    clearTimeout(this.timer);
+    if (this.droppedBytes > 0) {
+      this.log?.write(
+        `[pi-termctrl: ${formatSize(this.droppedBytes)} of earlier output omitted]\n`,
+      );
+    }
+    for (const chunk of this.chunks) this.log?.write(chunk);
+    const output = this.decoder.decode(Buffer.concat(this.chunks), { stream: true });
+    this.chunks.length = 0;
+    this.remember(output);
+    this.resolveBackground({ id: entry.id, logPath: entry.child.logPath, output });
+    return true;
+  }
+}
+
+/** The agent `bash` calls running in one session, and the Ctrl+B subscription while any run. */
+export class RunningBashCalls {
+  private readonly calls = new Set<BashCall>();
+  private unsubscribe: (() => void) | undefined;
+
+  constructor(private readonly registry: () => TermctrlRegistry) {}
+
+  /** Track a call; the first one subscribes to Ctrl+B. */
+  add(call: BashCall, ui: ExtensionUIContext): void {
+    this.calls.add(call);
+    if (this.unsubscribe !== undefined) return;
+    this.unsubscribe = ui.onTerminalInput((data) => {
+      if (!matchesKey(data, "ctrl+b")) return undefined;
+      this.backgroundAll(ui);
+      return { consume: true };
+    });
+  }
+
+  /** Stop tracking a call; the last one releases Ctrl+B back to the editor. */
+  delete(call: BashCall): void {
+    this.calls.delete(call);
+    if (this.calls.size > 0) return;
+    this.dispose();
+  }
+
+  /** Move every running call to the background. */
+  backgroundAll(ui: Pick<ExtensionUIContext, "notify">): void {
+    for (const call of this.calls) {
+      try {
+        call.background(this.registry());
+      } catch (error) {
+        ui.notify(error instanceof Error ? error.message : String(error), "warning");
+      }
+    }
+  }
+
+  dispose(): void {
+    this.unsubscribe?.();
+    this.unsubscribe = undefined;
+  }
+}
+
+/** Settings the replacement shares with Pi's built-in `bash`. */
+export interface BashReplacementOptions {
+  readonly cwd: string;
+  readonly commandPrefix: string | undefined;
+  readonly shellPath: string | undefined;
+  readonly registry: () => TermctrlRegistry;
+  readonly calls: RunningBashCalls;
+  /** Builds Pi's `bash` definition; tests wrap it to observe what reaches Pi's accumulator. */
+  readonly definitionFactory?: typeof createBashToolDefinition;
+}
+
+function backgroundOutputSchema(builtin: TSchema | undefined) {
+  const properties = builtin !== undefined && Type.IsObject(builtin) ? builtin.properties : {};
+  return Type.Object({
+    ...properties,
+    exit_code: Type.Optional(
+      Type.Number({ description: "Absent only when the command was moved to the background" }),
+    ),
+    background: Type.Optional(
+      Type.Object(
+        {
+          id: Type.String({ description: "Background job id, for terminal_stop" }),
+          log_path: Type.String({ description: "File receiving the job's output; read it" }),
+        },
+        { description: "Present when the command was moved to the background" },
+      ),
+    ),
+  });
+}
+
+function backgroundResult(outcome: BackgroundOutcome, startedAt: number) {
+  const truncation = truncateTail(outcome.output);
+  let text = truncation.content;
+  if (truncation.truncated) {
+    text += `\n\n[Showing lines ${truncation.totalLines - truncation.outputLines + 1}-${truncation.totalLines} of ${truncation.totalLines} (${formatSize(DEFAULT_MAX_BYTES)} or ${DEFAULT_MAX_LINES} line limit). Full output: ${outcome.logPath}]`;
+  }
+  const status = `Command moved to the background as ${outcome.id}. Its output so far and all later output go to ${outcome.logPath}; read that file to check progress, and stop it with terminal_stop {"id": "${outcome.id}"}. You will get an Exit notification when it ends.`;
+  return {
+    content: [{ type: "text" as const, text: text === "" ? status : `${text}\n\n${status}` }],
+    details: undefined,
+    structuredContent: {
+      output: truncation.content,
+      truncated: truncation.truncated,
+      wall_time_seconds: Math.round((performance.now() - startedAt) / 100) / 10,
+      background: { id: outcome.id, log_path: outcome.logPath },
+    },
+  };
+}
+
+/** Pi's `bash` definition plus `background`, executed through Pi's own pipes. */
+export function createBashReplacement(options: BashReplacementOptions) {
+  const builtinOptions: BashToolOptions = {};
+  if (options.commandPrefix !== undefined) builtinOptions.commandPrefix = options.commandPrefix;
+  if (options.shellPath !== undefined) builtinOptions.shellPath = options.shellPath;
+  const builtin = createBashToolDefinition(options.cwd, builtinOptions);
+  const local = createLocalBashOperations(
+    options.shellPath === undefined ? undefined : { shellPath: options.shellPath },
+  );
+  const parameters = Type.Object({
+    ...builtin.parameters.properties,
+    background: Type.Optional(
+      Type.Boolean({
+        description:
+          "Run in the background if still running after 2 seconds; returns a Background job id and log path",
+      }),
+    ),
+  });
+  return {
+    ...builtin,
+    parameters,
+    outputSchema: backgroundOutputSchema(builtin.outputSchema),
+    async execute(
+      toolCallId: string,
+      params: { command: string; timeout?: number; background?: boolean },
+      signal: AbortSignal | undefined,
+      onUpdate: Parameters<typeof builtin.execute>[3],
+      context: ExtensionToolContext,
+    ) {
+      const registry = options.registry();
+      const owner = context.sessionManager.getSessionId();
+      if (params.background === true) registry.checkCapacity(owner);
+      const call = new BashCall(owner, params.command, local);
+      const inner = (options.definitionFactory ?? createBashToolDefinition)(options.cwd, {
+        ...builtinOptions,
+        operations: { exec: (command, cwd, execOptions) => call.exec(command, cwd, execOptions) },
+      });
+      let backgrounded = false;
+      const forwardUpdate: typeof onUpdate =
+        onUpdate === undefined
+          ? undefined
+          : (update) => {
+              if (!backgrounded) onUpdate(update);
+            };
+      const startedAt = performance.now();
+      const running = inner.execute(
+        toolCallId,
+        params.timeout === undefined
+          ? { command: params.command }
+          : { command: params.command, timeout: params.timeout },
+        signal,
+        forwardUpdate,
+        context,
+      );
+      running.catch(() => {});
+      options.calls.add(call, context.ui);
+      const yieldTimer =
+        params.background === true
+          ? setTimeout(() => {
+              try {
+                call.background(registry);
+              } catch {
+                // The cap filled during the yield window; the command stays in the foreground.
+              }
+            }, BACKGROUND_YIELD_MS)
+          : undefined;
+      try {
+        const winner = await Promise.race([
+          running.then((result) => ({ kind: "finished" as const, result })),
+          call.backgrounded.then((outcome) => ({ kind: "background" as const, outcome })),
+        ]);
+        if (winner.kind === "finished") return winner.result;
+        backgrounded = true;
+        return backgroundResult(winner.outcome, startedAt);
+      } finally {
+        clearTimeout(yieldTimer);
+        options.calls.delete(call);
+      }
+    },
+  };
+}