pi-better-sandbox 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,212 @@
+# pi-better-sandbox
+
+A default-on write sandbox for Pi's foreground tools.
+
+It is installed by default with [`pi-better-harness`](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-harness#readme), and can be installed on its own:
+
+```sh
+pi install npm:pi-better-sandbox
+```
+
+Either way you keep starting Pi the way you always have — `pi`. There is
+no launcher, no wrapper command, and nothing to configure. From the first
+session start, Pi's built-in `bash` tool and the `!` / `!!` commands you type
+yourself run inside an OS sandbox that lets them write only under the directory
+you launched Pi from, and the built-in `write` and `edit` tools are held to the
+same policy.
+
+```
+Read:       every filesystem path
+Write:      the canonical launch directory and everything under it
+Exceptions: .git/hooks, .env, .env.local
+Network:    unchanged
+```
+
+For shell commands the denial is done by the kernel, not by inspecting command
+text: macOS uses Seatbelt (`sandbox-exec`) and Linux uses Bubblewrap (`bwrap`).
+A crafted command cannot talk its way past it, because the write syscall itself
+is refused.
+
+`write` and `edit` never start a child process — they change files inside Pi's
+own process — so there is no child to wrap. They are confined by a containment
+check on the canonical target instead, run inside Pi's own file-mutation queue,
+immediately before the filesystem call it guards. A refused mutation leaves
+nothing behind on disk.
+
+## What is confined, and what is not
+
+**Reads and network access are never restricted.** Every path on the filesystem
+stays readable and network behaviour is exactly what it was. This sandbox limits
+writes, and nothing else.
+
+Writes are confined for the integrated first-party execution paths, and only
+those:
+
+- Pi's built-in `bash` tool.
+- User-entered `!` and `!!` commands.
+- Pi's built-in `write` and `edit` tools.
+- Local [`pi-better-background-tasks`](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-background-tasks#readme)
+  spawns and watches, which capture this policy at launch.
+- [`pi-better-subagents`](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-subagents#readme)
+  children, through the same shared mechanism.
+
+**Not** confined:
+
+- Pi's own process.
+- `pi.exec` calls made by extensions.
+- Unrelated third-party extension code.
+- Another first-party surface's control plane. Each surface denies its own —
+  the files naming what it will run next — but not every other surface's, so
+  confinement is per surface rather than global.
+
+This is a tool-execution sandbox. It limits accidental damage from commands the
+model or you run through Pi's shell; it is not a boundary around Pi itself.
+
+Overriding `write` and `edit` changes nothing you can see: the parameter
+schemas, prompt guidance, call rendering, write previews, edit diffs, result
+details, mutation queueing, and cancellation are Pi's own. Only the filesystem
+operations underneath them are replaced.
+
+## Commands
+
+```text
+/sandbox                     show the effective status
+/sandbox on                  re-arm protection for operations started from now on
+/sandbox off                 turn protection off for this session (interactive confirmation)
+/sandbox deny list           show the write-denied paths
+/sandbox deny add <path>     stop allowing writes to a path
+/sandbox deny remove <path>  allow writes to a path again
+/sandbox deny reset          drop your changes and restore the packaged defaults
+/sandbox rules               open the write-denied paths editor
+```
+
+The footer shows `sandbox · on · <project>` while protection is active, and a
+prominent `sandbox · OFF`, `sandbox · UNAVAILABLE`, or `sandbox · FAILED`
+otherwise. Both surfaces report what the runtime actually resolved — which
+backend, which executable — never what was merely configured.
+
+`/sandbox off` needs an interactive confirmation and is refused outright when
+there is no interactive UI. There is no tool for changing sandbox state or its
+rules, so the model can neither disable its own confinement nor edit the paths
+it is confined away from.
+
+## Write-denied paths
+
+Three paths are denied out of the box — `.git/hooks`, `.env`, and `.env.local`,
+relative to whichever project you are in. They live in the package's source, so
+installing writes no settings file anywhere.
+
+Rules are paths, not patterns. Write one of three ways:
+
+| You type            | It means                                            |
+| ------------------- | --------------------------------------------------- |
+| `build/artifacts`   | that path inside **every** project you open          |
+| `~/.aws`            | that path under your home directory                  |
+| `/etc/hosts`        | exactly that path                                     |
+
+A relative rule is stored as a template and resolved against each project, which
+is why one global rule set is enough — there is no per-project database. Lists
+and the editor always show the canonical absolute path a rule currently resolves
+to. A directory denies its whole subtree; a file denies that exact file, whether
+or not it exists yet.
+
+`/sandbox rules` opens a compact keyboard-driven editor over the same rules:
+arrow keys to move, enter to remove the highlighted rule, or pick *Add* to type
+a new one and *Restore the packaged defaults* to start over. The slash commands
+and the editor are two front ends over one validation and persistence module, so
+they cannot disagree.
+
+Changes take effect for shell commands and file mutations started after them.
+A command already running keeps the rules it launched with.
+
+### Where your rules live
+
+Your changes are written to `~/.pi/agent/extensions/pi-better-sandbox.json`
+(under `$PI_CODING_AGENT_DIR` when you set one):
+
+```json
+{
+  "version": 1,
+  "denyWrite": [".env", ".env.local", ".git/hooks", "build/artifacts"]
+}
+```
+
+That file appears the first time you add or remove a rule, never at install
+time. `/sandbox deny reset` deletes it and puts the defaults shipped by the
+installed package version back in force — so an upgrade that changes the
+defaults is picked up by a reset rather than being masked by a stale copy.
+
+If the file cannot be read, the packaged defaults stay in force, the problem is
+reported, and rule changes are refused until you fix the file or reset it —
+a typo is never quietly turned into a lost rule set.
+
+### What is refused, and why
+
+- **Empty entries and patterns** (`*.pem`, `src/**/x`) — rules are concrete
+  paths; a pattern would silently match nothing.
+- **Duplicates**, however they are spelled: `.env`, `./.env`, the absolute path,
+  or a symlink pointing at the same file all resolve to one canonical path.
+- **Overlaps**, in both directions. A path already inside a denied directory
+  would change nothing; a directory that would swallow a narrower rule names
+  that rule so you can remove it deliberately instead of losing it silently.
+- **A rule that contains the project root** — `.`, `..`, `/`, or `~` when your
+  project lives under home. Denying it would make every write in the project
+  fail. `/sandbox off` is the thing you actually want there.
+
+A global rule that turns out to contain the root of a *different* project stays
+in your rule set but is held out in that project, with a message saying so.
+
+## Lifecycle
+
+The sandbox is enabled again at every session start: startup, new session,
+resume, fork, and reload. An off state is never written anywhere, so it cannot
+outlive the session you switched it off in.
+
+Toggles apply to operations launched after the change. A command already running
+keeps the policy it launched with.
+
+## Fail-closed behaviour
+
+While the sandbox is enabled and a backend cannot be applied, protected commands
+and file mutations are **blocked** rather than run unprotected:
+
+- No backend on this platform (`unavailable`).
+- A launch directory too broad to confine — `/` or your home directory
+  (`failed`). Relaunch Pi from the directory you are actually working in, or
+  turn the sandbox off on purpose.
+- A backend that was selected but failed to start. It is never retried directly.
+
+## Paths, symlinks and denied files
+
+The launch directory is canonicalized at session start, so reaching a project
+through a symlink does not widen what is writable. Denied entries are
+canonicalized the same way: a directory denies its whole subtree, a file denies
+that exact file, and an alias pointing at a denied file is denied too.
+
+## Platform support
+
+| Platform | Backend                     | Requirement                  |
+| -------- | --------------------------- | ---------------------------- |
+| macOS    | Seatbelt (`sandbox-exec`)   | ships with the OS            |
+| Linux    | Bubblewrap (`bwrap`)        | install `bubblewrap`         |
+| Other    | none                        | protected commands are blocked |
+
+## For other extensions
+
+The effective policy is published as a frozen snapshot on Pi's extension event
+bus. It carries policy and status only — never a way to run anything.
+
+```ts
+import {
+  FOREGROUND_SANDBOX_POLICY_CHANNEL,
+  FOREGROUND_SANDBOX_POLICY_REQUEST_CHANNEL,
+  type ForegroundSandboxPolicyEvent,
+} from "pi-better-sandbox";
+
+pi.events.on(FOREGROUND_SANDBOX_POLICY_CHANNEL, (policy) => {
+  // Snapshot it at launch time; a running operation keeps its launch policy.
+});
+
+// Loaded late and missed the last publication? Ask for the current one.
+pi.events.emit(FOREGROUND_SANDBOX_POLICY_REQUEST_CHANNEL, undefined);
+```

package/commands.ts

@@ -0,0 +1,214 @@
+/**
+ * The `/sandbox` slash command.
+ *
+ * Sandbox state is human-only by construction: this is a slash command, and the
+ * package registers no tool that can read or change it, so the model has no way
+ * to disable its own confinement or edit its own deny rules. Turning protection
+ * off additionally requires an interactive confirmation and is refused outright
+ * without an interactive UI.
+ *
+ * The `deny` subcommands and the `rules` page are two front ends over one
+ * `DenyRuleManager`; this module only parses arguments and renders outcomes.
+ */
+
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+import {
+    DenyRuleError,
+    type DenyRuleManager,
+    type DenyRuleReport,
+    formatDenyRuleReport,
+} from "./deny-rules.ts";
+import { openSandboxRulesPage } from "./rules-page.ts";
+import { formatSandboxReport } from "./status.ts";
+import type { ForegroundSandboxController, ForegroundSandboxStatus } from "./state.ts";
+
+export const SANDBOX_COMMAND_NAME = "sandbox";
+
+export const SANDBOX_COMMAND_DESCRIPTION =
+    "Show the foreground write sandbox, turn it on or off for this session, or manage write-denied paths";
+
+const USAGE = [
+    "Usage:",
+    "  /sandbox",
+    "  /sandbox on",
+    "  /sandbox off",
+    "  /sandbox deny list",
+    "  /sandbox deny add <path>",
+    "  /sandbox deny remove <path>",
+    "  /sandbox deny reset",
+    "  /sandbox rules",
+].join("\n");
+
+const DENY_USAGE = [
+    "Usage:",
+    "  /sandbox deny list",
+    "  /sandbox deny add <path>",
+    "  /sandbox deny remove <path>",
+    "  /sandbox deny reset",
+].join("\n");
+
+const DISABLE_TITLE = "Disable the foreground write sandbox?";
+
+const DISABLE_MESSAGE = [
+    "The built-in bash, write, and edit tools and user-entered ! / !! commands",
+    "will run with normal host write access for the rest of this session. New,",
+    "resumed, forked, and reloaded sessions start protected again.",
+].join("\n");
+
+const NO_UI_REJECTION =
+    "/sandbox off needs an interactive confirmation and there is no interactive UI here, so the sandbox stays on.";
+
+const RESET_TITLE = "Restore the packaged write-deny defaults?";
+
+export type SandboxCommandDeps = {
+    controller: ForegroundSandboxController;
+    /** The one validation and persistence path for write-deny rules. */
+    denyRules: DenyRuleManager;
+    /** Called after any state change so the footer and consumers stay truthful. */
+    onStateChange: (status: ForegroundSandboxStatus) => void;
+};
+
+/** Build the `/sandbox` handler. Exported so its behaviour is directly testable. */
+export function createSandboxCommandHandler({
+    controller,
+    denyRules,
+    onStateChange,
+}: SandboxCommandDeps) {
+    return async function handleSandboxCommand(
+        args: string,
+        ctx: ExtensionCommandContext,
+    ): Promise<void> {
+        // Only the verbs are case-folded. Everything after them is a path, and
+        // paths are case-sensitive on the filesystems this package supports.
+        const trimmed = args.trim();
+        const [verb = "", ...tail] = trimmed.split(/\s+/);
+        const subcommand = verb.toLowerCase();
+        const rest = trimmed.slice(verb.length).trim();
+
+        if (subcommand === "") {
+            ctx.ui.notify(formatSandboxReport(controller.status()), "info");
+            return;
+        }
+
+        if (subcommand === "on") {
+            const status = controller.enable();
+            onStateChange(status);
+            ctx.ui.notify(
+                status.state === "enabled"
+                    ? `Foreground sandbox on. ${status.reason}`
+                    : `Foreground sandbox re-armed but not active: ${status.reason}`,
+                status.state === "enabled" ? "info" : "warning",
+            );
+            return;
+        }
+
+        if (subcommand === "off") {
+            if (!ctx.hasUI) {
+                ctx.ui.notify(NO_UI_REJECTION, "error");
+                return;
+            }
+            const confirmed = await ctx.ui.confirm(DISABLE_TITLE, DISABLE_MESSAGE);
+            if (!confirmed) {
+                ctx.ui.notify("Foreground sandbox left on.", "info");
+                return;
+            }
+            const status = controller.disable();
+            onStateChange(status);
+            ctx.ui.notify(
+                "Foreground sandbox OFF for this session. Shell commands can now write anywhere.",
+                "warning",
+            );
+            return;
+        }
+
+        if (subcommand === "deny") {
+            await handleDeny(denyRules, ctx, tail[0]?.toLowerCase() ?? "list", rest);
+            return;
+        }
+
+        if (subcommand === "rules") {
+            await openSandboxRulesPage(denyRules, ctx);
+            return;
+        }
+
+        ctx.ui.notify(`Unknown /sandbox subcommand: ${subcommand}\n\n${USAGE}`, "error");
+    };
+}
+
+async function handleDeny(
+    denyRules: DenyRuleManager,
+    ctx: ExtensionCommandContext,
+    action: string,
+    rest: string,
+): Promise<void> {
+    // `rest` still carries the action word; the path is whatever follows it,
+    // verbatim, so a path containing spaces survives intact.
+    const argument = rest.slice(action.length).trim();
+
+    if (action === "list") {
+        ctx.ui.notify(formatDenyRuleReport(denyRules.report()), "info");
+        return;
+    }
+
+    if (action === "add" || action === "remove") {
+        if (argument === "") {
+            ctx.ui.notify(`/sandbox deny ${action} needs a path.\n\n${DENY_USAGE}`, "error");
+            return;
+        }
+        announce(ctx, () =>
+            action === "add" ? denyRules.add(argument) : denyRules.remove(argument),
+        );
+        return;
+    }
+
+    if (action === "reset") {
+        // Resetting discards rules the human wrote, so it is confirmed wherever
+        // there is someone to confirm it.
+        if (ctx.hasUI && denyRules.hasOverride()) {
+            const confirmed = await ctx.ui.confirm(
+                RESET_TITLE,
+                "Every write-deny rule you added or removed will be forgotten.",
+            );
+            if (!confirmed) {
+                ctx.ui.notify("Your write-deny rules were left as they are.", "info");
+                return;
+            }
+        }
+        announce(ctx, () => denyRules.reset());
+        return;
+    }
+
+    ctx.ui.notify(`Unknown /sandbox deny action: ${action}\n\n${DENY_USAGE}`, "error");
+}
+
+/** Run one rule change and show either the new rule set or why it was refused. */
+function announce(ctx: ExtensionCommandContext, change: () => DenyRuleReport): void {
+    try {
+        ctx.ui.notify(formatDenyRuleReport(change()), "info");
+    } catch (error) {
+        if (error instanceof DenyRuleError) {
+            ctx.ui.notify(error.message, "error");
+            return;
+        }
+        throw error;
+    }
+}
+
+const SUBCOMMANDS = ["on", "off", "deny", "rules"] as const;
+const DENY_ACTIONS = ["list", "add", "remove", "reset"] as const;
+
+/** Argument completions for `/sandbox`, including the `deny` actions. */
+export function sandboxArgumentCompletions(argumentPrefix: string) {
+    const prefix = argumentPrefix.trimStart().toLowerCase();
+    const denyPrefix = /^deny(\s|$)/.test(prefix) ? prefix.replace(/^deny\s*/, "") : undefined;
+
+    const values =
+        denyPrefix === undefined
+            ? SUBCOMMANDS.filter((value) => value.startsWith(prefix))
+            : DENY_ACTIONS.filter((value) => value.startsWith(denyPrefix)).map(
+                  (value) => `deny ${value}`,
+              );
+
+    return values.map((value) => ({ value, label: value }));
+}