specpi 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.33.0 - 2026-09-23
+
+- Run long commands as background jobs, so a long eval or build no longer holds the conversation. 0.32.0 judged a background-task system not worth building from Terminal-Bench transcripts, which measure task outcomes and cannot see the actual cost: a person unable to say anything until a many-minute command returns. The `background` tool starts a command and returns at once; when the job ends, its exit code and last lines of output arrive as a follow-up message and the agent picks it up. `/jobs` lists jobs, shows recent output and stops them.
+- Keep it one small tool that only starts jobs, 657 characters of schema. Status needs no tool, because the result arrives on its own, and stopping is a human command. Jobs run through Pi's own shell runner with the session's shell settings, are limited to four at once, log to capped owner-only files, and end with the session, which deletes their logs.
+- Apply every `bash` permission rule to background jobs. The installer records `background` in the permission system's `shellTools`, which gates its command through the same stack as `bash`, and removes the entry at uninstall. Before every start the extension checks the effective mapping, including a trusted project's, and refuses without it.
+- Turn background jobs off while the Jev command guard is on, because the guard only checks `bash`. Its saved state is read the way the guard reads it. A guard switched on for one session only is invisible to other extensions, so that case is documented rather than guessed at.
+- Offer the tool only to interactive sessions where a start could succeed, decided before the first request. Eval runs never see it, so their tool surface is unchanged.
+- Pair with SpecPi Chat 0.16.0, which shows running jobs in the session footer.
+- Say plainly in the working agreement that irreversible steps nobody asked for are off the table: rewriting Git history, pruning reflogs or objects, force-pushing, deleting data that cannot be restored. The agent does the reversible part, then says what remains and offers it. On Terminal-Bench's `sanitize-git-repo`, every attempt from either arm that left Git history alone passed, and every failure had rewritten it, destroying the commit the checker compares against. SpecPi's "reversible" wording already halved how often that happened (9 of 18 attempts against Pi's 17 of 18), which is why it led that task 12/18 to 3/18. The explicit rule targets the remaining 9. It is also the better behaviour outside a benchmark: purging keys from history breaks existing clones and needs a force-push, so it is a decision to offer, not to take. It adds 233 characters to every request, and its effect on the benchmark is not yet measured.
+
 ## 0.32.0 - 2026-09-23
 
 - Send less on every request. SpecPi's first request was 14,022 characters against Pi's 5,521, and that overhead rides every turn and is never removed by compaction. Measured again with all eight pins, the interactive default is now 11,119. A headless session drops the two tools below as well, which the measured parts put at about 8,300: SpecPi's overhead falls from 8,501 characters to about 2,800.

package/NPM_RELEASE.md

@@ -6,7 +6,7 @@ Publishing, tags, deprecation, ownership changes and GitHub Releases require exp
 
 ## Prepare
 
-1. This candidate is SpecPi **0.32.0**, paired with the Chat **0.15.0** VSIX. Browser QA **0.3.0** is already independently published; do not republish or edit its source as part of this release. Choose an unused version; update `package.json`, the dated `CHANGELOG.md` entry, README, and the website. Check Chat's version and VSIX download links. Preserve historical changelog entries.
+1. This candidate is SpecPi **0.33.0**, paired with the Chat **0.16.0** VSIX. Browser QA **0.3.0** is already independently published; do not republish or edit its source as part of this release. Choose an unused version; update `package.json`, the dated `CHANGELOG.md` entry, README, and the website. Check Chat's version and VSIX download links. Preserve historical changelog entries.
 2. Validate:
 
     ```sh

package/README.md

@@ -28,7 +28,7 @@
 
 ---
 
-SpecPi 0.32.0 is a small starting point for the [Pi coding agent](https://pi.dev/). It is one opinionated setup for how the agent should work, not a marketplace of plugins.
+SpecPi 0.33.0 is a small starting point for the [Pi coding agent](https://pi.dev/). It is one opinionated setup for how the agent should work, not a marketplace of plugins.
 
 At the center are two built-in extensions. **Scope control** keeps each task to the files it said it would touch. The **improvement loop** turns repeated friction into small, tested changes to the setup, instead of letting prompts and workarounds pile up. Around those are eight hand-picked packages, each locked to an exact version and checked before anything installs, plus **SpecPi Chat**, a VS Code panel for working alongside the agent.
 
@@ -38,6 +38,7 @@ It focuses on five things:
 - **Accuracy:** exact version pins, checksums on state, rollback on failure, and proof over promises
 - **Improvement:** local notes become small, checked changes through `/harness-improvement`
 - **Efficiency:** delegation, persistent goals, and browser QA handled by the right tool for the job
+- **Keep talking:** long evals, builds and servers can run as background jobs, so the conversation is not stuck until they finish. The agent hears back when each one ends, and `/jobs` lists or stops them
 - **Lean default:** web access, browser QA, and delegation stay off until you need them. Turn them on for a session with `/webaccess on`, `/browser on`, and `/delegate on` — or let the agent ask when it hits the need, and answer the prompt
 
 Everything it touches is written down, versioned, and easy to undo.
@@ -52,7 +53,7 @@ The solid rows are measured by us, from the request each setup actually sends th
   <a href="https://tannermidd.github.io/SpecPi/research/#specpi">
     <picture>
       <source media="(prefers-color-scheme: dark)" srcset="https://tannermidd.github.io/SpecPi/media/context-chart-dark.svg">
-      <img src="https://tannermidd.github.io/SpecPi/media/context-chart-light.svg" width="880" alt="Bar chart of characters sent on the first model call: Pi stock 5,521, SpecPi default 11,119, OpenCode 31,043, DeepSeek Harness 31,743, SpecPi enabled 35,767, Codex CLI 41,616, Oh My Pi 66,708, Claude Code 90,460.">
+      <img src="https://tannermidd.github.io/SpecPi/media/context-chart-light.svg" width="880" alt="Bar chart of characters sent on the first model call: Pi stock 5,521, SpecPi default 12,010, OpenCode 31,043, DeepSeek Harness 31,743, SpecPi enabled 36,658, Codex CLI 41,616, Oh My Pi 66,708, Claude Code 90,460.">
     </picture>
   </a>
 </p>
@@ -64,7 +65,7 @@ The gap between the two SpecPi bars comes from a few separate switches, so the e
   <a href="https://tannermidd.github.io/SpecPi/research/#specpi">
     <picture>
       <source media="(prefers-color-scheme: dark)" srcset="https://tannermidd.github.io/SpecPi/media/capability-chart-dark.svg">
-      <img src="https://tannermidd.github.io/SpecPi/media/capability-chart-light.svg" width="880" alt="Bar chart of tool-schema characters each capability adds: Pi built-ins 2,896, Improvement loop 1,601, Capability request 995, Goals 1,315, Browser QA 8,234, Delegation 4,453, Web access 11,298. Browser QA, Delegation, Web access are hidden until switched on.">
+      <img src="https://tannermidd.github.io/SpecPi/media/capability-chart-light.svg" width="880" alt="Bar chart of tool-schema characters each capability adds: Pi built-ins 2,896, Improvement loop 1,601, Capability request 995, Background jobs 657, Goals 1,315, Browser QA 8,234, Delegation 4,453, Web access 11,298. Browser QA, Delegation, Web access are hidden until switched on.">
     </picture>
   </a>
 </p>

package/SECURITY_MODEL.md

@@ -14,6 +14,18 @@ Optional tool groups ship withdrawn. The `request_capability` tool lets the mode
 
 `/capability allow <name>` records a standing grant so that group is offered without a prompt, and `/capability ask <name>` returns it to prompting. Recording either requires an interactive human command, and a grant that fires still announces itself in the session. Grants live in `<agent-dir>/specpi/capabilities/settings.json`, written atomically with owner-only permissions; links and irregular files are refused, and an unreadable file, a foreign schema or an unknown capability name reads as no grant. A standing grant removes the prompt, not the requirement for a human: headless sessions are still refused, so a granted capability cannot be activated by an unattended run. It also does not offer the group at startup — the model must still ask, and the group stays withdrawn until it does.
 
+## Background jobs
+
+The `background` tool starts a shell command and returns at once; the job reports its exit code and last lines of output as a follow-up message when it ends. It runs through Pi's own local shell runner with the session's `shellPath` and `shellCommandPrefix`, so the shell, working directory and process-tree cleanup on Pi's exit match the `bash` tool. It adds no new authority, and every start fails closed:
+
+- **Permission parity.** The installer records `shellTools.background = { commandArgument: "command" }` in the permission system's global config, so its full `bash` stack — command decomposition, wrapper flooring, path and outside-directory checks, and every `bash:` rule — applies to the command. The entry is merged into the existing file, backed up and rolled back with the rest of the transaction, left alone when the file carries comments, and removed at uninstall only if it is still SpecPi's. Before every start the extension reads the effective mapping (global, then a trusted project's, which could remap it) and refuses unless it gates `command`. An unreadable config refuses too.
+- **Command guard.** `specpi-jev-guard` checks `bash`, `powershell`, `write` and `edit` only, so background jobs are off while it is on. The extension resolves the guard's saved state as the guard does — its default on, the global file, then a trusted project's — and starts a job only when that resolves off. The guard's session-only switch lives in its own memory and no other extension can read it, so a guard switched on with `/jev-guard on` without `--global`, over a saved off, does not stop background jobs. Save the choice with `--global` to cover them.
+- **Interactive only.** Headless sessions are not offered the tool and are refused if they call it; there is nobody to report back to. A Pi that cannot list its commands is refused, because the guard and permission system cannot be detected.
+- **Bounded.** At most four jobs run at once. Each log is capped at 8 MiB under `<agent-dir>/specpi/background/`, owner-only, and deleted when the session ends; directories left by a crashed session are pruned after a day. A completion message carries at most 40 lines and 4,000 characters of output with control characters removed. Output is untrusted text, like any tool result.
+- **Session-owned.** `/jobs stop` and session end kill each job's process tree; Pi's own exit handling also kills tracked children. Process cleanup is best effort: a program that detaches itself from its parent, or a daemon a job starts, can outlive it, exactly as with `bash`.
+
+Eval runs overwrite the permission config with their `yoloMode` opt-in, which drops the mapping, so the tool is never offered there and eval rows keep their measured tool surface.
+
 ## Jev advisor
 
 The advisor is the only part of SpecPi that sends anything off this machine, and it ships off. With the master switch off there is no network call, no key read, no consent read and no prompt injection: the harness behaves exactly as it did before the extension existed.

package/THIRD_PARTY.md

@@ -52,4 +52,4 @@ The separately released `packages/browser-qa` source reuses the retired QA imple
 
 The website uses the bundled IBM Plex Sans and Plex Mono fonts under the SIL Open Font License 1.1; see [`site/fonts/LICENSE.txt`](https://github.com/TannerMidd/SpecPi/blob/main/site/fonts/LICENSE.txt). The website's scripts and diagrams are first-party code and assets. The README loads public package/license badges from Shields.io and build status from GitHub. Website fonts and media are not included in the npm package.
 
-SpecPi Chat 0.15.0 is a separately packaged VS Code extension with no bundled runtime dependencies. It uses VS Code's host APIs and Pi's RPC protocol. Generic tool output, visible custom messages, widgets, and dialogs stay owned by their upstream packages. Playwright **1.62.1** (Apache-2.0, [Microsoft Playwright](https://github.com/microsoft/playwright)) is a pinned development dependency for Chat's rendering tests; its browser is used for those checks and is not shipped in either artifact. The default Browser QA package independently uses the same pinned Playwright version for its runtime. Chat's global Destructive guard preset is a full replacement configuration reviewed against Permission System 32.0.2's schema and native pattern semantics. No upstream patch, new dependency, policy-layer merger, or independent command evaluator is included. See [the security model](SECURITY_MODEL.md) for its limits.
+SpecPi Chat 0.16.0 is a separately packaged VS Code extension with no bundled runtime dependencies. It uses VS Code's host APIs and Pi's RPC protocol. Generic tool output, visible custom messages, widgets, and dialogs stay owned by their upstream packages. Playwright **1.62.1** (Apache-2.0, [Microsoft Playwright](https://github.com/microsoft/playwright)) is a pinned development dependency for Chat's rendering tests; its browser is used for those checks and is not shipped in either artifact. The default Browser QA package independently uses the same pinned Playwright version for its runtime. Chat's global Destructive guard preset is a full replacement configuration reviewed against Permission System 32.0.2's schema and native pattern semantics. No upstream patch, new dependency, policy-layer merger, or independent command evaluator is included. See [the security model](SECURITY_MODEL.md) for its limits.

package/extensions/workflow-controls/background.mjs

@@ -0,0 +1,495 @@
+// Background jobs: start a long command, keep talking, hear back when it ends.
+//
+// A long eval or build run through `bash` holds the whole conversation until it returns; the person
+// at the keyboard cannot say anything to the agent in the meantime. A background job returns at once
+// and reports its exit code and last lines of output as a follow-up message when it finishes.
+//
+// It is deliberately small, and it never widens what may run:
+//
+// - One tool, and it only starts jobs. Its `command` is registered with the permission system as a
+//   shell argument (`shellTools`), so every `bash` rule applies to it at full parity. A job may not
+//   start unless that mapping is in effect.
+// - The Jev command guard gates `bash` alone. While it is on, background jobs are off, so a guard
+//   user never loses coverage. Only its saved state is visible to another extension; see
+//   guardEnabled.
+// - Interactive sessions only. A headless run has nobody to report back to.
+// - Jobs belong to the session: they are stopped, and their logs deleted, when it ends.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+export const BACKGROUND_TOOL = "background";
+export const BACKGROUND_MESSAGE = "specpi-background";
+export const BACKGROUND_STATUS = "specpi-background";
+
+/** The `shellTools` entry that makes the permission system gate `command` exactly like `bash`. */
+export const SHELL_TOOL_MAPPING = Object.freeze({ commandArgument: "command" });
+
+export const MAX_RUNNING_JOBS = 4;
+export const MAX_LOG_BYTES = 8 * 1024 * 1024;
+const TAIL_BUFFER_BYTES = 64 * 1024;
+const TAIL_LINES = 40;
+const TAIL_CHARS = 4000;
+const COMMAND_PREVIEW_CHARS = 200;
+const STALE_LOG_MS = 24 * 60 * 60 * 1000;
+
+export function agentDirectory() {
+    const configured = process.env.PI_CODING_AGENT_DIR;
+
+    return path.resolve(configured && configured.length > 0 ? configured : path.join(os.homedir(), ".pi", "agent"));
+}
+
+export function logRoot(agentDir = agentDirectory()) {
+    return path.join(agentDir, "specpi", "background");
+}
+
+/** A fresh log directory for one session's jobs. */
+export function sessionLogDir(agentDir = agentDirectory()) {
+    return path.join(logRoot(agentDir), `${process.pid}-${randomUUID().slice(0, 8)}`);
+}
+
+/**
+ * Remove log directories a crashed session left behind. A session deletes its own on exit, so
+ * anything older than a day belongs to a process that never got the chance.
+ */
+export function pruneStaleLogs({ root = logRoot(), maxAgeMs = STALE_LOG_MS, now = Date.now() } = {}) {
+    let removed = 0;
+    let entries = [];
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    } catch {
+        return removed;
+    }
+
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !/^\d+-[0-9a-f]{8}$/u.test(entry.name)) {
+            continue;
+        }
+
+        const dir = path.join(root, entry.name);
+        try {
+            if (now - fs.statSync(dir).mtimeMs > maxAgeMs) {
+                fs.rmSync(dir, { recursive: true, force: true });
+                removed += 1;
+            }
+        } catch {
+            // Held open or already gone; the next session tries again.
+        }
+    }
+
+    return removed;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Admission
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * Parse JSON that may carry `//` and `/* *\/` comments, as the permission system's config does.
+ * Comments inside strings are left alone. Returns undefined for a missing file and throws for an
+ * unreadable one, so a caller can tell "nothing configured" from "cannot verify".
+ */
+export function readJsonc(file) {
+    if (!fs.existsSync(file)) {
+        return undefined;
+    }
+
+    const text = fs.readFileSync(file, "utf8");
+    let out = "";
+    let inString = false;
+    for (let index = 0; index < text.length; index += 1) {
+        const char = text[index];
+        const next = text[index + 1];
+        if (inString) {
+            out += char;
+            if (char === "\\") {
+                out += next ?? "";
+                index += 1;
+            } else if (char === '"') {
+                inString = false;
+            }
+        } else if (char === '"') {
+            inString = true;
+            out += char;
+        } else if (char === "/" && next === "/") {
+            while (index < text.length && text[index] !== "\n") {
+                index += 1;
+            }
+
+            out += "\n";
+        } else if (char === "/" && next === "*") {
+            const end = text.indexOf("*/", index + 2);
+            index = end === -1 ? text.length : end + 1;
+        } else {
+            out += char;
+        }
+    }
+
+    const value = JSON.parse(out);
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${file} is not a JSON object`);
+    }
+
+    return value;
+}
+
+/**
+ * The guard's saved state, resolved the way the guard resolves it: its own default is on, the
+ * global file overrides that, and a trusted project's file overrides the global one.
+ *
+ * The guard also keeps a session-only switch in memory, and no other extension can read it. So a
+ * guard switched on with `/jev-guard on` (without `--global`) is invisible here; that is disclosed
+ * rather than guessed at. Saved state is what `/jev-guard on --global`, `setup` and SpecPi's own
+ * installer write.
+ */
+export function guardEnabled({ home = os.homedir(), cwd, trusted = false } = {}) {
+    let enabled = true;
+    let source = "default";
+    const files = [["global", path.join(home, ".pi", "jev-guard.json")]];
+    if (trusted && cwd) {
+        files.push(["project", path.join(cwd, ".pi", "jev-guard.json")]);
+    }
+
+    for (const [scope, file] of files) {
+        let value;
+        try {
+            // Parsed exactly as the guard parses it: a byte-order mark stripped, then strict JSON. A
+            // file it cannot parse is absent to it, so its default -- on -- applies; reading one with
+            // comments more leniently here would see "off" where the guard sees "on".
+            value = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8").replace(/^\uFEFF/u, "")) : undefined;
+        } catch {
+            value = undefined;
+        }
+
+        if (typeof value?.enabled === "boolean") {
+            enabled = value.enabled;
+            source = scope;
+        }
+    }
+
+    return { enabled, source };
+}
+
+export function permissionConfigPaths({ agentDir, cwd }) {
+    return {
+        global: path.join(agentDir, "extensions", "pi-permission-system", "config.json"),
+        project: cwd ? path.join(cwd, ".pi", "extensions", "pi-permission-system", "config.json") : undefined,
+    };
+}
+
+/**
+ * The `shellTools` mapping the permission system will actually apply to this tool: global, then a
+ * trusted project's entry, which replaces it wholesale on a key collision. A trusted repository could
+ * point the mapping at another argument, which would leave `command` ungated, so the effective entry
+ * is what gets checked, not the one SpecPi wrote.
+ */
+export function effectiveShellMapping({ agentDir, cwd, trusted = false }) {
+    const paths = permissionConfigPaths({ agentDir, cwd });
+    let mapping;
+    for (const file of trusted ? [paths.global, paths.project] : [paths.global]) {
+        const config = readJsonc(file);
+        const entry = config?.shellTools?.[BACKGROUND_TOOL];
+        if (entry !== undefined) {
+            mapping = entry;
+        }
+    }
+
+    return mapping;
+}
+
+export function mappingGatesCommand(mapping) {
+    return (
+        Boolean(mapping) &&
+        typeof mapping === "object" &&
+        mapping.commandArgument === SHELL_TOOL_MAPPING.commandArgument &&
+        (mapping.workdirArgument === undefined || typeof mapping.workdirArgument === "string")
+    );
+}
+
+/**
+ * Whether a job may start, and if not, a sentence the model and the human can act on. Every
+ * condition fails closed: an unreadable config or an unknown guard state refuses.
+ */
+export function admission({
+    interactive,
+    commandsKnown = true,
+    guardInstalled,
+    guard,
+    permissionInstalled,
+    mapping,
+    mappingError,
+    running,
+}) {
+    if (interactive !== true) {
+        return {
+            ok: false,
+            reason: "Background jobs need an interactive session to report back to. Run the command with bash.",
+        };
+    }
+
+    if (commandsKnown !== true) {
+        return {
+            ok: false,
+            reason: "Background jobs are off because this Pi cannot list its commands, so SpecPi cannot tell whether the command guard or the permission system is installed. Run the command with bash.",
+        };
+    }
+
+    if (guardInstalled && guard?.enabled !== false) {
+        return {
+            ok: false,
+            reason: "The Jev command guard is on, and it only checks bash, so background jobs are off while it is. Run the command with bash, or switch the guard off with /jev-guard off --global.",
+        };
+    }
+
+    if (permissionInstalled) {
+        if (mappingError) {
+            return {
+                ok: false,
+                reason: `Background jobs are off because the permission system's config could not be read to confirm bash rules apply: ${mappingError}`,
+            };
+        }
+
+        if (!mappingGatesCommand(mapping)) {
+            return {
+                ok: false,
+                reason: 'Background jobs are off because the permission system does not yet apply bash rules to them. Run `specpi update`, or add "shellTools": { "background": { "commandArgument": "command" } } to its global config.',
+            };
+        }
+    }
+
+    if (Number.isInteger(running) && running >= MAX_RUNNING_JOBS) {
+        return {
+            ok: false,
+            reason: `${MAX_RUNNING_JOBS} background jobs are already running. Wait for one to finish, or ask the user to stop one with /jobs stop <id>.`,
+        };
+    }
+
+    return { ok: true };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Jobs
+// ---------------------------------------------------------------------------------------------
+
+function sanitize(text) {
+    // Keep tab, newline and carriage return; drop other control characters and bidi overrides.
+    return String(text).replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f\u202a-\u202e\u2066-\u2069]/gu, "");
+}
+
+export function tailOf(text, { lines = TAIL_LINES, chars = TAIL_CHARS } = {}) {
+    const kept = sanitize(text).replace(/\r\n?/gu, "\n").replace(/\n+$/u, "").split("\n").slice(-lines).join("\n");
+
+    return kept.length > chars ? kept.slice(-chars) : kept;
+}
+
+export function formatDuration(ms) {
+    const seconds = Math.max(0, Math.round(ms / 1000));
+    const hours = Math.floor(seconds / 3600);
+    const minutes = Math.floor((seconds % 3600) / 60);
+    const rest = seconds % 60;
+    if (hours > 0) {
+        return `${hours}h ${minutes}m`;
+    }
+
+    return minutes > 0 ? `${minutes}m ${rest}s` : `${rest}s`;
+}
+
+function preview(command) {
+    const single = sanitize(command).replace(/\s+/gu, " ").trim();
+
+    return single.length > COMMAND_PREVIEW_CHARS ? `${single.slice(0, COMMAND_PREVIEW_CHARS - 1)}…` : single;
+}
+
+/**
+ * Run and track a session's jobs.
+ *
+ * `run(command, cwd, { onData, signal })` resolves `{ exitCode }` when the process ends and rejects
+ * when it is aborted; it is Pi's own local bash runner in production, so shell selection, process
+ * trees and cleanup on Pi's exit match the `bash` tool. `report(job)` is called once per job with its
+ * final state.
+ */
+export function createJobManager({ run, logDir, report, now = () => Date.now() }) {
+    const jobs = new Map();
+    let nextId = 1;
+    let closed = false;
+
+    const running = () => [...jobs.values()].filter((job) => job.state === "running");
+
+    function start({ command, cwd, label }) {
+        if (closed) {
+            throw new Error("This session has ended");
+        }
+
+        fs.mkdirSync(logDir, { recursive: true, mode: 0o700 });
+        const id = String(nextId);
+        nextId += 1;
+        const logPath = path.join(logDir, `job-${id}.log`);
+        const log = fs.openSync(logPath, "w", 0o600);
+        const controller = new AbortController();
+        const job = {
+            id,
+            label: typeof label === "string" && label.trim() ? preview(label).slice(0, 80) : undefined,
+            command: preview(command),
+            cwd,
+            logPath,
+            startedAt: now(),
+            state: "running",
+            exitCode: undefined,
+            endedAt: undefined,
+            bytes: 0,
+            truncated: false,
+            tail: "",
+            controller,
+            stoppedBy: undefined,
+        };
+        jobs.set(id, job);
+
+        const onData = (chunk) => {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+            const text = buffer.toString("utf8");
+            job.tail = (job.tail + text).slice(-TAIL_BUFFER_BYTES);
+            if (job.bytes < MAX_LOG_BYTES) {
+                const room = MAX_LOG_BYTES - job.bytes;
+                const slice = buffer.length > room ? buffer.subarray(0, room) : buffer;
+                try {
+                    fs.writeSync(log, slice);
+                } catch {
+                    // A full disk must not take the job down with it; the tail is still kept.
+                }
+
+                job.bytes += slice.length;
+                if (buffer.length > room && !job.truncated) {
+                    job.truncated = true;
+                    try {
+                        fs.writeSync(log, `\n[SpecPi: log capped at ${MAX_LOG_BYTES} bytes; the job keeps running]\n`);
+                    } catch {
+                        // As above.
+                    }
+                }
+            }
+        };
+
+        const finish = (state, exitCode) => {
+            if (job.state !== "running") {
+                return;
+            }
+
+            job.state = state;
+            job.exitCode = exitCode;
+            job.endedAt = now();
+            try {
+                fs.closeSync(log);
+            } catch {
+                // Already closed.
+            }
+
+            if (!closed) {
+                report(job);
+            }
+        };
+
+        Promise.resolve()
+            .then(() => run(command, cwd, { onData, signal: controller.signal }))
+            .then(
+                (result) => finish("exited", Number.isInteger(result?.exitCode) ? result.exitCode : null),
+                (error) => {
+                    job.error = error?.message;
+                    finish(controller.signal.aborted ? "stopped" : "failed", undefined);
+                },
+            );
+
+        return job;
+    }
+
+    function stop(id, by = "user") {
+        const job = jobs.get(String(id));
+        if (!job || job.state !== "running") {
+            return false;
+        }
+
+        job.stoppedBy = by;
+        job.controller.abort();
+
+        return true;
+    }
+
+    /** End every job and delete this session's logs. Nothing is reported after this. */
+    function close() {
+        closed = true;
+        for (const job of running()) {
+            job.stoppedBy = "session-end";
+            job.controller.abort();
+        }
+
+        try {
+            fs.rmSync(logDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+        } catch {
+            // A log still held open by a dying process is removed with the OS temp cleanup instead.
+        }
+    }
+
+    return {
+        start,
+        stop,
+        close,
+        get: (id) => jobs.get(String(id)),
+        list: () => [...jobs.values()],
+        running: () => running().length,
+    };
+}
+
+/** The follow-up the agent and the human both see when a job ends. */
+export function completionText(job, now = Date.now()) {
+    const name = job.label ? `${job.id} (${job.label})` : job.id;
+    const took = formatDuration((job.endedAt ?? now) - job.startedAt);
+    const outcome =
+        job.state === "exited"
+            ? `finished with exit code ${job.exitCode ?? "unknown"}`
+            : job.state === "stopped"
+              ? `was stopped${job.stoppedBy === "user" ? " by the user" : ""}`
+              : `could not run${job.error ? `: ${sanitize(job.error).slice(0, 200)}` : ""}`;
+    const tail = tailOf(job.tail);
+
+    return [
+        `Background job ${name} ${outcome} after ${took}.`,
+        `Command: ${job.command}`,
+        tail ? `Last lines of output:\n\`\`\`\n${tail.replace(/```/gu, "``\u200b`")}\n\`\`\`` : "It printed nothing.",
+        `Full log (deleted when this session ends): ${job.logPath}${job.truncated ? " (capped)" : ""}`,
+    ].join("\n");
+}
+
+export function startedText(job) {
+    return [
+        `Started background job ${job.id}${job.label ? ` (${job.label})` : ""}. It keeps running while you and the user carry on.`,
+        "When it ends you will receive its exit code and last lines of output as a message, so do not wait for it or poll it.",
+        `Its output is written to ${job.logPath} if you need to look before then. The user can list or stop jobs with /jobs.`,
+    ].join(" ");
+}
+
+export function statusText(jobs) {
+    const count = jobs.filter((job) => job.state === "running").length;
+
+    return count > 0 ? `${count} background job${count === 1 ? "" : "s"} running` : undefined;
+}
+
+export function listText(jobs, now = Date.now()) {
+    if (jobs.length === 0) {
+        return "No background jobs in this session.";
+    }
+
+    return jobs
+        .map((job) => {
+            const took = formatDuration((job.endedAt ?? now) - job.startedAt);
+            const state =
+                job.state === "running"
+                    ? `running ${took}`
+                    : job.state === "exited"
+                      ? `exit ${job.exitCode ?? "?"} after ${took}`
+                      : `${job.state} after ${took}`;
+
+            return `${job.id}  ${state}  ${job.label ?? job.command}`;
+        })
+        .join("\n");
+}

