Skip to content

docs(secure-agent-setup): sandbox-bypass warning hook + private-repo sync pattern#17

Merged
potiuk merged 3 commits into
mainfrom
docs-secure-setup-bypass-hook
Apr 30, 2026
Merged

docs(secure-agent-setup): sandbox-bypass warning hook + private-repo sync pattern#17
potiuk merged 3 commits into
mainfrom
docs-secure-setup-bypass-hook

Conversation

@potiuk

@potiuk potiuk commented Apr 30, 2026

Copy link
Copy Markdown
Member

Summary

  • Adds a Claude Code PreToolUse hook (tools/agent-isolation/sandbox-bypass-warn.sh) that prints a bold-red banner whenever the model invokes Bash with dangerouslyDisableSandbox: true. Belt-and-braces visibility for the existing permission prompt — does not block, just makes the bypass impossible to skim past.
  • Adds a Claude Code statusLine helper (tools/agent-isolation/sandbox-status-line.sh) that renders a continuous indicator in the terminal footer — green [sandbox] when sandbox.enabled: true is set in the resolved settings.json, bold-red [NO SANDBOX] otherwise. Closes the gap the per-call hook leaves: a session that simply never had the sandbox enabled (settings drift, unrelated project, fresh ~) emits no signal at all without it.
  • Adds three sections to secure-agent-setup.md: (1) installing the bypass-warn hook user-scope so it fires in every session on the host, (2) installing the status-line indicator the same way, and (3) keeping the user-scope pieces (hook scripts, status-line script, personal CLAUDE.md, optional global claude-iso.sh) in lockstep across machines via a private dotfile-style repo.
  • Adds two steps to "Adopter setup" recommending both observability features and the multi-machine sync pattern.
  • Regenerates the doctoc-managed TOC at the top of secure-agent-setup.md to include all the new sections (the original commit had flagged this as a follow-up).

