3 · The Agent Main Loop ★

query.ts, 1,730 lines. This is the single most important file in the whole system.

3.1 The skeleton of the loop

Start by peeling out the outermost structure, with every detail stripped away:

async function* queryLoop(params, consumedCommandUuids) {
  // —— Immutable parameters; never reassigned for the life of the loop ——
  const { systemPrompt, userContext, systemContext, canUseTool,
          fallbackModel, querySource, maxTurns, skipCacheWrite } = params

  // —— Mutable cross-iteration state, gathered into one struct ——
  let state: State = { messages: params.messages, ... }

  // —— One-time setup ——
  const config = buildQueryConfig()               // snapshot the environment and feature flags
  using pendingMemoryPrefetch = startRelevantMemoryPrefetch(...)  // memory prefetch

  while (true) {
    // 1. Destructure what this iteration needs out of state
    // 2. The five-tier context management pipeline   → Chapter 6
    // 3. Call the model (streaming)
    //    └─ execute tools while streaming            → Chapter 5
    // 4. Error recovery decisions → may continue back to the top of the loop
    // 5. No tool calls → return (done)
    // 6. Execute the remaining tools                  → Chapter 5
    // 7. Collect attachments, process queued messages
    // 8. state = {...new state}; on to the next iteration
  }
}

(using is JavaScript’s newer “explicit resource management” syntax: no matter which path the function exits through — normal return, thrown exception, closed from outside — the resource gets cleaned up. Generator functions have many exit paths, and missing any one of them means a resource leak.)

3.2 State: centralizing cross-iteration state

type State = {
  messages: Message[]                    // the current full message history
  toolUseContext: ToolUseContext         // the context object tool execution needs

  // —— Recovery bookkeeping ——
  autoCompactTracking: AutoCompactTrackingState | undefined
  maxOutputTokensRecoveryCount: number   // how many times output truncation has been retried
  hasAttemptedReactiveCompact: boolean   // whether reactive compaction already ran this turn (idempotency guard)
  maxOutputTokensOverride: number | undefined  // whether the output cap has already been escalated
  stopHookActive: boolean | undefined
  pendingToolUseSummary: Promise<ToolUseSummaryMessage | null> | undefined
  turnCount: number

  transition: Continue | undefined       // ★ "why" the previous iteration continued
}

claude-code/src/query.ts

A comment in the source explains why it is centralized:

3.3 transition: a field that exists purely for testability

transition takes part in no business logic. Its sole purpose is to record “why the previous loop iteration continued.” The comment says so directly:

3.4 The seven transition edges, one by one

① next_turn — normal progress

const next: State = {
  messages: [...messagesForQuery, ...assistantMessages, ...toolResults],
  toolUseContext: toolUseContextWithQueryTracking,
  autoCompactTracking: tracking,
  turnCount: nextTurnCount,
  maxOutputTokensRecoveryCount: 0,      // ★ reset
  hasAttemptedReactiveCompact: false,   // ★ reset
  pendingToolUseSummary: nextPendingToolUseSummary,
  maxOutputTokensOverride: undefined,   // ★ reset
  stopHookActive,
  transition: { reason: 'next_turn' },
}
state = next

Note that this is the only path that resets the recovery counters. None of the six that follow do. That rule is the heart of the defense against infinite loops.

② collapse_drain_retry — context too long; drain the collapse first

if (isWithheld413) {
  if (feature('CONTEXT_COLLAPSE') && contextCollapse &&
      state.transition?.reason !== 'collapse_drain_retry') {   // ★ only try if the last iteration wasn't this path
    const drained = contextCollapse.recoverFromOverflow(messagesForQuery, querySource)
    if (drained.committed > 0) {                                // something was actually drained
      state = { messages: drained.messages, ...,
                transition: { reason: 'collapse_drain_retry', committed: drained.committed } }
      continue
    }
  }
}

The way it limits retries is interesting: instead of a boolean lock, it checks “was the previous iteration’s transition this very path?” If the last iteration already drained once and this one is still a 413, draining is not going to solve the problem, so skip straight to the next tier.

③ reactive_compact_retry — reactive full summarization

