@haposoft/cafekit 0.18.0 → 0.18.2

package/bin/install.js

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

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/lib/managed-writer.js

@@ -60,9 +60,8 @@ function writeManagedFile(opts) {
   // Ownership manifest for this platform (read at run start), NOT the migration manifest.
   const ownership = (ctx.ownership && ctx.ownership[platformFolder]) || { files: {} };
 
-  // A file already written earlier THIS run (e.g. a spec template copied as part
-  // of the specs/ tree, then revisited by the template-sync loop) is ours — treat
-  // it as pristine against what we just wrote, not as a user-created file.
+  // A file already written earlier THIS run is ours — treat it as pristine
+  // against what we just wrote, not as a user-created file.
   const relForRun = tracker?.keyFor
     ? tracker.keyFor(dest)
     : path.relative(platformFolder, dest).replace(/\\/g, '/');

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) {