Oscillation detector hook

Edit-thrashing is the failure mode where an agent’s last three edits cancel each other out — A → B → A again, often because two test fixtures disagree and the agent cannot pick a side. The oscillation detector hook fingerprints every edit as a transition hash (a cheap hash over samples of old_string and new_string) and, on each proposed Edit call, checks whether the reverse transition appears in that file’s recent history. If it does, the hook blocks the edit before it executes — the flip never lands.

The block message is engineered as a redirect, not a refusal: what is the root cause of the conflict? is there a solution that avoids toggling between these states? should you ask the user before proceeding? In practice the agent usually takes the third option — surfacing the contradiction it would otherwise have fought indefinitely. Operational details that matter: history is per-session (keyed by parent PID in a temp file), a reset window (default ten minutes) keeps old edits from counting as thrash, replace_all bulk refactors are exempt, and the hook fails open — any internal error allows the edit rather than breaking the loop it guards. The full implementation is public in our deep-dive post.

When we built this, we found no public implementation of the pattern in the Claude Code ecosystem. Step-count caps and token budgets are common; transition-hash reversal blocking is not. The term is ours.

When to use

• Long agentic sessions where token budget is at risk of being burned in a thrash loop.
• Test-first workflows where conflicting fixtures expose the agent to oscillation.

Distinguish from

A simple step-count guardrail caps total iterations regardless of usefulness. The oscillation detector specifically catches non-converging iteration — the agent making changes but not progressing.