@lyupro/codex-bridge 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -4,6 +4,32 @@ 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.4] - 2026-08-05
+
+### Added
+
+- A continuation has to prove the orchestrator ordered it. `--continue` is refused unless the task text carries a `continue:` grant naming the run being continued and why, and the refusal costs nothing: no run folder is created and Codex is never started. The grant is single-use by construction rather than by a counter — continuing the last run of a chain appends a later one, so the same line stops matching by itself. Until this release a dispatcher could decide on a second pass alone: one did, spent 75 691 tokens of the Codex subscription and created a module the order never asked for.
+- A reply that stays silent about a live `codex-build` run of the same project is blocked. The guard reads the project's runs folder from disk instead of trusting the paths the reply chose to mention, so a second run can no longer be left working in the background while the verdict of the first is handed back. Runs of `codex-scout` and `codex-review` are not counted: they hold a read-only sandbox, and blocking a reply over one would spend the guard's budget on a run that touches nothing.
+- A `PreToolUse` lock refuses file edits inside a repository held by a live `codex-build` run. Knowing that a run is live is not the same as being unable to disturb it — edits made during that window land in the runner's before/after snapshot and fail an honest run for work it never did. An edit made through `Bash` still walks past the lock; parsing a command line is not something a guard can do reliably.
+
+### Fixed
+
+- `doctor` names the file each hook was registered for. With two hooks on one event it matched the installation record by event alone and reported the worktree lock's matcher as pointing at `order-gate.mjs` — the one line where an operator can check what is installed, showing the wrong file.
+- Hook presence is decided by this package's own command rather than by the matcher it currently sits under. The matcher is generated from the list of host tool names and grows whenever a spelling is added, so a host installed under the previous matcher would collect a duplicate hook on update and keep a hook pointing at a deleted file after uninstall.
+
+## [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

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,35 @@ 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');
+    // The file, not just the event: PreToolUse carries two hooks of this package, and matching
+    // by event alone reported the worktree lock's matcher as pointing at order-gate.mjs. The
+    // hook line is the only place an operator can see WHICH file a matcher was registered for,
+    // so a wrong name here is worse than no line at all.
+    const recorded = record.hooks.find((hook) => hook.event === definition.event
+      && path.basename(hook.path) === definition.file);
+    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) {
@@ -155,7 +157,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,7 +14,7 @@ import {
   writeInstallRecord,
 } from './manifest.mjs';
 import { copyPlannedFile, targetMatches } from './copy.mjs';
-import { inspectHook, mergeHook } from './settings-merge.mjs';
+import { commandFor, inspectHook, mergeHook } from './settings-merge.mjs';
 import { addRulesOwner, readRulesRegistry } from './rules-owners.mjs';
 
 async function targetExists(target) {
@@ -25,6 +27,24 @@ 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);
@@ -32,10 +52,14 @@ export async function install({ host, dryRun = false, force = false, 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),
@@ -68,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.' };
   }
@@ -79,7 +104,12 @@ 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') };
   }
@@ -95,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(),
@@ -111,7 +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,
   });
-  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,40 @@ 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 definitions = HOOK_DEFINITIONS.filter((entry) => entry.event === hook.event);
+    if (!definitions.length || 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');
+    }
+    const definition = definitions.find((entry) => path.basename(hook.path) === entry.file);
+    if (!definition || !record.files.includes(hook.path)) {
+      const files = definitions.map((entry) => entry.file).join(' or ');
+      throw new Error(`installation record hook path must name the installed ${files}`);
+    }
   }
   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 +201,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 +216,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/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,25 @@ function groupHooks(group) {
   return Array.isArray(group?.hooks) ? group.hooks : [];
 }
 
-export async function inspectHook(settingsPath, guardPath) {
+const hasOwnCommand = (group, command) =>
+  groupHooks(group).some((hook) => hook?.type === 'command' && hook.command === command);
+
+/**
+ * Presence is decided by the command, not by the matcher it currently sits under.
+ *
+ * The matcher is generated from the tool list in hook-definitions.mjs, so it changes whenever a
+ * host spelling is added — `Agent` became `Agent|Task` in one release, and the write-tool matcher
+ * will grow the same way. A host installed under the old matcher would then be invisible to the
+ * new lookup: update would register a duplicate and uninstall would leave a hook pointing at a
+ * deleted file. The command is this package's own absolute path, so it identifies our entry
+ * wherever the group ended up.
+ */
+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)
+    .some((group) => hasOwnCommand(group, spec.command));
+  return { ...state, ...spec, present };
 }
 
 function backupName(settingsPath) {
@@ -66,35 +96,41 @@ 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);
+  // Removal follows the same rule as the lookup above: our command, whatever matcher it is
+  // filed under. A foreign hook is left alone because its command is not ours, not because it
+  // sits in another group.
   for (let index = eventGroups.length - 1; index >= 0; index -= 1) {
     const group = eventGroups[index];
+    if (!hasOwnCommand(group, spec.command)) 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 };

package/cli/uninstall.mjs

