@webpieces/ai-hook-rules 0.4.584 → 0.4.587

package/README.md

@@ -40,7 +40,8 @@ openclaw plugins enable @webpieces/ai-hook-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
   `feature-branch-guard` on `Write|Edit|MultiEdit`. `Read` carries no guard — it is a
-  log-and-allow fast path that records every file the AI opens in `.webpieces/logs/guard-invocations.log`
+  log-and-allow fast path that records every file the AI opens in
+  `.webpieces/logs/<session>-<agent>-<hook>-guard-invocations.log`
   (never blocked), so you can see whether the AI read a project's `design.json` before editing it.
 
 For each hook the setup command prompts for a target: project `.claude/settings.json`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/ai-hook-rules",
-  "version": "0.4.584",
+  "version": "0.4.587",
   "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.584"
+    "@webpieces/rules-config": "0.4.587"
   },
   "publishConfig": {
     "access": "public"

package/src/adapters/hook-core.js

@@ -16,6 +16,7 @@ const to_error_1 = require("../core/to-error");
 const claude_code_response_1 = require("./claude-code-response");
 const shim_1 = require("../bin/shim");
 const l0_matrix_1 = require("../core/l0-matrix");
+const log_stream_1 = require("../core/log-stream");
 const HANDLED_FILE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit']);
 // Read-only tools carry NO guard or code rule, but the guards hook owns the per-invocation audit log
 // (guard-invocations.log). When the guards matcher includes these (see setup.ts GUARDS_HOOK), a
@@ -227,6 +228,9 @@ async function runMain(mode) {
             (0, claude_code_response_1.emitAllow)();
         }
         toolName = payload.tool_name;
+        // BEFORE enforceCommittedShim(), which can itself write a BLOCK line. See LogStream for why
+        // all three of session/agent/hook are needed to keep concurrent writers off one file.
+        log_stream_1.logStream.identify(payload.session_id ?? '', payload.agent_id ?? '', mode);
         // Prefer the payload cwd (the AI's actual working dir, follows a persisted `cd`) over
         // process.cwd(); they match today, but the payload is the authoritative signal and stays
         // correct if the hook is ever invoked from a fixed dir (e.g. via $CLAUDE_PROJECT_DIR).
@@ -271,18 +275,23 @@ async function runMain(mode) {
     }
     catch (err) {
         const error = (0, to_error_1.toError)(err);
-        // An escaped RuleFailError (a rule that threw past the runner's per-rule catch) or an
-        // InformAiError (bad config/stdin) both carry an AI-readable message; anything else is an
-        // unexpected bug. All three deny (fail closed) and surface their reason to the AI.
-        if (error instanceof types_1.RuleFailError) {
-            (0, claude_code_response_1.emitDeny)(error.aiMessage, toolName, 'rule-crash');
-        }
-        else if (error instanceof types_1.InformAiError) {
-            (0, claude_code_response_1.emitDeny)(error.message, toolName, 'bad-config-or-stdin');
-        }
-        else {
-            (0, claude_code_response_1.emitDeny)(`[ai-hooks] hook crashed unexpectedly — failing closed: ${error.message}`, toolName, 'hook-crash');
-        }
+        denyForCrash(error, toolName);
+    }
+}
+/**
+ * The fail-closed boundary for anything that escaped the hook body. An escaped RuleFailError (a rule
+ * that threw past the runner's per-rule catch) or an InformAiError (bad config/stdin) both carry an
+ * AI-readable message; anything else is an unexpected bug. All three DENY and surface their reason,
+ * because a hook that crashed established nothing and must never be read as an allow.
+ */
+// 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
+function denyForCrash(error, toolName) {
+    if (error instanceof types_1.RuleFailError) {
+        (0, claude_code_response_1.emitDeny)(error.aiMessage, toolName, 'rule-crash');
+    }
+    if (error instanceof types_1.InformAiError) {
+        (0, claude_code_response_1.emitDeny)(error.message, toolName, 'bad-config-or-stdin');
     }
+    (0, claude_code_response_1.emitDeny)(`[ai-hooks] hook crashed unexpectedly — failing closed: ${error.message}`, toolName, 'hook-crash');
 }
 //# sourceMappingURL=hook-core.js.map

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 } 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 { committedShimStale, governingShimRoot, isAllowed, shimStaleDenyReason, installedShimRulesVersion } from '../bin/shim';\nimport { writeGuardMatrixDoc, guardMatrixPointer } from '../core/l0-matrix';\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// (guard-invocations.log). 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    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 result = runBash(command, cwd, mode, agentIdentityOf(payload));\n    if (!result) { emitAllow(); }\n    // Persist the block + WHY. File-tool denies go to hook-rejection.log via logRejection, but a Bash\n    // deny had no audit trail — record it in guard-sync-decisions.log so \"blocked and why\" is complete\n    // for Bash too. `.webpieces` lives at the repo root, resolved from cwd. Best-effort; never blocks.\n    const root = new RepoRootFinder().resolveRepoRoot(cwd);\n    logGuardDecision(root, new GuardDecision('bash-guard', 'Bash', command ?? '', branchForLog(root), 'BLOCK', result.report));\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'));\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'));\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', 'config-bypass (feature-branch-guard skipped)'),\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'));\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// Committed-shim self-guard, moved here from the rendered shim (2026-07-24). 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' || !committedShimStale(shimRoot)) 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 docPath = writeGuardMatrixDoc(new RepoRootFinder().resolveRepoRoot(cwd));\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.\n    emitDeny(shimStaleDenyReason(installedShimRulesVersion(), shimRoot ?? '') + guardMatrixPointer(docPath), payload.tool_name, 'committed-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        // 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 (guard-invocations.log): 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        // An escaped RuleFailError (a rule that threw past the runner's per-rule catch) or an\n        // InformAiError (bad config/stdin) both carry an AI-readable message; anything else is an\n        // unexpected bug. All three deny (fail closed) and surface their reason to the AI.\n        if (error instanceof RuleFailError) {\n            emitDeny(error.aiMessage, toolName, 'rule-crash');\n        } else if (error instanceof InformAiError) {\n            emitDeny(error.message, toolName, 'bad-config-or-stdin');\n        } else {\n            emitDeny(`[ai-hooks] hook crashed unexpectedly — failing closed: ${error.message}`, toolName, 'hook-crash');\n        }\n    }\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 { AgentIdentity } from '../core/coordinator-worktree';\nimport { logRejection, extractRuleNames } from '../core/rejection-log';\nimport { logGuardDecision, GuardDecision, branchForLog, invocationLog } 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 { committedShimStale, governingShimRoot, isAllowed, shimStaleDenyReason, installedShimRulesVersion } from '../bin/shim';\nimport { writeGuardMatrixDoc, guardMatrixPointer } from '../core/l0-matrix';\nimport { logStream } from '../core/log-stream';\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// (guard-invocations.log). 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 result = runBash(command, cwd, mode, agentIdentityOf(payload));\n    if (!result) { emitAllow(); }\n    // Persist the block + WHY. File-tool denies go to hook-rejection.log via logRejection, but a Bash\n    // deny had no audit trail — record it in guard-sync-decisions.log so \"blocked and why\" is complete\n    // for Bash too. `.webpieces` lives at the repo root, resolved from cwd. Best-effort; never blocks.\n    const root = new RepoRootFinder().resolveRepoRoot(cwd);\n    logGuardDecision(root, new GuardDecision('bash-guard', 'Bash', command ?? '', branchForLog(root), 'BLOCK', result.report));\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'));\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'));\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', 'config-bypass (feature-branch-guard skipped)'),\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'));\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// Committed-shim self-guard, moved here from the rendered shim (2026-07-24). 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' || !committedShimStale(shimRoot)) 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 docPath = writeGuardMatrixDoc(new RepoRootFinder().resolveRepoRoot(cwd));\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.\n    emitDeny(shimStaleDenyReason(installedShimRulesVersion(), shimRoot ?? '') + guardMatrixPointer(docPath), payload.tool_name, 'committed-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(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 (guard-invocations.log): 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/guarantee-root.d.ts

