feat(retrieval): the ledger records what was OPENED, not merely what was shown (#4100)

Milestone 386 made a repeat REFERENCED rather than withheld, and the line it
chose says "You saw it earlier this session". Nothing ever checked that. The
arms emit a TEASER — title, trigger, get_rule(N) — so a session can be shown a
rule twenty times and never read a word of it, and a compaction summarises the
teaser away leaving nothing behind. The server was asserting something about
the reader's context it had no way to know.

Three states now, where there were two:

  never surfaced   "it is not in this session's loaded set"
  named, unopened  "Mentioned earlier this session but not opened — read it…"
  opened           "You opened it earlier this session; pull it… again"

The middle one is the honest one and the one that was missing. It keeps the
full invitation, because a session that skipped a teaser is in nearly the
position of one never shown it.

HOW "OPENED" BECOMES OBSERVABLE. A new PostToolUse hook watches the get_rule
call itself and appends to `<sid>.opened.ids`. PostToolUse does fire for MCP
tools — the event's own output schema carries `updatedMCPToolOutput`, which
would be meaningless otherwise — and the matcher is `mcp__.*__get_rule` so the
server segment, which varies by install, is not pinned.

This is NOT the self-report 386 rejected. That objection was to ASKING a model
whether it holds a rule, which is unverifiable. A tool call is an event the
harness reports whether anyone asks. Recording what a session DID and believing
what it SAYS about itself are different kinds of evidence.

Both ledgers clear together on compact/clear. Keeping `.opened.ids` across a
compaction would have the arms telling a freshly-summarised session "you opened
it earlier" about a rule now nowhere in its context — a more confident version
of the bug being removed. Same reader (scribe_rules_live) for both, so ageing,
last-entry-wins and the bare-id format are defined once.

Also closes two smoke-coverage holes the checker was reporting as SKIP: the new
recorder, and scribe_precompact_preserve.sh from #3680. The latter needed
STATIC_FLOOR to become a set — PreCompact's contract is inverted, its stdout
BECOMES the summarizer's instructions, so silence is its failure mode and a
generic read of it looks like a leak.

Step 2 of milestone 416, and a hard prerequisite for step 4: while suppression
keys on shown, widening k marks records "seen" faster than they are read, and
the ledger would degrade in proportion to the improvement.

Plugin minted 2026.09.16.1232 -> 2026.09.16.2102.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy

src/scribe/routes/plugin.py

@@ -100,6 +100,13 @@ async def autoinject_retrieve():
                              purpose: one session keeps ONE rule ledger, so a
                              rule named by any arm is not re-announced by
                              another. Ages out (#3751), so salience decays.
+        held_rule_ids      — comma-separated rule ids the session actually
+            (opt)            OPENED, observed from the `get_rule` call itself
+                             rather than claimed. A rule on exclude_rule_ids
+                             was NAMED; a rule here was READ, and the two say
+                             different things about what the reader holds —
+                             so they get different lines (#4100). Shares the
+                             ledger directory and the same clear-on-compact.
 
     TWO ARMS, TWO SETS OF GATES. Rules ride the same hook and the same query
     but nothing else: the notes menu can be disabled, thresholded and top-k'd
@@ -116,9 +123,10 @@ async def autoinject_retrieve():
     project_id, _repo, _unbound = await _project_scope()
     exclude_ids = _int_list(request.args.get("exclude_ids"))
     exclude_rule_ids = _int_list(request.args.get("exclude_rule_ids"))
+    held_rule_ids = _int_list(request.args.get("held_rule_ids"))
 
     rules = await plugin_ctx_svc.build_prompt_rule_hint(
-        g.user.id, q, project_id=project_id, exclude_rule_ids=exclude_rule_ids
+        g.user.id, q, project_id=project_id, exclude_rule_ids=exclude_rule_ids, held_rule_ids=held_rule_ids
     )
     result = await plugin_ctx_svc.build_autoinject_hint(
         g.user.id, q, project_id=project_id, exclude_ids=exclude_ids
@@ -157,14 +165,20 @@ async def pre_tool_rules():
                                   ledger on purpose: one session keeps one
                                   list, so a rule named by either arm is not
                                   re-offered by the other.
+        held_rule_ids (opt)     — rule ids the session actually OPENED, as
+                                  against merely named. Named and read are
+                                  different claims about the reader's
+                                  context, so they get different lines
+                                  (#4100).
     """
     tool = (request.args.get("tool") or "tool").strip()
     command = request.args.get("command") or ""
     project_id, _repo, _unbound = await _project_scope()
     exclude_rule_ids = _int_list(request.args.get("exclude_rule_ids"))
+    held_rule_ids = _int_list(request.args.get("held_rule_ids"))
     result = await plugin_ctx_svc.build_tool_rule_hint(
         g.user.id, tool, command,
-        project_id=project_id, exclude_rule_ids=exclude_rule_ids,
+        project_id=project_id, exclude_rule_ids=exclude_rule_ids, held_rule_ids=held_rule_ids,
     )
     return jsonify(result)
 
@@ -202,6 +216,9 @@ async def write_path_prior_art():
                              above, and for the same reason: a rule named
                              twenty turns ago should not be re-offered on
                              every subsequent write.
+        held_rule_ids (opt)  — RULE ids the session actually OPENED, as
+                             against merely named; drives the third
+                             reference wording (#4100).
         exclude_derive (opt) — comma-separated derive keys (a derive group id
                              or `canon:<snippet_id>`) already named this
                              session by the ledger arm (#2900); its own
@@ -225,6 +242,7 @@ async def write_path_prior_art():
         p.strip() for p in (request.args.get("exclude_derive") or "").split(",") if p.strip()
     ]
     exclude_rule_ids = _int_list(request.args.get("exclude_rule_ids"))
+    held_rule_ids = _int_list(request.args.get("held_rule_ids"))
     shapes = _parse_shapes(request.args.get("shapes") or "")
     api_key = getattr(g, "api_key", None)
     may_stamp = api_key is None or getattr(api_key, "scope", "") == "write"
@@ -235,7 +253,7 @@ async def write_path_prior_art():
         stamp_shapes=shapes if may_stamp else None,
         repo_key=repo_bindings_svc.normalize_repo_key(repo) if repo else "",
         exclude_derive=exclude_derive,
-        exclude_rule_ids=exclude_rule_ids,
+        exclude_rule_ids=exclude_rule_ids, held_rule_ids=held_rule_ids,
     )
     return jsonify(result)
 

src/scribe/services/plugin_context.py

@@ -927,6 +927,7 @@ async def build_prompt_rule_hint(
     *,
     project_id: int = 0,
     exclude_rule_ids: list[int] | None = None,
+    held_rule_ids: list[int] | None = None,
 ) -> dict:
     """Rules and preferences that may apply to what the operator just asked.
 
@@ -985,6 +986,7 @@ async def build_prompt_rule_hint(
         duration_ms = (time.perf_counter() - t0) * 1000.0
 
         already = set(exclude_rule_ids or [])
+        held = set(held_rule_ids or [])
         fresh = [(score, rule) for score, rule in hits if rule.id not in already]
 
         # BEFORE the early return, for the reason both sibling arms spell out
@@ -1020,7 +1022,10 @@ async def build_prompt_rule_hint(
             return out
 
         lines = [
-            _rule_hint_line(rule, where="to this request", seen=rule.id in already)
+            _rule_hint_line(
+                rule, where="to this request",
+                seen=rule.id in already, held=rule.id in held,
+            )
             for _score, rule in hits
         ]
         # FRESH-ONLY (#3752). A reference is a rendering decision, not a
@@ -1297,7 +1302,9 @@ def _rule_band(hits: list) -> list:
     return [(s, r) for s, r in hits if s >= top - _RULEHINT_BAND]
 
 
-def _rule_hint_line(rule, *, where: str, seen: bool, compact: bool = False) -> str:
+def _rule_hint_line(
+    rule, *, where: str, seen: bool, held: bool = False, compact: bool = False,
+) -> str:
     """One rule hint line — both arms, both tails, both kinds (#3750, #3849).
 
     THREE INDEPENDENT AXES SINCE #3851. `compact` joins `kind` and `seen`, and
@@ -1380,13 +1387,37 @@ def _rule_hint_line(rule, *, where: str, seen: bool, compact: bool = False) -> s
         "for how this has been done before" if preference
         else "before deciding it does not apply"
     )
-    tail = (
-        f"You saw it earlier this session; pull it with get_rule({rule.id}) "
-        "if you no longer hold it."
-        if seen else
-        f"Read it with get_rule({rule.id}) {reason}; it is not in this "
-        "session's loaded set."
-    )
+    # THREE STATES, BECAUSE TWO OF THEM WERE BEING TOLD THE SAME LIE (#4100).
+    #
+    # `seen` means an arm NAMED this rule earlier. It does not mean the session
+    # read it — the line is a teaser, and a teaser skimmed past leaves nothing
+    # behind, least of all after a compaction summarises the turn it arrived
+    # in. "You saw it earlier this session" asserted something about the
+    # reader's context that the server had no way to know.
+    #
+    # `held` is the observable half: a PostToolUse hook watches for the
+    # `get_rule` call itself, so this is a recorded EVENT rather than a claim.
+    # That distinction is what keeps the non-goal above intact — the objection
+    # was to asking a model about its own context, not to noticing what it did.
+    #
+    # The middle state is the honest one and the one that was missing: named,
+    # not opened. It gets the full invitation, because a session that skipped
+    # the teaser is in almost the same position as one that never saw it.
+    if held:
+        tail = (
+            f"You opened it earlier this session; pull it with "
+            f"get_rule({rule.id}) again if you no longer hold it."
+        )
+    elif seen:
+        tail = (
+            f"Mentioned earlier this session but not opened — read it with "
+            f"get_rule({rule.id}) {reason}."
+        )
+    else:
+        tail = (
+            f"Read it with get_rule({rule.id}) {reason}; it is not in this "
+            "session's loaded set."
+        )
     if compact:
         # THE TRIGGER GOES; THE TAIL STAYS. Only one of the two is expensive \u2014
         # a trigger runs 300-400 characters after #3855, the tail about 100 \u2014
@@ -1421,6 +1452,7 @@ async def build_write_path_hint(
     repo_key: str = "",
     exclude_derive: list[str] | None = None,
     exclude_rule_ids: list[int] | None = None,
+    held_rule_ids: list[int] | None = None,
 ) -> dict:
     """Prior-art hint for the plugin's PreToolUse hook on Write/Edit.
 
@@ -1842,6 +1874,7 @@ async def build_write_path_hint(
     rule_ids: list[int] = []
     try:
         already = set(exclude_rule_ids or [])
+        held = set(held_rule_ids or [])
         # Timed like the notes arm above. Without this the rule row was the one
         # source in the whole readout reporting a null p90_duration_ms (#3311)
         # — a gap that reads as "this surface is somehow not measurable" rather
@@ -1867,6 +1900,7 @@ async def build_write_path_hint(
             lines.append(
                 _rule_hint_line(
                     rule, where="here", seen=rule.id in already,
+                    held=rule.id in held,
                     compact=idx > 0,
                 )
             )
@@ -1957,6 +1991,7 @@ async def build_tool_rule_hint(
     *,
     project_id: int = 0,
     exclude_rule_ids: list[int] | None = None,
+    held_rule_ids: list[int] | None = None,
 ) -> dict:
     """Standing rules that may apply to the ACTION about to be taken (#3476).
 
@@ -2011,6 +2046,7 @@ async def build_tool_rule_hint(
         duration_ms = (time.perf_counter() - t0) * 1000.0
 
         already = set(exclude_rule_ids or [])
+        held = set(held_rule_ids or [])
         # Band first, dedup second — see the sibling arm for why that order is
         # load-bearing rather than incidental.
         kept = _rule_band(hits)
@@ -2048,6 +2084,7 @@ async def build_tool_rule_hint(
             _rule_hint_line(
                 rule, where=f"to this {tool_name} call",
                 seen=rule.id in already,
+                held=rule.id in held,
                 # Rank decides volume (#3851): the ranker's best guess gets the
                 # trigger, the rest get cited.
                 compact=idx > 0,