Stop loops and budget burn: the free mid-run guards

The cheapest failure to fix is the one that never fully happens. A loop caught at step 4 costs nothing; the same loop caught at the step limit cost you 40 steps and a pile of tokens. Snapback's mid-run guards exist to catch trouble while the run is still cheap — and they're free.

detect_loop — break the cycle early

A repeating tool call is the most common way an agent burns a run. detect_loop takes your recent steps and tells you if the agent is going in circles:

detect_loop({steps: [
  {action:"web_search", inputs:{query:"X"}},
  {action:"web_search", inputs:{query:"X"}},
  {action:"web_search", inputs:{query:"X"}} ]})

// → { looping: true, offending_action: "web_search", suggestions: [...] }

It's free, needs no token, and uses no LLM — a deterministic check you can call on every step without thinking about cost. When it flags a loop, you break out, change strategy, or escalate, instead of grinding to the step limit.

budget_guard — see the wall before you hit it

Loops aren't the only runaway. Context fills up, tokens burn faster than expected, cost creeps past what the task is worth. budget_guard takes your counters mid-run and returns advisory warnings with severity and concrete next actions:

budget_guard({
  tokens_used: 8200, token_budget: 10000,
  cost_usd: 0.42, cost_budget: 0.50,
  step: 18, step_budget: 25 })

// → { warnings: [{type:"token_burn", severity:"critical",
//                 suggestions:[...] }] }

The live guardian — stream and get warned in real time

For a run you want watched continuously, open a live session and stream steps to it. Snapback returns loop and budget warnings inline as the run proceeds:

const {session_id} = session_start()
session_step(session_id, {action:"web_search", inputs:{query:"X"}},
             {tokens_used: 8000, token_budget: 10000})
// ... after 3 identical steps → { warnings: [{type:"loop", ...}] }
session_end(session_id)   // → { summary }

Free by design

These guards are free and unlimited for a reason: the high-frequency safety checks should never be a cost you weigh against calling them. You only pay when you ask for a full diagnosis of a failure that already happened. The guards are how you make sure fewer failures get that far.