Anti-Pattern: Arbitrary Iteration Caps

You build an agentic loop. To feel safe, you write for i in range(5) and call it done. The agent stops after 5 turns.

This feels responsible. It is actually an anti-pattern. An arbitrary iteration cap as your primary stop mechanism cuts the model off mid-thought and produces incomplete work.

This lesson shows you the right mental model: a cap is a safety net, never the thing that decides when the task is finished.

The agentic loop is simple: send a request, inspect stop_reason, and react.

• tool_use → run the tools, append results to history, loop again
• end_turn → the model is finished; you stop

The model signals completion via stop_reason. Your job is to listen for that signal, not to guess a turn count in advance.

A multi-step task does not have a fixed length. A code refactor might need 3 turns; a research task might legitimately need 14.

If your loop stops at i == 5:

• The model may be mid tool-call, returning truncated or useless output.
• You ship incomplete work and call it 'done'.
• You are guessing the future instead of reacting to the model's actual stop_reason.

Decisions about when work is complete are model-driven. The cap knows nothing about the task.

There is a related anti-pattern that often hides next to iteration caps: parsing the model's text for completion words like 'done', 'finished', or 'complete'.

This is fragile. The model might write 'I'm not done yet' and your if 'done' in text check would fire incorrectly. Worse, it might genuinely finish without ever saying the magic word.

Terminate on stop_reason, never by scanning prose. The protocol gives you a reliable signal; text does not.

Caps are not useless. They are a safety net for the case where the loop misbehaves — a tool that keeps failing, or a model that gets stuck cycling.

Think of it like a circuit breaker: it should almost never trip. If your cap is firing on normal, healthy tasks, it is set too low and it is doing the wrong job.

The primary stop is end_turn. The cap only catches runaway loops that would otherwise burn tokens forever.

Here is the pattern that gets it right. The while True reacts to stop_reason; the cap sits outside as a guardrail with a generous limit.

Notice: a healthy task exits via end_turn. The cap only ever matters when something has gone wrong.

The difference between a safety net and a stop mechanism shows up in what you do when the limit is hit.

A correct safety net treats hitting the cap as an error condition: log it, surface partial results, and escalate. It is a signal that something is stuck.

An anti-pattern cap silently returns whatever it has as if the task succeeded. That is silent error suppression — you hide a failure and ship broken output downstream.

A useful rule for architects: reserve hard code for guarantees; leave decisions to the model.

• 'Is this task complete?' is a decision → the model answers it via end_turn.
• 'Never exceed N turns under any circumstances' is a guarantee → deterministic code enforces it.

An iteration cap is legitimately in the guarantee category. The mistake is letting a guarantee impersonate a decision — using the cap to decide completeness instead of to bound worst-case cost.

Don't confuse an iteration cap with a policy hook — both are deterministic code, but they guard different things.

• A hook (e.g. PostToolUse or an outgoing-call hook) gives 100% deterministic enforcement of a business rule: block a refund over $500, regardless of what the model wants.
• An iteration cap bounds loop cost / runaway behavior.

Use hooks when failure has financial, legal, or safety consequences. Use a cap to keep a loop from running forever. Neither one decides whether the task is logically complete.

If a cap is a net and not a plan, how high should it be? High enough that healthy tasks never touch it.

• Estimate the worst-case legitimate turn count for your task, then leave generous headroom on top.
• If you find yourself tuning the cap to make outputs 'feel complete', stop — you've turned it back into a stop mechanism.
• Track how often it trips. Frequent trips mean a stuck tool, a bad prompt, or a cap set too low.

Before you ship an agentic loop, confirm:

• The loop terminates on stop_reason == "end_turn" — the primary, model-driven stop.
• You inspect tool_use and append tool results to the full message history every turn.
• You never parse text for 'done' / 'finished' as a control signal.
• The iteration cap is generous and exists only as a safety net.
• Hitting the cap logs, surfaces partial results, and escalates — it never masquerades as success.

Apply the lesson to a real design decision.

Key takeaways:

• Completion is the model's decision, signalled by stop_reason == "end_turn". That is your primary stop.
• An iteration cap is a safety net, never the primary stopping mechanism. Set it generously so healthy tasks never hit it.
• Never parse text for words like 'done' to decide termination.
• When the cap does trip, treat it as an error: log, surface partial results, escalate — don't fake success.
• Reserve hard code for guarantees, decisions for the model. A cap bounds worst-case cost; it does not judge whether the work is finished.