@lyupro/codex-bridge 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.3] - 2026-08-05
+
+### Added
+
+- Dispatcher calls are refused before a subagent exists. A `PreToolUse` gate rejects a `codex-*` call whose task text carries no order label — and, for `codex-build`, no scope — or whose value is still a template placeholder. Until this release the missing input was discovered by the runner, after the subagent had been created and paid for out of the Claude subscription.
+- `codex-build` declares the outcome of its own run in a required `outcome` field. A run that could not do the work reports `fail`, and the verdict goes red with the reason even when the worktree is clean and verification is green — the shape that used to answer `OK`, because an empty delta is a legitimate outcome the runner cannot tell apart from a failure. Whether a run owed that declaration is read from the response schema it was handed, so runs recorded before this release keep the verdict of their own day.
+
+### Changed
+
+- Every dispatcher's description and prompt lists the inputs it requires, filled in at install time from the same table the gate enforces, and the runner's own refusals name the input, an example value and what to do about it. A caller no longer learns the contract by being refused.
+- A failed `codex-build` reports what it left in the worktree, the way a quota-exhausted run already did. "The work was not done" is not "the tree is clean", and where no snapshot exists the line says so instead of claiming there were no changes.
+- The installation record stores a list of hooks rather than a single hook, so a host can register more than one. Records written by earlier versions are read as a one-element list.
+
+## [0.1.2] - 2026-08-04
+
+### Fixed
+
+- A damaged ownership registry no longer breaks the command that reads it. Every command parses the registry before its first write, `doctor` reports the damage as a failed check while still printing the other eight, and `uninstall` finishes removing the package but keeps the shared rules file, because ownership is unknown and disarming another installation is worse than leaving a file behind. Until this release an `uninstall` on a damaged registry stopped after the hook was gone, leaving the host with every package file and no reply guard.
+- Owner updates are written through a temporary file under a lock, so two installers running at once merge instead of overwriting each other. The lock expires: an interrupted run used to leave it behind, and every later install and uninstall then died on it until someone deleted the file by hand.
+- Installation claims its share of the rules file before writing anything. Claiming it last meant a failure at that step left a fully installed host missing from the registry, and the next uninstall elsewhere would delete the rules out from under it.
+
 ## [0.1.1] - 2026-08-04
 
 ### Fixed

package/README.md

