@webpieces/ai-hook-rules 0.4.623 → 0.4.624

package/README.md

@@ -31,18 +31,11 @@ openclaw plugins enable @webpieces/ai-hook-rules
 # Drop webpieces.config.json into any project you want checked
 ```
 
-## The three hooks (Claude Code)
-
-`wp-install-ai-hooks` wires three `PreToolUse` hooks into the chosen `settings.json`:
-
-- `guarantee-root.sh` — matcher `Bash`. The **L-1** hook, and the only one registered with an
-  **absolute** `$CLAUDE_PROJECT_DIR/` path. The two guard hooks below are registered **relative**, so
-  the harness resolves them against the tool call's own cwd and each git tree is governed by its own
-  installed release rather than the primary clone's forever. That is only safe if the relative path
-  always resolves — a hook that fails to launch exits 127, which the harness treats as a non-blocking
-  error and lets the tool call proceed UNGUARDED — so L-1 refuses any `cd` that would park the shell
-  somewhere the other two cannot launch. It reads no config, runs no binary, and a denied `cd` never
-  executes, so there is nothing to recover from.
+## The two hooks (Claude Code)
+
+`wp-install-ai-hooks` wires two `PreToolUse` hooks into the chosen `settings.json`, **both registered
+with an absolute `$CLAUDE_PROJECT_DIR/` path** so they resolve from any cwd:
+
 - `wp-ai-rules-hook` — matcher `Write|Edit|MultiEdit`. Runs the code-style rules.
 - `wp-ai-guards-hook` — matcher `Write|Edit|MultiEdit|Bash|Read`. Runs the git/PR/branch guards
   (`hookGuards` section): bash git/PR guards on `Bash`, and file guards like
@@ -54,18 +47,29 @@ openclaw plugins enable @webpieces/ai-hook-rules
 For each guard hook the setup command prompts for a target: project `.claude/settings.json`,
 personal `.claude/settings.local.json`, the global `~/.claude/settings.json` (this-repo-only),
 or **none** (= uninstall). Installing and uninstalling are the same operation — pick a
-location, or pick "none" to remove the hook from every target. L-1 follows the guards hook (it judges
-`cd`, which arrives on `Bash`); a global install gets none, because those hooks name the bin path
-directly and have no relative path that could fail to resolve.
-
-### Keeping the four in step
-
-The installed surface is four things — `.claude/webpieces/ai-hook.sh`,
-`.claude/webpieces/guarantee-root.sh`, the `settings.json` entries registering them, and the
-`settings.json` `env` entry `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1` — and they only
-work as a set. The guards binary compares all four against the release it came from and fails closed
-on any mismatch, naming which one moved. **`pnpm exec wp-upgrade-shim`** regenerates all four
-(rewriting an old absolute registration to the relative form rather than adding beside it) and is
+location, or pick "none" to remove the hook from every target.
+
+**There is no third `cd` hook any more.** A `guarantee-root.sh` used to be registered alongside these
+two, denying any `cd` into a project subdirectory, because the two guard hooks were registered
+**relative** — the point being that each git tree would then be governed by its own installed release
+rather than the primary clone's — and a relative hook that fails to resolve exits 127, which the harness
+treats as a non-blocking error that lets the tool call proceed UNGUARDED. Measured 2026-08-10, the
+relative registration never delivered that: a linked worktree has no `node_modules`, so this script's
+upward walk always executed the MAIN tree'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 — governance was always the primary's. Both hooks are absolute now, the launch
+guarantee is structural, `cd` into a subdirectory is simply allowed, and version skew between trees is
+caught where it actually lives: the `trinary-version-skew` L1 row (`core/version-sync.ts`).
+
+### Keeping the three in step
+
+The installed surface is three things — `.claude/webpieces/ai-hook.sh`, the `settings.json` entries
+registering the two hooks, and the `settings.json` `env` entry
+`CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1` — and they only
+work as a set. The guards binary compares all three against the release it came from and fails closed
+on any mismatch, naming which one moved. **`pnpm exec wp-upgrade-shim`** regenerates all three
+(rewriting an old relative registration to the absolute form rather than adding beside it, and removing
+a leftover `guarantee-root.sh` registration) and is
 allowed through while that block is up. Its NAME is older than its job — it has not been shim-only
 since 2026-08-07 — and it is deliberately not renamed, because a rename with no functional change costs
 every consumer and buys nothing.
@@ -75,15 +79,18 @@ every consumer and buys nothing.
 Set to `1`, Claude Code resets the shell's cwd to the project directory after every Bash call. That is
 guard integrity, not ergonomics:
 
-- the guard hooks are registered **relative** (`sh ".claude/webpieces/ai-hook.sh" <bin>`) so each git
-  worktree runs its own release, binary and pin. A relative hook that cannot resolve exits 127, and per
-  the Claude Code hooks reference any non-2 non-zero exit is a NON-BLOCKING error — a **silent unguarded
-  allow**. Pinning the cwd to the project root PREVENTS that drift; the L-1 hook, which refuses a `cd`
-  that would park the shell out of reach, is the cure after the fact;
-- settings `env` is **inherited**, so the main agent and every subagent run with the same cwd, hence the
-  same relative-hook resolution, hence the same guard verdict — instead of a verdict that depends on
-  whatever `cd` happened earlier in the session;
-- it mechanically enforces "never `cd` into a sub-package in Bash", rather than relying on memory.
+- a `cd` that stays INSIDE the workspace otherwise PERSISTS to later calls, so a guard verdict would
+  depend on whatever `cd` happened earlier in the session — including one from an unrelated command
+  several turns ago. Resetting makes every call start from a known directory;
+- settings `env` is **inherited**, so the main agent and every subagent start each Bash call from the
+  same cwd, and therefore get the same verdict for the same command;
+- it keeps `$CLAUDE_PROJECT_DIR` and the shell's cwd in agreement by default, which is what makes the
+  `tree=` / `root=` columns in the audit log mean what a reader assumes they mean.
+
+(This entry once had a load-bearing safety job — the hooks were registered relative, and a relative
+path that cannot resolve exits 127, which the Claude Code hooks reference defines as a NON-BLOCKING
+error, i.e. a **silent unguarded allow**. Both hooks are absolute now, so that hazard is gone and this
+is about verdict stability, not launchability.)
 
 The trade, said out loud: with the flag on, the cwd reset is **silent and unconditional**, where without
 it the reset is conditional and prints a visible notice. A deliberate `cd` no longer persists across

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/ai-hook-rules",
-  "version": "0.4.623",
+  "version": "0.4.624",
   "description": "Pluggable write-time validation framework for AI coding agents (@webpieces/ai-hook-rules). Claude Code PreToolUse + openclaw before_tool_call adapters share one rule engine.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -25,7 +25,7 @@
     "directory": "packages/tooling/ai-hook-rules"
   },
   "dependencies": {
-    "@webpieces/rules-config": "0.4.623"
+    "@webpieces/rules-config": "0.4.624"
   },
   "publishConfig": {
     "access": "public"

package/src/adapters/hook-core.js

@@ -5,7 +5,6 @@ exports.runMain = runMain;
 const tslib_1 = require("tslib");
 const path = tslib_1.__importStar(require("path"));
 const runner_1 = require("../core/runner");
-const coordinator_worktree_1 = require("../core/coordinator-worktree");
 const rejection_log_1 = require("../core/rejection-log");
 const decision_log_1 = require("../core/decision-log");
 const main_sync_refresh_1 = require("../core/main-sync-refresh");
@@ -76,12 +75,6 @@ function normalizeToolInput(toolKind, toolInput) {
     }
     return null;
 }
-// The caller behind this payload. Both fields are sent only inside a subagent, so BOTH absent (or
-// empty) is the coordinator — the one distinction CoordinatorWorktreeGuard turns on.
-// webpieces-disable no-function-outside-class -- sibling of handleBash()/handleFileTool() in this module; the adapter is module-scope functions by design
-function agentIdentityOf(payload) {
-    return new coordinator_worktree_1.AgentIdentity(payload.agent_id ?? '', payload.agent_type ?? '');
-}
 // The rule name for a block's audit line: the FIRST rule the report cites, or `fallback` when the
 // report opens with no `[rule]` header (a hand-written guard message). Comma-joined when a report
 // cites several, so `rule=` never silently drops one.
@@ -95,8 +88,7 @@ function handleBash(payload, cwd, mode) {
     if (!command || command.trim() === '') {
         (0, claude_code_response_1.emitAllow)();
     }
-    const agent = agentIdentityOf(payload);
-    const result = (0, runner_1.runBash)(command, cwd, mode, agent);
+    const result = (0, runner_1.runBash)(command, cwd, mode);
     if (!result) {
         (0, claude_code_response_1.emitAllow)();
     }
@@ -204,12 +196,12 @@ function enforceCommittedShim(payload, cwd, mode) {
     const shimRoot = (0, shim_1.governingShimRoot)();
     if (mode === 'rules')
         return;
-    // WHICH of the four managed things moved — the shim, the L-1 hook, the settings.json
-    // registration, or its managed env entry (the Bash-cwd pin that keeps the RELATIVE hooks
-    // resolvable; see hook-registration.ts). Nothing validated the registration before, so a file on the
-    // old
-    // two-absolute-hook form silently reverted a repo to per-PRIMARY governance and disabled L-1
-    // entirely: the one component whose whole job is failing closed, switched off with no signal.
+    // WHICH of the three managed things moved — ai-hook.sh, the settings.json registration, or its
+    // managed env entry (the Bash-cwd pin that keeps a guard's verdict independent of where an earlier
+    // `cd` left the shell; see managed-env.ts). Nothing validated the registration before it joined this
+    // fault, so a settings file left on a superseded form silently changed WHO GOVERNS, with no signal
+    // anywhere — which is the whole reason the registration is a drift surface and not just an install
+    // step.
     const drifted = (0, hook_registration_1.managedSurfaceDrift)(shimRoot);
     if (drifted.length === 0)
         return;

package/src/adapters/hook-core.js.map

@@ -1 +1 @@
-{"version":3,"file":"hook-core.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/adapters/hook-core.ts"],"names":[],"mappings":"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","sourcesContent":["import * as path from 'path';\n\nimport { run, runBash, runRead } from '../core/runner';\nimport { AgentIdentity } from '../core/coordinator-worktree';\nimport { logRejection, extractRuleNames } from '../core/rejection-log';\nimport { logGuardDecision, GuardDecision, branchForLog, invocationLog, MATRIX_L0, MATRIX_L2 } from '../core/decision-log';\nimport { triggerMainSyncRefresh } from '../core/main-sync-refresh';\nimport { CONFIG_FILENAME } from '../core/load-config';\nimport { RepoRootFinder } from '@webpieces/rules-config';\nimport { NormalizedToolInput, NormalizedEdit, ToolKind, InformAiError, RuleFailError, HookMode, BlockedResult } from '../core/types';\nimport { toError } from '../core/to-error';\nimport { emitDeny, emitAllow } from './claude-code-response';\nimport { governingShimRoot, isAllowed, installedShimRulesVersion } from '../bin/shim';\nimport { shimStaleDenyReason } from '../bin/shim-deny-reason';\nimport { managedSurfaceDrift } from '../bin/hook-registration';\nimport { writeGuardMatrixDoc, guardMatrixPointer } from '../core/l0-matrix';\nimport { logStream, StreamIdentity } from '../core/log-stream';\nimport { L0_FAULT_SHIM_STALE, L0_FAULT_NONE } from '../core/l0-fault-codes';\n\n// Which category of rules this hook invocation runs. The hook is split into two independently\n// installable PreToolUse hooks; each runs ONE category (the runner filters by it), and both can\n// receive file AND bash payloads:\n//  - 'rules'  → code-style rules (file/edit scope). Bash payloads pass through (no code rules apply).\n//  - 'guards' → hookGuards section: bash git/PR guards on Bash AND file guards (feature-branch-guard)\n//               on Write/Edit, PLUS a log-and-allow audit of Read. Matcher is Write|Edit|MultiEdit|Bash|Read.\n//  - 'all'    → both categories, used by the openclaw plugin adapter (a single before_tool_call hook).\nexport type { HookMode };\n\nconst HANDLED_FILE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit']);\n\n// Read-only tools carry NO guard or code rule, but the guards hook owns the per-invocation audit log\n// (the `calls/` stream). When the guards matcher includes these (see setup.ts GUARDS_HOOK), a\n// log-and-allow fast path records every file the AI opens — so a human can later inspect whether it\n// read a project's design.json BEFORE editing the project. Never blocked. Scoped to Read for now;\n// widen (Grep/Glob/NotebookRead) later if desired.\nconst READ_ONLY_TOOLS = new Set(['Read']);\n\ninterface ClaudeCodePayload {\n    tool_name: string;\n    tool_input: ClaudeCodeToolInput;\n    // Claude Code sends the session's current working directory (follows a persisted `cd`). Used to\n    // scope guards to the git repo the AI is actually in — see runner git-repo-boundary governance.\n    cwd?: string;\n    // Present ONLY when the hook fires inside a SUBAGENT. Absent = the coordinator (the main agent\n    // loop) — there is no positive coordinator field to read. See AgentIdentity.\n    session_id?: string;\n    agent_id?: string;\n    agent_type?: string;\n}\n\ninterface ClaudeCodeToolInput {\n    file_path?: string;\n    content?: string;\n    old_string?: string;\n    new_string?: string;\n    edits?: ClaudeCodeEditEntry[];\n    command?: string;\n}\n\ninterface ClaudeCodeEditEntry {\n    old_string?: string;\n    new_string?: string;\n}\n\nfunction readStdin(): Promise<string> {\n    return new Promise((resolve: (value: string) => void) => {\n        let data = '';\n        process.stdin.setEncoding('utf8');\n        process.stdin.on('data', (chunk: string) => { data += chunk; });\n        process.stdin.on('end', () => resolve(data));\n        process.stdin.on('error', () => resolve(''));\n        if (process.stdin.isTTY) resolve('');\n    });\n}\n\nfunction safeParse(raw: string): ClaudeCodePayload | null {\n    if (!raw || raw.trim() === '') return null;\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        return JSON.parse(raw) as ClaudeCodePayload;\n    } catch (err: unknown) {\n        const error = toError(err);\n        throw new InformAiError(`Malformed hook input from Claude Code stdin: ${error.message}`, { cause: error });\n    }\n}\n\nfunction normalizeToolKind(toolName: string): ToolKind | null {\n    if (HANDLED_FILE_TOOLS.has(toolName)) return toolName as ToolKind;\n    return null;\n}\n\nfunction normalizeToolInput(toolKind: ToolKind, toolInput: ClaudeCodeToolInput): NormalizedToolInput | null {\n    const filePath = toolInput.file_path;\n    if (!filePath) return null;\n\n    if (toolKind === 'Write') {\n        return new NormalizedToolInput(filePath, [\n            new NormalizedEdit('', toolInput.content || ''),\n        ]);\n    }\n    if (toolKind === 'Edit') {\n        return new NormalizedToolInput(filePath, [\n            new NormalizedEdit(toolInput.old_string || '', toolInput.new_string || ''),\n        ]);\n    }\n    if (toolKind === 'MultiEdit') {\n        const raw = Array.isArray(toolInput.edits) ? toolInput.edits : [];\n        const edits = raw.map((e: ClaudeCodeEditEntry) => new NormalizedEdit(e.old_string || '', e.new_string || ''));\n        return new NormalizedToolInput(filePath, edits);\n    }\n    return null;\n}\n\n// The caller behind this payload. Both fields are sent only inside a subagent, so BOTH absent (or\n// empty) is the coordinator — the one distinction CoordinatorWorktreeGuard turns on.\n// webpieces-disable no-function-outside-class -- sibling of handleBash()/handleFileTool() in this module; the adapter is module-scope functions by design\nfunction agentIdentityOf(payload: ClaudeCodePayload): AgentIdentity {\n    return new AgentIdentity(payload.agent_id ?? '', payload.agent_type ?? '');\n}\n\n// The rule name for a block's audit line: the FIRST rule the report cites, or `fallback` when the\n// report opens with no `[rule]` header (a hand-written guard message). Comma-joined when a report\n// cites several, so `rule=` never silently drops one.\n// webpieces-disable no-function-outside-class -- sibling of handleBash()/handleFileTool() in this module; the adapter is module-scope functions by design\nfunction blockingRule(report: string, fallback: string): string {\n    const names = extractRuleNames(report);\n    return names.length > 0 ? names.join(',') : fallback;\n}\n\nfunction handleBash(payload: ClaudeCodePayload, cwd: string, mode: HookMode): void {\n    const command = payload.tool_input.command;\n    if (!command || command.trim() === '') { emitAllow(); }\n    const agent = agentIdentityOf(payload);\n    const result = runBash(command, cwd, mode, agent);\n    if (!result) { emitAllow(); }\n    // NO DECISION LINE HERE. This used to write a generic `bash-guard` line because a Bash deny once\n    // had no audit trail at all — but every layer now records its own: L1 into `L1-location/` with its\n    // row, L2's guards into `L2-decisions/` with their rule and cache, and emitDeny below stamps the\n    // call-level outcome onto `calls/`. So this was the THIRD line for one block, and the worst of the\n    // three: it re-resolved the root from `cwd` via RepoRootFinder, which is not necessarily the tree\n    // the guard actually judged, so a `cd`-relocated command scattered one block across two different\n    // `.webpieces` directories.\n    //\n    // Bash deny → pass 'Bash' so denyJson adds the ANSI-red systemMessage (the only field a Bash deny\n    // shows the human; permissionDecisionReason is invisible on Bash). See claude-code-response.ts.\n    emitDeny(result.report, 'Bash', blockingRule(result.report, 'bash-guard'), result.fault);\n}\n\n/**\n * The read-scoped guard pass. Returns normally to ALLOW; only calls emitDeny when the guard fires.\n *\n * Wrapped in its own catch that swallows into an allow. Every other path in this hook fails CLOSED,\n * and that is right for edits and shell commands — but a crash here would block the agent from\n * READING, which includes reading webpieces.config.json to turn the offending guard off. So this one\n * path deliberately inverts the policy: a broken read-guard degrades to a no-op, never to a wedge.\n */\n// webpieces-disable no-function-outside-class -- sibling of handleBash()/handleFileTool() in this module; the adapter is module-scope functions by design\nfunction handleRead(filePath: string, cwd: string, mode: HookMode): void {\n    if (filePath === '') return;\n    let result: BlockedResult | null = null;\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        result = runRead(filePath, cwd, mode);\n    } catch (err: unknown) {\n        const error = toError(err);\n        void error;\n        return; // fail OPEN — see the doc comment\n    }\n    if (!result) return;\n    logRejection('Read', new NormalizedToolInput(filePath, []), result, cwd);\n    emitDeny(result.report, 'Read', blockingRule(result.report, 'read-guard'), result.fault);\n}\n\nfunction handleFileTool(payload: ClaudeCodePayload, cwd: string, mode: HookMode): void {\n    const toolKind = normalizeToolKind(payload.tool_name);\n    if (!toolKind) { emitAllow(); }\n\n    const input = normalizeToolInput(toolKind, payload.tool_input);\n    if (!input) { emitAllow(); }\n\n    // Always allow edits to webpieces.config.json — it's the fix target when the config is broken.\n    // This exits BEFORE run(), so feature-branch-guard never sees a config edit; record that so the\n    // audit trail explains why a config edit on a bad branch was not blocked (see decision-log.ts).\n    if (path.basename(input.filePath) === CONFIG_FILENAME) {\n        if (mode !== 'rules') {\n            // `.webpieces/` (the decision log + sync cache these two calls write) lives at the repo\n            // root, not the AI's cwd — resolve it so a config edit from a subdir doesn't create a\n            // stray `<subdir>/.webpieces` tree.\n            const root = new RepoRootFinder().resolveRepoRoot(cwd);\n            logGuardDecision(\n                root,\n                new GuardDecision('feature-branch-guard', toolKind, input.filePath, branchForLog(root), 'ALLOW_EXEMPT', 'config-bypass (feature-branch-guard skipped)', '-', L0_FAULT_NONE, MATRIX_L2),\n            );\n            // The guard's own refresh trigger lives inside its check(), which we skip here — so warm\n            // the cache directly, otherwise a session that only edits webpieces.config.json never\n            // refreshes the sync status. Fire-and-forget; never blocks the edit.\n            triggerMainSyncRefresh(root);\n        }\n        emitAllow();\n    }\n\n    const result = run(toolKind, input, cwd, mode);\n    if (!result) { emitAllow(); }\n\n    logRejection(toolKind, input, result, cwd);\n    // File-tool deny → pass the Write/Edit/MultiEdit kind so denyJson omits systemMessage (the reason\n    // already renders red natively for these tools). See claude-code-response.ts.\n    emitDeny(result.report, toolKind, blockingRule(result.report, 'file-guard'), result.fault);\n}\n\n// What a stale committed shim lets through — now a thin adapter over the ONE L0 allowlist (isAllowed in\n// ../bin/shim), not a list of its own. A stale shim must NEVER trap the actions needed to recover: the\n// original \"block everything but the cures\" version also shadowed the always-allowed\n// webpieces.config.json edit (handleFileTool) and blocked reads, so a repo that ALSO needed its config\n// fixed would deadlock — blocked from editing the one file whose edit is normally always allowed, and\n// blocked from reading it to know how.\n//\n// It used to carry its OWN narrower list (isShimCureCommand: the three shim cures only), and that\n// narrowness was a defect, not a safety property: `pnpm install` and `git pull` — the two commands that\n// resolve the version disagreement underneath a stale shim — were denied. Consulting the shared\n// allowlist fixes that by construction.\n//\n// What is NOT a defect, and must not be \"fixed\": those cures rewrite the committed shim from the\n// INSTALLED binary's renderShim(), overwriting whatever was there. That is the invariant, not\n// collateral damage. The shim (D/X/K, in POSIX sh, pre-binary) and this binary (S/C/Y, in JS) are two\n// halves of ONE L0 and they exchange assumptions — the shim parses file_path and carries ALLOW-READ /\n// ALLOW-CONFIG entries this binary relies on. Pair a binary with a shim rendered by a DIFFERENT\n// release and L0 acquires holes that nothing reports. So the rule is absolute: the committed shim\n// equals renderShim() of the binary in node_modules, and a cure that forces that is the cure working.\n// See healShim's header, which states the same invariant from the other side.\n//\n// Corollary for anyone regenerating the shim in a webpieces PR: commit `templates/ai-hook.sh` (source,\n// locked to renderShim() by unit test) and leave `.claude/webpieces/ai-hook.sh` (generated artifact)\n// alone. In THIS repo the local source runs ahead of the pinned node_modules, so committing a shim\n// rendered from local source produces a commit whose shim and whose @webpieces pin come from different\n// releases — precisely the mismatch above. The artifact heals on the next upgrade; that is its job.\n//\n//   - 'allow-cure' → a Bash cure on the allowlist: emitAllow directly, bypassing the git guards.\n//   - 'pass'       → a recovery action the normal flow already permits, so fall THROUGH and let it: ANY\n//                    Read (you must read to know how to fix — see handleRead, which itself fails open),\n//                    or an edit to webpieces.config.json (the always-allowed recovery target).\n//   - 'deny'       → all OTHER work: blocked until the committed shim matches renderShim() again.\nexport type ShimStaleDecision = 'allow-cure' | 'pass' | 'deny';\n// webpieces-disable no-function-outside-class -- pure decision helper beside the adapter's other module-scope functions; exported for direct unit testing.\nexport function shimStaleRecoveryDecision(toolName: string, command: string, filePath: string): ShimStaleDecision {\n    const allowed = isAllowed(toolName, command, filePath);\n    if (allowed === 'pass') return 'pass';\n    if (allowed === 'allow') return 'allow-cure';\n    return 'deny';\n}\n\n// MANAGED-HOOK-SURFACE self-guard, moved here from the rendered shim (2026-07-24) and widened from one\n// file to three (2026-08-07). The committed\n// .claude/webpieces/ai-hook.sh is webpieces-MANAGED and generated from renderShim(); if it no longer\n// matches, it was reverted / hand-edited / predates this binary, so its OWN fail-closed logic can't be\n// trusted. We are the CURRENT binary from node_modules — the trustworthy party — so WE decide here\n// instead of the (possibly stale) shim. It used to `cmp` itself inside the shim: a double-edged trap,\n// since the check lived in the very file it guarded and a fix could only ship by regenerating that\n// file. Now we fail closed on all real WORK while always leaving the recovery path open (see\n// shimStaleRecoveryDecision): the whole L0 allowlist, any Read, and editing webpieces.config.json. We deny +\n// tell the AI; we do NOT silently rewrite the file under it. 'rules' hook skips it (guards owns the\n// shim). Returns normally (pass / nothing to do) or exits via emitAllow/emitDeny.\n// webpieces-disable no-function-outside-class -- sibling of handleBash()/handleFileTool() in this module; the adapter is module-scope functions by design\nfunction enforceCommittedShim(payload: ClaudeCodePayload, cwd: string, mode: HookMode): void {\n    // ONE root for the whole decision, resolved from the RUNNING MODULE (governingShimRoot), never from\n    // `cwd`: the shim file we compare and the renderShim() we compare it TO must come from the same\n    // install, or the check straddles two trees and can never converge (see governingShimRoot's header).\n    // `cwd` still selects where the L0 matrix doc is dropped — that is a \"where does the AI read\" question,\n    // not part of the judgement.\n    const shimRoot = governingShimRoot();\n    if (mode === 'rules') return;\n    // WHICH of the four managed things moved — the shim, the L-1 hook, the settings.json\n    // registration, or its managed env entry (the Bash-cwd pin that keeps the RELATIVE hooks\n    // resolvable; see hook-registration.ts). Nothing validated the registration before, so a file on the\n    // old\n    // two-absolute-hook form silently reverted a repo to per-PRIMARY governance and disabled L-1\n    // entirely: the one component whose whole job is failing closed, switched off with no signal.\n    const drifted = managedSurfaceDrift(shimRoot);\n    if (drifted.length === 0) return;\n    const decision = shimStaleRecoveryDecision(payload.tool_name, payload.tool_input.command ?? '', payload.tool_input.file_path ?? '');\n    if (decision === 'pass') return;\n    if (decision === 'allow-cure') emitAllow();\n    // Drop the L0 matrix doc where the AI can read it and point the deny at it — a Read is entry 1 of\n    // the same allowlist, so the pointer is always followable. Best-effort: no doc → no pointer.\n    const root = new RepoRootFinder().resolveRepoRoot(cwd);\n    const docPath = writeGuardMatrixDoc(root);\n    // WRITE THE AUDIT LINE HERE. This block happens BEFORE invocationLog.begin() — it has to, since a\n    // stale shim invalidates everything downstream — so emitDeny's flush finds nothing pending and an\n    // `S` storm left NO trace at all: the one fault most likely to block twenty consecutive tool calls\n    // was the one fault the trail could not show. A decision line is the fix that costs no reordering.\n    const target = payload.tool_input.command ?? payload.tool_input.file_path ?? '';\n    logGuardDecision(\n        root,\n        new GuardDecision('committed-shim-stale', payload.tool_name, target, branchForLog(root), 'BLOCK_AI_CURE', 'L0 fault S (committed shim != renderShim)', '-', L0_FAULT_SHIM_STALE, MATRIX_L0),\n    );\n    // L0 fault S in GUARD_MATRIX.md's codebook — named as the blocking rule so the invocation line\n    // says WHAT stopped the call, not merely that something did, and stamped as `fault=S` so the same\n    // grep finds it here as in the sh half's `L0-shim/` stream.\n    // A subagent is discriminated by `agent_id`, which Claude Code populates on stdin only off the main\n    // loop (main falls back to the session id, so the field is absent). Its cure differs: the hooks\n    // blocking it resolve through CLAUDE_PROJECT_DIR, which names the MAIN tree.\n    const inSubagent = (payload.agent_id ?? '') !== '';\n    emitDeny(shimStaleDenyReason(installedShimRulesVersion(), shimRoot ?? '', drifted, inSubagent) + guardMatrixPointer(docPath), payload.tool_name, 'committed-shim-stale', L0_FAULT_SHIM_STALE);\n}\n\n/**\n * Shared entry point for all three Claude Code PreToolUse adapters. `mode` selects which tool kinds\n * to validate; payloads outside the mode's scope pass through (emitAllow). Blocks by emitting a\n * PreToolUse `permissionDecision:\"deny\"` JSON on stdout (exit 0) — see claude-code-response.ts. Fails\n * CLOSED on any unexpected crash (emits a deny) so a broken hook never silently lets an edit through,\n * and the reason now surfaces in the Claude Code UI instead of being hidden on a stderr+exit-2 block.\n */\nexport async function runMain(mode: HookMode): Promise<void> {\n    // Captured from the payload as soon as it parses so the fail-closed catch below can tell denyJson\n    // which tool it is denying — a crash on a Bash call still gets the visible red systemMessage, a\n    // crash on a file tool does not. Empty (before parse / malformed input) → treated as non-Bash.\n    let toolName = '';\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const raw = await readStdin();\n        const payload = safeParse(raw);\n        if (!payload) { emitAllow(); }\n        toolName = payload.tool_name;\n\n        // BEFORE enforceCommittedShim(), which can itself write a BLOCK line. See LogStream for why\n        // all three of session/agent/hook are needed to keep concurrent writers off one file.\n        logStream.identify(new StreamIdentity(payload.session_id ?? '', payload.agent_id ?? '', mode));\n\n        // Prefer the payload cwd (the AI's actual working dir, follows a persisted `cd`) over\n        // process.cwd(); they match today, but the payload is the authoritative signal and stays\n        // correct if the hook is ever invoked from a fixed dir (e.g. via $CLAUDE_PROJECT_DIR).\n        const cwd = payload.cwd ?? process.cwd();\n\n        // Committed-shim self-guard: blocks real work while the committed shim is stale, but keeps the\n        // recovery path open (cures, reads, config edit). See enforceCommittedShim / shimStaleRecoveryDecision.\n        enforceCommittedShim(payload, cwd, mode);\n\n        // Read-only tools (Read): audit-log, warm the main-sync cache, then run the ONE read-scoped\n        // guard (read-stale-guard) and allow. Runs BEFORE the general rule engine — no code-style rule\n        // ever sees a Read, and the only way this path can deny is a stale `main`.\n        // The audit trail still records every file the AI opened (see setup.ts).\n        if (READ_ONLY_TOOLS.has(payload.tool_name)) {\n            const readPath = payload.tool_input.file_path ?? '';\n            if (mode !== 'rules') {\n                invocationLog.begin(cwd, payload.tool_name, readPath);\n                // Reads vastly outnumber edits, so refreshing here is what actually keeps the shared\n                // main-sync cache warm for feature-branch-guard. Detached; never slows the read.\n                triggerMainSyncRefresh(cwd);\n            }\n            handleRead(readPath, cwd, mode);\n            emitAllow();\n        }\n\n        // Per-invocation guard log (the `calls/` stream): tool + command/file + live branch +\n        // main-sync-status snapshot, on EVERY guards call, for later cleanup automation. Best-effort;\n        // never blocks the call. (The committed shim is no longer silently healed here — a mismatch is\n        // reported by the self-guard above, not rewritten out from under the AI.)\n        if (mode !== 'rules') {\n            const target = payload.tool_name === 'Bash' ? (payload.tool_input.command ?? '') : (payload.tool_input.file_path ?? '');\n            invocationLog.begin(cwd, payload.tool_name, target);\n        }\n\n        if (payload.tool_name === 'Bash') {\n            // No code-style rule is bash-scoped, so the rules hook ignores Bash.\n            if (mode === 'rules') { emitAllow(); }\n            handleBash(payload, cwd, mode);\n            return;\n        }\n\n        // File payloads run in 'rules' (code-style), 'guards' (file-scoped guards like\n        // feature-branch-guard), and 'all'. The runner filters to the right category.\n        handleFileTool(payload, cwd, mode);\n    } catch (err: unknown) {\n        const error = toError(err);\n        denyForCrash(error, toolName);\n    }\n}\n\n/**\n * The fail-closed boundary for anything that escaped the hook body. An escaped RuleFailError (a rule\n * that threw past the runner's per-rule catch) or an InformAiError (bad config/stdin) both carry an\n * AI-readable message; anything else is an unexpected bug. All three DENY and surface their reason,\n * because a hook that crashed established nothing and must never be read as an allow.\n */\n// webpieces-disable no-function-outside-class -- sibling of the module-scope hook entry points in this adapter; a lone class for one terminal boundary would break the file's shape\nfunction denyForCrash(error: Error, toolName: string): never {\n    if (error instanceof RuleFailError) {\n        emitDeny(error.aiMessage, toolName, 'rule-crash');\n    }\n    if (error instanceof InformAiError) {\n        emitDeny(error.message, toolName, 'bad-config-or-stdin');\n    }\n    emitDeny(`[ai-hooks] hook crashed unexpectedly — failing closed: ${error.message}`, toolName, 'hook-crash');\n}\n"]}
+{"version":3,"file":"hook-core.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/adapters/hook-core.ts"],"names":[],"mappings":"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","sourcesContent":["import * as path from 'path';\n\nimport { run, runBash, runRead } from '../core/runner';\nimport { logRejection, extractRuleNames } from '../core/rejection-log';\nimport { logGuardDecision, GuardDecision, branchForLog, invocationLog, MATRIX_L0, MATRIX_L2 } from '../core/decision-log';\nimport { triggerMainSyncRefresh } from '../core/main-sync-refresh';\nimport { CONFIG_FILENAME } from '../core/load-config';\nimport { RepoRootFinder } from '@webpieces/rules-config';\nimport { NormalizedToolInput, NormalizedEdit, ToolKind, InformAiError, RuleFailError, HookMode, BlockedResult } from '../core/types';\nimport { toError } from '../core/to-error';\nimport { emitDeny, emitAllow } from './claude-code-response';\nimport { governingShimRoot, isAllowed, installedShimRulesVersion } from '../bin/shim';\nimport { shimStaleDenyReason } from '../bin/shim-deny-reason';\nimport { managedSurfaceDrift } from '../bin/hook-registration';\nimport { writeGuardMatrixDoc, guardMatrixPointer } from '../core/l0-matrix';\nimport { logStream, StreamIdentity } from '../core/log-stream';\nimport { L0_FAULT_SHIM_STALE, L0_FAULT_NONE } from '../core/l0-fault-codes';\n\n// Which category of rules this hook invocation runs. The hook is split into two independently\n// installable PreToolUse hooks; each runs ONE category (the runner filters by it), and both can\n// receive file AND bash payloads:\n//  - 'rules'  → code-style rules (file/edit scope). Bash payloads pass through (no code rules apply).\n//  - 'guards' → hookGuards section: bash git/PR guards on Bash AND file guards (feature-branch-guard)\n//               on Write/Edit, PLUS a log-and-allow audit of Read. Matcher is Write|Edit|MultiEdit|Bash|Read.\n//  - 'all'    → both categories, used by the openclaw plugin adapter (a single before_tool_call hook).\nexport type { HookMode };\n\nconst HANDLED_FILE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit']);\n\n// Read-only tools carry NO guard or code rule, but the guards hook owns the per-invocation audit log\n// (the `calls/` stream). When the guards matcher includes these (see setup.ts GUARDS_HOOK), a\n// log-and-allow fast path records every file the AI opens — so a human can later inspect whether it\n// read a project's design.json BEFORE editing the project. Never blocked. Scoped to Read for now;\n// widen (Grep/Glob/NotebookRead) later if desired.\nconst READ_ONLY_TOOLS = new Set(['Read']);\n\ninterface ClaudeCodePayload {\n    tool_name: string;\n    tool_input: ClaudeCodeToolInput;\n    // Claude Code sends the session's current working directory (follows a persisted `cd`). Used to\n    // scope guards to the git repo the AI is actually in — see runner git-repo-boundary governance.\n    cwd?: string;\n    // Present ONLY when the hook fires inside a SUBAGENT; absent = the coordinator. Used to NAME the log\n    // writer file and nothing else — never to decide which tree a call acts on, which is measured from\n    // the path (see core/version-sync.ts). A worktree-isolated agent was measured resuming on the primary\n    // clone after its tree was reaped, so identity cannot stand in for location.\n    session_id?: string;\n    agent_id?: string;\n    agent_type?: string;\n}\n\ninterface ClaudeCodeToolInput {\n    file_path?: string;\n    content?: string;\n    old_string?: string;\n    new_string?: string;\n    edits?: ClaudeCodeEditEntry[];\n    command?: string;\n}\n\ninterface ClaudeCodeEditEntry {\n    old_string?: string;\n    new_string?: string;\n}\n\nfunction readStdin(): Promise<string> {\n    return new Promise((resolve: (value: string) => void) => {\n        let data = '';\n        process.stdin.setEncoding('utf8');\n        process.stdin.on('data', (chunk: string) => { data += chunk; });\n        process.stdin.on('end', () => resolve(data));\n        process.stdin.on('error', () => resolve(''));\n        if (process.stdin.isTTY) resolve('');\n    });\n}\n\nfunction safeParse(raw: string): ClaudeCodePayload | null {\n    if (!raw || raw.trim() === '') return null;\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        return JSON.parse(raw) as ClaudeCodePayload;\n    } catch (err: unknown) {\n        const error = toError(err);\n        throw new InformAiError(`Malformed hook input from Claude Code stdin: ${error.message}`, { cause: error });\n    }\n}\n\nfunction normalizeToolKind(toolName: string): ToolKind | null {\n    if (HANDLED_FILE_TOOLS.has(toolName)) return toolName as ToolKind;\n    return null;\n}\n\nfunction normalizeToolInput(toolKind: ToolKind, toolInput: ClaudeCodeToolInput): NormalizedToolInput | null {\n    const filePath = toolInput.file_path;\n    if (!filePath) return null;\n\n    if (toolKind === 'Write') {\n        return new NormalizedToolInput(filePath, [\n            new NormalizedEdit('', toolInput.content || ''),\n        ]);\n    }\n    if (toolKind === 'Edit') {\n        return new NormalizedToolInput(filePath, [\n            new NormalizedEdit(toolInput.old_string || '', toolInput.new_string || ''),\n        ]);\n    }\n    if (toolKind === 'MultiEdit') {\n        const raw = Array.isArray(toolInput.edits) ? toolInput.edits : [];\n        const edits = raw.map((e: ClaudeCodeEditEntry) => new NormalizedEdit(e.old_string || '', e.new_string || ''));\n        return new NormalizedToolInput(filePath, edits);\n    }\n    return null;\n}\n\n// The rule name for a block's audit line: the FIRST rule the report cites, or `fallback` when the\n// report opens with no `[rule]` header (a hand-written guard message). Comma-joined when a report\n// cites several, so `rule=` never silently drops one.\n// webpieces-disable no-function-outside-class -- sibling of handleBash()/handleFileTool() in this module; the adapter is module-scope functions by design\nfunction blockingRule(report: string, fallback: string): string {\n    const names = extractRuleNames(report);\n    return names.length > 0 ? names.join(',') : fallback;\n}\n\nfunction handleBash(payload: ClaudeCodePayload, cwd: string, mode: HookMode): void {\n    const command = payload.tool_input.command;\n    if (!command || command.trim() === '') { emitAllow(); }\n    const result = runBash(command, cwd, mode);\n    if (!result) { emitAllow(); }\n    // NO DECISION LINE HERE. This used to write a generic `bash-guard` line because a Bash deny once\n    // had no audit trail at all — but every layer now records its own: L1 into `L1-location/` with its\n    // row, L2's guards into `L2-decisions/` with their rule and cache, and emitDeny below stamps the\n    // call-level outcome onto `calls/`. So this was the THIRD line for one block, and the worst of the\n    // three: it re-resolved the root from `cwd` via RepoRootFinder, which is not necessarily the tree\n    // the guard actually judged, so a `cd`-relocated command scattered one block across two different\n    // `.webpieces` directories.\n    //\n    // Bash deny → pass 'Bash' so denyJson adds the ANSI-red systemMessage (the only field a Bash deny\n    // shows the human; permissionDecisionReason is invisible on Bash). See claude-code-response.ts.\n    emitDeny(result.report, 'Bash', blockingRule(result.report, 'bash-guard'), result.fault);\n}\n\n/**\n * The read-scoped guard pass. Returns normally to ALLOW; only calls emitDeny when the guard fires.\n *\n * Wrapped in its own catch that swallows into an allow. Every other path in this hook fails CLOSED,\n * and that is right for edits and shell commands — but a crash here would block the agent from\n * READING, which includes reading webpieces.config.json to turn the offending guard off. So this one\n * path deliberately inverts the policy: a broken read-guard degrades to a no-op, never to a wedge.\n */\n// webpieces-disable no-function-outside-class -- sibling of handleBash()/handleFileTool() in this module; the adapter is module-scope functions by design\nfunction handleRead(filePath: string, cwd: string, mode: HookMode): void {\n    if (filePath === '') return;\n    let result: BlockedResult | null = null;\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        result = runRead(filePath, cwd, mode);\n    } catch (err: unknown) {\n        const error = toError(err);\n        void error;\n        return; // fail OPEN — see the doc comment\n    }\n    if (!result) return;\n    logRejection('Read', new NormalizedToolInput(filePath, []), result, cwd);\n    emitDeny(result.report, 'Read', blockingRule(result.report, 'read-guard'), result.fault);\n}\n\nfunction handleFileTool(payload: ClaudeCodePayload, cwd: string, mode: HookMode): void {\n    const toolKind = normalizeToolKind(payload.tool_name);\n    if (!toolKind) { emitAllow(); }\n\n    const input = normalizeToolInput(toolKind, payload.tool_input);\n    if (!input) { emitAllow(); }\n\n    // Always allow edits to webpieces.config.json — it's the fix target when the config is broken.\n    // This exits BEFORE run(), so feature-branch-guard never sees a config edit; record that so the\n    // audit trail explains why a config edit on a bad branch was not blocked (see decision-log.ts).\n    if (path.basename(input.filePath) === CONFIG_FILENAME) {\n        if (mode !== 'rules') {\n            // `.webpieces/` (the decision log + sync cache these two calls write) lives at the repo\n            // root, not the AI's cwd — resolve it so a config edit from a subdir doesn't create a\n            // stray `<subdir>/.webpieces` tree.\n            const root = new RepoRootFinder().resolveRepoRoot(cwd);\n            logGuardDecision(\n                root,\n                new GuardDecision('feature-branch-guard', toolKind, input.filePath, branchForLog(root), 'ALLOW_EXEMPT', 'config-bypass (feature-branch-guard skipped)', '-', L0_FAULT_NONE, MATRIX_L2),\n            );\n            // The guard's own refresh trigger lives inside its check(), which we skip here — so warm\n            // the cache directly, otherwise a session that only edits webpieces.config.json never\n            // refreshes the sync status. Fire-and-forget; never blocks the edit.\n            triggerMainSyncRefresh(root);\n        }\n        emitAllow();\n    }\n\n    const result = run(toolKind, input, cwd, mode);\n    if (!result) { emitAllow(); }\n\n    logRejection(toolKind, input, result, cwd);\n    // File-tool deny → pass the Write/Edit/MultiEdit kind so denyJson omits systemMessage (the reason\n    // already renders red natively for these tools). See claude-code-response.ts.\n    emitDeny(result.report, toolKind, blockingRule(result.report, 'file-guard'), result.fault);\n}\n\n// What a stale committed shim lets through — now a thin adapter over the ONE L0 allowlist (isAllowed in\n// ../bin/shim), not a list of its own. A stale shim must NEVER trap the actions needed to recover: the\n// original \"block everything but the cures\" version also shadowed the always-allowed\n// webpieces.config.json edit (handleFileTool) and blocked reads, so a repo that ALSO needed its config\n// fixed would deadlock — blocked from editing the one file whose edit is normally always allowed, and\n// blocked from reading it to know how.\n//\n// It used to carry its OWN narrower list (isShimCureCommand: the three shim cures only), and that\n// narrowness was a defect, not a safety property: `pnpm install` and `git pull` — the two commands that\n// resolve the version disagreement underneath a stale shim — were denied. Consulting the shared\n// allowlist fixes that by construction.\n//\n// What is NOT a defect, and must not be \"fixed\": those cures rewrite the committed shim from the\n// INSTALLED binary's renderShim(), overwriting whatever was there. That is the invariant, not\n// collateral damage. The shim (D/X/K, in POSIX sh, pre-binary) and this binary (S/C/Y, in JS) are two\n// halves of ONE L0 and they exchange assumptions — the shim parses file_path and carries ALLOW-READ /\n// ALLOW-CONFIG entries this binary relies on. Pair a binary with a shim rendered by a DIFFERENT\n// release and L0 acquires holes that nothing reports. So the rule is absolute: the committed shim\n// equals renderShim() of the binary in node_modules, and a cure that forces that is the cure working.\n// See healShim's header, which states the same invariant from the other side.\n//\n// Corollary for anyone regenerating the shim in a webpieces PR: commit `templates/ai-hook.sh` (source,\n// locked to renderShim() by unit test) and leave `.claude/webpieces/ai-hook.sh` (generated artifact)\n// alone. In THIS repo the local source runs ahead of the pinned node_modules, so committing a shim\n// rendered from local source produces a commit whose shim and whose @webpieces pin come from different\n// releases — precisely the mismatch above. The artifact heals on the next upgrade; that is its job.\n//\n//   - 'allow-cure' → a Bash cure on the allowlist: emitAllow directly, bypassing the git guards.\n//   - 'pass'       → a recovery action the normal flow already permits, so fall THROUGH and let it: ANY\n//                    Read (you must read to know how to fix — see handleRead, which itself fails open),\n//                    or an edit to webpieces.config.json (the always-allowed recovery target).\n//   - 'deny'       → all OTHER work: blocked until the committed shim matches renderShim() again.\nexport type ShimStaleDecision = 'allow-cure' | 'pass' | 'deny';\n// webpieces-disable no-function-outside-class -- pure decision helper beside the adapter's other module-scope functions; exported for direct unit testing.\nexport function shimStaleRecoveryDecision(toolName: string, command: string, filePath: string): ShimStaleDecision {\n    const allowed = isAllowed(toolName, command, filePath);\n    if (allowed === 'pass') return 'pass';\n    if (allowed === 'allow') return 'allow-cure';\n    return 'deny';\n}\n\n// MANAGED-HOOK-SURFACE self-guard, moved here from the rendered shim (2026-07-24) and widened from one\n// file to three (2026-08-07). The committed\n// .claude/webpieces/ai-hook.sh is webpieces-MANAGED and generated from renderShim(); if it no longer\n// matches, it was reverted / hand-edited / predates this binary, so its OWN fail-closed logic can't be\n// trusted. We are the CURRENT binary from node_modules — the trustworthy party — so WE decide here\n// instead of the (possibly stale) shim. It used to `cmp` itself inside the shim: a double-edged trap,\n// since the check lived in the very file it guarded and a fix could only ship by regenerating that\n// file. Now we fail closed on all real WORK while always leaving the recovery path open (see\n// shimStaleRecoveryDecision): the whole L0 allowlist, any Read, and editing webpieces.config.json. We deny +\n// tell the AI; we do NOT silently rewrite the file under it. 'rules' hook skips it (guards owns the\n// shim). Returns normally (pass / nothing to do) or exits via emitAllow/emitDeny.\n// webpieces-disable no-function-outside-class -- sibling of handleBash()/handleFileTool() in this module; the adapter is module-scope functions by design\nfunction enforceCommittedShim(payload: ClaudeCodePayload, cwd: string, mode: HookMode): void {\n    // ONE root for the whole decision, resolved from the RUNNING MODULE (governingShimRoot), never from\n    // `cwd`: the shim file we compare and the renderShim() we compare it TO must come from the same\n    // install, or the check straddles two trees and can never converge (see governingShimRoot's header).\n    // `cwd` still selects where the L0 matrix doc is dropped — that is a \"where does the AI read\" question,\n    // not part of the judgement.\n    const shimRoot = governingShimRoot();\n    if (mode === 'rules') return;\n    // WHICH of the three managed things moved — ai-hook.sh, the settings.json registration, or its\n    // managed env entry (the Bash-cwd pin that keeps a guard's verdict independent of where an earlier\n    // `cd` left the shell; see managed-env.ts). Nothing validated the registration before it joined this\n    // fault, so a settings file left on a superseded form silently changed WHO GOVERNS, with no signal\n    // anywhere — which is the whole reason the registration is a drift surface and not just an install\n    // step.\n    const drifted = managedSurfaceDrift(shimRoot);\n    if (drifted.length === 0) return;\n    const decision = shimStaleRecoveryDecision(payload.tool_name, payload.tool_input.command ?? '', payload.tool_input.file_path ?? '');\n    if (decision === 'pass') return;\n    if (decision === 'allow-cure') emitAllow();\n    // Drop the L0 matrix doc where the AI can read it and point the deny at it — a Read is entry 1 of\n    // the same allowlist, so the pointer is always followable. Best-effort: no doc → no pointer.\n    const root = new RepoRootFinder().resolveRepoRoot(cwd);\n    const docPath = writeGuardMatrixDoc(root);\n    // WRITE THE AUDIT LINE HERE. This block happens BEFORE invocationLog.begin() — it has to, since a\n    // stale shim invalidates everything downstream — so emitDeny's flush finds nothing pending and an\n    // `S` storm left NO trace at all: the one fault most likely to block twenty consecutive tool calls\n    // was the one fault the trail could not show. A decision line is the fix that costs no reordering.\n    const target = payload.tool_input.command ?? payload.tool_input.file_path ?? '';\n    logGuardDecision(\n        root,\n        new GuardDecision('committed-shim-stale', payload.tool_name, target, branchForLog(root), 'BLOCK_AI_CURE', 'L0 fault S (committed shim != renderShim)', '-', L0_FAULT_SHIM_STALE, MATRIX_L0),\n    );\n    // L0 fault S in GUARD_MATRIX.md's codebook — named as the blocking rule so the invocation line\n    // says WHAT stopped the call, not merely that something did, and stamped as `fault=S` so the same\n    // grep finds it here as in the sh half's `L0-shim/` stream.\n    // A subagent is discriminated by `agent_id`, which Claude Code populates on stdin only off the main\n    // loop (main falls back to the session id, so the field is absent). Its cure differs: the hooks\n    // blocking it resolve through CLAUDE_PROJECT_DIR, which names the MAIN tree.\n    const inSubagent = (payload.agent_id ?? '') !== '';\n    emitDeny(shimStaleDenyReason(installedShimRulesVersion(), shimRoot ?? '', drifted, inSubagent) + guardMatrixPointer(docPath), payload.tool_name, 'committed-shim-stale', L0_FAULT_SHIM_STALE);\n}\n\n/**\n * Shared entry point for all three Claude Code PreToolUse adapters. `mode` selects which tool kinds\n * to validate; payloads outside the mode's scope pass through (emitAllow). Blocks by emitting a\n * PreToolUse `permissionDecision:\"deny\"` JSON on stdout (exit 0) — see claude-code-response.ts. Fails\n * CLOSED on any unexpected crash (emits a deny) so a broken hook never silently lets an edit through,\n * and the reason now surfaces in the Claude Code UI instead of being hidden on a stderr+exit-2 block.\n */\nexport async function runMain(mode: HookMode): Promise<void> {\n    // Captured from the payload as soon as it parses so the fail-closed catch below can tell denyJson\n    // which tool it is denying — a crash on a Bash call still gets the visible red systemMessage, a\n    // crash on a file tool does not. Empty (before parse / malformed input) → treated as non-Bash.\n    let toolName = '';\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const raw = await readStdin();\n        const payload = safeParse(raw);\n        if (!payload) { emitAllow(); }\n        toolName = payload.tool_name;\n\n        // BEFORE enforceCommittedShim(), which can itself write a BLOCK line. See LogStream for why\n        // all three of session/agent/hook are needed to keep concurrent writers off one file.\n        logStream.identify(new StreamIdentity(payload.session_id ?? '', payload.agent_id ?? '', mode));\n\n        // Prefer the payload cwd (the AI's actual working dir, follows a persisted `cd`) over\n        // process.cwd(); they match today, but the payload is the authoritative signal and stays\n        // correct if the hook is ever invoked from a fixed dir (e.g. via $CLAUDE_PROJECT_DIR).\n        const cwd = payload.cwd ?? process.cwd();\n\n        // Committed-shim self-guard: blocks real work while the committed shim is stale, but keeps the\n        // recovery path open (cures, reads, config edit). See enforceCommittedShim / shimStaleRecoveryDecision.\n        enforceCommittedShim(payload, cwd, mode);\n\n        // Read-only tools (Read): audit-log, warm the main-sync cache, then run the ONE read-scoped\n        // guard (read-stale-guard) and allow. Runs BEFORE the general rule engine — no code-style rule\n        // ever sees a Read, and the only way this path can deny is a stale `main`.\n        // The audit trail still records every file the AI opened (see setup.ts).\n        if (READ_ONLY_TOOLS.has(payload.tool_name)) {\n            const readPath = payload.tool_input.file_path ?? '';\n            if (mode !== 'rules') {\n                invocationLog.begin(cwd, payload.tool_name, readPath);\n                // Reads vastly outnumber edits, so refreshing here is what actually keeps the shared\n                // main-sync cache warm for feature-branch-guard. Detached; never slows the read.\n                triggerMainSyncRefresh(cwd);\n            }\n            handleRead(readPath, cwd, mode);\n            emitAllow();\n        }\n\n        // Per-invocation guard log (the `calls/` stream): tool + command/file + live branch +\n        // main-sync-status snapshot, on EVERY guards call, for later cleanup automation. Best-effort;\n        // never blocks the call. (The committed shim is no longer silently healed here — a mismatch is\n        // reported by the self-guard above, not rewritten out from under the AI.)\n        if (mode !== 'rules') {\n            const target = payload.tool_name === 'Bash' ? (payload.tool_input.command ?? '') : (payload.tool_input.file_path ?? '');\n            invocationLog.begin(cwd, payload.tool_name, target);\n        }\n\n        if (payload.tool_name === 'Bash') {\n            // No code-style rule is bash-scoped, so the rules hook ignores Bash.\n            if (mode === 'rules') { emitAllow(); }\n            handleBash(payload, cwd, mode);\n            return;\n        }\n\n        // File payloads run in 'rules' (code-style), 'guards' (file-scoped guards like\n        // feature-branch-guard), and 'all'. The runner filters to the right category.\n        handleFileTool(payload, cwd, mode);\n    } catch (err: unknown) {\n        const error = toError(err);\n        denyForCrash(error, toolName);\n    }\n}\n\n/**\n * The fail-closed boundary for anything that escaped the hook body. An escaped RuleFailError (a rule\n * that threw past the runner's per-rule catch) or an InformAiError (bad config/stdin) both carry an\n * AI-readable message; anything else is an unexpected bug. All three DENY and surface their reason,\n * because a hook that crashed established nothing and must never be read as an allow.\n */\n// webpieces-disable no-function-outside-class -- sibling of the module-scope hook entry points in this adapter; a lone class for one terminal boundary would break the file's shape\nfunction denyForCrash(error: Error, toolName: string): never {\n    if (error instanceof RuleFailError) {\n        emitDeny(error.aiMessage, toolName, 'rule-crash');\n    }\n    if (error instanceof InformAiError) {\n        emitDeny(error.message, toolName, 'bad-config-or-stdin');\n    }\n    emitDeny(`[ai-hooks] hook crashed unexpectedly — failing closed: ${error.message}`, toolName, 'hook-crash');\n}\n"]}

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

