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

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

• #33039

Powered by Codex Action

I filed #33512 as a narrower instance of this issue. After comparing the reports, I agree that it is substantially a subset of #33447.

The patch addresses the explicit-config conflict path corresponding to expected-behavior option 3. It changes the validation error to name:

features.multi_agent_v2.max_concurrent_threads_per_session

and explains that the v2 limit applies per session and includes the root thread.

Patch:
https://github.com/xQuester/codex/commit/edca81c45fcdb4063561a92192fd2217119c949f

Validation:
just test -p codex-core multi_agent_v2
68 tests passed.

This does not address the broader Desktop behavior where MultiAgentV2 may be selected without exposing the effective configuration source. I will close #33512 as a duplicate and keep the patch discussion here.

If this narrow fix aligns with the intended solution, I would appreciate an invitation to open the pull request.

Same for me. Feedback Id: 019f6446-090a-7880-a2fb-8562d44ca260

A better workaround is to get multi agent v1 again for gpt-5.6-sol (which does not have this issue) by overriding models.json with a custom catalog (make a copy from source) and change multi_agent_version to null (so it's by config) or v1 (so it's by model catalog json), and disabling deferred tools search.

Confirmed independently on Linux with codex-cli 0.144.5 (exact source tag rust-v0.144.5).

Reproduction:

• ~/.codex/config.toml contained agents.max_threads = 13 and agents.max_depth = 2.
• codex features list reported multi_agent_v2 as under development / false.
• The active tool-backed session nevertheless received the V2 collaboration namespace and the model-visible instruction: There are 4 available concurrency slots, meaning that up to 4 agents can be active at once, including you.
• The runtime enforced root + 3 subagents; attempting a fourth subagent failed with agent thread limit reached.
• Restarting/resuming after changing the legacy setting did not increase capacity.

The 0.144.5 source explains the silent mismatch:

1. DEFAULT_AGENT_MAX_THREADS is 6, but DEFAULT_MULTI_AGENT_V2_MAX_CONCURRENT_THREADS_PER_SESSION is 4.
2. effective_agent_max_threads(MultiAgentVersion::V2) ignores agent_max_threads and instead uses multi_agent_v2.max_concurrent_threads_per_session minus one for the root.
3. A selected model or resumed conversation can select/inherit MultiAgentVersion::V2 independently of features.multi_agent_v2 being enabled. Consequently, the explicit validation conflict is not triggered when the feature flag is false, even though the running session uses V2 and silently ignores agents.max_threads.

Relevant exact-version source:

• https://github.com/openai/codex/blob/87db9bc18ba5bc82c1cb4e4381b44f693ee35623/codex-rs/core/src/config/mod.rs#L207-L208
• https://github.com/openai/codex/blob/87db9bc18ba5bc82c1cb4e4381b44f693ee35623/codex-rs/core/src/config/mod.rs#L1431-L1443
• https://github.com/openai/codex/blob/87db9bc18ba5bc82c1cb4e4381b44f693ee35623/codex-rs/core/src/session/mod.rs#L3109-L3123
• https://github.com/openai/codex/blob/87db9bc18ba5bc82c1cb4e4381b44f693ee35623/codex-rs/core/src/session/mod.rs#L450-L465

The local workaround also succeeds here: remove agents.max_threads, then configure features.multi_agent_v2.enabled = true and features.multi_agent_v2.max_concurrent_threads_per_session = 13. codex features list now reports multi_agent_v2 true.

This confirms the issue is not limited to Windows/Desktop. The actionable fix would ideally warn or migrate whenever the resolved session version is V2 and agents.max_threads is present, even when V2 came from model metadata or resumed history rather than the local feature flag.

I can confirm that the underlying discoverability problem still exists on a newer Desktop/CLI build, although the configuration behavior has changed after the recent agent-setting unification.

Environment

• Codex Desktop: 26.727.6591.0
• Bundled CLI/app-server: codex-cli 0.146.0-alpha.9.2
• Windows, with the execution environment accessed through WSL
• Model: gpt-5.6-sol
• Effective CODEX_HOME: C:\Users\<redacted>\.codex

What happened

New tasks could use only one subagent:

root agent + 1 subagent = 2 active agents

The failure was deterministic. While the first subagent was running, attempting to spawn a second immediately returned:

agent thread limit reached

This was not a server-side account limit or a leaked agent slot. The effective user configuration contained:

[agents]
max_threads = 1

I did not knowingly set this value. I cannot prove which Desktop version, migration, experiment, or prior process wrote it, so I am not claiming a specific origin.

Effective backend was not discoverable from features list

codex features list reported:

multi_agent = true
multi_agent_v2 = false

However, the actual session rollout explicitly recorded:

multi_agent_version: v2

The task also exposed the V2 tool family, including followup_task, interrupt_agent, and list_agents.

This confirms that the model catalog/session can select MultiAgent V2 independently of the user-visible feature flag. The rollout record was the authoritative evidence; features list alone was misleading for diagnosing the active task.

Configuration change

I replaced the legacy alias:

[agents]
max_threads = 1

with the current canonical setting:

[agents]
max_concurrent_threads_per_session = 4

On this build, the setting counts subagents and does not include the root agent, so the resulting capacity is:

1 root + 4 subagents = 5 active agents

The current binary accepted the new key under --strict-config. Deliberately changing the value to a string produced:

expected usize

so the field and its type were verified against the actual bundled runtime.

I also checked for command-line, profile, project-level .codex/config.toml, system configuration, and managed-requirements overrides and did not find another concurrency source.

Real concurrency verification

A fresh Codex process reloaded the configuration and reported:

5 available concurrency slots, including you

It then successfully spawned four subagents before the first wait operation. Each ran a bounded 12-second probe:

A 1785725637.111 → 1785725649.115
B 1785725643.755 → 1785725655.758
C 1785725644.525 → 1785725656.528
D 1785725647.056 → 1785725659.059
OVERLAP_ALL4=true

All four intervals overlapped for approximately 2.06 seconds, confirming genuine four-subagent concurrency rather than serial reuse.

Existing Desktop tasks retained their creation-time two-slot configuration; only a fully restarted Desktop and newly created task used the new value.

Why this remains a product issue

The runtime configuration now works correctly once the relevant key is found. The unresolved problem is that Desktop and CLI diagnostics do not make the following visible:

1. the actual multi-agent version selected for the current task;
2. the effective subagent concurrency limit;
3. whether the value came from a canonical key, legacy alias, model metadata, session history, managed policy, or another configuration layer;
4. whether a legacy persisted value was migrated or preserved;
5. that existing tasks retain their creation-time limit and require a new task after restart.

In this case, a persistent max_threads = 1 silently reduced GPT-5.6 Sol to one subagent, while features list suggested that V2 was disabled. Diagnosing the cause required inspecting rollout JSONL, testing the runtime configuration parser, and running a timed concurrency probe.

Suggested improvement

Please expose the following in codex doctor, debug-config output, or Desktop diagnostics:

Effective multi-agent version: v2
Selection source: model catalog / session / explicit feature
Effective maximum subagents: 1
Configuration source: C:\Users\<redacted>\.codex\config.toml
Source key: agents.max_threads (legacy alias)
Task configuration snapshot: restart and create a new task to apply changes

A warning would also be useful when a legacy alias produces an unusually restrictive value, especially when the active task is using model-selected V2 while features list reports the explicit V2 flag as false.

I can provide a Desktop feedback ID or sanitized rollout excerpts if maintainers need them, but I have not attached the complete rollout because it may contain unrelated conversation and local-path data.