Iteration Loops and Stopping Conditions

A surprisingly common rookie mistake: wiring up a Claude API loop without a stopping condition and letting it run for nine hours on an impossible task, burning fifty dollars in API credits before anyone notices. It is easy to do. You forget to set max_iters, the task turns out to be unreachable, and the model patiently generates variations, runs tests, and generates more variations with complete confidence. The Anthropic dashboard lights up. The lesson sticks permanently.

Every serious production agent has to avoid this story. The only way is to design the loop for termination from the first line. Today's lesson covers how.

Why Stopping Is the Hard Part

Giving an agent a loop is trivial. Call the model, execute its tool calls, feed the results back, repeat. That is maybe twenty lines of Python. What is hard is knowing when you have actually arrived at the destination.

Consider the failure modes of a naive loop that has no stopping condition beyond "keep going":

• The task is impossible or ambiguous. The agent will chase a goal that cannot be reached forever.
• The task is already done but the agent does not recognize it, and keeps trying to "improve" something that is already correct.
• The agent oscillates — it makes a change, tests fail, it reverts, tests fail differently, it makes the same change again, forever.
• The model hallucinates progress. It believes it is making headway, announces partial success, and loops on the next step which does not exist.

The Four Stopping Conditions

Every serious agentic IDE uses some combination of these four. None of them is sufficient alone. All four are necessary in production.

The Production Loop

Here is a real, runnable agent loop with all four stopping conditions. 40 lines of Python. You can copy this into a file right now and build on it.

from anthropic import Anthropic

client = Anthropic()
TOOLS = ["bash", "read_file", "edit_file", "done"]

def run_agent(
    task: str,
    max_iters: int = 20,
    max_tokens: int = 100_000,
    success_check=None,
) -> dict:
    messages = [{"role": "user", "content": task}]
    tokens_used = 0

    for i in range(max_iters):
        resp = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=4096,
            tools=TOOLS,
            messages=messages,
        )
        messages.append({"role": "assistant", "content": resp.content})
        tokens_used += resp.usage.input_tokens + resp.usage.output_tokens

        # STOP 1: explicit completion
        if any(b.type == "tool_use" and b.name == "done" for b in resp.content):
            return {"status": "complete", "iters": i + 1, "tokens": tokens_used}

        # STOP 2: success check (e.g., tests pass)
        if success_check and success_check():
            return {"status": "success", "iters": i + 1, "tokens": tokens_used}

        # STOP 3: budget cap
        if tokens_used >= max_tokens:
            return {"status": "budget_exhausted", "iters": i + 1, "tokens": tokens_used}

        # Execute any tool calls the model issued
        tool_results = []
        for b in resp.content:
            if b.type == "tool_use":
                result = execute_tool(b.name, b.input)
                tool_results.append({"type": "tool_result", "tool_use_id": b.id, "content": result})
        if tool_results:
            messages.append({"role": "user", "content": tool_results})

    # STOP 4: max iterations
    return {"status": "max_iters", "iters": max_iters, "tokens": tokens_used}

This is the same shape Cline uses, the same shape Claude Code uses, the same shape aider uses. Different languages, different tools, different prompts — same loop structure.

Tuning the Limits

The values above are production defaults but every task needs its own tuning. A rough guide for sizing limits on a new task:

• Simple edit (add logging, rename a variable): max_iters=5, max_tokens=20k. If it takes more than 5 iterations, something is wrong with the task framing.
• Feature implementation (add a new endpoint, write a class): max_iters=20, max_tokens=100k. Enough room to iterate on tests, discover edge cases, refactor.
• Research run (explore a codebase, answer "where is X implemented"): max_iters=30, max_tokens=150k. Reading is cheap, exploration takes many cheap steps.
• Migration or sweeping refactor: max_iters=50, max_tokens=300k. Most expensive, most likely to need a human in the loop at checkpoints.

When the Loop Stops at the Wrong Time

The other failure mode is the opposite: the loop stops too early. The model calls done prematurely because it is overconfident, or the success check returns true on a test suite that was passing before the agent touched anything. Both are real.

The mitigations are specific:

• For premature done: make the done tool's schema require the model to summarize what it actually accomplished. Forcing a summary forces the model to actually check.
• For false-positive success: capture test results before the agent starts and compare to the final results. Only call it success if both the test count and the pass count improved.
• For "looks done but isn't": add a verification step as the last iteration. Run git diff and feed it back. The model often catches its own mistakes when shown the actual diff.

Hands-On: Break the Loop

Copy the 40-line loop above into a file called my_agent.py. Wire up an Anthropic API key. Then deliberately break it in each of the four ways so you see each stopping condition fire.

1. Trigger max_iters. Give it an impossible task ("find a bug in this empty file"). Set max_iters=5, max_tokens=very_high. Watch it exhaust iterations and return "max_iters".
2. Trigger budget cap. Set max_tokens=500, give it any task. It'll hit the budget on iteration 1 or 2 and return "budget_exhausted".
3. Trigger success. Pass a success_check that returns True after a few iterations. Watch it return "success" mid-loop.
4. Trigger completion. Give it a real task it can actually finish (add a docstring to one file). Watch the model itself call done and return "complete".

Seeing all four fire on the same code in one session is the single clearest way to internalize how production agent loops terminate. It takes 20 minutes and locks the concept in permanently.

What's Next

Day 5 is the capstone. You take everything from days 1-4 — shell tool, search, worktrees, stopping conditions — and assemble them into a working agentic coder of your own. Under 150 lines of Python. You will be able to point it at any repo and watch it actually work.