agent-switchboard 0.4.16 → 0.4.18

package/README.md

@@ -38,9 +38,10 @@ Library entries are agent-agnostic Markdown files (or directories for skills, JS
 | Commands         | ✓           | ✓\*   | ✓      | ✓      | ✓        |      |                |
 | Agents           | ✓           | ✓     | ✓      |        | ✓        |      |                |
 | Skills           | ✓           | ✓     | ✓      | ✓      | ✓        | ✓    |                |
-| Hooks            | ✓           |       |        |        |          |      |                |
+| Hooks            | ✓           | ✓†    |        |        |          |      |                |
 
-\* Codex commands use deprecated `~/.codex/prompts/`; prefer skills instead. Trae column applies to both `trae` and `trae-cn` variants.
+\* Codex commands use deprecated `~/.codex/prompts/`; prefer skills instead.
+† ASB currently distributes Codex hooks as command handlers. It writes `~/.codex/hooks.json` or `<project>/.codex/hooks.json`, filters unsupported hook entries, and reports config, trust, and review prerequisites. Trae column applies to both `trae` and `trae-cn` variants.
 
 Cursor rules are composed into a single `asb-rules.mdc` file at `~/.cursor/rules/` with `alwaysApply: true`.
 
@@ -93,7 +94,7 @@ Library content lives under `~/.agent-switchboard/` and agent configs are update
 | `asb command`                   | Interactive command selector                         |
 | `asb agent`                     | Interactive agent selector                           |
 | `asb skill`                     | Interactive skill selector                           |
-| `asb hook`                      | Interactive hook selector (Claude Code only)         |
+| `asb hook`                      | Interactive hook selector (Claude Code and Codex)    |
 | `asb sync`                      | Push all libraries + MCP to applications (no UI)     |
 | `asb <lib> load`                | Import files from a platform into the library        |
 | `asb <lib> list`                | Show inventory, enabled state, and sync timestamps   |
@@ -316,7 +317,7 @@ Entire directories are copied to each agent's skill location. Deactivated skills
 
 ### Hooks
 
-JSON-based hook definitions distributed to Claude Code's `settings.json`. Two storage formats:
+JSON-based hook definitions distributed to Claude Code's `settings.json` and Codex's `hooks.json`. Two storage formats:
 
 - **Single file**: `~/.agent-switchboard/hooks/<id>.json`
 - **Bundle**: `~/.agent-switchboard/hooks/<id>/hook.json` plus script files
@@ -327,7 +328,12 @@ asb hook load /path/to/hook.json       # import a JSON file
 asb hook load /path/to/hook-dir/       # import a bundle directory
 ```
 
-Bundle scripts are copied to `~/.claude/hooks/asb/<id>/` and the `${HOOK_DIR}` placeholder in commands is resolved to the absolute path at distribution time.
+Bundle scripts are copied to the target agent's ASB hook bundle directory and the `${HOOK_DIR}` placeholder in commands is resolved to the absolute path at distribution time:
+
+- Claude Code: `~/.claude/hooks/asb/<id>/`
+- Codex: `~/.codex/hooks/asb/<id>/` or `<project>/.codex/hooks/asb/<id>/`
+
+Codex hook sync writes `~/.codex/hooks.json` for global scope or `<project>/.codex/hooks.json` for project scope. ASB emits command handlers for `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `SessionStart`, `UserPromptSubmit`, and `Stop`; unsupported events and non-command handler types are filtered from Codex output and reported in sync results. Codex uses `[features].hooks` in `~/.codex/config.toml` (enabled by default when absent; legacy `[features].codex_hooks` is accepted for compatibility). Project-scoped hooks require the project to be trusted, and new or changed Codex hooks must be reviewed from `/hooks` in Codex before they run.
 
 ## Plugins
 

package/dist/hooks/codex-distribute.d.ts

@@ -5,8 +5,8 @@
  * <project>/.codex/hooks.json (project scope). Unlike Claude Code which
  * embeds hooks inside settings.json, Codex uses a dedicated file.
  *
- * Codex only supports: command handlers, 5 event types, no ${HOOK_DIR}
- * runtime expansion. ASB must filter unsupported entries and rewrite
+ * ASB currently distributes command handlers to Codex and Codex has no
+ * ${HOOK_DIR} runtime expansion. ASB must filter unsupported entries and rewrite
  * bundle paths to absolute paths before writing.
  */
 import type { ConfigScope } from '../config/scope.js';

package/dist/hooks/codex-distribute.js

@@ -5,22 +5,26 @@
  * <project>/.codex/hooks.json (project scope). Unlike Claude Code which
  * embeds hooks inside settings.json, Codex uses a dedicated file.
  *
- * Codex only supports: command handlers, 5 event types, no ${HOOK_DIR}
- * runtime expansion. ASB must filter unsupported entries and rewrite
+ * ASB currently distributes command handlers to Codex and Codex has no
+ * ${HOOK_DIR} runtime expansion. ASB must filter unsupported entries and rewrite
  * bundle paths to absolute paths before writing.
  */
+import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { ensureTrustEntry } from '../agents/codex.js';
+import { parse as parseToml } from '@iarna/toml';
 import { getCodexConfigPath, getCodexDir, getCodexHooksJsonPath, getProjectCodexDir, getProjectCodexHooksJsonPath, } from '../config/paths.js';
-import { distributeBundle } from '../library/distribute-bundle.js';
-import { ensureParentDir, rmDirRecursive } from '../library/fs.js';
+import { assertNoSymlinkAncestor, assertUsableBundleRoot, distributeBundle, } from '../library/distribute-bundle.js';
+import { ensureParentDir } from '../library/fs.js';
 import { listHookBundleFiles } from './library.js';
 import { HOOK_DIR_PLACEHOLDER } from './schema.js';
 const CODEX_SUPPORTED_EVENTS = new Set([
     'PreToolUse',
+    'PermissionRequest',
     'PostToolUse',
+    'PreCompact',
+    'PostCompact',
     'SessionStart',
     'UserPromptSubmit',
     'Stop',
@@ -49,6 +53,13 @@ function resolveHooksBundleParentDir(scope) {
     }
     return path.join(getCodexDir(), 'hooks', ASB_HOOKS_SUBDIR);
 }
+function resolveHooksBundleSafetyRoot(scope) {
+    const projectRoot = scope?.project?.trim();
+    if (projectRoot && projectRoot.length > 0) {
+        return getProjectCodexDir(projectRoot);
+    }
+    return getCodexDir();
+}
 function resolveHookBundleTargetDir(entry, scope) {
     return path.join(resolveHooksBundleParentDir(scope), entry.id);
 }
@@ -61,16 +72,40 @@ function preferHomeVar(command) {
         return command;
     return command.replaceAll(home, '$HOME');
 }
+function formatUnsupportedReason(diagnostic) {
+    const parts = [];
+    if (diagnostic.unsupportedEvents.length > 0) {
+        parts.push(`unsupported events: ${diagnostic.unsupportedEvents.join(', ')}`);
+    }
+    if (diagnostic.unsupportedHandlerTypes.length > 0) {
+        parts.push(`unsupported handler types: ${diagnostic.unsupportedHandlerTypes.join(', ')}`);
+    }
+    const prefix = diagnostic.fullyFiltered
+        ? 'hook has no Codex-compatible command handlers after filtering'
+        : 'hook was partially filtered for Codex compatibility';
+    return `${prefix} (${parts.join('; ')})`;
+}
 function filterForCodex(entries) {
     const result = [];
+    const diagnostics = [];
     for (const entry of entries) {
         const filteredHooks = {};
+        const unsupportedEvents = new Set();
+        const unsupportedHandlerTypes = new Set();
         for (const [event, groups] of Object.entries(entry.hooks)) {
-            if (!CODEX_SUPPORTED_EVENTS.has(event))
+            if (!CODEX_SUPPORTED_EVENTS.has(event)) {
+                unsupportedEvents.add(event);
                 continue;
+            }
             const filteredGroups = [];
             for (const group of groups) {
-                const filteredHandlers = (group.hooks ?? []).filter((h) => CODEX_SUPPORTED_HANDLER_TYPES.has(h.type ?? ''));
+                const filteredHandlers = (group.hooks ?? []).filter((h) => {
+                    const type = h.type ?? 'unknown';
+                    const supported = CODEX_SUPPORTED_HANDLER_TYPES.has(type);
+                    if (!supported)
+                        unsupportedHandlerTypes.add(type);
+                    return supported;
+                });
                 if (filteredHandlers.length > 0) {
                     filteredGroups.push({ ...group, hooks: filteredHandlers });
                 }
@@ -82,8 +117,16 @@ function filterForCodex(entries) {
         if (Object.keys(filteredHooks).length > 0) {
             result.push({ entry, hooks: filteredHooks });
         }
+        if (unsupportedEvents.size > 0 || unsupportedHandlerTypes.size > 0) {
+            diagnostics.push({
+                entryId: entry.id,
+                unsupportedEvents: [...unsupportedEvents].sort(),
+                unsupportedHandlerTypes: [...unsupportedHandlerTypes].sort(),
+                fullyFiltered: Object.keys(filteredHooks).length === 0,
+            });
+        }
     }
-    return result;
+    return { entries: result, diagnostics };
 }
 // ---------------------------------------------------------------------------
 // hooks.json I/O
@@ -93,7 +136,7 @@ function readHooksJson(filePath) {
         if (fs.existsSync(filePath)) {
             return {
                 ok: true,
-                data: JSON.parse(fs.readFileSync(filePath, 'utf-8')),
+                data: parseHooksJsonRoot(JSON.parse(fs.readFileSync(filePath, 'utf-8'))),
             };
         }
     }
@@ -102,6 +145,12 @@ function readHooksJson(filePath) {
     }
     return { ok: true, data: {} };
 }
+function parseHooksJsonRoot(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error('hooks.json has invalid shape: root must be an object');
+    }
+    return value;
+}
 function writeHooksJson(filePath, data) {
     ensureParentDir(filePath);
     fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf-8');
@@ -109,7 +158,7 @@ function writeHooksJson(filePath, data) {
 // ---------------------------------------------------------------------------
 // Config merge
 // ---------------------------------------------------------------------------
-function rewriteHookDir(hooks, distributedDir) {
+function rewriteHookDir(hooks, distributedDir, bundleHash) {
     const result = {};
     for (const [event, groups] of Object.entries(hooks)) {
         result[event] = groups.map((group) => ({
@@ -119,17 +168,33 @@ function rewriteHookDir(hooks, distributedDir) {
                     return handler;
                 return {
                     ...handler,
-                    command: preferHomeVar(handler.command
+                    command: preferHomeVar(annotateBundleCommand(handler.command
                         .replaceAll(HOOK_DIR_PLACEHOLDER, distributedDir)
                         .replaceAll(CLAUDE_PLUGIN_ROOT_HOOKS_PREFIX, distributedDir)
-                        .replaceAll(CLAUDE_PLUGIN_ROOT_HOOKS_PREFIX_WINDOWS, distributedDir)),
+                        .replaceAll(CLAUDE_PLUGIN_ROOT_HOOKS_PREFIX_WINDOWS, distributedDir), bundleHash)),
                 };
             }),
         }));
     }
     return result;
 }
-function mergeHooksIntoFile(fileData, filteredEntries, scope) {
+function annotateBundleCommand(command, bundleHash) {
+    if (!bundleHash)
+        return command;
+    return `${command}\n# asb-bundle-sha256=${bundleHash}`;
+}
+function computeBundleHash(entry) {
+    const hash = createHash('sha256');
+    const files = listHookBundleFiles(entry).sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+    for (const file of files) {
+        hash.update(file.relativePath);
+        hash.update('\0');
+        hash.update(fs.readFileSync(file.sourcePath));
+        hash.update('\0');
+    }
+    return hash.digest('hex');
+}
+function mergeHooksIntoFile(fileData, filteredEntries, scope, bundleHashes) {
     const existingHooks = (fileData.hooks ?? {});
     // Remove previously ASB-managed matcher groups
     const cleanedHooks = {};
@@ -141,7 +206,7 @@ function mergeHooksIntoFile(fileData, filteredEntries, scope) {
     // Merge filtered entries
     for (const { entry, hooks } of filteredEntries) {
         const resolvedHooks = entry.isBundle
-            ? rewriteHookDir(hooks, resolveHookBundleTargetDir(entry, scope))
+            ? rewriteHookDir(hooks, resolveHookBundleTargetDir(entry, scope), bundleHashes?.get(entry.id))
             : hooks;
         for (const [event, groups] of Object.entries(resolvedHooks)) {
             if (!cleanedHooks[event])
@@ -152,7 +217,12 @@ function mergeHooksIntoFile(fileData, filteredEntries, scope) {
         }
     }
     fileData.hooks = cleanedHooks;
-    fileData[ASB_MANAGED_KEY] = filteredEntries.map((f) => f.entry.id);
+    if (filteredEntries.length > 0) {
+        fileData[ASB_MANAGED_KEY] = filteredEntries.map((f) => f.entry.id);
+    }
+    else {
+        delete fileData[ASB_MANAGED_KEY];
+    }
 }
 // ---------------------------------------------------------------------------
 // Orphan cleanup for bundles
@@ -160,19 +230,24 @@ function mergeHooksIntoFile(fileData, filteredEntries, scope) {
 function cleanOrphanBundleDirs(activeIds, scope, dryRun) {
     const parentDir = resolveHooksBundleParentDir(scope);
     const results = [];
-    if (!fs.existsSync(parentDir))
+    const parentError = getOrphanBundleParentError(scope);
+    if (parentError) {
+        results.push(parentError);
+        return results;
+    }
+    if (!lstatIfExists(parentDir))
         return results;
     try {
         const entries = fs.readdirSync(parentDir, { withFileTypes: true });
         for (const entry of entries) {
-            if (!entry.isDirectory())
+            if (!entry.isDirectory() && !entry.isSymbolicLink())
                 continue;
             if (activeIds.has(entry.name))
                 continue;
             const dirPath = path.join(parentDir, entry.name);
             try {
                 if (!dryRun)
-                    rmDirRecursive(dirPath);
+                    removeHookBundlePath(dirPath);
                 results.push({
                     platform: 'codex',
                     targetDir: dirPath,
@@ -193,70 +268,163 @@ function cleanOrphanBundleDirs(activeIds, scope, dryRun) {
             }
         }
     }
-    catch {
-        // Ignore directory read errors
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        results.push({
+            platform: 'codex',
+            targetDir: parentDir,
+            status: 'error',
+            error: `Failed to scan orphan parent: ${msg}`,
+        });
     }
     return results;
 }
-// ---------------------------------------------------------------------------
-// Codex prerequisites: feature flag + project trust
-// ---------------------------------------------------------------------------
-function ensureCodexHooksFeature(results) {
-    const configPath = getCodexConfigPath();
-    if (!fs.existsSync(configPath))
+function getOrphanBundleParentError(scope) {
+    const parentDir = resolveHooksBundleParentDir(scope);
+    try {
+        const safetyRoot = resolveHooksBundleSafetyRoot(scope);
+        assertUsableBundleRoot(safetyRoot);
+        assertNoSymlinkAncestor(safetyRoot, parentDir);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return {
+            platform: 'codex',
+            targetDir: parentDir,
+            status: 'error',
+            error: `Failed to scan orphan parent: ${msg}`,
+        };
+    }
+    const stat = lstatIfExists(parentDir);
+    if (!stat)
+        return undefined;
+    if (!stat.isDirectory()) {
+        return {
+            platform: 'codex',
+            targetDir: parentDir,
+            status: 'error',
+            error: `Failed to scan orphan parent: bundle root exists and is not a directory: ${parentDir}`,
+        };
+    }
+    return undefined;
+}
+function lstatIfExists(filePath) {
+    try {
+        return fs.lstatSync(filePath);
+    }
+    catch (error) {
+        if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT') {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function removeHookBundlePath(targetPath) {
+    const stat = lstatIfExists(targetPath);
+    if (!stat)
         return;
-    const content = fs.readFileSync(configPath, 'utf-8');
-    if (content.includes('codex_hooks') && content.includes('true'))
+    if (stat.isDirectory() && !stat.isSymbolicLink()) {
+        const entries = fs.readdirSync(targetPath, { withFileTypes: true });
+        for (const entry of entries) {
+            removeHookBundlePath(path.join(targetPath, entry.name));
+        }
+        fs.rmdirSync(targetPath);
         return;
-    // Feature not explicitly enabled - add warning result
-    results.push({
-        platform: 'codex',
-        filePath: configPath,
-        status: 'written',
-        reason: 'codex_hooks feature flag may not be enabled in config.toml',
-    });
+    }
+    fs.unlinkSync(targetPath);
 }
-function ensureProjectTrust(projectRoot, results) {
-    const globalPath = getCodexConfigPath();
-    const globalContent = fs.existsSync(globalPath) ? fs.readFileSync(globalPath, 'utf-8') : '';
-    const trustResult = ensureTrustEntry(globalContent, projectRoot);
-    if (trustResult.warning) {
-        results.push({
-            platform: 'codex',
-            filePath: globalPath,
-            status: 'skipped',
-            reason: trustResult.warning,
-        });
+function readCodexConfigToml() {
+    const configPath = getCodexConfigPath();
+    if (!fs.existsSync(configPath))
+        return { ok: true, filePath: configPath, data: {} };
+    try {
+        const data = parseToml(fs.readFileSync(configPath, 'utf-8'));
+        return { ok: true, filePath: configPath, data };
     }
-    if (trustResult.changed) {
-        ensureParentDir(globalPath);
-        fs.writeFileSync(globalPath, trustResult.content, 'utf-8');
+    catch (error) {
+        return {
+            ok: false,
+            filePath: configPath,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function asBoolean(value) {
+    return typeof value === 'boolean' ? value : undefined;
+}
+function getHooksFeatureValue(features) {
+    return asBoolean(features?.hooks) ?? asBoolean(features?.codex_hooks);
+}
+function getObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    return value;
+}
+function getEffectiveHooksEnabled(config) {
+    const baseValue = getHooksFeatureValue(getObject(config.features));
+    const profileName = typeof config.profile === 'string' ? config.profile : undefined;
+    const profiles = getObject(config.profiles);
+    const profileConfig = profileName ? getObject(profiles?.[profileName]) : undefined;
+    const profileValue = getHooksFeatureValue(getObject(profileConfig?.features));
+    return profileValue ?? baseValue ?? true;
+}
+function addCodexHooksFeatureResult(config, results) {
+    const effectiveHooksEnabled = getEffectiveHooksEnabled(config.data);
+    if (!effectiveHooksEnabled) {
         results.push({
             platform: 'codex',
-            filePath: globalPath,
-            status: 'written',
-            reason: 'added project trust entry',
+            filePath: config.filePath,
+            status: 'conflict',
+            reason: 'features.hooks is disabled; enable it before Codex hooks can run',
         });
     }
 }
+function addProjectTrustResult(config, projectRoot, results) {
+    const projects = getObject(config.data.projects);
+    const project = getObject(projects?.[path.resolve(projectRoot)]);
+    const trustLevel = project?.trust_level;
+    if (trustLevel === 'trusted')
+        return;
+    const reason = typeof trustLevel === 'string'
+        ? `project is not trusted (trust_level="${trustLevel}"); Codex will ignore project hooks`
+        : 'project is not trusted; Codex will ignore project hooks until trust_level = "trusted" is configured';
+    results.push({ platform: 'codex', filePath: config.filePath, status: 'conflict', reason });
+}
+function addReviewResult(hooksJsonPath, results) {
+    results.push({
+        platform: 'codex',
+        filePath: hooksJsonPath,
+        status: 'conflict',
+        reason: 'open /hooks in Codex to review new or modified hooks before they can run',
+    });
+}
+function addConfigParseResult(config, results) {
+    results.push({
+        platform: 'codex',
+        filePath: config.filePath,
+        status: 'conflict',
+        reason: `Cannot parse config.toml to verify Codex hook prerequisites: ${config.error}`,
+    });
+}
 export function distributeCodexHooks(options) {
     const { scope, selected, dryRun = false, projectMode } = options;
     if (scope?.project && projectMode === 'none') {
         return { results: [] };
     }
     const results = [];
-    // Ensure Codex hooks feature flag is enabled
-    if (!dryRun) {
-        ensureCodexHooksFeature(results);
-    }
-    // Ensure project trust for project-scoped distribution
-    if (!dryRun && scope?.project) {
-        ensureProjectTrust(scope.project, results);
-    }
-    // Filter entries for Codex compatibility
-    const filteredEntries = filterForCodex(selected);
     // Pre-validate hooks.json before making any filesystem changes
     const hooksJsonPath = resolveHooksJsonPath(scope);
+    const filterResult = filterForCodex(selected);
+    const filteredEntries = filterResult.entries;
+    for (const diagnostic of filterResult.diagnostics) {
+        results.push({
+            platform: 'codex',
+            filePath: hooksJsonPath,
+            status: 'skipped',
+            reason: formatUnsupportedReason(diagnostic),
+            entryId: diagnostic.entryId,
+        });
+    }
     const fileResult = readHooksJson(hooksJsonPath);
     if (!fileResult.ok) {
         results.push({
@@ -293,55 +461,142 @@ export function distributeCodexHooks(options) {
             }
         }
     }
+    if (filteredEntries.length > 0) {
+        const config = readCodexConfigToml();
+        if (!config.ok) {
+            addConfigParseResult(config, results);
+        }
+        else {
+            addCodexHooksFeatureResult(config, results);
+            if (scope?.project)
+                addProjectTrustResult(config, scope.project, results);
+        }
+    }
     // Phase 1: Copy bundle files (only after validation passes)
     const bundleEntries = filteredEntries.filter((f) => f.entry.isBundle).map((f) => f.entry);
+    const activeBundleIds = new Set(bundleEntries.map((e) => e.id));
+    const bundleHashes = new Map();
     if (bundleEntries.length > 0) {
         const bundleOutcome = distributeBundle({
             section: 'hooks',
             selected: bundleEntries,
             platforms: ['codex'],
             resolveTargetDir: (_p, entry) => resolveHookBundleTargetDir(entry, scope),
+            resolveBundleRootDir: () => resolveHooksBundleSafetyRoot(scope),
             listFiles: listHookBundleFiles,
             getId: (entry) => entry.id,
             scope,
             dryRun,
         });
         results.push(...bundleOutcome.results);
+        if (bundleOutcome.results.some((result) => result.status === 'error' || result.status === 'conflict')) {
+            return { results };
+        }
+        for (const entry of bundleEntries) {
+            try {
+                bundleHashes.set(entry.id, computeBundleHash(entry));
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                results.push({
+                    platform: 'codex',
+                    filePath: hooksJsonPath,
+                    status: 'error',
+                    error: `Failed to hash bundle ${entry.id}: ${msg}`,
+                    entryId: entry.id,
+                });
+                return { results };
+            }
+        }
     }
-    // Clean up orphan bundle directories
-    const activeBundleIds = new Set(bundleEntries.map((e) => e.id));
-    results.push(...cleanOrphanBundleDirs(activeBundleIds, scope, dryRun));
+    const cleanupParentError = getOrphanBundleParentError(scope);
+    if (cleanupParentError) {
+        results.push(cleanupParentError);
+        return { results };
+    }
+    const appendCleanupResults = () => {
+        const cleanupResults = cleanOrphanBundleDirs(activeBundleIds, scope, dryRun);
+        results.push(...cleanupResults);
+        return cleanupResults.some((result) => result.status === 'error');
+    };
     // Phase 2: Merge hook configs into hooks.json
     const previouslyManaged = (fileData[ASB_MANAGED_KEY] ?? []);
     // Check for existing ASB groups
     const existingHooks = (fileData.hooks ?? {});
     const hasAsbGroups = Object.values(existingHooks).some((groups) => groups.some((g) => g._asb_source === true));
     if (filteredEntries.length === 0 && previouslyManaged.length === 0 && !hasAsbGroups) {
+        appendCleanupResults();
         return { results };
     }
     const before = JSON.stringify(fileData);
-    mergeHooksIntoFile(fileData, filteredEntries, scope);
+    mergeHooksIntoFile(fileData, filteredEntries, scope, bundleHashes);
+    const preserveCleanupMarker = filteredEntries.length === 0 && previouslyManaged.length > 0;
+    if (preserveCleanupMarker) {
+        fileData[ASB_MANAGED_KEY] = previouslyManaged;
+    }
     // Clean up empty state: if no hooks remain, remove the file entirely
     const mergedHooks = fileData.hooks;
     const totalGroups = Object.values(mergedHooks).reduce((sum, groups) => sum + groups.length, 0);
     const hasNoHooks = totalGroups === 0;
     if (hasNoHooks && filteredEntries.length === 0) {
-        // Remove ASB tracking keys
-        delete fileData[ASB_MANAGED_KEY];
+        if (!preserveCleanupMarker) {
+            delete fileData[ASB_MANAGED_KEY];
+        }
         // If file has only hooks (now empty) and ASB keys, consider deleting
         const remainingKeys = Object.keys(fileData).filter((k) => k !== 'hooks');
         if (remainingKeys.length === 0 && fs.existsSync(hooksJsonPath) && !dryRun) {
-            fs.unlinkSync(hooksJsonPath);
-            results.push({
-                platform: 'codex',
-                filePath: hooksJsonPath,
-                status: 'deleted',
-                reason: 'no hooks remain',
-            });
+            try {
+                fs.unlinkSync(hooksJsonPath);
+                results.push({
+                    platform: 'codex',
+                    filePath: hooksJsonPath,
+                    status: 'deleted',
+                    reason: 'no hooks remain',
+                });
+                appendCleanupResults();
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                results.push({ platform: 'codex', filePath: hooksJsonPath, status: 'error', error: msg });
+            }
             return { results };
         }
     }
     const after = JSON.stringify(fileData);
+    const finalizeCleanupMarker = () => {
+        if (!preserveCleanupMarker || dryRun)
+            return;
+        delete fileData[ASB_MANAGED_KEY];
+        const finalHooks = fileData.hooks;
+        const finalTotalGroups = Object.values(finalHooks).reduce((sum, groups) => sum + groups.length, 0);
+        const finalRemainingKeys = Object.keys(fileData).filter((k) => k !== 'hooks');
+        try {
+            if (finalTotalGroups === 0 &&
+                finalRemainingKeys.length === 0 &&
+                fs.existsSync(hooksJsonPath)) {
+                fs.unlinkSync(hooksJsonPath);
+                results.push({
+                    platform: 'codex',
+                    filePath: hooksJsonPath,
+                    status: 'deleted',
+                    reason: 'no hooks remain',
+                });
+            }
+            else {
+                writeHooksJson(hooksJsonPath, fileData);
+                results.push({
+                    platform: 'codex',
+                    filePath: hooksJsonPath,
+                    status: 'written',
+                    reason: 'cleanup finalized',
+                });
+            }
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            results.push({ platform: 'codex', filePath: hooksJsonPath, status: 'error', error: msg });
+        }
+    };
     if (before === after) {
         results.push({
             platform: 'codex',
@@ -349,16 +604,25 @@ export function distributeCodexHooks(options) {
             status: 'skipped',
             reason: 'up-to-date',
         });
+        if (!appendCleanupResults())
+            finalizeCleanupMarker();
     }
     else if (dryRun) {
         const reason = filteredEntries.length === 0 ? 'hooks cleared' : `${filteredEntries.length} hook(s) merged`;
         results.push({ platform: 'codex', filePath: hooksJsonPath, status: 'written', reason });
+        if (filteredEntries.length > 0)
+            addReviewResult(hooksJsonPath, results);
+        appendCleanupResults();
     }
     else {
         try {
             writeHooksJson(hooksJsonPath, fileData);
             const reason = filteredEntries.length === 0 ? 'hooks cleared' : `${filteredEntries.length} hook(s) merged`;
             results.push({ platform: 'codex', filePath: hooksJsonPath, status: 'written', reason });
+            if (filteredEntries.length > 0)
+                addReviewResult(hooksJsonPath, results);
+            if (!appendCleanupResults())
+                finalizeCleanupMarker();
         }
         catch (error) {
             const msg = error instanceof Error ? error.message : String(error);