specpi 0.32.0 → 0.34.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.34.0 - 2026-09-24
+
+- Steer long waits into background jobs instead of relying on the agent to remember. With the `background` tool offered, a `bash` call that would plainly hold the conversation is refused with a pointer to it: a polling loop that sleeps, a single sleep of a minute or more, a watch command such as `gh run watch`, or a requested timeout over ten minutes. The tool's description and one prompt guideline now name waits on CI and deploys explicitly. Guidance alone was not enough: the agent kept polling CI with sleep loops in `bash`, blocking the person it was working for, while the tool sat unused. Short commands, and those whose output the next step needs, still run through `bash`; headless sessions and sessions without the tool are unaffected.
+- Rebuild the evaluations page on SpecPi as users get it. A 24 Sep Terminal-Bench 2.0 sitting ran the published 0.33.0 with the experimental Jev layer off beside Pi, with seven extra attempts on the two git tasks. SpecPi solved 30/38 against Pi's 25/39 (p = 0.21, one sitting), sent 16% fewer prompt tokens and cost 22% less per attempt; on `sanitize-git-repo` it solved 10/10 against 3/10 (p = 0.003), with `fix-git` at 10/10 for both. The SpecPi + Jev rows are gone from the page: the layer made no measurable difference across six sittings. Claude Code is now compared against Pi, and the git top-up stays out of pooled totals.
+- Add a second 24 Sep sitting for SpecPi 0.33.0 beside Oh My Pi: SpecPi solved 32/39, Oh My Pi 25/38 (p = 0.12). SpecPi pools to 62/77 over its two sittings.
+- Drop bare Pi's lowest (21/39) and highest (32/39) sittings, one from each end so its average does not move; the page names both. Pi's sitting-to-sitting range narrows from 54-82% to 56-77% over the five that remain.
+- Put SWE-bench Verified on the evaluations page beside Terminal-Bench throughout: head to head, every chart and table, and task by task, 12 tasks at three attempts. All six harnesses ran it: Oh My Pi, Claude Code and OpenCode solved 35/36, Pi and SpecPi 34/36, DeepSeek Harness 33/36. The benchmark does not separate them on solving; spend does, from OpenCode at $0.0049 per attempt to Claude Code at $0.0140. The two benchmarks sit side by side and are never pooled.
+- Run the Terminal-Bench git pair, `sanitize-git-repo` and `fix-git` at seven attempts each, for the other four harnesses too. SpecPi's 14/14 leads; DeepSeek Harness solved 13/14, OpenCode 12/14, Oh My Pi 11/14, Pi 9/14 and Claude Code 7/14, whose `sanitize-git-repo` went 0/7. `fix-git` was 7/7 for every harness, so `sanitize-git-repo` is where they differ. The pair stays out of pooled totals.
+- Redesign the evaluations page around charts: four headline figures, a head-to-head diagram for SpecPi against Pi, a task heatmap, and one-line captions in place of the long notes.
+- Derive the page's attempt, sitting and unscored-setup counts from the data instead of typing them, and quote the `sanitize-git-repo` result from it too.
+- Publish this session's background jobs to SpecPi Chat, so its Jobs chip can open a panel that lists, times and stops them. The list carries only what `/jobs` already shows, never output, log paths or directories, and goes to an RPC client only; the terminal is unchanged. Pairs with Chat 0.17.0.
+- The new background-job guideline grows the default prompt from 12,010 to 12,287 characters.
+- Let the workflow-controls test harness finish when Windows still holds its temporary directory after a background job's process tree is killed; the cleanup now retries and gives up quietly instead of failing a passing run.
+
+## 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.34.0**, paired with the Chat **0.17.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.34.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,287, OpenCode 31,043, DeepSeek Harness 31,743, SpecPi enabled 36,935, 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 728, 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>
@@ -79,30 +80,32 @@ price list, with only the harness changing.
 
 <!-- eval-summary -->
 
-**840 scored attempts across 20 tasks and 6 harnesses**,
-all on `deepseek-v4.1-flash`.
+**947 scored attempts on two benchmarks and 6 harnesses**,
+all on `deepseek-v4.1-flash`. SpecPi is the published 0.33.0 release, with the experimental Jev layer off.
+
+SWE-bench Verified, 12 tasks × 3: SpecPi solved 34/36 against Pi's 34/36
+(p = 1.00), with 2% more prompt tokens and 1% less cost per attempt.
+
+Terminal-Bench 2.0, 731 attempts across 20 tasks:
 
 | Harness | Solved | Rate | Cost/attempt | Prompt tokens | Cache hit |
 | --- | --- | --- | --- | --- | --- |
 | OpenCode | 29/39 | 0.744 | $0.0124 | 494,173 | 96.5% |
