Loop detector & iteration safety

The agent can occasionally get stuck in a tight loop — same tool, same error, over and over. InsightWorker has three guard rails to catch this before it burns through your token budget.

Guard 1: max iterations per run

Each agent run has a hard ceiling on the number of LLM↔tool round trips. Default: 40.

# In ~/.insightworker/.env:
MAX_AGENT_ITERATIONS=40

# For complex multi-step apps, raise:
MAX_AGENT_ITERATIONS=80

When the cap is hit, you see:

Agent stopped: reached MAX_AGENT_ITERATIONS (40). The task may be too complex for a single run, or the agent is stuck. Raise the limit if needed, or break the task into smaller steps.

See also troubleshooting/max-iterations.md.

Guard 2: loop detector (3 consecutive same-tool errors)

If the same tool fails 3 times in a row (regardless of input), the agent stops with:

Loop detected: tool 'jira_search' has failed 3 consecutive times. Last error: "401 Unauthorized". Stopping to avoid infinite retry. Fix the underlying issue and try again.

This catches the most common runaway pattern: agent hits an auth error, tries again, hits the same error, tries again, etc. It's a safety net — the right fix is to address the underlying error, not to disable the detector.

To disable for a specific case (rare):

LOOP_DETECTOR_ENABLED=false

Guard 3: per-tool output cap

Each tool's output is capped at ~10% of the active model's context window, so a single noisy tool can't blow out the conversation history.

Override per-tool:

MAX_TOOL_OUTPUT_LENGTH=20000   # global override (chars, not tokens)

When a tool's output is truncated, the agent sees a clear marker:

[output truncated at 80000 chars; original was 234112 chars]

For tools that paginate (sharepoint_search, jira_search), prefer narrowing the query over raising the cap.

Token budget visibility

In the CLI you can monitor cumulative token use per session with:

insightworker --debug-tokens

Or in VS Code, watch the status bar token counter.

See also

• auto-approve-tools.md — control which tools run without confirmation
• troubleshooting/max-iterations.md — full iteration troubleshooting
• troubleshooting/tool-failures.md — common tool errors

Source: docs/permissions-and-safety/loop-detector.md in the public repo. Open a PR with corrections.