@haposoft/cafekit 0.16.0 → 0.16.2

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();
@@ -252,6 +254,12 @@ try {
   if (packageManager) parts.push(`PM: ${packageManager}`);
   if (framework)      parts.push(`Framework: ${framework}`);
   if (gitBranch)      parts.push(`Branch: ${gitBranch}`);
+  // Orca (onorca.dev) sets this in every pane; it is a presence marker, not a secret.
+  // ORCA_AGENT_HOOK_TOKEN and ORCA_AGENT_LAUNCH_TOKEN live in the same environment and
+  // must never be read or printed here.
+  if (typeof process.env.ORCA_PANE_KEY === 'string' && process.env.ORCA_PANE_KEY !== '') {
+    parts.push('Orca: pane');
+  }
 
   console.log(`Session ${source}. ${parts.length ? parts.join(' | ') : 'No project info detected.'}${updateNotice}`);
 

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'

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

@@ -13,6 +13,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
 
 function logCrash(error) {
   try {
@@ -49,7 +50,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 cwd     = payload.cwd || process.cwd();
 
   let POLICY;
@@ -69,7 +71,7 @@ try {
   // Read runtime configuration if exists
   let runtime = {};
   try {
-    const p = path.join(cwd, '.claude', 'runtime.json');
+    const p = runtimePath(cwd, 'runtime.json');
     if (fs.existsSync(p)) runtime = JSON.parse(fs.readFileSync(p, 'utf8'));
   } catch { /* ignore */ }
 
@@ -77,7 +79,9 @@ try {
   // (The Stop completion gate has its own toggle: spec.completion_gate.)
   if (runtime.spec && runtime.spec.tollgate === false) process.exit(0);
 
-  const baseDir   = process.env.PROJECT_ROOT || cwd;
+  // Same rule as spec-gate: an installed hook trusts its own location over the environment.
+  const installedRoot = path.basename(path.resolve(__dirname, '..')).startsWith('.') ? path.resolve(__dirname, '..', '..') : null;
+  const baseDir   = installedRoot || process.env.PROJECT_ROOT || cwd;
   const explicitFeature = payload.featureName || payload.feature || payload.explicitFeature || null;
   const explicitPath = payload.specPath || payload.spec_path || payload.featurePath || null;
   const resolveWorkflow = typeof RESOLVER.resolveWorkflowCandidate === 'function'
@@ -222,11 +226,11 @@ try {
       lines.push('- Migration required: add `Specs-Contract: process-first-ready-v1` after the plan title before tasks can enter Next.');
     }
     lines.push('- Sync each flat task `Status:` only after verified work; task proof belongs in that task\'s inline `## Receipt`.');
-    lines.push(`- Workflow source: \`specs/${featureName}/plan.md\`; Stop revalidates every task currently marked done.`);
+    lines.push(`- Workflow source: \`specs/${featureName}/plan.md\`; Stop re-checks every done receipt, binding Base/Head to the runtime until the task file is committed, unchanged, and the tree outside the specs root is clean.`);
   } else {
     lines.push('- Sync `spec.json` + task Markdown status after verified work; task proof belongs in `receipts/<task-basename>.md`.');
     lines.push(`- Create \`feature-receipt.md\` once after final integration proof${featureReceiptPresent ? ' (present)' : ' (not required before closeout)'}.`);
-    lines.push(`- Validate with \`node .claude/scripts/validate-spec-output.cjs specs/${featureName}\`; hooks revalidate receipt bytes but never grant approval.`);
+    lines.push(`- Validate with \`node ${runtimeDirName()}/scripts/validate-spec-output.cjs specs/${featureName}\`; hooks revalidate receipt bytes but never grant approval.`);
   }
   lines.push('');
 

package/src/claude/hooks/state.cjs

@@ -12,7 +12,7 @@
  *   Stop          → persist full session state and archive
  *   SubagentStop  → append agent completion note to current state
  *
- * Storage: .claude/session-state/latest.md (+ archive/)
+ * Storage: <runtime>/session-state/latest.md (+ archive/)
  * Exit: 0 always (fail-open)
  */
 
@@ -23,6 +23,7 @@ try {
   const crypto = require('crypto');
   const { execSync } = require('child_process');
   const { parseTranscript } = require('./lib/parser.cjs');
+  const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
 
   const EXPIRY_DAYS = 7;
   const MAX_ARCHIVES = 5;
@@ -32,8 +33,8 @@ try {
 
   function stateDir(cwd) {
     try {
-      const local = path.join(cwd, '.claude', 'session-state');
-      if (fs.existsSync(path.join(cwd, '.claude'))) {
+      const local = runtimePath(cwd, 'session-state');
+      if (fs.existsSync(runtimeDir(cwd))) {
         if (!fs.existsSync(local)) fs.mkdirSync(local, { recursive: true });
         return local;
       }
@@ -224,7 +225,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 event = data.hook_event_name || '';
     const cwd = data.cwd || process.cwd();
     const dir = stateDir(cwd);

package/src/claude/hooks/task-scaffold-guard.cjs

@@ -21,7 +21,7 @@
  *   1. fail-open when spec-scaffold.cjs is absent — you cannot force a tool that
  *      is not installed, so a hook shipped without its script must not deadlock.
  *   2. actionable block message — prints the exact scaffold command to run.
- *   3. escape hatch — "spec": { "scaffold_guard": false } in .claude/runtime.json.
+ *   3. escape hatch — "spec": { "scaffold_guard": false } in <runtime>/runtime.json.
  *
  * Exit: 0 = allow, 2 = block.
  */
@@ -29,11 +29,33 @@
 try {
   const fs   = require('fs');
   const path = require('path');
+  const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
+
+/**
+ * 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();
@@ -50,17 +72,17 @@ try {
   const isTaskFile = /(^|\/)specs\/[^/]+\/tasks\/task-[^/]+\.md$/.test(norm);
   if (!isTaskFile) process.exit(0);
 
-  // Valve 3: explicit escape hatch via .claude/runtime.json (fail-closed: a
+  // Valve 3: explicit escape hatch via <runtime>/runtime.json (fail-closed: a
   // missing/broken runtime.json keeps the guard ON).
   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 { /* malformed runtime.json -> keep guard on */ }
   if (runtime.spec && runtime.spec.scaffold_guard === false) process.exit(0);
 
   // Valve 1: fail-open if the scaffold script is not installed next to this hook
-  // (hook lives in .claude/hooks/, script in .claude/scripts/). Forcing a tool
+  // (hook lives in <runtime>/hooks/, script in <runtime>/scripts/). Forcing a tool
   // that does not exist would deadlock task creation.
   const scaffold = path.join(__dirname, '..', 'scripts', 'spec-scaffold.cjs');
   if (!fs.existsSync(scaffold)) process.exit(0);
@@ -71,14 +93,13 @@ try {
   // simply disables the guard itself. The hatch stays functional for humans.
   const m = norm.match(/(^|\/)specs\/([^/]+)\/tasks\//);
   const feature = m ? m[2] : '<feature>';
-  console.log(
+  denyWithReason(
     `TASK SCAFFOLD REQUIRED: task files must be generated, not hand-written.\n` +
     `Blocked Write: ${filePath}\n\n` +
     `Generate the stub(s), then Edit-fill the {{...}} placeholders:\n` +
-    `  node .claude/scripts/spec-scaffold.cjs ${feature} --tasks "R0-01-slug,R1-01-slug,..." --tasks-only\n` +
+    `  node ${runtimeDirName()}/scripts/spec-scaffold.cjs ${feature} --tasks "R0-01-slug,R1-01-slug,..." --tasks-only\n` +
     `Then use Edit (not Write) on each tasks/task-*.md stub.`
   );
-  process.exit(2);
 
 } catch (e) {
   // Never let a hook crash block the user — log and fail-open.