@event4u/agent-config 16.0.0 → 16.2.0

package/src/scripts/hook_manifest.yaml

@@ -150,6 +150,21 @@ concerns:
   # Warn-in-context (exit 2), never blocks. Default-OFF: no-ops unless
   # hooks.injection_scan.enabled is true in .agent-settings.yml. The runtime
   # backstop layered on the always-on untrusted-input-defense rule.
+  #
+  # THE INPUT IT READS, AND WHY IT CANNOT MOVE TO A BLOCKING SLOT
+  # (road-to-a-content-scanner-on-a-slot-that-can-refuse 1.1). It scans the
+  # tool RESULT -- fetched pages, file reads, MCP/tool responses -- which is
+  # why it declares `result` below. `pre_tool_use` is the only slot on this
+  # host with a non-null `block_exit`, and a pre-call payload has no tool
+  # response in it: the `result` body class resolves to `tool_response` /
+  # `toolResponse` / `tool_result` / `toolUseResult` (hooks/payload_stub.ts),
+  # none of which exist before the call runs. So rebinding for the deny would
+  # leave the scanner reading the arguments it was never written to inspect --
+  # more enforcing-looking and strictly less detecting. It stays on
+  # `post_tool_use` and the published claims say `detected, not blocked`;
+  # `docs/enforcement-by-host.md` § "The slot rows are not a statement about
+  # any concern" carries the reasoning, and `check_enforcement_matrix` prints
+  # the per-host binding audit that keeps it from drifting back.
   injection-scan:
     script: src/scripts/injection_scan_hook.ts
     args: []
@@ -186,6 +201,27 @@ concerns:
     fail_closed: true
     severity: blocking
     needs_payload_bodies: [input]
+  # road-to-a-kernel-that-guards-its-plumbing 1.2 — the build-output half of
+  # "one mechanism per file class". PreToolUse guard: DENIES Write/Edit/
+  # NotebookEdit and the shell write shapes whose target is
+  # `dist/hooks/dispatch.js` (the esbuild bundle) or `hooks/hooks.json` (the
+  # host binding file). Both are GENERATED — by `npm run build:hooks` and by
+  # condense.ts via `task sync` — so a hand edit is never legitimate, and a
+  # hand-edited bundle reaches every dispatch while being invisible in a source
+  # review. The plumbing SOURCES beside them (hook_manifest.yaml,
+  # host_lowering.yaml, the *-dispatcher.sh trampolines, both budget files) are
+  # edited on purpose all the time and carry the ADR-268 § 4 ratification
+  # RECORD instead — check_kernel_edit_ratified, path set extended by step 1.1.
+  # The legitimate builds pass: they reach these files through a build tool,
+  # not through a redirect / in-place sed / tee / mv shape. fail_closed: true —
+  # the guarantee is about a DETECTED write; a malformed envelope with no
+  # target allows. No agent-accessible override; the fix is to rebuild.
+  block-plumbing-writes:
+    script: src/scripts/hooks/block_plumbing_writes.ts
+    args: []
+    fail_closed: true
+    severity: blocking
+    needs_payload_bodies: [input]
   # road-to-asked-not-parked Phase 5.1 — one question per structured-ask call.
   # PreToolUse guard: DENIES a call to a host's native question picker whose
   # payload carries more than one question. `ask-when-uncertain`'s Iron Law is
@@ -462,8 +498,9 @@ concerns:
     # `name === 'Grep' || name === 'Glob'` and `name === 'Read'`
     # (code_graph_context_hook.ts), and a test pins the manifest list against it.
     #
-    # Deliberately NOT declared on the three blocking PreToolUse guards
-    # (block-no-verify, block-kernel-rule-writes, block-config-weakening): their
+    # Deliberately NOT declared on the four blocking PreToolUse guards
+    # (block-no-verify, block-kernel-rule-writes, block-plumbing-writes,
+    # block-config-weakening): their
     # tool sets span host-specific naming variants (`Bash` / `BashTool` /
     # `launch-process` / `launch_process`, `str-replace-editor` /
     # `str_replace_editor` / `save-file` / …), so a list that misses one variant
@@ -867,11 +904,18 @@ concerns:
   # pointer-shaped rule delivery is the 36.2 %-against-48 % run at
   # docs/CLAIMS.md:188-189.
   #
