@lyupro/codex-bridge 0.3.1 → 0.5.0

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, не этот. {{CODEX_REQUIRED_INPUTS_SUMMARY}}
+description: Имплементация ВНЕ подписки Claude — правки кода, новые модули, рефакторинг по образцу, починка тестов. Работу выполняет Codex CLI (подписка ChatGPT) с правом записи в репозиторий строго в пределах обязательного `scope`, Claude платит только за постановку задачи и ≤5 строк выжимки. Отчёт и полный лог кладёт в ~/.claude/codex-runs/, в чат — короткая выжимка + путь. Ревью и приёмку делает отдельный агент Claude, не этот. {{CODEX_REQUIRED_INPUTS_SUMMARY}} {{CODEX_STOP_SUMMARY}}
 model: haiku
 tools: Bash
 ---
@@ -28,20 +28,22 @@ job is to report the run status honestly, including failure.
 
 - 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 patterns are globs relative to the repository root. A pattern that matches nothing there is
+  refused before the run starts; a file this task is meant to create is declared with `--scope-new`.
 - 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 the `--continue` flag only when the orchestrator gave the matching `continue:`
-  grant explicitly; do not add or guess it yourself. A continuation is assigned by the
-  orchestrator, never chosen by you. After the verdict, return the exact attaching output and stop;
-  do not issue or invent another continuation. 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 `--continue` — before starting Codex, so no quota is spent. If the orchestrator did not
-  grant a repeat, return the runner's refusal exactly.
-- Optional: `effort: <none|minimal|low|medium|high|xhigh|max>`, `slug:`, `verify: <verification
-  command>` (for example `npm test`, `tsc --noEmit`).
+- `continue` — when the task text contains a line beginning with the `continue:` label, pass the
+  bare `--continue` flag even when its run name or reason looks malformed. Do not inspect, repair,
+  or swallow this grant; pass it through and let the runner issue the refusal. A continuation is
+  assigned by the orchestrator, never chosen by you. After the verdict, return the exact attaching
+  output and stop; do not issue or invent another continuation. If no such grant line is present,
+  the flag must not be present.
+- Optional: `effort: <none|minimal|low|medium|high|xhigh|max>`, `slug:` (by default, the slug is
+  taken from the order id), `verify: <verification command>` (for example `npm test`,
+  `tsc --noEmit`).
 
 ## The only thing you do
 
@@ -59,8 +61,10 @@ Add `--effort "<value>"` only when the orchestrator named a depth, and only with
 decides, which is the intended default — a placeholder copied from this template is refused before
 Codex starts.
 
-If the orchestrator gave the matching `continue:` grant, add the bare `--continue` flag to the
-command, with no value.
+If the task text contains a line beginning with the `continue:` label, add the bare `--continue`
+flag even when its run name or reason looks malformed. Do not inspect, repair, or swallow the line;
+the runner parses it and issues the refusal. If no such grant line is present, the flag must not be
+present in the command.
 No value
 is passed to it: the runner accepts only `1/true/yes/0/false/no`, while a placeholder string left in
 the
@@ -130,7 +134,7 @@ are designed for interactive work and cause harm in a delegated run — a failin
 and the task
 was not done; without them, 23k and the task was done. The flags affect one call; `~/.codex` is
 unchanged.
-The operator switches the mode through `/codex:env` (file `agents/codex/run-config.json`), and it
+The operator switches the mode through `/codex-bridge:env` (file `~/.lyupro/.codex-bridge/config.json`), and it
 is recorded in the run's `meta.json` — do not guess it or add flags yourself.
 `--dangerously-bypass-approvals-and-sandbox` is never used. `--model` is not
 passed: model IDs are volatile. The script fixes this once, so silent

package/src/agents/codex-review.md

@@ -1,6 +1,6 @@
 ---
 name: codex-review
