@event4u/agent-config 12.0.0 → 13.0.0

package/src/scripts/hooks/concern_registry.ts

@@ -57,12 +57,14 @@ import { main as codeGraphNudgeMain } from './code_graph_nudge_hook.js';
 import { main as uiRouteNudgeMain } from './ui_route_nudge_hook.js';
 import { main as orchestrationRecordMain } from './orchestration_record_hook.js';
 import { main as delegationNudgeMain } from './delegation_nudge_hook.js';
+import { main as skillRouteMain } from './skill_route_hook.js';
 import { main as endReviewNudgeMain } from './end_review_nudge_hook.js';
 import { main as turnEndGateMain } from './turn_end_gate_hook.js';
 import { main as editShapeMain } from './edit_shape_hook.js';
 import { main as rereadGuardMain } from './reread_guard_hook.js';
 import { main as sessionEolMain } from './session_eol_hook.js';
 import { main as subagentLedgerMain } from './subagent_ledger_hook.js';
+import { main as toolResultBytesMain } from './tool_result_bytes_hook.js';
 import { main as spawnGuardShadowMain } from './spawn_guard_shadow_hook.js';
 
 /** A concern `main` — argv-taking or not; both shapes exist. */
@@ -103,11 +105,13 @@ export const CONCERN_REGISTRY: Readonly<Record<string, ConcernMain>> = {
     'src/scripts/hooks/ui_route_nudge_hook.ts': uiRouteNudgeMain as ConcernMain,
     'src/scripts/hooks/orchestration_record_hook.ts': orchestrationRecordMain as ConcernMain,
     'src/scripts/hooks/delegation_nudge_hook.ts': delegationNudgeMain as ConcernMain,
+    'src/scripts/hooks/skill_route_hook.ts': skillRouteMain as ConcernMain,
     'src/scripts/hooks/end_review_nudge_hook.ts': endReviewNudgeMain as ConcernMain,
     'src/scripts/hooks/turn_end_gate_hook.ts': turnEndGateMain as ConcernMain,
     'src/scripts/hooks/edit_shape_hook.ts': editShapeMain as ConcernMain,
     'src/scripts/hooks/reread_guard_hook.ts': rereadGuardMain as ConcernMain,
     'src/scripts/hooks/session_eol_hook.ts': sessionEolMain as ConcernMain,
     'src/scripts/hooks/subagent_ledger_hook.ts': subagentLedgerMain as ConcernMain,
+    'src/scripts/hooks/tool_result_bytes_hook.ts': toolResultBytesMain as ConcernMain,
     'src/scripts/hooks/spawn_guard_shadow_hook.ts': spawnGuardShadowMain as ConcernMain,
 };

package/src/scripts/hooks/orchestration_record_hook.ts