-  # DEFAULT OFF, and off means ZERO bytes: the concern returns before reading
-  # `dist/router.json` unless `lean_projection.mode: delivery`. Under every
-  # shipped default it emits nothing, so its `hook-token-budget.json` row is
-  # registered against the derived per-prompt cap rather than a measured
-  # emission — there is no measured emission yet, and saying so is the point.
+  # SHIPPED ON FOR CLAUDE CODE SINCE ADR-267 — corrected 2026-09-12, because
+  # this comment still read "DEFAULT OFF … under every shipped default it emits
+  # nothing … there is no measured emission yet" after its twin in
+  # `hooks/rule_inject_hook.ts` had already been corrected. The shipped template
+  # carries `lean_projection.mode: delivery` with `hosts: [claude-code]`, and
+  # the emission IS measured: p50 6,674 B, p90 16,188 B, max 20,406 B over 318
+  # gate-open fires on the frozen corpus, which is the distribution the
+  # `user_prompt_submit` raise in `hook-token-budget.json` is derived from.
+  #
+  # OFF STILL MEANS ZERO BYTES: the concern returns before reading
+  # `dist/router.json` unless the resolved (mode, hosts) pair thins THIS host —
+  # so on any other host, and on a `mode: eager-all` rollback, it emits nothing.
   #
   # DELIBERATELY NOT nudge-class: it carries no `nudge_rank`. A rule body is not
   # a hint the model may ignore, so the one-ranked-nudge-per-slot exclusivity
@@ -904,6 +948,19 @@ concerns:
   # future blocking decision has a measured distribution to cite. Never
   # blocks the turn — see the hook's file header for the `host_semantics.
   # emitFor` proof. fail_closed: false.
+  # The reader the delivered-obligation record never had. SHADOW ONLY: it
+  # computes the verdict an armed detector would reach, records one row per
+  # missing SET, and returns allow on every path — arming is gated on a bar
+  # pre-registered in docs/CLAIMS.md before any code able to refuse exists.
+  # advisory + fail_closed: false, and both are load-bearing rather than
+  # conventional: this estate already carries one BLOCKING turn-end concern,
+  # and the first-ranked risk against this lane is that a second one refuses a
+  # clean turn and an operator disables the carrier for good.
+  obligation-settle:
+    script: src/scripts/hooks/obligation_settle_hook.ts
+    args: []
+    fail_closed: false
+    severity: advisory
   end-review-nudge:
     script: src/scripts/hooks/end_review_nudge_hook.ts
     args: []
@@ -1043,6 +1100,41 @@ concerns:
     # Provable from the hook's own source: READ_TOOLS ∪ WRITE_TOOLS.
     tools: [Read, Edit, Write]
     needs_payload_bodies: [input]
+  # Memory recall — delivers a memory the store ALREADY holds, at the moment
+  # the tool call it is about would run. The finding: in one long autonomous
+  # run the agent walked into four traps that each had a memory file written
+  # weeks earlier, and the store's own index records "of eleven error classes
+  # in one session, nine had a file here already and all nine were read AFTER
+  # the failure". `memory_lookup` is a CLI nothing calls automatically, so
+  # recall is model-carried and fails exactly when the agent is busy.
+  #
+  # A COMMITTED TRIGGER TABLE, never a similarity score: `RECALL_RULES` maps
+  # one precisely-decidable payload condition to one memory slug, so the floor
+  # is a predicate rather than a threshold and every row is replayed against a
+  # real payload in tests. A fuzzy match over 467 memory files would fire on
+  # most calls and be tuned out within a day.
+  #
+  # ADVISORY ONLY — binds on the blocking slot and never returns exit 1 on any
+  # path; a stale trigger row must never deny work. Delivery mirrors
+  # `reread-guard` (exit-2 warn, host-facing exit 0 on the verified `claude`
+  # platform). ONE memory per fire, pointer + the memory's own description,
+  # hard-capped at 768 bytes (registered BELOW the 1024 default in
+  # hook-token-budget.json so a later change that injects memory BODIES fails
+  # the build). Per-session per-slug latch under
+  # agents/runtime/state/memory-recall/ — slug keys and timestamps only, no
+  # field able to hold a path or a command. The silent path does zero fs work.
+  # An unresolvable store emits the pointer anyway plus a stderr diagnostic:
+  # an absent store and a store with no match are different answers.
+  # fail_closed: false.
+  memory-recall:
+    script: src/scripts/hooks/memory_recall_hook.ts
+    args: []
+    fail_closed: false
+    severity: advisory
+    # Provable from the hook's own source: the union of the `tools` sets on
+    # RECALL_RULES — COMMAND_TOOLS (rules 1 and 4) ∪ EDIT_TOOLS (rules 2, 3).
+    tools: [Bash, Edit, Write, MultiEdit, str-replace-editor, save-file, launch-process]
+    needs_payload_bodies: [input]
   # road-to-token-economy-recycling Phases 1.1 / 3.2 / 4.2 — session
   # end-of-life instrument + recycle advisory. Every Stop, incrementally
   # folds the transcript's newly appended lines (payload `transcript_path`,
