Skip to content

fix(#8259): verify Claude hooks.json and hook scripts before each launch - #8261

Merged
waynesun09 merged 8 commits into
mainfrom
agent/8259-claude-hooks-integrity
Oct 16, 2026
Merged

waynesun09 merged 8 commits into
mainfrom
agent/8259-claude-hooks-integrity

Conversation

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor

Summary

The Claude runtime loaded /sandbox/claude-config/hooks.json via --settings on every iteration but never checked it or the hook scripts under /sandbox/claude-config/hooks/. The agent can write to both, so iteration 1 could weaken the security hooks and iteration 2 would load the change. Each launch now checks both against digests held on the runner side and refuses to start (exit 97) on a mismatch. This is the same approach the codex runtime already uses.

Related Issue

#8259

Changes

  • internal/runtime/claude_integrity.go (new):
    • Bootstrap records runner-side digests, keyed by sandbox name: the SHA-256 of the uploaded hooks.json, plus each installed script's name and the digest of its embedded copy.
    • The launch guard reuses the codex helpers (codexSHACheck, codexHookScriptsGuard, codexAssetSHA256). It binds each digest to its filename and checks the directory exhaustively: no extra entries, no symlinks or subdirectories.
  • internal/runtime/claude.go:
    • installClaudeHooks records the digests after a successful upload.
    • Run fails closed (exit -1) when hooks are enabled but no digests were recorded.
    • buildRunCommand runs the guard before sourcing .env, then again after it behind unset -f, using command -p utilities, so a .env that rewrites a file or shadows sha256sum is still caught.
    • Exit 97 is reported as tampered hooks.
  • internal/security/hooks.go: hook commands now run python3 -B. Without it the PostToolUse chain writes hooks/__pycache__/ during iteration 1, and the exhaustive check would then refuse iteration 2 of every run.
  • Docs: runtime-implementation.md (hook contract, feature matrix, codex and pi comparisons), the threat model, and a troubleshooting entry in docs/runtimes/claude.md.
  • Decided out of scope, and documented:
    • Claude Code's own claude-config/settings.json (plugin state written by bootstrapPlugins);
    • the target repo's <repo>/.claude/settings.json;
    • rewrites during an iteration.
  • Digest eviction: like codex, the digests are never evicted. The runner is a one-shot process and sandbox names are unique per run.

Testing

  • make lint: pre-commit could not fetch its hook repos in the sandbox (TLS error). I ran the local hooks directly instead: gofmt, go vet, lint-interface-doc-sync, lint-docs-links, lint-mint-embed-sync, lychee, plus whitespace and EOF checks. All passed.
  • Tests added or updated for new and modified logic:
    • Launch tests run the real shell guard against temp directories. They change hooks.json or a script between iterations and assert iteration 2 is refused. Changes covered: modify, append, delete, swap in another allowed script, plant __pycache__/ or a json/ package, rewrite a file from .env, and shadow sha256sum with a function and a PATH entry.
    • Untouched files still pass, and empty digests fail closed.
    • A test runs the real PostToolUse command from hooks.json with PYTHONDONTWRITEBYTECODE unset and asserts the guard still passes. I confirmed this test fails without -B.
    • Unit tests cover digest recording and lookup, Run failing closed without recorded digests, and Run reporting exit 97.
  • go test ./internal/runtime/ passes. Patch coverage on the changed Go lines is about 95%.
  • Pre-existing failures, which also fail on the base commit in this sandbox:
    • TestSSRFValidator_DNSResolution and TestSSRFValidator_EgressAllowlist (internal/security; sandbox DNS);
    • TestStartFetchService_* and TestPostScriptEnv_NoSchemaAppended* (internal/cli).

🤖 Generated with Claude Code


Closes #8259

Post-script verification

  • Branch is not main/master (agent/8259-claude-hooks-integrity)
  • Secret scan passed (gitleaks — 003926f5cd3a1f8dc33a32b66964960891ed738a..HEAD)
  • PR body secret scan passed (gitleaks — no-git)

The Claude runtime passed --settings /sandbox/claude-config/hooks.json on
every iteration but never checked it or the hook scripts under
/sandbox/claude-config/hooks/. The agent runs as the user that wrote both,
so iteration 1 could rewrite them and iteration 2 would load the edits.

Port the codex launch guard to Claude, reusing its helpers:

- Bootstrap (installClaudeHooks) records, runner-side and keyed by sandbox
  name, the digest of the hooks.json it uploaded and the embedded digest
  of each hook script it installed.
- Run refuses with exit -1 when hooks are enabled but no digests were
  recorded. Otherwise the launch checks hooks.json and runs the exhaustive
  hooks-directory check (codexHookScriptsGuard) before sourcing .env, then
  again after it behind `unset -f`, using `command -p` utilities. A
  mismatch exits 97, which Run reports as tampered hooks.
- The hook commands now run `python3 -B`. Without it, running the
  PostToolUse chain writes hooks/__pycache__/, and the exhaustive check
  would refuse iteration 2 of every run.

Not covered here: Claude Code's own claude-config/settings.json (plugin
state from bootstrapPlugins), the target repo's .claude/settings.json, and
rewrites during an iteration. The docs now say so.

