Repository navigation
docs(global-settings): model switching under the immutable lock - #701
Conversation
The VSCode extension persists every model switch by rewriting the locked user settings file, so the picker fails with EPERM and a typed /model only applies for the session. Document this as a known, intended side effect of protection layer 4 and the fix: pin the default model (opus) in the git-root .claude/settings.local.json — local scope wins over the locked user scope — and switch to heavier models per session with a typed /model. - global-settings/README.md: note right after the lock step + pointer - docs/claude/global-claude-settings.md: new Troubleshooting section with symptom, cause, what still works, verification command, what not to do No VERSION bump: nothing that gets installed to ~/.claude/ changed, so users have nothing to update and should not be warned. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
a5f915c to
8e94946
Compare
|
Do not merge yet, wait for /review-pr to finish |
…ch section Ten findings from the /review-pr pass on this PR (Thorough mode, no blockers): - correct the mechanism: the toast comes from the model picker, not from a typed /model; the typed path attempts a persist and degrades to session-only when the write is refused (verified by contrasting two runs with the file locked and writable) - verification recipe no longer assumes `claude` is on PATH — the extension ships its own binary and does not add one - disclose that the project-local settings file is covered by none of the four protection layers, matching the precedent this doc already sets for sound-config.sh, and say why that is deliberate - warn that a bare "opus" in the local scope overrides "opus[1m]" in the user scope and silently drops the 1M context window - note the linked-git-worktree caveat for --show-toplevel - check-ignore now uses $ROOT so it works from a subdirectory - ANTHROPIC_MODEL takes precedence over `model` rather than being equivalent - align the table per the repo markdown rule; stop describing settings.local.json as MCP-only - cut the duplicated fix instructions from the README callout down to symptom plus a pointer, per the Reference-Don't-Duplicate core rule - narrow the VERSION bump policy to installed artifacts, so docs-only commits no longer contradict the stated rule Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
WilcoLouwerse
left a comment
There was a problem hiding this comment.
Verdict: APPROVE (Thorough) — posted as COMMENT because GitHub blocks self-APPROVE
Reviewed 8e949465 in Thorough mode. No blockers. Ten findings — four 🟡 and six 🟢 — all of them addressed in a follow-up commit on this branch rather than left as open threads, since author and reviewer are the same person here.
Findings
| # | Sev | Where | Finding |
|---|---|---|---|
| 1 | 🟡 | global-claude-settings.md table row + README callout |
Mechanism was wrong: the Failed to set model toast comes from the picker (setModel is its only caller), not from a typed /model. The typed path attempts a persist and degrades to "for this session only" when the write is refused. |
| 2 | 🟡 | verification recipe | Assumed claude is on PATH. The VSCode extension ships its own binary and adds no PATH entry, so the recipe was unrunnable for exactly the audience this section targets. |
| 3 | 🟡 | local-settings fix block | No disclosure that the recommended file is covered by none of the four protection layers (all three software layers and the kernel lock are anchored to ~/.claude/). This document already publishes that disclosure for sound-config.sh; the new file skipped it. |
| 4 | 🟡 | README callout | Fix instructions duplicated across both files in two different shell spellings, against this repo's own core rule in docs/claude/writing-docs.md ("Every piece of information should live in exactly one place"). |
| 5 | 🟡 | README.md VERSION policy |
The policy read "Any commit that modifies a file in global-settings/ MUST also increment VERSION" — unconditional, and this PR modifies global-settings/README.md without bumping. Rather than bump for a docs-only change, the policy now reads installed artifact and states explicitly that README-only commits don't trigger a bump. |
| 6 | 🟢 | env.ANTHROPIC_MODEL note |
Called "equivalent"; it actually takes precedence over model. The "(from …)" source annotation also never fires for the local scope. |
| 7 | 🟢 | table | Pipes and separator row not aligned per the repo's markdown rule. |
| 8 | 🟢 | --show-toplevel |
In a linked git worktree this yields the worktree, while Claude Code's canonical scope is the main repo root — a case this team hits often (this PR was authored in one). |
| 9 | 🟢 | check-ignore |
Repo-root-relative path immediately after "run from anywhere inside the repo"; now uses $ROOT. |
| 10 | 🟢 | file-locations list | Still described settings.local.json as MCP-only. |
One extra correctness fix went in alongside them: a bare "opus" in the local scope overrides "opus[1m]" in the user scope and silently drops the 1M context window. Verified — same repo, same user-scope pin, local "opus" → claude-opus-5; local "opus[1m]" → claude-opus-5[1m]. The section now warns about it.
Claims verified as accurate
Worth recording, since the whole section rests on them. Checked against extension.js, the CLI binary's strings, and live runs: the extension's model persist is hard-wired to the user scope (the localSettings branch of writeUserSettingsAndPush is unreachable from setModel); the picker writes the file before pushing the switch, so a refused write aborts it; model is a first-class settings key and the local scope outranks the user scope; the local scope resolves to the git root, not the cwd; there is no user-scope settings.local.json; modelUsage is the real JSON field, and opus/sonnet/fable resolve to claude-opus-5/claude-sonnet-5/claude-fable-5-1. Eleven of twelve testable claims held exactly, including the ordering claim flagged in advance as most likely to be wrong.
Out of scope — separate PR
All seven Write(...) entries in global-settings/settings.json's deny list appear to be inert: Claude Code prints a warning per session that only Edit(path) rules are matched by file-permission checks. Not a hole — each has an Edit(...) twin and Edit covers Write, so layer 1 holds — but it is dead config emitting seven warning lines every session. That change touches an installed artifact, so it needs its own PR with a VERSION bump.
🤖 Generated with Claude Code
What
Documents a side effect of protection layer 4 (the kernel immutable lock on the user settings file) that the install steps never mentioned, and the supported way around it.
Symptom. In the VSCode extension the model picker fails with
Failed to set model: EPERM: operation not permitted, open '~/.claude/settings.json'and does nothing; a typed/model <name>applies for the session but shows the same toast.Cause. The extension persists every model switch by rewriting the user settings file (
setModel→writeUserSettingsAndPush, hard-wired to the user scope). The lock refuses the write. Working as designed.Fix (documented).
modelis a regular settings key and the local scope wins over the locked user scope, so pin the default model in the git-root.claude/settings.local.json({"model": "opus"}) and switch to heavier models per session with a typed/model fable. Verified empirically withclaude -p … --output-format json | jq '.modelUsage | keys'on Claude Code 2.1.263:sonnet→claude-sonnet-5,opus→claude-opus-5,fable→claude-fable-5-1.Changes
global-settings/README.md— callout right after the lock step in the install block, with the one-liner fix and a pointer to the full section.docs/claude/global-claude-settings.md— new Troubleshooting section (the README already promised one): symptom, cause, what still works / what doesn't under the lock, the local-settings fix with verification command, one-off unlock route, what not to do.No VERSION bump
Deliberate. Nothing that gets installed to
~/.claude/changed —global-settings/README.mdis repo documentation, not an installed artifact, andsettings.json/ the hooks are untouched. Bumping would warn every user to update with nothing to update. Same handling as60628b8b(README +.examplechange, no bump).Notes
hotfix/global-settings-drop-mcpservers(fix(global-settings): drop dead mcpServers block, document MCP scopes (v2.4.1) #700) so this stacks cleanly on 2.4.1. GitHub retargets this PR tomainautomatically when fix(global-settings): drop dead mcpServers block, document MCP scopes (v2.4.1) #700 merges and its branch is deleted; if the branch is kept, retarget manually.settings.local.jsonexists in Claude Code —localSettingsis project scope only, resolved at the git root (not the cwd) in 2.1.2xx. That is why the docs say "git root".🤖 Generated with Claude Code