The Loop

The agent class in mini-swe-agent is about 100 lines of Python. It has one tool, bash. Every step appends to a single list of messages and nothing is ever removed. With a strong model behind it, that loop resolves more than 74% of SWE-bench Verified.¹ Whatever you picture when you hear the word agent, the working core is smaller than that.

A loop is all it is

Strip any coding agent down and you find the same shape: call the model, run the tool it asked for, append the result, call it again. The model does the thinking. Everything else, from which tools exist to what the model sees next turn to when it stops being called, belongs to the harness.

Claude Code's documentation names three phases, gather context, take action and verify results, and says they blend together. It also says the layer around the model that supplies tools and manages context is what the term agentic harness refers to.² This chapter draws the same ring with four stops: observe, plan, act, verify. Plan is the phase that tends to hide inside the model's reasoning. Verify is the one that tends to go missing.

The interesting engineering sits at the edges of the loop, not in the middle. What goes into the context each turn is chapter 2. What the tools look like is chapter 3. This chapter is about the loop itself: where it came from, when it should stop, when to run several, and how it survives being shut down.

Where the loop came from

Every phase in that ring was a paper before it was a product feature.

ReAct (2022) interleaved reasoning traces with actions and observations. The authors argued that reasoning helps a model track and revise its plan, while actions let it reach outside sources. With one or two in-context examples it beat imitation and reinforcement-learning baselines by an absolute 34 points on ALFWorld and 10 on WebShop.³

Reflexion (2023) added the verify step. The agent receives a feedback signal, writes a reflection in plain text, keeps it in an episodic memory buffer and tries again. That reached 91% pass@1 on HumanEval against GPT-4's 80%.⁴ Tree of Thoughts (2023) added planning in the strong sense: several candidate paths, lookahead, backtracking. On the Game of 24 it took GPT-4 from 4% with chain-of-thought to 74%.⁵

Then the field learned how much the loop's surroundings matter. SWE-bench put 2,294 real GitHub issues in front of models, and Claude 2 resolved 1.96%.⁶ SWE-agent changed the interface instead of the model, designing commands, file viewers and error feedback for what its authors called a new category of end user, and reached 12.5%.⁷ Today a 100-line bash loop clears 74% on the Verified subset, with much stronger models doing the heavy lifting.¹ The harness is a variable, and for a stretch it was the variable that moved fastest.

The last row is measured on SWE-bench Verified, a curated subset, so it is not a like-for-like comparison with the rows above it. The direction is the point.

“Looks done” is not a stop signal

Anthropic's widely cited taxonomy separates workflows, where LLMs and tools run through predefined code paths, from agents, where the model directs its own process and tool use.⁸ It lists five workflow patterns (prompt chaining, routing, parallelization, orchestrator-workers, evaluator-optimizer) and reserves agents for open-ended problems where the number of steps cannot be predicted. The price is latency, cost and compounding errors, which is why the same post recommends stopping conditions such as an iteration cap.⁸

Google's ADK makes the exits explicit. Its LoopAgent ends when it hits max_iterations or when a sub-agent sets escalate to true, and the docs' writer, critic and refiner example caps at five passes.⁹ Budget and escalation: every loop needs both.

The default exit in a coding agent is quieter and worse. The model stops when it believes it has finished. Claude Code's best-practices guide says so directly.

“Without a check it can run, ‘looks done’ is the only signal available, and you become the verification loop.”— Claude Code best practices, Anthropic

The guide lays out four escalating gates: a check written into the prompt, a /goal evaluator, a Stop hook that acts as a deterministic gate, and a verification subagent.¹⁰ A Stop hook can return a JSON decision of block with a reason, or exit with code 2, and the model keeps working with that reason in front of it. Its input carries a stop_hook_active flag so the hook itself can avoid looping forever.¹¹ In your own loop the same gate is a check that runs whenever the model ends a turn without a tool call; on failure, its output goes back in as the next message.

The stepper below plays the six-step “fix the failing tests” sequence from Claude Code's docs.² Turn the verification check off and watch what the loop reports.

Copy this: a minimal Stop-hook gate that runs the test suite and blocks Claude Code from stopping while it fails, checked against the current hooks reference (Oct 2026).¹¹

// .claude/settings.json
{ "hooks": { "Stop": [ { "hooks": [ { "type": "command",
    "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/tests-gate.sh",
    "timeout": 300 } ] } ] } }

#!/usr/bin/env bash
# save as .claude/hooks/tests-gate.sh, chmod +x (needs jq)
input=$(cat)
cd "$CLAUDE_PROJECT_DIR" || exit 1   # hooks run in the current dir, which follows cd
# Already continuing because a Stop hook blocked: allow the stop, never loop forever
[ "$(jq -r '.stop_hook_active' <<<"$input")" = "true" ] && exit 0
if out=$(npm test 2>&1); then exit 0; fi
jq -n --arg r "Tests are failing. Fix them and rerun npm test before stopping.
$(tail -n 20 <<<"$out")" '{decision: "block", reason: $r}'

