Stop Repetitive Hermes Tool Loops with Guardrails

Hermes watches for three unproductive patterns: the same failing call repeated exactly, repeated failures from one tool with different arguments, and idempotent calls returning the same result without progress. Warnings are enabled by default so an interactive agent can change strategy.

For unattended gateways, cron tasks, and kanban workers, a warning may not be enough. Enable hard stops so the runtime blocks pathological repetition.

tool_loop_guardrails:
  warnings_enabled: true
  hard_stop_enabled: true
  warn_after:
    exact_failure: 2
    same_tool_failure: 3
    idempotent_no_progress: 2
  hard_stop_after:
    exact_failure: 5
    same_tool_failure: 8
    idempotent_no_progress: 5
  loop_caps:
    max_web_searches: 50
    max_subagents: 50

Understand the two protection layers

Failure thresholds look for repeated bad behavior. Per-turn caps place absolute ceilings on web searches and spawned subagents even when each individual call succeeds. A batched delegation counts each child, because the resource being bounded is actual subagents rather than tool invocations.

The counters reset on the next conversation turn. Set a cap to 0 only when unlimited behavior is intentional and separately controlled.

Configure by operating surface

• Interactive CLI or TUI: warnings may be sufficient because a person can steer or interrupt.
• Gateway or cron: enable hard stops and make failure delivery observable.
• Research workflow: allow enough searches for a legitimate evidence set, but keep a finite cap.
• Delegated development: budget by real child count and keep implementation separate from independent review.

Guardrail checklist

• Warnings remain enabled unless an equivalent policy exists.
• Unattended runs use hard stops.
• Search and subagent caps match realistic workload size.
• A blocked loop produces a visible failure report.
• The root cause is repaired instead of only raising thresholds.
• Expensive external tools have their own quotas and timeouts.

Common pitfalls

• Increasing every threshold after one block. First inspect whether the agent was truly making progress.
• Disabling caps for a broad research prompt. Split the work into bounded phases instead.
• Assuming a batch counts once. Each delegated task spends one unit of the subagent cap.
• Hard-stopping interactive work without notice. Make the reason visible so the operator can choose a new strategy.

Verification

Use a disposable tool or mocked failure to repeat an identical call past the warning threshold and confirm the warning appears. In an unattended test profile, cross the hard-stop threshold and verify the call is blocked and the run ends cleanly. Test the search or subagent cap separately, then restore ordinary values.

Official reference: Hermes configuration.