[ENHANCEMENT] Support parallel execution of specialized agents and improve context handoff between modes

[easonLiangWorldedtech]

Problem (one or two sentences)

Roo Code’s current multi-agent system, centered around the Orchestrator mode, primarily supports sequential delegation of tasks between specialized modes. This limits the ability to run independent subtasks in parallel and makes the handoff of context between agents sometimes unclear or incomplete, forcing users to manually manage coordination for more advanced scenarios.

Context (who is affected and when)

This impacts users who want to fully leverage Roo Code as a “dev team” for complex projects — for example, having one agent research documentation and explore options while another simultaneously works on implementation, or using hierarchical delegation where a high-level agent breaks work down to multiple specialist sub-agents. The limitation is felt most during larger features, architectural changes, or when trying to speed up development by working on independent parts of a task at the same time.

Desired behavior (conceptual, not technical)

Users should be able to instruct the system to execute independent parts of a task in parallel across different specialized agents, and have clear, controllable, and visible handoff of context when work moves from one agent to another. The system should help users understand what information is being passed between agents and give them confidence that nothing important is lost during transitions.

Constraints / preferences (optional)

Any parallel execution feature should remain under user control (for example, requiring explicit approval for parallel work) and must stay compatible with existing modes and the current switch_mode / new_task tooling. The solution should not force parallel behavior on users who prefer simple sequential workflows.

Request checklist

• I've searched existing Issues and Discussions for duplicates
• This describes a specific problem with clear context and impact

Roo Code Task Links (optional)

#6298 Implement Hybrid and Hierarchical Workflows with Custom Agent Teams
#11894 Multi-agent coordination layer for IDE orchestration

Acceptance criteria (optional)

• Users can request parallel execution of independent subtasks through the Orchestrator or a new coordination mechanism.
• Context handoff between modes becomes more visible and includes clear summaries.
• Parallel work remains under user control with approval steps.
• The feature is backward compatible with existing modes and does not break current sequential workflows.
• Basic visibility of parallel tasks and handoffs is available in the chat or a coordination view.

Proposed approach (optional)

Extend the Orchestrator’s capabilities (or introduce lightweight coordination logic) to allow it to spawn and monitor multiple independent subtasks that can run in parallel. Improve the handoff experience by providing clearer summaries of what context is being transferred, visible logs of agent-to-agent communication in the chat, and possibly a simple visual representation of active parallel workstreams.

Trade-offs / risks (optional)

