Tool Execution sequential/parallel

源码版本v0.73.1

executeToolCalls is the sub-flow inside runLoop's inner loop that handles tool calls in an assistant message. It splits the tool-call lifecycle into five stages: prepareToolCall (lookup + validate + beforeToolCall hook) → executePreparedToolCall (actually run tool.execute) → finalizeExecutedToolCall (afterToolCall hook override) → emitToolExecutionEnd → createToolResultMessage. Both sequential and parallel modes share these five stages; the only difference is scheduling order: sequential finishes one tool before starting the next, while parallel prepares serially and then runs Promise.all to execute + finalize concurrently.

Responsibilities

1. Mode dispatch: executeToolCalls checks config.toolExecution and whether any tool has executionMode === "sequential"; if either is true, it goes sequential. See packages/agent/src/agent-loop.ts:350-365.
2. Prepare stage: prepareToolCall finds the tool, prepareToolCallArguments handles legacy args, validateToolArguments validates, and the beforeToolCall hook can block. See packages/agent/src/agent-loop.ts:529-579.
3. Execute stage: executePreparedToolCall calls tool.execute(id, args, signal, onUpdate); partial results flow to the UI via tool_execution_update events; exceptions are converted into error results. See packages/agent/src/agent-loop.ts:581-616.
4. Finalize stage: finalizeExecutedToolCall calls the afterToolCall hook to override content/details/isError/terminate by field; if the hook itself throws, it's also converted into an error result. See packages/agent/src/agent-loop.ts:618-661.
5. Build result message: createToolResultMessage wraps the finalized result into a ToolResultMessage (role/toolCallId/content/details/isError/timestamp), to be pushed into context by the caller. See packages/agent/src/agent-loop.ts:680-690.

Design motivation

Why prepare serially and execute concurrently? Because the beforeToolCall hook usually does side-effectful work like auth, logging, or rate limiting, and concurrent triggering easily races (e.g. refreshing an OAuth token at the same time). Serial prepare keeps hooks running in order. Execute is concurrent because tools themselves (reading files, running bash, HTTP requests) are independent, and serial wastes wall-clock time.

Why does tool_execution_end fire in "completion order" while toolResult messages fire in "source order"? In parallel mode, after Promise.all, the loop builds each toolResultMessage in order, but emitToolExecutionEnd is called as soon as each tool finishes finalizing — the UI gets a result the moment a tool completes, without waiting for the whole batch. The toolResult message gets fed back to the LLM, so out-of-order would confuse the model; it's emitted in the toolCall order from the assistant message. This split — event stream by completion order, message stream by source order — keeps UI responses fast and the LLM context stable.

Why are there both immediate and prepared outcomes? Cases like tool-not-found, argument validation failure, or beforeToolCall block never reach the execute step; they return an error result directly. Wrapping both that and a normal execute result in the same FinalizedToolCallOutcome shape means downstream emitToolExecutionEnd/createToolResultMessage don't need to distinguish the two paths.

Key files

• packages/agent/src/agent-loop.ts:350-365 — executeToolCalls mode dispatch; if any tool declares sequential, the whole batch goes sequential.
• packages/agent/src/agent-loop.ts:372-422 — executeToolCallsSequential: for (const toolCall of toolCalls) walks the five stages one at a time.
• packages/agent/src/agent-loop.ts:424-483 — executeToolCallsParallel: first loops prepare/immediate dispatch, pushing pending executions into () => Promise closures, then Promise.all runs them concurrently.
• packages/agent/src/agent-loop.ts:511-513 — shouldTerminateToolBatch: the batch terminates only when all finalized calls set terminate: true; if any doesn't, it continues.
• packages/agent/src/agent-loop.ts:515-527 — prepareToolCallArguments: uses the tool's own prepareArguments for arg compatibility; returns the same object without copying.
• packages/agent/src/agent-loop.ts:529-579 — prepareToolCall: tool-table lookup, validation, beforeToolCall hook; returns a PreparedToolCall or ImmediateToolCallOutcome.
• packages/agent/src/agent-loop.ts:581-616 — executePreparedToolCall: calls tool.execute; partial results go through tool_execution_update; exceptions become errors.
• packages/agent/src/agent-loop.ts:618-661 — finalizeExecutedToolCall: calls afterToolCall; field-level override; hook throws also become errors.
• packages/agent/src/agent-loop.ts:680-690 — createToolResultMessage: wraps the finalized outcome into a ToolResultMessage.

