universal-opencode-sandbox 0.1.1 → 0.4.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,18 +47,35 @@ 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.
-    "denied_paths": ["~/.ssh", "~/.aws"]
+    // Leave denied_paths unset to get the standard credential list below.
+    // Setting it replaces that list wholesale, so to add a path of your own,
+    // copy the standard list and extend it, for example:
+    // "denied_paths": ["~/.ssh", "~/.aws", "... the standard list below ...", "~/.config/my-cli"]
   },
   // "deny" (default) blocks all network access for sandboxed commands.
   "network": "deny",
   // What happens when a tool call asks to skip the sandbox (shell input
-  // "sandbox: false"): "deny" (default) blocks it, "allow" runs it unsandboxed.
+  // "sandbox: false"): "deny" (default) blocks it; "ask" prompts you with the
+  // exact command and runs it unsandboxed only after your approval; "allow"
+  // runs it unsandboxed without asking. Per-project overrides only tighten it.
   "unsandboxed": "deny",
+  // Commands pre-approved to run unsandboxed without a prompt, with "*"
+  // wildcards. The persistent form of an approval, kept here in your config
+  // where it stays visible and reviewable. Applies in "ask" mode.
+  "unsandboxed_allow": ["git push *", "npm publish*"],
+  // 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.
+  // See "Blocking host tools" below; for example, for the Paseo host app:
+  // "blocked_tools": ["paseo_create_terminal", "paseo_send_terminal_keys", "paseo_capture_terminal"],
   // 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 +86,75 @@ on purpose: they can be set from a repository's own config.
 
 `UNIVERSAL_SANDBOX_CONFIG` (a JSON string) tightens the same fields per invocation.
 
