@haposoft/cafekit 0.16.0 → 0.16.2

package/README.md

@@ -2,7 +2,7 @@
 
 > Native spec-driven workflow and runtime bundle for Claude Code and Codex CLI.
 
-[![Version](https://img.shields.io/badge/version-0.16.0-blue.svg)](https://github.com/haposoft/cafekit)
+[![Version](https://img.shields.io/badge/version-0.16.2-blue.svg)](https://github.com/haposoft/cafekit)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Claude%20Code](https://img.shields.io/badge/Claude%20Code-Native-orange.svg)](https://claude.ai/code)
 [![Codex%20CLI](https://img.shields.io/badge/Codex%20CLI-Native-111111.svg)](https://developers.openai.com/codex)
@@ -126,8 +126,9 @@ AGENTS.md
 CafeKit owns only its marked block in root `AGENTS.md`. Codex discovers skills
 and custom agents natively after the repository is trusted; no project
 `config.toml` is generated. Review and trust project hooks with `/hooks`.
-On Windows, installed hook commands are bound to the canonical project path
-without requiring Git and remain stable when a session starts in a subdirectory.
+Installed hook commands are bound to the canonical project path on every platform,
+so they need no Git repository, stay correct for a project nested inside a larger
+repository, and remain stable when a session starts in a subdirectory.
 CafeKit uses Codex's native status and usage UI instead of installing the
 Claude statusline.
 
@@ -165,6 +166,7 @@ CafeKit ships many skills, but the main release surface is:
 - `/cf:research <decision>`: choose proportional depth and return traceable evidence for an uncertain technical decision
 - `/cf:route <material-request>`: classify ambiguous, multi-step, multi-domain, or elevated-risk work and compose the shortest valid installed chain
 - `/cf:loop <bounded-experiment>`: run explicit-only numeric optimization in an isolated worktree and return a base-bound patch handoff
+- `/cf:orca <orca-request>`: inside an Orca (onorca.dev) pane, route a request to read, wait on, or send to another agent pane, or spawn one into a worktree
 - `/cf:specs <feature-description>`: create or resume a structured spec workflow
 - `/cf:develop <feature-name>`: implement from approved spec artifacts
 - `/cf:debug <issue>`: run adaptive-depth, diagnostic-only root-cause analysis with elimination and prevention-aware handoff

package/bin/__tests__/codex-hooks.test.js

@@ -1746,3 +1746,128 @@ test('Claude and Codex fail closed consistently for malformed cwd payloads', ()
     assert.equal(JSON.parse(codex.stdout).hookSpecificOutput.permissionDecision, 'deny');
   });
 });
+
+test('Codex emits the required decision for all six receipt states', () => {
+  // Codex owns no checker of its own: both wrappers in .codex/hooks/lib forward to
+  // the shared module, so the two receipt modes arrive by inheritance. This case is
+  // the regression lock on that inheritance. Each state asserts the decision Codex
+  // must emit on its own terms; parity with Claude is checked in addition, never
+  // instead, because both runtimes execute the same module and a broken
+  // implementation would agree with itself.
+  //
+  // The dirty-tree state runs the hook from a directory below the project root with
+  // the uncommitted change outside that directory's subtree. Without that, an
+  // implementation resolving the repository root from the working directory returns
+  // the same decision as a correct one and the case cannot fail.
+  inHookFixture((root, hooks) => {
+    const nested = path.join(root, 'packages', 'app');
+    const feature = path.join(root, 'specs', 'auth');
+    const taskFile = path.join(feature, 'task-01-auth.md');
+    const outsideDirt = path.join(root, 'src', 'outside.txt');
+    fs.mkdirSync(nested, { recursive: true });
+    fs.mkdirSync(feature, { recursive: true });
+    fs.mkdirSync(path.dirname(outsideDirt), { recursive: true });
+    fs.writeFileSync(path.join(feature, 'plan.md'), '# Auth plan\n');
+    fs.writeFileSync(outsideDirt, 'committed\n');
+
+    const staleBase = 'f'.repeat(40);
+    const staleHead = 'e'.repeat(40);
+    const taskBody = [
+      '# Task 01: auth', '', 'Status: done', '',
+      '## Dependencies', '', '- none', '',
+      '## Verification Plan', '', '- Command: node --test', '',
+      '## Receipt', '',
+      'Verification: PASS', 'Command: node --test', 'Exit: 0',
+      `Base: ${staleBase}`, `Head: ${staleHead}`,
+      '```text', '$ node --test', 'pass: 1', '```', '',
+    ].join('\n');
+    fs.writeFileSync(taskFile, taskBody);
+
+    const gate = path.join(hooks, 'spec-gate.cjs');
+    const payload = {
+      cwd: nested,
+      featureName: 'auth',
+      session_id: 'session-a',
+      hook_event_name: 'Stop',
+      stop_hook_active: false,
+    };
+    const git = (...args) => {
+      const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+      assert.equal(result.status, 0, result.stderr);
+      return result;
+    };
+    const decide = () => {
+      const result = runHook(gate, nested, payload);
+      assert.equal(result.status, 0, result.stderr);
+      return result.stdout.trim() === '' ? 'accept' : 'block';
+    };
+    // Use the same module instance that minted the context: a trusted runtime
+    // context is tracked per module, so mixing the package copy with the fixture
+    // copy would report a spurious binding failure.
+    const RECEIPT = require(path.join(PACKAGE_ROOT, 'src/claude/scripts/spec-receipt.cjs'));
+    const sharedDecides = () => {
+      const failures = RECEIPT.checkWorkflowTaskReceipt(
+        feature, 'task-01-auth.md', workflowRuntimeContext(root), POLICY,
+      ).failures;
+      return failures.length === 0 ? 'accept' : 'block';
+    };
+
+    // 1. untracked task file — never committed, so the binding stays.
+    assert.equal(decide(), 'block', 'an untracked task file must keep full binding');
+
+    // 2. staged but not committed — `git add` alone must not read as committed.
+    git('add', '-A');
+    assert.equal(decide(), 'block', 'a staged-only task file must keep full binding');
+
+    // 3. committed on a clean tree — the one accepting state.
+    git('commit', '-qm', 'receipt and source');
+    // Generated runtime state is excluded by design, so assert cleanliness the way
+    // the selector sees it: nothing dirty outside the specs root and the runtime
+    // state roots. The gate's own cache write must not read as a dirty worktree.
+    const cleanStatus = spawnSync('git', ['-C', root, 'status', '--porcelain', '--untracked-files=all',
+      '--', '.', ':(exclude,literal)specs', ':(exclude,literal).codex/hooks/.logs',
+      ':(exclude,literal).claude/hooks/.logs', ':(exclude,literal).codex/runtime.json'], { encoding: 'utf8' });
+    assert.equal(cleanStatus.stdout.trim(), '', 'nothing outside specs and runtime state may be dirty for this state to mean anything');
+    assert.equal(decide(), 'accept', 'a committed, unchanged receipt on a clean tree must be accepted');
+    assert.equal(sharedDecides(), 'accept', 'the shared checker must agree');
+
+    // 4. dirty tree outside the specs root, hook run from a nested directory with
+    //    the change outside that directory's subtree.
+    fs.writeFileSync(outsideDirt, 'uncommitted\n');
+    assert.ok(!path.relative(nested, outsideDirt).startsWith('..') === false,
+      'the dirt must lie outside the working directory used for the run');
+    assert.equal(decide(), 'block', 'an uncommitted change outside the specs root must rebind');
+    assert.equal(sharedDecides(), 'block', 'the shared checker must agree');
+    git('checkout', '--', 'src/outside.txt');
+
+    // 5. work confined to the specs root does not reopen a committed receipt.
+    fs.writeFileSync(path.join(feature, 'plan.md'), '# Auth plan\n\nEdited after the receipt landed.\n');
+    assert.equal(decide(), 'accept', 'edits inside the specs root must not rebind');
+    git('checkout', '--', 'specs/auth/plan.md');
+
+    // 6. committed then modified — the receipt itself changed after the commit.
+    fs.writeFileSync(taskFile, taskBody.replace(`Head: ${staleHead}`, `Head: ${'d'.repeat(40)}`));
+    assert.equal(decide(), 'block', 'a receipt edited after commit must be rebound');
+    assert.equal(sharedDecides(), 'block', 'the shared checker must agree');
+  });
+});
+
+test('Codex wrappers stay pass-through and carry no receipt-mode logic', () => {
+  // The mode selector must exist in exactly one place. If it is ever duplicated
+  // into the Codex wrapper, the two runtimes can drift apart silently.
+  const wrapper = fs.readFileSync(
+    path.join(PACKAGE_ROOT, 'src/codex/hooks/lib/spec-receipt.cjs'),
+    'utf8',
+  );
+  for (const marker of ['receiptBindingMode', 'skip-worktree', 'ls-files', 'cat-file', 'structure']) {
+    assert.ok(
+      !wrapper.includes(marker),
+      `the Codex wrapper must not reimplement receipt-mode logic; found ${marker}`,
+    );
+  }
+  assert.match(wrapper, /checkWorkflowTaskReceipt\(featureDir, taskPath, runtimeContext, policy\)/);
+  assert.match(
+    fs.readFileSync(path.join(PACKAGE_ROOT, 'src/codex/hooks/spec-state.cjs'), 'utf8'),
+    /Stop re-checks every done receipt/,
+  );
+});

package/bin/__tests__/codex-native.test.js

@@ -2035,6 +2035,101 @@ test('Codex Windows hook launchers stay project-bound without Git from nested cw
   });
 });
 
