fix(agent): route parallel/council fan-out to one concurrent spawn_parallel_agents call (#4754)

[M3gA-Mind]

What

An agent-efficiency eval found the orchestrator never fanning out sub-agents concurrently (PARALLEL=0 across the whole run):

• "spin up a separate researcher for each … in parallel" → 1 spawn (ignored the fan-out).
• "convene a council … multiple independent opinions" → 1 spawn.
• "fan out and summarize each of my last 4 threads" → 3 spawns at 9.8s / 155.2s / 355.5s — strictly serial, each sub-agent finishing before the next started.

Root cause (verified in code) — routing, not harness concurrency

I traced the concurrency path end to end:

• tinyagents spawn_parallel_agents → map_reduce is genuinely concurrent — futures::stream::iter(...).buffer_unordered(N) with eagerly-constructed per-worker futures. openhuman's adapter passes max_concurrency = N and FailurePolicy::CollectAll. As a single tool call it also sidesteps the harness's serial-multi-call path.
• So the concurrent fan-out primitive already works. The eval's failures come from the orchestrator using serial spawn_subagent (single or repeated) instead of the one concurrent spawn_parallel_agents call. The "only 1 spawn" council/parallel cases are decisive: the model never fanned out at all, which no harness change can fix.

This is an openhuman routing defect: the model reaches for spawn_subagent even when the user explicitly asks for parallel/council work.

Fix (minimal) — steer at the two decision points the model actually uses

1. orchestrator/prompt.md — explicit trigger→tool mapping: "in parallel" / "a separate researcher for each X" / "convene a council / multiple independent opinions" / "fan out over N" ⇒ one spawn_parallel_agents call (one task per worker), with a warning that looping spawn_subagent runs strictly one-at-a-time (~145s+ each) and defeats the parallel intent.
2. spawn_subagent.rs tool description — the string the model reads at tool-selection time now redirects concurrent fan-out to spawn_parallel_agents and calls out that repeated spawn_subagent serializes.
3. tests/orchestrator_parallel_fanout_routing.rs — regression test pinning the routing guidance in both places (mirrors the existing orchestrator_*_wiring.rs include-str tests).

Secondary finding (reported, out of scope)

The tinyagents harness does serialize multi-tool-call turns whenever tool-wrap middleware is registered (openhuman always registers 5: schema-guard, approval, cli-rpc, tool-policy, credential-scrub) — because ToolMiddleware::wrap_tool(&mut RunContext) holds an exclusive borrow across the call (agent_loop/tools.rs: tool_calls.len() > 1 && tool_middleware_len() == 0). That's a real latency limitation for legitimate in-turn multi-tool fan-out, but it's documented as deliberate, its fix is architectural (not minimal), and it would not address the confirmed single-spawn cases here. Flagging for separate tracking rather than changing the harness in this PR.

Testing

No local build (disk constrained); CI will compile/run. Failing-before/passing-after is deterministic: on main the prompt contains council 0× and the serial-loop warning 0×, and spawn_subagent's description mentions spawn_parallel_agents 0×; with the fix all three are present. (Note: the repo's cargo test --lib target has a pre-existing, unrelated compile break on main — web_tests.rs imports super::compose_system_prompt_suffix, which web/mod.rs doesn't re-export — so this regression is written as an integration test that compiles against the clean lib, per the existing orchestrator_*_wiring.rs convention.)

Closes #4754

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 41 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: dc270808-6046-4d23-9c0b-cca8eb4e213b

📥 Commits

Reviewing files that changed from the base of the PR and between 54511e6 and 9e404f1.

📒 Files selected for processing (3)

• src/openhuman/agent_orchestration/tools/spawn_subagent.rs
• src/openhuman/agent_registry/agents/orchestrator/prompt.md
• tests/orchestrator_parallel_fanout_routing.rs

---

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6e8d1a2c93

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[YellowSnnowmann]

Approve. The fix delivers what #4754 needs, and the root-cause call is correct.

The issue guessed the bug was in the tinyagents harness. Verified it is not: map_reduce fans out concurrently via futures::stream::iter(...).buffer_unordered(concurrency) with eagerly-built per-item futures (vendor/tinyagents/src/graph/parallel/mod.rs:62-80), and spawn_parallel_agents is registered for the orchestrator (agent.toml:239, tools/ops_tests.rs:190/221). So the concurrent primitive already works — the eval's PARALLEL=0 failures, especially the two cases that produced only ONE spawn, are a routing failure (model reaching for serial spawn_subagent) that no harness change could address. Steering the model at both decision points it reads is the right minimal lever.

Notes:

• The prompt fan-out block (orchestrator/prompt.md:117-125) sits cleanly after the existing "Parallel fan-out (spawn_parallel_agents)" section and reinforces, rather than contradicts, the surrounding guidance.
• The 3 include-str assertions in tests/orchestrator_parallel_fanout_routing.rs are all satisfiable against shipped text (spawn_parallel_agents, council at prompt.md:119, never a loop of at prompt.md:117, and spawn_parallel_agents inside the description() body) — meaningful pins, not tautologies.
• Secondary finding (tinyagents serializes in-turn multi-tool turns when tool-wrap middleware is registered — agent_loop/tools.rs:101, tool_calls.len() > 1 && tool_middleware_len() == 0) is real and accurately reported as out-of-scope: it's architectural and wouldn't fix the confirmed single-spawn cases. Fine to track separately.

Comment resolution: Codex P2 (description promising synchronous behavior) is genuinely addressed in 9e404f1 — the HEAD description() now reads "by default it runs as a reusable async worker and returns immediately — pass blocking: true to run it inline", which matches the actual if !blocking async-delegation default (spawn_subagent.rs:425). Thread is GitHub-unresolved but substantively handled; the author's reply documents the change. Worth clicking Resolve.

[YellowSnnowmann]

Approving — feature satisfied, no blocker/major issues, review comments addressed in code, CI green. Detailed review in the PR comment above.