chemenu/kb/concepts/Iteration and Cost Limits.md

---
type: types/concept.md
concept_type: workflow
tags: [gate, safety, iteration-budget, loop-breaker]
created: 2026-08-07
modified: 2026-08-31
related: [Mass-Update Gate, Anti-Cramming Heuristic, Index Scaling, wikitool, Structural Enforcement over Documented Rule]
sources: [Source - LLM Improvements Production Agent Gaps 2026, Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31, Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31]
confidence: 0.88
confidence_base: 0.88
provenance: sourced
summary: Im Code durchgesetzte Obergrenze von 60 wikitool-Aufrufen je Session\, Loop-Breaker bei 3 identischen Wiederholungen\, Slot-Erstattung bei abgelehntem Aufruf und ein seit 1.5.0 gemessenes Kalibrierungsband von 5-15 (einfach) bzw. 20-35 (komplex) Aufrufen
---
# Iteration and Cost Limits

**Typ:** workflow

## Definition

Eine hart in Code durchgesetzte Obergrenze für die Anzahl der Tool-Aufrufe, die eine Agent-Sitzung machen darf, bevor sie stoppen und explizite menschliche Genehmigung zum Fortfahren einholen muss - im Gegensatz zu einer nur im Prompt formulierten Anweisung wie „Nach N Schritten stoppen", die ein Agent sich selbst rationalisieren kann („nur noch ein Aufruf zur Behebung"). Das Muster hat zwei Komponenten: ein **Iteration-Budget-Gate** (eine Gesamtaufrufobergrenze pro Sitzung) und einen **Loop-Breaker** (sofortiger Abbruch, wenn die letzten Aufrufe identisch sind, unabhängig von der Gesamtanzahl).[^s-llm-improvements-production-agent-gaps-2026]

## Kernpunkte