@@ -1311,17 +1403,35 @@ roles:
     drop: [delegation-nudge, skill-route, end-review-nudge, review-baseline, council-availability, team-review-gate, self-repair, session-eol, interruption-ledger]
 
 platforms:
+  # `ask:` — the SHAPE of this host's user-facing question primitive.
+  #
+  #   native   the host exposes a structured-ask tool the agent can call, and
+  #            an owner-owned question uses it, carrying the recommendation as
+  #            its default option.
+  #   text     no such primitive; the numbered text block is the ask, and it
+  #            keeps its own Iron Law.
+  #
+  # DECLARED, NOT PROBED, and the difference matters: this row records what the
+  # host's documented tool surface offers, and nothing here verifies it at
+  # runtime. A host declaring `native` whose primitive turns out to be absent
+  # degrades to the text block — the same output either way — so the risk of a
+  # wrong row is a missed upgrade, never a broken ask.
+  #
+  # It exists so the shape is a row `hooks:status` prints rather than an
+  # assumption a contract makes on every host's behalf.
   augment:
+    ask:              text
     session_start:    [chat-history, hot-context, handoff-context, session-canary, council-availability, telemetry-disclosure, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
     session_end:      [chat-history, memory-learn, session-register, roadmap-progress, telemetry-flush]
     stop:             [chat-history, verify-before-complete, self-repair, session-register, roadmap-progress, design-pass-stop]
-    pre_tool_use:     [block-no-verify, evidence-independence, block-kernel-rule-writes, block-config-weakening, block-speaking-inbox-dir, rtk-wrap, design-slop, ui-route-nudge, code-graph-context, chain-nudge, ship-diff-volume, reread-guard]
+    pre_tool_use:     [block-no-verify, evidence-independence, block-kernel-rule-writes, block-plumbing-writes, block-config-weakening, block-speaking-inbox-dir, rtk-wrap, design-slop, ui-route-nudge, code-graph-context, chain-nudge, ship-diff-volume, reread-guard, memory-recall]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, push-settle, orchestration-record, telemetry-usage, tool-result-bytes, edit-shape, comment-discipline, design-pass]
 
   claude:
+    ask:              native
     session_start:    [chat-history, hot-context, handoff-context, session-canary, council-availability, telemetry-disclosure, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register, review-baseline, journal-record]
     session_end:      [chat-history, memory-learn, session-register, roadmap-progress, telemetry-flush, journal-record]
-    stop:             [chat-history, verify-before-complete, team-review-gate, end-review-nudge, turn-end-gate, self-repair, session-register, session-eol, interruption-ledger, roadmap-progress, design-pass-stop, suggestion-capture, journal-record, run-continuation]
+    stop:             [chat-history, verify-before-complete, team-review-gate, end-review-nudge, obligation-settle, turn-end-gate, self-repair, session-register, session-eol, interruption-ledger, roadmap-progress, design-pass-stop, suggestion-capture, journal-record, run-continuation]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, delegation-nudge, skill-route, git-authorization, session-canary, self-repair, session-register, rule-inject, suggestion-capture, journal-record]
     # `rule-inject` was bound here and is not any more
     # (road-to-delivery-for-every-host 3.2, owner ruling E2). E2's strategy is
@@ -1346,7 +1456,7 @@ platforms:
     # (+16,329 GPT tok, +69 % on the thin rule layer) are in
     # `project_thin_rules.path_only_ids`; the receiver is
     # `agents/roadmaps/stubs/road-to-a-path-route-under-delivery.md`.
-    pre_tool_use:     [block-no-verify, evidence-independence, block-kernel-rule-writes, block-config-weakening, block-speaking-inbox-dir, one-question-per-ask, rtk-wrap, design-slop, ui-route-nudge, code-graph-context, chain-nudge, ship-diff-volume, reread-guard, spawn-guard-shadow, source-first-gate]
+    pre_tool_use:     [block-no-verify, evidence-independence, block-kernel-rule-writes, block-plumbing-writes, block-config-weakening, block-speaking-inbox-dir, one-question-per-ask, rtk-wrap, design-slop, ui-route-nudge, code-graph-context, chain-nudge, ship-diff-volume, reread-guard, spawn-guard-shadow, source-first-gate, memory-recall]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, push-settle, orchestration-record, telemetry-usage, tool-result-bytes, edit-shape, comment-discipline, language-mirror, design-pass, journal-record]
     # `language-mirror` — round-5 § 6.1. `pre_compact` sets a pin-lost marker;
     # the `post_tool_use` entry above re-emits the pin exactly once while that
