fix(review): exclude project settings from branch-review worktrees

[seungpyoson]

Fixes #117 for branch reviews. The protection has limits, listed under "What this does not cover".

Problem

For a branch review, meaning --base, --scope branch, or auto scope on a clean working tree, review and adversarial review run claude -p inside a new worktree the plugin creates (scripts/lib/review-worktree.mjs). The worktree checks out the commit under review, and a print-mode child doesn't ask for trust. Nothing limited setting sources, so the checkout's project settings loaded. Tested at 19e5651 with the real CLI:

• .claude/settings.json hooks run at startup;
• its env reaches the processes the child starts. The review's git MCP server is node, so env: {"NODE_OPTIONS": "--require ./.claude/probe.cjs"} runs a file committed in the branch;
• CLAUDE.md and .claude/rules reach the model. So does AGENTS.md, which Claude Code 2.1.277 and later reads when a project has no CLAUDE.md.

Why --setting-sources, not disableAllHooks

#117 first suggested disableAllHooks. That stops hooks but not the other two paths: with hooks disabled, the NODE_OPTIONS file above still runs, and CLAUDE.md still loads. --setting-sources user stops project and local settings from loading at all, which covers all three.

An external review also found that on Claude Code 2.0.64 and 2.1.150, a checkout's permissions.allow: ["Bash"] let a worktree review run Bash under dontAsk, and that --setting-sources user blocked it on every version tested. Those versions are now refused (see below).

Change

• createReviewIsolation returns settingSources: "user" for a review worktree. Review and adversarial review pass it through.

• buildArgs gains an optional settingSources, emitted as --setting-sources <value>.

• In the worktree, user settings, managed settings and the --settings file still load; project and local settings do not.

• Claude Code 2.1.281 or later is required whenever settingSources is set. Older versions accept the flag without applying it everywhere. The Claude Code changelog records three fixes:

  • 2.1.211: nested .claude/rules files no longer load (before it, one loaded after Claude read a file in its directory);
  • 2.1.246: the command sandbox's filesystem configuration respects the flag;
  • 2.1.281: spawned sessions (teammates, /bg, claude agents sessions) inherit it.

  2.1.281 is the latest release that fixed the flag letting excluded settings through. runClaudeTurn reads claude --version and throws before starting Claude if the output doesn't start with a plain major.minor.patch at or above 2.1.281. A prerelease suffix counts as unreadable. An older release gets an error telling the user to update; output that can't be read as a release version gets an error saying so. The README prerequisites name the version.

• 2.1.281 is above npm's stable tag (2.1.274 today; latest is 2.1.283). Users on the stable channel can't run branch reviews until stable reaches 2.1.281, and "update Claude Code" won't help them unless they switch channels. If that's too strict, 2.1.246 is the alternative. The only gap between the two is spawned sessions. A review child can reach those only if the tools that start them are allowed. The review allowlist doesn't include them, so user or managed settings would have to allow them. This comes from reading the allowlist; spawned sessions weren't tested.

• Working-tree reviews, the stop-review gate, task and rescue are unchanged. They don't pass the flag, so the version check doesn't apply to them.

What this does not cover (for maintainers to decide)

