The previous ten posts examined permissions, hooks, tool scheduling, the state machine, streaming, error recovery, interrupts, and sub-agents one piece at a time. This final post adds no new mechanism. Its job is to assemble those pieces back into one complete agent loop.
Five ideas worth keeping
If you remember only five things from this series, make them these.
1. A loop runs autonomously—usually without a person in the middle
The user presses Enter once. The loop advances on its own. Ordinarily, the user does not need to direct every intermediate step. The loop pauses only when a tool needs permission, and the user can interrupt it at any time.
This is the essential difference between an agent and an ordinary chatbot. A chatbot stops after producing one answer. After a single user input, an agent can repeatedly call a model and tools until the task is complete.
2. A loop is a state machine, not merely a while statement
The core of the loop is not five lines of pseudocode. It is an explicit collection of states. At the end of every turn, the system records what should happen next. The following turn uses that state to choose the ordinary call path, retry path, compaction path, or recovery path.
That is why an error is not retried layer after layer inside one turn's try/catch. Control returns to the main loop, and a subsequent turn performs the recovery work. See Part 5: The QueryEngine Main Loop as a State Machine.
3. Errors become states that the loop can continue to process
A failed tool call is converted into a tool_result for the LLM. When the main loop itself needs to recover, that need becomes a transition for the next turn. Both cases follow the same principle: turn an error into state or data that the loop can continue to process, rather than allowing an exception to break the loop outright.
The loop is therefore more than an error handler waiting for something to go wrong. It is a recovery engine that actively attempts to repair progress. Only after internal recovery also fails does the final error reach the user. See Part 7: Retries and Eight Layers of Error Recovery.
4. Autonomous execution has three safeguards
Automatic execution does not mean an agent is uncontrollable. Three mechanisms let a person or the system regain control:
- Permission approval — before a risky tool runs, the loop pauses and waits for the user's decision.
- Interrupt — the user can stop a running loop at any time.
-
maxTurns— even without intervention, the loop stops when it reaches its turn limit.
They address three different moments: confirmation before execution, braking during execution, and an ultimate hard limit. Together, they constrain the autonomous loop.
5. The main agent and sub-agents reuse one loop
A sub-agent is not implemented with a separate loop. The main agent and every sub-agent invoke the same queryLoop code, run independently, and use agentId to distinguish their roles.
This reveals that the loop is not code written only for a chat window. It is Claude Code's general execution engine for letting AI advance a task autonomously. See Part 9: Sidechains, Sub-agents, and agentId Routing.
From a five-line skeleton to a complete system
Looking back across the series:
- Part 0: From the Chat Window to the Loop moved from the intuition of a chat window to a five-line loop skeleton.
-
Part 1: From Tool Declarations to Pre-Execution Approval through Part 4: From a Finished Answer to the Seven Meanings of
stop_reasonunpacked tool declarations, permissions, hooks, parallel scheduling, and stop decisions within a turn. - Part 5: The QueryEngine Main Loop as a State Machine used a state machine to unify those local mechanisms.
- Part 6: From SSE Events to Character-by-Character Rendering opened up the streaming process inside one model call.
- Part 7: Retries and Eight Layers of Error Recovery explained how the loop recovers after failure.
-
Part 8: From Ctrl-C to a Synthetic
tool_resultexplained how a user interrupts automated execution from outside the loop. - Part 9: Sidechains, Sub-agents, and agentId Routing generalized the same loop to sub-agents.
The original five-line pseudocode was never wrong. It simply left out what matters most: how execution branches between steps, how it recovers after failure, how a user reclaims control, and how one loop can serve different kinds of agents.
The loop executes; context carries information
The loop is the skeleton. It explains how events happen: when the model is called, when tools run, when the system retries, and when it stops.
Information flows through that skeleton: how messages are assembled, how the prompt cache is reused, how compaction shortens history, and how CLAUDE.md is injected. Those questions belong to the companion Claude Code Context Management research series.
The division of labor between the two series fits into two sentences:
The loop explains how things happen.
Context explains how information is organized.
Together, they form a complete picture of how a Claude Code agent operates.
Related series
- Claude Code Context Management research series — messages, caching, compaction, and context injection.
- Claude Code Tools research series — the capability and design of individual tools.
Top comments (0)