Core loop of sequential mode — one tool finishes all five stages before the next:

// packages/agent/src/agent-loop.ts:383-416
for (const toolCall of toolCalls) {
  await emit({ type: "tool_execution_start", toolCallId: toolCall.id, toolName: toolCall.name, args: toolCall.arguments });
  const preparation = await prepareToolCall(currentContext, assistantMessage, toolCall, config, signal);
  let finalized: FinalizedToolCallOutcome;
  if (preparation.kind === "immediate") {
    finalized = { toolCall, result: preparation.result, isError: preparation.isError };
  } else {
    const executed = await executePreparedToolCall(preparation, signal, emit);
    finalized = await finalizeExecutedToolCall(currentContext, assistantMessage, preparation, executed, config, signal);
  }
  await emitToolExecutionEnd(finalized, emit);
  const toolResultMessage = createToolResultMessage(finalized);
  await emitToolResultMessage(toolResultMessage, emit);
  finalizedCalls.push(finalized);
  messages.push(toolResultMessage);
}

In parallel mode prepare is serial and execute is concurrent; event ordering is the key difference:

// packages/agent/src/agent-loop.ts:434-477
for (const toolCall of toolCalls) {
  await emit({ type: "tool_execution_start", ... });
  const preparation = await prepareToolCall(currentContext, assistantMessage, toolCall, config, signal);
  if (preparation.kind === "immediate") {
    const finalized = { toolCall, result: preparation.result, isError: preparation.isError } satisfies FinalizedToolCallOutcome;
    await emitToolExecutionEnd(finalized, emit);   // immediate fires end right away
    finalizedCalls.push(finalized);
    continue;
  }
  finalizedCalls.push(async () => {                 // deferred until Promise.all
    const executed = await executePreparedToolCall(preparation, signal, emit);
    const finalized = await finalizeExecutedToolCall(currentContext, assistantMessage, preparation, executed, config, signal);
    await emitToolExecutionEnd(finalized, emit);    // fires end as soon as finalize is done
    return finalized;
  });
}
const orderedFinalizedCalls = await Promise.all(finalizedCalls.map((entry) => typeof entry === "function" ? entry() : Promise.resolve(entry)));
// then build toolResultMessage in source order ...

Data flow

Timing for an assistant message with 3 tool calls in parallel mode:

Boundaries and failure

• Tool not found: prepareToolCall can't find toolCall.name in the tool table; it returns an immediate error result without throwing or breaking the batch. See packages/agent/src/agent-loop.ts:536-543.
• Argument validation failure: validateToolArguments throws are caught and turned into an immediate error result; the tool's tool_execution_end is still emitted. See packages/agent/src/agent-loop.ts:572-578.
• beforeToolCall block: when beforeToolCall returns { block: true, reason }, the tool becomes an error result, with reason written into the result content. See packages/agent/src/agent-loop.ts:558-565.
• execute throws: executePreparedToolCall catches the exception and returns an isError: true result; partial result events are awaited via Promise.all before returning. See packages/agent/src/agent-loop.ts:608-615.
• afterToolCall throws: finalizeExecutedToolCall catches hook exceptions and overrides with an error result; other tools' finalize are not affected. See packages/agent/src/agent-loop.ts:650-654.
• Batch termination: shouldTerminateToolBatch requires the whole batch to set terminate: true to return true; runLoop uses this to set hasMoreToolCalls=false and exit the inner loop. See packages/agent/src/agent-loop.ts:511-513 and packages/agent/src/agent-loop.ts:206-214.

Summary

Tool execution is split into five stages: prepare/execute/finalize/emitEnd/createToolResultMessage. Sequential runs the whole batch serially; parallel runs prepare serially and execute concurrently, with events in completion order and toolResults in source order. The beforeToolCall/afterToolCall hooks are invoked during prepare and finalize; any exception is turned into an error result rather than breaking the batch. For the hook shapes and AgentTool fields, see Type Contracts; for where the five stages are called inside runLoop's inner loop, see Double while Loop.