claude-code - 💡(How to fix) Fix Agent tool: automatic async escalation when run_in_background is unset is undocumented

Summary

When calling the Agent tool without run_in_background: true, the harness can silently launch the agent as an async background task and return "Async agent launched successfully" instead of blocking until completion.

Expected behavior (per docs)

• run_in_background defaults to false → agent should block the main conversation until complete.
• Docs state: "Foreground subagents block the main conversation until complete."

Observed behavior

A codex-executor subagent dispatched without run_in_background: true returned "Async agent launched successfully" and completed ~3m45s later via a background notification — never blocking the main thread.

What the docs say

The sub-agents docs mention:

"Claude decides whether to run subagents foreground or background based on the task."

But there is no documentation explaining:

• What criteria trigger automatic async escalation
• Which subagent types (e.g. codex-executor) are always treated as background
• Whether run_in_background: false (or unset) is ever truly respected for certain agent types

Impact

Developers relying on foreground blocking behavior (e.g. to read output before proceeding) may get async execution silently. Conversely, developers who always set run_in_background: true may not know it is redundant for certain subagent types.

Suggested fix

Document the automatic async escalation criteria. Either:

1. Clarify which subagent types always run async regardless of run_in_background, or
2. Guarantee that run_in_background: false (default) always blocks, and make escalation opt-in only.