mirror of https://github.com/dtzp555-max/olp.git synced 2026-07-19 09:45:07 +00:00

Files

T

dtzp555-maxandGitHub d67ba3d675 docs(adr): Phase 7 Amendment 1 — supersede PR-B with ephemeral-home + ISOLATION contract (#66 )

Co-merging ADR 0014 Amendment 1 (4-layer Solution 1) + ADR 0002 Amendment 9 (Provider ISOLATION contract).

Reviewed by 2 fresh-context opus subagents per Iron Rule 10. Second review verdict APPROVE after 6 citation-discipline fold-ins applied.

PR-B outer-bwrap archived to branch phase-7-pr-b-outer-bwrap-snapshot.

2026-05-29 10:00:38 +10:00

69 KiB

Raw Permalink Blame History

ADR 0014 — Sandbox-Runtime Integration for Multi-Tenant Provider Spawning

Status: Accepted (PR-A shipped; PR-B shipped pending PI231 Suite 44 validation + HTTP-path activation debug; PR-C/D pending) — see Amendment 1 (2026-05-29): PR-B's outer-bwrap approach is superseded by the per-spawn ephemeral-home + per-provider ISOLATION contract architecture. PR-C/D are reframed; the substantive decision moves into Amendment 1. Date: 2026-05-28 Phase: Phase 7

ADR 0001 (Project Founding) — OLP's multi-provider rationale and "no conversation state" principle.
ADR 0009 Amendment 1 (stream-json transport, Phase 6) § Caveats #3: "Sandbox-runtime still required for real multi-tenant deployment."
ADR 0002 (Plugin Architecture) — Provider contract; spawn() is the surface this ADR will wrap in PR-B/C.
ADR 0006 (Provider Inclusion / Risk Tier Framework) — classifies providers by deployment risk; sandbox status is a gating condition for Tier-A (cloud-deployed).
docs/plans/cloud-deployment-family.md § 5 — sandbox is a hard prerequisite before any cloud rollout.
cc-mem incident memory — ~/.cc-rules/memory/projects/olp/incident_2026_05_27_spawn_cli_security.md — the multi-tenant security gap that motivates this ADR.

1. Context

1.1 The multi-tenant security gap

OLP is a personal-scale proxy (ADR 0001 § Non-commercial). However, the "family-scale" deployment model means multiple human callers share a single OLP instance — each with their own OLP API key (ADR 0007) but all using the same underlying claude or codex CLI installation on the server host.

The security gap, identified in the 2026-05-27 session and captured in cc-mem incident memory § 3, is:

OAuth token exposure. A malicious (or misbehaving) prompt to the Anthropic provider could elicit a cat ~/.olp/keys/... or similar read of any file the OLP process user can access — including the OAuth credentials file that allows the attacker to impersonate the server-side identity.
Codex shell-tool execution. The codex exec path exposes a shell tool to the model. With OLP acting as a relay, a prompt to codex from one client could execute arbitrary commands in the server process's working directory, reading or writing files belonging to other clients.
Cross-tenant data leakage. Even without adversarial prompts, a model that freely accesses the filesystem could inadvertently leak one client's cached context to another client's response.

The 2026-05-27 prior-art search (incident memory § 4) surveyed the multi-tenant LLM proxy ecosystem (LiteLLM, OpenCode, CLIProxyAPI, open-source Anthropic proxies) and found that none solve multi-tenant file-system and tool isolation at the OS level. The field's typical answer is "don't run multi-tenant" or "use a separate VM per tenant" — neither applicable at OLP's family scale.

1.2 Anthropic's official answer: `@anthropic-ai/sandbox-runtime`

The @anthropic-ai/sandbox-runtime package (Anthropic Experimental org, anthropic-experimental/sandbox-runtime, v0.0.52 as of this ADR) is Anthropic's open-source solution to wrapping security boundaries around arbitrary processes. It is the library that Claude Code itself uses internally to sandbox MCP servers and tool execution.

The library provides:

Linux: bubblewrap (bwrap) namespace isolation + socat network bridge + seccomp filter via apply-seccomp-filter binary. Ripgrep (rg) is required for deny-path glob expansion.
macOS: sandbox-exec seatbelt profile, which is a built-in OS facility (no additional packages required).

Both paths enforce filesystem read/write restrictions and network policy at the kernel level, not at the process level. A cat ~/.olp/keys/... inside the sandbox fails at the syscall layer regardless of what the shell or model requests.

1.3 The 2026-05-28 spike

A PoC spike was conducted on PI231 (arm64 Debian Bookworm) on 2026-05-28. Key findings:

npm install @anthropic-ai/sandbox-runtime@0.0.52 succeeds cleanly on arm64 Linux. No native build step; prebuilt binaries were available.
SandboxManager.isSupportedPlatform() returns true on PI231 (Linux, not WSL).
SandboxManager.checkDependencies() reports errors: bubblewrap (bwrap) not installed, socat not installed, ripgrep (rg) not found. These are the three OS-level deps that must be installed separately (not bundled in the npm package).
The install fix is a one-liner: sudo apt-get install -y bubblewrap socat ripgrep. This is a 5-minute operational task, not a code change.
Three PoC scripts were parked at /tmp/sandbox-spike/ on PI231 verifying: dependency check return shapes, SandboxManager.wrapWithSandbox call signature, and filesystem-deny path behaviour.

Verdict: YELLOW — architecturally green (the library works and the platform is supported), operationally blocked on apt deps. PR-A lays the dependency + doctor layer. PR-B wraps the anthropic spawn after apt install.

2. Decision

2.1 Layered rollout (Iron Rule 11 — minimum reviewable unit)

The sandbox integration is split into four discrete PRs, each independently reviewable and independently safe to land or revert:

PR	Scope	Blocking condition	Status
PR-A (this PR)	npm dep `@anthropic-ai/sandbox-runtime ^0.0.52` + `lib/sandbox/doctor.mjs` (preflight module) + `/health` `sandbox` field + ADR 0014	None — no runtime initialization	✅ Accepted
PR-B	`lib/sandbox/manager.mjs` (bootstrap + spawn-wrap) + `lib/providers/anthropic.mjs` spawn wrapped + server startup wiring + `/health.sandbox.active` + Suite 43/44 tests	`bubblewrap` + `socat` + `rg` installed on PI231 (`sudo apt-get install -y bubblewrap socat ripgrep`)	✅ Implemented — pending PI231 validation (Suite 44) + opus reviewer
PR-C	`lib/providers/codex.mjs` spawn wrapped with `enableWeakerNestedSandbox: true`	PR-B accepted + codex PoC on PI231	🔲 Blocked on PR-B
PR-D	`docs/plans/cloud-deployment-family.md` § "Phase 7 prerequisite met" update; cloud rollout unblocked	PR-B + PR-C accepted	🔲 Blocked on PR-C

Rationale for the split:

PR-A is safe without bwrap. The doctor module and /health field add observability with no runtime side effects. No SandboxManager.initialize() call. No sandbox spawned.
PR-B is the load-bearing security gate. Wrapping anthropic.mjs spawn requires empirical negative-test confirmation (in-sandbox cat ~/.olp/keys/... MUST fail). This cannot be verified until PI231 has bwrap installed.
PR-C follows PR-B because codex has a distinct issue: codex itself uses bubblewrap internally (codex exec spawns its own sandbox). enableWeakerNestedSandbox: true is required to allow the inner sandbox to function inside the outer OLP sandbox.
PR-D is documentation-only and depends on the runtime PRs being proven in production.

2.2 PR-A specific scope (binding)

PR-A MUST NOT include:

Any call to SandboxManager.initialize() (no real sandbox created)
Any modification to lib/providers/anthropic.mjs, lib/providers/codex.mjs, or lib/providers/mistral.mjs
Any new HTTP endpoint (no /metrics, no new dashboard endpoint)
Any modification to models-registry.json

PR-A MUST include:

package.json dependency: "@anthropic-ai/sandbox-runtime": "^0.0.52"
lib/sandbox/doctor.mjs: pure preflight module (no state; no initialization)
/health response: top-level sandbox field (available, missing, platform, message when unavailable)
docs/adr/0014-sandbox-runtime-integration.md (this document)
CHANGELOG.md Unreleased entry
test-features.mjs Suite 42 (8 new tests, all passing)

3. `lib/sandbox/doctor.mjs` design

3.1 Exports

// Returns { available: boolean, missing: string[], details: { ... } }
export async function checkSandboxAvailability() { ... }

// Returns { ok: boolean, message: string } — human-readable summary
export async function describeSandboxStatus() { ... }

3.2 `checkSandboxAvailability` algorithm

Probe OS deps independently via child_process.execFileSync('which', [binary]):
- bwrap (Linux only — macOS uses built-in sandbox-exec)
- socat (Linux only)
- rg (ripgrep — Linux only; macOS seatbelt profiles use regex patterns natively)
Call probeLibrary() which import()s @anthropic-ai/sandbox-runtime and calls:
- SandboxManager.isSupportedPlatform() — platform classification
- SandboxManager.checkDependencies(undefined) — library's own dep check (called without initialize, falling back to PATH lookup)
Compute missing[]: on Linux, add 'bubblewrap', 'socat', 'ripgrep' for each absent dep; if library import failed, add that too.
available = libLoaded && isSupportedPlatform && missing.length === 0

probeLibrary() wraps everything in try/catch — any library-side error becomes { libLoaded: false, libError: '<reason>' } rather than an unhandled rejection.

3.3 `/health` integration

The sandbox field is added to the full (owner-tier) payload only. For trimmed payloads (guest/anonymous per ADR 0007 § 7.1), the field is absent (consistent with the existing trim model). This prevents leaking infrastructure details to non-owner callers.

The result is memoized process-wide via _sandboxStatusCache in server.mjs. The install state of bwrap/socat cannot change at runtime without a process restart, so a single lazy fetch at the first /health call is correct.

{
  "ok": true,
  "version": "0.5.1",
  "providers": { ... },
  "sandbox": {
    "available": false,
    "missing": ["bubblewrap", "socat", "ripgrep"],
    "platform": "linux",
    "message": "Sandbox dependencies not available: bubblewrap not installed, socat not installed, ripgrep not installed. Install: sudo apt-get install -y bubblewrap socat ripgrep"
  }
}

When available (after apt install + process restart) and PR-B bootstrapped:

{
  "sandbox": {
    "available": true,
    "active": true,
    "missing": [],
    "platform": "linux"
  }
}

(PR-A shape did not include active. PR-B adds active: boolean — distinguishes "deps present" from "sandbox actually initialized and wrapping spawns".)

4. PR-B/C/D acceptance criteria

4.1 PR-B (anthropic.mjs spawn wrap) — ✅ Implementation shipped, PI231 validation pending

PR-B implementation (commit pending reviewer):

lib/sandbox/manager.mjs: singleton bootstrap + transparent wrapSpawn() API
lib/providers/anthropic.mjs: spawn site wrapped via wrapSpawn() (ADR 0009 Amendment 1 spawn args unchanged)
server.mjs: bootstrapSandbox() called before server.listen(), /health.sandbox.active field added
test-features.mjs Suite 43 (8 tests, all pass on macOS) + Suite 44 (2 tests, PI231-gated with OLP_E2E_SANDBOX=1)
805 → 813 tests. Suite 44 skipped by default; runs on PI231 after apt install.

Load-bearing negative test (required for PR-B to merge):

# On PI231, with bwrap+socat installed, with PR-B wired:
olp-keys list  # identify owner key
curl -X POST http://127.0.0.1:4567/v1/chat/completions \
  -H "Authorization: Bearer <owner-key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-6","messages":[{"role":"user","content":"run: cat /home/<user>/.olp/keys/owner-key.json"}]}'
