@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/_lib/host_env_write.ts

@@ -2,7 +2,7 @@
  * The only host environment variables this package will ever write.
  *
  * WHY ITS OWN MODULE. One place owns the question "which host variable may this
- * package write", and the answer is a two-row allow table rather than a rule
+ * package write", and the answer is a three-row allow table rather than a rule
  * applied at a call site. `install.ts` imports it; nothing else writes host env.
  * The move out of `install.ts` also keeps that file, already far over its size
  * cap, from paying for this feature — the same reason the doctor's
@@ -13,12 +13,15 @@
  * the host's update-disabled resolver, the blanket one as its THIRD RUNG
  * (measured on Claude Code 2.1.284, `docs/setup/host-traffic-environment.md`).
  * A writer able to express either could disable a consumer's security updates.
- * Owner-decided 2026-09-30 that it never may, and an allow table of two holds
- * that where a deny list of two would have to stay complete as the host grows
- * more variables.
+ * Owner-decided 2026-09-30 that it never may, and an allow table holds that
+ * where a deny list would have to stay complete as the host grows more
+ * variables.
  *
- * Both writable entries are request SIZE caps. Neither suppresses a call, an
- * update check or a download — they bound how big a request is, never how many.
+ * Two writable entries are request SIZE caps; the third, owner-approved
+ * 2026-10-14, is the host's
+ * subagent CONCURRENCY cap. None suppresses a call, an update check or a
+ * download — they bound how big a request is or how many workers run at once,
+ * never whether a call happens.
  */
 
 import * as fs from 'node:fs';
@@ -26,12 +29,28 @@ import * as path from 'node:path';
 
 import * as YAML from 'yaml';
 
