Hermes Agent stuck in a tool loop

What you see

Hermes keeps running the same command or re-reading the same file, polls a background process over and over, or sits on one step with no visible progress. In a messaging app the bot goes quiet mid-task, or a scheduled job never finishes.

Likely causes

An agent turn is a loop of model calls and tool calls that ends when the model decides it's done. If it never reaches that point, or a single tool call never returns, the turn appears stuck. Usually the agent is either waiting on something outside its control or retrying a goal it can't satisfy.

• The goal is ambiguous or unachievable, so the model keeps trying variations.
• A command is waiting for input it will never get (an interactive prompt, a pager, sudo on the gateway, which has no terminal).
• A long-running command or background process is still going, and the agent is waiting on it.
• An approval prompt is waiting for an answer; unanswered prompts are denied after the timeout (300 seconds by default).
• A subagent is still running in the background, or hit its own iteration limit.
• The provider stream has stalled.

Check this first

• Is there a pending approval prompt? In chat, answer with /approve or /deny.
• In the CLI, watch the tool progress lines; ~/.hermes/logs/tool_calls.log is used when display.tool_progress is set to log.
• Ask the agent to run process(action="list") or check background processes, if it started any.
• /status to confirm the model and provider; tail ~/.hermes/logs/gateway.log for gateway turns.
• For subagents, check their live transcripts or ask the parent to list its children.

Fix

First, stop the turn:

• CLI: Ctrl+C stops the current operation (pressing it twice within 2 seconds forces an exit), or type /stop to cancel the turn and its foreground work.
• Messaging: send /stop. Ordinary follow-up messages redirect the turn by default but do not cancel background children; /stop does.
• Redirect instead of stopping: with display.busy_input_mode set to steer, your message is injected after the next tool call, which is a gentle way to say 'stop retrying that, try X'.

Prevent it next time

• Cap tool-calling iterations per turn with agent.max_turns in config.yaml or --max-turns <N>. When the budget runs out the agent gets one grace call to wrap up.
• Keep terminal.timeout (180 seconds by default) sensible, and run genuinely long jobs in the background so the agent can be notified on completion rather than polling. Hermes already switches to completion notifications if it polls a silent process twice in a row.
• Cap subagents with delegation.max_iterations (default 250) and, if needed, delegation.child_timeout_seconds for inactivity.
• agent.session_stall_timeout (300 seconds by default) is a notify-only watchdog that tells you when a session stalls.
• Avoid interactive commands; ask for non-interactive flags, and don't rely on sudo through the gateway.
• Write clearer goals with a stopping condition: 'try at most two approaches, then report what failed'.

If it still fails

If the gateway itself has frozen, its watchdog exits the process when the event loop stalls so the service supervisor restarts it; hermes gateway restart does the same deliberately. Note that a restart does not resume running subagents, so rerun those tasks. If a particular model repeatedly loops on tool calls, test the same prompt in a fresh session with another model; the docs' Nous Portal guide, for example, notes that Hermes-4 models are chat models not suited to agent loops.

Related guides

• Hermes Agent subagents and delegation explained
• Hermes Agent scheduled job didn't run
• Hermes Agent task denied when scheduled
• Hermes Agent rate limits and provider errors

Spotted something wrong or out of date? Tell us on X at @HermesWatcher↗ (opens in a new tab) and we will fix it.

New Hermes Agent updates every day on X. Follow @HermesWatcher