5 · Tool Execution

This chapter covers how the program runs a batch of tool calls to completion once the model has produced them.

5.1 The execution pipeline at a glance

5.2 Concurrency partitioning: a greedy algorithm

function partitionToolCalls(toolUseMessages, toolUseContext): Batch[] {
  return toolUseMessages.reduce((acc: Batch[], toolUse) => {
    const tool = findToolByName(toolUseContext.options.tools, toolUse.name)
    const parsedInput = tool?.inputSchema.safeParse(toolUse.input)

    const isConcurrencySafe = parsedInput?.success
      ? (() => {
          try { return Boolean(tool?.isConcurrencySafe(parsedInput.data)) }
          catch {
            // If the predicate throws (e.g. shell quote parsing failed),
            // conservatively treat it as "unsafe"
            return false
          }
        })()
      : false                        // parameters don't even parse → also treated as unsafe

    if (isConcurrencySafe && acc[acc.length - 1]?.isConcurrencySafe) {
      acc[acc.length - 1]!.blocks.push(toolUse)      // merge into the previous parallel batch
    } else {
      acc.push({ isConcurrencySafe, blocks: [toolUse] })   // open a new batch
    }
    return acc
  }, [])
}

claude-code/src/services/tools/toolOrchestration.ts

The effect in practice:

5.3 Context modifications are queued until the batch ends

Some tools modify the shared context object (for instance EnterPlanMode switches the permission mode). If every tool in a parallel batch applied its change immediately, you would have a race.

if (isConcurrencySafe) {
  const queuedContextModifiers: Record<string, ((ctx) => ToolUseContext)[]> = {}

  for await (const update of runToolsConcurrently(blocks, ...)) {
    if (update.contextModifier) {
      const { toolUseID, modifyContext } = update.contextModifier
      if (!queuedContextModifiers[toolUseID]) queuedContextModifiers[toolUseID] = []
      queuedContextModifiers[toolUseID].push(modifyContext)      // ★ queue it first
    }
    yield { message: update.message, newContext: currentContext }  // still using the old context
  }

  // ★ Once the whole batch is done, apply the modifications strictly in the original tool-call order
  for (const block of blocks) {
    const modifiers = queuedContextModifiers[block.id]
    if (!modifiers) continue
    for (const modifier of modifiers) currentContext = modifier(currentContext)
  }
  yield { newContext: currentContext }
}

And Tool.ts has a matching backstop constraint:

5.4 A single execution: the full flow of runToolUse

Step ①: look up the tool by name, with alias support

// First look among the "tools the model can see"
let tool = findToolByName(toolUseContext.options.tools, toolName)

// Not found → check whether it's a deprecated name (old transcripts may still use the old name)
// e.g. an old transcript calls "KillShell", which is now an alias for "TaskStop"
// Fall back only when the name matches an "alias" rather than a "primary name"

The problem this design solves: after a tool is renamed, an old conversation the user resumes with --resume still contains call records under the old name. If that simply produced “tool does not exist,” that historical message could never be processed correctly.

Step ③: parameter shape validation, with an honest comment attached

// Validate input types with zod
// (surprisingly, the model is not great at generating valid input)
const parsedInput = tool.inputSchema.safeParse(input)
if (!parsedInput.success) {
  let errorContent = formatZodValidationError(tool.name, parsedInput.error)
  const schemaHint = buildSchemaNotSentHint(tool, ...)   // see Section 4.5
  if (schemaHint) errorContent += schemaHint
  ...
  return [{ message: createUserMessage({
    content: [{ type:'tool_result',
                content: `<tool_use_error>InputValidationError: ${errorContent}</tool_use_error>`,
                is_error: true, tool_use_id: toolUseID }],
    ... }) }]
}

That parenthetical — “surprisingly, the model is not great at generating valid input” — is a rare bit of candid griping in the source, but it states an important fact: even the strongest model’s tool parameters need strict validation and cannot be trusted.

Note the form of the error result: it is not a thrown exception; it is returned to the model as an ordinary “tool result”, just flagged with is_error: true and wrapped in a <tool_use_error> tag. That way the model can see what it got wrong and correct itself on the next turn.

Step ⑤: speculatively starting the classifier early

// Speculatively start the bash allow classifier check early so it runs in
// parallel with pre-tool hooks, deny/ask classifiers, and permission dialog
// setup. The UI indicator (setClassifierChecking) is NOT set here — it's
// set in interactiveHandler.ts only when the permission check returns `ask`
// with a pendingClassifierCheck. This avoids flashing "classifier running"

In other words: speculatively start the bash allow-classifier check early, so it runs in parallel with the pre-tool hooks, the deny/ask classifiers, and permission dialog setup. The “classifier running” UI indicator is not set here — it is set in the interactive handler only when the permission check returns “ask” along with a pending classifier check. That avoids the indicator flashing on and off.

5.5 The streaming tool executor

The conventional approach is to wait for the model’s entire response to finish streaming before running any tools. Claude Code’s approach: the moment the model finishes writing one tool call, start executing it.

Why this is possible

The model emits one token at a time. If this turn is going to write three tool calls, then when the first one is finished, the second has not yet begun — there is a gap of several seconds in between.

