sandbox: single active policy file, repo .sandboxrc else ~/.config/3code/sandboxrc

Author: capocasa

README.md

@@ -80,7 +80,7 @@ A working example lives in [`example/webserve.nim`](example/webserve.nim): a web
 
 **unreleased** - patient retry, single-file sandbox policy
 
-- **Single-file sandbox policy.** The sandbox policy now lives in exactly one file, `.3code/sandbox` in the project directory; the old two-level cascade (`~/.config/3code/sandbox` then the repo file) is gone. When the project file is missing at launch it is created from `~/.3code/sandbox`, which itself is created from the built-in default when missing, so the sandbox is still always on and you can now customize what every new project starts with by editing the home file. One implicit rule is appended after every rule in the file: the policy file itself is read-only, so the agent cannot widen its own sandbox by editing the policy (the `is under a writable rule` warning this replaces is gone).
+- **Single-file sandbox policy.** The old two-level cascade is gone: exactly one policy file is active at a time, the repo `.sandboxrc` when it exists, else the user file `~/.config/3code/sandboxrc`. The user file is created from the built-in default on first run, so the sandbox stays always on and you can change what every project without its own `.sandboxrc` gets by editing that one file. The first `:sandbox allow|readonly|deny` in a project materializes `.sandboxrc` by copying your user file, so project rules start from your baseline.
 - **Patient retry.** Retryable API failures (429 usage limits, 5xx, network errors) now keep retrying on one shared exponential backoff capped at 2048s, for up to ~64 attempts (~36h), instead of surfacing after a short probe. A long-running session rides out a provider's rolling usage window or a network dropout (the train ride) without dropping back to the prompt. The underlying error message and attempt counter keep scrolling by as transcript lines so you can see what is being waited out. `:retry on|off` toggles it (default on; `off` keeps the ~1-minute initial ramp-up so transient blips still self-heal); persisted in `[settings]` as `patient_retry`. Ctrl-C cancels a running hold at any time.
 
 **0.6.0** - filesystem sandbox backed by nimbox, folded into the `box` subcommand

config.example

@@ -20,7 +20,7 @@ current = "baseten.glm5"
 ; exa-key = "..."
 ; brave-key = "..."
 ; notify = off ; turn off the desktop notification that fires when a turn ends (on by default)
-; sandbox = off ; disable filesystem sandbox enforcement (on by default: .3code/sandbox policy)
+; sandbox = off ; disable filesystem sandbox enforcement (on by default: .sandboxrc in the project, else ~/.config/3code/sandboxrc)
 ; patient_retry = off ; disable patient retry of 429/5xx/network errors (on by default: ~36h hold so a long-running session rides out a usage limit or network dropout without dropping to the prompt)
 ; sandbox_wall_warn = off ; silence the Windows "wall not set up" warning (host rules in policy, no `3code wall setup-windows` yet)
 ; bash_path = "C:\\tools\\msys64\\usr\\bin\\bash.exe"  ; Windows only: override bash detection

docs/manual.md

@@ -360,26 +360,22 @@ Sub-agents are not supported because both research and user feedback says they a
 ## Sandbox
 
 3code confines every tool call to a filesystem sandbox you define. The
-sandbox is a plain text policy built from a cascade of files, each filling
-in for the ones below it:
-
-1. **system** - `~/.config/3code/sandbox`, next to your config.
-2. **repo** - `.sandboxrc` in your project directory.
-
-A missing level is not empty: it contributes the built-in default
-(`deny /`, `allow /tmp`, then `allow` for the cwd), so the
-sandbox is always on. The
-effective policy is the two texts concatenated (system then repo) and
-parsed once, so a repo-level `deny /` cleanly resets anything a
-system file opened above it. 3code never writes a sandbox file into your
-project on first run; the default lives in memory until you create one
-(explicitly, or via the `:sandbox` edit commands, which seed the repo
-file on first use). Yolo mode (everything writable) is fine but you have
-to ask for it explicitly.
+sandbox is a plain text policy living in exactly one file at a time:
+
+1. **repo** - `.sandboxrc` in your project directory, when it exists.
+2. **user** - `~/.config/3code/sandboxrc`, next to your config,
+   otherwise.
+
+There is no cascade and no merging: the repo file wins outright, the
+user file is the fallback. The user file is created from the built-in
+default on first run, so the sandbox is always on and you can change
+what every project without its own `.sandboxrc` gets by editing that
+one file. Yolo mode (everything writable) is fine but you have to ask
+for it explicitly.
 
 The sandbox is enforced two ways. Bash commands run through `3code box`,
 the built-in sandwall sandbox (Landlock on Linux, Seatbelt on macOS), which
-3code re-execs itself as; the box process loads the policy files itself,
+3code re-execs itself as; the box process loads the policy file itself,
 so every command launches on the freshest policy. The in-process
 read/write/patch tools check paths against the same policy (reloaded when
 the file changes) in the 3code process. Both layers run the same sandwall
@@ -433,7 +429,8 @@ writable project). Host rules (``allow api.example.com``,
 ``allow 1.2.3.4:8080``, ``allow *`` for no network restrictions) fence
 the network egress of sandboxed bash commands through the wall proxy.
 
-On first run in a new directory, 3code uses this default:
+On first run, 3code initializes `~/.config/3code/sandboxrc` with this
+default:
 
 ```
 deny /
@@ -490,8 +487,9 @@ REPL commands which append a rule and reload immediately:
 ```
 
 The first `allow`/`readonly`/`deny` in a project creates the `.sandboxrc`