- **Faustregel der Industrie:** ~5-15 Tool-Aufrufe für eine einfache, einstufige Aufgabe; ~15-25 für einen komplexen Multi-Tool-Workflow; >30 ist eine dokumentierte Warnung für schlechte Aufgabenzerlegung oder eine festgefahrene Schleife.[^s-llm-improvements-production-agent-gaps-2026]
- **In dieser Instanz gemessen (2026-08-31, `1.5.0`):** ~5-15 Aufrufe für eine einfache Aufgabe (gemessen 5-9), ~20-35 für einen komplexen Multi-Tool-Workflow. Das ist eine eigene Behauptung über diesen Stack, nicht eine Korrektur der darüberstehenden Branchen-Faustregel: die bleibt als belegte Aussage über den Stand der Technik stehen, die hier genannten Zahlen gelten für `wikitool`-Aufrufe in diesem Repository. Belegt sind sie durch die Sitzungszähler in `tools/.wikitool_session/budget.json`: `ingest-comma-bug-2026-08-31` 30 Aufrufe, `ingest-transcript-personalization-plane` 29, `ingest-issue-triage-2026-08-31` 26, `ingest-auto-mode-2026-08-31` 24. Jeder dieser vier gewöhnlichen Ingests lag auf oder über der Decke des zuvor dokumentierten Bandes von 15-25. Nachgezogen in `run_budget.py`, `instructions/gates.md` und den Skills `wiki-ingest` und `wiki-lint`; die Obergrenze von 60 blieb unverändert, weil sie kein Ziel ist, sondern der Punkt, ab dem eine Sitzung als festgefahren gilt.[^s-conversation-gate-counting-and-measured-calibration-session-2026-08-31]
- **Eine Richtgröße, die der Normalfall überschreitet, ist keine Richtgröße.** Sie lehrt einen Agenten, dass die Zahlen dekorativ sind - genau das Versagen, gegen das ein in Code durchgesetztes Budget immun sein soll. `instructions/gates.md` hält deshalb seit `1.5.0` auch fest, woher die Zahl kommt und wie sie neu zu messen ist, und nennt dafür `tools/.wikitool_session/budget.json`: eine Richtgröße ohne Messvorschrift veraltet still.[^s-conversation-gate-counting-and-measured-calibration-session-2026-08-31]
- **Warum reine Prompt-Limits scheitern:** Praktisch jeden dokumentierten Fall von „Agent hat Budget über Nacht aufgebraucht" führt auf die gleiche Grundursache zurück - keine in Code durchgesetzte Obergrenze, sondern nur als Prompt-Anleitung, die der Agent rationalisieren kann.[^s-llm-improvements-production-agent-gaps-2026]
- **Loop-Breaker-Begründung:** Erfasst den spezifischen Ausfallmodus eines Agenten, der denselben fehlgeschlagenen Vorgang in einer Sackgasse „höflich wiederholt" - identischer Befehl + Argumente N-mal hintereinander - auch wenn das Gesamtiterations-Budget noch nicht erschöpft ist.[^s-llm-improvements-production-agent-gaps-2026]
- **Implementiert (2026-08-07) in `tools/wikitool`:** Jeder Aufruf wird aufgezeichnet und in `main()` (`cli.py`) überprüft, bevor Typer an einen Subbefehl versendet, sodass kein einzelner Befehl manuell aktiviert werden muss. Der Status lebt in der gitignorierten `tools/.wikitool_session/budget.json`, indiziert nach `WIKITOOL_SESSION_ID` (oder als Fallback die Prozess-ID des aufgerufenen Shells), sodass eine neue Terminal/Sitzung mit einem neuen Budget startet. Standardobergrenze: seit Stack-Version `1.2.0` 60 Aufrufe/Sitzung, davor 30; Loop-Breaker-Fenster unverändert 3 identische Aufrufe hintereinander.[^s-conversation-comma-bug-budget-refund-and-lint-report-path-session-2026-08-31] Beide werden nur mit `--override-budget` umgangen, was der aufgerufene Agent nie von sich aus hinzufügen darf - nur nach expliziter menschlicher Genehmigung. Das verwandte [[Mass-Update Gate]] ging 2026-08-28 einen anderen Weg: Statt ein Bypass-Flag verwendet es einen dedizierten Code (42) mit der Bedeutung „ein Mensch muss dies sehen", und wird mit `--confirm <token>` gelöscht, bei dem der Token die exakte Dateiliste zusammenfasst - siehe diese Seite.
- **Auch das Zurücksetzen ist gated (2026-08-13):** `budget status` ist von der Zählung ausgenommen, sodass die Situation nach dem Gate-Auslöser meldbar bleibt, aber `budget reset` nicht - und es erfordert zusätzlich sein eigenes `--yes`. Das Ausnehmen des Befehls, der den Zähler löscht, würde das ganze Gate zur Formalität machen, die ein Agent umgehen könnte, indem er zuerst zurücksetzt.
- **Erstattung bei abgelehntem Aufruf (2026-08-31):** Das Budget soll Iteration zählen, nicht Reibung. Die Erstattung ist deshalb nicht auf den Exit-Code 1 gekeyt - das hätte `lint --fail-on-error` gratis gemacht, sobald es etwas findet -, sondern auf `_util.fail()`. `fail()` heißt: der Befehl hat abgelehnt, ein Argument zurückgewiesen oder als lesender Check Befunde gemeldet; es ist nichts passiert, also wird der Slot zurückgegeben. Ein Befehl, der seine Arbeit getan hat und danach ein Nicht-Null-Ergebnis meldet, wirft `typer.Exit(1)` direkt und bleibt gezählt. `record_and_check()` meldet zurück, ob es belastet hat, und `cli._run_traced` ruft im `finally`-Block `run_budget.refund()`. Der Aufruf bleibt in `recent`, damit der Loop-Breaker ihn weiterhin sieht - für eine wiederholt kaputte Invokation ist er das richtige Instrument, nicht der Zähler.[^s-conversation-comma-bug-budget-refund-and-lint-report-path-session-2026-08-31]
- **Verworfene Alternative:** die Schreibstellen zu markieren (35 Stellen in 15 Dateien), um die Erstattung auf „es wurde nichts geschrieben" zu keyen. Das ist fail-open: eine neue Schreibstelle, die den Marker vergisst, schwächt still ein Gate.[^s-conversation-comma-bug-budget-refund-and-lint-report-path-session-2026-08-31]
- **Obergrenze 30 → 60 (2026-08-31):** Das Kalibrierungsband (5-15 Aufrufe einfach, 15-25 komplex) blieb unangetastet, weil es die Arbeit beschreibt. Die Obergrenze beschrieb nichts und lag so dicht am Band, dass der Overhead eines realen Ingests sie allein erreichte. Der Loop-Breaker wurde bewusst **nicht** mitverdoppelt: er ist ein Detektor für drei identische Aufrufe und kein Budget, und eine Verdopplung ließe einen festgefahrenen Agenten doppelt so lange kreisen.[^s-conversation-comma-bug-budget-refund-and-lint-report-path-session-2026-08-31] Das Band selbst wurde noch am selben Tag in `1.5.0` an realen Läufen nachgemessen - siehe den gemessenen Punkt oben.[^s-conversation-gate-counting-and-measured-calibration-session-2026-08-31]
- **Eskalation, nicht stilles Versagen:** Ein ausgelöstes Gate ist nicht flüchtig - das Wiederholen mit denselben Argumenten schlägt absichtlich identisch fehl. Die richtige Reaktion ist, zu stoppen, Fortschritt und Blockierer dem Benutzer zusammenzufassen und auf Anweisungen zu warten (siehe AGENTS.md-Abschnitte „Tool Error Contracts" und „Iteration and Cost Limits").

