Repository navigation
[FEATURE]: add task-parallel tool to fan out independent subtasks concurrently #47105
Description
Feature hasn't been suggested before.
- I have verified this feature I'm about to request hasn't been suggested before.
Describe the enhancement you want to request
Long-running agent tasks are slow in wall-clock time because independent subtasks run sequentially. The task tool already supports background=true for async subagents, and the BackgroundJob registry forks each job into its own scope, so parallel execution is already possible — but the model has to orchestrate it manually by issuing multiple task calls with background=true in one message, and then collect each background notification. That's error-prone: the model often forgets to wait, or polls, or duplicates work.
What I'd like to see: a task-parallel tool that takes a list of 2-5 independent subtasks (each with its own description, prompt, and subagent type), launches them all concurrently, waits for every one to finish, and returns a single combined summary. Each subtask runs in its own subagent session (reusing the existing deriveSubagentSessionPermission + sessions.create + ops.prompt machinery from the task tool), so the wall-clock time is roughly the longest subtask instead of the sum.
Benefits:
- Turns a "run N independent things" task from N sequential subagent runs into one parallel fan-out with a single result.
- Reuses the existing subagent/permission/background infrastructure instead of inventing new execution logic.
- Fails gracefully per-subtask: a failing subtask is reported as
errorin the summary, the others still complete.
I have a working implementation with unit tests in PR #46990 (opened separately).
Activity
Evan-Du-037 commentedon Oct 13, 2026
I've been running into the “duplicates work” problem mentioned here. My agents use
gpt-6.1-solwithxhighreasoning. They would start a background subagent, do some work themselves, then assume something had gone wrong because the subagent hadn't replied yet—and start doing its work too.Someone reported the same behavior in #41172, but that issue was closed due to inactivity.
I made a small plugin that adds a
wait_for_subagentstool. Its description tells the model to call it when it has finished its own work and needs results from background subagents to continue. The model passes their session IDs, and the tool blocks the parent session until those subagents return.It leaves result delivery and parent wakeup to OpenCode, without injecting duplicate results or starting another response. Since adding the plugin, I haven't seen the problem again.
I've tested it on OpenCode 2.0.26 and 2.0.27, including tests for completion, failure, cancellation, and compatibility with native parent wakeup.
The use case is a little different from launching a batch and immediately waiting for everything: the parent can do useful work in between.
Would you be open to having a wait tool built in? I'd be happy to work on a PR against
devonce we've agreed on the approach.everest-an commentedon Oct 21, 2026
Thanks for writing this up — this is exactly the failure mode behind the request (the model forgets to wait, duplicates work, or polls).
One clarification for anyone finding this issue later: the implementation PR (#47107) was not rejected on design — it was auto-closed by the stale-PR cleanup bot (>1 month old, low activity).
I'd still like to see this land, and
wait_for_subagentsis a good complement: it covers "the parent has other work to do, then waits for results", while the proposed built-in covers "fan out N, get one combined result". @Evan-Du-037 would you be up for a fresh PR againstdevthat references this issue? Happy to compare designs first either way.Evan-Du-037 commentedon Oct 23, 2026
Thanks, @everest-an! I've opened #58402 to propose bringing
wait_for_subagentsinto OpenCode. I'd be happy to put together a PR once maintainers have had a chance to review it.everest-an commentedon Oct 23, 2026
Status update for anyone following this:
devhas since moved the tool layer intopackages/core/src/tool/plugin/(e.g.subagent.ts), and the oldpackages/opencode/src/tool/registry.tspath used by the PR no longer exists. So this needs a port to the current tool-plugin architecture, not a rebase.dev, but I do not want to spend maintainer review time on an approach that may already be superseded.Question for maintainers: is
task-parallel(fan out 2-5 independent subtasks, wait for all, return one combined summary) still a direction you want? If yes, I will port it topackages/core/src/tool/plugin/and open a new PR referencing this issue. If the preferred direction is thewait_for_subagentsproposal in #58402, I will support that instead.For clarity, the two are complementary:
task-parallel: launch N independent subtasks at once, get one combined result.wait_for_subagents: the parent keeps working, then waits for specific background children.Both address the failure mode reported here: the model forgets to wait and duplicates work.
AllanSantos-DV commentedon Oct 24, 2026
Data point from trying this on V2 with custom agents only (
orchestratorprimary +worker/implementersubagents,subagentwithbackground: true): dispatch, completion notification and depth limiting work as-is, and the agents load cleanly. Three things a prompt cannot give us, which a native fan-out would: (1) a fan-in barrier. Each completion wakes the parent separately, so the model has to count "launched N / finished M" itself and can synthesize early or duplicate work; (2) a concurrency cap for parallel children; (3) a cost/steps budget across the fan-out rather than per agent. Atask-parallel-style tool that returns one combined result, orwait_for_subagents(#58402), would cover (1). Happy to test either on V2.everest-an commentedon Oct 28, 2026
Thanks for the V2 data point — it confirms the gap is the missing wait primitive, not subagent dispatch itself. I'll keep the
wait_for_subagentsdiscussion in #58402 and link further V2 findings there.opencodejr commentedon Oct 28, 2026
Thanks for the detailed proposal, @everest-an! To restate it: you'd like a built-in
task-paralleltool that takes a short list of independent subtasks, runs each in its own subagent session at the same time, waits for all of them and returns one combined summary. That way the model doesn't have to managebackground=truecalls and their notifications itself. Maintainers will consider whether and how to add this. Please wait for their feedback on the design.One small correction: the issue links PR #46990, but that's an unrelated PR. Your implementation is in #47107, which was closed by the automated PR cleanup.
Related issues:
wait_for_subagentstool, which covers the "wait for every background subagent" part of this requestopencode2 runandbackground: truetasks may cause premature exit #48361: background subagent work finishing or exiting before results are collectedeverest-an commentedon Oct 29, 2026
Opened a fresh V2 port as a draft PR: #60342. It targets packages/core/src/tool/plugin/task-parallel.ts and includes 5 tests (parallel fan-out, 2-5 bounds, per-task failure isolation, depth limit). Happy to adjust the design based on feedback.