package/extensions/workflow-controls/index.ts

@@ -1,5 +1,10 @@
 import path from "node:path";
-import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+    SettingsManager,
+    createLocalBashOperations,
+    type ExtensionAPI,
+    type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
@@ -14,6 +19,23 @@ import {
     missingTools,
 } from "./capabilities.mjs";
 import { allowCapability, askCapability, autoAllowed, loadAutoAllowed, policyPath } from "./capability-policy.mjs";
+import {
+    BACKGROUND_MESSAGE,
+    BACKGROUND_STATUS,
+    BACKGROUND_TOOL,
+    admission as backgroundAdmissionFor,
+    agentDirectory as backgroundAgentDirectory,
+    completionText,
+    createJobManager,
+    effectiveShellMapping,
+    guardEnabled,
+    listText,
+    pruneStaleLogs,
+    sessionLogDir,
+    startedText,
+    statusText,
+    tailOf,
+} from "./background.mjs";
 import {
     canonicalRoot,
     compareWorktreeSnapshots,
@@ -407,16 +429,104 @@ export default function workflowControls(pi: ExtensionAPI) {
     let webAccessEnabled = loadStartupActivation();
     const applyWebAccess = () => syncToolGroup(pi, WEB_TOOL_NAMES, webAccessEnabled);
 
+    // Background jobs. The admission rules live in background.mjs and are re-checked at every start;
+    // the tool is only offered to a session where a start could succeed, decided before the first
+    // request so the cached prompt prefix is never disturbed.
+    let jobs: ReturnType<typeof createJobManager> | undefined;
+    let jobsContext: ExtensionContext | undefined;
+    const hasCommand = (names: string[] | undefined, name: string) =>
+        names?.some((entry) => entry === name || entry.startsWith(`${name}:`)) === true;
+    const backgroundAdmission = (ctx: ExtensionContext, running = 0) => {
+        let names: string[] | undefined;
+        try {
+            names =
+                typeof pi.getCommands === "function" ? pi.getCommands().map((command: any) => command.name) : undefined;
+        } catch {
+            names = undefined;
+        }
+
+        const trusted = typeof ctx.isProjectTrusted === "function" && ctx.isProjectTrusted() === true;
+        const permissionInstalled = hasCommand(names, "permission-system");
+        let mapping;
+        let mappingError;
+        if (permissionInstalled) {
+            try {
+                mapping = effectiveShellMapping({ agentDir: backgroundAgentDirectory(), cwd: ctx.cwd, trusted });
+            } catch (error) {
+                mappingError = safeMessage(error);
+            }
+        }
+
+        return backgroundAdmissionFor({
+            interactive: ctx.hasUI === true,
+            commandsKnown: names !== undefined,
+            guardInstalled: hasCommand(names, "jev-guard"),
+            guard: guardEnabled({ cwd: ctx.cwd, trusted }),
+            permissionInstalled,
+            mapping,
+            mappingError,
+            running,
+        });
+    };
+
+    const publishJobStatus = () => {
+        try {
+            jobsContext?.ui.setStatus(BACKGROUND_STATUS, statusText(jobs?.list() ?? []));
+        } catch {
+            // A status line is a courtesy; a closed UI must not fail the job.
+        }
+    };
+
+    const reportJob = (job: any) => {
+        publishJobStatus();
+        // A job the user stopped is news for the next prompt, not a reason to start a turn.
+        const stoppedByUser = job.state === "stopped" && job.stoppedBy === "user";
+        pi.sendMessage(
+            {
+                customType: BACKGROUND_MESSAGE,
+                content: completionText(job),
+                display: true,
+                details: { id: job.id, state: job.state, exitCode: job.exitCode, logPath: job.logPath },
+            },
+            stoppedByUser ? { deliverAs: "nextTurn" } : { triggerTurn: true, deliverAs: "followUp" },
+        );
+    };
+
+    // Pi's own local runner, with the session's shell settings, so a job starts exactly as `bash`
+    // would run it and its process tree is cleaned up the same way when Pi exits.
+    const runJob = (command: string, cwd: string, options: any) => {
+        const settings = SettingsManager.create(cwd, backgroundAgentDirectory());
+        const prefix = settings.getShellCommandPrefix();
+
+        return createLocalBashOperations({ shellPath: settings.getShellPath() }).exec(
+            prefix ? `${prefix}\n${command}` : command,
+            cwd,
+            options,
+        );
+    };
+
+    const endJobs = () => {
+        jobs?.close();
+        jobs = undefined;
+        publishJobStatus();
+    };
+
     pi.on("session_start", (_event, ctx) => {
         webAccessEnabled = loadStartupActivation();
         applyWebAccess();
         applyCapabilityRequest(ctx);
+        endJobs();
+        jobsContext = ctx;
+        pruneStaleLogs();
+        syncToolGroup(pi, [BACKGROUND_TOOL], backgroundAdmission(ctx).ok);
         beginRestore(ctx);
     });
 
     pi.on("session_tree", (_event, ctx) => beginRestore(ctx));
 
     pi.on("session_shutdown", (_event, ctx) => {
+        endJobs();
+        jobsContext = undefined;
         sessionGeneration += 1;
         snapshots.clear();
         latestSnapshot = undefined;
@@ -1032,6 +1142,98 @@ export default function workflowControls(pi: ExtensionAPI) {
         },
     });
 
+    pi.registerTool({
+        name: BACKGROUND_TOOL,
+        label: "Background",
+        description:
+            "Start a long-running shell command (an eval, build or server) without blocking the conversation. It returns at once; the exit code and last lines of output arrive later as a message. Use bash for anything quick, or when the next step needs the output. Bash permission rules apply.",
+        parameters: Type.Object(
+            {
+                command: Type.String({
+                    description: "Shell command, run as bash would run it in the session directory",
+                }),
+                label: Type.Optional(Type.String({ maxLength: 80, description: "Short name shown to the user" })),
+            },
+            { additionalProperties: false },
+        ),
+        async execute(_toolCallId, params: any, _signal, _onUpdate, ctx: ExtensionContext) {
+            const verdict = backgroundAdmission(ctx, jobs?.running() ?? 0);
+            if (!verdict.ok) {
+                return {
+                    content: [{ type: "text" as const, text: verdict.reason }],
+                    isError: true,
+                    details: { started: false },
+                };
+            }
+
+            const command = typeof params.command === "string" ? params.command : "";
+            if (command.trim().length === 0) {
+                return {
+                    content: [{ type: "text" as const, text: "Give the command to run." }],
+                    isError: true,
+                    details: { started: false },
+                };
+            }
+
+            jobsContext = ctx;
+            jobs ??= createJobManager({ run: runJob, logDir: sessionLogDir(), report: reportJob });
+            const job = jobs.start({ command, cwd: ctx.cwd, label: params.label });
+            publishJobStatus();
+
+            return {
+                content: [{ type: "text" as const, text: startedText(job) }],
+                details: { started: true, id: job.id, logPath: job.logPath },
+            };
+        },
+    });
+
+    pi.registerCommand("jobs", {
+        description: "List, show or stop this session's background jobs",
+        getArgumentCompletions: (prefix: string) =>
+            ["list", "output", "stop"]
+                .filter((value) => value.startsWith(prefix.trim().toLowerCase()))
+                .map((value) => ({ value, label: value })),
+        handler: async (args, ctx) => {
+            const [actionRaw = "list", target] = args.trim().split(/\s+/u).filter(Boolean);
+            const action = actionRaw.toLowerCase();
+            const all = jobs?.list() ?? [];
+            if (action === "list") {
+                ctx.ui.notify(listText(all), "info");
+
+                return;
+            }
+
+            if (action === "output") {
+                const job = target ? jobs?.get(target) : undefined;
+                if (!job) {
+                    ctx.ui.notify("Usage: /jobs output <id>. Run /jobs to see the ids.", "error");
+
+                    return;
+                }
+
+                ctx.ui.notify(`${tailOf(job.tail) || "(no output yet)"}\n\nFull log: ${job.logPath}`, "info");
+
+                return;
+            }
+
+            if (action === "stop") {
+                const targets =
+                    target === "all" ? all.filter((job) => job.state === "running") : [jobs?.get(target ?? "")];
+                const stopped = targets.filter((job) => job && jobs?.stop(job.id, "user")).map((job) => job!.id);
+                ctx.ui.notify(
+                    stopped.length > 0
+                        ? `Stopping background job${stopped.length === 1 ? "" : "s"} ${stopped.join(", ")}.`
+                        : "No running job matches. Usage: /jobs stop <id|all>.",
+                    stopped.length > 0 ? "info" : "error",
+                );
+
+                return;
+            }
+
+            ctx.ui.notify("Usage: /jobs [list|output <id>|stop <id|all>]", "error");
+        },
+    });
+
     pi.registerCommand("capability", {
         description: "Show withdrawn tool groups, or stop being asked before granting one",
         getArgumentCompletions: (prefix: string) =>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specpi",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Scope control and a human-selected harness improvement loop for Pi",
   "author": "Tanner Middleton",
   "repository": {
@@ -29,6 +29,7 @@
     "scripts/lock.mjs",
     "scripts/packages.mjs",
         "scripts/jev-guard.mjs",
+    "scripts/permission-shell-tools.mjs",
     "templates",
     "extensions",
     "skills",

package/scripts/permission-shell-tools.mjs

@@ -0,0 +1,146 @@
+// Install-time seam for @gotgenes/pi-permission-system: make it gate SpecPi's `background` tool
+// exactly like `bash`.
+//
+// The permission system gates native `bash` through its full command stack -- decomposition,
+// wrapper flooring, path and outside-directory checks, and every `bash:` rule. An extension tool
+// that runs shell commands under another name gets none of that unless the permission system is
+// told the tool is a shell; its documented `shellTools` setting does exactly that. Without it a
+// background job could run a command a `bash` rule denies.
+//
+// So SpecPi records one entry, `shellTools.background = { commandArgument: "command" }`, in the
+// permission system's global config at install and update, and removes it again at uninstall. The
+// extension checks the effective mapping before every start and refuses without it, so a missing
+// or altered entry turns background jobs off; it never leaves them ungated.
+//
+// Merged, never replaced: every other key in the file is the user's and survives unchanged. A file
+// carrying comments is left alone, because rewriting it as plain JSON would delete them; the run
+// says so and names the one line to add by hand.
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const PERMISSION_PACKAGE = "@gotgenes/pi-permission-system";
+export const SHELL_TOOL = "background";
+export const SHELL_TOOL_MAPPING = Object.freeze({ commandArgument: "command" });
+
+export function permissionConfigFile(agentDir) {
+    return path.join(agentDir, "extensions", "pi-permission-system", "config.json");
+}
+
+export function permissionInstalled(agentDir) {
+    try {
+        const manifest = path.join(agentDir, "npm", "node_modules", ...PERMISSION_PACKAGE.split("/"), "package.json");
+
+        return JSON.parse(fs.readFileSync(manifest, "utf8"))?.name === PERMISSION_PACKAGE;
+    } catch {
+        return false;
+    }
+}
+
+function sameMapping(value) {
+    return (
+        Boolean(value) &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        Object.keys(value).length === 1 &&
+        value.commandArgument === SHELL_TOOL_MAPPING.commandArgument
+    );
+}
+
+/** The file as plain JSON, `undefined` when absent, or `{ unreadable }` when it cannot be rewritten. */
+function readConfig(file) {
+    if (!fs.existsSync(file)) {
+        return { config: undefined };
+    }
+
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile()) {
+        return { unreadable: "it is not a regular file" };
+    }
+
+    try {
+        const config = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (!config || typeof config !== "object" || Array.isArray(config)) {
+            return { unreadable: "it is not a JSON object" };
+        }
+
+        return { config };
+    } catch {
+        return {
+            unreadable: "it is not plain JSON (comments are allowed there, but SpecPi will not rewrite them away)",
+        };
+    }
+}
+
+function writeConfig(file, config, mode) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const temporary = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(config, null, 4)}\n`, { mode });
+    fs.renameSync(temporary, file);
+}
+
+export function manualInstruction(agentDir) {
+    return `add "shellTools": { "${SHELL_TOOL}": { "commandArgument": "command" } } to ${permissionConfigFile(agentDir)} so bash rules apply to background jobs`;
+}
+
+/**
+ * Record the mapping. Returns what happened so the installer can report the cases worth reporting:
+ * a file it could not rewrite, or an existing `background` entry pointing somewhere else, which it
+ * replaces because that entry would have left `command` ungated.
+ */
+export function applyShellToolMapping(agentDir) {
+    if (!permissionInstalled(agentDir)) {
+        return { applied: false, reason: "not-installed" };
+    }
+
+    const file = permissionConfigFile(agentDir);
+    const { config, unreadable } = readConfig(file);
+    if (unreadable) {
+        return { applied: false, reason: "unreadable", detail: unreadable };
+    }
+
+    const current = config?.shellTools?.[SHELL_TOOL];
+    if (sameMapping(current)) {
+        return { applied: false, reason: "already-current" };
+    }
+
+    if (
+        config?.shellTools !== undefined &&
+        (typeof config.shellTools !== "object" || Array.isArray(config.shellTools))
+    ) {
+        return { applied: false, reason: "unreadable", detail: "its shellTools value is not an object" };
+    }
+
+    const next = {
+        ...(config ?? {}),
+        shellTools: { ...(config?.shellTools ?? {}), [SHELL_TOOL]: { ...SHELL_TOOL_MAPPING } },
+    };
+    writeConfig(file, next, config ? fs.statSync(file).mode & 0o777 : 0o600);
+
+    return { applied: true, reason: config ? "updated" : "created", replaced: current !== undefined };
+}
+
+/** Remove SpecPi's entry, and the file too when that entry was all it held. */
+export function removeShellToolMapping(agentDir) {
+    const file = permissionConfigFile(agentDir);
+    const { config, unreadable } = readConfig(file);
+    if (unreadable || !config || !sameMapping(config.shellTools?.[SHELL_TOOL])) {
+        return { removed: false };
+    }
+
+    const { [SHELL_TOOL]: _removed, ...shellTools } = config.shellTools;
+    const next = { ...config, shellTools };
+    if (Object.keys(shellTools).length === 0) {
+        delete next.shellTools;
+    }
+
+    if (Object.keys(next).length === 0) {
+        fs.rmSync(file);
+
+        return { removed: true, deletedFile: true };
+    }
+
+    writeConfig(file, next, fs.statSync(file).mode & 0o777);
+
+    return { removed: true, deletedFile: false };
+}

package/scripts/specpi.mjs

@@ -24,6 +24,12 @@ import { runValidator } from "../extensions/tool-wishlist/validators.mjs";
 import { acquireSpecPiLock } from "./lock.mjs";
 import { basePackages, checkBasePackages, installBasePackages, packageChanges, runBrowserQA } from "./packages.mjs";
 import { applyInertConfig as applyGuardConfig, configPath as guardConfigPath } from "./jev-guard.mjs";
+import {
+    applyShellToolMapping,
+    manualInstruction as shellToolInstruction,
+    permissionConfigFile,
+    removeShellToolMapping,
+} from "./permission-shell-tools.mjs";
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const VERSION = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8")).version;
@@ -41,6 +47,7 @@ const resourcePaths = [
     "extensions/workflow-controls/web-access.mjs",
     "extensions/workflow-controls/capabilities.mjs",
     "extensions/workflow-controls/capability-policy.mjs",
+    "extensions/workflow-controls/background.mjs",
     "extensions/tool-wishlist/index.ts",
     "extensions/tool-wishlist/core.mjs",
     "extensions/tool-wishlist/verification.mjs",
@@ -195,6 +202,9 @@ function printPlan(options = {}) {
     }
 
     console.log(`  ${agentsPath} (SpecPi marker block only)\n  ${manifestPath}`);
+    console.log(
+        `  ${permissionConfigFile(agentDir)} (one shellTools entry, only when the permission system is installed, so bash rules apply to background jobs)`,
+    );
     const wanted = new Set(managedFiles().map(([, target]) => target));
     for (const target of Object.keys(manifest?.files || {})) {
         if (!wanted.has(target)) {
@@ -301,6 +311,9 @@ async function mutate(options, operation) {
         const watched = [
             agentsPath,
             manifestPath,
+            // The permission system's global config: one shellTools entry, backed up and rolled back
+            // with everything else (see permission-shell-tools.mjs).
+            permissionConfigFile(agentDir),
             ...files.map(([, target]) => target),
             ...Object.keys(previous?.files || {}),
         ];
@@ -380,6 +393,24 @@ async function mutate(options, operation) {
             };
         }
 
+        // Tell the permission system that the background tool is a shell, so every bash rule applies
+        // to it. Outside the package branch because an existing base keeps its permission system
+        // under --skip-package-install too.
+        if (operation !== "uninstall") {
+            const mapping = applyShellToolMapping(agentDir);
+            if (mapping.reason === "unreadable") {
+                warnings.push(
+                    `Background jobs stay off: could not update the permission system's config because ${mapping.detail}. To enable them, ${shellToolInstruction(agentDir)}.`,
+                );
+            } else if (mapping.replaced) {
+                warnings.push(
+                    `Replaced a "background" shellTools entry in ${permissionConfigFile(agentDir)} that did not gate its command argument; bash rules now apply to background jobs.`,
+                );
+            }
+        } else {
+            removeShellToolMapping(agentDir);
+        }
+
         injectTestFailure("after-settings");
         const records = {};
         const wanted = new Set(files.map(([, target]) => target));

package/templates/AGENTS.md

@@ -1,6 +1,7 @@
 ## SpecPi Working Agreement
 
 - Keep changes small, testable, reversible, and tied to the human's request. Inspect existing code and guidance before editing; avoid adjacent feature accumulation.
+- Take no irreversible step the request did not ask for, such as rewriting Git history, pruning reflogs or objects, force-pushing, or deleting data that cannot be restored. Do the reversible part, then say what remains and offer it.
 - Prefer direct work and existing project tools. Ask concise questions only when material requirements are unclear.
 - Keep replies brief and human-readable: lead with the answer, use plain language, avoid jargon and repetitive progress updates, and include technical detail only when it helps the human decide or act.
 - Write commits and pull requests the same way: a short, clear title and a brief note on what changed, why, and what was tested.