Main agent needs subagent capacity/status preflight before spawn_agent attempts #23479

Summary

The main agent needs a reliable subagent capacity/status preflight before deciding to call spawn_agent.

Today, the agent can decide that delegation would be useful, attempt to spawn a subagent, hit a thread limit or stale subagent state, and then degrade into not using subagents at all. The failure mode is especially painful in long engineering sessions where subagents are needed for read-only exploration and parallel investigation.

Current behavior

From the user's perspective, the parent agent may not have a clear way to know:

• how many subagent slots are currently available
• whether completed subagents are still retained and counting against a limit
• whether any subagents are running, waiting, completed, or failed
• whether the last spawn failed because of thread limit, quota, provider failure, MCP startup, or another cause
• whether closing completed agents would free capacity
• whether retrying, waiting, reusing, or not delegating is the right next action

When spawn_agent fails, the parent agent may treat the failure as a generic inability to delegate and continue locally, instead of recovering or explaining the precise cause.

Expected behavior

Before or as part of spawn_agent, Codex should expose a compact capacity/status preflight to the main agent.

The exact API shape is flexible, but the agent needs information like:

subagent capacity: 0/6 slots available
active: 2 running, 0 waiting
retained completed: 4
recent spawn failure: thread limit reached
recommended recovery: close completed agents, then retry

The important behavior is:

1. The parent agent can see whether spawning is likely to succeed.
2. If spawning cannot succeed, the agent gets an explicit reason.
3. If there is a safe recovery path, the agent can take it or ask the user.
4. The agent should not silently abandon delegation just because one blind spawn attempt failed.

Why this matters

For large codebases, subagents are not just a convenience. They are how the parent keeps context clean while parallel read-only investigation happens in bounded lanes.

When a long-running session reaches subagent capacity, the current experience can turn into:

need research -> try spawn -> spawn failed -> stop using subagents -> parent context bloats

A preflight/status surface would let the parent agent recover intentionally:

need research -> inspect capacity -> close completed / wait / retry / explain -> continue delegation

Related issues

This overlaps with several existing subagent lifecycle issues, but the focus here is narrower: parent-agent preflight before delegation.

Related:

• Completed subagents continue to count against thread limit #22779: completed subagents continue to count against thread limit
• Subagent quota exhaustion is surfaced as “no response” instead of an explicit failure status to the main agent #16891: subagent quota exhaustion is surfaced as generic no response
• CLI: after compaction, Codex may keep saying "Agent spawn failed" even though earlier subagents already finished #16328: after compaction, Codex may keep saying Agent spawn failed
• Feature Request: Ability to check agent status and parent-child wait mechanism #16900: ability to check agent status and parent-child wait mechanism
• Add an Agent View for managing multiple Codex agents from the TUI #22321: Agent View for managing multiple Codex agents from the TUI

Those issues cover specific lifecycle or UI failures. This issue asks for a model-visible/runtime-visible preflight so the parent agent can make a good delegation decision before attempting spawn_agent.