Sub-agent sync-vs-async is session-host-dependent (not version/flag); run_in_background:false not reliably honored — no documented way to force synchronous execution

Description

Whether an Agent() / Task sub-agent runs synchronously (final message returned inline as the tool result, in the same turn) vs asynchronously (background task + task-notification on completion) is not controllable via a documented API, and it differs between sessions at the same Claude Code version and the same flags. run_in_background: false is honored in some sessions and silently ignored in others.

Version / environment (both sessions identical)

• Claude Code 2.1.183
• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Repro / observation

Call the Agent/Task tool with run_in_background: false explicitly set (e.g. prompt: reply PONG):

• Session A — env included CLAUDE_CODE_CHILD_SESSION=1 (a child session): the call returns PONG inline as the tool result, synchronously, in the same turn.
• Session B — top-level interactive session, same version, same AGENT_TEAMS flag: the same call launches async — Async agent launched … working in the background … notified when it completes — and the result arrives later as a task-notification. run_in_background: false is effectively ignored (always async, 3/3 attempts).

So sync-vs-async is determined by some session / hosting factor (appears related to CLAUDE_CODE_CHILD_SESSION), not by the version or the AGENT_TEAMS flag.

Expected vs actual

• Expected: identical version + flags produce identical, controllable behavior; run_in_background: false is honored consistently (synchronous, inline return).
• Actual: behavior depends on an undocumented session/host factor; run_in_background: false is honored in some sessions and ignored in others, with no documented way to tell which you will get.

Why this matters

• run_in_background is not documented as an Agent/Task tool parameter, and there is no documented, reliable way to force synchronous (foreground, inline-returning) sub-agent execution.
• The async path's completion signal is the task-notification, which is already known to be dropped / duplicated / mis-routed (#68997, #60001, #68065, #68749). An orchestrator that depends on a sub-agent's result therefore cannot escape that unreliable channel by forcing synchronous execution — because synchronous execution is not reliably available. This blocks a clean fix for the notification-drop stall in any multi-agent / agent-team workflow: the orchestrator is forced onto a channel that can silently drop, with only out-of-band polling as a workaround.

Requests (clarification)

1. Document the Agent/Task tool parameter schema, including run_in_background, and when/whether it is honored.
2. Either provide a reliable, documented way to force synchronous foreground sub-agent execution, or document exactly what determines sync vs async (session type / CLAUDE_CODE_CHILD_SESSION / launch mode), so it becomes controllable.

Related

• #68997 — background-agent completion notifications silently dropped (sequential dispatch; agents complete cleanly, no task-notification fires).
• #60001 — silent drops with ≥3 parallel dispatches.
• #68065 — completion notifications routed to the wrong agent ID (sequential dispatch).
• #68749 — sub-agent not woken by the completion of its last pending background task.

Those four are the downstream symptom (the async channel is unreliable). This issue is the upstream question they all run into: there is no reliable way to avoid the async channel by running the sub-agent synchronously.