@agentproto/command-sandbox 0.2.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/index.d.ts

@@ -0,0 +1,191 @@
+/**
+ * OS-level process confinement — macOS Seatbelt (`sandbox-exec`) and Linux
+ * bubblewrap (`bwrap`) backends for wrapping a spawned argv.
+ *
+ * Extracted from `@agentproto/runtime`'s original `command-tools.ts`-only
+ * use (which still consumes this package for `command_execute`) so
+ * `@agentproto/driver-agent-cli` can wrap its OWN adapter-child spawn
+ * (`define-agent-cli.ts` / `print-arm.ts`) through the identical policy and
+ * backends, without creating a circular package dependency — `runtime`
+ * depends on `driver-agent-cli` (it spawns adapter sessions), so
+ * `driver-agent-cli` cannot depend back on `runtime`. This package has zero
+ * workspace dependencies; both sides depend on it.
+ *
+ * The allowlist (`command-tools.ts` in `runtime`) gates WHICH binary may
+ * run; this bounds what that binary (or, for the adapter-spawn use, the
+ * agent-cli child itself) may READ/WRITE and — in strict mode — reach on
+ * the network. It closes the residual gap where an allowlisted interpreter
+ * (`bash`, `node`, `python3`, …) reads `~/.ssh/id_rsa` or exfiltrates: the
+ * cwd anchor bounds the working directory, not what the process opens.
+ *
+ * The Seatbelt profile was validated empirically (2026-07): under it `node`
+ * / `cat` read workspace files fine, `~/.ssh` reads fail with EPERM, and
+ * strict mode makes network connects fail with EPERM. Re-validated 2026-07-22
+ * against a REAL `npx`-spawned adapter child (`@agentclientprotocol/
+ * claude-agent-acp`, the actual `claude-code` AGENT-CLI.md bin): npm's
+ * arborist `lstat`s $HOME itself while resolving config and hard-fails with
+ * EPERM without a metadata-only re-allow across $HOME (see
+ * `buildSeatbeltProfile`) — content read/write and directory listing under
+ * $HOME stay denied; only stat/lstat-class metadata is re-opened.
+ *
+ * ## Two config keys, one file, deliberately not shared (PR 6b)
+ *
+ * `.agentproto/command-sandbox.json` governs TWO independent confinement
+ * axes that happen to live in the same file: the top-level `mode` (read by
+ * `loadSandboxConfig`) confines a single `command_execute` call; the nested
+ * `adapterSpawn` key (read by `loadAdapterSpawnSandboxConfig`) confines the
+ * ENTIRE adapter-spawn process tree for the life of a session. A workspace
+ * does NOT get `adapterSpawn` confinement for free by setting the top-level
+ * `mode` — it must set `adapterSpawn.mode` explicitly. This is deliberate,
+ * not an oversight: a misconfigured `command_execute` jail breaks one
+ * command's execution (the caller sees a failed tool call and can retry
+ * unconfined); a misconfigured adapter-spawn jail breaks the WHOLE session
+ * (every tool call, every turn, for as long as the adapter runs) — a
+ * strictly larger blast radius that deserves its own explicit opt-in rather
+ * than silently inheriting whatever `command_execute` happened to be
+ * configured with.
+ */
+type SandboxMode = "off" | "workspace" | "strict";
+/** Per-workspace config read from `.agentproto/command-sandbox.json`. */
+interface CommandSandboxConfig {
+    /**
+     * - `off`       — no confinement (default; today's behavior).
+     * - `workspace` — deny access to the home directory OUTSIDE the workspace
+     *                 (protects ~/.ssh, ~/.aws, credentials, …); system paths
+     *                 stay readable so interpreters still run. Network allowed.
+     * - `strict`    — `workspace` + deny ALL network.
+     */
+    mode: SandboxMode;
+    /** Extra absolute paths to grant read access (e.g. a shared cache). */
+    extraReadPaths: string[];
+    /** Network policy. Forced to `deny` when `mode === "strict"`. */
+    network: "deny" | "allow";
+}
+/** Inputs the backend needs to build a confinement for one command. */
+interface SandboxPolicy {
+    workspace: string;
+    extraReadPaths: string[];
+    /**
+     * Extra absolute paths to grant READ+WRITE access, outside the
+     * workspace — e.g. a toolchain's self-managed install directory
+     * (`~/Library/pnpm/.tools`) or a per-spawn scratch dir created before
+     * the wrap (`CLAUDE_CONFIG_DIR`'s mkdtemp'd settings dir). Unlike
+     * `extraReadPaths`, these are also writable. Defaults to `[]` when
+     * omitted by a caller built against the pre-`extraWritePaths` shape.
+     */
+    extraWritePaths?: string[];
+    network: "deny" | "allow";
+}
+interface CommandSandbox {
+    readonly id: string;
+    /**
+     * Wrap `argv` so the command runs confined, returning the new argv to spawn
+     * (e.g. `["sandbox-exec", "-p", <profile>, ...argv]`). Never throws —
+     * sandboxing is best-effort hardening, so an empty argv is returned as-is.
+     */
+    wrap(argv: string[], policy: SandboxPolicy): string[];
+}
+declare const DEFAULT_SANDBOX_CONFIG: CommandSandboxConfig;
+/**
+ * Escape hatch: overrides the workspace config file's `mode` when set to a
+ * valid `SandboxMode`, without editing the tracked `.agentproto/
+ * command-sandbox.json`. Two directions this matters: forcing `off` when a
+ * workspace has opted into `workspace`/`strict` but one call legitimately
+ * needs broad access (e.g. a one-off `pnpm install`), or forcing `workspace`/
+ * `strict` on for a session/CI run without committing a config file. Any
+ * other value (unset, typo, empty) is ignored and the file/default applies.
+ */
+declare const COMMAND_SANDBOX_MODE_ENV = "AGENTPROTO_COMMAND_SANDBOX_MODE";
+/**
+ * Load + normalize the per-workspace sandbox config. Missing file, bad JSON, or
+ * an unknown mode all fall back to `off` (fail-open on config, not on
+ * confinement — a broken config must not silently pretend to sandbox; that's
+ * surfaced by the caller when a mode is set but no backend exists).
+ * `COMMAND_SANDBOX_MODE_ENV`, when set to a valid mode, overrides whatever the
+ * file (or the default) resolved to.
+ */
+declare function loadSandboxConfig(workspace: string): Promise<CommandSandboxConfig>;
+/**
+ * Confinement config for the ADAPTER-SPAWN axis — a distinct, explicit
+ * `adapterSpawn` key in the same `.agentproto/command-sandbox.json` file
+ * `loadSandboxConfig` reads (see the module doc for why this isn't just the
+ * top-level `mode`).
+ */
+interface AdapterSpawnSandboxConfig {
+    /**
+     * `undefined` ⇒ the file has no `adapterSpawn` key at all (or no file
+     * exists) — this axis was never engaged by the workspace, so a caller
+     * that also passed no explicit mode stays silently unconfined (today's
+     * behavior). A resolved `SandboxMode`, INCLUDING explicit `"off"`, means
+     * the workspace (or `ADAPTER_COMMAND_SANDBOX_MODE_ENV`) engaged this axis
+     * on purpose.
+     */
+    mode: SandboxMode | undefined;
+    /** Extra read-only paths merged with the adapter-spawn wrapper's own
+     *  built-in toolchain defaults (`defaultToolchainReadPaths()`). */
+    extraReadPaths: string[];
+    /** Extra read+write paths merged with the built-in toolchain defaults
+     *  (`defaultToolchainWritePaths()`). */
+    extraWritePaths: string[];
+    /** Network policy. Forced to `deny` when `mode === "strict"`. */
+    network: "deny" | "allow";
+}
+/**
+ * Escape hatch for the adapter-spawn axis, mirroring `COMMAND_SANDBOX_MODE_ENV`
+ * but kept as a SEPARATE env var rather than reusing it — forcing
+ * `command_execute` into `workspace` mode for a CI run should not, as a side
+ * effect, also confine every adapter's own process tree (and vice versa).
+ */
+declare const ADAPTER_COMMAND_SANDBOX_MODE_ENV = "AGENTPROTO_ADAPTER_COMMAND_SANDBOX_MODE";
+/**
+ * Load + normalize the adapter-spawn confinement config from the `adapterSpawn`
+ * key of `.agentproto/command-sandbox.json`. Missing file / bad JSON / no
+ * `adapterSpawn` key ⇒ `mode: undefined` (axis untouched, NOT `"off"` — see
+ * `AdapterSpawnSandboxConfig.mode`'s doc for why that distinction matters).
+ * An `adapterSpawn` key that IS present but carries an unknown/missing `mode`
+ * resolves to `"off"`, matching `loadSandboxConfig`'s fail-open-on-config
+ * posture. `ADAPTER_COMMAND_SANDBOX_MODE_ENV`, when set to a valid mode,
+ * overrides whatever the file resolved to.
+ */
+declare function loadAdapterSpawnSandboxConfig(workspace: string): Promise<AdapterSpawnSandboxConfig>;
+/**
+ * Build a macOS Seatbelt (SBPL) profile for the policy. Strategy: start
+ * permissive (`allow default`) so interpreters can read their runtime + system
+ * libraries, then DENY the whole home directory (the crown jewels — ~/.ssh,
+ * ~/.aws, credentials), then RE-ALLOW the workspace subpath, any explicit
+ * extra read paths (read-only), and any explicit extra write paths
+ * (read+write — e.g. a toolchain's self-managed install dir living under
+ * `$HOME`, which a read-only re-allow can't satisfy). SBPL is
+ * last-match-wins, so the workspace/extra re-allows override the home deny.
+ * Strict mode also denies all network. Exported for testing.
+ */
+declare function buildSeatbeltProfile(policy: SandboxPolicy): string;
+/** macOS Seatbelt backend — wraps argv as `sandbox-exec -p <profile> …`. */
+declare const seatbeltSandbox: CommandSandbox;
+/**
+ * Build the bubblewrap argv (everything after `bwrap`). Unlike Seatbelt's
+ * "deny home except workspace", bwrap is allowlist-by-construction: ONLY the
+ * paths bound here are visible, so `$HOME` secrets (~/.ssh, credentials) are
+ * simply absent from the mount namespace. System dirs are read-only, the
+ * workspace + extra reads are bound read-only, extra writes are bound
+ * read-write (`--bind-try`, not `--ro-bind-try` — e.g. a toolchain's
+ * self-managed install dir, or a per-spawn scratch dir that may not exist yet
+ * when the argv is built), and strict mode adds `--unshare-net` for an
+ * isolated (no-connectivity) network namespace. Exported for testing.
+ *
+ * Empirically validated (2026-07, ubuntu container): workspace reads succeed,
+ * `~/.ssh` reads fail (invisible), and `--unshare-net` makes connects fail with
+ * ENETUNREACH.
+ */
+declare function buildBwrapArgs(argv: string[], policy: SandboxPolicy): string[];
+/** Linux bubblewrap backend — wraps argv as `bwrap <binds> -- …`. */
+declare const bwrapSandbox: CommandSandbox;
+/**
+ * The confinement backend available on this host, or `null` when none applies
+ * (macOS → Seatbelt, Linux → bubblewrap when installed, Windows unsupported).
+ * Callers warn when a sandbox mode is configured but this returns null — so a
+ * missing backend never silently pretends to confine.
+ */
+declare function resolveCommandSandbox(): CommandSandbox | null;
+
+export { ADAPTER_COMMAND_SANDBOX_MODE_ENV, type AdapterSpawnSandboxConfig, COMMAND_SANDBOX_MODE_ENV, type CommandSandbox, type CommandSandboxConfig, DEFAULT_SANDBOX_CONFIG, type SandboxMode, type SandboxPolicy, buildBwrapArgs, buildSeatbeltProfile, bwrapSandbox, loadAdapterSpawnSandboxConfig, loadSandboxConfig, resolveCommandSandbox, seatbeltSandbox };

