@event4u/agent-config 14.1.0 → 14.4.0

package/src/scripts/hooks/session_eol_hook.ts

@@ -54,6 +54,8 @@ import {
     scanEolSlice,
     type EolCounters,
 } from '../_lib/session_eol.js';
+import { buildCheckpoint, writeCheckpoint } from '../_lib/run_checkpoint.js';
+import { read_claimed_slug } from '../session_register_hook.js';
 import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
 import { readHookStdin } from './hook_stdin.js';
 import { atomic_write_json, is_replay_mode } from './state_io.js';
@@ -107,6 +109,23 @@ export function deriveSessionKey(envelope: JsonObject, payload: JsonObject): str
     );
 }
 
+/**
+ * The RAW session id, not the hashed key.
+ *
+ * `read_claimed_slug` keys the per-session claim file off the id the host
+ * exported, so handing it `deriveSessionKey`'s hash would look up a file that
+ * cannot exist and silently report "no contract" for every claimed run.
+ * Falls back to the envelope, which is where the dispatcher puts it, and
+ * deliberately does NOT fall back to the transcript path: that is a filename,
+ * not an identity, and `sessions:claim` never wrote a claim under one.
+ */
+export function payloadSessionId(payload: JsonObject, envelope: JsonObject): string {
+    return (
+        str(payload['session_id'] as JsonValue | undefined) ||
+        str(envelope['session_id'] as JsonValue | undefined)
+    ).trim();
+}
+
 /** Load prior per-session state; any read/shape error reads as "fresh session". */
 export function readState(file: string): SessionEolState {
     try {
@@ -337,6 +356,39 @@ export function main(): number {
 
     writeContextFill(workspaceRoot, tokens, threshold, now);
 
+    // ── UOTL Phase 6.1 — the deterministic half of the handoff ───────
+    //
+    // Above the threshold AND inside a running contract, leave a derived
+    // checkpoint behind. Two properties the advisory alone cannot give:
+    //
+    //   · It costs no judgement. Every field is recomputed from the
+    //     roadmap on disk, so a dying session produces it correctly even
+    //     when it has no context left to summarise anything.
+    //   · It is re-verifiable. A resumed run recomputes the same fields
+    //     and can name WHICH claim went stale rather than trusting the
+    //     record, which is the deliberate departure from resuming by
+    //     bookkeeping (Phase 3.2).
+    //
+    // "Inside a running contract" is the same carrier `run-continuation`
+    // uses — a `sessions:claim` for this session — and no second one is
+    // invented. Outside a contract this is silent: a checkpoint for a
+    // conversational session names work nobody is executing.
+    //
+    // Best-effort throughout. A checkpoint is a recovery aid, and a
+    // recovery aid that can fail a Stop is a liability.
+    const checkpointRunId = payloadSessionId(payload, envelope);
+    if (shouldAdvise && checkpointRunId !== '') {
+        try {
+            const slug = read_claimed_slug(workspaceRoot, checkpointRunId);
+            if (slug !== null) {
+                const cp = buildCheckpoint(workspaceRoot, eolSessionKey(checkpointRunId), slug);
+                if (cp !== null) writeCheckpoint(workspaceRoot, cp);
+            }
+        } catch {
+            // never block the Stop path
+        }
+    }
+
     if (shouldAdvise && threshold !== null && tokens !== null) {
         process.stdout.write(
             `${JSON.stringify({

package/src/scripts/hooks/skill_route_hook.ts

@@ -43,6 +43,66 @@
  * need an invalidation story for a tree that changes under the session, and
  * 12.3 ms does not buy one.
  *
+ * HOST-HONEST, AND FAIL-OPEN BY CONSTRUCTION (road-to-catalogue-host-fit Phase
+ * 3). The ranker reads the on-disk tree; the host does not necessarily deliver
+ * it. A skill the host truncated is still rankable and still pointable, and the
+ * pointer then names a skill whose description the model never received — worse
+ * than silence, because a pointer reads as a delivered capability. That is the
+ * roadmap's D-4, and it is MEASURED rather than assumed: 16 of 16 bare entries
+ * in the 2026-08-12 claude observation are still in this ranker's catalogue
+ * (`capture_skill_catalogue --pointable-bare`), among them `design-review`,
+ * `design-intelligence` and `fe-design` — skills this estate's own rules route
+ * to. So the pointer set is filtered against the latest per-entry observation
+ * for the CURRENT host.
+ *
+ * The filter only ever narrows on a positive reading, and every uncertain state
+ * resolves to no filtering at all: no observation log, no record for this host,
+ * a host that publishes no per-entry list, a malformed line, an unknown host, or
+ * any throw. `knownBareNames` returns `null` for each of them and
+ * `filterKnownBare` treats `null` as a pass-through, so behaviour is
+ * byte-identical to the unfiltered line. A filter that quietly hides skills on
+ * missing data is worse than the divergence it treats — the roadmap's own words,
+ * and the reason fail-open is a construction here rather than a convention.
+ *
+ * IT COSTS ZERO ON THE PATH THE HEADER ABOVE PROMISES IS FREE, AND 0.015 ms ON
+ * THE ONE THAT PAYS. The log read is passed in as a thunk, not a value, and
+ * `routePointers` calls it only after the term floor AND the rank both pass. A
+ * prompt below `MIN_TASK_TERMS` therefore still reads no files at all, which is
+ * the claim the 0 ms paragraph makes and an eagerly-read log would have quietly
+ * falsified.
+ *
+ * The FIRING path was measured rather than assumed, because R2 finding 10 is
+ * right that the paragraph above describes a path this branch changed. Measured
+ * 2026-08-18 on this tree, same method as the 12.3 ms figure: `knownBareForHost`
+ * alone is **0.015 ms median / 0.022 ms p95** (n=2000, warm) against a ranked
+ * pass of 8.3 ms median — three orders of magnitude below the ranker it rides
+ * on, and under 0.01 % of the slot's 250 ms p95 budget. The log is seven lines;
+ * a cache would need an invalidation story and 0.015 ms does not buy one, which
+ * is the same reasoning the ranker's own no-cache decision records.
+ *
+ * Note what the existing bench does NOT cover, so nobody reads it as coverage:
+ * `bench_hook_latency`'s synthetic payload carries neither `prompt` nor
+ * `platform`, so this concern returns before the ranker on every bench
+ * iteration. The figures above come from a direct probe, not from that harness.
+ *
+ * THE FLOOR APPLIES TO WHAT IS DELIVERED, NOT TO WHAT WAS RANKED. Filtering
+ * happens BEFORE `MIN_TOP_SCORE` and before the `TOP_K` slice, so the confidence
+ * question is asked of the best pointer the model can actually use. One rule, in
+ * one order: rank → drop the undeliverable → apply the floor → take the top
+ * three.
+ *
+ * That ordering makes silence a real outcome, and the number says so rather than
+ * the prose guessing: on `"review the authorization policy and tenant scope for
+ * this endpoint"` the ranker returns `authz-review` at 47 and the next entry at
+ * 23, against a floor of 31. Suppress the top-1 and NOTHING clears the floor —
+ * the line goes silent instead of naming a 23/100 pointer because the 47 one was
+ * undeliverable. That is the intended reading of a floor calibrated for
+ * confidence, and promoting a sub-floor pointer to fill the gap would be the
+ * "advisory worse than silence" failure this file's risk paragraph ranks first.
+ * `suppressed` is what distinguishes that silence from an unranked prompt, and
+ * `tests/hooks/skill_route_hook.test.ts` pins both cases against the real
+ * corpus rather than a constructed 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
@@ -51,6 +111,13 @@
  * removed. The score floor above is a TRIGGER calibration and is measured; the
  * adoption threshold is an OUTCOME claim and is deliberately absent.
  *
+ * `skill_route_bare_suppression_rate` is registered beside it under the same
+ * owner, review date and kill discipline, and inherits the same refusal: how
+ * often the filter fires is a number to collect, not one to promise. Its
+ * numerator is carried in the warn `reason` below — `N suppressed` — because no
+ * dedicated counter exists, and that gap is registered as a gap rather than
+ * implied to be automatic.
+ *
  * 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
@@ -73,7 +140,8 @@ 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 { OBSERVATION_LOG, readObservationLog, resolveSkillsRoot } from "../_lib/skill_catalogue.js";
+import { knownBareNames } from "../_lib/skill_catalogue_series.js";
 import { _tokenize, rank, type RankRow } from "../skill_tools/score_skill_relevance.js";
 
 const EXIT_ALLOW = 0;
@@ -119,31 +187,115 @@ function _isObject(v: unknown): v is JsonObject {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
 
+/**
+ * Names this host is known to have delivered bare, or `null` for no filtering.
+ *
+ * Every failure mode collapses to `null` — an unknown host, a missing log, an
+ * unreadable one, a host that enumerates nothing, a throw from anywhere in the
+ * read. The three-way distinction `knownBareNames` draws is preserved: an empty
+ * set means *measured clean*, `null` means *never measured*, and only the second
+ * one is produced here by accident.
+ */
+export function knownBareForHost(workspaceRoot: string, host: string | null): Set<string> | null {
+  if (host === null || host === "") return null;
+  try {
+    return knownBareNames(readObservationLog(path.join(workspaceRoot, OBSERVATION_LOG)), host);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Drop the ranked rows this host is known to have delivered bare.
+ *
+ * `null` is a pass-through and returns the input order untouched, which is the
+ * fail-open half of the header's contract and what makes an absent observation
+ * byte-identical to today.
+ */
+export function filterKnownBare(
+  rows: readonly RankRow[],
+  bare: Set<string> | null,
+): RankRow[] {
+  if (bare === null || bare.size === 0) return [...rows];
+  return rows.filter(([name]) => !bare.has(name));
+}
+
+/** What one routing pass decided, including what it refused to name. */
+export interface RouteDecision {
+  rows: RankRow[];
+  /**
+   * Would-be POINTERS dropped as known-bare — the suppression metric's numerator.
+   *
+   * Scoped to the pointer window (`TOP_K` of the unfiltered ranking), not to the
+   * whole ranked list. R2 finding 1: `rank` returns every non-zero-scoring skill
+   * and this catalogue has hundreds, so counting drops across all of them would
+   * let a bare name at rank 40 — never pointable, never a loss — bump the count
+   * on almost every fire. The registered metric defines this as skills the
+   * ranker wanted to POINT AT, and its upper falsifier would otherwise fire on a
+   * perfectly healthy join.
+   */
+  suppressed: number;
+}
+
 /**
  * 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.
+ *
+ * `bareProvider` is a THUNK, deliberately — see the header's zero-cost
+ * paragraph. It is called only once both the term floor and the rank have
+ * passed, so the short-prompt path still touches no files. Omitting it disables
+ * filtering entirely, which is what keeps every caller that predates the filter
+ * behaviourally unchanged.
  */
-export function routePointers(prompt: string, skillsDir: string | null): RankRow[] {
-  if (skillsDir === null) return [];
+export function routeDecision(
+  prompt: string,
+  skillsDir: string | null,
+  bareProvider?: () => Set<string> | null,
+): RouteDecision {
+  const silent: RouteDecision = { rows: [], suppressed: 0 };
+  if (skillsDir === null) return silent;
   // 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 [];
+    if (_tokenize(prompt).size < MIN_TASK_TERMS) return silent;
   } catch {
-    return [];
+    return silent;
   }
   let rows: RankRow[];
   try {
     rows = rank(prompt, skillsDir);
   } catch {
-    return [];
+    return silent;
+  }
+  let bare: Set<string> | null = null;
+  if (bareProvider !== undefined) {
+    try {
+      bare = bareProvider();
+    } catch {
+      bare = null; // fail open, never silent-narrow
+    }
   }
-  const top = rows[0];
-  if (top === undefined || top[1] < MIN_TOP_SCORE) return [];
-  return rows.slice(0, TOP_K);
+  const deliverable = filterKnownBare(rows, bare);
+  // The pointer WINDOW, not the ranked list — see `RouteDecision.suppressed`.
+  const suppressed =
+    bare === null ? 0 : rows.slice(0, TOP_K).filter(([name]) => bare.has(name)).length;
+  // The floor asks its question of the best DELIVERABLE pointer, not of a
+  // pointer the model cannot use. See the header's one-rule-one-order note.
+  const top = deliverable[0];
+  if (top === undefined || top[1] < MIN_TOP_SCORE) return { rows: [], suppressed };
+  return { rows: deliverable.slice(0, TOP_K), suppressed };
+}
+
+/** The rows alone. Kept because most callers and fixtures want only these. */
+export function routePointers(
+  prompt: string,
+  skillsDir: string | null,
+  bareProvider?: () => Set<string> | null,
+): RankRow[] {
+  return routeDecision(prompt, skillsDir, bareProvider).rows;
 }
 
 /**
@@ -191,13 +343,22 @@ export function main(): number {
   if (!prompt) return EXIT_ALLOW;
   if (isSyntheticPrompt(prompt)) return EXIT_ALLOW; // harness turn, not a task
 
-  const rows = routePointers(prompt, resolveSkillsRoot(_workspaceRoot(env)));
+  const root = _workspaceRoot(env);
+  const platform = env["platform"];
+  const host = typeof platform === "string" && platform ? platform : null;
+  const { rows, suppressed } = routeDecision(prompt, resolveSkillsRoot(root), () =>
+    knownBareForHost(root, host),
+  );
   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`,
+      reason:
+        `skill-route: ${rows.length} pointer(s), top ${rows[0]![1]}/100` +
+        // The suppression metric's numerator. Named only when non-zero, so the
+        // common line keeps its shape and its registered byte budget.
+        (suppressed > 0 ? `, ${suppressed} suppressed as host-bare` : ""),
       additional_context: buildRouteLine(rows),
     })}\n`,
   );

package/src/scripts/hooks/telemetry_usage_hook.ts

@@ -0,0 +1,339 @@
+#!/usr/bin/env tsx
+/**
+ * Deterministic PostToolUse Class-A usage capture
+ * (road-to-org-telemetry Phase 1, step 1.2).
+ *
+ * Why a hook rather than the existing collector. `skill_usage_collect.ts`
+ * scans the maintainer's own transcript directory and derives its project
+ * slug from this repository, so a consumer session is invisible to it by
+ * construction — the roadmap's Context table records that as still true
+ * after 479 commits. Phase 0's third spike then measured the size of the
+ * gap on the set the collector DOES read: **0 of 89** invocations detected,
+ * against 163 of 164 across every worktree slug. The zero in the usage
+ * report is an instrumentation artefact, not an adoption measurement.
+ *
+ * Phase 0's first spike settled the event this concern binds to:
+ * `post_tool_use` with `tool_name === "Skill"`, the skill name at
+ * `tool_input.skill` — present in 164 of 164 real invocations across 14,171
+ * live records. The transcript-scan fallback the roadmap pre-registered does
+ * not fire.
+ *
+ * DEFAULT-OFF, AND THE SWITCH IS NOT `enabled`. `read_remote_settings`
+ * activates only when `enabled` is true AND the org pack supplied an
+ * endpoint, an org id, and a salt. An external clone of this repository
+ * carries the key names and no values, so copying the tree cannot reach the
+ * write path. When inactive this concern performs zero telemetry file
+ * operations — no log write, no directory creation — and zero network calls.
+ * (It does read `.agent-settings.yml`, once per process and memoised: the
+ * settings file is how it learns it is off, the same as the artefact-
+ * engagement surface it mirrors.)
+ *
+ * NO OUTBOUND CALL EXISTS HERE, DELIBERATELY. Transport is Phase 2 and is
+ * blocked on `sink-choice`; org-wide enablement is Phase 3 and is blocked on
+ * `dpo-signoff`. This concern appends to a local JSONL file and stops.
+ *
+ * Exit code is ALWAYS 0 — malformed envelope, unreadable settings, failed
+ * write, anything. A hook `warn` (exit 2) is read as a hard BLOCK on this
+ * host (recorded trap), and a telemetry concern has nothing to say to the
+ * model, so it never warns either.
+ */
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import * as fs from 'node:fs';
+
+import {
+    read_remote_settings,
+    type RemoteTelemetrySettings,
+} from '../../agent-src/templates/scripts/telemetry/settings.js';
+import {
+    append_class_a_record,
+    build_class_a_record,
+    profile_from_legacy_tier,
+} from '../../agent-src/templates/scripts/telemetry/remote.js';
+import { is_replay_mode } from './state_io.js';
+import { readHookStdin } from './hook_stdin.js';
+
+const EXIT_ALLOW = 0;
+
+/** The tool name Phase 0 spike 1 confirmed for a skill invocation. */
+export const SKILL_TOOL_NAME = 'Skill';
+
+const SETTINGS_FILENAME = '.agent-settings.yml';
+
+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);
+}
+
+/** Unwrap the dispatcher envelope down to the platform-native payload. */
+export function unwrapPayload(envelope: JsonObject): JsonObject {
+    const inner = envelope['payload'];
+    return isObject(inner) ? inner : envelope;
+}
+
+/** Best-effort read of the tool name across host key variants. */
+export function extractToolName(payload: JsonObject): string | null {
+    const v = payload['tool_name'] ?? payload['toolName'] ?? payload['tool'];
+    return typeof v === 'string' && v ? v : null;
+}
+
+/**
+ * The invoked skill's name, off `tool_input.skill`.
+ *
+ * Spike 1 observed this key on 164 of 164 real invocations; the camelCase
+ * variant is accepted for the same reason `extractToolName` accepts one —
+ * host key casing has varied across versions in this tree before.
+ */
+export function extractSkillName(payload: JsonObject): string | null {
+    const input = payload['tool_input'] ?? payload['toolInput'];
+    if (!isObject(input)) return null;
+    const v = input['skill'] ?? input['skill_name'] ?? input['name'];
+    return typeof v === 'string' && v ? v : null;
+}
+
+/** Host id off the dispatcher envelope (`claude`, `augment`, …). */
+export function extractHost(envelope: JsonObject): string | null {
+    const v = envelope['platform'] ?? envelope['host'];
+    return typeof v === 'string' && v ? v : null;
+}
+
+/**
+ * The host session id. Hashed before it is recorded, never stored raw —
+ * it is a high-entropy opaque token that `check_secret_leak` reads as a
+ * candidate credential.
+ */
+export function extractSessionId(envelope: JsonObject, payload: JsonObject): string {
+    for (const source of [envelope, payload]) {
+        const v = source['session_id'] ?? source['sessionId'];
+        if (typeof v === 'string' && v) return v;
+    }
+    return '';
+}
+
+/**
+ * Read one top-level scalar out of the settings text.
+ *
+ * Deliberately a raw line scan rather than a YAML parse: this runs on the
+ * post-tool hot path, both values wanted here are top-level scalars from
+ * closed enums, and `build_class_a_record` rejects anything outside those
+ * enums — so a mis-parse produces a dropped field, never a wrong one.
+ *
+ * Accepts a trailing inline comment, which this file's own settings
+ * template uses heavily (`discipline_profile: essential  # ~3.3x kernel
+ * tokens`); rejecting it would have silently reported "not declared" for a
+ * perfectly ordinary line.
+ */
+function _scalar(settingsText: string, key: string): string | null {
+    const re = new RegExp(`^${key}:[ \\t]*([^#\\r\\n]+?)[ \\t]*(?:#.*)?$`, 'u');
+    for (const line of settingsText.split('\n')) {
+        const m = re.exec(line);
+        if (m && m[1]) {
+            const value = m[1].trim().replace(/^["']|["']$/gu, '');
+            if (!value) return null;
+            // The shipped template carries a placeholder until `install`
+            // fills it in; that is "not yet resolved", not a value.
+            if (value.startsWith('__')) return null;
+            return value;
+        }
+    }
+    return null;
+}
+
+/**
+ * The DECLARED discipline profile — the knob that actually decides which
+ * rule surfaces load.
+ *
+ * The first version of this function read `rule_loading_tier`, and that was
+ * wrong: the settings template calls that key a "legacy knob — superseded by
+ * discipline_profile above", and `resolve_discipline_profile` confirms the
+ * precedence — explicit `discipline_profile` wins outright and the legacy
+ * key is consulted only in its absence. So a default install would have had
+ * a knob recorded that does not decide the thing the field implies.
+ *
+ * The fallback mirrors the resolver's own legacy mapping, which needs no
+ * model id and is therefore safe to reproduce here. What is NOT reproduced
+ * is the resolver's both-absent default (`essential`): recording it would
+ * claim a declaration the install never made. Absent stays `null`, and a
+ * reader applies the documented default themselves.
+ */
+export function extractDisciplineProfile(settingsText: string): string | null {
+    const explicit = _scalar(settingsText, 'discipline_profile');
+    if (explicit !== null) return explicit;
+    return profile_from_legacy_tier(_scalar(settingsText, 'rule_loading_tier'));
+}
+
+/**
+ * Installed package version, from the env the installer sets. Never
+ * fabricated: an install that did not report one records `null`.
+ */
+export function extractPackageVersion(env: NodeJS.ProcessEnv): string | null {
+    const v = env['AGENT_CONFIG_PACKAGE_VERSION'];
+    return typeof v === 'string' && v.trim() ? v.trim() : null;
+}
+
+interface SettingsRead {
+    settings: RemoteTelemetrySettings;
+    text: string;
+    /**
+     * The directory the settings file was found in — the project root, and
+     * the base a relative `output.path` resolves against. NOT the session
+     * cwd: a session started in a subdirectory would otherwise scatter one
+     * log file per directory it happened to start in.
+     */
+    root: string;
+}
+
+/**
+ * Read + memoise the settings for one process. The in-process dispatcher
+ * runs every concern in one `node`, so without this the file would be read
+ * once per concern per tool call.
+ */
+const _settingsCache = new Map<string, SettingsRead>();
+
+/**
+ * Walk up from `start` to the first directory holding a settings file.
+ *
+ * A host may report a session `cwd` inside a subdirectory of the project,
+ * and reading only that directory made the concern silently inactive on a
+ * legitimately enabled install — a failure with no message, which is the
+ * worst shape for a default-off surface. Bounded by the filesystem root, so
+ * it terminates on every path; no hit returns `start` unchanged, and the
+ * settings read then fails closed exactly as before.
+ */
+export function resolveSettingsPath(start: string): string {
+    let dir = path.resolve(start);
+    for (;;) {
+        const candidate = path.join(dir, SETTINGS_FILENAME);
+        try {
+            if (fs.statSync(candidate).isFile()) return candidate;
+        } catch {
+            // Not here — keep walking.
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) return path.join(path.resolve(start), SETTINGS_FILENAME);
+        dir = parent;
+    }
+}
+
+export function readSettingsFor(consumerRoot: string): SettingsRead {
+    const p = resolveSettingsPath(consumerRoot);
+    const cached = _settingsCache.get(p);
+    if (cached !== undefined) return cached;
+
+    let text = '';
+    try {
+        text = fs.readFileSync(p, 'utf-8');
+    } catch {
+        text = '';
+    }
+    const read: SettingsRead = { settings: read_remote_settings(p), text, root: path.dirname(p) };
+    _settingsCache.set(p, read);
+    return read;
+}
+
+/** Test seam — the cache is process-global and tests write real files. */
+export function _resetSettingsCache(): void {
+    _settingsCache.clear();
+}
+
+function processEnvelope(envelope: JsonValue, consumer_root: string): number {
+    try {
+        if (!isObject(envelope)) return EXIT_ALLOW;
+
+        const payload = unwrapPayload(envelope);
+        if (extractToolName(payload) !== SKILL_TOOL_NAME) return EXIT_ALLOW;
+
+        const { settings, text, root } = readSettingsFor(consumer_root);
+        if (!settings.active) return EXIT_ALLOW;
+        if (is_replay_mode()) return EXIT_ALLOW;
+
+        const skill = extractSkillName(payload);
+        if (skill === null) return EXIT_ALLOW;
+
+        const record = build_class_a_record({
+            skill,
+            host: extractHost(envelope),
+            org_id: settings.org_id,
+            salt: settings.salt,
+            hostname: os.hostname(),
+            username: os.userInfo().username,
+            session_id: extractSessionId(envelope, payload),
+            package_version: extractPackageVersion(process.env),
+            discipline_profile: extractDisciplineProfile(text),
+        });
+
+        // Relative to the PROJECT root (the directory holding the settings
+        // file), never to the session cwd — otherwise a session started in a
+        // subdirectory writes its own stray log there.
+        const logPath = path.isAbsolute(settings.log_path)
+            ? settings.log_path
+            : path.join(root, settings.log_path);
+        // The growth budget travels from the settings the install actually
+        // declared, not from the appender's own defaults — a retention key
+        // the write path never reads would be a setting that decorates
+        // rather than decides.
+        append_class_a_record(logPath, record, {
+            max_age_days: settings.retention_max_age_days,
+            max_bytes: settings.retention_max_bytes,
+        });
+    } catch {
+        // Malformed payload, unreadable disk, a rejected id — never block
+        // the tool call, and never write a degraded record.
+        return EXIT_ALLOW;
+    }
+    return EXIT_ALLOW;
+}
+
+export function run(stdin_text: string, options: { consumer_root: string }): number {
+    let envelope: JsonValue;
+    try {
+        const raw = stdin_text.trim();
+        if (!raw) return EXIT_ALLOW;
+        envelope = JSON.parse(raw) as JsonValue;
+    } catch {
+        return EXIT_ALLOW;
+    }
+    return processEnvelope(envelope, options.consumer_root);
+}
+
+export function _resolveRoot(envelope: JsonValue): string {
+    if (isObject(envelope)) {
+        const cwd = envelope['cwd'];
+        if (typeof cwd === 'string' && cwd) return cwd;
+        const pr = envelope['workspace_root'] ?? envelope['project_root'];
+        if (typeof pr === 'string' && pr) return pr;
+    }
+    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, _resolveRoot(envelope));
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+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());