Module behavior_nudge 

In-band behavior nudges + turn-economy telemetry.

tools health measured two waste patterns this module targets (#848 follow-up):

1. Heavy reads — explicit mode=full/raw dominated recorded ctx_read modes (62% at introduction time) while the structural modes (signatures/map) cover orientation at a fraction of the tokens.
2. Tool-call chains — ctx_search → ctx_read → ctx_search/ ctx_callgraph sequences that a single ctx_compose call bundles; every extra turn re-reads the whole conversation server-side.

The mechanism is one trailing hint line appended to a tool result at the moment of waste — in-conversation context outweighs static rules. Hints are budgeted hard: at most one hint per pattern per server process (~30 tokens each), gated by the behavior_nudges config key ("auto" default | "off"). Every detection is also counted in a small local store so tools health reports the pattern honestly even with hints off. Deterministic thresholds, local-only state, no network.

Functions

observe

Observes one dispatched tool call. Counts detections in the persistent store and returns a hint line to append at most once per pattern per session — None when there is nothing to say. can_show suppresses the hint (machine-readable or firewalled results) without burning the once-per-session budget; detections are counted either way. Called post-dispatch, so it must stay cheap: no I/O unless a (rare) detection fired.