@lyupro/codex-bridge 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -4,6 +4,19 @@ 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

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) {
@@ -155,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,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,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/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 };

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyupro/codex-bridge",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Delegate implementation, reconnaissance and code review from Claude Code to the Codex CLI: dispatcher agents, a runner that survives a dropped call, and a verdict that checks the report against the worktree.",
   "keywords": [
     "claude-code",

package/src/agents/codex-build.md

@@ -1,6 +1,6 @@
 ---
 name: codex-build
-description: Имплементация ВНЕ подписки Claude — правки кода, новые модули, рефакторинг по образцу, починка тестов. Работу выполняет Codex CLI (подписка ChatGPT) с правом записи в репозиторий строго в пределах обязательного `scope`, Claude платит только за постановку задачи и ≤5 строк выжимки. Отчёт и полный лог кладёт в ~/.claude/codex-runs/, в чат — короткая выжимка + путь. Ревью и приёмку делает отдельный агент Claude, не этот.
+description: Имплементация ВНЕ подписки Claude — правки кода, новые модули, рефакторинг по образцу, починка тестов. Работу выполняет Codex CLI (подписка ChatGPT) с правом записи в репозиторий строго в пределах обязательного `scope`, Claude платит только за постановку задачи и ≤5 строк выжимки. Отчёт и полный лог кладёт в ~/.claude/codex-runs/, в чат — короткая выжимка + путь. Ревью и приёмку делает отдельный агент Claude, не этот. {{CODEX_REQUIRED_INPUTS_SUMMARY}}
 model: haiku
 tools: Bash
 ---
@@ -19,19 +19,19 @@ diff, and do not reason about the task.
 Your
 job is to report the run status honestly, including failure.
 
+## Required dispatcher inputs
+
+{{CODEX_REQUIRED_INPUTS}}
+
 ## What you receive as input
 
 - The task statement: what to change and the completion criteria.
 - The path to the repository. If none is given, use the current working directory.
-- `scope: "<glob,glob>"` — REQUIRED. The list of paths Codex may touch, relative to the
-  repository root; the runner will not start without it. If the orchestrator did not give it, do not
-  guess:
-  start the runner without `--scope` and return its refusal exactly.
-- `order id: <label>` — the label the orchestrator issued for this order. Pass it as `--order-id`
-  exactly as given. Never invent one, never edit one, never reuse one from another order: the
-  runner chains runs by this label, and a made-up label is how a repeat run hides. Absent means
-  the same as an absent `--scope`: start the runner without the flag and return its refusal
-  verbatim.
+- Every input listed under **Required dispatcher inputs** above, passed on exactly as given:
+  `order id` as `--order-id`, `scope` as `--scope`. Never invent a value, never edit one, never
+  reuse an order id from another order — the runner chains runs by that label, and a made-up label
+  is how a repeat run hides. If the orchestrator did not give a required input, do not guess: start
+  the runner without its flag and return the runner's refusal exactly.
 - `continue` — pass it as the `--continue` flag only if the orchestrator gave it explicitly; do not
   add or guess it yourself. The contract is the same kind as `--scope`: if this task (the same
   `slug` and the same repository) already had a run, the runner will refuse to start without

package/src/agents/codex-review.md

@@ -1,6 +1,6 @@
 ---
 name: codex-review
-description: Независимое второе мнение по коду от другой модели — ревью незакоммиченных правок, ветки или коммита силами Codex CLI (подписка ChatGPT). Не заменяет приёмку на стороне Claude, а дополняет её взглядом со стороны. Выдаёт строгий JSON с severity и confidence по каждой находке, в чат — ≤5 строк со счётчиком по важности.
+description: Независимое второе мнение по коду от другой модели — ревью незакоммиченных правок, ветки или коммита силами Codex CLI (подписка ChatGPT). Не заменяет приёмку на стороне Claude, а дополняет её взглядом со стороны. Выдаёт строгий JSON с severity и confidence по каждой находке, в чат — ≤5 строк со счётчиком по важности. {{CODEX_REQUIRED_INPUTS_SUMMARY}}
 model: haiku
 tools: Bash
 ---
@@ -15,6 +15,10 @@ against the Claude Max quota. Claude still performs acceptance in a separate pas
 second
 opinion, not a verdict.
 
+## Required dispatcher inputs
+
+{{CODEX_REQUIRED_INPUTS}}
+
 ## What you receive as input
 
 - What to review. One of these modes:
@@ -22,10 +26,11 @@ opinion, not a verdict.
   - branch against base — `--mode base:<branch>`;
   - specific commit — `--mode commit:<sha>`.
 - The path to the repository. If none is given, use the current working directory.
-- `order id: <label>` — the label the orchestrator issued for this order. Pass it as `--order-id`
-  exactly as given. Never invent one, never edit one, never reuse one from another order: the
-  runner chains runs by this label, and a made-up label is how a repeat run hides. If it was not
-  given, start the runner without the flag and return its refusal verbatim.
+- Every input listed under **Required dispatcher inputs** above, passed on exactly as given:
+  `order id` as `--order-id`. Never invent a value, never edit one, never reuse an order id from
+  another order — the runner chains runs by that label, and a made-up label is how a repeat run
+  hides. If the orchestrator did not give a required input, do not guess — start the runner without
+  its flag and return the runner's refusal verbatim.
 - Optional: review focus as text ("look for races and error handling"), `slug:`, `effort:
   <none|minimal|low|medium|high|xhigh|max>`.
 

package/src/agents/codex-scout.md

@@ -1,6 +1,6 @@
 ---
 name: codex-scout
-description: Разведка и диагностика ВНЕ подписки Claude — исследование кодовой базы, поиск причины бага, ревью, сбор фактов. Работу выполняет Codex CLI (подписка ChatGPT), Claude платит только за постановку задачи и ≤5 строк выжимки. Строго read-only: писать в репозиторий физически не может. Подробный отчёт кладёт в ~/.claude/codex-runs/, в чат — короткая выжимка + путь.
+description: Разведка и диагностика ВНЕ подписки Claude — исследование кодовой базы, поиск причины бага, ревью, сбор фактов. Работу выполняет Codex CLI (подписка ChatGPT), Claude платит только за постановку задачи и ≤5 строк выжимки. Строго read-only: писать в репозиторий физически не может. Подробный отчёт кладёт в ~/.claude/codex-runs/, в чат — короткая выжимка + путь. {{CODEX_REQUIRED_INPUTS_SUMMARY}}
 model: haiku
 tools: Bash
 ---
@@ -13,17 +13,21 @@ ChatGPT subscription. All heavy work (reading files, reasoning, generating the r
 on the Codex side. Every extra line you send to chat costs Claude tokens. Therefore: do not read
 files, do not run grep, do not retell the report, and do not reason about the task.
 
+## Required dispatcher inputs
+
+{{CODEX_REQUIRED_INPUTS}}
+
 ## What you receive as input
 
 - The task statement (what to find out / what to diagnose / what to review).
 - The path to the repository. If none is given, work in the current working directory.
 - Optional: `effort: <none|minimal|low|medium|high|xhigh|max>` — Codex reasoning depth.
 - Optional: `slug: <short-name>` for the run folder.
-- `order id: <label>` — the label the orchestrator issued for this order. Pass it as `--order-id`
-  exactly as given. Never invent one, never edit one, never reuse one from another order: the
-  runner chains runs by this label, and a made-up label is how a repeat run hides. If the
-  orchestrator did not give it, do not guess — start the runner without the flag and return its
-  refusal verbatim, the same way you would with a missing `--scope` in codex-build.
+- Every input listed under **Required dispatcher inputs** above, passed on exactly as given:
+  `order id` as `--order-id`. Never invent a value, never edit one, never reuse an order id from
+  another order — the runner chains runs by that label, and a made-up label is how a repeat run
+  hides. If the orchestrator did not give a required input, do not guess — start the runner without
+  its flag and return the runner's refusal verbatim.
 - `question: <text>` — REQUIRED and repeatable. For every sub-question the orchestrator gave,
   pass one `--question "<text>"` flag exactly as given. Never invent, merge, reword, or drop a
   sub-question. If the orchestrator did not give one, do not guess — start the runner without

package/src/hook-definitions.mjs

@@ -0,0 +1,25 @@
+/**
+ * Names the hooks this package registers in a host, and the tools they listen to.
+ *
+ * The gate and the installer would otherwise each carry their own idea of which tool starts a
+ * subagent, and the first host that renames it would leave a registered hook listening for a
+ * tool that never fires — silence indistinguishable from approval, which is the exact failure
+ * the gate exists to end. `cli/manifest.mjs` builds the settings matcher from SUBAGENT_TOOLS
+ * and `src/hooks/order-gate.mjs` recognises the same names, so a matcher can never drift away
+ * from what the hook actually checks.
+ */
+
+/**
+ * Every name a Claude Code host has used for the tool that launches a subagent. Both are live:
+ * this package is installed into hosts of different ages, `Task` is the long-standing name and
+ * `Agent` the current one. A hook registered for only one of them is dead weight on the other.
+ */
+export const SUBAGENT_TOOLS = Object.freeze(['Agent', 'Task']);
+
+/** A PreToolUse matcher is a regular expression over tool names, so alternation covers both. */
+export const SUBAGENT_TOOL_MATCHER = SUBAGENT_TOOLS.join('|');
+
+export const HOOK_DEFINITIONS = Object.freeze([
+  Object.freeze({ event: 'SubagentStop', matcher: '*', file: 'reply-guard.mjs' }),
+  Object.freeze({ event: 'PreToolUse', matcher: SUBAGENT_TOOL_MATCHER, file: 'order-gate.mjs' }),
+]);

package/src/hooks/order-gate.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse gate for the Codex dispatchers (codex-scout / codex-build / codex-review).
+ *
+ * The runner rejects a dispatcher immediately when order id (and scope for codex-build) is
+ * absent, but the old requirement lived only in the prompt read by the dispatcher. The caller
+ * therefore had no enforced place to provide it and codex-build died before doing work. This
+ * gate checks the producer's task text while it can still be corrected.
+ *
+ * Input is Claude Code's hook JSON on stdin. The last payload is retained for diagnostics so a
+ * future host schema change can be inspected instead of guessed at. Any uncertain shape passes
+ * silently because a diagnostic guard must never break an unrelated tool call.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { missingInputs } from '../required-inputs.mjs';
+import { SUBAGENT_TOOLS } from '../hook-definitions.mjs';
+
+const HOME = os.homedir();
+const LOG_DIR = path.join(HOME, '.claude', 'logs');
+const GUARDED = new Set(['codex-scout', 'codex-build', 'codex-review']);
+/**
+ * Both spellings of the subagent-launching tool, from the same list the installer builds its
+ * matcher from. Recognising only the name this host happens to use would make the gate silent
+ * on every other host, and a gate that is silent for an unknown reason is worse than none.
+ */
+const SUBAGENT_TOOL_NAMES = new Set(SUBAGENT_TOOLS);
+
+const pass = () => process.exit(0);
+
+let input;
+try {
+  input = JSON.parse(fs.readFileSync(0, 'utf8'));
+} catch {
+  pass();
+}
+
+try {
+  fs.mkdirSync(LOG_DIR, { recursive: true });
+  fs.writeFileSync(path.join(LOG_DIR, 'codex-order-gate.last.json'), `${JSON.stringify(input, null, 2)}\n`);
+} catch {
+  // Diagnostics are a convenience, never a reason to fail the turn.
+}
+
+if (!input || typeof input !== 'object' || Array.isArray(input)) pass();
+if (!SUBAGENT_TOOL_NAMES.has(input.tool_name)) pass();
+
+const toolInput = input.tool_input;
+if (!toolInput || typeof toolInput !== 'object' || Array.isArray(toolInput)) pass();
+if (!GUARDED.has(toolInput.subagent_type) || typeof toolInput.prompt !== 'string') pass();
+
+const missing = missingInputs(toolInput.subagent_type, toolInput.prompt);
+if (!missing.length) pass();
+
+const reason = [
+  'Order gate denied the Agent call because required dispatcher input(s) are missing or still placeholders.',
+  'Write each value in tool_input.prompt using `label: value` before launching the dispatcher:',
+  ...missing.map((entry) => `- ${entry.label}: ${entry.explanation} Example: \`${entry.example}\`.`),
+].join('\n');
+
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: 'PreToolUse',
+    permissionDecision: 'deny',
+    permissionDecisionReason: reason,
+  },
+}));