The guard buys one forced retry per stop. Remove it and Claude Code's own backstop applies: after stop hooks continue the turn eight times in a row with no tool call between, it overrides the next block and ends the turn (raise it with CLAUDE_CODE_STOP_HOOK_BLOCK_CAP).¹¹ Any other harness: when the model returns with no tool call, run the test command; if it fails, append the last 20 lines as a user message and call the model again, at most N times.

Ralph: the dumbest loop that works

Ralph is a pattern you can take to production: a deterministic outer loop around a nondeterministic worker, with all state on disk and a hard spend cap. Geoffrey Huntley's original is one line of shell, while :; do cat PROMPT.md | claude-code ; done.¹³ The same prompt runs every pass against a repository that changes underneath it. Each pass reads the files, does one item, and exits.

“That's the beauty of Ralph - the technique is deterministically bad in an undeterministic world.”— Geoffrey Huntley (2025)

When Ralph does something dumb, you do not swap the model; you add a sign to the prompt. Huntley's headline result, an MVP on a $50k contract for $297, is one practitioner's report, not a measurement.¹³

The original line will not run as written against the current CLI. A form that does, with both caps made explicit:

# Run only inside a container or VM, as a non-root user (e.g. the
# devcontainer): this skips every permission prompt, and Claude Code
# refuses the flag as root. --bare skips hooks and CLAUDE.md discovery
# and needs ANTHROPIC_API_KEY.
for i in $(seq 1 20); do                      # hard cap: 20 passes
  out=$(claude -p "$(cat PROMPT.md)" --bare \
        --dangerously-skip-permissions \
        --max-budget-usd 2.00)                # per-pass spend cap
  grep -q '<promise>DONE</promise>' <<<"$out" && break
done                                          # worst case about 20 x $2

--max-budget-usd stops a print-mode run once its estimated spend reaches the cap, counts subagent spend toward it, and can overshoot slightly, so leave headroom.¹⁴ Claude Code's docs limit skipping permissions to isolated containers and VMs, and on Linux and macOS it will not start in that mode as root or under sudo outside a recognized sandbox; an unattended loop belongs in a container, run as a non-root user.¹⁵ State lives in the repository and a progress file, never in the session.

Anthropic's ralph-wiggum plugin moves the loop inside the session with a Stop hook, started with a prompt, --max-iterations and --completion-promise. The hook blocks every stop until the output contains the exact promise string inside <promise> tags or the count reaches the cap. The README tells you to rely on --max-iterations as the primary safety mechanism.¹² In the Ralph panel above, drag the cap below the iteration where the promise lands: the loop stops, the spend is fixed, and the work is unfinished. That is the correct failure. Without the plugin, the outer script above does the same job.

Fan-out and orchestration

Once one loop works, the obvious move is to run several. Anthropic's research system has a lead agent that plans and delegates to subagents running in parallel. In that 2025 setup, with Opus 4 leading Sonnet 4 workers, it beat single-agent Opus 4 by 90.2% on an internal research eval. Token usage alone explained 80% of the performance variance on BrowseComp, the system uses about 15 times the tokens of a chat, and parallel tool calls cut research time by up to 90%.¹⁶ Cognition's Walden Yan argued the opposite the same month: share full context and full agent traces, not just individual messages. His example is a Flappy Bird clone split between two subagents that return a background and a bird in mismatched styles.¹⁷

“Actions carry implicit decisions, and conflicting decisions carry bad results.”— Walden Yan, Cognition (2025)

The two positions reconcile once you look at what each side parallelizes. Research is reads. Subagents search, condense and report back, which Anthropic's context-engineering guidance frames as a clean separation between search and synthesis.¹⁸ Code is writes, and two writers with different assumptions collide. Claude Code keeps subagents in separate context windows that return summaries, recommends a fresh-context reviewer that will not be biased toward code it just wrote, and gives parallel writers their own git worktrees.¹⁰ Cursor 2.0 runs up to eight agents on one prompt the same way, isolated on worktrees or remote machines.¹⁹ In your own harness a subagent is a child loop with its own message list, and its final message is the only thing the parent reads.

Four shapes cover most multi-agent systems. Three map onto Anthropic's workflow taxonomy: orchestrator-workers, prompt chaining, and the review shapes, which combine evaluator-optimizer with parallelization's voting variant (the same task run several times).⁸ The fourth is what coding tools added: parallel writers, each isolated on its own worktree.

