Loop detection
Catch a single agent run that's stuck repeating itself or blowing past a hard ceiling.
A budget rule limits spend over time. Loop detection is different — it watches one agent run (one trace) and steps in when that single run goes wrong: stuck repeating the same prompt, or running away past a hard ceiling. It's the Runaway loops tab on the Firewall page, with its own gallery at Catch a workflow stuck looping (app.tokenpolice.ai/firewall/loop/new).
A loop rule watches one trace, not a session or a conversation. A new agent run starts a
fresh watch with counters at zero. To cap a whole conversation, use a normal firewall rule that
groups by session_id — see Filter vs apply-to.
The two detectors
TokenPolice ships exactly two loop detectors.
Exact prompt repeat
Catches retry storms — the same prompt going out over and over inside one trace. It fingerprints each prompt's composition, so identical prompts produce identical fingerprints, and looks for a repeating cycle in the recent calls of that run.
| Setting | Range | Default |
|---|---|---|
| Window size — how many of the run's recent model calls to look at | 1–100 | 20 |
| Max cycle length — the longest back-and-forth pattern to look for | 1–5 | 3 |
| Repeats per cycle length — how many repetitions count as a loop | 2 or more, per length | 3 for length 1; 2 for lengths 2 and 3 |
With the defaults, the rule fires when the same prompt goes out 3 times in a row inside one run, or a 2-step prompt cycle repeats twice.
Per-trace hard cap
The circuit breaker: it stops one run from exceeding a ceiling, no matter why the run got expensive. You set a single threshold and its unit.
| Setting | Options |
|---|---|
| Threshold | A number |
| Unit | calls, USD, or tokens |
Alert, or stop the run
Each loop rule chooses what to do when it trips:
- Notify only — log it and alert you, but let the run continue.
- Block — stop a later model call on that run.
The stop lands late, by design. The product says it on every loop template: "The trigger is approximate — the call that crosses is allowed; we stop a later call on the same trace. Fast back-to-back calls can slip past." Treat a loop rule as a ceiling on runaway cost, not as an exact call counter.
When a loop rule blocks a call, your app receives a TokenPoliceBlockedError — the same exception
a budget block raises. If your users see a 429 or a 402, that is what your own HTTP API chose
to return when it caught the error; TokenPolice does not answer your users. See
Handling blocks.
Building one
The gallery groups four templates into two categories:
| Category | Template | You set |
|---|---|---|
| Going in circles | Stop the same request on repeat (most common) | Rule name; alert only, or block |
| Hard limits | Limit how many model calls one trace can make (most common) | Rule name; max calls per trace (default 25); alert or block |
| Hard limits | Limit how much one trace can spend | Rule name; max spend per trace (default $5); alert or block |
| Hard limits | Limit tokens per trace | Rule name; max tokens per trace (default 200,000); alert or block |
Templates default to alert only, and while they stay on alert only there is no When to turn it on step at all — the Dry-run / Enforce choice is hidden, because a notify rule has no enforcement mode to set. Switch the template's action to block and the Dry-run / Enforce control appears, to be set before you click Create rule. A blocking loop rule only stops calls when the rule is in Enforce and your app's SDK is in enforce mode; see Dry-run vs enforce.
You already have three
Every new workspace is provisioned with three loop rules on its Default Project, all set to notify only so they never stop anything:
| Rule | What it watches |
|---|---|
| Loop: Exact prompt repeat | The same prompt sent repeatedly within an agent run. |
| Loop: Per-trace call cap | A ceiling of 25 model calls in a single run. |
| Loop: Per-trace cost cap | A ceiling of $5.00 in a single run. |
They don't count against your plan's rule limit. Leave them alerting, retune them, or delete them.