@haposoft/cafekit 0.18.1 → 0.18.3

package/bin/__tests__/codex-setup-agents.test.js

@@ -0,0 +1,216 @@
+'use strict';
+
+// Codex loads no agents from a plugin, so the plugin ships them as TOML with an
+// ownership marker and a script copies them into the user's Codex agents directory.
+// The script replaces only files whose marker hash still matches their body.
+
+const { test, before, after } = require('node:test');
+const assert = require('node:assert/strict');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const SCRIPTS = path.resolve(__dirname, '../../scripts');
+const SRC = path.resolve(__dirname, '../../src');
+const { convertCodexAgentContent, codexAgentName } = require('../lib/codex-install.js');
+const { CODEX_POLICY_FILE, CODEX_EXPLICIT_ONLY_POLICY } = require('../phases/copy-payload.js');
+const MARKER = /^# CafeKit agent: plugin=(\S+) version=(\S+) sha256=([0-9a-f]{64})\n/;
+const REAL_AGENTS = path.join(os.homedir(), '.codex', 'agents');
+let work;
+let tree;
+let agentNames;
+let realBefore;
+
+const sha256 = (text) => crypto.createHash('sha256').update(text).digest('hex');
+
+function realState() {
+  try {
+    const stat = fs.statSync(REAL_AGENTS);
+    return `${stat.mtimeMs}:${fs.readdirSync(REAL_AGENTS).sort().join(',')}`;
+  } catch {
+    return 'absent';
+  }
+}
+
+before(async () => {
+  realBefore = realState();
+  work = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ck-codex-agents-')));
+  const lib = await import(path.join(SCRIPTS, 'build-codex-plugin.mjs'));
+  const claudeLib = await import(path.join(SCRIPTS, 'build-claude-plugin.mjs'));
+  agentNames = claudeLib.inScopeAgents();
+  tree = lib.build(path.join(work, 'plugin', 'cf-codex'));
+});
+
+after(() => {
+  fs.rmSync(work, { recursive: true, force: true });
+  assert.equal(realState(), realBefore, 'the real ~/.codex/agents changed');
+});
+
+let caseCount = 0;
+function setup() {
+  const dir = path.join(work, `case-${++caseCount}`);
+  const home = path.join(dir, 'home');
+  const repo = path.join(dir, 'repo');
+  fs.mkdirSync(home, { recursive: true });
+  fs.mkdirSync(repo, { recursive: true });
+  spawnSync('git', ['init', '-q'], { cwd: repo });
+  return { home, repo, agents: path.join(home, '.codex', 'agents') };
+}
+
+function setupAgents({ home, repo }, args = [], codexHome) {
+  const env = { ...process.env, HOME: home };
+  delete env.CODEX_HOME;
+  if (codexHome !== undefined) env.CODEX_HOME = codexHome;
+  return spawnSync('node', [path.join(tree, 'scripts/setup-agents.cjs'), ...args], { cwd: repo, encoding: 'utf8', env });
+}
+
+function shipped(name) {
+  return fs.readFileSync(path.join(tree, 'agents', name), 'utf8');
+}
+
+// An older CafeKit release of the same agent: a valid marker over a different body.
+function olderOwn(name) {
+  const body = `name = "${name.replace(/\.toml$/, '')}"\ndescription = "an older release"\ndeveloper_instructions = "old"\n`;
+  return `# CafeKit agent: plugin=cf version=0.0.1 sha256=${sha256(body)}\n${body}`;
+}
+
+test('agents-built-with-hash-marker: every in-scope agent ships as TOML whose marker hashes its body', () => {
+  const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../../package.json'), 'utf8'));
+  const files = fs.readdirSync(path.join(tree, 'agents')).sort();
+  assert.deepEqual(files, agentNames.map((agent) => `${codexAgentName(agent)}.toml`).sort());
+  for (const agent of agentNames) {
+    const text = shipped(`${codexAgentName(agent)}.toml`);
+    const [marker, plugin, version, digest] = text.match(MARKER) || [];
+    assert.ok(marker, `${agent} has no marker`);
+    assert.equal(plugin, 'cf');
+    assert.equal(version, pkg.version);
+    const body = text.slice(marker.length);
+    assert.equal(sha256(body), digest, agent);
+    assert.equal(body, convertCodexAgentContent(fs.readFileSync(path.join(SRC, 'claude/agents', `${agent}.md`), 'utf8'), `${agent}.md`), `${agent} differs from the npx conversion`);
+  }
+});
+
+test('write-when-absent: an empty agents directory receives every shipped agent', () => {
+  const ctx = setup();
+  const result = setupAgents(ctx);
+  assert.equal(result.status, 0, result.stderr);
+  const files = fs.readdirSync(path.join(tree, 'agents')).sort();
+  assert.deepEqual(fs.readdirSync(ctx.agents).sort(), files);
+  for (const file of files) assert.equal(fs.readFileSync(path.join(ctx.agents, file), 'utf8'), shipped(file), file);
+  assert.equal(result.stdout.match(/^written: /gm).length, files.length);
+});
+
+test('replace-own-unmodified: an unedited agent from an older release is replaced', () => {
+  const ctx = setup();
+  fs.mkdirSync(ctx.agents, { recursive: true });
+  fs.writeFileSync(path.join(ctx.agents, 'test_runner.toml'), olderOwn('test_runner.toml'));
+  const result = setupAgents(ctx);
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(fs.readFileSync(path.join(ctx.agents, 'test_runner.toml'), 'utf8'), shipped('test_runner.toml'));
+  assert.match(result.stdout, /^replaced: .*test_runner\.toml$/m);
+});
+
+test('keep-modified-own: an agent whose body was edited under the marker keeps its bytes', () => {
+  const ctx = setup();
+  fs.mkdirSync(ctx.agents, { recursive: true });
+  const edited = `${shipped('code_auditor.toml')}# my own note\n`;
+  fs.writeFileSync(path.join(ctx.agents, 'code_auditor.toml'), edited);
+  const result = setupAgents(ctx);
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(sha256(fs.readFileSync(path.join(ctx.agents, 'code_auditor.toml'), 'utf8')), sha256(edited));
+  assert.match(result.stdout, /^kept \(modified\): .*code_auditor\.toml$/m);
+});
+
+test('keep-foreign: a file CafeKit did not install keeps its bytes', () => {
+  const ctx = setup();
+  fs.mkdirSync(ctx.agents, { recursive: true });
+  const foreign = 'name = "debugger"\ndescription = "mine"\ndeveloper_instructions = "mine"\n';
+  fs.writeFileSync(path.join(ctx.agents, 'debugger.toml'), foreign);
+  const result = setupAgents(ctx);
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(fs.readFileSync(path.join(ctx.agents, 'debugger.toml'), 'utf8'), foreign);
+  assert.match(result.stdout, /^kept \(not installed by CafeKit\): .*debugger\.toml$/m);
+});
+
+test('mode-preserved: replacing an owned agent keeps its file mode', () => {
+  const ctx = setup();
+  fs.mkdirSync(ctx.agents, { recursive: true });
+  const file = path.join(ctx.agents, 'implementer.toml');
+  fs.writeFileSync(file, olderOwn('implementer.toml'), { mode: 0o600 });
+  fs.chmodSync(file, 0o600);
+  const result = setupAgents(ctx);
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(fs.readFileSync(file, 'utf8'), shipped('implementer.toml'));
+  assert.equal(fs.statSync(file).mode & 0o777, 0o600);
+  assert.deepEqual(fs.readdirSync(ctx.agents).filter((f) => f.endsWith('.tmp')), [], 'a temp file was left behind');
+});
+
+test('codex-home-honored: an absolute CODEX_HOME receives the agents and a relative one is refused', () => {
+  const ctx = setup();
+  const codexHome = path.join(ctx.home, 'custom-codex-home');
+  const result = setupAgents(ctx, [], codexHome);
+  assert.equal(result.status, 0, result.stderr);
+  assert.deepEqual(fs.readdirSync(path.join(codexHome, 'agents')).sort(), fs.readdirSync(path.join(tree, 'agents')).sort());
+  assert.ok(!fs.existsSync(path.join(ctx.home, '.codex')), 'agents also went to ~/.codex');
+  const refused = setup();
+  const relative = setupAgents(refused, [], 'relative-home');
+  assert.equal(relative.status, 1);
+  assert.match(relative.stderr, /CODEX_HOME must be an absolute path/);
+  assert.ok(!fs.existsSync(path.join(refused.repo, 'relative-home')) && !fs.existsSync(path.join(refused.home, '.codex')), 'a refused CODEX_HOME still wrote');
+});
+
+test('unreadable-kept: a file it cannot read is kept and the other agents still install', { skip: process.getuid?.() === 0 }, () => {
+  const ctx = setup();
+  fs.mkdirSync(ctx.agents, { recursive: true });
+  const locked = path.join(ctx.agents, 'debugger.toml');
+  fs.writeFileSync(locked, 'mine\n');
+  fs.chmodSync(locked, 0o000);
+  try {
+    const result = setupAgents(ctx);
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stdout, /^kept \(unreadable\): .*debugger\.toml$/m);
+    assert.equal(fs.readdirSync(ctx.agents).length, fs.readdirSync(path.join(tree, 'agents')).length);
+  } finally {
+    fs.chmodSync(locked, 0o600);
+  }
+  assert.equal(fs.readFileSync(locked, 'utf8'), 'mine\n');
+});
+
+test('symlink-kept: a symlinked agent stays a symlink and its target is untouched', () => {
+  const ctx = setup();
+  fs.mkdirSync(ctx.agents, { recursive: true });
+  const elsewhere = path.join(ctx.home, 'dotfiles-researcher.toml');
+  fs.writeFileSync(elsewhere, olderOwn('researcher.toml'));
+  const before = fs.readFileSync(elsewhere, 'utf8');
+  fs.symlinkSync(elsewhere, path.join(ctx.agents, 'researcher.toml'));
+  const result = setupAgents(ctx);
+  assert.equal(result.status, 0, result.stderr);
+  assert.ok(fs.lstatSync(path.join(ctx.agents, 'researcher.toml')).isSymbolicLink());
+  assert.equal(fs.readlinkSync(path.join(ctx.agents, 'researcher.toml')), elsewhere);
+  assert.equal(fs.readFileSync(elsewhere, 'utf8'), before);
+  assert.match(result.stdout, /^kept \(symlink\): .*researcher\.toml$/m);
+});
+
+test('repo-collision-reported: an agent of the same name in the repository is reported', () => {
+  const ctx = setup();
+  fs.mkdirSync(path.join(ctx.repo, '.codex/agents'), { recursive: true });
+  fs.writeFileSync(path.join(ctx.repo, '.codex/agents/test_runner.toml'), 'name = "test_runner"\n');
+  const result = setupAgents(ctx);
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /^collision: .*\.codex\/agents\/test_runner\.toml/m);
+  assert.equal((result.stdout.match(/^collision: /gm) || []).length, 1);
+});
+
+test('skill-explicit-no-target: the skill is explicit-only and the script refuses any argument', () => {
+  const skill = fs.readFileSync(path.join(tree, 'skills/setup-agents/SKILL.md'), 'utf8');
+  assert.match(skill, /^---\nname: cf-setup-agents\n/);
+  assert.match(skill, /\{cafekit:setup-agents\}/);
+  assert.equal(fs.readFileSync(path.join(tree, 'skills/setup-agents', CODEX_POLICY_FILE), 'utf8'), CODEX_EXPLICIT_ONLY_POLICY);
+  const ctx = setup();
+  const target = path.join(ctx.home, 'elsewhere');
+  const result = setupAgents(ctx, [target]);
+  assert.equal(result.status, 2);
+  assert.ok(!fs.existsSync(target) && !fs.existsSync(ctx.agents), 'the script wrote with an argument');
+});

