@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/hooks/block_config_weakening.ts

@@ -45,14 +45,56 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+// `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,
+    classOfPath,
+    parseSettingsClassRows,
+    type SettingsClass,
+} from '../../shared/settingsClasses.js';
 import { EDIT_TOOLS } from '../minimal_safe_diff_hook.js';
 import { readHookStdin } from './hook_stdin.js';
+import { EXIT_ALLOW, EXIT_BLOCK, EXIT_WARN } from './exit_codes.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
-const EXIT_ALLOW = 0;
-const EXIT_BLOCK = 1;
-const EXIT_WARN = 2;
+/**
+ * This package's own root — where the shipped class contract lives.
+ *
+ * RESOLVED BY SEARCH, not by counting `..` segments. This file runs from three
+ * layouts: the source tree, an installed `node_modules/@event4u/agent-config/`,
+ * and inlined into `dist/hooks/dispatch.js`, where every module shares the
+ * BUNDLE's `import.meta.url` and a fixed hop count lands somewhere else
+ * entirely. A review flagged the fixed-hop version as resolving a different
+ * root from the one the package occupies; walking up to the nearest directory
+ * that actually carries the contract answers the question the guard is asking
+ * ("where is the contract") instead of a proxy for it.
+ *
+ * `null` when no ancestor carries it — which is the fail-closed input to
+ * `readClassIndex`, not a silent default root.
+ */
+export function findPackageRoot(from: string): string | null {
+    let dir = path.dirname(from);
+    for (let i = 0; i < 12; i++) {
+        if (fs.existsSync(path.join(dir, SETTINGS_CLASSES_RELATIVE))) return dir;
+        const up = path.dirname(dir);
+        if (up === dir) break;
+        dir = up;
+    }
+    return null;
+}
 
 /**
  * The stated cap from `autonomous-execution` § Antipattern. Crossing it in one
@@ -81,7 +123,18 @@ const _PATH_KEYS: readonly string[] = ['file_path', 'path', 'target_file', 'file
  * where "weakening" needs context a tool call does not carry (a baseline count
  * may legitimately reset after a refactor); those warn and never block.
  */
