Detect when agents are stuck in repetitive action loops using a rolling 20-action window with escalating nudges — replan after 3 similar actions, explore after 5, force-done after 8.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Detect when agents are stuck in repetitive action loops using a rolling 20-action window with escalating nudges — replan after 3 similar actions, explore after 5, force-done after 8.
Detects when an agent is stuck in a repetitive action loop by maintaining a rolling 20-action
history window. Compares recent actions using normalized similarity scoring and applies
escalating interventions before the agent wastes tokens or blocks progress.
Designed for any agentic context — browser automation, file editing, API calls, or
multi-step orchestration — not tied to any specific tool type.
When to Use
Invoke this skill when:
An agent task has been running for more than 10 steps without clear progress
The same tool is being called repeatedly with similar arguments
A task appears stalled with no TaskUpdate(completed) after a long sequence
You want proactive loop-prevention in a custom orchestrator
Skill({ skill: 'behavioral-loop-detection' });
The Iron Law
SAME ACTION × 3 = REPLAN
SAME ACTION × 5 = EXPLORE
SAME ACTION × 8 = FORCE-DONE
Never let an agent silently loop forever. Each repetition consumes tokens and produces no value.
Action History Window
Maintenance Rules
Keep a rolling buffer of the last 20 actions (FIFO — drop oldest when full)
Each entry in the buffer: { toolName, normalizedArgs, timestamp, stepIndex }
Reset the buffer only when a fundamentally different tool/action type appears
Never reset on argument variation alone (e.g., same tool, different file path = still similar)
Normalized Action Comparison
Two actions are similar when:
The toolName is identical, AND
The normalized argument string similarity score ≥ 0.75 (Jaccard over word tokens)
Normalization rules (apply in order):
Convert all values to lowercase
Strip file paths down to basename only (e.g., /a/b/file.ts → file.ts)
Remove timestamps, UUIDs (8-4-4-4-12 hex pattern), and numeric IDs
Sort object keys alphabetically before stringifying
At the start of task execution or when this skill is loaded, create the buffer:
Command:
const actionBuffer = {
window: [], // Array of last 20 action entriesmaxSize: 20,
similarRunLength: 0, // Current streak of similar actionslastNormalized: null, // Normalized args of last action
};
Expected output: In-memory buffer ready; no file I/O required unless persisting across sessions.
Verify:actionBuffer.window.length === 0 on initialization.
Step 2: Record Each Action
Before executing any tool call, append to the buffer:
Expected output:{ similar: boolean, runLength: number, score: number }
Verify:runLength increments only when score >= 0.75.
Step 4: Apply Escalation Rule
Evaluate the run-length and emit the appropriate intervention:
Command:
functionapplyEscalation(runLength, taskId) {
if (runLength >= 8) {
console.error(`[loop-detection] FORCE-DONE: ${runLength} similar actions. Task ${taskId}`);
return {
level: 3,
action: 'force-done',
message:
'Loop limit reached (8 repetitions). Mark this task complete with partial results and explain what was not accomplished.',
};
}
if (runLength >= 5) {
console.error(`[loop-detection] EXPLORE: ${runLength} similar actions. Task ${taskId}`);
return {
level: 2,
action: 'explore',
message:
'You have repeated a similar action 5 times. The current approach is failing. Try a completely different tool or method.',
};
}
if (runLength >= 3) {
console.error(`[loop-detection] REPLAN: ${runLength} similar actions. Task ${taskId}`);
return {
level: 1,
action: 'replan',
message:
'You have repeated a similar action 3 times. Stop and produce a revised plan before continuing.',
};
}
return { level: 0, action: 'continue', message: null };
}
When level === 3, the agent MUST stop and complete the task:
Command:
// In the agent's task loop, when applyEscalation returns level 3:TaskUpdate({
taskId: context.taskId,
status: 'completed',
metadata: {
summary:
'Task partially completed. Loop detected after 8 similar actions. ' + partialResultsSummary,
partial: true,
loopDetected: true,
loopDetails: {
runLength: runLength,
lastAction: buffer.lastNormalized,
bufferSnapshot: buffer.window.slice(-5),
},
},
});
Expected output: Task marked completed with partial: true metadata.
Verify:TaskList() shows the task as completed, not in_progress.
Enforcement Hooks
Input validated against schemas/input.schema.json before execution.
Output contract defined in schemas/output.schema.json.
Pre-execute hook at hooks/pre-execute.cjs validates that taskId is provided.
Post-execute hook at hooks/post-execute.cjs emits a loop-detection event to tool-events.jsonl.
Integration Points
master-orchestrator: Integrate after each wave of agent spawns; check for stalled tasks
developer: Active during file-editing loops (same file edited 3+ times without test progress)
qa: Active during test-fix loops (same test file modified 3+ times without green)
planner: Active during re-planning loops (same plan section rewritten 3+ times)
Anti-Patterns
Never reset the buffer on every tool call — that defeats detection
Never apply force-done for level < 3 — nudges are sufficient at levels 1 and 2
Never compare raw unormalized args — path differences will mask real loops
Never skip the similarity check when toolName differs — tool variety alone ≠ not looping
Memory Protocol (MANDATORY)
Before starting: Read .claude/context/memory/learnings.md for previously detected loop patterns.
After completing: If a loop was detected and force-done triggered, append to .claude/context/memory/learnings.md:
## Behavioral Loop Detection — [date]
- Task [taskId]: [toolName] looped [N] times. Final normalized args: [args].
- Root cause hypothesis: [explain why the agent got stuck]
- Recommendation: [what to change in the task prompt or approach]
After issues: Append to .claude/context/memory/issues.md if force-done fires more than twice in a session.
Related Skills
verification-before-completion — Pre-completion gates that prevent false success
judge-verification — Independent LLM judge that verifies task completion
error-recovery-escalation — 5-level error recovery before force-done
context-compressor — Compress context when loop detection fires repeatedly