Test plan

  • bash -n tools/agent-isolation/sandbox-bypass-warn.sh parses cleanly.
  • bash -n tools/agent-isolation/sandbox-status-line.sh parses cleanly.
  • Hook positive path — emits red banner, exits 1:
    echo '{"tool_name":"Bash","tool_input":{"command":"ls ~/.aws","description":"check creds","dangerouslyDisableSandbox":true}}' \
        | tools/agent-isolation/sandbox-bypass-warn.sh; echo "exit=$?"
  • Hook negative path — silent, exits 0:
    echo '{"tool_name":"Bash","tool_input":{"command":"ls /tmp"}}' \
        | tools/agent-isolation/sandbox-bypass-warn.sh; echo "exit=$?"
  • Status line — sandboxed (run inside this repo where .claude/settings.json sets sandbox.enabled: true):
    echo '{"model":{"display_name":"Sonnet 4.6"},"workspace":{"current_dir":"'"$PWD"'"}}' \
        | tools/agent-isolation/sandbox-status-line.sh
    Expected: Sonnet 4.6 [sandbox] with [sandbox] in green.
  • Status line — un-sandboxed (run from a directory whose .claude/settings.json doesn't enable the sandbox):
    echo '{"model":{"display_name":"Sonnet 4.6"},"workspace":{"current_dir":"/tmp"}}' \
        | tools/agent-isolation/sandbox-status-line.sh
    Expected: Sonnet 4.6 [NO SANDBOX] in bold red.
  • secure-agent-setup.md and tools/agent-isolation/README.md render correctly on GitHub (table cells, code blocks, internal anchors).
  • doctoc TOC at the top of secure-agent-setup.md matches what pre-commit run doctoc would produce — the manual regeneration in commit 287d2e2 + the entry added in 795f69a should be a no-op when CI runs doctoc.

potiuk added 3 commits April 30, 2026 11:38
…sync pattern

Two new sections in `secure-agent-setup.md`:

- "Sandbox-bypass visibility hook" — install + wiring for a
  PreToolUse hook that prints a bold-red banner whenever the
  model invokes Bash with `dangerouslyDisableSandbox: true`.
  Recommended user-scope (`~/.claude/settings.json`) so it fires
  in every session on the host, not just tracker sessions.
  Includes a Verify snippet and Trade-offs notes (visibility-not-
  block; grep-based JSON match for schema robustness).

- "Syncing user-scope config across machines" — the dotfile-style
  pattern for keeping `CLAUDE.md`, hook scripts, and an optional
  global `claude-iso.sh` in lockstep across hosts via a private
  git repo. What-to-track table, repo layout, fresh-host setup,
  a minimal \`sync.sh\`, and a "Why a private repo" rationale.

Also adds two recommended/optional steps to "Adopter setup"
linking to the new sections.

Ships the hook script as \`tools/agent-isolation/sandbox-bypass-warn.sh\`
with the same ASF license header as the sibling \`claude-iso.sh\`,
and adds it to the directory's README files table.

The doctoc-managed TOC at the top of \`secure-agent-setup.md\` is
NOT updated by this commit — re-run doctoc before merging.

Generated-by: Claude Code (Claude Opus 4.7)
The previous commit (35bf73d) flagged that the doctoc-managed TOC
at the top of `secure-agent-setup.md` was not updated when the two
new sections — "Sandbox-bypass visibility hook" and "Syncing
user-scope config across machines" — were added. This commit
regenerates the TOC to include those sections plus their H3
subsections (maxlevel=3, matching `.pre-commit-config.yaml`).

doctoc itself was not run to produce this — it is not installed in
the local environment and the sandbox blocks the npm/uv network
access needed to fetch it. The anchors were instead derived by
hand following the same encoding rules already visible in the
existing TOC entries in this file:

- spaces → `-`
- in-word hyphens preserved (e.g. `user-scope`)
- parentheses, asterisks, periods, backticks dropped without a separator
- em-dash / slash with surrounding spaces → `--`

A future doctoc run (e.g. via the pre-commit hook in CI) should
produce a no-op diff against this TOC.

Generated-by: Claude Code (Claude Opus 4.7)
…footer

Adds a `statusLine` helper that makes the active sandbox state of
the current Claude Code session visible at all times — green
`[sandbox]` when `sandbox.enabled: true` is set in the resolved
`settings.json`, bold-red `[NO SANDBOX]` otherwise. The indicator
sits in the terminal footer that Claude Code already renders, so
no extra UI surface is added; it just makes the existing footer
informative about the *one* configuration property the rest of
this document is about.

Why it is needed even with the existing sandbox-bypass-warn hook:
the `PreToolUse` hook fires per-call when the model requests a
bypass, but a session whose `sandbox.enabled` was simply never set
(e.g. an unrelated project's `.claude/settings.json` is missing,
the user is in `~`, settings drift after a Claude Code upgrade)
emits no signal until something goes wrong. The status line covers
that gap by surfacing settings-level state continuously.

Three changes:

- `tools/agent-isolation/sandbox-status-line.sh` — the helper.
  Reads the statusLine JSON on stdin, resolves
  `.sandbox.enabled` from project- then user-scope `settings.json`
  via `jq`, prints `<model> [sandbox]` (green) or
  `<model> [NO SANDBOX]` (bold red). ASF license header matching
  the sibling scripts; executable bit set.
- `secure-agent-setup.md` — new H2 "Sandbox-state status line"
  between the bypass-warn hook section and the sync-config section
  (sibling user-scope observability features). Adopter step 5 now
  recommends both, the sync-config layout, "what to track" table
  and fresh-host setup snippet pick up the new script. TOC entry
  added by hand following the same encoding rule as the previous
  TOC regen — anchor `#sandbox-state-status-line`.
- `tools/agent-isolation/README.md` — Files table picks up the
  new script.

Trade-offs are documented in-line: the indicator is settings-level
truth, not session-level truth (CLI flags like
`--bypass-permissions` and runtime mode changes that override the
file are not visible), and pairing with the per-call bypass-warn
hook is the recommended belt-and-braces posture. A future Claude
Code statusLine schema that exposes sandbox state directly would
let the helper drop the file-read.

Generated-by: Claude Code (Claude Opus 4.7)
@potiuk potiuk merged commit 15be87f into main Apr 30, 2026
6 checks passed
@potiuk potiuk deleted the docs-secure-setup-bypass-hook branch April 30, 2026 09:57
@andreahlert andreahlert added the mode:platform Substrate / infra — not a mode (sandbox, CI, validators) label May 7, 2026
potiuk pushed a commit that referenced this pull request Jul 3, 2026
* feat(validator): add branch-name confidentiality check (#18, SOFT advisory)

Adds check #17 to skill-and-tool-validator: scans git checkout -b and
git switch -c examples inside fenced code blocks (across skills/ and docs/)
and flags any concrete branch name that contains an embargo-breaking term
— CVE IDs (CVE-YYYY-NNNNN), security, vulnerability/vuln, or advisory.

Pre-disclosure public branch names must not reveal embargo context;
neutral descriptive slugs are the safe alternative.  Lines explicitly
marked as bad examples (**bad**, bad:) are exempt, and placeholder
branch names (<fix-slug>, $VAR) are silently skipped.

The check is SOFT-advisory only (never blocks the run).  14 unit tests
cover CVE IDs, security framing, vuln/advisory terms, placeholder
exemptions, neutral names, and bad-example exemptions.  The full
codebase currently produces zero new violations.

Generated-by: Claude (Opus 4.7)

* fix for tool directories

* change regular expression
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

mode:platform Substrate / infra — not a mode (sandbox, CI, validators)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants