Repository navigation
Return actionable recovery guidance when /goal continuations hit the spawn_agent thread limit #20908
Description
Running /goal on codex-cli 0.128.0, I hit this failure mode:
The subagent pool is already at its thread limit in this session, so I can't spawn new workers. I'll keep moving locally...
The cap itself may be fine. The rough edge is the recovery path, and /goal makes that rough edge much easier to hit. Goals are meant for longer-running work, and each continuation reuses the same session/subagent pool. If earlier completed agents are still open, a later continuation can hit the cap and simply stop delegating.
Completed subagents still occupy slots until close_agent runs. Once the cap is reached, the model-visible error does not seem to point Codex toward the obvious recovery steps, so it tends to give up on delegation and continue locally even when it may only need to close or reuse existing agents.
The failure would be much easier for the model to recover from if the spawn_agent error said something closer to:
agent thread limit reached. Completed agents still count against the limit until close_agent is called. Use list_agents to inspect existing agents, close completed or unneeded agents, or reuse an existing agent before retrying spawn_agent.
I don't think this needs automatic closing; that could break useful follow-up workflows. It just needs the limit failure to be actionable enough that long-running /goal sessions can manage their agent pool instead of silently degrading to local-only work.
This is related to #19197, but narrower. That issue is about orphaned/stuck subagents and lifecycle controls generally. This one is specifically about the new persisted /goal workflow making thread-limit recovery important during long-running continuation work.
Code paths I checked in rust-v0.128.0:
codex-rs/core/src/agent/registry.rsfor slot reservation/releasecodex-rs/core/src/agent/control.rsforclose_agent/ shutdown behaviorcodex-rs/core/src/tools/handlers/multi_agents_common.rsforcollab_spawn_errorcodex-rs/core/src/goals.rsfor/goalcontinuation behavior
Activity
github-actions commentedon May 3, 2026
Potential duplicates detected. Please review them and close your issue if it is a duplicate.
Powered by Codex Action
[-]Make spawn_agent thread-limit failures actionable for /goal continuations[/-][+]Make agent thread-limit errors tell the model how to recover[/+]aadarwal commentedon May 3, 2026
Reviewed #19197. This is related, but I do not think it is the same issue.
#19197 is the broader lifecycle/leak report: orphaned or stuck subagents, missing controls, and eventual freezes. This issue is specifically about the new persisted
/goalworkflow making the thread-limit recovery path more important./goalis built for long-running continuation work, and those continuations reuse the same session/subagent pool. If completed agents are still open, a later goal continuation can hit the cap and the model currently just gives up on delegation.The fix requested here is intentionally narrower: when
spawn_agenthits the cap, make the model-visible error tell Codex to inspect, close, or reuse existing agents before continuing locally.[-]Make agent thread-limit errors tell the model how to recover[/-][+]Return actionable recovery guidance when /goal continuations hit the spawn_agent thread limit[/+]etraut-openai commentedon May 3, 2026
I don't think it would make sense for the
/goalsfeature to have any special-cased knowledge of subagent spawning. There are many failures that agents can encounter during long-running tasks. Subagent spawning limitations are not special in that regard. If you want to provide specialized recovery instructions for your agent for specific error conditions, I recommend doing so in your AGENTS.md or in your goal definition.