package/bin/__tests__/codex-specs-projection.test.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const { test } = require('node:test');
+const { normalizeCodexBody, CODEX_SPECS_SCOPE_MARKER, CODEX_SPECS_SCOPE_NOTE,
+  CODEX_RESEARCH_DEPTH_MARKER } = require('../lib/codex-install');
+const { splitFrontmatter } = require('../lib/codex-frontmatter');
+
+const SKILLS = path.resolve(__dirname, '../../src/claude/skills');
+const specsPath = path.join(SKILLS, 'specs/SKILL.md');
+const specs = fs.readFileSync(specsPath, 'utf8');
+
+function skillFiles(directory) {
+  return fs.readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
+    const file = path.join(directory, entry.name);
+    return entry.isDirectory() ? skillFiles(file) : entry.name === 'SKILL.md' ? [file] : [];
+  });
+}
+
+function assertMarker() {
+  assert.equal(typeof CODEX_SPECS_SCOPE_MARKER, 'string');
+  assert.ok(CODEX_SPECS_SCOPE_MARKER.length > 0);
+}
+
+test('codex specs projection carries the scope note immediately after unchanged frontmatter', () => {
+  assertMarker();
+  assert.equal(typeof CODEX_SPECS_SCOPE_NOTE, 'string');
+  const plain = normalizeCodexBody(specs);
+  const projected = normalizeCodexBody(specs, specsPath);
+  assert.match(projected, /^---\r?\n/);
+  const before = splitFrontmatter(plain), after = splitFrontmatter(projected);
+  assert.equal(after.frontmatter.name, 'cf-specs');
+  assert.deepEqual(after.frontmatter, before.frontmatter);
+  assert.equal(projected.slice(0, projected.length - after.body.length), plain.slice(0, plain.length - before.body.length));
+  assert.equal(after.body, `\n${CODEX_SPECS_SCOPE_NOTE}\n\n${before.body}`);
+  assert.equal(projected.split(CODEX_SPECS_SCOPE_MARKER).length - 1, 1);
+  assert.equal(normalizeCodexBody(projected, specsPath), projected);
+  assert.ok(CODEX_SPECS_SCOPE_NOTE.includes(CODEX_SPECS_SCOPE_MARKER));
+  assert.match(CODEX_SPECS_SCOPE_MARKER, /GATE-SCOPE.*final answer/);
+  assert.match(CODEX_SPECS_SCOPE_NOTE, /not in commentary or through `request_user_input`/);
+  assert.match(CODEX_SPECS_SCOPE_NOTE, /Do not send a summary after/);
+  assert.match(CODEX_SPECS_SCOPE_NOTE, /\[NEEDS CLARIFICATION: <question>\]/);
+  assert.match(CODEX_SPECS_SCOPE_NOTE, /real question.*not a placeholder/);
+  assert.match(CODEX_SPECS_SCOPE_NOTE, /EXPAND, KEEP, and CUT together/);
+  assert.match(CODEX_SPECS_SCOPE_NOTE, /Preserve.*NEEDS CLARIFICATION.*EXPAND.*KEEP.*CUT.*do not translate/);
+  assert.doesNotMatch(CODEX_SPECS_SCOPE_NOTE, /\b(?:Write|Edit|Read|Bash|WebSearch|WebFetch|AskUserQuestion)\b/);
+  assert.doesNotMatch(CODEX_SPECS_SCOPE_NOTE, /customer|sales|notif|khách|bán hàng|thông báo/i);
+});
+
+test('specs marker is absent from every other skill and research retains exactly one depth marker', () => {
+  assertMarker();
+  const others = skillFiles(SKILLS).filter(file => file !== specsPath);
+  for (const name of ['ask', 'research']) assert.ok(others.includes(path.join(SKILLS, name, 'SKILL.md')));
+  for (const file of others) {
+    const source = fs.readFileSync(file, 'utf8');
+    const projected = normalizeCodexBody(source, file);
+    assert.ok(!projected.includes(CODEX_SPECS_SCOPE_MARKER), file);
+    if (file === path.join(SKILLS, 'research/SKILL.md')) {
+      assert.equal(projected.split(CODEX_RESEARCH_DEPTH_MARKER).length - 1, 1);
+    } else if (file !== path.join(SKILLS, 'ask/SKILL.md')) {
+      assert.equal(projected, normalizeCodexBody(source), file);
+    }
+  }
+});
+
+test('specs note is scoped to the exact skill source path and supports Windows separators', () => {
+  assertMarker();
+  for (const sourcePath of ['', 'skills/specs/references/templates.md', 'other-skills/specs/SKILL.md']) {
+    const projected = normalizeCodexBody(specs, sourcePath);
+    assert.ok(!projected.includes(CODEX_SPECS_SCOPE_MARKER), sourcePath);
+    assert.equal(projected, normalizeCodexBody(specs), sourcePath);
+  }
+  assert.ok(normalizeCodexBody(specs, 'C:\\project\\skills\\specs\\SKILL.md').includes(CODEX_SPECS_SCOPE_MARKER));
+});

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