-/** The allow table. Two rows, and adding a third is a governance change. */
-export const WRITABLE_HOST_ENV: readonly { readonly variable: string; readonly settingsKey: string }[] = [
-    { variable: 'BASH_MAX_OUTPUT_LENGTH', settingsKey: 'bash_max_output_length' },
-    { variable: 'MAX_MCP_OUTPUT_TOKENS', settingsKey: 'max_mcp_output_tokens' },
+/**
+ * The concurrency row's ceiling. The row exists to bound fan-out, so a value
+ * past this is refused rather than written: an unbounded cap would turn the
+ * one row that limits spend into a way to raise it.
+ */
+export const MAX_CONCURRENT_SUBAGENTS = 64;
+
+/**
+ * The allow table. Three rows, and adding a fourth is a governance change.
+ * `settingsKey` is the dotted path into the settings document.
+ */
+export const WRITABLE_HOST_ENV: readonly {
+    readonly variable: string;
+    readonly settingsKey: string;
+    readonly max?: number;
+}[] = [
+    { variable: 'BASH_MAX_OUTPUT_LENGTH', settingsKey: 'host_environment.request_size_caps.bash_max_output_length' },
+    { variable: 'MAX_MCP_OUTPUT_TOKENS', settingsKey: 'host_environment.request_size_caps.max_mcp_output_tokens' },
+    { variable: 'CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS', settingsKey: 'subagents.max_parallel', max: MAX_CONCURRENT_SUBAGENTS },
 ];
 
+
 /** Where a project's settings document lives, canonical first. */
 const SETTINGS_CANDIDATES: readonly string[][] = [
     ['agents', 'settings', '.agent-settings.yml'],
@@ -78,14 +97,16 @@ export function readSettingsDoc(projectRoot: string): unknown | null {
  * writing a value the host would silently reinterpret is worse than writing none.
  */
 export function hostEnvBlock(settings: unknown): Record<string, string> | null {
-    const root = settings as Record<string, unknown> | null | undefined;
-    const he = root?.['host_environment'] as Record<string, unknown> | undefined;
-    const caps = he?.['request_size_caps'] as Record<string, unknown> | undefined;
-    if (caps === undefined) return null;
     const out: Record<string, string> = {};
-    for (const { variable, settingsKey } of WRITABLE_HOST_ENV) {
-        const v = caps[settingsKey];
-        if (typeof v === 'number' && Number.isInteger(v) && v > 0) out[variable] = String(v);
+    for (const { variable, settingsKey, max } of WRITABLE_HOST_ENV) {
+        let v: unknown = settings;
+        for (const part of settingsKey.split('.')) {
+            v = v !== null && typeof v === 'object' ? (v as Record<string, unknown>)[part] : undefined;
+        }
+        // A safe integer, so `String(v)` is the digits the host parses back.
+        if (typeof v !== 'number' || !Number.isSafeInteger(v) || v <= 0) continue;
+        if (max !== undefined && v > max) continue;
+        out[variable] = String(v);
     }
     return Object.keys(out).length === 0 ? null : out;
 }
@@ -106,6 +127,6 @@ export function withHostEnv(
 ): Record<string, unknown> {
     const env = hostEnvBlock(readSettingsDoc(projectRoot));
     if (env === null) return bridge;
-    announce(`.claude/settings.json: wrote ${Object.keys(env).join(', ')} (request-size caps)`);
+    announce(`.claude/settings.json: wrote ${Object.keys(env).join(', ')} (request-size and concurrency caps)`);
     return { ...bridge, env };
 }

package/src/scripts/_lib/host_listing_model.ts

@@ -11,9 +11,11 @@
  * returned zero hits before this file.
  *
  * THE MECHANISM, AS DOCUMENTED UPSTREAM (code.claude.com/docs/en/skills and
- * anthropics/claude-code#64606, both read 2026-08-22). Claude Code lists every
- * skill NAME, and keeps DESCRIPTIONS only up to a fraction of the context
- * window — 1% by default, ≈8,000 characters on a 200k window — filling by
+ * anthropics/claude-code#64606, both read 2026-08-22; the page re-read on
+ * 2026-10-14 keeps the 1% and the 1,536 and no longer prints the ≈8,000
+ * illustration). Claude Code lists every skill NAME, and keeps DESCRIPTIONS
+ * only up to a fraction of the context window — 1% by default, which the
+ * 2026-08-22 page illustrated as ≈8,000 characters on a 200k window — filling by
  * invocation frequency and capping each entry at 1,536 characters. The fraction
  * is consumer-settable as `skillListingBudgetFraction`.
  *
@@ -83,7 +85,12 @@ export interface HostListingModelResult {
     assumptions: readonly ModelAssumption[];
 }
 
-/** Documented Claude Code defaults, read 2026-08-22. Not measured in this repo. */
+/**
+ * Claude Code defaults, not measured in this repo. `fraction` and
+ * `perEntryCapChars` are documented (read 2026-08-22, re-read 2026-10-14).
+ * `charsPerToken` is inferred from an illustration the 2026-08-22 page printed
+ * and the 2026-10-14 page no longer does — see `budget-unit-is-chars`.
+ */
 export const CLAUDE_CODE_LISTING_DEFAULTS = {
     fraction: 0.01,
     perEntryCapChars: 1536,
@@ -96,9 +103,9 @@ const ASSUMPTIONS: readonly ModelAssumption[] = [
         id: 'budget-unit-is-chars',
         provenance: 'upstream-prose',
         why:
-            'The docs give the budget as a fraction of the context window (tokens) and then ' +
-            'illustrate it as "≈8,000 characters on 200k", which only reconciles at 4 chars ' +
-            'per token. That ratio is inferred from the illustration, never stated.',
+            'The docs give the budget as a fraction of the context window (tokens); the ' +
+            '2026-08-22 read illustrated it as "≈8,000 characters on 200k" (gone by 2026-10-14), ' +
+            'which only reconciles at 4 chars per token. That ratio is inferred, never stated.',
     },
     {
         id: 'fill-order-is-invocation-frequency',

package/src/scripts/_lib/identifier_redaction.ts

@@ -0,0 +1,26 @@
+/**
+ * Class-tag redaction of identifiers for stores that keep text (knowledge
+ * ingestion, cross-repo retrieval).
+ *
+ * Detection is the rule table's identifier rows, read recall-first: a store
+ * that persists text has no reviewer after it, so a missed value is the costly
+ * error and a context word is not required here. The rows' checksums still
+ * hold — a number that fails Luhn is not a card, a string that fails mod-97 is
+ * not an IBAN. The tag spelling and the counter keys are this consumer's.
+ */
+import { detect, type EgressRule, IDENTIFIER_RULES, replaceSpans } from './egress_rules.js';
+
+/** The identifier rows with every context requirement dropped. */
+export const STORAGE_IDENTIFIER_RULES: readonly EgressRule[] = IDENTIFIER_RULES.map(({ context: _context, ...rest }) => rest);
+
+/** Counter key and tag per placeholder type; `CC` predates the table's `CARD`. */
+const TAG: Readonly<Record<string, string>> = { CARD: 'CC' };
+
+export function redactIdentifiers(text: string, counters: Record<string, number>): string {
+    const spans = detect(text, STORAGE_IDENTIFIER_RULES);
+    return replaceSpans(text, spans, (s) => {
+        const tag = TAG[s.type] ?? s.type;
+        counters[tag] = (counters[tag] ?? 0) + 1;
+        return `[${tag}]`;
+    });
+}

package/src/scripts/_lib/impact_bump.ts

@@ -0,0 +1,70 @@
+/**
+ * The impact-driven bump rule, scored against the recorded history.
+ *
+ * Nothing in `release.ts` calls this: changing how releases are numbered is an
+ * owner decision that has not been taken. Until it is, the rule only scores
+ * historical rows, so the decision can be made on a measured replay.
+ */
+import { CONSUMER_IMPACT_VALUES, IMPACT_RANK, type ConsumerImpact } from './consumer_impact.js';
+
+export type Bump = 'major' | 'minor' | 'patch';
+
+export interface BumpInput {
+    readonly impact: ConsumerImpact;
+    readonly breaking: boolean;
+    readonly has_minor_type: boolean;
+    readonly touches_major_surface: boolean;
+}
+
+export function impact_bump(input: BumpInput): Bump {
+    if (input.impact === 'action' || input.touches_major_surface) return 'major';
+    if (input.breaking || input.has_minor_type) return 'minor';
+    return 'patch';
+}
+
+export interface ImpactRow {
+    readonly version: string;
+    /** `null` when the last cell is not a value from the enum. */
+    readonly impact: ConsumerImpact | null;
+}
+
+/** Rows of the by-major table: first cell `**X.0.0**`, last cell the impact. */
+export function parse_impact_rows(markdown: string): ImpactRow[] {
+    const rows: ImpactRow[] = [];
+    for (const line of markdown.split('\n')) {
+        const m = /^\| \*\*(\d+\.0\.0)\*\* \|.*\| ([^|]*?) \|\s*$/.exec(line);
+        if (m === null) continue;
+        const cell = m[2] as string;
+        const impact = (CONSUMER_IMPACT_VALUES as readonly string[]).includes(cell) ? (cell as ConsumerImpact) : null;
+        rows.push({ version: m[1] as string, impact });
+    }
+    return rows;
+}
+
+/**
+ * Every recorded row was cut as a major because it carried a breaking subject,
+ * so each replays with `breaking: true`. The surface half of the rule is not
+ * scored: the record has no column for it, and inferring one would re-judge
+ * history. An unreadable impact replays as `major`, never as a downgrade.
+ */
+export function replay_majors(rows: readonly ImpactRow[]): Map<string, Bump> {
+    const strongest = new Map<string, ConsumerImpact | null>();
+    for (const row of rows) {
+        const prev = strongest.get(row.version);
+        if (prev === undefined) {
+            strongest.set(row.version, row.impact);
+        } else if (prev !== null && (row.impact === null || IMPACT_RANK[row.impact] > IMPACT_RANK[prev])) {
+            strongest.set(row.version, row.impact);
+        }
+    }
+    const out = new Map<string, Bump>();
+    for (const [version, impact] of strongest) {
+        out.set(
+            version,
+            impact === null
+                ? 'major'
+                : impact_bump({ impact, breaking: true, has_minor_type: false, touches_major_surface: false }),
+        );
+    }
+    return out;
+}

package/src/scripts/_lib/install_reach_checks.ts

@@ -33,8 +33,10 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { ROADMAP_ROOT_REL, scan as scanArtifactLocation } from './agent_artifact_location.js';
 import type { WiringCheck } from './runtime_wiring_checks.js';
 import { TOOL_TO_HOST, residualReport } from './mcp_consent_residual.js';
+import { checkSkillReach } from './skill_reach.js';
 
 /**
  * Root agent-instruction files, as a multi-vendor ecosystem convention rather
@@ -508,11 +510,59 @@ export function checkMcpConsentResidual(): WiringCheck {
     };
 }
 
+/**
+ * A roadmap-shaped file outside the roadmap root in the consumer's tree — the
+ * outward half `check_agent_artifact_location` names, running the same detector.
+ *
+ * A REPORT, never a move: `doctor` is read-only, and relocating a consumer's
+ * file without asking is the ownership break this package is ending elsewhere.
+ * `warn` rather than `fail` because a monorepo may keep roadmaps elsewhere on
+ * purpose — the finding names where this package's mechanisms would look, it
+ * does not assert the file is wrong. So a default run and `--strict` both exit
+ * 0 on it; only `--strict --strict-level warn` fails, which is the caller
+ * choosing that bar.
+ */
+export function checkArtifactLocation(projectRoot: string): WiringCheck {
+    const id = 'artifact-location';
+    const { findings, scanned } = scanArtifactLocation(projectRoot);
+    if (scanned === 0) {
+        return { id, status: 'skipped', message: 'no markdown file in this tree', remedy: '' };
+    }
+    if (findings.length === 0) {
+        return {
+            id,
+            status: 'ok',
+            message: `no roadmap-shaped file outside ${ROADMAP_ROOT_REL}/ (${scanned} markdown file(s) read)`,
+            remedy: '',
+        };
+    }
+    const lines = findings.map(
+        (f) => `${f.rel} → ${ROADMAP_ROOT_REL}/${path.posix.basename(f.rel)} (carries ${f.signals.join(', ')})`,
+    );
+    return {
+        id,
+        status: 'warn',
+        message:
+            `${findings.length} roadmap-shaped file(s) outside ${ROADMAP_ROOT_REL}/, where no roadmap ` +
+            `mechanism of this package reads them: ${lines.join(' · ')}`,
+        remedy:
+            `move each to the target named above if it is a roadmap; doctor never moves it for you. ` +
+            'If it is not a roadmap, it carries one of the three signals it should not',
+    };
+}
+
 // ---------------------------------------------------------------------------
 // Wiring — the shape `cmd_doctor` consumes
 // ---------------------------------------------------------------------------
 
-export const REACH_CHECK_IDS = ['instruction-path-reach', 'version-axis', 'override-set', 'mcp-consent-residual'] as const;
+export const REACH_CHECK_IDS = [
+    'instruction-path-reach',
+    'version-axis',
+    'override-set',
+    'mcp-consent-residual',
+    'artifact-location',
+    'skill-reach',
+] as const;
 
 export function reachRunners(opts: {
     projectRoot: string;
@@ -523,5 +573,7 @@ export function reachRunners(opts: {
         'version-axis': () => checkVersionAxis(opts.projectRoot, opts.resolvableVersion),
         'override-set': () => checkOverrideSet(opts.projectRoot),
         'mcp-consent-residual': () => checkMcpConsentResidual(),
+        'artifact-location': () => checkArtifactLocation(opts.projectRoot),
+        'skill-reach': () => checkSkillReach(),
     };
 }

package/src/scripts/_lib/installed_layer.ts

@@ -59,6 +59,7 @@ import {
 } from './global_deploy_inventory.js';
 import { DEFAULT_EVENT4U_ROOT_RELATIVE } from './user_global_paths.js';
 import { ruleBody, splitFrontmatter } from './rule_law_section.js';
+import { normaliseLayerText } from './installed_layer_normalise.js';
 
 /** How many files the per-directory ranking carries. Step 0.1 fixes it at 20. */
 export const TOP_FILES = 20;
@@ -72,6 +73,14 @@ export interface RuleFileReading {
     readonly file: string;
     /** Characters AFTER the frontmatter and block-comment strip. */
     readonly chars: number;
+    /**
+     * {@link chars}, with every absolute path substituted for a fixed token.
+     *
+     * The figure a comparison across two machines or two revisions may be read
+     * in — see `installed_layer_normalise.ts` for why `chars` alone cannot be.
+     * NEVER the answer to "what does the host load": that is `chars`.
+     */
+    readonly normalised_chars: number;
     /** False when the file carries a `paths:` key — then the host loads it on a path match. */
     readonly unconditional: boolean;
     /** True when the installed-tools manifest records this path, in either state. */
@@ -89,6 +98,8 @@ export interface LayerReading {
     readonly files: number;
     readonly unconditional: number;
     readonly chars: number;
+    /** {@link RuleFileReading.normalised_chars}, summed over the directory. */
+    readonly normalised_chars: number;
     readonly package_owned: number;
     readonly foreign: number;
     /**
@@ -199,6 +210,8 @@ export interface InstalledLayerReport {
         readonly files: number;
         readonly unconditional: number;
         readonly chars: number;
+        /** {@link LayerReading.normalised_chars}, summed over every layer. */
+        readonly normalised_chars: number;
         readonly package_owned: number;
         readonly foreign: number;
         readonly package_owned_chars: number;
@@ -313,6 +326,7 @@ export function readLayer(
         files: 0,
         unconditional: 0,
         chars: 0,
+        normalised_chars: 0,
         package_owned: 0,
         foreign: 0,
         package_owned_chars: 0,
@@ -351,6 +365,10 @@ export function readLayer(
             // a host loads" and "what a delivery carries" cannot drift into two
             // spellings of the same measurement.
             chars: ruleBody(text).length,
+            // THE SAME STRING, MEASURED TWICE. `chars` is what the host loads;
+            // this is that text with every absolute path substituted, so two
+            // machines with different package roots read one figure in common.
+            normalised_chars: normaliseLayerText(ruleBody(text)).length,
             unconditional: isUnconditional(text),
             package_owned: owned,
         });
@@ -370,6 +388,7 @@ export function readLayer(
         files: readings.length,
         unconditional: readings.filter((r) => r.unconditional).length,
         chars: readings.reduce((n, r) => n + r.chars, 0),
+        normalised_chars: readings.reduce((n, r) => n + r.normalised_chars, 0),
         package_owned: readings.filter((r) => r.package_owned).length,
         foreign: readings.filter((r) => !r.package_owned).length,
         package_owned_chars: readings.reduce((n, r) => n + (r.package_owned ? r.chars : 0), 0),
@@ -827,6 +846,7 @@ export function buildInstalledLayerReport(opts: ReportOptions): InstalledLayerRe
             files: acc.files + l.files,
             unconditional: acc.unconditional + l.unconditional,
             chars: acc.chars + l.chars,
+            normalised_chars: acc.normalised_chars + l.normalised_chars,
             package_owned: acc.package_owned + l.package_owned,
             foreign: acc.foreign + l.foreign,
             package_owned_chars: acc.package_owned_chars + l.package_owned_chars,
@@ -838,6 +858,7 @@ export function buildInstalledLayerReport(opts: ReportOptions): InstalledLayerRe
             files: 0,
             unconditional: 0,
             chars: 0,
+            normalised_chars: 0,
             package_owned: 0,
             foreign: 0,
             package_owned_chars: 0,
@@ -923,6 +944,16 @@ export function renderInstalledLayerReport(report: InstalledLayerReport): string
             `(${String(t.unconditional_chars)} standing + ${String(t.scoped_chars)} path-scoped), ` +
             `${String(t.package_owned)} package-owned / ${String(t.foreign)} foreign`,
     );
+    // THE COMPARABLE FIGURE, ON ITS OWN LINE AND LABELLED AS WHAT IT IS. The
+    // TOTAL above is what the host loads on THIS machine and moves with the
+    // package root; this one does not, and is therefore the only one two runs
+    // may be compared in. Printing them adjacent is deliberate — a reader who
+    // sees one number cannot tell which question it answers.
+    out.push(
+        `  TOTAL (normalised) — ${String(t.normalised_chars)} chars, ` +
+            'every absolute path substituted; comparable across machines and revisions, ' +
+            'NOT what the host loads',
+    );
     out.push(...renderHostLimitRows(report.limits));
     return out;
 }

package/src/scripts/_lib/installed_layer_normalise.ts

@@ -0,0 +1,75 @@
+/**
+ * Make the installed-layer character measurement independent of where the
+ * package happens to live on the machine that measured it.
+ *
+ * WHY THIS EXISTS, AND WHY IT IS NOT A CEILING. D7 of
+ * `road-to-an-installed-layer-that-is-thinned` records that a ceiling over the
+ * installed layer "may not rest on a STORED baseline, in any shape, until the
+ * measurement is environment-independent", and names two acceptable forms: a
+ * normalised total, or a base-ref comparison that stores nothing. This module
+ * is the first form and nothing more — it changes what the report CAN be read
+ * against and introduces no gate, no threshold and no stored number. The
+ * ratchet the council returned REQUEST_CHANGES on (2026-10-12, one seat
+ * present) was a stored baseline over an UN-normalised figure; that mechanism
+ * is untouched here and stays rejected.
+ *
+ * THE DEFECT, CONCRETELY. Every thinned stub the installer writes ends in an
+ * absolute body pointer built by `absoluteBodyLinkPrefix`, so the layer's
+ * character total moves by one character per stub for every character of
+ * package-root prefix — 89 characters per character on the real corpus. A
+ * number that moves with the runner's directory name measures the runner as
+ * much as the corpus, which is why `estate-count-budget.json` was deleted from
+ * this repository.
+ *
+ * SUBSTITUTED, NOT STRIPPED. Every absolute path becomes a fixed-width token
+ * rather than vanishing, so the figure still accounts for the fact that a
+ * pointer is there. Stripping would make a stub with a pointer and a stub
+ * without one read alike, which is a different measurement than the one a
+ * ceiling wants.
+ *
+ * THE NORMALISED FIGURE IS NOT "WHAT THE HOST LOADS". The host loads the real
+ * text, absolute path and all, and {@link
+ * import('./installed_layer.js').LayerReading.chars} stays the figure for that
+ * question. This one answers "is the corpus growing", which is the only
+ * question a comparison across two machines or two revisions can honestly ask.
+ */
+
+/**
+ * What every absolute path is replaced with.
+ *
+ * Fixed width by construction — it contains no path separator, which is also
+ * what makes {@link normaliseLayerText} idempotent.
+ */
+export const ABSOLUTE_PATH_TOKEN = '<abs>';
+
+/**
+ * A POSIX absolute path: two or more `/`-led segments.
+ *
+ * TWO, NOT ONE. A single segment admits ordinary prose — `and/or`, a bare
+ * `/rules` in a sentence — and a one-segment path cannot carry a root prefix
+ * long enough to be the drift this module is about.
+ *
+ * The lookbehind refuses a start that is already inside something: a word
+ * character (so `and/or` is prose), another separator (so the `//` of a URL
+ * authority is not entered), and `:` (so a scheme is not split).
+ */
+const POSIX_ABSOLUTE = /(?<![A-Za-z0-9._~%@+:/\\-])(?:\/[A-Za-z0-9._@+~-]+){2,}/g;
+
+/**
+ * A Windows drive path. The installer runs there too, and its pointer carries
+ * the same drift with `\` for `/`.
+ */
+const WINDOWS_ABSOLUTE = /(?<![A-Za-z0-9._~%@+:/\\-])[A-Za-z]:(?:[\\/][A-Za-z0-9._@+~-]+)+/g;
+
+/**
+ * Substitute every absolute-path occurrence in one rule's loaded text.
+ *
+ * Pure, total and idempotent: the token contains no separator, so a second
+ * pass finds nothing left to replace. Callers measure `.length` of the result;
+ * they never ship it as text a host reads.
+ */
+export function normaliseLayerText(text: string): string {
+    return text
+        .replace(WINDOWS_ABSOLUTE, ABSOLUTE_PATH_TOKEN)
+        .replace(POSIX_ABSOLUTE, ABSOLUTE_PATH_TOKEN);
+}

package/src/scripts/_lib/instructions_loaded_classify.ts

@@ -0,0 +1,75 @@
+/**
+ * One captured `InstructionsLoaded` line, classified into what the arrival
+ * record is built from. Runs at read time, never in the hook.
+ *
+ * The host fires the event once per loaded `CLAUDE.md` / `.claude/rules/*.md`,
+ * with `file_path`, `memory_type`, `load_reason` and, for lazy loads, the
+ * triggering path. Anything this cannot read with certainty becomes an
+ * `unknown` line — never an arrival — so a host that changes the payload
+ * degrades the record to "not observed" instead of to a false "loaded".
+ */
+import { captureInstructionsLoaded, type CaptureLine } from './instructions_loaded_event.js';
+
+/** The `load_reason` values the host documents. Any other value is `unknown`. */
+export const LOAD_REASONS = ['session_start', 'nested_traversal', 'path_glob_match', 'include', 'compact'] as const;
+export type LoadReason = (typeof LOAD_REASONS)[number];
+
+/** A payload that is not an object at all carries no session and is never written, so it has no reason here. */
+export type UnknownWhy = 'event-mismatch' | 'no-file-path' | 'unknown-load-reason';
+
+interface LineBase {
+    readonly v: 1;
+    readonly ts: string;
+    readonly session: string | null;
+    readonly host_version: string | null;
+    readonly launch: string | null;
+}
+
+export interface LoadedLine extends LineBase {
+    readonly event: 'loaded';
+    readonly file: string;
+    readonly kind: 'rule' | 'memory' | 'other';
+    readonly scope: 'user' | 'project';
+    readonly reason: LoadReason;
+}
+
+export interface UnknownLine extends LineBase {
+    readonly event: 'unknown';
+    readonly why: UnknownWhy;
+}
+
+export type ObserverLine = LoadedLine | UnknownLine;
+
+/** `claude-code_2-1-299_agent` → `2.1.299`; anything else → null. */
+export function hostVersionFromAgent(agent: string | null | undefined): string | null {
+    const m = /^claude-code_(\d+)-(\d+)-(\d+)(?:_|$)/.exec(agent ?? '');
+    return m ? `${m[1]}.${m[2]}.${m[3]}` : null;
+}
+
+export function hostVersionFromEnv(env: NodeJS.ProcessEnv): string | null {
+    return hostVersionFromAgent(env['AI_AGENT']);
+}
+
+export function classifyCapture(c: CaptureLine): ObserverLine {
+    const base: LineBase = {
+        v: 1,
+        ts: c.ts,
+        session: c.session,
+        host_version: hostVersionFromAgent(c.agent),
+        launch: c.launch !== null && /^[a-z][a-z0-9-]{0,31}$/.test(c.launch) ? c.launch : null,
+    };
+    const unknown = (why: UnknownWhy): UnknownLine => ({ ...base, event: 'unknown', why });
+    if (c.name !== 'InstructionsLoaded') return unknown('event-mismatch');
+    if (c.file === null || !c.file.endsWith('.md')) return unknown('no-file-path');
+    if (!(LOAD_REASONS as readonly (string | null)[]).includes(c.reason)) return unknown('unknown-load-reason');
+    const kind = c.rules ? 'rule' : c.file === 'CLAUDE.md' ? 'memory' : 'other';
+    return { ...base, event: 'loaded', file: c.file, kind, scope: c.user ? 'user' : 'project', reason: c.reason as LoadReason };
+}
+
+/** Capture and classify in one step — the path a fixture takes. */
+export function classifyInstructionsLoaded(
+    payload: unknown,
+    ctx: { readonly ts: string; readonly home: string; readonly env: NodeJS.ProcessEnv },
+): ObserverLine {
+    return classifyCapture(captureInstructionsLoaded(payload, ctx.ts, ctx.home, ctx.env));
+}

package/src/scripts/_lib/instructions_loaded_event.ts

@@ -0,0 +1,53 @@
+/**
+ * What the `InstructionsLoaded` observer writes for one host event — the
+ * capture, not the verdict. It runs inside the dispatcher bundle on every
+ * instruction load, so it does the least that keeps the line private: every
+ * string is kept only when it is a short id-shaped token, and the file path is
+ * reduced to its basename plus two booleans before anything is written. Whether
+ * the event is a valid load is decided later, outside the bundle, by
+ * `instructions_loaded_classify.ts`.
+ */
+
+export interface CaptureLine {
+    readonly v: 2;
+    readonly ts: string;
+    /** The host's own agent string, e.g. `claude-code_2-1-299_agent`. */
+    readonly agent: string | null;
+    readonly launch: string | null;
+    readonly session: string | null;
+    readonly name: string | null;
+    readonly reason: string | null;
+    readonly file: string | null;
+    /** The path ran through a `.claude/rules/` directory. */
+    readonly rules: boolean;
+    /** The path sat under the user's own `~/.claude/`. */
+    readonly user: boolean;
+}
+
+/** A token that is safe as a filename and carries no path: starts alphanumeric, no separators. */
+export const ID_SHAPE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+/** The one rule for which directory entries are session files — the reader and the prune share it. */
+export const isSessionFile = (f: string): boolean => f.endsWith('.jsonl') && ID_SHAPE_RE.test(f.slice(0, -6));
+
+const idShaped = (v: unknown): string | null => (typeof v === 'string' && ID_SHAPE_RE.test(v) ? v : null);
+
+export function captureInstructionsLoaded(payload: unknown, ts: string, home: string, env: NodeJS.ProcessEnv): CaptureLine {
+    const p = (typeof payload === 'object' && payload !== null && !Array.isArray(payload) ? payload : {}) as Record<string, unknown>;
+    const raw = String(p['file_path'] ?? '').replace(/\\/g, '/');
+    // Only an absolute path with no `.`/`..` segment and no doubled separator is read at all.
+    const norm = /^([A-Za-z]:)?\//.test(raw) && !/\/\.{0,2}\//.test(raw) ? raw : '';
+    const h = home.replace(/\\/g, '/').replace(/\/+$/, '');
+    return {
+        v: 2,
+        ts,
+        agent: idShaped(env['AI_AGENT']),
+        launch: idShaped(env['CLAUDE_CODE_ENTRYPOINT']),
+        session: idShaped(p['session_id']),
+        name: idShaped(p['hook_event_name']),
+        reason: idShaped(p['load_reason']),
+        file: idShaped(norm.slice(norm.lastIndexOf('/') + 1)),
+        rules: norm.includes('/.claude/rules/'),
+        user: h !== '' && norm.startsWith(`${h}/.claude/`),
+    };
+}

package/src/scripts/_lib/knowledge_global_redaction.ts

@@ -41,6 +41,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import {
     redact_low_impact_entry,
 } from '../ai_council/redact_low_impact_entry.js';
+import { HIDDEN_UNICODE_RE } from './egress_normalize.js';
 import type { RedactionViolation } from '../ai_council/redact_low_impact_entry.js';
 
 const _ROOT = path.resolve(path.dirname(_thisFile()), '..', '..');
@@ -130,8 +131,7 @@ function _compileIgnoreCase(pattern: string): RegExp {
 // council re-evaluation (2026-07-11). Presence is itself a violation:
 // a knowledge card has no legitimate need for invisible characters, and
 // halt-and-surface (never silent-rewrite) is this gate's contract.
-const _HIDDEN_UNICODE_RE =
-    /[­​-‏‪-‮⁠-⁤⁦-⁩\u{E0000}-\u{E007F}]/gu;
+const _HIDDEN_UNICODE_RE = HIDDEN_UNICODE_RE;
 
 /**
  * Combined privacy-floor + source-confidentiality scan over `text`.