+### Escaping the sandbox with approval
+
+`unsandboxed: "ask"` registers an escape tool, `shell_unsandboxed`: one shell
+command outside the sandbox, and every call needs your approval - the prompt
+shows the exact command, and only an approval runs it. A rejection or a deny
+rule fails the call. With `unsandboxed: "allow"` the tool runs commands without
+asking; with `"deny"` (the default) the tool is not registered at all, so an
+agent cannot even ask.
+
+The prompt uses its own permission action, `unsandboxed`, so an allow rule for
+`shell` never silently covers an escape - and you can pre-approve command
+patterns through opencode's own permission rules, which the prompt then honors
+instead of asking again. A deny rule for the action hides the tool entirely.
+The prompt offers no persistent "always allow": every escape is approved per
+call, and where a host still renders an "always allow" button it behaves
+identically to "allow once" - the request carries no save scope, so nothing is
+ever stored. The persistent form of an approval is `unsandboxed_allow` in this
+plugin's own config, where it stays visible and reviewable.
+
+What the prompt looks like is up to the host: opencode's terminal UI checks the
+save scope and omits its "always allow" option entirely, so there the choice is
+simply allow once or reject; the web and desktop apps still render the button,
+which then approves just that call. The command is always visible somewhere -
+in the request message where the host renders it, and in the tool call with
+its full input in the timeline right above the prompt.
+
+```jsonc
+// opencode.jsonc
+{
+  "permissions": [
+    // Never ask again for these unsandboxed commands:
+    { "action": "unsandboxed", "resource": "git push *", "effect": "allow" },
+    // Or remove the escape route altogether (blocked_tools works too):
+    { "action": "unsandboxed", "resource": "*", "effect": "deny" }
+  ]
+}
+```
+
+### 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.
+
+Paths that live in a platform's app-data directory are listed per platform; the
+variants for the other platforms are nonexistent there and simply do nothing.
+
+- `~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.kube`, `~/.azure` - identity directories:
+  keys, cloud credentials, cluster tokens (identical on every platform)
+- `~/.netrc` and `~/_netrc` - plaintext logins for curl and friends (the latter
+  is the Windows convention)
+- `~/.config/gcloud`, `~/AppData/Roaming/gcloud` - GCP credentials and
+  service-account keys (Linux/macOS and Windows)
+- `~/.npmrc`, `~/.pypirc`, `~/.cargo/credentials`, `~/.docker/config.json` -
+  registry tokens of the major package managers and Docker
+- `~/.config/gh/hosts.yml`, `~/Library/Application Support/gh/hosts.yml`,
+  `~/AppData/Roaming/gh/hosts.yml` - the GitHub CLI token in each platform's
+  config-directory convention
+- `~/.local/share/opencode/auth.json` - OpenCode provider API keys (OpenCode
+  uses this XDG path on every platform, Windows included)
+- `~/.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 and Windows not-yet-existing paths are protected
+too.
+
 ## What is enforced
 
 - **Filesystem**: in `workspace-write` mode, writes are allowed in the workspace and
@@ -86,6 +174,77 @@ 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. For the agent's own route to a host app's tools, see
+[Blocking host tools](#blocking-host-tools).
+
+## Blocking host tools
+
+The OS sandbox confines the processes it spawns, but a host app around opencode can
+register tools that spawn processes of their own, outside the sandbox: a terminal
+tool runs a raw shell, and an agent with access to it can type into one. Two layers
+close that route. Both take the tool names as the agent sees them, and both support
+`*` as a wildcard.
+
+1. `blocked_tools` in this plugin's config denies every matching tool call, whatever
+   asks for it. It is read only from user-owned config outside the workspace, so a
+   repository config cannot re-allow a blocked tool.
+
+```jsonc
+// ~/.config/universal-opencode-sandbox/config.json
+{
+  "blocked_tools": ["paseo_create_terminal", "paseo_send_terminal_keys", "paseo_capture_terminal"]
+}
+```
+
+2. opencode's own `permissions` rules hide the tools from the agent's catalog
+   entirely, so the model never even sees them. Use the `permissions` array: the
+   older `permission` object is deprecated and, on current releases, silently
+   ignored.
+
+```jsonc
+// opencode.jsonc - example: denying the Paseo terminal tools
+{
+  "permissions": [
+    { "action": "paseo_create_terminal", "resource": "*", "effect": "deny" },
+    { "action": "paseo_send_terminal_keys", "resource": "*", "effect": "deny" },
+    { "action": "paseo_capture_terminal", "resource": "*", "effect": "deny" }
+  ]
+}
+```
+
+The names above are the Paseo terminal tools as a worked example; substitute the
+tool names of your own host app, or use a wildcard such as `"paseo_*"`. Layer 1 is
+the enforcement (a call cannot run), layer 2 the clean-up (the tool is not offered
+to the model at all); together a repository config cannot talk its way around them.
+
 ## Known limitations
 
 - With the sandbox enabled, OpenCode's per-command shell permission rules see the
@@ -95,7 +254,13 @@ on purpose: they can be set from a repository's own config.
   commands, prefer this plugin's `denied_paths` and filesystem policy.
 - Intel macOS is unsupported: the MXC npm package ships no darwin-x64 runtime yet.
 - MXC release builds on Windows emit required Microsoft diagnostic telemetry; see the
-  [MXC documentation](https://github.com/microsoft/mxc).
+  [MXC documentation](https://github.com/microsoft/mxc). Per MXC's field inventory
+  the events carry only operational metadata: the MXC version, the requested
+  sandbox kind and selected backend, run outcome, exit code, duration, a bounded
+  failure category, and random correlation identifiers. They explicitly do not
+  contain command lines, environment values, file paths, tokens, credentials,
+  sandbox output, or free-form error text. Telemetry is a no-op on macOS and
+  Linux: nothing leaves the host there.
 - MXC's process streams do not deliver under Bun (microsoft/mxc#1782). This plugin is
   unaffected: the executor is a native binary whose output the shell tool captures.
 
@@ -106,7 +271,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,325 @@
+#!/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",
+  "~/_netrc",
+  "~/.kube",
+  "~/.azure",
+  "~/.config/gcloud",
+  "~/AppData/Roaming/gcloud",
+  "~/.npmrc",
+  "~/.pypirc",
+  "~/.cargo/credentials",
+  "~/.docker/config.json",
+  "~/.config/gh/hosts.yml",
+  "~/Library/Application Support/gh/hosts.yml",
+  "~/AppData/Roaming/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: [], unsandboxedAllow: [] };
+  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)],
+    unsandboxedAllow: [...new Set(merged.unsandboxedAllow)]
+  };
+}
+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);
+  }
+  if (Array.isArray(raw.unsandboxed_allow)) {
+    for (const item of raw.unsandboxed_allow)
+      if (typeof item === "string")
+        merged.unsandboxedAllow.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: strictestUnsandboxed(merged.unsandboxed, raw.unsandboxed),
+    userCommands: raw.sandbox_user_commands === true || merged.userCommands === true,
+    blockedTools: merged.blockedTools,
+    unsandboxedAllow: merged.unsandboxedAllow,
+    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 strictestUnsandboxed(current, incoming) {
+  if (incoming !== "deny" && incoming !== "ask" && incoming !== "allow")
+    return current;
+  if (current === "deny" || incoming === "deny")
+    return "deny";
+  if (current === "ask" || incoming === "ask")
+    return "ask";
+  return "allow";
+}
+function expandHome(item, home = os.homedir()) {
+  return item === "~" ? home : item.startsWith("~/") ? path.join(home, item.slice(2)) : item;
+}
+function matchesWildcard(value, pattern) {
+  const normalized = value.replaceAll("\\", "/");
+  let escaped = pattern.replaceAll("\\", "/").replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+  if (escaped.endsWith(" .*"))
+    escaped = escaped.slice(0, -3) + "( .*)?";
+  return new RegExp(`^${escaped}$`, "s").test(normalized);
+}
+function toolBlocked(tool, patterns) {
+  return patterns.some((pattern) => matchesWildcard(tool, pattern));
+}
+
+// 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

@@ -1,6 +1,6 @@
 // src/index.ts
 import fs3 from "node:fs";
-import os3 from "node:os";
+import os4 from "node:os";
 import path3 from "node:path";
 import { Plugin } from "@opencode/plugin";
 
@@ -8,10 +8,32 @@ 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",
+  "~/_netrc",
+  "~/.kube",
+  "~/.azure",
+  "~/.config/gcloud",
+  "~/AppData/Roaming/gcloud",
+  "~/.npmrc",
+  "~/.pypirc",
+  "~/.cargo/credentials",
+  "~/.docker/config.json",
+  "~/.config/gh/hosts.yml",
+  "~/Library/Application Support/gh/hosts.yml",
+  "~/AppData/Roaming/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: [], unsandboxedAllow: [] };
   const global = readConfig(globalFile);
   if (global)
     merged = tighten(merged, global);
@@ -28,12 +50,15 @@ 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)],
+    unsandboxedAllow: [...new Set(merged.unsandboxedAllow)]
   };
 }
 function readConfig(file) {
@@ -50,18 +75,32 @@ 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.blockedTools.push(item);
+  }
+  if (Array.isArray(raw.unsandboxed_allow)) {
+    for (const item of raw.unsandboxed_allow)
       if (typeof item === "string")
-        merged.deniedPaths.push(item);
+        merged.unsandboxedAllow.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"),
+    unsandboxed: strictestUnsandboxed(merged.unsandboxed, raw.unsandboxed),
+    userCommands: raw.sandbox_user_commands === true || merged.userCommands === true,
+    blockedTools: merged.blockedTools,
+    unsandboxedAllow: merged.unsandboxedAllow,
     writableRoots: merged.writableRoots,
-    deniedPaths: merged.deniedPaths
+    deniedPaths: merged.deniedPaths,
+    deniedPathsExplicit: merged.deniedPathsExplicit
   };
 }
 function strictest(current, incoming, strict, loose) {
@@ -71,9 +110,28 @@ function strictest(current, incoming, strict, loose) {
     return loose;
   return current;
 }
+function strictestUnsandboxed(current, incoming) {
+  if (incoming !== "deny" && incoming !== "ask" && incoming !== "allow")
+    return current;
+  if (current === "deny" || incoming === "deny")
+    return "deny";
+  if (current === "ask" || incoming === "ask")
+    return "ask";
+  return "allow";
+}
 function expandHome(item, home = os.homedir()) {
   return item === "~" ? home : item.startsWith("~/") ? path.join(home, item.slice(2)) : item;
 }
+function matchesWildcard(value, pattern) {
+  const normalized = value.replaceAll("\\", "/");
+  let escaped = pattern.replaceAll("\\", "/").replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+  if (escaped.endsWith(" .*"))
+    escaped = escaped.slice(0, -3) + "( .*)?";
+  return new RegExp(`^${escaped}$`, "s").test(normalized);
+}
+function toolBlocked(tool, patterns) {
+  return patterns.some((pattern) => matchesWildcard(tool, pattern));
+}
 
 // src/wire.ts
 import { randomBytes } from "node:crypto";
@@ -124,7 +182,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" } } }
@@ -189,6 +248,75 @@ function windowsArgument(value) {
   return quoted + "\\".repeat(backslashes * 2) + '"';
 }
 
+// src/unsandboxed.ts
+import { spawn } from "node:child_process";
+import os3 from "node:os";
+var OUTPUT_LIMIT = 200000;
+var RETURN_LIMIT = 50000;
+var unsandboxedShellTool = (workspace) => ({
+  name: "shell_unsandboxed",
+  description: "Run one shell command OUTSIDE the sandbox, on the host. The user approves every call and sees the exact command (or has pre-approved a pattern). " + "Use this only for what the sandboxed shell cannot do and the user asked for, such as publishing a package, pushing over SSH, or reaching the network; " + "for everything else prefer the sandboxed shell tool.",
+  input: {
+    type: "object",
+    properties: {
+      command: { type: "string", description: "The shell command to run unsandboxed" },
+      timeout: { type: "number", description: "Timeout in milliseconds (default 120000)" },
+      workdir: { type: "string", description: "Working directory (default: the workspace)" }
+    },
+    required: ["command"],
+    additionalProperties: false
+  },
+  options: { permission: "unsandboxed" },
+  execute: async (raw, context) => {
+    const input = raw ?? {};
+    const command = input.command;
+    if (typeof command !== "string" || command === "")
+      throw new Error("a command is required");
+    const timeout = typeof input.timeout === "number" && input.timeout > 0 ? input.timeout : 120000;
+    const cwd = typeof input.workdir === "string" && input.workdir !== "" ? input.workdir : workspace;
+    return await new Promise((resolve) => {
+      const child = spawn(process.env.SHELL ?? "/bin/sh", ["-c", command], {
+        cwd,
+        env: { ...process.env, HOME: os3.userInfo().homedir }
+      });
+      let stdout = "";
+      let stderr = "";
+      let timedOut = false;
+      const timer = setTimeout(() => {
+        timedOut = true;
+        child.kill("SIGKILL");
+      }, timeout);
+      child.stdout?.on("data", (chunk) => {
+        if (stdout.length < OUTPUT_LIMIT)
+          stdout += chunk.toString();
+      });
+      child.stderr?.on("data", (chunk) => {
+        if (stderr.length < OUTPUT_LIMIT)
+          stderr += chunk.toString();
+      });
+      child.on("error", (error) => {
+        clearTimeout(timer);
+        resolve({ content: `failed to start: ${error.message}` });
+      });
+      child.on("close", (code) => {
+        clearTimeout(timer);
+        const combined = `stdout:
+${stdout}
+stderr:
+${stderr}`;
+        const tail = combined.length > RETURN_LIMIT ? `...${combined.slice(-RETURN_LIMIT)}` : combined;
+        resolve({
+          content: `${timedOut ? `timed out
+` : ""}exit code ${code ?? "unknown"}
+
+${tail}`,
+          metadata: { exitCode: code, timedOut }
+        });
+      });
+    });
+  }
+});
+
 // src/index.ts
 var BLOCKED = "universal-opencode-sandbox unavailable; command blocked";
 var src_default = Plugin.define({
@@ -207,7 +335,7 @@ var src_default = Plugin.define({
       log(enforce ? "error" : "warn", `${reason}; ${enforce ? 'shell commands will be blocked (set mode "permissive" to run unsandboxed)' : "commands will run without a sandbox"}`);
     }
     const inFlight = new Map;
-    const requestDirectory = path3.join(os3.tmpdir(), "universal-opencode-sandbox");
+    const requestDirectory = path3.join(os4.tmpdir(), "universal-opencode-sandbox");
     fs3.mkdirSync(requestDirectory, { recursive: true });
     const cleanup = (callID) => {
       const pending = inFlight.get(callID);
@@ -216,7 +344,50 @@ var src_default = Plugin.define({
       inFlight.delete(callID);
       fs3.rmSync(pending.file, { force: true });
     };
+    const escapeTool = policy.unsandboxed === "deny" ? undefined : await context.tool.transform((editor) => {
+      editor.add(unsandboxedShellTool(context.location.directory));
+    });
+    const askGuard = policy.unsandboxed === "ask" ? await context.permission.hook("evaluate", async (event) => {
+      if (event.action !== "unsandboxed")
+        return;
+      event.message = `Run this command outside the sandbox:
+
+${event.resources.join(" ")}`;
+      if (event.effect !== "allow")
+        return;
+      const force = () => {
+        event.effect = "ask";
+      };
+      try {
+        const session = await context.session.get({ sessionID: event.sessionID });
+        const specific = (session.permissions ?? []).some((rule) => rule.effect === "allow" && rule.action !== "*" && matchesWildcard(event.action, rule.action) && event.resources.every((resource) => matchesWildcard(resource, rule.resource)));
+        if (!specific)
+          force();
+      } catch {
+        force();
+      }
+    }) : undefined;
     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_unsandboxed") {
+        const escape = event.input?.command;
+        if (policy.unsandboxed === "ask" && typeof escape === "string" && escape !== "") {
+          const preapproved = policy.unsandboxedAllow.some((pattern) => matchesWildcard(escape, pattern));
+          if (!preapproved) {
+            await context.permission.assert({
+              sessionID: event.sessionID,
+              action: "unsandboxed",
+              resources: [escape],
+              metadata: { command: escape }
+            });
+            log("warn", `the user approved running a command unsandboxed: ${escape}`);
+          }
+        }
+        return;
+      }
       if (event.tool !== "shell")
         return;
       const input = event.input ?? {};
@@ -225,9 +396,23 @@ var src_default = Plugin.define({
         return;
       if (input.sandbox === false) {
         if (policy.unsandboxed === "deny") {
-          log("warn", `tool call asked to skip the sandbox; blocked (set unsandboxed "allow" to permit this)`);
+          log("warn", `tool call asked to skip the sandbox; blocked (set unsandboxed "ask" or "allow" to permit this)`);
           throw new Error("universal-opencode-sandbox: running this command unsandboxed is not allowed");
         }
+        if (policy.unsandboxed === "ask") {
+          const preapproved = policy.unsandboxedAllow.some((pattern) => matchesWildcard(command, pattern));
+          if (!preapproved) {
+            await context.permission.assert({
+              sessionID: event.sessionID,
+              action: "unsandboxed",
+              resources: [command],
+              metadata: { command }
+            });
+            log("warn", `the user approved running a command unsandboxed: ${command}`);
+          } else {
+            log("warn", `running a command unsandboxed without a prompt (unsandboxed_allow): ${command}`);
+          }
+        }
         return;
       }
       if (unavailable || gap) {
@@ -253,6 +438,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 +475,12 @@ var src_default = Plugin.define({
     return async () => {
       await before.dispose();
       await after.dispose();
+      if (shellBefore)
+        await shellBefore.dispose();
+      if (escapeTool)
+        await escapeTool.dispose();
+      if (askGuard)
+        await askGuard.dispose();
       for (const callID of [...inFlight.keys()])
         cleanup(callID);
     };

package/dist/policy.d.ts

@@ -10,13 +10,43 @@ 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";
+    readonly unsandboxed: "deny" | "ask" | "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[];
+    /** Commands pre-approved to run unsandboxed without a prompt, with "*" wildcards. */
+    readonly unsandboxedAllow: 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.
+ *
+ * Paths that live in a platform's app-data directory are listed per platform: the
+ * Windows variants are nonexistent (and therefore no-ops) on macOS and Linux, and
+ * vice versa. Entries under the profile directory itself (~/.ssh and friends) are
+ * identical everywhere.
+ */
+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;
+/**
+ * Matches a value against a pattern the way OpenCode's own permission rules do:
+ * "*" matches any sequence, "?" one character, a trailing " *" also matches the bare
+ * prefix, and backslashes normalize to forward slashes.
+ */
+export declare function matchesWildcard(value: string, pattern: string): boolean;
+/** 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/unsandboxed.d.ts

@@ -0,0 +1,35 @@
+export interface ToolResult {
+    readonly content?: string | ReadonlyArray<{
+        type: "text";
+        text: string;
+    }>;
+    readonly metadata?: Record<string, unknown>;
+}
+interface ToolContext {
+    readonly sessionID: string;
+}
+type FieldType = {
+    readonly type: "string" | "number";
+    readonly description: string;
+};
+export type ToolInputSchema = {
+    readonly type: "object";
+    readonly properties: {
+        readonly command: FieldType;
+        readonly timeout: FieldType;
+        readonly workdir: FieldType;
+    };
+    readonly required: readonly ["command"];
+    readonly additionalProperties: false;
+};
+export interface ToolRegistration {
+    readonly name: string;
+    readonly description: string;
+    readonly input: ToolInputSchema;
+    readonly options?: {
+        readonly permission?: string;
+    };
+    readonly execute: (input: unknown, context: ToolContext) => Promise<ToolResult>;
+}
+export declare const unsandboxedShellTool: (workspace: string) => ToolRegistration;
+export {};

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.1",
+  "version": "0.4.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",