docs(secure-agent-setup): sandbox-bypass warning hook + private-repo sync pattern#17
Merged
Conversation
…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)
This was referenced Jul 3, 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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
PreToolUsehook (tools/agent-isolation/sandbox-bypass-warn.sh) that prints a bold-red banner whenever the model invokes Bash withdangerouslyDisableSandbox: true. Belt-and-braces visibility for the existing permission prompt — does not block, just makes the bypass impossible to skim past.statusLinehelper (tools/agent-isolation/sandbox-status-line.sh) that renders a continuous indicator in the terminal footer — green[sandbox]whensandbox.enabled: trueis set in the resolvedsettings.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.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, personalCLAUDE.md, optional globalclaude-iso.sh) in lockstep across machines via a private dotfile-style repo.secure-agent-setup.mdto 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.shparses cleanly.bash -n tools/agent-isolation/sandbox-status-line.shparses cleanly..claude/settings.jsonsetssandbox.enabled: true):Sonnet 4.6 [sandbox]with[sandbox]in green..claude/settings.jsondoesn't enable the sandbox):Sonnet 4.6 [NO SANDBOX]in bold red.secure-agent-setup.mdandtools/agent-isolation/README.mdrender correctly on GitHub (table cells, code blocks, internal anchors).secure-agent-setup.mdmatches whatpre-commit run doctocwould produce — the manual regeneration in commit287d2e2+ the entry added in795f69ashould be a no-op when CI runs doctoc.