@@ -243,6 +243,27 @@ export function buildRecordInput(facts: DispatchFacts, ts: string, id: string):
 
     if (!facts.isAsync) {
         if (facts.resolvedModel) {
+            // road-to-inbox-harvest-2026-08-d-top-band-model-economy Step 1.1.
+            //
+            // The raw id goes into the field the schema already reserves for it
+            // ("the model id the provider reported SERVING"). Without it, a
+            // dispatch that ran on a band the three-tier vocabulary cannot
+            // express is byte-identical in the record to one where the host
+            // reported no model at all: `extractModelFamily` returns null for
+            // both, so `tiers` is omitted for both.
+            //
+            // That collapse is precisely what blocks ADR-035's reopen
+            // condition. "Did a vendor ship a band the three tiers cannot
+            // express" is answerable only if an unmapped id is distinguishable
+            // from an absent one, and recording the served id separates them:
+            // unmapped ⇒ `model_served` set with `tiers` absent; unreported ⇒
+            // both absent.
+            //
+            // Vendor-neutral by construction: the id is stored verbatim as an
+            // opaque host string. No band above `high` is named and no mapping
+            // is invented — naming a fourth band is the decision this
+            // measurement exists to inform, never one it may pre-empt.
+            input.model_served = facts.resolvedModel;
             const family = extractModelFamily(facts.resolvedModel);
             if (family) input.tiers = [family];
         }

package/src/scripts/hooks/skill_route_hook.ts

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+/**
+ * Skill route — `user_prompt_submit` concern
+ * (road-to-inbox-harvest-2026-08-d-runtime-skill-routing Phase 2).
+ *
+ * THE DEFECT THIS CLOSES. A deterministic task→skill ranker has shipped in
+ * this tree for months and is bound to nothing: `score_skill_relevance.rank`
+ * and its `suggest_skill_for_task` wrapper have no production caller, and
+ * `hook_manifest.yaml` had no concern that reached either. A capability that
+ * ships and never runs is indistinguishable from one that was never built —
+ * the same shape `delegation-nudge` was created to end for `classifyTask`, and
+ * this concern is deliberately its twin rather than a new mechanism.
+ *
+ * POINTERS, NEVER BODIES. The injected line names at most three skill IDs and
+ * their scores. It does not carry descriptions, excerpts, or file contents, and
+ * it never instructs the agent to load anything. The reason is the risk this
+ * roadmap's own register ranks first: a pointer line the agent trusts is worse
+ * than no line when the ranking is poor, so what is injected is the cheapest
+ * thing that can still be acted on — and the cheapest thing to ignore.
+ *
+ * SILENCE IS THE DEFAULT, AND BOTH FLOORS ARE MEASURED, NOT GUESSED. `rank`
+ * already drops every zero-scoring skill, but on real prompts it almost always
+ * returns SOMETHING, so "non-empty" is not a usable trigger. Measured over the
+ * routing-matrix corpus (496 prompt lines, `tests/eval/routing-matrix/*.yaml`,
+ * 2026-08-16): top-score median 18, p75 28, p90 30, max 70, and only 4 prompts
+ * score nothing at all.
+ *
+ * TWO floors are needed, because the score alone cannot express the failure at
+ * the short end. `MIN_TOP_SCORE` gates confidence; `MIN_TASK_TERMS` gates the
+ * denominator that confidence is computed over — the scorer divides by the task
+ * term count, so a one-term prompt scores 70/100 against whatever shares that
+ * term. Together they fire on 9.1 % of the corpus. A score floor at the median
+ * with no term floor would fire on half of all turns AND still hand 70/100 to
+ * `"fix it"` — the per-turn-reminder shape this estate has already measured
+ * failing at a 24/29 miss rate. Each constant carries its own derivation below.
+ *
+ * COST, MEASURED RATHER THAN ASSUMED. Ranking re-reads the skill catalogue per
+ * prompt, uncached. Measured 2026-08-16 on this tree: **12.3 ms warm** for a
+ * prompt that reaches the ranker, against the slot's 250 ms p95 budget — about
+ * 5 % of it. A prompt below `MIN_TASK_TERMS` costs **0 ms**, because the term
+ * floor is checked BEFORE the catalogue read; that ordering is deliberate and
+ * is what keeps conversational turns free. No cache is added: a cache would
+ * need an invalidation story for a tree that changes under the session, and
+ * 12.3 ms does not buy one.
+ *
+ * NO ADOPTION THRESHOLD IS COMMITTED HERE. Whether the line changes behaviour
+ * is a question for data, not for this header: `skill_route_pointer_rate` is
+ * registered in `hook-token-budget.json` under the same owner/review discipline
+ * as its sibling advisories, with the same kill standard — a nudge whose
+ * verdicts are measurably ignored gets its trigger tightened or its line
+ * removed. The score floor above is a TRIGGER calibration and is measured; the
+ * adoption threshold is an OUTCOME claim and is deliberately absent.
+ *
+ * DELIVERY PATH — the verified one, copied rather than re-derived. A
+ * `user_prompt_submit` concern returning `{decision:"allow", context:…}` at
+ * exit 0 produces zero stdout: `host_semantics.emitFor` drops the field for
+ * severity `"allow"`. The only shape that survives to
+ * `hookSpecificOutput.additionalContext` is `{decision:"warn", reason,
+ * additional_context}` at exit 2, which `emitFor` reduces to a real process
+ * exit of 0 — it never blocks the turn. `delegation_nudge_hook.ts` carries the
+ * full proof of that mechanism and this concern follows it exactly.
+ *
+ * PLATFORM SCOPE — `claude` only, for the same reason its twin gives:
+ * `host_semantics.VERIFIED_PLATFORMS` covers only `claude`, `cowork`'s
+ * trampoline discards dispatcher stdout unconditionally, and the other
+ * trampolines were never inspected for that property. Extending an exit-2
+ * delivery to an unverified propagation path is the speculative mapping
+ * `host_semantics.ts` exists to prevent.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { readHookStdin } from "./hook_stdin.js";
+import { isSyntheticPrompt } from "../_lib/prompt_shape.js";
+import { resolveSkillsRoot } from "../_lib/skill_catalogue.js";
+import { _tokenize, rank, type RankRow } from "../skill_tools/score_skill_relevance.js";
+
+const EXIT_ALLOW = 0;
+/** See the header: reduced to a real exit of 0 by `emitFor`'s warn branch. */
+const EXIT_WARN = 2;
+
+/**
+ * Minimum top-1 ranker score before this concern speaks.
+ *
+ * **31, not the measured p90 of 30, and the extra point is load-bearing.** The
+ * scorer is `overlap * 70 + personaHit * 30`, so a skill whose PERSONA slug
+ * appears in the prompt scores exactly 30 with zero keyword overlap. A floor of
+ * 30 with a `>=` test therefore admits a pure persona coincidence as if it were
+ * a ranked match. 31 is the smallest floor strictly above that value; it moves
+ * the corpus fire rate from 13.9 % to 9.1 %.
+ */
+export const MIN_TOP_SCORE = 31;
+
+/**
+ * Minimum distinct task terms before the score is trusted at all.
+ *
+ * The scorer divides by `|task_terms|`, so the score is inversely proportional
+ * to prompt length and degenerates at the short end: `"fix it"` tokenizes to
+ * ONE term and hands 70/100 to whichever skills happen to share it, which on
+ * this catalogue means the alphabetically first three. `MIN_TOP_SCORE` cannot
+ * fix that — the number is not too low, the denominator is too small.
+ *
+ * **3 is the routing-matrix corpus's own minimum**, so this floor excludes
+ * ZERO of the 496 prompt lines the score calibration rests on while removing
+ * every degenerate short prompt measured (`"fix it"` 1, `"mach das"` 2,
+ * `"was denkst du dazu"` 2, `"weiter"` 1). A floor of 4 would have cost 10 real
+ * corpus prompts for one tenth of a percentage point.
+ */
+export const MIN_TASK_TERMS = 3;
+
+/** Pointers per line. Three is the ranker's own default `--top`. */
+export const TOP_K = 3;
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+function _isObject(v: unknown): v is JsonObject {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Rank a prompt and return the pointers worth injecting, or `[]` for silence.
+ *
+ * Total by construction: a missing root, an unreadable catalogue, or a ranker
+ * error all resolve to `[]`. A routing advisory that can crash a turn is worse
+ * than one that says nothing.
+ */
+export function routePointers(prompt: string, skillsDir: string | null): RankRow[] {
+  if (skillsDir === null) return [];
+  // Denominator floor BEFORE the catalogue read: a prompt too short to score
+  // meaningfully cannot produce a pointer worth 337 file reads either.
+  try {
+    if (_tokenize(prompt).size < MIN_TASK_TERMS) return [];
+  } catch {
+    return [];
+  }
+  let rows: RankRow[];
+  try {
+    rows = rank(prompt, skillsDir);
+  } catch {
+    return [];
+  }
+  const top = rows[0];
+  if (top === undefined || top[1] < MIN_TOP_SCORE) return [];
+  return rows.slice(0, TOP_K);
+}
+
+/**
+ * The injected line. Names the floor it cleared, so a reader can tell a
+ * confident pointer from a lucky one without opening this file.
+ */
+export function buildRouteLine(rows: readonly RankRow[]): string {
+  const pointers = rows.map(([name, score]) => `${name} (${score})`).join(", ");
+  return (
+    `<skill-route>ranked skill pointers for this prompt: ${pointers}. ` +
+    `Deterministic keyword ranker, top-1 at or above ${MIN_TOP_SCORE}/100 — ` +
+    `pointers only, no bodies loaded. Open one if it fits; ignore the line if it does not.</skill-route>`
+  );
+}
+
+function _extractPrompt(payload: JsonObject): string {
+  for (const key of ["prompt", "userPrompt", "user_prompt", "message", "text"]) {
+    const v = payload[key];
+    if (typeof v === "string" && v.trim()) return v;
+  }
+  return "";
+}
+
+function _workspaceRoot(envelope: JsonObject): string {
+  const v = envelope["workspace_root"];
+  return typeof v === "string" && v ? v : process.cwd();
+}
+
+export function main(): number {
+  let envelope: JsonValue = {};
+  try {
+    const raw = readHookStdin();
+    envelope = raw.trim() ? (JSON.parse(raw) as JsonValue) : {};
+  } catch {
+    return EXIT_ALLOW; // malformed envelope — never block
+  }
+  const env: JsonObject = _isObject(envelope) ? envelope : {};
+
+  const event = env["event"];
+  const slot = typeof event === "string" && event !== "" ? event : "user_prompt_submit";
+  if (slot !== "user_prompt_submit") return EXIT_ALLOW;
+
+  const payload = _isObject(env["payload"]) ? (env["payload"] as JsonObject) : env;
+  const prompt = _extractPrompt(payload);
+  if (!prompt) return EXIT_ALLOW;
+  if (isSyntheticPrompt(prompt)) return EXIT_ALLOW; // harness turn, not a task
+
+  const rows = routePointers(prompt, resolveSkillsRoot(_workspaceRoot(env)));
+  if (rows.length === 0) return EXIT_ALLOW; // silence is the default
+
+  process.stdout.write(
+    `${JSON.stringify({
+      decision: "warn",
+      reason: `skill-route: ${rows.length} pointer(s), top ${rows[0]![1]}/100`,
+      additional_context: buildRouteLine(rows),
+    })}\n`,
+  );
+  return EXIT_WARN;
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url`.
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+  if (typeof __AGENT_CONFIG_BUNDLE__ !== "undefined" && __AGENT_CONFIG_BUNDLE__) return false;
+  if (process.argv[1] === undefined) return false;
+  const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+  if (import.meta.url === argvUrl) return true;
+  try {
+    const here = fs.realpathSync(fileURLToPath(import.meta.url));
+    const argv = fs.realpathSync(path.resolve(process.argv[1]));
+    return here === argv;
+  } catch {
+    return false;
+  }
+}
+
+if (_isCliEntry()) {
+  process.exit(main());
+}

package/src/scripts/hooks/tool_result_bytes_hook.ts

@@ -0,0 +1,219 @@
+#!/usr/bin/env tsx
+/**
+ * Tool-result byte counter — capture only, no behaviour change
+ * (road-to-inbox-harvest-2026-08-d-context-ledger Phase 1, Step 1.1).
+ *
+ * Why this exists. `hook-token-budget.json` registers the gap in its own
+ * words: *"bytes-into-context from tool RESULTS is not instrumented
+ * anywhere (the census covers hook payloads only)"*. The injection census
+ * measures what HOOKS put into context — a few kilobytes per turn under a
+ * per-slot cap. It does not measure what TOOLS put into context, which is
+ * the larger number by any plausible margin and the one nobody can cite.
+ * Every claim about context cost in this tree is therefore made against a
+ * denominator that excludes its own dominant term.
+ *
+ * This concern is the instrument and ONLY the instrument. It appends; it
+ * never decides, never advises, and emits nothing to the model. The
+ * threshold question — when is a tool result too large — is deliberately
+ * NOT answered here: the distribution has never been observed, and a
+ * threshold set before the distribution is a number invented rather than
+ * measured. That ordering is the house rule this repository has paid to
+ * learn more than once.
+ *
+ * ── What is recorded, and what is refused ──────────────────────────────
+ *
+ * PRIVACY BY CONSTRUCTION — never widen this file to record content.
+ *
+ * The record type has exactly three fields and NONE of them can hold free
+ * text: a timestamp, a tool NAME (an id-shaped enum — `Read`, `Bash`,
+ * `Grep` — the same single host string `orchestration_record_hook` already
+ * records), and a BYTE COUNT. A tool result routinely carries file
+ * contents, command output, secrets in an env dump, and customer data from
+ * an API response. None of it reaches this file's output, because the
+ * output has no field able to carry it. A record shape that cannot hold a
+ * secret has no scrubber that can fail — the same construction
+ * `domain-safety-pii` § Surface 2 prescribes for logs and the reason the
+ * sibling `subagent-ledger` refuses `last_assistant_message` in any form.
+ *
+ * The result is measured, never read: `_resultBytes` computes a length and
+ * discards the value in the same expression.
+ *
+ * ── Always exit 0 ─────────────────────────────────────────────────────
+ *
+ * A `warn` (exit 2) is read as a hard BLOCK on this host, and this concern
+ * has nothing to say to the model. Every path returns EXIT_ALLOW —
+ * malformed envelope, unparseable payload, unwritable disk. An instrument
+ * that can fail a turn is a mechanism, and this is not one yet.
+ *
+ * ── Absence is recorded, not inferred ─────────────────────────────────
+ *
+ * A payload carrying no readable result writes a line with `bytes: null`
+ * and `measurable: false` rather than writing nothing. The two cases are
+ * otherwise byte-identical in the output — "this host does not carry tool
+ * results in its PostToolUse payload" and "no tools ran" would produce the
+ * same empty file, and the first is a finding about the instrument's own
+ * coverage that the baseline has to be able to see. This is the
+ * instrument-goes-quiet failure the sibling ledger's round-1 review fixed
+ * one layer down, applied here before it can be shipped.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { is_replay_mode } from './state_io.js';
+import { readHookStdin } from './hook_stdin.js';
+
+const EXIT_ALLOW = 0;
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+function isObject(v: unknown): v is JsonObject {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Census file, relative to the consumer repo root. Sibling of
+ * `injection-census.jsonl` in the same directory and the same
+ * `{ts, …, bytes}` line shape — one family, two units: that file counts
+ * bytes this suite injects, this one counts bytes the host's tools do.
+ * Gitignored via `/agents/runtime/`.
+ */
+export const CENSUS_FILE = path.join('agents', 'runtime', 'state', 'tool-result-census.jsonl');
+
+/** The payload keys a host may use for a tool's result, widest first. */
+const RESULT_KEYS = ['tool_response', 'toolResponse', 'tool_result', 'toolUseResult'] as const;
+
+/**
+ * UTF-8 byte length of a tool result, or `null` when the payload carries
+ * none under any known key.
+ *
+ * A result is an object on most tools and a bare string on some (`Bash`
+ * returns its stdout directly — see the sibling hook's own test corpus), so
+ * both shapes are measured. The sibling's `extractToolResult` returns
+ * `JsonObject | null` and would report a bare-string result as absent,
+ * which is correct for its purpose (it reads named usage fields) and wrong
+ * for this one: a 400 KB command output is exactly the case this counter
+ * exists to see, and it is precisely the shape that extractor drops.
+ *
+ * Bytes, not characters: a multibyte result costs what it costs on the
+ * wire, and `String.length` would under-report it.
+ */
+export function _resultBytes(payload: JsonObject): number | null {
+    for (const key of RESULT_KEYS) {
+        const v = payload[key];
+        if (v === undefined || v === null) continue;
+        if (typeof v === 'string') return Buffer.byteLength(v, 'utf8');
+        try {
+            return Buffer.byteLength(JSON.stringify(v), 'utf8');
+        } catch {
+            // Circular or otherwise unserialisable — unmeasurable, not zero.
+            return null;
+        }
+    }
+    return null;
+}
+
+/** The tool's name, read from the same positions the sibling hook reads. */
+export function _toolName(payload: JsonObject, envelope: JsonObject): string | null {
+    const candidates = [
+        payload['tool_name'],
+        payload['toolName'],
+        payload['tool'],
+        envelope['tool_name'],
+        envelope['tool'],
+    ];
+    for (const v of candidates) {
+        if (typeof v === 'string' && v) return v;
+    }
+    return null;
+}
+
+function unwrapPayload(envelope: JsonObject): JsonObject {
+    const inner = envelope['payload'];
+    return isObject(inner) ? inner : envelope;
+}
+
+/** `${ts.slice(0,7)}` is NOT used here — the census is one flat file, as its sibling is. */
+function censusFile(consumerRoot: string): string {
+    return path.join(consumerRoot, CENSUS_FILE);
+}
+
+export interface CensusLine {
+    ts: string;
+    tool: string | null;
+    bytes: number | null;
+    /** `false` ⇒ the payload carried no readable result. See the header. */
+    measurable: boolean;
+}
+
+export function _appendCensusLine(consumerRoot: string, line: CensusLine): void {
+    if (is_replay_mode()) return;
+    const file = censusFile(consumerRoot);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, `${JSON.stringify(line)}\n`, 'utf8');
+}
+
+/** Process an ALREADY-PARSED dispatcher envelope. Always returns EXIT_ALLOW. */
+export function processEnvelope(envelope: JsonValue, consumerRoot: string): number {
+    try {
+        if (!isObject(envelope)) return EXIT_ALLOW;
+        if (envelope['event'] !== 'post_tool_use') return EXIT_ALLOW;
+
+        const payload = unwrapPayload(envelope);
+        const bytes = _resultBytes(payload);
+
+        _appendCensusLine(consumerRoot, {
+            ts: new Date().toISOString(),
+            tool: _toolName(payload, envelope),
+            bytes,
+            measurable: bytes !== null,
+        });
+    } catch {
+        // Malformed payload, unwritable disk, anything — never disturb the run.
+        return EXIT_ALLOW;
+    }
+    return EXIT_ALLOW;
+}
+
+/** Resolve the consumer repo root, same precedence as the sibling ledger. */
+export function resolveConsumerRoot(envelope: JsonValue): string {
+    if (isObject(envelope)) {
+        for (const key of ['workspace_root', 'project_root']) {
+            const v = envelope[key];
+            if (typeof v === 'string' && v) return v;
+        }
+        const cwd = unwrapPayload(envelope)['cwd'];
+        if (typeof cwd === 'string' && cwd) return cwd;
+    }
+    return process.cwd();
+}
+
+export function main(): number {
+    const raw = readHookStdin();
+    let envelope: JsonValue = {};
+    try {
+        envelope = raw.trim() ? (JSON.parse(raw) as JsonValue) : {};
+    } catch {
+        return EXIT_ALLOW;
+    }
+    return processEnvelope(envelope, resolveConsumerRoot(envelope));
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url`.
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+if (_isCliEntry()) process.exit(main());

package/src/scripts/hooks/ui_route_nudge_hook.ts

@@ -30,9 +30,12 @@
  * degradation valve `design_slop_hook` carries, for the same reason: an agent
  * that has decided to proceed must not be re-prompted into a loop.
  *
- * HOST BOUNDARY, STATED RATHER THAN IMPLIED. `pre_tool_use` exists on three
- * hosts. Everywhere else this concern has nowhere to bind and the obligation
- * stays model-carried, exactly as the two rules already declare. Run
+ * HOST BOUNDARY, STATED RATHER THAN IMPLIED. `pre_tool_use` is BOUND on three
+ * hosts. Everywhere else the obligation stays model-carried, exactly as the two
+ * rules already declare. Corrected 2026-08-17: this comment said the concern has
+ * "nowhere to bind" elsewhere, which the manifest's own `native_event_aliases`
+ * table refutes for cursor, cline and gemini — unbound, not unbindable. See
+ * `docs/contracts/hook-architecture-v1.md` § Which hosts carry pre_tool_use. Run
  * `agent-config hooks:status` for the host you are actually on.
  *
  * Default-OFF: no-ops unless `hooks.ui_route_nudge.enabled: true`.

package/src/scripts/hot_context_hook.ts

@@ -379,7 +379,19 @@ export function main(): number {
         if (_is_replay_mode()) {
             return 0; // replay fixtures: read-only, no state mutation
         }
-        if (event === 'stop' || event === 'session_end') {
+        // `pre_compact` joins the write set (road-to-inbox-harvest-2026-08-d-
+        // context-ledger Step 2.1). It is the only slot that fires WHILE state
+        // is being destroyed, and until now it carried no writer at all: the
+        // cache a post-compaction `session_start` restores was written at the
+        // last `stop`, so everything the session did since then was lost with
+        // the compaction. Writing here makes the restore reflect the moment
+        // before the loss instead of the moment before the last turn.
+        //
+        // Cheap and idempotent by construction: `_write_hot_context` is a
+        // deterministic rebuild from the history file, so an extra fire costs
+        // one rebuild and can never produce a worse cache than the older one it
+        // replaces. It emits nothing — the restore side is unchanged.
+        if (event === 'stop' || event === 'session_end' || event === 'pre_compact') {
             _write_hot_context(root);
         } else if (event === 'session_start') {
             const source = String(payload.source ?? '');