Launch tests change hooks.json or a script between iterations (modify,
append, delete, swap, plant __pycache__ or a json/ package, rewrite from
.env, shadow sha256sum) and assert iteration 2 is refused.

Pre-existing failures that also occur on the base commit in this sandbox:
TestSSRFValidator_DNSResolution and TestSSRFValidator_EgressAllowlist
(internal/security), and TestStartFetchService_* and
TestPostScriptEnv_NoSchemaAppended* (internal/cli). pre-commit could not
fetch its hook repos (TLS), so the local hooks were run directly.

Closes #8259

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@fullsend-ai-review

Copy link
Copy Markdown

🤖 Review · ⚠️ Cancelled · Ended 3:46 PM UTC

Commit: d828205 · View workflow run →

@fullsend-ai-review

fullsend-ai-review Bot commented Oct 9, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 3:48 PM UTC · Completed 3:58 PM UTC

Commit: d828205 · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $3.07

@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown

Site preview

Preview: https://df5a090f-site.fullsend-ai.workers.dev

Commit: d139709870f4b9e77696cfcf12cdfb7465caa4c4

@codecov

codecov Bot commented Oct 9, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 93.18182% with 6 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
internal/runtime/claude.go 85.36% 3 Missing and 3 partials ⚠️

📢 Thoughts on this report? Let us know!

@fullsend-ai-review fullsend-ai-review Bot added the risk/moderate PR risk: moderate label Oct 9, 2026
@fullsend-ai-review

fullsend-ai-review Bot commented Oct 9, 2026 •

Copy link
Copy Markdown

Risk Assessment: moderate (2/5)

Details

Moderate risk preserved following re-review anchoring, driven by unflagged modifications to runtime launch behavior and elevated file churn, balanced by complete acceptance criteria coverage and low metadata risk from a familiar bot author with no protected path edits.

Previous run

Risk Assessment: moderate (2/5)

Details

Moderate risk preserved following re-review anchoring, driven by unflagged modifications to runtime launch behavior and elevated file churn, balanced by complete acceptance criteria coverage and low metadata risk from a familiar bot author with no protected path edits.

Previous run (2)

Risk Assessment: moderate (2/5)

Details

Moderate risk preserved following re-review anchoring, driven by unflagged modifications to runtime launch behavior and elevated file churn, balanced by complete acceptance criteria coverage and low metadata risk from a familiar bot author with no protected path edits.

Previous run (3)

Risk Assessment: moderate (2/5)

Details

Moderate risk driven by unflagged modifications to existing runtime launch behavior and elevated churn in touched files, balanced by complete acceptance criteria coverage and low metadata risk from a familiar bot author with no protected path edits.

Previous run (4)

Risk Assessment: moderate (2/5)

Details

Moderate risk driven by unflagged modifications to existing runtime launch behavior and elevated churn in touched files, balanced by complete acceptance criteria coverage and low metadata risk from a familiar bot author with no protected path edits.

Previous run (5)

Risk Assessment: moderate (2/5)

Details

Moderate risk: a focused security fix by an automated bot with complete acceptance criteria coverage and no protected-path edits, balanced by high churn and coupling across the touched runtime files and a change to launch behavior without a feature flag.

@fullsend-ai-review

fullsend-ai-review Bot commented Oct 9, 2026 •

Copy link
Copy Markdown

Review

Findings

