MultiAgentV2 spawn_agent defaults to full-history fork, rejecting agent_type/model overrides

[iharc-jordan]

What variant of Codex are you using?

Codex Desktop with MultiAgentV2 enabled.

What happened?

With MultiAgentV2 enabled, spawn_agent defaults to a full-history fork when fork_turns is omitted. Full-history forks reject agent_type, model, and reasoning_effort overrides.

That makes the natural/default call shape for a specialized subagent fail:

{
  "agent_type": "domain_expert",
  "task_name": "domain_expert_default_fork_probe",
  "message": "Probe task: reply with exactly one sentence saying whether you started successfully."
}

Observed error:

Full-history forked agents inherit the parent agent type, model, and reasoning effort; omit agent_type, model, and reasoning_effort, or spawn without a full-history fork.

The same failure occurs for built-in roles such as explorer and worker when fork_turns is omitted. This is not specific to domain_expert; it is the MultiAgentV2 default fork behavior interacting with role/model/reasoning overrides.

Expected behavior

One of these should be true:

1. spawn_agent(agent_type=...) should default to a fork mode compatible with role/model/reasoning overrides.
2. The tool schema/docs should explicitly state that agent_type, model, or reasoning_effort require fork_turns: "none" or another non-full-history mode.
3. MultiAgentV2 should support full-history context plus a different child role/model/reasoning configuration, since "same context, specialized child" is a common multi-agent workflow.

Actual behavior

fork_turns is optional, but omission means "all", which maps to SpawnAgentForkMode::FullHistory. In that mode, MultiAgentV2 rejects overrides.

Current implementation appears to do this in codex-rs/core/src/tools/handlers/multi_agents_v2/spawn.rs:

• fork_turns.unwrap_or("all")
• "all" maps to SpawnAgentForkMode::FullHistory
• full-history mode calls reject_full_fork_spawn_overrides(role_name, model, reasoning_effort)

So a model following the visible spawn_agent schema can easily produce a rejected tool call by combining the default fork mode with an explicit agent_type.

Reproduction steps

1. Start a Codex Desktop/CLI session with MultiAgentV2 enabled.
2. Ask Codex to spawn a specialized subagent, or directly call:

{
  "agent_type": "explorer",
  "task_name": "explorer_default_fork_probe",
  "message": "Reply with exactly: STARTED"
}

3. Observe the full-history fork rejection.
4. Retry with:

{
  "agent_type": "explorer",
  "task_name": "explorer_no_fork_probe",
  "message": "Reply with exactly: STARTED",
  "fork_turns": "none"
}

5. Observe that the specialized role can spawn.

Why this seems like a bug / DX issue

The official subagents docs describe specialized/custom agents with different model configurations and instructions. The tool schema also exposes agent_type, model, and reasoning_effort as ordinary spawn_agent arguments.

But with MultiAgentV2 enabled, the default fork_turns value makes those ordinary-looking arguments fail unless the caller knows to add fork_turns: "none".

This creates a sharp edge for users and orchestrating agents:

• specialized subagent requests fail by default
• the workaround is not discoverable until after a rejected tool call
• users expecting "spawn a domain expert / explorer / worker" get a spawn failure instead of a specialized child

Suggested fix

Best option:

• If agent_type, model, or reasoning_effort is present and fork_turns is omitted, default to a compatible fork mode instead of full-history.

Alternative:

• Keep the current behavior, but update the tool schema/docs to explicitly state that role/model/reasoning overrides require fork_turns: "none" or another non-full-history mode.

Longer-term option:

• Support full-history context with a different child role/model/reasoning configuration, since "same context, specialized child" is a common MultiAgentV2 workflow.

Related issue

Possibly related, but broader and Windows/named-agent focused:

• Subagent-specific TOML config no longer works on Codex Windows; named agents spawn with default config #19399

[github-actions]

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

• Subagent-specific TOML config no longer works on Codex Windows; named agents spawn with default config #19399

Powered by Codex Action

[iharc-jordan]

I can create a fix for this if it is acceptable. I have never contributed before but I'm happy to if the team is busy elsewhere.

[joeykrug]

+1 reproducing on Codex CLI v0.125.0 (Linux) with multi_agent_v2 = true.

