[v2] Cognitive Lattice: Build Loop Entropy Detector

[SHAURYASANYAL3]

Phase 4: Cognitive Lattice

The Context

Agents frequently get stuck in deterministic loops (e.g., read_file -> parse -> read_file). Instead of asking an LLM "is the agent stuck?", we can mathematically prove it by analyzing the entropy of the action sequence.

Tasks

• Implement LoopEntropyDetector.
• Extract the last N actions taken by the agent.
• Generate n-grams (bigrams/trigrams) of the action sequence and count repetitions using collections.Counter.
• Calculate Shannon entropy for the sequence. Low entropy means high repetition (a loop).
• Enforce an invariant threshold to block execution when entropy drops below a healthy level (e.g., < 1.5).

Part of Epic #651

[rohitkumarnaidu]

Hey maintainer, I'd love to work on this issue and submit a PR. Could you please assign it to me?

[rohitkumarnaidu]

Hi! Could you please add the ELUSOC label to this so it gets tracked properly by the dashboard? Thanks!

[arcgod-design]

Hi @SHAURYASANYAL3! I'd love to build the LoopEntropyDetector for AgentWatch v2 under SSoC '26. I'm @arcgod-design.

My Approach:

• Implement LoopEntropyDetector that extracts the last N tool-call/action names from the agent's execution history
• Generate bigrams and trigrams of the action sequence and count repetitions using collections.Counter
• Compute Shannon entropy over the n-gram distribution; low entropy = high repetition = likely loop
• Enforce a configurable invariant: emit WARNING when entropy drops near threshold (e.g., < 2.0) and BLOCKED when it drops below the hard floor (e.g., < 1.5)
• Write unit tests covering diverse action sequences (no block), mild repetition (warn), and tight loops (block)

Could you please assign this to me (@arcgod-design)? Ready to start immediately!

[prasiddhi-105]

Hiii please assign this issue to me under SSOC'26

[Aqsa30nz]

Hi @SHAURYASANYAL3! I'd like to work on this issue.

I've gone through the existing detector implementations (LoopDetector, RecursionDepthDetector, and the other safety modules) to understand the project's design patterns. My goal is to keep this detector consistent with the existing v2 architecture rather than introducing a new pattern.

My implementation plan:

• Implement a dedicated LoopEntropyDetector with a single responsibility for measuring repetition in recent agent actions.
• Consume AgentEvents and maintain a bounded sliding window of the latest N action signatures, similar to the existing detector implementations.
• Generate configurable bigrams/trigrams from the recent action history, compute their frequency distribution using collections.Counter, and calculate Shannon entropy deterministically.
• Keep entropy computation independent from policy evaluation so warning/block thresholds remain configurable without changing the statistical implementation.
• Handle edge cases such as short histories, empty buffers, and highly repetitive action sequences.
• Add comprehensive unit tests covering healthy action diversity, gradual repetition, deterministic loops, and threshold boundary conditions while following the existing testing style.

I'll keep the PR focused, deterministic, well-tested, and aligned with the current codebase without introducing unrelated changes.

If this approach aligns with the intended design, I'd be happy to work on this issue. Thank you!