Skip to main content

Class: ToolLoopDetector

Defined in: security/ToolLoopDetector.ts:109

Detects and prevents tool call loops with exponential backoff.

Example​

const detector = new ToolLoopDetector({ maxRepeatedCalls: 3 });

// First call: allowed
detector.check('web_search', { query: 'hello' });
// → { allowed: true, consecutiveCount: 1, loopDetected: false }

// Second identical call: allowed
detector.check('web_search', { query: 'hello' });
// → { allowed: true, consecutiveCount: 2, loopDetected: false }

// Third identical call: loop detected, backoff suggested
detector.check('web_search', { query: 'hello' });
// → { allowed: false, loopDetected: true, suggestedDelayMs: 2000 }

Constructors​

Constructor​

new ToolLoopDetector(config?): ToolLoopDetector

Defined in: security/ToolLoopDetector.ts:114

Parameters​

config?​

ToolLoopDetectorConfig = {}

Returns​

ToolLoopDetector

Methods​

check()​

check(toolId, args): LoopDetectionResult

Defined in: security/ToolLoopDetector.ts:132

Checks if a tool call should be allowed or if a loop is detected.

Parameters​

toolId​

string

The tool being called

args​

Record<string, unknown>

The tool arguments

Returns​

LoopDetectionResult

Detection result with backoff suggestion

getStats()​

getStats(): object

Defined in: security/ToolLoopDetector.ts:225

Gets statistics about the current session.

Returns​

object

historySize​

historySize: number

totalCalls​

totalCalls: number

uniqueTools​

uniqueTools: number

windowMs​

windowMs: number

record()​

record(toolId, args): void

Defined in: security/ToolLoopDetector.ts:205

Records a tool call without checking for loops. Used for tool calls that bypass loop detection (e.g., HITL responses).

Parameters​

toolId​

string

args​

Record<string, unknown>

Returns​

void

reset()​

reset(): void

Defined in: security/ToolLoopDetector.ts:217

Resets the detector state. Call this at session boundaries.

Returns​

void