@webpieces/ai-hook-rules 0.3.224 → 0.3.226

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/ai-hook-rules",
-  "version": "0.3.224",
+  "version": "0.3.226",
   "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",
@@ -35,7 +35,7 @@
     "directory": "packages/tooling/ai-hook-rules"
   },
   "dependencies": {
-    "@webpieces/rules-config": "0.3.224"
+    "@webpieces/rules-config": "0.3.226"
   },
   "publishConfig": {
     "access": "public"

package/src/adapters/claude-code-response.d.ts

@@ -1,3 +1,3 @@
-export declare function denyJson(reason: string): string;
-export declare function emitDeny(reason: string): never;
+export declare function denyJson(reason: string, toolName: string): string;
+export declare function emitDeny(reason: string, toolName: string): never;
 export declare function emitAllow(): never;

package/src/adapters/claude-code-response.js

@@ -1,29 +1,58 @@
 "use strict";
 // The single place that knows Claude Code's PreToolUse decision protocol, so every deny in the
 // Claude Code adapter is emitted identically — and identically to the checked-in shim
-// (.claude/webpieces/ai-hook.sh, rendered by renderShim() in ../bin/setup.ts), which already emits
-// this exact JSON.
+// (.claude/webpieces/ai-hook.sh, rendered by renderShim() in ../bin/shim.ts), which emits the same JSON.
 //
 // A block is signalled by `permissionDecision: "deny"` JSON on STDOUT with exit 0 — NOT exit 2.
 // Claude Code only parses the JSON on exit 0; exit 2 would ignore stdout and the reason would not
-// surface in the terminal UI (the original bug). "deny" still blocks the tool, so this remains
-// fail-closed: it is not the silent-allow a bare exit 0 with no JSON would be.
+// surface in the terminal UI. "deny" still blocks the tool, so this remains fail-closed: it is not the
+// silent-allow a bare exit 0 with no JSON would be.
+//
+// WHY the tool-conditional `systemMessage` (verified by live tests against Claude Code v2.1.x — the
+// docs are wrong here; do NOT re-derive from them):
+//
+//   | deny field                        | Bash tool                         | Write/Edit/MultiEdit tool     |
+//   |-----------------------------------|-----------------------------------|-------------------------------|
+//   | permissionDecisionReason (plain)  | model sees it; USER SEES NOTHING  | model + RED "Error:" block ok |
+//   | systemMessage                     | ONLY user-visible field; grey     | grey extra line (redundant)   |
+//   | systemMessage wrapped in ANSI red | RED + visible to the user (fix)   | redundant 2nd red line        |
+//
+// So: on a **Bash** deny we ALSO emit a top-level `systemMessage` wrapped in ANSI red (ESC[31;1m …
+// ESC[0m) — it is the only field a Bash deny shows the human, and it honors ANSI. On
+// Write/Edit/MultiEdit we add NO `systemMessage` (the reason already renders red natively — a second
+// line is just noise). `permissionDecisionReason` is always plain text (never ANSI): it's what the
+// model reads and what Write/Edit renders red. JSON.stringify serializes the ESC char as the valid
+// \u escape, so the payload stays valid JSON — we build the ESC via String.fromCharCode(0x1b) so no
+// raw ESC (0x1b) byte ever lives in this source file. Do NOT use exit 2 (stdout JSON ignored;
+// stderr invisible to the user on Bash).
+// Refs: Claude Code GitHub issues #31592, #40380, #17356 (asymmetry "closed / not planned").
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.denyJson = denyJson;
 exports.emitDeny = emitDeny;
 exports.emitAllow = emitAllow;
-function denyJson(reason) {
-    return JSON.stringify({
-        hookSpecificOutput: {
-            hookEventName: 'PreToolUse',
-            permissionDecision: 'deny',
-            permissionDecisionReason: reason,
-        },
-    });
+// ANSI escape (0x1b) built at runtime so no raw ESC byte sits in source. ANSI red is a *bonus* — the
+// 🛑 prefix + reason stay meaningful if a future/CI renderer strips the color. One place = one escape.
+const ESC = String.fromCharCode(0x1b);
+function redSystemMessage(reason) {
+    return `${ESC}[31;1m🛑 ${reason}${ESC}[0m`;
+}
+function denyJson(reason, toolName) {
+    const hookSpecificOutput = {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: reason,
+    };
+    // Bash only: permissionDecisionReason is NOT user-visible, so add the red systemMessage.
+    if (toolName === 'Bash') {
+        return JSON.stringify({ systemMessage: redSystemMessage(reason), hookSpecificOutput });
+    }
+    // Write/Edit/MultiEdit (and anything else): reason renders red natively; no systemMessage.
+    return JSON.stringify({ hookSpecificOutput });
 }
-// Block the tool call and surface `reason` to both the user (terminal UI) and the model.
-function emitDeny(reason) {
-    process.stdout.write(denyJson(reason) + '\n');
+// Block the tool call and surface `reason` to both the user (terminal UI) and the model. `toolName`
+// selects whether the red `systemMessage` is added (Bash) or omitted (file tools) — see denyJson.
+function emitDeny(reason, toolName) {
+    process.stdout.write(denyJson(reason, toolName) + '\n');
     process.exit(0);
 }
 // Allow the tool call. No JSON needed — a silent exit 0 is "allow" in the PreToolUse protocol.

package/src/adapters/claude-code-response.js.map

@@ -1 +1 @@
-{"version":3,"file":"claude-code-response.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/adapters/claude-code-response.ts"],"names":[],"mappings":";AAAA,+FAA+F;AAC/F,sFAAsF;AACtF,mGAAmG;AACnG,mBAAmB;AACnB,EAAE;AACF,gGAAgG;AAChG,kGAAkG;AAClG,+FAA+F;AAC/F,+EAA+E;;AAE/E,4BAQC;AAGD,4BAGC;AAGD,8BAEC;AAnBD,SAAgB,QAAQ,CAAC,MAAc;IACnC,OAAO,IAAI,CAAC,SAAS,CAAC;QAClB,kBAAkB,EAAE;YAChB,aAAa,EAAE,YAAY;YAC3B,kBAAkB,EAAE,MAAM;YAC1B,wBAAwB,EAAE,MAAM;SACnC;KACJ,CAAC,CAAC;AACP,CAAC;AAED,yFAAyF;AACzF,SAAgB,QAAQ,CAAC,MAAc;IACnC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;IAC9C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC;AAED,+FAA+F;AAC/F,SAAgB,SAAS;IACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC","sourcesContent":["// The single place that knows Claude Code's PreToolUse decision protocol, so every deny in the\n// Claude Code adapter is emitted identically — and identically to the checked-in shim\n// (.claude/webpieces/ai-hook.sh, rendered by renderShim() in ../bin/setup.ts), which already emits\n// this exact JSON.\n//\n// A block is signalled by `permissionDecision: \"deny\"` JSON on STDOUT with exit 0 — NOT exit 2.\n// Claude Code only parses the JSON on exit 0; exit 2 would ignore stdout and the reason would not\n// surface in the terminal UI (the original bug). \"deny\" still blocks the tool, so this remains\n// fail-closed: it is not the silent-allow a bare exit 0 with no JSON would be.\n\nexport function denyJson(reason: string): string {\n    return JSON.stringify({\n        hookSpecificOutput: {\n            hookEventName: 'PreToolUse',\n            permissionDecision: 'deny',\n            permissionDecisionReason: reason,\n        },\n    });\n}\n\n// Block the tool call and surface `reason` to both the user (terminal UI) and the model.\nexport function emitDeny(reason: string): never {\n    process.stdout.write(denyJson(reason) + '\\n');\n    process.exit(0);\n}\n\n// Allow the tool call. No JSON needed — a silent exit 0 is \"allow\" in the PreToolUse protocol.\nexport function emitAllow(): never {\n    process.exit(0);\n}\n"]}
+{"version":3,"file":"claude-code-response.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/adapters/claude-code-response.ts"],"names":[],"mappings":";AAAA,+FAA+F;AAC/F,sFAAsF;AACtF,yGAAyG;AACzG,EAAE;AACF,gGAAgG;AAChG,kGAAkG;AAClG,uGAAuG;AACvG,oDAAoD;AACpD,EAAE;AACF,oGAAoG;AACpG,oDAAoD;AACpD,EAAE;AACF,8GAA8G;AAC9G,8GAA8G;AAC9G,8GAA8G;AAC9G,8GAA8G;AAC9G,8GAA8G;AAC9G,EAAE;AACF,mGAAmG;AACnG,qFAAqF;AACrF,qGAAqG;AACrG,mGAAmG;AACnG,mGAAmG;AACnG,oGAAoG;AACpG,8FAA8F;AAC9F,yCAAyC;AACzC,6FAA6F;;AAS7F,4BAYC;AAID,4BAGC;AAGD,8BAEC;AA/BD,qGAAqG;AACrG,uGAAuG;AACvG,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;AACtC,SAAS,gBAAgB,CAAC,MAAc;IACpC,OAAO,GAAG,GAAG,YAAY,MAAM,GAAG,GAAG,KAAK,CAAC;AAC/C,CAAC;AAED,SAAgB,QAAQ,CAAC,MAAc,EAAE,QAAgB;IACrD,MAAM,kBAAkB,GAAG;QACvB,aAAa,EAAE,YAAY;QAC3B,kBAAkB,EAAE,MAAM;QAC1B,wBAAwB,EAAE,MAAM;KACnC,CAAC;IACF,yFAAyF;IACzF,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,aAAa,EAAE,gBAAgB,CAAC,MAAM,CAAC,EAAE,kBAAkB,EAAE,CAAC,CAAC;IAC3F,CAAC;IACD,2FAA2F;IAC3F,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,kBAAkB,EAAE,CAAC,CAAC;AAClD,CAAC;AAED,oGAAoG;AACpG,kGAAkG;AAClG,SAAgB,QAAQ,CAAC,MAAc,EAAE,QAAgB;IACrD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC;IACxD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC;AAED,+FAA+F;AAC/F,SAAgB,SAAS;IACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC","sourcesContent":["// The single place that knows Claude Code's PreToolUse decision protocol, so every deny in the\n// Claude Code adapter is emitted identically — and identically to the checked-in shim\n// (.claude/webpieces/ai-hook.sh, rendered by renderShim() in ../bin/shim.ts), which emits the same JSON.\n//\n// A block is signalled by `permissionDecision: \"deny\"` JSON on STDOUT with exit 0 — NOT exit 2.\n// Claude Code only parses the JSON on exit 0; exit 2 would ignore stdout and the reason would not\n// surface in the terminal UI. \"deny\" still blocks the tool, so this remains fail-closed: it is not the\n// silent-allow a bare exit 0 with no JSON would be.\n//\n// WHY the tool-conditional `systemMessage` (verified by live tests against Claude Code v2.1.x — the\n// docs are wrong here; do NOT re-derive from them):\n//\n//   | deny field                        | Bash tool                         | Write/Edit/MultiEdit tool     |\n//   |-----------------------------------|-----------------------------------|-------------------------------|\n//   | permissionDecisionReason (plain)  | model sees it; USER SEES NOTHING  | model + RED \"Error:\" block ok |\n//   | systemMessage                     | ONLY user-visible field; grey     | grey extra line (redundant)   |\n//   | systemMessage wrapped in ANSI red | RED + visible to the user (fix)   | redundant 2nd red line        |\n//\n// So: on a **Bash** deny we ALSO emit a top-level `systemMessage` wrapped in ANSI red (ESC[31;1m …\n// ESC[0m) — it is the only field a Bash deny shows the human, and it honors ANSI. On\n// Write/Edit/MultiEdit we add NO `systemMessage` (the reason already renders red natively — a second\n// line is just noise). `permissionDecisionReason` is always plain text (never ANSI): it's what the\n// model reads and what Write/Edit renders red. JSON.stringify serializes the ESC char as the valid\n// \\u escape, so the payload stays valid JSON — we build the ESC via String.fromCharCode(0x1b) so no\n// raw ESC (0x1b) byte ever lives in this source file. Do NOT use exit 2 (stdout JSON ignored;\n// stderr invisible to the user on Bash).\n// Refs: Claude Code GitHub issues #31592, #40380, #17356 (asymmetry \"closed / not planned\").\n\n// ANSI escape (0x1b) built at runtime so no raw ESC byte sits in source. ANSI red is a *bonus* — the\n// 🛑 prefix + reason stay meaningful if a future/CI renderer strips the color. One place = one escape.\nconst ESC = String.fromCharCode(0x1b);\nfunction redSystemMessage(reason: string): string {\n    return `${ESC}[31;1m🛑 ${reason}${ESC}[0m`;\n}\n\nexport function denyJson(reason: string, toolName: string): string {\n    const hookSpecificOutput = {\n        hookEventName: 'PreToolUse',\n        permissionDecision: 'deny',\n        permissionDecisionReason: reason,\n    };\n    // Bash only: permissionDecisionReason is NOT user-visible, so add the red systemMessage.\n    if (toolName === 'Bash') {\n        return JSON.stringify({ systemMessage: redSystemMessage(reason), hookSpecificOutput });\n    }\n    // Write/Edit/MultiEdit (and anything else): reason renders red natively; no systemMessage.\n    return JSON.stringify({ hookSpecificOutput });\n}\n\n// Block the tool call and surface `reason` to both the user (terminal UI) and the model. `toolName`\n// selects whether the red `systemMessage` is added (Bash) or omitted (file tools) — see denyJson.\nexport function emitDeny(reason: string, toolName: string): never {\n    process.stdout.write(denyJson(reason, toolName) + '\\n');\n    process.exit(0);\n}\n\n// Allow the tool call. No JSON needed — a silent exit 0 is \"allow\" in the PreToolUse protocol.\nexport function emitAllow(): never {\n    process.exit(0);\n}\n"]}

package/src/adapters/hook-core.js

@@ -71,7 +71,9 @@ function handleBash(payload, cwd, mode) {
     if (!result) {
         (0, claude_code_response_1.emitAllow)();
     }
-    (0, claude_code_response_1.emitDeny)(result.report);
+    // Bash deny → pass 'Bash' so denyJson adds the ANSI-red systemMessage (the only field a Bash deny
+    // shows the human; permissionDecisionReason is invisible on Bash). See claude-code-response.ts.
+    (0, claude_code_response_1.emitDeny)(result.report, 'Bash');
 }
 function handleFileTool(payload, cwd, mode) {
     const toolKind = normalizeToolKind(payload.tool_name);
@@ -100,7 +102,9 @@ function handleFileTool(payload, cwd, mode) {
         (0, claude_code_response_1.emitAllow)();
     }
     (0, rejection_log_1.logRejection)(toolKind, input, result, cwd);
-    (0, claude_code_response_1.emitDeny)(result.report);
+    // File-tool deny → pass the Write/Edit/MultiEdit kind so denyJson omits systemMessage (the reason
+    // already renders red natively for these tools). See claude-code-response.ts.
+    (0, claude_code_response_1.emitDeny)(result.report, toolKind);
 }
 /**
  * Shared entry point for all three Claude Code PreToolUse adapters. `mode` selects which tool kinds
@@ -110,6 +114,10 @@ function handleFileTool(payload, cwd, mode) {
  * and the reason now surfaces in the Claude Code UI instead of being hidden on a stderr+exit-2 block.
  */
 async function runMain(mode) {
+    // Captured from the payload as soon as it parses so the fail-closed catch below can tell denyJson
+    // which tool it is denying — a crash on a Bash call still gets the visible red systemMessage, a
+    // crash on a file tool does not. Empty (before parse / malformed input) → treated as non-Bash.
+    let toolName = '';
     // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
     try {
         const raw = await readStdin();
@@ -117,6 +125,7 @@ async function runMain(mode) {
         if (!payload) {
             (0, claude_code_response_1.emitAllow)();
         }
+        toolName = payload.tool_name;
         // 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).
@@ -145,13 +154,13 @@ async function runMain(mode) {
         // 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);
+            (0, claude_code_response_1.emitDeny)(error.aiMessage, toolName);
         }
         else if (error instanceof types_1.InformAiError) {
-            (0, claude_code_response_1.emitDeny)(error.message);
+            (0, claude_code_response_1.emitDeny)(error.message, toolName);
         }
         else {
-            (0, claude_code_response_1.emitDeny)(`[ai-hooks] hook crashed unexpectedly — failing closed: ${error.message}`);
+            (0, claude_code_response_1.emitDeny)(`[ai-hooks] hook crashed unexpectedly — failing closed: ${error.message}`, toolName);
         }
     }
 }

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 } from '../core/runner';\nimport { logRejection } from '../core/rejection-log';\nimport { logGuardDecision, GuardDecision, branchForLog } from '../core/decision-log';\nimport { triggerMainSyncRefresh } from '../core/main-sync-refresh';\nimport { CONFIG_FILENAME } from '../core/load-config';\nimport { NormalizedToolInput, NormalizedEdit, ToolKind, InformAiError, RuleFailError, HookMode } from '../core/types';\nimport { toError } from '../core/to-error';\nimport { emitDeny, emitAllow } from './claude-code-response';\nimport { healShim } from '../bin/shim';\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. Matcher is Write|Edit|MultiEdit|Bash.\n//  - 'all'    → both categories, for the combined back-compat `wp-ai-hook` bin.\nexport type { HookMode };\n\nconst HANDLED_FILE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit']);\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}\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\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    emitDeny(result.report);\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            logGuardDecision(\n                cwd,\n                new GuardDecision('feature-branch-guard', toolKind, input.filePath, branchForLog(cwd), '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(cwd);\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    emitDeny(result.report);\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    // 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\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        // Keep the committed shim (.claude/webpieces/ai-hook.sh) identical to renderShim() so its\n        // fail-closed escape hatch + installer allowlist never go stale — no human hand-edits it.\n        // Runs only when the guards binary is actually installed (i.e. now), is best-effort, and\n        // never throws into the decision below. 'rules' hook skips it (guards owns the shim).\n        if (mode !== 'rules') healShim(cwd);\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);\n        } else if (error instanceof InformAiError) {\n            emitDeny(error.message);\n        } else {\n            emitDeny(`[ai-hooks] hook crashed unexpectedly — failing closed: ${error.message}`);\n        }\n    }\n}\n"]}
+{"version":3,"file":"hook-core.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/adapters/hook-core.ts"],"names":[],"mappings":";;AAgJA,0BA8CC;;AA9LD,mDAA6B;AAE7B,2CAA8C;AAC9C,yDAAqD;AACrD,uDAAqF;AACrF,iEAAmE;AACnE,qDAAsD;AACtD,yCAAsH;AACtH,+CAA2C;AAC3C,iEAA6D;AAC7D,sCAAuC;AAWvC,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;AAwBnE,SAAS,SAAS;IACd,OAAO,IAAI,OAAO,CAAC,CAAC,OAAgC,EAAE,EAAE;QACpD,IAAI,IAAI,GAAG,EAAE,CAAC;QACd,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAClC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,GAAG,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAChE,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAC7C,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;QAC7C,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK;YAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;AACP,CAAC;AAED,SAAS,SAAS,CAAC,GAAW;IAC1B,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC3C,8DAA8D;IAC9D,IAAI,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAsB,CAAC;IAChD,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,kBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,IAAI,qBAAa,CAAC,gDAAgD,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/G,CAAC;AACL,CAAC;AAED,SAAS,iBAAiB,CAAC,QAAgB;IACvC,IAAI,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAoB,CAAC;IAClE,OAAO,IAAI,CAAC;AAChB,CAAC;AAED,SAAS,kBAAkB,CAAC,QAAkB,EAAE,SAA8B;IAC1E,MAAM,QAAQ,GAAG,SAAS,CAAC,SAAS,CAAC;IACrC,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAE3B,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACvB,OAAO,IAAI,2BAAmB,CAAC,QAAQ,EAAE;YACrC,IAAI,sBAAc,CAAC,EAAE,EAAE,SAAS,CAAC,OAAO,IAAI,EAAE,CAAC;SAClD,CAAC,CAAC;IACP,CAAC;IACD,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,IAAI,2BAAmB,CAAC,QAAQ,EAAE;YACrC,IAAI,sBAAc,CAAC,SAAS,CAAC,UAAU,IAAI,EAAE,EAAE,SAAS,CAAC,UAAU,IAAI,EAAE,CAAC;SAC7E,CAAC,CAAC;IACP,CAAC;IACD,IAAI,QAAQ,KAAK,WAAW,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAsB,EAAE,EAAE,CAAC,IAAI,sBAAc,CAAC,CAAC,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,CAAC;QAC9G,OAAO,IAAI,2BAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC;AAED,SAAS,UAAU,CAAC,OAA0B,EAAE,GAAW,EAAE,IAAc;IACvE,MAAM,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC;IAC3C,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAAC,IAAA,gCAAS,GAAE,CAAC;IAAC,CAAC;IACvD,MAAM,MAAM,GAAG,IAAA,gBAAO,EAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;QAAC,IAAA,gCAAS,GAAE,CAAC;IAAC,CAAC;IAC7B,kGAAkG;IAClG,gGAAgG;IAChG,IAAA,+BAAQ,EAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACpC,CAAC;AAED,SAAS,cAAc,CAAC,OAA0B,EAAE,GAAW,EAAE,IAAc;IAC3E,MAAM,QAAQ,GAAG,iBAAiB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACtD,IAAI,CAAC,QAAQ,EAAE,CAAC;QAAC,IAAA,gCAAS,GAAE,CAAC;IAAC,CAAC;IAE/B,MAAM,KAAK,GAAG,kBAAkB,CAAC,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,IAAI,CAAC,KAAK,EAAE,CAAC;QAAC,IAAA,gCAAS,GAAE,CAAC;IAAC,CAAC;IAE5B,+FAA+F;IAC/F,gGAAgG;IAChG,gGAAgG;IAChG,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,6BAAe,EAAE,CAAC;QACpD,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;YACnB,IAAA,+BAAgB,EACZ,GAAG,EACH,IAAI,4BAAa,CAAC,sBAAsB,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,IAAA,2BAAY,EAAC,GAAG,CAAC,EAAE,OAAO,EAAE,8CAA8C,CAAC,CAClJ,CAAC;YACF,yFAAyF;YACzF,sFAAsF;YACtF,qEAAqE;YACrE,IAAA,0CAAsB,EAAC,GAAG,CAAC,CAAC;QAChC,CAAC;QACD,IAAA,gCAAS,GAAE,CAAC;IAChB,CAAC;IAED,MAAM,MAAM,GAAG,IAAA,YAAG,EAAC,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAC/C,IAAI,CAAC,MAAM,EAAE,CAAC;QAAC,IAAA,gCAAS,GAAE,CAAC;IAAC,CAAC;IAE7B,IAAA,4BAAY,EAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IAC3C,kGAAkG;IAClG,8EAA8E;IAC9E,IAAA,+BAAQ,EAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,OAAO,CAAC,IAAc;IACxC,kGAAkG;IAClG,gGAAgG;IAChG,+FAA+F;IAC/F,IAAI,QAAQ,GAAG,EAAE,CAAC;IAClB,8DAA8D;IAC9D,IAAI,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,SAAS,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC,OAAO,EAAE,CAAC;YAAC,IAAA,gCAAS,GAAE,CAAC;QAAC,CAAC;QAC9B,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC;QAE7B,sFAAsF;QACtF,yFAAyF;QACzF,uFAAuF;QACvF,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QAEzC,0FAA0F;QAC1F,0FAA0F;QAC1F,yFAAyF;QACzF,sFAAsF;QACtF,IAAI,IAAI,KAAK,OAAO;YAAE,IAAA,eAAQ,EAAC,GAAG,CAAC,CAAC;QAEpC,IAAI,OAAO,CAAC,SAAS,KAAK,MAAM,EAAE,CAAC;YAC/B,qEAAqE;YACrE,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;gBAAC,IAAA,gCAAS,GAAE,CAAC;YAAC,CAAC;YACtC,UAAU,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;YAC/B,OAAO;QACX,CAAC;QAED,+EAA+E;QAC/E,8EAA8E;QAC9E,cAAc,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,kBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,sFAAsF;QACtF,0FAA0F;QAC1F,mFAAmF;QACnF,IAAI,KAAK,YAAY,qBAAa,EAAE,CAAC;YACjC,IAAA,+BAAQ,EAAC,KAAK,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QACxC,CAAC;aAAM,IAAI,KAAK,YAAY,qBAAa,EAAE,CAAC;YACxC,IAAA,+BAAQ,EAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACtC,CAAC;aAAM,CAAC;YACJ,IAAA,+BAAQ,EAAC,0DAA0D,KAAK,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC;QAClG,CAAC;IACL,CAAC;AACL,CAAC","sourcesContent":["import * as path from 'path';\n\nimport { run, runBash } from '../core/runner';\nimport { logRejection } from '../core/rejection-log';\nimport { logGuardDecision, GuardDecision, branchForLog } from '../core/decision-log';\nimport { triggerMainSyncRefresh } from '../core/main-sync-refresh';\nimport { CONFIG_FILENAME } from '../core/load-config';\nimport { NormalizedToolInput, NormalizedEdit, ToolKind, InformAiError, RuleFailError, HookMode } from '../core/types';\nimport { toError } from '../core/to-error';\nimport { emitDeny, emitAllow } from './claude-code-response';\nimport { healShim } from '../bin/shim';\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. Matcher is Write|Edit|MultiEdit|Bash.\n//  - 'all'    → both categories, for the combined back-compat `wp-ai-hook` bin.\nexport type { HookMode };\n\nconst HANDLED_FILE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit']);\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}\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\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    // 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');\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            logGuardDecision(\n                cwd,\n                new GuardDecision('feature-branch-guard', toolKind, input.filePath, branchForLog(cwd), '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(cwd);\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);\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        // Keep the committed shim (.claude/webpieces/ai-hook.sh) identical to renderShim() so its\n        // fail-closed escape hatch + installer allowlist never go stale — no human hand-edits it.\n        // Runs only when the guards binary is actually installed (i.e. now), is best-effort, and\n        // never throws into the decision below. 'rules' hook skips it (guards owns the shim).\n        if (mode !== 'rules') healShim(cwd);\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);\n        } else if (error instanceof InformAiError) {\n            emitDeny(error.message, toolName);\n        } else {\n            emitDeny(`[ai-hooks] hook crashed unexpectedly — failing closed: ${error.message}`, toolName);\n        }\n    }\n}\n"]}