@@ -1378,6 +1488,7 @@ platforms:
   # Decision matrix + upstream blockers tracked in
   # agents/settings/contexts/chat-history-platform-hooks.md § Cowork.
   cowork:
+    ask:              text
     session_start:    [chat-history, hot-context, handoff-context, session-canary, council-availability, telemetry-disclosure, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
     session_end:      [chat-history, memory-learn, session-register, roadmap-progress, telemetry-flush]
     # end-review-nudge and delegation-nudge are DELIBERATELY NOT bound on
@@ -1392,7 +1503,7 @@ platforms:
     # still costs the dispatch, and its entire output is thrown away.
     stop:             [chat-history, verify-before-complete, self-repair, session-register, roadmap-progress, design-pass-stop]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, self-repair, session-register]
-    pre_tool_use:     [block-no-verify, evidence-independence, block-kernel-rule-writes, block-config-weakening, block-speaking-inbox-dir, rtk-wrap, design-slop, ui-route-nudge, code-graph-context, chain-nudge, ship-diff-volume, reread-guard, spawn-guard-shadow, source-first-gate]
+    pre_tool_use:     [block-no-verify, evidence-independence, block-kernel-rule-writes, block-plumbing-writes, block-config-weakening, block-speaking-inbox-dir, rtk-wrap, design-slop, ui-route-nudge, code-graph-context, chain-nudge, ship-diff-volume, reread-guard, spawn-guard-shadow, source-first-gate, memory-recall]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, push-settle, orchestration-record, telemetry-usage, tool-result-bytes, edit-shape, comment-discipline, design-pass]
     # subagent-ledger IS bound here, unlike the two nudges above, and the
     # difference is the delivery channel rather than the platform: the nudges
@@ -1413,6 +1524,7 @@ platforms:
   # covers a session where it does not. See
   # agents/settings/contexts/chat-history-platform-hooks.md § Cursor.
   cursor:
+    ask:              text
     session_start:      [chat-history, hot-context, handoff-context, session-canary, council-availability, telemetry-disclosure, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
     session_end:        [chat-history, memory-learn, session-register, roadmap-progress, telemetry-flush]
     stop:               [chat-history, verify-before-complete, self-repair, session-register, roadmap-progress, design-pass-stop]
@@ -1428,6 +1540,7 @@ platforms:
   # both map to session_start. TaskCancel maps to stop because the
   # session is interrupted with partial state (mirrors Augment Stop).
   cline:
+    ask:              text
     session_start:      [chat-history, hot-context, handoff-context, session-canary, council-availability, telemetry-disclosure, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
     session_end:        [chat-history, memory-learn, session-register, roadmap-progress, telemetry-flush]
     stop:               [chat-history, verify-before-complete, self-repair, session-register, roadmap-progress, design-pass-stop]
@@ -1447,6 +1560,7 @@ platforms:
   # surface to record verification commands; documented limitation).
   # minimal-safe-diff is omitted entirely on Windsurf for the same reason.
   windsurf:
+    ask:              text
     session_start:      [chat-history, hot-context, handoff-context, session-canary, council-availability, telemetry-disclosure, first-run-gate, onboarding-gate, verify-before-complete, profile-staleness, wrapper-freshness, surface-probe, session-register]
     stop:               [chat-history, verify-before-complete, self-repair, session-register, design-pass-stop]
     # language-mirror IS bound here: unlike minimal-safe-diff it needs only the
@@ -1464,6 +1578,7 @@ platforms:
   # turn-check semantics. AfterAgent fires when the agent loop ends
   # — this is our `stop` slot.
   gemini:
+    ask:              text
     session_start:      [chat-history, hot-context, handoff-context, session-canary, council-availability, telemetry-disclosure, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
     session_end:        [chat-history, memory-learn, session-register, roadmap-progress, telemetry-flush]
     stop:               [chat-history, verify-before-complete, self-repair, session-register, roadmap-progress, design-pass-stop]
@@ -1474,6 +1589,7 @@ platforms:
   # there. Concerns route through rule-only fallback; the dispatcher silently
   # no-ops on --platform copilot.
   copilot:
+    ask:              text
     fallback_only: true
 
 # Native-event → agent-config-event translation table. Used by per-platform

package/src/scripts/hooks/block_config_weakening.ts

@@ -45,14 +45,45 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import * as yaml from 'js-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 +112,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 +138,100 @@ 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.
+ */
+export function parseSettingsDoc(text: string, rel: string): unknown | null {
+    try {
+        return rel.endsWith('.json') ? (JSON.parse(text) as unknown) : yaml.load(text);
+    } 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 +300,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 +508,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);
 }
 
 /**