An agent calls a tool. The tool throws an error. The agent calls the exact same tool, with the exact same arguments, again. And again. If you've shipped anything agentic — a coding agent, a data extraction pipeline, a multi-step research workflow — you've watched this happen and burned through a token budget doing nothing.

The fix isn't a better prompt. It's an architectural one. Once you move from single-shot generation to a multi-step loop, you're not writing a prompt anymore, you're writing a control system, and control systems need guards that don't depend on the thing they're guarding.

Why "is_finished: true" isn't a stopping condition

The instinct is to ask the model to tell you when it's done. Don't build your loop around that. An LLM has no real memory of its last ten iterations beyond whatever's still sitting in context, and once an earlier failure scrolls out of that window, the model has no idea it already tried this. It just tries again.

This shows up as three distinct failure modes, and they're worth naming separately because each needs a different fix:

• Tool invocation deadlocks — the agent calls a tool with bad arguments, gets an error, and retries the identical call with a trivial tweak that doesn't address the actual problem.
• State ping-ponging — the agent edits a file, tests it, reverts it, edits it again, forever, never converging.
• Budget runaways — no deadlock, no ping-pong, just an agent that burns thousands of tokens and tool calls without ever reaching a natural stopping point.

Trusting the model's self-reported completion status treats the symptom as the diagnosis. You need something outside the LLM's context that actually remembers what happened.

Catch repeated calls with a hash of what the agent already tried

Keep an execution history outside the model's context window. Before any tool call goes out, hash the tool name plus its sorted arguments, and check whether you've seen that exact combination before:

import crypto from 'crypto';

interface ToolExecution {
  toolName: string;
  args: Record<string, unknown>;
}

export class LoopGuard {
  private historyHashes: Map<string, number> = new Map();
  private maxRepeatThreshold: number;

  constructor(maxRepeatThreshold = 2) {
    this.maxRepeatThreshold = maxRepeatThreshold;
  }

  public registerAndValidate(exec: ToolExecution): boolean {
    const serialized = `${exec.toolName}:${JSON.stringify(exec.args, Object.keys(exec.args).sort())}`;
    const hash = crypto.createHash('sha256').update(serialized).digest('hex');
    const count = (this.historyHashes.get(hash) || 0) + 1;
    this.historyHashes.set(hash, count);
    return count <= this.maxRepeatThreshold;
  }
}

When registerAndValidate returns false, don't just silently drop the call. Intercept it and inject a blunt system message back into the agent's context — something like: "You've attempted this exact operation twice without success. Choose a different approach or ask for clarification." A vague nudge won't cut it here; the model needs to be told, explicitly, that the strategy it's on is a dead end.

This one technique kills the most common failure mode — the identical retry — but it does nothing for an agent that's technically trying different things while still going nowhere. That's what the next two layers are for.

Bound the loop with real limits, not vibes

Never run an agent loop as an unbounded while (true) gated only on the model deciding it's finished. You need three independent ceilings, and they should all fire even if the other two somehow don't:

1. A hard step cap. 10–15 iterations per subtask is a reasonable default. Past that, something's wrong.
2. A token budget. Track cumulative prompt and completion tokens across every turn in the loop. Hit your cap — say $0.50 or 150k tokens — and you cut it off with whatever partial result exists.
3. A wall-clock timeout. Use an AbortController to kill hanging tool connections after a fixed time, 120 seconds is a sane starting point.

async function runAgenticLoop(task: string, maxSteps = 12): Promise<AgentResult> {
  const abortController = new AbortController();
  const timeoutId = setTimeout(() => abortController.abort(), 120000);

  try {
    for (let step = 1; step <= maxSteps; step++) {
      const decision = await llm.planNextStep({ task, step, signal: abortController.signal });

      if (decision.isComplete) {
        return { status: 'SUCCESS', result: decision.output };
      }

      const executionAllowed = loopGuard.registerAndValidate(decision.toolCall);
      if (!executionAllowed) {
        decision.contextUpdate = "LOOP_DETECTED_FORCE_REVISE";
      }

      await executeTool(decision.toolCall);
    }
    return { status: 'BUDGET_EXHAUSTED', error: 'Max step limit reached without convergence.' };
  } finally {
    clearTimeout(timeoutId);
  }
}

Notice this is where the hash guard from the last section actually plugs in — registerAndValidate runs inside the bounded loop, not instead of it. The two are meant to work together, not as alternatives.

When the agent is stuck but not repeating itself

Here's the case the first two layers miss: the agent isn't calling the identical tool with identical args, and it hasn't blown through its step budget yet, but it's also not making progress. Same error, different phrasing. Same broken logic, slightly reworded.

At temperature = 0.0, greedy decoding means the model gives you the same answer to the same prompt every time — which is exactly the problem when that answer is wrong. Run your default iterations low, around 0.1, for consistency. But the moment you detect two consecutive steps with zero net progress (no new file, same error signature), bump the temperature to somewhere in the 0.5–0.7 range for a single turn. That's enough entropy to knock the model off the reasoning path it was stuck on. Then drop it back down.

It's a small thing, but it's the difference between an agent that fails the same way forever and one that eventually finds a different route.

The four layers together

None of these four is optional, and none of them substitutes for another. Skip the hash guard and you'll retry forever. Skip the budget caps and a genuinely novel-looking-but-still-stuck agent runs indefinitely. Skip temperature escalation and you'll cap out on a lot of subtasks that were one weird-token away from finishing.

The underlying principle is simple even if the implementation isn't: don't let the LLM decide when to stop trusting itself. That decision has to live outside the model, in code that doesn't hallucinate and doesn't forget.