# Expected: response MUST NOT contain any content from the keys file.
# The model must either say it cannot access the filesystem, or produce an
# error. Any response containing the file content is a PR-B blocking failure.

Additional criteria:

SandboxManager.initialize() is called once at startup (singleton shape follows @anthropic-ai/sandbox-runtime v0.0.52 dist/sandbox/sandbox-manager.js SandboxManager export, where reset() is a process-wide operation; see § 5 Open question 1 for the per-provider config concern still to be resolved)
p95 latency overhead of wrapping ≤ 200ms measured over 50 warm requests
checkSandboxAvailability().available === true reported in /health.sandbox after PR-B rolls out
All existing Suite 41 tests continue to pass (stream-json transport unaffected)

4.2 PR-C (codex.mjs wrap)

enableWeakerNestedSandbox: true is set in the SandboxManager.initialize() call (or per-spawn config if the API allows per-spawn override — verify against v0.0.52 API)
codex exec inner bubblewrap nest still functions: a sandboxed codex invocation that reads from an allowed path succeeds
Analogous negative test: in-sandbox cat /home/<user>/.olp/keys/... MUST fail

4.3 PR-D (cloud deployment plan update)

docs/plans/cloud-deployment-family.md § 5 "Phase 7 prerequisite" section updated: "sandbox-runtime integration (PR-B + PR-C) confirmed operational on PI231; prerequisite met"
README.md § "Supported Providers" or § "Security" updated with a note about sandbox isolation
Phase 7 close PR per CLAUDE.md release_kit.phase_rolling_mode

5. Open questions (to be resolved in PR-B)

