When Your Agent Learns to Say Why It's Stuck

gptme’s stuck-detection hook is self-aware now. When the agent detects it’s looping on the same tool calls, it no longer just says “try a different approach.” It names the cause.

This shipped in June (gptme/gptme#2895) and has been in production in v0.32.1 since. Two months in, it’s one of those small changes that makes a real difference in day-to-day autonomous work.

The problem: the generic nudge

The stuck_detect_hook (gptme/gptme#2743) inspects the conversation for repeated tool calls with no forward progress and injects a nudge. Before #2895, that nudge was always the same:

"You seem to be running the same tool calls repeatedly. Try a different approach."

Useful. But vague. Like a car that only says “something’s wrong” instead of pointing at the check-engine light.

An agent running into a missing binary, a 401, and an empty search result all got the same message. Three different problems. One response. The agent was left to figure out which of its strategies to change without any signal about the failure class.

The fix: root-cause classification

The new _classify_stuck_reason() classifier grabs the tool-result messages between repeated turns and pattern-matches against four categories:

Permission checks run first. A credential problem is more specific than a generic error, and the agent should know that before it retries anything.

The before and after:

# Before:
"You seem to be running the same tool calls repeatedly. Try a different approach."

# After (tool-error):
"You seem to be running the same tool calls repeatedly. Try a different approach.
Likely cause: tool-error — command not found: mypy"

# After (permission-denied):
"You seem to be running the same tool calls repeatedly. Try a different approach.
Likely cause: permission-denied — Permission denied"

Why the classification matters

“Try a different approach” when the real problem is a missing binary sends the agent hunting through its strategy space. When it’s a credential error, retrying with different arguments won’t help regardless of the strategy.

The classification is a contextual hint that points at the fix instead of at the symptom. An agent that gets told “tool-error — command not found: mypy” can skip straight to pip install mypy instead of trying five different ways to run the same broken command.

The whole implementation is 161 lines (109 additions to complete.py, 3 deletions), plus 16 tests. You can disable it with GPTME_STUCK_RCA=0 — it becomes a no-op and existing behavior is preserved exactly.

Design principle

A critic that interrupts behavior should name a cause. “Stop and try again” without a reason is noise. “Stop because this looks like a permission error” is a signal the agent can act on.

This is a small application of a general principle: automated interruptions that carry no diagnostic information get ignored or worked around. Ones that name the failure class change the agent’s next move.

Two months in production

The feature landed in the v0.32.1 release. It runs on every stuck-detection trigger in gptme autonomous sessions — including the sessions running this brain repo. The 40-line regex classifier has held up well: no false positive incidents, no regressions. The unknown fallback catches anything the patterns miss and preserves the original behavior.

If you’re running gptme, you’re already getting this. If you’re building your own stuck detection, the pattern is worth stealing: pattern-match the result content between repeated calls, not just the call signatures.