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

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:

   [agents]
   max_threads = 10
   max_depth = 2

2. Fully restart Codex Desktop.

3. Create a new Desktop task that can use subagents.

4. Ask the root agent how many concurrency slots are available, or inspect the model-visible session instructions.

5. Observe a total of four slots (root + three children), rather than the configured agents.max_threads value.

6. Increase agents.max_threads, restart Desktop, and create another task.

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

  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:

  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

• Feature Request: Support for higher or configurable sub-agent spawning limits #16183 requested higher/configurable subagent limits.
• Main agent needs subagent capacity/status preflight before spawn_agent attempts #23479 requests runtime capacity/status preflight.
• MultiAgentV2 spawn_agent defaults to full-history fork, rejecting agent_type/model overrides #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.