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

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

• #19399

Powered by Codex Action

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.

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

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>

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

<img width="763" height="521" alt="Image" src="https://github.com/user-attachments/assets/0ef353c1-d7be-431b-881f-ce10c2ffbf54" />

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

I made a hook to require passing fork_turns to fix this for myself.

Additional macOS Codex Desktop reproduction (July 2026):

Before restoring our custom agent setup, we defined 11 named TOML roles with explicit model and model_reasoning_effort values, including lightweight scan roles and high-effort implementation/review roles.

Across a fresh-parent test set (5 parent threads and 4 spawned children), every observed spawned runtime reported the same effective context:

• multi_agent_version = v2
• multi_agent_mode = explicitRequestOnly
• agent_role = null
• model = gpt-5.6-sol
• model_reasoning_effort = high

That was true even where the requested custom role had a different configured model/effort. The child often completed the task, so this can be a silent routing failure rather than an obvious spawn error.

This is consistent with the full-history inheritance/override conflict described here, and makes it impossible to trust custom model routing or cost controls without inspecting child runtime metadata. We also reproduced the behavior after restarting the Desktop app.

Reproduced on Codex Desktop / CLI 0.144.5 on macOS after explicitly registering the custom agents in ~/.codex/config.toml and restarting Codex.

Parent thread: 019f6981-9265-7742-bf90-a3eef6f0ea07
Child thread: 019f6982-472d-7020-84b0-3f144dab1736

The parent called spawn_agent with:

• task_name: levelup_builder
• fork_turns: all

The exposed MultiAgentV2 tool surface did not provide an agent_type field for selecting the registered custom agent. The child metadata recorded:

• agent_path: /root/levelup_builder
• agent_role: null
• model: gpt-5.6-sol
• effort: low

The registered levelup_builder TOML specifies:

• model: gpt-5.3-codex-spark
• model_reasoning_effort: xhigh

The role-specific developer_instructions were also absent from the child. Explicit [agents.levelup_builder] registration and a full Codex restart did not change the result.

This suggests MultiAgentV2 treats task_name as a thread label and creates a full-history child without resolving the registered custom-agent configuration. This overlaps the named custom-agent/tool-surface gap reported in #15250. A durable fix appears to require exposing/resolving agent_type for registered agents, or automatically selecting a non-full-history spawn mode when a custom role is requested.