Deep Dive: Claude Code Agentic Loop

// src/query.ts:204
type State = {
  messages: Message[]                        // 跨迭代的消息历史
  toolUseContext: ToolUseContext              // 工具上下文（可变）
  autoCompactTracking: AutoCompactTrackingState | undefined
  maxOutputTokensRecoveryCount: number       // max_output_tokens 重试计数
  hasAttemptedReactiveCompact: boolean       // 是否已尝试过 reactive compact
  maxOutputTokensOverride: number | undefined
  pendingToolUseSummary: Promise<...> | undefined
  stopHookActive: boolean | undefined
  turnCount: number                          // 当前 turn 计数
  transition: Continue | undefined           // 上一轮为何继续
}

// src/query.ts:829-835
const msgToolUseBlocks = message.message.content.filter(
  content => content.type === 'tool_use',
) as ToolUseBlock[]
if (msgToolUseBlocks.length > 0) {
  toolUseBlocks.push(...msgToolUseBlocks)
  needsFollowUp = true   // ← 这是循环是否继续的唯一标志
}

// src/services/tools/StreamingToolExecutor.ts:40
export class StreamingToolExecutor {
  private tools: TrackedTool[] = []
  private siblingAbortController: AbortController  // 兄弟工具错误时联动中止
  private discarded = false

  addTool(block, assistantMessage): void        // 注册工具，立即尝试执行
  *getCompletedResults(): Generator<...>        // 取已完成的结果（非阻塞）
  async *getRemainingResults(): AsyncGenerator<...>  // 等待所有剩余工具完成
}

// 在流式循环内，每收到一个 assistant chunk 就：
for (const toolBlock of msgToolUseBlocks) {
  streamingToolExecutor.addTool(toolBlock, message)  // 注册并可能立即开始执行
}
// 然后取已经完成的结果
for (const result of streamingToolExecutor.getCompletedResults()) {
  yield result.message  // 立即输出工具结果
  toolResults.push(...)
}

// src/services/tools/toolOrchestration.ts:152
async function* runToolsConcurrently(toolUseMessages, ...) {
  yield* all(
    toolUseMessages.map(async function* (toolUse) {
      yield* runToolUse(toolUse, ...)
    }),
    getMaxToolUseConcurrency(),  // 默认 10，可通过 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY 调整
  )
}

// src/services/tools/toolOrchestration.ts:118
async function* runToolsSerially(toolUseMessages, ...) {
  let currentContext = toolUseContext
  for (const toolUse of toolUseMessages) {
    for await (const update of runToolUse(toolUse, ...)) {
      if (update.contextModifier) {
        currentContext = update.contextModifier.modifyContext(currentContext)
      }
      yield { message: update.message, newContext: currentContext }
    }
    markToolUseAsComplete(toolUseContext, toolUse.id)
  }
}

private canExecuteTool(isConcurrencySafe: boolean): boolean {
  const executingTools = this.tools.filter(t => t.status === 'executing')
  return (
    executingTools.length === 0 ||
    (isConcurrencySafe && executingTools.every(t => t.isConcurrencySafe))
  )
}

// src/services/tools/StreamingToolExecutor.ts:357-363
if (tool.block.name === BASH_TOOL_NAME) {
  this.hasErrored = true
  this.erroredToolDescription = this.getToolDescription(tool)
  this.siblingAbortController.abort('sibling_error')  // 杀死所有并发 Bash
}

// src/query.ts:1062
if (!needsFollowUp) {
  // ... 恢复检查 ...
  // 进入 stop hooks
  // 然后检查 token budget
  return { reason: 'completed' }
}

// src/query.ts:1705
if (maxTurns && nextTurnCount > maxTurns) {
  yield createAttachmentMessage({
    type: 'max_turns_reached',
    maxTurns,
    turnCount: nextTurnCount,
  })
  return { reason: 'max_turns', turnCount: nextTurnCount }
}

const stopHookResult = yield* handleStopHooks(...)

if (stopHookResult.preventContinuation) {
  return { reason: 'stop_hook_prevented' }
}

if (stopHookResult.blockingErrors.length > 0) {
  // 注入 blocking error 作为 meta 消息，continue 到下一轮
  state = { ..., transition: { reason: 'stop_hook_blocking' }, stopHookActive: true }
  continue
}

// src/query.ts:1308
if (feature('TOKEN_BUDGET')) {
  const decision = checkTokenBudget(budgetTracker!, ...)
  if (decision.action === 'continue') {
    // 注入 nudge message，继续循环
    state = { ..., transition: { reason: 'token_budget_continuation' } }
    continue
  }
  // action === 'stop' → fall through to return { reason: 'completed' }
}

// src/query.ts:628-648
if (!compactionResult && ...) {
  const { isAtBlockingLimit } = calculateTokenWarningState(...)
  if (isAtBlockingLimit) {
    yield createAssistantAPIErrorMessage({ content: PROMPT_TOO_LONG_ERROR_MESSAGE })
    return { reason: 'blocking_limit' }
  }
}

// src/query.ts:1519
if (shouldPreventContinuation) {
  return { reason: 'hook_stopped' }
}

// src/query.ts:799-822
let withheld = false
if (contextCollapse?.isWithheldPromptTooLong(message, ...)) { withheld = true }
if (reactiveCompact?.isWithheldPromptTooLong(message)) { withheld = true }
if (isWithheldMaxOutputTokens(message)) { withheld = true }
if (!withheld) { yield yieldMessage }  // 只有非暂扣消息才输出

// src/query.ts:893-953
} catch (innerError) {
  if (innerError instanceof FallbackTriggeredError && fallbackModel) {
    currentModel = fallbackModel
    attemptWithFallback = true
    // 生成合成 tool_result 错误，清空 assistantMessages
    // 创建新的 StreamingToolExecutor
    continue  // 重试 while(attemptWithFallback) 循环
  }
}

// src/query.ts:712-740
if (streamingFallbackOccured) {
  // 为已产生的 assistant 消息生成 tombstone（避免签名不一致）
  for (const msg of assistantMessages) {
    yield { type: 'tombstone', message: msg }
  }
  // 清空所有状态
  assistantMessages.length = 0
  toolResults.length = 0
  toolUseBlocks.length = 0
  // 丢弃旧 executor，创建新 executor
  streamingToolExecutor.discard()
  streamingToolExecutor = new StreamingToolExecutor(...)
}