Codex Desktop: MultiAgentV2 silently bypasses agents.max_threads with no migration warning

What variant of Codex are you using?

• Codex Desktop 26.707.9981.0
• Bundled Codex CLI 0.144.2
• Windows x86_64
• Model: gpt-5.6-sol

What happened?

Codex Desktop started a new task with a model-visible limit of four concurrent agent threads even though the user configuration set a higher agents.max_threads value:

[agents]
max_threads = 10
max_depth = 2

The task reported:

There are 4 available concurrency slots, meaning that up to 4 agents can be active at once, including you.

Changing agents.max_threads from 10 to 111, fully restarting Codex Desktop, and creating another task still produced the same four-slot limit.

Desktop showed no warning or migration guidance explaining that:

• the active Desktop task was using the MultiAgentV2 collaboration surface;
• agents.max_threads does not control MultiAgentV2 concurrency;
• MultiAgentV2 uses features.multi_agent_v2.max_concurrent_threads_per_session;
• the default total is four threads, including the root;
• or which configuration/runtime layer supplied the effective value.

Before adding an explicit v2 configuration, codex features list reported multi_agent_v2 as disabled, while the Desktop task exposed the v2-style collaboration.spawn_agent schema and enforced the four-slot session limit. This made the effective feature and configuration source especially difficult to discover.

Steps to reproduce

1. Add this to ~/.codex/config.toml:

``toml
[agents]
max_threads = 10
max_depth = 2
``

1. Fully restart Codex Desktop.
2. Create a new Desktop task that can use subagents.
3. Ask the root agent how many concurrency slots are available, or inspect the model-visible session instructions.
4. Observe a total of four slots (root + three children), rather than the configured agents.max_threads value.
5. Increase agents.max_threads, restart Desktop, and create another task.
6. Observe that the effective limit remains four and no actionable migration warning is shown.

Expected behavior

If Codex Desktop enables MultiAgentV2 for a task while the user has configured agents.max_threads, it should do at least one of the following:

1. migrate the value to the v2 setting;
2. show an actionable startup warning naming the replacement key;
3. reject the conflicting configuration with a clear error before the task starts; or
4. expose the effective concurrency limit and its source in Desktop diagnostics/settings.

The public documentation should also distinguish among:

• Codex v1 agents.max_threads;
• Desktop/CLI MultiAgentV2 max_concurrent_threads_per_session; and
• Responses API max_concurrent_subagents.

Actual behavior

Desktop silently started with the default four-slot limit. The user-visible configuration contained a higher agents.max_threads value, but there was no indication that another feature/configuration path had superseded it.

Confirmed local workaround

After removing agents.max_threads and using:

[agents]
max_depth = 2

[features.multi_agent_v2]
enabled = true
max_concurrent_threads_per_session = 111

the local Codex configuration loader accepted the configuration:

• codex features list reported multi_agent_v2 ... true;
• codex doctor --summary reported config loaded; and
• codex debug prompt-input probe produced:

``text
There are 111 available concurrency slots, meaning that up to 111 agents can be active at once, including you.
``

This confirms the replacement setting is recognized locally. It does not solve the discoverability or migration problem, and the Desktop runtime still requires a restart/new-task verification.

Current source behavior

The current openai/codex source and generated schema expose the mismatch:

• MultiAgentV2ConfigToml defines max_concurrent_threads_per_session;
• the v2 default is four total session threads;
• the child-thread budget is derived by subtracting the root thread; and
• config resolution contains the explicit error:

``text
agents.max_threads cannot be set when multi_agent_v2 is enabled
``

Relevant source:

• https://github.com/openai/codex/blob/main/codex-rs/core/config.schema.json
• https://github.com/openai/codex/blob/main/codex-rs/core/src/config/mod.rs

Why this is distinct from related issues

• #16183 requested higher/configurable subagent limits.
• #23479 requests runtime capacity/status preflight.
• #20077 covers fork_turns defaulting to full-history fork.

This report is specifically about Desktop enabling/using MultiAgentV2 without exposing the effective configuration source or providing migration guidance from agents.max_threads.

Additional information

OpenAI Support confirmed that the currently available public documentation does not explain the migration relationship between agents.max_threads and max_concurrent_threads_per_session, and recommended filing the issue in this repository.