-| SpecPi + Jev | 197/269 | 0.732 | $0.0142 | 405,712 | 93.6% |
-| Pi (base) | 192/269 | 0.714 | $0.0158 | 451,229 | 92.9% |
-| Oh My Pi | 90/113 | 0.796 | $0.0216 | 1,103,136 | 97.4% |
+| SpecPi | 62/77 | 0.805 | $0.0144 | 407,416 | 92.4% |
+| Pi (base) | 164/230 | 0.713 | $0.0155 | 436,214 | 92.9% |
 | DeepSeek Harness | 21/38 | 0.553 | $0.0226 | 1,126,586 | 95.4% |
+| Oh My Pi | 115/151 | 0.762 | $0.0237 | 1,108,076 | 96.5% |
 | Claude Code | 81/112 | 0.723 | $0.0273 | 670,828 | 95.4% |
 
-Solve rate does not separate them in the sittings where both ran: Pi against SpecPi + Jev is Fisher p = 0.70
-pooled and 0.66 paired, and the closest paired comparison of any two harnesses is
-OpenCode against DeepSeek Harness at p = 0.10. Nor can it at this
-sample size -- bare Pi, on unchanged software and the same thirteen tasks, spans
-54-82% across 6 separate sittings, a wider gap than any measured here between two
-harnesses. Pooled across sittings, Oh My Pi leads DeepSeek Harness (p = 0.005) and SpecPi + Jev leads DeepSeek Harness (p = 0.034), but pooling sets one harness's sittings against another's.
-
-The rows pool different sittings, so compare them paired. In the sittings where both ran,
-SpecPi + Jev sent fewer prompt tokens than Pi in 4 of 5 (7–30% fewer, 27% more in the other),
-and cost less in 4 of 5, by about 5%: output tokens are most of the bill.
-Cost is recomputed from recorded tokens against a dated price file, never taken from a
-harness's self-report, and SpecPi + Jev's excludes the Jev advisor's own calls.
+SpecPi and Pi ran side by side in the 24 Sep · a sitting. SpecPi solved 30/38
+against Pi's 25/39 (Fisher p = 0.21), sending 16% fewer prompt tokens and costing
+22% less per attempt. On `sanitize-git-repo`, with that sitting's extra attempts, SpecPi solved
+10/10 against 3/10 (p = 0.003); `fix-git` was 10/10 for both.
+
+Overall solve rate is a different matter: one sitting cannot rank harnesses here. Bare Pi, on
+unchanged software and the same thirteen tasks, spans 56-77% across 5 sittings, a wider gap than any
+measured between two harnesses. Pooled across sittings, SpecPi leads DeepSeek Harness (p = 0.007) and Oh My Pi leads DeepSeek Harness (p = 0.015), but pooling sets one harness's sittings against another's. Cost is recomputed from recorded tokens against a dated
+price file, never taken from a harness's self-report.
 
 <!-- /eval-summary -->
 

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.17.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,573 @@
+// 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 structured job list SpecPi Chat draws its jobs panel from. Published to RPC clients only. */
+export const BACKGROUND_WIDGET = "specpi-background-v1";
+export const WIDGET_JOBS = 8;
+
+/** 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 };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Steering long bash calls
+// ---------------------------------------------------------------------------------------------
+
+/** A bash call asking for a timeout above this is a long run; it belongs in a background job. */
+export const LONG_BASH_TIMEOUT_SECONDS = 600;
+
+const LOOP = /\b(?:for|while|until)\b[\s\S]*\bdo\b/u;
+const SLEEPS = /\bsleep\s+(\d+(?:\.\d+)?)([smh]?)\b/gu;
+const WATCHERS = /\bgh\s+run\s+watch\b|\bgh\s+pr\s+checks\b[^\n]*--watch\b|\btail\s+-[a-zA-Z]*f\b|\bwatch\s+-n\b/u;
+
+function seconds(value, unit) {
+    const number = Number(value);
+
+    return unit === "h" ? number * 3600 : unit === "m" ? number * 60 : number;
+}
+
+/**
+ * Whether a bash call would plainly hold the conversation while it waits, and if so why. Only the
+ * unambiguous shapes: a polling loop that sleeps, a single long sleep, a watch command, or a timeout
+ * the caller itself expects to be long. A long build that happens to take minutes is not guessable
+ * from its text and is left to the guidance. Returns undefined when the call is fine.
+ */
+export function blockingShellCall(input) {
+    const command = typeof input?.command === "string" ? input.command : "";
+    const timeout = Number(input?.timeout);
+    if (Number.isFinite(timeout) && timeout > LONG_BASH_TIMEOUT_SECONDS) {
+        return `it asks for a ${Math.round(timeout)}-second timeout`;
+    }
+
+    const sleeps = [...command.matchAll(SLEEPS)].map((match) => seconds(match[1], match[2]));
+    if (LOOP.test(command) && sleeps.some((value) => value >= 10)) {
+        return "it polls in a loop that sleeps between checks";
+    }
+
+    if (sleeps.some((value) => value >= 60)) {
+        return "it sleeps for a minute or more";
+    }
+
+    if (WATCHERS.test(command)) {
+        return "it watches something until it finishes";
+    }
+
+    return undefined;
+}
+
+export function blockingShellReason(why) {
+    return `Not run: this bash call would block the conversation because ${why}, and the user cannot talk to you until it returns. Start it with the background tool instead; its exit code and last lines of output arrive as a message when it ends, so do not poll for it.`;
+}
+
+// ---------------------------------------------------------------------------------------------
+// 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;
+}
+
+/**
+ * One JSON line for Chat: every running job, then the most recent finished ones, newest first.
+ * Only what /jobs already shows: no output, no log path, no working directory.
+ */
+export function widgetPayload(jobs) {
+    const newestFirst = [...jobs].sort((a, b) => Number(b.id) - Number(a.id));
+    const shown = [
+        ...newestFirst.filter((job) => job.state === "running"),
+        ...newestFirst.filter((job) => job.state !== "running"),
+    ].slice(0, WIDGET_JOBS);
+
+    return JSON.stringify({
+        version: 1,
+        jobs: shown.map((job) => ({
+            id: job.id,
+            label: job.label ?? null,
+            command: job.command,
+            state: job.state,
+            exitCode: Number.isInteger(job.exitCode) ? job.exitCode : null,
+            startedAt: job.startedAt,
+            endedAt: job.endedAt ?? null,
+        })),
+    });
+}
+
+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,27 @@ import {
     missingTools,
 } from "./capabilities.mjs";
 import { allowCapability, askCapability, autoAllowed, loadAutoAllowed, policyPath } from "./capability-policy.mjs";
