close_agent returns the pre-close status, which is easy to misread as the final close state

[nantas]

What version of Codex CLI is running?

codex-cli 0.115.0

What subscription do you have?

Unknown / source-level investigation

Which model were you using?

N/A (source-level investigation)

What platform is your computer?

Darwin 25.3.0 arm64 arm

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

ghostty

What issue are you seeing?

During a source-level investigation of Codex multi-agent behavior, I found that close_agent returns the receiver's status before shutdown is requested, not the final post-close state.

This appears to be intentional in the current implementation, but it is very easy for callers and workflow authors to misread.

Relevant source references:

• codex-rs/core/src/tools/handlers/multi_agents/close_agent.rs
  • handler reads current status first via subscribe_status(...).borrow_and_update(): lines around 45-52
  • then sends shutdown: lines around 71-78
  • then returns the earlier status: line around 98
• codex-rs/core/src/tools/spec.rs
  • tool description says: Close an agent when it is no longer needed and return its last known status.
• codex-rs/core/src/tools/handlers/multi_agents_tests.rs
  • test explicitly asserts result.status == status_before

The behavior is therefore consistent with the code and tests, but the API shape is easy to misuse when orchestrating subagents.

I searched for similar issues before opening this one and did not find a direct match for this close_agent status semantic.

What steps can reproduce the bug?

A minimal repro is:

1. Spawn an agent.
2. Call close_agent on that agent while it is not already in Shutdown state.
3. Observe that the returned payload contains the previous status.
4. Observe separately that the actual shutdown/not-found transition happens later via status updates or notifications.

In code terms:

1. close_agent subscribes to status and snapshots the current value.
2. close_agent then requests shutdown.
3. close_agent returns the status captured before the shutdown transition completed.

What is the expected behavior?

One of the following would be clearer:

• return the final closed state (Shutdown or NotFound) after waiting for it, or
• keep the current behavior but rename the returned field to something like previous_status, or
• return both values, e.g. { previous_status, shutdown_requested }.

The important part is making it harder to mistake the return value for the final closure state.

Additional information

This seems more like an API/UX semantic issue than a crash bug, but it has practical impact on multi-agent orchestration:

• workflow authors can incorrectly treat close_agent as a completion barrier
• callers can think the agent is fully shut down when the returned status still says running, completed, etc.
• the true terminal state may only be visible later through notifications or subsequent status checks

[jif-oai]

This is kind of by design. I will make it more explicit