@haposoft/cafekit 0.18.2 → 0.18.3

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

@@ -804,6 +804,37 @@ test('Codex compact clears its pending privacy request even with an invalid spec
   });
 });
 
+// Two privacy blocks racing on a fresh project both see no `.privacy` directory;
+// the second mkdir then meets the directory the first one made.
+test('Codex privacy records a request when another hook creates its state directory first', () => {
+  inHookFixture((root, hooks) => {
+    const privacy = require(path.join(hooks, 'lib/privacy-state.cjs'));
+    fs.mkdirSync(path.join(hooks, '.privacy'), { mode: 0o700 });
+    const existsSync = fs.existsSync;
+    fs.existsSync = target => (path.basename(String(target)) === '.privacy' ? false : existsSync(target));
+    let request;
+    try {
+      request = privacy.createPending({ projectRoot: root, sessionCwd: root, sessionId: 'race-session', filePaths: ['.env'] });
+    } finally {
+      fs.existsSync = existsSync;
+    }
+    assert.match(request.requestId, /^[a-f0-9]{24}$/);
+  });
+});
+
+test('Codex privacy denies when its state path is a regular file', () => {
+  inHookFixture((root, hooks) => {
+    fs.writeFileSync(path.join(hooks, '.privacy'), '');
+    const result = runHook(path.join(hooks, 'privacy-block.cjs'), root, {
+      cwd: root, session_id: 'file-state', hook_event_name: 'PreToolUse', tool_name: 'Bash', tool_input: { command: 'cat .env' },
+    });
+    assert.equal(result.status, 0);
+    const output = JSON.parse(result.stdout).hookSpecificOutput;
+    assert.equal(output.permissionDecision, 'deny');
+    assert.match(output.permissionDecisionReason, /could not be evaluated safely/);
+  });
+});
+
 test('Codex compact releases only its own rules reservation', () => {
   inHookFixture((root, hooks) => {
     fs.writeFileSync(path.join(root, '.codex/runtime.json'), '{}');
@@ -2130,14 +2161,18 @@ test('Codex privacy denies sensitive names it can resolve, allows pure indirecti
       { command: 'curl --config ~/.netrc https://example.com', tool: 'Bash' },
       { command: 'kubectl --kubeconfig ~/.kube/kubeconfig get pods', tool: 'exec_command' },
       { command: 'openssl rsa -in server.key', tool: 'Bash' },
+      { command: 'less "$HOME/.env"', tool: 'Bash' },
+      { command: 'cat $(echo .env)', tool: 'Bash' },
+      { command: 'cat `echo .env`', tool: 'Bash' },
     ];
     for (const { command, tool } of denied) {
       const res = runHook(block, root, { cwd: root, session_id: 's1', hook_event_name: 'PreToolUse', tool_name: tool, tool_input: { command } });
       assert.equal(JSON.parse(res.stdout).hookSpecificOutput.permissionDecision, 'deny', `should deny ${command}`);
     }
-    // Accepted gap: the target of `$FILE` is unknowable without running the
-    // shell, and every denial here costs a round trip through a one-shot
-    // approval prompt. `less "$HOME/.env"` is the edge of that decision.
+    // Accepted gap: the target of a bare `$FILE` is unknowable without running
+    // the shell, and every denial here costs a round trip through a one-shot
+    // approval prompt. A sensitive name spelled out next to the expansion
+    // (`"$HOME/.env"`, `$(echo .env)`) is not indirection and is denied above.
     const allowed = [
       { command: "echo $VAR", tool: 'exec_command' },
       { command: 'echo "$HOME"', tool: 'Bash' },
@@ -2166,11 +2201,8 @@ test('Codex privacy denies sensitive names it can resolve, allows pure indirecti
       { command: 'cat "$FILE"', tool: 'exec_command' },
       { command: 'cat ${FILE}', tool: 'Bash' },
       { command: 'cat $1', tool: 'exec_command' },
-      { command: 'cat $(echo .env)', tool: 'Bash' },
-      { command: 'cat `echo .env`', tool: 'Bash' },
       { command: 'head $SECRET', tool: 'exec_command' },
       { command: 'tail ${MY_FILE}', tool: 'Bash' },
-      { command: 'less "$HOME/.env"', tool: 'Bash' },
       { command: 'cat README.md $EXTRA', tool: 'Bash' },
       { command: 'echo ok; cat README.md $FILE', tool: 'Bash' },
       { command: 'cat README.md | head $FILE', tool: 'exec_command' },

package/bin/__tests__/codex-implicit-policy.test.js

@@ -0,0 +1,160 @@
+// Codex ignores the `disable-model-invocation` key that keeps a skill explicit-only on Claude Code. Its own
+// mechanism is `agents/openai.yaml` beside SKILL.md with `policy.allow_implicit_invocation: false`. These cases
+// pin that the Codex install writes that file for every explicit-only skill through the ownership-aware writer
+// (so upgrades and removals stay clean), writes it for no other skill, and that the catalog never lists such a skill.
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const test = require('node:test');
+const { spawnSync } = require('node:child_process');
+
+const { PLATFORMS } = require('../lib/context');
+const manifestLib = require('../lib/manifest');
+const { removeSkill } = require('../phases/skill-inventory');
+
+const PACKAGE_ROOT = path.join(__dirname, '..', '..');
+const INSTALLER = path.join(PACKAGE_ROOT, 'bin/install.js');
+const SOURCE_SKILLS = path.join(PACKAGE_ROOT, 'src/claude/skills');
+const POLICY = 'policy:\n  allow_implicit_invocation: false\n';
+
+const explicitOnly = fs.readdirSync(SOURCE_SKILLS)
+  .filter((name) => fs.existsSync(path.join(SOURCE_SKILLS, name, 'SKILL.md')))
+  .filter((name) => /^disable-model-invocation:\s*(["']?)true\1\s*$/m.test(
+    fs.readFileSync(path.join(SOURCE_SKILLS, name, 'SKILL.md'), 'utf8').split(/^---\s*$/m)[1] || ''));
+
+function install(root, platform) {
+  const result = spawnSync(process.execPath, [INSTALLER, '--platform', platform, '--yes'],
+    { cwd: root, encoding: 'utf8', env: { ...process.env, PATH: '/usr/bin:/bin' } });
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+  return result;
+}
+
+function withTempProject(run) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-codex-policy-'));
+  const previous = process.cwd();
+  try {
+    assert.equal(spawnSync('git', ['-C', root, 'init', '-q']).status, 0);
+    process.chdir(root);
+    return run(root);
+  } finally {
+    process.chdir(previous);
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+const policyFile = (root, skill) => path.join(root, '.agents/skills', skill, 'agents/openai.yaml');
+const ownershipKey = (root, file) => path.relative(path.join(root, PLATFORMS.codex.ownership?.recordRoot || PLATFORMS.codex.folder), file).replace(/\\/g, '/');
+const readOwnership = (root) => JSON.parse(fs.readFileSync(path.join(root, PLATFORMS.codex.folder, manifestLib.MANIFEST_FILE), 'utf8'));
+const writeOwnership = (root, data) => fs.writeFileSync(path.join(root, PLATFORMS.codex.folder, manifestLib.MANIFEST_FILE), JSON.stringify(data, null, 2));
+
+function catalog(root, script, skillsRoot) {
+  const result = spawnSync(process.execPath, [path.join(root, script), '--json', '--root', path.join(root, skillsRoot)],
+    { cwd: root, encoding: 'utf8' });
+  assert.equal(result.status, 0, result.stderr);
+  return JSON.parse(result.stdout);
+}
+
+test('the explicit-only skills are vibe and adv', () => {
+  assert.deepEqual(explicitOnly.sort(), ['adv', 'vibe']);
+});
+
+test('a Codex install writes the policy file for every explicit-only skill, owned, and for no other skill', () => {
+  withTempProject((root) => {
+    install(root, 'codex');
+    const ownership = readOwnership(root);
+    for (const skill of explicitOnly) {
+      const file = policyFile(root, skill);
+      assert.equal(fs.readFileSync(file, 'utf8'), POLICY, skill);
+      assert.equal(ownership.files[ownershipKey(root, file)]?.sha256, manifestLib.hashFile(file), `${skill} policy is not owned`);
+    }
+    const others = fs.readdirSync(path.join(root, '.agents/skills')).filter((name) => !explicitOnly.includes(name));
+    assert.ok(others.length > 10);
+    for (const skill of others) assert.equal(fs.existsSync(policyFile(root, skill)), false, skill);
+  });
+});
+
+test('reinstalling keeps the policy bytes and its ownership record unchanged', () => {
+  withTempProject((root) => {
+    install(root, 'codex');
+    const before = explicitOnly.map((skill) => readOwnership(root).files[ownershipKey(root, policyFile(root, skill))]?.sha256);
+    install(root, 'codex');
+    const after = explicitOnly.map((skill) => readOwnership(root).files[ownershipKey(root, policyFile(root, skill))]?.sha256);
+    assert.deepEqual(after, before);
+    for (const skill of explicitOnly) assert.equal(fs.readFileSync(policyFile(root, skill), 'utf8'), POLICY);
+  });
+});
+
+test('an owned policy file under a skill that dropped the key is removed on upgrade; a user-created one stays', () => {
+  withTempProject((root) => {
+    install(root, 'codex');
+    // An earlier release that marked ask explicit-only would have written and owned this file.
+    const owned = policyFile(root, 'ask');
+    fs.mkdirSync(path.dirname(owned), { recursive: true });
+    fs.writeFileSync(owned, POLICY);
+    const data = readOwnership(root);
+    data.files[ownershipKey(root, owned)] = { sha256: manifestLib.hashFile(owned), version: 'old' };
+    writeOwnership(root, data);
+    // A file the user wrote is never ours to delete.
+    const userFile = policyFile(root, 'debug');
+    fs.mkdirSync(path.dirname(userFile), { recursive: true });
+    fs.writeFileSync(userFile, POLICY);
+
+    install(root, 'codex');
+    assert.equal(fs.existsSync(owned), false, 'owned stale policy survived the upgrade');
+    assert.equal(readOwnership(root).files[ownershipKey(root, owned)], undefined, 'stale policy stayed in the manifest');
+    assert.equal(fs.readFileSync(userFile, 'utf8'), POLICY, 'user-created policy was removed');
+  });
+});
+
+test('a user edit to the policy file is preserved on upgrade', () => {
+  withTempProject((root) => {
+    install(root, 'codex');
+    const file = policyFile(root, 'vibe');
+    const edited = 'policy:\n  allow_implicit_invocation: true\n';
+    fs.writeFileSync(file, edited);
+    install(root, 'codex');
+    assert.equal(fs.readFileSync(file, 'utf8'), edited);
+  });
+});
+
+test('removing an explicit-only skill removes its whole tree, the policy file included', () => {
+  withTempProject((root) => {
+    install(root, 'codex');
+    const ctx = {
+      ownership: { [PLATFORMS.codex.folder]: readOwnership(root) },
+      trackers: { codex: manifestLib.createTracker(PLATFORMS.codex.folder, 'next', PLATFORMS.codex.ownership) },
+      dryRun: false,
+      ui: { warn() {}, detail() {} },
+      results: { updated: 0, preserved: 0, preservedFiles: [] }
+    };
+    removeSkill(ctx, 'codex', 'vibe');
+    assert.deepEqual(ctx.results.preservedFiles, []);
+    assert.equal(fs.existsSync(path.join(root, '.agents/skills/vibe')), false);
+  });
+});
+
+test('a Claude install writes no policy file', () => {
+  withTempProject((root) => {
+    install(root, 'claude');
+    for (const skill of fs.readdirSync(path.join(root, '.claude/skills'))) {
+      assert.equal(fs.existsSync(path.join(root, '.claude/skills', skill, 'agents/openai.yaml')), false, skill);
+    }
+  });
+});
+
+test('neither runtime catalog lists an explicit-only skill, and both still list the others', () => {
+  withTempProject((root) => {
+    install(root, 'claude,codex');
+    for (const [script, skillsRoot] of [['.codex/scripts/generate-skill-catalog.cjs', '.agents/skills'],
+      ['.claude/scripts/generate-skill-catalog.cjs', '.claude/skills']]) {
+      const parsed = catalog(root, script, skillsRoot);
+      const ids = parsed.skills.map((skill) => skill.public_id);
+      for (const skill of explicitOnly) {
+        assert.equal(ids.includes(`cf:${skill}`), false, `${script} lists cf:${skill}`);
+        assert.ok(parsed.diagnostics.some((item) => item.directory === skill && item.code === 'explicit_only'), `${script}: ${skill}`);
+      }
+      assert.ok(ids.includes('cf:ask') && ids.includes('cf:specs'), script);
+    }
+  });
+});

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

@@ -2326,7 +2326,10 @@ test('Codex installed Specs and spec-maker reject adaptive coverage mutations',
     );
     assert.equal(catalog.status, 0, catalog.stderr);
     const catalogData = JSON.parse(catalog.stdout);
-    assert.equal(catalogData.total, skillNames.length);
+    // Explicit-only skills run only when named, so the catalog leaves them out of automatic routing.
+    const explicitOnly = skillFiles.filter((file) => /^disable-model-invocation:\s*true\s*$/m.test(fs.readFileSync(file, 'utf8')));
+    assert.ok(explicitOnly.length >= 1);
+    assert.equal(catalogData.total, skillNames.length - explicitOnly.length);
     assert.equal(
       catalogData.root,
       fs.realpathSync(path.join(root, '.agents', 'skills'))
@@ -3213,15 +3216,15 @@ test('Codex installed code_auditor carries no Strict attestation marker', () =>
   });
 });
 
-test('reinstall preserves untracked Codex runtime files while omp keeps its cleanup policy', () => {
+test('reinstall preserves untracked Codex and omp runtime files', () => {
   for (const platform of ['codex', 'omp']) inTempProject(root => {
     const first = installPlatforms(root, ['codex', 'omp']);
     assert.equal(first.status, 0, `${first.stdout}\n${first.stderr}`);
     const runtime = `.${platform}`;
     const retired = ['change-firewall.cjs', 'spec-final-state.cjs'];
     for (const name of retired) fs.writeFileSync(path.join(root, runtime, 'scripts', name), 'legacy\n');
-    const retiredSkillFiles = platform === 'codex'
-      ? ['code-review/references/verification-gate.md', 'specs/references/archive-workflow.md'] : [];
+    // omp installs no skills, so a reinstall of omp alone must leave .agents/skills to Codex.
+    const retiredSkillFiles = ['code-review/references/verification-gate.md', 'specs/references/archive-workflow.md'];
     for (const rel of retiredSkillFiles) {
       const target = path.join(root, '.agents/skills', rel);
       fs.mkdirSync(path.dirname(target), { recursive: true });
@@ -3229,10 +3232,14 @@ test('reinstall preserves untracked Codex runtime files while omp keeps its clea
     }
     const again = installPlatforms(root, [platform], ['--force-overwrite']);
     assert.equal(again.status, 0, `${again.stdout}\n${again.stderr}`);
-    const preserved = platform === 'codex';
-    for (const rel of retiredSkillFiles) assert.equal(fs.existsSync(path.join(root, '.agents/skills', rel)), preserved, rel);
-    for (const name of retired) assert.equal(fs.existsSync(path.join(root, runtime, 'scripts', name)), preserved, name);
-    if (preserved) assert.match(again.stdout + again.stderr, /Preserved 4 obsolete runtime/);
+    const output = again.stdout + again.stderr;
+    for (const rel of retiredSkillFiles) assert.equal(fs.existsSync(path.join(root, '.agents/skills', rel)), true, rel);
+    for (const name of retired) assert.equal(fs.existsSync(path.join(root, runtime, 'scripts', name)), true, name);
+    if (platform === 'codex') assert.match(output, /Preserved 4 obsolete runtime/);
+    else {
+      assert.match(output, /Preserved 2 obsolete runtime/);
+      assert.doesNotMatch(output, /\.agents\/skills/);
+    }
     assert.equal(fs.existsSync(path.join(root, '.agents/skills/code-review/SKILL.md')), true);
     assert.equal(fs.existsSync(path.join(root, runtime, 'scripts/spec-resolver.cjs')), true);
   });

package/bin/__tests__/codex-plugin-build.test.js

@@ -0,0 +1,230 @@
+'use strict';
+
+const { test, before, after } = require('node:test');
+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 REPO = path.resolve(__dirname, '../../../..');
+const SRC = path.resolve(__dirname, '../../src');
+const SCRIPT = path.resolve(__dirname, '../../scripts/build-codex-plugin.mjs');
+let lib;
+let claudeLib;
+let work;
+let tree;
+
+function walk(root, base = root) {
+  return fs.readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
+    const full = path.join(root, entry.name);
+    return entry.isDirectory() ? walk(full, base) : [path.relative(base, full)];
+  });
+}
+
+before(async () => {
+  lib = await import(SCRIPT);
+  claudeLib = await import(path.resolve(__dirname, '../../scripts/build-claude-plugin.mjs'));
+  work = fs.mkdtempSync(path.join(os.tmpdir(), 'ck-codex-plugin-build-'));
+  tree = lib.build(path.join(work, 'cf-codex'));
+});
+
+after(() => fs.rmSync(work, { recursive: true, force: true }));
+
+test('inventory-and-policy: the Claude plugin skill list, Codex names, and explicit-only policies', () => {
+  const skills = fs.readdirSync(path.join(tree, 'skills')).sort();
+  // The Claude plugin's skills plus the Codex-only ones.
+  assert.deepEqual(skills, [...claudeLib.inScopeSkills(), ...lib.CODEX_ONLY_SKILLS].sort());
+  const { isExplicitOnlySkill, CODEX_POLICY_FILE, CODEX_EXPLICIT_ONLY_POLICY } = require('../phases/copy-payload');
+  for (const skill of skills) {
+    const text = fs.readFileSync(path.join(tree, 'skills', skill, 'SKILL.md'), 'utf8');
+    assert.match(text, new RegExp(`^---\\nname: cf-${skill}\\n`), `${skill} keeps the installer's Codex name`);
+    const policy = path.join(tree, 'skills', skill, CODEX_POLICY_FILE);
+    const skillSource = lib.CODEX_ONLY_SKILLS.includes(skill) ? path.join(SRC, 'codex/plugin/skills', skill) : path.join(SRC, 'claude/skills', skill);
+    if (isExplicitOnlySkill(skillSource)) {
+      assert.equal(fs.readFileSync(policy, 'utf8'), CODEX_EXPLICIT_ONLY_POLICY, `${skill} policy`);
+    } else {
+      assert.ok(!fs.existsSync(policy), `${skill} has an unexpected policy file`);
+    }
+  }
+});
+
+test('path-allowlist: Markdown reaches plugin files through {CAFEKIT_ROOT}, never an install path', () => {
+  const offenders = [];
+  for (const file of walk(tree).filter((f) => f.endsWith('.md'))) {
+    const text = fs.readFileSync(path.join(tree, file), 'utf8');
+    if (/\.codex[/\\](skills|references|scripts|rules|hooks|output-styles)\b/.test(text)) offenders.push(`${file}: .codex runtime path`);
+    if (/\.agents[/\\]skills\b/.test(text)) offenders.push(`${file}: .agents/skills path`);
+    if (/(?<!~\/)\.codex\/agents\//.test(text)) offenders.push(`${file}: project .codex/agents path`);
+    if (/\.claude[/\\](skills|references|scripts|rules)\b/.test(text)) offenders.push(`${file}: .claude runtime path`);
+    if (/\{CAFEKIT_ROOT\}\/scripts\//.test(text)) offenders.push(`${file}: script reached by path instead of {cafekit:<name>}`);
+    for (const [, rel] of text.matchAll(/\{CAFEKIT_ROOT\}\/([^\s`'")]+)/g)) {
+      const target = rel.replace(/[.,:;]+$/, '');
+      if (/[<*]/.test(target)) continue;
+      if (!fs.existsSync(path.join(tree, target))) offenders.push(`${file}: {CAFEKIT_ROOT}/${target} does not exist`);
+    }
+  }
+  assert.deepEqual(offenders, []);
+  const commands = lib.scriptCommands(tree);
+  assert.ok(commands.includes('provenance'), 'provenance is not in the command table');
+  for (const name of commands) assert.ok(fs.existsSync(path.join(tree, 'scripts', `${name}.cjs`)), `${name} has no script`);
+});
+
+test('manifest-and-marketplace: plugin.json and the repo marketplace carry the keys Codex reads', () => {
+  const manifest = JSON.parse(fs.readFileSync(path.join(tree, '.codex-plugin/plugin.json'), 'utf8'));
+  assert.equal(manifest.name, 'cf');
+  assert.equal(manifest.version, require('../../package.json').version);
+  for (const key of ['description', 'author', 'license', 'interface']) assert.ok(manifest[key], `plugin.json lacks ${key}`);
+  const market = lib.marketplace();
+  assert.equal(typeof market.name, 'string');
+  const entry = market.plugins.find((p) => p.name === 'cf');
+  assert.deepEqual(entry.source, { source: 'local', path: './plugins/cf-codex' });
+  assert.ok(entry.policy?.installation && entry.policy?.authentication && entry.category, 'entry lacks policy or category');
+});
+
+test('marketplace-not-ignored: git can commit .agents/plugins/marketplace.json', () => {
+  // --no-index: a tracked file would otherwise always read as not ignored.
+  const run = spawnSync('git', ['check-ignore', '-q', '--no-index', '.agents/plugins/marketplace.json'], { cwd: REPO });
+  assert.equal(run.status, 1, 'the marketplace file is ignored by git');
+  const skills = spawnSync('git', ['check-ignore', '-q', '--no-index', '.agents/skills/specs/SKILL.md'], { cwd: REPO });
+  assert.equal(skills.status, 0, 'npx-installed .agents/skills must stay ignored');
+  // A reinstall must not append `.agents/` after `!.agents/plugins/` and hide the marketplace again.
+  const { hasPattern } = require('../phases/root-config');
+  assert.ok(hasPattern(['.agents/*', '!.agents/plugins/'], '.agents/'));
+});
+
+test('claude-marketplace-guard: the Codex marketplace never points at the Claude plugin tree', () => {
+  const entry = lib.marketplace().plugins.find((p) => p.name === 'cf');
+  assert.notEqual(path.normalize(entry.source.path), path.normalize('./plugins/cf'));
+  assert.ok(!fs.existsSync(path.join(REPO, 'plugins/cf/.codex-plugin')), 'the Claude tree must not carry a Codex manifest');
+});
+
+test('check-detects-drift: --check fails after one byte changes in a fresh copy', () => {
+  const copy = lib.build(path.join(work, 'copy'));
+  const clean = spawnSync('node', [SCRIPT, '--check', copy], { encoding: 'utf8' });
+  assert.equal(clean.status, 0, clean.stderr);
+  fs.appendFileSync(path.join(copy, 'skills/specs/SKILL.md'), 'x');
+  const drift = spawnSync('node', [SCRIPT, '--check', copy], { encoding: 'utf8' });
+  assert.equal(drift.status, 1);
+  assert.match(drift.stderr, /changed skills\/specs\/SKILL\.md/);
+});
+
+// ── Runtime and hooks.json ─────────────────────────────────────────────────────
+
+const RUNTIME_DIRS = ['hooks', 'rules', 'output-styles'];
+
+function npxInstall() {
+  const repo = fs.mkdtempSync(path.join(work, 'npx-'));
+  spawnSync('git', ['init', '-q'], { cwd: repo });
+  const run = spawnSync('node', [path.resolve(__dirname, '../install.js'), '--platform', 'codex', '-y'], {
+    cwd: repo, encoding: 'utf8', env: { ...process.env, HOME: fs.mkdtempSync(path.join(work, 'home-')) },
+  });
+  assert.equal(run.status, 0, run.stderr || run.stdout);
+  return repo;
+}
+
+function runtimeFiles(root) {
+  return RUNTIME_DIRS.flatMap((dir) => (fs.existsSync(path.join(root, dir)) ? walk(path.join(root, dir)).map((f) => `${dir}/${f}`) : []))
+    .concat(fs.existsSync(path.join(root, 'runtime.schema.json')) ? ['runtime.schema.json'] : [])
+    .filter((f) => f !== 'hooks/hooks.json' && !f.includes('/.logs/'))
+    .sort();
+}
+
+test('runtime-matches-npx: the plugin runtime holds the same files and bytes as an npx Codex install', () => {
+  const installed = path.join(npxInstall(), '.codex');
+  const expected = runtimeFiles(installed);
+  assert.deepEqual(runtimeFiles(tree), expected);
+  for (const file of expected) {
+    assert.ok(fs.readFileSync(path.join(tree, file)).equals(fs.readFileSync(path.join(installed, file))), `${file} differs from the npx install`);
+  }
+});
+
+test('requires-resolve: every relative require in the plugin hooks resolves inside the tree', () => {
+  const missing = [];
+  for (const file of walk(path.join(tree, 'hooks')).filter((f) => f.endsWith('.cjs'))) {
+    const full = path.join(tree, 'hooks', file);
+    for (const [, spec] of fs.readFileSync(full, 'utf8').matchAll(/require\(\s*['"](\.{1,2}\/[^'"]+)['"]\s*\)/g)) {
+      const target = path.resolve(path.dirname(full), spec);
+      if (![target, `${target}.cjs`, `${target}.js`].some((t) => fs.existsSync(t))) missing.push(`hooks/${file} → ${spec}`);
+    }
+  }
+  assert.deepEqual(missing, []);
+});
+
+function pluginHandlers() {
+  const { hooks } = JSON.parse(fs.readFileSync(path.join(tree, 'hooks/hooks.json'), 'utf8'));
+  return Object.entries(hooks).flatMap(([event, groups]) => groups.flatMap((group) => group.hooks.map((h) => ({ event, ...h }))));
+}
+
+test('hook-commands-fallback: every plugin hook has a POSIX command with a node PATH fallback and a Windows command', () => {
+  const template = JSON.parse(fs.readFileSync(path.join(SRC, 'codex/hooks.json'), 'utf8')).hooks;
+  const handlers = pluginHandlers();
+  // The template's runtime hooks plus the one plugin-only SessionStart hook.
+  const pluginOnly = handlers.filter((h) => h.command.includes('/plugin/hooks/'));
+  assert.deepEqual(pluginOnly.map((h) => h.event), ['SessionStart']);
+  assert.equal(handlers.length - pluginOnly.length, Object.values(template).flat().flatMap((g) => g.hooks).length);
+  for (const handler of handlers) {
+    const [, dir, script] = handler.command.match(/((?:plugin\/)?hooks)\/([a-z0-9-]+\.cjs)"$/) || [];
+    assert.ok(script && fs.existsSync(path.join(tree, dir, script)), `bad command ${handler.command}`);
+    assert.match(handler.command, /^PATH="\$PATH":'[^']+'(:'[^']+')* node "\$\{PLUGIN_ROOT\}\/(plugin\/)?hooks\/[a-z0-9-]+\.cjs"$/);
+    assert.equal(typeof handler.commandWindows, 'string');
+    assert.ok(handler.commandWindows.includes(script) && handler.commandWindows.includes('PLUGIN_ROOT'), handler.commandWindows);
+  }
+});
+
+test('no-build-machine-paths: hooks.json names no absolute path of the machine that built it', () => {
+  const text = fs.readFileSync(path.join(tree, 'hooks/hooks.json'), 'utf8');
+  for (const local of [REPO, os.homedir(), path.dirname(process.execPath)]) assert.ok(!text.includes(local), `hooks.json contains ${local}`);
+  const windows = pluginHandlers()[0].commandWindows;
+  const decoded = spawnSync('node', ['-e', `${windows.replace(/^node -e "|"$/g, '').replace(/require\('module'\)\.runMain\(\)/, 'console.log(process.argv[1])')}`], {
+    encoding: 'utf8', env: { ...process.env, PLUGIN_ROOT: path.join(work, 'win-root') },
+  });
+  assert.equal(decoded.stdout.trim(), path.join(work, 'win-root', 'hooks', pluginHandlers()[0].command.match(/hooks\/([a-z0-9-]+\.cjs)"$/)[1]));
+});
+
+test('npx-hook-commands-unchanged: the npx install still gets absolute project launchers', () => {
+  const repo = npxInstall();
+  const { hooks } = JSON.parse(fs.readFileSync(path.join(repo, '.codex/hooks.json'), 'utf8'));
+  for (const handler of Object.values(hooks).flat().flatMap((g) => g.hooks)) {
+    assert.match(handler.command, /node '[^']+\/\.codex\/hooks\/[a-z0-9-]+\.cjs'$/);
+    assert.ok(handler.command.includes(fs.realpathSync(repo)));
+    assert.ok(!handler.command.includes('PLUGIN_ROOT'));
+    const encoded = handler.commandWindows.split(' ').pop();
+    assert.ok(Buffer.from(encoded, 'base64url').toString('utf8').startsWith(path.join(fs.realpathSync(repo), '.codex', 'hooks')), 'npx Windows launcher lost its project path');
+  }
+});
+
+const SAMPLE_PAYLOADS = {
+  SessionStart: { source: 'startup' },
+  UserPromptSubmit: { prompt: 'hello' },
+  PreToolUse: { tool_name: 'Bash', tool_input: { command: 'ls' } },
+  PermissionRequest: { tool_name: 'Bash', tool_input: { command: 'ls' } },
+  PostToolUse: { tool_name: 'apply_patch', tool_input: { command: '' }, tool_response: {} },
+  Stop: { stop_hook_active: false },
+  SubagentStart: { agent_type: 'debugger' },
+  SubagentStop: { agent_type: 'debugger', stop_hook_active: false },
+  PreCompact: { trigger: 'manual' },
+};
+
+test('hook-smoke: every generated plugin launcher runs its hook to exit 0 without a crash log', () => {
+  // A private root holding the tree, so every crash log a hook writes lands under it.
+  const sandbox = fs.mkdtempSync(path.join(work, 'smoke-'));
+  const smokeTree = lib.build(path.join(sandbox, 'plugin', 'cf-codex'));
+  const repo = path.join(sandbox, 'repo');
+  fs.mkdirSync(repo);
+  spawnSync('git', ['init', '-q'], { cwd: repo });
+  const data = path.join(sandbox, 'data');
+  const failures = [];
+  for (const handler of pluginHandlers()) {
+    const payload = { session_id: 'codex-smoke', hook_event_name: handler.event, cwd: repo, ...(SAMPLE_PAYLOADS[handler.event] || {}) };
+    const run = spawnSync('sh', ['-c', handler.command], {
+      cwd: repo, input: JSON.stringify(payload), encoding: 'utf8', timeout: 20000,
+      env: { ...process.env, HOME: path.join(sandbox, 'home'), PLUGIN_ROOT: smokeTree, PLUGIN_DATA: data, CLAUDE_PLUGIN_ROOT: smokeTree, CLAUDE_PLUGIN_DATA: data },
+    });
+    if (run.status !== 0) failures.push(`${handler.event} ${handler.command}: exit ${run.status} ${run.stderr.slice(0, 200)}`);
+  }
+  const crashLogs = walk(sandbox).filter((f) => f.endsWith('hook-log.jsonl'))
+    .filter((f) => /"status":"crash"/.test(fs.readFileSync(path.join(sandbox, f), 'utf8')));
+  for (const log of crashLogs) failures.push(`crash logged in ${log}: ${fs.readFileSync(path.join(sandbox, log), 'utf8').slice(0, 200)}`);
+  assert.deepEqual(failures, []);
+});

package/bin/__tests__/codex-plugin-context.test.js

@@ -0,0 +1,135 @@
+'use strict';
+
+// The Codex plugin cannot ship AGENTS.md and Codex substitutes nothing in skill text, so
+// a plugin-only SessionStart hook injects the CafeKit core and defines {CAFEKIT_ROOT}
+// and the {cafekit:<name>} commands. The npx install must never receive that hook.
+
+const { test, before, after } = require('node:test');
+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 SCRIPTS = path.resolve(__dirname, '../../scripts');
+const INSTALL = path.resolve(__dirname, '../install.js');
+const ROOT_LENGTH = 120;
+let work;
+let lib;
+let tree;
+
+before(async () => {
+  work = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ck-codex-context-')));
+  lib = await import(path.join(SCRIPTS, 'build-codex-plugin.mjs'));
+  // A plugin root of exactly ROOT_LENGTH characters, the size the core budget assumes.
+  const pad = ROOT_LENGTH - work.length - '/cf-codex'.length - 1;
+  assert.ok(pad > 0, `temp directory too long: ${work}`);
+  tree = lib.build(path.join(work, 'p'.repeat(pad), 'cf-codex'));
+  assert.equal(tree.length, ROOT_LENGTH);
+});
+
+after(() => fs.rmSync(work, { recursive: true, force: true }));
+
+function hook(root, { cwd = work, env = {} } = {}) {
+  const base = { ...process.env, HOME: path.join(work, 'home'), PLUGIN_DATA: path.join(work, 'data'), CLAUDE_PLUGIN_DATA: path.join(work, 'data') };
+  delete base.PLUGIN_ROOT; delete base.CLAUDE_PLUGIN_ROOT;
+  const fullEnv = { ...base, ...(root ? { PLUGIN_ROOT: root, CLAUDE_PLUGIN_ROOT: root } : {}), ...env };
+  const script = path.join(root || tree, 'plugin/hooks/plugin-context.cjs');
+  return spawnSync('node', [script], { cwd, encoding: 'utf8', env: fullEnv, input: JSON.stringify({ session_id: 'ctx', hook_event_name: 'SessionStart', source: 'startup', cwd }) });
+}
+
+function context(root = tree, options) {
+  const result = hook(root, options);
+  assert.equal(result.status, 0, result.stderr);
+  return JSON.parse(result.stdout).hookSpecificOutput.additionalContext;
+}
+
+test('emits-session-start-json: the hook prints the SessionStart JSON Codex reads, registered for every source', () => {
+  const result = hook(tree);
+  assert.equal(result.status, 0, result.stderr);
+  const output = JSON.parse(result.stdout);
+  assert.equal(output.hookSpecificOutput.hookEventName, 'SessionStart');
+  assert.equal(typeof output.hookSpecificOutput.additionalContext, 'string');
+  const { hooks } = JSON.parse(fs.readFileSync(path.join(tree, 'hooks/hooks.json'), 'utf8'));
+  const group = hooks.SessionStart.find((g) => g.hooks.some((h) => h.command.includes('/plugin/hooks/plugin-context.cjs')));
+  assert.ok(group, 'plugin-context is not registered on SessionStart');
+  assert.deepEqual(group.matcher.split('|').sort(), ['clear', 'compact', 'resume', 'startup']);
+  assert.match(group.hooks[0].commandWindows, /'plugin','hooks','plugin-context\.cjs'/);
+});
+
+test('core-under-10000-chars: with a 120-character plugin root the injected text stays within the host cap', () => {
+  const text = context();
+  assert.ok(text.length <= 10000, `${text.length} characters`);
+});
+
+test('marker-in-first-2000: the core marker sits in the first 2000 characters', () => {
+  const index = context().indexOf('CAFEKIT-CODEX-CORE-LOADED');
+  assert.ok(index >= 0 && index < 2000, `marker at ${index}`);
+});
+
+test('command-table-complete: every recorded script has one absolute command that runs', () => {
+  const text = context();
+  const names = lib.scriptCommands(tree);
+  assert.ok(names.length > 0);
+  const table = [...text.matchAll(/^ {2}- `\{cafekit:([A-Za-z0-9-]+)\}`: `(.+)`$/gm)];
+  assert.deepEqual(table.map(([, name]) => name), names);
+  assert.ok(!/\{cafekit:[A-Za-z0-9-]+\}/.test(text.replace(/^ {2}- `\{cafekit:[^\n]*$/gm, '')), 'a command is named outside the table');
+  const scratch = fs.mkdtempSync(path.join(work, 'run-'));
+  for (const [, name, command] of table) {
+    assert.match(command, new RegExp(`^node '${tree.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/scripts/${name}\\.cjs'$`));
+    const run = spawnSync('sh', ['-c', `${command} --help`], { cwd: scratch, encoding: 'utf8', input: '' });
+    assert.ok([0, 1, 2].includes(run.status), `${name}: exit ${run.status}`);
+    assert.doesNotMatch(run.stderr, /Cannot find module|MODULE_NOT_FOUND/, name);
+  }
+});
+
+test('rule-paths-exist: the root, the rules directory and every rules file named in the core exist', () => {
+  const text = context();
+  assert.match(text, new RegExp(`means \`${tree.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\``));
+  const section = text.slice(text.indexOf('## Detailed rules'));
+  const dir = section.match(/`([^`]+\/rules)\/`/)[1];
+  assert.equal(dir, path.join(tree, 'rules'));
+  const files = [...section.matchAll(/`([a-z-]+\.md)`/g)].map(([, f]) => f);
+  assert.ok(files.length >= 9, files.join(', '));
+  for (const file of files) assert.ok(fs.existsSync(path.join(dir, file)), file);
+  assert.doesNotMatch(text, /\{CAFEKIT_ROOT\}\//, 'an unresolved root token remains');
+});
+
+test('dollar-in-root: a plugin root containing `$&` is injected literally', () => {
+  const root = path.join(work, 'dollar-$&-root', 'cf-codex');
+  fs.cpSync(tree, root, { recursive: true });
+  const text = context(root);
+  assert.ok(text.includes(`means \`${root}\``));
+  assert.ok(text.includes(`node '${root}/scripts/provenance.cjs'`));
+});
+
+test('silent-without-plugin-root: without a plugin root, or with one inherited from elsewhere, the hook prints nothing', () => {
+  for (const env of [{}, { PLUGIN_ROOT: work, CLAUDE_PLUGIN_ROOT: work }]) {
+    const result = hook(null, { env });
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(result.stdout, '');
+  }
+});
+
+function walk(root) {
+  if (!fs.existsSync(root)) return [];
+  return fs.readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
+    const full = path.join(root, entry.name);
+    return entry.isDirectory() ? walk(full) : [full];
+  });
+}
+
+test('npx-install-lacks-plugin-hook: an npx Codex install neither ships nor calls the plugin hook, and the plugin stands down beside it', () => {
+  const repo = path.join(work, 'npx-repo');
+  fs.mkdirSync(repo);
+  spawnSync('git', ['init', '-q'], { cwd: repo });
+  const install = spawnSync('node', [INSTALL, '--platform', 'codex', '-y'], { cwd: repo, encoding: 'utf8', env: { ...process.env, HOME: path.join(work, 'npx-home') } });
+  assert.equal(install.status, 0, install.stderr || install.stdout);
+  const installed = walk(repo).filter((f) => !f.includes(`${path.sep}.git${path.sep}`));
+  assert.deepEqual(installed.filter((f) => /plugin-context\.cjs$|script-commands\.json$/.test(f)), []);
+  assert.ok(!installed.some((f) => fs.readFileSync(f).includes('CAFEKIT-CODEX-CORE-LOADED')), 'the plugin core reached the npx install');
+  assert.doesNotMatch(fs.readFileSync(path.join(repo, '.codex/hooks.json'), 'utf8'), /plugin-context/);
+  const beside = hook(tree, { cwd: repo });
+  assert.equal(beside.status, 0, beside.stderr);
+  assert.equal(beside.stdout, '');
+});