@haposoft/cafekit 0.18.1 → 0.18.2

package/bin/lib/codex-install.js

@@ -8,6 +8,22 @@ const { preserveAddressingSection } = require('./instruction-blocks');
 const CODEX_BLOCK_START = '<!-- CAFEKIT CODEX START -->';
 const CODEX_BLOCK_END = '<!-- CAFEKIT CODEX END -->';
 const INSTRUCTION_EXTENSIONS = new Set(['.md', '.mdx', '.txt']);
+const CODEX_ASK_DESCRIPTION_BOUNDARY = 'A request to fix or change something is still answered without editing any file; point the user to $cf-fix.';
+const CODEX_ASK_NOTE = 'Rule 1 (Codex): never edit, create, or delete files in this skill, '
+  + 'even when the user says fix it or sửa giúp luôn. Do not run commands that write files. '
+  + 'Answer the cause with evidence and tell the user to run $cf-fix.';
+const CODEX_RESEARCH_DEPTH_MARKER = 'Codex research depth: treat a settled repository decision that remains in force as a known option.';
+const CODEX_RESEARCH_DEPTH_NOTE = CODEX_RESEARCH_DEPTH_MARKER
+  + ' Use Quick for that decision. An outdated supporting rationale alone does not raise depth '
+  + 'unless correcting it changes the recommendation. Conflicting evidence that changes the '
+  + 'recommendation still requires escalation under the depth table.';
+const CODEX_SPECS_SCOPE_MARKER = 'Codex scope gate: put the GATE-SCOPE question in the final answer of the turn.';
+const CODEX_SPECS_SCOPE_NOTE = CODEX_SPECS_SCOPE_MARKER
+  + ' Ask it there, not in commentary or through `request_user_input`. Do not send a summary after the question. '
+  + 'For each item needing a decision, use `[NEEDS CLARIFICATION: <question>]`, replacing <question> '
+  + 'with the real question, not a placeholder or a quotation of this note. Offer EXPAND, KEEP, and CUT together. '
+  + 'Preserve the exact words NEEDS CLARIFICATION, EXPAND, KEEP, and CUT; do not translate them. '
+  + 'Wait for the user to decide; do not choose scope or implement code on their behalf.';
 
 const AGENT_NAMES = [
   'brainstormer',
@@ -200,11 +216,15 @@ function normalizeAskUserQuestion(content) {
   const oneSeparator = '(?:[^\\S\\r\\n]+|[^\\S\\r\\n]*\\r?\\n[^\\S\\r\\n]*)';
   const pattern = new RegExp(
     `(?:(\\b(?:${determinerPattern}|[0-9]+)\\b)(${oneSeparator}))?`
-      + `(\\bAskUserQuestion\\b|${masked.askMarkerPattern})`,
+      + `(\\bAskUserQuestion\\b|${masked.askMarkerPattern}|\\bnative(?:\\s+structured user-input|\\s+input)\\s+tool\\b)`,
     'g'
   );
-  const normalized = masked.content.replace(pattern, (match, determiner, spacing, _token, offset, source) => {
-    const literalIndex = match.indexOf('AskUserQuestion');
+  const withoutRuntimePossessive = masked.content.replace(
+    /\bthe runtime['’]s\s+native(?:\s+structured user-input|\s+input)\s+tool\b/g,
+    "a question in the turn's final answer"
+  );
+  const normalized = withoutRuntimePossessive.replace(pattern, (match, determiner, spacing, _token, offset, source) => {
+    const literalIndex = match.search(/AskUserQuestion|\bnative\b/);
     const tokenOffset = offset + (literalIndex >= 0
       ? literalIndex
       : match.indexOf(masked.askMarkerPrefix));
@@ -219,18 +239,33 @@ function normalizeAskUserQuestion(content) {
       const normalizedDeterminer = /^an$/i.test(determiner)
         ? (determiner[0] === 'A' ? 'A' : 'a')
         : determiner;
-      return `${normalizedDeterminer}${spacing}structured user-input request`;
+      return `${normalizedDeterminer}${spacing}question in the turn's final answer`;
     }
 
     const trailing = source.slice(offset + match.length);
     const pluralContext = new RegExp(`^${oneSeparator}(?:calls|batches)\\b`, 'i').test(trailing);
-    return `${pluralContext ? '' : 'a '}structured user-input request`;
+    return `${pluralContext ? '' : 'a '}question in the turn's final answer`;
   });
   return masked.restore(normalized);
 }
 
-function normalizeRuntimePaths(content) {
-  return normalizeSourcePaths(content, {
+function normalizeRuntimePaths(content, sourcePath = '') {
+  const stateRootsPattern = /const RUNTIME_STATE_ROOTS = Object\.freeze\(\[[\s\S]*?\]\);/;
+  const sharedStateRoots = path.basename(sourcePath) === 'provenance.cjs'
+    ? content.match(stateRootsPattern)?.[0] : null;
+  const preservedRoots = [];
+  let markerPrefix = '\uE000CAFEKIT_HOST_';
+  while (content.includes(markerPrefix)) markerPrefix += '_';
+  const rootToken = /(?<![\w/\\])\.claude(?:[/\\])?(?![\w/\\.-])/g;
+  const instruction = isInstructionAsset(sourcePath) ? content.replace(/^.*$/gm, line => {
+    if (!/(?<![\w/\\])\.codex(?:[/\\])?(?![\w/\\.-])/.test(line)) return line;
+    return line.replace(rootToken, original => {
+      const marker = `${markerPrefix}${preservedRoots.length}\uE001`;
+      preservedRoots.push([marker, original]);
+      return marker;
+    });
+  }) : content;
+  let next = normalizeSourcePaths(instruction, {
     runtimeRoot: '.codex',
     skillsRoot: '.agents/skills'
   })
@@ -239,6 +274,15 @@ function normalizeRuntimePaths(content) {
     .replace(/(?<!~\/)\.claude(?=[/\\])/g, '.codex')
     .replace(/(['"])\.claude\1/g, '$1.codex$1')
     .replace(/`\.claude`/g, '`.codex`');
+  // This table describes every runtime's generated state, not the install root.
+  if (sharedStateRoots) next = next.replace(stateRootsPattern, () => sharedStateRoots);
+  if (/\/ai-multimodal\/scripts\/(?:media_optimizer|document_converter)\.py$/.test(sourcePath.replace(/\\/g, '/'))) {
+    // Shared skills live under .agents; native support/config still lives in .codex.
+    next = next.replace(/\bclaude_dir = skills_dir\.parent\b/g,
+      "claude_dir = skills_dir.parent.parent / '.codex'");
+  }
+  for (const [marker, original] of preservedRoots) next = next.split(marker).join(original);
+  return next;
 }
 
 function normalizeSkillNames(content) {
@@ -262,6 +306,7 @@ function normalizeAgentNames(content) {
 
 function normalizeAgentInvocations(content) {
   return content
+    .replace(/\bTask\s*\(\s*Explore\s*\)/g, 'spawn_agent(agent_type="explorer", fork_turns="none", task_name="explore", message="Describe the scan")')
     .replace(/\bAgent\s*\(/g, 'spawn_agent(')
     .replace(/\bsubagent_type\s*=\s*"([^"]+)"/g, (_match, name) => (
       `agent_type="${normalizeAgentRole(name)}", fork_turns="none"`
@@ -286,15 +331,60 @@ function isInstructionAsset(sourcePath) {
 }
 
 function normalizeCodexBody(content, sourcePath = '') {
-  let next = normalizeRuntimePaths(String(content));
+  let next = normalizeRuntimePaths(String(content), sourcePath);
   next = next
-    .replace(/\bCLAUDE\.md\b/g, 'AGENTS.md')
+    .replace(/^.*$/gm, line => line.replace(/\bCLAUDE\.md\b/g, (name, offset) => (
+      isInstructionAsset(sourcePath) && /(?<![\w/\\])AGENTS\.md\b/.test(line)
+        && !/[\w/\\]/.test(line[offset - 1] || '') ? name : 'AGENTS.md'
+    )))
     .replace(/\bClaude Code\b/g, 'Codex CLI');
 
   if (!isInstructionAsset(sourcePath)) return next;
 
+  if (/(?:^|\/)rules\/orchestrator\.md$/.test(String(sourcePath).replace(/\\/g, '/'))) {
+    next = next
+      .replace('When the current session or a subagent runs on a model below `fable` (e.g. `opus`, `sonnet`, `haiku`) and hits a hard problem',
+        'When the current session or a subagent hits a hard problem')
+      .replace('It runs autonomously on the strongest available model',
+        'It runs autonomously with high reasoning effort on the session model unless configuration selects another');
+  }
+
   next = normalizeAgentInvocations(normalizeAgentNames(normalizeSkillNames(next)));
-  return applyReplacements(normalizeAskUserQuestion(next), INSTRUCTION_REPLACEMENTS);
+  next = next.replace(/`?CLAUDE_CODE_SUBAGENT_MODEL`?/g,
+    'the configured agent model (`model` in `.codex/agents/<agent>.toml`, or `[agents].default_subagent_model` in native Codex configuration)');
+  next = applyReplacements(normalizeAskUserQuestion(next), INSTRUCTION_REPLACEMENTS);
+  const { frontmatter, body } = splitFrontmatter(next);
+  if (frontmatter.when_to_use && frontmatter.description) {
+    const description = `${frontmatter.description} Use when: ${frontmatter.when_to_use}`;
+    if (description.length <= 1024) {
+      const header = next.slice(0, next.length - body.length)
+        .replace(/^description:[^\r\n]*(?:\r?\n[ \t]+[^\r\n]*)*/m,
+          () => `description: ${JSON.stringify(description)}`);
+      next = header + body;
+    }
+  }
+  // Only the installed ask skill receives this Codex-specific boundary, never eval prompts.
+  if (/(?:^|\/)skills\/ask\/SKILL\.md$/.test(String(sourcePath).replace(/\\/g, '/'))) {
+    const { frontmatter, body } = splitFrontmatter(next);
+    const description = `${frontmatter.description} ${CODEX_ASK_DESCRIPTION_BOUNDARY}`;
+    if (description.length > 1024) throw new Error('Codex ask description exceeds 1024 characters');
+    const header = next.slice(0, next.length - body.length)
+      .replace(/^description:[^\r\n]*$/m, () => `description: ${JSON.stringify(description)}`);
+    next = `${header}\n${CODEX_ASK_NOTE}\n\n${body}`;
+  }
+  // Only the installed research skill receives this note, never prompts or templates.
+  if (/(?:^|\/)skills\/research\/SKILL\.md$/.test(String(sourcePath).replace(/\\/g, '/'))) {
+    const { body } = splitFrontmatter(next);
+    const header = next.slice(0, next.length - body.length);
+    next = `${header}\n${CODEX_RESEARCH_DEPTH_NOTE}\n\n${body}`;
+  }
+  // Only the installed specs skill receives this note, never prompts or templates.
+  if (/(?:^|\/)skills\/specs\/SKILL\.md$/.test(String(sourcePath).replace(/\\/g, '/')) && !next.includes(CODEX_SPECS_SCOPE_NOTE)) {
+    const { body } = splitFrontmatter(next);
+    const header = next.slice(0, next.length - body.length);
+    next = `${header}\n${CODEX_SPECS_SCOPE_NOTE}\n\n${body}`;
+  }
+  return next;
 }
 
 function getCodexCopyOptions(baseOptions = {}) {
@@ -307,14 +397,42 @@ function getCodexCopyOptions(baseOptions = {}) {
 function convertCodexAgentContent(content, fileName = '') {
   const { frontmatter, body } = splitFrontmatter(content);
   const name = codexAgentName(frontmatter.name || fileName);
-  const description = normalizeCodexBody(
+  let description = normalizeCodexBody(
     frontmatter.description || `CafeKit Codex agent: ${name}`
   );
-  const instructions = normalizeCodexBody(body).trim();
+  let agentBody = body;
+  if (['git_ops', 'project_manager'].includes(name)) {
+    let inTeamSection = false;
+    agentBody = body.split('\n').flatMap(line => {
+      if (/^## /.test(line)) {
+        inTeamSection = /^## (?:Team Mode|Collaborative Interlocking \(Swarm Protocol\))\s*$/.test(line);
+      }
+      if (!inTeamSection) return [line];
+      if (/\b(?:TaskList|TaskGet|TaskUpdate|SendMessage|shutdown_request)\b|When instantiated as a team member|When triggered as an active teammate/.test(line)) return [];
+      return [line.replace(/^(\s*)\d+\. /, '$1- ')];
+    }).join('\n');
+  }
+  let instructions = normalizeCodexBody(agentBody).trim();
+  const readOnly = ['brainstormer', 'code_auditor', 'inspector', 'researcher'].includes(name);
+  if (readOnly) {
+    instructions += '\n\n## Read-only role\n\nRead-only role: never create, never edit, and never delete files, and never run commands that write to disk; return findings in your reply.';
+  }
+  const reasoning = [];
+  if (name === 'strategist') {
+    description = 'Autonomous advisory counsel with high reasoning effort; inherits the session model unless native spawn or agent defaults select another. No session model switch or user interview. Mention @strategist or spawn it for hard design, debugging, or trade-off calls. Advisory-only; returns advice, not code.';
+    instructions = instructions
+      .replace('consulted for counsel and running on the strongest available model',
+        'consulted for counsel with high reasoning effort on the configured native model')
+      .replace(/## Runtime note\s+[\s\S]*$/,
+        '## Runtime note\n\nThis agent sets `model_reasoning_effort = "high"` and omits `model`. It inherits the session model unless an explicit native spawn or `[agents].default_subagent_model` selects another. No strongest-model selection is guaranteed. For deployment control, set `model` in `.codex/agents/strategist.toml` or configure native agent defaults in native Codex configuration; choose a model that supports high reasoning effort. Advice remains advisory-only and never counts as execution proof.');
+    reasoning.push('model_reasoning_effort = "high"');
+  }
 
   return [
     `name = ${JSON.stringify(name)}`,
     `description = ${JSON.stringify(description)}`,
+    ...(readOnly ? ['sandbox_mode = "read-only"'] : []),
+    ...reasoning,
     `developer_instructions = ${JSON.stringify(instructions)}`,
     ''
   ].join('\n');
@@ -365,6 +483,10 @@ function transformManagedCodexContent(content, transform) {
 }
 
 module.exports = {
+  CODEX_RESEARCH_DEPTH_MARKER,
+  CODEX_RESEARCH_DEPTH_NOTE,
+  CODEX_SPECS_SCOPE_MARKER,
+  CODEX_SPECS_SCOPE_NOTE,
   normalizeCodexBody,
   getCodexCopyOptions,
   codexAgentName,

package/bin/lib/context.js

@@ -128,7 +128,7 @@ const PLATFORMS = {
     detectFiles: ['.omp'],
     commandsDir: null,
     // omp discovers .claude/skills and .agents/skills itself, so CafeKit copies
-    // no skill payload for it. See specs/omp-runtime-support/plan.md.
+    // no skill payload for it. See specs/archive/omp-runtime-support/plan.md.
     skillsDir: '.agents/skills',
     agentsDir: null,
     skillsRef: '.agents/skills',

package/bin/phases/claude-runtime.js

@@ -16,6 +16,7 @@ const {
   getCopyOptions
 } = require('../lib/context');
 const { sha256 } = require('../lib/manifest');
+const { assertNoSymlinkPath } = require('../lib/path-safety');
 const { writeManagedFile, copyManagedTree } = require('../lib/managed-writer');
 const { report, treeAction } = require('./report');
 const {
@@ -164,30 +165,84 @@ function copyClaudeRuntimeFiles(ctx, platformKey) {
   });
 }
 
-/** Delete runtime files marked obsolete by the manifest. Claude only. */
-function removeObsoleteClaudeRuntimeFiles(ctx, platformKey) {
-  if (platformKey !== 'claude') return;
-
-  const obsoleteFiles = ctx.manifest?.obsolete?.runtimeFiles || [];
-  const targetBase = PLATFORMS.claude.folder;
-
-  obsoleteFiles.forEach((relPath) => {
-    const targetPath = path.join(targetBase, relPath);
-    if (!fs.existsSync(targetPath)) return;
-
-    const isDir = fs.statSync(targetPath).isDirectory();
-    if (!ctx.dryRun) {
-      fs.rmSync(targetPath, { force: true, recursive: isDir });
-      // Remove the entry from the manifest so it doesn't linger as a zombie.
-      if (ctx.trackers && ctx.trackers.claude) {
-        ctx.trackers.claude.prune(relPath);
-        // Directories: prune every tracked file underneath as well.
-        if (isDir) ctx.trackers.claude.prunePrefix(`${relPath}/`);
+/** Remove only obsolete runtime bytes proven unchanged by the ownership manifest. */
+function removeObsoleteRuntimeFiles(ctx, platformKey) {
+  const completed = (ctx.obsoleteRuntimeCleanedPlatforms ||= new Set());
+  if (completed.has(platformKey)) return;
+  completed.add(platformKey);
+  const preserved = new Set();
+  for (const key of [platformKey]) {
+    const platform = PLATFORMS[key];
+    const tracker = ctx.trackers?.[key];
+    const ownership = ctx.ownership?.[platform.folder] || { files: {} };
+    const obsoleteFiles = (ctx.manifest?.obsolete?.runtimeFiles || [])
+      .filter(relative => key === 'claude' || /^(?:hooks|scripts|skills)\//.test(relative));
+    for (const relative of obsoleteFiles) {
+      const targetPath = key === 'codex' && relative.startsWith('skills/')
+        ? path.join(platform.skillsDir, relative.slice('skills/'.length))
+        : path.join(platform.folder, relative);
+      let stat;
+      try {
+        assertNoSymlinkPath(targetPath);
+        stat = fs.statSync(targetPath);
+      } catch (error) {
+        if (error.code === 'ENOENT') {
+          if (key === 'codex' && tracker && !ctx.dryRun) tracker.prune(tracker.keyFor(targetPath));
+          continue;
+        }
+        preserved.add(targetPath);
+        continue;
+      }
+      try {
+        if (!tracker) throw new Error('Missing ownership tracker');
+        const trackedKeys = [];
+        const inspect = file => {
+          assertNoSymlinkPath(file);
+          const current = fs.statSync(file);
+          if (current.isDirectory()) {
+            for (const name of fs.readdirSync(file)) inspect(path.join(file, name));
+            return;
+          }
+          if (!current.isFile()) throw new Error('Unsupported obsolete file type');
+          const trackedKey = tracker.keyFor(file);
+          const recordedHash = ownership.files?.[trackedKey]?.sha256;
+          if (!recordedHash || recordedHash !== sha256(fs.readFileSync(file))) {
+            throw new Error('Obsolete file is not proven unchanged');
+          }
+          trackedKeys.push(trackedKey);
+        };
+        inspect(targetPath);
+        assertNoSymlinkPath(targetPath);
+        const targetKey = tracker.keyFor(targetPath);
+        if (!ctx.dryRun) {
+          fs.rmSync(targetPath, { force: true, recursive: stat.isDirectory() });
+          for (const trackedKey of trackedKeys) tracker.prune(trackedKey);
+          if (stat.isDirectory()) {
+            tracker.prune(targetKey);
+            tracker.prunePrefix(`${targetKey}/`);
+          }
+        }
+        ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Removed obsolete ${key} runtime: ${relative}`);
+        ctx.results.updated++;
+      } catch {
+        preserved.add(targetPath);
       }
     }
-    ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Removed obsolete runtime: ${relPath}`);
-    ctx.results.updated++;
-  });
+  }
+  if (preserved.size) {
+    ctx.results.preserved = (ctx.results.preserved || 0) + preserved.size;
+    (ctx.results.preservedFiles ||= []).push(...preserved);
+  }
+  const allPreserved = (ctx.obsoleteRuntimePreserved ||= new Set());
+  for (const target of preserved) allPreserved.add(target);
+  const selected = (ctx.platforms || [platformKey]).filter(key => key === 'claude' || key === 'codex');
+  if (selected.every(key => completed.has(key)) && allPreserved.size) {
+    ctx.ui.warn(`Preserved ${allPreserved.size} obsolete runtime item(s); review and remove manually if no longer needed: ${[...allPreserved].join(', ')}`);
+  }
+}
+
+function removeObsoleteClaudeRuntimeFiles(ctx, platformKey) {
+  if (platformKey === 'claude') removeObsoleteRuntimeFiles(ctx, platformKey);
 }
 
 /** Remove renamed agents only when ownership manifest proves pristine bytes. */
@@ -258,7 +313,7 @@ function copyClaudeMdFile(ctx, platformKey) {
 }
 
 /** Copy the rules/ tree (ownership-aware; no longer force-overwrites). */
-function copyRulesDirectory(ctx, platformKey) {
+function copyRulesDirectory(ctx, platformKey, excludedNames = new Set()) {
   if (!hasPlatformCapability(platformKey, 'rules')) return;
 
   const src = path.join(SRC, 'claude/rules');
@@ -270,9 +325,19 @@ function copyRulesDirectory(ctx, platformKey) {
   }
 
   const transform = getCopyOptions(platformKey, {}).transform;
-  const agg = copyManagedTree({
+  const options = {
     src, dest, platformFolder: PLATFORMS[platformKey].folder, ctx, tracker: ctx.trackers[platformKey], transform
-  });
+  };
+  let agg;
+  if (excludedNames.size === 0) agg = copyManagedTree(options);
+  else {
+    agg = { created: 0, updated: 0, unchanged: 0, preserved: 0, missing: 0 };
+    for (const name of fs.readdirSync(src)) {
+      if (excludedNames.has(name)) continue;
+      const child = copyManagedTree({ ...options, sourceRoot: src, src: path.join(src, name), dest: path.join(dest, name) });
+      for (const key of Object.keys(agg)) agg[key] += child[key];
+    }
+  }
   report(ctx, treeAction(agg), 'rules/ directory');
 }
 
@@ -303,6 +368,7 @@ module.exports = {
   copyOutputStylesDirectory,
   copyClaudeRuntimeFiles,
   removeObsoleteClaudeRuntimeFiles,
+  removeObsoleteRuntimeFiles,
   copyClaudeMdFile,
   copyClaudeAgentsMdFile,
   ensureSharedAgentsMdCore,

package/bin/phases/claude-settings.js

@@ -12,6 +12,26 @@ const { PLATFORMS } = require('../lib/context');
 
 const SRC_CLAUDE = path.join(__dirname, '../../src/claude');
 
+const FORMER_MATCHERS = new Set([
+  'Read|Write|Edit|MultiEdit|Bash|Glob',
+  'Read|Write|Edit|MultiEdit|Bash|Glob|Grep',
+]);
+
+function refreshManagedMatchers(settings, template, ctx) {
+  if (!Array.isArray(settings.hooks?.PreToolUse)) return settings;
+  const targets = template.hooks?.PreToolUse || [];
+  const entries = settings.hooks.PreToolUse.map(entry => {
+    if (!FORMER_MATCHERS.has(entry?.matcher) || !Array.isArray(entry.hooks) || !entry.hooks.length) return entry;
+    const candidates = targets.filter(target =>
+      entry.hooks.every(hook => target.hooks.some(managed => managed.command === hook?.command)));
+    if (candidates.length !== 1) return entry;
+    ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Settings: hook PreToolUse matcher updated`);
+    ctx.results.updated++;
+    return { ...entry, matcher: candidates[0].matcher };
+  });
+  return { ...settings, hooks: { ...settings.hooks, PreToolUse: entries } };
+}
+
 /**
  * Remove obsolete hook entries from a settings object whose command matches any
  * manifest-listed substring (e.g. a retired router hook). Returns a possibly
@@ -97,7 +117,8 @@ function mergeClaudeSettings(ctx, platformKey) {
     }
   }
 
-  const mergedSettings = pruneObsoleteSettingsHooks({ ...existingSettings }, ctx);
+  const mergedSettings = refreshManagedMatchers(
+    pruneObsoleteSettingsHooks({ ...existingSettings }, ctx), managedSettings, ctx);
 
   // statusLine: adopt managed value if upgrading, missing, or CafeKit-owned.
   if (managedSettings.statusLine) {

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,7 @@ 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;
 }
 
 /** Rewrite a managed template handler into absolute launchers for both platforms. */
@@ -104,10 +164,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 +179,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 +198,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 +209,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 +256,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 +278,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 +305,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++;
   }