Docs: clarify Multi-Agent V2 concurrency key, precedence, and root-inclusive counting

[omarpinarecords]

What issue are you seeing?

As of 2026-08-23, the official Codex documentation describes only the global concurrency setting:

[agents]
max_concurrent_threads_per_session = 5

It says this value counts spawned-agent threads and excludes the primary thread:

• https://learn.chatgpt.com/docs/agent-configuration/subagents#global-settings
• https://learn.chatgpt.com/docs/config-file/config-reference

However, the current Codex runtime and configuration schema also accept the explicit Multi-Agent V2 setting:

[features.multi_agent_v2]
max_concurrent_threads_per_session = 6

For this V2-specific setting, the value is the total session concurrency and includes the primary thread. Therefore, these two configurations represent the same desired capacity:

[agents] value 5                  -> 1 primary + 5 subagents = 6 total
[features.multi_agent_v2] value 6 -> 1 primary + 5 subagents = 6 total

The public configuration reference does not list features.multi_agent_v2.max_concurrent_threads_per_session, explain its root-inclusive semantics, or state its precedence relative to the global [agents] setting. Reusing the same field name with different counting semantics creates an easy off-by-one configuration error.

Environment and verification

• Codex Desktop: 26.818.41509
• Installed Codex CLI: 0.149.0
• Bundled Desktop CLI/app-server: 0.149.0-alpha.4.1
• Platform: macOS
• Model-selected multi-agent backend: V2

A sanitized runtime test kept this global setting:

[agents]
max_concurrent_threads_per_session = 16

and added only:

[features.multi_agent_v2]
max_concurrent_threads_per_session = 6

Results:

1. Strict configuration loading succeeded.
2. Effective configuration readback contained both values.
3. A new Desktop task reported exactly six available concurrency slots, including the primary.
4. The effective capacity was therefore one primary plus five subagents.

Before the explicit V2 setting was added, the same current runtime mapped the global value of 16 to 17 total threads. This demonstrates both the current global fallback behavior and the precedence/different semantics of the V2-specific value.

Expected documentation

Please document one of the following clearly:

1. If [agents].max_concurrent_threads_per_session is the recommended public interface, say that Codex translates its subagent-only value into the active V2 total and explain what happens when an explicit V2 value is also present.
2. If the V2-specific setting is supported for direct use, list features.multi_agent_v2.max_concurrent_threads_per_session in the configuration reference and state that it includes the primary thread.
3. Document the precedence rule and provide an example for “one primary plus five subagents.”

Related issue and why this report is narrower

Related: #33447.

That issue primarily reports an older Desktop migration/diagnostics failure in which a legacy setting was silently bypassed. Current 0.149 behavior has changed: the canonical global setting now works as a V2 fallback. This report is limited to the remaining current documentation gap—the accepted explicit V2 key, its root-inclusive semantics, and its precedence are still absent from the official documentation.

Issue routing metadata

• Type: documentation / configuration reference gap
• Scope: public OpenAI Codex Desktop and CLI
• Owning folder/project: not project-owned; Codex product documentation
• Target repo: openai/codex
• Privacy class: public-safe; local paths, account details, and unrelated configuration excluded
• Source basis: official documentation, current configuration schema/source, strict configuration validation, and fresh-task runtime readback
• Duty verbs: document, distinguish, clarify
• Impact: users can configure the wrong concurrency value or cannot discover which accepted setting controls a V2 task
• Priority: normal
• Owner: OpenAI Codex documentation/configuration maintainers
• Next safe action: confirm the intended public interface and update the subagents/configuration-reference pages
• Approval gate: none after submission
• Validation/close criteria: official docs name the supported key or explicitly designate it internal, explain whether the primary is counted, explain precedence/fallback behavior, and include a 1-primary-plus-5-subagents example