Medium

  • [sandbox-escape] internal/runtime/claude_integrity.go:157 — The post-.env cleanup in claudeGuardedEnv (unset -f claude test command cut wc sha256sum find echo) does not unset [, but both guards depend on it: codexSHACheck wraps every digest comparison in [ ... ], and codexHookScriptsGuard uses [ -z ... ] and [ ... -eq N ] for the directory checks. The doc comment at line 102 gives the same reason for test, [ and echo, but only two of the three are unset. The pi runtime's equivalent cleanup (pi_run.go:576, :604) includes [. If a shell that accepts [ as a function name ran the launch (for example bash outside POSIX mode), .env could rewrite hooks.json or a hook script and define an always-true [, and the second guard would pass. In the documented launch shell (sh -c, which is dash in the sandbox image) this is not exploitable. Running [() { return 0; } under dash gives Bad function name, a syntax error that aborts the sourcing shell. That is why this is medium and not high. The gap is still a real defense-in-depth inconsistency with pi.
    Remediation: Add [ to the post-.env unset -f list in claudeGuardedEnv (as pi_run.go:576 does), or rewrite the guard comparisons to use test, which is already unset. Add a regression test that sources a .env that rewrites a hook and tries to define [, and assert that launch exits 97 or fails closed.

  • [incomplete-doc] docs/reference/harness-reference.md:187 — This PR adds PYTHONUSERBASE to claudeLoaderEnvUnset (internal/runtime/claude.go:47) and to the table in docs/runtimes/claude.md:233. The .env.d host files paragraph in the harness reference lists the variables Claude runs unset after .env.d files (LD_PRELOAD, LD_LIBRARY_PATH, LD_AUDIT, PYTHONPATH, PYTHONHOME, PYTHONSTARTUP, NODE_OPTIONS, NODE_PATH, BUN_OPTIONS) and omits PYTHONUSERBASE.
    Remediation: Add PYTHONUSERBASE to the Claude unset list in that paragraph, so it matches claudeLoaderEnvUnset and docs/runtimes/claude.md.

Earlier findings

  • f_0a94e75ba421ec61 — reclassified high → medium. The [ gap is still present in claude_integrity.go, but [() {...} is a Bad function name syntax error under dash, the sandbox sh. The bypass needs a shell that accepts the name. It is still listed above.

Labels: PR hardens the sandboxed Claude runtime launch in Go and touches security docs.


Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR
Previous run

Review

Findings

High

  • [sandbox-escape] internal/runtime/claude_integrity.go:156 — The guard is still bypassable because the launch shell sources the agent-writable .env between the two guard passes. An earlier iteration can leave the hooks intact on the first pass, then use .env to rewrite hooks.json and exec Claude. exec replaces the shell, so the unset -f, the loader-variable clearing and the second integrity pass never run. This is a synchronous bypass, not just the documented background-process window.
    Remediation: Do not execute agent-writable shell code in the trusted launch sequence. Parse permitted environment assignments as data, keep security configuration on the runner, and launch through trusted code that always verifies first. Add a regression case where .env rewrites the hooks and tries to exec Claude before returning.

Medium

  • [incomplete-doc] docs/reference/harness-reference.md:187 — The .env.d host files paragraph lists the variables Claude runs unset after sourcing, but omits PYTHONUSERBASE. This PR added it to claudeLoaderEnvUnset and to docs/runtimes/claude.md.
    Remediation: Add PYTHONUSERBASE to the list so it matches claudeLoaderEnvUnset and docs/runtimes/claude.md.

Low

  • [code-organization] internal/runtime/claude_integrity.go:68 — The Claude guard calls codex-prefixed helpers (codexAssetSHA256, codexHookScriptsGuard, codexSHACheck, codexPreflightPython). Other cross-runtime mechanisms live in runtime-neutral files with neutral names. This is a maintainability issue only, and the commit message says the move was deliberately left out of scope.
    Remediation: Move the shared helpers to a runtime-neutral file, rename them, and update the codex and Claude call sites.
  • [naming-convention] internal/security/hooks.go:371 — shellSingleQuote duplicates the helper that internal/sandbox, internal/runtime and internal/cli all name shellQuote.
    Remediation: Rename it to shellQuote and update its call sites in GenerateHooksConfigPinned.
  • [error-handling-idiom] internal/runtime/claude.go:372 — The HooksSettingsPath error quotes the supplied path with %q but prints security.SandboxHooksSettings with %s. docs/contributing/go-code.md says to use %q for values in error messages.
    Remediation: Change the format to "HooksSettingsPath %q is not %q: ...".
Previous run (2)

Review

Findings

High

  • [sandbox-escape] internal/runtime/claude_integrity.go:140 — Prior finding f_0a94e75ba421ec61 is still present. The interpreter/PYTHONPATH bypass is addressed, but the agent-writable .env still controls the launch after both integrity checks. For example, an earlier iteration can append claude() { printf '{"hooks":{}}' > /sandbox/claude-config/hooks.json; command /usr/local/bin/claude "$@"; } to .env. Both guards see the original files, and unset -f test command cut wc sha256sum find echo does not remove that function. buildRunCommand then invokes bare claude, so the function rewrites hooks.json just before the real CLI loads it via --settings. A claude wrapper on a PATH that .env prepends gives the same bypass. Pinning the hook interpreter and hook PATH does not protect this path.
    Remediation: Do not source the agent-writable .env as executable shell in the trusted launch process. Take environment assignments from runner-held state, or parse a restricted data format without evaluating shell syntax, then run a pinned absolute Claude executable in a clean launch environment. Add regression tests for a .env-defined claude function and a PATH wrapper that rewrite hooks.json immediately before forwarding to Claude.

Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR
Previous run (3)

Review

Findings

High

  • [sandbox-escape] internal/runtime/claude_integrity.go:129 — The launch guard checks the bytes of hooks.json and the hook scripts and clears LD_PRELOAD/LD_LIBRARY_PATH/LD_AUDIT. It does not restore PATH or unset PYTHONPATH/PYTHONHOME/PYTHONSTARTUP after sourcing the agent-writable .env. The hook command in internal/security/hooks.go is still a bare python3 -B <script>. An earlier iteration can export a PATH entry holding a fake python3, or a PYTHONPATH with a sitecustomize.py that exits 0. Neither changes a checked file, so both guard passes succeed and the security hooks are skipped on the next iteration. That is the same threat Claude runtime does not check hooks.json or hook scripts between validation iterations #8259 sets out to close. The codex runtime pins an absolute interpreter with -I, pins PATH across .env, and unsets PYTHON*. This PR documents the gap as "Not covered" (ADR 0100, runtime-implementation.md, threat model) but does not fix it. Documenting a gap does not resolve it, and the code at this location is unchanged since the prior review. The severity stays anchored at high. The challenger argued for medium because the gap predates this PR. That is not enough to show the earlier assessment was clearly incorrect.
    Remediation: Do what codex does. Resolve an absolute python3 at Bootstrap and render it with -I into the Claude hooks.json, so the hooks.json digest covers it. Capture PATH before .env and restore it after. Unset PYTHONPATH, PYTHONHOME and PYTHONSTARTUP alongside LD_*. Add regression tests showing that a fake python3 on PATH and an injected sitecustomize.py cannot stop the hooks from running.

Earlier findings

  • f_ba73f4b59f20a7cd — resolved_by_change: the incremental diff adds an "Implementation note (October 2026)" to docs/ADRs/0100-codex-sandbox-hooks.md, above the passage on residual script writability. It states that Claude Code now checks hooks.json and the hook scripts before each launch (exit 97) and still does not pin the interpreter or PATH.

Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR
Previous run (4)

Review

Findings

High

  • [sandbox-escape] internal/runtime/claude_integrity.go:129 — After the launch sources the agent-writable .env, the hardening clears only LD_PRELOAD, LD_LIBRARY_PATH and LD_AUDIT and runs unset -f on the hashing utilities. PATH, PYTHONPATH and PYTHONHOME stay under the agent's control and are inherited by claude and its hook subprocesses. GenerateHooksConfig runs every hook as bare python3 -B <script> (internal/security/hooks.go:201), which is a PATH lookup, and without -I the interpreter still honours PYTHONPATH, PYTHONHOME and sitecustomize. An earlier iteration can put a fake python3 first on PATH, or plant a sitecustomize.py via PYTHONPATH, through .env. hooks.json and the scripts stay byte-identical, so both digest passes succeed, yet the security hooks never really run in the next iteration. The codex launch pins the interpreter (absolute path, -I, -B) and PATH across .env for exactly this reason (ADR 0100, Decision). The new docs say Claude Code "no longer shares this residue" and sit it beside codex, which overstates what this change protects.
    Remediation: After sourcing .env, restore a trusted PATH and run hooks with an absolute interpreter path and isolated startup (-I or equivalent, plus -B) so PYTHONPATH, PYTHONHOME and user-site/sitecustomize are ignored while imports from the verified hooks directory still work. Add launch-plus-hook tests that plant a fake python3 on PATH and a sitecustomize.py via PYTHONPATH and assert the real hook still runs. If deferred, list interpreter/PATH/env pinning under "Not covered" in docs/contributing/runtime-implementation.md and drop the "no longer shares this residue" wording.

Low

  • [stale-doc] docs/ADRs/0100-codex-sandbox-hooks.md:58 — ADR 0100 says the hook scripts stay agent-writable between iterations, "the residue Claude Code and pi also have" (and, in Consequences, that on the other two runtimes the pinning is "agent-writable between iterations with no check"). Since this PR, Claude Code checks hooks.json and the scripts before each launch, so the script-integrity part is out of date; the interpreter/PATH/config pinning part remains accurate for Claude. Accepted ADRs are point-in-time records, so at most a short annotation is warranted (optional).
    Remediation: Optionally add a short implementation note like the existing September 2026 note: since Claude runtime does not check hooks.json or hook scripts between validation iterations #8259 Claude Code checks hooks.json and the hook scripts before each launch (exit 97) but does not pin the interpreter or PATH. Mention the edit in the PR description per docs/contributing/adrs.md.

Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR
Previous run (5)

Review

Findings

Medium

  • [integrity-bypass] internal/runtime/claude_integrity.go:126 — After sourcing .env, the second-pass guard only runs unset -f ...; it does not clear LD_PRELOAD, LD_LIBRARY_PATH or LD_AUDIT. A .env written in an earlier iteration can modify hooks.json or a hook script and export a preload library that makes the real sha256sum print the expected digest, so the second guard passes. The codex launch clears these variables before its second guard (codex_run.go:365).
    Remediation: after . .env and before the second guard, run unset LD_PRELOAD LD_LIBRARY_PATH LD_AUDIT (matching codex_run.go:365), keeping the chain fail-closed. Add a launch test that asserts the unset comes after the .env source.
  • [stale-doc] docs/architecture.md:951 — Says pi's hook-adapter integrity check "has no Claude Code equivalent", and the following flowchart shows Claude launching without a check. This PR adds one, so the statement is now wrong. The file is not in the diff.
    Remediation: update line 951 and the flowchart to show Claude Code's pre-launch hooks integrity check.
  • [stale-doc] docs/problems/tool-call-risk-assessment.md:125 — Still says hooks "on Claude Code and pi ... stay writable between iterations". The matching sentence in security-threat-model.md was updated to name only pi; this one was missed.
    Remediation: say only pi's hooks stay writable between iterations, and that Claude Code now verifies hooks.json and the hook scripts before each launch.

Low

  • [api-contract-violation] internal/runtime/claude_integrity.go:99 — The guard always hashes security.SandboxHooksSettings, while buildRunCommand passes params.HooksSettingsPath to --settings unchanged. A caller supplying a different non-empty path would pass the check on the default file while Claude loads an unchecked one. The only production caller (internal/cli/run.go) sets exactly the default path or empty, so this is latent.
    Remediation: reject a non-empty HooksSettingsPath other than security.SandboxHooksSettings in Run, or bind the guard to the path passed to --settings.
  • [naming conventions] internal/runtime/claude_integrity.go:38 — claudeHooksTamperedExit = codexHooksMissingExit departs from the <runtime>HooksMissingExit = 97 pattern and ties Claude's constant to the codex runtime.
    Remediation: optionally rename to claudeHooksMissingExit and define it as 97.
  • [code organization] internal/runtime/claude_integrity.go:60 — Calls codex-prefixed helpers (codexAssetSHA256, codexSHACheck, codexHookScriptsGuard); the test uses testCodexHookScripts. The reuse is deliberate, so this is a maintainability nit.
    Remediation: consider moving the generic helpers into a runtime-neutral file with neutral names.

Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-coder

fullsend-ai-coder Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 4:00 PM UTC · Completed 4:07 PM UTC

Commit: d828205 · View workflow run →

Runtime: claude · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $0.54

- clear LD_PRELOAD, LD_LIBRARY_PATH and LD_AUDIT after sourcing .env and
  before the second hooks guard, matching the codex launch; add launch
  tests for the ordering and the effect
- reject a HooksSettingsPath other than the default in ClaudeRuntime.Run so
  --settings cannot load a file the guard did not hash
- rename claudeHooksTamperedExit to claudeHooksMissingExit (97)
- update architecture.md and tool-call-risk-assessment.md, which still said
  Claude Code had no hooks integrity check

Not changed: moving the codex-prefixed helpers into a runtime-neutral file
(deliberate reuse, out of scope for this PR).
Pre-commit hooks could not run (hook repos unreachable from the sandbox);
checked whitespace, secrets, gofmt, go vet and go test ./internal/runtime/.

Addresses #8261

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 Fix agent — iteration 1 (bot-triggered)

Addressed 5 of 6 findings: added the LD_* unset before the second guard with tests, rejected a non-default hooks settings path, renamed the exit constant, and updated the two stale docs. Declined the helper-reorganisation nit as out of scope. go test ./internal/runtime passes. Pre-commit could not run because its hook repositories are unreachable from the sandbox.

Fixed (5):

  1. [integrity-bypass] second hooks guard does not clear LD_PRELOAD/LD_LIBRARY_PATH/LD_AUDIT after .env is sourced (internal/runtime/claude_integrity.go): Added 'unset LD_PRELOAD LD_LIBRARY_PATH LD_AUDIT' after sourcing .env and before the second guard, matching the codex launch. Added a placement assertion and a launch test where .env exports the three variables and claude sees them cleared.
  2. [stale-doc] architecture.md says Claude Code has no pre-launch integrity check (docs/architecture.md): Reworded the paragraph and added a guard node and exit-97 refusal node to the claude branch of the flowchart.
  3. [stale-doc] tool-call-risk-assessment.md says hooks stay writable on Claude Code and pi (docs/problems/tool-call-risk-assessment.md): Now says only pi's hooks stay writable between iterations and that Claude Code verifies hooks.json and the hook scripts before each launch.
  4. [api-contract-violation] guard always hashes the default hooks file while --settings uses params.HooksSettingsPath (internal/runtime/claude.go): ClaudeRuntime.Run now returns an error (exit -1, nothing run) for a non-empty HooksSettingsPath other than security.SandboxHooksSettings. Added a test.
  5. [naming conventions] claudeHooksTamperedExit aliases the codex constant (internal/runtime/claude_integrity.go): Renamed to claudeHooksMissingExit and defined it as 97, updating all uses in claude.go and the tests.

Disagreed (1):

  1. [code organization] Claude guard reuses codex-prefixed helpers; consider a runtime-neutral file: The reviewer calls the reuse deliberate and a maintainability nit. Moving and renaming shared helpers across codex and pi call sites is a refactor outside this PR's purpose and the minimal-diff scope of this fix; better as a follow-up.

Tests: passed

CI inspections (5):

  1. test (CI) (passing, success): Unit tests passed on the reviewed head.
  2. codecov/patch (passing, success): Patch coverage gate passed.
  3. functional-tests (passing, success): Passed.
  4. playback (E2E Tests) (pending, in_progress): Still running when inspected.
  5. commit-lint (passing, success): Passed.

Conflict update: skipped; strategy none; forge MERGEABLE; target main

Decision points
  • Reject non-default HooksSettingsPath rather than binding the guard to the passed path (alternatives: Bind the guard to params.HooksSettingsPath, Reject any non-default path in Run; rationale: Bootstrap records digests for the default hooks file only, so rejecting is the smaller change and fails closed.)

Next steps:

  • /fs-review — request a re-review of the changes
  • /fs-fix <your instruction> — run another fix pass with specific guidance
  • Push commits directly — review re-runs automatically on push
    Updated by fullsend fix agent

@fullsend-ai-review

fullsend-ai-review Bot commented Oct 9, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 4:09 PM UTC · Completed 4:23 PM UTC

Commit: b5175a3 · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $3.84

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-coder

fullsend-ai-coder Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 4:25 PM UTC · Completed 4:30 PM UTC

Commit: b5175a3 · View workflow run →

Runtime: claude · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $0.49

Address review feedback on PR #8261: the Claude launch guard verifies
hooks.json and the hook scripts but does not pin the python3 interpreter,
PATH or PYTHON* environment across the agent-writable .env. List that under
"Not covered" in runtime-implementation.md, drop the "no longer shares this
residue" wording, qualify the matching sentences in the threat-model and
tool-call-risk docs, and add a short implementation note to ADR 0100.

Pinning the interpreter and PATH is deferred: .env legitimately prepends
runner-written PATH entries, so it needs a design of its own.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 Fix agent — iteration 2 (bot-triggered)

Deferred the high-severity interpreter/PATH pinning finding as the review permits: documented it under 'Not covered' and removed the overstated 'no longer shares this residue' wording across the docs. Also added the optional short implementation note to ADR 0100. Docs only; no code changed. The sandbox could not run pre-commit (network blocked), so the staged secret scan and whitespace check were run instead.

Fixed (2):

  1. Claude hook interpreter, PATH and PYTHON environment are not pinned across the agent-writable .env, yet docs say Claude Code no longer shares the residue* (docs/contributing/runtime-implementation.md): Took the reviewer's stated deferral option: listed interpreter/PATH/env pinning under 'Not covered' in the Claude integrity bullet, dropped the 'no longer shares this residue' wording in the pi section, and qualified the matching sentences in security-threat-model.md and tool-call-risk-assessment.md. No launch-command or hooks.json change was made.
  2. ADR 0100 says Claude Code has the same agent-writable hook-script residue as pi (docs/ADRs/0100-codex-sandbox-hooks.md): Added a short October 2026 implementation note: since Claude runtime does not check hooks.json or hook scripts between validation iterations #8259 Claude Code checks hooks.json and the scripts before each launch (exit 97) but does not pin the interpreter or PATH. The accepted ADR body is otherwise unchanged. This ADR edit should be mentioned in the PR description per docs/contributing/adrs.md.

Tests: passed

CI inspections (5):

  1. CI / test (passing, success)
  2. CI / commit-lint (passing, success)
  3. Functional Tests / functional-tests (passing, success)
  4. E2E Tests / playback (passing, success)
  5. E2E Tests / behaviour (flaky, failure): One behaviour subtest about URL-sourced harness config validation failed after a long runtime; it exercises dispatch/config code this PR does not touch, while all Claude, codex and pi hook subtests passed. Recommend rerunning the job; not rerun by the fix agent.

Conflict update: skipped; strategy none; forge MERGEABLE; target main@9282c8b4a1a7f6bf5811f5d17eb17b5166c7262e

Decision points
  • Implement interpreter/PATH pinning now versus defer it and document the gap (alternatives: Pin PATH and use an absolute interpreter with isolated startup in the launch and hooks.json, Defer and document under Not covered; rationale: The .env legitimately prepends runner-written PATH entries (workspace bin, go bin), so restoring a pre-.env PATH would break tool lookup for the agent. Dropping -I's script-directory import behavior would also need hook_io import changes, and an absolute interpreter needs a Bootstrap preflight and a GenerateHooksConfig signature change. That is a design change beyond this PR, and the review allows deferral. Recommend a follow-up issue for it, ideally with launch-plus-hook tests planting a fake python3 and a sitecustomize.py.)

Next steps:

  • /fs-review — request a re-review of the changes
  • /fs-fix <your instruction> — run another fix pass with specific guidance
  • Push commits directly — review re-runs automatically on push
    Updated by fullsend fix agent

@fullsend-ai-review

fullsend-ai-review Bot commented Oct 9, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 4:32 PM UTC · Completed 4:43 PM UTC

Commit: e4a58f7 · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $2.50

@fullsend-ai-review

fullsend-ai-review Bot commented Oct 16, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 2:42 PM UTC · Completed 2:55 PM UTC

Commit: 8e1dfeb · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $3.83

fullsend-ai-review[bot]

This comment was marked as outdated.

@waynesun09

Copy link
Copy Markdown
Member

@ralphbean @ifireball could one of you review and approve? I took this bot PR over: merged main, closed the claude function/PATH-wrapper launch route (test added), and documented what remains (#8494, #8498). Validated with a real local run: two clean iterations, and iteration 2 refused with exit 97 after iteration 1 edited hooks.json. My commits need a second approver under the ruleset. behaviour failed on a BT-org rate limit and is being rerun.

@waynesun09 waynesun09 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving after the takeover. Main is merged in, and the hooks guard now runs on both sides of .env inside the pinned-binary launch; gateway runs check the hook scripts only, since their settings go inline. TestClaudeLaunch_EnvCannotReplaceClaude covers the claude function and PATH-wrapper routes, and a real local run did two clean iterations and refused iteration 2 with exit 97 after hooks.json was edited. What remains is tracked in #8494 and #8498.

@waynesun09
waynesun09 added this pull request to the merge queue Oct 16, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Oct 16, 2026
…ks-integrity

Point TestInstallClaudeHooks_PinsInterpreter's upload stub at $5: #8485 put --no-git-ignore before the sandbox name, so the local path moved from $4 to $5.

Assisted-by: Claude
Signed-off-by: Wayne Sun <gsun@redhat.com>
@fullsend-ai-review

fullsend-ai-review Bot commented Oct 16, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 4:57 PM UTC · Completed 5:08 PM UTC

Commit: d139709 · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $2.43

@fullsend-ai-review fullsend-ai-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See the review comment for full details.

Comment thread internal/runtime/claude_integrity.go Resolved
@fullsend-ai-review fullsend-ai-review Bot added security Security threat model and related concerns component/sandbox OpenShell sandbox environment go Pull requests that update go code labels Oct 16, 2026
@waynesun09
waynesun09 added this pull request to the merge queue Oct 16, 2026
Merged via the queue into main with commit 4382b5c Oct 16, 2026
74 checks passed
@waynesun09
waynesun09 deleted the agent/8259-claude-hooks-integrity branch October 16, 2026 17:36
jctanner added a commit to jctanner-fullsend-ai/fullsend that referenced this pull request Oct 29, 2026
Renumber the ADR 0150 -> 0152 (0146-0151 are claimed by open PRs
fullsend-ai#8679, fullsend-ai#8694, fullsend-ai#8698, fullsend-ai#8702; fullsend-ai#8702 was filed first for 0150).

Per waynesun09's reviews (first round 14:56, second round 18:29):

- restructure the Decision as rules 1-10 with the conformance table
  separated out (moved to docs/contributing/runtime-implementation.md
  so it can track the implementation as the code changes, linked from
  Consequences)
- add the Options section back per the ADR template (fail-open with
  warning, per-runtime resolvers, version-floor acceptance,
  hash-verification as primary mechanism — each rejected)
- add rules 9 (executables, not just directories) and 10 (scope:
  settings sources fullsend-ai#8637, hooks.json integrity fullsend-ai#8261, plugin trust
  ADR 0094)
- gaps against the rules are tracked in issues, not the ADR: fullsend-ai#8763
  (per-file trust for every executable a hook runs) and fullsend-ai#8764 (paths
  that let a tool call through without a hook verdict), both filed by
  the reviewer; rule 8's root-launch exception stays as a one-sentence
  stated limit
- fix the pre-fullsend-ai#8605 Codex wording: the PATH was restored for itself
  and its hook adapter's children
- fix the architecture.md sentence to state the decision for all
  runtimes, not Codex only
- factual corrections from the first round: the shared resolver is
  hookPreflightInterpreter; the boundary value is FULLSEND_TRUSTED_PATH;
  the pre-fullsend-ai#8605 gap was image-PATH agent-writable dirs; pi included
  (same treatment in fullsend-ai#8589, pinned python3 not Node)

Per the dual-model review round (GLM 5.3 + DeepSeek V4.1 Flash):
- breaking change names the runtimes (pi has no version preflight)
- forge scope before Consequences, full forge list

Signed-off-by: James Tanner <jtanner@redhat.com>
jctanner added a commit to jctanner-fullsend-ai/fullsend that referenced this pull request Oct 29, 2026
Renumber the ADR 0150 -> 0152 (0146-0151 are claimed by open PRs
fullsend-ai#8679, fullsend-ai#8694, fullsend-ai#8698, fullsend-ai#8702; fullsend-ai#8702 was filed first for 0150).

Per waynesun09's reviews (first round 14:56, second round 18:29):

- restructure the Decision as rules 1-10 with the conformance table
  separated out (moved to docs/contributing/runtime-implementation.md
  so it can track the implementation as the code changes, linked from
  Consequences)
- add the Options section back per the ADR template
- add rules 9 (executables, not just directories) and 10 (scope)
- gaps tracked in issues only: fullsend-ai#8763 and fullsend-ai#8764 linked bare, no
  implementation-state prose in the ADR
- fold the root-launch case into rule 8 as an explicit scope
  precondition (accurate wording: the PATH still drops relative,
  empty, and missing entries as root; it cannot exclude
  agent-writable directories) instead of a contradictory
  Consequences 'limit'
- cite the pre-fullsend-ai#8605 Codex behavior at the correct SHA
  (bbe0ab2^1 = 191d723), not unqualified line numbers
- state the OpenCode exclusion in rule 6 and the conformance table
  (no ADR 0090 hook wiring until unbound-force#515)
- fix the fullsend-ai#8589 chronology (merged earlier the same day as fullsend-ai#8605,
  not an extension after it)
- fix the Options wording on hash verification (detects a
  substitution only at the next check; the ADR 0094 preflight
  detects at check time, not 'after the fact')
- reference PR fullsend-ai#8261 explicitly as a PR
- fix the architecture.md sentence to state the decision for all
  runtimes, not Codex only
- factual corrections from the first round: the shared resolver is
  hookPreflightInterpreter; the boundary value is FULLSEND_TRUSTED_PATH;
  the pre-fullsend-ai#8605 gap was image-PATH agent-writable dirs; pi included
  (same treatment in fullsend-ai#8589, pinned python3 not Node)
- update the conformance table Codex row to the post-fullsend-ai#8633 mechanism
  (envDataTrustedPin within codexBinaryPin) with the bbe0ab2 state
  noted

Per the dual-model review round (GLM 5.3 + DeepSeek V4.1 Flash):
- breaking change names the runtimes (pi has no version preflight)
- forge scope before Consequences, full forge list

Signed-off-by: James Tanner <jtanner@redhat.com>

This branch was successfully deployed

1 active and 1 inactive deployments
site-preview — d1397098 Deployed Oct 16, 2026 by github-actions[bot]
dev — d1397098 Deployed Oct 16, 2026 by waynesun09 via behaviour #16868
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

component/sandbox OpenShell sandbox environment fullsend-no-fix Skip bot-triggered fix agent runs go Pull requests that update go code ready-for-review Triggers review agent dispatch risk/moderate PR risk: moderate security Security threat model and related concerns

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Claude runtime does not check hooks.json or hook scripts between validation iterations

1 participant