• Working-tree reviews load the user's repository's project settings without a trust prompt, as they do today. Auto scope picks a working-tree review whenever the tree has any change, including an untracked file. With an untrusted branch checked out and any local change, a review runs that branch's hooks and env (including code through NODE_OPTIONS) and loads its CLAUDE.md.
• The stop-review gate has the same exposure and doesn't need a local change. Once enabled, it runs whenever a turn changes the working-tree fingerprint, and the fingerprint includes the index (git write-tree, scripts/lib/git.mjs:115; hooks/stop-review-gate-hook.mjs:309-313). A turn that only checks out a branch with different content changes the index, so asking Codex to check out a PR is enough to run that PR's settings, unattended.
• Passing settingSources: "user" to the gate or to working-tree reviews would close this, but those runs would then lose the project's own CLAUDE.md and deny rules. Whether to do that is a product decision, so this PR leaves it alone. The gate is the stronger candidate because it runs without being asked.
• Rescue loads workspace project settings, as today: hooks, env, .mcp.json servers (it doesn't pass --strict-mcp-config), and CLAUDE.md. --write rescue behaves the same.

Behaviour change

• Branch reviews no longer load the checkout's CLAUDE.md, AGENTS.md, .claude/rules or project settings. Repositories used with Codex often have only AGENTS.md; their branch reviews lose those project instructions. That includes all project deny rules: rules on paths outside the repository and on tools such as WebFetch stop applying as well, and a worktree does not confine reads.
• Deny rules, allow rules and instructions in user settings still apply. An external review confirmed that a user permissions.allow rule for Bash still lets a review run Bash under dontAsk. Users who rely on project deny rules for reviews should move them to user settings.
• Branch reviews fail on Claude Code older than 2.1.281, with a message to update.
• This needs a CHANGELOG line at release.

Verification

The full companion (node scripts/claude-companion.mjs review --cwd <repo> ...) was run with real Claude CLIs against a local mock API, with a fresh CLAUDE_CONFIG_DIR and CODEX_HOME. The test repo commits .claude/settings.json, .claude/probe.cjs and CLAUDE.md on main, then a code change on feature, so none of them is in the reviewed diff. .claude/settings.json contains a SessionStart hook and the NODE_OPTIONS env above.

Ref, CLI, target	Result	Hook ran	NODE_OPTIONS code ran	CLAUDE.md reached model
main, 2.1.283, --base main	completed	yes	yes	yes
main, 2.1.283, --base main, user disableAllHooks	completed	no	yes	yes
this branch, 2.1.283, --base main	completed	no	no	no
this branch, 2.1.283, working tree	completed	yes	yes	yes (unchanged)
this branch, 2.1.281, --base main	completed	no	no	no
this branch, 2.1.211, --base main	refused: update to 2.1.281	no	no	no
this branch, 2.1.210, --base main	refused: update to 2.1.281	no	no	no
this branch, 2.1.210, working tree	completed	yes	yes	yes (unchanged)

The same run with AGENTS.md in place of CLAUDE.md on 2.1.283: AGENTS.md reached the model on main with --base main and in this branch's working-tree review, but not in this branch's --base main review.

Checks at head b937125:

• check:version-sync, check:changelog, lint, typecheck pass.
• test 518/518, test:integration 47/47, test:e2e 23/23.
• On a heavily loaded machine, some integration and e2e runs failed, including this PR's refusal test in an external review: the fake CLI's auth status exceeded the 10-second preflight timeout. Reruns pass.

New tests:

• buildArgs emits the flag only when set.
• assertSettingSourcesSupported:
  • accepts 2.1.281 and later;
  • rejects 2.1.280, 2.1.246, 2.1.210 and older;
  • rejects output that doesn't start with a plain release version, such as 2.1.283-rc.1, 2.1.283.0 or v2.1.283.
• createReviewIsolation returns "user" for a worktree and nothing for the working tree.
• The stop-gate argv carries no flag.
• Review and adversarial review, across auto scope on a clean tree, --scope branch and --base main, pass user. Across auto scope on a dirty tree and --scope working-tree, they pass no flag. Task passes no flag.
• On a fake 2.1.280 CLI, both review commands fail with the update message before starting Claude and leave no worktree behind. A working-tree review still runs on that CLI.

Pre-existing, noticed while testing

• createSandboxSettings returns null for an unknown mode, and buildArgs then omits --settings.
• The read-only preset comment says there is "no shell surface", which doesn't hold for rescue's Bash(git …:*) entries.
• getClaudeAvailability reports any claude --version failure, including its 10-second timeout, as "claude CLI not found in PATH". The version check uses it, so a slow CLI on a loaded machine fails a branch review with that message.
• $cc:setup shows the Claude Code version but doesn't flag one below 2.1.281, so users learn about the requirement from the README or from a refused branch review.
• A CC_PLUGIN_CODEX_CLAUDE_BIN wrapper whose --version output doesn't start with the plain version now blocks branch reviews that worked before. Real claude --version output from 2.1.281 to 2.1.283 passes.

The branch has six commits. The first two tried disableAllHooks, then --setting-sources on every review. A squash merge gives the net diff.