Experience-Driven Black-Box Cost Control for Coding Agents
Python agentic-aiagentic-codingai-codingai-coding-assistantanthropicartificial-intelligenceclaude-codecodexcoding-agentcoding-agentscost-optimizationcost-reductiondeveloper-toolsgithub-copilotllmopen-sourceopenaiproductivitytoken-optimization
Loop guard
How the failure-loop guard (see the main README) decides, one tool call at a time.
Per tool call, turn.TurnGuard:
- folds the call into a
state.SpiralState-- edits per file, files edited, error outputs, verification runs, and how often a failure repeats one seen before (edits made through the shell count too,shell_edits.py); - checks a hard backstop: stuck and far past this repository's envelope (an unspent redirect is still given first);
- asks
rules.assess_abort: a free gate decides whether the turn is worth a look; then the judge (judge.py) decides -- in the plugin always, once the repository has an envelope; without a judge (some experiment arms), the strict heuristicis_stuckwith the envelope does; - answers the first stuck verdict with a redirect (
rules.nudge_text, or a judge-written one) and starts a fresh segment, so the agent gets a fair window to recover; a later one with anabortverdict, which the plugin delivers as a notice to the person (it never stops a turn).
The envelope (envelope.py) is a percentile of how long this repository's turns run when
they end well -- the agent stopped on its own and no check after its last edit failed. Only such
turns feed it, and a turn's own outcome only gates later turns. The guard's thresholds start
from a preset (SPIRAL_LEVELS), learn on top of it, and can be pinned by hand
(loopguard.<name> settings).
| Module | |
|---|---|
turn.py |
TurnGuard: the guard for one prompt-turn, persisted between hook calls |
rules.py |
thresholds and presets, the gate, is_stuck, assess_abort, the redirect text |
envelope.py |
EnvelopeTracker and its per-repository storage |
state.py |
SpiralState, completed_calls (one streamed line to finished calls) |
shell_edits.py |
files a shell command writes (sed -i, redirects, inline Python, ...) |
judge.py |
the stuck judge and redirect writer (model calls) |