@haposoft/cafekit 0.16.0 → 0.16.1

package/src/claude/hooks/completion-authority.cjs

@@ -3,6 +3,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
 let STATE;
 let evaluateCloseout;
 
@@ -27,7 +28,7 @@ function projectRoot(payload = {}) {
   }
 
   const installedRoot = path.resolve(__dirname, '..', '..');
-  const installedHook = path.join(installedRoot, '.claude', 'hooks', path.basename(__filename));
+  const installedHook = runtimePath(installedRoot, 'hooks', path.basename(__filename));
   if (fs.existsSync(installedHook)) return installedRoot;
 
   const sourceFixture = typeof process.env.PROJECT_ROOT === 'string'
@@ -50,7 +51,7 @@ function sessionId(payload) {
 
 function readRuntime(root) {
   try {
-    const file = path.join(root, '.claude', 'runtime.json');
+    const file = runtimePath(root, 'runtime.json');
     return fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : {};
   } catch { return {}; }
 }
@@ -135,9 +136,14 @@ function stop(payload) {
 
 let mode = process.argv[2] || null;
 try {
-  const payload = readPayload();
+  const raw = readPayload();
+  // Read the loop guard before normalization: the catch below answers a block, so a
+  // reader failure must not be able to reach it. Both spellings are accepted here.
+  const hostLoop = raw.stop_hook_active === true || raw.stopHookActive === true;
+  const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
+  const payload = normalizeHookPayload(raw);
   mode = mode || (payload.hook_event_name === 'UserPromptSubmit' ? '--approve' : '--stop');
-  if (mode === '--stop' && payload.stop_hook_active === true) {
+  if (mode === '--stop' && hostLoop) {
     // Host loop prevention is always silent, including when dependencies are unavailable.
   } else {
     const dependencyError = loadAuthority();

package/src/claude/hooks/docs-sync.cjs

@@ -19,7 +19,8 @@ try {
 
   // Đọc stdin theo chuẩn hook
   const stdin = fs.readFileSync(0, 'utf8').trim();
-  const payload = stdin ? JSON.parse(stdin) : {};
+  const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
+  const payload = stdin ? normalizeHookPayload(JSON.parse(stdin)) : {};
   const cwd = payload.cwd || process.cwd();
   const config = loadConfig({ cwd, includeProject: false, includeAssertions: false, includeLocale: false });
 

package/src/claude/hooks/inspect-block.cjs

@@ -8,7 +8,7 @@
  * Blocks access to heavy directories that would flood the LLM context window.
  * Also warns on overly-broad glob patterns.
  *
- * Disable: set "inspect": { "enabled": false } in .claude/runtime.json
+ * Disable: set "inspect": { "enabled": false } in <runtime>/runtime.json
  *
  * Exit: 0 = allow, 2 = block
  */
@@ -60,19 +60,41 @@ try {
     return out.filter(Boolean);
   }
 
+  const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
   function readRuntime(cwd) {
     try {
-      const p = path.join(cwd, '.claude', 'runtime.json');
+      const p = runtimePath(cwd, 'runtime.json');
       return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf8')) : {};
     } catch { return {}; }
   }
 
   // ── Main ──────────────────────────────────────────────────────────────────
 
+/**
+ * Deny the call with a reason every host can read.
+ *
+ * The reason is the JSON `permissionDecisionReason`, which Claude Code reads natively and
+ * grok honours "regardless of exit code"; the same text also goes to stderr, because on
+ * an exit-2 denial that is the channel Claude Code feeds back, and grok reads only the
+ * first stderr line. Exit 2 stays so a host that reads neither still blocks.
+ */
+function denyWithReason(reason) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason
+    }
+  }) + '\n');
+  process.stderr.write(reason + '\n');
+  process.exit(2);
+}
+
   const stdin   = fs.readFileSync(0, 'utf8').trim();
   if (!stdin) process.exit(0);
 
-  const data      = JSON.parse(stdin);
+  const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
+  const data      = normalizeHookPayload(JSON.parse(stdin));
   const toolName  = data.tool_name  || '';
   const toolInput = data.tool_input || {};
   const cwd       = data.cwd        || process.cwd();
@@ -88,12 +110,11 @@ try {
 
   // Broad glob check
   if (toolInput.pattern && isBroadGlob(toolInput.pattern)) {
-    console.log(
+    denyWithReason(
       `SCOPE LIMIT EXCEEDED: Glob pattern is excessively broad\n` +
       `Requested Pattern: ${toolInput.pattern}\n\n` +
       `Please narrow your scope (e.g., src/**/*.ts rather than **/*.ts).`
     );
-    process.exit(2);
   }
 
   // Blocked directory check
@@ -101,12 +122,11 @@ try {
   for (const p of paths) {
     if (isBlockedPath(p)) {
       const blocked = p.replace(/\\/g, '/').split('/').find(s => BLOCKED_DIRS.includes(s));
-      console.log(
+      denyWithReason(
         `SCOPE LIMIT EXCEEDED: Directory "${blocked}/" is explicitly forbidden\n` +
         `Requested Path: ${p}\n` +
         `Restricted zones: ${BLOCKED_DIRS.join(', ')}`
       );
-      process.exit(2);
     }
   }
 

package/src/claude/hooks/lib/config.cjs

@@ -9,7 +9,10 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
-const RUNTIME_CONFIG_PATH = '.claude/runtime.json';
+const { runtimeDirName } = require('./runtime-dir.cjs');
+
+// Derived from this library's own location so an install under .omp/ or .codex/ reads its own file.
+const RUNTIME_CONFIG_PATH = `${runtimeDirName()}/runtime.json`;
 
 const CONFIG_PATH = RUNTIME_CONFIG_PATH;
 
@@ -461,7 +464,7 @@ function sanitizeConfig(config, projectRoot) {
  *
  * Resolution order (each layer overrides the previous):
  *   1. DEFAULT_CONFIG (hardcoded defaults)
- *   2. Runtime config (./.claude/runtime.json) - installed CafeKit runtime config
+ *   2. Runtime config (<runtime-dir>/runtime.json, derived by lib/runtime-dir.cjs) - installed CafeKit runtime config
  *
  * @param {Object} options - Options for config loading
  * @param {boolean} options.includeProject - Include project section (default: true)

package/src/claude/hooks/lib/counter.cjs

@@ -6,6 +6,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { runtimeDir } = require('./runtime-dir.cjs');
 
 function getMcpServerNames(filePath) {
   if (!fs.existsSync(filePath)) return new Set();
@@ -83,16 +84,17 @@ function countConfigs(cwd) {
 
   // Project scope
   if (cwd) {
+    const projectRuntime = runtimeDir(cwd);
     if (fs.existsSync(path.join(cwd, 'CLAUDE.md'))) claudeMdCount++;
     if (fs.existsSync(path.join(cwd, 'CLAUDE.local.md'))) claudeMdCount++;
-    if (fs.existsSync(path.join(cwd, '.claude', 'CLAUDE.md'))) claudeMdCount++;
-    if (fs.existsSync(path.join(cwd, '.claude', 'CLAUDE.local.md'))) claudeMdCount++;
-    rulesCount += countRulesInDir(path.join(cwd, '.claude', 'rules'));
+    if (fs.existsSync(path.join(projectRuntime, 'CLAUDE.md'))) claudeMdCount++;
+    if (fs.existsSync(path.join(projectRuntime, 'CLAUDE.local.md'))) claudeMdCount++;
+    rulesCount += countRulesInDir(path.join(projectRuntime, 'rules'));
     mcpCount += countMcpServersInFile(path.join(cwd, '.mcp.json'));
-    const projectSettings = path.join(cwd, '.claude', 'settings.json');
+    const projectSettings = path.join(projectRuntime, 'settings.json');
     mcpCount += countMcpServersInFile(projectSettings);
     hooksCount += countHooksInFile(projectSettings);
-    const localSettings = path.join(cwd, '.claude', 'settings.local.json');
+    const localSettings = path.join(projectRuntime, 'settings.local.json');
     mcpCount += countMcpServersInFile(localSettings);
     hooksCount += countHooksInFile(localSettings);
   }

package/src/claude/hooks/lib/hook-payload.cjs

@@ -0,0 +1,160 @@
+/**
+ * Copyright (c) 2026 Haposoft. MIT License.
+ *
+ * Hook payload normalization.
+ *
+ * The gate hooks were written against Claude Code's stdin envelope: snake_case keys and
+ * capitalised tool names. Two other hosts run the very same scripts with a different
+ * spelling. Grok CLI loads `.claude/settings.json` through its Claude-compatibility layer
+ * but sends camelCase keys (`toolName`, `stopHookActive`) and its own tool names
+ * (`run_terminal_command`, `read_file`, `search_replace`). Oh My Pi's bridge sends
+ * Claude-shaped keys with lowercase tool names (`bash`, `read`).
+ *
+ * A hook that reads `data.tool_name` on a grok payload gets `undefined`, extracts no
+ * paths, and allows the call: the gate looks installed and is open. This module is the
+ * one place that reconciles those spellings, so every hook keeps a single code path.
+ *
+ * Two rules earn their keep:
+ *
+ *   1. The tool name is aliased by VALUE, under any key. omp already sends `tool_name`,
+ *      so a key-only translation would silently skip its lowercase names.
+ *   2. Every name that can reach a `Bash` matcher must map to `Bash`. Grok expands
+ *      matchers by alias, so a shell call can arrive under a name the hook does not
+ *      recognise; an unmapped name skips the command scan and a secret-bearing command
+ *      is never examined.
+ *
+ * The reader is total: it never throws. Callers include two fail-closed hooks whose final
+ * catch emits a block, so an exception here would block the Stop gate on Claude too.
+ */
+
+'use strict';
+
+/** Grok's event values are snake_case; the hooks compare against Claude's PascalCase. */
+const EVENT_NAMES = Object.freeze({
+  pre_tool_use: 'PreToolUse',
+  post_tool_use: 'PostToolUse',
+  post_tool_use_failure: 'PostToolUseFailure',
+  permission_denied: 'PermissionDenied',
+  user_prompt_submit: 'UserPromptSubmit',
+  session_start: 'SessionStart',
+  session_end: 'SessionEnd',
+  stop: 'Stop',
+  stop_failure: 'StopFailure',
+  stop_cancelled: 'StopCancelled',
+  subagent_start: 'SubagentStart',
+  subagent_stop: 'SubagentStop',
+  pre_compact: 'PreCompact',
+  post_compact: 'PostCompact',
+  notification: 'Notification',
+});
+
+/**
+ * Foreign tool names to the Claude names the rules were authored against.
+ *
+ * Grok's registry and matcher aliases come first, then omp's lowercase registry. Where
+ * both hosts use a spelling (`write`, `grep`) they agree on the destination. `write` is
+ * grok's file-creating tool and maps to `Write`, while `search_replace` edits an existing
+ * file and maps to `Edit`; conflating them would make the scaffold guard reject ordinary
+ * edits. `delete_file` maps to `Write` so a delete is gated like any other file write.
+ */
+const TOOL_ALIASES = Object.freeze({
+  // grok — every spelling that reaches a Bash matcher
+  run_terminal_command: 'Bash',
+  run_terminal_cmd: 'Bash',
+  PowerShell: 'Bash',
+  // grok — file and search tools
+  read_file: 'Read',
+  hashline_read: 'Read',
+  search_replace: 'Edit',
+  hashline_edit: 'Edit',
+  write: 'Write',
+  delete_file: 'Write',
+  grep: 'Grep',
+  grep_search: 'Grep',
+  hashline_grep: 'Grep',
+  list_dir: 'Glob',
+  web_search: 'WebSearch',
+  web_fetch: 'WebFetch',
+  spawn_subagent: 'Task',
+  todo_write: 'TodoWrite',
+  // omp — lowercase registry
+  bash: 'Bash',
+  read: 'Read',
+  edit: 'Edit',
+  glob: 'Glob',
+  find: 'Glob',
+  ls: 'Glob',
+  webfetch: 'WebFetch',
+  websearch: 'WebSearch',
+});
+
+/**
+ * Camel-cased foreign key to the snake_case key the hooks read.
+ *
+ * `transcriptPath` is deliberately absent: grok stores sessions in its own format, and
+ * mapping it would make `state.cjs` stream a file it cannot parse. The last three pairs
+ * cover fields whose grok spelling is unverified, so both spellings are accepted.
+ */
+const KEY_ALIASES = Object.freeze({
+  hookEventName: 'hook_event_name',
+  sessionId: 'session_id',
+  stopHookActive: 'stop_hook_active',
+  lastAssistantMessage: 'last_assistant_message',
+  toolName: 'tool_name',
+  toolInput: 'tool_input',
+  toolUseId: 'tool_use_id',
+  toolResult: 'tool_response',
+  subagentType: 'agent_type',
+  subagentId: 'agent_id',
+  permissionMode: 'permission_mode',
+  workspaceRoot: 'workspace_root',
+  userPrompt: 'prompt',
+  startSource: 'source',
+  compactTrigger: 'trigger',
+});
+
+const owns = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
+
+/** The Claude name for a foreign tool, or the input unchanged when unknown. */
+function normalizeToolName(name) {
+  if (typeof name !== 'string' || name === '') return name;
+  return owns(TOOL_ALIASES, name) ? TOOL_ALIASES[name] : name;
+}
+
+/** The Claude name for an event value, or the input unchanged (already PascalCase). */
+function normalizeEventName(value) {
+  if (typeof value !== 'string' || value === '') return value;
+  return owns(EVENT_NAMES, value) ? EVENT_NAMES[value] : value;
+}
+
+/**
+ * A hook payload in the shape the gate scripts read, whatever host sent it.
+ *
+ * Anything that is not a plain object is returned as-is rather than coerced, so a caller
+ * that already guards on shape keeps its own behaviour. The input is never mutated.
+ */
+function normalizeHookPayload(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return payload;
+
+  const out = { ...payload };
+
+  // A snake_case key already present wins: the host that sent it meant it.
+  for (const [foreign, native] of Object.entries(KEY_ALIASES)) {
+    if (owns(out, foreign) && !owns(out, native)) out[native] = out[foreign];
+  }
+
+  if (owns(out, 'hook_event_name')) out.hook_event_name = normalizeEventName(out.hook_event_name);
+  // By value, under whichever key carried it — omp sends `tool_name` with a lowercase value.
+  if (owns(out, 'tool_name')) out.tool_name = normalizeToolName(out.tool_name);
+
+  // grok's `read_file` carries its argument as `path`; the hooks read `file_path`.
+  const input = out.tool_input;
+  if (input && typeof input === 'object' && !Array.isArray(input)
+      && owns(input, 'path') && !owns(input, 'file_path')) {
+    out.tool_input = { ...input, file_path: input.path };
+  }
+
+  return out;
+}
+
+module.exports = { normalizeHookPayload, normalizeToolName, TOOL_ALIASES, KEY_ALIASES, EVENT_NAMES };

package/src/claude/hooks/lib/hook-state-dir.cjs

@@ -5,7 +5,7 @@
  * gate/tollgate caches.
  *
  * Hooks run from two places. In an installed project they live in
- * `.claude/hooks/`, whose `.logs/` is gitignored, so writing beside the hook is
+ * `<runtime-dir>/hooks/`, whose `.logs/` is gitignored, so writing beside the hook is
  * correct. During this package's tests they run straight from
  * `packages/spec/src/claude/hooks/`, where the same write lands inside the
  * source tree as an untracked directory. That changes the worktree digest the
@@ -32,7 +32,7 @@ function isSourceTree(dir) {
 /** Absolute directory for hook-generated state; create it before writing. */
 function hookStateDir() {
   return isSourceTree(HOOKS_DIR)
-    ? path.join(os.tmpdir(), 'cafekit-hook-logs', 'claude')
+    ? path.join(os.tmpdir(), 'cafekit-hook-logs', require('./runtime-dir.cjs').runtimeDirName().slice(1))
     : path.join(HOOKS_DIR, '.logs');
 }
 

package/src/claude/hooks/lib/runtime-dir.cjs

@@ -0,0 +1,49 @@
+/**
+ * Copyright (c) 2026 Haposoft. MIT License.
+ *
+ * Runtime-directory derivation for the gate hooks.
+ *
+ * The hooks used to hardcode `.claude` in every project-runtime path, so a copy installed
+ * under `.omp/hooks/` or `.codex/hooks/` read another platform's config, never matched
+ * installed-root detection, and wrote session state into a directory that did not exist.
+ * This module ships in `hooks/lib/`, so the runtime root is always two levels up from
+ * here and its basename is the answer: `.claude`, `.codex`, or `.omp`.
+ *
+ * In the source tree the same files live at `packages/spec/src/<platform>/hooks/lib/`, so
+ * the basename is the undotted platform name; it is mapped to its dotted form so tests
+ * that run hooks from source see the same directory an install would. A dotted basename
+ * always wins over the source-tree check, because an install can legitimately sit under a
+ * path that happens to contain `/packages/spec/src/`.
+ *
+ * Anything else yields `.claude`, which is exactly the behaviour every caller had before
+ * this module existed. There is deliberately no "derived" flag: nobody would read it.
+ *
+ * The source-tree marker is inlined rather than required from `hook-state-dir.cjs` so a
+ * fixture that copies a hook by hand needs to copy only this one library.
+ */
+
+const path = require('path');
+
+const SOURCE_MARKER = `${path.sep}packages${path.sep}spec${path.sep}src${path.sep}`;
+const HOOKS_DIR = path.resolve(__dirname, '..');
+const RUNTIME_ROOT = path.resolve(HOOKS_DIR, '..');
+
+/** `.claude`, `.codex`, `.omp`, or whatever dotted folder this hook tree is installed under. */
+function runtimeDirName() {
+  const base = path.basename(RUNTIME_ROOT);
+  if (base.startsWith('.')) return base;
+  if (HOOKS_DIR.includes(SOURCE_MARKER)) return `.${base}`;
+  return '.claude';
+}
+
+/** Absolute runtime directory for a project, e.g. `<cwd>/.omp`. */
+function runtimeDir(cwd) {
+  return path.join(cwd, runtimeDirName());
+}
+
+/** Absolute path under the runtime directory, e.g. `runtimePath(cwd, 'runtime.json')`. */
+function runtimePath(cwd, ...segments) {
+  return path.join(runtimeDir(cwd), ...segments);
+}
+
+module.exports = { runtimeDirName, runtimeDir, runtimePath };

package/src/claude/hooks/precompact.cjs

@@ -69,7 +69,8 @@ function activeTask(root) {
 
 try {
   const stdin = fs.readFileSync(0, 'utf8').trim();
-  const payload = stdin ? JSON.parse(stdin) : {};
+  const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
+  const payload = stdin ? normalizeHookPayload(JSON.parse(stdin)) : {};
   if (!payload || typeof payload !== 'object' || Array.isArray(payload)) process.exit(0);
 
   const root = projectRoot(payload);

package/src/claude/hooks/privacy-block.cjs

@@ -41,9 +41,10 @@ try {
     /\.env\.(example|sample|template|test)$/i
   ];
 
+  const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
   function readRuntime(cwd) {
     try {
-      const file = path.join(cwd, '.claude', 'runtime.json');
+      const file = runtimePath(cwd, 'runtime.json');
       return fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : {};
     } catch {
       return {};
@@ -200,7 +201,8 @@ try {
   const stdin = fs.readFileSync(0, 'utf8').trim();
   if (!stdin) process.exit(0);
 
-  const data = JSON.parse(stdin);
+  const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
+  const data = normalizeHookPayload(JSON.parse(stdin));
   const toolName = data.tool_name || '';
   const toolInput = data.tool_input || {};
   const cwd = typeof data.cwd === 'string' && data.cwd.trim() ? data.cwd : process.cwd();

package/src/claude/hooks/rules.cjs

@@ -16,9 +16,10 @@ try {
   const os   = require('os');
   const path = require('path');
 
+  const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
   function readRuntime(cwd) {
     try {
-      const p = path.join(cwd, '.claude', 'runtime.json');
+      const p = runtimePath(cwd, 'runtime.json');
       return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf8')) : null;
     } catch { return null; }
   }
@@ -48,7 +49,8 @@ try {
   const stdin = fs.readFileSync(0, 'utf8').trim();
   if (!stdin) process.exit(0);
 
-  const payload   = JSON.parse(stdin);
+  const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
+  const payload   = normalizeHookPayload(JSON.parse(stdin));
   const sessionId = payload.session_id || null;
   const payloadCwd = typeof payload.cwd === 'string' ? payload.cwd.trim() : '';
   const cwd       = payloadCwd || process.env.PROJECT_ROOT || process.cwd();

package/src/claude/hooks/secret-output-guardrail.cjs

@@ -24,7 +24,8 @@ try {
   const stdin = fs.readFileSync(0, 'utf8').trim();
   if (!stdin) process.exit(0);
 
-  const payload = JSON.parse(stdin);
+  const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
+  const payload = normalizeHookPayload(JSON.parse(stdin));
   const prompt = String(payload.prompt || payload.user_prompt || '');
   if (!containsSecretKeyword(prompt)) process.exit(0);
 

package/src/claude/hooks/semantic-review-authority.cjs

@@ -3,6 +3,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
 const { spawnSync } = require('child_process');
 const STATE = require('./completion-authority-state.cjs');
 const PATH_SAFETY = require('./lib/runtime-path-safety.cjs');
@@ -28,7 +29,7 @@ function inside(root, target) {
 
 function projectRoot(payload = {}) {
   const installedRoot = path.resolve(__dirname, '..', '..');
-  if (fs.existsSync(path.join(installedRoot, '.claude', 'hooks', path.basename(__filename)))) {
+  if (fs.existsSync(runtimePath(installedRoot, 'hooks', path.basename(__filename)))) {
     try { return STATE.canonicalProjectRoot(installedRoot); } catch {}
   }
   for (const candidate of [process.env.CLAUDE_PROJECT_DIR, process.env.PROJECT_ROOT]) {
@@ -70,7 +71,7 @@ function parseClaim(message) {
 }
 
 function validatorFor(root) {
-  const installedRoot = path.join(root, '.claude');
+  const installedRoot = runtimeDir(root);
   const installedHook = path.join(installedRoot, 'hooks', path.basename(__filename));
   if (fs.existsSync(installedHook)) {
     const canonicalHook = PATH_SAFETY.canonicalRegularFile(root, installedHook, 'installed semantic hook');
@@ -82,7 +83,7 @@ function validatorFor(root) {
 
   const sourceRuntime = path.resolve(__dirname, '..');
   const sourceRoot = path.resolve(sourceRuntime, '..');
-  if (path.basename(sourceRuntime) !== 'claude' || path.basename(sourceRoot) !== 'src') {
+  if (`.${path.basename(sourceRuntime)}` !== runtimeDirName() || path.basename(sourceRoot) !== 'src') {
     throw new Error('semantic validator runtime root is not recognized');
   }
   const validator = path.join(sourceRuntime, 'scripts', 'validate-spec-output.cjs');
@@ -143,7 +144,8 @@ function verifyAttestation(root, specFile, featureName, semanticDigest) {
 if (require.main === module) {
   try {
     const raw = fs.readFileSync(0, 'utf8').trim();
-    if (raw) recordFromSubagentStop(JSON.parse(raw));
+    const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
+    if (raw) recordFromSubagentStop(normalizeHookPayload(JSON.parse(raw)));
   } catch (error) {
     process.stderr.write(`CafeKit semantic review SubagentStop claim rejected: ${error.message}\n`);
   }

package/src/claude/hooks/session.cjs

@@ -14,6 +14,7 @@
 try {
   const fs   = require('fs');
   const path = require('path');
+  const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
   const os   = require('os');
   const { execSync } = require('child_process');
 
@@ -49,16 +50,16 @@ try {
     }
 
     const installedRoot = path.resolve(__dirname, '..', '..');
-    const installedHook = path.join(installedRoot, '.claude', 'hooks', path.basename(__filename));
+    const installedHook = runtimePath(installedRoot, 'hooks', path.basename(__filename));
     if (fs.existsSync(installedHook)) return installedRoot;
 
     try { return fs.realpathSync(process.cwd()); } catch { return path.resolve(process.cwd()); }
   }
 
-  /** Read .claude/runtime.json config */
+  /** Read <runtime>/runtime.json config */
   function readRuntime(cwd) {
     try {
-      const p = path.join(cwd, '.claude', 'runtime.json');
+      const p = runtimePath(cwd, 'runtime.json');
       return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf8')) : {};
     } catch { return {}; }
   }
@@ -143,12 +144,12 @@ try {
   }
 
   /**
-   * Read the installed CafeKit version from .claude/cafekit.json.
+   * Read the installed CafeKit version from <runtime>/cafekit.json.
    * Returns null if not found.
    */
   function getInstalledVersion(cwd) {
     try {
-      const p = path.join(cwd, '.claude', 'cafekit.json');
+      const p = runtimePath(cwd, 'cafekit.json');
       if (!fs.existsSync(p)) return null;
       const meta = JSON.parse(fs.readFileSync(p, 'utf8'));
       return typeof meta.version === 'string' ? meta.version : null;
@@ -158,14 +159,14 @@ try {
   /**
    * Check for a newer CafeKit version and return an update notice string,
    * or an empty string if already up to date or check fails.
-   * Result is cached in .claude/.cafekit-update-cache.json for 12 hours.
+   * Result is cached in <runtime>/.cafekit-update-cache.json for 12 hours.
    */
   async function checkCafeKitUpdate(cwd) {
     const installed = getInstalledVersion(cwd);
     if (!installed) return '';
 
     const CACHE_TTL = 12 * 60 * 60 * 1000; // 12 hours
-    const cachePath = path.join(cwd, '.claude', '.cafekit-update-cache.json');
+    const cachePath = runtimePath(cwd, '.cafekit-update-cache.json');
 
     // Return cached result if still fresh.
     try {
@@ -195,7 +196,8 @@ try {
 
   (async () => {
   const stdin   = fs.readFileSync(0, 'utf8').trim();
-  const payload = stdin ? JSON.parse(stdin) : {};
+  const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
+  const payload = stdin ? normalizeHookPayload(JSON.parse(stdin)) : {};
   const source  = payload.source || 'unknown';
   const envFile = process.env.CLAUDE_ENV_FILE;
   const cwd     = projectRoot();

package/src/claude/hooks/spec-gate.cjs

@@ -15,6 +15,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
 
 function projectRoot(payload = {}) {
   const configured = typeof process.env.CLAUDE_PROJECT_DIR === 'string'
@@ -25,7 +26,7 @@ function projectRoot(payload = {}) {
   }
 
   const installedRoot = path.resolve(__dirname, '..', '..');
-  const installedHook = path.join(installedRoot, '.claude', 'hooks', path.basename(__filename));
+  const installedHook = runtimePath(installedRoot, 'hooks', path.basename(__filename));
   if (fs.existsSync(installedHook)) return installedRoot;
 
   const sourceFixture = typeof process.env.PROJECT_ROOT === 'string'
@@ -78,8 +79,13 @@ try {
     throw new Error('hook payload must be a JSON object');
   }
 
-  // Never re-block a continuation caused by our own block (infinite-loop guard).
-  if (payload.stop_hook_active === true) process.exit(0);
+  // Never re-block a continuation caused by our own block (infinite-loop guard). Grok
+  // spells this `stopHookActive`; both are accepted here rather than through the payload
+  // reader, because the catch at the end of this file answers a block, so a reader that
+  // threw above the guard would block every completion instead of only a foreign one.
+  // The rest of this hook is already host-neutral: sessionIdentity() accepts sessionId
+  // and sessionID, the resolver reads camelCase targets, and projectRoot reads cwd.
+  if (payload.stop_hook_active === true || payload.stopHookActive === true) process.exit(0);
 
   let POLICY;
   let RESOLVER;
@@ -108,7 +114,7 @@ try {
   // Missing/malformed runtime.json keeps the gate ON (fail-closed, valve 3 style).
   let runtime = {};
   try {
-    const rp = path.join(cwd, '.claude', 'runtime.json');
+    const rp = runtimePath(cwd, 'runtime.json');
     if (fs.existsSync(rp)) runtime = JSON.parse(fs.readFileSync(rp, 'utf8'));
   } catch { /* gate stays on */ }
   // Active-spec discovery via shared resolver — explicit target if present, else fail on ambiguity.
@@ -225,10 +231,14 @@ try {
     process.exit(0);
   }
 
-  // Cache hardening: every Stop revalidates the canonical receipt for
-  // every task currently marked done, so a cached PASS cannot hide later
-  // mutations (deletion, placeholder, changed Verification/Command/Exit/
-  // Base/Head, stale provenance). Cache is an optimization, not truth.
+  // Cache hardening: every Stop re-reads and re-checks the receipt of every
+  // task currently marked done, so a cached PASS cannot hide later mutations
+  // (deletion, placeholder, changed Verification/Command/Exit, missing
+  // output, edited artifact bytes). Base/Head are compared against the live
+  // runtime only while the task file differs from its committed bytes or the
+  // tree outside the specs root is dirty; a committed, unchanged receipt on a
+  // clean tree is checked on structure alone. Cache is an optimization, not
+  // truth.
   const featureCache = cacheExists ? (cache[featureName] || {}) : {};
   const allDoneTasks = Object.keys(taskRegistry).filter((tp) =>
     (taskRegistry[tp]?.status || 'pending') === 'done'