package/src/bin/shim.js

@@ -61,18 +61,31 @@ fi
 # in the PreToolUse protocol; the guards resume automatically once node_modules is present.
 PAYLOAD="$(cat)"
 CMD="$(printf '%s' "$PAYLOAD" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\\([^"\\\\]*\\)".*/\\1/p')"
+TOOL="$(printf '%s' "$PAYLOAD" | sed -n 's/.*"tool_name"[[:space:]]*:[[:space:]]*"\\([^"\\\\]*\\)".*/\\1/p')"
 if printf '%s' "$CMD" | grep -Eq '${exports.INSTALLER_ALLOW_ERE}'; then
   exit 0                     # allow the installer so the assistant can self-heal the deadlock
 fi
 # Not an installer command → FAIL CLOSED. Deny via Claude Code's PreToolUse JSON protocol
 # (permissionDecision "deny" on stdout, then exit 0) rather than a bare "exit 2". BOTH block the call,
-# but only the JSON's permissionDecisionReason is surfaced to the human in the terminal UI (and to the
-# model) — an exit-2 stderr message is NOT reliably shown on a blocked call, so the user would never
-# see the "run pnpm install" fix. This still fails closed: "deny" blocks the tool; it is not the silent
-# allow a plain exit 0 with no JSON would be. The reason is a single JSON string with no
-# double-quotes/backslashes, so it stays valid JSON after \${BIN_NAME} is substituted in.
+# but the reason must be made visible, and HOW depends on the tool (verified by live tests; the docs
+# are wrong here):
+#   - Bash deny:  permissionDecisionReason is NOT shown to the human — ONLY a top-level systemMessage
+#                 is, and it honors ANSI. So for Bash we emit systemMessage wrapped in ANSI red so the
+#                 "run pnpm install" fix is visible (today, on Bash, it is invisible).
+#   - Write/Edit/MultiEdit deny: permissionDecisionReason renders as a RED "Error:" block natively —
+#                 no systemMessage needed (a second line would be redundant).
+#   - NEVER exit 2 (stdout JSON ignored; stderr not reliably shown on a blocked Bash call).
+# The ESC is emitted as the literal 6-char JSON escape \\u001b (built via \${BS} so no raw ESC byte and
+# no \\uXXXX sits in this source); Claude Code's JSON parser turns \\u001b into ESC. The reason is a
+# single JSON string with no double-quotes/backslashes, so it stays valid JSON after \${BIN_NAME} subs.
 REASON="❌ @webpieces/ai-hook-rules is declared in package.json but is not installed (\${BIN_NAME} not found). Run 'pnpm install' (or this repo's installer) to enable the webpieces AI guards, then retry. (If you removed @webpieces/ai-hook-rules on purpose, delete its hooks from .claude/settings.json.)"
-printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\\n' "\$REASON"
+if [ "\$TOOL" = "Bash" ]; then
+  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"
+else
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\\n' "\$REASON"
+fi
 exit 0                       # decision is carried by permissionDecision "deny", not the exit code
 `;
 }

package/src/bin/shim.js.map

@@ -1 +1 @@
-{"version":3,"file":"shim.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/bin/shim.ts"],"names":[],"mappings":";;;AAgBA,4BAEC;AAoBD,gCAsCC;AAuBD,4BAcC;;AAjHD,+CAAyB;AACzB,mDAA6B;AAE7B,8EAA8E;AAC9E,qGAAqG;AACrG,oGAAoG;AACpG,mGAAmG;AACnG,mGAAmG;AACnG,8BAA8B;AAC9B,EAAE;AACF,6FAA6F;AAC7F,qGAAqG;AACrG,oFAAoF;AACpF,8EAA8E;AACjE,QAAA,WAAW,GAAG,8BAA8B,CAAC;AAE1D,SAAgB,QAAQ,CAAC,WAAmB;IACxC,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC;AACxE,CAAC;AAED,6FAA6F;AAC7F,qGAAqG;AACrG,uGAAuG;AACvG,EAAE;AACF,iGAAiG;AACjG,mGAAmG;AACnG,6FAA6F;AAChF,QAAA,mBAAmB,GAC5B,qEAAqE,CAAC;AAE1E,iGAAiG;AACjG,qGAAqG;AACrG,oGAAoG;AACvF,QAAA,kBAAkB,GAAG,mDAAmD,CAAC;AAEtF,oGAAoG;AACpG,kGAAkG;AAClG,wFAAwF;AACxF,SAAgB,UAAU;IACtB,OAAO;;;;;;;;;;;;;;;;;;;;;;;oCAuByB,2BAAmB;;;;;;;;;;;;;CAatD,CAAC;AACF,CAAC;AAED,gGAAgG;AAChG,iGAAiG;AACjG,mGAAmG;AACnG,sGAAsG;AACtG,uFAAuF;AACvF,SAAS,YAAY,CAAC,GAAW;IAC7B,IAAI,GAAG,GAAG,GAAG,CAAC;IACd,SAAS,CAAC;QACN,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM;QAC1B,GAAG,GAAG,MAAM,CAAC;IACjB,CAAC;IACD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;IAC9C,IAAI,GAAG,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAAE,OAAO,GAAG,CAAC;IACpD,OAAO,IAAI,CAAC;AAChB,CAAC;AAED,qGAAqG;AACrG,mGAAmG;AACnG,+EAA+E;AAC/E,SAAgB,QAAQ,CAAC,GAAW;IAChC,8DAA8D;IAC9D,IAAI,CAAC;QACD,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC,IAAI;YAAE,OAAO;QAClB,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;QAC7B,IAAI,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,OAAO;YAAE,OAAO;QACxD,EAAE,CAAC,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACnD,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAChC,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,6BAA6B;QAC7B,oEAAoE;IACxE,CAAC;AACL,CAAC","sourcesContent":["import * as fs from 'fs';\nimport * as path from 'path';\n\n// ---------------------------------------------------------------------------\n// The single checked-in shim (.claude/webpieces/ai-hook.sh). Both project hooks point at it, passing\n// their bin name as the first arg. settings.json points here (not at the bare bin) so a missing bin\n// (fresh clone, package removed) yields a friendly message instead of the raw `sh: No such file or\n// directory` on every Write/Edit/Bash tool call. `.claude` is committed, so the shim survives even\n// when node_modules does not.\n//\n// This module is the SINGLE SOURCE OF TRUTH for the shim body + the installer allowlist. The\n// installer (setup.ts) renders it on install; the running guards binary re-renders and self-heals it\n// (healShim) so the committed .sh can never go stale — no human ever hand-edits it.\n// ---------------------------------------------------------------------------\nexport const SHIM_MARKER = '.claude/webpieces/ai-hook.sh';\n\nexport function shimPath(projectRoot: string): string {\n    return path.join(projectRoot, '.claude', 'webpieces', 'ai-hook.sh');\n}\n\n// Package-manager install commands allowed to pass the fail-closed shim so the assistant can\n// self-heal the guards (run `pnpm install`) when node_modules is absent — otherwise the guard blocks\n// the very command that re-enables it (deadlock). nx/pnpm monorepo only. POSIX ERE (fed to `grep -E`).\n//\n// Base command + `--flags` only. Because nothing but `--word` tokens may follow `install`, shell\n// operators (`;`, `&&`, `|`, backticks, `$()`, `>`, `<`) cannot match — so nothing can be smuggled\n// alongside the install. Keep in sync with INSTALLER_ALLOW_JS below (locked by a unit test).\nexport const INSTALLER_ALLOW_ERE =\n    '^(pnpm|npm) install([[:space:]]+--[A-Za-z][A-Za-z-]*)*[[:space:]]*$';\n\n// JS-regex twin of INSTALLER_ALLOW_ERE (POSIX `[[:space:]]` → `\\s`). Not used by the fail-closed\n// shim (which is pure sh), but kept as the single JS-side definition should a future guard ever need\n// to recognise installer commands in the runner. A unit test asserts the two agree on a sample set.\nexport const INSTALLER_ALLOW_JS = /^(pnpm|npm) install(\\s+--[A-Za-z][A-Za-z-]*)*\\s*$/;\n\n// Normal template literal (not String.raw): it carries #235's shell escapes verbatim (\\${BIN_NAME},\n// \\$REASON, \\\\n for the deny JSON) AND my sed backslashes (doubled: \\\\(, \\\\), \\\\1, [^\"\\\\\\\\]). The\n// grep pattern is interpolated from INSTALLER_ALLOW_ERE (its value has no backslashes).\nexport function renderShim(): string {\n    return `#!/bin/sh\n# Managed by @webpieces/ai-hook-rules (wp-setup-ai-hooks) — do not edit; the installer AND the running\n# guards binary both overwrite this file (self-healing) from renderShim(). Checked in on purpose so the\n# hook has a stable, committed entry point even when node_modules is absent. Safe to delete along with\n# the matching .claude/settings.json entries if you remove @webpieces/ai-hook-rules.\n#\n# Usage (wired into .claude/settings.json): sh \"$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh\" <bin-name>\nBIN_NAME=\"$1\"\nshift\n# Resolve the bin relative to THIS script (…/<root>/.claude/webpieces/ai-hook.sh → <root>), not the\n# caller's cwd — the hook can be invoked from any directory (a subdir, or a nested clone).\nROOT=\"$(CDPATH= cd -- \"$(dirname -- \"$0\")/../..\" && pwd)\"\nBIN=\"$ROOT/node_modules/.bin/$BIN_NAME\"\nif [ -x \"$BIN\" ]; then\n  exec \"$BIN\" \"$@\"          # exec preserves stdin — hooks receive the tool payload as JSON on stdin\nfi\n# Bin missing (fresh clone before install, or a broken install). The webpieces guards CANNOT run.\n# Before failing closed, peek at the tool payload and let ONLY package-manager install commands\n# through: the assistant's own Bash tool routes through this hook too, so blocking everything would\n# deadlock the one command (pnpm/npm install) that re-enables the guards. A silent exit 0 = \"allow\"\n# in the PreToolUse protocol; the guards resume automatically once node_modules is present.\nPAYLOAD=\"$(cat)\"\nCMD=\"$(printf '%s' \"$PAYLOAD\" | sed -n 's/.*\"command\"[[:space:]]*:[[:space:]]*\"\\\\([^\"\\\\\\\\]*\\\\)\".*/\\\\1/p')\"\nif printf '%s' \"$CMD\" | grep -Eq '${INSTALLER_ALLOW_ERE}'; then\n  exit 0                     # allow the installer so the assistant can self-heal the deadlock\nfi\n# Not an installer command → FAIL CLOSED. Deny via Claude Code's PreToolUse JSON protocol\n# (permissionDecision \"deny\" on stdout, then exit 0) rather than a bare \"exit 2\". BOTH block the call,\n# but only the JSON's permissionDecisionReason is surfaced to the human in the terminal UI (and to the\n# model) — an exit-2 stderr message is NOT reliably shown on a blocked call, so the user would never\n# see the \"run pnpm install\" fix. This still fails closed: \"deny\" blocks the tool; it is not the silent\n# allow a plain exit 0 with no JSON would be. The reason is a single JSON string with no\n# double-quotes/backslashes, so it stays valid JSON after \\${BIN_NAME} is substituted in.\nREASON=\"❌ @webpieces/ai-hook-rules is declared in package.json but is not installed (\\${BIN_NAME} not found). Run 'pnpm install' (or this repo's installer) to enable the webpieces AI guards, then retry. (If you removed @webpieces/ai-hook-rules on purpose, delete its hooks from .claude/settings.json.)\"\nprintf '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"%s\"}}\\\\n' \"\\$REASON\"\nexit 0                       # decision is carried by permissionDecision \"deny\", not the exit code\n`;\n}\n\n// Find the repo root that owns the committed shim to heal: walk up from `cwd` (the invocation's\n// actual dir) to the nearest ancestor holding a shim, falling back to $CLAUDE_PROJECT_DIR (which\n// Claude Code exports to hooks) only if the walk finds nothing. cwd-first keeps this correct for a\n// nested clone and testable (a temp root is honoured over the ambient project env). Returns null when\n// no committed shim exists (e.g. a global / absolute install, which has none to heal).\nfunction findShimRoot(cwd: string): string | null {\n    let dir = cwd;\n    for (;;) {\n        if (fs.existsSync(shimPath(dir))) return dir;\n        const parent = path.dirname(dir);\n        if (parent === dir) break;\n        dir = parent;\n    }\n    const env = process.env['CLAUDE_PROJECT_DIR'];\n    if (env && fs.existsSync(shimPath(env))) return env;\n    return null;\n}\n\n// Best-effort: keep the committed shim identical to renderShim() so the fail-closed escape hatch and\n// allowlist never drift. Only rewrites an EXISTING shim (never creates one) so global installs are\n// untouched. NEVER throws — a self-heal must never block or crash a tool call.\nexport function healShim(cwd: string): void {\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const root = findShimRoot(cwd);\n        if (!root) return;\n        const target = shimPath(root);\n        const desired = renderShim();\n        if (fs.readFileSync(target, 'utf8') === desired) return;\n        fs.writeFileSync(target, desired, { mode: 0o755 });\n        fs.chmodSync(target, 0o755);\n    } catch (err: unknown) {\n        //const error = toError(err);\n        // Ignore: healing is a convenience, not part of the guard decision.\n    }\n}\n"]}
+{"version":3,"file":"shim.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/bin/shim.ts"],"names":[],"mappings":";;;AAgBA,4BAEC;AAoBD,gCAmDC;AAuBD,4BAcC;;AA9HD,+CAAyB;AACzB,mDAA6B;AAE7B,8EAA8E;AAC9E,qGAAqG;AACrG,oGAAoG;AACpG,mGAAmG;AACnG,mGAAmG;AACnG,8BAA8B;AAC9B,EAAE;AACF,6FAA6F;AAC7F,qGAAqG;AACrG,oFAAoF;AACpF,8EAA8E;AACjE,QAAA,WAAW,GAAG,8BAA8B,CAAC;AAE1D,SAAgB,QAAQ,CAAC,WAAmB;IACxC,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC;AACxE,CAAC;AAED,6FAA6F;AAC7F,qGAAqG;AACrG,uGAAuG;AACvG,EAAE;AACF,iGAAiG;AACjG,mGAAmG;AACnG,6FAA6F;AAChF,QAAA,mBAAmB,GAC5B,qEAAqE,CAAC;AAE1E,iGAAiG;AACjG,qGAAqG;AACrG,oGAAoG;AACvF,QAAA,kBAAkB,GAAG,mDAAmD,CAAC;AAEtF,oGAAoG;AACpG,kGAAkG;AAClG,wFAAwF;AACxF,SAAgB,UAAU;IACtB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;oCAwByB,2BAAmB;;;;;;;;;;;;;;;;;;;;;;;;;CAyBtD,CAAC;AACF,CAAC;AAED,gGAAgG;AAChG,iGAAiG;AACjG,mGAAmG;AACnG,sGAAsG;AACtG,uFAAuF;AACvF,SAAS,YAAY,CAAC,GAAW;IAC7B,IAAI,GAAG,GAAG,GAAG,CAAC;IACd,SAAS,CAAC;QACN,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM;QAC1B,GAAG,GAAG,MAAM,CAAC;IACjB,CAAC;IACD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;IAC9C,IAAI,GAAG,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAAE,OAAO,GAAG,CAAC;IACpD,OAAO,IAAI,CAAC;AAChB,CAAC;AAED,qGAAqG;AACrG,mGAAmG;AACnG,+EAA+E;AAC/E,SAAgB,QAAQ,CAAC,GAAW;IAChC,8DAA8D;IAC9D,IAAI,CAAC;QACD,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC,IAAI;YAAE,OAAO;QAClB,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;QAC7B,IAAI,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,OAAO;YAAE,OAAO;QACxD,EAAE,CAAC,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACnD,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAChC,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,6BAA6B;QAC7B,oEAAoE;IACxE,CAAC;AACL,CAAC","sourcesContent":["import * as fs from 'fs';\nimport * as path from 'path';\n\n// ---------------------------------------------------------------------------\n// The single checked-in shim (.claude/webpieces/ai-hook.sh). Both project hooks point at it, passing\n// their bin name as the first arg. settings.json points here (not at the bare bin) so a missing bin\n// (fresh clone, package removed) yields a friendly message instead of the raw `sh: No such file or\n// directory` on every Write/Edit/Bash tool call. `.claude` is committed, so the shim survives even\n// when node_modules does not.\n//\n// This module is the SINGLE SOURCE OF TRUTH for the shim body + the installer allowlist. The\n// installer (setup.ts) renders it on install; the running guards binary re-renders and self-heals it\n// (healShim) so the committed .sh can never go stale — no human ever hand-edits it.\n// ---------------------------------------------------------------------------\nexport const SHIM_MARKER = '.claude/webpieces/ai-hook.sh';\n\nexport function shimPath(projectRoot: string): string {\n    return path.join(projectRoot, '.claude', 'webpieces', 'ai-hook.sh');\n}\n\n// Package-manager install commands allowed to pass the fail-closed shim so the assistant can\n// self-heal the guards (run `pnpm install`) when node_modules is absent — otherwise the guard blocks\n// the very command that re-enables it (deadlock). nx/pnpm monorepo only. POSIX ERE (fed to `grep -E`).\n//\n// Base command + `--flags` only. Because nothing but `--word` tokens may follow `install`, shell\n// operators (`;`, `&&`, `|`, backticks, `$()`, `>`, `<`) cannot match — so nothing can be smuggled\n// alongside the install. Keep in sync with INSTALLER_ALLOW_JS below (locked by a unit test).\nexport const INSTALLER_ALLOW_ERE =\n    '^(pnpm|npm) install([[:space:]]+--[A-Za-z][A-Za-z-]*)*[[:space:]]*$';\n\n// JS-regex twin of INSTALLER_ALLOW_ERE (POSIX `[[:space:]]` → `\\s`). Not used by the fail-closed\n// shim (which is pure sh), but kept as the single JS-side definition should a future guard ever need\n// to recognise installer commands in the runner. A unit test asserts the two agree on a sample set.\nexport const INSTALLER_ALLOW_JS = /^(pnpm|npm) install(\\s+--[A-Za-z][A-Za-z-]*)*\\s*$/;\n\n// Normal template literal (not String.raw): it carries #235's shell escapes verbatim (\\${BIN_NAME},\n// \\$REASON, \\\\n for the deny JSON) AND my sed backslashes (doubled: \\\\(, \\\\), \\\\1, [^\"\\\\\\\\]). The\n// grep pattern is interpolated from INSTALLER_ALLOW_ERE (its value has no backslashes).\nexport function renderShim(): string {\n    return `#!/bin/sh\n# Managed by @webpieces/ai-hook-rules (wp-setup-ai-hooks) — do not edit; the installer AND the running\n# guards binary both overwrite this file (self-healing) from renderShim(). Checked in on purpose so the\n# hook has a stable, committed entry point even when node_modules is absent. Safe to delete along with\n# the matching .claude/settings.json entries if you remove @webpieces/ai-hook-rules.\n#\n# Usage (wired into .claude/settings.json): sh \"$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh\" <bin-name>\nBIN_NAME=\"$1\"\nshift\n# Resolve the bin relative to THIS script (…/<root>/.claude/webpieces/ai-hook.sh → <root>), not the\n# caller's cwd — the hook can be invoked from any directory (a subdir, or a nested clone).\nROOT=\"$(CDPATH= cd -- \"$(dirname -- \"$0\")/../..\" && pwd)\"\nBIN=\"$ROOT/node_modules/.bin/$BIN_NAME\"\nif [ -x \"$BIN\" ]; then\n  exec \"$BIN\" \"$@\"          # exec preserves stdin — hooks receive the tool payload as JSON on stdin\nfi\n# Bin missing (fresh clone before install, or a broken install). The webpieces guards CANNOT run.\n# Before failing closed, peek at the tool payload and let ONLY package-manager install commands\n# through: the assistant's own Bash tool routes through this hook too, so blocking everything would\n# deadlock the one command (pnpm/npm install) that re-enables the guards. A silent exit 0 = \"allow\"\n# in the PreToolUse protocol; the guards resume automatically once node_modules is present.\nPAYLOAD=\"$(cat)\"\nCMD=\"$(printf '%s' \"$PAYLOAD\" | sed -n 's/.*\"command\"[[:space:]]*:[[:space:]]*\"\\\\([^\"\\\\\\\\]*\\\\)\".*/\\\\1/p')\"\nTOOL=\"$(printf '%s' \"$PAYLOAD\" | sed -n 's/.*\"tool_name\"[[:space:]]*:[[:space:]]*\"\\\\([^\"\\\\\\\\]*\\\\)\".*/\\\\1/p')\"\nif printf '%s' \"$CMD\" | grep -Eq '${INSTALLER_ALLOW_ERE}'; then\n  exit 0                     # allow the installer so the assistant can self-heal the deadlock\nfi\n# Not an installer command → FAIL CLOSED. Deny via Claude Code's PreToolUse JSON protocol\n# (permissionDecision \"deny\" on stdout, then exit 0) rather than a bare \"exit 2\". BOTH block the call,\n# but the reason must be made visible, and HOW depends on the tool (verified by live tests; the docs\n# are wrong here):\n#   - Bash deny:  permissionDecisionReason is NOT shown to the human — ONLY a top-level systemMessage\n#                 is, and it honors ANSI. So for Bash we emit systemMessage wrapped in ANSI red so the\n#                 \"run pnpm install\" fix is visible (today, on Bash, it is invisible).\n#   - Write/Edit/MultiEdit deny: permissionDecisionReason renders as a RED \"Error:\" block natively —\n#                 no systemMessage needed (a second line would be redundant).\n#   - NEVER exit 2 (stdout JSON ignored; stderr not reliably shown on a blocked Bash call).\n# The ESC is emitted as the literal 6-char JSON escape \\\\u001b (built via \\${BS} so no raw ESC byte and\n# no \\\\uXXXX sits in this source); Claude Code's JSON parser turns \\\\u001b into ESC. The reason is a\n# single JSON string with no double-quotes/backslashes, so it stays valid JSON after \\${BIN_NAME} subs.\nREASON=\"❌ @webpieces/ai-hook-rules is declared in package.json but is not installed (\\${BIN_NAME} not found). Run 'pnpm install' (or this repo's installer) to enable the webpieces AI guards, then retry. (If you removed @webpieces/ai-hook-rules on purpose, delete its hooks from .claude/settings.json.)\"\nif [ \"\\$TOOL\" = \"Bash\" ]; then\n  BS='\\\\'                     # one literal backslash, so the \\\\u001b escape never sits in this source\n  ESC=\"\\${BS}u001b\"          # the 6 chars: backslash u 0 0 1 b — Claude Code parses \\\\u001b → ESC\n  printf '{\"systemMessage\":\"%s🛑 %s%s\",\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"%s\"}}\\\\n' \"\\${ESC}[31;1m\" \"\\$REASON\" \"\\${ESC}[0m\" \"\\$REASON\"\nelse\n  printf '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"%s\"}}\\\\n' \"\\$REASON\"\nfi\nexit 0                       # decision is carried by permissionDecision \"deny\", not the exit code\n`;\n}\n\n// Find the repo root that owns the committed shim to heal: walk up from `cwd` (the invocation's\n// actual dir) to the nearest ancestor holding a shim, falling back to $CLAUDE_PROJECT_DIR (which\n// Claude Code exports to hooks) only if the walk finds nothing. cwd-first keeps this correct for a\n// nested clone and testable (a temp root is honoured over the ambient project env). Returns null when\n// no committed shim exists (e.g. a global / absolute install, which has none to heal).\nfunction findShimRoot(cwd: string): string | null {\n    let dir = cwd;\n    for (;;) {\n        if (fs.existsSync(shimPath(dir))) return dir;\n        const parent = path.dirname(dir);\n        if (parent === dir) break;\n        dir = parent;\n    }\n    const env = process.env['CLAUDE_PROJECT_DIR'];\n    if (env && fs.existsSync(shimPath(env))) return env;\n    return null;\n}\n\n// Best-effort: keep the committed shim identical to renderShim() so the fail-closed escape hatch and\n// allowlist never drift. Only rewrites an EXISTING shim (never creates one) so global installs are\n// untouched. NEVER throws — a self-heal must never block or crash a tool call.\nexport function healShim(cwd: string): void {\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const root = findShimRoot(cwd);\n        if (!root) return;\n        const target = shimPath(root);\n        const desired = renderShim();\n        if (fs.readFileSync(target, 'utf8') === desired) return;\n        fs.writeFileSync(target, desired, { mode: 0o755 });\n        fs.chmodSync(target, 0o755);\n    } catch (err: unknown) {\n        //const error = toError(err);\n        // Ignore: healing is a convenience, not part of the guard decision.\n    }\n}\n"]}

package/templates/ai-hook.sh

@@ -21,16 +21,29 @@ fi
 # in the PreToolUse protocol; the guards resume automatically once node_modules is present.
 PAYLOAD="$(cat)"
 CMD="$(printf '%s' "$PAYLOAD" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"\\]*\)".*/\1/p')"