package/src/meta/outcome.mjs

@@ -0,0 +1,65 @@
+/**
+ * The outcome a build run declared about itself, and whether it was contracted to declare one.
+ *
+ * The runner cannot infer this. On 2026-08-04 (`2026-08-04_202959_build`) a build was asked to
+ * fix a function in a module absent from the checkout and answered `OK — No code change was
+ * made because the requested target file is absent`: every artifact was well-formed and a clean
+ * tree is a legitimate outcome for "check and fix if broken", so nothing in the verdict could
+ * object. Plan_12 moved the outcome from inference to declaration — the executor states it, the
+ * runner reads it.
+ *
+ * The contract marker is the run's own schema.json, not a version number written beside it. The
+ * schema IS the contract Codex was handed, so "was this run required to declare an outcome" and
+ * "what was it required to answer" cannot drift apart: they are the same file. A run from before
+ * this version, or a replay of an archived folder, has no `outcome` in its schema and keeps the
+ * verdict it always had.
+ */
+import path from 'node:path';
+import { line, readJson } from './paths.mjs';
+
+const FIELD = 'outcome';
+
+/** The values schemas.mjs allows; anything else in a result.json is a broken answer. */
+const DONE = 'done';
+const FAIL = 'fail';
+
+/**
+ * Was this run handed a schema that demands an outcome? Read off the run's own schema.json,
+ * which the launcher writes before Codex is invoked, so the answer describes the contract this
+ * run actually ran under rather than the one the current source happens to define.
+ */
+export function requiresOutcome(runDir) {
+  const schema = readJson(path.join(runDir, 'schema.json'));
+  return Array.isArray(schema?.required) && schema.required.includes(FIELD);
+}
+
+/**
+ * Why the declared outcome fails the run, or null when it does not. Three ways to fail: the
+ * executor said the work was not done; the field is missing although the schema required it
+ * (Codex enforces the schema, so this is a hand-edited or truncated result rather than a normal
+ * answer); the field holds a value the enum does not define.
+ *
+ * A declared `done` is not proof of anything — it only stops here. The tree, the scope and the
+ * report are checked after this, exactly as before: the field adds a reason to go red, it
+ * removes none.
+ */
+export function outcomeGap(runDir, result) {
+  if (!requiresOutcome(runDir)) return null;
+  // Compared exactly, never normalised. Trimming and lower-casing would let `"DONE"` or
+  // `" done "` — values the enum forbids and Codex would have rejected — buy their way past
+  // this check, and a malformed success is exactly the shape this file exists to stop. A
+  // malformed failure loses nothing by the same rule: it still goes red, only by the
+  // unknown-value branch.
+  const declared = result?.[FIELD];
+  if (declared === DONE) return null;
+  if (declared === FAIL) {
+    // The reason comes from summary rather than a field of its own: summary is already
+    // mandatory and already describes what happened, and two fields about one thing drift.
+    const stated = line(result?.summary || '', 240);
+    return `the task was not done: ${stated || 'build declared fail and gave no summary'}`;
+  }
+  if (declared === undefined || declared === null || declared === '') {
+    return 'result is not filled in: the response contract requires outcome "done" or "fail"';
+  }
+  return `result declares an unknown outcome “${line(String(declared), 40)}”, expected "done" or "fail"`;
+}

