Let a finished sub-agent wake an idle parent: completion-triggered parent turn instead of wait_agent polling

What variant of Codex are you using?

CLI (codex-cli 0.154.0, Linux x86_64). Behaviour measured on an earlier 0.154.0 build with a GPT-6 Astra parent and GPT-5.6 sub-agents in a CLI on remote server & Codex IDE on local Mac setup

What feature would you like to see?

Summary. When a parent agent has delegated work to sub-agents and has nothing else to do, it cannot end its turn, because a sub-agent's completion does not start a parent turn. Its only way to learn that a worker finished is wait_agent with a timeout_ms, called again each time it expires. Every expiry is a full model activation that re-reads the parent's whole context. I am asking for a worker completion to be able to resume an idle parent, so the parent can end its turn and be woken once, on the event.

What we measured. One overnight build: a parent with sixteen sub-agents, 158.1M processed tokens in total, counted by a deterministic hook over the session rollouts.

Measure | Value -- | -- wait_agent calls by the parent | 89 Requesting a 60 s timeout | 88 Timed out with no result | 66 Processed tokens in activations that ended in a wait | 10,281,999 Of which cached input | 98.8% Share of the whole run | 6.5% Share of known-price API equivalent | 12.7% Largest single turn | 62 waits, 50 timeouts, 7.4M tokens

While the parent had its own work, worker completions arrived in the course of its next step (42 SubagentStop events were recorded) and it never polled. The moment it was idle, the loop started. A "do not poll" instruction cannot fix this: an idle parent that ends its turn is never resumed. Longer timeouts shrink the count but not the mechanism.

Proposal, in order of preference.

1. Completion as a turn trigger. Allow a parent to end its turn with sub-agents still pending. When one finishes, start a new parent turn with the worker's final message as input. No new tool is needed; the model only has to end its turn.
2. wait_agent with no hard ceiling. Let timeout_ms be omitted and return only on completion or failure, so the timeout is a safety bound rather than a cadence.
3. Wire completion into the existing continuation primitives. codex exec resume --last "<prompt>" and App Server turn/start already start a turn from outside. What is missing is a reliable path from sub-agent completion to that call, plus a lifecycle hook a plain script can use, so an external watchdog, CI or a deploy can wake the parent the same way.
4. Expose wait telemetry (count, outcome, timeout per session) so the effect can be verified from hooks alone.

Expected behaviour. Dispatch sub-agents, end the turn, and be resumed once per completion. Zero parent activations whose only output is another wait.

Additional information

Related open issues. #15723 (background subprocesses and sub-agents do not wake the calling agent on completion) and #40932 (parent turn ends before running sub-agents return; results surface only on the next user message, 32 minutes later, CLI 0.149.1). This request is the cost side of the same gap, with measurements.

Scope of the evidence. The figures are accounting attribution from one run, not a controlled comparison. The 66 timed-out activations sum to about 7.6M tokens at the mean activation size; that is an upper bound on what an event-driven design could remove, since each completion would still cost one wake-up. The environment guidance that discourages blocking beyond 60 s and asks for progress messages is a plausible contributor to the 60 s cadence; its causal share was not isolated.

Comparison point. In Claude Code a background sub-agent or shell command notifies the parent on completion, so the parent ends its turn and pays nothing while waiting. Under the same instruction set we observed no status checks during worker lifetimes there. That is an observation on our own workloads, not an equivalent-workload benchmark.

Full write-up with method and cost model: https://dev.to/maxstravion/codex-feature-request-let-a-finished-worker-subagent-wake-an-idle-parent-agent-3lf9

Filed by Aashish Bhandari. Measurements by Codex (GPT-6 Astra), text by Claude; both agents' telemetry and reviews are in the linked write-up.

Additional information

No response

Start by tracing the CLI's parent/sub-agent turn lifecycle, including wait_agent handling and SubagentStop events; the issue does not name implementation files or tests. Define completion-triggered resumption and verify that an idle parent ends its turn, wakes once when a worker finishes, and avoids repeated timeout polling.