Make the multi-agent v2 max_threads conflict error actionable

Resolved 💬 2 comments Opened Jul 16, 2026 by eureka-pd Closed Jul 16, 2026
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

What issue are you seeing?

When multi-agent v2 is enabled together with the legacy agents.max_threads setting, Codex rejects the configuration with:

agents.max_threads cannot be set when features.multi_agent_v2 is enabled

The error does not identify the replacement setting or explain that the v2 limit has different semantics. This made diagnosing Terra/Luna child-agent routing and result delivery unnecessarily confusing.

What steps can reproduce the bug?

[features.multi_agent_v2]
enabled = true

[agents]
max_threads = 3

  1. Save the configuration above to config.toml.
  2. Start Codex.
  3. Observe the configuration validation error.

What is the expected behavior?

The error should point users to:

features.multi_agent_v2.max_concurrent_threads_per_session

It should also explain that this limit applies per session and includes the root thread.

Additional information

I prepared and tested a minimal patch in my fork:

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

Branch:
https://github.com/xQuester/codex/tree/codex/improve-multi-agent-v2-migration-error

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

Current main already contains the separate model-override and parent-result-delivery improvements. This patch only makes the legacy thread-limit migration error actionable.

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

View original on GitHub ↗

2 Comments

github-actions[bot] contributor · 1 month ago

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

  • #33447

Powered by Codex Action

xQuester · 1 month ago

Closing as a narrower duplicate of #33447. I moved the patch details and validation results to that issue.