@haposoft/cafekit 0.18.1 → 0.18.2

package/bin/__tests__/omp-bridge.test.js

@@ -22,15 +22,18 @@ const MANIFEST = require(path.join(PACKAGE_ROOT, 'src/claude/migration-manifest.
  * The hooks an omp install runs: the Claude set the manifest ships, then `src/omp/hooks/`
  * written over it. Composed once under a dotted folder so runtime-dir.cjs derives `.omp`.
  */
-const COMPOSED_ROOT = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-omp-composed-'));
-const HOOKS = path.join(COMPOSED_ROOT, '.omp', 'hooks');
-for (const rel of MANIFEST.runtime.files.filter((f) => f.startsWith('hooks/'))) {
-  const target = path.join(COMPOSED_ROOT, '.omp', rel);
-  fs.mkdirSync(path.dirname(target), { recursive: true });
-  fs.copyFileSync(path.join(PACKAGE_ROOT, 'src/claude', rel), target);
+function composeOmp(root) {
+  for (const rel of MANIFEST.runtime.files.filter((f) => f.startsWith('hooks/'))) {
+    const target = path.join(root, '.omp', 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/omp/hooks'), path.join(root, '.omp', 'hooks'), { recursive: true });
+  fs.cpSync(path.join(PACKAGE_ROOT, 'src/claude/scripts'), path.join(root, '.omp', 'scripts'), { recursive: true });
+  return path.join(root, '.omp', 'hooks');
 }
-fs.cpSync(path.join(PACKAGE_ROOT, 'src/omp/hooks'), HOOKS, { recursive: true });
-fs.cpSync(path.join(PACKAGE_ROOT, 'src/claude/scripts'), path.join(COMPOSED_ROOT, '.omp', 'scripts'), { recursive: true });
+const COMPOSED_ROOT = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-omp-composed-'));
+const HOOKS = composeOmp(COMPOSED_ROOT);
 
 let bridge;
 test.before(async () => { bridge = await import(BRIDGE); });
@@ -49,10 +52,10 @@ function registered(eventName) {
     .filter(Boolean);
 }
 
-// Deliberate, named divergences while omp is not yet updated. Each must still be a real
-// difference, so the test fails (and the entry must go) once omp catches up.
-const CLAUDE_ONLY = { PostToolUse: ['spec-state.cjs'] };
-const OMP_ONLY = { SessionStart: ['docs-sync.cjs'] };
+// Deliberate, named divergences. Each must still be a real difference, so the test fails
+// (and the entry must go) once omp catches up.
+const CLAUDE_ONLY = {};
+const OMP_ONLY = {};
 
 test('the dispatch table mirrors settings.json for every event omp can deliver', () => {
   const { DISPATCH } = bridge;
@@ -169,3 +172,54 @@ test('input injections flow back as a transform that keeps the user text intact'
     assert.match(r.inject, /Secret handling/, 'secret-output-guardrail must inject on a credential prompt');
   } finally { fs.rmSync(root, { recursive: true, force: true }); }
 });
+
+test('the omp session id is used for every event that does not carry its own', () => {
+  const ctx = { cwd: '/tmp/project', sessionManager: { getSessionId: () => 'omp-session-1' } };
+  assert.equal(bridge.shapePayload('input', { text: 'hi' }, ctx).session_id, 'omp-session-1');
+  assert.equal(bridge.shapePayload('tool_result', { toolName: 'edit', input: {} }, ctx).session_id, 'omp-session-1');
+  assert.equal(bridge.shapePayload('session_stop', { session_id: 'omp-session-1' }, ctx).session_id, 'omp-session-1',
+    'session_stop carries the same id omp hands extensions, so touch and state stay in one place');
+  assert.ok(!bridge.DISPATCH.session_start.hooks.includes('docs-sync.cjs'), 'docs-sync runs on demand, as on Claude');
+});
+
+function ompPacket(root, name) {
+  const dir = path.join(root, 'specs', name);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'plan.md'), `# ${name}\nSpecs-Contract: process-first-ready-v1\n`);
+  fs.writeFileSync(path.join(dir, 'task-01-work.md'), ['# Task 01 — work', '', 'Status: pending', '',
+    '## Dependencies', '', '- none', '', '## Verification Plan', '', '- Command: node --test', ''].join('\n'));
+  return dir;
+}
+
+test('an omp edit inside a packet scopes the tollgate to it', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-omp-touch-'));
+  try {
+    const hooks = composeOmp(root);
+    const alpha = ompPacket(root, 'alpha');
+    ompPacket(root, 'beta');
+    const { spawnSync } = require('node:child_process');
+    for (const args of [['init', '-q'], ['config', 'user.email', 'cafekit@example.invalid'],
+      ['config', 'user.name', 'CafeKit Test'], ['commit', '--allow-empty', '-qm', 'fixture']]) {
+      assert.equal(spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' }).status, 0);
+    }
+    const session = (id) => ({ cwd: root, sessionManager: { getSessionId: () => id } });
+
+    const untouched = await bridge.runEvent('input', { text: 'Continue' }, session('omp-a'), { dir: hooks });
+    assert.doesNotMatch(untouched.inject, /Multiple active specs|Spec state changed/, 'a session that touched nothing hears nothing');
+
+    // A failed edit records nothing.
+    await bridge.runEvent('tool_result', { toolName: 'edit', input: { path: path.join(alpha, 'plan.md') }, content: [], isError: true },
+      session('omp-a'), { dir: hooks });
+    const afterFailure = await bridge.runEvent('input', { text: 'Continue' }, session('omp-a'), { dir: hooks });
+    assert.doesNotMatch(afterFailure.inject, /Multiple active specs|Spec state changed/, 'a failed edit records nothing');
+
+    await bridge.runEvent('tool_result', { toolName: 'edit', input: { path: path.join(alpha, 'plan.md') }, content: [], isError: false },
+      session('omp-a'), { dir: hooks });
+    // As on Claude, a session that touched one of two active packets is told about both.
+    const touched = await bridge.runEvent('input', { text: 'Continue' }, session('omp-a'), { dir: hooks });
+    assert.match(touched.inject, /Multiple active specs detected: alpha, beta/);
+
+    const other = await bridge.runEvent('input', { text: 'Continue' }, session('omp-b'), { dir: hooks });
+    assert.doesNotMatch(other.inject, /Multiple active specs|Spec state changed/, "another omp session's touch does not leak");
+  } finally { fs.rmSync(root, { recursive: true, force: true }); }
+});

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

@@ -133,11 +133,9 @@ function expectedOverlay(name) {
     source = source.replace(from, to);
   };
   if (name === 'privacy-block.cjs') {
-    edit("        permissionDecision: 'ask',\n        permissionDecisionReason: `Sensitive file access requires approval: ${basename}`\n",
-      "        // omp has no ask state on tool_call, so an ask under Claude becomes a denial here.\n"
-      + "        permissionDecision: 'deny',\n        permissionDecisionReason: `Sensitive file access requires approval: ${basename}`\n");
-    edit("      permissionDecision: 'ask',\n      permissionDecisionReason: 'Sensitive access could not be evaluated safely.'\n",
-      "      permissionDecision: 'deny',\n      permissionDecisionReason: 'Sensitive access could not be evaluated safely.'\n");
+    edit("      permissionDecision: 'ask',\n",
+      "      // omp has no ask state on tool_call, so an ask under Claude becomes a denial here.\n"
+      + "      permissionDecision: 'deny',\n");
   }
   return source;
 }
@@ -157,3 +155,11 @@ test('the fork differs from Claude only by its overlay', () => {
   assert.match(phase, /claudeHookFiles/, 'the phase must install the Claude set first');
   assert.match(phase, /overlayFiles/, 'the phase must write the overlay over it');
 });
+
+test('an empty stdin is denied under omp, where Claude asks', () => {
+  const result = spawnSync(process.execPath, [path.join(INSTALLED, 'privacy-block.cjs')], { input: '', encoding: 'utf8' });
+  assert.equal(result.status, 0, result.stderr);
+  const output = JSON.parse(result.stdout).hookSpecificOutput;
+  assert.equal(output.permissionDecision, 'deny');
+  assert.match(output.permissionDecisionReason, /Sensitive access could not be evaluated safely\./);
+});

package/bin/__tests__/orca-session.test.js

@@ -149,8 +149,15 @@ function composeCodexHookTree(root) {
     path.join(hooksDir, 'lib', 'hook-context.cjs'));
   fs.copyFileSync(path.join(PACKAGE_ROOT, 'src/codex/hooks/lib/privacy-state.cjs'),
     path.join(hooksDir, 'lib', 'privacy-state.cjs'));
+  fs.copyFileSync(path.join(PACKAGE_ROOT, 'src/codex/hooks/lib/rules-reservation.cjs'),
+    path.join(hooksDir, 'lib', 'rules-reservation.cjs'));
+  fs.copyFileSync(path.join(PACKAGE_ROOT, 'src/claude/hooks/lib/update-check.cjs'),
+    path.join(hooksDir, 'lib', 'update-check.cjs'));
   fs.copyFileSync(path.join(PACKAGE_ROOT, 'src/claude/hooks/lib/runtime-path-safety.cjs'),
     path.join(hooksDir, 'lib', 'runtime-path-safety.cjs'));
+  for (const name of ['privacy-paths.cjs', 'privacy-command-analysis.cjs']) {
+    fs.copyFileSync(path.join(PACKAGE_ROOT, 'src/claude/hooks/lib', name), path.join(hooksDir, 'lib', name));
+  }
   return path.join(hooksDir, 'session.cjs');
 }
 

package/bin/__tests__/privacy-paths.test.js

@@ -0,0 +1,317 @@
+'use strict';
+
+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, after } = require('node:test');
+const SOURCE = path.resolve(__dirname, '../../src');
+const roots = [];
+
+function fixture(host) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ck-privacy-paths-'));
+  roots.push(root);
+  if (host === 'codex') {
+    assert.equal(spawnSync('git', ['init', '-q', root]).status, 0);
+    const install = spawnSync(process.execPath, [path.resolve(__dirname, '../install.js'), '--platform', 'codex', '-y'], {
+      cwd: root, encoding: 'utf8',
+    });
+    assert.equal(install.status, 0, install.stderr);
+  } else {
+    fs.cpSync(path.join(SOURCE, 'claude/hooks'), path.join(root, '.claude/hooks'), { recursive: true });
+  }
+  return { root, hooks: path.join(root, `.${host}/hooks`) };
+}
+
+function invoke(f, tool_name, tool_input, spawnOptions = {}) {
+  const env = { ...process.env };
+  delete env.CLAUDE_PROJECT_DIR;
+  const result = spawnSync(process.execPath, [path.join(f.hooks, 'privacy-block.cjs')], {
+    cwd: f.cwd || f.root, encoding: 'utf8', env,
+    input: JSON.stringify({ tool_name, tool_input, cwd: f.cwd || f.root, session_id: 'privacy-paths-probe' }),
+    ...spawnOptions,
+  });
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(result.stderr, '', 'hook must not emit a stack trace');
+  return result.stdout.trim() ? JSON.parse(result.stdout).hookSpecificOutput : null;
+}
+
+after(() => {
+  for (const root of roots) {
+    const locked = path.join(root, 'locked');
+    if (fs.existsSync(locked)) fs.chmodSync(locked, 0o700);
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+const cases = [
+  ['Read sensitive', 'Read', { file_path: '.env' }, true],
+  ['Grep sensitive glob', 'Grep', { pattern: 'x', glob: '.env*' }, true],
+  ['NotebookEdit sensitive notebook_path', 'NotebookEdit', { notebook_path: '.env' }, true],
+  ['MCP path', 'mcp__fs__read_file', { path: '.env' }, true],
+  ['MCP nested file_path', 'mcp__x__y', { args: { file_path: 'certs/a.pem' } }, true],
+  ['MCP file uri', 'mcp__fs__read', root => ({ uri: `file://${root}/.env` }), true],
+  ['MCP source destination', 'mcp__fs__move_file', { source: '.env', destination: 'x' }, true],
+  ['MCP relative_path', 'mcp__s__read', { relative_path: '.env' }, true],
+  ['Bash sensitive operand', 'Bash', { command: 'cat .env' }, true],
+  ['Bash env-file option', 'Bash', { command: 'docker compose --env-file .env up' }, true],
+  ['shell argv bash -lc', 'shell', { command: ['bash', '-lc', 'cat .env'] }, true],
+  ['patch Update File', 'apply_patch', { command: '*** Begin Patch\n*** Update File: .env\n*** End Patch' }, true],
+  ['patch Move to', 'apply_patch', { command: '*** Begin Patch\n*** Update File: a.txt\n*** Move to: .env\n*** End Patch' }, true],
+  ['Read ordinary file', 'Read', { file_path: 'app.ts' }, false],
+  ['Read exempt .env.example', 'Read', { file_path: '.env.example' }, false],
+  ['Grep ordinary glob', 'Grep', { pattern: 'API_KEY', glob: '*.ts' }, false],
+  ['Bash ls', 'Bash', { command: 'ls' }, false],
+];
+
+for (const host of ['claude', 'codex']) {
+  const f = fixture(host);
+  for (const [name, tool, input, sensitive] of cases) {
+    test(`privacy-paths ${host}: ${name}`, () => {
+      const output = invoke(f, tool, typeof input === 'function' ? input(f.root) : input);
+      if (!sensitive) return assert.equal(output, null);
+      assert.equal(output?.permissionDecision, host === 'claude' ? 'ask' : 'deny');
+      if (host === 'codex') {
+        assert.match(output.permissionDecisionReason, /APPROVE CAFEKIT PRIVACY /);
+        assert.match(output.permissionDecisionReason, /y \(or yes \/ có\)/);
+      }
+    });
+  }
+}
+
+test('privacy-paths codex: missing shared lib denies even Bash ls', () => {
+  const f = fixture('codex');
+  fs.rmSync(path.join(f.hooks, 'lib/privacy-paths.cjs'), { force: true });
+  const output = invoke(f, 'Bash', { command: 'ls' });
+  assert.equal(output?.permissionDecision, 'deny');
+  assert.match(output.permissionDecisionReason, /could not be evaluated safely/);
+});
+
+test('privacy-paths: unavailable glob matcher keeps sensitive children', () => {
+  const f = fixture('claude');
+  fs.writeFileSync(path.join(f.root, 'credentials.json'), '');
+  const { sensitivePaths } = require(path.join(SOURCE, 'claude/hooks/lib/privacy-paths.cjs'));
+  const original = path.matchesGlob;
+  try {
+    path.matchesGlob = undefined;
+    let paths;
+    assert.doesNotThrow(() => { paths = sensitivePaths('Grep', { glob: '*.ts' }, f.root); });
+    assert.ok(paths.includes(path.join(f.root, 'credentials.json')));
+  } finally {
+    path.matchesGlob = original;
+  }
+});
+
+const runtimeWrites = [
+  ['Write runtime', 'Write', { file_path: '.claude/runtime.json' }],
+  ['Edit runtime', 'Edit', { file_path: '.codex/runtime.json' }],
+  ['NotebookEdit runtime', 'NotebookEdit', { notebook_path: '.omp/runtime.json' }],
+  ['patch approval directory', 'apply_patch', { command: '*** Begin Patch\n*** Add File: .codex/hooks/.privacy/g.json\n*** End Patch' }],
+  ['MCP runtime', 'mcp__fs__write_file', { path: '.claude/runtime.json' }],
+  ['MultiEdit runtime', 'MultiEdit', { edits: [{ file_path: '.claude/runtime.json' }] }],
+  ['Write backslash runtime', 'Write', { file_path: '.CLAUDE\\RUNTIME.JSON' }],
+  ['symlink directory Write', 'Write', { file_path: 'c/runtime.json' }],
+  ['symlink directory shell', 'Bash', { command: "echo '{}' > c/runtime.json" }],
+  ['dangling approval symlink', 'Write', { file_path: 'links/lnk2' }],
+  ['dangling runtime symlink', 'Write', { file_path: 'links/lnk-runtime' }],
+  ['chained approval symlink', 'Bash', { command: 'echo x > links/t1' }],
+  ['chained runtime symlink', 'Bash', { command: 'echo x > links/r1' }],
+  ['looping write symlink', 'Bash', { command: 'echo x > links/loop1' }],
+  ...[
+    'cp -r evil/.claude .', 'mv evil/.codex .', 'cp -r evil/.omp .', 'mv evil/.privacy .',
+  ].map(command => [`runtime directory source ${command}`, 'Bash', { command }]),
+  ['clobber redirect', 'Bash', { command: 'echo x >| .claude/runtime.json' }],
+  ['quoted heredoc header tail', 'Bash', { command: "cat <<'EOF' > .claude/runtime.json\n{}\nEOF" }],
+  ...[
+    'cd "$PWD/.claude" && echo \'{}\' > runtime.json',
+    'cd $(pwd)/.claude && cp /tmp/r runtime.json',
+  ].map(command => [`dynamic directory ${command}`, 'Bash', { command }]),
+  ...[
+    'cp /tmp/r.json .claude/runtime.json > /dev/null',
+    'cp /tmp/r.json .claude/runtime.json 2>&1',
+    'mv r .codex/runtime.json 2>/dev/null',
+    'install r .omp/runtime.json > /dev/null',
+    'ln r .claude/runtime.json 2>&1',
+    'cp /tmp/r.json .claude/runtime.json < /dev/null',
+    'cp /tmp/r.json .claude/runtime.json <<< x',
+    'cp a .claude/runtime.json 0</dev/null',
+    'cp a .claude/runtime.json 0< /dev/null',
+    'cp a .claude/runtime.json 3</dev/null',
+  ].map(command => [`redirect operands ${command}`, 'Bash', { command }]),
+  ...[
+    "echo '{}' > .claude/runtime.json", "echo '{}' > .CLAUDE/RUNTIME.JSON",
+    'echo x >> .claude/./runtime.json', 'tee .codex//runtime.json',
+    'sed -i s/a/b/ .omp/runtime.json', 'cp r.json .claude/',
+    'mv r.json .codex/runtime.json', 'cp t .codex/hooks/./.privacy/',
+    'cd .claude && cp /tmp/r.json runtime.json', 'echo x > sub/.claude/runtime.json',
+    'install r.json .omp/', 'ln r.json .codex/runtime.json',
+    'pushd .codex && echo x > runtime.json',
+    "sed -ni 's/a/b/p' .claude/runtime.json", 'cp -t.claude r.json',
+    'cd .claude && echo "$(echo x > runtime.json)"',
+  ].map(command => [command, 'Bash', { command }]),
+];
+const runtimeAllowed = [
+  ['Read runtime', 'Read', { file_path: '.claude/runtime.json' }],
+  ['cat .codex/runtime.json', 'Bash', { command: 'cat .codex/runtime.json' }],
+  ['jq .paths .claude/runtime.json', 'Bash', { command: 'jq .paths .claude/runtime.json' }],
+  ['Write ordinary runtime', 'Write', { file_path: 'docs/runtime.json' }],
+  ['Write resolved ordinary runtime', 'Write', { file_path: '.claude/../docs/runtime.json' }],
+];
+
+for (const host of ['claude', 'codex']) {
+  const f = fixture(host);
+  fs.mkdirSync(path.join(f.root, '.claude'), { recursive: true });
+  fs.symlinkSync('.claude', path.join(f.root, 'c'), 'dir');
+  fs.mkdirSync(path.join(f.root, 'links'));
+  fs.symlinkSync('../.codex/hooks/.privacy/g.json', path.join(f.root, 'links/lnk2'));
+  fs.symlinkSync('../.claude/runtime.json', path.join(f.root, 'links/lnk-runtime'));
+  fs.symlinkSync('t2', path.join(f.root, 'links/t1'));
+  fs.symlinkSync('../.codex/hooks/.privacy/g.json', path.join(f.root, 'links/t2'));
+  fs.symlinkSync('r2', path.join(f.root, 'links/r1'));
+  fs.symlinkSync('../.claude/runtime.json', path.join(f.root, 'links/r2'));
+  fs.symlinkSync('loop2', path.join(f.root, 'links/loop1'));
+  fs.symlinkSync('loop1', path.join(f.root, 'links/loop2'));
+  for (const name of ['.claude', '.codex', '.omp', '.privacy']) {
+    const directory = path.join(f.root, 'evil', name);
+    fs.mkdirSync(directory, { recursive: true });
+    fs.writeFileSync(path.join(directory, 'runtime.json'), '{}');
+  }
+  for (const [name, tool, input] of runtimeWrites) {
+    test(`privacy-paths ${host}: runtime writes ${name}`, () => {
+      const output = invoke(f, tool, input);
+      assert.equal(output?.permissionDecision, host === 'claude' ? 'ask' : 'deny');
+      assert.doesNotMatch(output.permissionDecisionReason, /could not be evaluated safely/);
+      if (host === 'codex') {
+        assert.match(output.permissionDecisionReason, /APPROVE CAFEKIT PRIVACY /);
+        assert.match(output.permissionDecisionReason, /y \(or yes \/ có\)/);
+      }
+    });
+  }
+  for (const [name, tool, input] of runtimeAllowed) {
+    test(`privacy-paths ${host}: runtime allows ${name}`, () => assert.equal(invoke(f, tool, input), null));
+  }
+}
+
+test('privacy-paths claude: subdirectory switch cannot disable root privacy', () => {
+  const f = fixture('claude');
+  const cwd = path.join(f.root, 'sub');
+  fs.mkdirSync(path.join(cwd, '.claude'), { recursive: true });
+  fs.writeFileSync(path.join(cwd, '.claude/runtime.json'), JSON.stringify({ privacyBlock: false }));
+  fs.writeFileSync(path.join(f.root, '.env'), '');
+  assert.equal(invoke({ ...f, cwd }, 'Read', { file_path: '../.env' })?.permissionDecision, 'ask');
+});
+
+test('privacy-paths claude: root switch still allows a manual opt-out', () => {
+  const f = fixture('claude');
+  fs.writeFileSync(path.join(f.root, '.claude/runtime.json'), JSON.stringify({ privacyBlock: false }));
+  fs.writeFileSync(path.join(f.root, '.env'), '');
+  assert.equal(invoke(f, 'Read', { file_path: '.env' }), null);
+});
+
+const recursiveSensitive = [
+  'grep -r API_KEY .', 'grep -rn API_KEY .', 'grep -Rin key .', 'grep -rl KEY .',
+  'grep --recursive KEY .', 'grep -d recurse KEY .', 'grep -R KEY', 'grep -r KEY src .',
+  "bash -c 'grep -rn KEY .'", 'echo . | xargs grep -r KEY',
+  'rg KEY .', 'rg --hidden KEY .', 'rg -u -u KEY .',
+  "rg --hidden -g '!*.ts' KEY .", "grep -r --include='*' KEY .",
+  'grep -r --include .env KEY .', "grep -r --include='.e*' KEY .",
+  'grep -R KEY linked', 'ag KEY .', 'rg -uu KEY .', 'rg -. KEY .',
+  'grep --dereference-recursive KEY .', 'grep --directories=recurse KEY .',
+  "find src -exec grep -rn KEY . \\;",
+  "rg --iglob 'CREDENTIALS.JSON' KEY .", "rg --glob-case-insensitive -g 'CREDENTIALS.JSON' KEY .",
+  "rg -g '*.ts' --iglob 'CREDENTIALS.JSON' KEY .", "rg -uug '*' KEY hidden",
+];
+const recursiveAllowed = [
+  'grep -r KEY src', 'grep -r --include=*.ts KEY .', "rg -g '*.ts' KEY .",
+  'grep -r KEY app.ts', 'grep -r KEY nope/', 'grep KEY .', 'grep -r KEY examples',
+  'rg --files src', 'grep -reKEY src',
+];
+const recursiveGrep = [
+  { pattern: 'KEY' }, { pattern: 'KEY', path: '.' },
+  { pattern: 'KEY', glob: '*' }, { pattern: 'KEY', glob: '.*' },
+  { pattern: 'KEY', glob: '*.{env,json}' },
+];
+
+for (const host of ['claude', 'codex']) {
+  const f = fixture(host);
+  for (const name of ['.env', 'credentials.json', '.env.example', 'app.ts']) {
+    fs.writeFileSync(path.join(f.root, name), '');
+  }
+  for (const dir of ['src', 'linked', 'examples', 'locked', 'hidden', 'a']) fs.mkdirSync(path.join(f.root, dir));
+  fs.symlinkSync('../.env', path.join(f.root, 'linked/notes.txt'));
+  fs.writeFileSync(path.join(f.root, 'examples/.env.example'), '');
+  fs.writeFileSync(path.join(f.root, 'hidden/.env'), '');
+  fs.writeFileSync(path.join(f.root, 'a/.env'), '');
+  fs.writeFileSync(path.join(f.root, 'aws-production-service-account-credentials-backup-2026.json'), '');
+  const wildcardDirectory = path.join(f.root, 'wildcard-count');
+  fs.mkdirSync(wildcardDirectory);
+  fs.writeFileSync(path.join(wildcardDirectory, `credentials${'a'.repeat(200)}b.json`), '');
+  fs.writeFileSync(path.join(f.root, 'locked/credentials.json'), '');
+  const locked = path.join(f.root, 'locked');
+  fs.chmodSync(locked, 0);
+  const probe = (name, tool, input, sensitive, options = {}) => test(`privacy-paths ${host}: recursive ${name}`, options, () => {
+    const output = invoke(f, tool, input, options.timeout
+      ? { timeout: options.timeout - 1000, killSignal: 'SIGKILL' } : {});
+    if (!sensitive) return assert.equal(output, null);
+    assert.equal(output?.permissionDecision, host === 'claude' ? 'ask' : 'deny');
+    if (host === 'codex') {
+      assert.match(output.permissionDecisionReason, /APPROVE CAFEKIT PRIVACY /);
+      assert.match(output.permissionDecisionReason, /y \(or yes \/ có\)/);
+    }
+  });
+  for (const command of recursiveSensitive) probe(command, 'Bash', { command }, true);
+  for (const input of recursiveGrep) probe(`Grep ${JSON.stringify(input)}`, 'Grep', input, true);
+  for (const command of ["rg -g '/credentials.json' KEY", "rg -g '/*.json' KEY", "rg --hidden -g '/.e*' KEY"]) {
+    probe(`anchored ${command}`, 'Bash', { command }, true);
+  }
+  probe('anchored Grep glob', 'Grep', { pattern: 'KEY', glob: '/*.json' }, true);
+  probe('bounded glob shell range', 'Bash', { command: "rg -g '{1..100000}' -g '*' KEY ." }, true, { timeout: 10000 });
+  probe('bounded glob Grep range', 'Grep', { glob: '{1..100000}' }, true, { timeout: 10000 });
+  probe('bounded glob Grep length', 'Grep', { glob: 'x'.repeat(257) }, true, { timeout: 10000 });
+  probe('bounded combinations shell', 'Bash', {
+    command: `rg -g '${'{a,b}'.repeat(20)}' -g '*' KEY .`,
+  }, true, { timeout: 10000 });
+  probe('bounded combinations nested Grep', 'Grep', {
+    glob: '{a,{b,{c,{d,e}}}}'.repeat(12),
+  }, true, { timeout: 10000 });
+  probe('bounded combinations narrow Grep', 'Grep', {
+    path: '.', glob: '*.{ts,tsx}',
+  }, false, { timeout: 10000 });
+  probe('narrow grammar escaped braces shell', 'Bash', {
+    command: `rg -g '${'\\{a,b\\}'.repeat(20)}' -g '*' KEY .`,
+  }, true, { timeout: 10000 });
+  probe('narrow grammar repeated wildcards Grep', 'Grep', {
+    path: '.', globs: [`${'*?'.repeat(20)}z`, '*'],
+  }, true, { timeout: 10000 });
+  probe('narrow grammar extglob Grep', 'Grep', {
+    glob: '+(a|*)'.repeat(10),
+  }, true, { timeout: 10000 });
+  probe('total wildcard count in brace Grep', 'Grep', {
+    path: 'wildcard-count', globs: ['{*a*a*a*a*az,q}', '*'],
+  }, true, { timeout: 10000 });
+  for (const command of ['rg --unrestricted --unrestricted KEY a', 'rg -.n KEY a', 'ag -u KEY a', 'ag --unrestricted KEY a']) {
+    probe(`hidden flags ${command}`, 'Bash', { command }, true);
+  }
+  for (const input of [{ path: 1 }, { glob: ['*'] }, { globs: 5 }]) {
+    test(`privacy-paths ${host}: malformed Grep ${JSON.stringify(input)}`, () => {
+      const { sensitivePaths } = require(path.join(SOURCE, 'claude/hooks/lib/privacy-paths.cjs'));
+      let paths;
+      assert.doesNotThrow(() => { paths = sensitivePaths('Grep', input, f.root); });
+      assert.ok(paths.includes(path.join(f.root, 'credentials.json')));
+      const output = invoke(f, 'Grep', input);
+      assert.equal(output?.permissionDecision, host === 'claude' ? 'ask' : 'deny');
+      assert.doesNotMatch(output.permissionDecisionReason, /could not be evaluated safely/);
+      if (host === 'codex') {
+        assert.match(output.permissionDecisionReason, /APPROVE CAFEKIT PRIVACY /);
+        assert.match(output.permissionDecisionReason, /y \(or yes \/ có\)/);
+      }
+    });
+  }
+  for (const command of recursiveAllowed) probe(command, 'Bash', { command }, false);
+  probe('Grep narrow glob', 'Grep', { pattern: 'KEY', path: '.', glob: '*.ts' }, false);
+  probe('Grep narrow recursive glob', 'Grep', { pattern: 'KEY', path: '.', glob: '**/*.ts' }, false);
+  probe('grep -r KEY locked/', 'Bash', { command: 'grep -r KEY locked/' }, false, {
+    skip: typeof process.getuid === 'function' && process.getuid() === 0,
+  });
+}

package/bin/__tests__/usage-hook-retired.test.js

@@ -38,6 +38,7 @@ function install(root, platforms) {
   const result = spawnSync(process.execPath, [INSTALLER, '--platform', platforms.join(','), '--yes'],
     { cwd: root, encoding: 'utf8', env: { ...process.env, PATH: '/usr/bin:/bin' } });
   assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+  return result;
 }
 
 function commands(settings) {
@@ -55,7 +56,7 @@ test('fresh claude install ships no usage hook', () => {
   });
 });
 
-test('upgrade removes an installed usage hook and its CafeKit entries but keeps a foreign one', () => {
+test('upgrade preserves an edited usage hook while removing its CafeKit entries', () => {
   inTempProject((root) => {
     install(root, ['claude']);
     const settingsPath = path.join(root, '.claude', 'settings.json');
@@ -74,8 +75,9 @@ test('upgrade removes an installed usage hook and its CafeKit entries but keeps
     });
     fs.writeFileSync(settingsPath, JSON.stringify(before, null, 2));
 
-    install(root, ['claude']);
-    assert.equal(fs.existsSync(path.join(root, '.claude', 'hooks', 'usage.cjs')), false, 'an edited copy is removed too');
+    const upgrade = install(root, ['claude']);
+    assert.equal(fs.readFileSync(path.join(root, '.claude', 'hooks', 'usage.cjs'), 'utf8'), '// user edit\n');
+    assert.match(upgrade.stdout + upgrade.stderr, /Preserved 1 obsolete runtime/);
     const after = commands(JSON.parse(fs.readFileSync(settingsPath, 'utf8')));
     assert.equal(after.includes(CAFEKIT_USAGE_COMMAND), false, 'both CafeKit entries are pruned');
     assert.equal(after.includes(FOREIGN_USAGE_COMMAND), true, 'a hook outside .claude/hooks/ survives');

package/bin/install.js

@@ -16,6 +16,7 @@
  */
 
 const { spawnSync } = require('child_process');
+const fs = require('fs');
 const { buildContext, PLATFORMS, packageJson } = require('./lib/context');
 const lock = require('./lib/lock');
 const backup = require('./lib/backup');
@@ -45,6 +46,28 @@ const { runPostInstall } = require('./phases/post-install');
 const { setupSkillDeps } = require('./phases/skills-setup');
 const { printSummary } = require('./phases/summary');
 
+function preflightTrackedRootFiles(ctx) {
+  const files = ['AGENTS.md'];
+  if (ctx.platforms.includes('claude')) files.push('CLAUDE.md');
+  for (const file of files) {
+    try {
+      fs.lstatSync(file);
+      continue;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    const result = spawnSync('git', ['ls-files', '-v', '--error-unmatch', '--', file], {
+      cwd: process.cwd(), encoding: 'utf8', timeout: 3000, shell: false,
+    });
+    if (!result.error && result.status === 0) {
+      if (result.stdout[0]?.toUpperCase() === 'S') continue;
+      throw new Error(`${file} is tracked by git but missing from the working tree; restore it with \`git checkout -- ${file}\`, or \`git rm ${file}\` if the deletion is intended, then rerun the installer.`);
+    }
+    if (!result.error && (result.status === 1 || /not a git repository/i.test(result.stderr || ''))) continue;
+    ctx.ui.warn(`Could not confirm git state for ${file}; installing a fresh copy.`);
+  }
+}
+
 /** Install a single platform: payload + runtime + metadata, under one spinner. */
 function installPlatform(ctx, platformKey) {
   const platform = PLATFORMS[platformKey];
@@ -175,6 +198,8 @@ async function main() {
     await selectDocumentSkills(ctx);
     if (ctx.cancelled) { lock.release(); process.exit(0); }
 
+    preflightTrackedRootFiles(ctx);
+
     // ── Pre-run snapshot for rollback ─────────────────────
     // Capture platform folders AND the root files the pipeline mutates
     // (CLAUDE.md, .gitignore) so a mid-run failure rolls back cleanly.