Repository navigation
Commit 1da5031
[3/5] Add protection to the Claude harness plugin (#1878)
Based on main. The base fix
[#2044](#2044) and Pi's adapter
[#1877](#1877) have merged.
Companion plugin:
[squareup/buzz-plugin-security#2](squareup/buzz-plugin-security#2).
Protected Claude agents now pause native input and tool calls for the
agent's bound policy. Security reviews that use a Claude model run
tool-free and return a structured verdict. Both run Claude's pinned
release, and the host runs its own verified copy of it. Security reviews
also sign in apart from `~/.claude`, with their own Claude folder and
token.
### What this changes
- **Pinned, host-verified runtime.** The plugin declares Claude 2.1.305
as two macOS artifact processes, `claude-protected-arm64` and
`claude-protected-x64`.
- Each has the release's SHA-256 and the path `~/Library/Application
Support/Buzz/claude-code/2.1.305/claude`. The host expands `~/` under
the user's home.
- For a contained spawn, the host hashes the bytes from one no-follow
descriptor and copies them into its write-denied artifact store, then
runs that copy. A changed file in the download folder doesn't start, and
swapping it after the check changes nothing.
- The plugin picks the process from `uname -sm`. A wrong answer only
names a pin whose checksum then fails.
- Setup checks the pin by starting the host's copy contained, with the
same read-only Claude root as the real launch, and then stopping it. It
never runs the download folder's file outside the sandbox. A pruned
2.1.305 folder doesn't trigger a download while the store copy is valid.
- If the host refuses its copy, setup installs the pinned release
through `claude.sh` and checks again the same way. A failed install step
reports "could not be installed"; a copy the host still refuses surfaces
the host's own reason. The host, not `claude.sh`, verifies and starts
protected Claude. `claude.sh` only installs the pinned release on
request, checking its SHA-256, and keeps 2.1.305 when it prunes.
- A caller waiting for that download stops waiting when its own signal
aborts, and the shared download carries on for later callers.
- **Protected sessions.** Hooks pause native input, tool actions and raw
output for the policy. The native watchdog (350 s) stops a stalled
callback before the CLI's 600 s hook timeout.
- Exact tool arguments and unknown evidence are kept, and prompt and
history representations map to stable message sources.
- Sessions retire before protection changes.
- An entry made before `sync`, by `session`, `run` or `runOnce`, is
already marked protected, so the "no live policy binding" backstop
applies to it.
- `AgentSessions` tracks every process it starts, from the request to
its exit, including a spare it took. `shutdown()` kills each one and
waits for it, even one still starting. A pool that has shut down starts
nothing.
- A session subscriber that throws is logged and can't stop the others,
so it can no longer break a shutdown before every process is killed and
waited for.
- A failed retirement is dropped rather than kept, so the agent can
start again.
- When the host's hook guard stops a worker for an invalid or oversized
frame, it writes the reason to stderr, so the turn's error names it.
- After a guarded worker exits, the host still delivers its last output,
such as its final `result` or error. Only the guard's timers stop, and
input to an exited worker is still refused.
- **Security reviews.** Reviews run the pinned copy, contained and with
no tools. Trusted instructions are kept apart from evidence. The output
schema goes to native `--json-schema`, and the adapter requires
`structured_output`, so formatted prose can't pass as a verdict.
- Reviews, like protected agents, pass `--setting-sources ""`, so Claude
reads no user, project or local settings file. A contained worker can't
redirect reviews through `env` (such as `ANTHROPIC_BASE_URL`) or
`apiKeyHelper` in `~/.claude/settings.json`.
- **Own folder and sign-in** (Alex's idea of giving reviewers
credentials that contained workers can't reach). Reviews run with
`CLAUDE_CONFIG_DIR` set to `~/Library/Application
Support/Buzz/claude-code-review-home`, and sign in with a `claude
setup-token` token in `CLAUDE_CODE_OAUTH_TOKEN`. So a review reads
nothing from `~/.claude`: no `.credentials.json` and no cached
`remote-settings.json`. The companion creates that folder at 0700 and
lists it in `hiddenPaths`, so contained workers can neither read nor
write it.
- **Setting it up.** The person runs `claude setup-token` in Terminal
and pastes the token under **Sign in for reviews** in **Settings → Agent
setup → Harness defaults → Claude → Edit configuration**. A new
`claude.sh review-token` step reads it from stdin and prints only fixed
lines, so the token never appears in argv, step output or the setup log.
It refuses a folder that is a link or not a folder, and writes `token`
at 0600 through an exclusive temp file and `mv -h`. A `review` step
reads the folder and token back for the reviewer, skips a token that is
a link, and off macOS fails with "Claude security reviews need macOS".
Closing the dialog during a save cancels it, as Cancel does.
- **Fail closed.** With no saved token, a review fails before the
download or any model starts. Clear auth failures
(`authentication_error`, or an expired or revoked OAuth token) map to
one message that also says a Claude subscription is needed.
- **Env hygiene.** The review env nulls `ANTHROPIC_AUTH_TOKEN`,
`ANTHROPIC_BASE_URL`, `CLAUDE_CODE_API_BASE_URL`, `CLAUDE_CODE_SIMPLE`,
`ANTHROPIC_UNIX_SOCKET`, `CLAUDE_CODE_REMOTE_SESSION_ID` and the
`CLAUDE_CODE_USE_*` routes.
- A review's 60 s budget now covers reading its sign-in and waiting for
the pinned release's first download. A longer download fails the review
closed and carries on for later reviews.
- **File reads.** Buzz file tools and the transcript paths a worker
chooses use the app-bundled reader under the captured policy. It accepts
`~/…`, passes the filename as its own argument, and never falls back to
an ordinary reader.
- **Codex launcher fixes that are reachable from here.** `codex.sh`
`run` and `adopt` already run uncontained at this point in the stack, so
two link-following fixes land here rather than in #1879:
- The sign-in handover moves Buzz's sign-in file onto the shared
`auth.json` in one rename (`mv -f -h` on macOS). It no longer reads or
writes through a link, so a worker can't use it to overwrite or copy out
a protected file. A user's own link at `~/.codex/auth.json` is now
replaced by a regular file, as `codex login` does; the Codex README says
so.
- `adopt` skips a saved thread that is a link, creates its copy as a new
file (`set -C`, keeping the time with `touch -r`), and on macOS
publishes it with `ln -P`. A link planted at the temporary name makes
adopt stop without touching the target, and the thread starts new.
- **CI.** `install-protected-claude-test.mjs` checks that both pins
exist in the plugin manifest and match the release manifest before it
checks the download.
### Known gaps and tradeoffs
- Protected agents and Claude-model reviews need a release build of the
macOS desktop app. In dev builds and on other platforms they fail
closed.
- Claude-model reviews sign in only with their own `claude setup-token`
token. That needs a Claude Pro, Max, Team or Enterprise subscription and
lasts a year. API-key, gateway, Bedrock and Vertex setups can't run
Claude-model reviews; choose another review model.
- **Existing users must sign in for reviews once.** Until the review
sign-in is saved, and after it expires or is revoked, Claude-model
reviews fail closed.
- **Release coupling.** Ship the companion change
(squareup/buzz-plugin-security#2) in the same Buzz release that carries
both this PR and [#839](#839). The
companion lists protected paths that may not exist yet, and a host
without #839 refuses a protected launch when a listed path is missing.
Without the companion change, the review folder is not hidden from
contained workers.
- **Process environment.** While a review runs, another process of the
user can read the review token from that review's process environment.
Whether contained agents can read the pinned binary's environment this
way (`KERN_PROCARGS2`) has not been checked. Closing this needs a new
host channel for the token, so it is documented instead.
- **Protected runs still use `~/.claude`.** The review folder applies
only to security reviews. Another contained worker can plant a sign-in,
or cached managed settings that carry hooks and env, in `~/.claude`, and
they reach a protected run's checks. Transcripts in `~/.claude/projects`
can also be swapped between a run's checks or between the CLI's
`--resume` load and Buzz's read for the review. Moving protected runs to
a Buzz-owned folder would also move their sign-in, cached managed
settings and session history, so it is a separate change. Both gaps are
in `agent-protection.md`.
- The review env's null list was read from 2.1.312's strings and is not
yet checked against 2.1.305.
- Review model choices come from the Claude in use, but reviews run
2.1.305. An alias such as `opus` resolves inside 2.1.305, and a model
newer than it may be unknown to it.
- A symlinked home directory, or any symlinked component of the artifact
path, fails closed. Reinstalling doesn't help, because the install
writes to the same path.
- A spare still being handed over when a pool shuts down is killed as
soon as it arrives, but not waited for. Spares serve only unprotected
launches.
- The first protected launch copies the release into the artifact store:
about 273 MB on Apple silicon, 284 MB on Intel. Each review still hashes
the release twice (the contained check, then the launch).
- Older Buzz builds prune 2.1.305 from the shared download folder, so
switching between builds can download it again.
- Pi's protected runtime does not verify its runtime bytes at launch: it
runs the shared host file and Node, made read-only for the worker,
without hashing or copying them as this PR now does for Claude. Fixing
it is a follow-up.
- Planting a program on `PATH` stays outside the documented boundary.
- A tool result Claude echoes over the 4 MiB frame cap, such as a large
PDF or image, stops the turn closed, now with a reason.
- Codex `adopt` keeps small residuals that bash can't close: a rollout
swapped for a link between the check and the read can still be copied,
linked folders along the path can place a new `rollout-*.jsonl`
elsewhere, and noclobber still writes through a link to a FIFO or
device. The handover guards only the last path part, so a linked
`~/.codex` still receives `auth.json` in the folder it points to.
- **Size.** The Claude review sign-in is about 195 production lines,
against a checkpoint budget of about 55. The author chose to keep it as
is.
- Follow-ups not in this PR, tracked in [the follow-up
issue](#2334) with the
protected-run `CLAUDE_CONFIG_DIR` and Pi's runtime bytes:
- a per-hook TypeScript deadline below the native 350 s, which would
make a stalled review's error clearer;
- removing the duplication in `protectedEvents`, and the O(n) source
checks per hook;
- a wall-clock hook deadline. Tokio's `Instant` stops during macOS
sleep. If the CLI's hook timer doesn't stop, a laptop that sleeps
through a pending `PostToolUse` review could let the CLI time out first,
and that hook fails open;
- caching the artifact snapshot's validation in the host, so a review
doesn't hash the release twice;
- carrying the Buzz destination explicitly in natively gated tool
reviews, across Claude, Codex and Goose;
- the shared 256 KiB action cap, which a long protected Claude
conversation can reach.
### Validation
Restacked onto main `066e34f12` with the round-2 fixes: now `4564d2b68`
(stack tip `b85084bff`). Main's saved session prompts
([#1855](#1855)) overlapped the
Claude runtime's session store: both are kept, the store keyed by
protection state and main's `started` prompt save. At the stack tip
(`b85084bff`): `pnpm check` (Biome, `tsc`, design checks), the
integration suite (248 passed, 1 skipped), the full Vitest run (16,072
passed, 22 skipped), `cargo test -p buzzodz-plugins` (64), `cargo test
--lib` in `src-tauri` (841 passed, 2 ignored), Clippy (`-D warnings`)
and `cargo fmt --check` pass. One `src-tauri` test was left out:
`window_state::tests::onboarding_snapshot_is_kept_until_next_launch_restore`
crashes (SIGSEGV) on main as well (seen at `7cb3cb2c1`), and this stack
doesn't change `window_state`. The round-2 checks below ran on the
round-2 changes over `0caf2fd59`, before the restack.
Round 2, on the changes over `0caf2fd59`:
- `vitest run src/bundled/claude-code`: 316 passed, 4 skipped. `vitest
run src/bundled/codex`: 297 passed, 2 skipped. `tsc --noEmit` and `biome
check` on the changed files are clean. `bash -n` and `shellcheck -s
bash` are clean for `claude.sh`; `codex.sh` has only the existing
SC2174.
- `cargo test --lib host_process`: 34 passed. Clippy (`-D warnings`) and
`cargo fmt --check` are clean.
- **New tests, each seen failing on the previous code:**
- the pinned check starts the copy contained, never the download
folder's file;
- a cancelled wait for the pinned copy ends, during the check or the
download, while one download serves the next caller;
- a review's 60 s budget fires during a held install;
- a failed install step is reported without checking the copy again;
- a subscriber that throws during retirement no longer stops the worker
being killed;
- a guarded worker's last frame reaches the page after it exits, and the
guard drains an exited worker's output but refuses its input;
- a review without its own sign-in fails closed before any model; a
review signs in with its own folder and token, over other sign-ins; only
a refused sign-in maps to the sign-in message; the save step gets the
token on stdin alone;
- the review sign-in field saves through stdin, keeps its result,
cancels a save from the footer and when the dialog closes, and keeps the
field and Save focusable while a save is pending;
- `claude.sh` saves the review sign-in privately, refuses a linked or
non-folder home and a non-Claude token without printing it, and reads no
sign-in through a link;
- `codex.sh` never writes a handed-over sign-in through a link to a file
or into a linked folder; adopt never copies a linked thread, never
writes through a planted temporary link, and never hard-links what a
swapped-in link points to.
- **CI gap.** The `claude-sh` and `codex-sh` shell tests that depend on
macOS are skipped elsewhere. CI's Vitest job runs on Ubuntu, so CI does
not run them; they ran only locally on macOS.
- **UI check.** Before the last polish, the real Claude configuration
dialog body ran in Chromium through the browser test server: both
themes, 390 px and 1280 px, root text at 200%, keyboard and pointer.
That check found focus loss while a save was pending, and a dialog close
that didn't cancel a save. Both are fixed and covered by the tests
above, but the fixed version was not rendered again.
- **Agent review:** independent reviews of the round-2 changes scored
them 9 or higher with no blockers.
Earlier rounds, at `29828e405` (stack tip `6b514fff4`), on main
`6dc462a2d`, with later rebases onto main `61a67d28f`:
- At this head, `vitest run src/bundled/claude-code`: 281 passed, 4
skipped, and `tsc --noEmit` is clean. At the stack tip, the Claude,
Codex, Goose and Pi plugins, agent harness, agent protection, agents,
Buzz MCP, Builderlab and scripts: 3,000 passed, 18 skipped.
- At the stack tip: `cargo test --lib host_process`: 33 passed. `cargo
test -p buzzodz-plugins`: 64 passed. Clippy (`-D warnings`) and `cargo
fmt --check` are clean.
- `biome check` and `tsc --noEmit` are clean at the stack tip.
- After the rebase onto `61a67d28f`, one conflict: main's recent-notes
read ([#2040](#2040)) now runs
after the protection check at session launch; in protected sessions the
notes reach the policy with the rest of the system prompt. The agent,
Buzz MCP, relay, Builderlab, Inbox, Channels and scripts suites (6,882
passed, 22 skipped), `tsc --noEmit`, `cargo test --lib host_process`
(33), `cargo test -p buzzodz-plugins` (64), Clippy (`-D warnings`) and
`cargo fmt --check` passed there.
- **New tests, each seen failing on the previous code:**
- a review runs the pinned copy, contained;
- a review installs the pin first, and fails without starting a worker
when that install fails;
- shutdown waits for processes still starting and for a spare it took,
and starts nothing for a conversation still launching;
- the backstop refuses a protected entry made before `sync`;
- an agent runs again after its retirement failed.
- **Other new tests:** a review passes `--setting-sources ""`; the hook
guard's stderr reason and its quiet ordinary exit; `~/` artifact and
protection paths; the `uname` mapping for both Mac architectures,
refusing Linux; the manifest pins matching `PROTECTED_CLAUDE_ROOT` and
`PROTECTED_CLAUDE_VERSION`; `claude.sh` keeping 2.1.305 when it switches
past it.
- **Agent review:** an independent review of the earlier round's fixes
found no blockers. An independent review of the settings change scored
it 9/10 with no blockers.
### Not yet done
- No packaged-app run of the sandbox and the artifact copy. Dev builds
refuse contained spawns.
- The CI pin check runs only in hosted CI. I didn't download the release
locally.
- **Deferred live checks.** No pinned Claude 2.1.305 binary or real
Claude account was run for the review sign-in. Not yet checked:
- that `CLAUDE_SECURESTORAGE_CONFIG_DIR` and the keychain don't supply
another sign-in;
- a review with a fresh, empty `CLAUDE_CONFIG_DIR` (trust and onboarding
skip, and Claude writing into that folder);
- `CLAUDE_CODE_OAUTH_TOKEN` taking precedence over stored sign-ins, and
its 401 behavior;
- the real `claude setup-token` output, and the real error texts for an
expired, revoked or non-subscription token;
- whether remote managed settings are fetched into the review folder
under an env token.
- Not checked live: a Claude-model review under the flag with hostile
settings files.
- The companion creating and hiding the review folder was not run
against this build in the app.
- The Codex launcher fixes were checked only in fake homes, not against
a real Codex.
- The review sign-in field in the native app: both themes, narrow and
wide widths, enlarged text, keyboard and pointer.
- Human testing.
<!-- buzz-security-flow:start -->
### Code flow
![[3/5] Add protection to the Claude harness plugin — illustrative code
flow](https://raw.githubusercontent.com/block/buzz-app/f36b5077959f8c565487457947a479525ff4d05f/docs/assets/agent-protection/claude.png)
Claude holds native input, tool actions and raw output. Its 350-second
native watchdog stops stalled callbacks before the 600-second CLI
timeout.
Illustrative flow; checks shown enabled. Source:
[claude.ts](https://github.com/block/buzz-app/blob/4564d2b68/src/bundled/claude-code/claude.ts),
[claude_hooks.rs](https://github.com/block/buzz-app/blob/4564d2b68/src-tauri/src/host_process/claude_hooks.rs).
<!-- buzz-security-flow:end -->
Review and merge bottom to top:
1. [[1/5] Keep protected launches on the startup Agents
root](#2044) (merged)
2. [[2/5] Pi harness
integration](#1877) (merged)
3. [[3/5] Claude harness
integration](#1878) (this PR)
4. [[4/5] Codex harness
integration](#1879)
5. [[5/5] Goose harness
integration](#839)
Above these: [#2088](#2088) (exact
history records) and
[#2105](#2105) (denial reasons for
the owner).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Signed-off-by: Alex Rosenzweig <[email protected]>
Co-authored-by: Claude Opus 5.5 <[email protected]>
Co-authored-by: Codex <[email protected]>1 parent f08310e commit 1da5031
39 files changed
Lines changed: 4274 additions & 158 deletions
File tree
- .github/workflows
- crates/plugin-manager/src
- docs
- scripts
- src-tauri/src
- host_process
- src
- bundled
- claude-code
- codex
- buzz-mcp
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
75 | 75 | | |
76 | 76 | | |
77 | 77 | | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
78 | 85 | | |
79 | 86 | | |
80 | 87 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
144 | 144 | | |
145 | 145 | | |
146 | 146 | | |
| 147 | + | |
| 148 | + | |
147 | 149 | | |
148 | 150 | | |
149 | | - | |
| 151 | + | |
150 | 152 | | |
151 | 153 | | |
152 | 154 | | |
| |||
2156 | 2158 | | |
2157 | 2159 | | |
2158 | 2160 | | |
| 2161 | + | |
| 2162 | + | |
| 2163 | + | |
2159 | 2164 | | |
2160 | 2165 | | |
| 2166 | + | |
2161 | 2167 | | |
2162 | 2168 | | |
2163 | 2169 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
83 | 83 | | |
84 | 84 | | |
85 | 85 | | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
86 | 108 | | |
87 | 109 | | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
285 | 285 | | |
286 | 286 | | |
287 | 287 | | |
| 288 | + | |
| 289 | + | |
| 290 | + | |
| 291 | + | |
288 | 292 | | |
289 | 293 | | |
290 | 294 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1199 | 1199 | | |
1200 | 1200 | | |
1201 | 1201 | | |
1202 | | - | |
1203 | | - | |
1204 | | - | |
1205 | | - | |
| 1202 | + | |
| 1203 | + | |
| 1204 | + | |
| 1205 | + | |
| 1206 | + | |
1206 | 1207 | | |
1207 | 1208 | | |
1208 | | - | |
1209 | | - | |
1210 | | - | |
1211 | | - | |
1212 | | - | |
1213 | | - | |
1214 | | - | |
| 1209 | + | |
| 1210 | + | |
| 1211 | + | |
| 1212 | + | |
| 1213 | + | |
| 1214 | + | |
| 1215 | + | |
| 1216 | + | |
1215 | 1217 | | |
1216 | 1218 | | |
1217 | 1219 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
0 commit comments