package/src/meta/reply.mjs

@@ -9,6 +9,7 @@
  * The lines built here ARE the reply. Agents forward this text verbatim instead of
  * composing prose, which is what keeps a delegated run at five lines.
  */
+import fs from 'node:fs';
 import path from 'node:path';
 import { changedPaths, line, readText } from './paths.mjs';
 import { splitRunChanges } from './environment.mjs';
@@ -113,10 +114,32 @@ export function failReply(ctx, meta) {
   return [
     `FAIL — ${line(meta.reason, 170)}`,
     `Artifacts: raw.log ${meta.log_bytes} B · ${path.basename(ctx.resultPath)} ${meta.result_ok ? 'filled' : 'empty or missing'} · exit=${meta.exit}`,
+    // A failed build says what it left behind, exactly as a LIMIT does. "The work was not
+    // done" is not "the tree is clean": a run can write half a change and then declare fail,
+    // and the orchestrator has to know whether there is something to revert before it decides
+    // anything else.
+    ...(ctx.agent === 'codex-build' ? [`Worktree: ${worktreeState(ctx.runDir)}`] : []),
     `Log: ${ctx.file('raw.log')}`,
   ];
 }
 
+/**
+ * What the run left in the tree, or an admission that nobody knows. Both snapshots are
+ * required: a run killed before it wrote state-after.txt has no delta to compute, and
+ * printing "no new changes" there would be a claim made out of missing data — the same
+ * mistake status.json's `tree_after: false` exists to prevent.
+ */
+function worktreeState(runDir) {
+  const hasSnapshots = ['state-before.txt', 'state-after.txt'].every((f) =>
+    fs.existsSync(path.join(runDir, f)),
+  );
+  if (!hasSnapshots) return 'unknown — the run left no worktree snapshot, check git status';
+  const { work } = runChanges(runDir);
+  return work.length
+    ? `has unfinished changes (${work.length}): ${line(work.slice(0, 3).join(', '), 120)}`
+    : 'no new changes';
+}
+
 export function limitReply(ctx, meta) {
   const rows = [
     'LIMIT — ChatGPT quota exhausted, work not completed',

package/src/meta/verdict.mjs

@@ -22,6 +22,7 @@ import {
 } from './paths.mjs';
 import { chainBaseline } from './chain.mjs';
 import { splitRunChanges } from './environment.mjs';
+import { outcomeGap } from './outcome.mjs';
 
 /**
  * Quota exhaustion is a transport error, not a word. Both markers must sit on the same
@@ -306,6 +307,13 @@ export function resolveStatus({ log, logBytes, resultOk, exit, agent, result, ru
       reason: `verification “${line(result.verify_command || 'no command', 60)}” failed; changes remain in the tree`,
     };
   }
+  // What the executor says about its own work, after verification and ahead of scope: work
+  // that was never done matters more than where it was not done. Only runs whose schema.json
+  // demanded the field are judged by it — see outcome.mjs.
+  if (agent === 'codex-build') {
+    const declared = outcomeGap(runDir, result);
+    if (declared) return { status: 'FAIL', reason: declared };
+  }
   // Answers that never arrived, or arrived as coordinates. Scout-only, and per-question
   // only when questions.json is absent — see scoutCoverageGap().
   if (agent === 'codex-scout') {

package/src/required-inputs.mjs

@@ -0,0 +1,104 @@
+/**
+ * Defines the inputs the orchestrator must give each Codex dispatcher.
+ *
+ * This contract belongs beside the gate because the dispatcher prompt was the only place that
+ * named order id and scope, so the caller launched codex-build without either value and the
+ * runner refused the call before Codex could do any work. Pass 2 can render the same entries
+ * into agent instructions without creating a second list that can drift.
+ */
+
+const PLACEHOLDER_VALUES = new Set(['todo', 'tbd', 'label', 'none', 'order id', 'scope', 'xxx']);
+
+const freezeEntries = (entries) => Object.freeze(entries.map((entry) => Object.freeze(entry)));
+
+export const REQUIRED_INPUTS = Object.freeze({
+  'codex-scout': freezeEntries([
+    {
+      label: 'order id',
+      source: 'the orchestrator',
+      explanation: 'The label this order is known by. Repeating a call with the same label joins the run already in flight and costs no quota; a different piece of work needs a new label, never a reused one.',
+      example: 'plan-13-scout-20260804',
+    },
+  ]),
+  'codex-build': freezeEntries([
+    {
+      label: 'order id',
+      source: 'the orchestrator',
+      explanation: 'The label this order is known by. Repeating a call with the same label joins the run already in flight and costs no quota; a different piece of work needs a new label, never a reused one.',
+      example: 'plan-13-build-20260804',
+    },
+    {
+      label: 'scope',
+      source: 'the orchestrator',
+      explanation: 'Comma-separated globs relative to the repository root, listing every file the run may touch — including each caller of what changes, not only the file being edited. Anything outside the list fails the run.',
+      example: 'src/runner/**,tests/runner/**',
+    },
+  ]),
+  'codex-review': freezeEntries([
+    {
+      label: 'order id',
+      source: 'the orchestrator',
+      explanation: 'The label this order is known by. Repeating a call with the same label joins the run already in flight and costs no quota; a different piece of work needs a new label, never a reused one.',
+      example: 'plan-13-review-20260804',
+    },
+  ]),
+});
+
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+function cleanValue(value) {
+  if (typeof value !== 'string') return '';
+  return value.trim().replace(/^([`'\"])(.*)\1$/, '$2').trim();
+}
+
+function isPlaceholder(value) {
+  const cleaned = cleanValue(value);
+  if (!cleaned) return true;
+  if (cleaned.startsWith('<') && cleaned.endsWith('>')) return true;
+  return PLACEHOLDER_VALUES.has(cleaned.replace(/[.,;:]+$/, '').trim().toLowerCase());
+}
+
+function extractValue(promptText, label) {
+  const labelPattern = escapeRegExp(label).replaceAll('\\ ', '\\s+');
+  const flag = `--${label.replaceAll(/\s+/g, '-')}`;
+  const direct = new RegExp(
+    `(?:^|\\r?\\n)\\s*(?:[-*]\\s*)?(?:[*_` + '`' + `]?${labelPattern}[*_` + '`' + `]?)\\s*(?::|=|—|-)\\s*([^\\r\\n]*)`,
+    'im',
+  );
+  const directMatch = promptText.match(direct);
+  if (directMatch) return cleanValue(directMatch[1]);
+
+  const flagPattern = new RegExp(
+    `${escapeRegExp(flag)}(?:=|\\s+)(?:"([^"]*)"|'([^']*)'|([^\\s\\r\\n]+))`,
+    'i',
+  );
+  const flagMatch = promptText.match(flagPattern);
+  if (!flagMatch) return null;
+  return cleanValue(flagMatch[1] ?? flagMatch[2] ?? flagMatch[3]);
+}
+
+/** Returns the immutable input entries for one dispatcher type. */
+export function requiredInputsFor(agentType) {
+  return REQUIRED_INPUTS[agentType] || [];
+}
+
+/** Returns required entries whose value is absent or is still an obvious template placeholder. */
+export function missingInputs(agentType, promptText) {
+  const prompt = typeof promptText === 'string' ? promptText : '';
+  return requiredInputsFor(agentType).filter((entry) => isPlaceholder(extractValue(prompt, entry.label)));
+}
+
+/** Renders the compact contract the orchestrator sees while choosing a dispatcher. */
+export function renderRequiredInputSummary(agentType) {
+  const entries = requiredInputsFor(agentType);
+  if (!entries.length) return '';
+  const labels = entries.map((entry) => `\`${entry.label}\``);
+  return `Requires ${entries[0].source}-provided ${labels.join(' and ')}.`;
+}
+
+/** Renders the same contract for pass 2 agent instructions. */
+export function renderRequiredInputs(agentType) {
+  return requiredInputsFor(agentType)
+    .map((entry) => `- ${entry.label}: ${entry.explanation} Example: \`${entry.example}\`.`)
+    .join('\n');
+}

package/src/runner/args.mjs

@@ -8,12 +8,17 @@
 import path from 'node:path';
 import { AGENTS } from '../write-meta.mjs';
 import { ALLOWED_EFFORTS } from '../run-config.mjs';
+import { requiredInputsFor } from '../required-inputs.mjs';
 
 export function die(message) {
   console.error(`run-codex: ${message}`);
   process.exit(2);
 }
 
+function requiredInput(agentType, label) {
+  return requiredInputsFor(agentType).find((entry) => entry.label === label);
+}
+
 // Flags that carry no value. A value is accepted only in its explicit yes/no spellings;
 // anything else stops the run. The permissive reading this replaces — "not 0/false/no means
 // yes" — turned the prompt's own placeholder text (`--continue "<only if the orchestrator provided
@@ -63,10 +68,12 @@ export function parseArgs(argv) {
   if (!AGENTS[opts.agent]) die(`unknown --agent ${opts.agent}`);
   opts.orderId = String(opts['order-id'] ?? '').trim();
   if (!opts.orderId) {
+    const orderInput = requiredInput(opts.agent, 'order id');
     die(
-      '--order-id is required: the orchestrator issues the order label and the runner will not invent one. ' +
+      `--order-id is required: ${orderInput.source} supplies the ${orderInput.label}; the runner will not invent one. ` +
         'A repeat of the same order should come back with --continue. If this appeared right after a package update, ' +
-        'the installed dispatcher prompts are stale and need npm run dev:install (local dev) or codex-bridge update.',
+        'the installed dispatcher prompts are stale and need npm run dev:install (local dev) or codex-bridge update. ' +
+        `Example: --order-id "${orderInput.example}". Action: get the value from ${orderInput.source}, pass it as --order-id, and retry.`,
     );
   }
   if (opts.agent === 'codex-scout') {
@@ -101,10 +108,11 @@ export function parseArgs(argv) {
     .map((p) => p.trim())
     .filter(Boolean);
   if (opts.agent === 'codex-build' && !opts.scopePatterns.length) {
+    const scopeInput = requiredInput(opts.agent, 'scope');
     die(
-      '--scope is required for codex-build: comma-separated globs relative to the repo root, ' +
-        'e.g. --scope "packages/event-calendar/**,apps/orchestrator/src/maestro/calendar-refresh.ts". ' +
-        'Anything outside the list is off limits and fails the run.',
+      `--scope is required for codex-build: ${scopeInput.source} supplies the ${scopeInput.label}. ` +
+        `${scopeInput.explanation} Example: --scope "${scopeInput.example}". ` +
+        `Action: get the value from ${scopeInput.source}, pass it as --scope, and retry.`,
     );
   }
   return opts;

package/src/runner/prompts.mjs

@@ -52,6 +52,15 @@ Working rules:
   cannot be done, do not pretend it is done; list it in leftovers.
 - After making changes, run verification: ${opts.verify || 'determine the command from the project'}.
   Put the command actually run in verify_command and whether it passed in verify_passed.
+- Declare the outcome in outcome: "done" if the work the task asked for was carried out,
+  "fail" if it was not — for any reason at all, including an impossible order, a file that
+  does not exist, a scope that forbids the only fix, or running out of time. "done" with an
+  empty changes[] is correct only when the task asked you to check something and nothing
+  needed changing; if you could not do what was asked, "fail" is the answer even when the
+  worktree is clean and verification is green. This is not a self-grade: work that was done
+  and merely leaves follow-ups is "done" with the follow-ups in leftovers, and partial work
+  that satisfies the definition of done is "done" too. On "fail" the first sentence of summary
+  states the reason — it is what the orchestrator is shown.
 - summary and changes describe only changes in this repository for this task. Do not include
   anything unrelated in them.
 - Each change is a separate changes[] entry, exactly one file per entry. The file field contains

package/src/runner/schemas.mjs

@@ -51,8 +51,30 @@ const BUILD_SCHEMA = {
   $schema: 'https://json-schema.org/draft/2020-12/schema',
   type: 'object',
   additionalProperties: false,
-  required: ['summary', 'changes', 'verify_command', 'verify_passed', 'leftovers', 'report_markdown'],
+  required: [
+    'outcome',
+    'summary',
+    'changes',
+    'verify_command',
+    'verify_passed',
+    'leftovers',
+    'report_markdown',
+  ],
   properties: {
+    // The outcome is declared, never inferred. On 2026-08-04 a build asked to fix a function
+    // in a module that does not exist answered `OK — no code change was made`: every artifact
+    // was well-formed, the tree was legitimately clean, and the runner has no way to know
+    // whether the order required an edit. A string rather than a boolean because the set of
+    // outcomes will grow (`blocked` is a candidate) and an enum extends without breaking the
+    // contract. Presence of this field in the run's own schema.json is also the marker that
+    // says the run was contracted to declare an outcome — see meta/outcome.mjs.
+    outcome: {
+      type: 'string',
+      enum: ['done', 'fail'],
+      description:
+        'done — the work the task asked for was carried out. fail — it was not, for any ' +
+        'reason at all (impossible order, missing file, blocked by scope, out of time).',
+    },
     summary: { type: 'string', minLength: 1 },
     changes: {
       type: 'array',