if ((isWithheld413 || isWithheldMedia) && reactiveCompact) {
  const compacted = await reactiveCompact.tryReactiveCompact({
    hasAttempted: hasAttemptedReactiveCompact,   // ★ the idempotency guard is passed in
    querySource, aborted: ..., messages: messagesForQuery,
    cacheSafeParams: { systemPrompt, userContext, systemContext,
                       toolUseContext, forkContextMessages: messagesForQuery },
  })
  if (compacted) {
    const postCompactMessages = buildPostCompactMessages(compacted)
    for (const msg of postCompactMessages) yield msg
    state = { messages: postCompactMessages, ...,
              hasAttemptedReactiveCompact: true,     // ★ lock it
              transition: { reason: 'reactive_compact_retry' } }
    continue
  }
  // Recovery failed — emit the withheld error and finish
  yield lastMessage
  void executeStopFailureHooks(lastMessage, toolUseContext)
  return { reason: isWithheldMedia ? 'image_error' : 'prompt_too_long' }
}

Note cacheSafeParams — compaction itself makes a model call, and that call reuses the current session’s cache prefix, so the system prompt and the other parameters must be passed through unchanged. Chapter 6 goes into detail.

④ max_output_tokens_escalate — a one-time bump of the output cap

const capEnabled = getFeatureValue_CACHED_MAY_BE_STALE('tengu_otk_slot_v1', false)
if (capEnabled &&
    maxOutputTokensOverride === undefined &&         // ★ hasn't been escalated yet
    !process.env.CLAUDE_CODE_MAX_OUTPUT_TOKENS) {    // ★ the user hasn't set it manually
  logEvent('tengu_max_tokens_escalate', { escalatedTo: ESCALATED_MAX_TOKENS })
  state = { ..., maxOutputTokensOverride: ESCALATED_MAX_TOKENS,
            transition: { reason: 'max_output_tokens_escalate' } }
  continue
}

The logic: the default output cap is 8,000 tokens (to control cost). If the output gets truncated, first resend the request unchanged, raising only the cap to 64,000 — no extra prompt message, nothing to disturb the model’s train of thought. This step happens at most once per turn.

⑤ max_output_tokens_recovery — multi-round continuation

if (maxOutputTokensRecoveryCount < MAX_OUTPUT_TOKENS_RECOVERY_LIMIT) {   // limit is 3
  const recoveryMessage = createUserMessage({
    content:
      `Output token limit hit. Resume directly — no apology, no recap ` +
      `of what you were doing. Pick up mid-thought if that is where the ` +
      `cut happened. Break remaining work into smaller pieces.`,
    isMeta: true,        // ★ sent to the model only; not shown to the user
  })
  state = { messages: [...messagesForQuery, ...assistantMessages, recoveryMessage],
            maxOutputTokensRecoveryCount: maxOutputTokensRecoveryCount + 1,
            maxOutputTokensOverride: undefined,     // clear the escalation flag so it can escalate again next time
            transition: { reason: 'max_output_tokens_recovery',
                          attempt: maxOutputTokensRecoveryCount + 1 } }
  continue
}
// All 3 attempts used up — emit the withheld error
yield lastMessage

Each of the three sentences in that continuation instruction solves a specific problem:

⑥ stop_hook_blocking — a pre-finish check fails

const stopHookResult = yield* handleStopHooks(...)

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

if (stopHookResult.blockingErrors.length > 0) {
  state = {
    messages: [...messagesForQuery, ...assistantMessages, ...stopHookResult.blockingErrors],
    maxOutputTokensRecoveryCount: 0,
    // ★★★ This line is where the most important comment in the whole book lives
    hasAttemptedReactiveCompact,     // Preserve it! Do NOT reset!
    stopHookActive: true,
    transition: { reason: 'stop_hook_blocking' },
  }
  continue
}

⑦ token_budget_continuation — budget not exhausted; keep digging

if (feature('TOKEN_BUDGET')) {
  const decision = checkTokenBudget(budgetTracker!, toolUseContext.agentId,
                                    getCurrentTurnTokenBudget(), getTurnOutputTokens())
  if (decision.action === 'continue') {
    incrementBudgetContinuationCount()
    state = { messages: [...messagesForQuery, ...assistantMessages,
                createUserMessage({ content: decision.nudgeMessage, isMeta: true })],
              transition: { reason: 'token_budget_continuation' } }
    continue
  }
  if (decision.completionEvent?.diminishingReturns) {
    logForDebugging(`Token budget early stop: diminishing returns at ${...}%`)
  }
}