@@ -1,39 +1,70 @@
 /**
- * THE INSTALLED HOOK SURFACE — three hooks, and the ONE place their spelling is defined.
+ * THE INSTALLED HOOK SURFACE — two hooks, both ABSOLUTE, and the ONE place their spelling is defined.
+ *
+ * ─── 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
+ *
+ * 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.
+ *
+ * ─── Why the relative experiment was reversed ──────────────────────────────────────────────────────
+ * Relative registration was adopted so each git tree would be governed by "its own release, binary and
+ * pin". MEASURED 2026-08-10: it never delivered that. 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; it never ran its own release. Governance was already the primary's, in every tree, the whole
+ * time.
+ *
+ * The price of that fiction was an entire guard layer. A relative path only resolves at a tree root, and
+ * a hook that cannot resolve exits 127 — per the hooks reference a NON-BLOCKING error, i.e. a SILENT
+ * UNGUARDED ALLOW. So L-1 had to deny every `cd` into a project subdirectory. That denial produced the
+ * force-to-root bug class, the reaped-worktree `cd` prescription, and a measured hard deadlock: L-1 told
+ * a worktree-isolated agent to `cd` to the primary clone, which the harness refuses for an isolated
+ * agent, leaving it unable to stay or to follow the cure.
+ *
+ * An absolute path resolves from ANY cwd. So the launch guarantee is structural, L-1 has no job left and
+ * is deleted, and `cd` into a subdirectory is simply allowed. What used to be true only by policing the
+ * shell is now true by construction.
+ *
+ * ─── What replaces the property that was lost ──────────────────────────────────────────────────────
+ * Nothing is lost that was ever delivered — but the case relative registration WANTED to handle (a tree
+ * that genuinely needs a different @webpieces) is now DETECTED instead of silently mis-governed:
+ * `VersionSyncGuard` (L1 row 8) blocks when a worktree's pin disagrees with the main tree's, and
+ * prescribes either aligning the pins (same git hash → same tracked pin → one install in the main tree)
+ * or using a separate CLONE, which — unlike a worktree — really does get its own node_modules and its
+ * own governance.
  *
- * ─── Why three, and why two of them are RELATIVE ───────────────────────────────────────────────────
- * `.claude/settings.json` used to register two hooks, BOTH absolute via `$CLAUDE_PROJECT_DIR`. That
- * variable NEVER moves — proven from four separate worktrees' own logs, every line reading
- * `root=<worktree> projectDir=<primary>` — so every tree was governed by the PRIMARY's shim, the
- * PRIMARY's binary and the PRIMARY's pin, forever. A worktree could never be judged by the release its
- * own branch pins, and measuring one tree while running another's binary is the non-convergent
- * "two-tree straddle" recorded in shim.ts (an agent gave up after four cures).
- *
- * The hooks reference says "the hook runs in the `cwd` value from the JSON input", so a RELATIVE
- * command resolves against the tool call's own tree. Hence:
- *
- *   H1  absolute  sh "$CLAUDE_PROJECT_DIR/.claude/webpieces/guarantee-root.sh"   matcher Bash
- *   H2  relative  sh ".claude/webpieces/ai-hook.sh" wp-ai-guards-hook            matcher Write|…|Read
- *   H3  relative  sh ".claude/webpieces/ai-hook.sh" wp-ai-rules-hook             matcher Write|Edit|MultiEdit
+ * ─── Why the registration is a DRIFT SURFACE, not just an install step ─────────────────────────────
+ * Nothing used to validate `.claude/settings.json` at all, so a settings file left on a superseded form
+ * silently changed who governs. The installed surface is THREE things (ai-hook.sh, the registration, and
+ * the managed `env` entry — see managed-env.ts), all three are compared against this release, and
+ * `wp-upgrade-shim` regenerates all three. A cure that fixes two of three is worse than no cure, because
+ * it reports success.
+ */
+/**
+ * The RETIRED L-1 hook's committed path. Named here, in the one module that must still recognise it, and
+ * matched ONLY by isManagedCommand() so repairRegistration() can delete the stale entry. There is no
+ * guarantee-root.ts any more — this literal is all that remains of it, deliberately.
  *
- * H1 stays absolute because it is the one hook that must ALWAYS resolve: a relative hook that cannot
- * resolve exits 127, and per the same reference any non-2 non-zero exit is a NON-BLOCKING error — i.e.
- * a SILENT UNGUARDED ALLOW. H1 refuses any `cd` that would park the shell where H2/H3 cannot launch,
- * which is what makes the relative pair admissible at all. See guarantee-root.ts.
+ * It is a one-way RECOGNISER, not a shim: nothing emits it, `expectedEntries()` never returns it, and a
+ * settings file carrying it is reported STALE. Its only job is to make the retired entry findable so it
+ * can be REMOVED.
+ */
+export declare const LEGACY_GUARANTEE_ROOT_MARKER = ".claude/webpieces/guarantee-root.sh";
+/**
+ * When this recogniser may be deleted, as a value rather than a comment nobody re-reads.
  *
- * H1 matches `Bash` alone because only Bash can move the shell — the same reason stated at the top of
- * guarantee-root.ts, and the reason the rendered guarantee-root.sh exits 0 immediately for every other
- * tool. Registering it wider would spawn a process per Write/Read to do nothing.
+ * A removal-only migration is still dead weight once no consumer can be carrying the old shape. The
+ * hazard of deleting it EARLY is severe and silent — repair would stop stripping the retired entry, and
+ * a hook registered against a deleted file exits 127, which the Claude Code hooks reference defines as a
+ * NON-BLOCKING error, i.e. every `cd` unjudged while the cure reports success. So it gets a stated date
+ * and a test that fails once the date passes, instead of an intention.
  *
- * ─── Why the registration is a DRIFT SURFACE, not just an install step ─────────────────────────────
- * Nothing used to validate `.claude/settings.json` at all, so a settings file left on the old
- * two-absolute-hook form silently reverted a repo to per-PRIMARY governance and disabled H1 — the one
- * component whose whole job is failing closed. The installed surface is therefore FOUR things
- * (ai-hook.sh, guarantee-root.sh, the registration, and the managed `env` entry — see managed-env.ts for
- * what that fourth one is and why it is guard integrity rather than ergonomics), all four are compared
- * against this release, and `wp-upgrade-shim` regenerates all four. A cure that fixes three of four is
- * worse than no cure, because it reports success.
+ * `legacy-marker-expiry.spec.ts` reads this and fails after it, which is the reminder.
  */
