Tech Brief: Parallelizable Tasks

Problem

The extension's execution model is strictly serial — one task at a time, one tool at a time. The delegation flow (delegateParentAndOpenChild / reopenParentFromDelegation in ClineProvider.ts) was built on top of this sequential model, resulting in three architectural race conditions patched with careful step ordering rather than proper concurrency primitives. The e2e tests in PR #94 are failing non-deterministically because these races cannot be fixed without structural changes.

Additionally, LLM responses frequently contain multiple independent tool calls (e.g., reading several files). These execute sequentially today, adding unnecessary latency.

Proposed Solution

An incremental migration from serial to concurrent execution, delivered in 5 epics and 18 stories. The approach has two key safety properties:

1. TaskScheduler ships at maxConcurrency = 1 — structurally identical to current behavior. This validates the architecture before any user-visible change.
2. Parallel tool execution is gated behind an experiment flag (PARALLEL_TOOL_EXECUTION, default false). Only promoted to default-on after file-level write serialization is in place.

Architecture

Before

ClineProvider
  └─ clineStack: Task[]          ← LIFO array, 18 usage sites
       └─ Task
            └─ presentAssistantMessage()  ← sequential switch, boolean re-entrancy guard
                 └─ tool_use → execute → tool_result → next tool_use → ...

Shared mutable state: Task.lastGlobalApiRequestTime (static), terminalProcess (single slot), didRejectTool (global), presentAssistantMessageLocked (boolean).

After

ClineProvider
  └─ TaskRegistry                 ← Map + stack adapter (Expand-Contract migration)
  └─ TaskScheduler                ← semaphore-based concurrency control
       └─ Task
            └─ ToolExecutionContext    ← per-tool-call scoped state
            └─ DispatchState           ← IDLE | SERIAL | PARALLEL
            └─ presentAssistantMessageParallel()
                 ├─ parallelizable tools → Promise.allSettled + pLimit(8)
                 ├─ file-write tools    → per-path SequencerByKey serialization
                 └─ sequential tools    → one at a time after parallel batch

Tool Classification

This follows OpenAI Codex's approach (supports_parallel_tool_calls() trait, default false) rather than Gemini CLI's model-driven per-call classification.

Key Design Decisions

Milestones

Milestone 1: Foundation + Race Fixes (Epics 1 & 2)

6 stories, all parallelizable across engineers.

Extract shared primitives (RateLimitClock, TaskSemaphore, experiment flag), fix the two delegation race conditions with proper lock boundaries, and add task status transition guards with startup reconciliation for crash recovery. No behavior change.

Milestone 2: TaskScheduler at maxConcurrency=1 (Epic 3)

6 stories, sequential after 3.2a lands first.

Introduce TaskRegistry (replaces clineStack), TaskScheduler (semaphore-based), fan-out code path (reachable only at maxConcurrency > 1), webview task-scoping guard split across two stories (3.2c extension-side focus gate; 3.2d webview-side rejection guard + per-task seq migration), and child completion callback with two injection paths (disk-based for suspended parent, in-memory for live parent). At maxConcurrency = 1, behavior is identical to today.

Milestone 3: Parallel Tool Execution (Epic 4)

5 stories, strictly sequential.

Scope per-tool state into ToolExecutionContext, replace boolean re-entrancy guard with DispatchState enum, implement parallel dispatch with Promise.allSettled + pLimit, add per-file write serialization, and serialize approval dialogs. All gated behind PARALLEL_TOOL_EXECUTION flag.

Milestone 4: Integration Validation (Epic 5)

1 story. Six end-to-end scenarios exercising the full path from parallel dispatch through subtask fan-out.

Delivery Order and Critical Path

          ┌─ 1.1 ─┐
          ├─ 1.2 ─┤
Weeks 1-2 ├─ 1.3  │ (all parallel)
          ├─ 2.1  │
          └─ 2.2 ─┘
               │
Week 3    3.2a (TaskRegistry — must land first)
               │
Week 4    3.1 (TaskScheduler — rebases onto 3.2a)
               │
Weeks 4-5 3.2b → 3.2c → 3.2d (fan-out + webview guard)
               │
Week 5    3.3 (child completion)
               │
Weeks 6-8 4.1 → 4.2a → 4.2b → 4.2c → 4.3 (strictly sequential)
               │
Week 9    5.1 (integration tests)

Critical path: 3.2a → 3.1 → 3.2b → 3.2c → 3.2d → 3.3 → (Epic 4 can start at 4.1 once 1.2+1.3 land)

Risk Summary

Scope Boundaries

In scope: VS Code extension only (18 stories across 5 epics).

Out of scope:

• Standalone CLI delegation experience (deferred)
• Rich webview multi-task display (split-pane, tabbed task views — Stories 3.2c + 3.2d cover the safety layer; richer UI deferred)
• Per-taskId lock granularity in TaskHistoryStore
• End-to-end flag-off regression test suite
• TaskRegistry Phase C (remove internal stack)

Story Count