-description: Независимое второе мнение по коду от другой модели — ревью незакоммиченных правок, ветки или коммита силами Codex CLI (подписка ChatGPT). Не заменяет приёмку на стороне Claude, а дополняет её взглядом со стороны. Выдаёт строгий JSON с severity и confidence по каждой находке, в чат — ≤5 строк со счётчиком по важности. {{CODEX_REQUIRED_INPUTS_SUMMARY}}
+description: Независимое второе мнение по коду от другой модели — ревью незакоммиченных правок, ветки или коммита силами Codex CLI (подписка ChatGPT). Не заменяет приёмку на стороне Claude, а дополняет её взглядом со стороны. Выдаёт строгий JSON с severity и confidence по каждой находке, в чат — ≤5 строк со счётчиком по важности. {{CODEX_REQUIRED_INPUTS_SUMMARY}} {{CODEX_STOP_SUMMARY}}
 model: haiku
 tools: Bash
 ---
@@ -27,17 +27,21 @@ 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.
+- Scope patterns are globs relative to the repository root. A pattern that matches nothing there is
+  refused before the run starts.
 - 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.
-- `continue` is conditional — pass the `--continue` flag only when the orchestrator gave the
-  matching `continue:` grant explicitly; do not add or guess it yourself. A continuation is
+- `continue` — when the task text contains a line beginning with the `continue:` label, pass the
+  bare `--continue` flag even when its run name or reason looks malformed. Do not inspect, repair,
+  or swallow this grant; pass it through and let the runner issue the refusal. A continuation is
   assigned by the orchestrator, never chosen by you. After the verdict, return the exact attaching
-  output and stop; do not issue or invent another continuation.
-- Optional: review focus as text ("look for races and error handling"), `slug:`, `effort:
-  <none|minimal|low|medium|high|xhigh|max>`.
+  output and stop; do not issue or invent another continuation. If no such grant line is present,
+  the flag must not be present.
+- Optional: review focus as text ("look for races and error handling"), `slug:` (by default, the
+  slug is taken from the order id), `effort: <none|minimal|low|medium|high|xhigh|max>`.
 
 ## The only thing you do
 