+export declare const LEGACY_MARKER_REMOVE_AFTER = "2026-12-01";
 /** One PreToolUse hook entry as webpieces registers it. Data-only → a class, per CLAUDE.md. */
 export declare class HookRegistrationEntry {
     readonly matcher: string;
@@ -60,22 +91,43 @@ 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";
-export declare const GUARANTEE_ROOT_MATCHER = "Bash";
 /**
- * The RELATIVE guard-hook command — `sh ".claude/webpieces/ai-hook.sh" <bin>`.
- *
- * Relative, NOT `$CLAUDE_PROJECT_DIR/…`: that is the whole point (see the header). 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.
+ * The guard-hook command — `sh "$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh" <bin>`.
+ *
+ * ABSOLUTE. This replaced a RELATIVE spelling, and the reversal is the whole point of this release.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
  */
 export declare function shimCommand(bin: string): string;
-/** H1's command. ABSOLUTE on purpose — it must resolve from ANY cwd or it cannot fail closed. */
-export declare const GUARANTEE_ROOT_COMMAND = "sh \"$CLAUDE_PROJECT_DIR/.claude/webpieces/guarantee-root.sh\"";
-export declare const GUARANTEE_ROOT_ENTRY: HookRegistrationEntry;
 /** The registration entry for one guard bin. */
 export declare function guardHookEntry(bin: string): HookRegistrationEntry;
-/** True when this PreToolUse command is one webpieces owns (either .sh file, in any spelling). */
+/**
+ * True when this PreToolUse command is one webpieces owns — in ANY spelling it has ever shipped.
+ *
+ * THE SINGLE MOST IMPORTANT LINE IN THIS RELEASE. `LEGACY_GUARANTEE_ROOT_MARKER` is matched here and
+ * NOWHERE else: it is how `repairRegistration()` finds and REMOVES the retired H1 entry from a settings
+ * file written by an older release. Drop it and the repair silently leaves a live L-1 hook registered
+ * against a file this release deletes — exit 127, which the Claude Code hooks reference defines as a
+ * NON-BLOCKING error, so every `cd` goes unjudged while `wp-upgrade-shim` reports success and no drift
+ * check can name it. Removal-only, never emitted: it appears in no `expectedEntries()` result, so it is
+ * a one-way migration and not a second accepted spelling.
+ */
 export declare function isManagedCommand(command: string): boolean;
 /** Every webpieces-managed entry of one settings file, flattened to matcher + command pairs. */
 export declare function managedEntries(settings: ClaudeSettings): readonly HookRegistrationEntry[];
@@ -88,14 +140,14 @@ export declare function registeredBins(settings: ClaudeSettings): readonly strin
 /**
  * The exact set of entries THIS RELEASE expects in a settings file that registers `bins`.
  *
- * H1 rides with the GUARDS hook, not the rules hook: H1 judges Bash, and `Bash` is in the guards
- * matcher. A file carrying only the rules hook (the supported split install, where a team ships the
- * guards and a developer keeps the code-style rules local) gets no H1 and needs none.
+ * ONE entry per registered bin, and nothing else. There used to be a third, `guarantee-root.sh`, added
+ * 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[];
 /**
- * True when a settings file registers webpieces hooks in a shape this release does not expect — the
- * old two-absolute-hook form, a missing guarantee-root entry, a stray duplicate, a wrong matcher.
+ * 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.
  *
  * 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.
@@ -110,9 +162,14 @@ export declare function addHookEntry(settings: ClaudeSettings, entry: HookRegist
  * carries any value other than the one required one.
  *
  * Gated on `registeredBins()` for the SAME reason `registrationStale()` is: a settings file that
- * registers no webpieces hooks is not a project install and is never judged. A global (absolute)
- * install names the bin path directly and has no relative resolution to protect, so an `env` entry
- * there is nothing this release governs.
+ * registers no webpieces hooks is not a project install and is never judged — a global install names
+ * the bin path directly and carries no shim marker at all, so there is nothing here to keep in step.
+ *
+ * NOTE what this entry is for NOW. It was originally justified by keeping the then-RELATIVE hook path
+ * resolvable; that job is retired, because both hooks are absolute and resolve from any cwd. It is kept
+ * for VERDICT STABILITY — a guard's answer must depend on the command, not on where an earlier `cd` left
+ * the shell — and because settings `env` is inherited, every subagent shares that cwd and therefore that
+ * verdict. See managed-env.ts, which states this at length.
  */
 export declare function envStale(settings: ClaudeSettings): boolean;
 /**
@@ -127,12 +184,12 @@ export declare function envStale(settings: ClaudeSettings): boolean;
  */
 export declare function applyManagedEnv(settings: ClaudeSettings): boolean;
 /**
- * Bring one settings object to the three-hook form AND the managed `env` entry IN PLACE. Returns true
- * when it changed anything.
+ * Bring one settings object to the two-hook ABSOLUTE form AND the managed `env` entry IN PLACE. Returns
+ * true when it changed anything.
  *
  * REMOVE-then-ADD for the hooks, never add-beside: two spellings of one registration is exactly the
- * compatibility shim the backwards-compat reviewer rejects, and leaving the `$CLAUDE_PROJECT_DIR/`-
- * prefixed entry beside the relative one would run the PRIMARY's binary alongside the tree's own — the
+ * compatibility shim the backwards-compat reviewer rejects, and leaving a RELATIVE entry beside the
+ * absolute one would run two shims per call — the
  * straddle this whole change exists to delete.
  *
  * THE TWO REPAIRS ARE EVALUATED INDEPENDENTLY, and that is load-bearing rather than tidy: this used to
@@ -165,15 +222,22 @@ export declare class SettingsRepair {
 }
 /** Rewrite every stale project settings file under `root`; returns what changed, per file. */
 export declare function repairRegistrationAt(root: string): readonly SettingsRepair[];
-/** The four names the drift check reports, so a deny can say WHICH of them moved. */
+/**
+ * The THREE names the drift check reports, so a deny can say WHICH of them moved.
+ *
+ * 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.
+ */
 export declare const SHIM_SURFACE = ".claude/webpieces/ai-hook.sh";
-export declare const GUARANTEE_ROOT_SURFACE = ".claude/webpieces/guarantee-root.sh";
 export declare const REGISTRATION_SURFACE = ".claude/settings.json hook registration";
 export declare const ENV_SURFACE = ".claude/settings.json env.CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR";
 /**
- * WHICH of the four managed surfaces disagree with this release — the input to fault S.
+ * WHICH of the three managed surfaces disagree with this release — the input to fault S.
  *
- * All four are checked against the SAME root, resolved from the RUNNING MODULE (governingShimRoot),
+ * All three 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.
  */