(airflow-steward) 02/02: docs(secure-agent-setup): sync status-line docs with settings.local.json reader

[po...@apache.org]

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

potiuk pushed a commit to branch fix-sandbox-statusline-local-json
in repository https://gitbox.apache.org/repos/asf/airflow-steward.git

commit aab24a43d10b3a2f31bd883a1c5b3b3fe512fc8e
Author: Jarek Potiuk <ja...@potiuk.com>
AuthorDate: Fri May 1 13:52:23 2026 +0200

    docs(secure-agent-setup): sync status-line docs with settings.local.json reader
    
    Match the doc's description of the Sandbox-state status line to the
    script's actual lookup precedence — project settings.local.json first,
    then project settings.json, then ~/.claude/settings.local.json, then
    ~/.claude/settings.json — and call out that `/sandbox` toggles are now
    reflected (since they persist to project settings.local.json). Drop the
    outdated "in-session permission-mode changes are missed" trade-off; CLI
    flags remain the only blind spot.
    
    Co-Authored-By: Claude Opus 4.7 (1M context) <no...@anthropic.com>
---
 secure-agent-setup.md           | 44 ++++++++++++++++++++++++++---------------
 tools/agent-isolation/README.md |  2 +-
 2 files changed, 29 insertions(+), 17 deletions(-)

diff --git a/secure-agent-setup.md b/secure-agent-setup.md
index 0e3e6eb..7cf21e2 100644
--- a/secure-agent-setup.md
+++ b/secure-agent-setup.md
@@ -516,9 +516,18 @@ The framework ships
 [`tools/agent-isolation/sandbox-status-line.sh`](tools/agent-isolation/sandbox-status-line.sh)
 to render exactly that:
 
-- `<model> [sandbox]` in green when the active `settings.json`
-  sets `"sandbox": { "enabled": true }`, OR
-- `<model> [NO SANDBOX]` in bold red when it does not.
+- `<model> [sandbox]` in green when the active settings set
+  `"sandbox": { "enabled": true }`, OR
+- `<model> [NO SANDBOX]` in bold red when they do not.
+
+The script walks the same precedence Claude Code itself uses for
+`sandbox.enabled` — project `settings.local.json` first, then
+project `settings.json`, then `~/.claude/settings.local.json`,
+then `~/.claude/settings.json` — and stops at the first file
+that sets the key (to `true` *or* `false`). The `/sandbox`
+slash-command toggle persists to project `settings.local.json`,
+so flipping it mid-session is reflected in the prefix on the
+next render.
 
 Like the [Sandbox-bypass visibility hook](#sandbox-bypass-visibility-hook),
 this is **complementary**, not authoritative — see Trade-offs
@@ -565,28 +574,31 @@ echo '{"model":{"display_name":"Sonnet 4.6"},"workspace":{"current_dir":"'"$PWD"
 
 Expected output, *inside* this repo (its
 [`.claude/settings.json`](.claude/settings.json) sets
-`sandbox.enabled: true`): `Sonnet 4.6 [sandbox]` with `[sandbox]`
-rendered in green. From a directory whose `.claude/settings.json`
-does **not** enable the sandbox (or does not exist) and whose
-`~/.claude/settings.json` likewise does not set
-`sandbox.enabled: true`, the output is `[NO SANDBOX]` in bold red.
+`sandbox.enabled: true`, and assuming `.claude/settings.local.json`
+either does not exist or does not override the key):
+`Sonnet 4.6 [sandbox]` with `[sandbox]` rendered in green. From a
+directory whose project and user settings files do **not** enable
+the sandbox (or do not exist), the output is `[NO SANDBOX]` in
+bold red.
 
 **Trade-offs.**
 
 - **Settings-level truth, not session-level truth.** The script
   reads `sandbox.enabled` from the file system. It cannot see CLI
-  flags (`--bypass-permissions`, equivalent runtime overrides) or
-  in-session permission-mode changes that override the file —
+  flags (`--bypass-permissions`, equivalent runtime overrides) —
   those still display as `[sandbox]` even though the running
-  session is unprotected. Pair the indicator with the
+  session is unprotected. The `/sandbox` slash-command toggle
+  *is* reflected, because it persists to project
+  `settings.local.json`, which the script reads. Pair the
+  indicator with the
   [Sandbox-bypass visibility hook](#sandbox-bypass-visibility-hook)
   so per-call bypass attempts also surface in real time.
 - **Schema robustness.** The Claude Code statusLine input JSON
-  does not currently expose sandbox state — we read settings.json
-  ourselves. If a future Claude Code release adds a sandbox field
-  to the statusLine input, the script can be simplified to read
-  that field directly. Until then the file-read approach is the
-  only option, with the trade-off above.
+  does not currently expose sandbox state — we read the settings
+  files ourselves. If a future Claude Code release adds a sandbox
+  field to the statusLine input, the script can be simplified to
+  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
 
diff --git a/tools/agent-isolation/README.md b/tools/agent-isolation/README.md
index 34b7f10..a5ceb50 100644
--- a/tools/agent-isolation/README.md
+++ b/tools/agent-isolation/README.md
@@ -29,7 +29,7 @@ versions.
 | [`check-tool-updates.sh`](check-tool-updates.sh) | Reads the manifest and reports upstream releases that are newer than the pin AND have themselves aged past the 7-day cooldown. Side-effect-free — no installs, no edits, no PRs. |
 | [`claude-iso.sh`](claude-iso.sh) | Shell function to launch Claude Code with `env -i` and a tiny passthrough list, stripping every credential-shaped environment variable from the parent shell. The framework's "layer 0" of the secure setup. |
 | [`sandbox-bypass-warn.sh`](sandbox-bypass-warn.sh) | Claude Code `PreToolUse` hook (Bash matcher). Prints a bold-red banner to stderr whenever the model invokes the Bash tool with `dangerouslyDisableSandbox: true`. Belt-and-braces visibility for the sandbox-bypass permission prompt. Recommended user-scope (`~/.claude/settings.json`) so it fires across every session on the host. |
-| [`sandbox-status-line.sh`](sandbox-status-line.sh) | Claude Code `statusLine` helper. Renders `<model> [sandbox]` (green) or `<model> [NO SANDBOX]` (bold red) based on `sandbox.enabled` in the active `settings.json`, so the terminal footer always shows whether the current session is sandboxed. Recommended user-scope. |
+| [`sandbox-status-line.sh`](sandbox-status-line.sh) | Claude Code `statusLine` helper. Renders `<model> [sandbox]` (green) or `<model> [NO SANDBOX]` (bold red) based on `sandbox.enabled` in the active settings — project `settings.local.json` first, then project `settings.json`, then user-scope, mirroring Claude Code's own precedence. Reflects in-session `/sandbox` toggles (which persist to project `settings.local.json`). Recommended user-scope. |
 
 ## Usage at a glance