> ## Documentation Index
> Fetch the complete documentation index at: https://openrouter.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Doom-Loop Detection

> Detect and act on agent runs that repeat the same tool calls, server-tool requests, or text without making progress.

## Overview

Sometimes an agent gets stuck. It tries the same tool call, gets the same result, and tries again anyway, like a robot vacuum bumping into the same wall forever. That's a doom loop: the run keeps spending money without getting anywhere.

Doom-loop detection watches for this inside the `callModel` tool loop. It's **off by default**. Turn it on with `doomLoop: true`:

```typescript theme={null}
const result = callModel(client, {
  model: 'openai/gpt-4o',
  input: 'Research this topic',
  tools: [searchTool, bashTool] as const,
  doomLoop: true, // recommended defaults: observe@2, block@3, stop@6
  // or tune it:
  // doomLoop: {
  //   ladder: { observe: 2, steer: false, block: 3, stop: 6 },
  //   text: { minRepeats: 4 }, // or `false` to disable text detection
  // },
});

// Was the run stopped by detection?
const verdict = await result.getDoomLoopVerdict();
if (verdict) console.warn(verdict.message);
```

```python title="Python" lines theme={null}
import asyncio
import json
import os

from pydantic import BaseModel
from openrouter_agent import OpenRouter, HookEntry, HookName, HooksManager, call_model, step_count_is, tool


class SearchInput(BaseModel):
    query: str


class BashInput(BaseModel):
    command: str


search_tool = tool(
    name="search",
    description="Search the web for a query",
    input_schema=SearchInput,
    execute=lambda params, ctx: {"results": [f"No results for {params.query}"]},
)

bash_tool = tool(
    name="bash",
    description="Run a shell command",
    input_schema=BashInput,
    execute=lambda params, ctx: {"stdout": "", "exit_code": 0},
)

# The Python agent SDK has no built-in doom_loop option yet, so detect
# repeated identical tool calls with a PreToolUse hook and block them.
# The hook sees one call at a time with no turn boundary, so every identical
# call counts, including duplicates in one model response. That is stricter
# than the built-in detector, which counts a repeat once per turn.
BLOCK_AT = 3  # block the 3rd identical call in a row
streak: dict[str, tuple[str, int]] = {}  # tool name -> (last input, repeat count)
verdict: dict | None = None


def detect_doom_loop(payload, ctx):
    global verdict
    name = payload.get("tool_name") or payload.get("name")
    args = payload.get("tool_input", payload.get("input", payload.get("arguments")))
    key = json.dumps(args, sort_keys=True, default=str)
    last_key, count = streak.get(name, ("", 0))
    count = count + 1 if key == last_key else 1  # a changed input resets the tool's streak
    streak[name] = (key, count)
    if count >= BLOCK_AT:
        verdict = {"tool": name, "repeats": count}
        return {"block": f"Doom loop: {name} called {count} times with the same input. Try something different."}
    return None


hooks = HooksManager()
hooks.on(HookName.PreToolUse.value, HookEntry(handler=detect_doom_loop))


async def main() -> None:
    client = OpenRouter(api_key=os.environ["OPENROUTER_API_KEY"])
    result = call_model(
        client,
        {
            "model": "openai/gpt-4o",
            "input": "Research this topic",
            "tools": [search_tool, bash_tool],
            "hooks": hooks,
            "stop_when": step_count_is(6),  # hard stop as a backstop
        },
    )
    text = await result.get_text()

    # Was a doom loop detected?
    print("Doom-loop verdict:", verdict)
    print("Final text:", text)


asyncio.run(main())

```

