中军帐

The turn loop is the harness's heartbeat: a single while (true) inside the generator queryLoop (claude-code/src/query.ts:307). One iteration is one model request plus the batch of tools that request asked for. Per iteration the loop (1) shrinks the conversation until it fits, (2) streams one model response, and (3) either terminates — the model issued no tool calls — or executes the tools and feeds their results into a fresh iteration. There is no recursion and no scheduler: the loop "recurses" by rebuilding a mutable State struct (claude-code/src/query.ts:204-217) and continuing.

Two thin layers wrap it. query() delegates straight to queryLoop and, only when the loop returns normally, marks consumed slash-commands as completed (claude-code/src/query.ts:219-239). Above that, QueryEngine.submitMessage is the outer driver that seeds the loop and re-emits its stream as SDK messages (claude-code/src/QueryEngine.ts:209-686); ask() constructs the engine and yields from it (claude-code/src/QueryEngine.ts:1249-1291).

How it works

Seeding. submitMessage runs processUserInput to expand slash commands and attachments and pushes the results into this.mutableMessages (claude-code/src/QueryEngine.ts:410-434) — the durable, cross-turn conversation store on the engine (claude-code/src/QueryEngine.ts:184-207) — then drives query() in a for await loop (claude-code/src/QueryEngine.ts:209-686). Before its first iteration, queryLoop snapshots the immutable params, injected deps, config, and starts a once-per-turn memory prefetch (claude-code/src/query.ts:241-305). All I/O flows through the QueryDeps seam — callModel, microcompact, autocompact, uuid — with productionDeps() wiring the real implementations (claude-code/src/query/deps.ts:21-40); env/statsig gates are snapshotted exactly once into QueryConfig (claude-code/src/query/config.ts:15-46). A taskBudgetRemaining counter lives as a loop-local, decremented across compaction boundaries rather than stored on State (claude-code/src/query.ts:291-292).

Top of each iteration: make it fit. The iteration destructures State (claude-code/src/query.ts:311-321) and yields a stream_request_start event (claude-code/src/query.ts:337). Then the compaction pipeline runs in a deliberately load-bearing order — tool-result budget, snip, microcompact, context-collapse, autocompact — each stage feeding what it freed to the next so a cheap stage can turn the expensive one into a no-op (claude-code/src/query.ts:379-468). A hard blocking-limit check can return {reason:'blocking_limit'} before any API call, but it is skipped whenever reactive compact or context collapse own overflow recovery: a synthetic pre-API error would starve both of the real prompt-too-long they need to react to (claude-code/src/query.ts:592-648).

The model call. deps.callModel streams inside an inner while (attemptWithFallback) wrapper (claude-code/src/query.ts:654-708). Three things happen per streamed message. First, recoverable errors — prompt-too-long, media-size, max_output_tokens — are withheld from the yield and surfaced only if recovery later exhausts (claude-code/src/query.ts:799-825); yielding early would leak an intermediate error to SDK callers that terminate the session on any error field (claude-code/src/query.ts:166-179). Second, assistant messages are accumulated and any tool_use block sets needsFollowUp = true (claude-code/src/query.ts:826-845). Third, if the streamingToolExecution gate is on (claude-code/src/query.ts:561-568), those tools start executing while the model is still streaming (claude-code/src/query.ts:837-844). A FallbackTriggeredError swaps in the fallback model and retries the whole request (claude-code/src/query.ts:894-951); any other throw yields an API-error message and returns {reason:'model_error'} (claude-code/src/query.ts:955-997). An abort during streaming first emits synthetic tool_result blocks so no tool_use is left unmatched, then returns aborted_streaming (claude-code/src/query.ts:1015-1052).

The branch. needsFollowUp is the sole loop-exit signal — derived from tool_use blocks seen in the stream, not from stop_reason, which the code comments is "unreliable — it's not always set correctly" (claude-code/src/query.ts:553-558).

No follow-up (claude-code/src/query.ts:1062): withheld errors get their recovery here. A withheld 413 tries the context-collapse drain first (cheap, keeps granular history), then reactive compact (full summary), each continuing the loop with a rebuilt State (claude-code/src/query.ts:1085-1183). A withheld max_output_tokens escalates the output cap and retries, up to a recovery limit (claude-code/src/query.ts:1188-1256). Then stop hooks run: handleStopHooks returns {blockingErrors, preventContinuation} (claude-code/src/query/stopHooks.ts:60-81) and can end the turn outright or inject blocking-error messages and force another iteration — carefully preserving the reactive-compact guard, since resetting it here once caused an infinite compact→error→hook→compact spiral (claude-code/src/query.ts:1267-1306). If nothing intervenes, the loop returns {reason:'completed'} (claude-code/src/query.ts:1357).

