@haposoft/cafekit 0.16.0-rc.8 → 0.16.1

package/src/codex/hooks/rules.cjs

@@ -5,6 +5,7 @@ const fs = require('fs');
 const path = require('path');
 const {
   getHookContext,
+  hookStateDir,
   logCrash,
   readPayload,
   resolveProjectPath
@@ -15,7 +16,7 @@ function reservationFile(projectRoot, sessionId) {
     .update(String(sessionId || 'unknown'))
     .digest('hex')
     .slice(0, 16);
-  return path.join(projectRoot, '.codex', 'hooks', '.logs', `rules-${key}.json`);
+  return path.join(hookStateDir(projectRoot), `rules-${key}.json`);
 }
 
 /** Reserve one injection slot per session. Returns null on reservation errors. */
@@ -35,6 +36,28 @@ function reserveSession(projectRoot, sessionId) {
   }
 }
 
+/**
+ * Body of the output style for `codingLevel`, or null.
+ *
+ * Codex CLI has no output-style feature, so the style Claude Code would load natively is
+ * injected here instead. The rules hook reserves one injection per session, so this costs
+ * the same as a host-loaded style rather than repeating every turn.
+ */
+function readCodingStyle(projectRoot, level) {
+  if (!Number.isInteger(level) || level < 0 || level > 5) return null;
+  try {
+    const dir = path.join(projectRoot, '.codex', 'output-styles');
+    const match = fs.readdirSync(dir).find((name) => name.startsWith(`coding-level-${level}-`));
+    if (!match) return null;
+    const raw = fs.readFileSync(path.join(dir, match), 'utf8');
+    // Strip the frontmatter Claude Code reads; Codex only needs the instructions.
+    const body = raw.replace(/^---\n[\s\S]*?\n---\n/, '').trim();
+    return body || null;
+  } catch {
+    return null;
+  }
+}
+
 function readRuntime(projectRoot) {
   try {
     const file = path.join(projectRoot, '.codex', 'runtime.json');
@@ -74,6 +97,11 @@ try {
     `- docs.maxLoc: ${runtime.docs?.maxLoc || 800} lines per doc file`
   );
 
+  const style = readCodingStyle(projectRoot, runtime.codingLevel);
+  if (style) {
+    lines.push('', '## Communication style', style);
+  }
+
   process.stdout.write(`${lines.join('\n')}\n`);
 } catch (error) {
   logCrash('rules', error);

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

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Copyright (c) 2026 Haposoft. MIT License.
+ *
+ * UserPromptSubmit hook — secret-output-guardrail.cjs (Codex)
+ *
+ * Mirror of the Claude hook. The privacy hook gates whether a sensitive file may be
+ * read; nothing gated whether an approved value may then be printed into the
+ * transcript, where it survives compaction and is replayed on every later turn.
+ *
+ * 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. Fail-open.
+ */
+
+const { logCrash, readPayload } = require('./lib/hook-context.cjs');
+const { REMINDER, containsSecretKeyword } = require('./lib/secret-keywords.cjs');
+
+try {
+  const payload = readPayload();
+  if (!payload) process.exit(0);
+
+  const prompt = String(payload.prompt || payload.user_prompt || '');
+  if (!containsSecretKeyword(prompt)) process.exit(0);
+
+  process.stdout.write(`${REMINDER}\n`);
+} catch (error) {
+  logCrash('secret-output-guardrail', error);
+}

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

@@ -6,6 +6,7 @@ const path = require('path');
 const {
   atomicWrite,
   getHookContext,
+  hookStateDir,
   logCrash,
   readPayload
 } = require('./lib/hook-context.cjs');
@@ -132,13 +133,7 @@ try {
   const currentStatuses = processWorkflow
     ? Object.fromEntries(Object.entries(registry).map(([taskPath, task]) => [taskPath, task?.status || 'pending']))
     : taskStatusMap(activeSpec);
-  const cacheFile = path.join(
-    projectRoot,
-    '.codex',
-    'hooks',
-    '.logs',
-    'spec-gate-last.json'
-  );
+  const cacheFile = path.join(hookStateDir(projectRoot), 'spec-gate-last.json');
   const cacheExists = fs.existsSync(cacheFile);
   let cache = {};
   if (cacheExists) {
@@ -169,7 +164,7 @@ 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, then use explicit sync-finalize.`
+      reason: `Completion gate: ${staleFlashTasks.length} task(s) marked done with FLASH_UNVERIFIED (${staleFlashTasks.join(', ')}). Run /cf:test, then use explicit sync-finalize.`
     })}\n`);
     process.exit(0);
   }

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

@@ -7,6 +7,7 @@ const path = require('path');
 const {
   atomicWrite,
   getHookContext,
+  hookStateDir,
   logCrash,
   readPayload
 } = require('./lib/hook-context.cjs');
@@ -21,7 +22,7 @@ function cacheFile(projectRoot, sessionId) {
     .update(String(sessionId || 'unknown'))
     .digest('hex')
     .slice(0, 16);
-  return path.join(projectRoot, '.codex', 'hooks', '.logs', `tollgate-${key}.txt`);
+  return path.join(hookStateDir(projectRoot), `tollgate-${key}.txt`);
 }
 
 try {
@@ -155,7 +156,7 @@ try {
     }
     lines.push(
       '- Sync each flat task `Status:` only after verified work; task proof belongs in that task\'s inline `## Receipt`.',
-      `- Workflow source: \`specs/${active.featureName}/plan.md\`; Stop revalidates every task currently marked done.`,
+      `- Workflow source: \`specs/${active.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.`,
       '- Hooks revalidate receipt bytes but never grant approval.'
     );
   } else {

package/src/codex/hooks.json

@@ -38,6 +38,11 @@
     "UserPromptSubmit": [
       {
         "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/secret-output-guardrail.cjs\"",
+            "commandWindows": "node \".codex/hooks/secret-output-guardrail.cjs\""
+          },
           {
             "type": "command",
             "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/privacy-approval.cjs\"",

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

@@ -30,7 +30,13 @@ 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. Missing, stale, contradictory,
+fenced block of current command output.
+
+A done task keeps that binding while its file differs from its committed bytes,
+and is validated on structure alone once the file is committed, unchanged, and the
+tree outside the specs root is clean. 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

package/src/codex/runtime.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "./runtime.schema.json",
   "privacyBlock": true,
   "inspect": {
     "enabled": true
@@ -23,6 +24,7 @@
     "thinkingLanguage": null,
     "responseLanguage": null
   },
+  "codingLevel": 1,
   "hooks": {},
   "assertions": []
 }

package/src/common/.env.example

@@ -8,7 +8,7 @@
 # ============================================
 
 # Google Gemini / AI Studio API key
-# Required for hapo:test Multimodal Visual checks
+# Required for cf:test Multimodal Visual checks
 # Get from: https://aistudio.google.com/apikey
 GEMINI_API_KEY=
 

package/src/omp/extensions/cafekit-bridge.mjs

@@ -0,0 +1,233 @@
+/**
+ * Copyright (c) 2026 Haposoft. MIT License.
+ *
+ * CafeKit bridge for Oh My Pi.
+ *
+ * omp has no hooks.json. It loads extensions from `.omp/extensions/` and emits lifecycle
+ * events to them. This extension is the only thing that stands between those events and
+ * CafeKit's gate scripts in `.omp/hooks/`: it shapes each omp event into the Claude-shaped
+ * 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:
+ *  - 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
+ *    shorter budget so a slow gate blocks with its own name instead of a generic reason.
+ *  - omp's `input` payload is `{ type, text, images, source }` with no session id or cwd.
+ *    Session-scoped hooks (`rules.cjs`) exit when the id is missing, so the bridge mints one
+ *    per load and reuses it; omp loads an extension once per session.
+ *  - `session_stop` carries `stop_hook_active`, the same field `spec-gate.cjs` uses to avoid
+ *    re-blocking its own continuation. The bridge honours it before dispatching anything.
+ *
+ * Not mapped, because omp has no such events: SubagentStart (`agent.cjs`) and SubagentStop
+ * (`semantic-review-authority.cjs`). Task 04 documents this gap for operators.
+ */
+
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Stay under omp's 30000 ms cut-off so our reason wins over its substitute. */
+export const BRIDGE_TIMEOUT_MS = 8000;
+
+/**
+ * omp event → the CafeKit hooks registered for the equivalent Claude event.
+ * 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_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', 'completion-authority.cjs', 'spec-state.cjs', 'usage.cjs'] },
+  tool_call:              { event: 'PreToolUse',       hooks: ['privacy-block.cjs', 'inspect-block.cjs', 'task-scaffold-guard.cjs'] },
+  tool_result:            { event: 'PostToolUse',      hooks: ['state.cjs', 'usage.cjs'] },
+  session_stop:           { event: 'Stop',             hooks: ['spec-gate.cjs', 'completion-authority.cjs', 'state.cjs'] },
+};
+
+/** One id per extension load. omp loads an extension once per session, so this is per-session. */
+const SESSION_ID = `omp-${randomUUID()}`;
+
+export function hooksDir() {
+  if (process.env.CAFEKIT_OMP_HOOKS_DIR) return process.env.CAFEKIT_OMP_HOOKS_DIR;
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'hooks');
+}
+
+/** 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,
+    cwd,
+  };
+  switch (kind) {
+    case 'session_start':
+      payload.source = event?.reason === 'resume' ? 'resume' : 'startup';
+      break;
+    case 'session_compact':
+      payload.source = 'compact';
+      break;
+    case 'session_before_compact':
+      payload.trigger = event?.reason === 'manual' ? 'manual' : 'auto';
+      break;
+    case 'input':
+      payload.prompt = typeof event?.text === 'string' ? event.text : '';
+      break;
+    case 'tool_call':
+      payload.tool_name = event?.toolName ?? event?.tool_name ?? '';
+      payload.tool_input = event?.input ?? {};
+      payload.tool_use_id = event?.toolCallId ?? null;
+      break;
+    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_use_id = event?.toolCallId ?? null;
+      break;
+    case 'session_stop':
+      payload.stop_hook_active = event?.stop_hook_active === true;
+      payload.last_assistant_message = event?.last_assistant_message ?? null;
+      break;
+    default:
+      break;
+  }
+  return payload;
+}
+
+/**
+ * Read a hook's verdict. No CafeKit hook writes a block reason to stderr; the three
+ * mechanisms in use are stdout JSON `decision:"block"`, stdout JSON
+ * `hookSpecificOutput.permissionDecision` of `deny` (or `ask`, which omp cannot express),
+ * and exit 2 with the reason on stdout. Anything else is an allow, and any stdout text
+ * that is not a verdict is context to inject.
+ */
+export function interpretVerdict({ code, stdout = '', stderr = '' }, hookName) {
+  const out = String(stdout).trim();
+  const lines = out ? out.split('\n') : [];
+  const inject = [];
+  let block = null;
+
+  for (const line of lines) {
+    let parsed = null;
+    try { parsed = JSON.parse(line); } catch { parsed = null; }
+    if (!parsed || typeof parsed !== 'object') { inject.push(line); continue; }
+
+    if (parsed.decision === 'block') {
+      block = block || { reason: parsed.reason || `Blocked by ${hookName}` };
+      continue;
+    }
+    const decision = parsed.hookSpecificOutput?.permissionDecision;
+    if (decision === 'deny' || decision === 'ask') {
+      block = block || { reason: parsed.hookSpecificOutput.permissionDecisionReason || `Blocked by ${hookName}` };
+      continue;
+    }
+    const extra = parsed.hookSpecificOutput?.additionalContext;
+    if (typeof extra === 'string' && extra) inject.push(extra);
+  }
+
+  if (!block && code === 2) {
+    block = { reason: out || String(stderr).trim() || `Blocked by ${hookName}` };
+  }
+  return { block: Boolean(block), reason: block?.reason, inject: inject.join('\n').trim() };
+}
+
+/** 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) => {
+    let child;
+    try {
+      child = spawn(process.execPath, [hookPath], {
+        cwd,
+        env: { ...process.env, PROJECT_ROOT: cwd },
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+    } catch (error) {
+      resolve({ code: null, stdout: '', stderr: String(error?.message || error), timedOut: false, failed: true });
+      return;
+    }
+    const out = []; const err = [];
+    let settled = false;
+    const finish = (result) => { if (!settled) { settled = true; resolve(result); } };
+    const timer = setTimeout(() => {
+      try { child.kill('SIGKILL'); } catch { /* already gone */ }
+      finish({ code: null, stdout: Buffer.concat(out).toString('utf8'), stderr: Buffer.concat(err).toString('utf8'), timedOut: true, failed: true });
+    }, timeoutMs);
+    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 }); });
+    try { child.stdin.write(JSON.stringify(payload)); child.stdin.end(); } catch { /* close handler still runs */ }
+  });
+}
+
+/**
+ * Dispatch every hook for an omp event and fold their verdicts. The first block wins and
+ * short-circuits; injected context from allowing hooks is concatenated. A hook that fails
+ * or times out on a gating event counts as a block naming that hook, matching omp's own
+ * fail-closed posture rather than fighting it.
+ */
+export async function runEvent(kind, event, ctx, { timeoutMs = BRIDGE_TIMEOUT_MS, dir = hooksDir() } = {}) {
+  const entry = DISPATCH[kind];
+  if (!entry) return { block: false, inject: '' };
+
+  // A Stop that omp re-fires after our own block must not block again (infinite loop).
+  if (kind === 'session_stop' && event?.stop_hook_active === true) return { block: false, inject: '', skipped: 'stop_hook_active' };
+
+  const gating = kind === 'tool_call' || kind === 'session_stop';
+  const payload = shapePayload(kind, event, ctx);
+  const injections = [];
+
+  for (const hookName of entry.hooks) {
+    const hookPath = path.join(dir, hookName);
+    if (!existsSync(hookPath)) {
+      // A missing gate must be loud on gating events; silently allowing is the worst outcome.
+      if (gating) return { block: true, reason: `CafeKit gate ${hookName} is not installed under ${dir}`, hook: hookName };
+      continue;
+    }
+    const result = await dispatchHook(hookPath, payload, { cwd: payload.cwd, timeoutMs });
+    if (result.failed) {
+      if (gating) {
+        const why = result.timedOut ? `exceeded ${timeoutMs} ms` : (result.stderr.trim() || 'failed to run');
+        return { block: true, reason: `CafeKit gate ${hookName} ${why}`, hook: hookName };
+      }
+      continue;
+    }
+    const verdict = interpretVerdict(result, hookName);
+    if (verdict.block) return { block: true, reason: verdict.reason, hook: hookName };
+    if (verdict.inject) injections.push(verdict.inject);
+  }
+  return { block: false, inject: injections.join('\n\n') };
+}
+
+/** Extension entry point: omp calls this once with its ExtensionAPI. */
+export default function cafekitBridge(pi) {
+  const opts = {};
+
+  pi.on('session_start', async (event, ctx) => { await runEvent('session_start', event, ctx, opts); });
+  pi.on('session_compact', async (event, ctx) => { await runEvent('session_compact', event, ctx, opts); });
+  pi.on('session_before_compact', async (event, ctx) => { await runEvent('session_before_compact', event, ctx, opts); });
+  pi.on('tool_result', async (event, ctx) => { await runEvent('tool_result', event, ctx, opts); });
+
+  pi.on('tool_call', async (event, ctx) => {
+    const r = await runEvent('tool_call', event, ctx, opts);
+    return r.block ? { block: true, reason: r.reason } : undefined;
+  });
+
+  // omp cannot block a prompt, so a hook's block reason on input is surfaced as context.
+  pi.on('input', async (event, ctx) => {
+    const r = await runEvent('input', event, ctx, opts);
+    const extra = [r.block ? r.reason : '', r.inject].filter(Boolean).join('\n\n');
+    if (!extra) return { action: 'continue' };
+    return { action: 'transform', text: `${event.text}\n\n${extra}`, images: event.images };
+  });
+
+  pi.on('session_stop', async (event, ctx) => {
+    const r = await runEvent('session_stop', event, ctx, opts);
+    if (r.block) return { decision: 'block', reason: r.reason };
+    return r.inject ? { continue: true, additionalContext: r.inject } : undefined;
+  });
+}

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

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2026 Haposoft. MIT License.
+ *
+ * PreToolUse Hook — privacy-block.cjs
+ *
+ * Claude Code CLI privacy gate for sensitive files.
+ *
+ * Runtime contract:
+ * - Sensitive access returns Claude Code's native PreToolUse "ask" decision
+ * - The same decision applies to direct tools and Bash commands
+ * - Symlinks are classified by their resolved target before their alias
+ *
+ * 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 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
+  ];
+
+  const ALLOWED_EXEMPTIONS = [
+    /\.env\.(example|sample|template|test)$/i
+  ];
+
+  const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
+  function readRuntime(cwd) {
+    try {
+      const file = runtimePath(cwd, 'runtime.json');
+      return fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : {};
+    } catch {
+      return {};
+    }
+  }
+
+  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);
+
+  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);
+
+  for (const filePath of paths) {
+    const target = resolveTarget(filePath, cwd);
+
+    // 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);
+  }
+
+  process.exit(0);
+} catch (_) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: 'Sensitive access could not be evaluated safely.'
+    }
+  }) + '\n');
+  process.exit(0);
+}