Claude Code Recursion Loop Reveals Silent Cost Surge and Tool Design Fixes

July 2025 saw a Claude Code instance enter a silent recursion loop that consumed 1.67 billion tokens in five hours, generating an estimated $16 k–$50 k in API charges before detection. The agent never crashed or threw an error; it simply kept calling tools, each call producing ambiguous or silent results that prompted another call. The article explains that such loops arise when a tool result is ambiguous, fails silently, returns conflicting information, or the model misreads its own output. To prevent this, the author recommends making every tool result self‑describing with fields like status, search_id, query_summary, total_matches, is_complete, and next_action_hint.

The self‑describing example shows a status of “success”, a unique search_id, a query_summary echo of the user’s parameters, and a results array that includes currency. The is_complete flag signals that the search is finished, while next_action_hint gives the agent a short instruction on the next step, such as presenting options or asking for new parameters. The article also provides a Python wrapper that automatically injects next_action_hint by deriving it from the result. By adopting these patterns, developers can avoid silent loops and ensure agents terminate correctly.