Follow-up: tool results are drained from the streaming executor or executed as a batch via runTools (claude-code/src/query.ts:1366-1408); an async tool-use summary is kicked off without blocking the next API call (claude-code/src/query.ts:1469-1481); queued commands, prefetched memories, and skill discoveries are appended as attachment messages (claude-code/src/query.ts:1580-1628); maxTurns is enforced (claude-code/src/query.ts:1679-1712) — and enforced a second time on the aborted-during-tools exit (claude-code/src/query.ts:1506-1515). Finally the next State is built with messages = [...messagesForQuery, ...assistantMessages, ...toolResults] and control loops (claude-code/src/query.ts:1714-1728). Note the discipline: State is never field-mutated across iterations; every continue site rebuilds the entire struct, so forgetting a field there would silently reset it.

Back outside. submitMessage's for await switches on each yielded message type, records the transcript, and re-yields normalized SDK messages (claude-code/src/QueryEngine.ts:757-969). Assistant messages are persisted fire-and-forget because the streaming layer mutates the last message's usage on message_delta; awaiting the write would deadlock against the write queue's drain timer (claude-code/src/QueryEngine.ts:717-732). Two details are easy to miss. First, there are two independent turn counters: queryLoop's state.turnCount increments only on the follow-up path and drives maxTurns (claude-code/src/query.ts:1679-1712), while the engine's local turnCount increments on every yielded user message and feeds result.num_turns (claude-code/src/QueryEngine.ts:753-755). Second, the Terminal reason queryLoop returns is discarded by the for await; the SDK result subtype is instead derived from messages.findLast(assistant|user) via isResultSuccessful (claude-code/src/QueryEngine.ts:1058-1118). Fittingly, Terminal and Continue are empty stub interfaces not present in the leaked source — the reason codes are internal, structurally-typed bookkeeping (claude-code/src/query/transitions.ts:1-3).

Why it matters

Every other harness mechanism is a passenger on this loop. Compaction is a phase at the top of each iteration (claude-code/src/query.ts:379-468); hooks are a gate on the terminal path (claude-code/src/query.ts:1267-1306); memory and skills ride in as attachments before the next iteration (claude-code/src/query.ts:1580-1628); budgets and turn limits are checked at its continue/return sites (claude-code/src/query.ts:1679-1712). Understand this file and you have the map on which everything else is a landmark.

It also encodes four transferable harness-design lessons. Trust data over metadata: the loop continues on observed tool_use blocks, not the model-reported stop_reason (claude-code/src/query.ts:553-558). Rebuild state, don't mutate it: every loop-back site constructs a whole new State (claude-code/src/query.ts:1714-1728), making each transition auditable — down to a transition field that exists so tests can assert why the loop continued (claude-code/src/query.ts:204-217). Withhold what you might fix: recoverable errors stay out of the caller-visible stream until recovery is truly exhausted (claude-code/src/query.ts:799-825, claude-code/src/query.ts:166-179). And keep the seams injectable: the model call and both compactors enter through QueryDeps (claude-code/src/query/deps.ts:21-40), which is what makes a while (true) with a dozen exit paths testable at all.

Read the source

Start at the wrapper and descend:

1. ask() builds a QueryEngine and yields from submitMessage — claude-code/src/QueryEngine.ts:1249-1291.
2. submitMessage seeds the loop (input expansion at claude-code/src/QueryEngine.ts:410-434) and consumes it (claude-code/src/QueryEngine.ts:757-969); note the durable mutableMessages store (claude-code/src/QueryEngine.ts:184-207).
3. query() → queryLoop handoff — claude-code/src/query.ts:219-239; loop setup at claude-code/src/query.ts:241-305.
4. The while (true) itself — claude-code/src/query.ts:307 — then read one full iteration in order: compaction (claude-code/src/query.ts:379-468), preempt (claude-code/src/query.ts:592-648), model call (claude-code/src/query.ts:654-708), the withhold/collect stream body (claude-code/src/query.ts:799-845), the branch (claude-code/src/query.ts:1062 vs claude-code/src/query.ts:1366-1408), and the State rebuild (claude-code/src/query.ts:1714-1728).
5. Finish with the helpers: claude-code/src/query/deps.ts:21-40, claude-code/src/query/config.ts:15-46, claude-code/src/query/stopHooks.ts:60-81, and the telling stub claude-code/src/query/transitions.ts:1-3.