[Feature]: Adaptive reasoning effort policy for mixed-capability combos and tool-bearing requests #2731

What are you trying to accomplish?

I need an OpenAI-compatible combo that mixes models with different reasoning-effort capabilities to expose a usable shared effort picker without sending an incompatible effort parameter to targets that cannot accept it.

Concretely, a combo should be able to include:

• a model that accepts reasoning effort both with and without tools;
• a model that accepts reasoning effort on plain text requests, but must omit the effort parameter when the request includes tools;
• a model that intentionally exposes no effort control.

What prevents this today?

Two capability shapes cannot currently be represented together:

1. The Chat Completions bridge can declare per-model supported efforts, but it does not support the request-level compatibility rule "omit effort only when tools are present".
2. Combo catalog derivation intersects every known target ladder. An explicitly empty ladder means "no effort control" and participates in that intersection, so one no-effort target can make the whole combo picker empty even when other targets support the same four rungs.

Keeping the provider-wide ladder empty avoids upstream errors, but it also hides reasoning controls for models that genuinely support them.

What should OpenCodex do?

Add a per-model compatibility flag for OpenAI Chat providers so a model can expose supported efforts while omitting the wire effort field when the request includes tools.

Add an opt-in combo reasoning effort mode with these semantics:

• default strict keeps the current intersection behavior unchanged;
• adaptive derives the public combo ladder from targets that expose non-empty effort control;
• targets with an explicit empty ladder remain supported as no-effort-control targets;
• per-concrete-target request conversion preserves the selected effort only for targets that support it, and omits it for targets that intentionally expose no effort control;
• the new per-model tools-compatibility flag omits the wire effort field whenever tools are present;
• combo target order and failover behavior remain unchanged.

Example usage or interface

Provider configuration:

{
  "providers": {
    "custom-openai-chat": {
      "type": "openai-chat",
      "modelReasoningEfforts": {
        "model-a": ["low", "medium", "high", "xhigh"],
        "model-b": ["low", "medium", "high", "xhigh"]
      },
      "omitReasoningEffortWithToolsModels": ["model-b"]
    }
  }
}

Expected request behavior:

model-a + tools + reasoning effort high
  -> send reasoning_effort=high

model-b + no tools + reasoning effort high
  -> send reasoning_effort=high

model-b + tools + reasoning effort high
  -> omit reasoning_effort and let the upstream model default apply

Combo configuration:

{
  "combos": {
    "mixed": {
      "targets": [
        { "provider": "custom-openai-chat", "model": "model-a" },
        { "provider": "custom-openai-chat", "model": "model-b" },
        { "provider": "no-effort-provider", "model": "model-c" }
      ],
      "defaultEffort": "medium",
      "reasoningEffortMode": "adaptive"
    }
  }
}

Expected catalog behavior:

strict  -> current all-known-target intersection (unchanged)
adaptive -> [low, medium, high, xhigh] from non-empty target ladders

Expected adaptive failover behavior:

model-a target -> selected effort is sent
model-b target without tools -> selected effort is sent
model-b target with tools -> selected effort is omitted
model-c no-effort target -> selected effort is omitted

Alternatives or workarounds

Current workarounds are either too weak or unsafe:

• Set an empty provider-wide ladder. This prevents upstream errors, but hides effort controls for models that support them and makes the combo picker empty.
• Advertise a full ladder for every model. This makes tool-bearing requests to incompatible models fail deterministically instead of adapting.
• Manually route around incompatible models. This loses ordered combo failover.
• Retry the deterministic 400. Retrying cannot repair an invalid tools + effort parameter combination; the request must be constructed differently.

Additional context

This is related to, but narrower than, previous routed-effort propagation issues:

• [Bug] Reasoning effort selected in Codex Desktop is not propagated to routed DeepSeek and GLM models #1100 covered selected efforts not propagating to routed DeepSeek/GLM models.
• Feature request: per-model option to stop advertising synthetic max/ultra reasoning rungs on models that don't support them #1870 covered hiding synthetic unsupported max/ultra rungs.
• [Bug]: Kimi client integration never emits capabilities/support_efforts — routed models (incl. combos) show as 'thinking unsupported' #2688 covered routed models not advertising support_efforts.

This proposal covers a different gap: per-model effort compatibility that depends on whether tools are present, plus an opt-in combo policy for mixed-capability targets.

No secrets or personal data are included. Provider names and model IDs above are synthetic examples. The compatibility evidence should be covered by deterministic local request-construction tests rather than by logging raw upstream traffic.