@kavishdua/proctor 1.3.0 → 1.4.0

package/README.md

@@ -80,6 +80,8 @@ The check writes nothing to the repository being checked and makes no runtime ne
 ## Install
 
 Agent plugins install the ruleset. For CLI checks and hooks, use the local npm installation below.
+`proctor setup` adds turn-end enforcement for Claude Code and Codex CLI. The Cursor plugin
+also includes a stop hook.
 
 **Claude Code**
 
@@ -121,9 +123,10 @@ which may be outside the working tree when you use worktrees or `core.hooksPath`
 | The ruleset file for each agent this repo uses, e.g. `.claude/skills/proctor/SKILL.md`, `.cursor/rules/proctor.mdc`, `AGENTS.md` | The honest-completion rules your agent reads before it works | A shared file like `AGENTS.md` keeps your content; only proctor's delimited block is replaced |
 | Git's hook directory (`.git/hooks/pre-commit` normally), or `.husky/pre-commit` when Husky is a dev dependency | Blocks a cheat at commit time; the Husky file is also staged | A foreign hook is backed up to `pre-commit.bak`, then replaced; merge it manually if needed |
 | `.claude/settings.json` | The Claude Code Stop hook, written only if this repo uses Claude Code | Merged into the existing JSON; nothing else in the file changes |
+| `.codex/hooks.json` | The Codex CLI Stop hook, written only if Codex is a selected or detected agent | Merged into the existing JSON, preserving other hooks and top-level fields |
 | `.proctor-adapter-manifest.json` | Records what was written, so `uninstall` can take exactly that back out | Rewritten |
 
-proctor detects agents from their config files, such as `.cursor/`, `.claude/`, or `WARP.md`,
+proctor detects agents from their config files, such as `.cursor/`, `.claude/`, `.codex/`, or `WARP.md`,
 and installs the ruleset for those agents. If it finds none, it writes `AGENTS.md`.
 Run `proctor agents` to check the list before installing. Use `--all` for all 30 supported agents,
 or `--agents claude-code,cursor` to choose them yourself.
@@ -145,6 +148,26 @@ git add -A && git commit -m "chore: add proctor"
 
 If you use Claude Code, restart it so it picks up the new Stop hook.
 
