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

type, concept_type, tags, created, modified, related, sources, provenance, summary

type	concept_type	tags	created	modified	related	sources	provenance	summary
types/concept.md	workflow	gate safety iteration-budget loop-breaker	2026-08-07	2026-09-02	compares-with Mass-Update Gate see-also Anti-Cramming Heuristic see-also Index Scaling mechanism wikitool exemplifies Structural Enforcement over Documented Rule see-also MCP-Leseserver	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 Source - MCP Read Server Implementation Session 2026-09-02	sourced	Im Code durchgesetzte Obergrenze von 60 wikitool-Aufrufen je Session, Loop-Breaker bei 3 identischen Wiederholungen, Slot-Erstattung, ein gemessenes Kalibrierungsband, und Retrieval sowie der MCP-Leseserver bleiben ausgenommen

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).¹

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.¹
• 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.²
• 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.²
• 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.¹
• 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.¹
• 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.³ 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.³
• 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.³
• 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.³ Das Band selbst wurde noch am selben Tag in 1.5.0 an realen Läufen nachgemessen - siehe den gemessenen Punkt oben.²
• 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.
• Im MCP-Leseserver. Das Gate begrenzt eine Agenten-Session am unbemerkten Iterieren über den Wiki-Zustand - deshalb ist Retrieval bereits generell ausgenommen (SKIP_COMMANDS) -, nicht einen Nutzer, der oft sucht. Ein zu häufig suchender Nutzer ist ein Ressourcenproblem, das vor den Serverprozess gehört (Rate Limiting), nicht in dieses Gate - beide zu vermischen würde es zu einem Rate Limiter verwässern.⁴

Beziehungen

Siehe auch

• Source - LLM Improvements Production Agent Gaps 2026
• Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31

Fußnoten

Beziehungen

• compares-with: Mass-Update Gate
• see-also: Anti-Cramming Heuristic
• see-also: Index Scaling
• mechanism: wikitool
• exemplifies: Structural Enforcement over Documented Rule
• see-also: MCP-Leseserver

---

1. Source - LLM Improvements Production Agent Gaps 2026 ↩︎

2. Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31 ↩︎

3. Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31 ↩︎

4. Source - MCP Read Server Implementation Session 2026-09-02 ↩︎