codex - 💡(How to fix) Fix Completed subagents continue to count against thread limit

What version of Codex CLI is running?

codex-cli 0.130.0

What subscription do you have?

Pro

Which model were you using?

ChatGPT 5.5

What platform is your computer?

Darwin 25.4.0 arm64 arm (MacBook Pro, M4 Max, MacOS Tahoe 26.4.1)

What terminal emulator and version are you using (if applicable)?

WarpTerminal v0.2026.05.13.09.15.stable_01

Codex doctor report

Not available. codex doctor --json is not supported by this installed CLI version; it exits with unexpected argument --json.

What issue are you seeing?

Completed subagents can continue to count against the per-session agent thread limit. After enough subagents have completed, a later spawn_agent call may fail with:

collab spawn failed: agent thread limit reached

This can happen even when earlier subagents have reached a final/completed state and are no longer doing work. Explicitly closing completed agents can free the quota, which suggests the quota is tied to thread removal/close rather than completion.

What steps can reproduce the bug?

Generic reproduction:

1. Start a Codex session with subagents enabled.
2. Spawn subagents sequentially or in batches.
3. Wait for each spawned subagent to complete normally.
4. Do not explicitly close the completed subagents.
5. Continue spawning more subagents in the same session until the configured agents.max_threads quota is reached.

Expected result: completed subagents should no longer consume active spawn quota.

Actual result: later spawns can fail with agent thread limit reached until completed subagents are explicitly closed or the session is restarted.

A focused code-level reproduction is to set a low agents.max_threads, spawn an agent, drive it to TurnComplete, and then attempt another spawn. The second spawn should be allowed once the first agent is final.

What is the expected behavior?

Subagent quota should represent agents that are currently active/running or being reused for new work, not agents that have already reached a final status. Completed agents may remain addressable for history/listing purposes, but they should not block new spawns unless they are restarted and reacquire a quota slot.

Additional information

I investigated the relevant lifecycle/accounting path and found that spawned/resumed agents increment quota, while quota release was tied to explicit shutdown/close/thread removal. Normal completion updates agent status but does not release the quota slot.

I have a focused branch with a proposed fix and tests here: https://github.com/pengyou200902/codex/tree/fix/subagent-thread-limit

Proposed approach:

• Track counted agent IDs separately from retained agent metadata.
• Release the quota slot when an agent reaches a final status, while preserving metadata.
• Reacquire a quota slot before sending new work to an existing completed agent.
• Handle resumed agents whose restored history already has a final status.

Validation run on the branch:

• just fmt
• just fix -p codex-core
• cargo test -p codex-core release_spawn_slot_preserves_agent_metadata_until_thread_release
• cargo test -p codex-core completed_agent_releases_max_threads_slot
• cargo test -p codex-core spawn_slot

Per docs/contributing.md, I am opening this issue first and would only open a PR if maintainers invite one.