Document / gate Ultra multi-agent features when using API-key custom model_providers #37859

What version of Codex CLI is running?

0.147.0 (CLI + Desktop)

What subscription do you have?

ChatGPT Pro for account features; inference often via custom model_providers with API key (wire_api = "responses", env_key, requires_openai_auth = false).

Which model were you using?

gpt-5.6-sol with model_reasoning_effort = "ultra" on a custom API provider.

What platform is your computer?

macOS (applies generally)

What issue are you seeing?

Codex currently advertises or accepts Ultra-related settings for sessions that use a regular API-key model provider, but several Ultra product capabilities only work on the ChatGPT / first-party backend path.

Concretely:

Users reasonably assume that:

model_provider = "my_api"   # API key provider
model = "gpt-5.6-sol"
model_reasoning_effort = "ultra"
[features]
multi_agent_v2 = true

means they get the same Ultra multi-agent experience as ChatGPT-signed-in Codex. They do not. There is no clear in-product warning, and docs do not draw a hard line between:

1. Ultra as reasoning effort (portable to many providers), vs
2. Ultra as multi-agent product (ChatGPT-backend / first-party only today).

What steps can reproduce the bug?

1. Configure any working custom Responses API provider with API key auth.
2. Set Sol + model_reasoning_effort = "ultra" + enable multi-agent features.
3. Use Desktop/CLI as if Ultra multi-agent were fully available (spawn parallel subagents, multi-agent coordination).
4. Observe failures or silent single-agent answers; switch to ChatGPT-auth default provider and see full behavior.

What is the expected behavior?

Please do one or both of:

1. Document in config reference / subagents / models docs:
   • which Ultra capabilities require ChatGPT authentication / first-party backend
   • which work with arbitrary Responses-compatible API providers
2. Gate or label in UI/CLI when model_provider is a custom API-key provider:
   • show that multi-agent Ultra is unavailable or degraded
   • avoid implying that effort=ultra alone enables full Ultra multi-agent

Without this, power users waste time debugging config when the limit is product architecture.

Additional information

Related:

• Ultra multi-agent / Responses multi_agent does not work with regular API-key model providers #37858 — Ultra multi-agent / Responses multi_agent broken on regular API providers
• Native subagent orchestration does not work correctly with non-OpenAI custom providers #17598 — native subagent orchestration with custom providers
• gpt-5.6-sol/terra/luna hardcode use_responses_lite / multi_agent_version, causing 400s on Azure (and likely any non-ChatGPT-backend) model_provider #31882 / Codex with GPT-5.6-Sol through Azure fails every turn with X-OpenAI-Internal-Codex-Responses-Lite #31870 — ChatGPT-backend-only headers / responses-lite assumptions on Sol/Terra/Luna

This issue is specifically about honest product surface + docs, not only the protocol fix requested in #37858.