You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@airflow.apache.org by po...@apache.org on 2026/05/01 14:01:32 UTC

(airflow-steward) 01/01: docs(secure-agent-setup): split technical details into secure-agent-internals.md

This is an automated email from the ASF dual-hosted git repository.

potiuk pushed a commit to branch docs/split-secure-agent-internals
in repository https://gitbox.apache.org/repos/asf/airflow-steward.git

commit f8b1c29222d69ccd1ef882167cc2a1279b61bf25
Author: Jarek Potiuk <ja...@potiuk.com>
AuthorDate: Fri May 1 16:01:15 2026 +0200

    docs(secure-agent-setup): split technical details into secure-agent-internals.md
    
    Splits the previous Part 1 / Part 2 single-file structure into two
    documents along the same line:
    
    - `secure-agent-setup.md` (kept) — context, installation,
      demonstration. The full install path, three new agent-guided
      prompts (first-time setup / verify / keep-updated), and the five
      session screenshots demonstrating each visible state stay here.
      An adopter who only wants the secure setup running reads this
      file end-to-end and stops.
    
    - `secure-agent-internals.md` (new) — the mental-model deep dive.
      How `sandbox.enabled` actually directs the Bash tool, how
      bubblewrap (Linux) and Seatbelt (macOS) enforce at the OS layer,
      the SNI / DoH blind spot motivating `Bash(curl *)` deny-listing,
      and the feedback-mechanism layering table. No screenshots — those
      remain in the setup doc, demonstrating the mechanisms this doc
      describes.
    
    Cross-references in both directions: setup → internals via the
    intro paragraph and a See-also bullet; internals → setup via the
    intro paragraph, the feedback-table cells, and a See-also section
    pointing at the screenshots and the install pages for each
    surfacing piece.
    
    Heading levels rebalanced for the split: setup's H3 sections
    become H2 (Part-wrapper dropped), H4 sub-sections become H3.
    Internals' H3-section title becomes the file H1, and its H4
    sub-sections become H2.
    
    Generated-by: Claude Code (Opus 4.7)
---
 secure-agent-internals.md | 141 ++++++++++++++++++++++++++
 secure-agent-setup.md     | 252 +++++++++++++++-------------------------------
 2 files changed, 220 insertions(+), 173 deletions(-)

