Make the multi-agent v2 max_threads conflict error actionable
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
- Save the configuration above to config.toml.
- Start Codex.
- 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.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