feat: Phase 4 - Background Read-Only Concurrency (BackgroundTaskRunner)

[roomote-v0]

This PR attempts to address Issue #12330 (Phase 4: Background Read-Only Concurrency).

Summary

Implements the MVP for Phase 4 of the parallel execution roadmap, enabling read-only background tasks to run concurrently alongside the user's active foreground task. This is the first time the single-open invariant is relaxed -- background tasks live in a separate backgroundTasks collection managed by BackgroundTaskRunner, completely isolated from the clineStack.

Key Changes

New: BackgroundTaskRunner service (src/core/task/BackgroundTaskRunner.ts)

• Manages a Map<string, BackgroundTaskInfo> of concurrent background tasks
• Configurable concurrency limit (default 3) and timeout (default 5 minutes)
• Handles task lifecycle: registration, completion, cancellation, timeout
• Cascading cancellation when parent task is cancelled or provider is disposed

Modified: Task class (src/core/task/Task.ts)

• Added isBackgroundTask flag that suppresses all webview interactions
• addToClineMessages(): skips postStateToWebview when background
• updateClineMessage(): skips postMessageToWebview when background
• ask(): auto-approves all tool uses immediately when background (no user interaction)
• saveClineMessages(): skips updateTaskHistory on provider when background
• Added onBackgroundComplete callback for async result delivery

Modified: new_task tool

• Added optional background parameter ("true" to spawn as background)
• Tool schema updated in native-tools definition
• toolParamNames and type definitions updated in shared/tools.ts
• Background tasks skip the delegateParentAndOpenChild flow entirely

Modified: AttemptCompletionTool

• Background task completion invokes onBackgroundComplete callback
• Bypasses normal delegation/approval flow for background tasks

Modified: ClineProvider

• Added backgroundTaskRunner instance
• Added spawnBackgroundTask() method that creates isolated Task instances
• Added handleBackgroundTaskComplete() for async result injection into parent
• Background tasks disposed during provider cleanup

Design Decisions

• Separate collection, not unified registry: Background tasks use a separate backgroundTasks Map rather than modifying the clineStack. This keeps all existing foreground behavior completely unchanged.
• Webview-silent: Background tasks never call postStateToWebview, postMessageToWebview, or updateTaskHistory. They accumulate messages internally only.
• Auto-approval: All ask() calls in background tasks are immediately approved, enabling fully autonomous execution.
• No checkpoints: Background tasks have enableCheckpoints: false since they are read-only and have nothing to roll back.

Testing

• 17 new tests for BackgroundTaskRunner covering registration, completion, cancellation, parent cascading, timeout, disposal, and concurrency limits
• All existing tests pass (Task.spec.ts: 42 tests, ClineProvider.spec.ts: 87 tests, tools: 363 tests, native-tools-filtering: 3 tests)
• Full lint and type-check pass across all workspaces

What is NOT in this MVP

• No parallel task UI panel (future phase)
• No tab switching between task conversations
• No write parallelism or file locking
• No real-time progress indicators for background tasks
• No checkpointing for background tasks

Feedback and guidance are welcome!

Interactively review PR in Roo Code Cloud

[easonLiangWorldedtech]

@roomote

Thanks for implementing Phase 4 so quickly. The PR looks well-structured and follows the conservative approach we discussed (separate backgroundTasks collection + webview-silent design).

A few questions and feedback:

1. Result delivery & Visibility
   Background task results are injected into the parent via handleBackgroundTaskComplete() using ContextHandoffSummary. This is good for structured handoff, but during the task execution, the user has no visibility at all.
   As we discussed earlier, I'm okay with no progress in MVP. However, do you think the current completion-time injection is sufficient, or should we plan some minimal visibility improvement (even just a simple notification when it finishes) as a quick follow-up?

2. Auto-approval in background tasks
   All ask() calls are auto-approved. This enables fully autonomous execution, which makes sense for read-only background work. But is there any scenario where we might still want the background task to ask for user input on certain actions?

3. Error handling & User notification
   How are errors or timeouts from background tasks currently surfaced to the user? Is there any notification mechanism when a background task fails?

4. Next step
   The implementation looks solid and within the agreed MVP scope. Are you ready for this PR to be reviewed by maintainers, or do you want to make any adjustments first?