diff --git a/secure-agent-internals.md b/secure-agent-internals.md
new file mode 100644
index 0000000..b02dbcc
--- /dev/null
+++ b/secure-agent-internals.md
@@ -0,0 +1,141 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [How sandbox isolation works](#how-sandbox-isolation-works)
+  - [What `sandbox.enabled` actually does](#what-sandboxenabled-actually-does)
+  - [Linux: bubblewrap + user namespaces](#linux-bubblewrap--user-namespaces)
+  - [macOS: Seatbelt](#macos-seatbelt)
+  - [The blind spot: `Bash(curl *)` and DNS-over-HTTPS](#the-blind-spot-bashcurl--and-dns-over-https)
+  - [How the feedback mechanisms layer together](#how-the-feedback-mechanisms-layer-together)
+  - [See also](#see-also)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+     https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# How sandbox isolation works
+
+This is the companion to
+[`secure-agent-setup.md`](secure-agent-setup.md): the mental
+model for *how* the filesystem-sandbox layer (Layer 1 of the
+[Three-layer defence](secure-agent-setup.md#three-layer-defence)
+table) actually intercepts a Bash call, what the agent's own
+tools do that the sandbox does *not* cover, and where each
+visible state of a session originates. Optional for adoption —
+the setup document is sufficient to install and verify the
+secure setup — and worth reading when you want to understand
+which layer is doing what, or are debugging why a specific
+call did or did not get through.
+
+## What `sandbox.enabled` actually does
+
+`sandbox.enabled: true` is not a flag the agent inspects; it is a
+directive to Claude Code's Bash tool to wrap every subprocess in
+an OS-level container before launching it. The model itself never
+sees the boundary — it just gets a `command not found` /
+`No such file or directory` back from a Bash call that tried to
+reach outside the allowed paths.
+
+The agent's own Read, Edit, and Write tools are **not** sandboxed.
+Those tools call into Claude Code's runtime directly and hit the
+host filesystem with whatever privileges the user running
+`claude` has. `permissions.deny` (`Read(~/.aws/**)`,
+`Read(~/.ssh/**)`, …) is what stops the agent's Read tool from
+reading those paths — the sandbox would not.
+
+The two layers are complementary, not redundant. The sandbox stops
+a Bash subprocess (an MCP server's child process, a `gh` CLI call,
+a `python` snippet the model decided to run) from reading a denied
+path. `permissions.deny` stops the agent's Read tool from reading
+the same path. A secure setup needs both: the framework's
+[`.claude/settings.json`](.claude/settings.json) deny-lists
+`Read(~/.config/gh/**)` *and* allow-reads `~/.config/gh/` in the
+sandbox, so `gh` can see its token but the agent can never read
+the file.
+
+## Linux: bubblewrap + user namespaces
+
+On Linux, Claude Code launches each Bash subprocess inside a
+fresh **mount namespace** built by
+[`bubblewrap`](https://github.com/containers/bubblewrap). bubblewrap
+bind-mounts only the paths listed in `sandbox.filesystem.allowRead`
+into the new namespace; everything else from the host is
+*literally absent* from the subprocess's view of the filesystem.
+
+The visible result is precise: a `cat ~/.aws/credentials` from
+inside the sandbox returns `No such file or directory`, not
+`Permission denied`. The path doesn't exist as far as the
+subprocess is concerned — there is nothing to deny access to.
+That is the same mechanism `flatpak` and `firejail` use.
+
+Network egress is layered on top of the same namespace via
+[`socat`](http://www.dest-unreach.org/socat/), which terminates
+the outgoing TLS connection, reads the SNI extension, and
+forwards only to hosts in `sandbox.network.allowedDomains`.
+A connection to a non-allowed host fails at the proxy.
+
+## macOS: Seatbelt
+
+On macOS, bubblewrap and socat are not used — Claude Code wraps
+Bash subprocesses in
+[`sandbox-exec`](https://developer.apple.com/library/archive/documentation/Security/Conceptual/AppSandboxDesignGuide/AboutAppSandbox/AboutAppSandbox.html)
+instead, generating a `.sb` profile that the kernel enforces at
+the syscall level. The same `denyRead` / `allowRead` /
+`allowedDomains` shape from `settings.json` drives the generated
+profile.
+
+The visible result differs slightly: a denied read typically
+returns `Operation not permitted` rather than
+`No such file or directory`, because Seatbelt rejects the syscall
+before the filesystem driver runs. The policy outcome is the
+same — denied paths are unreachable from within the subprocess.
+
+No system packages need pinning on macOS — Seatbelt ships with
+the OS. The framework's
+[`pinned-versions.toml`](tools/agent-isolation/pinned-versions.toml)
+only pins `bubblewrap`, `socat`, and `claude-code` itself;
+Seatbelt does not appear because its version *is* the OS version.
+
+## The blind spot: `Bash(curl *)` and DNS-over-HTTPS
+
+The SNI proxy filters by the TLS Server Name Indication
+extension, which a well-behaved client puts on the wire in
+clear text before the TLS handshake completes. A client that
+uses DNS-over-HTTPS through an allow-listed CDN (Cloudflare,
+Google) can cleanly dodge that inspection — the SNI says
+`cloudflare-dns.com`, the actual query is for somewhere else.
+That is why the framework's `permissions.deny` list also
+contains `Bash(curl *)`, `Bash(wget *)`, and the various cloud
+CLIs — defence in depth against an exfiltration path that the
+sandbox alone does not close.
+
+## How the feedback mechanisms layer together
+
+| Mechanism | Scope | What it tells you | When it fires |
+|---|---|---|---|
+| `sandbox.enabled` in settings | per-session | Source of truth — is the sandbox active for this session? | At session start; persists for the session unless `/sandbox` toggles it. |
+| [Sandbox-state status line](secure-agent-setup.md#sandbox-state-status-line) | per-session, always-on | Visual confirmation of the source of truth. | Re-rendered on every status-line update. |
+| [Sandbox-bypass visibility hook](secure-agent-setup.md#sandbox-bypass-visibility-hook) | per-call | A specific Bash call is asking to step outside the sandbox. | Only when `dangerouslyDisableSandbox: true` is set on the call. |
+| Claude Code permission prompt | per-call | The gate — approve or deny the bypass. | Same firing condition as the hook; the hook augments the prompt with a banner the user cannot skim past. |
+
+The settings file is the source of truth; the status line and
+the hook surface that truth on two different time scales —
+always-on (status line) and per-call (hook). The permission
+prompt is the actual gate. Installing all four means a
+sandbox-bypass that lands without your noticing has to skim past
+two banners and silently approve a prompt — a much higher bar
+than skimming a single permission dialog.
+
+## See also
+
+- [`secure-agent-setup.md`](secure-agent-setup.md) — install +
+  verify + keep-updated path. The five session screenshots
+  demonstrating each layer in action live there too, in
+  [What a session looks like](secure-agent-setup.md#what-a-session-looks-like).
+- [Sandbox-state status line](secure-agent-setup.md#sandbox-state-status-line)
+  and
+  [Sandbox-bypass visibility hook](secure-agent-setup.md#sandbox-bypass-visibility-hook)
+  — the install instructions for the surfacing pieces this
+  document only describes mechanically.
diff --git a/secure-agent-setup.md b/secure-agent-setup.md
index ae69fed..27a0502 100644
--- a/secure-agent-setup.md
+++ b/secure-agent-setup.md
@@ -3,22 +3,39 @@
 **Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
 
 - [Secure agent setup](#secure-agent-setup)
-  - [Part 1 — Installation + demonstration](#part-1--installation--demonstration)
-    - [Threat model](#threat-model)
-    - [Three-layer defence](#three-layer-defence)
-    - [Required tools (pinned versions)](#required-tools-pinned-versions)
-    - [The framework's own `.claude/settings.json`](#the-frameworks-own-claudesettingsjson)
-    - [The clean-env wrapper](#the-clean-env-wrapper)
-    - [Sandbox-bypass visibility hook](#sandbox-bypass-visibility-hook)
-    - [Sandbox-state status line](#sandbox-state-status-line)
-    - [Syncing user-scope config across machines](#syncing-user-scope-config-across-machines)
-    - [Adopter setup](#adopter-setup)
-    - [Verification](#verification)
-    - [Keeping the setup updated](#keeping-the-setup-updated)
-  - [Part 2 — Technical details](#part-2--technical-details)
-    - [How sandbox isolation works](#how-sandbox-isolation-works)
-    - [Residual risks](#residual-risks)
-    - [See also](#see-also)
+  - [Threat model](#threat-model)
+  - [Three-layer defence](#three-layer-defence)
+  - [Required tools (pinned versions)](#required-tools-pinned-versions)
+    - [Install commands](#install-commands)
+    - [Distro-specific shortcut — Linux Mint 22.x / Ubuntu 24.04 Noble](#distro-specific-shortcut--linux-mint-22x--ubuntu-2404-noble)
+    - [Bumping a pinned version](#bumping-a-pinned-version)
+    - [Wiring the check script into a weekly routine](#wiring-the-check-script-into-a-weekly-routine)
+  - [The framework's own `.claude/settings.json`](#the-frameworks-own-claudesettingsjson)
+  - [The clean-env wrapper](#the-clean-env-wrapper)
+  - [Sandbox-bypass visibility hook](#sandbox-bypass-visibility-hook)
+    - [Why install it user-scope, not project-scope](#why-install-it-user-scope-not-project-scope)
+    - [Install (user-scope)](#install-user-scope)
+    - [Verify](#verify)
+    - [Trade-offs](#trade-offs)
+  - [Sandbox-state status line](#sandbox-state-status-line)
+  - [Syncing user-scope config across machines](#syncing-user-scope-config-across-machines)
+    - [What to track, what not to track](#what-to-track-what-not-to-track)
+    - [Layout](#layout)
+    - [Setting up a fresh host](#setting-up-a-fresh-host)
+    - [A minimal `sync.sh`](#a-minimal-syncsh)
+    - [Why a *private* repo](#why-a-private-repo)
+  - [Adopter setup](#adopter-setup)
+    - [Direct manual install](#direct-manual-install)
+    - [Via a Claude Code prompt](#via-a-claude-code-prompt)
+  - [Verification](#verification)
+    - [Direct Bash verification](#direct-bash-verification)
+    - [Via a Claude Code prompt](#via-a-claude-code-prompt-1)
+  - [Keeping the setup updated](#keeping-the-setup-updated)
+    - [Direct steps](#direct-steps)
+    - [Via a Claude Code prompt](#via-a-claude-code-prompt-2)
+  - [What a session looks like](#what-a-session-looks-like)
+  - [Residual risks](#residual-risks)
+  - [See also](#see-also)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -45,19 +62,17 @@ This setup does not eliminate that risk. It reduces it to the
 tracker repo — and forces every credential-using bash subprocess to
 run with a narrowed view of the home directory.
 
-The document is split in two halves. **Part 1** (below) is the
-adopter's path — threat model, layer overview, install commands
-for each piece, the end-to-end recipe, and verification. A reader
-who only wants the secure setup running can stop at the end of
-Part 1. **Part 2** is the mental-model path — how
-`sandbox.enabled` actually intercepts a Bash call, what
-bubblewrap (Linux) and Seatbelt (macOS) do at the OS layer,
-where the blind spots are, and what residual risks remain after
-the setup is in place.
+Internals — the mental model for *how* the filesystem-sandbox
+layer (Layer 1) actually intercepts a Bash call at the runtime
+and OS layers, what the agent's own tools do that the sandbox
+does *not* cover, and where the blind spots are — live in a
+separate document:
+[`secure-agent-internals.md`](secure-agent-internals.md). This
+document is sufficient to install and verify the secure setup;
+the internals doc is optional reading for understanding which
+layer is doing what.
 
-## Part 1 — Installation + demonstration
-
-### Threat model
+## Threat model
 
 The setup defends against three concrete failure modes:
 
@@ -82,7 +97,7 @@ It does **not** defend against:
 - A maliciously-crafted MCP server installed at user scope. Audit
   `~/.claude/.mcp.json` and `~/.claude.json` periodically.
 
-### Three-layer defence
+## Three-layer defence
 
 | Layer | Mechanism | What it stops |
 |---|---|---|
@@ -96,7 +111,7 @@ Layers 1, 2, and 3 are configured by the same
 dogfoods. Adopters copy the same shape into their own tracker repo
 (see [Adopter setup](#adopter-setup) below).
 
-### Required tools (pinned versions)
+## Required tools (pinned versions)
 
 Every system-level tool the secure setup depends on is pinned with a
 **7-day cooldown** before the framework adopts a new upstream
@@ -117,7 +132,7 @@ The pin date floor (`pinned_at` in the manifest) is the day the
 manifest was last touched; it is the framework's promise that every
 version above had at least 7 days to settle before being adopted.
 
-#### Install commands
+### Install commands
 
 The exact commands are also in `pinned-versions.toml` under each
 tool's `install.<distro>` field; below is the one-line view per
@@ -152,7 +167,7 @@ version, no pin enforced — Homebrew rolls forward, so the
 npm install -g --no-save @anthropic-ai/claude-code@2.1.117
 ```
 
-#### Distro-specific shortcut — Linux Mint 22.x / Ubuntu 24.04 Noble
+### Distro-specific shortcut — Linux Mint 22.x / Ubuntu 24.04 Noble
 
 The pinned versions above (bubblewrap `0.11.1`, socat `1.8.1.1`) are
 the *upstream* releases that have aged past the framework's 7-day
@@ -199,7 +214,7 @@ follows the same `*.local` convention as Claude Code's
 > converge — once Noble's next LTS adopts a newer bubblewrap, this
 > section retires.
 
-#### Bumping a pinned version
+### Bumping a pinned version
 
 When an upstream release has aged past the 7-day cooldown and you
 want to adopt it:
@@ -221,7 +236,7 @@ want to adopt it:
 The check script is idempotent and side-effect-free — it never edits
 the manifest, never installs anything, never opens a PR.
 
-#### Wiring the check script into a weekly routine
+### Wiring the check script into a weekly routine
 
 The framework's `/schedule` slash-command lets you wire the check
 script into a recurring agent without leaving Claude Code:
@@ -237,7 +252,7 @@ itself — the surfaced candidates are a *proposal*, and the framework
 maintainer's deliberate confirmation (per step 5 above) is what
 actually lands the bump.
 
-### The framework's own `.claude/settings.json`
+## The framework's own `.claude/settings.json`
 
 The framework dogfoods the secure config in
 [`.claude/settings.json`](.claude/settings.json). The full block is
@@ -305,7 +320,7 @@ agent should never *see* it. `sandbox.filesystem.allowRead` permits
 the bash subprocess to read the file; `permissions.deny[Read(...)]`
 blocks the agent's Read tool from reading the same path.
 
-### The clean-env wrapper
+## The clean-env wrapper
 
 Layer 0 — strip credential-shaped env vars from the parent shell
 before invoking `claude` — is implemented by
@@ -398,7 +413,7 @@ CLAUDE_ISO_ALLOW="GH_TOKEN" GH_TOKEN="$(op read 'op://Personal/GitHub/token')" c
 The `CLAUDE_ISO_ALLOW` mechanism is opt-in per invocation — no
 implicit propagation, no persistent allowlist.
 
-### Sandbox-bypass visibility hook
+## Sandbox-bypass visibility hook
 
 The Bash tool accepts a `dangerouslyDisableSandbox: true` flag that
 lets the model run a single command outside the sandbox — necessary
@@ -419,7 +434,7 @@ visible. The user still has to approve the call at the permission
 prompt — the banner gives them a fair chance to read what they are
 about to approve.
 
-#### Why install it user-scope, not project-scope
+### Why install it user-scope, not project-scope
 
 Unlike the framework's
 [`.claude/settings.json`](.claude/settings.json) (which is
@@ -435,7 +450,7 @@ entry into a tracker's `.claude/settings.json`) — the trade-off is
 narrower coverage in exchange for one fewer file to manage at the
 user level.
 
-#### Install (user-scope)
+### Install (user-scope)
 
 ```bash
 # Copy the hook script into ~/.claude/scripts/ (or symlink it from
@@ -470,7 +485,7 @@ array rather than creating a second matcher block:
 }
 ```
 
-#### Verify
+### Verify
 
 The hook is exit-code-driven — exit 1 with stderr output means
 "show stderr to the user, tool proceeds". To test without a real
@@ -485,7 +500,7 @@ Expected: a four-line red banner on stderr, then `exit=1`. A second
 call with `dangerouslyDisableSandbox` set to `false` (or absent
 entirely) should produce no output and `exit=0`.
 
-#### Trade-offs
+### Trade-offs
 
 - **No block, only visibility.** The hook deliberately exits 1, not
   2 — exit 2 would block the call outright, and that defeats the
@@ -505,7 +520,7 @@ entirely) should produce no output and `exit=0`.
   every Claude Code upgrade — same cadence as the
   [Verification](#verification) section below.
 
-### Sandbox-state status line
+## Sandbox-state status line
 
 The Claude Code terminal footer (`statusLine`) is the
 always-visible bottom-of-window line that renders the model name,
@@ -603,7 +618,7 @@ bold red.
   read that field directly. Until then the file-read approach is
   the only option, with the trade-off above.
 
-### Syncing user-scope config across machines
+## Syncing user-scope config across machines
 
 The user-scope pieces of the secure setup —
 `~/.claude/scripts/sandbox-bypass-warn.sh`, an optional global copy
@@ -621,7 +636,7 @@ collaboration preferences and the scripts may reference internal
 paths). Track the artifacts you want shared, symlink them into
 `~/.claude/`, and run a small sync script that pulls/commits/pushes.
 
-#### What to track, what not to track
+### What to track, what not to track
 
 | Track in the synced repo | Keep per-machine |
 |---|---|
@@ -641,7 +656,7 @@ synced repo, then on each new host edit `~/.claude/settings.json`
 once to point at the synced scripts. The "Install" snippets above
 already follow this pattern.
 
-#### Layout
+### Layout
 
 A minimal repo layout:
 
@@ -660,7 +675,7 @@ A minimal repo layout:
 Each tracked artifact lives in the repo; the path under `~/.claude/`
 is a symlink pointing at the repo. Editing either side updates both.
 
-#### Setting up a fresh host
+### Setting up a fresh host
 
 ```sh
 git clone git@github.com:<you>/claude-config.git ~/.claude-config
@@ -689,7 +704,7 @@ in the relevant sections (the hook entry in
 `~/.claude/settings.json`, the `source …/claude-iso.sh` line in
 `~/.bashrc` / `~/.zshrc`, etc.).
 
-#### A minimal `sync.sh`
+### A minimal `sync.sh`
 
 The script is intentionally tiny — pull, commit anything dirty,
 push. Run it manually, on a cron, on a systemd timer, or wherever
@@ -712,7 +727,7 @@ git diff --cached --quiet || \
 git log @{u}.. --oneline | grep -q . && git push
 ```
 
-#### Why a *private* repo
+### Why a *private* repo
 
 Three reasons make this non-negotiable:
 
@@ -731,14 +746,14 @@ Three reasons make this non-negotiable:
 Public dotfile repos are fine for shell aliases and editor configs;
 they are the wrong shape for agent-runtime files.
 
-### Adopter setup
+## Adopter setup
 
 If you are adopting the framework into your own tracker repo, copy
 the secure setup into your tracker's working tree. Two paths —
 the manual recipe is below, the agent-guided form is in the
 sub-section that follows.
 
-#### Direct manual install
+### Direct manual install
 
 1. Install the pinned tools per [Install commands](#install-commands)
    above.
@@ -779,7 +794,7 @@ sub-section that follows.
    dotfile-style repo per
    [Syncing user-scope config across machines](#syncing-user-scope-config-across-machines).
 
-#### Via a Claude Code prompt
+### Via a Claude Code prompt
 
 Paste the following into Claude Code at the start of a fresh
 session in your tracker repo. Claude walks every install step,
@@ -860,14 +875,14 @@ prompt in the same session — it has all the context already), and
 [Keeping the setup updated](#keeping-the-setup-updated) is the
 section to revisit after every Claude Code upgrade.
 
-### Verification
+## Verification
 
 After installing and configuring, verify the setup actually denies
 what it claims to. Two paths — pick whichever is easier; the
 Claude-prompt path is more thorough, the direct-Bash path is
 faster.
 
-#### Direct Bash verification
+### Direct Bash verification
 
 Inside a `claude-iso` session, run these from the agent's Bash
 tool. Each should fail or be denied:
@@ -880,7 +895,7 @@ curl https://example.com    # → blocked by permissions.deny
 
 Each command should produce a denial — not a leaked credential.
 
-#### Via a Claude Code prompt
+### Via a Claude Code prompt
 
 Paste the following into Claude Code at the start of a fresh
 session in the tracker repo. Claude walks every install step and
@@ -919,7 +934,7 @@ Re-run either form after every Claude Code upgrade — the sandbox
 semantics occasionally evolve and the framework maintainer wants
 to know the day a denial silently turns into an allow.
 
-### Keeping the setup updated
+## Keeping the setup updated
 
 The secure setup has three independent moving parts that drift on
 different schedules: the framework checkout (`.claude/settings.json`,
@@ -930,7 +945,7 @@ any user-scope copies of helper scripts you installed under
 `~/.claude/scripts/` or `~/.claude/agent-isolation/`. Keeping them
 synchronised is a periodic operation, not a one-time install.
 
-#### Direct steps
+### Direct steps
 
 1. **Framework checkout.** From your `airflow-steward` clone,
    pull the latest:
@@ -977,7 +992,7 @@ synchronised is a periodic operation, not a one-time install.
    (either form) to confirm the denials still fire after the
    update.
 
-#### Via a Claude Code prompt
+### Via a Claude Code prompt
 
 Paste the following into Claude Code at the start of a fresh
 session in the tracker repo. Claude reports drift and upgrade
@@ -1012,103 +1027,7 @@ agent via the framework's `/schedule` slash-command if you want
 it to run unattended; the surfaced drift and upgrade candidates
 land as a report you skim, not as auto-applied changes.
 
-## Part 2 — Technical details
-
-### How sandbox isolation works
-
-This is the mental model for *how* the filesystem-sandbox layer
-(Layer 1 of the [Three-layer defence](#three-layer-defence)
-table from Part 1) actually intercepts a Bash call, what the
-agent's own tools do that the sandbox does *not* cover, and what
-each visible state of a session means in practice. Optional for
-adoption — Part 1 above is sufficient to install the secure
-setup — and worth reading when you want to understand which
-layer is doing what, or are debugging why a specific call did
-or did not get through.
-
-#### What `sandbox.enabled` actually does
-
-`sandbox.enabled: true` is not a flag the agent inspects; it is a
-directive to Claude Code's Bash tool to wrap every subprocess in
-an OS-level container before launching it. The model itself never
-sees the boundary — it just gets a `command not found` /
-`No such file or directory` back from a Bash call that tried to
-reach outside the allowed paths.
-
-The agent's own Read, Edit, and Write tools are **not** sandboxed.
-Those tools call into Claude Code's runtime directly and hit the
-host filesystem with whatever privileges the user running
-`claude` has. `permissions.deny` (`Read(~/.aws/**)`,
-`Read(~/.ssh/**)`, …) is what stops the agent's Read tool from
-reading those paths — the sandbox would not.
-
-The two layers are complementary, not redundant. The sandbox stops
-a Bash subprocess (an MCP server's child process, a `gh` CLI call,
-a `python` snippet the model decided to run) from reading a denied
-path. `permissions.deny` stops the agent's Read tool from reading
-the same path. A secure setup needs both: the framework's
-[`.claude/settings.json`](.claude/settings.json) deny-lists
-`Read(~/.config/gh/**)` *and* allow-reads `~/.config/gh/` in the
-sandbox, so `gh` can see its token but the agent can never read
-the file.
-
-#### Linux: bubblewrap + user namespaces
-
-On Linux, Claude Code launches each Bash subprocess inside a
-fresh **mount namespace** built by
-[`bubblewrap`](https://github.com/containers/bubblewrap). bubblewrap
-bind-mounts only the paths listed in `sandbox.filesystem.allowRead`
-into the new namespace; everything else from the host is
-*literally absent* from the subprocess's view of the filesystem.
-
-The visible result is precise: a `cat ~/.aws/credentials` from
-inside the sandbox returns `No such file or directory`, not
-`Permission denied`. The path doesn't exist as far as the
-subprocess is concerned — there is nothing to deny access to.
-That is the same mechanism `flatpak` and `firejail` use.
-
-Network egress is layered on top of the same namespace via
-[`socat`](http://www.dest-unreach.org/socat/), which terminates
-the outgoing TLS connection, reads the SNI extension, and
-forwards only to hosts in `sandbox.network.allowedDomains`.
-A connection to a non-allowed host fails at the proxy.
-
-#### macOS: Seatbelt
-
-On macOS, bubblewrap and socat are not used — Claude Code wraps
-Bash subprocesses in
-[`sandbox-exec`](https://developer.apple.com/library/archive/documentation/Security/Conceptual/AppSandboxDesignGuide/AboutAppSandbox/AboutAppSandbox.html)
-instead, generating a `.sb` profile that the kernel enforces at
-the syscall level. The same `denyRead` / `allowRead` /
-`allowedDomains` shape from `settings.json` drives the generated
-profile.
-
-The visible result differs slightly: a denied read typically
-returns `Operation not permitted` rather than
-`No such file or directory`, because Seatbelt rejects the syscall
-before the filesystem driver runs. The policy outcome is the
-same — denied paths are unreachable from within the subprocess.
-
-No system packages need pinning on macOS — Seatbelt ships with
-the OS. The framework's
-[`pinned-versions.toml`](tools/agent-isolation/pinned-versions.toml)
-only pins `bubblewrap`, `socat`, and `claude-code` itself;
-Seatbelt does not appear because its version *is* the OS version.
-
-#### The blind spot: `Bash(curl *)` and DNS-over-HTTPS
-
-The SNI proxy filters by the TLS Server Name Indication
-extension, which a well-behaved client puts on the wire in
-clear text before the TLS handshake completes. A client that
-uses DNS-over-HTTPS through an allow-listed CDN (Cloudflare,
-Google) can cleanly dodge that inspection — the SNI says
-`cloudflare-dns.com`, the actual query is for somewhere else.
-That is why the framework's `permissions.deny` list also
-contains `Bash(curl *)`, `Bash(wget *)`, and the various cloud
-CLIs — defence in depth against an exfiltration path that the
-sandbox alone does not close.
-
-#### What a session looks like
+## What a session looks like
 
 The four screenshots below cover the visible states an adopter
 actually meets. Each is reproducible from this repo with the
@@ -1200,24 +1119,7 @@ unbypassable backstop for everything the runtime cannot
 lexically pre-parse (this screenshot). Either layer alone has
 gaps; together they are the actual sandbox.
 
-#### How the feedback mechanisms layer together
-
-| Mechanism | Scope | What it tells you | When it fires |
-|---|---|---|---|
-| `sandbox.enabled` in settings | per-session | Source of truth — is the sandbox active for this session? | At session start; persists for the session unless `/sandbox` toggles it. |
-| [Sandbox-state status line](#sandbox-state-status-line) | per-session, always-on | Visual confirmation of the source of truth. | Re-rendered on every status-line update. |
-| [Sandbox-bypass visibility hook](#sandbox-bypass-visibility-hook) | per-call | A specific Bash call is asking to step outside the sandbox. | Only when `dangerouslyDisableSandbox: true` is set on the call. |
-| Claude Code permission prompt | per-call | The gate — approve or deny the bypass. | Same firing condition as the hook; the hook augments the prompt with a banner the user cannot skim past. |
-
-The settings file is the source of truth; the status line and
-the hook surface that truth on two different time scales —
-always-on (status line) and per-call (hook). The permission
-prompt is the actual gate. Installing all four means a
-sandbox-bypass that lands without your noticing has to skim past
-two banners and silently approve a prompt — a much higher bar
-than skimming a single permission dialog.
-
-### Residual risks
+## Residual risks
 
 This setup substantially shrinks the credential-leakage surface, but
 some risks remain inherent to running an agent against pre-disclosure
@@ -1242,8 +1144,12 @@ content:
   `~/.claude/.mcp.json` and `~/.claude.json` quarterly; remove any
   MCP server you don't actively use.*
 
-### See also
+## See also
 
+- [`secure-agent-internals.md`](secure-agent-internals.md) —
+  mental model for the filesystem-sandbox layer (mechanism,
+  OS-level enforcement on Linux/macOS, the SNI/DoH blind spot,
+  and how the feedback mechanisms layer together).
 - [`AGENTS.md` — Confidentiality of `<tracker>`](AGENTS.md#confidentiality-of-the-tracker-repository)
   — the framework's policy on what tracker content may go where.
 - [`AGENTS.md` — Local setup](AGENTS.md#local-setup) — the wider