feat: add custom model names and option descriptors

[juliusmarminge]

Custom models can now have a display name and editable option descriptors in Settings → Providers → Models. Legacy slug-only settings remain valid, and clients receive the names and descriptors through provider snapshots.

Only options supported by each provider integration affect turns. Antigravity does not support custom models. Documentation is limited to a short user task section under the current repository guidelines.

Validation: the 15 editor tests cover copied option defaults, boolean and description preservation, and provider-specific copy behavior. Web typecheck and focused lint pass. The broader focused suite passed during preparation. Screenshots are the original captures from the implementation thread.

Before: original slug-only form from the request

After: custom Codex model editor

After: saved custom model row

After: Codex composer options with Ultra as default

Original Claude demo before the fix: context-window options are now excluded from copies

Implementation: Claude Fable 5.1 via Claude Code. PR preparation: GPT-6 via Codex.

---

Note

Medium Risk
Touches model selection, Claude catalog scoping/effort resolution, and persisted provider config shape; incorrect descriptor handling could change what options reach CLIs, but legacy slugs remain valid and changes are covered by focused tests.

Overview
Custom models move from slug-only strings to structured settings (CustomModelSetting: legacy bare slug or full entry with optional name and capabilities). Shared readCustomModelEntries / toCustomModelSetting normalize mixed on-disk data; provider settings schemas and patches accept the union without breaking old configs.

Server and picker behavior now honor stored names and option descriptors: providerModelsFromSettings and Codex custom-model append keep per-entry capabilities (bare slugs still get driver defaults). Claude scopeClaudeModelCatalog strips built-in aliases shadowed by custom slugs, appends capability-bearing custom rows to the catalog, and passes user effort ids through verbatim when there is no manifest effortMap.

Web Settings → Models adds an inline CustomModelEditor (presets per driver, copy-from-built-in, validation) and edit/save on custom rows; display prefers settings over stale probe rows for name/capabilities. Model picker options use custom display names. User docs note Antigravity has no custom models.

^{Reviewed by Cursor Bugbot for commit 04f95ef. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add custom model names and option descriptors to provider settings

• Custom model settings change from bare slug strings to structured entries (slug, name, optional capabilities). Legacy bare slugs remain accepted at all schema boundaries.
• New CustomModelEditor in the web settings UI lets users edit model names, add/remove option descriptors and choices, copy descriptors from built-in models, and validate before saving.
• Shared parsing/serialization in model.ts (readCustomModelEntries, toCustomModelSetting) handles both compact slugs and structured entries, dropping malformed rows silently and serializing back to bare slugs when no custom name or descriptors are present.
• Provider catalogs and snapshots (ClaudeModelCatalog, CodexProvider, providerSnapshot) now use custom entry names and capabilities when present, falling back to driver defaults for bare entries.
• Behavioral Change: all customModels fields in settings and patch schemas now accept structured entries alongside strings. Custom entries without capabilities remain opaque in Claude's catalog. The Claude contextWindow descriptor is excluded from editor presets and built-in-model copy operations but retained in authored definitions. CodexProvider custom entries without explicit capabilities inherit the first built-in model's capabilities (or null when none exist).

^{Macroscope summarized 04f95ef.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.5 KiB	13.6 KiB	+64 B (+0.5%)	15.1 KiB	✅
Codex	Thread snapshot wire	7.0 KiB	7.0 KiB	−3 B (−0.0%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.5 KiB	6.6 KiB	+67 B (+1.0%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	57.0 KiB	57.1 KiB	+88 B (+0.2%)	66.4 KiB	✅
Codex	Live turn messages	8	10	+2 (+25.0%)	21	✅
Claude	Total thread wire	13.5 KiB	13.6 KiB	+19 B (+0.1%)	15.1 KiB	✅
Claude	Thread snapshot wire	7.0 KiB	7.0 KiB	+4 B (+0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.5 KiB	6.5 KiB	+15 B (+0.2%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	57.8 KiB	57.8 KiB	+44 B (+0.1%)	66.4 KiB	✅
Claude	Live turn messages	8	9	+1 (+12.5%)	21	✅

Baseline: 5a2f3eb · PR result: 04f95ef · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 113.8 KiB
• Claude decoded thread snapshot: 114.5 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR adds a new custom-model editing workflow and propagates user-authored names and option descriptors through settings, model selection, provider snapshots, and production turn handling. Its cross-layer runtime impact and substantial new UI/logic exceed the scope of an automatically approvable bounded change.

Notes:

• No code objects were reviewed. Approvability was decided on eligibility alone.

^{You can add or adjust custom eligibility rules. Learn more.}

[juliusmarminge]

Fixed in 8f4447c5b. Claude context-window options are excluded from presets and built-in copies; manually authored descriptors remain editable. Boolean true, false, and unset values survive copying, reopening, and renaming. All nine editor tests, web typecheck, and focused lint pass.

Full audit of 6c7e6646a: fix first. The feature is useful, but two P2 issues remain.

• Claude's context-window preset has no runtime effect. The editor offers 200k and 1M, while custom catalog entries have an empty runtime profile. I ran both selections through the actual catalog helpers: both resolve to the same API model slug and neither resolves a context-token limit, although the selected display value changes. Remove the unsupported preset and exclude runtime-dependent choices when copying, or implement the required mapping. Add a test that checks the outgoing model selection rather than just the menu descriptors.
• Saving an entry discards boolean current values. The draft writer emits only id, label and type for toggles. A direct definitionFromDraft(draftFromDefinition(entry)) round trip strips thinking.currentValue: true even without edits; copying a built-in's enabled toggle loses it too. Preserve boolean current values through the draft and test both true and false.

Reviewed the full diff, settings compatibility, all six provider paths, web/desktop editing, mobile snapshot consumption, and the existing review fixes. The 157 focused tests pass but do not cover these cases. No browser or live-provider sessions were run for this audit.

The documentation update removes the internal feature summary and glossary entry entirely, leaving one three-line user paragraph. No rebase was needed; the PR already contains current main. All five screenshots remain in the PR description.