## Beispiele

- Ein `wiki-ingest`-Lauf über eine große Quelle, die über 60 `wikitool`-Aufrufe hinaus weiterhin Entity-Seiten erstellt, löst das Iteration-Budget-Gate aus.
- Ein Agent, der nach wiederholten Fehlschlägen `xref add --a X --b Y` dreimal hintereinander wiederholt, löst den Loop-Breaker beim vierten Versuch aus, bevor er je die 60-Aufrufobergrenze erreicht.
- `tools/wikitool budget status` (kostenlos) / `tools/wikitool budget reset --yes [--all]` - Sichtbarkeits- und Zurücksetzbefehle für den sitzungsbezogenen Zähler.

## Wann zu verwenden

- Jeder agentische Workflow, der eine unbegrenzte Anzahl von Malen über eine Sammlung variabler Größe (Seiten, Entities, Dateien) iterieren kann, ohne einen natürlichen Haltepunkt in den Daten selbst eingebettet zu haben.
- Besonders relevant für die Skills `wiki-ingest`/`wiki-lint`, die viele Entity/Concept-Seiten, Cross-References und Lint-Durchläufe für eine einzelne Quelle berühren können.

## Wann NICHT zu verwenden

- Einzelne, begrenzte Einmalvorgänge, bei denen die Aufrufen-Anzahl inhärent festgelegt ist (z. B. ein einzelner `new entity`-Aufruf) - das Gate wird dort immer noch gleichmäßig angewendet, wird aber im Wesentlichen nie ausgelöst.
- Als Ersatz für das [[Mass-Update Gate]], das auf den *Schadensradius* eines `publish` (Dateien, die von einem einzelnen Push betroffen sind) begrenzt ist, nicht auf die *Iterationsmenge* über eine Sitzung - die beiden Gates beheben unterschiedliche Ausfallmodi und beide bleiben notwendig.

## Verwandte Concepts

- [[Mass-Update Gate]] - das verwandte Sicherheitsgate, das dieses Muster spiegelt, begrenzt auf Veröffentlichungsgröße statt Sitzungsiterationsvolumen
- [[Anti-Cramming Heuristic]] - eines der Wiki-Qualitätsprobleme, die ein unbegrenzter Ingest-Lauf sonst verletzen könnte
- [[Index Scaling]] - das andere Wiki-Qualitätsproblem, das durch unkontrolliertes Seitenwachstum gefährdet ist
- [[wikitool]] - die CLI, die dieses Gate implementiert

## Beziehungen

- **spiegelt das gleiche Muster wie:** [[Mass-Update Gate]]
- **schützt:** [[Anti-Cramming Heuristic]]
- **schützt:** [[Index Scaling]]
- **implementiert durch:** [[wikitool]]
- **wendet an:** [[Structural Enforcement over Documented Rule]]

## Siehe auch

- [[Mass-Update Gate]]
- [[Anti-Cramming Heuristic]]
- [[Index Scaling]]
- [[wikitool]]
- [[Source - LLM Improvements Production Agent Gaps 2026]]
- [[Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31]]
- [[Structural Enforcement over Documented Rule]]

## Fußnoten

[^s-llm-improvements-production-agent-gaps-2026]: [[Source - LLM Improvements Production Agent Gaps 2026]]
[^s-conversation-gate-counting-and-measured-calibration-session-2026-08-31]: [[Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31]]
[^s-conversation-comma-bug-budget-refund-and-lint-report-path-session-2026-08-31]: [[Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31]]