Predict no-watermark loop failure
What you'll learn
Long-running agents need budget watermarks: at 80% commit and exit cleanly, at 95% hard exit. No watermark = clipped final output and lost progress.
- No watermark = runaway loop = clipped output / lost context.
- Two watermarks: 80% (soft, commit + exit cleanly), 95% (hard exit).
- Watermarks live at the loop / harness layer, not in prompts.
An agent loop without **session-budget watermarks** is the canonical 'runaway agent' failure: the agent keeps trying things, retrying, and editing until it runs out of context window. By the time it stops, it has produced a clipped final answer, lost early-conversation context, or summarised away the actual progress. The fix is a self-pacing discipline: at ~80% of context fill, *commit in-flight work and exit cleanly*; at ~95%, *hard exit*. Exiting cleanly *is* success.
The failure mode signature: long-running tasks (47 turns, 100 turns) where the agent edits the same file, runs tests, re-edits, re-tests, and either dies mid-stream or returns a vague 'I made some progress; continue from here' summary. The clipped output is the visible symptom; the structural cause is no budget watermark, so retries consumed the window.
Watermarks belong at the loop layer, not the prompt layer. The model's job is to do work; the harness or surrounding orchestration code's job is to monitor token usage and call the watermark. Two thresholds: 80% = soft (finish current unit, commit, exit); 95% = hard (immediate exit, even if mid-unit). The next session resumes from the committed state.
Why two thresholds: 80% is the point where the *graceful* exit is still possible — there's enough budget to write a useful summary, commit changes, and leave the workspace in a state the next session can pick up from. 95% is the safety net for cases where the 80% logic missed (e.g., a single tool call ate 15% of context unexpectedly). Hard exit at 95% prevents the unrecoverable state where the agent runs out of room mid-summary.
Key points
- No watermark = runaway loop = clipped output / lost context.
- Two watermarks: 80% (soft, commit + exit cleanly), 95% (hard exit).
- Watermarks live at the loop / harness layer, not in prompts.
- 'Exit cleanly' is success — partial work committed and recoverable.
Examples
Agent has been going for 47 turns, looping between editing a file and running tests. Tests still fail. The final output is 'I'm continuing to work on this — please re-run for further progress.' Diagnosis: window filled, summary clipped, no watermark caught it.
At each loop iteration, check token usage. If ≥80%: commit current changes, write a 'state-of-play' file, return a summary, exit. If ≥95%: hard exit immediately. Next session: read state-of-play, resume.
Pitfalls
- Treating 'increase max_tokens' as the fix. max_tokens is per-message generation length, not loop budget.
- Putting the watermark logic in the prompt ('please stop at 80%'). The model doesn't reliably track its own context usage; the harness must.
- Treating a clean 80% exit as a *failure*. It's success — partial progress is preserved and recoverable.
- Setting only one threshold. 80% alone misses unexpected context spikes; 95% alone misses the graceful-exit window.
Source notes: 00-academy-basics/notes/06-claude-code-in-action.md
Ask Claude
Build a prompt with this lesson + your question, copy it, and open the Claude Project in a new tab.