StreamingToolExecutor: Full Breakdown of Claude Code’s Four‑Layer Parallel Tool Execution Mechanism

01 | Hidden latency: serial waiting for tool execution

Traditional agents accumulate all tool_use blocks from the API stream, wait for the stream to finish, then run tools sequentially, so total time = API stream time + tool execution time. Claude Code starts a tool as soon as its parameters are complete, running it in parallel with the remaining API stream; total time ≈ max(API stream time, tool execution time). For example, a 2‑second tool and a 3‑second stream drop from 5 s to 3 s.

02 | Source location: concurrency core at line 370

The core resides in src/services/tools/StreamingToolExecutor.ts as the StreamingToolExecutor class, which holds an ordered TrackedTool[] array. Each TrackedTool contains:

id

block

(original ToolUseBlock)

assistantMessage

status

– one of 'queued', 'executing', 'completed',

'yielded'

isConcurrencySafe

(boolean)

optional promise, results, pendingProgress The separation of completed and yielded lets the executor signal that a result has already been returned to the upper layer.

03 | Concurrency determination: two safety rules

The boolean isConcurrencySafe is computed once in addTool(). The private method canExecuteTool(isConcurrencySafe) implements the rules:

Rule 1 : If no tool is currently executing, any tool may start. Rule 2 : If a tool is executing, a new tool may start only when it is marked safe and all currently executing tools are also safe.

Typical scenarios:

Read + Read → ✅ safe (both read‑only)

Read + WebFetch → ✅ safe (independent resources)

Write + Read → ❌ unsafe (write must be exclusive)

Write + Write → ❌ unsafe (data race)

Bash + Read → ❌ unsafe (Bash commands are not concurrency‑safe by default)

Bash (read‑only) + Read → depends on the Bash tool’s isConcurrencySafe implementation

04 | Queue scheduling: the subtlety of processQueue()

processQueue()

iterates the ordered tool array. When it encounters a non‑safe tool that cannot start, it breaks the loop, preventing later tools from being launched out of order. This break preserves the message order expected by Claude.

private async processQueue(): Promise<void> {
  for (const tool of this.tools) {
    if (tool.status !== 'queued') continue;
    if (this.canExecuteTool(tool.isConcurrencySafe)) {
      await this.executeTool(tool);
    } else {
      // If the tool is unsafe, stop scanning further
      if (!tool.isConcurrencySafe) break;
    }
  }
}

05 | Execution layer: three‑level AbortController nesting

The executor builds a hierarchy of abort signals:

parent abortController (held by toolUseContext)
  └─ siblingAbortController (owned by StreamingToolExecutor)
       └─ toolAbortController (one per tool)

Each level has a distinct cancellation scope: the tool‑level cancels only that tool, the sibling level cancels all tools in the same batch without bubbling to the parent, and the top‑level aborts the whole execution round.

06 | Bash‑specific logic: why only Bash triggers sibling cancellation

When a Bash tool returns an error result, the executor marks the batch as errored and calls siblingAbortController.abort('sibling_error'). The comment explains that Bash commands often form implicit dependency chains (e.g., a failed mkdir makes subsequent cd meaningless), so aborting sibling tools prevents wasted work. Read or WebFetch tools lack such chains, so their failures do not cancel siblings.

07 | Result output: immediate progress vs ordered final results

Two output mechanisms run in parallel:

Progress messages are yielded as soon as they arrive, regardless of order.

Final results are yielded only after a tool reaches completed and the executor has verified that no unsafe tool is still executing; the results are emitted in the original tool order.

// Progress handling in getCompletedResults()
while (tool.pendingProgress.length > 0) {
  const progressMessage = tool.pendingProgress.shift()!;
  yield { message: progressMessage, newContext: this.toolUseContext };
}
// Result handling
if (tool.status === 'completed' && tool.results) {
  tool.status = 'yielded';
  for (const message of tool.results) {
    yield { message, newContext: this.toolUseContext };
  }
  markToolUseAsComplete(this.toolUseContext, tool.id);
} else if (tool.status === 'executing' && !tool.isConcurrencySafe) {
  break; // unsafe tool blocks further ordered output
}

The executor also uses Promise.race between running tool promises and a progress‑available promise, ensuring that either a tool finishes or a progress update arrives before the loop continues.

08 | Design insights: four transferable engineering lessons

Insight 1 : An ordered array plus a four‑state machine provides deterministic concurrent scheduling.

Insight 2 : Layered abort signals must match their cancellation semantics; three levels keep scopes clear.

Insight 3 : Separate channels for progress (real‑time UX) and final results (model reasoning) avoid trade‑offs between responsiveness and correctness.

Insight 4 : A “local fail‑closed” rule (only Bash failures cancel siblings) balances safety and robustness; a fully fail‑closed or fully fail‑open policy would be either too fragile or too permissive.

09 | Critique: costs of the design

Cost 1 : isConcurrencySafe is static; it is computed once in addTool() and cannot adapt to different inputs (e.g., reading two different files is safe, editing the same file is not).

Cost 2 : Unsafe tools become serialization barriers; heavy use of writes can degrade performance to pure sequential execution.

Cost 3 : The hard‑coded Bash check for sibling cancellation creates technical debt; new tools with similar dependency semantics would require code changes.

Cost 4 : Context modifiers are currently unsupported for concurrent tools, limiting extensibility.

10 | Practical recommendations for your own agent project

Define an accurate isConcurrencySafe function for each tool; avoid blanket false which forces serial execution.

Adopt the three‑layer AbortController pattern to keep cancellation scopes isolated.

Emit progress updates on a separate channel from final results to keep the UI responsive while preserving ordered reasoning.

Prefer an ordered array with a break‑on‑barrier strategy over a complex task scheduler for typical agent workloads (≤ 20 tools).

Conclusion

The StreamingToolExecutor implements a concise yet powerful concurrency model for Claude Code: a four‑state machine, two clear safety rules, and a three‑level abort hierarchy. These mechanisms together deliver real‑time progress, ordered final results, and graceful failure handling, offering a reusable blueprint for building robust AI‑agent tool pipelines.