+TOOL="$(printf '%s' "$PAYLOAD" | sed -n 's/.*"tool_name"[[:space:]]*:[[:space:]]*"\([^"\\]*\)".*/\1/p')"
 if printf '%s' "$CMD" | grep -Eq '^(pnpm|npm) install([[:space:]]+--[A-Za-z][A-Za-z-]*)*[[:space:]]*$'; then
   exit 0                     # allow the installer so the assistant can self-heal the deadlock
 fi
 # Not an installer command → FAIL CLOSED. Deny via Claude Code's PreToolUse JSON protocol
 # (permissionDecision "deny" on stdout, then exit 0) rather than a bare "exit 2". BOTH block the call,
-# but only the JSON's permissionDecisionReason is surfaced to the human in the terminal UI (and to the
-# model) — an exit-2 stderr message is NOT reliably shown on a blocked call, so the user would never
-# see the "run pnpm install" fix. This still fails closed: "deny" blocks the tool; it is not the silent
-# allow a plain exit 0 with no JSON would be. The reason is a single JSON string with no
-# double-quotes/backslashes, so it stays valid JSON after ${BIN_NAME} is substituted in.
+# but the reason must be made visible, and HOW depends on the tool (verified by live tests; the docs
+# are wrong here):
+#   - Bash deny:  permissionDecisionReason is NOT shown to the human — ONLY a top-level systemMessage
+#                 is, and it honors ANSI. So for Bash we emit systemMessage wrapped in ANSI red so the
+#                 "run pnpm install" fix is visible (today, on Bash, it is invisible).
+#   - Write/Edit/MultiEdit deny: permissionDecisionReason renders as a RED "Error:" block natively —
+#                 no systemMessage needed (a second line would be redundant).
+#   - NEVER exit 2 (stdout JSON ignored; stderr not reliably shown on a blocked Bash call).
+# The ESC is emitted as the literal 6-char JSON escape \u001b (built via ${BS} so no raw ESC byte and
+# no \uXXXX sits in this source); Claude Code's JSON parser turns \u001b into ESC. The reason is a
+# single JSON string with no double-quotes/backslashes, so it stays valid JSON after ${BIN_NAME} subs.
 REASON="❌ @webpieces/ai-hook-rules is declared in package.json but is not installed (${BIN_NAME} not found). Run 'pnpm install' (or this repo's installer) to enable the webpieces AI guards, then retry. (If you removed @webpieces/ai-hook-rules on purpose, delete its hooks from .claude/settings.json.)"
-printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\n' "$REASON"
+if [ "$TOOL" = "Bash" ]; then
+  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"
+else
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\n' "$REASON"
+fi
 exit 0                       # decision is carried by permissionDecision "deny", not the exit code