What it is

The agent loop runs until the model stops asking for tools — but "the model emitted no tool call" is not the same as "the work is done." This page covers the three-gate decision that sits at the bottom of queryLoop (claude-code/src/query.ts:241) and decides, each time the model falls silent, whether the turn truly ends or the loop runs one more time.

Gate one is Stop hooks: user-configured rules that run after the model finishes and can either hard-veto termination or send the work back for rework (claude-code/src/query.ts:1267). Gate two is a token budget: a self-pacing meter that nudges the model to keep working until it has spent roughly 90% of an allocated output-token target, stopping earlier only if it detects diminishing returns (claude-code/src/query/tokenBudget.ts:45-93). Threading through both is a state transition label — a field on the loop's mutable State that records why the previous iteration continued (claude-code/src/query.ts:216), so the reason for every extra lap is auditable rather than implicit in the message stream.

How it works

Trace the bottom of one loop iteration. After the streaming API call (claude-code/src/query.ts:659) returns an assistant message that requests no further tools, control reaches handleStopHooks (claude-code/src/query.ts:1267) — stop conditions are evaluated after streaming completes but before any token-budget decision.

handleStopHooks runs the configured Stop hooks, and, when the session is a teammate, the TaskCompleted and TeammateIdle hooks in sequence (claude-code/src/query/stopHooks.ts:180-189, claude-code/src/query/stopHooks.ts:335-453). Their results split into two distinct outcomes:

• If any hook asks to prevent continuation, the handler short-circuits and returns { preventContinuation: true } (claude-code/src/query/stopHooks.ts:269-270, claude-code/src/query/stopHooks.ts:326-327); the loop returns immediately with reason: 'stop_hook_prevented' (claude-code/src/query.ts:1278). This is the hard "go home" — the turn ends.
• If a hook instead emits blocking errors, those are injected back into the conversation as messages, stopHookActive is set to true, the transition is labelled 'stop_hook_blocking', and the loop continues so the model must address the complaint (claude-code/src/query.ts:1282-1305). This is "redo it," not "stop."

Only if stop hooks neither veto nor block does control reach checkTokenBudget (claude-code/src/query.ts:1309). The budget machinery is set up once per session: a BudgetTracker holding continuationCount, lastDeltaTokens, lastGlobalTurnTokens, and startedAt is created at loop entry (claude-code/src/query.ts:280, claude-code/src/query/tokenBudget.ts:6-11, claude-code/src/query/tokenBudget.ts:13-20). What it measures is the model's own output this turn: at turn start snapshotOutputTokensForTurn records outputTokensAtTurnStart and the turn's budget (claude-code/src/bootstrap/state.ts:724, claude-code/src/bootstrap/state.ts:733-736), and each iteration getTurnOutputTokens() returns the delta above that baseline (claude-code/src/bootstrap/state.ts:726-727).

checkTokenBudget then decides (claude-code/src/query/tokenBudget.ts:45-93):

• Subagents are exempt. If an agentId is set (or the budget is null/non-positive), it returns stop immediately — only the main session paces itself (claude-code/src/query/tokenBudget.ts:51-52).
• Diminishing returns. With thresholds COMPLETION_THRESHOLD = 0.9 and DIMINISHING_THRESHOLD = 500 (claude-code/src/query/tokenBudget.ts:3-4), it computes isDiminishing — true when there have already been 3+ continuations and both the delta since the last check and the previous delta are under 500 tokens (claude-code/src/query/tokenBudget.ts:59-62). That is the "several empty nets" case: still pushing, producing almost nothing.
• Continue. If not diminishing and the turn's output is still under 90% of the budget, it returns action: 'continue' with a nudgeMessage, incrementing continuationCount and recording the deltas (claude-code/src/query/tokenBudget.ts:64-76). The nudge text is Stopped at X% of token target (Y / Z). Keep working — do not summarize. (claude-code/src/utils/tokenBudget.ts:66-72) — note it explicitly forbids wrapping up early with a summary.

On a continue decision the loop increments the session continuation counter (claude-code/src/bootstrap/state.ts:741-742), appends the nudge as a meta user message, labels the transition 'token_budget_continuation', and loops back (claude-code/src/query.ts:1316-1340). Otherwise the budget returns stop and the loop ends with reason: 'completed' (claude-code/src/query.ts:1357). (The ordinary tool-using path is different: when the model did request tools, the loop executes them and re-laps with transition 'next_turn' — claude-code/src/query.ts:1384, claude-code/src/query.ts:1725 — without consulting stop conditions at all.)

Why it matters

These three gates separate three things a naïve loop conflates: the model thinks it's finished, policy says it may finish, and the budget says it's worth finishing.

The token budget exists because models tend to declare victory and summarize too early. By measuring output tokens produced this turn against a target and injecting a "keep working — do not summarize" nudge until ~90% is spent (claude-code/src/query/tokenBudget.ts:64-76, claude-code/src/utils/tokenBudget.ts:66-72), the harness converts an allocated effort into actually-delivered work. The diminishing-returns escape hatch (claude-code/src/query/tokenBudget.ts:59-62) keeps that from becoming wasteful: once the model is clearly spinning — three-plus continuations yielding sub-500-token bursts — the loop stops even with budget left, rather than burning the remainder on empty laps.

Stop hooks matter because they give external policy two genuinely different verbs. preventContinuation is a clean veto that ends the turn (claude-code/src/query.ts:1278); blocking errors are a bounce-back that re-runs the model with the objection in context and stopHookActive: true (claude-code/src/query.ts:1282-1305). The stopHookActive flag and the preserved reactive-compact guard in that branch are deliberate loop-safety: the source comment there records that naïvely resetting state on a stop-hook bounce produced an infinite compact→error→bounce cycle.

The transition label is the cheap part that makes the rest legible. Because every continuation site writes a reason — 'stop_hook_blocking', 'token_budget_continuation', 'next_turn' (claude-code/src/query.ts:1302, claude-code/src/query.ts:1338, claude-code/src/query.ts:1725) — onto the State (claude-code/src/query.ts:216), the why of each lap is first-class data, which (per the field's own comment) lets tests assert that a recovery path fired without inspecting message contents.

Read the source

• The loop and its mutable State.transition field: claude-code/src/query.ts:241, claude-code/src/query.ts:216.
• Stop conditions, evaluated after streaming, before budget: claude-code/src/query.ts:1267; the two outcomes — veto (claude-code/src/query.ts:1278, claude-code/src/query/stopHooks.ts:326-327) and bounce-back (claude-code/src/query.ts:1282-1305).
• The hook types that run, in order: claude-code/src/query/stopHooks.ts:180-189, claude-code/src/query/stopHooks.ts:335-453; the preventContinuation signal: claude-code/src/query/stopHooks.ts:269-270.
• The budget tracker, baseline, and delta: claude-code/src/query.ts:280, claude-code/src/query/tokenBudget.ts:6-11, claude-code/src/bootstrap/state.ts:733-736, claude-code/src/bootstrap/state.ts:726-727.
• The continue/stop decision, 90% threshold, and diminishing returns: claude-code/src/query/tokenBudget.ts:45-93, claude-code/src/query/tokenBudget.ts:64-76, claude-code/src/query/tokenBudget.ts:59-62, claude-code/src/query/tokenBudget.ts:3-4.
• The nudge message and its injection + transition: claude-code/src/utils/tokenBudget.ts:66-72, claude-code/src/query.ts:1316-1340.