// Inside the streaming loop in query.ts
if (message.type === 'assistant') {
  const msgToolUseBlocks = message.message.content.filter(c => c.type === 'tool_use')
  if (msgToolUseBlocks.length > 0) {
    toolUseBlocks.push(...msgToolUseBlocks)
    needsFollowUp = true
  }
  if (streamingToolExecutor && !toolUseContext.abortController.signal.aborted) {
    for (const toolBlock of msgToolUseBlocks) {
      streamingToolExecutor.addTool(toolBlock, message)     // ★ enqueue the moment it arrives
    }
  }
}
// In the same loop, keep harvesting the ones that have finished
if (streamingToolExecutor && !toolUseContext.abortController.signal.aborted) {
  for (const result of streamingToolExecutor.getCompletedResults()) {
    if (result.message) {
      yield result.message
      toolResults.push(...normalizeMessagesForAPI([result.message], ...))
    }
  }
}

The executor’s internal state machine

type ToolStatus = 'queued' | 'executing' | 'completed' | 'yielded'
//                 waiting    running       finished      emitted

type TrackedTool = {
  id: string
  block: ToolUseBlock
  assistantMessage: AssistantMessage
  status: ToolStatus
  isConcurrencySafe: boolean
  promise?: Promise<void>
  results?: Message[]
  pendingProgress: Message[]      // progress messages stored separately; emitted immediately
  contextModifiers?: Array<(ctx: ToolUseContext) => ToolUseContext>
}

Concurrency rules

private canExecuteTool(isConcurrencySafe: boolean): boolean {
  const executingTools = this.tools.filter(t => t.status === 'executing')
  return (
    executingTools.length === 0                                   // nothing running → go ahead
    || (isConcurrencySafe && executingTools.every(t => t.isConcurrencySafe))
                                        // or: I'm safe AND everything running is safe
  )
}

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 {
      // Can't run this tool. Unsafe tools must preserve order, so stop right here
      // and don't try the tools after it
      if (!tool.isConcurrencySafe) break
    }
  }
}

The class comment sums up three rules:

5.6 The sibling abort controller: the most elegant design in the file

// Child of toolUseContext.abortController. Fires when a Bash tool errors
// so sibling subprocesses die immediately instead of running to completion.
// Aborting this does NOT abort the parent — query.ts won't end the turn.
private siblingAbortController: AbortController

constructor(...) {
  this.siblingAbortController = createChildAbortController(
    toolUseContext.abortController      // ★ the parent controller
  )
}

In other words: this is a child of the main abort controller. It fires when a Bash tool errors, so the sibling subprocesses in the same batch die immediately instead of pointlessly running to completion. Aborting this child does not abort the parent — so the main loop does not end the turn.

5.7 The discard mechanism

/**
 * Discards all pending and in-progress tools. Called when streaming fallback
 * occurs and results from the failed attempt should be abandoned.
 * Queued tools won't start, and in-progress tools will receive synthetic errors.
 */
discard(): void {
  this.discarded = true
}

In other words: discard all pending and in-progress tools. Called when a streaming request fails and falls back, at which point the results of the failed attempt should be abandoned. Queued tools will not start, and in-progress tools will receive synthetic error results.

This method is called from two places, and both handle it identically:

// Scenario 1: the streaming request failed; fall back to a non-streaming retry
if (streamingFallbackOccured) {
  for (const msg of assistantMessages) yield { type:'tombstone', message: msg }
  logEvent('tengu_orphaned_messages_tombstoned', { orphanedMessageCount: ... })
  assistantMessages.length = 0; toolResults.length = 0; toolUseBlocks.length = 0
  if (streamingToolExecutor) {
    streamingToolExecutor.discard()
    streamingToolExecutor = new StreamingToolExecutor(...)    // ★ build a brand-new one
  }
}

// Scenario 2: model fallback to the backup model (see Section 3.7)
// The same four steps: emit tombstones, clear the arrays, discard the executor, rebuild

The comment explains why it rebuilds rather than reuses:

5.8 “Tombstone” messages

A new concept appeared above: tombstone. It is a control-signal message meaning “please remove this message from the UI and the transcript.”

yield { type: 'tombstone' as const, message: msg }

Why is it needed? The comment explains:

The scenario: when a streaming request fails, the model has already emitted part of its content, and the UI has already displayed it. That content cannot stay — it is incomplete and its signatures are invalid. So a tombstone is sent to retract it.

This design matters for a streaming UI: you have already painted something on the screen, and now you need a “retract” mechanism. And the retraction has to apply to both the UI and the record on disk.

5.9 Final processing of results

After a tool finishes, its result goes through two more processing steps before it is returned to the model:

① Spilling oversized results to disk

Every tool declares maxResultSizeChars. A result over the limit is written to disk, and what the model receives is “a preview of the first 2000 bytes + the file path.” See Section 6.2 for details.

② Serialization

mapToolResultToToolResultBlockParam(content: Output, toolUseID: string): ToolResultBlockParam

Each tool decides for itself “how my output should become text for the model.” For instance, the Read tool adds line numbers, and the Bash tool marks standard output and standard error separately.

Note that the Tool interface also has a method dedicated to transcript search:

/**
 * Flattened text of what renderToolResultMessage shows IN TRANSCRIPT MODE.
 * For transcript search indexing: the index counts occurrences in this string,
 * the highlight overlay scans the actual screen buffer. For count ≡ highlight,
 * this must return the text that ends up visible — not the model-facing
 * serialization from mapToolResultToToolResultBlockParam.
 *
 * Phantoms are not fine — text that's claimed here but doesn't render is a
 * count≠highlight bug.
 */
extractSearchText?(out: Output): string

In other words: this method returns a flattened version of “the text actually rendered in transcript mode.” It serves the search index: the index counts occurrences in this string, while the highlight overlay scans the real screen buffer. For the “count” and the “highlights” to be equal, this must return the text that is ultimately visible — not the serialization meant for the model. … Phantom text is not acceptable — text claimed here that does not actually render is a “count ≠ highlight” bug.