Skip to content

Anti-fixation ​

Anti-fixation stops an agent from grinding one failing method as if it were the only method. A PostToolUse hook counts how many times the same thing has failed the same way this session, and once a count crosses its threshold it interrupts with a re-frame: name the assumption you're holding, the route you keep taking, and two routes that are not it. Three nudges on one key without a fix escalates to a light diverge run seeded with what has already been tried. It is the route half of the adherence pairing: task-anchor keeps the goal fixed while anti-fixation keeps the road to it from calcifying, and the rest of the time it says nothing at all, nothing lands in context until a bar is crossed.

In Practice ​

Three strikes on one file trip the nudge. You edit the same file against the same error three times and the error text never actually moves, digits and hex are stripped before comparing so line 42 and line 43 read as the same failure. On the third matching failure the hook prints the tier 1 text from nudge.md followed by a summary line:

signal file_error, 3 strikes on one key this session, nudge 1

Check what it's been counting. The detector is silent by design, so status is the only window into it:

nu .claude/anti-fixation/anti-fixation.nu status

Fresh in a session, before anything has failed, the tail of that output reads exactly:

nothing counted yet this session

Once something has struck, the same command lists the live keys sorted by count, and how many have already escalated.

The nudge doesn't shift it, so it escalates. The same key gets nudged escalate_after times (default 3, which with the shipped cooldown: 2 lands around the seventh actual strike) and escalate is still true in signals.nuon. The hook prints escalate.md instead of nudge.md, which walks you through kicking off a light diverge run seeded with the routes already tried:

nu .claude/workflows/frames.nu select --mode light

That escalation fires once per key per session; the same key nudges from then on and never escalates a second time.

Move a threshold while you're tuning it. Rather than hand-editing signals.nuon:

nu .claude/anti-fixation/anti-fixation.nu tune file_error 4

An example outcome. file_error now fires at 4, and every other key's tuning is untouched.

The Hook ​

detect.nu ​

The PostToolUse observer - matched on Edit|Write|MultiEdit|Bash. A recursion guard exits immediately when HARNESS_HOOKS_OFF is set to 1, so a harness hook further up the chain that already spawned this Claude process doesn't get counted again by its own child. Past that guard it reads signals.nuon, decides whether the tool result actually failed (a structured success/is_error/interrupted field first, then an anchored error-pattern match on the response text as a fallback), builds one candidate key per signal that's on, and tallies each in state/<session id>.nuon. Only the first candidate to cross its own threshold gets to speak in a given turn. It fails open at every step: an unreadable payload, config, or state file just exits 0 rather than blocking the session.

The Driver and Command ​

anti-fixation.nu ​

The /anti-fixation engine - status, on, off, reset, and tune subcommands, all reading or writing signals.nuon and this session's state/<session id>.nuon and nothing else. status is the one you want most, since it's the only way to see the tallies the detector keeps invisible.

commands/anti-fixation.md ​

The slash command - wraps the driver script, status with no verb is the default, and explains what each field in the status output means for tuning.

Config and Templates ​

signals.nuon ​

The tuning registry - project owned, so an --update never resets it. Carries the master switch (enabled), the escalation settings (escalate, escalate_after, ask_first, cooldown, decay_turns, decay_minutes), and the signal rows themselves. Adding a signal is a row here, never a code edit.

nudge.md ​

The tier 1 text - asks for the assumption being held, the route being repeated described as an approach rather than as individual attempts, and two genuinely different routes, then to pick one and say why.

escalate.md ​

The tier 2 text - instructs a light diverge run seeded with the problem (never the current approach) and every route already burned, and falls back to working the tier 1 questions by hand if diverge isn't installed.

settings-fragment.json ​

The hook wiring - registers detect.nu as a PostToolUse hook matched on Edit|Write|MultiEdit|Bash. An install alone wires nothing; the fragment only takes effect once it's merged into the project's settings.json, which is what harness hooks (press w) does.

Signal Registry ​

The shipped rows in signals.nuon, each tuned on its own:

SignalShipsThresholdCatches
file_erroron3Same file edited against the same error, the primary fixation case.
test_idon3Same test failing, keyed on the test id rather than its output text.
error_stringoff4Same error text anywhere, broad and prone to false trips on generic messages.
tool_signatureon3Same tool called with the same args, a re-run that changed nothing.

The State Files ​

state/<session id>.nuon is detect.nu's per-session tally, generated and disposable, reset just deletes the calling session's and reset --all deletes every one. One file per session, named for the id rather than holding it - a single shared state.nuon meant two sessions working the same project blanked each other's counts every time they interleaved, so no key ever reached its threshold. A tally left behind by a session that's gone is reaped on the next session's first turn. Each file holds:

{ session: <id>, turn: <n>, keys: [...], escalated: [...] }

Each entry in keys is { key, count, nudged, nudges, last, at }: count is strikes, nudges is how many times the nudge itself has fired on that key (the number escalate_after counts against), and last/at are the turn number and unix timestamp used for decay. A key drops once decay_turns (default 40) or decay_minutes (default 30) has passed since its last strike, whichever bites first, and a successful call clears any open file_error or tool_signature key for that same file or command outright, since a pass carries no error text to match against.

Connects to ​

  • Paired with Task Anchor under the adherence group - anchor holds the original ask and its done criteria, anti-fixation holds the route toward it, a re-frame is never licence to solve a different problem.
  • Escalation is a soft dependency on diverge - escalate.md runs a light diverge workflow, and without the part installed the module says so once and runs the nudge tier only.
  • Its hook only takes effect once settings-fragment.json is merged by harness hooks, an install alone leaves it wired but silent.
  • The condensed, end-user version of this page is the module's own USAGE.md, at harness/modules/adherence/anti-fixation/USAGE.md - that one is the thin command, config, and gotcha reference, this page is the fuller depth of the same part.