The Core Agent Loop Cycle¶
Every Claude Code session — whether interactive or headless — follows this cycle:
Claude is not a chatbot that waits for input between turns. Within a single session it chains tool calls autonomously: read files, run commands, edit code, run tests, read results, iterate. Each full round-trip (Claude output → tool execution → result back to Claude) is one turn.
Alternative Framing: Universal Agent Thesis¶
Cobus Greyling proposes a four-step cycle that generalises across all agent tooling and domains:
The distinguishing fourth step — Learn — means the agent updates its own state
or strategy based on feedback from previous actions. In Claude Code terms, "Learn"
maps to reading test output, reviewing prior commits, or updating PROGRESS.md
before the next iteration. An agent that only loops Perceive → Reason → Act
without incorporating feedback is executing, not improving.
Two Lenses on Loop Primitives¶
A loop can be decomposed two complementary ways. Keep both in mind — they answer different questions.
| Lens | Primitives | Answers |
|---|---|---|
| Functional (what the loop does) | Execution · Verification · Orchestration · Observability | "Which capability failed?" |
| Mechanical (what the loop is built from) | Automations · Worktrees · Skills · Connectors · Sub-agents · Memory | "Which component do I configure?" |
The functional lens names the four jobs every non-trivial loop performs:
- Execution — doing the work (the Act step above)
- Verification — checking the work before it ships (Verification)
- Orchestration — coordinating multiple agents/steps (Subagents, Fan-Out)
- Observability — being able to see what the loop did and why, so a failure can be attributed to the right layer. Without it you cannot tell whether execution, verification, or orchestration broke — you only see that the loop failed.
"loop engineering is the right frame — execution, verification, and orchestration are the primitives, but without observability you can't tell which layer failed." (@miltonheyan, Jun 2026)
Observability is the prerequisite fourth — already the tweet's own point, made explicit here: the other three are undiagnosable without it.
The mechanical lens is the Six Building Blocks you actually configure to realise those functions. Observability in practice means run logs, the cross-run memory file (Loop Contract), and behavioural eval harnesses that score real runs across multiple dimensions (travisbreaks/coding-agent-evals, Jun 2026).
What a Turn Actually Sends (Codex, primary source)¶
OpenAI's own account of the Codex CLI agent loop shows the turn abstraction above is not free:
every turn resends the entire growing conversation as a JSON input list to a stateless
Responses API (no previous_response_id, deliberately, to keep Zero-Data-Retention support
simple) — with a fixed injection order of a sandbox-permissions message, optional developer
instructions, aggregated AGENTS.md/skills content (capped at 32 KiB), and an environment-context
block. This makes the loop quadratic in raw JSON size by construction; prompt caching turns
effective cost linear only while the prefix stays byte-identical — changing the tool list, model,
sandbox mode, or working directory mid-conversation invalidates the cache, so Codex appends new
marker messages instead of editing earlier ones to preserve the shared prefix. (OpenAI,
"Unrolling the Codex agent loop", Jan
2026; direct fetch 403s — captured via Wayback.)
Loop Termination¶
A session ends at one of these runtime signals. They are the mechanical events that enforce the design-time Stop Condition Taxonomy (completion-check / budget / max-iterations / no-progress):
- Claude produces a text-only response (no tool calls) —
success(enforces a completion check) max_turnsis reached —error_max_turns(enforces budget / max-iteration stops)max_budget_usdis exceeded —error_max_budget_usd(enforces the budget stop)- Structured-output validation keeps failing after retries —
error_max_structured_output_retries(enforces the completion-check stop for--json-schema/outputFormatruns) - A Stop hook rejects the result — loop re-enters (a completion check that has not yet passed)
- An unrecoverable error occurs —
error_during_execution