This mechanism runs in the opposite direction: not “prevent using too much,” but “the user explicitly gave a budget, so use it fully.” And it has “diminishing returns” detection — if continuing to dig is no longer producing anything new, it stops early instead of burning through the budget.

3.5 The error-withholding mechanism

Inside the streaming loop, three kinds of recoverable error are never emitted to the external caller:

let withheld = false                      // withheld = held back

if (feature('CONTEXT_COLLAPSE')) {
  if (contextCollapse?.isWithheldPromptTooLong(message, isPromptTooLongMessage, querySource))
    withheld = true
}
if (reactiveCompact?.isWithheldPromptTooLong(message))          withheld = true
if (mediaRecoveryEnabled &&
    reactiveCompact?.isWithheldMediaSizeError(message))          withheld = true
if (isWithheldMaxOutputTokens(message))                          withheld = true

if (!withheld) { yield yieldMessage }     // only messages that weren't withheld get emitted

// ★ But withheld or not, it goes into the internal array so the recovery logic below can find it
if (message.type === 'assistant') assistantMessages.push(message)

Only when every recovery option is exhausted is it emitted: yield lastMessage.

3.6 Interrupt handling

This is the part that home-grown agents most often miss, and the part most likely to blow up in production.

The shape of the problem

The fix

if (toolUseContext.abortController.signal.aborted) {
  if (streamingToolExecutor) {
    // Streaming executor in use: consume getRemainingResults()
    // It generates synthetic (fabricated) results for tools that are "queued" or "executing"
    for await (const update of streamingToolExecutor.getRemainingResults()) {
      if (update.message) yield update.message
    }
  } else {
    // No streaming executor: fabricate a fallback result marked as an error for every tool_use
    yield* yieldMissingToolResultBlocks(assistantMessages, 'Interrupted by user')
  }
  ...
  // Interruption message: skip it if this is a "submit interrupt" (caused by the user sending a new message),
  // because the user message that follows immediately explains the situation on its own
  if (toolUseContext.abortController.signal.reason !== 'interrupt') {
    yield createUserInterruptionMessage({ toolUse: false })
  }
  return { reason: 'aborted_streaming' }
}

That fallback function is short, but it is the safety net for the entire system:

function* yieldMissingToolResultBlocks(assistantMessages, errorMessage) {
  for (const assistantMessage of assistantMessages) {
    const toolUseBlocks = assistantMessage.message.content
        .filter(content => content.type === 'tool_use')
    for (const toolUse of toolUseBlocks) {
      yield createUserMessage({
        content: [{ type:'tool_result', content: errorMessage,
                    is_error: true,
                    tool_use_id: toolUse.id }],      // ★ the id must match
        toolUseResult: errorMessage,
        sourceToolAssistantUUID: assistantMessage.uuid,
      })
    }
  }
}

It is called from four places: on user interrupt, on switching to the fallback model, on falling back after a streaming request fails, and in the outermost exception handler.

3.7 Model fallback: three actions

When the primary model is overloaded (the server reports insufficient capacity), the loop switches to the fallback model. Claude Code does three things:

catch (innerError) {
  if (innerError instanceof FallbackTriggeredError && fallbackModel) {
    currentModel = fallbackModel
    attemptWithFallback = true

    // Action 1: fill in synthetic results for every tool call already issued
    yield* yieldMissingToolResultBlocks(assistantMessages, 'Model fallback triggered')
    assistantMessages.length = 0
    toolResults.length = 0
    toolUseBlocks.length = 0
    needsFollowUp = false

    // Action 2: discard the pending results in the streaming executor and build a fresh one
    //           so orphaned results carrying old tool_use_ids don't leak into the retried request
    if (streamingToolExecutor) {
      streamingToolExecutor.discard()
      streamingToolExecutor = new StreamingToolExecutor(...)
    }

    toolUseContext.options.mainLoopModel = fallbackModel

    // Action 3: ★ strip thinking-block signatures
    if (process.env.USER_TYPE === 'ant') {
      messagesForQuery = stripSignatureBlocks(messagesForQuery)
    }
    ...
    yield createSystemMessage(
      `Switched to ${renderModelName(innerError.fallbackModel)} due to high demand for ...`,
      'warning')
    continue
  }
  throw innerError
}