@@ -0,0 +1,90 @@
+/**
+ * L-1 — the layer BELOW L0: guarantee the shell stays somewhere the RELATIVE guard hooks can launch.
+ *
+ * ─── Why a layer below L0 exists at all ────────────────────────────────────────────────────────────
+ * From the Claude Code hooks reference: exit 2 is the blocking channel, exit 0 carries the JSON
+ * decision, and ANY OTHER exit is a "non-blocking error. Execution continues; the action proceeds" —
+ * including "File missing or not executable: Error logged; tool proceeds."
+ *
+ *   A HOOK THAT FAILS TO LAUNCH IS A SILENT ALLOW. Not a block, not an error the AI sees.
+ *
+ * Every layer L0-L4 assumes the hook process ran at all. This file is what makes that assumption true.
+ *
+ * ─── Why the guard hooks become RELATIVE ───────────────────────────────────────────────────────────
+ * `.claude/settings.json` registers hooks as `sh "$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh"`,
+ * and `$CLAUDE_PROJECT_DIR` NEVER moves — proven from four separate worktrees' own logs, every line
+ * reading `root=<worktree> projectDir=<primary>`. So every tree is governed by the PRIMARY's shim and
+ * the PRIMARY's binary, forever: a worktree can 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 fix is to re-root the WHOLE hook, not to measure differently. 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 — each tree runs its own shim, its own binary, its own pin. One version, one tree.
+ *
+ * That is only safe if the relative path is guaranteed to resolve. Hence this file.
+ *
+ * ─── Why this is a SEPARATE checked-in file from ai-hook.sh ────────────────────────────────────────
+ * 1. It is the ONE file that must stay $CLAUDE_PROJECT_DIR-anchored, so it is the one file that cannot
+ *    be upgraded per-tree. Its surface is therefore kept minimal: a path check. No drift scraper, no
+ *    allowlist, no config load, no binary — nothing that needs to change often.
+ * 2. Its stability profile is the OPPOSITE of ai-hook.sh's. The shim changes most releases; a `cd`
+ *    validator should converge and stop. Sharing one file forces the stable half to inherit the
+ *    volatile half's churn — which is today's problem, one level up.
+ * 3. A NEW FILE IS INVISIBLE TO OLD RELEASES; A NEW FLAG BREAKS THEM. Measured 2026-08-06: registering
+ *    `ai-hook.sh --force-root` made the installed shim read `--force-root` as a BIN NAME, fail to find
+ *    it, and emit fault U — denying `ls` and the very `cd` that would have fixed it:
+ *      16:32:20  --force-root  Bash  tree=primary  fault=U  DENY-UNDECLARED  ls
+ *    A separate file is simply not registered until a release that ships it, so old releases are safe.
+ *
+ * ─── The invariant, maintained inductively ─────────────────────────────────────────────────────────
+ * A session always starts at a tree root (primary for the coordinator, the worktree for a subagent).
+ * The only thing that moves the shell is a `cd`, and (measured 2026-08-02, effective-tree.ts) a `cd`
+ * that stays INSIDE the workspace PERSISTS to later calls, while a `cd` that LEAVES it is RESET by the
+ * harness before the next call.
+ *
+ *   If every `cd` that would leave a tree root is refused, "the shell is at a tree root" is an
+ *   INDUCTIVE INVARIANT — so this hook never inspects cwd as a state, only the command.
+ *
+ * That is also why it is registered for Bash ALONE: no other tool can move the shell.
+ *
+ * ─── The predicate, in three tests ─────────────────────────────────────────────────────────────────
+ *   1. destination holds `.git`  → ALLOW. Complete by construction: the primary clone has a .git DIR,
+ *      every linked worktree (nested or sibling) has a .git FILE, and a nested foreign clone under
+ *      repositories/** has its own .git DIR. The first two are where the relative hooks launch; the
+ *      third is a tree we deliberately do not govern.
+ *   2. destination is OUTSIDE $CLAUDE_PROJECT_DIR → ALLOW. The harness resets it before the next call,
+ *      so at most ONE call runs at a path we do not govern — and there is nothing there to guard.
+ *   3. otherwise (inside a governed tree, no .git — `tools/`, `dataform/`, `packages/…`) → DENY. This
+ *      is the only region that is both STICKY and UNGUARDED.
+ *
+ * It reads NO config. `excludePaths` governs which FILES are enforced, not whether the hook may run,
+ * and it cannot be parsed here anyway (this is sh, pre-config, pre-binary). The one measured divergence
+ * is `tools/**`: exempt by excludePaths, denied here — correctly, because the real hooks genuinely
+ * cannot launch there and we genuinely want them to. Cost: 4 calls in a 2,236-call sample.
+ *
+ * ─── Nothing to recover from ───────────────────────────────────────────────────────────────────────
+ * A denied `cd` NEVER EXECUTES — PreToolUse denies the whole tool call before the shell moves — so the
+ * shell is still at a root. There is no bad state and no cure command that needs allowlisting, which is
+ * what keeps this hook from ever being able to wedge a session.
+ *
+ * Measured cost of the deny: 47 of 2,236 real Bash calls (2.10%), or 9.7% of all `cd` commands.
+ */
+export declare const GUARANTEE_ROOT_MARKER = ".claude/webpieces/guarantee-root.sh";
+export declare function guaranteeRootPath(projectRoot: string): string;
+/**
+ * The POSIX-sh source. Byte-identical to `templates/guarantee-root.sh`, locked by a unit test, exactly
+ * as renderShim()/templates/ai-hook.sh are — so the file a consumer commits and the file this release
+ * expects can never silently diverge.
+ */
+export declare function renderGuaranteeRoot(): string;
+/**
+ * True when a committed guarantee-root.sh EXISTS but no longer equals renderGuaranteeRoot(). Missing
+ * file → false: a repo that has not adopted L-1 yet is not "stale", it is simply still on the two-hook
+ * registration, and `wp-install-ai-hooks` is what moves it forward.
+ *
+ * `root` is the tree whose committed copy this BINARY governs — resolved from the running module's own
+ * location by governingShimRoot(), never from cwd and never from $CLAUDE_PROJECT_DIR, for the same
+ * reason the shim's own check is anchored that way: it makes the two-tree straddle unconstructible.
+ */
+export declare function committedGuaranteeRootStale(root: string | null): boolean;

