Event-driven wakeup when background exec sessions complete #32188

What variant of Codex are you using?

cli

What feature would you like to see?

Description

Long-running commands currently require the model to poll write_stdin, remain inside a long-running tool call, or delegate monitoring to a subagent. Repeated polling creates additional model turns, while a monitoring subagent adds its own context and reasoning costs.

Codex already waits for background processes asynchronously and emits an ExecCommandEnd event when they exit. It would be useful to optionally wake an idle thread when that event occurs.

Proposed behavior

Add an opt-in completion mode to exec_command:

{
  "cmd": "just test",
  "yield_time_ms": 1000,
  "on_exit": "wake"
}

on_exit could accept:

• "none": preserve the current behavior and require explicit polling
• "wake": resume the thread once the background process exits

When "wake" is selected and the command yields a background session, Codex should:

1. Allow the current turn to finish and become idle.
2. Wait for the process without model inference.
3. Enqueue a bounded completion notification when the process exits.
4. Start one continuation turn containing the exit status, duration, and a capped output summary.
5. Avoid a duplicate continuation if completion was already observed through write_stdin.

The tool response should make it clear that automatic notification is registered and polling is unnecessary.

Motivation

This would make long-running tests, builds, deployments, and similar commands event-driven instead of polling-driven. It would reduce unnecessary model turns and remove the need to create “babysitter” subagents solely to monitor process completion.

A recent agent run used many high-effort subagents and thousands of model cycles, accumulating roughly 470 million subagent tokens. Process monitoring was not the only source of that usage, but native completion wakeups would eliminate one avoidable class of polling and monitoring work.

Important cases

• Existing behavior remains unchanged when on_exit is omitted.
• Completion wakes an idle thread exactly once.
• Completion arriving around the turn’s answer boundary is not lost.
• Manually observing completion does not cause a later duplicate wakeup.
• Injected command output is strictly bounded.
• Multiple processes completing close together do not create an unbounded number of continuation turns.
• Cancellation and session shutdown do not produce stale wakeups.

This could reuse the existing background exit watcher and pending-work scheduling mechanisms rather than requiring an active model turn while the process runs.

Additional information

No response