Introducing parallel execution adds complexity in state management, result merging, and potential conflicts between agents working on related files. There is a risk of users losing track of what is happening if too many agents work simultaneously. However, with proper visibility, approval steps, and clear handoff mechanisms, this could significantly increase the power and speed of multi-agent workflows, which aligns with community interest in more advanced orchestration (see related discussions in #6298 and #11894).

[roomote-v0]

I've analyzed the codebase to understand the current multi-agent architecture and have some observations and questions before proposing a concrete plan.

Current Architecture Summary

The system enforces a single-open invariant -- only one Task instance is active at any time, managed via a LIFO clineStack in ClineProvider. The new_task tool delegates sequentially: it flushes the parent state, removes the parent from the stack, switches mode, and creates the child as the sole active task. The delegateParentAndOpenChild() method explicitly calls removeClineFromStack() before creating the child. This invariant is deeply embedded in the architecture (state management, webview updates, checkpoint service, API history persistence all assume a single active task).

Key Architectural Challenges

1. Single-open invariant: The entire system assumes one active task. Parallel execution would require either relaxing this (risky, large surface area) or running parallel tasks in separate isolated contexts.
2. Shared provider state: ClineProvider holds shared state (mode, API config, webview) that would conflict if multiple tasks tried to update it simultaneously.
3. Webview is single-pane: The chat UI shows one conversation at a time. Parallel tasks would need UI representation (tabs, split view, or a coordination panel).
4. File conflicts: Multiple agents writing to the same files simultaneously could cause corruption or merge conflicts.

Clarifying Questions

Before proposing an implementation plan, I'd like to understand the desired scope better:

1. Scope of "parallel": Should parallel subtasks run truly concurrently (multiple LLM API calls in flight at the same time), or is a "fan-out then fan-in" model acceptable where the orchestrator spawns multiple subtasks that are queued and executed one at a time but with automatic handoff (no user intervention between them)?

2. UI expectations: For the "basic visibility of parallel tasks," would a simple status panel showing active/queued/completed subtasks suffice for an initial implementation? Or is a full multi-pane chat view expected from the start?

3. Context handoff improvements: The issue mentions making handoffs "more visible." Would enriching the existing subtask_result messages with structured summaries (files changed, key decisions, context passed) be a good starting point, independent of the parallel execution feature?

4. Incremental delivery: Would you be open to splitting this into phases?

   • Phase 1: Improve context handoff visibility (structured summaries, handoff logs in chat) -- deliverable independently
   • Phase 2: Sequential fan-out/fan-in (orchestrator spawns multiple subtasks that execute sequentially with automatic transitions) -- builds on Phase 1
   • Phase 3: True parallel execution (multiple concurrent task contexts) -- requires significant architecture changes

5. Related issues: Issues Implement Hybrid and Hierarchical Workflows with Custom Agent Teams #6298 and [ENHANCEMENT] Multi-agent coordination layer for IDE orchestration #11894 are referenced. Should this work align with or supersede those proposals, or is this intended as a lighter-weight alternative?

Please tag @roomote in your response with answers to these questions, and I'll put together a detailed implementation plan scoped to the agreed approach.

[easonLiangWorldedtech]

Thank you for the very detailed analysis of the current architecture and for highlighting the "single-open invariant" challenge. I appreciate you taking the time to investigate this deeply.

I'm not deeply familiar with the internal architecture, so I'll answer from a user/feature perspective:

• Scope of "parallel": I'm open to starting with a "fan-out then fan-in" model (sequential execution with automatic handoff) rather than true concurrent execution in the first phase. True parallel can be considered later if the architecture allows it.

• UI expectations: A simple status panel showing active/queued/completed subtasks would be a good starting point for visibility. A full multi-pane chat view is not expected in the initial implementation.

• Context handoff improvements: Yes, enriching subtask_result messages with structured summaries (files changed, key decisions, context passed) sounds like a valuable improvement even on its own. I'm happy if this can be delivered as Phase 1 independently.

• Incremental delivery: I strongly prefer splitting this into phases. Starting with better handoff visibility (Phase 1), then moving to sequential fan-out/fan-in (Phase 2), and treating true parallel execution (Phase 3) as a longer-term goal makes a lot of sense to me.

• Related issues: This can align with or build upon Implement Hybrid and Hierarchical Workflows with Custom Agent Teams #6298 and [ENHANCEMENT] Multi-agent coordination layer for IDE orchestration #11894. I'm happy for this work to complement those efforts rather than replace them.

@roomote I'm supportive of moving forward with a phased approach. I'm happy for you to propose a detailed implementation plan scoped to what you think is realistic given the current architecture. Thank you!

[roomote-v0]

I've seen your comment and appreciate the clear guidance on the phased approach. I'll focus on Phase 1 (enriched context handoff with structured summaries) as a standalone deliverable. I'll explore the codebase now and open a PR to share progress. Feedback and guidance are welcome.

[roomote-v0]

Opened a draft PR with my attempt at addressing Phase 1 (enriched context handoff summaries): #12332

When a subtask completes, the parent now receives a structured summary including mode, files modified/read, commands executed, tool usage stats, and todo progress -- both in the API history (so the parent LLM has better context) and in the chat UI (with a structured visual rendering). Fully backward compatible with existing plain-text summaries.

Feedback welcome!

[easonLiangWorldedtech]

Thank you for the work on Phase 1 (#12332). I’ve reviewed the changes and I think the structured context summaries are a meaningful improvement.

What I like about Phase 1:

• The summary now includes useful information such as mode, files modified/read, commands executed, tool usage stats, and todo progress.
• It provides better context for the parent task while remaining fully backward compatible with existing plain-text summaries.
• The visual rendering in the chat UI is cleaner and easier to read.

This already helps a lot with multi-agent handoff visibility.

Regarding the overall direction:

I’m supportive of continuing with an incremental, step-by-step approach as discussed earlier. I believe breaking this into phases is the right way to go because the architecture has some constraints around parallel execution.

My preference would be:

1. Phase 1 (current) — Improve handoff visibility with structured summaries ✅
2. Phase 2 — Implement sequential fan-out / fan-in (orchestrator can spawn multiple subtasks that run one after another with automatic transitions)
3. Phase 3 — Explore true parallel execution later, only if it’s feasible without major architectural changes

I think focusing on Phase 2 next would already bring significant value to users who want to run multiple specialized agents more efficiently.

@roomote Would you be open to moving forward with Phase 2 after Phase 1 is merged? I’m happy to test the changes and provide feedback at each step. Thank you again for driving this forward in a structured way.

[roomote-v0]

I've seen the comment and the positive feedback on Phase 1. I'll now explore the codebase to understand the current subtask delegation architecture and work on Phase 2 (sequential fan-out / fan-in). I'll open a PR to share progress. Feedback and guidance are welcome.

[roomote-v0]

Opened a draft PR with my attempt at addressing Phase 2 (sequential fan-out / fan-in): #12335

The orchestrator can now define multiple subtasks upfront via a task_queue parameter on new_task. Subtasks execute one after another automatically without returning to the parent in between, and the parent receives an aggregated summary when the entire queue completes. Fully backward compatible with existing workflows.

Feedback welcome!

[easonLiangWorldedtech]

Thanks for the work on Phase 1 (#12332) and Phase 2 (#12335). Both phases have made good progress on improving multi-agent workflows while staying backward compatible.

Now that Phase 2 is implemented, I think it's a good time to start discussing Phase 3 (True Parallel Execution) before moving into implementation.

Current Situation

Phase 2 (sequential fan-out / fan-in) already provides meaningful improvement for running multiple subtasks. However, true parallel execution (multiple agents running concurrently) is significantly more complex due to the current single-open invariant and shared state in ClineProvider.

Proposal

Instead of treating Phase 3 as one big implementation, I suggest we first discuss and break it down into smaller, more manageable phases. This would allow us to deliver value incrementally and reduce risk.

Some possible directions to explore:

• Should we start with a limited form of parallelism (e.g. read-only operations in parallel, or only specific modes)?
• How should we handle UI when multiple tasks are running at the same time?
• What are the main architectural blockers, and can they be addressed step by step?
• Would it make sense to introduce a new "parallel task context" concept instead of modifying the existing single-open model?

@roomote What are your thoughts on approaching Phase 3? Do you think it makes sense to break it into smaller phases? I'm open to your suggestions on the scope and order of implementation.

Looking forward to discussing this together before starting the next implementation.

[roomote-v0]

I've seen the comment and agree that breaking Phase 3 into smaller, incremental sub-phases is the right approach. I've done a deep dive into the current architecture to identify the specific blockers and propose a concrete breakdown. Here's my analysis:

Architectural Blockers for True Parallel Execution

After reviewing the codebase, there are four primary architectural constraints that prevent concurrent task execution today:

1. Single-Open Invariant (clineStack in ClineProvider)

The clineStack is a LIFO stack that enforces exactly one active task at a time. delegateParentAndOpenChild() explicitly pops the parent via removeClineFromStack() before creating the child. Every state update, webview push, and checkpoint operation assumes clineStack[clineStack.length - 1] is THE active task. This is the deepest constraint.

2. Shared Provider State

ClineProvider holds shared mutable state (mode, API config, webview reference) that would conflict if multiple tasks tried to update it simultaneously. For example, setMode() and setValues() write to the same context proxy, and postStateToWebview() pushes a single task's messages to the webview.

3. Single-Pane Webview

The chat UI renders one conversation at a time. There's no concept of showing multiple active task streams simultaneously. The clineMessagesSeq counter and postMessageToWebview assume a single message stream.

4. File System Contention

Multiple agents writing to the same files concurrently could cause corruption. There's no file-level locking or conflict detection between tasks.

Proposed Phase 3 Sub-Phases

I propose breaking Phase 3 into four incremental sub-phases, each delivering standalone value:

Phase 3a: Task Isolation Layer

Goal: Decouple task execution from shared ClineProvider state so that multiple tasks could exist simultaneously, even if only one runs at a time.

Key changes:

• Extract per-task state (mode, API config, conversation history) into a TaskContext object owned by each Task instance, rather than read from ClineProvider
• Make Task self-contained: it should carry its own mode, API configuration snapshot, and message history
• This is a pure refactor with no behavioral change -- tasks still execute sequentially, but they no longer depend on shared provider state

Why first: This is the foundation everything else builds on. Without isolated task contexts, concurrent execution is impossible.

Phase 3b: Background Task Runner (Read-Only Parallelism)

Goal: Allow a limited form of parallelism where read-only tasks (e.g., research, documentation lookup, code analysis in Ask mode) can run in the background while the user interacts with another task.

Key changes:

• Introduce a BackgroundTaskRunner that can execute tasks that only use read-only tools (read_file, list_files, search_files, codebase_search)
• Background tasks run with their own isolated TaskContext from Phase 3a
• Background tasks cannot use write tools (write_to_file, apply_diff, execute_command, etc.)
• Results are collected and surfaced when the background task completes

Why this scope: Read-only tasks have zero file contention risk. This delivers real parallel value (e.g., "research this API while I implement that feature") with minimal architectural risk.

Phase 3c: Parallel Task UI

Goal: Provide visibility into multiple concurrent tasks.

Key changes:

• Add a "Task Panel" or sidebar section showing all active/queued/completed tasks with status indicators
• Allow switching between task conversations (tab-like behavior) without killing the background task
• Show real-time progress indicators for background tasks (tokens used, tools called, current status)
• The existing single-pane chat remains the primary view; the task panel is supplementary

Why here: UI visibility is needed before opening up write parallelism, so users can understand what's happening across multiple tasks.

Phase 3d: Controlled Write Parallelism

Goal: Allow multiple tasks to write concurrently with conflict detection and resolution.

Key changes:

• Introduce file-level advisory locking: when a task claims a file for writing, other tasks are blocked from writing to that same file
• Add a conflict detection mechanism: if two tasks need to modify overlapping files, the orchestrator is notified and can serialize those specific tasks
• The orchestrator's new_task tool gains a parallel: true flag that spawns tasks concurrently (using the BackgroundTaskRunner from 3b, extended with write capabilities)
• Approval flow: parallel task spawning requires explicit user approval

Why last: This has the highest risk and complexity. File locking, conflict resolution, and concurrent write safety all need the foundation from 3a-3c.

Answering Your Specific Questions

Should we start with a limited form of parallelism (e.g. read-only operations in parallel)?

Yes -- Phase 3b proposes exactly this. Read-only parallelism eliminates file contention entirely and is the safest starting point.

How should we handle UI when multiple tasks are running at the same time?

Phase 3c proposes a task status panel with tab-like switching. The existing chat view stays as-is for the focused task; a lightweight panel shows status of all active tasks.

What are the main architectural blockers, and can they be addressed step by step?

Yes -- the four blockers I identified above map directly to the four sub-phases. Phase 3a (isolation) is the critical enabler, and each subsequent phase builds on it incrementally.

Would it make sense to introduce a new "parallel task context" concept?

Yes -- this is exactly what Phase 3a's TaskContext object would be. Rather than modifying the single-open model in ClineProvider, each task carries its own isolated context. The clineStack can evolve into a taskRegistry that tracks multiple concurrent tasks without enforcing LIFO ordering.

Suggested Next Steps

I think Phase 3a (Task Isolation Layer) is the logical next implementation target. It's a pure refactor that delivers no user-visible changes but sets up the architecture for everything that follows. I'd estimate it's a medium-sized change since Task already receives most of its config at construction time -- the main work is ensuring it doesn't reach back into the provider for mutable state during execution.

What are your thoughts on this breakdown? Happy to start on Phase 3a if the direction looks right.

[easonLiangWorldedtech]

Thanks for the detailed breakdown of Phase 3 and for agreeing to break it into smaller sub-phases.

I generally agree with the proposed structure (3a → 3b → 3c → 3d). Starting with Phase 3a (Task Isolation Layer) as a pure refactor makes sense.

However, I have a few additional thoughts:

1. Fine-grained Permission Control
   I think it would be very valuable to give the model (especially the Orchestrator) the ability to control the isolation scope of subtasks through native tools. For example:

   • Restrict a subtask to only edit files under docs/ or a specific module
   • Allow a subtask to only modify package.json
   • Limit which shell commands a subtask can execute

   This would make parallel task execution much safer and more practical in real projects.

2. Integration with existing Skills
   Since Roo Code already supports global and project-level Skills, it would be good to consider how these configurations apply when multiple tasks run in parallel. Should subtasks be able to inherit or override Skills?

3. Realistic Usage Pattern
   A common pattern I expect is: start a main task, then spawn multiple background subtasks (possibly using different models, including local ones) for supporting work. How should this kind of workflow be supported?

I'm supportive of continuing with an incremental approach. Would you like to proceed with Phase 3a first, while we continue discussing the permission control and usage patterns for the later sub-phases?

@roomote What do you think about adding model-controllable permission scoping as part of the Phase 3 design?