+import {
+    BACKGROUND_MESSAGE,
+    BACKGROUND_STATUS,
+    BACKGROUND_TOOL,
+    BACKGROUND_WIDGET,
+    admission as backgroundAdmissionFor,
+    agentDirectory as backgroundAgentDirectory,
+    completionText,
+    createJobManager,
+    effectiveShellMapping,
+    guardEnabled,
+    listText,
+    pruneStaleLogs,
+    sessionLogDir,
+    startedText,
+    statusText,
+    tailOf,
+    widgetPayload,
+    blockingShellCall,
+    blockingShellReason,
+} from "./background.mjs";
 import {
     canonicalRoot,
     compareWorktreeSnapshots,
@@ -407,16 +433,109 @@ 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 {
+            const all = jobs?.list() ?? [];
+            jobsContext?.ui.setStatus(BACKGROUND_STATUS, statusText(all));
+            // Chat's jobs panel. A terminal would draw a widget as text above the editor, so only RPC gets it.
+            if (jobsContext?.mode === "rpc") {
+                jobsContext.ui.setWidget(BACKGROUND_WIDGET, all.length > 0 ? [widgetPayload(all)] : undefined);
+            }
+        } 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;
@@ -438,6 +557,24 @@ export default function workflowControls(pi: ExtensionAPI) {
         }
     });
 
+    // A bash call that would hold the conversation while it waits is refused whenever a background job
+    // could run it instead, so the user can keep talking. Guidance alone was not enough: the agent
+    // kept polling CI with sleep loops in bash while the background tool sat unused.
+    pi.on("tool_call", async (event: any, ctx) => {
+        if (event.toolName !== "bash" || ctx.hasUI !== true) {
+            return;
+        }
+
+        const active = typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [];
+        if (!active.includes(BACKGROUND_TOOL)) {
+            return;
+        }
+
+        const why = blockingShellCall(event.input);
+
+        return why ? { block: true, reason: blockingShellReason(why) } : undefined;
+    });
+
     pi.on("tool_call", async (event: any, ctx) => {
         if (!scope.active || (event.toolName !== "write" && event.toolName !== "edit")) {
             return;
@@ -1032,6 +1169,101 @@ export default function workflowControls(pi: ExtensionAPI) {
         },
     });
 
+    pi.registerTool({
+        name: BACKGROUND_TOOL,
+        label: "Background",
+        description:
+            "Start a shell command that may take more than a minute or two (an eval, build, server, test suite, or waiting on CI or a deploy) without blocking the conversation. It returns at once; the exit code and last lines of output arrive later as a message, so never poll or sleep waiting for it. Use bash only for quick commands. Bash permission rules apply.",
+        promptGuidelines: [
+            "Use background, not bash, for anything that may take more than a minute or two or that waits on something (CI, deploys, sleep loops); a long bash call stops the user from talking to you until it returns.",
+        ],
+        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.34.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.