```go title="Go" lines theme={null}
// Doom-loop detection around the tool loop (observe@2, block@3, stop@6)
messages := []Message{{Role: "user", Content: "Research this topic"}}
// canonical normalizes arguments, so reordered fields or extra whitespace still match.
canonical := func(args string) string {
	var v any
	dec := json.NewDecoder(strings.NewReader(args))
	dec.UseNumber() // keep large integer IDs exact; float64 would merge distinct ones
	if err := dec.Decode(&v); err != nil {
		return args // invalid JSON still counts: compare the raw text
	}
	b, err := json.Marshal(v) // object keys come out sorted
	if err != nil {
		return args
	}
	return string(b)
}
streak := map[string]int{} // "tool\x00input" -> turns in a row with that call
verdict := ""
for i := 0; verdict == "" && i < 20; i++ {
	msg := chat("openai/gpt-4o", messages, []any{searchTool, bashTool})
	messages = append(messages, msg)
	if len(msg.ToolCalls) == 0 {
		break
	}
	turn := map[string]bool{}   // calls already counted in this turn
	called := map[string]bool{} // tools the model used in this turn
	for _, tc := range msg.ToolCalls {
		name := tc.Function.Name
		key := name + "\x00" + canonical(tc.Function.Arguments)
		called[name] = true
		if !turn[key] { // identical calls in one turn count once
			turn[key] = true
			streak[key]++
		}
		// Decide before dispatch, so a blocked or stopped call never runs.
		var result string
		switch n := streak[key]; {
		case verdict != "":
			result = "Not run: the run was stopped."
		case n >= 6:
			verdict = fmt.Sprintf("Doom loop: %s repeated %d times, run stopped", name, n)
			result = "Stopped: doom loop detected."
		case n >= 3:
			result = "Blocked: identical call repeated. Try a different approach."
		default:
			if n >= 2 {
				log.Printf("observe: %s repeated %d times", name, n)
			}
			result = runTool(name, tc.Function.Arguments)
		}
		messages = append(messages, Message{Role: "tool", ToolCallID: tc.ID, Content: result})
	}
	// Changing a tool's input resets its streak. Other tools in between do not.
	for key := range streak {
		if name, _, _ := strings.Cut(key, "\x00"); called[name] && !turn[key] {
			delete(streak, key)
		}
	}
}

// Was the run stopped by detection?
if verdict != "" {
	log.Println(verdict)
}
```

```text title="Output" theme={null}
Doom-loop verdict: None
Final text: What topic would you like me to research?
```

It watches for three kinds of stuck:

1. **Repeating a call to one of your tools.** The model calls a tool you defined in `tools` with the same inputs, turn after turn. Broken calls count too: a model that keeps sending empty `{}` or invalid JSON is just as stuck.
2. **Repeating a request to an OpenRouter server tool.** Server tools like web search run on OpenRouter's side, not in your code, so you never see the call. The detector still catches a model running the exact same web search every turn.
3. **Repeating the same text.** A phrase repeating at the end of one response, or a response that's identical to the previous one.

## How repeats are counted

Each time the model repeats itself, its streak grows by one. The rules for counting are simple and predictable: the same transcript always produces the same result.

A repeat only counts when the model saw the result and tried the same thing again. So if the model fires five identical calls at once in a single turn, that counts as one, not five. Using other tools in between doesn't reset a tool's streak. Changing the inputs does.

## What happens as the streak grows

You set a threshold for each action you want. When the streak reaches a threshold, that action fires, and the strongest one wins:

| Action | Effect |
| - | - |
| `observe` | Take notes only: emit the `DoomLoopDetected` hook so you can see it happened |
| `steer` | Nudge the agent with a message before its next turn, telling it it's repeating itself (off by default) |
| `escalate` | Call in help: run the next turn on a stronger model and/or a forced `openrouter:advisor` consult, then switch back (off by default; needs an `escalation` config) |
| `block` | Refuse to run the repeated call. The model gets an error explaining why, so it can change course. Text and server-tool repeats can't be blocked (they already happened); those fall through to the strongest weaker action you've enabled (`escalate`, `steer`, or `observe`) |
| `stop` | End the run before it wastes more money (`SessionEnd.reason: 'doom_loop'`). Any unfinished tool calls get clean error outputs, so the saved conversation stays valid and can be resumed |

The SDK checks your thresholds make sense and warns about combinations that can't work. For example, `block` without `stop` means a stubborn model can keep retrying the blocked call forever (bounded only by `stopWhen`), and a weaker action set at a higher threshold than a stronger one can never fire.