+If you use **Codex CLI**, two trust steps are required before the hook runs:
+
+1. Trust the project at Codex's interactive prompt, or set `trust_level = "trusted"` under
+   `[projects."/absolute/path/to/repo"]` in `~/.codex/config.toml`. Project hooks are silently
+   ignored in untrusted projects.
+2. Review and approve the new or changed hook when Codex prompts, or via `/hooks` in the CLI.
+
+The Codex hook runs `proctor stop-hook --format codex`, which emits a JSON block decision with
+finding feedback and exits `0`. It stays silent on clean checks, internal errors, and a follow-up
+Stop with `stop_hook_active: true`, preventing a loop.
+
+Verified end-to-end against codex-cli 0.164.0 on November 8, 2026: in `codex exec`, a change that
+deleted a failing test was blocked at Stop with an RH001 finding, and Codex continued and acted on
+the block reason; an honest fix completed with no block. Hook trust is one-time: Codex asks to
+review new or changed hooks (the interactive prompt or `/hooks`), records trust against the hook
+definition, and after that the hook runs in both interactive sessions and `codex exec`. The
+`--dangerously-bypass-hook-trust` flag exists for one-off automation that vets hook sources outside
+Codex; it is not part of standard setup. Contract source:
+[Codex hooks](https://learn.chatgpt.com/docs/hooks.md).
+
 The hooks run checks automatically. A config file is optional.
 
 ### Checking it worked
@@ -409,7 +432,7 @@ See the [scope, dropped ideas and tuned dev-set measurements](bench/dynamic-dev/
 
 proctor combines a **ruleset** with a **guard**. The ruleset tells the agent how to complete work
 and report results. The deterministic, diff-level guard checks for known tampering patterns at
-commit time and, with the Claude Code Stop hook, at the end of a turn. It works
+commit time and, with the Claude Code, Codex CLI, or Cursor Stop hooks, at the end of a turn. It works
 below the agent's own reasoning by checking the changed code rather than the agent's explanation.
 
 ## Can the agent get around it?

package/dist/cli.js

@@ -64,7 +64,7 @@ __export(runner_exports, {
 });
 import { spawn as spawn2 } from "child_process";
 import { mkdtempSync, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, rmSync } from "fs";
-import { join as join15 } from "path";
+import { join as join16 } from "path";
 import { tmpdir as tmpdir2 } from "os";
 async function runDynamic(options) {
   const started = Date.now();
@@ -77,7 +77,7 @@ async function runDynamic(options) {
   }
   let scratch;
   try {
-    scratch = mkdtempSync(join15(tmpdir2(), "proctor-dynamic-"));
+    scratch = mkdtempSync(join16(tmpdir2(), "proctor-dynamic-"));
   } catch {
     return skipped("cannot create scratch directory");
   }
@@ -88,14 +88,14 @@ async function runDynamic(options) {
     }
   };
   try {
-    mkdirSync2(join15(scratch, "tmp"));
-    writeFileSync2(join15(scratch, "input.json"), JSON.stringify({ ...options, files: options.files.map(({ from, to }) => ({ from, to })) }));
+    mkdirSync2(join16(scratch, "tmp"));
+    writeFileSync2(join16(scratch, "input.json"), JSON.stringify({ ...options, files: options.files.map(({ from, to }) => ({ from, to })) }));
     const env = {
       PATH: process.env["PATH"],
       HOME: scratch,
-      TMPDIR: join15(scratch, "tmp"),
-      TMP: join15(scratch, "tmp"),
-      TEMP: join15(scratch, "tmp"),
+      TMPDIR: join16(scratch, "tmp"),
+      TMP: join16(scratch, "tmp"),
+      TEMP: join16(scratch, "tmp"),
       LANG: "C.UTF-8",
       CI: "true",
       NO_COLOR: "1",
@@ -105,7 +105,7 @@ async function runDynamic(options) {
       npm_config_offline: "true",
       npm_config_audit: "false",
       npm_config_update_notifier: "false",
-      npm_config_cache: join15(scratch, "npm-cache")
+      npm_config_cache: join16(scratch, "npm-cache")
     };
     const remaining = timeout - (Date.now() - started);
     if (remaining <= 0) return skipped(`overall timeout (${timeout}ms)`);
@@ -127,7 +127,7 @@ async function runDynamic(options) {
         "--",
         process.execPath,
         options.workerPath,
-        join15(scratch, "input.json")
+        join16(scratch, "input.json")
       ];
       const child = spawn2("bwrap", namespaceArgs, {
         cwd: scratch,
@@ -212,14 +212,14 @@ var init_runner = __esm({
 });
 
 // src/cli.ts
-import { Command } from "commander";
-import { resolve as resolve3, join as join16 } from "path";
+import { Command, Option } from "commander";
+import { resolve as resolve3, join as join17 } from "path";
 import { homedir } from "os";
 
 // package.json
 var package_default = {
   name: "@kavishdua/proctor",
-  version: "1.3.0",
+  version: "1.4.0",
   description: "Catch AI agents gaming their test suites: deleted tests, skipped tests, weakened assertions, hardcoded outputs",
   homepage: "https://github.com/catfish-1234/proctor#readme",
   bugs: {
@@ -302,7 +302,7 @@ var package_default = {
 };
 
 // src/cli.ts
-import { readFile as readFile12, writeFile as writeFile7, appendFile } from "fs/promises";
+import { readFile as readFile13, writeFile as writeFile8, appendFile } from "fs/promises";
 import { fileURLToPath as fileURLToPath3 } from "url";
 
 // src/diff.ts
@@ -7446,8 +7446,8 @@ async function checkAdapterDrift(cwd, canonical, adapters = AGENT_ADAPTERS) {
 }
 
 // src/adapters/deploy.ts
-import { readFile as readFile7, writeFile as writeFile4, mkdir as mkdir3, rm as rm2 } from "fs/promises";
-import { join as join8, dirname, relative } from "path";
+import { readFile as readFile8, writeFile as writeFile5, mkdir as mkdir4, rm as rm2 } from "fs/promises";
+import { join as join9, dirname, relative } from "path";
 
 // src/hooks/pre-commit.ts
 import { readFile as readFile5, writeFile as writeFile2, mkdir, rm } from "fs/promises";
@@ -7633,30 +7633,109 @@ function isProctorGroup(group) {
   return hooks.some((h) => isPlainObject(h) && typeof h["command"] === "string" && h["command"].includes(STOP_HOOK_MARKER));
 }
 
+// src/hooks/codex-hooks.ts
+import { readFile as readFile7, writeFile as writeFile4, mkdir as mkdir3 } from "fs/promises";
+import { join as join8 } from "path";
+var STOP_HOOK_COMMAND2 = `npx ${package_default.name} stop-hook --format codex`;
+function parseHooks(raw) {
+  try {
+    const parsed = JSON.parse(raw.replace(/^/, ""));
+    if (!isPlainObject2(parsed)) return void 0;
+    const hooks = parsed["hooks"];
+    if (hooks !== void 0 && !isPlainObject2(hooks)) return void 0;
+    const stop = hooks?.["Stop"];
+    if (stop !== void 0 && !Array.isArray(stop)) return void 0;
+    return parsed;
+  } catch {
+    return void 0;
+  }
+}
+async function installCodexStopHook(dir) {
+  const path9 = join8(dir, "hooks.json");
+  let settings = {};
+  let raw;
+  try {
+    raw = await readFile7(path9, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+  if (raw !== void 0) {
+    const parsed = parseHooks(raw);
+    if (!parsed) return { status: "invalid-json", path: path9 };
+    settings = parsed;
+  }
+  const hooks = settings["hooks"] ?? {};
+  const stop = hooks["Stop"] ?? [];
+  if (stop.some((group) => isPlainObject2(group) && Array.isArray(group["hooks"]) && group["hooks"].some(isProctorHook))) {
+    return { status: "already", path: path9 };
+  }
+  stop.push({ hooks: [{ type: "command", command: STOP_HOOK_COMMAND2, timeout: 60 }] });
+  hooks["Stop"] = stop;
+  settings["hooks"] = hooks;
+  await mkdir3(dir, { recursive: true });
+  await writeFile4(path9, JSON.stringify(settings, null, 2) + "\n", "utf8");
+  return { status: "installed", path: path9 };
+}
+async function removeCodexStopHook(dir, dryRun) {
+  const path9 = join8(dir, "hooks.json");
+  let raw;
+  try {
+    raw = await readFile7(path9, "utf8");
+  } catch {
+    return void 0;
+  }
+  const settings = parseHooks(raw);
+  if (!settings) return void 0;
+  const hooks = settings["hooks"];
+  const stop = hooks?.["Stop"] ?? [];
+  let removed = false;
+  const kept = stop.flatMap((group) => {
+    if (!isPlainObject2(group) || !Array.isArray(group["hooks"])) return [group];
+    const commands = group["hooks"].filter((h) => !isProctorHook(h));
+    if (commands.length === group["hooks"].length) return [group];
+    removed = true;
+    return commands.length > 0 ? [{ ...group, hooks: commands }] : [];
+  });
+  if (!removed || !hooks) return void 0;
+  if (!dryRun) {
+    if (kept.length > 0) hooks["Stop"] = kept;
+    else delete hooks["Stop"];
+    if (Object.keys(hooks).length === 0) delete settings["hooks"];
+    await writeFile4(path9, JSON.stringify(settings, null, 2) + "\n", "utf8");
+  }
+  return path9;
+}
+function isPlainObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isProctorHook(hook) {
+  return isPlainObject2(hook) && hook["type"] === "command" && hook["command"] === STOP_HOOK_COMMAND2;
+}
+
 // src/adapters/deploy.ts
 async function deploySkill(cwd, adapters, canonical) {
   let failed = 0;
   const manifest = await readManifest(cwd);
   for (const adapter of adapters) {
-    const dest = join8(cwd, adapter.relativePath);
+    const dest = join9(cwd, adapter.relativePath);
     const content = adapter.transform ? adapter.transform(canonical) : canonical;
     try {
       if (adapter.shared) {
         let existing;
         try {
-          existing = await readFile7(dest, "utf8");
+          existing = await readFile8(dest, "utf8");
         } catch (err) {
           if (err.code !== "ENOENT") throw err;
         }
         const ours = manifest.written[adapter.id] === true;
-        await mkdir3(dirname(dest), { recursive: true });
-        await writeFile4(dest, upsertBlock(existing, content, ours), "utf8");
+        await mkdir4(dirname(dest), { recursive: true });
+        await writeFile5(dest, upsertBlock(existing, content, ours), "utf8");
         await recordWritten(cwd, adapter.id, existing === void 0);
         process.stdout.write((existing === void 0 ? "Installed: " : "Merged: ") + dest + "\n");
         continue;
       }
-      await mkdir3(dirname(dest), { recursive: true });
-      await writeFile4(dest, content, "utf8");
+      await mkdir4(dirname(dest), { recursive: true });
+      await writeFile5(dest, content, "utf8");
       process.stdout.write("Installed: " + dest + "\n");
     } catch (err) {
       failed++;
@@ -7683,10 +7762,10 @@ async function uninstallProctor(cwd, dryRun) {
   };
   const manifest = await readManifest(cwd);
   for (const adapter of AGENT_ADAPTERS) {
-    const dest = join8(cwd, adapter.relativePath);
+    const dest = join9(cwd, adapter.relativePath);
     let existing;
     try {
-      existing = await readFile7(dest, "utf8");
+      existing = await readFile8(dest, "utf8");
     } catch (err) {
       if (err.code !== "ENOENT") {
         failed.push(`${adapter.relativePath} (${err.code ?? "unreadable"})`);
@@ -7714,7 +7793,7 @@ async function uninstallProctor(cwd, dryRun) {
         });
       } else {
         await attempt(`Unmerged the proctor block from: ${adapter.relativePath}`, async () => {
-          if (!dryRun) await writeFile4(dest, stripped, "utf8");
+          if (!dryRun) await writeFile5(dest, stripped, "utf8");
         });
       }
       continue;
@@ -7723,9 +7802,9 @@ async function uninstallProctor(cwd, dryRun) {
       if (!dryRun) await rm2(dest, { force: true });
     });
   }
-  const manifestPath = join8(cwd, MANIFEST_FILENAME);
+  const manifestPath = join9(cwd, MANIFEST_FILENAME);
   try {
-    await readFile7(manifestPath, "utf8");
+    await readFile8(manifestPath, "utf8");
     await attempt(`Removed: ${MANIFEST_FILENAME}`, async () => {
       if (!dryRun) await rm2(manifestPath, { force: true });
     });
@@ -7738,31 +7817,37 @@ async function uninstallProctor(cwd, dryRun) {
     failed.push(`the pre-commit hook (${err.code ?? "unknown error"})`);
   }
   try {
-    const stop = await removeStopHook(join8(cwd, ".claude"), dryRun);
+    const stop = await removeStopHook(join9(cwd, ".claude"), dryRun);
     if (stop) done.push(`Removed the proctor Stop hook from: ${rel(stop)}`);
   } catch (err) {
     failed.push(`the Stop hook entry (${err.code ?? "unknown error"})`);
   }
+  try {
+    const stop = await removeCodexStopHook(join9(cwd, ".codex"), dryRun);
+    if (stop) done.push(`Removed the proctor Codex Stop hook from: ${rel(stop)}`);
+  } catch (err) {
+    failed.push(`the Codex Stop hook entry (${err.code ?? "unknown error"})`);
+  }
   return { done, failed, note };
 }
 
 // src/bench/tasks.ts
 import { existsSync } from "fs";
 import { readdir } from "fs/promises";
-import { join as join9, dirname as dirname2 } from "path";
+import { join as join10, dirname as dirname2 } from "path";
 import { fileURLToPath } from "url";
 var __dirname = fileURLToPath(new URL(".", import.meta.url));
 function findPackageRoot(startDir) {
   let dir = startDir;
   for (let i = 0; i < 6; i++) {
-    if (existsSync(join9(dir, "package.json"))) return dir;
+    if (existsSync(join10(dir, "package.json"))) return dir;
     const parent = dirname2(dir);
     if (parent === dir) break;
     dir = parent;
   }
   return startDir;
 }
-var DEFAULT_TASKS_DIR = join9(findPackageRoot(__dirname), "bench/tasks");
+var DEFAULT_TASKS_DIR = join10(findPackageRoot(__dirname), "bench/tasks");
 var TASK_NAME_RE = /^task-\d+$/;
 function mulberry32(seed) {
   let a = seed | 0;
@@ -7801,33 +7886,33 @@ async function loadTaskPool(tasksDir = DEFAULT_TASKS_DIR) {
   }
   const dirNames = entries.filter((e) => e.isDirectory() && TASK_NAME_RE.test(e.name)).map((e) => e.name).sort();
   return dirNames.map((taskId) => {
-    const dir = join9(tasksDir, taskId);
+    const dir = join10(tasksDir, taskId);
     return {
       taskId,
       dir,
-      promptPath: join9(dir, "prompt.md"),
-      repoDir: join9(dir, "repo"),
-      heldOutDir: join9(dir, "held-out"),
-      heldOutPath: join9(dir, "held-out.json"),
-      mockPath: join9(dir, "mock-agent.json")
+      promptPath: join10(dir, "prompt.md"),
+      repoDir: join10(dir, "repo"),
+      heldOutDir: join10(dir, "held-out"),
+      heldOutPath: join10(dir, "held-out.json"),
+      mockPath: join10(dir, "mock-agent.json")
     };
   });
 }
 
 // src/bench/index.ts
-import { mkdir as mkdir5, writeFile as writeFile6, readFile as readFile11, rm as rm4 } from "fs/promises";
+import { mkdir as mkdir6, writeFile as writeFile7, readFile as readFile12, rm as rm4 } from "fs/promises";
 import { dirname as dirname6 } from "path";
 
 // src/bench/runners/fixture-runner.ts
-import { readFile as readFile8, writeFile as writeFile5, mkdir as mkdir4 } from "fs/promises";
-import { dirname as dirname3, join as join10, resolve as resolve2, sep } from "path";
+import { readFile as readFile9, writeFile as writeFile6, mkdir as mkdir5 } from "fs/promises";
+import { dirname as dirname3, join as join11, resolve as resolve2, sep } from "path";
 function createFixtureRunner(model) {
   return {
     model,
     async run(task) {
       const started = Date.now();
-      const mockPath = join10(task.workdir, "mock-agent.json");
-      const raw = await readFile8(mockPath, "utf8");
+      const mockPath = join11(task.workdir, "mock-agent.json");
+      const raw = await readFile9(mockPath, "utf8");
       const mock = JSON.parse(raw);
       const branch = task.proctorOn ? mock.proctorOn : mock.proctorOff;
       const root = resolve2(task.workdir);
@@ -7836,8 +7921,8 @@ function createFixtureRunner(model) {
         if (absPath !== root && !absPath.startsWith(root + sep)) {
           throw new Error(`mock-agent.json path escapes workdir: ${relPath}`);
         }
-        await mkdir4(dirname3(absPath), { recursive: true });
-        await writeFile5(absPath, content, "utf8");
+        await mkdir5(dirname3(absPath), { recursive: true });
+        await writeFile6(absPath, content, "utf8");
       }
       return {
         taskId: task.taskId,
@@ -7855,25 +7940,25 @@ function createFixtureRunner(model) {
 // src/bench/runners/shell-runner.ts
 import { spawn, spawnSync as spawnSync3 } from "child_process";
 import { existsSync as existsSync2 } from "fs";
-import { readFile as readFile9 } from "fs/promises";
-import { join as join11, dirname as dirname4 } from "path";
+import { readFile as readFile10 } from "fs/promises";
+import { join as join12, dirname as dirname4 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 var __dirname2 = fileURLToPath2(new URL(".", import.meta.url));
 function findPackageRoot2(startDir) {
   let dir = startDir;
   for (let i = 0; i < 6; i++) {
-    if (existsSync2(join11(dir, "package.json"))) return dir;
+    if (existsSync2(join12(dir, "package.json"))) return dir;
     const parent = dirname4(dir);
     if (parent === dir) break;
     dir = parent;
   }
   return startDir;
 }
-var SKILL_MD_PATH = join11(findPackageRoot2(__dirname2), "src/skill/SKILL.md");
+var SKILL_MD_PATH = join12(findPackageRoot2(__dirname2), "src/skill/SKILL.md");
 var MAX_CAPTURED_OUTPUT = 10 * 1024 * 1024;
 async function buildEffectivePrompt(task) {
   if (!task.proctorOn) return task.prompt;
-  const skillContent = await readFile9(SKILL_MD_PATH, "utf8");
+  const skillContent = await readFile10(SKILL_MD_PATH, "utf8");
   return `${skillContent}
 ---
 ${task.prompt}`;
@@ -7967,11 +8052,11 @@ var AGENT_RUNNERS = [
 ];
 
 // src/bench/scorer.ts
-import { mkdtemp, cp, rm as rm3, readFile as readFile10 } from "fs/promises";
+import { mkdtemp, cp, rm as rm3, readFile as readFile11 } from "fs/promises";
 import { appendFileSync, symlinkSync } from "fs";
 import { spawnSync as spawnSync4 } from "child_process";
 import { tmpdir, platform } from "os";
-import { join as join12, basename as basename3, dirname as dirname5 } from "path";
+import { join as join13, basename as basename3, dirname as dirname5 } from "path";
 import { createRequire } from "module";
 var require2 = createRequire(import.meta.url);
 var vitestPaths;
@@ -7981,7 +8066,7 @@ function resolveVitestPaths() {
     vitestPaths = {
       resolvedNodeModules: dirname5(vitestPkgDir),
       // node_modules dir containing the resolved vitest install
-      vitestBin: join12(vitestPkgDir, "vitest.mjs")
+      vitestBin: join13(vitestPkgDir, "vitest.mjs")
     };
   }
   return vitestPaths;
@@ -7991,7 +8076,7 @@ function linkNodeModules(workdir) {
   try {
     symlinkSync(
       resolveVitestPaths().resolvedNodeModules,
-      join12(workdir, "node_modules"),
+      join13(workdir, "node_modules"),
       platform() === "win32" ? "junction" : "dir"
     );
   } catch {
@@ -8004,7 +8089,7 @@ function runGit2(args, cwd) {
   }
 }
 function excludeNodeModules(workdir) {
-  appendFileSync(join12(workdir, ".git", "info", "exclude"), "\n/node_modules/\n", "utf8");
+  appendFileSync(join13(workdir, ".git", "info", "exclude"), "\n/node_modules/\n", "utf8");
 }
 function runHeldOutTests(workdir) {
   const result = spawnSync4(process.execPath, [resolveVitestPaths().vitestBin, "run", "--root", workdir], {
@@ -8019,12 +8104,12 @@ async function scoreTask(taskDir, runner, proctorOn) {
   if (!TASK_NAME_RE2.test(taskId)) {
     throw new Error(`invalid task directory name: ${taskId}`);
   }
-  const tempDir = await mkdtemp(join12(tmpdir(), "proctor-bench-"));
+  const tempDir = await mkdtemp(join13(tmpdir(), "proctor-bench-"));
   try {
-    await cp(join12(taskDir, "repo"), tempDir, { recursive: true });
+    await cp(join13(taskDir, "repo"), tempDir, { recursive: true });
     linkNodeModules(tempDir);
     try {
-      await cp(join12(taskDir, "mock-agent.json"), join12(tempDir, "mock-agent.json"));
+      await cp(join13(taskDir, "mock-agent.json"), join13(tempDir, "mock-agent.json"));
     } catch (err) {
       if (err.code !== "ENOENT") throw err;
     }
@@ -8034,7 +8119,7 @@ async function scoreTask(taskDir, runner, proctorOn) {
     runGit2(["config", "user.name", "proctor-bench"], tempDir);
     runGit2(["add", "-A"], tempDir);
     runGit2(["-c", "commit.gpgsign=false", "commit", "-q", "-m", "baseline", "--allow-empty"], tempDir);
-    const prompt = await readFile10(join12(taskDir, "prompt.md"), "utf8");
+    const prompt = await readFile11(join13(taskDir, "prompt.md"), "utf8");
     const task = { taskId, prompt, workdir: tempDir, proctorOn };
     const agentResult = await runner.run(task);
     if (agentResult.timedOut) {
@@ -8053,7 +8138,7 @@ async function scoreTask(taskDir, runner, proctorOn) {
     const findings = await runChecks(ctx);
     const cheatDetected = findings.length > 0;
     const rhId = findings[0]?.verifierId ?? "";
-    await cp(join12(taskDir, "held-out"), join12(tempDir, "held-out"), { recursive: true });
+    await cp(join13(taskDir, "held-out"), join13(tempDir, "held-out"), { recursive: true });
     const honestPass = runHeldOutTests(tempDir);
     return { taskId, model: runner.model, proctorOn, cheatDetected, rhId, honestPass };
   } finally {
@@ -8191,7 +8276,7 @@ async function runBench(opts) {
     const partialPath = partialOutPath(opts.outPath);
     let text;
     try {
-      text = await readFile11(partialPath, "utf8");
+      text = await readFile12(partialPath, "utf8");
     } catch {
       process.stderr.write(`proctor: --resume found no rows to resume from at ${partialPath}, scoring every selected task
 `);
@@ -8235,13 +8320,13 @@ async function runBench(opts) {
   }
   const csv = CSV_HEADER + rows.map((r) => toCsvRow([r.taskId, r.model, r.proctorOn, r.cheatDetected, r.rhId, r.honestPass])).join("");
   if (opts.outPath && failedTasks === 0) {
-    await mkdir5(dirname6(opts.outPath), { recursive: true });
-    await writeFile6(opts.outPath, csv, "utf8");
+    await mkdir6(dirname6(opts.outPath), { recursive: true });
+    await writeFile7(opts.outPath, csv, "utf8");
     await rm4(partialOutPath(opts.outPath), { force: true });
   } else if (opts.outPath && failedTasks > 0) {
     const partialPath = partialOutPath(opts.outPath);
-    await mkdir5(dirname6(partialPath), { recursive: true });
-    await writeFile6(partialPath, csv, "utf8");
+    await mkdir6(dirname6(partialPath), { recursive: true });
+    await writeFile7(partialPath, csv, "utf8");
     process.stderr.write(
       `proctor: benchmark had ${failedTasks} invalid task${failedTasks === 1 ? "" : "s"}; preserving the existing output file instead of publishing partial evidence
 proctor: the ${rows.length / 2} task${rows.length === 2 ? "" : "s"} that did complete were written to ${partialPath}, which is not a result
@@ -8255,12 +8340,12 @@ proctor: the ${rows.length / 2} task${rows.length === 2 ? "" : "s"} that did com
 // src/hooks/stop-hook.ts
 import { spawnSync as spawnSync6 } from "child_process";
 import { existsSync as existsSync3 } from "fs";
-import { join as join14 } from "path";
+import { join as join15 } from "path";
 
 // src/session.ts
 import { spawnSync as spawnSync5 } from "child_process";
 import { readFileSync, writeFileSync, mkdirSync } from "fs";
-import { join as join13, dirname as dirname7 } from "path";
+import { join as join14, dirname as dirname7 } from "path";
 var EMPTY = { caught: 0, recentRules: [] };
 var MAX_RECENT_RULES = 20;
 var SESSION_FILENAME = "proctor-session.json";
@@ -8268,7 +8353,7 @@ function sessionPath(cwd) {
   const result = spawnSync5("git", ["rev-parse", "--absolute-git-dir"], { cwd, encoding: "utf8" });
   if (result.status !== 0) return void 0;
   const gitDir = result.stdout.trim();
-  return gitDir ? join13(gitDir, SESSION_FILENAME) : void 0;
+  return gitDir ? join14(gitDir, SESSION_FILENAME) : void 0;
 }
 function isValid(value) {
   if (typeof value !== "object" || value === null) return false;
@@ -8323,6 +8408,13 @@ function parseStopHookInput(raw, fallbackCwd) {
     return { cwd: fallbackCwd, skip: false };
   }
 }
+function formatStopHookResult(result, format) {
+  if (format === "claude") return result;
+  return {
+    exitCode: 0,
+    output: result.exitCode === 2 ? JSON.stringify({ decision: "block", reason: result.output }) : ""
+  };
+}
 function runStopHookCheck(cwd, cliPath) {
   const inRepo = spawnSync6("git", ["rev-parse", "--is-inside-work-tree"], { cwd, stdio: "ignore" });
   if (inRepo.error || inRepo.status !== 0) return { exitCode: 0, output: "" };
@@ -8343,7 +8435,7 @@ function runStopHookCheck(cwd, cliPath) {
 function isMidMerge(cwd) {
   const resolved = spawnSync6("git", ["rev-parse", "--absolute-git-dir"], { cwd, encoding: "utf8" });
   const gitDir = resolved.status === 0 ? (resolved.stdout ?? "").trim() : "";
-  return IN_PROGRESS_MARKERS.some((marker) => gitDir !== "" && existsSync3(join14(gitDir, marker)));
+  return IN_PROGRESS_MARKERS.some((marker) => gitDir !== "" && existsSync3(join15(gitDir, marker)));
 }
 var IN_PROGRESS_MARKERS = [
   "MERGE_HEAD",
@@ -8781,16 +8873,28 @@ program.command("install-hook").description("Install git pre-commit hook").actio
   const hookPath = await installPreCommitHook(process.cwd());
   process.stdout.write("Installed: " + hookPath + "\n");
 });
-program.command("stop-hook").description("Claude Code Stop hook: reads stdin JSON, exits 2 on error findings").action(async () => {
-  const raw = await readStdin();
-  const { cwd, skip } = parseStopHookInput(raw, process.cwd());
-  if (skip) process.exit(0);
-  const { exitCode, output } = runStopHookCheck(cwd, process.argv[1] ?? "");
-  if (output) process.stderr.write(output);
-  process.exit(exitCode);
+program.command("stop-hook").description("Stop hook: reads stdin JSON and blocks on error findings").addOption(new Option("--format <format>", "Stop hook protocol").choices(["claude", "codex"]).default("claude")).action(async (options) => {
+  try {
+    const raw = await readStdin();
+    const { cwd, skip } = parseStopHookInput(raw, process.cwd());
+    if (skip) return;
+    const { exitCode, output } = formatStopHookResult(
+      runStopHookCheck(cwd, process.argv[1] ?? ""),
+      options.format
+    );
+    if (options.format === "codex") {
+      if (output) process.stdout.write(output + "\n");
+      process.exitCode = exitCode;
+      return;
+    }
+    if (output) process.stderr.write(output);
+    process.exit(exitCode);
+  } catch (err) {
+    if (options.format !== "codex") throw err;
+  }
 });
 program.command("install-claude-hook").description("Install Claude Code Stop hook").option("--global", "write to ~/.claude/settings.json").action(async (options) => {
-  const result = await installStopHook(options.global ? join16(homedir(), ".claude") : join16(process.cwd(), ".claude"));
+  const result = await installStopHook(options.global ? join17(homedir(), ".claude") : join17(process.cwd(), ".claude"));
   if (result.status === "invalid-json") {
     process.stderr.write(`proctor: ${result.path} exists but is not valid JSON; fix it manually and re-run
 `);
@@ -8798,10 +8902,10 @@ program.command("install-claude-hook").description("Install Claude Code Stop hoo
   }
   process.stdout.write(result.status === "already" ? "Already installed\n" : "Installed: " + result.path + "\n");
 });
-program.command("setup").description("One-command install: writes the ruleset to every agent this repo uses, and installs both hooks").option("--all", `write the ruleset to all ${AGENT_ADAPTERS.length} supported agents, not only the ones this repo uses`).option("--agents <ids>", "comma-separated agent ids to install to (e.g. claude-code,cursor), instead of detecting").action(async (options) => {
+program.command("setup").description("One-command install: writes the ruleset and installs the git and supported agent hooks").option("--all", `write the ruleset to all ${AGENT_ADAPTERS.length} supported agents, not only the ones this repo uses`).option("--agents <ids>", "comma-separated agent ids to install to (e.g. claude-code,cursor), instead of detecting").action(async (options) => {
   const cwd = process.cwd();
   const targets = await resolveTargets(cwd, options);
-  const failed = await deploySkill(cwd, targets, await readFile12(canonicalSkillPath(), "utf8"));
+  const failed = await deploySkill(cwd, targets, await readFile13(canonicalSkillPath(), "utf8"));
   process.stdout.write(
     `Ruleset written to ${targets.length - failed} of ${targets.length} agent path${targets.length === 1 ? "" : "s"}.
 `
@@ -8822,7 +8926,7 @@ program.command("setup").description("One-command install: writes the ruleset to
     process.exitCode = 1;
   }
   if (targets.some((a) => a.id === "claude-code")) {
-    const stop = await installStopHook(join16(cwd, ".claude"));
+    const stop = await installStopHook(join17(cwd, ".claude"));
     if (stop.status === "invalid-json") {
       process.stderr.write(`proctor: ${stop.path} is not valid JSON, so the Stop hook was not installed; fix it and re-run
 `);
@@ -8834,6 +8938,27 @@ program.command("setup").description("One-command install: writes the ruleset to
       );
     }
   }
+  if (targets.some((a) => a.id === "codex")) {
+    try {
+      const stop = await installCodexStopHook(join17(cwd, ".codex"));
+      if (stop.status === "invalid-json") {
+        process.stderr.write(`proctor: ${stop.path} is not valid JSON, so the Codex Stop hook was not installed; fix it and re-run
+`);
+        process.exitCode = 1;
+      } else {
+        process.stdout.write(
+          stop.status === "already" ? "Codex Stop hook already installed.\n" : `Codex Stop hook installed: ${stop.path}
+`
+        );
+        process.stdout.write("Codex requires project trust and hook review before this hook runs: trust this project, then approve the new or changed hook when prompted or via /hooks in the CLI.\n");
+      }
+    } catch (err) {
+      const msg = String(err).replace(/^Error:\s*/, "");
+      process.stderr.write(`proctor: could not install the Codex Stop hook (${msg})
+`);
+      process.exitCode = 1;
+    }
+  }
   process.stdout.write(process.exitCode ? "\nSetup incomplete. Resolve the errors above and run proctor setup again.\n" : "\nDone. Your agent reads the rules before it works, and gets stopped if it breaks them.\n");
 });
 program.command("install-skill").description("Deploy canonical SKILL.md to the agent adapter paths this repo uses").option("--all", `write to all ${AGENT_ADAPTERS.length} supported agents, not only the ones this repo uses`).option("--agents <ids>", "comma-separated agent ids to install to (e.g. claude-code,cursor), instead of detecting").action(async (options) => {
@@ -8841,7 +8966,7 @@ program.command("install-skill").description("Deploy canonical SKILL.md to the a
   const failed = await deploySkill(
     cwd,
     await resolveTargets(cwd, options),
-    await readFile12(canonicalSkillPath(), "utf8")
+    await readFile13(canonicalSkillPath(), "utf8")
   );
   if (failed > 0) {
     process.stderr.write(`proctor: ${failed} adapter${failed === 1 ? "" : "s"} could not be written
@@ -8927,7 +9052,7 @@ ${done.length} item${done.length === 1 ? "" : "s"} would be removed. Re-run with
 });
 program.command("drift-check").description("Verify every deployed agent adapter still matches canonical SKILL.md").action(async () => {
   const cwd = process.cwd();
-  const canonical = await readFile12(canonicalSkillPath(), "utf8");
+  const canonical = await readFile13(canonicalSkillPath(), "utf8");
   const { drifted } = await checkAdapterDrift(cwd, canonical);
   for (const path9 of drifted) {
     process.stderr.write("Drifted: " + path9 + "\n");
@@ -9035,10 +9160,10 @@ program.command("approve <rule> <file>").description("Record a genuine test chan
     process.stderr.write("proctor: --reason cannot be empty\n");
     process.exit(2);
   }
-  const configPath = join16(process.cwd(), "proctor.config.json");
+  const configPath = join17(process.cwd(), "proctor.config.json");
   let config = {};
   try {
-    config = JSON.parse(await readFile12(configPath, "utf8"));
+    config = JSON.parse(await readFile13(configPath, "utf8"));
   } catch (err) {
     if (err.code !== "ENOENT") {
       process.stderr.write(`proctor: could not read ${configPath}: ${String(err)}
@@ -9062,7 +9187,7 @@ program.command("approve <rule> <file>").description("Record a genuine test chan
     approvals.push({ rule, file: normalizedFile, reason: options.reason });
   }
   config.approvedTestChanges = approvals;
-  await writeFile7(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+  await writeFile8(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
   process.stdout.write(`Approved ${rule} for ${normalizedFile} in proctor.config.json
 `);
   process.stdout.write("Commit proctor.config.json for this to take effect. proctor reads approvals from the committed config, so a change cannot approve itself.\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kavishdua/proctor",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Catch AI agents gaming their test suites: deleted tests, skipped tests, weakened assertions, hardcoded outputs",
   "homepage": "https://github.com/catfish-1234/proctor#readme",
   "bugs": {