@webpieces/ai-hook-rules 0.4.710 → 0.4.712

package/src/bin/hook-registration.d.ts

@@ -1,10 +1,19 @@
+import { AiType } from '../core/agent-event';
 /**
- * THE INSTALLED HOOK SURFACE — two hooks, both ABSOLUTE, and the ONE place their spelling is defined.
+ * THE INSTALLED HOOK SURFACE — two hooks per harness, all ABSOLUTE, and the ONE place their spelling is
+ * defined. See `HarnessRegistration` below, which is what makes "per harness" data rather than four
+ * module constants that were only ever true of Claude Code.
  *
  * ─── ONE GOVERNOR: the MAIN tree judges every tree ─────────────────────────────────────────────────
  *
- *   H1  sh "$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh" wp-ai-guards-hook   Write|…|Bash|Read
- *   H2  sh "$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh" wp-ai-rules-hook    Write|Edit|MultiEdit
+ *   Claude Code — .claude/settings.json
+ *     H1  sh "$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh" wp-ai-guards-hook  Write|…|Bash|Read
+ *     H2  sh "$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh" wp-ai-rules-hook   Write|Edit|MultiEdit
+ *   Codex — .codex/hooks.json (the SAME `hooks.PreToolUse` JSON shape, measured)
+ *     H1  sh "$PWD/.claude/webpieces/ai-hook.sh" wp-ai-guards-hook                 Bash|apply_patch
+ *     H2  sh "$PWD/.claude/webpieces/ai-hook.sh" wp-ai-rules-hook                  apply_patch
+ *
+ * ONE shim file serves all four: `.claude/` there is a path, not a claim about who is calling.
  *
  * This REPLACES a three-hook form in which these two were RELATIVE (`sh ".claude/webpieces/ai-hook.sh"`)
  * and a third hook, L-1 `guarantee-root.sh`, existed solely to guarantee that relative path resolved.
@@ -81,6 +90,12 @@ export interface HookEntry {
     matcher: string;
     hooks: HookCommand[];
 }
+/**
+ * One settings file as webpieces reads it. MEASURED: Codex's `.codex/hooks.json` uses the IDENTICAL
+ * `hooks.PreToolUse[].hooks[].command` shape, so one reader, one writer and one repair serve both files
+ * — the difference between the harnesses is entirely in the VALUES (matcher, shim anchor), which is what
+ * `HarnessRegistration` carries. The `env` block below is Claude Code's alone.
+ */
 export interface ClaudeSettings {
     hooks?: {
         PreToolUse?: HookEntry[];
@@ -90,34 +105,147 @@ export interface ClaudeSettings {
 }
 export declare const RULES_BIN = "wp-ai-rules-hook";
 export declare const GUARDS_BIN = "wp-ai-guards-hook";
-export declare const RULES_MATCHER = "Write|Edit|MultiEdit";
-export declare const GUARDS_MATCHER = "Write|Edit|MultiEdit|Bash|Read";
 /**
- * The guard-hook command — `sh "$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh" <bin>`.
+ * ONE HARNESS'S registration surface — where its hooks live, what they match, and how they name the
+ * shim. Data-only → a class, per CLAUDE.md.
  *
- * ABSOLUTE. This replaced a RELATIVE spelling, and the reversal is the whole point of this release.
+ * ─── Why this exists ──────────────────────────────────────────────────────────────────────────────
+ * The matchers and the shim command used to be four module constants written for Claude Code alone.
+ * Applied to Codex they are wrong in both halves, and the way they are wrong is SILENT:
  *
- * The relative form existed to give each git tree its own release, binary and pin. **It never delivered
- * that.** Measured 2026-08-10: a linked worktree has no `node_modules`, so ai-hook.sh's upward walk
- * executes the PRIMARY's binary — `readlink -f` resolved a worktree agent's bin to
- * `<primary>/node_modules/@webpieces/ai-hook-rules`. A worktree ran its own SCRIPT and its own CONFIG,
- * never its own release. The property was fiction, and paying for it cost an entire guard layer: a
- * relative path only resolves at a tree root, so L-1 (guarantee-root.sh) had to deny every `cd` into a
- * project subdirectory, which produced the force-to-root bug class, the reaped-worktree `cd`
- * prescription, and a measured hard deadlock where L-1 told a worktree-isolated agent to `cd` to the
- * primary clone — which the harness refuses for an isolated agent.
+ *   - MATCHER. Codex's file-editing tool is `apply_patch` (MEASURED, codex-cli 0.151.0). A matcher of
+ *     `Write|Edit|MultiEdit` matches it never, so every file rule is unreachable while the settings file
+ *     looks perfectly installed. Its shell tool IS called `Bash` — Codex reuses Claude's name — which is
+ *     the trap: half the matcher works, so the hooks appear to be running.
+ *   - ANCHOR. `$CLAUDE_PROJECT_DIR` does not exist in a Codex hook's environment (measured: 46 vars, no
+ *     such key), so the command expands to `sh "/.claude/webpieces/ai-hook.sh"`, which dies — and per the
+ *     hooks protocol a non-2 non-zero exit is a NON-BLOCKING error, i.e. a silent unguarded allow.
  *
- * Absolute resolves from ANY cwd, so L-1 has no job left and is deleted. One governor: the MAIN tree
- * judges every tree, which is what was already happening via the borrowed binary — the design now says
- * so out loud, and `VersionSyncGuard` blocks the case where that is the wrong answer.
+ * Both halves of that were live in real repos, written by a Codex Desktop sync that transliterated the
+ * Claude setup. Making the registration per-harness DATA is what stops a future harness inheriting a
+ * matcher that was never true for it.
  *
- * Invoked via `sh <file>` rather than executed directly so a missing executable bit on the checked-in
- * shim (fresh clone, a filesystem that drops the bit, git core.fileMode quirks) can never break the hook
- * with a raw `Permission denied` on every tool call. Quoted to survive spaces in the path.
+ * ─── ONE SHIM, both harnesses ─────────────────────────────────────────────────────────────────────
+ * `SHIM_MARKER` is shared deliberately: `.claude/webpieces/ai-hook.sh` is the single fail-closed entry
+ * point, and moving or duplicating it would double the L0 allowlist regexes, the drift surfaces and the
+ * cures. The `.claude/` prefix is a path, not a claim about which agent is calling.
  */
-export declare function shimCommand(bin: string): string;
-/** The registration entry for one guard bin. */
-export declare function guardHookEntry(bin: string): HookRegistrationEntry;
+export declare class HarnessRegistration {
+    readonly aiType: AiType;
+    /** How the installer and the drift report name this harness to a human. */
+    readonly label: string;
+    /** Which tool names the RULES hook (code-style, file-scoped) must see. */
+    readonly rulesMatcher: string;
+    /**
+     * Which tool names the GUARDS hook must see. Wider than the rules matcher by the shell tool and,
+     * for Claude Code, by `Read` — Read carries no guard, but the guards hook owns the
+     * per-invocation audit log, so matching it records every file the AI opens (log-and-allow fast
+     * path in hook-core.ts; a Read is never blocked). Codex has no Read tool at all: a read arrives
+     * as `Bash` running a pager, which the shell matcher already covers and read-parity synthesizes.
+     */
+    readonly guardsMatcher: string;
+    /** The settings files this harness's hooks can be installed into, relative to the repo root. */
+    readonly settingsFiles: readonly string[];
+    /**
+     * THE PREFIX THE SHIM PATH IS ANCHORED ON, and the reason each harness needs its own.
+     *
+     * **BYTE-STABILITY IS A HARD CONSTRAINT ON THE CODEX VALUE.** Codex trusts a hook entry
+     * TOFU — `~/.codex/config.toml` records a `trusted_hash` per entry — so ANY change to these bytes
+     * invalidates that trust and re-prompts the human, whose third option is `Continue without
+     * trusting (hooks won't run)`: one keystroke to a silently unguarded session. Changing this
+     * string is therefore never a cosmetic edit. The hash is NOT reproducible from outside Codex
+     * (16 encodings tried against a file we authored), so the installer can never repair trust for
+     * itself — see ./codex-trust.ts, which REPORTS and never writes.
+     */
+    readonly shimAnchor: string;
+    /**
+     * True when this harness's settings file also carries the managed `env` block. Claude Code's
+     * settings `env` is inherited by every subagent, which is what makes it the right home for the
+     * Bash-cwd pin (see managed-env.ts). Codex has no equivalent surface — and needs none: its cwd
+     * is MEASURED not to drift at all (`cd x && pwd` prints x, the next call is back at the repo
+     * root, for the coordinator and for subagents alike).
+     */
+    readonly managesEnv: boolean;
+    /** What `managedSurfaceDrift()` calls this harness's registration when it has moved. */
+    readonly registrationSurface: string;
+    constructor(aiType: AiType, 
+    /** How the installer and the drift report name this harness to a human. */
+    label: string, 
+    /** Which tool names the RULES hook (code-style, file-scoped) must see. */
+    rulesMatcher: string, 
+    /**
+     * Which tool names the GUARDS hook must see. Wider than the rules matcher by the shell tool and,
+     * for Claude Code, by `Read` — Read carries no guard, but the guards hook owns the
+     * per-invocation audit log, so matching it records every file the AI opens (log-and-allow fast
+     * path in hook-core.ts; a Read is never blocked). Codex has no Read tool at all: a read arrives
+     * as `Bash` running a pager, which the shell matcher already covers and read-parity synthesizes.
+     */
+    guardsMatcher: string, 
+    /** The settings files this harness's hooks can be installed into, relative to the repo root. */
+    settingsFiles: readonly string[], 
+    /**
+     * THE PREFIX THE SHIM PATH IS ANCHORED ON, and the reason each harness needs its own.
+     *
+     * **BYTE-STABILITY IS A HARD CONSTRAINT ON THE CODEX VALUE.** Codex trusts a hook entry
+     * TOFU — `~/.codex/config.toml` records a `trusted_hash` per entry — so ANY change to these bytes
+     * invalidates that trust and re-prompts the human, whose third option is `Continue without
+     * trusting (hooks won't run)`: one keystroke to a silently unguarded session. Changing this
+     * string is therefore never a cosmetic edit. The hash is NOT reproducible from outside Codex
+     * (16 encodings tried against a file we authored), so the installer can never repair trust for
+     * itself — see ./codex-trust.ts, which REPORTS and never writes.
+     */
+    shimAnchor: string, 
+    /**
+     * True when this harness's settings file also carries the managed `env` block. Claude Code's
+     * settings `env` is inherited by every subagent, which is what makes it the right home for the
+     * Bash-cwd pin (see managed-env.ts). Codex has no equivalent surface — and needs none: its cwd
+     * is MEASURED not to drift at all (`cd x && pwd` prints x, the next call is back at the repo
+     * root, for the coordinator and for subagents alike).
+     */
+    managesEnv: boolean, 
+    /** What `managedSurfaceDrift()` calls this harness's registration when it has moved. */
+    registrationSurface: string);
+    /** Which matcher one guard bin registers under. */
+    matcherFor(bin: string): string;
+    /**
+     * The guard-hook command — `sh "<anchor>/.claude/webpieces/ai-hook.sh" <bin>`.
+     *
+     * ABSOLUTE, in both harnesses. Claude's anchor replaced a RELATIVE spelling and that reversal is
+     * documented at length in this file's header: relative resolves only at a tree root, a hook that
+     * cannot resolve exits 127, and per the hooks reference that is a NON-BLOCKING error — a silent
+     * unguarded allow. It also cost an entire guard layer (L-1) whose only job was to police the `cd`
+     * that made the relative path resolvable.
+     *
+     * Invoked via `sh <file>` rather than executed directly so a missing executable bit on the
+     * checked-in shim (fresh clone, a filesystem that drops the bit, git core.fileMode quirks) can never
+     * break the hook with a raw `Permission denied` on every tool call. Quoted to survive spaces.
+     */
+    shimCommand(bin: string): string;
+    /** The registration entry for one guard bin under this harness. */
+    entryFor(bin: string): HookRegistrationEntry;
+    /** This harness's settings files under one repo root, absolute. */
+    settingsPaths(projectRoot: string): readonly string[];
+}
+export declare const CLAUDE_REGISTRATION: HarnessRegistration;
+/**
+ * Codex's registration, every value of it MEASURED against codex-cli 0.151.0 rather than assumed.
+ *
+ * `$PWD` is the anchor because there is no project-dir variable to use and none is needed: the payload
+ * `cwd` and the hook process's own `PWD` are both the repo root on EVERY call — for the coordinator and
+ * for subagents — and a `cd` inside one command never survives into the next. That was measured, not
+ * hoped for, and it is the same effect Claude Code gets from the managed
+ * `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` env entry. See `shimAnchor` for why these exact bytes are
+ * not free to change.
+ */
+export declare const CODEX_REGISTRATION: HarnessRegistration;
+/**
+ * Every harness webpieces arms, in installer order.
+ *
+ * The drift check, the repair and the installer all iterate THIS, so a harness cannot be armed by the
+ * installer and then left unvalidated — which is exactly the state `.codex/hooks.json` was in before it
+ * was a managed surface: written by something else, silently wrong, and invisible to every check.
+ */
+export declare const HARNESS_REGISTRATIONS: readonly HarnessRegistration[];
 /**
  * True when this PreToolUse command is one webpieces owns — in ANY spelling it has ever shipped.
  *
@@ -145,7 +273,7 @@ export declare function registeredBins(settings: ClaudeSettings): readonly strin
  * whenever the GUARDS bin was present; it is retired, and a settings file still carrying it is STALE —
  * `repairRegistration()` removes it via isManagedCommand()'s legacy marker.
  */
-export declare function expectedEntries(bins: readonly string[]): readonly HookRegistrationEntry[];
+export declare function expectedEntries(harness: HarnessRegistration, bins: readonly string[]): readonly HookRegistrationEntry[];
 /**
  * True when a settings file registers webpieces hooks in a shape this release does not expect: a
  * RELATIVE shim command, a leftover guarantee-root entry, a stray duplicate, or a wrong matcher.
@@ -153,7 +281,7 @@ export declare function expectedEntries(bins: readonly string[]): readonly HookR
  * Compared as a SET, not a sequence: Claude Code runs all matching hooks in parallel, so array order
  * carries no meaning and reordering must not read as drift.
  */
-export declare function registrationStale(settings: ClaudeSettings): boolean;
+export declare function registrationStale(harness: HarnessRegistration, settings: ClaudeSettings): boolean;
 /** Drop every webpieces-managed PreToolUse command; returns true if anything was removed. */
 export declare function dropManagedEntries(settings: ClaudeSettings): boolean;
 /** Append one PreToolUse entry. */
@@ -199,14 +327,28 @@ export declare function applyManagedEnv(settings: ClaudeSettings): boolean;
  * have been reported as drifted by fault S and then left unrepaired by its own prescribed cure. A cure
  * that skips half the surface is the failure mode `upgrade-shim.ts`'s header exists to prevent.
  */
-export declare function repairRegistration(settings: ClaudeSettings): boolean;
-/** The two project settings files the installer can write. */
-export declare function projectSettingsPaths(projectRoot: string): readonly string[];
+export declare function repairRegistration(harness: HarnessRegistration, settings: ClaudeSettings): boolean;
 export declare function readSettings(settingsPath: string): ClaudeSettings;
 export declare function writeSettings(settingsPath: string, settings: ClaudeSettings): void;
-/** True when either project settings file under `root` carries a stale registration. */
-export declare function registrationStaleAt(root: string | null): boolean;
-/** True when either project settings file under `root` is missing the managed `env` entry. */
+/**
+ * True when any settings file ONE HARNESS owns under `root` carries a stale registration.
+ *
+ * Per harness, not per repo, so the drift report can NAME which one moved — `.claude/settings.json` and
+ * `.codex/hooks.json` have different cures, and a fault that says only "the registration is stale" sends
+ * the reader to the wrong file half the time.
+ *
+ * A file that does not exist, or exists and registers no webpieces hooks, is never judged (see
+ * `registrationStale`). That is what keeps a repo which has never armed Codex from suddenly faulting on
+ * a `.codex/hooks.json` it does not have.
+ */
+export declare function registrationStaleAt(harness: HarnessRegistration, root: string | null): boolean;
+/**
+ * True when either Claude project settings file under `root` is missing the managed `env` entry.
+ *
+ * CLAUDE-ONLY by construction, and stated as such rather than looped over the harnesses: `env` is a
+ * Claude Code settings surface, Codex has no equivalent, and Codex's cwd is measured not to drift, which
+ * is the whole thing the entry is for. See HarnessRegistration.managesEnv.
+ */
 export declare function envStaleAt(root: string | null): boolean;
 /**
  * WHAT was rewritten in ONE settings file. Data-only → a class, per CLAUDE.md.
@@ -221,24 +363,39 @@ export declare class SettingsRepair {
     readonly env: boolean;
     constructor(settingsPath: string, registration: boolean, env: boolean);
 }
-/** Rewrite every stale project settings file under `root`; returns what changed, per file. */
+/**
+ * Rewrite every stale settings file under `root`, for EVERY harness; returns what changed, per file.
+ *
+ * Existing files only — this never CREATES a registration. Arming a harness is the installer's decision
+ * (`wp-install-ai-hooks`); this is the cure for one that has already been armed and has drifted, so a
+ * repo that has never armed Codex is left exactly as it was.
+ */
 export declare function repairRegistrationAt(root: string): readonly SettingsRepair[];
 /**
- * The THREE names the drift check reports, so a deny can say WHICH of them moved.
+ * The names the drift check reports, so a deny can say WHICH surface moved.
+ *
+ * There were four, then three, and there are now FOUR again — but the fourth is not the one that was
+ * deleted. `GUARANTEE_ROOT_SURFACE` went with L-1 itself: an absolutely-registered shim resolves from
+ * any cwd, so there is no launch guarantee left to police and no second .sh file to keep byte-locked. A
+ * settings file still carrying the retired H1 entry is not its own surface — it is ordinary REGISTRATION
+ * drift, which `registrationStaleAt()` reports and `repairRegistration()` fixes by removing it.
+ *
+ * The new fourth is `.codex/hooks.json`, and it is here because of what happened while it was NOT a
+ * managed surface: something else wrote it, with a matcher that matched no Codex file tool and a shim
+ * path anchored on a variable Codex does not set, and no check in this package could see it. A file the
+ * guards depend on and nothing validates is the exact shape of that incident.
  *
- * There were four. `GUARANTEE_ROOT_SURFACE` is gone with L-1 itself: an absolutely-registered shim
- * resolves from any cwd, so there is no launch guarantee left to police and no second .sh file to keep
- * byte-locked. A settings file still carrying the retired H1 entry is not its own surface any more —
- * it is ordinary REGISTRATION drift, which `registrationStaleAt()` already reports and
- * `repairRegistration()` already fixes by removing it.
+ * Each harness's registration surface is its own name, from HarnessRegistration.registrationSurface, so
+ * the deny sends the reader to the file that actually moved.
  */
 export declare const SHIM_SURFACE = ".claude/webpieces/ai-hook.sh";
-export declare const REGISTRATION_SURFACE = ".claude/settings.json hook registration";
+export declare const REGISTRATION_SURFACE: string;
+export declare const CODEX_REGISTRATION_SURFACE: string;
 export declare const ENV_SURFACE = ".claude/settings.json env.CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR";
 /**
- * WHICH of the three managed surfaces disagree with this release — the input to fault S.
+ * WHICH of the managed surfaces disagree with this release — the input to fault S.
  *
- * All three are checked against the SAME root, resolved from the RUNNING MODULE (governingShimRoot),
+ * All of them are checked against the SAME root, resolved from the RUNNING MODULE (governingShimRoot),
  * never from cwd and never from `$CLAUDE_PROJECT_DIR`: the files we compare and the renderers we
  * compare them TO must come from one install, or the check straddles two trees and can never converge.
  */