package/src/bin/guarantee-root.js

@@ -0,0 +1,271 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GUARANTEE_ROOT_MARKER = void 0;
+exports.guaranteeRootPath = guaranteeRootPath;
+exports.renderGuaranteeRoot = renderGuaranteeRoot;
+exports.committedGuaranteeRootStale = committedGuaranteeRootStale;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const to_error_1 = require("../core/to-error");
+/**
+ * L-1 — the layer BELOW L0: guarantee the shell stays somewhere the RELATIVE guard hooks can launch.
+ *
+ * ─── Why a layer below L0 exists at all ────────────────────────────────────────────────────────────
+ * From the Claude Code hooks reference: exit 2 is the blocking channel, exit 0 carries the JSON
+ * decision, and ANY OTHER exit is a "non-blocking error. Execution continues; the action proceeds" —
+ * including "File missing or not executable: Error logged; tool proceeds."
+ *
+ *   A HOOK THAT FAILS TO LAUNCH IS A SILENT ALLOW. Not a block, not an error the AI sees.
+ *
+ * Every layer L0-L4 assumes the hook process ran at all. This file is what makes that assumption true.
+ *
+ * ─── Why the guard hooks become RELATIVE ───────────────────────────────────────────────────────────
+ * `.claude/settings.json` registers hooks as `sh "$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh"`,
+ * and `$CLAUDE_PROJECT_DIR` NEVER moves — proven from four separate worktrees' own logs, every line
+ * reading `root=<worktree> projectDir=<primary>`. So every tree is governed by the PRIMARY's shim and
+ * the PRIMARY's binary, forever: a worktree can 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 fix is to re-root the WHOLE hook, not to measure differently. 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 — each tree runs its own shim, its own binary, its own pin. One version, one tree.
+ *
+ * That is only safe if the relative path is guaranteed to resolve. Hence this file.
+ *
+ * ─── Why this is a SEPARATE checked-in file from ai-hook.sh ────────────────────────────────────────
+ * 1. It is the ONE file that must stay $CLAUDE_PROJECT_DIR-anchored, so it is the one file that cannot
+ *    be upgraded per-tree. Its surface is therefore kept minimal: a path check. No drift scraper, no
+ *    allowlist, no config load, no binary — nothing that needs to change often.
+ * 2. Its stability profile is the OPPOSITE of ai-hook.sh's. The shim changes most releases; a `cd`
+ *    validator should converge and stop. Sharing one file forces the stable half to inherit the
+ *    volatile half's churn — which is today's problem, one level up.
+ * 3. A NEW FILE IS INVISIBLE TO OLD RELEASES; A NEW FLAG BREAKS THEM. Measured 2026-08-06: registering
+ *    `ai-hook.sh --force-root` made the installed shim read `--force-root` as a BIN NAME, fail to find
+ *    it, and emit fault U — denying `ls` and the very `cd` that would have fixed it:
+ *      16:32:20  --force-root  Bash  tree=primary  fault=U  DENY-UNDECLARED  ls
+ *    A separate file is simply not registered until a release that ships it, so old releases are safe.
+ *
+ * ─── The invariant, maintained inductively ─────────────────────────────────────────────────────────
+ * A session always starts at a tree root (primary for the coordinator, the worktree for a subagent).
+ * The only thing that moves the shell is a `cd`, and (measured 2026-08-02, effective-tree.ts) a `cd`
+ * that stays INSIDE the workspace PERSISTS to later calls, while a `cd` that LEAVES it is RESET by the
+ * harness before the next call.
+ *
+ *   If every `cd` that would leave a tree root is refused, "the shell is at a tree root" is an
+ *   INDUCTIVE INVARIANT — so this hook never inspects cwd as a state, only the command.
+ *
+ * That is also why it is registered for Bash ALONE: no other tool can move the shell.
+ *
+ * ─── The predicate, in three tests ─────────────────────────────────────────────────────────────────
+ *   1. destination holds `.git`  → ALLOW. Complete by construction: the primary clone has a .git DIR,
+ *      every linked worktree (nested or sibling) has a .git FILE, and a nested foreign clone under
+ *      repositories/** has its own .git DIR. The first two are where the relative hooks launch; the
+ *      third is a tree we deliberately do not govern.
+ *   2. destination is OUTSIDE $CLAUDE_PROJECT_DIR → ALLOW. The harness resets it before the next call,
+ *      so at most ONE call runs at a path we do not govern — and there is nothing there to guard.
+ *   3. otherwise (inside a governed tree, no .git — `tools/`, `dataform/`, `packages/…`) → DENY. This
+ *      is the only region that is both STICKY and UNGUARDED.
+ *
+ * It reads NO config. `excludePaths` governs which FILES are enforced, not whether the hook may run,
+ * and it cannot be parsed here anyway (this is sh, pre-config, pre-binary). The one measured divergence
+ * is `tools/**`: exempt by excludePaths, denied here — correctly, because the real hooks genuinely
+ * cannot launch there and we genuinely want them to. Cost: 4 calls in a 2,236-call sample.
+ *
+ * ─── Nothing to recover from ───────────────────────────────────────────────────────────────────────
+ * A denied `cd` NEVER EXECUTES — PreToolUse denies the whole tool call before the shell moves — so the
+ * shell is still at a root. There is no bad state and no cure command that needs allowlisting, which is
+ * what keeps this hook from ever being able to wedge a session.
+ *
+ * Measured cost of the deny: 47 of 2,236 real Bash calls (2.10%), or 9.7% of all `cd` commands.
+ */
+exports.GUARANTEE_ROOT_MARKER = '.claude/webpieces/guarantee-root.sh';
+// webpieces-disable no-function-outside-class -- L-1 sibling of shim.ts's shimPath(); this module is deliberately dependency-free module-scope functions so it stays callable from a tree too broken to build a DI container
+function guaranteeRootPath(projectRoot) {
+    return path.join(projectRoot, '.claude', 'webpieces', 'guarantee-root.sh');
+}
+// Deny REASON constraint, inherited from the shim: the text is interpolated into a `REASON="…"` shell
+// assignment and then printf'd into a JSON string, so it may contain NO double quotes and NO
+// backslashes. Single quotes only — do not "improve" them.
+const DENY_NOT_LITERAL = 'This cd target is not a literal path, so the guards cannot tell where the shell will end up. '
+    + 'Use a literal absolute path: cd /abs/path && <your command>. '
+    + 'A $VAR, ~, $(...) or backtick is never expanded by the guard.';
+const DENY_NO_TARGET = 'A bare cd (or cd -) moves the shell somewhere the guards cannot predict - a bare cd goes to '
+    + 'your home directory, where the webpieces hooks do not exist and every later tool call would '
+    + 'run UNGUARDED. Name the directory: cd /abs/path && <your command>.';
+// `%s` is the destination, then the project root. Kept to one short paragraph on purpose: L0 already
+// ran a message diet and these denies regress straight back to a wall of text if each one argues.
+const DENY_SUBDIR = 'The webpieces guard hooks are registered RELATIVE (.claude/webpieces/ai-hook.sh) so that each '
+    + 'git tree is governed by its own release. %s has no .claude/webpieces/ai-hook.sh, so a shell '
+    + 'parked there launches NO hooks at all and every later tool call runs UNGUARDED - and a cd that '
+    + 'stays inside the project PERSISTS to your next call. Run it from the tree root instead: '
+    + 'cd %s && <your command>. Tools that take their own directory (git -C, pnpm -C, pnpm --filter, '
+    + 'nx) need no cd at all.';
+/**
+ * The cd audit trail. A THIRD parallel writer joins guards+rules on every Bash call, so it gets its
+ * own file under the same session/agent/hook key LogStream uses — one writer per directory, so an
+ * append can never interleave with another's (macOS PIPE_BUF is 512 bytes and real log lines exceed it).
+ *
+ * Unlike the shim's RESOLVE_LOG_DIR_SH this needs NO worktree resolution: H1 is $CLAUDE_PROJECT_DIR-
+ * anchored by definition, so the primary clone's `.webpieces` is always the right home. That is the one
+ * upside of being the hook that cannot follow the tree.
+ *
+ * Every write is swallowed and nothing ever reaches stdout — stdout is the PreToolUse decision channel
+ * and a stray byte there would corrupt allow/deny.
+ */
+const CD_AUDIT_SH = `# --- cd audit (best-effort; never blocks, never touches stdout) --------------------------------
+SID="$(printf '%s' "$PAYLOAD" | sed -n 's/.*"session_id"[[:space:]]*:[[:space:]]*"\\([^"\\\\]*\\)".*/\\1/p')"
+AID="$(printf '%s' "$PAYLOAD" | sed -n 's/.*"agent_id"[[:space:]]*:[[:space:]]*"\\([^"\\\\]*\\)".*/\\1/p')"
+# Untrusted payload values are used as path segments, so anything outside [A-Za-z0-9._-] collapses to _
+# and a leading dot is neutralised — ../../etc can never escape the logs directory.
+clean() { printf '%s' "$1" | tr -c 'A-Za-z0-9._-' '_' \\
+  | sed -e 's/\\.\\{2,\\}/_/g' -e 's/^\\.\\{1,\\}/_/' | cut -c1-64; }
+wp_cd_log() {              # $1 = verdict, $2 = destination (may be empty)
+  {
+    [ -n "$CLAUDE_PROJECT_DIR" ] || return 0
+    _d="$CLAUDE_PROJECT_DIR/.webpieces/logs"
+    mkdir -p "$_d" 2>/dev/null || return 0
+    # Flat name, same scheme as LogStream.fileName(): <session>-<agent|coordinator>-guarantee-root-<base>
+    # ALWAYS prefixed; a missing session_id renders as 'unknown'. No bare-name branch anywhere.
+    _p="$(clean "\${SID:-unknown}")-$(clean "\${AID:-coordinator}")-guarantee-root-"
+    _f="$_d/\${_p}cd-audit.log"
+    _sz="$(wc -c < "$_f" 2>/dev/null | tr -d ' ')"
+    case "$_sz" in ''|*[!0-9]*) _sz=0 ;; esac
+    [ "$_sz" -gt 524288 ] && mv -f "$_f" "$_d/\${_p}cd-audit.1.log" 2>/dev/null
+    printf '%s\\t%s\\tdest=%s\\tcwd=%s\\t%s\\n' \\
+      "$(date '+%Y-%m-%dT%H:%M:%S%z' 2>/dev/null)" "$1" "$2" "$CWD" "$CMD" >> "$_f"
+  } 2>/dev/null || true
+}
+`;
+// The deny boundary. Extracted for the same reason CD_AUDIT_SH and HEADER_SH are — to keep the
+// renderer inside the 70-line method budget — and spliced back verbatim. Mirrors the shim's own emit:
+// for Bash, permissionDecisionReason is NOT user-visible, so the red systemMessage carries the text.
+const DENY_EMIT_SH = `wp_cd_log DENY "\${ABS:-$DEST}"
+
+BS='\\'                      # one literal backslash, so the \\u001b escape never sits in this source
+ESC="\${BS}u001b"           # the 6 chars: backslash u 0 0 1 b — Claude Code parses \\u001b -> ESC
+printf '{"systemMessage":"%s🛑 %s%s","hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\\n' "\${ESC}[31;1m" "$REASON" "\${ESC}[0m" "$REASON"
+exit 0                       # the decision is carried by permissionDecision deny, not the exit code
+`;
+// The file's own banner. Extracted to a module const for the same reason renderShim() extracts
+// VERSION_DRIFT_GUARD_SH — to keep the renderer inside the 80-line method budget — and spliced back
+// in verbatim, byte for byte.
+const HEADER_SH = `#!/bin/sh
+# webpieces L-1 hook — GUARANTEE ROOT. Generated by renderGuaranteeRoot(); do not hand-edit.
+#
+# Registered ABSOLUTE in .claude/settings.json, matcher "Bash":
+#   sh "$CLAUDE_PROJECT_DIR/.claude/webpieces/guarantee-root.sh"
+#
+# It exists because the GUARD hooks beside it are registered RELATIVE, so that each git tree is
+# governed by its own @webpieces release. A relative hook that cannot resolve does not block — the
+# harness logs it and lets the tool call proceed UNGUARDED. This file makes that unreachable by
+# refusing any cd that would park the shell where the relative hooks cannot launch.
+#
+# Three tests, no config, no binary, no network:
+#   1. destination holds .git                     -> ALLOW (tree root, worktree, or foreign clone)
+#   2. destination is outside $CLAUDE_PROJECT_DIR -> ALLOW (the harness resets the cwd next call)
+#   3. otherwise                                  -> DENY  (sticky AND unguarded)
+#
+# A denied cd never runs, so the shell never leaves the root and there is nothing to recover from.
+`;
+/**
+ * The POSIX-sh source. Byte-identical to `templates/guarantee-root.sh`, locked by a unit test, exactly
+ * as renderShim()/templates/ai-hook.sh are — so the file a consumer commits and the file this release
+ * expects can never silently diverge.
+ */
+// webpieces-disable no-function-outside-class -- L-1 twin of shim.ts's renderShim(), byte-locked to templates/guarantee-root.sh; module-scope for the same dependency-free reason
+function renderGuaranteeRoot() {
+    return `${HEADER_SH}
+PAYLOAD="$(cat)"
+CWD="$(printf '%s' "$PAYLOAD" | sed -n 's/.*"cwd"[[:space:]]*:[[:space:]]*"\\([^"\\\\]*\\)".*/\\1/p')"
+TOOL="$(printf '%s' "$PAYLOAD" | sed -n 's/.*"tool_name"[[:space:]]*:[[:space:]]*"\\([^"\\\\]*\\)".*/\\1/p')"
+
+# The command PREFIX, not the whole command — note there is no closing " in this pattern.
+# WHY: a JSON payload escapes an embedded double quote as \\", and \`[^"\\\\]*\` stops dead at that
+# backslash, so the usual "capture between quotes" form yields the EMPTY STRING for any command
+# containing a quote at all (measured: \`cd /a/b && echo "hi"\` -> ''). An empty CMD here would mean
+# "no cd found" -> ALLOW, i.e. this guard would fail OPEN for every quoted command — the exact hazard
+# it exists to close. Capturing only up to the first quote/backslash is enough, because everything
+# L-1 needs (is the FIRST word a cd, and what is its target) lives in the prefix; a quote can only
+# appear later, in the part we do not need.
+CMD="$(printf '%s' "$PAYLOAD" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\\([^"\\\\]*\\).*/\\1/p')"
+
+# Only Bash can move the shell. Anything else, and any payload we cannot read, is not ours.
+[ "$TOOL" = "Bash" ] || exit 0
+[ -n "$CMD" ] || exit 0
+
+${CD_AUDIT_SH}
+
+# Does the command OPEN with cd/pushd? Only a LEADING cd counts — the same rule effective-tree.ts
+# enforces, because a later cd cannot retroactively move a command that has already run.
+FIRST="$(printf '%s' "$CMD" | sed -n 's/^[[:space:]]*\\([^[:space:]]\\{1,\\}\\).*/\\1/p')"
+case "$FIRST" in
+  cd|pushd) ;;
+  *) exit 0 ;;                 # no leading cd: nothing to audit, nothing to judge
+esac
+
+# The target: a single-quoted path first (that is how a path with spaces is spelled), else a bare word.
+DEST="$(printf '%s' "$CMD" | sed -n "s/^[[:space:]]*[a-z]\\{2,5\\}[[:space:]]\\{1,\\}'\\([^']*\\)'.*/\\1/p")"
+[ -n "$DEST" ] || DEST="$(printf '%s' "$CMD" | sed -n 's/^[[:space:]]*[a-z]\\{2,5\\}[[:space:]]\\{1,\\}\\([^[:space:];&|]\\{1,\\}\\).*/\\1/p')"
+
+REASON=""
+if [ -z "$DEST" ] || [ "$DEST" = "-" ]; then
+  REASON='${DENY_NO_TARGET}'
+else
+  # A target the guard cannot expand is a target it cannot judge. sh has no regex here, so test the
+  # four unexpandable shapes directly.
+  case "$DEST" in
+    *'$'*|*'\`'*|'~'|'~/'*) REASON='${DENY_NOT_LITERAL}' ;;
+  esac
+fi
+
+if [ -z "$REASON" ]; then
+  # Resolve against the shell's real cwd. A destination that does not exist needs no verdict: the cd
+  # itself will fail and the shell stays exactly where it is.
+  ABS="$(CDPATH= cd -- "\${CWD:-.}" 2>/dev/null && CDPATH= cd -- "$DEST" 2>/dev/null && pwd)"
+  if [ -z "$ABS" ]; then wp_cd_log ALLOW-NO-SUCH-DIR "$DEST"; exit 0; fi
+
+  # TEST 1 — a git tree of any kind. A worktree's .git is a FILE, a clone's is a DIR; -e covers both.
+  if [ -e "$ABS/.git" ]; then wp_cd_log ALLOW-GIT-TREE "$ABS"; exit 0; fi
+
+  # TEST 2 — outside the governed project. The harness resets the cwd before the next call, so at most
+  # one command runs there, on paths we do not govern anyway.
+  case "$ABS/" in
+    "$CLAUDE_PROJECT_DIR"/*) ;;
+    *) wp_cd_log ALLOW-OUTSIDE "$ABS"; exit 0 ;;
+  esac
+
+  # TEST 3 — inside a governed tree with no shim beside it: sticky AND unguarded.
+  REASON="$(printf '${DENY_SUBDIR}' "$ABS" "$CLAUDE_PROJECT_DIR")"
+fi
+
+${DENY_EMIT_SH}`;
+}
+/**
+ * True when a committed guarantee-root.sh EXISTS but no longer equals renderGuaranteeRoot(). Missing
+ * file → false: a repo that has not adopted L-1 yet is not "stale", it is simply still on the two-hook
+ * registration, and `wp-install-ai-hooks` is what moves it forward.
+ *
+ * `root` is the tree whose committed copy this BINARY governs — resolved from the running module's own
+ * location by governingShimRoot(), never from cwd and never from $CLAUDE_PROJECT_DIR, for the same
+ * reason the shim's own check is anchored that way: it makes the two-tree straddle unconstructible.
+ */
+// webpieces-disable no-function-outside-class -- L-1 twin of shim.ts's committedShimStale(); module-scope for the same dependency-free reason
+function committedGuaranteeRootStale(root) {
+    if (root === null)
+        return false;
+    const file = guaranteeRootPath(root);
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        if (!fs.existsSync(file))
+            return false;
+        return fs.readFileSync(file, 'utf8') !== renderGuaranteeRoot();
+    }
+    catch (err) {
+        const error = (0, to_error_1.toError)(err);
+        void error; // best-effort: an unreadable tree counts as "not stale" so this never wedges a call
+        return false;
+    }
+}
+//# sourceMappingURL=guarantee-root.js.map