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

Activity

1. github-actions

   added

   bugSomething isn't workingSomething isn't working

   appIssues related to the Codex desktop appIssues related to the Codex desktop app

   windows-osIssues related to Codex on Windows systemsIssues related to Codex on Windows systems

   subagentIssues involving subagents or multi-agent featuresIssues involving subagents or multi-agent features

   configIssues involving config.toml, config keys, config merging, or config updatesIssues involving config.toml, config keys, config merging, or config updates

   on Jul 15, 2026
2. github-actions commented on Jul 15, 2026

   

   github-actionsbot

   on Jul 15, 2026 – with GitHub Actions

   Contributor

   More actions

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

   • agents.max_threads=6 but Codex Desktop runtime is capped at 4 #33039

   Powered by Codex Action

   👍React with 👍1Reacted by Ignat Remizov
3. eureka-pd commented on Jul 16, 2026

   

   eureka-pd

   on Jul 16, 2026

   More actions

   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:
   eureka-pd@edca81c

   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.
4. mbrq-cs commented on Jul 16, 2026

   

   mbrq-cs

   on Jul 16, 2026

   More actions

   Same for me. Feedback Id: 019f6446-090a-7880-a2fb-8562d44ca260
5. ignatremizov commented on Jul 16, 2026

   

   ignatremizov

   on Jul 16, 2026

   More actions

   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.
6. lirundong commented on Jul 17, 2026

   

   lirundong

   on Jul 17, 2026

   More actions

   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:

   • codex/codex-rs/core/src/config/mod.rs

     Lines 207 to 208 in 87db9bc

     	pub(crate) const DEFAULT_AGENT_MAX_THREADS: Option<usize> = Some(6);
     	pub(crate) const DEFAULT_MULTI_AGENT_V2_MAX_CONCURRENT_THREADS_PER_SESSION: usize = 4;

   • codex/codex-rs/core/src/config/mod.rs

     Lines 1431 to 1443 in 87db9bc

     	pub(crate) fn effective_agent_max_threads(
     	&self,
     	multi_agent_version: MultiAgentVersion,
     	) -> Option<usize> {
     	match multi_agent_version {
     	MultiAgentVersion::V2 => Some(
     	self.multi_agent_v2
     	.max_concurrent_threads_per_session
     	.saturating_sub(1),
     	),
     	MultiAgentVersion::Disabled | MultiAgentVersion::V1 => {
     	self.agent_max_threads.or(DEFAULT_AGENT_MAX_THREADS)
     	}

   • codex/codex-rs/core/src/session/mod.rs

     Lines 3109 to 3123 in 87db9bc

     	pub(crate) fn resolve_multi_agent_version_for_model(
     	&self,
     	model_info: &ModelInfo,
     	config: &Config,
     	) -> MultiAgentVersion {
     	if let Some(multi_agent_version) = self.multi_agent_version() {
     	return multi_agent_version;
     	}
     	let selected = model_info
     	.multi_agent_version
     	.unwrap_or_else(|| config.multi_agent_version_from_features());
     	self.set_multi_agent_version_if_unset(selected)
     	}

   • codex/codex-rs/core/src/session/mod.rs

     Lines 450 to 465 in 87db9bc

     	pub(crate) fn resolve_multi_agent_version(
     	conversation_history: &InitialHistory,
     	inherited_multi_agent_version: Option<MultiAgentVersion>,
     	) -> Option<MultiAgentVersion> {
     	if inherited_multi_agent_version == Some(MultiAgentVersion::Disabled) {
     	return Some(MultiAgentVersion::Disabled);
     	}
     	conversation_history
     	.get_multi_agent_version()
     	.or(inherited_multi_agent_version)
     	.or(match conversation_history {
     	InitialHistory::New | InitialHistory::Cleared => None,
     	// Threads created before runtime metadata existed keep the legacy V1 tool surface.
     	InitialHistory::Resumed(_) | InitialHistory::Forked(_) => Some(MultiAgentVersion::V1),
     	})

   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.
7. bmethod

   added a commit that references this issue on Jul 19, 2026

   docs(orch): Codex thread cap is MultiAgentV2's configurable default; …

   ...

   1f53770
8. itsdestin

   added a commit that references this issue on Jul 20, 2026

   docs(orchestration): agent-orchestration landscape + native workflow …

   ...

   aab0aa4
9. bmethod

   added a commit that references this issue on Jul 27, 2026

   feat(orch): absorb spawn choreography into a spawn-adapter helper (#900…

   ...

   e0b1c87
10. null0526 commented on Aug 3, 2026

    

    null0526

    on Aug 3, 2026

    More actions

    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.