@lyupro/codex-bridge 0.6.5 → 0.6.7

package/src/home/hooks/reply-guard.mjs

@@ -21,18 +21,23 @@
  * argument about the SHAPE of the reply can loop forever and eventually steps aside, an
  * argument about EXTERNAL run state cannot be argued away by the model and ends the turn
  * with `continue: false` instead of a silent pass. See MAX_FORM_BLOCKS / MAX_STATE_BLOCKS.
+ * In the handback era, SubagentHandback delivers the caller-visible answer before SubagentStop.
+ * Plan_62 makes this hook yield after delivery and audit every transcript tool call against gate receipts.
  *
  * Input is JSON on stdin. The fields used here (`agent_type`, `last_assistant_message`)
- * come from Claude Code; the last payload is kept in logs/codex-reply-guard.last.json so
- * the contract stays inspectable if it ever changes shape.
+ * come from Claude Code; the last payload is kept in state/diagnostics/reply-guard.last.json
+ * so the contract stays inspectable if it ever changes shape.
  */
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { AGENTS } from '../lib/agents.mjs';
+import { BRAND_STATE_DIR } from '../lib/brand-home.mjs';
 import { runOrderMismatch, transcriptOrderId } from '../lib/dispatcher-order.mjs';
+import { decideDispatcherStop, transcriptToolUses } from '../lib/dispatcher-stop.mjs';
 import { recognizeHostRefusal } from '../lib/host-refusal.mjs';
 import { readJsonFileSync } from '../lib/json-file.mjs';
+import { readDispatcherState, updateDispatcherState } from '../lib/dispatcher-state.mjs';
+import { hostSdkVersion, recordHandbackWitness } from '../lib/handback-witness.mjs';
 import { runLiveness } from '../lib/meta/run-liveness.mjs';
 import { resolveProjectRunsDir } from '../lib/runner/project-dir.mjs';
 import { runsRoot } from '../lib/runner/runs-root.mjs';