Overall I'm happy with the direction. Feedback welcome.

[roomote-v0]

Fixaroo   See task

Added user-visible VS Code notifications for background task completion, errors, and timeouts. Also documented the auto-approval design decision for read-only background tasks. All checks pass (lint, types, 19 tests).

_{View commit | Revert commit}

[easonLiangWorldedtech]

@roomote

Thanks for adding the VS Code notifications and documenting the auto-approval behavior. This addresses the visibility concern nicely without breaking the webview-silent principle.

A few quick questions:

1. Can you briefly describe what the notifications look like? (e.g. Do they show task name + result summary? Can user click the notification to see more details?)

2. With this addition, do you consider the Phase 4 MVP implementation complete?

If yes, I'm okay with marking this PR as ready for review.

Also, just to confirm: after this PR is reviewed and merged, what would be the next recommended phase to work on?

[roomote-v0]

Proofessor   See task

I reviewed the code to answer your questions. Here's what I found:

1. What do the notifications look like?

The PR uses standard VS Code notification toasts (via vscode.window.showInformationMessage / showWarningMessage). There are three notification types:

• Completion (info-level): "Background task {taskId} completed." -- shown in handleBackgroundTaskComplete
• Timeout (warning-level): "Background task {taskId} timed out and was cancelled." -- wired via the onTaskTimeout callback at ClineProvider.ts L145-147
• Error (warning-level): "Background task {taskId} encountered an error: {error.message}" -- wired via the onTaskError callback at ClineProvider.ts L148-150

Currently the notifications only show the internal task ID (a generated identifier), not a human-friendly task name or result summary. The notifications are plain text toasts with no clickable action buttons -- clicking the notification does not navigate anywhere or reveal more details. The actual result content is injected into the parent task's conversation via say("subtask_result", ...) if the parent is still the foreground task.

2. Is the Phase 4 MVP complete?

From a code perspective, yes -- the core MVP functionality is all in place:

• BackgroundTaskRunner with lifecycle management, concurrency limits, timeouts
• Task class modifications for webview silencing and auto-approval
• new_task tool with background parameter
• AttemptCompletionTool integration for background task result delivery
• ClineProvider integration with spawn, completion handling, and disposal cleanup
• VS Code notifications for visibility
• 19 tests covering the BackgroundTaskRunner

The items listed under "What is NOT in this MVP" (parallel task UI panel, tab switching, write parallelism, real-time progress, checkpointing) are all explicitly scoped out as future work. So this looks complete for the stated MVP scope.

3. Next recommended phase

Based on the roadmap progression and what's excluded from this MVP, the natural next step would be a Parallel Task UI Panel (Phase 5) that gives users visibility into running background tasks -- showing status, progress, and results in the webview rather than just VS Code toasts. This would address the current limitation where background task results are only visible if the parent task is still the foreground task when the background task completes.

No code changes were needed here -- just answering the reviewer's questions from the existing implementation.

[easonLiangWorldedtech]

@roomote

Thanks for the detailed explanation.

A few takeaways from your reply:

• Phase 4 MVP implementation is complete from a code perspective.
• The current notifications are basic (only show taskId, no result summary, not clickable). This is acceptable for MVP.
• You recommend the next phase to be Phase 5: Parallel Task UI Panel, which makes sense to improve visibility.

Next steps I’d like to do:

1. Please mark PR feat: Phase 4 - Background Read-Only Concurrency (BackgroundTaskRunner) #12342 as ready for review.
2. Let’s move the discussion of Phase 5 back to the main issue ([ENHANCEMENT] Support parallel execution of specialized agents and improve context handoff between modes #12330). I want to discuss the scope and direction of Phase 5 first before starting any implementation.

Could you mark the PR as ready, and then share your initial thoughts on what Phase 5 should include (especially around visibility and task management UI)?

We can discuss the scope in the issue before moving to coding.

[roomote-v0]

Fixaroo   See task

Done. PR #12342 is now marked as ready for review, and initial Phase 5 thoughts have been posted on issue #12330.

[roomote-v0]

Closing as part of PR restructuring per issue #12330. This work will be combined into the new Remaining Phases (4+5+6) PR with proper stacked branching.