feat(claude-code-settings): add modelPicker, spinnerTipsOverride tipsFile/label

[GeneralD]

Claude Code v2.1.243 added modelPicker, and v2.1.247 added tipsFile, label and object-form tip entries to spinnerTipsOverride. Neither is described here yet, and the current spinnerTipsOverride shape now rejects valid configurations.

spinnerTipsOverride

• Add tipsFile — a path to a JSON file holding the same tip shapes, so the tip content can live outside settings.json. Constrained to the path forms the CLI accepts (absolute or ~/~/-rooted; relative paths are ignored at runtime).
• Add label — the prefix shown before custom tips (default "Tip", effective limit 40 characters).
• tips entries may now be a plain string or {id, text, cooldownSessions?, priority?}, with the numeric bounds the CLI applies (cooldownSessions 0–1000, priority −10…10).
• Drop required: ["tips"]. The CLI marks tips optional, and a tipsFile-only override is valid — that is the configuration the new setting exists to enable, and the current schema flags it as an error.

modelPicker

An ordered list of {model, label?, description?} rows for the /model picker, plus replaceBuiltInOptions. Added next to modelOverrides.

Where the descriptions and constraints come from

Field descriptions, the 500-character tip limit, the ^[A-Za-z0-9._-]{1,64}$ id pattern, the numeric bounds, and the notes about which settings tiers each key is read from are taken from the CLI's own schema descriptions and runtime normalization rather than paraphrased, so they should stay accurate against the tool.

Two deliberate judgement calls, flagged so they are easy to overrule:

• The tip object uses additionalProperties: false, matching the prevailing style in this file (spinnerVerbs and neighbours), even though the CLI itself is permissive there. Happy to relax it if you prefer to mirror the tool exactly.
• cooldownSessions is typed integer (a session count) while priority is number, since the CLI accepts any finite number there and truncates it (Math.trunc + clamp).

Tests

Positive — src/test/claude-code-settings/:

• spinner-tips-file.json — a tipsFile-only override, which the current schema rejects
• spinner-tips-file-windows.json — a Windows drive-rooted tipsFile path
• spinner-tips-object-entries.json — mixed string and object tips
• model-picker.json — alias, labelled, and provider-format (Bedrock) rows

Negative — src/negative_test/claude-code-settings/:

• invalid-spinner-tip-entry.json — a tip id containing spaces
• invalid-spinner-tip-cooldown.json — cooldownSessions above 1000
• invalid-spinner-tip-priority.json — priority outside −10…10
• invalid-spinner-tip-label.json — a label longer than 40 characters
• invalid-spinner-tips-file-relative.json — a relative tipsFile path
• invalid-model-picker-row.json — a picker row missing the required model

Review

Copilot's review round is addressed in 96f1dc6 and 01cced6: numeric bounds on cooldownSessions/priority, maxLength on label, and a tipsFile path pattern — each verified against the CLI's (2.1.251) runtime normalization before adopting. The tip object stays closed per the judgement call above.

Verification

• node ./cli.js check --schema-name=claude-code-settings.json passes.
• npm run prettier reports no formatting differences repo-wide.
• node ./cli.js check-strict --schema-name=claude-code-settings.json reports the same single pre-existing error on this branch as on master (/$defs/hookCommand/anyOf/0/properties/type missing title), so this change adds no new strict-metaschema failures. It is untouched here since it is unrelated.
• Confirmed the negative tests actually bite: temporarily rewriting one to be valid makes check fail with "Schema validation succeeded ... but was supposed to fail", and restoring it makes check pass again.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[github-actions]

Thanks for the PR!

This section of the codebase is owned by @domdomegg, @bogini, @sarahdeaton, and @ant-kurt - if they write a comment saying "LGTM" then it will be merged.

[miteshashar]

I'm deliberately leaving modelPicker and spinnerTipsOverride out of my v2.1.251 sync (#6273) so this can land on its own. I verified modelPicker independently against settings-reference#modelpicker — the shape matches, including replaceBuiltInOptions defaulting to false and options being required.

Three bounds documented in settings-reference#spinnertipsoverride look like they're missing:

• tips[].priority — docs say "-10 to 10, default 0", so minimum: -10, maximum: 10
• tips[].cooldownSessions — docs say "0 to 1000, default 0"; the PR has minimum: 0 but no maximum: 1000
• label — docs say "up to 40 characters", so maxLength: 40

Two optional extras while you're in there:

• The spinnerTipsOverride description still points at docs/en/settings#available-settings. That anchor no longer resolves to per-key content — the per-setting reference moved to the settings-reference page, so settings-reference#spinnertipsoverride is the live target.
• tipsFile also accepts "an object with a tips array, up to 256 KB", which the current description doesn't mention. Doesn't affect validation since the field is a path string, just completeness.

Nothing blocking from my side — the modelPicker half looks correct as written.

[GeneralD]

Thanks for the careful review. Addressed in 96f1dc6.

• Added priority bounds of -10 through 10 and cooldownSessions bounds of 0 through 1000.
• Added label maxLength: 40.
• Updated the spinnerTipsOverride reference to settings-reference#spinnertipsoverride.
• Completed the tipsFile description: it accepts a JSON tips array or an object with a tips array, with a 256 KB size limit.
• Added isolated negative fixtures for priority, cooldown, and label-length violations.

Validation passed:

• node ./cli.js check --schema-name=claude-code-settings.json
• npm run prettier -- --ignore-path .gitignore src/schemas/json/claude-code-settings.json src/test/claude-code-settings src/negative_test/claude-code-settings
• git diff --check

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.