PR #13549: feat: tool loop detection and intervention

• Repository: NousResearch/hermes-agent
• Author: breca
• State: closed | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/13549

Description (problem / solution / changelog)

What does this PR do?

Small local models can get trapped in tool-calling loops when they miss key feedback in tool results. A model might call web_search(query="foo"), get "no results found", then call it again with the same args on the next turn, and keep repeating until all iterations are exhausted. The existing _deduplicate_tool_calls() only catches repeats within a single turn — it doesn't see cross-turn loops.

This adds cross-turn (tool_name, args_hash) tracking that detects when the model repeats the same tool call with the same arguments across turns. An escalation ladder progressively intervenes:

Related Issue

Inspired by NousResearch/hermes-agent#481 — "Tool-Call Loop Guard" proposal. This PR implements Phase 1 (basic repetition detection with SHA-256 hashing and escalation ladder). Phase 2 features (ping-pong detection, exempt tools list, context truncation recovery) are not included.

Addresses NousResearch/hermes-agent#13208 — the four core flaws identified there (loop detection failure, error pattern recognition, state persistence loss, resource waste) are directly addressed by the escalation ladder and re-prompt mechanism.

Type of Change

• ✨ New feature (non-breaking change that adds functionality)
• ✅ Tests (adding or improving test coverage)

Changes Made

• run_agent.py — added _hash_tool_args() and _check_tool_loop() methods, integrated into the main loop after _execute_tool_calls()
• hermes_cli/config.py — added agent.loop_detection config block with enabled, max_repeats_before_nudge, max_repeats_before_reprompt, max_repeats_before_stop
• tests/run_agent/test_tool_loop_detection.py — 24 unit tests covering hash normalization, full escalation ladder, independent counters, empty result exclusion, multi-tool turns, and edge cases

How to Test

1. Run the test suite: pytest tests/run_agent/test_tool_loop_detection.py -v — all 24 tests pass
2. Test with a small model that loops on repeated tool calls — the escalation should trigger at the configured thresholds
3. Verify config overrides work: set agent.loop_detection.max_repeats_before_nudge: 1 in ~/.hermes/config.yaml and confirm nudge triggers on the 2nd call

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass (55 pre-existing failures unrelated to this change; 14083 passed)
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Ubuntu 24.04

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — docstrings added to both new methods
• I've updated cli-config.yaml.example if I added/changed config keys — defaults in DEFAULT_CONFIG are sufficient, consistent with other auxiliary config sections
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — no platform-specific code
• I've updated tool descriptions/schemas if I changed tool behavior — N/A

Screenshots / Logs

When the loop detection triggers, the agent emits status messages like:

⚠️ Model repeated `web_search` — nudging to process results
⚠️ Model still repeating `web_search` — stronger warning
⚠️ Model stuck in tool loop — breaking for re-prompt
❌ Model entered tool loop calling `web_search` 6 times — terminated

Changed files

• hermes_cli/config.py (modified, +9/-0)
• run_agent.py (modified, +220/-0)
• tests/run_agent/test_tool_loop_detection.py (added, +351/-0)