@haposoft/cafekit 0.16.0-rc.8 → 0.16.1

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

@@ -0,0 +1,39 @@
+'use strict';
+
+/**
+ * Where a Claude hook keeps its own generated state: crash logs and the
+ * gate/tollgate caches.
+ *
+ * Hooks run from two places. In an installed project they live in
+ * `<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
+ * receipt provenance is bound to, and the completion gate then reports every
+ * done task as stale. It surfaced three times as a false alarm before the cause
+ * was found, so source-tree runs write to a temp directory instead.
+ *
+ * Keeping the rule here means a new hook cannot reintroduce the bug by copying
+ * the old `path.join(__dirname, '.logs')` line.
+ */
+
+const os = require('os');
+const path = require('path');
+
+// This module ships in `hooks/lib/`, so the hook directory is always its parent.
+const HOOKS_DIR = path.join(__dirname, '..');
+const SOURCE_MARKER = `${path.sep}packages${path.sep}spec${path.sep}src`;
+
+/** True when `dir` sits inside this package's source tree rather than an install. */
+function isSourceTree(dir) {
+  return String(dir || '').includes(SOURCE_MARKER);
+}
+
+/** Absolute directory for hook-generated state; create it before writing. */
+function hookStateDir() {
+  return isSourceTree(HOOKS_DIR)
+    ? path.join(os.tmpdir(), 'cafekit-hook-logs', require('./runtime-dir.cjs').runtimeDirName().slice(1))
+    : path.join(HOOKS_DIR, '.logs');
+}
+
+module.exports = { hookStateDir, isSourceTree };

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/lib/secret-keywords.cjs

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) 2026 Haposoft. MIT License.
+ *
+ * Secret-output guardrail keyword matcher.
+ *
+ * These patterns detect prompts about credential handling. They are deliberately
+ * separate from the privacy hooks: those gate whether a sensitive file may be READ,
+ * while this list drives a soft reminder about whether a value may be PRINTED.
+ * Approval for the first is not approval for the second.
+ */
+
+const SECRET_KEYWORD_PATTERNS = [
+  /\.env(?:\b|$)/i,
+  /(?:^|[^A-Za-z0-9])credentials?(?:$|[^A-Za-z0-9])/i,
+  /(?:^|[^A-Za-z0-9])secrets?(?:$|[^A-Za-z0-9])/i,
+  /(?:^|[^A-Za-z0-9])api[\s_-]*keys?(?:$|[^A-Za-z0-9])/i,
+  /(?:^|[^A-Za-z0-9])access[\s_-]*keys?(?:$|[^A-Za-z0-9])/i,
+  /(?:^|[^A-Za-z0-9])tokens?(?:$|[^A-Za-z0-9])/i,
+  /(?:^|[^A-Za-z0-9])bearer(?:$|[^A-Za-z0-9])/i,
+  /(?:^|[^A-Za-z0-9])jwts?(?:$|[^A-Za-z0-9])/i,
+  /(?:^|[^A-Za-z0-9])private[\s_-]*keys?(?:$|[^A-Za-z0-9])/i,
+  /(?:^|[^A-Za-z0-9])oauth(?:[\s_-]+client)?[\s_-]*secrets?(?:$|[^A-Za-z0-9])/i,
+  /(?:^|[^A-Za-z0-9])client[\s_-]*secrets?(?:$|[^A-Za-z0-9])/i,
+  /(?:^|[^A-Za-z0-9])cloud[\s_-]*keys?(?:$|[^A-Za-z0-9])/i,
+  /(?:^|[^A-Za-z0-9])env[\s_-]+files?(?:$|[^A-Za-z0-9])/i,
+];
+
+/** The reminder text. It names no value and quotes no prompt. */
+const REMINDER = [
+  '## Secret handling',
+  '- Do not print raw credentials, API keys, tokens, JWTs, private keys, or secret values into the conversation.',
+  '- Use [redacted], variable names, counts, or high-level status instead.',
+  '- Approval to read a sensitive file or command output does not grant permission to print raw values.',
+  '- If a value is needed for a machine action, pass it through a non-echoing path and report only success or failure.',
+].join('\n');
+
+function containsSecretKeyword(prompt) {
+  if (typeof prompt !== 'string' || prompt.trim() === '') return false;
+  return SECRET_KEYWORD_PATTERNS.some((pattern) => pattern.test(prompt));
+}
+
+module.exports = { SECRET_KEYWORD_PATTERNS, REMINDER, containsSecretKeyword };

