Replace hard iteration limit with context-window bounding and loop detection

[drpedapati]

Summary

The current max_tool_iterations: 20 hard limit is too restrictive for complex tasks. It causes legitimate workflows to fail with "I've completed processing but have no response to give" before reaching their deliverable.

Current Behavior

// ~/.picoclaw/config.json
"agents": {
  "defaults": {
    "max_tool_iterations": 20
  }
}

After 20 tool calls, the agent stops regardless of task completion state.

Problem

A typical literature review task requires:

• 1-2 iterations: project setup
• 2-4 iterations: pubmed search
• 3-6 iterations: pubmed fetch (multiple batches)
• 2-4 iterations: data processing/analysis
• 2-4 iterations: document creation (docx-review)
• 1-2 iterations: verification

Total: 11-22 iterations minimum

The agent consistently exhausts 20 iterations on data gathering and never reaches the document creation step.

Evidence from Logs

iteration=19: pubmed fetch 41635784 41625329... --json > pubmed_fetch_more.json
iteration=20: python - <<'PY' ... (processing)
Response: I've completed processing but have no response to give.

The agent was still gathering data at iteration 20 - never got to docx-review create.

Proposed Solution: OpenClaw's Approach

OpenClaw has no hard iteration limit. Instead it uses:

1. Context Window Bounding

context_window: 150000  # tokens

The agent runs until it hits token limits, then compacts. This naturally limits iterations based on actual resource usage.

2. Loop Detection (Optional)

loop_detection:
  enabled: true
  repeat_threshold: 3      # warn after 3 identical calls
  critical_threshold: 6    # hard stop after 6 identical calls

This catches infinite loops without penalizing legitimate complex workflows.

3. Compaction on Overflow

compaction_mode: safeguard

When context fills, compact the conversation rather than failing.

Why This Is Better

Approach	Hard Iteration Limit	Context + Loop Detection
Complex tasks	❌ Fails at 20	✅ Runs to completion
Infinite loops	❌ Wastes 20 iterations	✅ Caught at 3-6 repeats
Resource efficiency	❌ Arbitrary cutoff	✅ Based on actual usage
User experience	❌ "No response to give"	✅ Completes or explains why

Suggested Implementation

1. Deprecate max_tool_iterations or set default to 200+
2. Add loop_detection config with repeat/critical thresholds
3. Add context window tracking with compaction support
4. Environment variable: PICOCLAW_LOOP_DETECTION_ENABLED=true

Acceptance Criteria

• Agent can complete a 30+ iteration task (literature review → Word doc)
• Infinite loops are detected and stopped within 6 iterations
• Context overflow triggers compaction, not failure
• Existing max_tool_iterations config still works (for users who want hard limits)

[harshbansal7]

Interesting and pretty useful and definitely required. Well documented as well👍

[nikolasdehor]

Strong proposal. The hard iteration limit is indeed the wrong abstraction for bounding agent execution. I have direct experience with this from OpenClaw, which moved away from iteration limits to context-window bounding + loop detection a while ago, and it made a significant difference for complex workflows.

A few implementation considerations for PicoClaw specifically:

1. Loop detection granularity

Comparing full tool calls for repetition is not enough. The agent can loop with slightly different arguments each time (e.g., incrementing a page number endlessly, or retrying a failing web_fetch with minor URL variations). The detection should hash on (tool_name, normalized_args) where normalization strips things like timestamps, UUIDs, and pagination params:

type LoopDetector struct {
    history []string // ring buffer of recent tool call hashes
    window  int      // lookback window size
}

func (ld *LoopDetector) Check(toolName string, args map[string]interface{}) LoopStatus {
    hash := hashToolCall(toolName, normalizeArgs(args))
    count := 0
    for _, h := range ld.history {
        if h == hash {
            count++
        }
    }
    ld.history = append(ld.history, hash)
    if len(ld.history) > ld.window {
        ld.history = ld.history[1:]
    }
    switch {
    case count >= 6:
        return LoopCritical // hard stop
    case count >= 3:
        return LoopWarning  // inject warning into context
    default:
        return LoopNone
    }
}

2. Context-window bounding vs. token counting

PicoClaw currently does not count tokens in the conversation (it relies on the provider to reject when context is full). Adding a token estimator is not trivial — different models have different tokenizers. A practical middle ground: track message character count as a rough proxy (1 token ≈ 4 chars for English) and trigger compaction at ~80% of the estimated context window.

3. Backward compatibility

Keep max_tool_iterations working but add a deprecation warning. Users who explicitly set it to 200 should not have loop detection override them. The priority should be: loop_detection.critical_threshold (if enabled) > max_tool_iterations (if set) > context window limit.

4. Compaction integration

This feature depends on having working history compression (#475). If compression itself introduces bugs (orphaned tool pairs), the agent will fail at compaction time. So fixing #475 should be a prerequisite for this feature.

This would be a substantial but high-impact change. I would suggest implementing it incrementally: (1) loop detection first, (2) configurable iteration limit increase, (3) context-window bounding with compaction.

[hum-ma]

It would be really good to have loop detection which first reminds the model that the previous runs have been too similar, and then stops pretty soon if it doesn't recover.

Looping issue also here: #819

[webpolis]

There is this tiny MCP https://github.com/cyqlelabs/mcp-dual-cycle-reasoner which may help avoiding loops.

[drpedapati]

Migrated to drpedapati/sciclaw#114 — was opened on upstream repo by mistake.