@haposoft/cafekit 0.18.1 → 0.18.3

package/bin/phases/codex-hooks.js

@@ -17,21 +17,81 @@ const { PLATFORMS } = require('../lib/context');
 
 const CODEX_SRC = path.join(__dirname, '../../src/codex');
 const HOOK_COMMAND_TEMPLATE = /^node "\.codex\/hooks\/([a-z0-9-]+\.cjs)"$/;
-// Exact shapes earlier installers wrote, kept only to recognize and upgrade them. Before
-// 0.16.2 the path came from Git; 0.16.2 fixed the path but still resolved `node` through
-// PATH. Matching the whole command keeps a hook the user wrote from ever being rewritten.
-const LEGACY_POSIX_COMMANDS = [
-  /^node "\$\(git rev-parse --show-toplevel\)\/\.codex\/hooks\/([a-z0-9-]+\.cjs)"$/,
-  /^node '(?:[^']|'\\'')*[/\\]hooks[/\\]([a-z0-9-]+\.cjs)'$/,
-];
-
-function legacyPosixScript(command) {
-  if (typeof command !== 'string') return null;
-  for (const pattern of LEGACY_POSIX_COMMANDS) {
-    const match = command.match(pattern);
-    if (match) return match[1];
+const LEGACY_GIT_COMMAND = /^node "\$\(git rev-parse --show-toplevel\)\/\.codex\/hooks\/([a-z0-9-]+\.cjs)"$/;
+const SHELL_QUOTED = "'(?:[^']|'\\\\'')*'";
+const POSIX_COMMAND = new RegExp(`^(?:PATH="\\$PATH"(?::${SHELL_QUOTED})+ )?node (${SHELL_QUOTED})$`);
+const WINDOWS_LAUNCHER = 'node -e "process.argv[1]=Buffer.from(process.argv[1],\'base64url\').toString(\'utf8\');require(\'module\').runMain()" ';
+
+// Former template values from the hooks.json history. Custom expressions never
+// establish ownership, even when every handler belongs to CafeKit.
+const FORMER_MATCHERS = {
+  PreToolUse: new Set([
+    'Bash|apply_patch|Edit|Write|Read|Glob|Grep|mcp__.*',
+    'Bash|exec_command|apply_patch|Edit|Write|Read|Glob|Grep|mcp__.*|shell',
+  ]),
+  PostToolUse: new Set([
+    'Agent|spawn_agent|update_plan|task|Task|TodoWrite',
+    'apply_patch|Edit|Write|MultiEdit',
+  ]),
+};
+
+function refreshManagedMatchers(config, template, ctx) {
+  let updated = 0;
+  const hooks = { ...(config.hooks || {}) };
+  for (const [event, former] of Object.entries(FORMER_MATCHERS)) {
+    if (!Array.isArray(hooks[event])) continue;
+    hooks[event] = hooks[event].map(group => {
+      const handlers = Array.isArray(group?.hooks) ? group.hooks : [];
+      const scripts = handlers.map(managedHandlerScript);
+      if (!scripts.some(Boolean)) return group;
+      const candidates = handlers.length && scripts.every(Boolean)
+        ? (template.hooks[event] || []).filter(target => {
+          const wanted = target.hooks.map(managedHandlerScript);
+          return scripts.every(script => wanted.includes(script));
+        }) : [];
+      const target = candidates.length === 1 ? candidates[0] : null;
+      if (target && (group.matcher || '') === (target.matcher || '')) return group;
+      if (target && former.has(group.matcher)) {
+        updated += 1;
+        ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Codex hooks: ${event} matcher updated`);
+        return { ...group, matcher: target.matcher };
+      }
+      ctx.ui.warn(`Codex hooks: ${event} matcher preserved; custom, mixed, or ambiguous group. Review it manually.`);
+      return group;
+    });
   }
-  return null;
+  return { config: { ...config, hooks }, updated };
+}
+
+// A basename alone cannot prove ownership: users may also run tools/hooks/session.cjs.
+// Only known source scripts at the native runtime path and an exact emitted launcher
+// shape may be rebound or count as already registered.
+const MANAGED_SCRIPTS = new Set(fs.readdirSync(path.join(CODEX_SRC, 'hooks')).filter((name) => /^[a-z0-9-]+\.cjs$/.test(name)));
+
+function nativeScript(target) {
+  if (!path.posix.isAbsolute(target) && !path.win32.isAbsolute(target)) return null;
+  const match = target.match(/[/\\]\.codex[/\\]hooks[/\\]([a-z0-9-]+\.cjs)$/);
+  return match && MANAGED_SCRIPTS.has(match[1]) ? match[1] : null;
+}
+
+function managedCommandScript(command) {
+  if (typeof command !== 'string') return null;
+  const template = command.match(HOOK_COMMAND_TEMPLATE) || command.match(LEGACY_GIT_COMMAND);
+  if (template) return MANAGED_SCRIPTS.has(template[1]) ? template[1] : null;
+  const posix = command.match(POSIX_COMMAND);
+  if (posix) return nativeScript(posix[1].slice(1, -1).replace(/'\\''/g, "'"));
+  if (!command.startsWith(WINDOWS_LAUNCHER)) return null;
+  const encoded = command.slice(WINDOWS_LAUNCHER.length);
+  if (!/^[A-Za-z0-9_-]+$/.test(encoded)) return null;
+  const target = Buffer.from(encoded, 'base64url').toString('utf8');
+  return Buffer.from(target, 'utf8').toString('base64url') === encoded ? nativeScript(target) : null;
+}
+
+function managedHandlerScript(handler) {
+  if (handler?.type !== 'command') return null;
+  const fields = ['command', 'commandWindows'].filter((field) => handler[field] !== undefined);
+  const scripts = fields.map((field) => managedCommandScript(handler[field]));
+  return scripts.length > 0 && scripts.every((script) => script && script === scripts[0]) ? scripts[0] : null;
 }
 
 /** The hook script a command runs, which is stable across installs and platforms. */
@@ -57,8 +117,8 @@ function hookPathFor(script, projectRoot) {
  * nothing outside a repository and the *outer* root for a project nested inside one. Both
  * cases produced a path that does not exist, so Codex started every hook, every hook died,
  * and the gates were silently absent. The path is known at install time, so it is written
- * directly. The literal `/hooks/<script>.cjs` segment must survive, because hookScript()
- * reads it as the identity that lets a reinstall recognize CafeKit's own entries.
+ * directly. The literal `.codex/hooks/<script>.cjs` path and emitted launcher shape
+ * let managedHandlerScript() recognize CafeKit's own entries on a reinstall.
  */
 /**
  * Directories to fall back on when PATH carries no `node`.
@@ -88,7 +148,42 @@ function posixHookCommand(script, projectRoot) {
  */
 function windowsHookCommand(script, projectRoot) {
   const encoded = Buffer.from(hookPathFor(script, projectRoot), 'utf8').toString('base64url');
-  return 'node -e "process.argv[1]=Buffer.from(process.argv[1],\'base64url\').toString(\'utf8\');require(\'module\').runMain()" ' + encoded;
+  return WINDOWS_LAUNCHER + encoded;
+}
+
+// The Codex plugin cannot carry absolute paths: its root moves on every update and
+// differs per machine. Codex exports PLUGIN_ROOT to plugin hooks, so both launchers
+// resolve it at run time, and the PATH floor lists only machine-independent aliases.
+const PLUGIN_NODE_FALLBACKS = ['/usr/local/bin', '/opt/homebrew/bin'];
+
+/** Launchers for one hook script inside the Codex plugin tree. */
+function pluginHookCommands(script) {
+  if (!/^[a-z0-9-]+\.cjs$/.test(script)) throw new Error(`Unsupported Codex plugin hook script: ${script}`);
+  const fallbacks = PLUGIN_NODE_FALLBACKS.map((dir) => `:${shellQuote(dir)}`).join('');
+  return {
+    command: `PATH="$PATH"${fallbacks} node "\${PLUGIN_ROOT}/hooks/${script}"`,
+    commandWindows: `node -e "process.argv[1]=require('path').join(process.env.PLUGIN_ROOT,'hooks','${script}');require('module').runMain()"`,
+  };
+}
+
+/** The plugin's hooks.json: the managed template with every launcher rebound to PLUGIN_ROOT. */
+function pluginHooksConfig(template) {
+  const hooks = {};
+  for (const [eventName, groups] of Object.entries(template.hooks || {})) {
+    hooks[eventName] = groups.map((group) => ({
+      ...group,
+      hooks: group.hooks.map((handler) => {
+        const match = String(handler.command).match(HOOK_COMMAND_TEMPLATE);
+        if (!match) throw new Error(`Unsupported Codex hook command: ${handler.command}`);
+        return { ...handler, ...pluginHookCommands(match[1]) };
+      }),
+    }));
+  }
+  return {
+    ...template,
+    description: 'CafeKit lifecycle hooks for the Codex plugin. Review and trust them with /hooks before they run.',
+    hooks,
+  };
 }
 
 /** Rewrite a managed template handler into absolute launchers for both platforms. */
@@ -104,10 +199,9 @@ function materializeHookCommands(handler, projectRoot) {
 }
 
 /**
- * Repair launchers an older installer wrote. A reinstall treats an already-registered
- * script as the user's placement and leaves it alone, so without this pass every existing
- * project would keep its broken git-derived command forever. Only the exact byte pattern
- * CafeKit itself emitted is rewritten; anything else stays untouched.
+ * Rebind recognized CafeKit launchers after an upgrade or a project move. Registration
+ * preserves the user's event/matcher placement; only emitted command shapes change,
+ * and a custom field for another platform remains untouched.
  */
 function repairLegacyCodexLaunchers(config, projectRoot) {
   if (!config.hooks) return { config, repaired: 0 };
@@ -120,13 +214,13 @@ function repairLegacyCodexLaunchers(config, projectRoot) {
       return {
         ...group,
         hooks: group.hooks.map((handler) => {
-          const legacy = legacyPosixScript(handler?.command);
-          const template = typeof handler?.commandWindows === 'string'
-            && handler.commandWindows.match(HOOK_COMMAND_TEMPLATE);
-          if (!legacy && !template) return handler;
+          if (handler?.type !== 'command') return handler;
           const next = { ...handler };
-          if (legacy) next.command = posixHookCommand(legacy, projectRoot);
-          if (template) next.commandWindows = windowsHookCommand(template[1], projectRoot);
+          for (const [field, build] of [['command', posixHookCommand], ['commandWindows', windowsHookCommand]]) {
+            const script = managedCommandScript(handler[field]);
+            if (script) next[field] = build(script, projectRoot);
+          }
+          if (next.command === handler.command && next.commandWindows === handler.commandWindows) return handler;
           repaired += 1;
           return next;
         }),
@@ -139,7 +233,7 @@ function repairLegacyCodexLaunchers(config, projectRoot) {
 /** Drop CafeKit hooks the manifest has retired, leaving foreign entries untouched. */
 function pruneObsoleteCodexHooks(config, ctx) {
   const obsolete = ctx.manifest?.obsolete?.settingsHookCommandSubstrings || [];
-  if (!config.hooks || obsolete.length === 0) return { config, removed: 0 };
+  if (!config.hooks) return { config, removed: 0 };
 
   let removed = 0;
   const pruned = {};
@@ -150,7 +244,8 @@ function pruneObsoleteCodexHooks(config, ctx) {
       if (!Array.isArray(group?.hooks)) { keptGroups.push(group); continue; }
       const keptHooks = group.hooks.filter((handler) => {
         const command = handler?.command || '';
-        const isObsolete = obsolete.some((substring) => command.includes(substring));
+        const isObsolete = obsolete.some((substring) => command.includes(substring))
+          || (eventName === 'SessionStart' && managedHandlerScript(handler) === 'docs-sync.cjs');
         if (isObsolete) removed += 1;
         return !isObsolete;
       });
@@ -196,12 +291,15 @@ function mergeCodexHooks(ctx, platformKey, projectRoot = process.cwd()) {
     ctx.results.updated++;
   }
 
-  const { config: base, repaired } = repairLegacyCodexLaunchers(pruned, projectRoot);
+  const { config: rebound, repaired } = repairLegacyCodexLaunchers(pruned, projectRoot);
   if (repaired > 0) {
-    ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Codex hooks: rebound ${repaired} launcher(s) written by an older installer`);
+    ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Codex hooks: rebound ${repaired} launcher(s) to the current project`);
     ctx.results.updated++;
   }
 
+  const { config: base, updated: matcherUpdates } = refreshManagedMatchers(rebound, managed, ctx);
+  ctx.results.updated += matcherUpdates;
+
   const merged = { ...base };
   if (typeof managed.description === 'string' && typeof merged.description !== 'string') {
     merged.description = managed.description;
@@ -215,7 +313,7 @@ function mergeCodexHooks(ctx, platformKey, projectRoot = process.cwd()) {
     // it. Matching on the script rather than the whole command survives the path
     // differences between installs and platforms.
     const registered = new Set(
-      groups.flatMap((group) => (group?.hooks || []).map((handler) => hookScript(handler?.command))).filter(Boolean),
+      groups.flatMap((group) => (Array.isArray(group?.hooks) ? group.hooks : []).map(managedHandlerScript)).filter(Boolean),
     );
 
     for (const managedGroup of managedGroups) {
@@ -242,7 +340,7 @@ function mergeCodexHooks(ctx, platformKey, projectRoot = process.cwd()) {
     merged.hooks[eventName] = groups;
   }
 
-  if (added === 0 && removed === 0) {
+  if (added === 0 && removed === 0 && matcherUpdates === 0) {
     ctx.ui.detail(`  → ${ctx.dryRun ? '[dry-run] ' : ''}Codex hooks: already registered`);
     ctx.results.unchanged++;
   }
@@ -254,8 +352,11 @@ function mergeCodexHooks(ctx, platformKey, projectRoot = process.cwd()) {
 }
 
 module.exports = {
+  managedHandlerScript,
   mergeCodexHooks,
   pruneObsoleteCodexHooks,
   repairLegacyCodexLaunchers,
   hookScript,
+  pluginHookCommands,
+  pluginHooksConfig,
 };

package/bin/phases/codex-runtime.js

@@ -2,10 +2,11 @@
 
 const fs = require('fs');
 const path = require('path');
-const { PLATFORMS } = require('../lib/context');
-const { writeManagedFile, copyManagedTree } = require('../lib/managed-writer');
+const { PLATFORMS, getCopyOptions } = require('../lib/context');
+const { writeManagedFile } = require('../lib/managed-writer');
 const { report, treeAction } = require('./report');
-const { copyRulesDirectory, copyOutputStylesDirectory } = require('./claude-runtime');
+const { isGeneratedArtifact } = require('../lib/copy-utils');
+const { removeObsoleteRuntimeFiles } = require('./claude-runtime');
 const {
   managedRange,
   upsertManagedCodexBlock
@@ -23,30 +24,9 @@ const CODEX_OWN_RUNTIME = [
   ['runtime.json', 'runtime.json']
 ];
 
-/**
- * Delete hooks, scripts and skill files the manifest marks obsolete. Codex tracker keys are project-relative
- * (`.codex/hooks/…`), so the record is pruned through keyFor, and always: a record whose
- * file is already gone must still leave the manifest.
- */
+/** Use the shared ownership and symlink checks for Codex runtime cleanup. */
 function removeObsoleteCodexHooks(ctx, platformKey) {
-  const platform = PLATFORMS[platformKey];
-  const tracker = ctx.trackers && ctx.trackers[platformKey];
-  const obsoleteHooks = (ctx.manifest?.obsolete?.runtimeFiles || []).filter((rel) => rel.startsWith('hooks/') || rel.startsWith('scripts/') || rel.startsWith('skills/'));
-  for (const rel of obsoleteHooks) {
-    // Skill files live in the shared skills directory, not under the runtime folder.
-    const target = rel.startsWith('skills/')
-      ? path.join(platform.skillsDir, rel.slice('skills/'.length))
-      : path.join(platform.folder, rel);
-    const exists = fs.existsSync(target);
-    if (!ctx.dryRun) {
-      if (exists) fs.rmSync(target, { force: true, recursive: fs.statSync(target).isDirectory() });
-      if (tracker) tracker.prune(tracker.keyFor(target));
-    }
-    if (exists) {
-      ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Removed obsolete Codex runtime: ${rel}`);
-      ctx.results.updated++;
-    }
-  }
+  removeObsoleteRuntimeFiles(ctx, platformKey);
 }
 
 function writeSourceFile(ctx, platformKey, src, dest, label) {
@@ -61,8 +41,105 @@ function writeSourceFile(ctx, platformKey, src, dest, label) {
   report(ctx, action, label);
 }
 
+// A shim in src/codex/hooks/lib re-exports one Claude library so the source tree
+// keeps a single copy; installs ship the real Claude file in its place.
+const SHIM_PATTERN = /^(?:['"]use strict['"];?\s*)?module\.exports\s*=\s*require\(['"]\.\.\/\.\.\/\.\.\/claude\/hooks\/lib\/([^'"/]+)['"]\);?\s*$/;
+
+function isCodexShim(file, name) {
+  const match = fs.readFileSync(file, 'utf8').match(SHIM_PATTERN);
+  return Boolean(match && match[1] === name);
+}
+
+/**
+ * The Codex runtime files and where they land under the runtime root, shared by
+ * this installer and the Codex plugin build so the two cannot drift apart.
+ * Each entry: { src, dest (relative), group, transform: 'codex-body' | null }.
+ */
+function codexRuntimeLayout() {
+  const entries = [];
+  const add = (src, dest, group, transform = null) => entries.push({ src, dest, group, transform });
+  const hookDir = path.join(CODEX_SRC, 'hooks');
+  const libDir = path.join(hookDir, 'lib');
+  // Hooks ship file by file; a directory or symlink here would be dropped silently.
+  const requireFile = (file) => {
+    if (!fs.lstatSync(file).isFile()) throw new Error(`Codex runtime layout expects a regular file: ${file}`);
+    return file;
+  };
+  for (const name of fs.readdirSync(hookDir)) {
+    if (name !== 'lib' && !isGeneratedArtifact(name)) add(requireFile(path.join(hookDir, name)), `hooks/${name}`, 'hooks');
+  }
+  const sharedLibraries = [];
+  for (const name of fs.readdirSync(libDir)) {
+    if (isGeneratedArtifact(name)) continue;
+    const file = requireFile(path.join(libDir, name));
+    if (isCodexShim(file, name)) sharedLibraries.push(name);
+    else add(file, `hooks/lib/${name}`, 'hooks');
+  }
+  add(path.join(SRC, 'claude', 'runtime.schema.json'), 'runtime.schema.json', 'schema');
+  for (const name of sharedLibraries) add(path.join(SRC, 'claude', 'hooks', 'lib', name), `hooks/lib/${name}`, 'shared-lib');
+  const overrides = fs.readdirSync(path.join(CODEX_SRC, 'rules')).filter((name) => !isGeneratedArtifact(name));
+  for (const name of fs.readdirSync(path.join(SRC, 'claude', 'rules'))) {
+    if (!overrides.includes(name) && !isGeneratedArtifact(name)) add(path.join(SRC, 'claude', 'rules', name), `rules/${name}`, 'rules', 'codex-body');
+  }
+  for (const name of fs.readdirSync(path.join(SRC, 'claude', 'output-styles'))) {
+    if (!isGeneratedArtifact(name)) add(path.join(SRC, 'claude', 'output-styles', name), `output-styles/${name}`, 'output-styles', 'codex-body');
+  }
+  for (const name of overrides) add(path.join(CODEX_SRC, 'rules', name), `rules/${name}`, 'rule-overrides');
+  return entries;
+}
+
+/** Every layout group in install order with its report label; null reports each file. */
+const LAYOUT_GROUPS = [
+  ['hooks', 'Codex native hooks'],
+  ['schema', null],
+  ['shared-lib', null],
+  ['rules', 'rules/ directory'],
+  ['output-styles', 'output-styles/ directory'],
+  ['rule-overrides', 'Codex native rule overrides']
+];
+
+const SHARED_LIB_LABELS = {
+  'runtime.schema.json': 'Codex runtime schema',
+  'privacy-command-analysis.cjs': 'Codex privacy command analyzer',
+  'privacy-paths.cjs': 'Codex privacy path analyzer',
+  'secret-keywords.cjs': 'Codex secret keyword matcher',
+  'runtime-path-safety.cjs': 'Codex runtime path safety',
+  'inspect-paths.cjs': 'Codex inspection path analyzer',
+  'spec-touch.cjs': 'Codex spec touch helpers',
+  'update-check.cjs': 'Codex update check'
+};
+
+/** Write one layout group; `label` reports the group, or each file when omitted. */
+function writeLayoutGroup(ctx, platformKey, entries, label) {
+  const platform = PLATFORMS[platformKey];
+  const bodyTransform = getCopyOptions(platformKey, {}).transform;
+  const agg = { created: 0, updated: 0, unchanged: 0, preserved: 0, missing: 0 };
+  for (const entry of entries) {
+    const { action } = writeManagedFile({
+      src: entry.src,
+      dest: path.join(platform.folder, entry.dest),
+      sourceRoot: SRC,
+      platformFolder: platform.folder,
+      ctx,
+      tracker: ctx.trackers[platformKey],
+      transform: entry.transform === 'codex-body' ? bodyTransform : undefined
+    });
+    if (label) {
+      if (agg[action] !== undefined) agg[action]++;
+    } else {
+      const name = path.basename(entry.dest);
+      report(ctx, action, SHARED_LIB_LABELS[name] || `Codex hook helper: ${name}`);
+    }
+  }
+  if (label) report(ctx, treeAction(agg), label);
+}
+
 function installRuntimeFiles(ctx, platformKey) {
   const platform = PLATFORMS[platformKey];
+  // Validate the whole layout before the first write, so a bad source cannot leave a partial install.
+  const layout = codexRuntimeLayout();
+  const unknown = layout.filter((entry) => !LAYOUT_GROUPS.some(([name]) => name === entry.group));
+  if (unknown.length) throw new Error(`Codex runtime layout group not installed: ${unknown[0].group}`);
   for (const [sourceRel, targetRel] of CODEX_OWN_RUNTIME) {
     writeSourceFile(
       ctx,
@@ -82,61 +159,12 @@ function installRuntimeFiles(ctx, platformKey) {
 
   mergeCodexHooks(ctx, platformKey);
 
-  const agg = copyManagedTree({
-    src: path.join(CODEX_SRC, 'hooks'),
-    dest: path.join(platform.folder, 'hooks'),
-    platformFolder: platform.folder,
-    ctx,
-    tracker: ctx.trackers[platformKey]
-  });
-  report(ctx, treeAction(agg), 'Codex native hooks');
-  removeObsoleteCodexHooks(ctx, platformKey);
-  // Keep one canonical command analyzer in the Claude source tree, then
-  // materialize the same bytes into the installed Codex runtime.
-  // One canonical runtime schema lives in the Claude source tree; both installed
-  // runtimes reference it as ./runtime.schema.json beside their runtime.json.
-  writeSourceFile(
-    ctx,
-    platformKey,
-    path.join(SRC, 'claude', 'runtime.schema.json'),
-    path.join(platform.folder, 'runtime.schema.json'),
-    'Codex runtime schema'
-  );
-  writeSourceFile(
-    ctx,
-    platformKey,
-    path.join(SRC, 'claude', 'hooks', 'lib', 'privacy-command-analysis.cjs'),
-    path.join(platform.folder, 'hooks', 'lib', 'privacy-command-analysis.cjs'),
-    'Codex privacy command analyzer'
-  );
-  writeSourceFile(
-    ctx,
-    platformKey,
-    path.join(SRC, 'claude', 'hooks', 'lib', 'secret-keywords.cjs'),
-    path.join(platform.folder, 'hooks', 'lib', 'secret-keywords.cjs'),
-    'Codex secret keyword matcher'
-  );
-  writeSourceFile(
-    ctx,
-    platformKey,
-    path.join(SRC, 'claude', 'hooks', 'lib', 'runtime-path-safety.cjs'),
-    path.join(platform.folder, 'hooks', 'lib', 'runtime-path-safety.cjs'),
-    'Codex runtime path safety'
-  );
-}
-
-function installNativeRuleOverrides(ctx, platformKey) {
-  const platform = PLATFORMS[platformKey];
-  const source = path.join(CODEX_SRC, 'rules');
-  if (!fs.existsSync(source)) return;
-  const agg = copyManagedTree({
-    src: source,
-    dest: path.join(platform.folder, 'rules'),
-    platformFolder: platform.folder,
-    ctx,
-    tracker: ctx.trackers[platformKey]
-  });
-  report(ctx, treeAction(agg), 'Codex native rule overrides');
+  for (const [name, label] of LAYOUT_GROUPS) {
+    writeLayoutGroup(ctx, platformKey, layout.filter((entry) => entry.group === name), label);
+    // Obsolete hook files go before the canonical schema and shared Claude libraries
+    // are materialized, matching the order earlier installs used.
+    if (name === 'hooks') removeObsoleteCodexHooks(ctx, platformKey);
+  }
 }
 
 function installManagedAgentsMd(ctx) {
@@ -170,11 +198,8 @@ function installManagedAgentsMd(ctx) {
 function installCodexRuntime(ctx, platformKey) {
   if (platformKey !== 'codex') return ctx;
   installRuntimeFiles(ctx, platformKey);
-  copyRulesDirectory(ctx, platformKey);
-  copyOutputStylesDirectory(ctx, platformKey);
-  installNativeRuleOverrides(ctx, platformKey);
   installManagedAgentsMd(ctx);
   return ctx;
 }
 
-module.exports = { installCodexRuntime };
+module.exports = { installCodexRuntime, codexRuntimeLayout, LAYOUT_GROUPS };

package/bin/phases/copy-payload.js

@@ -16,6 +16,7 @@ const {
   getCopyOptions
 } = require('../lib/context');
 const { writeManagedFile, copyManagedTree } = require('../lib/managed-writer');
+const { hashFile } = require('../lib/manifest');
 const { report, treeAction } = require('./report');
 const {
   codexAgentName,
@@ -24,6 +25,43 @@ const {
 
 const SRC = path.join(__dirname, '../../src');
 
+// Codex ignores `disable-model-invocation`; its explicit-only switch is this file beside SKILL.md.
+const CODEX_POLICY_FILE = path.join('agents', 'openai.yaml');
+const CODEX_EXPLICIT_ONLY_POLICY = 'policy:\n  allow_implicit_invocation: false\n';
+
+function isExplicitOnlySkill(skillSource) {
+  const skillFile = path.join(skillSource, 'SKILL.md');
+  if (!fs.existsSync(skillFile)) return false;
+  const frontmatter = fs.readFileSync(skillFile, 'utf8').match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  // Quoted or bare, as the catalog parser reads it: a skill the catalog hides must also get the policy.
+  return Boolean(frontmatter) && /^disable-model-invocation:\s*(["']?)true\1\s*$/m.test(frontmatter[1]);
+}
+
+/**
+ * Keep a Codex skill's policy file in step with its source: write it (owned) for an explicit-only
+ * skill, and remove an owned, unmodified copy once the skill is no longer explicit-only. A copy the
+ * user wrote or edited is left alone.
+ */
+function syncCodexInvocationPolicy({ skillSource, skillDest, platformFolder, ctx, tracker }) {
+  const dest = path.join(skillDest, CODEX_POLICY_FILE);
+  if (isExplicitOnlySkill(skillSource)) {
+    const { action } = writeManagedFile({ dest, platformFolder, ctx, tracker, content: CODEX_EXPLICIT_ONLY_POLICY });
+    report(ctx, action, `skill policy: ${path.basename(skillDest)}`);
+    return;
+  }
+  if (!fs.existsSync(dest) || !fs.lstatSync(dest).isFile()) return;
+  const key = tracker.keyFor(dest);
+  const owned = ctx.ownership?.[platformFolder]?.files?.[key]?.sha256;
+  if (!owned || owned !== hashFile(dest)) return;
+  if (!ctx.dryRun) {
+    fs.rmSync(dest, { force: true });
+    tracker.prune(key);
+    const agentsDir = path.dirname(dest);
+    if (fs.readdirSync(agentsDir).length === 0) fs.rmdirSync(agentsDir);
+  }
+  ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Removed skill policy: ${dest}`);
+}
+
 /**
  * Spec command files installed for a platform. Claude ships spec-* commands.
  */
@@ -97,9 +135,7 @@ function copyPlatformFiles(ctx, platformKey) {
     // The specs skill tree above carries its templates; remove the ones retired
     // with the spec.json planning flow from earlier installs.
     if (platformKey === 'claude' || platformKey === 'codex') {
-      const retiredTemplates = platformKey === 'claude'
-        ? ['init.json', 'spec-state.json', 'requirements-init.md', 'requirements.md', 'design.md', 'task.md']
-        : ['spec-state.json', 'requirements-init.md', 'requirements.md', 'design.md', 'task.md'];
+      const retiredTemplates = ['init.json', 'spec-state.json', 'requirements-init.md', 'requirements.md', 'design.md', 'task.md'];
       for (const fileName of retiredTemplates) {
         const retired = path.join(platform.skillsDir, 'specs', 'templates', fileName);
         if (!fs.existsSync(retired)) continue;
@@ -134,6 +170,9 @@ function copyPlatformFiles(ctx, platformKey) {
           });
           ctx.results.installedSkills++;
           report(ctx, treeAction(agg), `Skill: ${skillName}`);
+          if (platformKey === 'codex') {
+            syncCodexInvocationPolicy({ skillSource, skillDest, platformFolder, ctx, tracker });
+          }
         } else {
           report(ctx, 'missing', `skill: ${skillName}`);
         }
@@ -223,4 +262,11 @@ function copyPlatformFiles(ctx, platformKey) {
   return ctx;
 }
 
-module.exports = { copyPlatformFiles, getPlatformSpecFiles };
+module.exports = {
+  copyPlatformFiles,
+  getPlatformSpecFiles,
+  // Shared with the Codex plugin build so plugin and npx skills carry the same policy.
+  isExplicitOnlySkill,
+  CODEX_POLICY_FILE,
+  CODEX_EXPLICIT_ONLY_POLICY
+};

package/bin/phases/omp-runtime.js

@@ -23,7 +23,7 @@ const path = require('path');
 const { PLATFORMS } = require('../lib/context');
 const { writeManagedFile, copyManagedTree } = require('../lib/managed-writer');
 const { report, treeAction } = require('./report');
-const { copyRulesDirectory } = require('./claude-runtime');
+const { copyRulesDirectory, removeObsoleteRuntimeFiles } = require('./claude-runtime');
 
 const SRC = path.join(__dirname, '../../src');
 const CLAUDE_SRC = path.join(SRC, 'claude');
@@ -128,34 +128,12 @@ function installBridge(ctx, platformKey) {
   }
 }
 
-/**
- * Delete hooks, scripts and skill files the manifest marks obsolete. Mirrors removeObsoleteClaudeRuntimeFiles, but the
- * omp tracker records keys relative to the project root (`.omp/hooks/…`), so the record is
- * pruned through keyFor rather than by the bare `hooks/…` path.
- */
-function removeObsoleteOmpHooks(ctx, platformKey) {
-  const platform = PLATFORMS[platformKey];
-  const tracker = ctx.trackers && ctx.trackers[platformKey];
-  const obsoleteHooks = (ctx.manifest?.obsolete?.runtimeFiles || []).filter((rel) => rel.startsWith('hooks/') || rel.startsWith('scripts/') || rel.startsWith('skills/'));
-  for (const rel of obsoleteHooks) {
-    // Skill files live in the shared skills directory, not under the runtime folder.
-    const target = rel.startsWith('skills/')
-      ? path.join(platform.skillsDir, rel.slice('skills/'.length))
-      : path.join(platform.folder, rel);
-    if (!fs.existsSync(target)) continue;
-    if (!ctx.dryRun) {
-      fs.rmSync(target, { force: true, recursive: fs.statSync(target).isDirectory() });
-      if (tracker) tracker.prune(tracker.keyFor(target));
-    }
-    ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Removed obsolete omp runtime: ${rel}`);
-    ctx.results.updated++;
-  }
-}
-
 function installOmpRuntime(ctx, platformKey) {
   if (platformKey !== 'omp') return;
   installHooks(ctx, platformKey);
-  removeObsoleteOmpHooks(ctx, platformKey);
+  // Obsolete hooks, scripts and the old `.mjs` bridge go only when their bytes still match the
+  // ownership record; an edited, untracked or symlinked copy is kept and reported.
+  removeObsoleteRuntimeFiles(ctx, platformKey);
   installRuntimeFiles(ctx, platformKey);
   installBridge(ctx, platformKey);
   copyRulesDirectory(ctx, platformKey);

package/bin/phases/root-config.js

@@ -17,11 +17,14 @@
 const fs = require('fs');
 const path = require('path');
 
-/** True if `lines` already carries `pattern` with or without a trailing slash. */
+/**
+ * True if `lines` already carries `pattern` with or without a trailing slash, or as
+ * `dir/*`, which ignores the same files while letting a later `!dir/sub/` re-include one.
+ */
 function hasPattern(lines, pattern) {
   const bare = pattern.replace(/\/$/, '');
   const withSlash = bare + '/';
-  return lines.includes(pattern) || lines.includes(bare) || lines.includes(withSlash);
+  return lines.includes(pattern) || lines.includes(bare) || lines.includes(withSlash) || lines.includes(bare + '/*');
 }
 
 const PLAN_PATTERNS = new Set([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.18.1",
+  "version": "0.18.3",
   "description": "Native spec-driven workflows for Claude Code and Codex CLI. Bundles CafeKit skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/CLAUDE.md

@@ -7,6 +7,10 @@
 
 ## Claude Code runtime
 
+Project notes (commands, files to leave unchanged, slow or expensive operations)
+belong in the root AGENTS.md after the CAFEKIT CORE END marker; Claude Code reads
+them through `@AGENTS.md`.
+
 - Edit project skills under `.claude/skills/`, not `~/.claude/skills`.
 - Run Python skill scripts with the skill venv:
   - macOS/Linux: `.claude/skills/.venv/bin/python3 scripts/<script>.py`
@@ -17,7 +21,7 @@
   GATE-REVIEW after adversarial review. It never starts implementation.
 - Start implementation only through a new explicit `/cf:develop` invocation.
   Execute one unblocked task at a time; each task has exactly one `Status:`
-  field and the controller is its sole state-and-proof writer.
+  field and the controller is its sole state-and-proof writer. Inside a vibe run, the vibe-run exception in the state-sync rule applies.
 - Use `/cf:sync` for surgical updates to observed file state. A done task
   requires a canonical final inline `## Receipt` with the exact command,
   `Exit: 0`, `Verification: PASS`, runtime-derived Base and Head values, and