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