Feature request: per-model option to stop advertising synthetic `max`/`ultra` reasoning rungs on models that don't support them

[marcellmanfrin]

What are you trying to accomplish?

I need to route Codex to the Alibaba Token Plan (Qwen) endpoint and have the model picker advertise only the reasoning efforts each Qwen model actually supports. For example, qwen3.8-max should offer low/medium/xhigh and not max/ultra, so the UI reflects the real capability of each model.

What prevents this today?

The catalog row for any reasoning-capable routed model is padded with synthetic top rungs. In src/codex/catalog/effort.ts, applyReasoningLevels appends max and ultra to every reasoning model unless preserveExact is set, and preserveExact only applies to exact-combo models (provider === COMBO_NAMESPACE). As a result, after ocx sync the entry alibaba-token-plan-intl/qwen3.8-max emits supported_reasoning_levels = [low, medium, xhigh, max, ultra] even when modelReasoningEfforts is configured as ["low", "medium", "xhigh"].

What should OpenCodex do?

Add a per-model (or per-provider) config option to suppress the synthetic top rungs so the catalog advertises exactly the provider/registry's supported levels: qwen3.8-max -> [low, medium, xhigh]. Wire clamping via clampToSupportedCodexEffort already keeps requests correct, so this should only affect what the picker shows. Ideally the flag keeps max available for subagent spawn_agent (so that path doesn't hard-fail) while hiding ultra, or gates the mock entirely behind user choice.

Example usage or interface

With a provider configured as:

{
  "providers": {
    "alibaba-token-plan-intl": {
      "adapter": "openai-chat",
      "baseUrl": "https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
      "apiKey": "${BAILIAN_TOKEN_PLAN_API_KEY}",
      "modelReasoningEfforts": { "qwen3.8-max": ["low", "medium", "xhigh"] }
    }
  }
}

After ocx sync, the catalog entry for alibaba-token-plan-intl/qwen3.8-max should advertise supported_reasoning_levels = [low, medium, xhigh] (no synthetic max/ultra).

Alternatives or workarounds

Today the only workarounds are to define the models as exact combos (whch changes their slug to combo/...) or to use noReasoningModels (which removes the effort control entirely). Neither preserves the model identity while trimming only the unsupported top rungs.

Additional context

Suggested implementation: add e.g. preserveExactReasoningRungs?: boolean on the provider, or reuse modelReasoningEfforts as the authoritative advertised ladder. This request is for per-model control over the advertised effort ladder.

[coderabbitai]

🔗 Related PRs

#763 - fix(catalog): prioritize model names in picker labels [merged]
#853 - feat(server): advertise reasoning-effort ladders on the raw /v1/models list [merged]
#1300 - fix(catalog): preserve nested reasoning efforts [open]
#1669 - feat(catalog): add modelPickerOrder to customize the Codex model-picker order [open]
#1716 - feat(models): per-custom-model reasoning effort in the Models dashboard [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[github-actions]

Issue reopened

The report now contains the information required by the automated check. Thanks for updating it.

[Ingwannu]

The report is accurate: current applyReasoningLevels deliberately adds synthetic max and ultra to routed reasoning models unless the row is in the exact-combo path.

One product constraint needs to be resolved before implementation: Codex uses the same supported_reasoning_levels field for both the visible picker and spawn_agent effort validation. There is no separate hidden "spawn-only max" rung in the current catalog schema. Therefore an exact advertised ladder of [low, medium, xhigh] also means a direct spawn_agent(reasoning_effort: "max") can be rejected by the client before OpenCodex gets a chance to clamp it.

A safe option would be an explicit per-model exact-ladder opt-in, with today's synthetic behavior remaining the default. Please confirm that the intended tradeoff is: exact picker truth is preferred even when omitted top-tier sub-agent overrides become invalid for that model. Once confirmed, the config name and tests should make that behavior explicit rather than silently changing existing providers.

[marcellmanfrin]

I agree that an exact advertised ladder should reflect the model’s actual capabilities. My preference would still be to silently clamp unsupported higher efforts when they reach OpenCodex, since clampToSupportedCodexEffort already provides that fallback.

I understand your point, though, that spawn_agent may reject max client-side if max is absent from supported_reasoning_levels, before OpenCodex can perform the clamp.

Is there any current mechanism to keep max accepted for spawn_agent validation while exposing only [low, medium, xhigh] in the picker? If not, then I’m fine with the exact-ladder opt-in and accept that explicit spawn_agent(..., reasoning_effort: "max") overrides would become invalid for that model.

[Ingwannu]

There is no current catalog mechanism that keeps a hidden max rung valid only for spawn_agent while omitting it from the visible picker; both surfaces consume the same supported_reasoning_levels row.

Your confirmation resolves the product tradeoff. The conservative implementation contract is:

• keep today's synthetic max/ultra behavior as the default;
• add an explicit per-model exact-ladder opt-in on the provider;
• for opted-in models, advertise the sanitized configured modelReasoningEfforts[model] ladder without synthetic top rungs;
• retain runtime clamping for requests that do reach OpenCodex, while documenting that the Codex client can reject an omitted explicit sub-agent effort before routing;
• regression-test ordinary models, opted-in exact models, catalog sync, and direct spawn_agent validation implications.

I am removing needs-info and marking this as an implementation-ready help-wanted enhancement. Please keep any PR narrowly scoped to the catalog/config contract and target dev.