What a subagent returns is an API. Anthropic's guidance notes a subagent may spend tens of thousands of tokens exploring and still return a condensed summary, often 1,000 to 2,000 tokens.¹⁸ Make that a contract: fixed fields, a hard cap of 2,000 tokens, and a lead that validates the shape before it reads the content. The field names below are a suggestion; the fixed shape is the point.

{
  "status": "done | partial | blocked",
  "answer": "the conclusion, in 3 to 8 sentences",
  "evidence": ["src/cart/pricing.py:27", "pytest -q: exit 0"],
  "changed": [],
  "open_questions": ["what the lead has to decide"],
  "tokens_used": 41200
}

A blocked status with a question is a legitimate answer. Without it, a worker that lacks information guesses.

Budget the tree, not the node. At fifteen times the tokens, per-agent caps still let a lead spawn its way past any sane total. Give the root one budget that every descendant draws from, and cap depth and width as well. Claude Code and its Agent SDK already count subagent spend toward the run's budget; once it is reached, spawning another subagent fails with “Budget limit reached” and running background subagents are stopped.²⁰ In your own orchestrator, pass a shared budget down the tree, decrement it on every model response, and refuse to spawn when it is empty.

Check the failure modes before launch. A Berkeley study of more than 1,600 multi-agent traces across seven frameworks (MAST) found 14 failure modes in three categories, and verification is one of them.²¹ Read them as a pre-launch checklist:

When the loop breaks

Production loops seldom fail in the model's reasoning. They fail at the seams: a 529 from the API, a tool that hangs, a write that half-happened before a crash, a retry that sends the email twice. Sort every failure into one of three classes, because each gets a different retry rule and the model sees something different.

Claude Code runs a separate StopFailure hook when a turn ends on an API error, with types such as rate_limit, overloaded and server_error, which is the place to hang an alert.¹¹

Give every write tool an idempotency key. Retries and resumes replay calls, and a payment, email or ticket created twice is a real incident. Stripe's API is the reference design: the client sends a unique key, the server saves the first result, and a retry with the same key gets that saved result instead of a second action.²⁴ For an agent, derive the key from the run id and the tool-call id, so a resumed run reuses it.

Put a timeout on every tool. A hung tool holds the whole loop and its budget. Claude Code's Bash tool defaults to two minutes and lets the model raise that to ten, and HTTP-based MCP requests time out after 60 seconds by default, but the overall MCP tool limit defaults to about 28 hours, so give slow servers their own timeout.²⁵

Checkpoint before the side effect, not after. Write the intended call and its inputs to durable storage, run it, then record the result. On restart, a call with an intent and no result is the one to reconcile, using its key. Do not lean on the agent's undo: Claude Code's checkpoints track files edited in the session, not files changed only by Bash, and nothing outside the filesystem.²⁶

Show the model one useful line. After a failure the model needs what failed, why, and what to try next, not 400 lines of traceback. SWE-agent's interface gains came partly from error feedback designed for the model,⁷ and Anthropic's tool-writing guidance says the same.²⁷

“…prompt-engineer your error responses to clearly communicate specific and actionable improvements, rather than opaque error codes or tracebacks.”— Ken Aizawa, Anthropic (2025)

Surviving the session boundary

Long tasks outlive a context window, and each new session begins with no memory of the last.²⁸ Anthropic's harness for long-running agents treats that as a handoff problem. An initializer agent writes an init.sh, a progress file and the first commit. Every later session is a coding agent that builds one feature against a JSON list of 200-plus features, each marked pass or fail. Each session opens with the same ritual: read the progress log, check git history, run the basic tests, pick the next failing feature.²⁸

Drop the ritual and the failures are predictable: declaring the project done early, leaving bugs and undocumented changes behind, marking features passed without testing them, and spending tokens rediscovering state.²⁸ Two of those four are verification failures.

Cloud agents face a harder version, where the gap is a CI run or a human review that takes hours. Cognition found containers cannot survive those gaps and now snapshots memory, process trees and filesystem at the hypervisor level so a task can stop and resume.²⁹ OpenAI's Codex cloud gives each task its own workspace and hands back diffs, logs and test results with citations, not a claim that it worked.³⁰ Claude Code stores sessions as JSONL that can be resumed or forked, but sessions are independent.² Anything that must carry over belongs in files.

What it costs

A while statement costs nothing; each pass through the model does. A cap is a budget: maximum iterations times tokens per iteration is the most a loop can spend, which is why the Ralph panel multiplies them, and for a tree of agents the cap belongs at the root. Agentic systems trade latency and cost for task performance by design,⁸ so spend on verification: the test run, the fresh reviewer, the Stop hook that refuses “looks done.” Cost per task, model routing, and how to staff and govern all of this are in Part 06. Every turn also feeds the model a context window, and that window is usually the first thing to degrade. That is Chapter 2.