-export type ConfigKind = 'allowlist' | 'advisory' | null;
+export type ConfigKind = 'allowlist' | 'advisory' | 'class-c' | null;
+
+/**
+ * Project settings files 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'];
+
+/** Where the class contract lives, relative to the package root. */
+export const SETTINGS_CLASSES_RELATIVE = 'docs/contracts/settings-classes.md';
 
 /** Classify a target path into a config surface, or null for everything else. */
 export function classify_target(p: string): ConfigKind {
@@ -96,9 +149,154 @@ export function classify_target(p: string): ConfigKind {
     if (/-budget(s)?\.(json|ya?ml)$/.test(base) || base === 'budgets.yml') {
         return 'advisory';
     }
+    // `settings.json` only under a host directory: the bare name is common
+    // enough elsewhere that classifying it on the basename alone would fence
+    // files that carry no settings key at all.
+    if (base === 'settings.json') {
+        return /(^|\/)\.(claude|cursor|augment|windsurf)\/settings\.json$/.test(posix) ? 'class-c' : null;
+    }
+    if (CLASS_C_BASENAMES.includes(base)) {
+        return 'class-c';
+    }
     return null;
 }
 
+/**
+ * Leaf key paths of a parsed settings document, dotted.
+ *
+ * LEAVES ONLY, and the choice is load-bearing in both directions. A class-C key
+ * whose value is a MAP (`hooks`, say) has children that never appear as their
+ * own rows in the contract, so emitting only leaves and letting `classOfPath`
+ * walk up to the nearest classified ancestor is what makes `hooks.enabled`
+ * resolve to C. Emitting the interior nodes as well would double-count the same
+ * change and report a parent that nothing edited.
+ */
+export function leafPaths(value: unknown, prefix = ''): Map<string, string> {
+    const out = new Map<string, string>();
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        if (prefix !== '') out.set(prefix, JSON.stringify(value ?? null));
+        return out;
+    }
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+        const key = prefix === '' ? k : `${prefix}.${k}`;
+        for (const [ck, cv] of leafPaths(v, key)) out.set(ck, cv);
+    }
+    return out;
+}
+
+/**
+ * Parse a settings document, or `null` when it is not parseable.
+ *
+ * `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 {
+        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;
+    }
+}
+
+/** Dotted paths whose value differs between two settings documents. */
+export function changedKeys(before: unknown, after: unknown): string[] {
+    const a = leafPaths(before);
+    const b = leafPaths(after);
+    const out = new Set<string>();
+    for (const [k, v] of b) if (a.get(k) !== v) out.add(k);
+    for (const k of a.keys()) if (!b.has(k)) out.add(k);
+    return [...out].sort();
+}
+
+/**
+ * The class index, read from the shipped contract. `null` when it cannot be
+ * read AT ALL, which the caller treats as fail-closed.
+ *
+ * Not cached: the file is small, and a cache would keep a stale fence alive
+ * across an upgrade that reclassified a key — the same reasoning the server's
+ * own reader states for the same file.
+ */
+export function readClassIndex(packageRoot: string): Map<string, SettingsClass> | null {
+    try {
+        const text = fs.readFileSync(path.join(packageRoot, SETTINGS_CLASSES_RELATIVE), 'utf-8');
+        const index = buildSettingsClassIndex(parseSettingsClassRows(text));
+        return index.size === 0 ? null : index;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * The guarded subset of a change list.
+ *
+ * A key is guarded when its nearest classified ancestor is C, and ALSO when
+ * nothing on its path is classified at all — the same per-key refusal
+ * `settings:set` and the GUI write route already apply, reached here through
+ * the same shared classifier rather than a second copy of the rule.
+ */
+export function guardedKeys(index: ReadonlyMap<string, SettingsClass> | null, keys: readonly string[]): string[] {
+    if (index === null) return [...keys];
+    return keys.filter((k) => {
+        const cls = classOfPath(index, k);
+        return cls === 'C' || cls === undefined;
+    });
+}
+
 /**
  * Count allowlist entries in a blob.
  *
@@ -167,6 +365,89 @@ export interface Decision {
 }
 
 /** Decide from the cumulative session total for one allowlist file. */
+/**
+ * The refusal reason for a class-C settings edit, or `null` to allow.
+ *
+ * WHAT THIS FENCES, and what it deliberately does not. The unit is the KEY, not
+ * the file: a Class A key stays agent-writable through this path exactly as it
+ * is through `settings:set`, and fencing the whole file would make an ordinary
+ * preference edit need a human. Only a key the contract classifies C — or one
+ * nothing on its path classifies at all, which is the same fail-closed default
+ * the CLI writer applies — is refused.
+ *
+ * THE UNPARSEABLE CASES REFUSE, both of them, and for the same reason. A
+ * contract this guard cannot read leaves it with no way to tell a C key from an
+ * A key; a resulting document it cannot parse leaves it with no key list at
+ * all. Allowing either would mean the fence is lifted by making one file
+ * unreadable for the length of one tool call, which is a bypass with no
+ * authorisation step in it.
+ *
+ * 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.
+ */
+export function classCVerdict(
+    ti: JsonObject,
+    on_disk: string | null,
+    rel_path: string,
+    index: ReadonlyMap<string, SettingsClass> | null,
+): string | null {
+    const before = on_disk === null ? null : parseSettingsDoc(on_disk, rel_path);
+
+    const content = ti['content'];
+    const oldStr = ti['old_string'];
+    const newStr = ti['new_string'];
+    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
+        // `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
+        // this guard while the real edit changed it — the guard evaluating a
+        // different edit from the one executed. Reported by an independent
+        // review before this landed.
+        const all = ti['replace_all'];
+        if (all !== undefined && typeof all !== 'boolean') {
+            return (
+                `${rel_path}: this edit carries a \`replace_all\` value the guard cannot ` +
+                'interpret, so the text it would produce is unknown and no key can be ' +
+                'cleared. Re-send it as a plain edit, or write the change through ' +
+                '`agent-config settings:set`.'
+            );
+        }
+        afterText = all === true ? on_disk.split(oldStr).join(newStr) : on_disk.replace(oldStr, newStr);
+    }
+    if (afterText === null) return null;
+
+    const after = parseSettingsDoc(afterText, rel_path);
+    if (after === null) {
+        return (
+            `${rel_path}: the result of this edit does not parse as settings, so no key ` +
+            'list can be derived and no key can be cleared. Fix the syntax, or write the ' +
+            'change through `agent-config settings:set`, which refuses a Class C key by name.'
+        );
+    }
+
+    const guarded = guardedKeys(index, changedKeys(before, after));
+    if (guarded.length === 0) return null;
+
+    const unreadable =
+        index === null
+            ? ' The class contract could not be read, so EVERY changed key is treated as ' +
+              'guarded — that is the fail-closed direction, not a classification.'
+            : '';
+    return (
+        `${rel_path}: this edit changes ${String(guarded.length)} guarded settings key(s) — ` +
+        `${guarded.slice(0, 5).join(', ')}${guarded.length > 5 ? ', …' : ''}.` +
+        unreadable +
+        ' A Class C key is a policy dial (spend ceiling, allowlist, gate switch, hooks) and ' +
+        'is a human edit by contract: docs/contracts/settings-classes.md. Every other key in ' +
+        'this file stays writable.'
+    );
+}
+
 export function decide(kind: ConfigKind, rel_path: string, session_total: number, added: number): Decision {
     if (kind === null || added <= 0) {
         return { action: 'allow', reason: '' };
@@ -292,6 +573,15 @@ export function main(): number {
         } catch {
             on_disk = null;
         }
+        if (kind === 'class-c') {
+            const rel_c = path.relative(root, abs) || p;
+            const pkg = findPackageRoot(_HERE);
+            const verdict = classCVerdict(ti, on_disk, rel_c, pkg === null ? null : readClassIndex(pkg));
+            if (verdict === null) continue;
+            process.stderr.write(`block-config-weakening: BLOCKED — ${verdict}\n`);
+            return EXIT_BLOCK;
+        }
+
         const added = added_entries(ti, on_disk);
         if (added <= 0) {
             continue;

package/src/scripts/hooks/block_kernel_rule_writes.ts

@@ -49,6 +49,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import * as path from 'node:path';
 
 import { is_kernel_rule } from '../_lib/kernel_rules.js';
+import { shellWriteTarget } from '../_lib/shell_write_shapes.js';
 import { EDIT_TOOLS } from '../minimal_safe_diff_hook.js';
 import { COMMAND_TOOLS } from '../before_complete_hook.js';
 import { readHookStdin } from './hook_stdin.js';
@@ -133,87 +134,17 @@ export function targets_kernel_rule(filePath: string): string | null {
     return basename.replace(/\.md$/, '');
 }
 
-/** In-place mutators that name their target as a plain argument. */
-const _MUTATOR_VERBS: ReadonlySet<string> = new Set([
-    'sed',
-    'tee',
-    'truncate',
-    'rm',
-    'shred',
-]);
-/** Verbs whose LAST positional argument is the destination. */
-const _DEST_LAST_VERBS: ReadonlySet<string> = new Set(['mv', 'cp', 'install', 'rsync']);
-
 /**
- * Shell tokens that, in a command naming a kernel rule path, mean the path is
- * being WRITTEN rather than read. Reads (`cat`, `grep`, `head`, `diff`,
- * `git show`) carry none of these and stay allowed — a kernel rule is
- * immutable, not secret.
+ * The kernel rule a command WRITES, or null.
+ *
+ * The shape catalogue moved to `_lib/shell_write_shapes.ts` when
+ * `block_plumbing_writes.ts` needed the same shapes over a different file set
+ * (road-to-a-kernel-that-guards-its-plumbing 1.2). Behaviour here is unchanged:
+ * the narrowness, the reads-stay-allowed rule and the known-open interpreter
+ * residual are all properties of that shared module now, stated in its header.
  */
 function _bash_targets_kernel_rule(command: string): string | null {
-    // Cheap reject first: no kernel-rule path in the string at all.
-    const tokens = command.split(/\s+/).filter((t) => t.length > 0);
-    const stripped = tokens.map((t) => t.replace(/^['"]|['"]$/g, ''));
-    const ruleOf = (t: string): string | null => targets_kernel_rule(t);
-    if (!stripped.some((t) => ruleOf(t) !== null)) {
-        return null;
-    }
-
-    // 1. Redirection into the path: `> p`, `>> p`, `>p`, `>>p`.
-    for (let i = 0; i < stripped.length; i += 1) {
-        const tok = stripped[i] as string;
-        const inline = /^>{1,2}(.+)$/.exec(tok);
-        if (inline) {
-            const r = ruleOf(inline[1] as string);
-            if (r !== null) {
-                return r;
-            }
-        }
-        if (tok === '>' || tok === '>>') {
-            const next = stripped[i + 1];
-            if (typeof next === 'string') {
-                const r = ruleOf(next);
-                if (r !== null) {
-                    return r;
-                }
-            }
-        }
-    }
-
-    // 2. A mutator verb anywhere in the pipeline, with the path as an argument.
-    //    `sed` only counts in its in-place form — `sed 's/x/y/' file` prints.
-    const verbs = new Set<string>();
-    let prevWasSeparator = true;
-    for (const tok of stripped) {
-        if (['&&', '||', ';', '|'].includes(tok)) {
-            prevWasSeparator = true;
-            continue;
-        }
-        if (prevWasSeparator && !tok.startsWith('-')) {
-            verbs.add(path.basename(tok));
-            prevWasSeparator = false;
-        }
-    }
-    const sedInPlace = verbs.has('sed') && stripped.some((t) => /^-i/.test(t));
-    for (const verb of verbs) {
-        if (verb === 'sed' && !sedInPlace) {
-            continue;
-        }
-        if (_MUTATOR_VERBS.has(verb)) {
-            const hit = stripped.map(ruleOf).find((r) => r !== null);
-            if (hit !== undefined && hit !== null) {
-                return hit;
-            }
-        }
-        if (_DEST_LAST_VERBS.has(verb)) {
-            const last = stripped[stripped.length - 1] as string;
-            const r = ruleOf(last);
-            if (r !== null) {
-                return r;
-            }
-        }
-    }
-    return null;
+    return shellWriteTarget(command, targets_kernel_rule);
 }
 
 /**