Want different behavior for one tool? The `DoomLoopDetected` [lifecycle hook](https://openrouter.ai/docs/agent-sdk/call-model/lifecycle-hooks.md) sees every verdict and can override the action per event (`overrideAction`, last handler wins). Downgrade a block to observe for a tool you know repeats harmlessly, or jump straight to stop.

## Getting unstuck with a stronger model

Instead of just blocking a stuck agent, you can give it help. With `escalate`, the next turn runs on a smarter model, then switches back to the cheap one:

```typescript theme={null}
const result = callModel(client, {
  model: 'z-ai/glm-5.2', // the everyday executor
  input: 'Research this topic',
  tools: [searchTool] as const,
  doomLoop: {
    ladder: { observe: 2, escalate: 3, block: 5, stop: 8 },
    escalation: {
      // Either or both:
      model: 'anthropic/claude-opus-4.6', // run the NEXT turn on a stronger model
      advisor: true, // and/or force an openrouter:advisor consult
      maxEscalations: 2, // spend cap for the whole conversation
    },
  },
});
```

```python title="Python" lines theme={null}
# The Python agent SDK has no built-in doom_loop option yet, so emulate the
# ladder (observe@2, escalate@3, block@5, stop@8) with a PreToolUse hook.
# A hook cannot switch models inside a run, so escalation here is a separate
# follow-up run on a stronger model, not the next turn of the stuck run.
LADDER = {"observe": 2, "escalate": 3, "block": 5, "stop": 8}
EXECUTOR = "z-ai/glm-5.2"  # the everyday executor
ESCALATION_MODEL = "anthropic/claude-opus-4.6"  # consulted in a follow-up run
MAX_ESCALATIONS = 2  # spend cap for one research() call


def make_detector():
    # One detector per research() call, so a second call starts with fresh
    # streaks, a fresh escalation budget, and no verdict.
    streak: dict[str, tuple[str, int]] = {}  # tool name -> (last input, repeat count)
    state = {"escalate": False, "escalations": 0, "verdict": None}

    def detect_doom_loop(payload, ctx):
        name = payload.get("tool_name") or payload.get("name")
        args = payload.get("tool_input", payload.get("input", payload.get("arguments")))
        key = json.dumps(args, sort_keys=True, default=str)
        last_key, n = streak.get(name, ("", 0))
        # A changed input resets the tool's streak. The hook has no turn boundary,
        # so duplicates in one model response each count (see the first example).
        n = n + 1 if key == last_key else 1
        streak[name] = (key, n)
        if n >= LADDER["stop"]:
            # The hook only records the verdict. It is read after call_model returns,
            # and the step limit on the call is what ends the run.
            state["verdict"] = {"tool": name, "repeats": n}
        if n >= LADDER["block"]:
            return {"block": f"Doom loop: {name} repeated {n} times. Try something different."}
        if n >= LADDER["escalate"] and state["escalations"] < MAX_ESCALATIONS:
            state["escalate"] = True
            return {"block": "Stuck: escalating to a stronger model."}
        return None

    hooks = HooksManager()
    hooks.on(HookName.PreToolUse.value, HookEntry(handler=detect_doom_loop))
    return hooks, state


async def research(client, prompt="Research this topic"):
    hooks, state = make_detector()
    opts = {"input": prompt, "tools": [search_tool], "hooks": hooks}
    text = await call_model(client, {**opts, "model": EXECUTOR, "stop_when": step_count_is(LADDER["stop"])}).get_text()
    while state["escalate"] and state["verdict"] is None:
        state["escalate"] = False
        state["escalations"] += 1
        # Follow-up run: the stronger model gets the prompt and the stuck run's last
        # answer, not its tool history. Its advice then goes to a new executor run.
        stuck = f"{prompt}\n\nA previous attempt got stuck repeating a tool call and ended with:\n{text}"
        hint = await call_model(client, {**opts, "input": stuck, "model": ESCALATION_MODEL, "stop_when": step_count_is(1)}).get_text()
        text = await call_model(client, {**opts, "input": f"{prompt}\n\nAdvice: {hint}", "model": EXECUTOR, "stop_when": step_count_is(LADDER["stop"])}).get_text()
    return text

```

```go title="Go" lines theme={null}
// Escalation ladder around the tool loop (observe@2, escalate@3, block@5, stop@8)
const executor, stronger = "z-ai/glm-5.2", "anthropic/claude-opus-4.6"
messages := []Message{{Role: "user", Content: "Research this topic"}}
// canonical normalizes arguments, so reordered fields or extra whitespace still match.
canonical := func(args string) string {
	var v any
	dec := json.NewDecoder(strings.NewReader(args))
	dec.UseNumber() // keep large integer IDs exact; float64 would merge distinct ones
	if err := dec.Decode(&v); err != nil {
		return args // invalid JSON still counts: compare the raw text
	}
	b, err := json.Marshal(v) // object keys come out sorted
	if err != nil {
		return args
	}
	return string(b)
}
streak := map[string]int{} // "tool\x00input" -> turns in a row with that call
verdict := ""
escalateNext, escalations := false, 0
for i := 0; verdict == "" && i < 20; i++ {
	model := executor // the everyday executor
	if escalateNext && escalations < 2 { // maxEscalations: spend cap for the whole conversation
		model = stronger // run the NEXT turn on a stronger model, then switch back
		escalations++
	}
	escalateNext = false
	msg := chat(model, messages, []any{searchTool})
	messages = append(messages, msg)
	if len(msg.ToolCalls) == 0 {
		break
	}
	turn := map[string]bool{}   // calls already counted in this turn
	called := map[string]bool{} // tools the model used in this turn
	for _, tc := range msg.ToolCalls {
		name := tc.Function.Name
		key := name + "\x00" + canonical(tc.Function.Arguments)
		called[name] = true
		if !turn[key] { // identical calls in one turn count once
			turn[key] = true
			streak[key]++
		}
		// Decide before dispatch, so a blocked or stopped call never runs.
		var result string
		switch n := streak[key]; {
		case verdict != "":
			result = "Not run: the run was stopped."
		case n >= 8:
			verdict = fmt.Sprintf("Doom loop: %s repeated %d times, run stopped", name, n)
			result = "Stopped: doom loop detected."
		case n >= 5:
			result = "Blocked: identical call repeated. Try a different approach."
		default:
			if n >= 3 {
				escalateNext = true // the stronger model sees the full message history
			} else if n == 2 {
				log.Printf("observe: %s repeated %d times", name, n)
			}
			result = runTool(name, tc.Function.Arguments)
		}
		messages = append(messages, Message{Role: "tool", ToolCallID: tc.ID, Content: result})
	}
	// Changing a tool's input resets its streak. Other tools in between do not.
	for key := range streak {
		if name, _, _ := strings.Cut(key, "\x00"); called[name] && !turn[key] {
			delete(streak, key)
		}
	}
}
```

When this fires, the engine tells the model a loop was detected, runs one turn with the extra help, then goes back to normal. `maxEscalations` caps how many times this can happen in a conversation, even across pauses and resumes. Once the budget runs out, the weaker actions take over.

## Telling the detector what counts as "the same": `loopKey`

By default, two calls count as the same when all their inputs match exactly. That default is sometimes wrong, so you can give each tool its own idea of "the same" with `loopKey`:

```typescript theme={null}
// Compute the identity. A web-search tool normalizes its query,
// so "Cats" and " cats " count as the same search.
tool({
  name: 'web_search',
  inputSchema: z.object({ query: z.string() }),
  loopKey: ({ query }) => query.trim().toLowerCase(),
  execute: async ({ query }) => search(query),
});

// Only some fields matter. A bash call is identified by the command
// AND where it runs; other fields (e.g. verbose) don't count.
tool({
  name: 'bash',
  inputSchema: z.object({
    command: z.string(),
    cwd: z.string(),
    verbose: z.boolean(),
  }),
  loopKey: ({ command, cwd }) => ({ command, cwd }),
  execute: async ({ command, cwd }) => run(command, cwd),
});

// false: never count this tool. Repetition is this tool's job.
tool({
  name: 'check_status',
  inputSchema: z.object({ jobId: z.string() }),
  loopKey: false,
  execute: async ({ jobId }) => poll(jobId),
});
```

```python title="Python" lines theme={null}
# The Python agent SDK has no loop_key option yet, so keep a per-tool
# key function next to each tool and use it in your PreToolUse detector.
class SearchInput(BaseModel):
    query: str

class BashInput(BaseModel):
    command: str
    cwd: str
    verbose: bool

class StatusInput(BaseModel):
    job_id: str

web_search = tool(name="web_search", input_schema=SearchInput,
                  execute=lambda p, ctx: search(p.query))
bash = tool(name="bash", input_schema=BashInput,
            execute=lambda p, ctx: run(p.command, p.cwd))
check_status = tool(name="check_status", input_schema=StatusInput,
                    execute=lambda p, ctx: poll(p.job_id))

LOOP_KEYS = {
    # Compute the identity: "Cats" and " cats " count as the same search.
    "web_search": lambda a: a["query"].strip().lower(),
    # Only some fields matter: command AND cwd; verbose doesn't count.
    "bash": lambda a: {"command": a["command"], "cwd": a["cwd"]},
    # False: never count this tool. Repetition is this tool's job.
    "check_status": False,
}


def loop_key(name, args):
    fn = LOOP_KEYS.get(name)
    if fn is False:
        return False
    identity = args  # default: all inputs must match
    if fn is not None:
        try:
            identity = fn(args)
        except Exception:
            identity = args  # a failing key function falls back to the full input
    return json.dumps(identity, sort_keys=True, separators=(",", ":"), default=str)

```

```go title="Go" lines theme={null}
// loopKey: how each tool decides two calls are "the same".
// Returns the call's identity, and false if the call should never count.
type loopKeyFn func(args string) (string, bool)

loopKeys := map[string]loopKeyFn{
	// Compute the identity. A web-search tool normalizes its query,
	// so "Cats" and " cats " count as the same search.
	"web_search": func(args string) (string, bool) {
		var in struct {
			Query string `json:"query"`
		}
		json.Unmarshal([]byte(args), &in)
		return strings.ToLower(strings.TrimSpace(in.Query)), true
	},

	// Only some fields matter. A bash call is identified by the command
	// AND where it runs; other fields (e.g. verbose) don't count.
	"bash": func(args string) (string, bool) {
		var in struct {
			Command string `json:"command"`
			Cwd     string `json:"cwd"`
		}
		json.Unmarshal([]byte(args), &in)
		key, _ := json.Marshal(in)
		return string(key), true
	},

	// false: never count this tool. Repetition is this tool's job.
	"check_status": func(string) (string, bool) { return "", false },
}

```

A function-form `loopKey` can return `null` to skip one specific call. If it fails in any way (returns `undefined`, throws, or returns something that can't be hashed), the SDK falls back to comparing all the inputs and logs a warning. Detection never crashes a run.

A field-name array (`loopKey: ['command', 'cwd']`) also works. Because it's plain data rather than code, it survives caching and can travel over the wire via `_meta['openrouter/loopKey']`. [MCP-wrapped tools](https://openrouter.ai/docs/agent-sdk/call-model/mcp-tools.md) accept a `loopKey` via `markMcp(tool, { loopKey })` or the `loopKeys` map on `createMCPTools`.

## Pausing and resuming

You don't need to worry about a model dodging detection with rearranged JSON keys or formatting changes, and a model stuck sending the same invalid JSON gets caught instead of bouncing off the parse error forever.

The detector's memory lives inside the conversation state, so streaks survive when you save and resume a conversation, as long as your resuming call also passes `doomLoop`. You can clear a `stop` verdict by sending a fresh user message, but the streaks stay, so you'll still catch a model that goes right back to repeating.

> [!NOTE]
>
> The SDK treats built-in `task`-tool calls as internal: they're exempt from doom-loop detection. See [Async Tools](https://openrouter.ai/docs/agent-sdk/call-model/async-tools.md).

## What this doesn't catch

* **Loops with changing inputs.** If the model invents a fresh timestamp or random value each call, the calls never look "the same". You can fix this per tool with a `loopKey` that picks out the fields that matter.
* **Saying the same thing in different words.** Text detection needs exact repeats. Rephrasing the same idea doesn't trip it.
* **Inputs changed by hooks.** Repeats are judged on what the model sent, before any `PreToolUse` hook rewrites it. A hook can't create repeats that weren't there, and can't hide ones that were.
* **Calls your own code executes.** Manual and client-executed calls pause the loop and aren't counted. Only calls the SDK ran, blocked, or failed to parse count as evidence.
