universal-opencode-sandbox 0.1.0 → 0.3.0

package/README.md

@@ -26,9 +26,11 @@ Requires OpenCode 2.x (the `@opencode/plugin` 2.x contract).
 ```
 
 The sandbox is on by default once the plugin is installed, in its strictest useful
-mode: the workspace is writable (and the system temp directory), everything else is
-read-only, the network is denied, and a command the sandbox cannot run is blocked
-rather than run unconfined.
+mode: the workspace and the system temp directory are writable, everything else is
+write-denied, the network is denied, credential stores are unreadable (see the
+default list below), and a command the sandbox cannot run is blocked rather than
+run unconfined. No configuration is required for that; the config file below only
+changes it.
 
 ## Configure
 
@@ -45,11 +47,13 @@ on purpose: they can be set from a repository's own config.
   // "permissive" runs it unsandboxed with a warning.
   "mode": "enforce",
   "filesystem": {
-    // "read-only" (default) denies every write; "workspace-write" allows writes to
-    // the workspace, the temp directory, and writable_roots.
+    // "workspace-write" (default) allows writes to the workspace, the temp
+    // directory, and writable_roots; "read-only" denies every write.
     "mode": "workspace-write",
     "writable_roots": [],
-    // Paths the sandboxed command can neither read nor write, e.g. credentials.
+    // Paths the sandboxed command can neither read nor write. Unset (default):
+    // the standard credential list below. Setting the list replaces it: the
+    // entries are then yours, and per-project overrides only add to them.
     "denied_paths": ["~/.ssh", "~/.aws"]
   },
   // "deny" (default) blocks all network access for sandboxed commands.
@@ -57,6 +61,14 @@ on purpose: they can be set from a repository's own config.
   // What happens when a tool call asks to skip the sandbox (shell input
   // "sandbox: false"): "deny" (default) blocks it, "allow" runs it unsandboxed.
   "unsandboxed": "deny",
+  // Also sandbox user "!" commands and plugin shells, protecting the user from
+  // social engineering ("run this for me") and accidental damage. Default: false.
+  "sandbox_user_commands": true,
+  // Tool names the agent may not call at all; "*" is a wildcard. Use this to close
+  // escape routes outside the sandbox, such as a host app's unsandboxed terminal
+  // tools (an agent can otherwise spawn or drive a raw shell there). Unlike
+  // opencode's own permission rules, a repository config cannot re-allow these.
+  "blocked_tools": ["paseo_create_terminal", "paseo_send_terminal_keys"],
   // Per-project overrides, keyed by the workspace's absolute path. Every field is
   // optional and can only make the policy stricter, never looser.
   "projects": {
@@ -67,6 +79,28 @@ on purpose: they can be set from a repository's own config.
 
 `UNIVERSAL_SANDBOX_CONFIG` (a JSON string) tightens the same fields per invocation.
 
+### Default denied paths
+
+Without a `denied_paths` entry, the sandbox denies reading and writing these
+credential stores. A stolen long-lived credential cannot be undone by a restart,
+so reading is denied even though the network usually is too: a secret read once
+can be copied into the workspace and walk out through a commit.
+
+- `~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.netrc`, `~/.kube`, `~/.azure` - identity
+  directories: keys, cloud credentials, cluster tokens
+- `~/.config/gcloud` - GCP credentials and service-account keys
+- `~/.npmrc`, `~/.pypirc`, `~/.cargo/credentials`, `~/.docker/config.json` -
+  registry tokens of the major package managers and Docker
+- `~/.config/gh/hosts.yml` and `~/Library/Application Support/gh/hosts.yml` -
+  the GitHub CLI token (both config-directory conventions)
+- `~/.local/share/opencode/auth.json` - OpenCode provider API keys
+- `~/.claude/.credentials.json`, `~/.codex/auth.json` - credentials of the
+  other agent CLIs
+
+Setting `denied_paths` replaces this list. On Linux only paths that exist are
+enforced (an upstream deny bug would otherwise create stray directories,
+microsoft/mxc#1780); on macOS not-yet-existing paths are protected too.
+
 ## What is enforced
 
 - **Filesystem**: in `workspace-write` mode, writes are allowed in the workspace and
@@ -86,6 +120,53 @@ on purpose: they can be set from a repository's own config.
   Linux), or a missing executor blocks the command in `enforce` mode instead of
   running it unconfined. `mode: "permissive"` trades that guarantee for convenience.
 
+## Sandboxed terminal
+
+The package also ships `sandboxed-shell`, a small CLI that starts an **interactive
+shell inside the same sandbox**: the same filesystem and network policy as the agent
+commands, applied to everything you (or anything else) type into it.
+
+```bash
+# Safe terminal: interactive zsh under Seatbelt/bubblewrap/ProcessContainer
+sandboxed-shell --workspace /path/to/project
+```
+
+This gives you two terminal types next to each other:
+
+| Terminal type | How | What runs inside |
+|---|---|---|
+| Safe terminal | `sandboxed-shell` (or `exec` it in an existing terminal) | The MXC sandbox policy from your config |
+| Admin terminal | your normal shell | Unconfined, for server restarts and admin work |
+
+The safe terminal fails closed: if the sandbox cannot run, no shell is started, and
+exiting it ends the session with no unsandboxed fallback. It inherits your
+environment (PATH, TERM, HOME) so it behaves like a normal terminal; secrets in the
+environment stay put because egress is denied and the filesystem policy still applies.
+
+**Locking it down for other users**: the two-type design is exactly what lets you
+disable the admin terminal for regular users. The plugin confines opencode agents;
+terminals spawned by a host app (for example Paseo) are confined by having the host
+start them through `sandboxed-shell` instead of a plain shell. Whoever controls
+terminal creation controls the choice: point every terminal at the wrapper and nobody
+gets an unsandboxed one. Inside opencode itself, two layers close the agent's route
+to a host app's terminals: `blocked_tools` denies the terminal tools at every tool
+call (a repository config cannot re-allow it), and opencode's own `permissions` rules
+hide them from the agent's tool catalog entirely:
+
+```jsonc
+// opencode.jsonc, next to this plugin in your config
+{
+  "permissions": [
+    { "action": "paseo_create_terminal", "resource": "*", "effect": "deny" },
+    { "action": "paseo_send_terminal_keys", "resource": "*", "effect": "deny" },
+    { "action": "paseo_capture_terminal", "resource": "*", "effect": "deny" }
+  ]
+}
+```
+
+Use the `permissions` array: the older `permission` object is deprecated and, on
+current releases, silently ignored.
+
 ## Known limitations
 
 - With the sandbox enabled, OpenCode's per-command shell permission rules see the
@@ -106,7 +187,10 @@ and Windows 11 (ProcessContainer): output and exit codes stream through, writes
 the workspace succeed, writes outside are denied, protected config files cannot be
 planted, and network egress is blocked (except the documented Windows gap). Also
 verified end to end inside a real OpenCode 2.2.7 session: an agent's shell command
-writes inside the workspace and is denied outside it.
+writes inside the workspace and is denied outside it. The `sandboxed-shell` terminal
+was verified interactively on macOS: commands run with full environment, writes inside
+the workspace succeed, writes outside are denied, network egress is blocked, and
+`denied_paths` (for example `~/.ssh`) cannot be read.
 
 ## License
 

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { spawn } from "node:child_process";
+import fs3 from "node:fs";
+import os3 from "node:os";
+import path3 from "node:path";
+
+// src/policy.ts
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+var realHome = () => os.userInfo().homedir;
+var defaultDeniedPaths = [
+  "~/.ssh",
+  "~/.aws",
+  "~/.gnupg",
+  "~/.netrc",
+  "~/.kube",
+  "~/.azure",
+  "~/.config/gcloud",
+  "~/.npmrc",
+  "~/.pypirc",
+  "~/.cargo/credentials",
+  "~/.docker/config.json",
+  "~/.config/gh/hosts.yml",
+  "~/Library/Application Support/gh/hosts.yml",
+  "~/.local/share/opencode/auth.json",
+  "~/.claude/.credentials.json",
+  "~/.codex/auth.json"
+];
+var configDirectory = () => path.join(process.env.XDG_CONFIG_HOME ?? path.join(realHome(), ".config"), "universal-opencode-sandbox");
+var configPath = () => path.join(configDirectory(), "config.json");
+function resolvePolicy(workspace, environment = process.env, globalFile = configPath()) {
+  let merged = { writableRoots: [], deniedPaths: [], blockedTools: [] };
+  const global = readConfig(globalFile);
+  if (global)
+    merged = tighten(merged, global);
+  const project = global?.projects?.[workspace];
+  if (project)
+    merged = tighten(merged, project);
+  const injected = environment.UNIVERSAL_SANDBOX_CONFIG;
+  if (injected) {
+    try {
+      merged = tighten(merged, JSON.parse(injected));
+    } catch {}
+  }
+  return {
+    enabled: merged.enabled ?? true,
+    mode: merged.mode ?? "enforce",
+    filesystem: {
+      mode: merged.filesystemMode ?? "workspace-write",
+      writableRoots: [...new Set(merged.writableRoots)],
+      deniedPaths: merged.deniedPathsExplicit ? [...new Set(merged.deniedPaths)] : defaultDeniedPaths
+    },
+    network: merged.network ?? "deny",
+    unsandboxed: merged.unsandboxed ?? "deny",
+    userCommands: merged.userCommands ?? false,
+    blockedTools: [...new Set(merged.blockedTools)]
+  };
+}
+function readConfig(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return;
+  }
+}
+function tighten(merged, raw) {
+  if (Array.isArray(raw.filesystem?.writable_roots)) {
+    for (const root of raw.filesystem.writable_roots)
+      if (typeof root === "string")
+        merged.writableRoots.push(root);
+  }
+  if (Array.isArray(raw.filesystem?.denied_paths)) {
+    const items = raw.filesystem.denied_paths.filter((item) => typeof item === "string");
+    merged.deniedPaths = merged.deniedPathsExplicit ? [...merged.deniedPaths, ...items] : items;
+    merged.deniedPathsExplicit = true;
+  }
+  if (Array.isArray(raw.blocked_tools)) {
+    for (const item of raw.blocked_tools)
+      if (typeof item === "string")
+        merged.blockedTools.push(item);
+  }
+  return {
+    enabled: raw.enabled === undefined ? merged.enabled : raw.enabled === false ? false : merged.enabled === false ? false : true,
+    mode: strictest(merged.mode, raw.mode, "enforce", "permissive"),
+    filesystemMode: strictest(merged.filesystemMode, raw.filesystem?.mode, "read-only", "workspace-write"),
+    network: strictest(merged.network, raw.network, "deny", "allow"),
+    unsandboxed: strictest(merged.unsandboxed, raw.unsandboxed, "deny", "allow"),
+    userCommands: raw.sandbox_user_commands === true || merged.userCommands === true,
+    blockedTools: merged.blockedTools,
+    writableRoots: merged.writableRoots,
+    deniedPaths: merged.deniedPaths,
+    deniedPathsExplicit: merged.deniedPathsExplicit
+  };
+}
+function strictest(current, incoming, strict, loose) {
+  if (current === strict || incoming === strict)
+    return strict;
+  if (incoming === loose)
+    return loose;
+  return current;
+}
+function expandHome(item, home = os.homedir()) {
+  return item === "~" ? home : item.startsWith("~/") ? path.join(home, item.slice(2)) : item;
+}
+function toolBlocked(tool, patterns) {
+  return patterns.some((pattern) => {
+    const source = pattern.split("*").map((part) => part.replace(/[|\\{}()[\]^$+?.]/g, "\\$&")).join(".*");
+    return new RegExp(`^${source}$`).test(tool);
+  });
+}
+
+// src/wire.ts
+import { randomBytes } from "node:crypto";
+import fs2 from "node:fs";
+import os2 from "node:os";
+import path2 from "node:path";
+import { fileURLToPath } from "node:url";
+var PROTECTED = ["opencode.json", "opencode.jsonc", ".opencode", ".claude", ".agents"];
+function wireRequest(input, platform = process.platform) {
+  const workspace = real(input.workspace);
+  const cwd = real(input.cwd);
+  const writable = [
+    workspace,
+    ...(input.tmpRoots ?? [os2.tmpdir()]).map(real),
+    ...input.policy.filesystem.writableRoots.map((root) => real(expandHome(root)))
+  ];
+  const protectedPaths = PROTECTED.map((item) => path2.join(workspace, item));
+  const deniedPaths = input.policy.filesystem.deniedPaths.map((item) => real(expandHome(item)));
+  let filesystem;
+  if (input.policy.filesystem.mode !== "workspace-write") {
+    filesystem = { readwritePaths: [], readonlyPaths: [input.workspace], deniedPaths: existing(deniedPaths, platform) };
+  } else if (platform === "win32") {
+    filesystem = { readwritePaths: writable, readonlyPaths: [], deniedPaths: [...protectedPaths, ...deniedPaths] };
+  } else if (platform === "linux") {
+    filesystem = {
+      readwritePaths: writable,
+      readonlyPaths: protectedPaths.filter((item) => exists(item)),
+      deniedPaths: existing(deniedPaths, platform)
+    };
+  } else {
+    filesystem = { readwritePaths: writable, readonlyPaths: protectedPaths, deniedPaths };
+  }
+  const request = {
+    version: "1.0.0",
+    containerId: randomBytes(16).toString("hex"),
+    containment: platform === "darwin" ? "seatbelt" : platform === "win32" ? "processcontainer" : "bubblewrap",
+    ...platform === "darwin" ? { seatbelt: {} } : {},
+    ...platform === "win32" ? {
+      processContainer: {
+        capabilities: input.policy.network === "allow" ? ["internetClient"] : [],
+        ui: { isolation: "container", desktopSystemControl: false, systemSettings: "none", ime: false },
+        filesystem: undefined,
+        network: undefined
+      }
+    } : {},
+    lifecycle: { destroyOnExit: true, preservePolicy: false },
+    process: {
+      commandLine: input.command,
+      timeout: input.timeout,
+      cwd,
+      inheritDefaultEnv: true,
+      ...input.environment === undefined ? {} : { env: input.environment }
+    },
+    filesystem,
+    ...input.policy.network === "deny" ? { network: { egress: { default: "deny" }, ingress: { default: "deny", hostLoopback: "deny" } } } : { network: { egress: { default: "allow" } } }
+  };
+  return request;
+}
+function exists(item) {
+  try {
+    fs2.statSync(item);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function real(item) {
+  try {
+    return fs2.realpathSync(item);
+  } catch {
+    return item;
+  }
+}
+function existing(paths, platform) {
+  return platform === "linux" ? paths.filter(exists) : paths;
+}
+function unsupportedNetwork(platform, network) {
+  return platform === "win32" && network === "deny";
+}
+function resolveExecutor(platform = process.platform, arch = process.arch) {
+  const name = platform === "darwin" ? "mxc-exec-mac" : platform === "win32" ? "wxc-exec.exe" : platform === "linux" ? "lxc-exec" : undefined;
+  if (!name)
+    return `no MXC executor exists for ${platform}`;
+  const sdk = path2.dirname(fileURLToPath(import.meta.resolve("@microsoft/mxc-sdk/package.json")));
+  const executor = path2.join(sdk, "bin", arch === "arm64" ? "arm64" : "x64", name);
+  if (!fs2.existsSync(executor)) {
+    return platform === "darwin" && arch === "x64" ? "the installed @microsoft/mxc-sdk ships no Intel macOS executor yet" : `the MXC executor is missing from the @microsoft/mxc-sdk package: ${executor}`;
+  }
+  return executor;
+}
+function quote(value, platform = process.platform) {
+  if (platform === "win32")
+    return windowsArgument(value);
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function windowsArgument(value) {
+  if (!/[\s"]/.test(value))
+    return value;
+  let quoted = '"';
+  let backslashes = 0;
+  for (const character of value) {
+    if (character === "\\") {
+      backslashes++;
+      continue;
+    }
+    if (character === '"') {
+      quoted += "\\".repeat(backslashes * 2 + 1) + '"';
+      backslashes = 0;
+      continue;
+    }
+    quoted += "\\".repeat(backslashes) + character;
+    backslashes = 0;
+  }
+  return quoted + "\\".repeat(backslashes * 2) + '"';
+}
+
+// src/cli.ts
+var HELP = `sandboxed-shell: an interactive shell inside the MXC sandbox
+
+Usage: sandboxed-shell [--workspace <dir>] [--shell <path>]
+
+Options:
+  -w, --workspace <dir>  The workspace the policy treats as writable (default: cwd)
+  -s, --shell <path>     The shell to run inside the sandbox (default: $SHELL, /bin/zsh)
+  -h, --help             Show this help
+
+The policy comes from the same config as the plugin:
+  ~/.config/universal-opencode-sandbox/config.json
+
+Fails closed: when the sandbox cannot run, nothing runs.`;
+function fail(message) {
+  console.error(`sandboxed-shell: ${message}`);
+  process.exit(1);
+}
+var workspace = process.cwd();
+var shell = process.env.SHELL ?? "/bin/zsh";
+var args = process.argv.slice(2);
+for (let index = 0;index < args.length; index++) {
+  const arg = args[index];
+  if (arg === "-h" || arg === "--help") {
+    console.log(HELP);
+    process.exit(0);
+  } else if (arg === "-w" || arg === "--workspace") {
+    workspace = args[++index] ?? fail(`${arg} needs a value`);
+  } else if (arg === "-s" || arg === "--shell") {
+    shell = args[++index] ?? fail(`${arg} needs a value`);
+  } else {
+    fail(`unknown argument: ${arg}
+
+${HELP}`);
+  }
+}
+if (!fs3.existsSync(workspace))
+  fail(`workspace does not exist: ${workspace}`);
+var policy = resolvePolicy(workspace);
+if (!policy.enabled) {
+  fail("the sandbox is disabled in the config; refusing to start an unsandboxed shell (set enabled true to use this terminal)");
+}
+var executor = resolveExecutor();
+if (!fs3.existsSync(executor))
+  fail(executor);
+if (unsupportedNetwork(process.platform, policy.network)) {
+  fail('the sandbox backend on Windows cannot enforce network denial yet; set network "allow" in the sandbox config to use this terminal');
+}
+var environment = Object.entries(process.env).filter((entry) => typeof entry[1] === "string").map(([key, value]) => `${key}=${value}`);
+var request = wireRequest({
+  command: quote(shell),
+  workspace,
+  cwd: workspace,
+  timeout: 0,
+  policy,
+  environment
+});
+var requestDirectory = path3.join(os3.tmpdir(), "universal-opencode-sandbox");
+fs3.mkdirSync(requestDirectory, { recursive: true });
+var file = path3.join(requestDirectory, `terminal_${Date.now()}_${Math.random().toString(36).slice(2, 8)}.json`);
+fs3.writeFileSync(file, JSON.stringify(request), { mode: 384 });
+var child = spawn(executor, [file], { stdio: "inherit" });
+var remove = () => fs3.rmSync(file, { force: true });
+child.on("error", (error) => {
+  remove();
+  fail(error.message);
+});
+child.on("exit", (code, signal) => {
+  remove();
+  if (signal !== null)
+    process.kill(process.pid, signal);
+  process.exit(code ?? 1);
+});

package/dist/index.js

@@ -8,10 +8,29 @@ import { Plugin } from "@opencode/plugin";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-var configDirectory = () => path.join(process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config"), "universal-opencode-sandbox");
+var realHome = () => os.userInfo().homedir;
+var defaultDeniedPaths = [
+  "~/.ssh",
+  "~/.aws",
+  "~/.gnupg",
+  "~/.netrc",
+  "~/.kube",
+  "~/.azure",
+  "~/.config/gcloud",
+  "~/.npmrc",
+  "~/.pypirc",
+  "~/.cargo/credentials",
+  "~/.docker/config.json",
+  "~/.config/gh/hosts.yml",
+  "~/Library/Application Support/gh/hosts.yml",
+  "~/.local/share/opencode/auth.json",
+  "~/.claude/.credentials.json",
+  "~/.codex/auth.json"
+];
+var configDirectory = () => path.join(process.env.XDG_CONFIG_HOME ?? path.join(realHome(), ".config"), "universal-opencode-sandbox");
 var configPath = () => path.join(configDirectory(), "config.json");
 function resolvePolicy(workspace, environment = process.env, globalFile = configPath()) {
-  let merged = { writableRoots: [], deniedPaths: [] };
+  let merged = { writableRoots: [], deniedPaths: [], blockedTools: [] };
   const global = readConfig(globalFile);
   if (global)
     merged = tighten(merged, global);
@@ -28,12 +47,14 @@ function resolvePolicy(workspace, environment = process.env, globalFile = config
     enabled: merged.enabled ?? true,
     mode: merged.mode ?? "enforce",
     filesystem: {
-      mode: merged.filesystemMode ?? "read-only",
+      mode: merged.filesystemMode ?? "workspace-write",
       writableRoots: [...new Set(merged.writableRoots)],
-      deniedPaths: [...new Set(merged.deniedPaths)]
+      deniedPaths: merged.deniedPathsExplicit ? [...new Set(merged.deniedPaths)] : defaultDeniedPaths
     },
     network: merged.network ?? "deny",
-    unsandboxed: merged.unsandboxed ?? "deny"
+    unsandboxed: merged.unsandboxed ?? "deny",
+    userCommands: merged.userCommands ?? false,
+    blockedTools: [...new Set(merged.blockedTools)]
   };
 }
 function readConfig(file) {
@@ -50,9 +71,14 @@ function tighten(merged, raw) {
         merged.writableRoots.push(root);
   }
   if (Array.isArray(raw.filesystem?.denied_paths)) {
-    for (const item of raw.filesystem.denied_paths)
+    const items = raw.filesystem.denied_paths.filter((item) => typeof item === "string");
+    merged.deniedPaths = merged.deniedPathsExplicit ? [...merged.deniedPaths, ...items] : items;
+    merged.deniedPathsExplicit = true;
+  }
+  if (Array.isArray(raw.blocked_tools)) {
+    for (const item of raw.blocked_tools)
       if (typeof item === "string")
-        merged.deniedPaths.push(item);
+        merged.blockedTools.push(item);
   }
   return {
     enabled: raw.enabled === undefined ? merged.enabled : raw.enabled === false ? false : merged.enabled === false ? false : true,
@@ -60,8 +86,11 @@ function tighten(merged, raw) {
     filesystemMode: strictest(merged.filesystemMode, raw.filesystem?.mode, "read-only", "workspace-write"),
     network: strictest(merged.network, raw.network, "deny", "allow"),
     unsandboxed: strictest(merged.unsandboxed, raw.unsandboxed, "deny", "allow"),
+    userCommands: raw.sandbox_user_commands === true || merged.userCommands === true,
+    blockedTools: merged.blockedTools,
     writableRoots: merged.writableRoots,
-    deniedPaths: merged.deniedPaths
+    deniedPaths: merged.deniedPaths,
+    deniedPathsExplicit: merged.deniedPathsExplicit
   };
 }
 function strictest(current, incoming, strict, loose) {
@@ -74,6 +103,12 @@ function strictest(current, incoming, strict, loose) {
 function expandHome(item, home = os.homedir()) {
   return item === "~" ? home : item.startsWith("~/") ? path.join(home, item.slice(2)) : item;
 }
+function toolBlocked(tool, patterns) {
+  return patterns.some((pattern) => {
+    const source = pattern.split("*").map((part) => part.replace(/[|\\{}()[\]^$+?.]/g, "\\$&")).join(".*");
+    return new RegExp(`^${source}$`).test(tool);
+  });
+}
 
 // src/wire.ts
 import { randomBytes } from "node:crypto";
@@ -124,7 +159,8 @@ function wireRequest(input, platform = process.platform) {
       commandLine: input.command,
       timeout: input.timeout,
       cwd,
-      inheritDefaultEnv: true
+      inheritDefaultEnv: true,
+      ...input.environment === undefined ? {} : { env: input.environment }
     },
     filesystem,
     ...input.policy.network === "deny" ? { network: { egress: { default: "deny" }, ingress: { default: "deny", hostLoopback: "deny" } } } : { network: { egress: { default: "allow" } } }
@@ -217,6 +253,10 @@ var src_default = Plugin.define({
       fs3.rmSync(pending.file, { force: true });
     };
     const before = await context.tool.hook("execute.before", async (event) => {
+      if (toolBlocked(event.tool, policy.blockedTools)) {
+        log("warn", `tool call to ${event.tool} blocked by the sandbox config (blocked_tools)`);
+        throw new Error(`universal-opencode-sandbox: the tool ${event.tool} is blocked by the sandbox config`);
+      }
       if (event.tool !== "shell")
         return;
       const input = event.input ?? {};
@@ -253,6 +293,32 @@ var src_default = Plugin.define({
         log("warn", `failed to wrap the command; running unsandboxed: ${error instanceof Error ? error.message : String(error)}`);
       }
     });
+    const shellBefore = policy.userCommands ? await context.shell.hook("create.before", async (invocation) => {
+      if (invocation.command.startsWith(`${quote(executor)} `))
+        return;
+      if (unavailable || gap) {
+        if (enforce)
+          throw new Error(`${BLOCKED}: ${reason}`);
+        return;
+      }
+      try {
+        const request = wireRequest({
+          command: invocation.command,
+          workspace: context.location.directory,
+          cwd: invocation.cwd,
+          timeout: invocation.timeout || 0,
+          policy
+        });
+        const id = `shell_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        const file = path3.join(requestDirectory, `${id}.json`);
+        fs3.writeFileSync(file, JSON.stringify(request), { mode: 384 });
+        invocation.command = `${quote(executor)} ${quote(file)}`;
+      } catch (error) {
+        if (enforce)
+          throw new Error(`${BLOCKED}: ${error instanceof Error ? error.message : String(error)}`);
+        log("warn", `failed to wrap a shell command; running unsandboxed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }) : undefined;
     const after = await context.tool.hook("execute.after", async (event) => {
       const pending = inFlight.get(event.id);
       if (pending === undefined)
@@ -264,6 +330,8 @@ var src_default = Plugin.define({
     return async () => {
       await before.dispose();
       await after.dispose();
+      if (shellBefore)
+        await shellBefore.dispose();
       for (const callID of [...inFlight.keys()])
         cleanup(callID);
     };

package/dist/policy.d.ts

@@ -11,12 +11,29 @@ export interface Policy {
     readonly network: "deny" | "allow";
     /** What happens when a tool call asks to skip the sandbox (shell input "sandbox: false"). */
     readonly unsandboxed: "deny" | "allow";
+    /** Also sandbox user "!" commands and plugin shells, not just agent shell tool calls. */
+    readonly userCommands: boolean;
+    /** Tool names the agent may not call at all, with "*" as a wildcard ("paseo_*"). */
+    readonly blockedTools: string[];
 }
+/**
+ * Credential stores a sandboxed command can neither read nor write by default: the
+ * classic identity directories plus the plaintext credential files of the major
+ * CLIs, cloud SDKs and agent tools. A stolen long-lived credential cannot be undone
+ * by a restart, so reading is denied even though the network usually is too: a secret
+ * read once can be copied into the workspace and walk out through a commit. Setting
+ * denied_paths in the config replaces this list; the entries are then the user's.
+ */
+export declare const defaultDeniedPaths: string[];
 export declare const defaultPolicy: Policy;
 /**
  * Resolves the sandbox policy for a workspace: the global config file, tightened by the
  * matching per-project override, tightened by UNIVERSAL_SANDBOX_CONFIG. Security fields
- * only ever get stricter across explicit values; roots and denied paths accumulate.
+ * only ever get stricter across explicit values; roots and blocked tools accumulate.
+ * Denied paths start from defaultDeniedPaths and are replaced wholesale by the first
+ * layer that sets denied_paths, then extended by later layers.
  */
 export declare function resolvePolicy(workspace: string, environment?: NodeJS.ProcessEnv, globalFile?: string): Policy;
 export declare function expandHome(item: string, home?: string): string;
+/** True when the tool name matches a blocked pattern; "*" in a pattern matches any sequence. */
+export declare function toolBlocked(tool: string, patterns: readonly string[]): boolean;

package/dist/wire.d.ts

@@ -39,6 +39,8 @@ export interface WireInput {
     readonly timeout: number;
     readonly policy: Policy;
     readonly tmpRoots?: string[];
+    /** Extra KEY=VALUE environment entries layered over the backend default (used by the sandboxed-shell CLI). */
+    readonly environment?: string[];
 }
 /** Maps a policy and one command onto the wire request, platform-aware. */
 export declare function wireRequest(input: WireInput, platform?: NodeJS.Platform): WireRequest;

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "universal-opencode-sandbox",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Universal OS-level sandbox for OpenCode agent shell commands on macOS, Linux and Windows, enforced by Microsoft MXC",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "sandboxed-shell": "dist/cli.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -17,7 +20,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "bun build ./src/index.ts --outdir dist --target node --format esm --external @microsoft/mxc-sdk --external @opencode/plugin && bun x tsc -p tsconfig.declarations.json",
+    "build": "bun build ./src/index.ts ./src/cli.ts --outdir dist --target node --format esm --external @microsoft/mxc-sdk --external @opencode/plugin && bun x tsc -p tsconfig.declarations.json",
     "dev": "bun run --watch src/index.ts",
     "test": "bun test",
     "typecheck": "tsc --noEmit",