@@ -44,6 +49,7 @@ import {
   abandonedRunStop,
   deadRunReason,
   deadRunStop,
+  handbackDemandReason,
   liveRunReason,
   liveRunStop,
   missingDiscoveredMetaStop,
@@ -65,8 +71,6 @@ import {
 // Plan_46's first invariant recognizes only direct expressions such as
 // blockForm('Contract violated: run codex-bridge run and return its stdout verbatim.');
 // The broader hook-directory scan protects the extracted verdict text from the same incident.
-const HOME = os.homedir();
-const LOG_DIR = path.join(HOME, '.claude', 'logs');
 const GUARDED = new Set(Object.keys(AGENTS));
 
 /**
@@ -91,7 +95,13 @@ const GUARDED = new Set(Object.keys(AGENTS));
  * worktree was busy.
  */
 /** Never let a guard failure break real work: on any doubt, stay silent. */
-const pass = () => process.exit(0);
+let dispatcherSystemMessage = null;
+const pass = () => {
+  if (dispatcherSystemMessage) {
+    process.stdout.write(JSON.stringify({ systemMessage: dispatcherSystemMessage }));
+  }
+  process.exit(0);
+};
 
 let input;
 try {
@@ -101,8 +111,9 @@ try {
 }
 
 try {
-  fs.mkdirSync(LOG_DIR, { recursive: true });
-  fs.writeFileSync(path.join(LOG_DIR, 'codex-reply-guard.last.json'), `${JSON.stringify(input, null, 2)}\n`);
+  const diagnosticsDir = path.join(BRAND_STATE_DIR, 'diagnostics');
+  fs.mkdirSync(diagnosticsDir, { recursive: true });
+  fs.writeFileSync(path.join(diagnosticsDir, 'reply-guard.last.json'), `${JSON.stringify(input, null, 2)}\n`);
 } catch {
   // Diagnostics are a convenience, never a reason to fail the turn.
 }
@@ -112,10 +123,59 @@ try {
 // unrelated one, which cost a re-answer for nothing.
 if (!GUARDED.has(input.agent_type)) pass();
 
+const emitStop = (payload) => {
+  process.stdout.write(JSON.stringify(payload));
+  process.exit(0);
+};
+try {
+  if (typeof input.session_id === 'string' && input.session_id.length > 0
+    && typeof input.agent_id === 'string' && input.agent_id.length > 0) {
+    const ids = {
+      stateDir: BRAND_STATE_DIR,
+      sessionId: input.session_id,
+      agentId: input.agent_id,
+    };
+    const state = readDispatcherState(ids);
+    const toolUses = transcriptToolUses(input.agent_transcript_path);
+    const stop = decideDispatcherStop({ state, toolUses });
+    if (stop.unseen.length) {
+      const names = stop.unseen.map((toolUse) => toolUse.name).join(', ');
+      dispatcherSystemMessage = `codex-bridge: dispatcher ${input.agent_type} used ${names} outside the dispatcher gate — do not trust its answer; run codex-bridge doctor.`;
+      await recordHandbackWitness({
+        stateDir: BRAND_STATE_DIR,
+        kind: 'alarm',
+        sdkVersion: hostSdkVersion(),
+        detail: `${input.agent_type} ${input.agent_id}: ${names} outside the dispatcher gate`,
+      });
+    }
+    if (stop.stateUpdate) {
+      await updateDispatcherState(ids, (current) => ({
+        ...(current.corrupt ? {} : current),
+        ...stop.stateUpdate,
+      }));
+    }
+    if (stop.route === 'yield') {
+      if (dispatcherSystemMessage) emitStop({ systemMessage: dispatcherSystemMessage });
+      pass();
+    }
+    if (stop.route === 'demand') {
+      emitStop({
+        decision: 'block',
+        reason: handbackDemandReason,
+        ...(dispatcherSystemMessage ? { systemMessage: dispatcherSystemMessage } : {}),
+      });
+    }
+  }
+} catch {
+  // The handback path is fail-open; the established reply checks remain the fallback.
+}
+
 const reply = String(input.last_assistant_message || '').trim();
 if (!reply) pass();
 const emit = (payload) => {
-  process.stdout.write(JSON.stringify(payload));
+  process.stdout.write(JSON.stringify(
+    dispatcherSystemMessage ? { ...payload, systemMessage: dispatcherSystemMessage } : payload,
+  ));
   process.exit(0);
 };
 /** Wrong shape of reply: three tries, then the reply goes through as it always has. */
@@ -166,7 +226,12 @@ if (!runDir) {
   let candidates;
   try {
     searchedRunsDir = resolveProjectRunsDir(runsRoot(), input.cwd, { create: false }).dir;
-    candidates = recentRuns(searchedRunsDir, { agent: input.agent_type });
+    // Plan_62 r2: on 2026-09-24 the newest run of this agent type belonged to an earlier order, and the
+    // guard judged the reply against that stranger's folder. With the order id known, only its runs count.
+    candidates = recentRuns(searchedRunsDir, {
+      agent: input.agent_type,
+      ...(orderedOrderId ? { orderId: orderedOrderId } : {}),
+    });
   } catch {
     pass();
   }

package/src/home/hooks/reply-verdicts.mjs

@@ -57,6 +57,11 @@ export const missingRunReason =
   'confirmed. Run codex-bridge run and return its stdout verbatim. If the runner refused before ' +
   'creating a folder, return that refusal exactly as printed.';
 
+export const handbackDemandReason =
+  'Hand your answer back now through SubagentHandback. If the dispatcher gate refuses the handback, run ' +
+  'exactly the command its refusal quotes and hand back again; the gate replaces the message with the ' +
+  "runner's output.";
+
 export const noRecentRunReason =
   'Contract violated: the response has no RUN= or ATTACH= line, and no recent run for this ' +
   'dispatcher was found on disk. Run codex-bridge run and return its stdout verbatim; your own ' +

package/src/home/hooks/worktree-lock.mjs

@@ -1,44 +1,44 @@
-#!/usr/bin/env node
-/**
- * PreToolUse lock for file tools and plainly recognisable shell writes in the Claude Code host.
- *
- * A live codex-build runner snapshots its repository before and after editing. Letting the
- * orchestrator write during that window folds unrelated work into the runner's result, exactly
- * as the 2026-08-05 incident did. This hook denies only a recognised file path inside a live
- * build run's repository; every malformed or unreadable input passes so diagnostics never break
- * unrelated host work.
- */
-import fs from 'node:fs';
-import path from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { formatSilence, heartbeatAge } from '../lib/heartbeat.mjs';
-import { SHELL_TOOLS, WRITE_TOOLS } from '../lib/hook-definitions.mjs';
-import { runsRoot } from '../lib/runner/runs-root.mjs';
-import { allLiveRuns, normalizePath } from './live-runs.mjs';
-import { shellWriteIntent } from './shell-write-intent.mjs';
-
-const WRITE_TOOL_NAMES = new Set(WRITE_TOOLS);
-const SHELL_TOOL_NAMES = new Set(SHELL_TOOLS);
-const pass = () => process.exit(0);
-
-let input;
-try {
-  input = JSON.parse(fs.readFileSync(0, 'utf8'));
-} catch {
-  pass();
-}
-
-if (!input || typeof input !== 'object' || Array.isArray(input)) pass();
-if (!WRITE_TOOL_NAMES.has(input.tool_name) && !SHELL_TOOL_NAMES.has(input.tool_name)) pass();
-
-const toolInput = input.tool_input;
-if (!toolInput || typeof toolInput !== 'object' || Array.isArray(toolInput)) pass();
-let rawPaths;
-if (WRITE_TOOL_NAMES.has(input.tool_name)) {
-  const pathField = input.tool_name === 'NotebookEdit' ? 'notebook_path' : 'file_path';
-  const rawPath = toolInput[pathField];
-  if (typeof rawPath !== 'string' || !rawPath.trim()) pass();
-  rawPaths = [rawPath];
+#!/usr/bin/env node
+/**
+ * PreToolUse lock for file tools and plainly recognisable shell writes in the Claude Code host.
+ *
+ * A live codex-build runner snapshots its repository before and after editing. Letting the
+ * orchestrator write during that window folds unrelated work into the runner's result, exactly
+ * as the 2026-08-05 incident did. This hook denies only a recognised file path inside a live
+ * build run's repository; every malformed or unreadable input passes so diagnostics never break
+ * unrelated host work.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { formatSilence, heartbeatAge } from '../lib/heartbeat.mjs';
+import { SHELL_TOOLS, WRITE_TOOLS } from '../lib/hook-definitions.mjs';
+import { runsRoot } from '../lib/runner/runs-root.mjs';
+import { allLiveRuns, normalizePath } from './live-runs.mjs';
+import { shellWriteIntent } from './shell-write-intent.mjs';
+
+const WRITE_TOOL_NAMES = new Set(WRITE_TOOLS);
+const SHELL_TOOL_NAMES = new Set(SHELL_TOOLS);
+const pass = () => process.exit(0);
+
+let input;
+try {
+  input = JSON.parse(fs.readFileSync(0, 'utf8'));
+} catch {
+  pass();
+}
+
+if (!input || typeof input !== 'object' || Array.isArray(input)) pass();
+if (!WRITE_TOOL_NAMES.has(input.tool_name) && !SHELL_TOOL_NAMES.has(input.tool_name)) pass();
+
+const toolInput = input.tool_input;
+if (!toolInput || typeof toolInput !== 'object' || Array.isArray(toolInput)) pass();
+let rawPaths;
+if (WRITE_TOOL_NAMES.has(input.tool_name)) {
+  const pathField = input.tool_name === 'NotebookEdit' ? 'notebook_path' : 'file_path';
+  const rawPath = toolInput[pathField];
+  if (typeof rawPath !== 'string' || !rawPath.trim()) pass();
+  rawPaths = [rawPath];
 } else {
   let intent;
   try {
@@ -48,69 +48,70 @@ if (WRITE_TOOL_NAMES.has(input.tool_name)) {
     // the scanner. Unrecognised input must fail open; the witness checks writes afterwards.
     pass();
   }
-  if (!intent.writes || !intent.paths.length) pass();
-  rawPaths = intent.paths;
-}
-
-let liveRuns;
-try {
-  liveRuns = allLiveRuns(runsRoot());
-} catch {
-  pass();
-}
-let match;
-for (const rawPath of rawPaths) {
-  let targetPath;
-  try {
-    if (path.isAbsolute(rawPath)) targetPath = rawPath;
-    else if (typeof input.cwd === 'string' && input.cwd.trim()) targetPath = path.resolve(input.cwd, rawPath);
-    else continue;
-  } catch {
-    continue;
-  }
-  const target = normalizePath(targetPath);
-  if (!target) continue;
-  const owner = liveRuns.find(({ status }) => {
-    if (status.agent !== 'codex-build') return false;
-    const repository = normalizePath(status.repo);
-    return Boolean(repository) && (target === repository || target.startsWith(`${repository}/`));
-  });
-  if (owner) {
-    match = { owner, targetPath };
-    break;
-  }
-}
-if (!match) pass();
-
-const { status, dir } = match.owner;
-// A run is only ever failed for what `git status --porcelain` reports, and an ignored path never
-// appears there — the witness that grades a run does not see it either. Meanwhile the working
-// order for a live run is to touch exactly those files: plans and checklists live in ignored
-// folders. On 2026-08-23 this guard refused four such edits in five minutes, which is worse than
-// a miss: a miss has the witness behind it, a false refusal has nothing and reads as a broken
-// tool. Only a proven `ignored` passes — anything else (not a repository, git absent, any other
-// error) keeps the refusal, because "no proof it is ignored" is not "proof it is harmless".
-const repository = normalizePath(status.repo);
-const target = normalizePath(match.targetPath);
-const gitMetadata = target === `${repository}/.git` || target.startsWith(`${repository}/.git/`);
-if (!gitMetadata) {
-  const ignored = spawnSync('git', ['-C', status.repo, 'check-ignore', '--quiet', '--', match.targetPath], {
-    stdio: 'ignore',
-  });
-  if (ignored.status === 0) pass();
-}
-process.stdout.write(JSON.stringify({
-  hookSpecificOutput: {
-    hookEventName: 'PreToolUse',
-    permissionDecision: 'deny',
-    permissionDecisionReason: `Worktree lock denied ${input.tool_name}: ${match.targetPath} is inside repository `
-      + `${status.repo}, held by live run folder ${dir} (agent ${status.agent}, slug ${status.slug}). `
-      // "Working, last progress X ago" rather than "silent for X": this hook only ever denies a
-      // run whose heartbeat is still fresh — a stale one is not live here and the edit passes. The
-      // first live probe printed "silent for 10 seconds" next to a stop command on a perfectly
-      // healthy run, which reads as "it hung, kill it" and would cost the operator 20 minutes of
-      // work they meant to keep.
-      + `It is working; last progress ${formatSilence(heartbeatAge(dir))} ago. `
-      + `To take the repository back before it finishes: codex-bridge stop ${path.basename(dir)}.`,
-  },
-}));
+  if (!intent.writes || !intent.paths.length) pass();
+  rawPaths = intent.paths;
+}
+
+let liveRuns;
+try {
+  liveRuns = allLiveRuns(runsRoot());
+} catch {
+  pass();
+}
+let match;
+for (const rawPath of rawPaths) {
+  let targetPath;
+  try {
+    if (path.isAbsolute(rawPath)) targetPath = rawPath;
+    else if (typeof input.cwd === 'string' && input.cwd.trim()) targetPath = path.resolve(input.cwd, rawPath);
+    else continue;
+  } catch {
+    continue;
+  }
+  const target = normalizePath(targetPath);
+  if (!target) continue;
+  const owner = liveRuns.find(({ status }) => {
+    if (status.agent !== 'codex-build') return false;
+    const repository = normalizePath(status.repo);
+    return Boolean(repository) && (target === repository || target.startsWith(`${repository}/`));
+  });
+  if (owner) {
+    match = { owner, targetPath };
+    break;
+  }
+}
+if (!match) pass();
+
+const { status, dir } = match.owner;
+// A run is only ever failed for what `git status --porcelain` reports, and an ignored path never
+// appears there — the witness that grades a run does not see it either. Meanwhile the working
+// order for a live run is to touch exactly those files: plans and checklists live in ignored
+// folders. On 2026-08-23 this guard refused four such edits in five minutes, which is worse than
+// a miss: a miss has the witness behind it, a false refusal has nothing and reads as a broken
+// tool. Only a proven `ignored` passes — anything else (not a repository, git absent, any other
+// error) keeps the refusal, because "no proof it is ignored" is not "proof it is harmless".
+const repository = normalizePath(status.repo);
+const target = normalizePath(match.targetPath);
+const gitMetadata = target === `${repository}/.git` || target.startsWith(`${repository}/.git/`);
+if (!gitMetadata) {
+  const ignored = spawnSync('git', ['-C', status.repo, 'check-ignore', '--quiet', '--', match.targetPath], {
+    stdio: 'ignore',
+    windowsHide: true,
+  });
+  if (ignored.status === 0) pass();
+}
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: 'PreToolUse',
+    permissionDecision: 'deny',
+    permissionDecisionReason: `Worktree lock denied ${input.tool_name}: ${match.targetPath} is inside repository `
+      + `${status.repo}, held by live run folder ${dir} (agent ${status.agent}, slug ${status.slug}). `
+      // "Working, last progress X ago" rather than "silent for X": this hook only ever denies a
+      // run whose heartbeat is still fresh — a stale one is not live here and the edit passes. The
+      // first live probe printed "silent for 10 seconds" next to a stop command on a perfectly
+      // healthy run, which reads as "it hung, kill it" and would cost the operator 20 minutes of
+      // work they meant to keep.
+      + `It is working; last progress ${formatSilence(heartbeatAge(dir))} ago. `
+      + `To take the repository back before it finishes: codex-bridge stop ${path.basename(dir)}.`,
+  },
+}));

package/src/home/lib/atomic-json.mjs

@@ -0,0 +1,21 @@
+/**
+ * Publishes a JSON record whole or not at all: a temporary file in the target's directory renamed over it.
+ *
+ * Plan_62 B2 wrote this twice, once per state module; two copies of one write discipline drift apart the
+ * first time either is fixed. Callers hold their own lock — this does not serialize concurrent writers
+ * (`config-edit.mjs` keeps its own compare-and-swap publish for that reason).
+ */
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function writeJsonAtomic(file, record) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, `${JSON.stringify(record, null, 2)}\n`, { flag: 'wx' });
+    fs.renameSync(temporary, file);
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
+}

package/src/home/lib/brand-home.mjs

@@ -15,6 +15,10 @@
 import os from 'node:os';
 import path from 'node:path';
 
+export function brandStateDir(root) {
+  return path.join(root, 'state');
+}
+
 export function resolveBrandHome({ homedir = os.homedir(), env = process.env } = {}) {
   const overridden = Boolean(env.CODEX_BRIDGE_HOME);
   const root = path.resolve(
@@ -23,6 +27,7 @@ export function resolveBrandHome({ homedir = os.homedir(), env = process.env } =
   return {
     root,
     source: overridden ? 'CODEX_BRIDGE_HOME' : 'default',
+    stateDir: brandStateDir(root),
     configPath: path.join(root, 'config.json'),
     conventionsPath: path.join(root, 'conventions.md'),
   };
@@ -35,5 +40,6 @@ export function resolveBrandHome({ homedir = os.homedir(), env = process.env } =
  * environment after import, which would not be seen here.
  */
 export const BRAND_HOME = resolveBrandHome();
+export const BRAND_STATE_DIR = BRAND_HOME.stateDir;
 export const BRAND_CONFIG_PATH = BRAND_HOME.configPath;
 export const BRAND_CONVENTIONS_PATH = BRAND_HOME.conventionsPath;

package/src/home/lib/dispatcher-command.mjs

@@ -0,0 +1,79 @@
+/** Owns the canonical dispatcher command because the 2026-09-23 TradeForge and 2026-09-24 local incidents let haiku ignore its prompt and register two paid runs for one order id. */
+import { CLI_NAMES } from './cli-names.mjs';
+import {
+  extractValue,
+  isAbsoluteTaskFilePath,
+  isInputPlaceholder,
+  parseContinuationGrant,
+  REQUIRED_INPUTS,
+} from './required-inputs.mjs';
+import { firstShellUnsafeSequence } from './shell-unsafe.mjs';
+
+function refusal(reason) {
+  return { refusal: `Refused: ${reason}.` };
+}
+
+function unsafeValueReason(value, label) {
+  const sequence = firstShellUnsafeSequence(value);
+  if (sequence !== null) return `input "${label}" contains unsafe shell sequence ${JSON.stringify(sequence)}`;
+  if (value.includes('"') || value.includes('\r') || value.includes('\n')) {
+    return `input "${label}" contains a double quote or line break`;
+  }
+  return null;
+}
+
+function quote(value) {
+  return `"${value}"`;
+}
+
+/** Builds the only permitted run command directly from the immutable order transcript. */
+export function canonicalRunCommand(agentType, promptText) {
+  if (typeof agentType !== 'string' || !Object.prototype.hasOwnProperty.call(REQUIRED_INPUTS, agentType)) {
+    return refusal(`unknown dispatcher agent ${JSON.stringify(agentType)}`);
+  }
+  if (typeof promptText !== 'string') return refusal('prompt text is missing or is not text');
+
+  const inputs = new Map();
+  for (const entry of REQUIRED_INPUTS[agentType]) {
+    if (entry.conditional) continue;
+    const value = extractValue(promptText, entry.label);
+    if (isInputPlaceholder(value, entry.label)) {
+      return refusal(`required input "${entry.label}" is missing or is a placeholder`);
+    }
+    const unsafe = unsafeValueReason(value, entry.label);
+    if (unsafe) return refusal(unsafe);
+    if (entry.label === 'task file' && !isAbsoluteTaskFilePath(value)) {
+      return refusal('input "task file" must be an absolute path');
+    }
+    inputs.set(entry.label, value);
+  }
+
+  // The continuation grant never reaches the command line (`--continue` is bare), so its free-text
+  // reason is not screened: the live grant "…five risks; advise settles them" would have been refused.
+  const optionalLabels = ['repository', 'scope new', 'slug', 'effort'];
+  for (const label of optionalLabels) {
+    const value = extractValue(promptText, label);
+    if (value === null) continue;
+    const unsafe = unsafeValueReason(value, label);
+    if (unsafe) return refusal(unsafe);
+    inputs.set(label, value);
+  }
+
+  const tokens = [CLI_NAMES[0], 'run', '--agent', agentType, '--repo', quote(inputs.get('repository') || '.')];
+  if (agentType === 'codex-advisor') tokens.push('--phase', quote(inputs.get('phase')));
+  if (agentType === 'codex-build') {
+    tokens.push('--scope', quote(inputs.get('scope')));
+    if (inputs.get('scope new')) tokens.push('--scope-new', quote(inputs.get('scope new')));
+  }
+  if (inputs.get('slug')) tokens.push('--slug', quote(inputs.get('slug')));
+  tokens.push('--order-id', quote(inputs.get('order id')));
+  tokens.push('--task-file', quote(inputs.get('task file')));
+  if (inputs.get('effort')) tokens.push('--effort', quote(inputs.get('effort')));
+  if (parseContinuationGrant(promptText)) tokens.push('--continue');
+  return { command: tokens.join(' ') };
+}
+
+/** Compares the proposed command as text, allowing whitespace only around its boundary. */
+export function sameCommand(candidate, canonical) {
+  return typeof candidate === 'string' && typeof canonical === 'string' && candidate.trim() === canonical;
+}

package/src/home/lib/dispatcher-gate.mjs

@@ -0,0 +1,95 @@
+/** Holds dispatchers to the ordered runner because the 2026-09-23 TradeForge incident let one write and hand back without running it. */
+import { canonicalRunCommand, sameCommand } from './dispatcher-command.mjs';
+import { ownTranscriptPath, transcriptPrompt } from './dispatcher-order.mjs';
+import { HANDBACK_TOOL } from './hook-definitions.mjs';
+
+export { HANDBACK_TOOL };
+
+export function gateOrder(payload) {
+  const transcriptPath = ownTranscriptPath(payload);
+  const prompt = transcriptPath ? transcriptPrompt(transcriptPath) : null;
+  if (!transcriptPath || !prompt) {
+    return {
+      refusal: `the order could not be read from the agent transcript ${transcriptPath || '(none)'}`,
+    };
+  }
+  return canonicalRunCommand(payload.agent_type, prompt);
+}
+
+export function runnerOutput(payload) {
+  if (payload?.hook_event_name === 'PostToolUse') {
+    const output = payload.tool_response?.stdout;
+    return typeof output === 'string' && output.length > 0 ? { output, exitCode: 0 } : null;
+  }
+  if (payload?.hook_event_name !== 'PostToolUseFailure' || typeof payload.error !== 'string'
+    || payload.error.length === 0) return null;
+
+  const newline = payload.error.indexOf('\n');
+  const firstLine = (newline < 0 ? payload.error : payload.error.slice(0, newline)).replace(/\r$/, '');
+  const match = /^Exit code (\d+)$/.exec(firstLine);
+  const output = match ? (newline < 0 ? '' : payload.error.slice(newline + 1)) : payload.error;
+  return output.length > 0 ? { output, exitCode: match ? Number(match[1]) : null } : null;
+}
+
+export function isFinalOutput(output) {
+  return !output.split(/\r?\n/).some((line) => line.startsWith('STARTED '));
+}
+
+function denial(message, order) {
+  const prefix = `codex-bridge dispatcher gate: ${message}`;
+  if (typeof order?.command !== 'string' || order.command.length === 0) return prefix;
+  return `${prefix}\n${order.command}\nRun it exactly, in the foreground; repeating it attaches to the same run.`;
+}
+
+function deny(message, order, stateUpdate) {
+  const decision = { kind: 'deny', reason: denial(message, order) };
+  if (stateUpdate) decision.stateUpdate = stateUpdate;
+  return decision;
+}
+
+function allow(message) {
+  return { kind: 'allow', message, stateUpdate: { handback: 'delivered' } };
+}
+
+export function decidePreToolUse({ payload, order, state }) {
+  const toolName = payload?.tool_name;
+  // Once the caller holds the answer, the dispatcher is finished. On 2026-09-23 the real run was started
+  // after the handback and wrote into a tree the caller believed settled; a substituted FAIL followed by a
+  // late run would repeat exactly that, so nothing — not even the canonical command — runs past delivery.
+  if (state?.handback === 'delivered') {
+    return deny('the handback was already delivered; this dispatcher is finished and may not act further.');
+  }
+  if (toolName === 'Bash') {
+    if (order?.refusal) {
+      return deny('the order could not be read; nothing may run, so hand back now.', order);
+    }
+    if (order?.command && sameCommand(payload.tool_input?.command, order.command)
+      && payload.tool_input?.run_in_background !== true) return { kind: 'pass' };
+    return deny('only the canonical runner command may run in the foreground.', order);
+  }
+
+  if (toolName === HANDBACK_TOOL) {
+    if (order?.refusal) return allow(`FAIL — dispatcher gate: ${order.refusal}`);
+    if (typeof state?.runnerOutput === 'string' && state.runnerOutput.length > 0) {
+      if (state.runnerFinal) return allow(state.runnerOutput);
+      return deny('the run has started without a verdict; repeat the exact command to attach and wait.', order);
+    }
+
+    const attempts = Number.isInteger(state?.handbackAttempts) ? state.handbackAttempts : 0;
+    const handbackAttempts = attempts + 1;
+    if (handbackAttempts === 1) {
+      return deny('the dispatcher handed back without a runner verdict; run the command first.', order,
+        { handbackAttempts });
+    }
+    return {
+      kind: 'allow',
+      message: 'FAIL — dispatcher did not delegate: it handed back without running `' + order.command + '`',
+      stateUpdate: { handbackAttempts, handback: 'delivered' },
+    };
+  }
+
+  if (order?.refusal) {
+    return deny('the order could not be read; nothing may run, so hand back now.', order);
+  }
+  return deny('only the canonical runner command may run before handback.', order);
+}