Make the multi-agent v2 max_threads conflict error actionable

Resolved 💬 2 comments Opened Jul 16, 2026 by xQuester Closed Jul 16, 2026

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 ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