package/dist/index.mjs

@@ -0,0 +1,175 @@
+import { existsSync } from 'fs';
+import { readFile } from 'fs/promises';
+import { homedir } from 'os';
+import { resolve } from 'path';
+
+/**
+ * @agentproto/command-sandbox v0.1.0
+ * OS-level process confinement (Seatbelt / bubblewrap) for a spawned argv.
+ */
+
+var CONFIG_REL = ".agentproto/command-sandbox.json";
+var DEFAULT_SANDBOX_CONFIG = {
+  mode: "off",
+  extraReadPaths: [],
+  network: "allow"
+};
+var COMMAND_SANDBOX_MODE_ENV = "AGENTPROTO_COMMAND_SANDBOX_MODE";
+async function loadSandboxConfig(workspace) {
+  const path = resolve(workspace, CONFIG_REL);
+  let resolved = DEFAULT_SANDBOX_CONFIG;
+  if (existsSync(path)) {
+    try {
+      const parsed = JSON.parse(
+        await readFile(path, "utf8")
+      );
+      const mode = parsed.mode === "workspace" || parsed.mode === "strict" ? parsed.mode : "off";
+      const extraReadPaths = Array.isArray(parsed.extraReadPaths) ? parsed.extraReadPaths.filter((x) => typeof x === "string") : [];
+      const network = mode === "strict" || parsed.network === "deny" ? "deny" : "allow";
+      resolved = { mode, extraReadPaths, network };
+    } catch {
+      resolved = DEFAULT_SANDBOX_CONFIG;
+    }
+  }
+  const envMode = process.env[COMMAND_SANDBOX_MODE_ENV];
+  if (envMode === "off" || envMode === "workspace" || envMode === "strict") {
+    return {
+      ...resolved,
+      mode: envMode,
+      network: envMode === "strict" ? "deny" : resolved.network
+    };
+  }
+  return resolved;
+}
+var DEFAULT_ADAPTER_SPAWN_SANDBOX_CONFIG = {
+  mode: void 0,
+  extraReadPaths: [],
+  extraWritePaths: [],
+  network: "allow"
+};
+var ADAPTER_COMMAND_SANDBOX_MODE_ENV = "AGENTPROTO_ADAPTER_COMMAND_SANDBOX_MODE";
+async function loadAdapterSpawnSandboxConfig(workspace) {
+  const path = resolve(workspace, CONFIG_REL);
+  let resolved = DEFAULT_ADAPTER_SPAWN_SANDBOX_CONFIG;
+  if (existsSync(path)) {
+    try {
+      const parsed = JSON.parse(await readFile(path, "utf8"));
+      const raw = parsed.adapterSpawn;
+      if (raw && typeof raw === "object") {
+        const mode = raw.mode === "workspace" || raw.mode === "strict" || raw.mode === "off" ? raw.mode : "off";
+        const extraReadPaths = Array.isArray(raw.extraReadPaths) ? raw.extraReadPaths.filter((x) => typeof x === "string") : [];
+        const extraWritePaths = Array.isArray(raw.extraWritePaths) ? raw.extraWritePaths.filter((x) => typeof x === "string") : [];
+        const network = mode === "strict" || raw.network === "deny" ? "deny" : "allow";
+        resolved = { mode, extraReadPaths, extraWritePaths, network };
+      }
+    } catch {
+      resolved = DEFAULT_ADAPTER_SPAWN_SANDBOX_CONFIG;
+    }
+  }
+  const envMode = process.env[ADAPTER_COMMAND_SANDBOX_MODE_ENV];
+  if (envMode === "off" || envMode === "workspace" || envMode === "strict") {
+    return {
+      ...resolved,
+      mode: envMode,
+      network: envMode === "strict" ? "deny" : resolved.network
+    };
+  }
+  return resolved;
+}
+function sbplQuote(p) {
+  return p.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function buildSeatbeltProfile(policy) {
+  const home = homedir();
+  const ws = resolve(policy.workspace);
+  const parts = [
+    "(version 1)",
+    "(allow default)",
+    `(deny file-read* file-write* (subpath "${sbplQuote(home)}"))`,
+    // Metadata-only re-allow across all of $HOME (stat/lstat — existence,
+    // permissions, mtime; NOT directory listing or file content, both of
+    // which need file-read-data and stay denied). Empirically required
+    // (2026-07): npm/npx's arborist `lstat`s ancestor directories while
+    // resolving config/paths and hard-fails with EPERM on $HOME itself
+    // otherwise — even for a workspace-cwd invocation that never reads
+    // any OTHER file under $HOME. Without this, no npx-spawned adapter
+    // (claude-agent-acp included) can even start under `workspace` mode.
+    `(allow file-read-metadata (subpath "${sbplQuote(home)}"))`,
+    `(allow file-read* file-write* (subpath "${sbplQuote(ws)}"))`
+  ];
+  for (const extra of policy.extraReadPaths) {
+    parts.push(`(allow file-read* (subpath "${sbplQuote(resolve(extra))}"))`);
+  }
+  for (const extra of policy.extraWritePaths ?? []) {
+    parts.push(
+      `(allow file-read* file-write* (subpath "${sbplQuote(resolve(extra))}"))`
+    );
+  }
+  if (policy.network === "deny") parts.push("(deny network*)");
+  return parts.join("");
+}
+var seatbeltSandbox = {
+  id: "seatbelt",
+  wrap(argv, policy) {
+    if (argv.length === 0) return argv;
+    return ["sandbox-exec", "-p", buildSeatbeltProfile(policy), ...argv];
+  }
+};
+var BWRAP_SYSTEM_DIRS = [
+  "/usr",
+  "/usr/local",
+  "/bin",
+  "/sbin",
+  "/lib",
+  "/lib64",
+  "/etc",
+  "/opt"
+];
+function buildBwrapArgs(argv, policy) {
+  const ws = resolve(policy.workspace);
+  const out = [
+    "--die-with-parent",
+    "--proc",
+    "/proc",
+    "--dev",
+    "/dev",
+    "--tmpfs",
+    "/tmp"
+  ];
+  for (const d of BWRAP_SYSTEM_DIRS) out.push("--ro-bind-try", d, d);
+  out.push("--bind", ws, ws);
+  for (const extra of policy.extraReadPaths) {
+    const p = resolve(extra);
+    out.push("--ro-bind-try", p, p);
+  }
+  for (const extra of policy.extraWritePaths ?? []) {
+    const p = resolve(extra);
+    out.push("--bind-try", p, p);
+  }
+  if (policy.network === "deny") out.push("--unshare-net");
+  out.push("--", ...argv);
+  return out;
+}
+var bwrapSandbox = {
+  id: "bwrap",
+  wrap(argv, policy) {
+    if (argv.length === 0) return argv;
+    return ["bwrap", ...buildBwrapArgs(argv, policy)];
+  }
+};
+function bwrapAvailable() {
+  return existsSync("/usr/bin/bwrap") || existsSync("/bin/bwrap") || existsSync("/usr/local/bin/bwrap");
+}
+function resolveCommandSandbox() {
+  if (process.platform === "darwin" && existsSync("/usr/bin/sandbox-exec")) {
+    return seatbeltSandbox;
+  }
+  if (process.platform === "linux" && bwrapAvailable()) {
+    return bwrapSandbox;
+  }
+  return null;
+}
+
+export { ADAPTER_COMMAND_SANDBOX_MODE_ENV, COMMAND_SANDBOX_MODE_ENV, DEFAULT_SANDBOX_CONFIG, buildBwrapArgs, buildSeatbeltProfile, bwrapSandbox, loadAdapterSpawnSandboxConfig, loadSandboxConfig, resolveCommandSandbox, seatbeltSandbox };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * OS-level process confinement — macOS Seatbelt (`sandbox-exec`) and Linux\n * bubblewrap (`bwrap`) backends for wrapping a spawned argv.\n *\n * Extracted from `@agentproto/runtime`'s original `command-tools.ts`-only\n * use (which still consumes this package for `command_execute`) so\n * `@agentproto/driver-agent-cli` can wrap its OWN adapter-child spawn\n * (`define-agent-cli.ts` / `print-arm.ts`) through the identical policy and\n * backends, without creating a circular package dependency — `runtime`\n * depends on `driver-agent-cli` (it spawns adapter sessions), so\n * `driver-agent-cli` cannot depend back on `runtime`. This package has zero\n * workspace dependencies; both sides depend on it.\n *\n * The allowlist (`command-tools.ts` in `runtime`) gates WHICH binary may\n * run; this bounds what that binary (or, for the adapter-spawn use, the\n * agent-cli child itself) may READ/WRITE and — in strict mode — reach on\n * the network. It closes the residual gap where an allowlisted interpreter\n * (`bash`, `node`, `python3`, …) reads `~/.ssh/id_rsa` or exfiltrates: the\n * cwd anchor bounds the working directory, not what the process opens.\n *\n * The Seatbelt profile was validated empirically (2026-07): under it `node`\n * / `cat` read workspace files fine, `~/.ssh` reads fail with EPERM, and\n * strict mode makes network connects fail with EPERM. Re-validated 2026-07-22\n * against a REAL `npx`-spawned adapter child (`@agentclientprotocol/\n * claude-agent-acp`, the actual `claude-code` AGENT-CLI.md bin): npm's\n * arborist `lstat`s $HOME itself while resolving config and hard-fails with\n * EPERM without a metadata-only re-allow across $HOME (see\n * `buildSeatbeltProfile`) — content read/write and directory listing under\n * $HOME stay denied; only stat/lstat-class metadata is re-opened.\n *\n * ## Two config keys, one file, deliberately not shared (PR 6b)\n *\n * `.agentproto/command-sandbox.json` governs TWO independent confinement\n * axes that happen to live in the same file: the top-level `mode` (read by\n * `loadSandboxConfig`) confines a single `command_execute` call; the nested\n * `adapterSpawn` key (read by `loadAdapterSpawnSandboxConfig`) confines the\n * ENTIRE adapter-spawn process tree for the life of a session. A workspace\n * does NOT get `adapterSpawn` confinement for free by setting the top-level\n * `mode` — it must set `adapterSpawn.mode` explicitly. This is deliberate,\n * not an oversight: a misconfigured `command_execute` jail breaks one\n * command's execution (the caller sees a failed tool call and can retry\n * unconfined); a misconfigured adapter-spawn jail breaks the WHOLE session\n * (every tool call, every turn, for as long as the adapter runs) — a\n * strictly larger blast radius that deserves its own explicit opt-in rather\n * than silently inheriting whatever `command_execute` happened to be\n * configured with.\n */\n\nimport { existsSync } from \"node:fs\"\nimport { readFile } from \"node:fs/promises\"\nimport { homedir } from \"node:os\"\nimport { resolve } from \"node:path\"\n\nexport type SandboxMode = \"off\" | \"workspace\" | \"strict\"\n\n/** Per-workspace config read from `.agentproto/command-sandbox.json`. */\nexport interface CommandSandboxConfig {\n  /**\n   * - `off`       — no confinement (default; today's behavior).\n   * - `workspace` — deny access to the home directory OUTSIDE the workspace\n   *                 (protects ~/.ssh, ~/.aws, credentials, …); system paths\n   *                 stay readable so interpreters still run. Network allowed.\n   * - `strict`    — `workspace` + deny ALL network.\n   */\n  mode: SandboxMode\n  /** Extra absolute paths to grant read access (e.g. a shared cache). */\n  extraReadPaths: string[]\n  /** Network policy. Forced to `deny` when `mode === \"strict\"`. */\n  network: \"deny\" | \"allow\"\n}\n\n/** Inputs the backend needs to build a confinement for one command. */\nexport interface SandboxPolicy {\n  workspace: string\n  extraReadPaths: string[]\n  /**\n   * Extra absolute paths to grant READ+WRITE access, outside the\n   * workspace — e.g. a toolchain's self-managed install directory\n   * (`~/Library/pnpm/.tools`) or a per-spawn scratch dir created before\n   * the wrap (`CLAUDE_CONFIG_DIR`'s mkdtemp'd settings dir). Unlike\n   * `extraReadPaths`, these are also writable. Defaults to `[]` when\n   * omitted by a caller built against the pre-`extraWritePaths` shape.\n   */\n  extraWritePaths?: string[]\n  network: \"deny\" | \"allow\"\n}\n\nexport interface CommandSandbox {\n  readonly id: string\n  /**\n   * Wrap `argv` so the command runs confined, returning the new argv to spawn\n   * (e.g. `[\"sandbox-exec\", \"-p\", <profile>, ...argv]`). Never throws —\n   * sandboxing is best-effort hardening, so an empty argv is returned as-is.\n   */\n  wrap(argv: string[], policy: SandboxPolicy): string[]\n}\n\nconst CONFIG_REL = \".agentproto/command-sandbox.json\"\n\nexport const DEFAULT_SANDBOX_CONFIG: CommandSandboxConfig = {\n  mode: \"off\",\n  extraReadPaths: [],\n  network: \"allow\",\n}\n\n/**\n * Escape hatch: overrides the workspace config file's `mode` when set to a\n * valid `SandboxMode`, without editing the tracked `.agentproto/\n * command-sandbox.json`. Two directions this matters: forcing `off` when a\n * workspace has opted into `workspace`/`strict` but one call legitimately\n * needs broad access (e.g. a one-off `pnpm install`), or forcing `workspace`/\n * `strict` on for a session/CI run without committing a config file. Any\n * other value (unset, typo, empty) is ignored and the file/default applies.\n */\nexport const COMMAND_SANDBOX_MODE_ENV = \"AGENTPROTO_COMMAND_SANDBOX_MODE\"\n\n/**\n * Load + normalize the per-workspace sandbox config. Missing file, bad JSON, or\n * an unknown mode all fall back to `off` (fail-open on config, not on\n * confinement — a broken config must not silently pretend to sandbox; that's\n * surfaced by the caller when a mode is set but no backend exists).\n * `COMMAND_SANDBOX_MODE_ENV`, when set to a valid mode, overrides whatever the\n * file (or the default) resolved to.\n */\nexport async function loadSandboxConfig(\n  workspace: string,\n): Promise<CommandSandboxConfig> {\n  const path = resolve(workspace, CONFIG_REL)\n  let resolved = DEFAULT_SANDBOX_CONFIG\n  if (existsSync(path)) {\n    try {\n      const parsed = JSON.parse(\n        await readFile(path, \"utf8\"),\n      ) as Partial<CommandSandboxConfig>\n      const mode: SandboxMode =\n        parsed.mode === \"workspace\" || parsed.mode === \"strict\"\n          ? parsed.mode\n          : \"off\"\n      const extraReadPaths = Array.isArray(parsed.extraReadPaths)\n        ? parsed.extraReadPaths.filter((x): x is string => typeof x === \"string\")\n        : []\n      // strict implies network deny; workspace honors the field (default allow).\n      const network: \"deny\" | \"allow\" =\n        mode === \"strict\" || parsed.network === \"deny\" ? \"deny\" : \"allow\"\n      resolved = { mode, extraReadPaths, network }\n    } catch {\n      resolved = DEFAULT_SANDBOX_CONFIG\n    }\n  }\n  const envMode = process.env[COMMAND_SANDBOX_MODE_ENV]\n  if (envMode === \"off\" || envMode === \"workspace\" || envMode === \"strict\") {\n    return {\n      ...resolved,\n      mode: envMode,\n      network: envMode === \"strict\" ? \"deny\" : resolved.network,\n    }\n  }\n  return resolved\n}\n\n/**\n * Confinement config for the ADAPTER-SPAWN axis — a distinct, explicit\n * `adapterSpawn` key in the same `.agentproto/command-sandbox.json` file\n * `loadSandboxConfig` reads (see the module doc for why this isn't just the\n * top-level `mode`).\n */\nexport interface AdapterSpawnSandboxConfig {\n  /**\n   * `undefined` ⇒ the file has no `adapterSpawn` key at all (or no file\n   * exists) — this axis was never engaged by the workspace, so a caller\n   * that also passed no explicit mode stays silently unconfined (today's\n   * behavior). A resolved `SandboxMode`, INCLUDING explicit `\"off\"`, means\n   * the workspace (or `ADAPTER_COMMAND_SANDBOX_MODE_ENV`) engaged this axis\n   * on purpose.\n   */\n  mode: SandboxMode | undefined\n  /** Extra read-only paths merged with the adapter-spawn wrapper's own\n   *  built-in toolchain defaults (`defaultToolchainReadPaths()`). */\n  extraReadPaths: string[]\n  /** Extra read+write paths merged with the built-in toolchain defaults\n   *  (`defaultToolchainWritePaths()`). */\n  extraWritePaths: string[]\n  /** Network policy. Forced to `deny` when `mode === \"strict\"`. */\n  network: \"deny\" | \"allow\"\n}\n\nconst DEFAULT_ADAPTER_SPAWN_SANDBOX_CONFIG: AdapterSpawnSandboxConfig = {\n  mode: undefined,\n  extraReadPaths: [],\n  extraWritePaths: [],\n  network: \"allow\",\n}\n\n/**\n * Escape hatch for the adapter-spawn axis, mirroring `COMMAND_SANDBOX_MODE_ENV`\n * but kept as a SEPARATE env var rather than reusing it — forcing\n * `command_execute` into `workspace` mode for a CI run should not, as a side\n * effect, also confine every adapter's own process tree (and vice versa).\n */\nexport const ADAPTER_COMMAND_SANDBOX_MODE_ENV =\n  \"AGENTPROTO_ADAPTER_COMMAND_SANDBOX_MODE\"\n\n/**\n * Load + normalize the adapter-spawn confinement config from the `adapterSpawn`\n * key of `.agentproto/command-sandbox.json`. Missing file / bad JSON / no\n * `adapterSpawn` key ⇒ `mode: undefined` (axis untouched, NOT `\"off\"` — see\n * `AdapterSpawnSandboxConfig.mode`'s doc for why that distinction matters).\n * An `adapterSpawn` key that IS present but carries an unknown/missing `mode`\n * resolves to `\"off\"`, matching `loadSandboxConfig`'s fail-open-on-config\n * posture. `ADAPTER_COMMAND_SANDBOX_MODE_ENV`, when set to a valid mode,\n * overrides whatever the file resolved to.\n */\nexport async function loadAdapterSpawnSandboxConfig(\n  workspace: string,\n): Promise<AdapterSpawnSandboxConfig> {\n  const path = resolve(workspace, CONFIG_REL)\n  let resolved = DEFAULT_ADAPTER_SPAWN_SANDBOX_CONFIG\n  if (existsSync(path)) {\n    try {\n      const parsed = JSON.parse(await readFile(path, \"utf8\")) as {\n        adapterSpawn?: Record<string, unknown>\n      }\n      const raw = parsed.adapterSpawn\n      if (raw && typeof raw === \"object\") {\n        const mode: SandboxMode =\n          raw.mode === \"workspace\" || raw.mode === \"strict\" || raw.mode === \"off\"\n            ? raw.mode\n            : \"off\"\n        const extraReadPaths = Array.isArray(raw.extraReadPaths)\n          ? raw.extraReadPaths.filter((x): x is string => typeof x === \"string\")\n          : []\n        const extraWritePaths = Array.isArray(raw.extraWritePaths)\n          ? raw.extraWritePaths.filter((x): x is string => typeof x === \"string\")\n          : []\n        const network: \"deny\" | \"allow\" =\n          mode === \"strict\" || raw.network === \"deny\" ? \"deny\" : \"allow\"\n        resolved = { mode, extraReadPaths, extraWritePaths, network }\n      }\n    } catch {\n      resolved = DEFAULT_ADAPTER_SPAWN_SANDBOX_CONFIG\n    }\n  }\n  const envMode = process.env[ADAPTER_COMMAND_SANDBOX_MODE_ENV]\n  if (envMode === \"off\" || envMode === \"workspace\" || envMode === \"strict\") {\n    return {\n      ...resolved,\n      mode: envMode,\n      network: envMode === \"strict\" ? \"deny\" : resolved.network,\n    }\n  }\n  return resolved\n}\n\n/** Escape a path for embedding in an SBPL string literal. */\nfunction sbplQuote(p: string): string {\n  return p.replace(/\\\\/g, \"\\\\\\\\\").replace(/\"/g, '\\\\\"')\n}\n\n/**\n * Build a macOS Seatbelt (SBPL) profile for the policy. Strategy: start\n * permissive (`allow default`) so interpreters can read their runtime + system\n * libraries, then DENY the whole home directory (the crown jewels — ~/.ssh,\n * ~/.aws, credentials), then RE-ALLOW the workspace subpath, any explicit\n * extra read paths (read-only), and any explicit extra write paths\n * (read+write — e.g. a toolchain's self-managed install dir living under\n * `$HOME`, which a read-only re-allow can't satisfy). SBPL is\n * last-match-wins, so the workspace/extra re-allows override the home deny.\n * Strict mode also denies all network. Exported for testing.\n */\nexport function buildSeatbeltProfile(policy: SandboxPolicy): string {\n  const home = homedir()\n  const ws = resolve(policy.workspace)\n  const parts = [\n    \"(version 1)\",\n    \"(allow default)\",\n    `(deny file-read* file-write* (subpath \"${sbplQuote(home)}\"))`,\n    // Metadata-only re-allow across all of $HOME (stat/lstat — existence,\n    // permissions, mtime; NOT directory listing or file content, both of\n    // which need file-read-data and stay denied). Empirically required\n    // (2026-07): npm/npx's arborist `lstat`s ancestor directories while\n    // resolving config/paths and hard-fails with EPERM on $HOME itself\n    // otherwise — even for a workspace-cwd invocation that never reads\n    // any OTHER file under $HOME. Without this, no npx-spawned adapter\n    // (claude-agent-acp included) can even start under `workspace` mode.\n    `(allow file-read-metadata (subpath \"${sbplQuote(home)}\"))`,\n    `(allow file-read* file-write* (subpath \"${sbplQuote(ws)}\"))`,\n  ]\n  for (const extra of policy.extraReadPaths) {\n    parts.push(`(allow file-read* (subpath \"${sbplQuote(resolve(extra))}\"))`)\n  }\n  for (const extra of policy.extraWritePaths ?? []) {\n    parts.push(\n      `(allow file-read* file-write* (subpath \"${sbplQuote(resolve(extra))}\"))`,\n    )\n  }\n  if (policy.network === \"deny\") parts.push(\"(deny network*)\")\n  return parts.join(\"\")\n}\n\n/** macOS Seatbelt backend — wraps argv as `sandbox-exec -p <profile> …`. */\nexport const seatbeltSandbox: CommandSandbox = {\n  id: \"seatbelt\",\n  wrap(argv, policy) {\n    if (argv.length === 0) return argv\n    return [\"sandbox-exec\", \"-p\", buildSeatbeltProfile(policy), ...argv]\n  },\n}\n\n/** Read-only system directories bubblewrap binds so interpreters find their\n *  binaries + shared libraries. `--ro-bind-try` skips any that don't exist on\n *  the distro (e.g. no `/lib64` on some), so the same list is portable. */\nconst BWRAP_SYSTEM_DIRS: readonly string[] = [\n  \"/usr\",\n  \"/usr/local\",\n  \"/bin\",\n  \"/sbin\",\n  \"/lib\",\n  \"/lib64\",\n  \"/etc\",\n  \"/opt\",\n]\n\n/**\n * Build the bubblewrap argv (everything after `bwrap`). Unlike Seatbelt's\n * \"deny home except workspace\", bwrap is allowlist-by-construction: ONLY the\n * paths bound here are visible, so `$HOME` secrets (~/.ssh, credentials) are\n * simply absent from the mount namespace. System dirs are read-only, the\n * workspace + extra reads are bound read-only, extra writes are bound\n * read-write (`--bind-try`, not `--ro-bind-try` — e.g. a toolchain's\n * self-managed install dir, or a per-spawn scratch dir that may not exist yet\n * when the argv is built), and strict mode adds `--unshare-net` for an\n * isolated (no-connectivity) network namespace. Exported for testing.\n *\n * Empirically validated (2026-07, ubuntu container): workspace reads succeed,\n * `~/.ssh` reads fail (invisible), and `--unshare-net` makes connects fail with\n * ENETUNREACH.\n */\nexport function buildBwrapArgs(argv: string[], policy: SandboxPolicy): string[] {\n  const ws = resolve(policy.workspace)\n  const out: string[] = [\n    \"--die-with-parent\",\n    \"--proc\",\n    \"/proc\",\n    \"--dev\",\n    \"/dev\",\n    \"--tmpfs\",\n    \"/tmp\",\n  ]\n  for (const d of BWRAP_SYSTEM_DIRS) out.push(\"--ro-bind-try\", d, d)\n  out.push(\"--bind\", ws, ws)\n  for (const extra of policy.extraReadPaths) {\n    const p = resolve(extra)\n    out.push(\"--ro-bind-try\", p, p)\n  }\n  for (const extra of policy.extraWritePaths ?? []) {\n    const p = resolve(extra)\n    out.push(\"--bind-try\", p, p)\n  }\n  if (policy.network === \"deny\") out.push(\"--unshare-net\")\n  out.push(\"--\", ...argv)\n  return out\n}\n\n/** Linux bubblewrap backend — wraps argv as `bwrap <binds> -- …`. */\nexport const bwrapSandbox: CommandSandbox = {\n  id: \"bwrap\",\n  wrap(argv, policy) {\n    if (argv.length === 0) return argv\n    return [\"bwrap\", ...buildBwrapArgs(argv, policy)]\n  },\n}\n\n/** Absolute path to a `bwrap` binary, or null when bubblewrap isn't installed. */\nfunction bwrapAvailable(): boolean {\n  return (\n    existsSync(\"/usr/bin/bwrap\") ||\n    existsSync(\"/bin/bwrap\") ||\n    existsSync(\"/usr/local/bin/bwrap\")\n  )\n}\n\n/**\n * The confinement backend available on this host, or `null` when none applies\n * (macOS → Seatbelt, Linux → bubblewrap when installed, Windows unsupported).\n * Callers warn when a sandbox mode is configured but this returns null — so a\n * missing backend never silently pretends to confine.\n */\nexport function resolveCommandSandbox(): CommandSandbox | null {\n  if (process.platform === \"darwin\" && existsSync(\"/usr/bin/sandbox-exec\")) {\n    return seatbeltSandbox\n  }\n  if (process.platform === \"linux\" && bwrapAvailable()) {\n    return bwrapSandbox\n  }\n  return null\n}\n"]}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@agentproto/command-sandbox",
+  "version": "0.2.0",
+  "description": "@agentproto/command-sandbox — OS-level process confinement (macOS Seatbelt / Linux bubblewrap) for a spawned argv. Extracted so both @agentproto/runtime's command_execute tool and @agentproto/driver-agent-cli's adapter-spawn can wrap a child process through the same policy/backends without a circular package dependency.",
+  "keywords": [
+    "agentproto",
+    "sandbox",
+    "seatbelt",
+    "bubblewrap",
+    "confinement",
+    "open-standard",
+    "agentic"
+  ],
+  "homepage": "https://agentproto.sh",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentproto/ts",
+    "directory": "packages/command-sandbox"
+  },
+  "bugs": {
+    "url": "https://github.com/agentproto/ts/issues"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@agentproto/tooling": "0.1.0-alpha.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}