Skip to content

fix(#8641): pin runner-owned settings in the claude --settings document - #8642

Merged
waynesun09 merged 3 commits into
mainfrom
agent/8641-pin-runner-settings
Oct 21, 2026
Merged

waynesun09 merged 3 commits into
mainfrom
agent/8641-pin-runner-settings

Conversation

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor

Summary

Pins the settings the runner owns in the --settings document fullsend generates for Claude Code, on every run. Before this, a lower-priority settings file ($CLAUDE_CONFIG_DIR/settings.json, or the repository's .claude/settings.json and .claude/settings.local.json) could override the sandbox hook settings through its env block, or switch the hooks off with disableAllHooks. --settings only wins for the keys it sets, so each key is now set explicitly. The launch also clears three Claude Code variables after .env, because they change how Claude Code loads settings and runs hook commands.

Related Issue

Related: #8261, #8637

Changes

  • internal/runtime/claude.go
    • installClaudeHooks now records the hook settings (bootstrapHookEnv) before it renders hooks.json. The read still happens before appendHookEnv.
    • New claudeRunnerSettings adds two things to the document:
      • an env block holding TIRITH_FAIL_ON, TIRITH_REQUIRED, FULLSEND_EGRESS_ALLOWLIST, FULLSEND_CANARY_TOKEN and FULLSEND_TOOL_ALLOWLIST, each with the value Bootstrap recorded, or "" where the runner has none
      • "disableAllHooks": false
    • On gateway runs the hook settings are merged into the claudeGatewaySettings env block rather than replacing it. Both additions are covered by the hooks.json digest and appear in the inline gateway document.
    • New claudeSettingsEnvUnset lists CLAUDE_CODE_SAFE_MODE, CLAUDE_CODE_SIMPLE and CLAUDE_CODE_SHELL_PREFIX.
  • internal/runtime/claude_integrity.go: claudeGuardedEnv unsets those three variables right after claudeLoaderEnvUnset, with hooks on or off. The comment that listed the config-dir and repository settings files as out of scope is updated.
  • Docs:
    • docs/runtimes/claude.md: the hook settings and hook activation come from the runner's settings document, and the lower-priority files cannot change them. The cleared-variables table gains a row for the new unsets.
    • docs/reference/harness-reference.md and docs/guides/dev/cli-internals.md: the list of cleared variables now includes the new names.

Testing

  • make lint passes (stage changes first, then run). pre-commit could not fetch its remote hook repos in the sandbox (TLS failure). I ran the local hooks directly and they pass: gofmt, go vet, lint-broken-symlinks, lint-docs-links, lychee. Whitespace and end-of-file were checked by hand, and secrets were scanned with scan-secrets.
  • Tests added/updated for new or modified logic
    • TestClaudeRunnerSettings: the env block (values and "") and disableAllHooks, on non-gateway and gateway runs, including the merged gateway env, and checks the gateway settings passed in are not modified.
    • TestInstallClaudeHooks_PinsRunnerSettings: the uploaded hooks.json and its recorded digest, for non-gateway, oidc gateway and api-key gateway runs. The inline --settings document must match exactly.
    • TestClaudeLaunch_ClearsSettingsVariablesSetByEnv: runs the real launch under /bin/sh and dash, with hooks on and off, using a .env that exports the three variables. claude must not see them. A control run without the unset confirms the values do reach claude, so the test is not passing because .env was ignored.
    • Updated: TestBuildRunCommand_HooksGuardPlacement and TestInstallClaudeHooks_RecordsDigests.
    • Mutation-checked: each change was dropped in turn (the unset with hooks on, the unset with hooks off, the env pin, the empty-string pins, disableAllHooks, merging the gateway env, and passing the runner settings in installClaudeHooks). Each mutation fails at least one test.
    • go test -race ./internal/runtime/ passes. claudeRunnerSettings and claudeGuardedEnv have 100% coverage.

Note: FULLSEND_CANARY_TOKEN is now also in hooks.json, and on gateway runs in the inline --settings argument. The agent can already read that value in the workspace .env, so nothing new is exposed inside the sandbox.

Not breaking: the pinned values are what the harness configured. A repository that sets these keys in its own .claude/settings.json now gets the runner's values.

Checklist

  • PR title follows Conventional Commits (correct type, ! for breaking changes)
  • Commits are signed off (DCO) — human and human-directed agent sessions only (autonomous agent commit; exempt)
  • I wrote this contribution myself and can explain all changes in it

🤖 Generated with Claude Code


Closes #8641

Post-script verification

  • Branch is not main/master (agent/8641-pin-runner-settings)
  • Secret scan passed (gitleaks — 5bbf11a05f1220107ae0a6196fbc436bec15d292..HEAD)
  • PR body secret scan passed (gitleaks — no-git)

Claude Code merges the --settings document fullsend generates with
$CLAUDE_CONFIG_DIR/settings.json and the repository's
.claude/settings.json and .claude/settings.local.json. --settings wins
only for the keys it sets, so an env block in a lower-priority file was
applied inside Claude Code after the launch re-exported the hook
settings (#8637), and a disableAllHooks there could switch the hooks
off.

installClaudeHooks now records the hook settings (bootstrapHookEnv)
before it renders hooks.json, and claudeRunnerSettings adds to the
document, on every run:

- env: TIRITH_FAIL_ON, TIRITH_REQUIRED, FULLSEND_EGRESS_ALLOWLIST,
  FULLSEND_CANARY_TOKEN and FULLSEND_TOOL_ALLOWLIST with the values
  Bootstrap recorded, or "" (unset) where the runner has none. On
  gateway runs these are merged into the claudeGatewaySettings env
  block instead of replacing it.
- "disableAllHooks": false.

Both land in the hooks.json digest the launch guard checks and in the
inline document on gateway runs.

After .env the launch also unsets CLAUDE_CODE_SAFE_MODE,
CLAUDE_CODE_SIMPLE and CLAUDE_CODE_SHELL_PREFIX
(claudeSettingsEnvUnset), next to claudeLoaderEnvUnset.

Tests cover the env block (values and "") and disableAllHooks on the
non-gateway and both gateway routes, the merged gateway env, the
digest, and the launch under /bin/sh and dash with a .env exporting
the three variables, with a control run showing they reach claude
without the unset. Each test was mutation-checked by dropping the
change it covers.

Note: pre-commit could not fetch remote hook repos in the sandbox
(TLS failure). The local hooks (gofmt, go vet, lint-broken-symlinks,
lint-docs-links, lychee) were run directly and pass; whitespace and
EOF were checked by hand, and secrets were scanned with scan-secrets.

Closes #8641

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@waynesun09

Copy link
Copy Markdown
Member

/fs-fix-stop

@github-actions github-actions Bot added the fullsend-no-fix Skip bot-triggered fix agent runs label Oct 21, 2026
@github-actions

Copy link
Copy Markdown

Fix agent disabled for this PR. Remove the fullsend-no-fix label or use /fs-fix to re-engage.

@fullsend-ai-review

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

Copy link
Copy Markdown

🤖 Review · ⚠️ Cancelled · Started 1:34 AM UTC · Ended 1:48 AM UTC

Commit: 2e437b9 · View workflow run →

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown

Site preview

Preview: https://4f371927-site.fullsend-ai.workers.dev

Commit: 1843ebcb10ea7ae62fc320a3d8452a18d1ba509e

@codecov

codecov Bot commented Oct 21, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 96.29630% with 1 line in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
internal/runtime/claude.go 96.00% 1 Missing ⚠️

📢 Thoughts on this report? Let us know!

A settings file's env block is applied inside Claude Code, after the
launch clears its variables, and reaches the hook commands it starts.
Set every claudeLoaderEnvUnset and claudeSettingsEnvUnset name to ""
in the generated --settings document, and add
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB to the cleared Claude Code variables:
it removes credential-named variables, FULLSEND_CANARY_TOKEN among them,
from the hooks' environment.

Skip the hooks-on /bin/sh case of the launch test where /bin/sh rejects
`unset -f [` (bash 3.2 on macOS), and say in the docs which keys the
settings document pins.

Assisted-by: Claude (fix), Codex (review), Claude (review)
Signed-off-by: Wayne Sun <gsun@redhat.com>
@fullsend-ai-review

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

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 1:49 AM UTC · Completed 2:05 AM UTC

Commit: 0c661fe · View workflow run →

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

@fullsend-ai-review

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

Copy link
Copy Markdown

<!-- fullsend:risk-assessment -->
Risk Assessment: moderate (2/5)

Details

Well-scoped bot change matching issue requirements with zero protected paths, balanced by high recent commit churn in the Claude runtime and unflagged modification of runner settings.

Previous run

<!-- fullsend:risk-assessment -->
Risk Assessment: moderate (2/5)

Details

Well-scoped bot change matching issue requirements with zero protected paths, balanced by high recent commit churn in the Claude runtime and unflagged modification of runner settings.

@fullsend-ai-review

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

Copy link
Copy Markdown

Looks good to me

Previous run

<!-- fullsend:review-findings-v2:eyJ2ZXJzaW9uIjoyLCJhY3Rpb24iOiJyZXF1ZXN0LWNoYW5nZXMiLCJmaW5kaW5ncyI6W3sic2V2ZXJpdHkiOiJtZWRpdW0iLCJjYXRlZ29yeSI6ImluamVjdGlvbi12dWxuIiwiZmlsZSI6ImludGVybmFsL3J1bnRpbWUvY2xhdWRlLmdvIiwiaWQiOiJmXzgzZmNiODJmMmQzZTBhMGUiLCJsaW5lIjoxMDI5LCJhY3Rpb25hYmxlIjp0cnVlfSx7InNldmVyaXR5IjoibG93IiwiY2F0ZWdvcnkiOiJkb2Mtc3R5bGUiLCJmaWxlIjoiZG9jcy9yZWZlcmVuY2UvaGFybmVzcy1yZWZlcmVuY2UubWQiLCJpZCI6ImZfZDgwMTZkYjUyMTM1NTA0NCIsImxpbmUiOjIyNywiYWN0aW9uYWJsZSI6ZmFsc2V9XX0= -->

Review

Findings

Medium

  • [injection-vuln] internal/runtime/claude.go:1029 — claudeRunnerSettings pins every hookEnvManagedKeys name and sets every claudeLoaderEnvUnset and claudeSettingsEnvUnset name to "" in the --settings env block, but not BASH_ENV or ENV. The codebase treats both as execution-controlling elsewhere: envDataDropNames (internal/runtime/env_data.go:82) refuses them from .env because an exported BASH_ENV runs a file in every non-interactive bash the CLI starts. The PR's own comment says a settings file's env block is applied inside Claude Code for the hook commands it starts, so a repository .claude/settings.json can still set BASH_ENV/ENV for hook and Bash-tool child shells, which is the override path this PR is meant to close. Whether a hook can be bypassed this way depends on Claude Code running hooks through bash, which could not be confirmed from static review.
    Remediation: Also pin BASH_ENV and ENV to "" in claudeRunnerSettings (a dedicated list, or by extending claudeSettingsEnvUnset so the launch unsets them too), and extend the pin assertions in claude_gateway_test.go (TestClaudeRunnerSettings, TestInstallClaudeHooks_PinsRunnerSettings) to cover them.

Low

  • [doc-style] docs/reference/harness-reference.md:227 — The edited '.env.d host files' paragraph is still a single line of about 1,800 characters; docs/contributing/documentation.md asks for Markdown prose wrapped at about 80 columns and for rewrapping a paragraph you are already editing.
    Remediation: Rewrap the edited paragraph at about 80 columns.

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.

envDataDropNames refuses both from .env; set them to "" in the generated
--settings document too, so a settings file's env block cannot hand one
to the shells Claude Code starts. Rewrap the edited .env.d paragraph in
the harness reference.

Assisted-by: Claude (fix), Codex (review), Claude (review)
Signed-off-by: Wayne Sun <gsun@redhat.com>
@fullsend-ai-review

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

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 2:10 AM UTC · Completed 2:19 AM UTC

Commit: 1843ebc · View workflow run →

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

@fullsend-ai-review fullsend-ai-review Bot added the ready-for-merge All reviewers approved — ready to merge label Oct 21, 2026

@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.

Validated in the fleet sandbox image with Claude Code 2.1.304: with the settings document rendered from this head, lower-priority settings files and .env no longer change the hook settings or hook activation. Go runtime suite green on Linux.

@waynesun09
waynesun09 added this pull request to the merge queue Oct 21, 2026
Merged via the queue into main with commit 7902d2a Oct 21, 2026
72 checks passed
@waynesun09
waynesun09 deleted the agent/8641-pin-runner-settings branch October 21, 2026 02:54

This branch was successfully deployed

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

Labels

fullsend-no-fix Skip bot-triggered fix agent runs ready-for-merge All reviewers approved — ready to merge ready-for-review Triggers review agent dispatch risk/moderate PR risk: moderate

Projects

None yet

Development

Successfully merging this pull request may close these issues.

runtime/claude: pin runner-owned settings in the generated --settings document on every run

1 participant