Repository navigation
fix(claude): stop pinning the model in settings.local.json (#40326) - #40403
Conversation
Claude Code reads a settings `model` key as a pin and folds that model's whole family into one alias row. Crew wrote a session's pinned model there, so a session pinned to Opus 4.8 was offered one `opus` row and no Opus 5 or Opus 5.5, Crew cached that short list as what the account is served, and an in-chat /model to the pinned id did nothing. The pin already reaches the session over session/set_config_option (_apply_startup_model), which narrows nothing, so the seed no longer writes it. The one model the seed still writes is the substitute a restricted-model advisory names. A sibling sharing a seed checks the model it runs against the seed's list. Closes #37240 (cherry picked from commit 6936cc9)
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks. The settings seed stops writing the pin as Notes
[DESIGN-REVIEWED] 27328f1 Description read[DESCRIPTION-READ] 69fbc2f1e0e33adad6e4b5dc09f2c2809f1405632fedad1f9be4d04c4825428c That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Every item follows from the measured family-fold defect. The one leftover is that the retry model now reaches the adapter by two routes, the seed file and the envelope. Notes
What this change shipsInventory (8 items) — 7 justifiedIntent: on the Claude Code harness, a pinned Bot or chat sees every model in the picker, and an in-chat
[FIRST-PRINCIPLES-REVIEWED] 27328f1 Description read[DESCRIPTION-READ] 4229993a87e988b944823b074972b7a60d3da83f8f406dd939f81881e52b44b9 That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Problem / Motivation
Goal: On the Claude Code harness, a Bot or chat with a pinned model sees every model the account serves in the picker, Opus 5 and Opus 5.5 included, and an in-chat
/modelswitch sticks.A user on the Claude Code harness reported that the model picker has no Opus 5.5 row, and that the Opus 4.6 rows carry an Opus 5.5 description. Standalone Claude Code on the same host lists Opus 5.5.
Why it matters
Anyone on the Claude Code harness with a Bot or chat pinned to a model loses the newer models of that model's family from the picker, so they cannot pick the newest Opus from Kiro Crew at all. The short list is then cached as what the account is served, so every later picker shows it too.
Not a goal
~/.claude/settings.jsonpins a model, Claude Code itself folds that family the same way. Kiro Crew does not edit that file.What changed (motivation → approach → change)
This is a pick of #40326 onto
release/0.13.0for the next 0.13 build: one commit,git cherry-pick -xof main's6936cc9aed45. Every change below comes from that main commit. One doc line indocs/system-specs/modules/claude-code-provider.mdconflicted; the release side keeps its(issue #22995)reference and the pick drops themodelkey claim, as on main.Claude Code reads a
modelkey in a settings file as a pin and folds that model's whole family into one alias row. Kiro Crew wrote the session's pinned model asmodelinto<work dir>/.claude/settings.local.json. So a session pinned to Opus 4.8 was offered oneopusrow and no Opus 5 or Opus 5.5, Kiro Crew cached that short list as what the account is served, and/model <the pinned id>did nothing because the file kept re-pinning it.The pin already reaches the session a second way:
_apply_startup_modelpushes it oversession/set_config_option, which narrows nothing. So the settings seed (acp/client_claude_seed.py) no longer writes the session's pin. It still writesavailableModelswhen another settings source defines one, and it still writesmodelfor the one case that needs it: the substitute model the backend names in a restricted-model advisory, warm cache or cold.With no pin in the seed,
session/newstarts on the user's own default model. When a policy refuses that default ("Model X is restricted ... Using Y instead"), the one retry names the session's pin if the backend advertised it, and the substitute otherwise (_substitution_retry_model). If the backend refuses the pin too, the start falls back once to the model it offers, as before, since a session on that model beats one that never starts. Both the per-chat client and the shared runtime use this, so one start re-sendssession/newat most twice. The retry's model also rides the envelope's flag tier (options.settings.model), so a seed another session shares, which is not rewritten, cannot hide it.A sibling session that shares another session's seed now checks the model it runs (its substitute, else its pin) against that seed's list, since the seed no longer names a pin. An unpinned sibling can now share a pinned owner's seed: the seed no longer starts it on the owner's model.
The Claude Code provider spec, the field table in
src/kiro_crew/docs/agent-spec-fields.mdand the mirror docstring say the pin is pushed live and never written.Backwards compatibility
Compatible: a pinned session still runs its pin, now set only over
session/set_config_option; an unpinned session, the substitution retry and the permission keys of the seed are unchanged.Removes nothing: the seed's
modelkey was a duplicate channel for a value the live push already delivers; the substitute case keeps it.Tests
test_acp_session_mcp.py::TestLocalSettingsSeed::test_a_pinned_model_never_reaches_the_settings_file(new, both with and without another source'savailableModels): a pinned session's seed has nomodelkey, and the list still names the pin.test_acp_seed_provenance_sibling_sharing.py: an unpinned sibling shares a pinned owner's seed; an unpinned sibling is refused a seed carrying a substitute; a sibling whose pin the seed does not list is still refused.test_acp_client_model_substitution.pyandtest_claude_shared_runtime.py: on a warm cache a refused inherited default keeps a served pin (substitute equal to the pin or not), a pin the backend does not advertise adopts the substitute, a refused pin falls back once to the offered model, a start never re-sends more than twice, and a sibling sharing the seed carries the retry model on the envelope.modelkey now assert its absence; the substitution re-seed tests set the adopted substitute, as both real callers do.-n 4 --dist loadand once serially (-n0), green each time.Proof: PROVEN test/test_acp_client_model_substitution.py::TestSubstitutionFollow::test_a_served_pin_survives_a_refused_inherited_default[other_model], test/test_acp_client_model_substitution.py::TestSubstitutionFollow::test_a_served_pin_survives_a_refused_inherited_default[the_pin], test/test_acp_client_model_substitution.py::TestSubstitutionFollow::test_a_pin_not_served_adopts_the_substitute, test/test_acp_client_model_substitution.py::TestSubstitutionFollow::test_a_refused_pin_falls_back_once_to_the_offered_model, test/test_acp_client_model_substitution.py::TestSubstitutionFollow::test_a_start_never_retries_more_than_twice (head 27328f1)
Manual verification
Drove the Claude Agent SDK that
@agentclientprotocol/claude-agent-acp0.99.1 installs (@anthropic-ai/claude-agent-sdk0.3.312), with a freshHOMEandCLAUDE_CONFIG_DIR,CLAUDE_CODE_USE_BEDROCK=1and no credentials (supportedModels()answers offline),settingSources: ["user", "project", "local"]and a project.claude/settings.local.json:settings.local.jsonsupportedModels()lists{}(the head's seed for a pinned session){"model": "us.anthropic.claude-opus-4-8"}(main's seed)opusrow: "Opus 4.8 · Custom Opus model"{"model": "global.anthropic.claude-opus-4-6-v1[1m]"}opusrow plus the pinned id, both "Opus 4.6 (1M context)"Real-machine verification
Machine: own Linux computer, Amazon Linux 2023, x86_64, 32 vCPU / 247 GB.
Before (main 0a2e92e): a pinned session's seed is
{"model": "<pin>", ...}, and the SDK probe above with that file lists oneopusrow and no Opus 5 or Opus 5.5.After (head 079d382):
python -m pytest -n0 test/test_acp_session_mcp.py -k pinned_model_neverpasses (it failed on main withassert 'model' not in {...}), the seed carries nomodelkey, and the SDK probe with that file lists every Opus row.Cleanup: own computer; the probe's scratch
HOMEand project folder deleted.Related Issues
Part of #37240
Sibling sweep
Swept: git grep -nE '["model"] *=|"model": *(self|model|pin|resolved)' -- src/kiro_crew/acp src/kiro_crew/providers
Sibling: src/kiro_crew/acp/client_claude_session.py -- not affected -- its inline settings beside a project-owned file are parsed from the same rendered payload
Sibling: src/kiro_crew/acp/harness/claude.py -- not affected -- the shared runtime seeds through the same
_write_claude_local_settingsPattern harvest
Not generalizable: the defect is one adapter's reading of one settings key; no other harness seed writes a model pin into a file the harness re-reads.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...); PR Hygiene does not count commits