package/src/claude/hooks/precompact.cjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2026 Haposoft. MIT License.
+ *
+ * PreCompact Hook — precompact.cjs
+ * Implements: https://docs.anthropic.com/en/docs/claude-code/hooks
+ *
+ * Compaction drops the transcript that told the session where it was. The
+ * existing SessionStart warning tells the operator something was lost but not
+ * what, so recovery starts from a blank slate and the session re-derives facts
+ * it already had. This hook writes down the machine-checkable anchors just
+ * before the drop: branch, HEAD, how dirty the tree is, and which task the
+ * packet says is in flight. `session.cjs` prints them back on the compact
+ * restart.
+ *
+ * Only facts the runtime can re-derive are recorded. Nothing here is proof of
+ * work and nothing here grants an authorization; a compacted session must still
+ * re-ask for a pending confirmation.
+ *
+ * Storage: the hook state directory (temp when run from source).
+ * Exit: 0 always (fail-open).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const RECOVERY_FILE = 'compact-recovery.json';
+
+function gitLine(root, args) {
+  const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+  if (result.error || result.status !== 0) return null;
+  const value = String(result.stdout || '').trim();
+  return value === '' ? null : value;
+}
+
+function projectRoot(payload) {
+  const configured = typeof process.env.CLAUDE_PROJECT_DIR === 'string' ? process.env.CLAUDE_PROJECT_DIR.trim() : '';
+  const candidates = [configured, typeof payload.cwd === 'string' ? payload.cwd.trim() : '', process.cwd()];
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    try { return fs.realpathSync(path.resolve(candidate)); } catch { /* next */ }
+  }
+  return process.cwd();
+}
+
+/** The one task the packet currently says is in flight, if any. */
+function activeTask(root) {
+  try {
+    const RESOLVER = require(path.join(__dirname, '..', 'scripts', 'spec-resolver.cjs'));
+    if (typeof RESOLVER.resolveWorkflowCandidate !== 'function') return null;
+    const resolved = RESOLVER.resolveWorkflowCandidate({ projectRoot: root, runtime: {}, target: null });
+    if (!resolved || resolved.error || resolved.layoutKind !== 'process-v3') return null;
+    const registry = resolved.taskRegistry || {};
+    const inProgress = Object.keys(registry).filter((taskPath) => registry[taskPath]?.status === 'in_progress');
+    return {
+      feature: resolved.featureName || null,
+      in_progress: inProgress,
+      counts: Object.values(registry).reduce((acc, task) => {
+        const status = task?.status || 'pending';
+        acc[status] = (acc[status] || 0) + 1;
+        return acc;
+      }, {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
+try {
+  const stdin = fs.readFileSync(0, 'utf8').trim();
+  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);
+  const status = gitLine(root, ['status', '--porcelain']);
+  const record = {
+    captured_at: new Date().toISOString(),
+    trigger: typeof payload.trigger === 'string' ? payload.trigger : null,
+    session_id: typeof payload.session_id === 'string' ? payload.session_id : null,
+    project_root: root,
+    branch: gitLine(root, ['rev-parse', '--abbrev-ref', 'HEAD']),
+    head: gitLine(root, ['rev-parse', '--short', 'HEAD']),
+    dirty_count: status === null ? null : status.split('\n').filter((line) => line.trim() !== '').length,
+    workflow: activeTask(root),
+  };
+
+  const dir = require('./lib/hook-state-dir.cjs').hookStateDir();
+  fs.mkdirSync(dir, { recursive: true });
+  const target = path.join(dir, RECOVERY_FILE);
+  const temp = `${target}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(record, null, 2)}\n`);
+  fs.renameSync(temp, target);
+  process.exit(0);
+} catch (error) {
+  try {
+    const dir = require('./lib/hook-state-dir.cjs').hookStateDir();
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(
+      path.join(dir, 'hook-log.jsonl'),
+      `${JSON.stringify({ ts: new Date().toISOString(), hook: 'precompact', status: 'crash', error: error.message })}\n`,
+    );
+  } catch (_) { /* fail-open */ }
+  process.exit(0);
+}

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();
@@ -93,7 +95,7 @@ try {
 } catch (e) {
   try {
     const fs = require('fs'), p = require('path');
-    const d = p.join(__dirname, '.logs');
+    const d = require('./lib/hook-state-dir.cjs').hookStateDir();
     if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
     fs.appendFileSync(p.join(d, 'hook-log.jsonl'),
       JSON.stringify({ ts: new Date().toISOString(), hook: 'rules', status: 'crash', error: e.message }) + '\n');

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

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2026 Haposoft. MIT License.
+ *
+ * UserPromptSubmit Hook — secret-output-guardrail.cjs
+ * Implements: https://docs.anthropic.com/en/docs/claude-code/hooks
+ *
+ * The privacy hook gates whether a sensitive file may be read. Nothing gated what
+ * happens after that approval, so an approved read could still put a raw key into
+ * the transcript — where it survives compaction, is written to disk, and is replayed
+ * to the model on every later turn. This injects a reminder when the prompt itself is
+ * about credential handling.
+ *
+ * It reads the prompt and never echoes it: no prompt text and no matched value is
+ * written out, so the guardrail cannot itself become the leak.
+ *
+ * Exit: 0 always (fail-open)
+ */
+
+try {
+  const fs = require('fs');
+  const { REMINDER, containsSecretKeyword } = require('./lib/secret-keywords.cjs');
+
+  const stdin = fs.readFileSync(0, 'utf8').trim();
+  if (!stdin) process.exit(0);
+
+  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);
+
+  console.log(REMINDER);
+  process.exit(0);
+
+} catch (e) {
+  try {
+    const fs = require('fs'), p = require('path');
+    const d = require('./lib/hook-state-dir.cjs').hookStateDir();
+    if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+    fs.appendFileSync(p.join(d, 'hook-log.jsonl'),
+      JSON.stringify({ ts: new Date().toISOString(), hook: 'secret-output-guardrail', status: 'crash', error: e.message }) + '\n');
+  } catch (_) {}
+  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();
@@ -261,6 +263,32 @@ try {
     console.log('Any pending confirmations requested via AskUserQuestion might have been lost.');
     console.log('Do not proceed without explicitly asking the user again to ensure safety.');
     console.log('Use AskUserQuestion: "The chat context was compressed. Do I still have permission to proceed?"');
+
+    // Anchors captured by the PreCompact hook. These are re-derivable facts, not
+    // proof and not an authorization: they save the session from rebuilding its
+    // bearings, and nothing more.
+    try {
+      const fs2 = require('fs'), p2 = require('path');
+      const file = p2.join(require('./lib/hook-state-dir.cjs').hookStateDir(), 'compact-recovery.json');
+      const record = JSON.parse(fs2.readFileSync(file, 'utf8'));
+      const parts = [];
+      if (record.branch) parts.push(`branch ${record.branch}`);
+      if (record.head) parts.push(`HEAD ${record.head}`);
+      if (typeof record.dirty_count === 'number') parts.push(`${record.dirty_count} uncommitted path(s)`);
+      console.log('\n=== State before compaction ===');
+      if (record.captured_at) console.log(`Captured: ${record.captured_at}`);
+      if (parts.length) console.log(`Repository: ${parts.join(' | ')}`);
+      const workflow = record.workflow;
+      if (workflow && workflow.feature) {
+        const counts = Object.entries(workflow.counts || {}).map(([k, v]) => `${v} ${k}`).join(', ');
+        console.log(`Feature: ${workflow.feature}${counts ? ` (${counts})` : ''}`);
+        if (Array.isArray(workflow.in_progress) && workflow.in_progress.length > 0) {
+          console.log(`In flight: ${workflow.in_progress.join(', ')}`);
+        }
+      }
+      console.log('Re-read these from disk before acting; they describe the moment before compaction.');
+      console.log('=== End of pre-compaction state ===');
+    } catch (_) { /* no capture available */ }
   }
 
   process.exit(0);
@@ -269,7 +297,7 @@ try {
 } catch (e) {
   try {
     const fs = require('fs'), p = require('path');
-    const d = p.join(__dirname, '.logs');
+    const d = require('./lib/hook-state-dir.cjs').hookStateDir();
     if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
     fs.appendFileSync(p.join(d, 'hook-log.jsonl'),
       JSON.stringify({ ts: new Date().toISOString(), hook: 'session', status: 'crash', error: e.message }) + '\n');

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'
@@ -44,7 +45,7 @@ function projectRoot(payload = {}) {
 
 function logCrash(error) {
   try {
-    const d = path.join(__dirname, '.logs');
+    const d = require('./lib/hook-state-dir.cjs').hookStateDir();
     if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
     fs.appendFileSync(
       path.join(d, 'hook-log.jsonl'),
@@ -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.
@@ -202,7 +208,7 @@ try {
     process.exit(0);
   }
   const taskRegistry = resolved.taskRegistry || activeSpec.task_registry || {};
-  const cacheFile = path.join(__dirname, '.logs', 'spec-gate-last.json');
+  const cacheFile = path.join(require('./lib/hook-state-dir.cjs').hookStateDir(), 'spec-gate-last.json');
   const cacheExists = fs.existsSync(cacheFile);
   let cache = {};
   if (cacheExists) {
@@ -220,15 +226,19 @@ try {
   if (staleFlashTasks.length > 0) {
     process.stdout.write(JSON.stringify({
       decision: 'block',
-      reason: `Completion gate: ${staleFlashTasks.length} task(s) marked done with FLASH_UNVERIFIED (${staleFlashTasks.join(', ')}). Run /hapo:test for exact proof, then use explicit sync-finalize.`
+      reason: `Completion gate: ${staleFlashTasks.length} task(s) marked done with FLASH_UNVERIFIED (${staleFlashTasks.join(', ')}). Run /cf:test for exact proof, then use explicit sync-finalize.`
     }) + '\n');
     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,10 +13,11 @@
 
 const fs = require('fs');
 const path = require('path');
+const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
 
 function logCrash(error) {
   try {
-    const d = path.join(__dirname, '.logs');
+    const d = require('./lib/hook-state-dir.cjs').hookStateDir();
     if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
     fs.appendFileSync(
       path.join(d, 'hook-log.jsonl'),
@@ -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'
@@ -182,7 +186,7 @@ try {
     total: taskEntries.length,
     featureReceiptPresent,
   });
-  const cacheFile = path.join(__dirname, '.logs', 'tollgate-last.txt');
+  const cacheFile = path.join(require('./lib/hook-state-dir.cjs').hookStateDir(), 'tollgate-last.txt');
 
   let lastKey = '';
   if (stateKey) {
@@ -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('');