-file (seeded with the built-in default, then your appended rule) so you
-have something concrete to version and share. `:sandbox off` disables
+file by copying your user file, then appends the rule, so project rules
+start from your baseline and you have something concrete to version and
+share. `:sandbox off` disables
 enforcement entirely for the session (bash runs unconfined, in-process
 checks pass through); it persists in `[settings]` as `sandbox = off`. This
 is the only way to run without a sandbox short of editing the file.

src/threecode.nim

@@ -100,14 +100,14 @@ proc ensureBash() =
       quit ExitUsage
 
 proc initSandbox(cwd: string) =
-  ## Load the cascaded sandbox policy into the global state and resolve
-  ## this binary's own path for bash wrapping. The policy is built from the
-  ## system file (next to `~/.config/3code/config`) and the repo file
-  ## (`.sandboxrc`), each falling back to the built-in default when
-  ## absent, so no file is ever written into the project on first run. When
-  ## `sandboxEnabled` is false (the `[settings] sandbox = off` switch), this
-  ## does nothing: bash runs unconfined and the in-process checks pass
-  ## through (`active` stays false).
+  ## Load the sandbox policy into the global state and resolve this
+  ## binary's own path for bash wrapping. Exactly one file is active:
+  ## the repo `.sandboxrc` when it exists, else the user file
+  ## `~/.config/3code/sandboxrc`, which is initialized from the
+  ## built-in default on first run so the sandbox is always on. When
+  ## `sandboxEnabled` is false (the `[settings] sandbox = off` switch),
+  ## this does nothing: bash runs unconfined and the in-process checks
+  ## pass through (`active` stays false).
   # The provider stub binary (the tty/visual test harness) skips sandbox
   # setup entirely so its behaviour matches the pre-sandbox binary. Those
   # tests drive REPL rendering, not enforcement, and `active=true` plus the
@@ -118,7 +118,8 @@ proc initSandbox(cwd: string) =
     return
   if not sandboxEnabled:
     return
-  sandbox.current = sandbox.loadCascaded(cwd)
+  discard sandbox.ensureUserPolicy()
+  sandbox.current = sandbox.loadPolicy(cwd)
   sandbox.active = true
   # The bash tool re-execs this binary as `3code box restrict ...`, so
   # resolve our own path once. The box subcommand is always compiled in, but
@@ -353,10 +354,11 @@ proc main() =
     if prompt == "":
       restoredDraft = loadPendingDraft(session.cwd)
 
-  # Sandbox is mandatory: the cascaded policy is loaded, each level
-  # falling back to the built-in default when absent. Paths resolve
-  # relative to the session cwd so the policy follows the project, not
-  # the binary.
+  # Sandbox is mandatory: the user policy file is initialized from
+  # the built-in default when absent, then the single active file
+  # (repo `.sandboxrc` or the user file) is loaded. Paths resolve
+  # relative to the session cwd so the policy follows the project,
+  # not the binary.
   initSandbox(session.cwd)
 
   try:

src/threecode/box.nim

@@ -40,21 +40,19 @@ Usage:
   children are confined: writes outside the writable paths fail with
   EACCES.
 
-  With --policy, the writable/read-only sets come from the given policy
-  files (cascaded in order, system first, relative targets resolved
-  against the project dir: the parent of a `.sandboxrc` file, else cwd).
-  Explicit
-  RWPATH/ROPATH args union with the policy sets. Policy files themselves
-  are forced read-only inside the sandbox.
+  With --policy, the writable/read-only sets come from the given
+  policy file (relative targets resolve against the project dir: the
+  parent of a `.sandboxrc` file, else cwd). Explicit RWPATH/ROPATH
+  args union with the policy sets. The policy file itself is forced
+  read-only inside the sandbox.
 
   System dirs (/usr, /bin, /lib, /dev/*, etc.) are always read-only so the
   command's binaries, libs, and device nodes stay runnable; --ro adds to
   that set, it does not replace it.
 
 Examples:
   3code box restrict /tmp /home/me/work -- ls -la
-  3code box --policy ~/.config/3code/sandbox --policy .sandboxrc \
-    restrict -- make test
+  3code box --policy .sandboxrc restrict -- make test
   3code box restrict . -- make test
 
 Landlock is monotonic: the restriction is permanent for this process and all
@@ -111,6 +109,9 @@ proc resolvePolicy(a: BoxArgs): tuple[writable, readonly, denied: seq[string];
   var denied: seq[string]
   var hostRules = 0
   if a.policies.len > 0:
+    # Exactly one active policy file: 3code passes the repo `.sandboxrc`
+    # when it exists, else the user file. Multiple --policy args are
+    # still accepted (concatenated) for standalone box use.
     var texts: seq[string]
     for f in a.policies:
       texts.add(if fileExists(f): readFile(f) else: "")

src/threecode/library.nim

@@ -147,12 +147,13 @@ proc initAgentSession*(opts: AgentOptions): AgentSession =
   materializeBuiltinSkills()
 
   # Config first (it reads `[settings] sandbox = off`), then the
-  # sandbox: same cascaded policy and order as the CLI. Paths resolve
+  # sandbox: same single-file policy as the CLI. Paths resolve
   # against the session cwd so the policy follows the project.
   var colorKeys: Table[string, string]
   (activeCurrent, activeProviders, colorKeys) = loadStateOrEmpty(configPath())
   if sandboxEnabled:
-    sandbox.current = sandbox.loadCascaded(cwd)
+    discard sandbox.ensureUserPolicy()
+    sandbox.current = sandbox.loadPolicy(cwd)
     sandbox.active = true
     sandbox.procboxExe = sandbox.findProcbox()
     if not sandbox.backendWorks(sandbox.procboxExe):