module LittleGhost::Agent::ToolLoop

Stop an agent from repeating a tool call that cannot make progress. Detection follows identical tool names, arguments, result status, and result content within one invocation.

class CustomerSupportAgent < LittleGhost::Agent
  detect_tool_loops warning_at: 3, terminate_at: 5,
    except: AccountRefreshTool
end

If a support model makes the same ineffective lookup three times, its third result includes a warning to change approach. A fourth repeat carries the final warning, and a fifth stops the run with ToolLoopError.

Detection is inactive until detect_tool_loops is declared. Exclusions may be tool classes, instances, names, or symbols. State is isolated per active invocation and guarded for concurrent tool batches; unfinished subagent waits do not count as repeated progress failures.

Only identical normalized arguments and results advance the counter. A changed result resets that sequence, while a terminating repeat prevents the duplicate tool body from running again.