mirror of
https://github.com/AgentSeal/codeburn.git
synced 2026-11-16 21:59:29 +00:00
* feat(guard): warn and stop identical-call loops and failing-command retries The PreToolUse hook now watches two more signals next to the dollar caps. The same tool called with the same input (hashed as JSON with sorted keys) 4 times in a row gets a one-time warning and the 8th call is denied. A shell command (Bash or PowerShell) that already failed 3 times in the session gets a one-time warning and is denied once it has failed 5 times; successful runs do not reset the count. Both pairs are guard.json settings (loopWarnAfter, loopStopAfter, retryWarnAfter, retryStopAfter), validated like the dollar caps, null turns one off, and guard status prints them. The incoming call is read from the hook payload and recorded by tool_use_id, since the transcript can lag. The session cache (version 4) keeps a rolling window of the last 16 calls, pending shell calls and failure counts per command, folded from the same incremental tail read as the cost. When a loop or retry warning fired, the Stop note adds one line with the count and what the calls after the first warning cost. On a generated 20 MB transcript the warm hook takes about 13 ms (median of 5); the first cold read of the whole file takes about 480 ms, as before. * fix(guard): let allow lift loop blocks and tell the agent at the warning codeburn guard allow now lifts the loop and retry stops as well as the hard cap, for that session only, so polling a CI job on purpose has the same way out. The deny reasons name it. Loop and retry warnings now also reach the agent through PreToolUse additionalContext, with the same sentence plus "Change approach or ask the user." It is sent without a permissionDecision, since "allow" would also skip the user's permission prompt. The docs now say the loop count tops out at 17 (16 earlier calls plus the incoming one).
1.9 KiB
1.9 KiB
Guard your budget
codeburn guard install # hooks into this project's .claude/settings.json
codeburn guard install --global # or into ~/.claude/settings.json
codeburn guard status # caps, install locations, flagged projects
codeburn guard uninstall # removes cleanly, leaves your own hooks alone
Guard installs opt-in hooks into Claude Code that watch session cost while you work:
- Soft cap (default $5): a one-time in-session warning when a session passes it.
- Hard cap (default $15): stops the session.
- Checkpoint (default $3): if a session ends past this with no edits and no commits, a nudge suggests starting fresh with a named deliverable.
- Loops (default warn at 4, stop at 8): the same tool called with the same input that many times in a row gets a one-time warning, then the call is stopped. Any different call resets the count, which tops out at 17.
- Retries (default warn at 3, stop at 5): a shell command that already failed that many times in the session gets a one-time warning, then further runs of it are stopped. Successful runs do not reset it.
codeburn guard allowlifts all three stops (hard cap, loops, retries) for that session only, for example when you poll a CI job on purpose.- Loop and retry warnings reach both you and the agent. When one fired, the end-of-turn note says how many calls it was and what the calls after the warning cost.
- Session openers: projects where optimize found waste get a one-line flag at session start.
Caps are edited in ~/.config/codeburn/guard.json as softUSD, hardUSD, checkpointUSD, loopWarnAfter, loopStopAfter, retryWarnAfter and retryStopAfter (set a value to null to disable it). Add --statusline to show session cost in the Claude Code status line. Installs go through the same journal as everything else, so codeburn act undo removes them too. Hooks fail open: a broken guard never blocks a session.