@haposoft/cafekit 0.18.1 → 0.18.3

package/src/codex/scripts/setup-agents.cjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Install the CafeKit agents shipped in the Codex plugin into the user's Codex agents
+ * directory ($CODEX_HOME/agents, default ~/.codex/agents). Codex loads no agents from a
+ * plugin, so this runs once after the plugin is installed or updated.
+ *
+ * Every shipped file starts with a marker naming the plugin, its version and the sha256
+ * of the body below it. A file counts as CafeKit's own only when its marker hash still
+ * matches its body; only those are replaced. Anything else stays byte for byte:
+ * a missing marker, an edited body, or a symlink.
+ *
+ * A file it cannot read is kept and reported, and the other agents still install.
+ * Takes no arguments: the target is never chosen by the caller.
+ * Exit: 0 done, 1 failure, 2 usage.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+
+const MARKER = /^# CafeKit agent: plugin=(\S+) version=(\S+) sha256=([0-9a-f]{64})\n/;
+
+const sha256 = (text) => crypto.createHash('sha256').update(text).digest('hex');
+
+/** 'absent' | 'symlink' | 'foreign' | 'modified' | 'own' */
+function ownership(file) {
+  let stat;
+  try {
+    stat = fs.lstatSync(file);
+  } catch (error) {
+    if (error.code === 'ENOENT') return 'absent';
+    throw error;
+  }
+  if (stat.isSymbolicLink()) return 'symlink';
+  if (!stat.isFile()) return 'foreign';
+  const text = fs.readFileSync(file, 'utf8');
+  const marker = text.match(MARKER);
+  if (!marker) return 'foreign';
+  return sha256(text.slice(marker[0].length)) === marker[3] ? 'own' : 'modified';
+}
+
+// Write beside the target and rename over it, so a reader never sees half a file.
+function writeAtomic(file, data, mode) {
+  const temp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  try {
+    fs.writeFileSync(temp, data, { mode, flag: 'wx' });
+    fs.chmodSync(temp, mode);
+    fs.renameSync(temp, file);
+  } catch (error) {
+    fs.rmSync(temp, { force: true });
+    throw error;
+  }
+}
+
+// Codex reads agents from its home, so a session started with CODEX_HOME installs there.
+// A relative CODEX_HOME is refused rather than guessed, so it never falls back to ~/.codex.
+function codexHome() {
+  const configured = process.env.CODEX_HOME;
+  if (!configured) return path.join(os.homedir(), '.codex');
+  if (!path.isAbsolute(configured)) throw new Error(`CODEX_HOME must be an absolute path: ${configured}`);
+  return configured;
+}
+
+function repositoryRoot() {
+  const result = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8', timeout: 5000 });
+  return result.status === 0 && result.stdout.trim() ? result.stdout.trim() : process.cwd();
+}
+
+function main(argv) {
+  if (argv.length > 0) {
+    process.stderr.write('setup-agents takes no arguments; it installs into $CODEX_HOME/agents (default ~/.codex/agents).\n');
+    return 2;
+  }
+  const sourceDir = path.join(__dirname, '..', 'agents');
+  const targetDir = path.join(codexHome(), 'agents');
+  const repoAgents = path.join(repositoryRoot(), '.codex', 'agents');
+  const files = fs.readdirSync(sourceDir).filter((name) => name.endsWith('.toml')).sort();
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  const counts = {};
+  for (const name of files) {
+    const shipped = fs.readFileSync(path.join(sourceDir, name), 'utf8');
+    const target = path.join(targetDir, name);
+    let state;
+    try {
+      state = ownership(target);
+    } catch {
+      state = 'unreadable';
+    }
+    let action;
+    if (state === 'absent') {
+      writeAtomic(target, shipped, 0o644);
+      action = 'written';
+    } else if (state === 'own') {
+      if (fs.readFileSync(target, 'utf8') === shipped) {
+        action = 'unchanged';
+      } else {
+        writeAtomic(target, shipped, fs.statSync(target).mode & 0o777);
+        action = 'replaced';
+      }
+    } else {
+      action = { symlink: 'kept (symlink)', foreign: 'kept (not installed by CafeKit)', modified: 'kept (modified)', unreadable: 'kept (unreadable)' }[state];
+    }
+    counts[action] = (counts[action] || 0) + 1;
+    process.stdout.write(`${action}: ${target}\n`);
+    if (fs.existsSync(path.join(repoAgents, name))) {
+      process.stdout.write(`collision: ${path.join(repoAgents, name)} has the same agent name in this repository\n`);
+    }
+  }
+  const summary = Object.entries(counts).map(([action, count]) => `${count} ${action}`).join(', ');
+  process.stdout.write(`CafeKit agents in ${targetDir}: ${summary}\n`);
+  return 0;
+}
+
+try {
+  process.exitCode = main(process.argv.slice(2));
+} catch (error) {
+  process.stderr.write(`setup-agents failed: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/src/common/AGENTS.md

@@ -8,7 +8,7 @@
   keeps canonical execution proof in its final inline `## Receipt`.
 - Specs uses three user decisions: GATE-SCOPE for scope, GATE-REVIEW for adversarial findings,
   and GATE-DONE for completion. Planning never starts implementation; implementation
-  requires a new explicit user invocation.
+  requires a new explicit user invocation. A vibe run the user invokes delegates these gates as the state-sync rule's vibe-run exception states.
 - Synchronize only observed task state with surgical edits. Never invent proof,
   readiness, approval, review independence, or completed work.
 - `NO_TESTS` and `0 tests + exit 0` do not pass when the task requires automated tests.

package/src/omp/extensions/{cafekit-bridge.mjs → cafekit-bridge.js}

@@ -9,7 +9,11 @@
  * payload the scripts read, runs the scripts as child processes, and translates their
  * verdicts back into omp's contract.
  *
- * Three facts read from the installed omp binary drive the design:
+ * Facts read from the installed omp binary drive the design:
+ *  - omp auto-loads only `<name>.{ts,js}` and `<dir>/index.{ts,js}` from `.omp/extensions/`, so this
+ *    file is `.js`; an `.mjs` bridge is never loaded and every gate is silently off.
+ *  - omp is a Bun binary: `process.execPath` is omp itself, not node, so the hooks are run
+ *    with a `node` found on PATH (see hookRunner).
  *  - omp fails CLOSED at `tool_call`: a handler that throws or exceeds
  *    `extensionHandlers.toolCallTimeoutMs` (default 30000) is replaced by omp's own
  *    `{ block: true, reason: "Extension … timed out" }`. The bridge therefore keeps a
@@ -26,7 +30,7 @@
 
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { existsSync } from 'node:fs';
+import { accessSync, constants, existsSync, realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -38,16 +42,16 @@ export const BRIDGE_TIMEOUT_MS = 8000;
  * Mirrors src/claude/settings/settings.json; `omp-bridge.test.js` fails if the two drift.
  */
 export const DISPATCH = {
-  session_start:          { event: 'SessionStart',     hooks: ['session.cjs', 'docs-sync.cjs', 'state.cjs'] },
+  session_start:          { event: 'SessionStart',     hooks: ['session.cjs', 'state.cjs'] },
   session_compact:        { event: 'SessionStart',     hooks: ['session.cjs'], source: 'compact' },
   session_before_compact: { event: 'PreCompact',       hooks: ['precompact.cjs'] },
   input:                  { event: 'UserPromptSubmit', hooks: ['secret-output-guardrail.cjs', 'rules.cjs', 'spec-state.cjs'] },
   tool_call:              { event: 'PreToolUse',       hooks: ['privacy-block.cjs', 'inspect-block.cjs'] },
-  tool_result:            { event: 'PostToolUse',      hooks: ['state.cjs'] },
+  tool_result:            { event: 'PostToolUse',      hooks: ['state.cjs', 'spec-state.cjs'] },
   session_stop:           { event: 'Stop',             hooks: ['spec-gate.cjs', 'state.cjs'] },
 };
 
-/** One id per extension load. omp loads an extension once per session, so this is per-session. */
+/** Fallback id per extension load, for an omp whose context has no session manager. */
 const SESSION_ID = `omp-${randomUUID()}`;
 
 export function hooksDir() {
@@ -55,13 +59,37 @@ export function hooksDir() {
   return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'hooks');
 }
 
+function sessionIdFrom(ctx) {
+  try {
+    const id = ctx?.sessionManager?.getSessionId?.();
+    return typeof id === 'string' && id ? id : null;
+  } catch { return null; }
+}
+
+/**
+ * Only the file paths of a tool result's details. An edit's details also carry the old and
+ * new text of every file it changed, which no hook needs on stdin.
+ */
+function resultPaths(details) {
+  if (!details || typeof details !== 'object') return {};
+  const paths = (list) => (Array.isArray(list) ? list.filter((entry) => typeof entry?.path === 'string').map((entry) => ({ path: entry.path })) : undefined);
+  const out = {};
+  if (typeof details.path === 'string') out.path = details.path;
+  const perFile = paths(details.perFileResults);
+  if (perFile) out.perFileResults = perFile;
+  const changes = paths(details.fileChanges);
+  if (changes) out.fileChanges = changes;
+  return out;
+}
+
 /** Build the Claude-shaped payload a CafeKit hook reads on stdin. */
 export function shapePayload(kind, event, ctx) {
   const entry = DISPATCH[kind];
   const cwd = ctx?.cwd || process.cwd();
   const payload = {
     hook_event_name: entry.event,
-    session_id: event?.session_id || SESSION_ID,
+    // omp's own id first: session_stop carries it, and touch and state must stay in one place.
+    session_id: event?.session_id || sessionIdFrom(ctx) || SESSION_ID,
     cwd,
   };
   switch (kind) {
@@ -85,7 +113,7 @@ export function shapePayload(kind, event, ctx) {
     case 'tool_result':
       payload.tool_name = event?.toolName ?? event?.tool_name ?? '';
       payload.tool_input = event?.input ?? {};
-      payload.tool_response = { content: event?.content ?? [], isError: event?.isError === true };
+      payload.tool_response = { content: event?.content ?? [], isError: event?.isError === true, details: resultPaths(event?.details) };
       payload.tool_use_id = event?.toolCallId ?? null;
       break;
     case 'session_stop':
@@ -135,12 +163,54 @@ export function interpretVerdict({ code, stdout = '', stderr = '' }, hookName) {
   return { block: Boolean(block), reason: block?.reason, inject: inject.join('\n').trim() };
 }
 
+function isInside(root, target) {
+  const rel = path.relative(root, target);
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+function realOrSelf(target) {
+  try { return realpathSync(target); } catch { return path.resolve(target); }
+}
+
+/**
+ * The executable that runs a hook. Under node that is `process.execPath`. Under Bun (omp)
+ * it is the first `node` on PATH that sits in an absolute PATH entry outside the project,
+ * so a repository cannot plant its own `node` (`.`, `node_modules/.bin`) in front of the
+ * gates. Returns `{ command }` or `{ error }`; never throws.
+ */
+export function hookRunner({ cwd = process.cwd(), env = process.env, bun = process.versions?.bun, platform = process.platform } = {}) {
+  if (!bun) return { command: process.execPath };
+  const project = realOrSelf(cwd);
+  const names = platform === 'win32'
+    ? String(env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';').filter(Boolean).map((ext) => `node${ext.toLowerCase()}`)
+    : ['node'];
+  const delimiter = platform === 'win32' ? ';' : ':';
+  for (const dir of String(env.PATH || env.Path || '').split(delimiter)) {
+    if (!dir || !path.isAbsolute(dir)) continue;
+    for (const name of names) {
+      const candidate = path.join(dir, name);
+      try {
+        if (!statSync(candidate).isFile()) continue;
+        if (platform !== 'win32') accessSync(candidate, constants.X_OK);
+      } catch { continue; }
+      if (isInside(project, realOrSelf(candidate))) continue;
+      return { command: candidate };
+    }
+  }
+  return { error: 'node was not found on PATH outside the project' };
+}
+
 /** Run one hook as a child process with a hard budget. Never throws. */
 export function dispatchHook(hookPath, payload, { cwd, timeoutMs = BRIDGE_TIMEOUT_MS } = {}) {
   return new Promise((resolve) => {
+    const runner = hookRunner({ cwd });
+    if (runner.error) {
+      resolve({ code: null, signal: null, stdout: '', stderr: runner.error, timedOut: false, failed: true });
+      return;
+    }
     let child;
     try {
-      child = spawn(process.execPath, [hookPath], {
+      child = spawn(runner.command, [hookPath], {
         cwd,
         env: { ...process.env, PROJECT_ROOT: cwd },
         stdio: ['pipe', 'pipe', 'pipe'],
@@ -159,7 +229,7 @@ export function dispatchHook(hookPath, payload, { cwd, timeoutMs = BRIDGE_TIMEOU
     child.stdout.on('data', (c) => out.push(c));
     child.stderr.on('data', (c) => err.push(c));
     child.on('error', (error) => { clearTimeout(timer); finish({ code: null, stdout: '', stderr: String(error?.message || error), timedOut: false, failed: true }); });
-    child.on('close', (code) => { clearTimeout(timer); finish({ code, stdout: Buffer.concat(out).toString('utf8'), stderr: Buffer.concat(err).toString('utf8'), timedOut: false, failed: false }); });
+    child.on('close', (code, signal) => { clearTimeout(timer); finish({ code, signal, stdout: Buffer.concat(out).toString('utf8'), stderr: Buffer.concat(err).toString('utf8'), timedOut: false, failed: false }); });
     try { child.stdin.write(JSON.stringify(payload)); child.stdin.end(); } catch { /* close handler still runs */ }
   });
 }
@@ -198,6 +268,12 @@ export async function runEvent(kind, event, ctx, { timeoutMs = BRIDGE_TIMEOUT_MS
     }
     const verdict = interpretVerdict(result, hookName);
     if (verdict.block) return { block: true, reason: verdict.reason, hook: hookName };
+    // A gate that dies without a verdict (a broken node shim, a crash, a kill) must not
+    // read as an allow: only 0 and 2 are answers a gate gives on purpose.
+    if (gating && result.code !== 0 && result.code !== 2) {
+      const how = result.signal ? `was killed by ${result.signal}` : `exited with code ${result.code}`;
+      return { block: true, reason: `CafeKit gate ${hookName} ${how}`, hook: hookName };
+    }
     if (verdict.inject) injections.push(verdict.inject);
   }
   return { block: false, inject: injections.join('\n\n') };

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

@@ -14,32 +14,23 @@
  * Exit: 0 (the JSON hook output carries the permission decision)
  */
 
-try {
-  const fs = require('fs');
-  const path = require('path');
-  const { commandAccess } = require('./lib/privacy-command-analysis.cjs');
+const EVALUATION_FAILURE = 'Sensitive access could not be evaluated safely.';
 
-  const RESTRICTED_PATTERNS = [
-    /^\.env(?:[.\[*?{]|$)/i,
-    /^credentials/i,
-    /secrets?\.(ya?ml|json)$/i,
-    /\.pem$/i,
-    /\.key$/i,
-    /\.p12$/i,
-    /\.pfx$/i,
-    /^id_(rsa|ed25519|ecdsa|dsa)$/i,
-    /\.netrc$/i,
-    /\.pgpass$/i,
-    /kubeconfig/i,
-    /\.keystore$/i,
-    /\.jks$/i,
-    /auth\.json$/i,
-    /token(s)?\.json$/i
-  ];
+function askForPermission(reason) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      // omp has no ask state on tool_call, so an ask under Claude becomes a denial here.
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason
+    }
+  }) + '\n');
+}
 
-  const ALLOWED_EXEMPTIONS = [
-    /\.env\.(example|sample|template|test)$/i
-  ];
+try {
+  const fs = require('fs');
+  const { sensitivePaths, displayNames } = require('./lib/privacy-paths.cjs');
+  const { projectRoot: resolveProjectRoot } = require('./lib/project-root.cjs');
 
   const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
   function readRuntime(cwd) {
@@ -51,200 +42,28 @@ try {
     }
   }
 
-  function isSafe(filePath) {
-    const base = path.basename(filePath);
-    return ALLOWED_EXEMPTIONS.some((rule) => rule.test(base) || rule.test(filePath));
-  }
-
-  function isSensitive(filePath) {
-    const base = path.basename(filePath);
-    return RESTRICTED_PATTERNS.some((rule) => rule.test(base) || rule.test(filePath));
-  }
-
-  /**
-   * Resolve a symlink to its real target so a harmless-looking name that points
-   * at a sensitive file cannot slip through the basename check. Returns null
-   * when the path cannot be resolved (missing file, broken link) — fail-open to
-   * the original-path check in that case. See isSymlinkToSensitive for dangling handling.
-   */
-  function resolveTarget(filePath, cwd) {
-    try {
-      const requested = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
-      return fs.realpathSync(requested);
-    } catch {
-      return null;
-    }
-  }
-
-  /**
-   * When realpath fails, check whether the requested path is a symlink (or chain)
-   * whose lexical target is sensitive. Dangling link to protected target -> true (fail-closed ask);
-   * dangling benign link or link to allowed example/template -> false (allow).
-   * Limit hops to avoid loops; malformed/looping -> fail closed.
-   * TOCTOU note: check and use are not atomic; target could be swapped between this check and the actual read.
-   * This is a best-effort guardrail, not an arbitrary-shell security boundary. For strong isolation use OS sandbox.
-   */
-  function isSymlinkToSensitive(filePath, cwd) {
-    try {
-      const requested = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
-      let current = requested;
-      let hops = 0;
-      const MAX_HOPS = 8;
-      while (hops < MAX_HOPS) {
-        let stat;
-        try {
-          stat = fs.lstatSync(current);
-        } catch {
-          return false;
-        }
-        if (!stat.isSymbolicLink()) return false;
-        let linkTarget;
-        try {
-          linkTarget = fs.readlinkSync(current);
-        } catch {
-          return true;
-        }
-        if (isSensitive(linkTarget) && !isSafe(linkTarget)) return true;
-        if (isSafe(linkTarget)) return false;
-        const next = path.isAbsolute(linkTarget) ? linkTarget : path.resolve(path.dirname(current), linkTarget);
-        if (next === current) return true;
-        try {
-          const real = fs.realpathSync(next);
-          if (isSensitive(real) && !isSafe(real)) return true;
-          if (isSafe(real)) return false;
-          return false;
-        } catch {
-          current = next;
-          hops += 1;
-          continue;
-        }
-      }
-      return true;
-    } catch {
-      return true;
-    }
-  }
-
-  function extractBashPaths(command) {
-    // The analyzer parses the command and returns the operands of every reading
-    // command it recognises, nested shells and `find -exec` included. Treating
-    // every unresolved expansion as sensitive, as this did before, asked on
-    // `cat $FILE`, `wc -l *.cjs` and `cat ~/.zshrc` alike. Noise is what trains
-    // people to click through the prompt that matters.
-    // A heredoc whose delimiter is quoted (<<'BODY') is inert: the shell
-    // expands nothing inside it, so no word in the body is ever read. The
-    // analyzer has no notion of heredocs and parses the body as shell, so prose
-    // that quotes a command -- a PR body carrying `cat .env` in backticks --
-    // came back as a real command substitution. Blank those bodies out first.
-    // An unquoted delimiter (<<BODY) does expand, so it is left to the
-    // analyzer.
-    const scrubbed = String(command).replace(
-      /(<<-?[ \t]*)(['"])([A-Za-z_]\w*)\2[^\n]*\n[\s\S]*?\n[ \t]*\3\b/g,
-      '$1$2$3$2'
-    );
-
-    const paths = new Set(commandAccess(scrubbed).paths);
-
-    // Two shapes the analyzer cannot return. It drops any word carrying an
-    // expansion, so `~/.ssh/id_rsa` and `certs/*.pem` still have to be matched
-    // by name. And it only walks commands it recognises, so an unknown tool
-    // handed a secret through a file-shaped option, such as
-    // `docker compose --env-file .env`, is invisible to it.
-    const FILE_OPTION = /^--?[\w-]*(?:file|config|key|cert|identity)$/i;
-    const tokens = scrubbed.split(/[\s|;&<>"'()`]+/);
-    for (let index = 0; index < tokens.length; index += 1) {
-      const token = tokens[index];
-      const shaped = /^~|[*?[{]/.test(token);
-      const optionFed = index > 0 && FILE_OPTION.test(tokens[index - 1]);
-      if (!shaped && !optionFed) continue;
-      const value = token.replace(/^~/, '').replace(/^["'()`]+|["'(),]+$/g, '');
-      if (value && isSensitive(value) && !isSafe(value)) paths.add(value);
-    }
-
-    return [...paths];
-  }
-
-  function extractPaths(toolName, input) {
-    const paths = [];
-    if (!input) return paths;
-
-    for (const key of ['file_path', 'path']) {
-      if (typeof input[key] === 'string' && input[key].trim()) {
-        paths.push(input[key].trim());
-      }
-    }
-
-    for (const key of ['paths', 'search_paths']) {
-      if (Array.isArray(input[key])) {
-        paths.push(...input[key].filter(Boolean));
-      }
-    }
-
-    if (toolName === 'Bash' && typeof input.command === 'string') {
-      paths.push(...extractBashPaths(input.command));
-    }
-
-    return paths.filter(Boolean);
-  }
-
-  function askForPermission(filePath) {
-    const basename = path.basename(filePath);
-    process.stdout.write(JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: 'PreToolUse',
-        // omp has no ask state on tool_call, so an ask under Claude becomes a denial here.
-        permissionDecision: 'deny',
-        permissionDecisionReason: `Sensitive file access requires approval: ${basename}`
-      }
-    }) + '\n');
-  }
-
   const stdin = fs.readFileSync(0, 'utf8').trim();
-  if (!stdin) process.exit(0);
+  if (!stdin) {
+    askForPermission(EVALUATION_FAILURE);
+    process.exit(0);
+  }
 
   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();
-  const runtime = readRuntime(cwd);
-
-  if (runtime.privacyBlock === false) process.exit(0);
-
-  const paths = extractPaths(toolName, toolInput);
-  if (!paths.length) process.exit(0);
+  const projectRoot = resolveProjectRoot(data);
+  const runtime = readRuntime(projectRoot);
 
-  for (const filePath of paths) {
-    const target = resolveTarget(filePath, cwd);
+  // A plugin is trusted once for every repository, so a repository cannot switch it off.
+  if (runtime.privacyBlock === false && !require('./lib/plugin-options.cjs').isPlugin()) process.exit(0);
 
-    // The real target is authoritative: an exempt-looking alias must not hide
-    // a sensitive target, while a real .env.example target remains safe.
-    if (target) {
-      if (isSensitive(target) && !isSafe(target)) {
-        askForPermission(filePath);
-        process.exit(0);
-      }
-      if (isSafe(target)) continue;
-    } else {
-      if (isSymlinkToSensitive(filePath, cwd)) {
-        askForPermission(filePath);
-        process.exit(0);
-      }
-    }
-
-    if (isSafe(filePath) || !isSensitive(filePath)) continue;
-    askForPermission(filePath);
-    process.exit(0);
-  }
+  const paths = sensitivePaths(toolName, toolInput, cwd);
+  if (paths.length) askForPermission(`Sensitive file access requires approval: ${displayNames(paths)}`);
 
   process.exit(0);
 } catch (_) {
-  process.stdout.write(JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: 'PreToolUse',
-      permissionDecision: 'deny',
-      permissionDecisionReason: 'Sensitive access could not be evaluated safely.'
-    }
-  }) + '\n');
+  askForPermission(EVALUATION_FAILURE);
   process.exit(0);
 }

package/src/codex/rules/state-sync.md

@@ -1,60 +0,0 @@
-# Process-first state synchronization
-
-## Primary file state
-
-For new work, `specs/<feature>/plan.md` and its direct-child
-`task-NN-*.md` files are canonical, hand-editable state. Task files stay flat
-beside the plan; indexes and host task views are disposable projections.
-
-Each task has exactly one `Status:` field using `pending`, `in_progress`,
-`paused`, `blocked`, or `done`. The controller is the sole writer of task
-status and proof. A task's final `## Receipt` is its only canonical execution
-proof.
-
-## Surgical synchronization
-
-Before changing state:
-
-1. read the plan row and the task's Outcome, Acceptance, Dependencies,
-   Verification Plan, Status, and Receipt;
-2. confirm every dependency and owned path at the requested boundary;
-3. edit only the observed Status, concrete blocker, implemented checkbox, or
-   Receipt; and
-4. re-read the file and confirm exactly one Status field and one Receipt
-   section.
-
-Starting or resuming changes only Status to `in_progress`. Blocking records a
-specific cause without creating proof. Do not replace a whole packet to make a
-state transition.
-
-Set `Status: done` only after the inline Receipt passes the
-`validateCanonicalReceipt` contract: exact command, `Exit: 0`,
-`Verification: PASS`, runtime-derived Base and Head values, and a non-empty
-fenced block of current command output.
-
-A done task is bound to live Base and Head only while its own task file has a copy in
-`HEAD` that its current bytes no longer match. A file that is committed and unchanged,
-and a file that was never committed at all, are both validated on structure alone: the
-first has a baseline it still matches, the second has no baseline to drift from, and
-committing a packet is the user's choice that a gitignored specs root removes entirely.
-Work elsewhere in the tree never reopens a receipt, because Base is the last commit
-touching anything outside the specs root, so every finished receipt records an older
-Base by construction. Every structural check runs in all cases.
-The gate detects drift, not invention: a valid
-Base and Head pair costs one command and no verification run, so neither mode proves
-that the command was executed. Missing, stale, contradictory,
-placeholder, copied, failure, or zero-test evidence leaves the task unfinished.
-
-Synchronization never fabricates commands, output, timestamps, completed
-work, reviewer identity, user approval, or product readiness. A passing command
-proves only the boundary it executed.
-
-## Human gates and workflow ownership
-
-- GATE-SCOPE records the user's scope decision before the plan is written.
-- GATE-REVIEW records the user's disposition of deduplicated adversarial findings.
-- Develop starts only after a new explicit user invocation and executes one
-  unblocked task at a time.
-- Sync changes only observed file state and never starts implementation.
-- GATE-DONE occurs after current receipts and limitations are shown; the user decides
-  whether the requested feature is complete.