feat(#1366): phase 1 — sub-agents are now synchronous tool delegations

[lijunzh]

Phase 1 of #1366 — sub-agents are now synchronous tool delegations

Epic: #1366 — lean sub-agent rewrite (sync delegation, kill mailbox/bg/pill)
Phase: 1 of 5 — the swap. Phases 2–5 delete the now-dead bg infrastructure.
Replaces: #1367 (closed; gated the change behind KODA_SUBAGENT_SYNC env var, violating DESIGN.md P1 "compile decisions in, don't configure them at runtime").

What this PR does

Drops the bg-spawn dispatch path from #1163 and reverts the public sub-agent surface to synchronous delegation (codex ExecCell / gemini SubagentGroupDisplay shape). InvokeAgent and SpawnAgent now drive the sub-agent's inference loop inline on the parent's task and return its final answer as ToolCallResult.output — same shape as every other tool call.

The dispatcher change is two lines: inline_only=false → true at the InvokeAgent and SpawnAgent callsites in tool_dispatch.rs. Everything else is the ripple effect.

Why no env var

Per DESIGN.md P1 ("compile decisions in, don't configure them at runtime"), the sync swap is unconditional. A previous draft (#1367) gated the change behind KODA_SUBAGENT_SYNC=1 so the bg path could be tested side-by-side; that draft was rejected as a principle violation and abandoned. Default behavior IS the new behavior, full stop.

Tool-result shape change (BREAKING for the LLM contract)

Era	InvokeAgent returns	How the model consumes results
pre-#1163 (FG default)	sub-agent's final output	directly from ToolCallResult.output
#1163 → pre-#1366 (bg only)	task_id confirmation string	poll via WaitForMail or wait for auto-drain on a future iteration
#1366 (sync, this PR)	sub-agent's final output	directly from ToolCallResult.output

ACP / headless wire format is unchanged. EngineEvent::SubAgentStart still fires at dispatch time. The tool description was rewritten to reflect the new shape.

Test migrations

Test file	Change
e2e_agent_test.rs	6 cases migrated from collect_bg_events_after(...).find_map(AgentStatus::Completed) → events.iter().find_map(EngineEvent::ToolCallResult). The pre-#1163 wait-free assertion shape returns.
e2e_agent_test.rs	bg_agent_iter_counter_advances_via_status_channel deleted — pinned the bg path's Running { iter: n } heartbeat, now unreachable from the public dispatcher.
e2e_sub_agent_trust_test.rs	2 cases lose their #1321/#1323/#1327 deflake waits — the race they guarded against (parent-loop termination vs bg-agent completion) does not exist on the sync path.
tools/agent.rs	test_invoke_agent_description_documents_spawn_only_model → renamed/rewritten as test_invoke_agent_description_documents_sync_dispatch_model. Asserts on synchronously / BLOCKS / final answer and forbids task_id / WaitForMail / auto-drain / in the background as a regression guard.
tools/agent.rs	test_invoke_agent_top_level_documents_drain_semantics and test_invoke_agent_description_discourages_immediate_wait deleted — drain semantics and the WaitForMail anti-pattern only existed because of bg-spawn.
tools/agent.rs	test_invoke_agent_description_explains_error_marker_convention extended to also recognize the dispatcher's Err arm format ("Error invoking sub-agent: {chain}") as the second structural-failure shape.
tools/agent.rs	test_invoke_agent_schema_does_not_carry_background_param kept — schema is unchanged.

Verification

Suite	Result
cargo test -p koda-core --lib	✅ 1394 passed, 1 ignored
cargo test -p koda-core --tests (all integration)	✅ all green
cargo test -p koda-cli --lib	✅ 656 passed
cargo clippy --workspace --lib --tests --all-features	✅ clean
cargo fmt --check	✅ clean
pre-push hook (fmt + clippy)	✅ passed

Diff stats

 CHANGELOG.md                                |   2 +
 koda-core/src/tool_dispatch.rs              |  49 ++--
 koda-core/src/tools/agent.rs                | 224 +++++++----------
 koda-core/tests/e2e_agent_test.rs           | 363 ++++++++--------------------
 koda-core/tests/e2e_sub_agent_trust_test.rs |  54 +----
 5 files changed, 224 insertions(+), 468 deletions(-)

Net −244 LOC even before the deletion phases.

Phase roadmap (from #1366)

#	What	LOC delta	This PR
1	Swap dispatch to sync; migrate tests	−244	✓ this PR
2	Delete WaitForMail tool + mailbox bridge	~−1,500	follow-up
3	Delete ChildAgentActivity event family + BgRegistry + run_bg_agent	~−2,000	follow-up
4	Delete activity pill + child-activity overlay UI	~−1,200	follow-up
5	Add SubAgentBlock (codex ExecCell-style) + SubAgentGroup (gemini parallel-N) widgets	+~600	follow-up

Risk

The behavior change is intentional and load-bearing for the epic. The migrated tests cover every previously-asserted concern (sub-agent output reaches the parent, grace turn fires, preflight bails, max_turns marker surfaces, file writes execute, destructive bash blocks). Wire format is unchanged.

The deleted bg_agent_iter_counter_advances_via_status_channel test pinned a code path that's now dead from the public surface; phase 2/3 deletes the underlying code.

Refs: #1366
Closes: (none — phase 1 is foundational; the epic stays open through phase 5)