@@ -78,7 +78,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', 'runtime-dir.cjs', 'hook-payload.cjs']) {
+  for (const helper of ['hook-state-dir.cjs', 'runtime-dir.cjs', 'hook-payload.cjs', 'project-root.cjs']) {
     const target = path.join(destinationRoot, 'hooks', 'lib', helper);
     fs.mkdirSync(path.dirname(target), { recursive: true });
     fs.copyFileSync(path.join(hooksRoot, 'lib', helper), target);

package/bin/__tests__/docs-sync-on-demand.test.js

@@ -47,29 +47,34 @@ function makeStale(root) {
   execSync('git -c user.email=t@t -c user.name=t add -A && git -c user.email=t@t -c user.name=t commit -qm fixture', { cwd: root });
 }
 
-test('fresh claude install runs no docs-sync at SessionStart', () => {
-  inTempProject((root) => {
-    install(root, ['claude']);
-    const settings = JSON.parse(fs.readFileSync(path.join(root, '.claude', 'settings.json'), 'utf8'));
-    assert.equal(commands(settings, 'SessionStart').some((c) => c.includes('docs-sync.cjs')), false);
-    assert.equal(fs.existsSync(path.join(root, '.claude', 'hooks', 'docs-sync.cjs')), true, 'the hook stays installed for on-demand use');
+for (const [runtime, folder, config] of [['claude', '.claude', 'settings.json'], ['codex', '.codex', 'hooks.json']]) {
+  test(`fresh ${runtime} install runs no docs-sync at SessionStart`, () => {
+    inTempProject((root) => {
+      install(root, [runtime]);
+      const settings = JSON.parse(fs.readFileSync(path.join(root, folder, config), 'utf8'));
+      assert.equal(commands(settings, 'SessionStart').some((c) => c.includes('docs-sync.cjs')), false);
+      assert.equal(fs.existsSync(path.join(root, folder, 'hooks', 'docs-sync.cjs')), true, 'the hook stays installed for on-demand use');
+    });
   });
-});
 
-test('upgrade drops the SessionStart docs-sync entry', () => {
-  inTempProject((root) => {
-    install(root, ['claude']);
-    const settingsPath = path.join(root, '.claude', 'settings.json');
-    const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
-    const kept = commands(settings, 'SessionStart');
-    settings.hooks.SessionStart[0].hooks.push({ type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/docs-sync.cjs"' });
-    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
-    install(root, ['claude']);
-    const after = commands(JSON.parse(fs.readFileSync(settingsPath, 'utf8')), 'SessionStart');
-    assert.equal(after.some((c) => c.includes('docs-sync.cjs')), false);
-    for (const command of kept) assert.ok(after.includes(command), `kept: ${command}`);
+  test(`${runtime} upgrade drops the managed SessionStart docs-sync entry`, () => {
+    inTempProject((root) => {
+      install(root, [runtime]);
+      const settingsPath = path.join(root, folder, config);
+      const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      const kept = commands(settings, 'SessionStart');
+      const command = runtime === 'claude'
+        ? 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/docs-sync.cjs"'
+        : 'node ".codex/hooks/docs-sync.cjs"';
+      settings.hooks.SessionStart[0].hooks.push({ type: 'command', command });
+      fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+      install(root, [runtime]);
+      const after = commands(JSON.parse(fs.readFileSync(settingsPath, 'utf8')), 'SessionStart');
+      assert.equal(after.some((c) => c.includes('docs-sync.cjs')), false);
+      for (const command of kept) assert.ok(after.includes(command), `kept: ${command}`);
+    });
   });
-});
+}
 
 test('the docs skill runs docs-sync on demand', () => {
   for (const rel of ['SKILL.md', 'references/update-workflow.md']) {

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

@@ -0,0 +1,183 @@
+'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 } = require('node:test');
+const SOURCE = path.resolve(__dirname, '../../src');
+
+// Invoke installed-layout hooks with stdin JSON: denial must be real, not a crash.
+function fixture(host, run, variant = '') {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'ck-inspect-'));
+  const root = path.join(temp, 'build/app');
+  const link = path.join(temp, 'project-link');
+  const hooks = path.join(root, `.${host}/hooks`);
+  try {
+    fs.mkdirSync(root, { recursive: true });
+    fs.symlinkSync(root, link, 'dir');
+    fs.cpSync(path.join(SOURCE, `${host}/hooks`), hooks, { recursive: true });
+    if (host === 'codex') {
+      for (const name of ['runtime-path-safety', 'privacy-command-analysis', 'privacy-paths', 'secret-keywords', 'inspect-paths']) {
+        const source = path.join(SOURCE, `claude/hooks/lib/${name}.cjs`);
+        // Before the shared lib exists, exercise the original native implementation.
+        if (fs.existsSync(source)) fs.copyFileSync(source, path.join(hooks, `lib/${name}.cjs`));
+      }
+    }
+    const cwd = variant === 'nested' ? path.join(root, 'packages/x') : root;
+    fs.mkdirSync(cwd, { recursive: true });
+    const projectRoot = variant === 'symlink' ? link : root;
+    run({ root, temp, cwd, hook(tool_name, tool_input, payload = {}) {
+      const log = path.join(hooks, '.logs/hook-log.jsonl');
+      const before = fs.existsSync(log) ? fs.readFileSync(log, 'utf8') : '';
+      const result = spawnSync(process.execPath, [path.join(hooks, 'inspect-block.cjs')], {
+        cwd, encoding: 'utf8', input: JSON.stringify({ cwd, tool_name, tool_input, ...payload }),
+        env: { ...process.env, CLAUDE_PROJECT_DIR: projectRoot },
+      });
+      const after = fs.existsSync(log) ? fs.readFileSync(log, 'utf8') : '';
+      assert.doesNotMatch(after.slice(before.length), /"status":"crash"/, result.stderr);
+      return result;
+    } });
+  } finally { fs.rmSync(temp, { recursive: true, force: true }); }
+}
+
+const cases = [];
+function add(name, tool, input, deny = false, variant = '', payload = {}) {
+  cases.push({ name, tool, input, deny, variant, payload });
+}
+function shell(command, deny = false) { add(command, 'Bash', { command }, deny); }
+add('Read node_modules', 'Read', { file_path: 'node_modules/x/index.js' }, true);
+add('Read absolute dist', 'Read', ({ root }) => ({ file_path: `${root}/dist/a.js` }), true);
+add('Glob broad', 'Glob', { pattern: '**/*' }, true);
+add('Glob dist', 'Glob', { pattern: '*.js', path: 'dist' }, true);
+add('Grep path', 'Grep', { pattern: 'foo', path: 'node_modules' }, true);
+add('Grep glob', 'Grep', { pattern: 'foo', glob: 'dist/**' }, true);
+for (const command of [
+  'cat dist/index.js', 'nl -ba dist/a.js', 'sed -n 1,5p build/x',
+  'grep -rn foo node_modules', 'rg foo dist', 'find ./dist', 'ls node_modules',
+  'npm exec cat ./dist/index.js', 'npx cat dist/a.js', 'npm exec -- cat dist/a',
+  'FOO=1 cat dist/a', 'env FOO=1 cat dist/a', 'sudo -u root cat dist/a',
+  'vite build --outDir ./dist $(cat dist/index.js)', 'echo `cat dist/a`', 'echo "$(cat dist/a)"',
+]) shell(command, true);
+add('Bash tilde path', 'Bash', ({ root }) => ({ command: `cat ~/${path.relative(os.homedir(), root)}/dist/a` }), true);
+add('missing tool name', undefined, { path: './dist/index.js' }, true);
+add('exec_command reader', 'exec_command', { cmd: 'cat dist/index.js' }, true);
+for (const tool of ['Edit', 'Write', 'MultiEdit']) {
+  add(`${tool} write`, tool, ({ root }) => ({ file_path: `${root}/scripts/build/release.js` }));
+}
+add('NotebookEdit write', 'NotebookEdit', { notebook_path: 'dist/a.ipynb' });
+add('patch package main', 'apply_patch', { command: '*** Begin Patch\n*** Update File: package.json\n+"main": "./dist/index.js"\n*** End Patch' });
+add('patch Add File', 'apply_patch', { command: '*** Begin Patch\n*** Add File: src/build/config.ts\n+x\n*** End Patch' });
+for (const pattern of ['target', 'node_modules']) add(`Grep regex ${pattern}`, 'Grep', { pattern });
+for (const command of [
+  '.agents/skills/.venv/bin/python3 scripts/search.py q', '.claude/skills/.venv/bin/python3 scripts/x.py',
+  'python3 -m venv .venv', 'source .venv/bin/activate && pytest',
+  'node_modules/.bin/eslint src', 'npx eslint dist/', 'python3 scripts/x.py build/out',
+  'tsc --outDir ./build', 'vite build --outDir ./dist', 'npm run build -- --outDir ./dist',
+  'cargo build --target-dir ./target', 'cd build && cmake ..', 'tree -I node_modules',
+  'grep -rn foo . --exclude-dir node_modules', "rg --glob '!**/node_modules/**' foo",
+  'find . -path ./node_modules -prune -o -print', 'echo concat vendor', "echo '$(cat dist/a)'",
+  "git commit -F - <<'EOF'\nls node_modules cleanup\nEOF",
+]) shell(command);
+add('Grep excluded glob', 'Grep', { pattern: 'foo', glob: '!dist/**' });
+for (const variant of ['', 'nested', 'symlink']) {
+  add(`project above blocked segment ${variant || 'root'}`, 'Read', ({ root }) => ({ file_path: `${fs.realpathSync(root)}/src/a.js` }), false, variant);
+}
+add('Read ordinary', 'Read', { file_path: 'src/a.js' });
+shell('cat src/a.js');
+
+// Wrapper options, nested substitutions, and structured paths.
+for (const command of [
+  'time -p env -u FOO BAR=1 command -- cat dist/a', 'nice -n 5 nohup cat dist/a',
+  'xargs -I {} cat dist/a', 'pnpm exec -- cat dist/a', 'pnpx --yes cat dist/a',
+  'yarn exec -- cat dist/a', 'bunx --bun cat dist/a', 'npx -p cat -- cat dist/a',
+  'echo "$(echo $(cat dist/a))"', 'echo ok; cat dist/a', 'echo ok\ncat dist/a',
+  'echo ok | cat dist/a', 'rg -e foo dist/a', 'awk \'{print $1}\' dist/a',
+  'less dist/a', 'more dist/a', 'bat dist/a', 'wc dist/a', 'du dist', 'file dist/a', 'stat dist/a',
+  'cat -n dist/a', 'wc -c dist/a', 'du -s dist', 'ls -L dist',
+  'echo $( (cat dist/a) )', 'env -S "cat dist/a"', 'env --split-string="cat" dist/a',
+  'npm exec -c "cat dist/a"', 'npx --call="cat dist/a"',
+  'cat src/a <<\\EOF\nprose\nEOF\ncat dist/a', "cat src/a <<E'OF'\nprose\nEOF\ncat dist/a",
+]) shell(command, true);
+for (const command of [
+  'grep --include node_modules foo src', 'rg -e node_modules src',
+  'rg --exclude-dir=node_modules foo src', 'tree -P dist',
+  'echo "cat dist/a"', "echo '`cat dist/a`'", 'cat src/a.js <<EOF\ncat dist/a\nEOF',
+]) shell(command);
+add('nested paths', 'mcp__files__read', { operations: [{ paths: ['dist/a'] }] }, true);
+add('notebook path reader', 'Read', { notebook_path: 'dist/a.ipynb' }, true);
+add('unknown command reader', 'mcp__shell', { command: 'cat dist/a' }, true);
+add('missing name command reader', undefined, { command: 'cat dist/a' }, true);
+add('write skips command too', 'Write', { file_path: 'dist/a', command: 'cat dist/a' });
+
+// Output redirections are writes; search option values are not patterns.
+for (const command of [
+  "cat > dist/index.html <<'EOF'\n<html></html>\nEOF",
+  'ls src > build/files.txt', 'wc -l src/a.ts > coverage/summary.txt',
+  'grep x src 2> build/err', 'ls src >> build/x', 'ls src 2>&1', 'ls src>build/x',
+  'rg --max-depth 2 target src', 'rg -j 4 build src', 'rg -M 200 dist src',
+  'rg --sort path target src', 'grep -rn -d skip build src',
+]) shell(command);
+for (const command of ['cat < dist/a', 'cat <dist/a']) shell(command, true);
+
+add('Grep glob:"**/*.ts", path:"src"', 'Grep', { pattern: 'x', glob: '**/*.ts', path: 'src' });
+add('Glob pattern:"**/*.ts", path:"src"', 'Glob', { pattern: '**/*.ts', path: 'src' });
+shell("rg -g '**/*.ts' x src");
+add('Glob broad without path', 'Glob', { pattern: '**/*' }, true);
+add('Grep glob:"**/*.ts", path:"."', 'Grep', { pattern: 'x', glob: '**/*.ts', path: '.' }, true);
+add('Glob broad absolute project root', 'Glob', ({ root }) => ({ pattern: '**/*.ts', path: root }), true);
+add('Glob broad path:".."', 'Glob', { pattern: '**/*', path: '..' }, true);
+add('Glob broad filesystem root', 'Glob', { pattern: '**/*', path: '/' }, true);
+add('Glob broad home', 'Glob', { pattern: '**/*', path: '~' }, true);
+add('Glob broad normalized project root', 'Glob', { pattern: '**/*', path: 'src/..' }, true);
+add('Glob broad blocked directory', 'Glob', { pattern: '**/*.ts', path: 'node_modules' }, true);
+shell("rg --glob '**/*' symbol .", true);
+shell("rg --glob '**/*' symbol; cat src/file.ts", true);
+shell("cd ..; rg --glob '**/*' symbol src", true);
+shell("env -C .. rg --glob '**/*' symbol src", true);
+for (const command of [
+  "rg -E utf8 -g '**/*' x", "rg --ignore-file .gitignore -g '**/*' x",
+  "rg --engine pcre2 -g '**/*' x", "rg --type-add 'web:*.html' -g '**/*' x",
+  "echo . | xargs rg -g '**/*' x src", "env -C.. rg -g '**/*' x src",
+  "builtin cd .. && rg -g '**/*' x src",
+]) shell(command, true);
+add('Bash broad glob with non-string session cwd', 'Bash', { command: "rg -g '**/*' x src" }, true, '', { cwd: 1 });
+add('Bash broad glob with non-string input cwd', 'Bash', { command: "rg -g '**/*' x src", cwd: 1 }, true);
+for (const key of ['cwd', 'workdir']) {
+  add(`Bash broad glob with ${key}:".."`, 'Bash', { command: "rg -g '**/*' x src", [key]: '..' }, true);
+}
+for (const flag of [
+  '--json', '-S', '--smart-case', '-N', '--no-heading', '--heading', '--column', '--vimgrep',
+  '--follow', '--no-ignore', '--no-ignore-dot', '--no-ignore-exclude', '--no-ignore-files',
+  '--no-ignore-global', '--no-ignore-parent', '--no-ignore-vcs', '--no-ignore-messages',
+  '--no-ignore-file-case-insensitive', '--count-matches', '-b', '--trim',
+  '-C3', '-A2', '-m5', '-tts',
+]) shell(`rg -g '**/*.ts' ${flag} x src`);
+for (const command of [
+  "eval 'cd ..'; rg -g '**/*' x src", "source setup.sh; rg -g '**/*' x src",
+  ". setup.sh; rg -g '**/*' x src", "env -iC.. rg -g '**/*' x src",
+]) shell(command, true);
+
+for (const host of ['claude', 'codex']) {
+  for (const entry of cases) {
+    if (host === 'codex' && entry.payload.cwd === 1) continue;
+    test(`inspect-paths ${host}: ${entry.name}`, () => fixture(host, (context) => {
+      const input = typeof entry.input === 'function' ? entry.input(context) : entry.input;
+      const result = context.hook(entry.tool, input, entry.payload);
+      assert.equal(result.status, entry.deny ? 2 : 0, result.stderr || result.stdout);
+      if (entry.deny) {
+        if (host === 'claude') assert.equal(JSON.parse(result.stdout).hookSpecificOutput.permissionDecision, 'deny');
+        assert.match(result.stderr, /SCOPE LIMIT EXCEEDED/);
+      } else assert.equal(result.stdout, '');
+    }, entry.variant));
+  }
+}
+
+test('inspect-paths lib blocks broad glob with non-string context.cwd', () => {
+  const { inspectInput } = require('../../src/claude/hooks/lib/inspect-paths.cjs');
+  const result = inspectInput('Bash', { command: "rg -g '**/*' x src" }, {
+    cwd: 1, projectRoot: process.cwd(),
+  });
+  assert.equal(result.broadGlob, '**/*');
+});