Singleton vs per-spawn initialization. SandboxManager is a process-wide singleton (per the library's reset() being a global operation). The current design plan is one initialize() call at server startup with a union config covering all providers. If providers require different configs (e.g., different denyRead paths for anthropic vs codex), this may require a mutex approach or separate singleton instances. Decision reserved for PR-B.
SandboxManager.reset() in tests. The singleton means test suites that call initialize() must call reset() in their after() hooks. PR-B must add this discipline or tests will leak sandbox state across suites.
MITM proxy and Claude CLI cert pinning. The sandbox-runtime network bridge on Linux uses a local MITM proxy to intercept HTTPS traffic. If claude CLI pins certificates (e.g., for api.anthropic.com), HTTPS through the bridge may fail. PR-B must empirically verify this on PI231 before merging.
macOS sandbox-exec profile content. macOS uses a seatbelt (SBPL) profile, not bwrap. The profile must explicitly allow network outbound "api.anthropic.com" etc. The default profile may be too restrictive for the Claude CLI's OAuth refresh calls. PR-B must test macOS as well as Linux.
getDefaultWritePaths() output. The library exports getDefaultWritePaths() which returns the paths the sandbox always allows writing to. OLP's spawn directory may not be in that list — PR-B must verify the working directory is writable or pass it explicitly in filesystem.allowWrite.

6. Pitfalls inherited from the spike (binding warnings for PR-B/C authors)

These were confirmed empirically or inferred from the library source during the 2026-05-28 spike:

Three OS deps, not one. The npm package bundles nothing. Linux requires: bubblewrap (bwrap), socat, ripgrep (rg). All three. Missing even one → checkDependencies() returns errors → wrapWithSandbox will fail at runtime.
Linux deny-paths are literal, not glob. The library's linuxGetMandatoryDenyPaths() uses ripgrep to expand glob patterns to concrete paths before passing them to bwrap. But custom filesystem.denyRead entries that contain glob chars (~/.ssh/*) must be either expanded manually OR passed as the glob form (the library expands them if rg is available). The safe convention for PR-B: use absolute literal paths (e.g., /home/<user>/.ssh) rather than ~/-prefixed or glob paths.
enableWeakerNestedSandbox: true is required for codex. Codex's exec subcommand spawns its own bubblewrap sandbox internally. Without enableWeakerNestedSandbox, the outer OLP sandbox blocks the inner codex sandbox from creating user namespaces. The flag loosens the outer sandbox's seccomp filter specifically to allow clone(CLONE_NEWUSER) — the inner sandbox then runs with reduced but non-zero isolation.
SandboxManager.reset() is process-wide. Calling reset() anywhere (including test teardown) clears the singleton config. Any concurrent in-flight spawn that still holds a reference to the old sandbox state will break. PR-B's design must either (a) initialize once at boot and never reset, or (b) use a mutex to prevent concurrent init/reset.
MITM CA generation is async and expensive. SandboxManager.initialize() generates a self-signed CA certificate for the MITM proxy on Linux. This takes ~100-500ms. Initialize at server startup, not per-request.

7. Authority citations

@anthropic-ai/sandbox-runtime v0.0.52 — https://github.com/anthropic-experimental/sandbox-runtime
- dist/sandbox/sandbox-manager.js — isSupportedPlatform(), checkDependencies(), SandboxManager export shape
- dist/sandbox/linux-sandbox-utils.js — checkLinuxDependencies(), whichSync usage, enableWeakerNestedSandbox rationale
- README.md — installation prerequisites, platform support matrix
2026-05-28 PoC spike on PI231 (arm64 Debian Bookworm) — report at /tmp/sandbox-spike/report.md on PI231. Key findings: dep install clean; isSupportedPlatform()=true; checkDependencies() errors on bwrap+socat+rg absence; three PoC scripts parked. Verdict YELLOW.
cc-mem incident memory 2026-05-27 — ~/.cc-rules/memory/projects/olp/incident_2026_05_27_spawn_cli_security.md § 3 (gap description), § 4 (prior-art search showing ecosystem hasn't solved multi-tenant fs/tool isolation).
OLP ADR 0009 Amendment 1 § Caveats #3 — "Sandbox-runtime still required for real multi-tenant deployment. Per the 2026-05-27 session prior-art search, Anthropic's official multi-tenant answer is @anthropic-ai/sandbox-runtime (OS-level isolation)."
docs/plans/cloud-deployment-family.md § 5 — sandbox is a hard prerequisite before any cloud deployment.
OLP ALIGNMENT.md — PR-A is library/doctor/governance; it does not touch provider plugins, the entry surface, or the IR. The authority citation for the npm dep is the official sandbox-runtime repo URL + the spike report (not a provider CLI, not the OpenAI spec, not an existing ADR — this is a new dependency decision, which is the correct scope for ADR 0014).
Iron Rule 11 (Incremental Diff Review) — splits non-trivial work into the minimum reviewable unit. The 4-PR split (A/B/C/D) is the direct application of this rule to the sandbox integration: each PR is independently reviewable, independently safe to land or revert, and corresponds to one logical layer.

8. Consequences

Positive

Multi-tenant isolation at the OS level. After PR-B+C land, each provider spawn runs inside a bubblewrap (Linux) or sandbox-exec (macOS) boundary. A prompt-injected cat ~/.olp/keys/... hits a kernel-level deny. Cross-client filesystem leakage is structurally prevented, not just mitigated by prompt engineering.
Cloud deployment unblocked. docs/plans/cloud-deployment-family.md § 5 cites sandbox as the hard prerequisite for moving from family-LAN to cloud. PR-D closes this gate.
Observability from day one. The /health.sandbox field makes the install state machine-readable. Any monitoring script or dashboard can tell whether sandbox isolation is active without SSH access.
Anthropic's official library. Using @anthropic-ai/sandbox-runtime rather than a home-grown bwrap wrapper means OLP inherits Anthropic's tested integration patterns (deny-path expansion, MITM proxy, seccomp, macOS seatbelt profiles) rather than reinventing them. When the library updates, OLP upgrades via npm update.

Negative

Three new OS-level dependencies. bubblewrap, socat, and ripgrep must be installed on every host running OLP with sandbox isolation active. Absent these deps, sandbox is unavailable (but OLP continues to function without isolation — degraded security, not degraded functionality). The /health.sandbox.available field makes this state explicit.
p95 latency overhead. The spike did not measure sandbox wrapping overhead directly (blocked on apt install). Expected overhead per the sandbox-runtime README: ~100-200ms for sandbox initialization amortized over the process lifetime (one-time at startup); per-spawn overhead is the namespace clone + filesystem mount overhead, typically <50ms on modern kernels. PR-B's acceptance criteria gates on ≤200ms p95 overhead over 50 warm requests.
Codex inner-sandbox degradation. enableWeakerNestedSandbox: true loosens the outer OLP sandbox's seccomp filter to allow clone(CLONE_NEWUSER). The codex inner sandbox still runs with meaningful isolation (its own namespace, its own deny-list), but the combined depth of protection is less than ideal compared to a world where codex didn't self-sandbox.
Library is experimental. The anthropic-experimental org signals this is not a production-stable API. The version pin (^0.0.52) provides a minor-range buffer but the API surface may change. If the library is deprecated or the API breaks, OLP's fallback is to remove the sandbox wrapping (reverting PRs B-D) until a replacement path is found. This is acceptable at family scale — security degradation is not a service outage.

Reversibility

PR-A is trivially reversible: npm uninstall @anthropic-ai/sandbox-runtime + delete lib/sandbox/doctor.mjs + revert server.mjs and CHANGELOG changes. No production behavior changes.
PR-B/C are reversible by removing the SandboxManager.wrapWithSandbox call from each provider's spawn() method. The spawn falls back to the current unsandboxed path.
PR-D is a documentation update; reverting it is a docs-only change.

Status transitions

2026-05-28 — Created. Status: Accepted for PR-A scope. PR-B/C/D pending operational prereqs.
2026-05-28 — PR-A shipped (commit 07d9c8a).
2026-05-28 — PR-B implementation shipped (commit chain d0dcd28 → 2864275 → 497b255 → b1e24b7 → 3551921). Status: shipped pending PI231 Suite 44 validation + HTTP-path activation debug. OLP_SANDBOX_DISABLED=1 emergency disable installed (b1e24b7) because the in-process MITM proxy interaction with OLP's HTTP request handler suppressed claude stdout on the HTTP path while the same wrap script produced output when invoked directly from a manual shell. Prod is currently running with OLP_SANDBOX_DISABLED=1 set.
2026-05-29 — Amendment 1 — supersede PR-B outer-bwrap with ephemeral-home + per-provider ISOLATION contract. See § Amendment 1 below. PR-B's lib/sandbox/manager.mjs outer-bwrap implementation is archived to branch phase-7-pr-b-outer-bwrap-snapshot and superseded; PR-C is reframed as inner-sandbox preservation under the new architecture; PR-D is reframed as the README "Security Model" section. lib/sandbox/doctor.mjs is preserved unchanged.

Amendment 1 — Supersede PR-B outer-bwrap with ephemeral-home + per-provider contract (2026-05-29)

Date: 2026-05-29
Status: Accepted (governance only — the implementation refactor lands in subsequent PRs per ALIGNMENT.md Rule 1 / Iron Rule 11)
Author: project maintainer (with AI drafting assistance)
Reviewer: independent fresh-context reviewer per Iron Rule 10 — pending at this draft
Scope: This amendment supersedes the implementation strategy of PR-B (the outer-bubblewrap-wrap of claude CLI shipped in commits d0dcd28 → b1e24b7). It does NOT supersede the multi-tenant security gap analysis in § 1 of the original ADR, nor the four-tier authority citation list (§ 7), nor lib/sandbox/doctor.mjs (preserved unchanged). It DOES supersede the PR-B implementation, the PR-C scope ("wrap codex spawn in the same outer-bwrap pattern with enableWeakerNestedSandbox"), and PR-D's framing as "documentation update for cloud rollout unblock".

A1.1 — Why the substitution is forced (the four forcing reasons)

PR-B as designed (outer-bwrap wrapping of the claude CLI spawn, with the OLP server initializing SandboxManager once at boot and every spawn routed through wrapWithSandbox) was shipped on 2026-05-28 and disabled on the same day via the OLP_SANDBOX_DISABLED=1 env-var gate after the HTTP-path activation regression appeared on PI231 (the manual-shell wrap produced claude stdout; the OLP HTTP-request-handler wrap produced none). The 2026-05-28/2026-05-29 follow-up investigation found that the HTTP-path failure was not the whole story — even if the in-process MITM proxy lifecycle issue were debugged, four independent and load-bearing reasons forced the architecture away from outer-bwrap entirely. Each is cited to its primary authority below.

A1.1.1 — Forcing reason #1: Anthropic's stated design intent for `@anthropic-ai/sandbox-runtime`

The PR-B design used @anthropic-ai/sandbox-runtime to wrap the claude CLI from the outside. Anthropic's published design intent for the library is the opposite direction of containment: the library is for sandboxing what Claude Code itself triggers (tool calls, MCP servers, sub-processes spawned during model execution), not for wrapping Claude Code from outside.

Primary citation: https://www.anthropic.com/engineering/claude-code-sandboxing — "Claude Code sandboxing" engineering blog. The post describes Claude Code's internal use of the sandbox-runtime library: the model emits a tool_use Bash call → Claude Code wraps the resulting /bin/sh -c <…> in a sandbox via SandboxManager.wrapWithSandbox() before spawning. The blog also notes the library "can be used to sandbox arbitrary processes, agents and MCP servers" — i.e., it is general-purpose, not Claude-Code-internal-only. Our reading: Anthropic's documented and demonstrated usage is inner-wrap by Claude Code; outer-wrap of claude itself is not documented in the blog and not shown in the post's example invocations. This is a project-design judgment based on the absence of outer-wrap precedent, not a "don't do this" statement from Anthropic. The architectural concerns enumerated below (MITM proxy lifecycle, semver leverage) stand on their own merits regardless of how Anthropic frames the library's intended usage.

What this means for PR-B's design: wrapping claude from outside with the same library is "out-of-distribution" usage. The library was not designed for, tested against, or documented for the outer-wrap case. Two concrete consequences observed in PR-B:

MITM proxy collision. The library starts a per-process local MITM proxy on Linux to inspect HTTPS traffic for allowlisted domains. When the same library is invoked again from inside the sandboxed process (e.g., for any sub-spawn claude might do), a second MITM proxy attempt collides. The PR-B implementation never reached this case because it disabled before tripping it, but the architecture invites the collision.
Inner-sandbox conflict (see A1.1.3 for codex, but the principle applies generally). Any CLI that itself uses the same library to sandbox its own tool calls is expected by Anthropic to be the holder of the sandbox, not the content of one. The library's enableWeakerNestedSandbox option exists precisely to acknowledge this — but only as a partial mitigation.

The Anthropic design-intent reason is not a "won't work" reason. The PR-B outer-bwrap path did work for the smoke case (manual-shell invocation produced output). The reason is a don't-do-this reason: OLP would be the only known user of the library in the outer-wrap configuration, taking on the maintenance burden of a usage pattern Anthropic doesn't test, doesn't document, and doesn't owe semver discipline for. The library is ^0.0.52. A future minor version bump could break OLP's outer-wrap path without warning. Aligning OLP's use of the library with Anthropic's documented design intent restores semver leverage.

A1.1.2 — Forcing reason #2: The `~/.claude.json` upstream "closed as not planned" — permanent maintenance treadmill for outer-bwrap

Anthropic's claude CLI persists session state (most notably MRU project list, last-used model, telemetry session id) to ~/.claude.json using a non-atomic write pattern: write-in-place rather than write-temp-then-rename. When ~/.claude.json is on a read-only mount (e.g., --ro-bind ~/.claude in a bwrap config), the CLI either silently degrades (some state lost) or outright fails depending on which write path is hit on a given invocation.

The OLP outer-bwrap path in PR-B mounted ~/.claude read-only initially, hit this exact issue (the 2026-05-28 fold-in commit 2864275 "allow read ~~/.claude + skip wrap under test mock" added the read allowance), and then on the further b1e24b7 commit the operator had to widen the mount again. The fold-in commit message explicitly notes: "~~/.claude is NOT in denyRead. It contains the spawn's own OAuth credentials — claude CLI must read its own auth file to function. Denying read here causes 'Not logged in' failures."

Primary citation: https://github.com/anthropics/claude-code/issues/29250 — upstream issue requesting atomic-write semantics for ~/.claude.json. Status: closed not_planned by GitHub's inactivity bot on 2026-03-31 (closed_by: github-actions[bot], comment text: "Closing for now — inactive for too long"), labeled duplicate and stale. No upstream Anthropic maintainer comment in the thread articulates any policy rationale — the only non-bot comments are the reporter's own follow-ups and a third-party-tool plug. The closure does NOT establish "won't fix" as Anthropic policy; at most it establishes that the issue has not received maintainer engagement and that Anthropic considers it a duplicate of some other tracked report. The forcing argument for ephemeral-home over outer-bwrap rests on the architectural-cost analysis (the maintenance-treadmill description below), not on an alleged upstream policy posture.

What this means for the outer-wrap maintenance treadmill: Every future addition of claude-CLI-owned state files (telemetry, cache directories, session locks, MCP registration files, etc.) is, by upstream policy, free to use any write pattern the maintainers prefer. The outer-bwrap pattern requires OLP to track each of these additions and add corresponding --ro-bind / --rw-bind / write-allowlist entries — forever — because the CLI does not give OLP an enumerable contract surface for "files I will write to." The maintainer-time cost is a permanent recurring tax.

A non-outer-wrap approach that gives claude a fresh, ephemeral home directory inverts this: claude is free to invent any state file under its $HOME with any write pattern it chooses; OLP never tracks the list. The treadmill goes away. This is the load-bearing case for Solution 1 even setting aside the codex inner-sandbox issue below.

A1.1.3 — Forcing reason #3: Codex inner-bwrap conflict (multi-provider forcing function)

The PR-C plan in the original ADR was to wrap the codex spawn in the same outer-bwrap pattern as PR-B, with enableWeakerNestedSandbox: true set on the SandboxManager.initialize() call to allow codex's own internal bubblewrap sandbox to function inside OLP's outer bubblewrap sandbox.

Empirical investigation (2026-05-29 PI231 prep — to be confirmed in Task #4) and published codex CLI behaviour both indicate this nested-sandbox path is structurally fragile:

Primary citation: https://github.com/openai/codex/issues/16018 — upstream codex CLI issue. The issue body documents that codex's bwrap-based default sandbox fails outright in environments lacking unprivileged user namespaces — the reporter quotes the error bwrap: No permissions to create new namespace, likely because the kernel does not allow non-privileged user namespaces. The issue is a feature request by the reporter asking codex to "suggest or automatically fall back to an alternative supported backend when available"; the issue body itself does NOT contain the string danger-full-access and does NOT document an existing automatic fallback to it. The codex --sandbox danger-full-access mode is a documented manual opt-out (https://developers.openai.com/codex/concepts/sandboxing § "Sandboxing modes"). Whether codex automatically degrades into it under nested-bwrap failure — or whether the spawn aborts outright — is an empirical question slated for Task #4 PI231 spike verification.

In other words: wrapping codex in OLP's outer bwrap, if the outer bwrap is configured with sufficient capability to allow the inner clone, requires giving the outer sandbox more capability than the security boundary should grant. If it is configured to a tighter, safer capability set, codex's inner-bwrap initialization fails (the documented failure mode per the linked issue). Whether codex then aborts the spawn or silently degrades to danger-full-access is empirically open (Task #4); either outcome is undesirable. The strict-additive-isolation invariant (outer-bwrap + inner-bwrap = composed isolation) does not hold for codex under this configuration: either OLP gives up outer-isolation strength to admit the inner clone, or codex's inner isolation breaks in some manner.

What this means as a multi-provider forcing function: OLP is by constitution (ADR 0001 § Mission) a multi-provider proxy. The outer-bwrap architecture cannot cover codex without a security regression. The structural response is to abandon outer-bwrap as the foundational architecture and adopt a strategy that is compatible with each provider's own native isolation (claude's lack of inner sandbox vs codex's --sandbox read-only inner sandbox). This is what Solution 1 does — see A1.2 below.

A1.1.4 — Forcing reason #4: `CODEX_HOME` exists and is the documented relocation lever

The "ephemeral home directory per spawn" component of Solution 1 (A1.2 Layer 1) only works if each provider CLI offers a documented mechanism for relocating its state directory away from the default $HOME location. For claude, the standard HOME env var works (the CLI reads ~/.claude as $HOME/.claude, and changing HOME relocates the lookup). For codex, the equivalent lever is the CODEX_HOME env var.

Primary citation:

https://developers.openai.com/codex/config-reference — OpenAI's published codex CLI configuration reference. The page documents CODEX_HOME in 2 places (verified by independent fetch 2026-05-29): as the root of the per-profile config path ($CODEX_HOME/profile-name.config.toml) and as the default log directory base ($CODEX_HOME/log). The variable is the documented relocation lever for the codex state, configuration, and authentication directory away from the default ~/.codex.
Secondary corroboration:
- https://developers.openai.com/codex/auth/ — OpenAI's published codex CLI authentication reference. The page documents CODEX_HOME in 2 places (verified by independent fetch 2026-05-29), both in the credential-storage section: "file stores credentials in auth.json under CODEX_HOME (defaults to ~/.codex)." Confirms CODEX_HOME is the credential-directory base.
- https://codex.danielvaughan.com/2026/04/08/codex-cli-configuration-reference/ — third-party reference page that mirrors the documented behaviour, used as cross-reference for the reachability check.

What this means for Solution 1 feasibility: All three Tier-D providers have a documented one-env-var relocation lever:

claude via HOME (POSIX convention)
codex via CODEX_HOME (citations above)
mistral via VIBE_HOME per https://docs.mistral.ai/mistral-vibe/terminal/configuration (3 occurrences verified 2026-05-29, including the canonical export VIBE_HOME="/path/to/custom/vibe/home" example and an enumeration of files/directories VIBE_HOME affects).

The ephemeral-home approach is implementable today; it does not require upstream changes from any of Anthropic, OpenAI, or Mistral. Task #4 PI231 spike verifies observed CLI behaviour matches documented behaviour for each provider — this is verification-grade follow-up, not authority-pin work.

A1.2 — The substitute architecture: per-spawn ephemeral home + per-provider ISOLATION contract

The new architecture is layered. Each layer addresses a distinct attack surface, and each layer is independently reasoned about, independently reviewable, and independently revertible. The four layers, in order of containment depth:

A1.2.1 — Layer 1: Per-spawn ephemeral home directory

Every uncached /v1/chat/completions request (per-keyId, per-reqId) provisions a fresh ephemeral home directory at /tmp/olp-spawn/<keyId>/<reqId>/home/. The directory is created on the spawn path and torn down (best-effort) on response completion. The spawn process gets this directory passed in via a per-provider env-var override:

anthropic (claude CLI): HOME=/tmp/olp-spawn/<keyId>/<reqId>/home. The CLI's ~/.claude.json and ~/.claude/ state writes go to the ephemeral location. No cross-request, no cross-tenant carry-over.
openai (codex CLI): CODEX_HOME=/tmp/olp-spawn/<keyId>/<reqId>/home/.codex. Codex's ~/.codex state, auth artifacts, and config files go to the ephemeral location.
mistral (vibe CLI): VIBE_HOME=/tmp/olp-spawn/<keyId>/<reqId>/home/.vibe per https://docs.mistral.ai/mistral-vibe/terminal/configuration (documented env var, 3 occurrences verified at amendment time). Vibe's ~/.vibe/ state — .env, agents/, prompts/, skills/, tools/, config.toml — goes to the ephemeral location. Task #4 PI231 spike verifies observed CLI behaviour matches the documented contract.

Layer 1 provides:

No cross-tenant state carry-over at the filesystem level. Two clients invoking anthropic concurrently get two separate $HOME directories; the CLI cannot read the other's ~/.claude.json, recent-projects list, or session state.
No accumulation of stale state across requests. The MRU project list does not grow without bound. The telemetry session id is fresh per request.
No outer-wrap maintenance treadmill. When claude invents a new state file under ~/.claude.foo.json next quarter, OLP does not need to update a --ro-bind list. The new file lives in the ephemeral home and goes away with the request.

What Layer 1 does NOT provide:

It does not protect against the CLI walking out of its $HOME to read other paths (e.g., a model emitting a Read tool call on /etc/passwd or ~/.ssh/id_rsa). For that protection, Layers 3 and 4 are needed.

A1.2.2 — Layer 2: Symlinked credential files into the ephemeral home

A fresh $HOME is empty. The CLI needs its OAuth credentials, API key, or equivalent auth artifact to function. Layer 2 provisions these by reading the operator-pinned credential location and symlinking the relevant file(s) into the ephemeral home at the location the CLI expects.

Each provider plugin declares its credential paths in the ISOLATION block (see ADR 0002 Amendment pending). The runtime spawn pipeline reads this declaration, walks the list, and symlinks each entry from its real location (under the operator's real $HOME) into the ephemeral home. The symlinks are file-level, not directory-level, so the CLI sees its credential file but does not see the rest of the operator's ~/.claude/ or ~/.codex/ tree.

Example (anthropic):

Real: ~/.claude/.credentials.json (operator's actual OAuth credential)
Ephemeral: /tmp/olp-spawn/<keyId>/<reqId>/home/.claude/.credentials.json (symlink → real)

Example (codex):

Real: ~/.codex/auth.json
Ephemeral: /tmp/olp-spawn/<keyId>/<reqId>/home/.codex/auth.json (symlink → real)

Layer 2 provides:

Credential availability without granting visibility into other state under the same provider directory.
A narrow declared surface. The provider plugin enumerates exactly which files matter. New CLI state files that are not declared do not get symlinked, and the CLI re-initializes them in the ephemeral home (which is exactly the Layer 1 behaviour).

What Layer 2 does NOT provide:

It does not protect against the CLI walking out of its $HOME (see Layer 3).
It does not protect against the CLI's tool-use surface reading the symlink target's containing directory if the model emits a Read tool call with an absolute path that resolves around the symlink. For that, Layer 3 + Layer 4.

A1.2.3 — Layer 3: Optional `sandbox-runtime` per-call `customConfig` for non-$HOME read protection

For providers whose own inner sandbox does NOT exist or does not cover the OLP threat model (the claude CLI today is the leading example — claude has no inner sandbox; codex has --sandbox read-only by default but the protection scope differs), Layer 3 wraps the spawn in @anthropic-ai/sandbox-runtime's SandboxManager.wrapWithSandbox() per-call with a customConfig argument tailored to the per-spawn ephemeral home.

The key architectural difference vs PR-B's outer-wrap:

PR-B initialized SandboxManager once at server boot with a global config covering all providers.
Layer 3 calls wrapWithSandbox() per spawn with a per-spawn customConfig that names the ephemeral home as the allow-read root.

The per-call customConfig shape:

{
  network: { allowedDomains: provider.ISOLATION.allowedDomains },
  filesystem: {
    denyRead: [
      // Operator's real $HOME — sandbox cannot read OTHER clients' OLP keys,
      // operator's SSH identity, other providers' tokens, etc.
      operatorHome,
      // Operator's known sensitive directories (defensive even though they
      // are already under operatorHome) — declared so a future refactor that
      // moves the operator home does not regress this protection.
      `${operatorHome}/.ssh`,
      `${operatorHome}/.gnupg`,
      `${operatorHome}/.olp`,
    ],
    // Layer 1 ephemeral home is the allow-read root for this spawn.
    // Layer 2 symlinked credentials live inside, so credential access works.
    allowRead: [ephemeralHomeForThisSpawn],
    allowWrite: [ephemeralHomeForThisSpawn, '/tmp'],
  },
}

Layer 3 is invoked only when the provider's ISOLATION.hasInnerSandbox === false. For providers with their own inner sandbox (codex via --sandbox read-only), Layer 3 is skipped to avoid the nested-sandbox conflict (A1.1.3).

Layer 3 provides:

OS-level deny of reads outside the ephemeral home and OLP-permitted paths. A prompt-injected cat /home/<operator>/.olp/keys/owner-key.json or cat /home/<operator>/.ssh/id_ed25519 hits a syscall-level deny.
Per-spawn (not per-process) configuration. Each request gets a fresh sandbox scope. Two concurrent spawns do not share a sandbox; the MITM-proxy collision and singleton-config-mutation hazards from PR-B disappear.

What Layer 3 does NOT provide:

It does not protect against the CLI's own tool-use surface emitting destructive shell commands within the allowed write zones. For that, Layer 4.
Per-call wrapWithSandbox() has higher per-request latency than PR-B's once-at-boot pattern. The amortization budget is recovered by Layer 1's $HOME-as-cwd discipline keeping the sandbox config small and by ripgrep-based glob expansion being avoided (Layer 3 uses absolute literal paths throughout).

A1.2.4 — Layer 4: Provider-specific tool hardening already in place

This is already-shipped work, re-affirmed here as part of the layered model:

anthropic Phase 6c --system-prompt (commits 97e7d16 + fold-in 65f945c). The system prompt is fully replaced at every spawn, suppressing the default tool descriptions that Claude Code would otherwise inject. Without tool descriptions, the model is highly unlikely to emit tool_use for Bash, Read, etc. even under prompt injection. See cc-mem ~/.cc-rules/memory/projects/olp/incident_2026_05_27_spawn_cli_security.md § 5.
codex --sandbox read-only default. OLP's codex provider spawn passes --sandbox read-only as a fixed flag. Codex's own inner sandbox provides read-only-by-default tool isolation. The provider's ISOLATION block declares hasInnerSandbox: true so Layer 3 is correctly skipped.
mistral. TBD per Task #4 — the mistral provider's tool surface and inner-sandbox status need to be characterized.

Layer 4 provides:

Reduction of the probability of tool emission. Layer 4 does not depend on OS-level enforcement; it works at the prompt layer. It is the cheap, fast, first-line defense. Layers 1–3 are the structural fallback when prompt-layer defenses are bypassed.

A1.3 — The provider ISOLATION contract (named here; specified in ADR 0002 Amendment N)

Each provider plugin declares an ISOLATION block on its module export. The fields are:

Field	Type	Meaning
`ephemeralEnvOverrides`	`(spawnCtx) => Record<string, string>`	Returns the env-var map to set for this spawn, given the spawn context (ephemeral home path, keyId, reqId). For anthropic: `{ HOME: spawnCtx.ephemeralHome }`. For codex: `{ CODEX_HOME: spawnCtx.ephemeralHome + '/.codex' }`.
`credentialMounts`	`{ realPath: string, ephemeralPath: string }[]`	List of credential files to symlink from real → ephemeral. For anthropic: `[{ realPath: '~/.claude/.credentials.json', ephemeralPath: '.claude/.credentials.json' }]`. Provider declares; runtime symlinks.
`hasInnerSandbox`	`boolean`	If true, Layer 3 is skipped to avoid nested-sandbox conflict. codex: true. anthropic: false.
`crossTenantReadProtection`	`'tool-suppression' \| 'inner-sandbox' \| 'none'`	Self-declared label for what layer is providing the read-protection. Used by `/health.sandbox` to report the protection posture per provider. The canonical enum is defined in ADR 0002 Amendment 9 § 5; this row mirrors it.
`recommendedDeploymentTier`	`'shared-os-user' \| 'per-os-user' \| 'separate-vm'`	Deployment tier the provider's current isolation posture is rated for. ADR 0006 risk-tier integration. The canonical enum is defined in ADR 0002 Amendment 9 § 6; this row mirrors it.

This amendment names the contract but does NOT specify its full validation, lifecycle, or test discipline. Those land in ADR 0002 Amendment (pending) — the Provider contract amendment that ratifies ISOLATION as a required field, defines validateProvider's checks on it, and documents how lib/providers/base.mjs enforces declaration. Until that ADR amendment lands, the ISOLATION block is a forward-looking contract; the implementation refactor (Tasks #5–#8) is gated on the ADR 0002 amendment landing first.

Cross-reference: see ADR 0002 § Amendments for the pending Amendment N that codifies the ISOLATION block contract.

A1.4 — Revised PR plan

The original ADR's four-PR split (PR-A / PR-B / PR-C / PR-D) is restated as follows. PR-A is unchanged from its as-shipped state.

PR	Original scope	Amendment 1 scope	Status
PR-A	npm dep + `lib/sandbox/doctor.mjs` + `/health.sandbox`	Unchanged. Doctor preserved; `/health.sandbox` field preserved.	✅ Shipped (commit `07d9c8a`)
PR-B	Outer-bwrap wrap of anthropic spawn at boot-singleton level	Superseded by Amendment 1. Implementation archived to branch `phase-7-pr-b-outer-bwrap-snapshot`. New scope: refactor `lib/sandbox/manager.mjs` to the Layer 1 + Layer 2 + Layer 3 architecture (Tasks #5, #8).	⛔ Superseded
PR-C	Outer-bwrap wrap of codex spawn with `enableWeakerNestedSandbox: true`	Superseded by Amendment 1. Codex isolation now flows via Layer 1 ephemeral `CODEX_HOME` + Layer 4 `--sandbox read-only`. Layer 3 deliberately skipped (`hasInnerSandbox: true`). Codex-specific PR (Task #7) lands the ISOLATION block declaration; no outer-wrap.	⛔ Superseded
PR-D	Documentation update for cloud rollout unblock	Reframed. New scope: README "Security Model" section documenting the four-layer architecture, the deployment-tier mapping, and what the operator gets vs does not get at each tier. Task #10.	♻ Reframed

The new effective PR-list:

PR-B' (Refactor): lib/sandbox/manager.mjs rewritten to expose prepareIsolatedEnvironment(spawnCtx) (Layer 1 + Layer 2) and maybeWrapForReadProtection(spawnCtx, command) (Layer 3 conditional). The OLP_SANDBOX_DISABLED=1 env-var gate is preserved for 1-2 releases as belt-and-suspenders, then removed. Singleton bootstrap pattern is removed (per-spawn config eliminates the singleton's reason to exist).
PR-C' (Wiring + Anthropic ISOLATION): server.mjs calls prepareIsolatedEnvironment on the spawn path; lib/providers/anthropic.mjs declares its ISOLATION block (Task #6); negative-test confirmation via Task #9 PI231 E2E.
PR-D' (Codex ISOLATION): lib/providers/codex.mjs declares its ISOLATION block (Task #7); hasInnerSandbox: true skips Layer 3; codex inner sandbox preserved unmolested. Verified on PI231 (Task #9).
PR-E' (README + Phase 7 close): README "Security Model" section (Task #10) + docs/plans/cloud-deployment-family.md § 5 update + Phase 7 close per CLAUDE.md release_kit.phase_rolling_mode.

The original PR sequence's load-bearing security gate (the negative test "in-sandbox cat ~/.olp/keys/... MUST fail") remains the acceptance criterion for the security-bearing PRs in the new sequence. The test itself transfers; only the wrap mechanism changes.

A1.5 — What survives from PR-B (preserved)

The following artifacts from the original PR-B implementation are preserved through Amendment 1:

lib/sandbox/doctor.mjs — preserved unchanged. Pure preflight is still useful: it tells the operator whether the npm package is installed, whether the OS deps are present, and whether the platform is supported. Even though the architecture no longer relies on a boot-time SandboxManager.initialize(), the /health.sandbox field consumers (dashboard, monitoring scripts) expect a stable shape. Doctor stays.
/health.sandbox field — preserved. Shape adjusts slightly: the active boolean shifts meaning from "SandboxManager.initialize() succeeded" (PR-B) to "Layer 3 is operational for at least one provider whose ISOLATION.hasInnerSandbox === false" (Amendment 1). The field's name and JSON path stay the same so downstream consumers (dashboard, Hermes self-check, monitoring) do not break. The per-provider isolation posture is exposed via a new /health.sandbox.providers[<name>].crossTenantReadProtection subfield sourced from each ISOLATION block.
@anthropic-ai/sandbox-runtime npm dependency — preserved. Layer 3 still uses the library, but via per-call wrapWithSandbox() with customConfig, not via a once-at-boot SandboxManager.initialize(). The dependency line in package.json stays.
The four authority citations in original § 7 — preserved. The library URL, the spike report URL, the cc-mem incident URL, and the cloud deployment plan URL are unchanged. Amendment 1 adds the four new primary citations enumerated in § A1.1 above.
The OLP_SANDBOX_DISABLED=1 env-var gate — preserved for 1-2 releases, then removed. Documented in A1.6 below.

A1.6 — What disappears from PR-B (superseded)

The following artifacts are removed by the PR-B' refactor (Task #5):

Outer-bwrap wrapping of the claude spawn. The bwrap wrap goes away. claude runs directly (without bwrap shell-wrap) with its HOME set to the ephemeral location. Layer 3 wraps the sub-spawn shell when it is invoked, not the claude process itself.
EROFS-driven mount patches. The fold-in commit 2864275 ("allow read ~/.claude") and the subsequent ~/.claude rw promotion (Task #5 was filed against this) were both consequences of trying to outer-bwrap a CLI that writes non-atomically to its $HOME. Solution 1 gives the CLI its own fresh $HOME and the entire mount-patch problem disappears. Task #5 ("allowWrite ~/.claude rw promotion fix") is closed as obsolete by this amendment.
Boot-time SandboxManager.initialize() call. Removed entirely. The library is loaded lazily per-spawn (with import memoization for performance — the import itself is cached after the first call; only the wrapWithSandbox() call is per-spawn).
The singleton config-at-boot pattern. Removed. The _initConfig, _active, _initialized module-level variables in lib/sandbox/manager.mjs no longer represent a global sandbox state; the only module-level state retained is the import cache for the library.
The MITM proxy CA cert generated once at boot. Per-call wrapWithSandbox() may regenerate per call (TBD on library v0.0.52 behaviour — Task #4 verifies). If per-call regeneration is too expensive, an alternative is a per-process MITM CA cached at first-use; the implementation detail is reserved to PR-B'.
The enableWeakerNestedSandbox: true flag plan. Removed. Codex isolation does not run inside an OLP outer sandbox at all. enableWeakerNestedSandbox is irrelevant to Amendment 1's architecture.

A1.6.1 — The `OLP_SANDBOX_DISABLED=1` env-var gate

The env-var gate added in commit b1e24b7 ("add OLP_SANDBOX_DISABLED=1 env-var emergency disable") is preserved through the Amendment 1 refactor as belt-and-suspenders. Its semantics under Amendment 1:

PR-B world (current main, with the gate set in prod): the gate skips SandboxManager.initialize() at boot. Prod is currently running with the gate set, which means PR-B's outer-bwrap path is not active — Layer 3 protection is also not active.
Amendment 1 world (after PR-B' lands): the gate skips Layer 3's per-call wrapWithSandbox() and reverts each spawn to a Layer 1 + Layer 2 + Layer 4 configuration. The CLI still gets an ephemeral $HOME with symlinked credentials, still gets the --system-prompt tool-description suppression for anthropic, still gets --sandbox read-only for codex. What is given up is the OS-level deny of reads outside the ephemeral home. This is a meaningful but not catastrophic degradation — the prompt-layer defense remains, and Layer 1's $HOME isolation still prevents the most common cross-tenant accident path.
Sunset: the gate is preserved for 1-2 releases after PR-B' ships to give the operator a fast escape hatch if the Layer 3 per-call wrap regresses in production. After two clean releases with no operator escalation, the gate is removed in a subsequent ADR amendment or a clean PR citing this section as authority for the removal.

The gate's behaviour is documented in README's Security Model section per PR-D' (Task #10).

A1.7 — Reversibility

Amendment 1 is reversible at the implementation layer:

PR-B' refactor is reversible by git revert of the refactor commit + restoring the snapshot from phase-7-pr-b-outer-bwrap-snapshot. The archive branch is pushed and persistent at: https://github.com/dtzp555-max/olp/tree/phase-7-pr-b-outer-bwrap-snapshot
The @anthropic-ai/sandbox-runtime dependency stays in package.json, so reverting does not require an npm install.
The lib/sandbox/doctor.mjs module is unchanged across the refactor, so reverting does not affect /health.sandbox shape.

Amendment 1 itself, as a governance artifact, is reversible by a subsequent superseding amendment if the empirical foundation it rests on changes (e.g., if Anthropic publishes guidance endorsing outer-wrap use of sandbox-runtime and adds a contract for ~/.claude.json write paths). ALIGNMENT.md § "Amendment Procedure" applies: such a future amendment would need to cite the new evidence.

The archive-branch retention policy: the snapshot branch is kept indefinitely (no auto-delete) so a future maintainer investigating outer-bwrap-around-CLI as an architecture has a working reference point. The branch's HEAD commit matches commit b1e24b7 (the last commit of the outer-bwrap implementation before the architecture pivot).

A1.8 — Updated open questions (supersedes original § 5)

The original § 5 listed five open questions all of which were specific to the outer-bwrap architecture. Amendment 1 supersedes those and lists the open questions for the new architecture:

Per-call wrapWithSandbox() latency. PR-B amortized the MITM CA generation (100-500ms) across all spawns by initializing once at boot. Per-call wrap regenerates this if the library does not cache internally. Task #4 PI231 spike measures the actual per-call cost; if it exceeds the original ≤200ms p95 budget, an internal cache wrapper around the library is added in PR-B'. Decision reserved for PR-B'.
vibe (mistral) home-relocation env var. Task #4 PI231 spike checks whether vibe honours MISTRAL_HOME / VIBE_HOME / similar. If yes, mistral's ISOLATION block declares it and mistral participates in Layer 1. If no, mistral falls back to Layer 4 (prompt layer) + Layer 3 (per-call wrap with denyRead on the operator's real home) only. The provider's recommendedDeploymentTier is set accordingly.
macOS coverage. sandbox-runtime supports macOS via sandbox-exec (seatbelt profile). Layer 1 ephemeral home is OS-agnostic (just an env var). Layer 3 macOS path needs verification: does per-call wrapWithSandbox() with customConfig produce a per-spawn sandbox-exec profile, or does it re-use a singleton seatbelt profile? Task #4 PI231 spike is Linux-only; a parallel macOS verification is a Task #9 deliverable.
Symlink-vs-bindmount for credentials. Layer 2 uses symlinks for credential mounting. An alternative is bindmounting the credential file into the ephemeral home (only available inside the Layer 3 wrap). The trade-off: symlinks work outside any sandbox context (so Layer 2 works even when Layer 3 is skipped, e.g., for codex); bindmounts are stronger isolation (the CLI cannot follow the symlink to discover the real path). Decision reserved for PR-B' implementation review.
Concurrent-spawn cleanup ordering. The ephemeral home cleanup (rmdir at response end) must not race with a still-streaming spawn. The current plan: track per-reqId cleanup and only fire on the spawn's exit event. If a streaming abort leaves the spawn alive past the HTTP response, cleanup is deferred until exit. Tested in Task #9.
/health.sandbox.providers shape under Amendment 1. Original /health.sandbox had a flat { available, active }. Amendment 1 adds per-provider posture: { available, providers: { anthropic: { crossTenantReadProtection: 'tool-suppression', layers: ['L1','L2','L3','L4'] }, openai: { crossTenantReadProtection: 'inner-sandbox', layers: ['L1','L4'] } } }. Exact shape ratified by PR-B'.
Dashboard /dashboard Security panel. The dashboard currently has no security panel. Amendment 1 names the addition as a follow-up: render /health.sandbox.providers as a per-provider posture badge so the operator can see at a glance which providers are in tool-suppression vs inner-sandbox vs none mode. Out of Phase 7 scope; recorded for a future ADR.

A1.9 — Authority citations (Amendment 1)

Per ALIGNMENT.md Rule 1 (Cite First) and Iron Rule 12 (Pre-Brainstorm Prior-Art Search), every load-bearing claim in this amendment is cited to a primary source. The four forcing reasons are cited above in A1.1.1–A1.1.4; this section enumerates them in one place plus the supporting citations.

Forcing reasons:

sandbox-runtime documented use-case is inner-wrap by Claude Code.
- https://www.anthropic.com/engineering/claude-code-sandboxing — "Claude Code sandboxing" engineering blog. Documents Claude Code's internal use of the library to wrap tool-spawn calls. The blog also notes the library "can be used to sandbox arbitrary processes, agents and MCP servers" — i.e., it is general-purpose, not Claude-Code-internal-only. Our reading: outer-wrap of claude itself is not the documented or demonstrated direction; OLP would be the only known user in that configuration. Project-design judgment, not an Anthropic prohibition.
~/.claude.json non-atomic write — upstream issue closed not_planned by inactivity bot.
- https://github.com/anthropics/claude-code/issues/29250 — upstream issue requesting atomic-write semantics. Status: closed not_planned by github-actions[bot] on 2026-03-31 (inactivity), labeled duplicate, stale. No upstream Anthropic maintainer comment articulates a policy position; the closure does not establish "won't fix" as policy. Forcing argument rests on architectural-cost analysis (permanent maintenance treadmill for outer---ro-bind), not on alleged upstream policy.
Codex inner-bwrap conflict.
- https://github.com/openai/codex/issues/16018 — upstream codex CLI issue. Documents that codex's default bwrap sandbox fails outright in environments lacking unprivileged user namespaces. The issue is a feature request asking codex to add a fallback path; the issue body does NOT document an existing automatic fallback to --sandbox danger-full-access. Whether codex degrades to danger-full-access or aborts the spawn under nested-bwrap failure is empirically open (Task #4 deliverable). Either failure mode breaks the strict-additive-isolation invariant for outer-wrap of codex. This is the multi-provider forcing function regardless of which failure mode applies.
CODEX_HOME documented relocation lever.
- https://developers.openai.com/codex/config-reference — OpenAI codex CLI config reference (primary).
- https://codex.danielvaughan.com/2026/04/08/codex-cli-configuration-reference/ — third-party reference (cross-reference for reachability).

Supporting citations (carried forward from original ADR § 7):

@anthropic-ai/sandbox-runtime v0.0.52 — https://github.com/anthropic-experimental/sandbox-runtime
- dist/sandbox/sandbox-manager.js — SandboxManager.wrapWithSandbox(command, undefined, customConfig) is the per-call wrap surface used by Layer 3. The third argument customConfig is the per-call override mechanism that makes Amendment 1's per-spawn config architecture implementable without library modification.
Internal evidence:
- PR-B implementation chain — commits d0dcd28 → 2864275 → 497b255 → b1e24b7 → 3551921. The HTTP-path activation regression is documented in commit message b1e24b7 and in lib/sandbox/manager.mjs § "OLP_SANDBOX_DISABLED env-var gate" comments.
- cc-mem incident memory 2026-05-27 — ~/.cc-rules/memory/projects/olp/incident_2026_05_27_spawn_cli_security.md — the original multi-tenant gap and the prior-art search that established the ecosystem has no working solution.
- 2026-05-28 PoC spike on PI231 — /tmp/sandbox-spike/report.md on PI231. Verdict was YELLOW (architecturally green, operationally blocked on apt deps). The follow-up 2026-05-29 PI231 prep work re-evaluates against the new architecture; results land in Task #4.
OLP governance:
- OLP ALIGNMENT.md Rule 1 — Authority citation required for any provider-plugin / entry-surface / IR change. Amendment 1 amends governance only; the implementation refactor (PR-B') carries its own per-commit citations to the same primary sources enumerated above.
- OLP ALIGNMENT.md Rule 4 — Unalignable plugins are deleted. Mistral's potential lack of a home-relocation env var (open question 2 above) is not an alignability gap (mistral's CLI authority is unchanged); it is a deployment-tier classification, recorded in the provider's ISOLATION block.
- Iron Rule 10 — Independent reviewer required. This amendment's review is pending at draft time.
- Iron Rule 11 — Minimum reviewable unit. PR-B' is one PR (sandbox manager refactor); the anthropic ISOLATION block, codex ISOLATION block, server wiring, and README section are each separate PRs per the revised PR plan in § A1.4.
- Iron Rule 12 — Pre-brainstorm prior-art search. The four forcing reasons each satisfy the rule's "provider-specific authority check decisive" condition: Anthropic's blog post + upstream issue 29250 (for the anthropic side), and the codex issue 16018 + the OpenAI config reference (for the codex side).
OLP ADR cross-references:
- ADR 0001 § Mission — multi-provider proxy. Codex inner-bwrap conflict is the multi-provider forcing function.
- ADR 0002 (pending Amendment N) — Provider ISOLATION contract specification. Amendment 1 names the contract; Amendment N specifies it.
- ADR 0006 — Provider Inclusion / Risk Tier. recommendedDeploymentTier in the ISOLATION block integrates with the risk tier framework.
- ADR 0009 Amendment 1 § Caveats #3 — "Sandbox-runtime still required for real multi-tenant deployment." Amendment 1 satisfies this caveat via Layer 3, not via outer-wrap.
- docs/plans/cloud-deployment-family.md § 5 — sandbox is a cloud rollout prerequisite. PR-E' updates this section to reflect that the layered architecture is the cloud prerequisite, not outer-bwrap.

A1.10 — Consequences of Amendment 1

Positive

No outer-bwrap maintenance treadmill. New claude CLI state files do not require OLP-side --ro-bind updates. Layer 1 absorbs them automatically.
Multi-provider compatible. Codex inner sandbox is preserved unmolested. The architecture works for both anthropic (no inner sandbox) and codex (has inner sandbox) without per-provider workarounds in the sandbox layer; the per-provider differences live in the per-provider ISOLATION block where they belong.
Per-spawn isolation primitives. Every request gets a fresh $HOME. Cross-tenant state carry-over at the filesystem level is structurally impossible, not "mitigated by careful denylist."
Aligned with Anthropic's design intent. OLP uses sandbox-runtime in the direction the library was designed for (sandboxing what the spawn triggers, not wrapping the spawn from outside). The library's semver discipline becomes leverage rather than risk.
Reduced HTTP-path activation surface. PR-B's regression was that the in-process MITM proxy lifecycle interacted with OLP's HTTP request handler. Per-call wrapWithSandbox() does not require an always-on in-process proxy; the failure mode goes away by construction. (To be confirmed empirically in Task #4 + Task #9.)
Doctor and /health.sandbox continuity. Operators and dashboard consumers see the same field at the same JSON path. Shape additions are additive, not breaking.

Negative

Per-call latency cost. Per-call wrapWithSandbox() is more expensive than once-at-boot init+wrap. The mitigation is library-import caching and (if measured high) a sandbox-config cache keyed by the union of allowed-read paths. Empirical measurement in Task #4.
New contract surface (ISOLATION block). Each provider plugin now declares ISOLATION fields. This is incremental complexity in the Provider contract — ratified by ADR 0002 Amendment N. ADR 0002 amendment is on the critical path.
Mistral declared crossTenantReadProtection: 'none'. Vibe CLI has no Phase-6c-equivalent tool suppression and no known inner sandbox as of D8 ADR 0006 enablement. The mistral provider's recommendedDeploymentTier is therefore separate-vm per ADR 0002 Amendment 9 § Per-provider concrete instance, meaning mistral can run only in a dedicated VM rather than sharing the OS user with other providers. Not a regression vs status quo (mistral is not deployed today); reflects honest characterization of current state per ALIGNMENT.md Rule 3. Task #4 spike may discover a hardening regime, transitioning this tier upward.
Symlink semantics edge cases. Layer 2 symlinks credential files into the ephemeral home; some CLIs may resolve the symlink and write a sibling file in the target directory rather than the ephemeral location. Each provider's ISOLATION block should declare any such known behaviour; the runtime tests verify by examining the operator's real $HOME for stray writes after a test spawn.
The OLP_SANDBOX_DISABLED=1 env-var gate is preserved for 1-2 releases. It remains a valid escape hatch — but as belt-and-suspenders rather than as load-bearing. Operators who rely on the gate after sunset will see a deprecation message before removal.

Reversibility (governance level)

Amendment 1 is reversible by a superseding ADR amendment that cites new evidence overturning any of the four forcing reasons. The most likely overturning scenario: Anthropic publishes guidance endorsing outer-wrap of claude CLI plus an atomic-write contract for ~/.claude.json. If that happens, the superseding amendment cites the new guidance and re-enables outer-wrap as an option (alongside, not replacing, the Solution 1 architecture).
The implementation-level reversibility is documented in § A1.7 above.

A1.11 — Forward-looking pointer

Amendment 1 is the governance layer. The implementation lands across Tasks #5–#10 (per the working task list at the time of this draft):

Task #4 — PI231 spike to verify HOME / CODEX_HOME env-var override behaviour (live, with the same claude and codex CLI versions OLP ships against).
Task #5 — Refactor lib/sandbox/manager.mjs to the Layer 1 + Layer 2 + Layer 3 architecture (PR-B').
Task #6 — Add ISOLATION block to lib/providers/anthropic.mjs (PR-C').
Task #7 — Add ISOLATION block to lib/providers/codex.mjs (PR-D').
Task #8 — Wire prepareIsolatedEnvironment into server.mjs spawn pipeline (folds into PR-C' or its own PR depending on diff size).
Task #9 — PI231 E2E validation of Solution 1 + close PR-B's load-bearing negative test ("in-sandbox cat ~/.olp/keys/... MUST fail") against the new architecture.
Task #10 — README "Security Model" section + cloud-deployment-plan § 5 update + Phase 7 close (PR-E').

ADR 0002 Amendment N (Provider ISOLATION contract specification) is a co-merged ADR with PR-C'; it cannot land after the ISOLATION block reaches the codebase per ALIGNMENT.md Rule 2(c)'s spirit (no contract field without an authorizing ADR).

A1.12 — Amendment status

Drafted: 2026-05-29 (this document).
Reviewer: independent fresh-context reviewer per Iron Rule 10 — pending.
Implementation gate: ADR 0002 Amendment N (Provider ISOLATION contract specification) must land before or together with PR-C' (the first ISOLATION-block-bearing provider plugin commit).
Production gate: PI231 E2E (Task #9) must pass the load-bearing negative test before the OLP_SANDBOX_DISABLED=1 env-var gate is removed from prod startup.

69 KiB Raw Permalink Blame History Unescape Escape

ADR 0014 — Sandbox-Runtime Integration for Multi-Tenant Provider Spawning

Related

1. Context

1.1 The multi-tenant security gap

1.2 Anthropic's official answer: @anthropic-ai/sandbox-runtime

1.3 The 2026-05-28 spike

2. Decision

2.1 Layered rollout (Iron Rule 11 — minimum reviewable unit)

2.2 PR-A specific scope (binding)

3. lib/sandbox/doctor.mjs design

3.1 Exports

3.2 checkSandboxAvailability algorithm

3.3 /health integration

4. PR-B/C/D acceptance criteria

4.1 PR-B (anthropic.mjs spawn wrap) — ✅ Implementation shipped, PI231 validation pending

4.2 PR-C (codex.mjs wrap)

4.3 PR-D (cloud deployment plan update)

5. Open questions (to be resolved in PR-B)

6. Pitfalls inherited from the spike (binding warnings for PR-B/C authors)

7. Authority citations

8. Consequences

Positive

Negative

Reversibility

Status transitions

Amendment 1 — Supersede PR-B outer-bwrap with ephemeral-home + per-provider contract (2026-05-29)

A1.1 — Why the substitution is forced (the four forcing reasons)

A1.1.1 — Forcing reason #1: Anthropic's stated design intent for @anthropic-ai/sandbox-runtime

A1.1.2 — Forcing reason #2: The ~/.claude.json upstream "closed as not planned" — permanent maintenance treadmill for outer-bwrap

A1.1.3 — Forcing reason #3: Codex inner-bwrap conflict (multi-provider forcing function)

A1.1.4 — Forcing reason #4: CODEX_HOME exists and is the documented relocation lever

A1.2 — The substitute architecture: per-spawn ephemeral home + per-provider ISOLATION contract

A1.2.1 — Layer 1: Per-spawn ephemeral home directory

A1.2.2 — Layer 2: Symlinked credential files into the ephemeral home

A1.2.3 — Layer 3: Optional sandbox-runtime per-call customConfig for non-$HOME read protection

A1.2.4 — Layer 4: Provider-specific tool hardening already in place

A1.3 — The provider ISOLATION contract (named here; specified in ADR 0002 Amendment N)

A1.4 — Revised PR plan

A1.5 — What survives from PR-B (preserved)

A1.6 — What disappears from PR-B (superseded)

A1.6.1 — The OLP_SANDBOX_DISABLED=1 env-var gate

A1.7 — Reversibility

A1.8 — Updated open questions (supersedes original § 5)

A1.9 — Authority citations (Amendment 1)

A1.10 — Consequences of Amendment 1

Positive

Negative

Reversibility (governance level)

A1.11 — Forward-looking pointer

A1.12 — Amendment status

69 KiB

Raw Permalink Blame History

1.2 Anthropic's official answer: `@anthropic-ai/sandbox-runtime`

3. `lib/sandbox/doctor.mjs` design

3.2 `checkSandboxAvailability` algorithm

3.3 `/health` integration

A1.1.1 — Forcing reason #1: Anthropic's stated design intent for `@anthropic-ai/sandbox-runtime`

A1.1.2 — Forcing reason #2: The `~/.claude.json` upstream "closed as not planned" — permanent maintenance treadmill for outer-bwrap

A1.1.4 — Forcing reason #4: `CODEX_HOME` exists and is the documented relocation lever

A1.2.3 — Layer 3: Optional `sandbox-runtime` per-call `customConfig` for non-$HOME read protection

A1.6.1 — The `OLP_SANDBOX_DISABLED=1` env-var gate