@@ -17,7 +17,8 @@ node bin/codex-bridge.mjs stop <run>    # close a hanging run by hand, without h
 ```
 
 `install` copies the package into the host's `agents/codex/`, its slash commands into
-`commands/codex/`, and registers the stop hook in `settings.json` — **merged**, so hooks that
+`commands/codex/`, and registers both the stop hook and the pre-dispatch order gate in
+`settings.json` — **merged**, so hooks that
 are already there survive, and the file is backed up before every write. Run it twice and the
 second run does nothing. `--dry-run` prints the plan and touches nothing.
 

package/cli/doctor.mjs

@@ -2,7 +2,13 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { fileFingerprint, readInstallRecord, packageInfo } from './manifest.mjs';
+import {
+  fileFingerprint,
+  HOOK_DEFINITIONS,
+  readInstallRecord,
+  packageInfo,
+} from './manifest.mjs';
+import { commandFor, inspectHook } from './settings-merge.mjs';
 import { readRulesRegistry } from './rules-owners.mjs';
 import { runsRoot } from '../src/runner/runs-root.mjs';
 import { resolveProjectRunsDir } from '../src/runner/project-dir.mjs';
@@ -53,22 +59,6 @@ function projectRunsCheck() {
   return check('projectRuns', 'ok', `${path.resolve(resolved.dir)} (${note})`);
 }
 
-function hookCommands(value) {
-  if (Array.isArray(value)) return value.flatMap(hookCommands);
-  if (value && typeof value === 'object') {
-    const own = value.type === 'command' && typeof value.command === 'string' ? [value.command] : [];
-    return [...own, ...Object.values(value).filter((child) => child !== value.command).flatMap(hookCommands)];
-  }
-  return [];
-}
-
-function commandReferences(command, expected) {
-  const normalizedExpected = path.resolve(expected).split(path.sep).join('/');
-  const tokens = [...command.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)]
-    .map((match) => match[1] ?? match[2] ?? match[3]);
-  return tokens.some((token) => path.resolve(token).split(path.sep).join('/') === normalizedExpected);
-}
-
 export function probeCodex() {
   const command = process.platform === 'win32' ? process.env.ComSpec || 'cmd.exe' : 'codex';
   const args = process.platform === 'win32' ? ['/d', '/s', '/c', 'codex --version'] : ['--version'];
@@ -79,23 +69,30 @@ export function probeCodex() {
   return { available: true, value: (result.stdout || result.stderr).trim() };
 }
 
-async function hookCheck(host, record) {
-  if (!record) return check('hook', 'warn', 'cannot check before installation');
-  let settings;
-  try {
-    settings = JSON.parse(await fs.readFile(host.settingsPath, 'utf8'));
-  } catch (err) {
-    const value = err.code === 'ENOENT' ? 'settings.json is absent' : `settings.json is invalid: ${err.message}`;
-    return check('hook', 'warn', value);
-  }
-  const registration = settings?.hooks?.SubagentStop;
-  if (!registration) return check('hook', 'warn', 'SubagentStop is not registered');
-  const expected = path.resolve(host.root, record.hook.path);
-  const commands = hookCommands(registration);
-  const pointsToGuard = commands.some((command) => commandReferences(command, expected));
-  return pointsToGuard
-    ? check('hook', 'ok', `SubagentStop -> ${expected}`)
-    : check('hook', 'warn', 'SubagentStop does not point to the installed reply-guard.mjs');
+async function hookChecks(host, record) {
+  return Promise.all(HOOK_DEFINITIONS.map(async (definition) => {
+    const key = `hook:${definition.event}`;
+    if (!record) return check(key, 'warn', 'cannot check before installation');
+    const recorded = record.hooks.find((hook) => hook.event === definition.event);
+    if (!recorded) {
+      return check(key, 'warn', `${definition.event} hook is not present in the installation record`);
+    }
+    const expected = path.resolve(host.root, recorded.path);
+    try {
+      const state = await inspectHook(host.settingsPath, {
+        event: definition.event,
+        matcher: definition.matcher,
+        command: commandFor(expected),
+      });
+      if (state.present) {
+        return check(key, 'ok', `${definition.event} matcher ${definition.matcher} -> ${expected}`);
+      }
+      return check(key, 'warn', `${definition.event} matcher ${definition.matcher} does not point to the installed ${definition.file}`);
+    } catch (err) {
+      const value = err.code === 'ENOENT' ? 'settings.json is absent' : `settings.json is invalid: ${err.message}`;
+      return check(key, 'warn', `${definition.event} hook: ${value}`);
+    }
+  }));
 }
 
 async function rulesCheck(host, record) {
@@ -103,7 +100,13 @@ async function rulesCheck(host, record) {
   if (!record.rules) {
     return check('rules', 'warn', 'rules were not installed by this installation; install or update will add them');
   }
-  const registry = await readRulesRegistry(host);
+  let registry;
+  try {
+    registry = await readRulesRegistry(host);
+  } catch (err) {
+    // Keep every diagnostic visible: package removal on a broken registry left the host without its watchdog.
+    return check('rules', 'fail', err.message);
+  }
   const ownerNote = registry?.owners.length > 1 ? `; ${registry.owners.length} owners` : '';
   const fingerprint = await fileFingerprint(record.rules.path);
   if (!fingerprint) return check('rules', 'fail', `${record.rules.path}${ownerNote ? ` (${registry.owners.length} owners)` : ''}`);
@@ -149,7 +152,7 @@ export async function diagnose({ host, codexProbe = probeCodex, currentPackage }
   ));
   const rules = await rulesCheck(host, record);
   checks.push(rules);
-  checks.push(await hookCheck(host, record));
+  checks.push(...await hookChecks(host, record));
 
   const codex = codexProbe();
   checks.push(check('codex', codex.available ? 'ok' : 'warn', codex.value || 'available'));

package/cli/install.mjs

@@ -4,6 +4,8 @@ import path from 'node:path';
 import {
   buildInstallPlan,
   fileFingerprint,
+  HOOK_DEFINITIONS,
+  installedHookPath,
   packageInfo,
   readInstallRecord,
   recordMatchesPackage,
@@ -12,8 +14,8 @@ import {
   writeInstallRecord,
 } from './manifest.mjs';
 import { copyPlannedFile, targetMatches } from './copy.mjs';
-import { inspectHook, mergeHook } from './settings-merge.mjs';
-import { addRulesOwner } from './rules-owners.mjs';
+import { commandFor, inspectHook, mergeHook } from './settings-merge.mjs';
+import { addRulesOwner, readRulesRegistry } from './rules-owners.mjs';
 
 async function targetExists(target) {
   try {
@@ -25,15 +27,39 @@ async function targetExists(target) {
   }
 }
 
+function hookTargets(host) {
+  return HOOK_DEFINITIONS.map((definition) => {
+    const target = installedHookPath(host, definition);
+    return {
+      definition,
+      target,
+      relative: path.relative(host.root, target).split(path.sep).join('/'),
+      spec: { event: definition.event, matcher: definition.matcher, command: commandFor(target) },
+    };
+  });
+}
+
+function recordHasHooks(record, targets) {
+  return Boolean(record)
+    && targets.every(({ definition, relative }) => record.hooks?.some((hook) =>
+      hook.event === definition.event && hook.path === relative));
+}
+
 export async function install({ host, dryRun = false, force = false, packageRoot } = {}) {
+  // Validate the shared registry before writes; package removal on a broken registry left the host without its watchdog.
+  await readRulesRegistry(host);
   const plan = await buildInstallPlan(host, packageRoot);
   const rule = { ...rulesPlan(host, packageRoot), processing: 'copy' };
   const currentPackage = await packageInfo(packageRoot);
   const record = await readInstallRecord(host);
-  const inspectedHook = await inspectHook(
-    host.settingsPath,
-    path.join(host.agentsDir, 'hooks', 'reply-guard.mjs'),
-  );
+  const targets = hookTargets(host);
+  for (const target of targets) {
+    if (!plan.some((item) => item.relativeToHost === target.relative)) {
+      throw new Error(`install plan does not contain hooks/${target.definition.file}`);
+    }
+  }
+  const inspectedHooks = await Promise.all(targets.map(({ spec }) =>
+    inspectHook(host.settingsPath, spec)));
   const states = await Promise.all(plan.map(async (item) => ({
     item,
     exists: await targetExists(item.target),
@@ -66,7 +92,8 @@ export async function install({ host, dryRun = false, force = false, packageRoot
   const sameRecord = recordMatchesPackage(record, plan, currentPackage,
     new Map(states.map((state) => [state.item.relativeToHost, state.fingerprint])),
     { path: rule.target, fingerprint: ruleState.fingerprint });
-  if (!changedFiles.length && !changedRule && inspectedHook.present && sameRecord) {
+  if (!changedFiles.length && !changedRule && inspectedHooks.every((state) => state.present)
+    && recordHasHooks(record, targets) && sameRecord) {
     if (!dryRun) await addRulesOwner(host);
     return { exitCode: 0, output: 'codex-bridge is already installed; nothing to do.' };
   }
@@ -77,11 +104,20 @@ export async function install({ host, dryRun = false, force = false, packageRoot
     if (changedRule) {
       lines.push(`${ruleState.exists ? 'Would overwrite' : 'Would create'} ${rule.target}`);
     }
-    lines.push(inspectedHook.present ? 'Hook is already registered.' : 'Would register SubagentStop hook.');
+    inspectedHooks.forEach((state, index) => {
+      const { definition } = targets[index];
+      lines.push(state.present
+        ? `${definition.event} hook is already registered.`
+        : `Would register ${definition.event} hook for matcher ${definition.matcher}.`);
+    });
     lines.push('Would write installation record.');
     return { exitCode: 0, output: lines.join('\n') };
   }
 
+  // Claim ownership of the shared rules file before writing anything. Claiming it last meant a
+  // failure at that step left a fully installed host absent from the registry, and the next
+  // uninstall elsewhere would then delete the rules out from under it.
+  await addRulesOwner(host);
   for (const { item } of changedFiles) await copyPlannedFile(item, host.agentsDir);
   if (changedRule) await copyPlannedFile(rule, host.agentsDir);
   // Seeded files are written once and then belong to the operator: an existing one is left
@@ -89,15 +125,16 @@ export async function install({ host, dryRun = false, force = false, packageRoot
   for (const seed of seedPlan(host, packageRoot)) {
     if (!(await targetExists(seed.target))) await copyPlannedFile(seed, host.agentsDir);
   }
-  const hookResult = await mergeHook(
-    host.settingsPath,
-    path.join(host.agentsDir, 'hooks', 'reply-guard.mjs'),
-    inspectedHook,
-  );
-  const hookRelative = plan.find((item) => path.basename(item.target) === 'reply-guard.mjs')?.relativeToHost;
-  if (!hookRelative) throw new Error('install plan does not contain hooks/reply-guard.mjs');
+  const hookResults = [];
+  for (const { spec } of targets) hookResults.push(await mergeHook(host.settingsPath, spec));
   const fingerprints = Object.fromEntries(await Promise.all(plan.map(async (item) =>
     [item.relativeToHost, await fileFingerprint(item.target)])));
+  const hooks = targets.map(({ definition, relative }, index) => {
+    const prior = record?.hooks?.find((hook) => hook.event === definition.event);
+    const createdGroup = hookResults[index].createdGroup || prior?.createdGroup === true;
+    return createdGroup ? { event: definition.event, path: relative, createdGroup: true }
+      : { event: definition.event, path: relative };
+  });
   await writeInstallRecord(host, {
     ...currentPackage,
     installedAt: new Date().toISOString(),
@@ -105,8 +142,10 @@ export async function install({ host, dryRun = false, force = false, packageRoot
     files: plan.map((item) => item.relativeToHost),
     fingerprints,
     rules: { path: rule.target, fingerprint: await fileFingerprint(rule.target) },
-    hook: { event: 'SubagentStop', path: hookRelative, createdGroup: hookResult.createdGroup || record?.hook?.createdGroup || false },
+    hooks,
   });
-  await addRulesOwner(host);
-  return { exitCode: 0, output: `Installed ${plan.length + 1} files and registered the SubagentStop hook.` };
+  return {
+    exitCode: 0,
+    output: `Installed ${plan.length + 1} files and registered the ${targets.map(({ definition }) => definition.event).join(' and ')} hooks.`,
+  };
 }

package/cli/manifest.mjs

@@ -3,6 +3,15 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
+// The hook table lives under src/ because the installed gate reads it too: cli/ is not copied
+// into a host, so a definition kept here would be invisible to the very hook it describes.
+import { HOOK_DEFINITIONS } from '../src/hook-definitions.mjs';
+import {
+  renderRequiredInputSummary,
+  renderRequiredInputs,
+} from '../src/required-inputs.mjs';
+
+export { HOOK_DEFINITIONS };
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 export const PACKAGE_ROOT = path.resolve(HERE, '..');
@@ -29,7 +38,11 @@ export const INSTALL_TABLE = Object.freeze([
 const posix = (value) => value.split(path.sep).join('/');
 
 export function replacePlaceholders(content, agentsDir) {
-  return content.replaceAll('{{CODEX_BRIDGE_DIR}}', posix(path.resolve(agentsDir)));
+  const agentType = content.match(/^name:\s*([^\r\n]+)$/m)?.[1].trim();
+  return content
+    .replaceAll('{{CODEX_BRIDGE_DIR}}', posix(path.resolve(agentsDir)))
+    .replaceAll('{{CODEX_REQUIRED_INPUTS_SUMMARY}}', renderRequiredInputSummary(agentType))
+    .replaceAll('{{CODEX_REQUIRED_INPUTS}}', renderRequiredInputs(agentType));
 }
 
 export async function packageInfo(packageRoot = PACKAGE_ROOT) {
@@ -41,6 +54,10 @@ export function installRecordPath(host) {
   return path.join(host.agentsDir, INSTALL_RECORD_NAME);
 }
 
+export function installedHookPath(host, definition) {
+  return path.join(host.agentsDir, 'hooks', definition.file);
+}
+
 /** Where each seeded file comes from and where it goes; contents are copied verbatim. */
 export function seedPlan(host, packageRoot = PACKAGE_ROOT) {
   return SEEDED_SOURCES.map((source) => ({
@@ -136,21 +153,38 @@ export function validateInstallRecord(record) {
       throw new Error('installation record rules fingerprint must be a 64-character hexadecimal SHA256 string');
     }
   }
-  if (!record.hook || typeof record.hook !== 'object' || Array.isArray(record.hook)) {
-    throw new Error('installation record hook must be an object');
+  if (record.hooks !== undefined && record.hook !== undefined) {
+    throw new Error('installation record must use hooks instead of hook');
   }
-  if (record.hook.event !== 'SubagentStop' || typeof record.hook.path !== 'string' || !record.hook.path) {
-    throw new Error('installation record hook must identify SubagentStop and its path');
+  const hooks = record.hooks !== undefined ? record.hooks : record.hook !== undefined ? [record.hook] : null;
+  if (!Array.isArray(hooks) || !hooks.length) {
+    throw new Error('installation record hooks must be a non-empty list');
   }
-  if (path.isAbsolute(record.hook.path) || record.hook.path.split(/[\\/]/).includes('..')) {
-    throw new Error('installation record hook path must stay relative to the host root');
-  }
-  if (path.basename(record.hook.path) !== 'reply-guard.mjs' || !record.files.includes(record.hook.path)) {
-    throw new Error('installation record hook path must name the installed reply-guard.mjs');
+  for (const hook of hooks) {
+    if (!hook || typeof hook !== 'object' || Array.isArray(hook)) {
+      throw new Error('installation record hook must be an object');
+    }
+    const definition = HOOK_DEFINITIONS.find((entry) => entry.event === hook.event);
+    if (!definition || typeof hook.path !== 'string' || !hook.path) {
+      throw new Error('installation record hook must identify a supported event and its path');
+    }
+    if (path.isAbsolute(hook.path) || hook.path.split(/[\\/]/).includes('..')) {
+      throw new Error('installation record hook path must stay relative to the host root');
+    }
+    if (path.basename(hook.path) !== definition.file || !record.files.includes(hook.path)) {
+      throw new Error(`installation record hook path must name the installed ${definition.file}`);
+    }
   }
   return record;
 }
 
+export function normalizeInstallRecord(record) {
+  validateInstallRecord(record);
+  if (record.hooks !== undefined) return record;
+  const { hook, ...withoutLegacyHook } = record;
+  return { ...withoutLegacyHook, hooks: [hook] };
+}
+
 export async function readInstallRecord(host) {
   let raw;
   try {
@@ -165,7 +199,7 @@ export async function readInstallRecord(host) {
   } catch (err) {
     throw new Error(`invalid installation record JSON: ${err.message}`);
   }
-  const record = validateInstallRecord(parsed);
+  const record = normalizeInstallRecord(parsed);
   // Earlier versions installed the config as a package file and recorded it. Dropping it here
   // is what stops the next update from calling the operator's edited config an orphan and
   // deleting it, and it needs no migration step: the record is rewritten on the next write.
@@ -180,8 +214,8 @@ export async function readInstallRecord(host) {
 }
 
 export async function writeInstallRecord(host, record) {
-  validateInstallRecord(record);
-  await fs.writeFile(installRecordPath(host), `${JSON.stringify(record, null, 2)}\n`);
+  const normalized = normalizeInstallRecord(record);
+  await fs.writeFile(installRecordPath(host), `${JSON.stringify(normalized, null, 2)}\n`);
 }
 
 export async function buildInstallPlan(host, packageRoot = PACKAGE_ROOT) {

package/cli/rules-owners.mjs

@@ -1,11 +1,16 @@
 /** Tracks which Claude Code hosts own the shared Codex bridge rules file. */
 import fs from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 import { normalizeRepoPath } from '../src/runner/project-dir.mjs';
 
 export const RULES_REGISTRY_NAME = '.codex-bridge-rules.json';
 export const RULES_REGISTRY_VERSION = 1;
 
+const REGISTRY_LOCK_RETRIES = 200;
+const REGISTRY_LOCK_DELAY_MS = 5;
+const REGISTRY_LOCK_STALE_MS = 30_000;
+
 export function rulesRegistryPath(host) {
   return path.join(host.codexRulesDir, RULES_REGISTRY_NAME);
 }
@@ -59,8 +64,66 @@ function hasSameOwners(raw, registry) {
 }
 
 async function writeRulesRegistry(host, registry) {
+  const target = rulesRegistryPath(host);
+  const temporary = `${target}.${randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(temporary, `${JSON.stringify(registry, null, 2)}\n`, { flag: 'wx' });
+    await fs.rename(temporary, target);
+  } catch (err) {
+    await fs.rm(temporary, { force: true }).catch(() => {});
+    throw err;
+  }
+}
+
+function registryLockPath(host) {
+  return `${rulesRegistryPath(host)}.lock`;
+}
+
+function waitForRegistryLock() {
+  return new Promise((resolve) => setTimeout(resolve, REGISTRY_LOCK_DELAY_MS));
+}
+
+/**
+ * A lock nobody released is worse than no lock: interrupting an install left the file behind and
+ * every later install and uninstall died on it until someone deleted it by hand (reproduced
+ * 2026-08-04). An owner update takes milliseconds, so a lock older than the staleness window
+ * belongs to a process that is gone.
+ */
+async function dropStaleLock(lockPath) {
+  try {
+    const { mtimeMs } = await fs.stat(lockPath);
+    if (Date.now() - mtimeMs < REGISTRY_LOCK_STALE_MS) return false;
+    await fs.rm(lockPath, { force: true });
+    return true;
+  } catch {
+    // Vanished or unreadable — let the next open() decide rather than guess here.
+    return false;
+  }
+}
+
+async function acquireRegistryLock(host) {
   await fs.mkdir(host.codexRulesDir, { recursive: true });
-  await fs.writeFile(rulesRegistryPath(host), `${JSON.stringify(registry, null, 2)}\n`);
+  const lockPath = registryLockPath(host);
+  for (let attempt = 0; attempt < REGISTRY_LOCK_RETRIES; attempt += 1) {
+    try {
+      const handle = await fs.open(lockPath, 'wx');
+      return { handle, lockPath };
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      if (!(await dropStaleLock(lockPath))) await waitForRegistryLock();
+    }
+  }
+  throw new Error(`timed out waiting for rules ownership registry lock: ${lockPath}`);
+}
+
+async function withRegistryLock(host, action) {
+  const lock = await acquireRegistryLock(host);
+  try {
+    return await action();
+  } finally {
+    await lock.handle.close().catch(() => {});
+    await fs.rm(lock.lockPath, { force: true }).catch(() => {});
+  }
 }
 
 export async function readRulesRegistry(host) {
@@ -68,15 +131,19 @@ export async function readRulesRegistry(host) {
 }
 
 export async function addRulesOwner(host) {
-  const loaded = await loadRulesRegistry(host);
-  const owner = normalizedRulesOwner(host);
-  const current = loaded?.registry || { version: RULES_REGISTRY_VERSION, owners: [] };
-  const registry = {
-    version: RULES_REGISTRY_VERSION,
-    owners: normalizeOwners([...current.owners, owner]),
-  };
-  if (!loaded || !hasSameOwners(loaded.raw, registry)) await writeRulesRegistry(host, registry);
-  return registry;
+  await loadRulesRegistry(host);
+  return withRegistryLock(host, async () => {
+    // Read after locking so a concurrent installer is merged instead of overwritten.
+    const loaded = await loadRulesRegistry(host);
+    const owner = normalizedRulesOwner(host);
+    const current = loaded?.registry || { version: RULES_REGISTRY_VERSION, owners: [] };
+    const registry = {
+      version: RULES_REGISTRY_VERSION,
+      owners: normalizeOwners([...current.owners, owner]),
+    };
+    if (!loaded || !hasSameOwners(loaded.raw, registry)) await writeRulesRegistry(host, registry);
+    return registry;
+  });
 }
 
 export function remainingRulesOwners(registry, host) {
@@ -86,16 +153,20 @@ export function remainingRulesOwners(registry, host) {
 }
 
 export async function removeRulesOwner(host) {
-  const loaded = await loadRulesRegistry(host);
-  if (!loaded) return null;
-  const registry = {
-    version: RULES_REGISTRY_VERSION,
-    owners: remainingRulesOwners(loaded.registry, host),
-  };
-  if (registry.owners.length) {
-    if (!hasSameOwners(loaded.raw, registry)) await writeRulesRegistry(host, registry);
-  } else {
-    await fs.rm(rulesRegistryPath(host), { force: true });
-  }
-  return registry;
+  const initial = await loadRulesRegistry(host);
+  if (!initial) return null;
+  return withRegistryLock(host, async () => {
+    const loaded = await loadRulesRegistry(host);
+    if (!loaded) return null;
+    const registry = {
+      version: RULES_REGISTRY_VERSION,
+      owners: remainingRulesOwners(loaded.registry, host),
+    };
+    if (registry.owners.length) {
+      if (!hasSameOwners(loaded.raw, registry)) await writeRulesRegistry(host, registry);
+    } else {
+      await fs.rm(rulesRegistryPath(host), { force: true });
+    }
+    return registry;
+  });
 }

package/cli/settings-merge.mjs

@@ -1,14 +1,31 @@
-/** Merges and removes the codex-bridge SubagentStop hook without disturbing host settings. */
+/** Merges and removes named codex-bridge hooks without disturbing host settings. */
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 
-const EVENT = 'SubagentStop';
+const LEGACY_SPEC = { event: 'SubagentStop', matcher: '*' };
 
-function commandFor(guardPath) {
+export function commandFor(guardPath) {
   return `node "${path.resolve(guardPath)}"`;
 }
 
+function normalizeSpec(specOrPath) {
+  if (typeof specOrPath === 'string') {
+    return { ...LEGACY_SPEC, command: commandFor(specOrPath) };
+  }
+  if (!specOrPath || typeof specOrPath !== 'object'
+    || typeof specOrPath.event !== 'string'
+    || typeof specOrPath.matcher !== 'string'
+    || typeof specOrPath.command !== 'string') {
+    throw new TypeError('hook spec must contain event, matcher, and command strings');
+  }
+  return {
+    event: specOrPath.event,
+    matcher: specOrPath.matcher,
+    command: specOrPath.command,
+  };
+}
+
 async function readSettings(settingsPath) {
   try {
     const raw = await fs.readFile(settingsPath, 'utf8');
@@ -27,8 +44,8 @@ async function readSettings(settingsPath) {
   }
 }
 
-function groups(settings) {
-  const value = settings?.hooks?.[EVENT];
+function groups(settings, event) {
+  const value = settings?.hooks?.[event];
   return Array.isArray(value) ? value : [];
 }
 
@@ -40,12 +57,14 @@ function groupHooks(group) {
   return Array.isArray(group?.hooks) ? group.hooks : [];
 }
 
-export async function inspectHook(settingsPath, guardPath) {
+export async function inspectHook(settingsPath, specOrPath) {
   const state = await readSettings(settingsPath);
-  const command = commandFor(guardPath);
-  const present = groups(state.settings).some((group) =>
-    groupHooks(group).some((hook) => hook?.type === 'command' && hook.command === command));
-  return { ...state, command, present };
+  const spec = normalizeSpec(specOrPath);
+  const present = groups(state.settings, spec.event)
+    .filter((group) => group?.matcher === spec.matcher)
+    .some((group) => groupHooks(group)
+      .some((hook) => hook?.type === 'command' && hook.command === spec.command));
+  return { ...state, ...spec, present };
 }
 
 function backupName(settingsPath) {
@@ -66,35 +85,38 @@ async function atomicWrite(settingsPath, settings, previous) {
   }
 }
 
-export async function mergeHook(settingsPath, guardPath, inspected) {
-  const state = inspected || await inspectHook(settingsPath, guardPath);
+export async function mergeHook(settingsPath, specOrPath, inspected) {
+  const spec = normalizeSpec(specOrPath);
+  const state = inspected || await inspectHook(settingsPath, spec);
   if (state.present) return { changed: false, createdGroup: false };
   const settings = structuredClone(state.settings);
   settings.hooks ??= {};
-  if (!Array.isArray(settings.hooks[EVENT])) settings.hooks[EVENT] = [];
-  let group = settings.hooks[EVENT].find((entry) => entry?.matcher === '*');
+  if (!Array.isArray(settings.hooks[spec.event])) settings.hooks[spec.event] = [];
+  let group = settings.hooks[spec.event].find((entry) => entry?.matcher === spec.matcher);
   const createdGroup = !group;
   if (!group) {
-    group = { matcher: '*', hooks: [] };
-    settings.hooks[EVENT].push(group);
+    group = { matcher: spec.matcher, hooks: [] };
+    settings.hooks[spec.event].push(group);
   }
   if (!Array.isArray(group.hooks)) group.hooks = [];
-  group.hooks.push(ownHook(state.command));
+  group.hooks.push(ownHook(spec.command));
   await atomicWrite(settingsPath, settings, state);
   return { changed: true, createdGroup };
 }
 
-export async function removeHook(settingsPath, guardPath, { createdGroup = false } = {}) {
-  const state = await inspectHook(settingsPath, guardPath);
+export async function removeHook(settingsPath, specOrPath, { createdGroup = false } = {}) {
+  const spec = normalizeSpec(specOrPath);
+  const state = await inspectHook(settingsPath, spec);
   if (!state.present) return { changed: false };
   const settings = structuredClone(state.settings);
-  const eventGroups = groups(settings);
+  const eventGroups = groups(settings, spec.event);
   for (let index = eventGroups.length - 1; index >= 0; index -= 1) {
     const group = eventGroups[index];
+    if (group?.matcher !== spec.matcher) continue;
     if (!Array.isArray(group?.hooks)) continue;
     group.hooks = group.hooks.filter((hook) =>
-      !(hook?.type === 'command' && hook.command === state.command));
-    if (createdGroup && group.matcher === '*' && group.hooks.length === 0) eventGroups.splice(index, 1);
+      !(hook?.type === 'command' && hook.command === spec.command));
+    if (createdGroup && group.hooks.length === 0) eventGroups.splice(index, 1);
   }
   await atomicWrite(settingsPath, settings, state);
   return { changed: true };