Docs: define nested subagent completion routing and completed-agent retention

What type of documentation issue is this?

Missing, incorrect, and confusing documentation.

Summary

Codex's public multi-agent documentation, the model-visible tool contract, and
observed runtime behavior do not establish one coherent contract for nested
subagent completion and completed-agent retention.

The model-visible wait_agent description says it waits for a mailbox update
from "any live agent, including queued messages and final-status
notifications." The public multi-agent guide instead describes a subagent's
final response as being delivered to its parent agent. In a nested tree, the
runtime behaved as a one-hop parent mailbox: a grandchild's final was visible
as Completed in the UI and in list_agents, but it did not arrive in the
root agent's wait_agent mailbox.

The same session exposed a second undocumented boundary. A completed role
agent that was still needed for a possible follow-up disappeared when its
parent spawned a sibling. The public documentation describes concurrency in
terms of simultaneously active subagent turns and says there is no fixed limit
on the total number created or tree depth. It does not explain a separate
retained-context limit, when completed agents may be reclaimed, or how an
orchestrator can keep one addressable.

Nested-completion reproduction

1. A root agent spawns a packet host.
2. The packet host spawns a draft host.
3. The draft host sends an explicit message directly to root; root receives
   it, proving that direct task messages can cross that level when addressed
   explicitly.
4. The draft host ends its bounded action with its final response.
5. The UI records Completed <canonical draft-host target>, and
   list_agents reports the target as completed with the expected final
   payload.
6. Repeated wait_agent calls at root time out without delivering that final.
7. A diagnostic follow-up confirms that the draft host emitted its final and
   observed no send error.

The direct child host's own final does reach root. The discrepancy appears
specifically at descendant depth: global diagnostic visibility is not the
same thing as root-mailbox delivery.

Retention/reclamation reproduction

1. Build a tree of root -> packet host -> draft host -> asserter.
2. Let the asserter complete, but retain its canonical target because an
   auditor may reject and require another turn from that exact asserter.
3. Have the draft host spawn the auditor.
4. The completed asserter disappears from list_agents and is no longer
   available for the required follow-up.

This happened at a four-agent topology, but the available diagnostics do not
show whether the cause was a slot limit, a completed-agent reclamation policy,
or another lifecycle rule. That ambiguity is part of the documentation gap.

Practical impact

• An orchestrator can see Completed in the chat trace while waiting forever
  for the completion event its tool contract appears to promise.
• list_agents is useful as a snapshot but has no documented attestation or
  join semantics, so it cannot safely substitute for a mailbox final.
• A parent that ends its turn cannot be assumed to relay later child finals to
  root. In practice, every non-root parent must remain in a supervisor loop,
  wait for each child, and explicitly relay/attest completion upward.
• Polling and diagnostic wakes add turns, latency, and tokens without proving
  that an entire subtree has quiesced.
• Multi-stage workflows that need to revisit a completed specialist can fail
  when that specialist is reclaimed without an explicit retire decision.
• It is unclear whether waiting agents consume concurrency capacity, whether a
  waiting parent protects completed descendants, and when a completed target
  remains addressable by followup_task.

Requested contract/documentation

Please document (and make the tool descriptions agree on) the following:

1. Whether final responses are delivered exactly one hop to the direct parent,
   transitively to root, or to both.
2. Whether wait_agent observes only the caller's mailbox, any descendant's
   final, or global lifecycle events.
3. The distinction among an explicit message, a task-control/status message,
   a final response, a UI Completed entry, and a list_agents completed
   snapshot.
4. The supported join pattern for a subtree. If completion is intentionally
   one-hop, show the canonical parent supervisor/relay loop and explain that a
   parent must stay waiting until all children have finalized.
5. When completed agents are retained, when they can be reclaimed, and whether
   there is a pin/retain/retire mechanism for an agent needed later.
6. The separate accounting, if any, for running, waiting, idle, interrupted,
   and completed-but-retained agents. Clarify how this relates to
   max_concurrent_subagents and the root-inclusive slot count.
7. What lifecycle event an orchestrator can treat as authoritative proof that
   a particular target's latest turn, or an entire subtree, has finished.

At minimum, if one-hop delivery and opportunistic reclamation are intentional,
the model-visible tool descriptions should say so. A first-class
join_subtree/completion-attestation primitive and an explicit retention
control would make deterministic orchestration much safer.

Related issues

• #15723 covers the related problem that an idle parent is not automatically
  resumed when background work completes.
• #17569 asks for missing agent-tool documentation generally.
• #33447 and #40211 cover multi-agent configuration/concurrency documentation.

This report is narrower than a general wake-up request and broader than a
configuration-key correction: it asks for the authoritative routing, join,
and retention contract needed to orchestrate a nested tree.

Documentation location

• https://developers.openai.com/api/docs/guides/responses-multi-agent
• The model-visible descriptions of wait_agent, list_agents,
  followup_task, and spawn_agent in a hosted Codex multi-agent session.

Environment

Observed in a hosted Codex multi-agent session on 2026-08-27. The exact runtime
build identifier was not exposed. No private transcript or repository content
is included in this report.

Start with the Responses multi-agent guide and the model-visible descriptions for wait_agent, list_agents, followup_task, and spawn_agent. Compare their stated behavior with the nested-completion and retention reproductions, then document one consistent routing, join, lifecycle, and retention contract; done means the guide and tool descriptions agree.