Most cost gates for agent/LLM workflows check a delta: did this PR make the run more expensive than the last one, by more than X%? That's a good regression alarm. But it answers a developer's question ("did I make it worse?"), not a budget owner's question ("are we going to blow the monthly number?").
Those are genuinely different gates, and a team that only has the percentage one keeps getting surprised. A workflow can pass every percentage check — each PR adds a harmless-looking 3% — and still cross the line where the absolute monthly spend stops being okay. Percentages compound quietly; dollars are what shows up on the invoice.
So the second gate I want on any agent workflow is an absolute ceiling: "a single run of this job must not cost more than $N," full stop, regardless of whether it went up or down since yesterday.
Three things make that gate actually usable rather than theater:
1. The ceiling is priced, not token-counted. "Under 2M tokens" is meaningless to the person who signs off on spend, because a token of Opus output and a token of cached Haiku input differ by ~100× in price. The gate has to multiply each token bucket (input, output, cache-write at ~1.25×, cache-read at ~0.1×) by that model's real per-token price and sum to an actual dollar figure. If your gate reports tokens and makes a human convert, nobody converts, and the ceiling drifts.
2. The ceiling is per-run and per-workflow, not global. A nightly full-repo audit and a per-PR lint agent have wildly different legitimate costs; one global number is either too loose for the small job or too tight for the big one. You want to set max-usd
on the specific workflow, so each job carries the ceiling that matches what it's for.
3. It shows the headroom, not just pass/fail. "$0.43 of a $0.50 ceiling — 86%" on every run is the line that lets you move the limit before it starts failing builds, instead of discovering the wall by hitting it. A gate that only says "blocked" the first time you cross is a gate people rip out.
The percentage gate and the dollar gate aren't competitors — I run both. The percentage one catches the sudden regression (someone pasted a 50k-token fixture into the prompt); the dollar one catches the slow one (the workflow that was always a bit expensive and finally crossed what the budget can absorb). Different failure modes, and the second is the one your finance owner will actually ask you about.
If you want it off the shelf: wartzar-bee/ci-guardrail
is an Apache-2.0 GitHub Action (built on @wartzar-bee/tokenscope
) that prices token usage into real dollars per run and can gate on an absolute max-usd
ceiling as well as a delta — so you can wire the "don't exceed $N per run" check straight into the workflow that needs it. But the mental model is the point whatever tool you reach for: a percentage answers the developer's question, a dollar ceiling answers the budget owner's.
For those of you already gating agent cost: do you gate on the relative delta, an absolute dollar ceiling, or both — and if you had to pick one to start with, which caught more real problems for you?