Claude Code Tool Execution: Scheduling, Streaming, and Governance

query.ts does not execute tools directly.

It hands tool work to services/tools/ — a subsystem that treats tool execution as a pipeline with scheduling, governance, abort control, progress, and transcript shaping all included.

Once you see that, "the model called a tool" stops being the right mental model. The model emits a tool_use block. The execution subsystem turns that into governed work.

File structure

src/
├── services/
│   └── tools/
│       ├── toolOrchestration.ts
│       ├── toolExecution.ts
│       ├── StreamingToolExecutor.ts
│       └── toolResultPersistence.ts

The scheduling layer: partitionToolCalls

The most important invariant in toolOrchestration.ts is how concurrency is decided:

concurrency is per-invocation, not per-tool-type.

partitionToolCalls groups adjacent concurrent-safe calls into one batch, then groups the next set of exclusive calls into a serial batch, and so on. The batching respects the original order from the model — it never reorders calls.

export async function* runTools(toolUseMessages, assistantMessages, canUseTool, toolUseContext) {
  let currentContext = toolUseContext
  for (const { isConcurrencySafe, blocks } of partitionToolCalls(toolUseMessages, currentContext)) {
    if (isConcurrencySafe) {
      // Run this batch concurrently — collect context modifiers, apply in order after
      const queuedContextModifiers = {}
      for await (const update of runToolsConcurrently(blocks, ...)) {
        if (update.contextModifier) {
          queuedContextModifiers[update.contextModifier.toolUseID] ??= []
          queuedContextModifiers[update.contextModifier.toolUseID].push(update.contextModifier.modifyContext)
        }
        yield { message: update.message, newContext: currentContext }
      }
      // Apply context modifiers in original block order — not concurrent arrival order
      for (const block of blocks) {
        for (const modifier of queuedContextModifiers[block.id] ?? []) {
          currentContext = modifier(currentContext)
        }
      }
    } else {
      // Serial batch — each tool sees the previous tool's updated context
      for await (const update of runToolsSerially(blocks, ...)) {
        if (update.newContext) currentContext = update.newContext
        yield { message: update.message, newContext: currentContext }
      }
    }
  }
}

The context modifier ordering is the subtle detail: when running concurrently, all tools start with the same currentContext. Their contextModifier callbacks (which mutate the context — e.g., updating file state cache, adding a tracked path) are applied after the batch, in the original block order, not the arrival order of completions. This prevents nondeterministic context state.

The per-tool pipeline: runToolUse

runToolUse is a generator that handles one tool_use block from end to end. In order:

StreamingToolExecutor: speculation during the stream

The default execution model would be: wait for the full assistant response, then execute all tool calls. StreamingToolExecutor changes this.

As the assistant response streams in and tool_use blocks complete their JSON parsing, StreamingToolExecutor can start executing them immediately. The model's output latency overlaps with tool execution latency.

When streaming fails and a fallback model is tried:

1. The old StreamingToolExecutor is discarded — discard() marks it as dead
2. Orphaned partial messages from the failed attempt are yielded as tombstone events — the UI and transcript remove them
3. A fresh executor is created for the fallback attempt

if (streamingFallbackOccurred) {
  for (const msg of assistantMessages) {
    yield { type: 'tombstone', message: msg }
  }
  if (streamingToolExecutor) {
    streamingToolExecutor.discard()
    streamingToolExecutor = new StreamingToolExecutor(tools, canUseTool, toolUseContext)
  }
}

This is why tombstone messages exist: they are not error signals, they are cleanup signals for a specific streaming recovery path.

The hook invariant: hooks cannot override deny or safety checks

One of the most important policy decisions in toolHooks.ts is resolveHookPermissionDecision:

A PreToolUse hook returning allow does not bypass deny rules or safety-check rules.

Hooks operate inside the governance system. They can approve requests that would otherwise prompt the user — but they cannot override rules that the user or administrator explicitly set as deny, and they cannot skip safety-check gates (.git/, .claude/, shell configs).

This keeps hooks powerful without making them a back door around policy.

// Partition tool calls into concurrent/serial batches, run in order
export async function* runTools(toolUseMessages, assistantMessages, canUseTool, ctx) {
let context = ctx
for (const { isConcurrencySafe, blocks } of partitionToolCalls(toolUseMessages, context)) {
  if (isConcurrencySafe) {
    const pending = {}
    for await (const update of runToolsConcurrently(blocks, assistantMessages, canUseTool, context)) {
      if (update.contextModifier) {
        pending[update.contextModifier.toolUseID] ??= []
        pending[update.contextModifier.toolUseID].push(update.contextModifier.modifyContext)
      }
      yield { message: update.message, newContext: context }
    }
    // Apply modifiers in original order — not completion order
    for (const block of blocks) {
      for (const mod of pending[block.id] ?? []) {
        context = mod(context)
      }
    }
  } else {
    for await (const update of runToolsSerially(blocks, assistantMessages, canUseTool, context)) {
      if (update.newContext) context = update.newContext
      yield { message: update.message, newContext: context }
    }
  }
}
}