Skip to content

docs(global-settings): model switching under the immutable lock - #701

Merged
WilcoLouwerse merged 2 commits into
mainfrom
docs/global-settings-model-switch-eperm
Sep 8, 2026
Merged

WilcoLouwerse merged 2 commits into
mainfrom
docs/global-settings-model-switch-eperm

Conversation

@WilcoLouwerse

@WilcoLouwerse WilcoLouwerse commented Sep 8, 2026 •

Copy link
Copy Markdown
Contributor

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). model is 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 with claude -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.md is repo documentation, not an installed artifact, and settings.json / the hooks are untouched. Bumping would warn every user to update with nothing to update. Same handling as 60628b8b (README + .example change, no bump).

Notes

🤖 Generated with Claude Code

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>
@WilcoLouwerse WilcoLouwerse changed the title docs(global-settings): model switching under the immutable lock — pin default in local settings (v2.4.2) docs(global-settings): model switching under the immutable lock Sep 8, 2026
@WilcoLouwerse
WilcoLouwerse force-pushed the docs/global-settings-model-switch-eperm branch from a5f915c to 8e94946 Compare September 8, 2026 09:03
@WilcoLouwerse

Copy link
Copy Markdown
Contributor Author

Do not merge yet, wait for /review-pr to finish

Base automatically changed from hotfix/global-settings-drop-mcpservers to main September 8, 2026 09:45
…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 WilcoLouwerse left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

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

@WilcoLouwerse
WilcoLouwerse merged commit 57cde34 into main Sep 8, 2026
41 checks passed
@WilcoLouwerse
WilcoLouwerse deleted the docs/global-settings-model-switch-eperm branch September 8, 2026 13:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant