codex - 💡(How to fix) Fix MultiAgentV2 subagents can acknowledge, time out, or shut down without executing the spawn task

What version of Codex CLI is running?

codex-cli 0.130.0

What subscription do you have?

Plus

Which model were you using?

gpt-5.5

What platform is your computer?

Darwin 25.3.0 arm64 arm

What terminal emulator and version are you using (if applicable)?

Ghostty

Codex doctor report

not available

What issue are you seeing?

Codex TUI / Desktop-style local session with MultiAgentV2 enabled.

Observed locally:

codex-cli 0.130.0

Original ~/.codex/config.toml settings when first reproduced:

model = "gpt-5.5"
model_reasoning_effort = "low"

[features]
multi_agent = true
multi_agent_v2 = true

I later changed the feature flags to only keep MultiAgentV2 enabled, restarted Codex, and reproduced the ack-only initial spawn again:

[features]
multi_agent = false
multi_agent_v2 = true

Related issue

This is partially related to:

https://github.com/openai/codex/issues/20077

That issue covers the first failure mode: with MultiAgentV2 enabled, a full-history fork rejects agent_type, model, and reasoning_effort overrides. This report is about what happens after using the workaround (fork_turns: "none") or after using inherited full-history forks without overrides: subagents may not actually execute the delivered task.

What happened?

I asked Codex to spawn a subagent to verify skill visibility after archiving duplicate skills.

The intended child task was simple and read-only:

Check whether:
1. <HOME>/.codex/skills/02-code/02-yeet/SKILL.md is active or archived.
2. github:yeet exists at <HOME>/.codex/plugins/cache/openai-curated/github/d947469e/skills/yeet/SKILL.md.
3. A list of <PROJECT> project-local design skills are active under .codex/skills/design/ or archived under .codex/skills/.archive/design-duplicates-2026-05-18/.

I saw multiple unexpected outcomes:

1. Full-history fork with explicit model/reasoning failed as described in #20077.
2. Retrying with fork_turns: "none" spawned the agent, and list_agents showed the intended task in last_task_message, but the subagent completed with only an acknowledgement of project instructions instead of performing the check.
3. Retrying again with a shorter imperative task and fork_turns: "none" spawned the agent, but it later showed as shutdown with no final report delivered.
4. Retrying with inherited full-history context and no role/model/reasoning override spawned the agent, but it timed out repeatedly. list_agents showed the agent as running and the intended task in last_task_message.
5. Attempts to close the stuck inherited-context agent were inconsistent: one close attempt reported thread ... not found, while earlier traces showed similar path-resolution errors such as live agent path /root/skill_visibility_check_3/skill_visibility_check_3 not found.
6. After changing the config to multi_agent = false and multi_agent_v2 = true, then restarting Codex, a fresh fork_turns: "none" subagent still completed with only an acknowledgement instead of the requested check. Sending a followup_task to the same agent did work, which suggests the agent is reachable and the task is executable, but the initial spawn message is not reliably handled as the first actionable task.

Expected behavior

When spawn_agent returns success and list_agents shows the intended task in last_task_message, the child agent should do one of the following:

1. Execute the task and return a final report.
2. Return a clear error explaining why it cannot execute the task.
3. Remain reachable and closeable by its canonical path.

It should not silently complete with an unrelated acknowledgement, shut down without a final response, or remain running without useful mailbox output after repeated wait_agent calls.

Actual behavior

Attempt 1: full-history override rejection

Call shape:

{
  "task_name": "skill_visibility_check",
  "agent_type": "default",
  "model": "gpt-5.5",
  "reasoning_effort": "low",
  "fork_turns": "all",
  "message": "You are in <WORKSPACE>. Do not modify files. Check skill visibility..."
}

Observed output:

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.

This matches #20077.

Attempt 2: fork_turns: "none" spawns, but child only acknowledges

Call shape:

{
  "task_name": "skill_visibility_check",
  "agent_type": "default",
  "model": "gpt-5.5",
  "reasoning_effort": "low",
  "fork_turns": "none",
  "message": "You are in <WORKSPACE>. Do not modify files. Check skill visibility after a cleanup..."
}

The parent saw:

Spawned <AGENT_NICKNAME_1> [default] (gpt-5.5 low)

list_agents showed the intended task under last_task_message, but the child completed with:

Understood. I’m in `<WORKSPACE>` and will follow the vault/project instructions: discovery first, small reversible edits, no secrets, no destructive or production-impacting commands without confirmation.

No filesystem check was performed and no requested report was returned.

Attempt 3: shorter fork_turns: "none" prompt shuts down without a report

Call shape:

{
  "task_name": "skill_visibility_check_2",
  "agent_type": "default",
  "model": "gpt-5.5",
  "reasoning_effort": "low",
  "fork_turns": "none",
  "message": "TASK: Inspect skill visibility now. Do not modify files... Do not just acknowledge. Perform the check and report evidence paths."
}

After waiting, list_agents showed:

agent_name: /root/skill_visibility_check_2
agent_status: shutdown
last_task_message: TASK: Inspect skill visibility now...

No final report was delivered to the parent mailbox.

Attempt 4: inherited full-history context avoids override rejection but hangs

Call shape:

{
  "task_name": "skill_visibility_check_3",
  "fork_turns": "all",
  "message": "Do not modify files. Perform the skill visibility check now and return the report, not an acknowledgement..."
}

This spawned successfully with inherited context. list_agents showed:

agent_name: /root/skill_visibility_check_3
agent_status: running
last_task_message: Do not modify files. Perform the skill visibility check now and return the report...

But repeated wait_agent calls timed out and no report arrived.

Attempting to close it later returned:

collab tool failed: thread <THREAD_ID> not found

In an earlier trace, trying to close the same logical agent by relative name produced:

live agent path `/root/skill_visibility_check_3/skill_visibility_check_3` not found

Attempt 5: only multi_agent_v2 = true still ack-only on initial spawn, but follow-up works

After the previous attempts, I changed the config from:

multi_agent = true
multi_agent_v2 = true

to:

multi_agent = false
multi_agent_v2 = true

I restarted Codex and verified there were no old live subagents:

list_agents -> only /root running

Then I spawned a fresh checker:

{
  "task_name": "skill_visibility_after_flag_change",
  "agent_type": "default",
  "model": "gpt-5.5",
  "reasoning_effort": "low",
  "fork_turns": "none",
  "message": "TASK: Do not modify files. Perform this check now and return concise evidence, not an acknowledgement..."
}

The spawn returned successfully:

{"task_name":"/root/skill_visibility_after_flag_change","nickname":"<AGENT_NICKNAME_3>"}

wait_agent completed, but the child again returned only an acknowledgement:

Understood. I’ll follow the <PROJECT> workspace instructions: discovery first, concise updates, small reversible edits, no secrets, and no deploy/migration/production-data actions without confirmation.

Then I sent a follow-up task to the same child:

{
  "target": "/root/skill_visibility_after_flag_change",
  "message": "You did not perform the requested check. Do it now. Use read-only shell commands only and return the evidence paths. Do not acknowledge only."
}

That follow-up succeeded and returned the requested evidence:

Read-only check complete.

`02-yeet` is archived, not active:
- Missing active path: `<HOME>/.codex/skills/02-code/02-yeet/SKILL.md`
- Found archived path: `<HOME>/.codex/skills/.archive/github-publishing/02-yeet/SKILL.md`

`github:yeet` exists:
- `<HOME>/.codex/plugins/cache/openai-curated/github/d947469e/skills/yeet/SKILL.md`

All listed <PROJECT> local design skills are archived under:
- `.codex/skills/.archive/design-duplicates-2026-05-18/`

None of the listed design skills are active under:
- `.codex/skills/design/`

This makes the issue narrower: the subagent can receive and perform a later task, but the initial spawn message can be treated as something to acknowledge rather than execute.

What steps can reproduce the bug?

1. Enable MultiAgentV2. I reproduced with both of these configurations:

[features]
multi_agent = true
multi_agent_v2 = true

and, after restart:

[features]
multi_agent = false
multi_agent_v2 = true

1. Start or restart a Codex session.

2. Spawn a simple read-only checker with explicit model override and no history:

{
  "task_name": "spawn_task_delivery_probe",
  "agent_type": "default",
  "model": "gpt-5.5",
  "reasoning_effort": "low",
  "fork_turns": "none",
  "message": "Do not modify files. Run `pwd` and `ls .`, then return the output summary. Do not just acknowledge."
}

1. Observe whether the child executes the task, only acknowledges instructions, shuts down without a final response, or times out.

2. Repeat with inherited full-history context:

{
  "task_name": "spawn_task_delivery_probe_full_context",
  "fork_turns": "all",
  "message": "Do not modify files. Run `pwd` and `ls .`, then return the output summary. Do not just acknowledge."
}

1. If it hangs, run list_agents, then try close_agent with the canonical path.

2. If the child only acknowledges, send a followup_task with the same instruction. In my repro, follow-up worked, which points to initial spawn-message handling rather than the child being unable to execute the task.

What is the expected behavior?

The parent can observe that the task was accepted and attached as last_task_message, but the child may not execute it or may not deliver a final result. That makes subagents unreliable for verification workflows, especially when the parent needs a small independent check.

The failure is also hard to recover from:

• wait_agent can time out while the agent remains running.
• A child can become shutdown without a delivered final response.
• close_agent can fail with thread/path lookup errors.
• The visible UI may show the task preview, while the child session itself appears to contain only generic/project context or an acknowledgement.
• A follow-up task to the same child can succeed, even when the initial spawn message was not executed.

Additional information

Suggested fix

At minimum:

1. Ensure the spawn message is delivered as the child agent's actionable first task, not only as parent-visible metadata or a mailbox item that can be ignored.
2. If the child exits without responding to the task, return an explicit failure to the parent.
3. Ensure wait_agent surfaces shutdown-without-final as a terminal event, not just a timeout/no-op.
4. Ensure close_agent can close agents by canonical path after a timeout, or returns a clear state explanation.
5. Add a regression test for a simple spawned child that must call a read-only tool and return final output.
6. Add a regression test where the child must execute the initial spawn message, then compare it against a later followup_task to ensure the first message is not treated differently.

Local trace evidence

Local session trace IDs from the repro:

parent thread: <THREAD_ID>
ack-only child: <THREAD_ID>
shutdown/no-report child: <THREAD_ID>
hanging inherited-context child: <THREAD_ID>
post-restart ack-then-followup child: <THREAD_ID>

Relevant local files:

<HOME>/.codex/sessions/2026/05/18/rollout-2026-05-18T14-51-12-<THREAD_ID>.jsonl
<HOME>/.codex/sessions/2026/05/18/rollout-2026-05-18T14-59-14-<THREAD_ID>.jsonl
<HOME>/.codex/sessions/2026/05/18/rollout-2026-05-18T15-03-13-<THREAD_ID>.jsonl
<HOME>/.codex/sessions/2026/05/18/rollout-2026-05-18T15-06-40-<THREAD_ID>.jsonl
<HOME>/.codex/sessions/2026/05/18/rollout-2026-05-18T15-16-08-<THREAD_ID>.jsonl