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

Open 💬 2 comments Opened Aug 10, 2026 by RaviTharuma

💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

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:

| Capability | ChatGPT-auth / first-party provider | Regular API-key model_providers.* |
|---|---|---|
| Reasoning effort ultra | works | often works (effort enum only) |
| Server-side multi-agent / Responses multi_agent | works | fails (Unsupported parameter: multi_agent or no multi-agent tree) |
| Native Ultra-style parallel subagent product | works | incomplete / broken (see #17598, #37858) |
| Client multi_agent_v2 / spawn_agent | works | partial; known custom-provider bugs |

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:

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

What steps can reproduce the bug?

Configure any working custom Responses API provider with API key auth.
Set Sol + model_reasoning_effort = "ultra" + enable multi-agent features.
Use Desktop/CLI as if Ultra multi-agent were fully available (spawn parallel subagents, multi-agent coordination).
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:

Document in config reference / subagents / models docs:

which Ultra capabilities require ChatGPT authentication / first-party backend
which work with arbitrary Responses-compatible API providers

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

#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.

View original on GitHub ↗

2 Comments

github-actions[bot] contributor · 17 days ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

#37858

Powered by Codex Action

jdcodes1 · 9 days ago

Supporting this documentation/gating request with the client-side mechanism (detailed in #37858 and #37822): inter-agent task payloads are transported as encrypted_content blobs that only the originating ChatGPT-backed session can have decrypted server-side — the client never decrypts them (InterAgentCommunication::to_model_input_item, protocol/src/protocol.rs#L813-L846). With requires_openai_auth = false API-key providers there is no decrypting backend, so sub-agents receive an empty payload and idle. That's why the failure is silent and partial rather than a clean error: the spawn machinery works, only the message content evaporates.

Which means the gate you're asking for has a precise, checkable condition: at spawn time, if the thread's provider isn't the first-party ChatGPT-auth backend (or once a plaintext fallback lands, whenever sender/receiver providers differ), fail the multi-agent tool call with an explicit "multi-agent requires ChatGPT auth on the first-party provider" — and the docs statement falls out of the same condition. Fixing the transport (plaintext path exists: InterAgentCommunication::new) would eventually lift the restriction, but documenting + gating is worth shipping first since it converts hours of silent debugging into one clear message.