@@ -59,8 +63,10 @@ line. To get the verdict, run the **identical command a second time** — same `
 `--slug`, same flags. That second call does not start a second run and costs no quota: it attaches
 to the run already in flight, prints `ATTACH=<path>`, blocks until the verdict exists and prints it.
 
-If the orchestrator gave the matching `continue:` grant, add the bare `--continue` flag to the
-command, with no value. If it was not given, the flag must not be present in the command at all.
+If the task text contains a line beginning with the `continue:` label, add the bare `--continue`
+flag even when its run name or reason looks malformed. Do not inspect, repair, or swallow the line;
+the runner parses it and issues the refusal. If no such grant line is present, the flag must not be
+present in the command at all.
 
 Background execution (`run_in_background`, `&`, `nohup`) is prohibited. Interruption is no longer a
 problem worth handling: if the attaching call is killed by a time ceiling, repeat it — every repeat
@@ -112,7 +118,7 @@ properties that broke the contract.
 Regular `codex exec` follows the schema (verified during scouting), so the review uses it: with
 `--ignore-user-config` (structurally read-only, half the startup ballast), `--sandbox
 read-only`, `--disable hooks --disable plugins` (operator extensions do not affect the run;
-the default, switched through `/codex:env`), and without `--model` — model IDs are volatile. The
+the default, switched through `/codex-bridge:env`), and without `--model` — model IDs are volatile. The
 runner determines the review scope
 itself through git: the exact file list and diff command go into the prompt and are saved in the run
 folder's

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/, в чат — короткая выжимка + путь. {{CODEX_REQUIRED_INPUTS_SUMMARY}}
+description: Разведка и диагностика ВНЕ подписки Claude — исследование кодовой базы, поиск причины бага, ревью, сбор фактов. Работу выполняет Codex CLI (подписка ChatGPT), Claude платит только за постановку задачи и ≤5 строк выжимки. Строго read-only: писать в репозиторий физически не может. Подробный отчёт кладёт в ~/.claude/codex-runs/, в чат — короткая выжимка + путь. {{CODEX_REQUIRED_INPUTS_SUMMARY}} {{CODEX_STOP_SUMMARY}}
 model: haiku
 tools: Bash
 ---
@@ -23,8 +23,11 @@ files, do not run grep, do not retell the report, and do not reason about the ta
 
 - 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.
+- Scope patterns are globs relative to the repository root. A pattern that matches nothing there is
+  refused before the run starts.
 - Optional: `effort: <none|minimal|low|medium|high|xhigh|max>` — Codex reasoning depth.
-- Optional: `slug: <short-name>` for the run folder.
+- Optional: `slug: <short-name>` for the run folder; by default, the slug is taken from the order
+  id.
 - 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
@@ -34,12 +37,12 @@ files, do not run grep, do not retell the report, and do not reason about the ta
   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
   the flag and return its refusal verbatim.
-- `continue` — pass the `--continue` flag only when the orchestrator gave the matching `continue:`
-  grant explicitly; do not add or guess it yourself. A continuation is assigned by the
-  orchestrator, never chosen by you. After the verdict, return the exact attaching output and stop;
-  do not issue or invent another continuation. The contract is strict, like `--scope` in
-  codex-build: if this task (the same `slug` and the same repository) already had a run, the runner
-  will refuse to start without `--continue` — before starting Codex, so no quota is spent.
+- `continue` — when the task text contains a line beginning with the `continue:` label, pass the
+  bare `--continue` flag even when its run name or reason looks malformed. Do not inspect, repair,
+  or swallow this grant; pass it through and let the runner issue the refusal. A continuation is
+  assigned by the orchestrator, never chosen by you. After the verdict, return the exact attaching
+  output and stop; do not issue or invent another continuation. If no such grant line is present,
+  the flag must not be present.
 
 ## The only thing you do
 
@@ -60,8 +63,10 @@ Add `--effort "<value>"` only when the orchestrator named a depth, and only with
 decides, which is the intended default — a placeholder copied from this template is refused before
 Codex starts.
 
-If the orchestrator gave the matching `continue:` grant, add the bare `--continue` flag to the
-command, with no value.
+If the task text contains a line beginning with the `continue:` label, add the bare `--continue`
+flag even when its run name or reason looks malformed. Do not inspect, repair, or swallow the line;
+the runner parses it and issues the refusal. If no such grant line is present, the flag must not be
+present in the command.
 No value
 is passed to it: the runner accepts only `1/true/yes/0/false/no`, while a placeholder string left in
 the
@@ -117,7 +122,7 @@ The flags are proven, and they do not belong in the prompt: `--ignore-user-confi
 startup ballast (~9k quota instead of ~19k) and structurally blocks writing — no flags can override
 read-only; `--disable hooks --disable plugins` disable the operator's extensions for this call,
 so the run does not depend on what is installed in `~/.codex` today (the default, switched
-by the operator through `/codex:env`); `--model` is never passed because model IDs
+by the operator through `/codex-bridge:env`); `--model` is never passed because model IDs
 are volatile.
 The run is asynchronous, and waiting for it is a separate call. That is deliberate: while the start
 and the wait were one call, a time ceiling on that call looked exactly like a dead run, and the

package/src/commands/env.md

@@ -4,8 +4,8 @@ allowed-tools: Bash
 argument-hint: "[hooks|plugins on|off] | [reset]"
 ---
 
-<!-- Part of the agents/codex/ package. The file lives here out of necessity: the slash command name
-     is set by its location under commands/<namespace>/, and Claude Code understands neither
+<!-- Part of the agents/codex-bridge/ package. The file lives here out of necessity: the slash
+     command name is set by its location under commands/<namespace>/, and Claude Code understands neither
      symlinks nor pointer files (verified 2026-08-02). Edit it here; it travels as a copy when the
      package is installed. -->
 
@@ -30,8 +30,8 @@ Call forms:
 - `plugins on` / `plugins off` — the same for plugins;
 - `reset` — back to the default (both off).
 
