1.2 · The Agent Loop

1.2 · 20 min

The Agent Loop

A language model cannot run your tests. It cannot read a file it was not given, cannot check whether its fix compiled, cannot even see the current time. Everything in Lesson 1.1 describes a brain in a jar. The thing that turns that brain into an agent that ships working code is a loop wrapped around it, and the loop is so simple you can draw it in four boxes.

The loop

MODELdecidesTOOL CALLbash, editRESULToutput, errorCONTEXTthe transcriptemitsexecutesreturnsreadsrepeats until doneagent / actioncontext / data

One pass works like this. The model reads the context (your prompt, plus everything accumulated so far) and decides its next action. If the action needs the world, it emits a tool call: a structured request like "run npm test" or "read src/auth.ts". The harness executes that call and appends the result, output or error, back into the context. The model reads the updated context and decides again. Repeat until the model decides the task is done and emits a final answer instead of another tool call.

That is the entire trick. An agent is a model using tools in a loop. The model never touches your machine; it only emits requests. The harness (Claude Code, here) never thinks; it only executes and reports. Intelligence and capability live on opposite sides of the tool-call boundary, and every behavior you will ever see, good or pathological, is some number of passes around this cycle.

Claude Code's own docs describe the loop as three blended phases: gather context, take action, verify results. Those map onto the figure directly: gathering is loops whose tool calls read (searching files, fetching docs), acting is loops whose tool calls write or execute, and verifying is loops that run checks and read the results. A question about your codebase might terminate after two read loops. A bug fix might take forty passes: read, edit, test, read the failure, edit again.

The tools, concretely

Tool calls are not abstract. As of July 2026, Claude Code's tool reference lists the built-ins by exact name, and the names matter because you will use them later in permission rules and hooks. The ones that carry most sessions:

  • Read, Glob, Grep: read file contents, find files by pattern, search inside files. No permission prompt; reading is cheap and safe.
  • Edit, Write: modify or create files. Permission required.
  • Bash: execute shell commands. Permission required, and deservedly.
  • WebFetch, WebSearch: pull external content into context. Permission required.
  • Agent: spawn a subagent with its own separate context window and report back. That one line is doing a lot of work; Lesson 2.5 unpacks it.

Notice the split: the tools that only observe are free, the tools that change the world are gated. That is the trust model in one sentence, and you met it in the Lesson 0.2 lab when Claude grouped its own tools for you.

Power and failure live in the same place

The loop is why agents compound. Each pass conditions on all previous results, so the model course-corrects: a failing test in iteration 12 reshapes iteration 13. Nothing about a single model call can do that. This is also why "autonomy" is not a personality trait of the model; it is a number. How many loop iterations run between moments where you look? An autocomplete tool runs zero loops. A chat assistant runs one. Claude Code left alone on a task might run sixty. More loop length means more leverage and more accumulated deviation from what you meant, at the same time, from the same mechanism.

Because iteration N conditions on everything before it, early mistakes do not stay small. A wrong assumption in loop 3 ("this project uses Jest", when it uses Vitest) gets built on in loops 4 through 30: config files written for the wrong runner, tests importing the wrong assertion API, an install of a dependency you did not want. The loop does not have a backspace. It has course-correction only when a tool result contradicts the assumption loudly enough, and if nothing does (Jest happily installs), the error compounds silently. You will formalize this in 1.5 as drift; for now, hold the mechanical version: the loop amplifies whatever enters it, including errors.

The other structural consequence: the loop is only as honest as its results stage. The model knows the world exclusively through tool results. If a test suite passes vacuously (zero tests collected), the result says "passed" and the model, reasonably, proceeds. Garbage in the results channel becomes confident wrongness in the very next decision. When you design verification in Part 3, you are really designing what flows through that one edge of the figure.

In practice: read a session as loops

Once you see sessions as loop passes, live sessions become legible. You stop reading Claude's prose narration and start reading its tool calls: what did it decide to look at, what did it change, what did it run, what came back. The narration is commentary; the tool calls are the ground truth of what happened.

Lablab-1-2Annotate the loop

Goal: Run a real multi-step task and produce a written annotation of every loop iteration: decision, tool call, result, and what the result changed.

Prereqs: the agentic-practice repo, with parse-duration.ts from the 1.1 lab (any version).

  1. Start a fresh session in the practice repo and dispatch a task that forces several loop passes:
PromptA task that must loop

Add a test file for parse-duration.ts using Node's built-in test runner (node:test, no new dependencies). Cover at least: simple units, a compound string, and one invalid input. Run the tests. If any fail, fix parse-duration.ts (not the tests) and run them again until green.

  1. Watch the session, and for every tool action Claude takes, write one line in a scratch file loop-log.md: iteration number, what tool it used, on what, and what came back (success, output, error).
  2. When the session finishes, annotate each line with its loop stage: gathering context (reads, searches), taking action (edits, writes), or verifying (test runs and reading their results).
  3. Find the iteration where a result changed Claude's plan: a failing test, a file that did not contain what it expected. Mark it. That edge, result flowing back into decision, is the loop earning its keep.

Verify

  • loop-log.md lists every tool action in order, each tagged as gather, act, or verify.
  • The task ended with a real green test run you saw in the output, not a claim of one.
  • You marked at least one iteration where a tool result visibly redirected the next action. If the run was too clean to show one, re-run with an invalid-input case you know the current implementation gets wrong.
>Troubleshooting
  • Claude wrote tests but never ran them: your dispatch let it stop early. Re-read the prompt; it says run and iterate until green. Tell it "run the tests now" and keep annotating; the missing verify loop is itself a finding.
  • The whole task finished in two iterations: the task was too small for your implementation. Ask for an additional edge case ("support decimal values like 1.5h") to force more passes.
  • Tests fail because node:test is unavailable: check node --version; the built-in runner needs a modern Node. Any Node 20+ is fine.

Where it breaks

Two reading errors to avoid. First: judging a session by its final message. "All tests pass" is a model-generated sentence; the tool result where tests actually passed is evidence. If you cannot find the green run in the transcript, it did not happen. Second: interrupting the loop too eagerly. Watching an agent read four files you consider irrelevant is uncomfortable, but gathering loops are cheap and often save acting loops. Interrupt when it starts changing the world on a wrong assumption, not when it explores. You are allowed to steer at any point; Claude Code is built for interruption. Spend those interruptions where the loop is about to compound an error, which is almost always at the transition from gathering to acting.

Knowledge check

Knowledge check

Q1Mid-task, Claude says: 'The tests pass, so I'll move on to the refactor.' Scrolling up, you see it wrote the test file but there is no test-run tool call anywhere. Which loop stage failed, and what happened?
Q2In loop 3 of a long session, Claude misidentifies your test runner and installs the wrong one. Loops 4 through 20 build on it without error. What made this expensive?
Q3Why does 'autonomy' in this course mean loop length between human looks, rather than a property of the model?
Q4Which tools run without a permission prompt in Claude Code as of July 2026, and why does the split make sense?

Sources