universal-opencode-sandbox 0.3.0 → 0.4.0

package/README.md

@@ -51,16 +51,22 @@ on purpose: they can be set from a repository's own config.
     // directory, and writable_roots; "read-only" denies every write.
     "mode": "workspace-write",
     "writable_roots": [],
-    // 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"]
+    // 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,
@@ -68,7 +74,8 @@ on purpose: they can be set from a repository's own config.
   // 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"],
+  // 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": {
@@ -79,6 +86,44 @@ 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
@@ -86,20 +131,29 @@ 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
+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` and `~/Library/Application Support/gh/hosts.yml` -
-  the GitHub CLI token (both config-directory conventions)
-- `~/.local/share/opencode/auth.json` - OpenCode provider API keys
+- `~/.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 not-yet-existing paths are protected too.
+microsoft/mxc#1780); on macOS and Windows not-yet-existing paths are protected
+too.
 
 ## What is enforced
 
@@ -148,13 +202,35 @@ disable the admin terminal for regular users. The plugin confines opencode agent
 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:
+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, next to this plugin in your config
+// opencode.jsonc - example: denying the Paseo terminal tools
 {
   "permissions": [
     { "action": "paseo_create_terminal", "resource": "*", "effect": "deny" },
@@ -164,8 +240,10 @@ hide them from the agent's tool catalog entirely:
 }
 ```
 
-Use the `permissions` array: the older `permission` object is deprecated and, on
-current releases, silently ignored.
+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
 
@@ -176,7 +254,13 @@ current releases, silently ignored.
   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.
 

package/dist/cli.js

@@ -16,15 +16,18 @@ var defaultDeniedPaths = [
   "~/.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"
@@ -32,7 +35,7 @@ var defaultDeniedPaths = [
 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: [] };
+  let merged = { writableRoots: [], deniedPaths: [], blockedTools: [], unsandboxedAllow: [] };
   const global = readConfig(globalFile);
   if (global)
     merged = tighten(merged, global);
@@ -56,7 +59,8 @@ function resolvePolicy(workspace, environment = process.env, globalFile = config
     network: merged.network ?? "deny",
     unsandboxed: merged.unsandboxed ?? "deny",
     userCommands: merged.userCommands ?? false,
-    blockedTools: [...new Set(merged.blockedTools)]
+    blockedTools: [...new Set(merged.blockedTools)],
+    unsandboxedAllow: [...new Set(merged.unsandboxedAllow)]
   };
 }
 function readConfig(file) {
@@ -82,14 +86,20 @@ function tighten(merged, raw) {
       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: 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,
     deniedPathsExplicit: merged.deniedPathsExplicit
@@ -102,14 +112,27 @@ 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) => {
-    const source = pattern.split("*").map((part) => part.replace(/[|\\{}()[\]^$+?.]/g, "\\$&")).join(".*");
-    return new RegExp(`^${source}$`).test(tool);
-  });
+  return patterns.some((pattern) => matchesWildcard(tool, pattern));
 }
 
 // src/wire.ts

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";
 
@@ -14,15 +14,18 @@ var defaultDeniedPaths = [
   "~/.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"
@@ -30,7 +33,7 @@ var defaultDeniedPaths = [
 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: [] };
+  let merged = { writableRoots: [], deniedPaths: [], blockedTools: [], unsandboxedAllow: [] };
   const global = readConfig(globalFile);
   if (global)
     merged = tighten(merged, global);
@@ -54,7 +57,8 @@ function resolvePolicy(workspace, environment = process.env, globalFile = config
     network: merged.network ?? "deny",
     unsandboxed: merged.unsandboxed ?? "deny",
     userCommands: merged.userCommands ?? false,
-    blockedTools: [...new Set(merged.blockedTools)]
+    blockedTools: [...new Set(merged.blockedTools)],
+    unsandboxedAllow: [...new Set(merged.unsandboxedAllow)]
   };
 }
 function readConfig(file) {
@@ -80,14 +84,20 @@ function tighten(merged, raw) {
       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: 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,
     deniedPathsExplicit: merged.deniedPathsExplicit
@@ -100,14 +110,27 @@ 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) => {
-    const source = pattern.split("*").map((part) => part.replace(/[|\\{}()[\]^$+?.]/g, "\\$&")).join(".*");
-    return new RegExp(`^${source}$`).test(tool);
-  });
+  return patterns.some((pattern) => matchesWildcard(tool, pattern));
 }
 
 // src/wire.ts
@@ -225,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({
@@ -243,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);
@@ -252,11 +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 ?? {};
@@ -265,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) {
@@ -332,6 +477,10 @@ var src_default = Plugin.define({
       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,11 +10,13 @@ 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
@@ -23,6 +25,11 @@ export interface Policy {
  * 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;
@@ -35,5 +42,11 @@ export declare const defaultPolicy: Policy;
  */
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-opencode-sandbox",
-  "version": "0.3.0",
+  "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",