@event4u/agent-config 16.2.0 → 16.4.0

package/src/scripts/hooks/block_config_weakening.ts

@@ -45,7 +45,18 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import * as yaml from 'js-yaml';
+// `yaml`, not `js-yaml`, and the choice is about the BUNDLE rather than about
+// this file. Every concern is inlined into one `dist/hooks/dispatch.js` that
+// every dispatch loads, and this import was the only `js-yaml` one left on that
+// path while six other modules — `dispatch_hook.ts` and `host_lowering.ts`
+// among them — already pulled `yaml`. Measured on 2026-10-01 from the esbuild
+// metafile: `js-yaml` contributed 95,846 bytes (6.13 %) of a 1,564,211-byte
+// bundle, paid on every hook event, for one call site. The behavioural delta is
+// normalised in `parseSettingsDoc` below — three constraints, each MEASURED
+// against the old reader rather than read off documentation — and pinned both by
+// the characterization tests written before the swap and by a differential test
+// that runs BOTH readers over one corpus and asserts the same refusal set.
+import { parseDocument as parseYamlDocument } from 'yaml';
 
 import {
     buildSettingsClassIndex,
@@ -115,12 +126,13 @@ const _PATH_KEYS: readonly string[] = ['file_path', 'path', 'target_file', 'file
 export type ConfigKind = 'allowlist' | 'advisory' | 'class-c' | null;
 
 /**
- * Project settings files whose keys this guard fences. User-global files are
+ * Project settings files, and the committed git-convention carrier (ADR-283),
+ * whose keys this guard fences. User-global files are
  * never in reach — the hook only sees a path a tool call named, and the writes
  * that reach `~/.event4u/` go through `settings:set`, which applies its own
  * per-key refusal.
  */
-const CLASS_C_BASENAMES: readonly string[] = ['.agent-settings.yml', '.agent-settings.yaml', 'settings.json'];
+const CLASS_C_BASENAMES: readonly string[] = ['.agent-settings.yml', '.agent-settings.yaml', '.git-convention.yml', 'settings.json'];
 
 /** Where the class contract lives, relative to the package root. */
 export const SETTINGS_CLASSES_RELATIVE = 'docs/contracts/settings-classes.md';
@@ -179,10 +191,64 @@ export function leafPaths(value: unknown, prefix = ''): Map<string, string> {
  * `null` is NOT "no keys changed" — the caller treats it as an unreadable
  * corpus and refuses, because a guard that allows whatever it cannot parse is
  * bypassed by making the file unparseable for one call.
+ *
+ * THE YAML READER IS CONSTRAINED, and all three constraints exist to keep the
+ * refusal set the same as `js-yaml`'s rather than to express a preference.
+ * Each was MEASURED against the old reader over a shared corpus, which the
+ * differential test re-runs; the equivalence is not argued from documentation.
+ *
+ *   · `schema: 'core'` + `resolveKnownTags: false` — WITHOUT THIS, THE SWAP
+ *     WOULD HAVE WEAKENED THE GUARD. `js-yaml` v5's default CORE schema does
+ *     not carry the YAML 1.1 tags, so `!!timestamp`, `!!binary`, `!!set`,
+ *     `!!omap`, `!!pairs` and any unknown `!custom` tag THREW — the document
+ *     was unparseable and the guard refused. The `yaml` package resolves them
+ *     by default, so the same document would have parsed and the guard would
+ *     have gone on to allow an edit it previously refused. Found by an
+ *     independent council review (openai/codex-default, 2026-10-01) and
+ *     confirmed by running both readers: six tagged inputs, `js-yaml` throws on
+ *     all six, default `yaml` returns a value for all six.
+ *   · A WARNING IS A REFUSAL. `yaml` reports an unresolvable tag as a warning
+ *     and keeps parsing where `js-yaml` throws, so treating warnings as success
+ *     would re-open the same hole one tag at a time. `parseDocument` is used
+ *     rather than `parse` precisely to see them.
+ *   · NULLISH IS UNPARSEABLE. `js-yaml` threw on an empty document and returned
+ *     `null` for a value-less one (`~`, `null`); both landed on refusal. `yaml`
+ *     returns `null` for all three instead of throwing on the first, so without
+ *     this collapse an EMPTIED settings file would arrive at the caller as a
+ *     parsed document with no keys — the one shape that turns "I cannot read
+ *     this" into "nothing changed".
+ *
+ *   · `merge: false` — PINNED, NOT FIXING AN OBSERVED DIFFERENCE. The `yaml`
+ *     package documents `merge` as defaulting to the document's YAML VERSION:
+ *     true for 1.1, false for 1.2. A second review round (openai/codex-default)
+ *     flagged that a `%YAML 1.1` directive could therefore re-enable merge
+ *     resolution past the schema pin, which would expose keys the old reader
+ *     left nested under a literal `<<`. Measured, and it does NOT reproduce
+ *     here — under `schema: 'core'` a `%YAML 1.1` document reads
+ *     `{"personal":{"<<":{…}}}` identically with and without this option, same
+ *     as `js-yaml`. It is set anyway because the cost is a word and the finding
+ *     named a real documented coupling between two options: a future default
+ *     cannot flip it silently. An option set without an observed failure behind
+ *     it is said so rather than implied.
+ *
+ * A merge key (`<<: *anchor`) was raised as a difference by the other seat and
+ * is NOT one: both readers leave `<<` literal at these versions, with and
+ * without a version directive. The same differential corpus pins both forms, so
+ * the question is settled by a reading rather than re-litigated from
+ * documentation next time.
  */
 export function parseSettingsDoc(text: string, rel: string): unknown | null {
+    if (rel.endsWith('.json')) {
+        try {
+            return (JSON.parse(text) as unknown) ?? null;
+        } catch {
+            return null;
+        }
+    }
     try {
-        return rel.endsWith('.json') ? (JSON.parse(text) as unknown) : yaml.load(text);
+        const doc = parseYamlDocument(text, { schema: 'core', resolveKnownTags: false, merge: false });
+        if (doc.errors.length > 0 || doc.warnings.length > 0) return null;
+        return (doc.toJS() as unknown) ?? null;
     } catch {
         return null;
     }
@@ -317,10 +383,25 @@ export interface Decision {
  * unreadable for the length of one tool call, which is a bypass with no
  * authorisation step in it.
  *
+ * The edit forms it models: `Write` (`content`), `Edit` (`old_string` /
+ * `new_string`, with `replace_all`) and `MultiEdit` (an `edits` list of those
+ * pairs, applied in order).
+ *
  * WHAT IT CANNOT SEE: an edit applied through a shell redirect rather than an
  * edit tool — `EDIT_TOOLS` is the corpus, and the shell shapes are
  * `block_plumbing_writes`' subject, not this one.
  */
+/** The host writes `new_string` verbatim; `String.replace` would expand `$&`-style tokens. */
+function _replaceFirstLiteral(text: string, from: string, to: string): string {
+    const at = text.indexOf(from);
+    return text.slice(0, at) + to + text.slice(at + from.length);
+}
+
+/** An empty `old_string` is the host's create form, which `split('')` does not model. */
+function _applyEdit(text: string, from: string, to: string, all: unknown): string {
+    return all === true && from !== '' ? text.split(from).join(to) : _replaceFirstLiteral(text, from, to);
+}
+
 export function classCVerdict(
     ti: JsonObject,
     on_disk: string | null,
@@ -332,11 +413,22 @@ export function classCVerdict(
     const content = ti['content'];
     const oldStr = ti['old_string'];
     const newStr = ti['new_string'];
+    const forms = [content !== undefined, oldStr !== undefined || newStr !== undefined, ti['edits'] !== undefined];
+    if (forms.filter(Boolean).length > 1) {
+        return (
+            `${rel_path}: this edit carries more than one edit form (content, old_string/new_string, edits), ` +
+            'so the guard cannot tell which one the host will run and no key can be cleared. ' +
+            'Re-send it as one form, or write the change through `agent-config settings:set`.'
+        );
+    }
+    // A file that does not exist yet is created by an edit with an empty
+    // `old_string`, so it is modelled as empty text rather than left unchecked.
+    const current = on_disk ?? '';
     let afterText: string | null = null;
     if (typeof content === 'string') {
         afterText = content;
-    } else if (typeof oldStr === 'string' && typeof newStr === 'string' && on_disk !== null) {
-        if (!on_disk.includes(oldStr)) return null; // the edit will not apply
+    } else if (typeof oldStr === 'string' && typeof newStr === 'string') {
+        if (!current.includes(oldStr)) return null; // the edit will not apply
         // `replace_all` is the host's own flag and it changes WHICH text the
         // edit produces. Modelling only the first occurrence let a
         // `replace_all` edit whose SECOND occurrence is the Class C one pass
@@ -352,7 +444,23 @@ export function classCVerdict(
                 '`agent-config settings:set`.'
             );
         }
-        afterText = all === true ? on_disk.split(oldStr).join(newStr) : on_disk.replace(oldStr, newStr);
+        afterText = _applyEdit(current, oldStr, newStr, all);
+    } else if (ti['edits'] !== undefined && !Array.isArray(ti['edits'])) {
+        return `${rel_path}: this MultiEdit carries an edit the guard cannot interpret, so the text it would produce is unknown and no key can be cleared. Re-send it as plain edits, or write the change through \`agent-config settings:set\`.`;
+    } else if (Array.isArray(ti['edits'])) {
+        // MultiEdit applies its pairs in order and applies none when one misses.
+        let text = current;
+        for (const e of ti['edits']) {
+            const o = _isObject(e) ? e['old_string'] : undefined;
+            const n = _isObject(e) ? e['new_string'] : undefined;
+            const a = _isObject(e) ? e['replace_all'] : undefined;
+            if (typeof o !== 'string' || typeof n !== 'string' || (a !== undefined && typeof a !== 'boolean')) {
+                return `${rel_path}: this MultiEdit carries an edit the guard cannot interpret, so the text it would produce is unknown and no key can be cleared. Re-send it as plain edits, or write the change through \`agent-config settings:set\`.`;
+            }
+            if (!text.includes(o)) return null;
+            text = _applyEdit(text, o, n, a);
+        }
+        afterText = text;
     }
     if (afterText === null) return null;
 

package/src/scripts/hooks/block_plumbing_writes.ts

@@ -5,10 +5,14 @@
  * road-to-a-kernel-that-guards-its-plumbing 1.2 — the other half of a
  * deliberate split, and the split is the whole design:
  *
- *   · plumbing SOURCES (`hook_manifest.yaml`, `host_lowering.yaml`, the
- *     `*-dispatcher.sh` trampolines, both hook budget files) are edited
- *     legitimately all the time. They carry a RECORD — the ADR-268 § 4
- *     ratification gate, path set extended by step 1.1 — not a deny.
+ *   · plumbing SOURCES are edited legitimately all the time. They carry a
+ *     RECORD — the ADR-268 § 4 ratification gate — not a deny. Which files
+ *     count is NOT listed here: it is `check_kernel_edit_ratified`'s
+ *     `PLUMBING_SOURCE_RE` plus the verdict-deciding modules of the
+ *     dispatcher's import closure (`derivedPlumbing`), computed at run time.
+ *     A copy of that list here drifted once already — it named the pattern
+ *     and missed the policy module a refactor moved out of the dispatcher —
+ *     so this header points at the set instead of restating it.
  *   · plumbing BUILD OUTPUTS have no legitimate hand edit at all. They carry a
  *     DENY, which is this file.
  *
@@ -24,8 +28,16 @@
  *   invisible in a source review.
  * - `hooks/hooks.json` — the host binding file, written by `condense.ts` via
  *   `task sync`. A hand edit here silently unbinds a guard.
+ * - `src/scripts/hook_manifest.json` and `src/scripts/hooks/host_lowering.json`
+ *   — the compiled plumbing tables, written by `compile_hook_manifest`
+ *   (road-to-blocking-severities 2.2). These are the ones the RUNTIME actually
+ *   reads: `dispatch_hook._load_yaml` and `host_lowering.resolveTable` serve
+ *   the compiled body in preference to the YAML whenever its fingerprint
+ *   matches, so an edited table is what every host is told about which concern
+ *   runs and which slot can refuse, while the reviewed YAML beside it still
+ *   says something else.
  *
- * Both are matched under any parent directory, because a consumer install
+ * All four are matched under any parent directory, because a consumer install
  * carries them under its own project root rather than under this repository's.
  *
  * WHAT STILL PASSES, and why that is not a hole.
@@ -94,15 +106,35 @@ function _isObject(v: JsonValue | undefined): v is JsonObject {
 export const PLUMBING_BUILD_OUTPUTS: readonly string[] = [
     'dist/hooks/dispatch.js',
     'hooks/hooks.json',
+    'src/scripts/hook_manifest.json',
+    'src/scripts/hooks/host_lowering.json',
 ];
 
 /**
  * Where each output comes from, printed in the deny so the reader is told what
  * to run instead of only what not to do.
+ *
+ * road-to-blocking-severities 2.2 added the two compiled tables. They are the
+ * same KIND of file as the first two — written by a build, never by hand — and
+ * until this step they were refused by nothing, which mattered more here than
+ * it would have for an ordinary generated artifact: `dispatch_hook._load_yaml`
+ * and `host_lowering.resolveTable` both serve the compiled body IN PREFERENCE
+ * to the YAML whenever its fingerprint matches, so an edited JSON is what every
+ * host is told about which concern runs and which slot can refuse.
+ *
+ * Their YAML sources stay OUT of this set and keep carrying a ratification
+ * record instead — a hand edit there is legitimate and is exactly how the
+ * plumbing is maintained. The split is the one the guard's header already
+ * draws: a deny for files with no legitimate hand edit, a record for files
+ * whose hand edits are the point.
  */
 const REGENERATED_BY: Readonly<Record<string, string>> = {
     'dist/hooks/dispatch.js': 'npm run build:hooks',
     'hooks/hooks.json': 'task sync',
+    'src/scripts/hook_manifest.json':
+        './scripts-run src/scripts/compile_hook_manifest --table manifest',
+    'src/scripts/hooks/host_lowering.json':
+        './scripts-run src/scripts/compile_hook_manifest --table host-lowering',
 };
 
 // Keys across platforms that carry the tool's target file path.

package/src/scripts/hooks/code_graph_context_hook.ts

@@ -31,10 +31,15 @@
  * "per-host `enforced_by` resolved from the table, not from a host name" means
  * in practice.
  *
- * Once per session (a latch keyed by session id), so it cannot nag.
+ * Once per distinct SEARCH TARGET, capped at five lines per session (step 2.2),
+ * so it cannot nag. It was once-per-session until step 2.1 added `Bash`: with
+ * shell searches in scope a single line covered the first `grep` of a session
+ * and nothing after it, which is the opposite of the problem — the state that
+ * matters is the state at the question being asked.
  * fail_closed: false — every error path returns allow; a context line must
  * never break a tool call.
  */
+import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -55,13 +60,127 @@ function isObject(v: unknown): v is JsonObject {
 interface ToolIntent {
     isSearch: boolean;
     isCodeRead: boolean;
+    /**
+     * What this call is ABOUT — a Grep/Glob pattern, a read path, or the search
+     * term of a shell search. The per-target latch key (step 2.2): the same
+     * question asked twice is one question, and a hook that answered it once
+     * has nothing to add the second time.
+     *
+     * Empty when the call is neither a search nor a code read, and never the
+     * raw command line of an arbitrary Bash call — see {@link bashSearchToken}.
+     */
+    target: string;
+}
+
+/**
+ * The shell search heads this hook recognises.
+ *
+ * A closed list on purpose. "Any Bash command might be a search" is the reading
+ * that makes the hook chatty — Risk-Register rank 2 — so a command whose head
+ * is not here is silent AND does not latch, exactly as a non-code `Read` is.
+ */
+const SEARCH_HEADS = new Set(['grep', 'rg', 'ag', 'find', 'ack', 'fd']);
+
+/**
+ * Short options that consume the NEXT word as their value.
+ *
+ * Without this the value is read as the search term: a completion review of
+ * step 2.1 measured `grep -A 5 foo` keying the latch on `"5"` and
+ * `rg -g *.ts alpha` keying on `"*.ts"` — which also silenced a second,
+ * genuinely different search behind the same glob. A latch keyed on an option's
+ * argument is worse than no latch: it collapses distinct questions onto one slot.
+ */
+const VALUE_TAKING = new Set([
+    '-A', '-B', '-C', '-m', '-e', '-f', '-g', '-t', '-T', '-d', '--include',
+    '--exclude', '--glob', '--max-count', '--after-context', '--before-context',
+    '--context', '--regexp', '--file', '--type', '--maxdepth', '--depth',
+]);
+
+/** Asking a tool for its own usage is not a search, and must not spend a slot. */
+const NOT_A_SEARCH = new Set(['--help', '-h', '--version', '-V', '--usage']);
+
+/** `find` carries its subject in `-name`, not in the first positional. */
+const FIND_SUBJECT = new Set(['-name', '-iname', '-path', '-ipath', '-regex']);
+
+/**
+ * The search term inside ONE pipeline segment, or `null`.
+ *
+ * Split out from {@link bashSearchToken} so a pipeline can be scanned segment
+ * by segment: `cat x | grep needle` is a search, and reading only the head of
+ * the whole command missed every one of them. The same review measured that.
+ */
+function segmentSearchToken(words: readonly string[]): string | null {
+    if (words.length === 0) return null;
+    let i = 0;
+    let head = (words[0] as string).split('/').pop() as string;
+    if (head === 'git') {
+        // `git -C <path> grep <term>` is the form this tree's own token-efficiency
+        // rule mandates, and a `words[1] === 'grep'` test missed all of it. Scan
+        // past git's own options to the subcommand.
+        let j = 1;
+        while (j < words.length && (words[j] as string).startsWith('-')) {
+            j += VALUE_TAKING.has(words[j] as string) || words[j] === '-C' ? 2 : 1;
+        }
+        if (words[j] !== 'grep') return null;
+        head = 'git grep';
+        i = j + 1;
+    } else if (SEARCH_HEADS.has(head)) {
+        i = 1;
+    } else {
+        return null;
+    }
+    const rest = words.slice(i);
+    if (rest.some((w) => NOT_A_SEARCH.has(w))) return null;
+    if (head === 'find') {
+        const at = rest.findIndex((w) => FIND_SUBJECT.has(w));
+        if (at !== -1 && at + 1 < rest.length) return strip(rest[at + 1] as string);
+    }
+    for (let k = 0; k < rest.length; k += 1) {
+        const w = rest[k] as string;
+        if (w.startsWith('-')) {
+            if (VALUE_TAKING.has(w)) k += 1; // its value is not the subject
+            continue;
+        }
+        return strip(w);
+    }
+    return head;
+}
+
+function strip(w: string): string {
+    return w.replace(/^["']|["']$/g, '');
+}
+
+/**
+ * The thing a shell search is searching FOR, or `null` when the command is not
+ * a structure search at all.
+ *
+ * Reads EVERY pipeline segment, not just the first: `cat x | grep needle` and
+ * `… | rg symbol` are searches, and they are the common shape. The first
+ * segment that is a search wins, so one line yields one latch key.
+ *
+ * `git grep` is the one two-word head and is resolved past git's own options.
+ * Failing a positional subject the key is the command's head, which collapses a
+ * flag-only search onto one slot rather than leaking a command line into a
+ * state file — and the key is stored as a digest in any case
+ * ({@link latchKey}).
+ */
+export function bashSearchToken(command: string): string | null {
+    for (const segment of command.split(/\||&&|;/)) {
+        const words = segment.trim().split(/\s+/).filter((w) => w !== '');
+        const hit = segmentSearchToken(words);
+        if (hit !== null) return hit;
+    }
+    return null;
 }
 
 /**
  * Best-effort read of the intercepted tool + its target from the envelope.
  *
- * Carried over from the nudge unchanged, and the manifest's `tools:` filter is
- * pinned against exactly this branch surface — Grep, Glob, Read.
+ * The manifest's `tools:` filter is pinned against exactly this branch surface
+ * — Grep, Glob, Read, Bash. `Bash` joined it in step 2.1 for the reason the
+ * step gives: the searches an agent actually runs in this tree are shell
+ * searches, so a matcher that saw only the structured search tools was watching
+ * the door nobody uses.
  */
 export function classifyTool(envelope: JsonObject): ToolIntent {
     const payload = isObject(envelope['payload']) ? envelope['payload'] : envelope;
@@ -71,13 +190,29 @@ export function classifyTool(envelope: JsonObject): ToolIntent {
     const ti = (isObject(payload['tool_input']) ? payload['tool_input'] : envelope['tool_input']) as
         | JsonObject
         | undefined;
-    const isSearch = name === 'Grep' || name === 'Glob';
-    let isCodeRead = false;
+    const silent: ToolIntent = { isSearch: false, isCodeRead: false, target: '' };
+
+    if (name === 'Grep' || name === 'Glob') {
+        const pat = isObject(ti) ? (ti['pattern'] ?? ti['query']) : undefined;
+        return { isSearch: true, isCodeRead: false, target: typeof pat === 'string' ? pat : name };
+    }
     if (name === 'Read' && isObject(ti)) {
         const fp = ti['file_path'] ?? ti['path'];
-        if (typeof fp === 'string') isCodeRead = CODE_EXT.test(fp);
+        if (typeof fp === 'string' && CODE_EXT.test(fp)) {
+            return { isSearch: false, isCodeRead: true, target: fp };
+        }
+        return silent;
+    }
+    if (name === 'Bash' && isObject(ti)) {
+        const cmd = ti['command'];
+        if (typeof cmd !== 'string') return silent;
+        const token = bashSearchToken(cmd);
+        // Any other Bash command is silent AND does not latch: it consumed no
+        // slot, so the next real search still gets its line.
+        if (token === null) return silent;
+        return { isSearch: true, isCodeRead: false, target: token };
     }
-    return { isSearch, isCodeRead };
+    return silent;
 }
 
 function sessionId(envelope: JsonObject): string {
@@ -88,33 +223,117 @@ function sessionId(envelope: JsonObject): string {
 function latchFile(root: string): string {
     return path.join(root, 'agents', 'runtime', 'state', 'code-graph-context.json');
 }
-function alreadySpoke(root: string, session: string): boolean {
+
+/**
+ * At most this many context lines in one session (step 2.2).
+ *
+ * The cap is the chattiness bound, and it is the half that does not depend on
+ * the agent's behaviour: per-target alone is unbounded, because a session that
+ * greps thirty distinct symbols would hear thirty lines and the consumer would
+ * turn the hook off. Five is a stated default, not a measurement — a session
+ * that has been told the graph's state five times has been told.
+ */
+export const MAX_CONTEXT_LINES_PER_SESSION = 5;
+
+/** How many sessions the latch file retains before evicting the oldest. */
+export const MAX_SESSIONS_LATCHED = 200;
+
+/**
+ * What the latch file records for a target: a truncated digest, never the
+ * target itself.
+ *
+ * A council review of step 2.1 (2026-10-01, anthropic + openai) asked for one
+ * concrete thing before the shell tool was routed here — that command text is
+ * neither persisted nor carried into diagnostics. Routing on the shell tool
+ * makes the target a search TERM an operator typed, and a term can be a
+ * customer name, a token fragment or an internal hostname. Nothing downstream
+ * needs to read it back: the latch answers "have I spoken about this one", and
+ * equality over a digest answers that exactly as well.
+ *
+ * Not a security boundary and not claimed as one — a short digest of a short
+ * term is guessable by anyone who can enumerate terms. It is the same
+ * PII-exclusion-by-construction move `domain-safety-pii` § Surface 2 asks for:
+ * the file is shaped so the plaintext is not in it to leak.
+ */
+export function latchKey(target: string): string {
+    return createHash('sha256').update(target).digest('hex').slice(0, 16);
+}
+
+/**
+ * Should this target get a line, given what this session already heard?
+ *
+ * Pure, so the two rules it encodes can be tested without a filesystem: a
+ * repeat is silent at any count, and a NEW target is silent once the cap is
+ * reached. Takes the target in the clear and hashes here, so no caller can
+ * forget to.
+ */
+export function speaksFor(spoken: readonly string[], target: string): boolean {
+    if (spoken.includes(latchKey(target))) return false;
+    return spoken.length < MAX_CONTEXT_LINES_PER_SESSION;
+}
+
+function readLatch(root: string): Record<string, string[]> {
     try {
-        const state = JSON.parse(fs.readFileSync(latchFile(root), 'utf-8')) as Record<string, boolean>;
-        return state[session] === true;
+        const raw = JSON.parse(fs.readFileSync(latchFile(root), 'utf-8')) as Record<string, unknown>;
+        const out: Record<string, string[]> = {};
+        for (const [k, v] of Object.entries(raw)) {
+            // A pre-2.2 file stored `true` per session. Read it as "this session
+            // is done", which is what it meant — never as an empty list, which
+            // would hand an upgraded session a fresh budget it already spent.
+            if (Array.isArray(v)) out[k] = v.filter((x): x is string => typeof x === 'string');
+            else if (v === true) out[k] = Array.from({ length: MAX_CONTEXT_LINES_PER_SESSION }, (_, i) => `legacy:${String(i)}`);
+        }
+        return out;
     } catch {
-        return false;
+        return {};
     }
 }
-function latch(root: string, session: string): void {
+
+/**
+ * The cheap read-only half, so the `git status` probe behind `graphState` runs
+ * only for a call that could still produce a line (Risk-Register rank 3).
+ *
+ * Advisory only — {@link latchTarget} re-reads and remains the authority. A
+ * disagreement between the two can only come from a concurrent write, and it
+ * resolves toward silence, which is the safe direction for a context line.
+ */
+export function wouldSpeak(root: string, session: string, target: string): boolean {
+    return speaksFor(readLatch(root)[session] ?? [], target);
+}
+
+/**
+ * Decide and record in one step, because the two must not drift apart: a reader
+ * that says yes and a writer that records something else is how a cap leaks.
+ * Returns whether the caller may speak.
+ */
+export function latchTarget(root: string, session: string, target: string): boolean {
+    const state = readLatch(root);
+    const spoken = state[session] ?? [];
+    if (!speaksFor(spoken, target)) return false;
     try {
-        const p = latchFile(root);
-        let state: Record<string, boolean> = {};
-        try {
-            state = JSON.parse(fs.readFileSync(p, 'utf-8')) as Record<string, boolean>;
-        } catch {
-            /* fresh */
+        state[session] = [...spoken, latchKey(target)];
+        // Nothing prunes a finished session, so without this the file
+        // accumulated up to five digests per session id for the life of the
+        // repository — a review's finding, and the sibling instrument added in
+        // the same change caps itself and says why local-and-gitignored is not
+        // the same as free. Insertion order is the eviction order: the oldest
+        // session is the one least likely to speak again, and re-latching a
+        // dropped session costs one extra line, never a wrong answer.
+        const ids = Object.keys(state);
+        for (const old of ids.slice(0, Math.max(0, ids.length - MAX_SESSIONS_LATCHED))) {
+            if (old !== session) delete state[old];
         }
-        state[session] = true;
+        const p = latchFile(root);
         fs.mkdirSync(path.dirname(p), { recursive: true });
         fs.writeFileSync(p, JSON.stringify(state));
     } catch {
         /* fail-open: a persistence failure must not break the tool call */
     }
+    return true;
 }
 
 /**
- * The three-state staleness token this hook reports.
+ * The four-state staleness token this hook reports.
  *
  * Re-exported, not defined here: Phase 3's verbs must print the same token, and
  * an engine module importing this hook to learn it would invert the dependency
@@ -139,6 +358,13 @@ export function contextLine(state: GraphState): string {
             'grep is the other path — say which one answered.'
         );
     }
+    if (state === 'edited') {
+        return (
+            'code-graph: level with HEAD, but indexed files are edited in the working tree. ' +
+            'Relationship answers miss anything written since the last build — ' +
+            '`agent-config code-graph refresh` picks the edits up, or use grep and say so.'
+        );
+    }
     const n = state.slice('behind:'.length);
     return (
         `code-graph: ${n} commit(s) behind. Relationship answers may miss anything newer — ` +
@@ -160,11 +386,14 @@ export function main(): number {
     const pr = envelope['workspace_root'] ?? envelope['project_root'];
     const root = typeof cwd === 'string' && cwd ? cwd : typeof pr === 'string' && pr ? pr : '.';
 
-    const { isSearch, isCodeRead } = classifyTool(envelope);
+    const { isSearch, isCodeRead, target } = classifyTool(envelope);
     if (!isSearch && !isCodeRead) return EXIT_ALLOW;
 
     const session = sessionId(envelope);
-    if (alreadySpoke(root, session)) return EXIT_ALLOW; // once per session
+    // Once per distinct target, at most five per session (2.2). Checked BEFORE
+    // `graphState`, because that call now runs a `git status` probe and a line
+    // this session will not emit must not pay for one.
+    if (!wouldSpeak(root, session, target)) return EXIT_ALLOW;
 
     let state: GraphState;
     try {
@@ -176,7 +405,7 @@ export function main(): number {
     // so a session that builds a graph mid-flight still gets the line once.
     if (state === 'absent') return EXIT_ALLOW;
 
-    latch(root, session);
+    if (!latchTarget(root, session, target)) return EXIT_ALLOW;
     process.stdout.write(`${JSON.stringify({ decision: 'warn', reason: contextLine(state) })}\n`);
     return EXIT_WARN;
 }