We have both reviewer and explorer roles configured in ~/.codex/agents/ with role-specific model = "gpt-5.5" / model_reasoning_effort overrides — the exact "specialized child with same context" workflow described in this issue. Every multi-agent spawn the lead thread attempts in our coding-agent automation gets rejected with the verbatim error string at the codex_core::tools::router ERROR level, and the lead thread then falls back to serial single-thread execution.

Two examples from our logs in the past hour:

2026-04-29T03:30:35.696218Z ERROR codex_core::tools::router: error=Full-history forked agents inherit the parent agent type, model, and reasoning effort; omit agent_type, model, and reasoning_effort, or spawn without a full-history fork.
2026-04-29T03:30:35.720510Z ERROR codex_core::tools::router: error=Full-history forked agents inherit the parent agent type, model, and reasoning effort; ...
2026-04-29T03:30:35.876210Z ERROR codex_core::tools::router: ...
2026-04-29T04:13:56.729037Z ERROR codex_core::tools::router: error=Full-history forked agents inherit the parent agent type, model, and reasoning effort; ...

The lead thread's own narration of the failure:

The first spawn attempt hit a tooling constraint about full-history forks with explicit roles. I'm retrying with fresh role-specific threads and the relevant instructions embedded.

So in practice, multi-agent-v2 with role overrides currently degrades to single-thread + role-discipline-via-prompt for us. Functional, but parallelism is lost.

Strong agreement with the suggested fix:

If agent_type, model, or reasoning_effort is present and fork_turns is omitted, default to a compatible fork mode instead of full-history.

That seems like the least-surprise option — caller intent ("specialized child") wins over the silent default ("inherit everything"). The longer-term option ("same context + different role/model/reasoning") would be ideal because that's the actual workflow we want, but I assume that requires deeper API/runtime changes.

Happy to test a fix on a release candidate if useful.

[jakvbs]

I can reproduce a related failure on codex-cli 0.128.0.

A/B result:

• --disable multi_agent_v2: subagent completes, writes a dynamic nonce file, and wait returns the child final response.
• --enable multi_agent_v2 with default spawn behavior: wait times out, nonce file is missing, child final response is missing.
• --enable multi_agent_v2 with explicit fork_turns: "none": subagent completes and returns the expected dynamic nonce.

This suggests the V2 default full-history fork can make a child inherit parent orchestration context strongly enough that even a simple isolated worker task may not execute. Explicit fork_turns: "none" is a working workaround for task-worker style subagents.

Observed local smoke summaries:

V1 disabled:
WAIT_STATUS=completed
FILE_NONCE=<value>
CHILD_FINAL=CHILD_NONCE <same value>

V2 default:
WAIT_STATUS=timeout
FILE_NONCE=missing
CHILD_FINAL=missing

V2 fork_turns none:
WAIT_STATUS=completed
FILE_NONCE=<value>
CHILD_FINAL=CHILD_NONCE <same value>

[fightZy]

• 1 There is a possibility of a call error and a second attempt is needed

[netbrah]

We hit this on our side too. The combination is especially painful when an agent prompt also instructs "always pass agent_type to bind subagents to a role config" — every first dispatch is guaranteed to fail. Captured in a rollout: the parent burns a turn on the rejection, reasons about it, then re-dispatches with fork_turns: "none".

A small fix that resolves it cleanly: when fork_turns is omitted and the caller supplied any of agent_type / model / reasoning_effort, default the fork mode to "none" instead of "all". An explicit fork_turns="all" paired with overrides should still be rejected — that's a genuine contradiction, and the rejection now means what it says. The rejection error is also worth rewriting to tell the caller the actual fix (set fork_turns="none", or omit it entirely) rather than "omit your role."

Diff is small — roughly:

• SpawnAgentArgs::fork_mode() in multi_agents_v2/spawn.rs takes a has_child_overrides flag and picks the default accordingly.
• Tool schema description for fork_turns documents the override-aware default.
• Two tests: one locks in the new ergonomic (overrides + implicit fork_turns ⇒ no-fork spawn with role applied), the other locks in the still-strict behavior for explicit fork_turns="all" + overrides.

Happy to send a PR if it would help — let me know if there's a preferred shape (behind a feature flag vs. unconditional, exact error wording, etc.).