+// Run an installed POSIX launcher with no PATH at all, so neither `git` nor a `node` on
+// PATH can rescue it. The launcher must already carry everything it needs.
+function runPosixLauncher(command, cwd) {
+  return spawnSync(command.replace(/^node /, `"${process.execPath}" `), {
+    cwd,
+    encoding: 'utf8',
+    input: JSON.stringify({
+      session_id: 'posix-launcher-test',
+      cwd,
+      hook_event_name: 'SessionStart',
+      source: 'startup'
+    }),
+    env: { ...process.env, PATH: '' },
+    shell: true
+  });
+}
+
+function sessionLauncher(projectRoot) {
+  const config = JSON.parse(
+    fs.readFileSync(path.join(projectRoot, '.codex', 'hooks.json'), 'utf8')
+  );
+  return { config, command: config.hooks.SessionStart[0].hooks[0].command };
+}
+
+test('Codex POSIX hook launchers run without Git and outside the repository root', () => {
+  inTempProject((root) => {
+    // A launcher that asks Git for its root gets nothing here and the outer root one
+    // directory down, and in both cases points at a path that does not exist.
+    const plain = path.join(root, 'no-git-project');
+    fs.mkdirSync(plain, { recursive: true });
+    assert.equal(install(plain).status, 0);
+
+    const repoRoot = path.join(root, 'repo');
+    const nested = path.join(repoRoot, 'packages', 'inner');
+    fs.mkdirSync(nested, { recursive: true });
+    spawnSync('git', ['init', '-q'], { cwd: repoRoot });
+    assert.equal(install(nested).status, 0);
+
+    for (const projectRoot of [plain, nested]) {
+      const { config, command } = sessionLauncher(projectRoot);
+      for (const { handler } of allHookLaunchers(config)) {
+        // `node '<single-quoted absolute path>'` and nothing else. Inside single quotes
+        // the shell expands nothing, so a project path may safely contain $, a backtick,
+        // or the word git — this fixture's own path contains it.
+        assert.match(
+          handler.command,
+          /^node '(?:[^']|'\\'')+'$/,
+          `launcher must be a plain quoted path: ${handler.command}`
+        );
+        assert.doesNotMatch(handler.command, /rev-parse/, `launcher must not consult Git: ${handler.command}`);
+        assert.ok(
+          handler.command.includes(path.join(projectRoot, '.codex', 'hooks')),
+          `launcher must name this project's hooks directory: ${handler.command}`
+        );
+      }
+      const launched = runPosixLauncher(command, projectRoot);
+      assert.equal(launched.status, 0, launched.stderr);
+      assert.match(launched.stdout, /Session startup\./);
+    }
+  });
+});
+
+test('a reinstall repairs Codex launchers that resolved their path through Git', () => {
+  inTempProject((root) => {
+    assert.equal(install(root).status, 0);
+    const configPath = path.join(root, '.codex', 'hooks.json');
+
+    // Exactly what an installer before 0.16.2 wrote.
+    const downgraded = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    for (const { handler } of allHookLaunchers(downgraded)) {
+      const script = path.basename(handler.command.replace(/'$/, ''));
+      handler.command = `node "$(git rev-parse --show-toplevel)/.codex/hooks/${script}"`;
+    }
+    const foreign = { type: 'command', command: 'node "$(git rev-parse --show-toplevel)/tools/mine.cjs"' };
+    downgraded.hooks.SessionStart[0].hooks.push(foreign);
+    fs.writeFileSync(configPath, `${JSON.stringify(downgraded, null, 2)}\n`);
+
+    const again = install(root);
+    assert.equal(again.status, 0, again.stderr);
+    assert.match(again.stdout, /repaired \d+ launcher/, 'the repair must be reported, not silent');
+
+    const { config, command } = sessionLauncher(root);
+    const commands = allHookLaunchers(config).map(({ handler }) => handler.command);
+    assert.equal(
+      commands.filter((entry) => /rev-parse/.test(entry)).length,
+      1,
+      'only the hook CafeKit did not author may keep its own command'
+    );
+    assert.ok(commands.includes(foreign.command), 'a foreign hook must survive untouched');
+    const launched = runPosixLauncher(command, root);
+    assert.equal(launched.status, 0, launched.stderr);
+    assert.match(launched.stdout, /Session startup\./);
+  });
+});
+
 test('Codex installed Specs and spec-maker reject adaptive coverage mutations', () => {
   inTempProject((root) => {
     const userInstructions = '# User rules\n\nKeep this exact.\n';

package/bin/__tests__/develop-contract.test.js

@@ -89,7 +89,7 @@ function installClaudeRuntimeClosure(fixtureRoot, entry = 'hooks/spec-gate.cjs')
     fs.copyFileSync(path.join(hooksRoot, hook), target);
   }
   // Hook helpers the raw-copied hooks require at runtime.
-  for (const helper of ['hook-state-dir.cjs']) {
+  for (const helper of ['hook-state-dir.cjs', 'runtime-dir.cjs', 'hook-payload.cjs']) {
     const target = path.join(destinationRoot, 'hooks', 'lib', helper);
     fs.mkdirSync(path.dirname(target), { recursive: true });
     fs.copyFileSync(path.join(hooksRoot, 'lib', helper), target);
@@ -3338,3 +3338,45 @@ test('P0 canonical phantom vectors - zero, cancellation, suite, FAIL, error, col
   assert.equal(POLICY.isTapMetadataHeading('# Notes'), false);
   assert.equal(POLICY.isTapMetadataHeading('# pass 1 explanation'), false);
 });
+
+test('generated runtime state under every platform folder stays out of the worktree digest', () => {
+  // The gate writes its cache and the installer writes runtime.json under the platform
+  // folder on every run. If those writes moved Head, a project tracking its runtime
+  // directory could never hold a stable receipt. The exclusion list must name each
+  // shipped platform, and a real source change must still move Head.
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-state-roots-'));
+  try {
+    for (const args of [['init', '-q'], ['config', 'user.email', 'cafekit@example.invalid'], ['config', 'user.name', 'CafeKit Test'], ['commit', '--allow-empty', '-qm', 'fixture']]) {
+      const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+      assert.equal(result.status, 0, result.stderr);
+    }
+    fs.mkdirSync(path.join(root, 'specs', 'demo'), { recursive: true });
+    fs.writeFileSync(path.join(root, 'specs', 'demo', 'plan.md'), '# Demo plan\n');
+    const derive = () => PROVENANCE_HELPER.deriveRuntimeContext({
+      projectRoot: root,
+      specsRoot: path.join(root, 'specs'),
+      specFile: path.join(root, 'specs', 'demo', 'plan.md'),
+      featureName: 'demo',
+      runtimeSession: 'state-roots',
+    });
+    const before = derive();
+
+    for (const folder of ['.claude', '.codex', '.omp']) {
+      fs.mkdirSync(path.join(root, folder, 'hooks', '.logs'), { recursive: true });
+      fs.mkdirSync(path.join(root, folder, '.logs'), { recursive: true });
+      fs.writeFileSync(path.join(root, folder, 'hooks', '.logs', 'spec-gate-last.json'), '{"demo":{}}\n');
+      fs.writeFileSync(path.join(root, folder, '.logs', 'hook-log.jsonl'), '{}\n');
+      fs.writeFileSync(path.join(root, folder, 'runtime.json'), '{"spec":{"completion_gate":true}}\n');
+    }
+    const afterState = derive();
+    assert.equal(afterState.head, before.head, 'runtime state under .claude, .codex, and .omp must not move Head');
+    assert.equal(afterState.base, before.base);
+
+    // Anything else under the platform folder is source: a hook edit must move Head.
+    fs.mkdirSync(path.join(root, '.omp', 'hooks'), { recursive: true });
+    fs.writeFileSync(path.join(root, '.omp', 'hooks', 'rules.cjs'), '// edited\n');
+    assert.notEqual(derive().head, before.head, 'a real file under the platform folder must still move Head');
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});

package/bin/__tests__/grok-envelope.test.js

@@ -0,0 +1,271 @@
+'use strict';
+
+// Grok CLI runs these hooks through its Claude-compatibility layer, so the scripts must
+// answer the same way whether the envelope came from Claude Code or from grok. Each case
+// runs a real hook as a child process from a tree shaped like an install, with grok's
+// camelCase envelope on stdin and CLAUDE_PROJECT_DIR set the way grok sets it.
+//
+// Every case names the gate it protects. Before the payload reader existed, each of them
+// answered nothing: the hook read an undefined key, found no tool and no path, and let
+// the call through while looking installed.
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { test } = require('node:test');
+
+const PACKAGE_ROOT = path.join(__dirname, '../..');
+const MANIFEST = require(path.join(PACKAGE_ROOT, 'src/claude/migration-manifest.json'));
+
+/**
+ * A `.claude` tree holding exactly what an install ships, inside a git repository.
+ * The repository matters because the Stop gate derives provenance with git before it
+ * reads anything else.
+ */
+function withInstall(run, { git = false } = {}) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-grok-envelope-'));
+  try {
+    for (const rel of MANIFEST.runtime.files.filter((f) => f.startsWith('hooks/'))) {
+      const target = path.join(root, '.claude', rel);
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.copyFileSync(path.join(PACKAGE_ROOT, 'src/claude', rel), target);
+    }
+    fs.cpSync(path.join(PACKAGE_ROOT, 'src/claude/scripts'), path.join(root, '.claude', 'scripts'),
+      { recursive: true });
+    if (git) {
+      for (const args of [['init', '-q'], ['config', 'user.email', 'cafekit@example.invalid'],
+        ['config', 'user.name', 'CafeKit Test'], ['commit', '--allow-empty', '-qm', 'fixture']]) {
+        const r = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+        assert.equal(r.status, 0, r.stderr);
+      }
+    }
+    return run(root);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+/** Run one installed hook the way grok runs it. */
+function runHook(root, name, payload, args = []) {
+  const r = spawnSync(process.execPath, [path.join(root, '.claude', 'hooks', name), ...args], {
+    cwd: root,
+    input: JSON.stringify(payload),
+    encoding: 'utf8',
+    // grok sets CLAUDE_PROJECT_DIR as an alias of GROK_WORKSPACE_ROOT on every hook.
+    env: { ...process.env, CLAUDE_PROJECT_DIR: root, PROJECT_ROOT: '', GROK_SESSION_ID: 'grok-1' },
+  });
+  return { code: r.status, stdout: r.stdout || '', stderr: r.stderr || '' };
+}
+
+function decisionOf(stdout) {
+  for (const line of stdout.trim().split('\n').filter(Boolean)) {
+    try {
+      const parsed = JSON.parse(line);
+      const d = parsed?.hookSpecificOutput?.permissionDecision ?? parsed?.decision;
+      if (d) return { decision: d, reason: parsed?.hookSpecificOutput?.permissionDecisionReason ?? parsed?.reason };
+    } catch { /* not JSON, keep looking */ }
+  }
+  return { decision: null, reason: null };
+}
+
+test('the privacy gate asks on a grok run_terminal_command', () => {
+  withInstall((root) => {
+    fs.writeFileSync(path.join(root, '.env'), 'TOKEN=redacted\n');
+    // grok's shell tool under grok's key names. Reading `data.tool_name` here yields
+    // undefined, so the command is never scanned and the secret is handed over.
+    const r = runHook(root, 'privacy-block.cjs', {
+      hookEventName: 'pre_tool_use',
+      sessionId: 'grok-1',
+      cwd: root,
+      toolName: 'run_terminal_command',
+      toolInput: { command: `cat ${path.join(root, '.env')}` },
+    });
+    const { decision, reason } = decisionOf(r.stdout);
+    assert.equal(decision, 'ask', 'a grok shell call touching .env must reach the approval prompt');
+    assert.match(reason, /\.env/, 'the prompt must name what it is protecting');
+  });
+});
+
+test('the privacy gate asks on a grok read_file path', () => {
+  withInstall((root) => {
+    fs.writeFileSync(path.join(root, '.env'), 'TOKEN=redacted\n');
+    // grok's read tool carries its argument as `path`, not `file_path`.
+    const r = runHook(root, 'privacy-block.cjs', {
+      hookEventName: 'pre_tool_use',
+      cwd: root,
+      toolName: 'read_file',
+      toolInput: { path: path.join(root, '.env') },
+    });
+    assert.equal(decisionOf(r.stdout).decision, 'ask');
+  });
+});
+
+test('an ordinary grok read is not disturbed', () => {
+  withInstall((root) => {
+    fs.writeFileSync(path.join(root, 'README.md'), '# hello\n');
+    const r = runHook(root, 'privacy-block.cjs', {
+      hookEventName: 'pre_tool_use',
+      cwd: root,
+      toolName: 'read_file',
+      toolInput: { path: path.join(root, 'README.md') },
+    });
+    assert.equal(decisionOf(r.stdout).decision, null, 'the gate must not ask about an ordinary file');
+    assert.equal(r.code, 0);
+  });
+});
+
+test('a broad glob is denied with its full reason in JSON', () => {
+  withInstall((root) => {
+    const r = runHook(root, 'inspect-block.cjs', {
+      hookEventName: 'pre_tool_use',
+      cwd: root,
+      toolName: 'Glob',
+      toolInput: { pattern: '**/*.ts' },
+    });
+    const { decision, reason } = decisionOf(r.stdout);
+    assert.equal(decision, 'deny');
+    // grok reads only the first stderr line, so the actionable half of the message has to
+    // travel in the JSON reason or the model is blocked without being told what to do.
+    assert.match(reason, /SCOPE LIMIT EXCEEDED/);
+    assert.match(reason, /Please narrow your scope/, 'the whole message must survive, not just its first line');
+    assert.equal(r.code, 2, 'exit 2 stays for a host that reads neither channel');
+  });
+});
+
+test('a nested task write is denied under the grok write tool', () => {
+  withInstall((root) => {
+    const target = path.join(root, 'specs', 'demo', 'tasks', 'task-R0-01-x.md');
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    // grok creates files with `write`; `search_replace` edits an existing one. The guard
+    // fires on Write only, so the alias has to keep those two apart.
+    const r = runHook(root, 'task-scaffold-guard.cjs', {
+      hookEventName: 'pre_tool_use',
+      cwd: root,
+      toolName: 'write',
+      toolInput: { path: target, content: '# x' },
+    });
+    const { decision, reason } = decisionOf(r.stdout);
+    assert.equal(decision, 'deny');
+    assert.match(reason, /TASK SCAFFOLD REQUIRED/);
+    assert.match(reason, /spec-scaffold\.cjs/, 'the command the model must run has to reach it');
+    assert.equal(r.code, 2);
+
+    // The escape route the message names must stay open: an edit is not a create.
+    const edit = runHook(root, 'task-scaffold-guard.cjs', {
+      hookEventName: 'pre_tool_use',
+      cwd: root,
+      toolName: 'search_replace',
+      toolInput: { path: target, old_string: 'a', new_string: 'b' },
+    });
+    assert.equal(decisionOf(edit.stdout).decision, null, 'search_replace must not be treated as a create');
+    assert.equal(edit.code, 0);
+  });
+});
+
+/** A packet the Stop gate will block: one done task with no receipt. */
+function unprovenPacket(root) {
+  const feature = path.join(root, 'specs', 'demo');
+  fs.mkdirSync(feature, { recursive: true });
+  fs.writeFileSync(path.join(feature, 'plan.md'), '# Demo plan\n');
+  fs.writeFileSync(path.join(feature, 'task-01-demo.md'), [
+    '# Task 01: demo', '', 'Status: done', '', '## Dependencies', '', '- none', '',
+    '## Verification Plan', '', '- Command: node --test', '',
+  ].join('\n'));
+}
+
+test('the Stop gate honours stopHookActive', () => {
+  withInstall((root) => {
+    // The fixture must be one the gate would otherwise block, or silence proves nothing:
+    // an empty specs directory makes the gate exit quietly for a different reason.
+    unprovenPacket(root);
+    // Without the guard the gate re-blocks its own continuation until grok's cap ends
+    // the turn eight rounds later.
+    const r = runHook(root, 'spec-gate.cjs', {
+      hookEventName: 'stop',
+      sessionId: 'grok-1',
+      cwd: root,
+      stopHookActive: true,
+    });
+    assert.equal(r.stdout.trim(), '', 'a continuation round must pass silently');
+    assert.equal(r.code, 0);
+  }, { git: true });
+});
+
+test('the Stop gate still blocks an unproven done task', () => {
+  withInstall((root) => {
+    unprovenPacket(root);
+    // The guard must not become a way through: a Stop with no continuation flag still
+    // faces the receipt check.
+    const r = runHook(root, 'spec-gate.cjs', {
+      hookEventName: 'stop', sessionId: 'grok-1', cwd: root, stopHookActive: false,
+    });
+    const body = decisionOf(r.stdout);
+    assert.equal(body.decision, 'block', 'a done task without a receipt must still be blocked');
+  }, { git: true });
+});
+
+test('the approval hook takes its approve path on a grok prompt', () => {
+  withInstall((root) => {
+    // Registered without an argv mode, this hook picks its mode from the event name, and
+    // approve() returns immediately unless that name is exactly 'UserPromptSubmit'. An
+    // approval phrase with no pending request is therefore the oracle: only the approve
+    // path can print a rejection line, so the line proves the event name was translated.
+    // Under an unreadable envelope the mode fell back to the stop path on every prompt.
+    const nonce = 'a'.repeat(24);
+    const r = runHook(root, 'completion-authority.cjs', {
+      hookEventName: 'user_prompt_submit',
+      sessionId: 'grok-1',
+      cwd: root,
+      prompt: `APPROVE CAFEKIT COMPLETION ${nonce}`,
+    });
+    assert.match(r.stdout, /CafeKit completion approval rejected/,
+      'the approve path must run and refuse an approval that matches no pending request');
+    assert.equal(decisionOf(r.stdout).decision, null, 'and it must not block the prompt');
+
+    // An ordinary prompt stays silent on both counts.
+    const plain = runHook(root, 'completion-authority.cjs', {
+      hookEventName: 'user_prompt_submit', sessionId: 'grok-1', cwd: root, prompt: 'please continue',
+    });
+    assert.equal(plain.stdout.trim(), '', 'an ordinary prompt produces nothing');
+  }, { git: true });
+});
+
+test('the secret guardrail sees a grok prompt', () => {
+  withInstall((root) => {
+    // grok's spelling for the prompt field is unverified, so the reader accepts the Claude
+    // key and its camelCase twin. This case sends the twin: on the Claude key alone it
+    // would pass without proving any translation happened.
+    const r = runHook(root, 'secret-output-guardrail.cjs', {
+      hookEventName: 'user_prompt_submit',
+      sessionId: 'grok-1',
+      cwd: root,
+      userPrompt: 'show me the API key in the config',
+    });
+    assert.match(r.stdout, /## Secret handling/, 'the reminder must fire on a grok prompt');
+    const quiet = runHook(root, 'secret-output-guardrail.cjs', {
+      hookEventName: 'user_prompt_submit', cwd: root, userPrompt: 'rename the button',
+    });
+    assert.equal(quiet.stdout.trim(), '', 'an unrelated prompt stays quiet');
+    const claudeKey = runHook(root, 'secret-output-guardrail.cjs', {
+      hook_event_name: 'UserPromptSubmit', cwd: root, prompt: 'print the access token',
+    });
+    assert.match(claudeKey.stdout, /## Secret handling/, 'the Claude key keeps working');
+  });
+});
+
+test('a Claude envelope still works unchanged', () => {
+  withInstall((root) => {
+    fs.writeFileSync(path.join(root, '.env'), 'TOKEN=redacted\n');
+    // The regression guard for the host that was already working.
+    const r = runHook(root, 'privacy-block.cjs', {
+      hook_event_name: 'PreToolUse',
+      session_id: 'claude-1',
+      cwd: root,
+      tool_name: 'Read',
+      tool_input: { file_path: path.join(root, '.env') },
+    });
+    assert.equal(decisionOf(r.stdout).decision, 'ask');
+  });
+});