The comment on the third action:

3.8 The three laws of thinking blocks

Near the top of the file is a comment written like a spellbook, but its content is a set of real hard constraints:

Rule 3 directly constrains every context compaction implementation in Chapter 6: compaction, truncation, and replay — if any one of them cuts through the middle of a “thinking-block trajectory,” the API rejects the entire request.

That means you cannot simply say “keep the last 6 messages and compact everything before them” — if message 7 is a thinking block and message 6 is its corresponding tool result, you have chopped a complete trajectory in half. The boundary of the protected window must fall in a gap between trajectories.

3.9 Other mechanisms in the loop

Query chain tracing

const queryTracking = toolUseContext.queryTracking
  ? { chainId: toolUseContext.queryTracking.chainId,
      depth:   toolUseContext.queryTracking.depth + 1 }   // subagent depth +1
  : { chainId: deps.uuid(), depth: 0 }                    // top level: start a new chain

Every model call carries a “chain ID + depth.” The main agent is depth 0, a subagent it spawns is depth 1, and so on. Every telemetry event carries these two fields — so when analyzing the data, every model call triggered by a single user request (including all the subagents’) can be strung together into a tree.

Queued messages: mid-turn injection

const sleepRan = toolUseBlocks.some(b => b.name === SLEEP_TOOL_NAME)
const isMainThread = querySource.startsWith('repl_main_thread') || querySource === 'sdk'
const currentAgentId = toolUseContext.agentId

const queuedCommandsSnapshot = getCommandsByMaxPriority(sleepRan ? 'later' : 'next')
  .filter(cmd => {
    if (isSlashCommand(cmd)) return false            // slash commands can't be injected mid-turn
    if (isMainThread) return cmd.agentId === undefined
    // ★ Subagents only take task notifications addressed to them; they never get user prompts
    return cmd.mode === 'task-notification' && cmd.agentId === currentAgentId
  })

This handles the case where the user sends another message while the model is thinking, or a background task finishes and needs to notify the model.

The key isolation rule is in the comment:

Tool summaries: generated asynchronously by a cheap small model

if (config.gates.emitToolUseSummaries && toolUseBlocks.length > 0 &&
    !toolUseContext.abortController.signal.aborted &&
    !toolUseContext.agentId) {          // ★ subagents don't generate them (they're not shown in the UI)
  ...
  // Kick off summary generation but don't wait for it — the result is passed to the next iteration
  nextPendingToolUseSummary = generateToolUseSummary({...})
    .then(summary => summary ? createToolUseSummaryMessage(summary, toolUseIds) : null)
    .catch(() => null)
}

This summary uses Haiku (a smaller, cheaper model) and takes about 1 second. It is kicked off in one iteration and consumed in the next:

// At the top of the next iteration
if (pendingToolUseSummary) {
  const summary = await pendingToolUseSummary
  if (summary) yield summary
}

Comment: “Yield tool use summary from previous turn — haiku (~1s) resolved during model streaming (5-30s)” (emit the previous turn’s tool summary — Haiku takes about 1 second, and it finishes during the 5 to 30 seconds the model spends streaming).

How the memory prefetch is consumed

if (pendingMemoryPrefetch &&
    pendingMemoryPrefetch.settledAt !== null &&        // ★ consume only once settled
    pendingMemoryPrefetch.consumedOnIteration === -1) { // ★ and not yet consumed
  const memoryAttachments = filterDuplicateMemoryAttachments(
    await pendingMemoryPrefetch.promise,
    toolUseContext.readFileState,      // ★ filter by already-read file state to avoid duplicate injection
  )
  for (const memAttachment of memoryAttachments) { ... }
  pendingMemoryPrefetch.consumedOnIteration = turnCount - 1
}

Comment: “only if settled and not already consumed on an earlier iteration. If not settled yet, skip (zero-wait) and retry next iteration — the prefetch gets as many chances as there are loop iterations before the turn ends.”

In other words: consume it only if it has settled and was not already consumed on an earlier iteration. If it has not settled yet, skip it (zero wait) and try again next iteration — the prefetch gets as many chances as there are iterations before the turn ends.

3.10 Every exit point of the loop

Ten named exit points. Each one can be counted separately in data analysis — the foundation of observability (Chapter 12).