@@ -1,8 +1,13 @@
 /** Uninstalls only recorded codex-bridge files while preserving host data and foreign files. */
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { fileFingerprint, installRecordPath, readInstallRecord } from './manifest.mjs';
-import { removeHook } from './settings-merge.mjs';
+import {
+  fileFingerprint,
+  HOOK_DEFINITIONS,
+  installRecordPath,
+  readInstallRecord,
+} from './manifest.mjs';
+import { commandFor, removeHook } from './settings-merge.mjs';
 import { readRulesRegistry, removeRulesOwner, remainingRulesOwners } from './rules-owners.mjs';
 
 async function removeEmpty(directory) {
@@ -25,6 +30,10 @@ function remainingOwnersText(count) {
   return `${count} other owner${count === 1 ? '' : 's'} ${count === 1 ? 'remains' : 'remain'}`;
 }
 
+function hookDefinition(event) {
+  return HOOK_DEFINITIONS.find((definition) => definition.event === event);
+}
+
 export async function uninstall({ host, dryRun = false } = {}) {
   // Preflight before removing the hook: package removal on a broken registry left the host without its watchdog.
   let registry = null;
@@ -61,14 +70,24 @@ export async function uninstall({ host, dryRun = false } = {}) {
         }
       }
     }
-    lines.push('Would remove the SubagentStop hook and installation record.');
+    for (const hook of record.hooks) {
+      const definition = hookDefinition(hook.event);
+      lines.push(`Would remove the ${hook.event} hook for matcher ${definition.matcher}.`);
+    }
+    lines.push('Would remove the installation record.');
     lines.push(preservation);
     return { exitCode: 0, output: lines.join('\n') };
   }
 
-  await removeHook(host.settingsPath, path.join(host.root, record.hook.path), {
-    createdGroup: record.hook.createdGroup === true,
-  });
+  for (const hook of record.hooks) {
+    const definition = hookDefinition(hook.event);
+    const target = path.join(host.root, hook.path);
+    await removeHook(host.settingsPath, {
+      event: hook.event,
+      matcher: definition.matcher,
+      command: commandFor(target),
+    }, { createdGroup: hook.createdGroup === true });
+  }
   let ownership = null;
   if (!registryError) {
     try {

package/cli/update.mjs

@@ -5,13 +5,15 @@ import { install } from './install.mjs';
 import {
   buildInstallPlan,
   fileFingerprint,
+  HOOK_DEFINITIONS,
+  installedHookPath,
   packageInfo,
   readInstallRecord,
   recordMatchesPackage,
   rulesPlan,
 } from './manifest.mjs';
 import { targetMatches } from './copy.mjs';
-import { inspectHook } from './settings-merge.mjs';
+import { commandFor, inspectHook } from './settings-merge.mjs';
 import { addRulesOwner, readRulesRegistry } from './rules-owners.mjs';
 
 async function exists(target) {
@@ -37,6 +39,23 @@ function classifyOrphan(state, record) {
   return 'modified';
 }
 
+function hookTargets(host) {
+  return HOOK_DEFINITIONS.map((definition) => {
+    const target = installedHookPath(host, definition);
+    return {
+      definition,
+      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));
+}
+
 /**
  * What the run actually did, counted by outcome. `Updated codex-bridge.` alone told the operator
  * nothing about the files that were rewritten or removed on their behalf.
@@ -62,7 +81,7 @@ function conflictOutput(conflicts, legacy, dryRun) {
   return [heading, ...lines].join('\n');
 }
 
-function dryRunOutput(states, hookPresent, legacy) {
+function dryRunOutput(states, hookStates, legacy) {
   const lines = [];
   for (const state of states) {
     if (state.status === 'outdated') lines.push(`Would update ${state.relative}.`);
@@ -72,7 +91,10 @@ function dryRunOutput(states, hookPresent, legacy) {
     if (state.status === 'orphaned' && state.exists) lines.push(`Would remove ${state.relative}.`);
     if (state.status === 'modified' && !state.item) lines.push(`Would preserve modified orphan ${state.relative}.`);
   }
-  if (!hookPresent) lines.push('Would register SubagentStop hook.');
+  hookStates.forEach(({ state, target }) => {
+    const { definition } = target;
+    if (!state.present) lines.push(`Would register ${definition.event} hook for matcher ${definition.matcher}.`);
+  });
   lines.push('Would write installation record with new fingerprints.');
   if (legacy && states.some((state) => state.status === 'modified')) {
     lines.push('Installation record has no fingerprints; differing files are treated as modified.');
@@ -135,19 +157,23 @@ export async function update({ host, dryRun = false, force = false, packageRoot
     return { exitCode: 1, output: conflictOutput(conflicts, legacy, dryRun) };
   }
 
-  const guardPath = path.join(host.agentsDir, 'hooks', 'reply-guard.mjs');
-  const inspectedHook = await inspectHook(host.settingsPath, guardPath);
+  const targets = hookTargets(host);
+  const inspectedHooks = await Promise.all(targets.map(async (target) => ({
+    target,
+    state: await inspectHook(host.settingsPath, target.spec),
+  })));
   const currentPackage = await packageInfo(packageRoot);
   const recordCurrent = recordMatchesPackage(record, plan, currentPackage,
     new Map(plannedStates.map((state) => [state.relative, state.fingerprint])),
     { path: rule.target, fingerprint: ruleState.fingerprint });
   const changed = states.some((state) => state.status !== 'up-to-date');
-  if (!changed && inspectedHook.present && recordCurrent) {
+  if (!changed && inspectedHooks.every(({ state }) => state.present)
+    && recordHasHooks(record, targets) && recordCurrent) {
     if (!dryRun) await addRulesOwner(host);
     return { exitCode: 0, output: 'codex-bridge is up to date' };
   }
   if (dryRun) {
-    return { exitCode: 0, output: dryRunOutput(states, inspectedHook.present, legacy) };
+    return { exitCode: 0, output: dryRunOutput(states, inspectedHooks, legacy) };
   }
 
   for (const state of orphanStates) {