-The state lives in `agents/codex/run-config.json` and lands in the `meta.json` of every run, so the
-artifacts always show which environment a run went through.
+The state lives in `~/.lyupro/.codex-bridge/config.json` and lands in the `meta.json` of every run,
+so the artifacts always show which environment a run went through.
 
 If the user turns `hooks` on, say in one line: while the failing `Stop` hook of `oh-my-codex` stays
 in `~/.codex/hooks.json`, runs will again spend quota on unrelated repairs. Checking the report

package/src/commands/usage.md

@@ -3,8 +3,8 @@ description: Show the ChatGPT quota spent on runs delegated to Codex — by day,
 allowed-tools: Bash
 ---
 
-<!-- Part of the agents/codex/ package. The file lives here out of necessity: the slash command name
-     is set by its location under commands/<namespace>/, and Claude Code understands neither
+<!-- Part of the agents/codex-bridge/ package. The file lives here out of necessity: the slash
+     command name is set by its location under commands/<namespace>/, and Claude Code understands neither
      symlinks nor pointer files (verified 2026-08-02). Edit it here; it travels as a copy when the
      package is installed. -->
 
@@ -44,14 +44,14 @@ for(const proj of fs.readdirSync(root)){
   try{repo=JSON.parse(fs.readFileSync(path.join(pdir,'.project.json'),'utf8')).repo||null}catch{}
   for(const run of fs.readdirSync(pdir)){
     const dir=path.join(pdir,run),meta=path.join(dir,'meta.json'),log=path.join(dir,'raw.log');
-    let tokens=null,agent=null,sandbox=null;
+    let tokens=null,agent=null,sandbox=null,runnerVersion=false;
     if(fs.existsSync(meta)){
-      try{const m=JSON.parse(fs.readFileSync(meta,'utf8'));tokens=m.tokens??null;agent=m.agent||null;sandbox=m.sandbox||null}catch{}
+      try{const m=JSON.parse(fs.readFileSync(meta,'utf8'));tokens=m.tokens??null;agent=m.agent||null;sandbox=m.sandbox||null;runnerVersion=Object.hasOwn(m,'runner_version')}catch{}
     } else if(fs.existsSync(log)){
       const hit=[...fs.readFileSync(log,'utf8').matchAll(/tokens used[\r\n]+([^\r\n]+)/g)].pop();
       tokens=hit?parseInt(hit[1].replace(/\D/g,''),10)||null:null;
     } else continue;
-    const entry={proj,repo,run,day:run.slice(0,10),agent:agent||(/review/.test(run)?'codex-review':/build/.test(run)?'codex-build':'codex-scout'),sandbox};
+    const entry={proj,repo,run,day:run.slice(0,10),agent:agent||(/review/.test(run)?'codex-review':/build/.test(run)?'codex-build':'codex-scout'),sandbox,runnerVersion};
     if(tokens===null){unknown.push(entry);continue}
     runs.push({...entry,tokens});
   }
@@ -63,7 +63,9 @@ const fmt=n=>n.toLocaleString('en-US');
 const row=(l,rs)=>'  '+String(l).padEnd(22)+String(rs.length).padStart(3)+' runs  '+fmt(sum(rs)).padStart(11)+'  average '+fmt(Math.round(sum(rs)/rs.length));
 if(runs.length)console.log('TOTAL: '+fmt(sum(runs))+' tokens over '+runs.length+' runs · average '+fmt(Math.round(sum(runs)/runs.length)));
 if(unknown.length)console.log('Unaccounted: '+unknown.length+' runs (Codex reported no spending) — the total is understated');
-const risky=[...runs,...unknown].filter(r=>r.sandbox&&r.sandbox!=='read-only'&&r.sandbox!=='workspace-write');
+const legacy=[...runs,...unknown].filter(r=>!r.runnerVersion);
+if(legacy.length)console.log('Before the runner: '+legacy.length+' runs carry no runner version and are not judged by the sandbox contract');
+const risky=[...runs,...unknown].filter(r=>r.runnerVersion&&r.sandbox&&r.sandbox!=='read-only'&&r.sandbox!=='workspace-write');
 if(risky.length)console.log('WARNING: '+risky.length+' runs went outside the usual sandbox: '+risky.map(r=>r.run+' ('+r.sandbox+')').join(', '));
 if(runs.length){
   console.log('');console.log('By day:');

package/src/heartbeat.mjs

@@ -51,7 +51,7 @@ export function heartbeatAge(runDir, now = Date.now()) {
 
 /**
  * How long a run has been silent, in words. It lives beside the age it formats because both the
- * worktree lock's refusal and `sweep`'s report have to name the same silence to the same operator;
+ * worktree lock's refusal and `unlock`'s report have to name the same silence to the same operator;
  * two copies of this drifted apart the moment they were written.
  */
 export function formatSilence(age) {

package/src/hook-definitions.mjs

@@ -39,9 +39,22 @@ export const SHELL_TOOLS = Object.freeze(['Bash', 'PowerShell']);
 /** A PreToolUse matcher is a regular expression over tool names, so alternation covers both. */
 export const SHELL_TOOL_MATCHER = SHELL_TOOLS.join('|');
 
+// Plan_31 routes host stop requests through the package guard; keep the matcher derived from
+// the tool list so registration and uninstall cannot drift from the host event spelling.
+export const STOP_TOOLS = Object.freeze(['TaskStop']);
+
+/** A PreToolUse matcher is a regular expression over tool names, so the list remains authoritative. */
+export const STOP_TOOL_MATCHER = STOP_TOOLS.join('|');
+
+/**
+ * Stable CLI names live beside each event and file because the Plan_19 drift incident left
+ * registration, diagnostics, and the guard itself carrying different hook identities. The
+ * dispatcher must consume this one list instead of guessing a name from a path at its call site.
+ */
 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' }),
-  Object.freeze({ event: 'PreToolUse', matcher: WRITE_TOOL_MATCHER, file: 'worktree-lock.mjs' }),
-  Object.freeze({ event: 'PreToolUse', matcher: SHELL_TOOL_MATCHER, file: 'prune-guard.mjs' }),
+  Object.freeze({ name: 'reply-guard', event: 'SubagentStop', matcher: '*', file: 'reply-guard.mjs' }),
+  Object.freeze({ name: 'order-gate', event: 'PreToolUse', matcher: SUBAGENT_TOOL_MATCHER, file: 'order-gate.mjs' }),
+  Object.freeze({ name: 'worktree-lock', event: 'PreToolUse', matcher: WRITE_TOOL_MATCHER, file: 'worktree-lock.mjs' }),
+  Object.freeze({ name: 'prune-guard', event: 'PreToolUse', matcher: SHELL_TOOL_MATCHER, file: 'prune-guard.mjs' }),
+  Object.freeze({ name: 'stop-guard', event: 'PreToolUse', matcher: STOP_TOOL_MATCHER, file: 'stop-guard.mjs' }),
 ]);

package/src/hooks/guard-tries.mjs

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { readJsonFileSync } from '../json-file.mjs';
+
+const LOG_DIR = path.join(os.homedir(), '.claude', 'logs');
+/**
+ * The file keeps its reply-guard name although two guards now share it: renaming would abandon the
+ * budgets already spent on hosts in the field, and a guard that forgets its refusals starts
+ * refusing the same call again.
+ */
+export const BLOCKED_FILE = path.join(LOG_DIR, 'codex-reply-guard.blocked.json');
+export const FORM = 'form';
+export const STATE = 'state';
+export const MAX_FORM_BLOCKS = 3;
+export const MAX_STATE_BLOCKS = 3;
+
+const wholeCount = (value) => (Number.isInteger(value) && value > 0 ? value : 0);
+
+function priorCount(prior, kind) {
+  if (prior && typeof prior === 'object' && !Array.isArray(prior)) {
+    return wholeCount(prior[kind]);
+  }
+  if (kind === FORM && typeof prior === 'number') return wholeCount(prior);
+  if (kind === FORM) return prior ? 1 : 0;
+  return 0;
+}
+
+// Plan_31 reuses this persisted try budget so the TaskStop guard cannot grow a second,
+// divergent counter beside reply-guard's existing per-agent escape hatch.
+export function takeTry(agentId, kind, maxBlocks = kind === STATE ? MAX_STATE_BLOCKS : MAX_FORM_BLOCKS) {
+  if (!agentId) return 'untracked';
+
+  let seen;
+  try {
+    seen = readJsonFileSync(BLOCKED_FILE);
+  } catch {
+    seen = {};
+  }
+  if (!seen || typeof seen !== 'object' || Array.isArray(seen)) seen = {};
+
+  const current = priorCount(seen[agentId], kind);
+  if (current >= maxBlocks) return 'exhausted';
+
+  const prior = seen[agentId];
+  const next = prior && typeof prior === 'object' && !Array.isArray(prior) ? { ...prior } : {};
+  next[kind] = current + 1;
+  seen[agentId] = next;
+
+  const ids = Object.keys(seen);
+  if (ids.length > 200) ids.slice(0, ids.length - 200).forEach((id) => delete seen[id]);
+  try {
+    fs.mkdirSync(path.dirname(BLOCKED_FILE), { recursive: true });
+    fs.writeFileSync(BLOCKED_FILE, `${JSON.stringify(seen)}\n`);
+  } catch {
+    return 'untracked';
+  }
+  return 'granted';
+}

package/src/hooks/live-runs.mjs

@@ -2,8 +2,8 @@
  * Shared, fail-open knowledge of live Codex runs.
  *
  * The reply guard and the worktree lock must answer the same question: a status.json is live
- * only while it says `running`, its runner pid accepts signal 0, and its progress heartbeat is
- * fresh. Keeping those probes and the directory scan here prevents the two protections from
+ * only while it says `running`, its runner pid is judged alive for this run, and its progress
+ * heartbeat is fresh. Keeping those probes and the directory scan here prevents the two protections from
  * disagreeing about a run, which would recreate the 2026-08-06 incident where a dead Codex
  * child left its worker and lock looking live through a grandchild-held stdio pipe.
  *
@@ -13,17 +13,26 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { isHeartbeatFresh } from '../heartbeat.mjs';
+import { heartbeatAge, isHeartbeatFresh } from '../heartbeat.mjs';
+import { readJsonFileSync } from '../json-file.mjs';
+import {
+  IDENTITY_ALIVE,
+  IDENTITY_DEAD,
+  IDENTITY_FOREIGN,
+  processIdentity,
+} from '../process-identity.mjs';
 
-/** Signal 0 tests existence without stopping the process; EPERM still means that it exists. */
-export const isPidAlive = (pid) => {
-  if (typeof pid !== 'number') return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err.code === 'EPERM';
-  }
+/**
+ * The hook requires pid judgment plus a fresh heartbeat. Identity uncertainty stays live here
+ * (fail-open), while the identity module deliberately treats a missing heartbeat as unverified;
+ * isHeartbeatFresh() keeps its pre-Plan_20 missing-file compatibility for this separate question.
+ */
+// Plan_31 needs confirmed process identity before warning about paid work that TaskStop leaves
+// behind; existing lock/reply guards retain the fail-open default for uncertain identities.
+export const isPidAlive = (pid, runDir, status = {}, options = {}) => {
+  const identity = processIdentity({ runDir, status: { ...status, pid } });
+  if (options.requireConfirmedIdentity === true) return identity === IDENTITY_ALIVE;
+  return identity !== IDENTITY_DEAD && identity !== IDENTITY_FOREIGN;
 };
 
 /**
@@ -47,7 +56,9 @@ function isNonEmptyString(value) {
   return typeof value === 'string' && Boolean(value.trim());
 }
 
-function recognizedStatus(runDir, status) {
+function recognizedStatus(runDir, status, options) {
+  const heartbeatFresh = isHeartbeatFresh(runDir)
+    && (options.requireConfirmedIdentity !== true || heartbeatAge(runDir) !== null);
   return Boolean(status)
     && typeof status === 'object'
     && !Array.isArray(status)
@@ -56,20 +67,20 @@ function recognizedStatus(runDir, status) {
     && isNonEmptyString(status.agent)
     && isNonEmptyString(status.slug)
     && isNonEmptyString(status.repo)
-    && isPidAlive(status.pid)
-    && isHeartbeatFresh(runDir);
+    && heartbeatFresh
+    && isPidAlive(status.pid, runDir, status, options);
 }
 
 function readStatus(runDir) {
   try {
-    return JSON.parse(fs.readFileSync(path.join(runDir, 'status.json'), 'utf8'));
+    return readJsonFileSync(path.join(runDir, 'status.json'));
   } catch {
     return null;
   }
 }
 
 /** Scan one project's direct run folders; unreadable or unfamiliar entries are ignored. */
-export function liveRuns(runsDir) {
+export function liveRuns(runsDir, options = {}) {
   if (typeof runsDir !== 'string' || !runsDir.trim()) return [];
   let entries;
   try {
@@ -82,13 +93,13 @@ export function liveRuns(runsDir) {
     if (!entry.isDirectory()) continue;
     const dir = path.join(runsDir, entry.name);
     const status = readStatus(dir);
-    if (recognizedStatus(dir, status)) result.push({ dir, status });
+    if (recognizedStatus(dir, status, options)) result.push({ dir, status });
   }
   return result;
 }
 
 /** Scan every project under the configured runs root for worktree ownership. */
-export function allLiveRuns(runsRoot) {
+export function allLiveRuns(runsRoot, options = {}) {
   if (typeof runsRoot !== 'string' || !runsRoot.trim()) return [];
   let projects;
   try {
@@ -99,7 +110,7 @@ export function allLiveRuns(runsRoot) {
   const result = [];
   for (const project of projects) {
     if (!project.isDirectory()) continue;
-    result.push(...liveRuns(path.join(runsRoot, project.name)));
+    result.push(...liveRuns(path.join(runsRoot, project.name), options));
   }
   return result;
 }

package/src/hooks/order-gate.mjs

@@ -14,7 +14,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { missingInputs } from '../required-inputs.mjs';
+import { diagnoseInput, missingInputs } from '../required-inputs.mjs';
 import { SUBAGENT_TOOLS } from '../hook-definitions.mjs';
 
 const HOME = os.homedir();
@@ -56,7 +56,12 @@ 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}\`.`),
+  ...missing.flatMap((entry) => {
+    const lines = [`- ${entry.label}: ${entry.explanation} Example: \`${entry.example}\`.`];
+    const diagnosis = diagnoseInput(toolInput.prompt, entry.label);
+    if (diagnosis) lines.push(`  found \`${diagnosis.line}\`, ${diagnosis.reason}`);
+    return lines;
+  }),
 ].join('\n');
 
 process.stdout.write(JSON.stringify({

package/src/hooks/reply-guard.mjs

@@ -29,11 +29,12 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { readJsonFileSync } from '../json-file.mjs';
 import { isPidAlive, liveRuns, normalizePath } from './live-runs.mjs';
+import { FORM, MAX_STATE_BLOCKS, STATE, takeTry } from './guard-tries.mjs';
 
 const HOME = os.homedir();
 const LOG_DIR = path.join(HOME, '.claude', 'logs');
-const BLOCKED_FILE = path.join(LOG_DIR, 'codex-reply-guard.blocked.json');
 const GUARDED = new Set(['codex-scout', 'codex-build', 'codex-review']);
 const STATUSES = ['OK', 'FAIL', 'LIMIT'];
 
@@ -47,8 +48,6 @@ const STATUSES = ['OK', 'FAIL', 'LIMIT'];
  * quota on retries that never converge. Three tries, then let it through so the operator
  * sees a reply with substance in it and judges for himself.
  */
-const MAX_FORM_BLOCKS = 3;
-
 /**
  * The same allowance for blocks caused by EXTERNAL state — the run is still going, or its
  * runner died. Counted separately because the two run out for unrelated reasons: three
@@ -60,11 +59,6 @@ const MAX_FORM_BLOCKS = 3;
  * orchestrator got a promise from a process that no longer existed and never learned the
  * worktree was busy.
  */
-const MAX_STATE_BLOCKS = 3;
-
-const FORM = 'form';
-const STATE = 'state';
-
 /** Never let a guard failure break real work: on any doubt, stay silent. */
 const pass = () => process.exit(0);
 
@@ -90,56 +84,6 @@ if (!GUARDED.has(input.agent_type)) pass();
 const reply = String(input.last_assistant_message || '').trim();
 if (!reply) pass();
 
-/**
- * Reads one stored entry into {form, state}. Three shapes live in this file at once and all
- * three must keep their meaning: the current pair, the single number written by the previous
- * version, and an ISO string from the version before that (it meant "blocked once"). A
- * number is read as form tries — that budget is the one the old counter mostly guarded.
- * Anything else counts as one form try already spent, so an agent recorded before this fix
- * does not silently get its tries back.
- */
-const readCounts = (prior) => {
-  const whole = (value) => (Number.isInteger(value) && value > 0 ? value : 0);
-  if (prior && typeof prior === 'object' && !Array.isArray(prior)) {
-    return { form: whole(prior.form), state: whole(prior.state) };
-  }
-  if (typeof prior === 'number') return { form: whole(prior), state: 0 };
-  return { form: prior ? 1 : 0, state: 0 };
-};
-
-/**
- * Spends one try of the named budget. stop_hook_active is not reliable here (it already
- * arrives true in normal runs), so the loop protection is our own.
- *
- *   'granted'   — block normally, a try was recorded;
- *   'exhausted' — this budget is used up, the caller decides what that means;
- *   'untracked' — the guard cannot count at all (no agent id, log not writable). A guard
- *                 that cannot count must not decide anything, least of all end a session.
- */
-const takeTry = (agentId, kind) => {
-  if (!agentId) return 'untracked';
-  let seen;
-  try {
-    seen = JSON.parse(fs.readFileSync(BLOCKED_FILE, 'utf8'));
-  } catch {
-    seen = {};
-  }
-  if (!seen || typeof seen !== 'object' || Array.isArray(seen)) seen = {};
-  const counts = readCounts(seen[agentId]);
-  if (counts[kind] >= (kind === STATE ? MAX_STATE_BLOCKS : MAX_FORM_BLOCKS)) return 'exhausted';
-  counts[kind] += 1;
-  seen[agentId] = counts;
-  // Keep the file from growing without bound; order of insertion is good enough.
-  const ids = Object.keys(seen);
-  if (ids.length > 200) ids.slice(0, ids.length - 200).forEach((id) => delete seen[id]);
-  try {
-    fs.writeFileSync(BLOCKED_FILE, `${JSON.stringify(seen)}\n`);
-  } catch {
-    return 'untracked';
-  }
-  return 'granted';
-};
-
 const emit = (payload) => {
   process.stdout.write(JSON.stringify(payload));
   process.exit(0);
@@ -253,7 +197,7 @@ const statusPath = path.join(runDir, 'status.json');
 if (fs.existsSync(statusPath)) {
   let runStatus = null;
   try {
-    runStatus = JSON.parse(fs.readFileSync(statusPath, 'utf8'));
+    runStatus = readJsonFileSync(statusPath);
   } catch {
     runStatus = null;
   }
@@ -317,7 +261,7 @@ if (!fs.existsSync(metaPath)) {
 
 let meta;
 try {
-  meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+  meta = readJsonFileSync(metaPath);
 } catch {
   pass();
 }