codex - 💡(How to fix) Fix Codex Desktop main thread can stay stuck thinking when a sub-agent remains active

What version of the Codex App are you using (From “About Codex” dialog)?

26.513.31313 (2867)

What subscription do you have?

ChatGPT Pro

What platform is your computer?

Darwin 25.5.0 arm64 arm

Hardware: Mac with Apple M1 Max.

What issue are you seeing?

Codex Desktop can leave the main thread stuck in an active thinking state when a sub-agent is still active/running, even after the visible work in the main thread has already completed.

Observed behavior from the affected turn:

• The main agent was handling a simple local configuration request: append a new section to ~/.codex/AGENTS.md.
• Because the sandbox could read but not write that home-directory file, the assistant checked the file and then checked whether the target section already existed.
• The visible shell/tool work completed quickly:
  • ls -l ~/.codex/AGENTS.md && tail -n 20 ~/.codex/AGENTS.md returned successfully.
  • rg -n "Persistent Codex Agent Rules|Sub-agent Lifecycle|thread count is back to 1" ~/.codex/AGENTS.md returned no matches and exited normally with code 1, which is expected for rg when no match is found.
• After that, the main thread still appeared to be stuck on thinking instead of completing or reporting a blocker.
• The user observed that a sub-agent was still running/active, and the main thread did not clearly surface that it was waiting on that sub-agent, did not show a clear sub-agent action request, and did not automatically close/terminate the child thread.
• The user had to interrupt the turn manually.

After interruption, the thread showed:

<turn_aborted>
The user interrupted the previous turn on purpose. Any running unified exec processes may still be running in the background. If any tools/commands were aborted, they may have partially executed.
</turn_aborted>

This looks like a Desktop app sub-agent lifecycle/status synchronization problem rather than a shell command problem. The visible commands had already returned. The remaining active state appeared to be tied to a child/sub-agent thread still being considered running or not reconciled with the parent thread.

Impact:

• The main thread can appear hung even when its visible foreground work is done.
• It is not clear to the user whether the parent is still reasoning, waiting on a sub-agent, blocked, or leaking an idle/running child thread.
• The user may need to interrupt the parent turn manually, which risks leaving background work in an uncertain state.
• Long-running work with sub-agents becomes harder to trust because the app does not clearly show when the thread count/lifecycle has returned to the parent-only state.

What steps can reproduce the bug?

I do not yet have a fully isolated deterministic repro, but the observed repro pattern was:

1. Open Codex Desktop on macOS using version 26.513.31313 (2867).
2. Use a local workspace/thread where a sub-agent has been created or is still shown as active/running.
3. In the main thread, run a simple task that should complete quickly. The observed prompt was a request to append this section to ~/.codex/AGENTS.md:

# Persistent Codex Agent Rules (Sub-agent Lifecycle)

You are the main orchestrator. Follow these rules on EVERY task:

1. Only spawn sub-agents when the task clearly benefits from parallelism or specialization.
2. Always assign each sub-agent a narrow, explicit role + a clear termination condition.
3. After a sub-agent completes its work (or fails), IMMEDIATELY close/terminate the sub-agent thread using an explicit close command. Do not leave any sub-agent in "awaiting instruction", "running", or idle state.
4. Before returning your final answer, confirm that ALL sub-agents have been closed and the thread count is back to 1.
5. If you ever detect a sub-agent that appears stuck, immediately stop it and report the issue.
6. Limit concurrent sub-agents to max 3-4 unless explicitly told otherwise.

Use the /agent command internally when needed to inspect and manage threads.

1. The main agent determines it cannot write directly to ~/.codex/AGENTS.md from the sandbox, then runs read-only checks like:

ls -l ~/.codex/AGENTS.md && tail -n 20 ~/.codex/AGENTS.md
rg -n "Persistent Codex Agent Rules|Sub-agent Lifecycle|thread count is back to 1" ~/.codex/AGENTS.md

1. The commands complete. In the observed case, rg returned no matches, which was expected.
2. Instead of the parent thread returning a final answer or a clear blocker, Codex Desktop continues to show the main thread as thinking.
3. Inspect the thread/sub-agent state. A sub-agent is still shown as active/running, but the parent thread does not clearly explain that it is waiting on that sub-agent or provide an obvious lifecycle action.
4. Interrupt the parent turn manually.

Session/token/context details:

• Session id was not captured from the UI at the time of the issue.
• Token limit/context window usage was not captured.
• No long-running shell process was visible in the transcript; the visible shell commands had completed.

What is the expected behavior?

The Desktop app should keep parent-thread and sub-agent lifecycle state synchronized.

Expected behavior when a sub-agent is active:

• If the parent is waiting on a sub-agent, the main thread should clearly show that state, including which sub-agent it is waiting on.
• If the sub-agent is awaiting user input or review, that should be surfaced clearly in the main thread, not hidden behind a child thread state.
• If the sub-agent has completed or failed, the app should reconcile that state so the parent can continue or finish.
• If the sub-agent is idle/stuck, the app should provide a clear way to stop/close that sub-agent and unblock the parent.
• The main thread should not remain indefinitely in a generic thinking state after all visible foreground tools/commands have completed.
• Interrupting the parent should not leave the user uncertain about whether child agents or background work are still active.

A more robust behavior would be a visible parent status such as Waiting on sub-agent: <name> or Sub-agent requires input, plus an explicit inspect/stop action for the child agent.

Additional information

This may be related to, but is more specific than, several existing issues:

• #20754: Codex Desktop can remain stuck showing thinking/running even after the task has completed.
• #22361: Subagent review requests are not clearly surfaced in the main thread.
• #18252: Main-thread subagent list can be inconsistent or lose expand/collapse controls.

The difference in this report is the macOS Desktop App version 26.513.31313 (2867) and the specific observed failure mode where the parent thread stayed in thinking while a sub-agent remained active/running, even though the visible main-thread command sequence had already completed.

If there is a recommended location for collecting Codex Desktop session ids, sub-agent ids, or lifecycle logs on macOS, I can attach those the next time this happens.