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

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:

• #37858 — Ultra multi-agent / Responses multi_agent broken on regular API providers
• #17598 — native subagent orchestration with custom providers
• #31882 / #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.

Start by locating the config reference, subagents and models documentation, then trace the CLI or UI handling for custom model_provider settings and multi_agent_v2. Document which Ultra capabilities require ChatGPT authentication or a first-party provider, and make the product surface clearly label unavailable or degraded multi-agent behavior for API-key providers.