oh-my-codex 0.18.12 → 0.18.14

package/dist/scripts/__tests__/codex-native-hook.test.js

@@ -160,6 +160,31 @@ if [[ "$cmd" == "capture-pane" ]]; then
   printf '%s\\n' ${captureText}
   exit 0
 fi
+if [[ "$cmd" == "set-buffer" ]]; then
+  printf '%s' "\${@: -1}" > "${tmuxLogPath}.buffer"
+  exit 0
+fi
+if [[ "$cmd" == "show-buffer" ]]; then
+  if [[ -f "${tmuxLogPath}.buffer" ]]; then cat "${tmuxLogPath}.buffer"; fi
+  exit 0
+fi
+if [[ "$cmd" == "paste-buffer" ]]; then
+  target=""
+  while [[ "$#" -gt 0 ]]; do
+    case "$1" in
+      -t) target="$2"; shift 2 ;;
+      *) shift ;;
+    esac
+  done
+  if [[ -f "${tmuxLogPath}.buffer" ]]; then
+    echo "send-keys -t \${target} -l $(cat "${tmuxLogPath}.buffer")" >> "${tmuxLogPath}"
+  fi
+  exit 0
+fi
+if [[ "$cmd" == "delete-buffer" ]]; then
+  rm -f "${tmuxLogPath}.buffer"
+  exit 0
+fi
 if [[ "$cmd" == "send-keys" ]]; then
   ${sendDelaySeconds > 0 ? `sleep ${sendDelaySeconds}` : ""}
   ${removePathOnSend ? `rm -rf ${removePathOnSend}` : ""}
@@ -346,9 +371,9 @@ describe("codex native hook dispatch", () => {
             assert.equal(result.status, 0, result.stderr || result.stdout);
             assert.equal(result.stderr, "");
             const output = parseSingleJsonStdout(result.stdout);
-            assert.equal(output.continue, false);
+            assert.equal(output.continue, undefined);
             assert.equal(output.decision, undefined);
-            assert.equal(output.stopReason, "native_hook_stdin_parse_error");
+            assert.equal(output.stopReason, undefined);
             assert.equal(output.hookSpecificOutput, undefined);
             assert.match(String(output.systemMessage ?? ""), /stdin JSON parsing failed inside codex-native-hook:/);
         }
@@ -421,6 +446,151 @@ describe("codex native hook dispatch", () => {
         assert.equal(output.hookSpecificOutput, undefined);
         assert.match(String(output.systemMessage ?? ""), /stdin JSON parsing failed inside codex-native-hook:/);
     });
+    it("emits no-op JSON stdout for PreToolUse non-Bash tools with null output", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-cli-pretool-nonbash-noop-"));
+        try {
+            const result = spawnSync(process.execPath, [nativeHookScriptPath()], {
+                cwd,
+                input: JSON.stringify({
+                    hook_event_name: "PreToolUse",
+                    cwd,
+                    session_id: "sess-cli-pretool-nonbash-noop",
+                    thread_id: "thread-cli-pretool-nonbash-noop",
+                    turn_id: "turn-cli-pretool-nonbash-noop",
+                    tool_name: "Read",
+                    tool_input: { file_path: "package.json" },
+                }),
+                encoding: "utf-8",
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            assert.equal(result.status, 0, result.stderr || result.stdout);
+            assert.equal(result.stderr, "");
+            assert.deepEqual(parseSingleJsonStdout(result.stdout), {});
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("emits PreToolUse CLI advisory JSON with only systemMessage", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-cli-pretool-schema-safe-"));
+        try {
+            const output = parseSingleJsonStdout(runNativeHookCli({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-cli-pretool-schema-safe",
+                thread_id: "thread-cli-pretool-schema-safe",
+                turn_id: "turn-cli-pretool-schema-safe",
+                tool_name: "Bash",
+                tool_input: { command: "rm -rf dist" },
+            }, { cwd }));
+            assert.deepEqual(output, {
+                systemMessage: "Destructive Bash command detected (`rm -rf dist`). Confirm the target and expected side effects before running it.",
+            });
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("emits PreToolUse CLI block JSON with only systemMessage", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-cli-pretool-block-schema-safe-"));
+        try {
+            const output = parseSingleJsonStdout(runNativeHookCli({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-cli-pretool-block-schema-safe",
+                thread_id: "thread-cli-pretool-block-schema-safe",
+                turn_id: "turn-cli-pretool-block-schema-safe",
+                tool_name: "Bash",
+                tool_input: { command: 'OMX_LORE_COMMIT_GUARD=1 git commit -m "fix tests"' },
+            }, { cwd }));
+            assert.deepEqual(Object.keys(output).sort(), ["systemMessage"]);
+            assert.match(String(output.systemMessage ?? ""), /Lore protocol/);
+            assert.equal(output.decision, undefined);
+            assert.equal(output.stopReason, undefined);
+            assert.equal(output.hookSpecificOutput, undefined);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("preserves ralplan PreToolUse planning guard as schema-safe CLI systemMessage", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-cli-ralplan-pretool-boundary-"));
+        const sessionId = "sess-cli-ralplan-pretool-boundary";
+        const stateDir = join(cwd, ".omx", "state");
+        try {
+            await writeJson(join(stateDir, "session.json"), { session_id: sessionId });
+            await writeJson(join(stateDir, "sessions", sessionId, "skill-active-state.json"), {
+                active: true,
+                skill: "ralplan",
+                phase: "planning",
+                session_id: sessionId,
+                active_skills: [{ skill: "ralplan", phase: "planning", active: true, session_id: sessionId }],
+            });
+            await writeJson(join(stateDir, "sessions", sessionId, "ralplan-state.json"), {
+                active: true,
+                mode: "ralplan",
+                current_phase: "critic-review",
+                session_id: sessionId,
+            });
+            const output = parseSingleJsonStdout(runNativeHookCli({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: sessionId,
+                thread_id: "thread-cli-ralplan-pretool-boundary",
+                tool_name: "Edit",
+                tool_input: { file_path: "src/runtime.ts", old_string: "a", new_string: "b" },
+            }, { cwd }));
+            assert.deepEqual(Object.keys(output).sort(), ["systemMessage"]);
+            assert.match(String(output.systemMessage ?? ""), /Ralplan is active \(phase: critic-review\)/);
+            assert.match(String(output.systemMessage ?? ""), /implementation\/write tools are blocked/);
+            assert.match(String(output.systemMessage ?? ""), /Write only planning artifacts/);
+            assert.equal(output.decision, undefined);
+            assert.equal(output.reason, undefined);
+            assert.equal(output.hookSpecificOutput, undefined);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("preserves deep-interview PreToolUse planning guard as schema-safe CLI systemMessage", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-cli-deep-interview-pretool-boundary-"));
+        const sessionId = "sess-cli-deep-interview-pretool-boundary";
+        const stateDir = join(cwd, ".omx", "state");
+        try {
+            await writeJson(join(stateDir, "session.json"), { session_id: sessionId });
+            await writeJson(join(stateDir, "sessions", sessionId, "skill-active-state.json"), {
+                active: true,
+                skill: "deep-interview",
+                phase: "planning",
+                session_id: sessionId,
+                active_skills: [{ skill: "deep-interview", phase: "planning", active: true, session_id: sessionId }],
+            });
+            await writeJson(join(stateDir, "sessions", sessionId, "deep-interview-state.json"), {
+                active: true,
+                mode: "deep-interview",
+                current_phase: "intent-first",
+                session_id: sessionId,
+            });
+            const output = parseSingleJsonStdout(runNativeHookCli({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: sessionId,
+                thread_id: "thread-cli-deep-interview-pretool-boundary",
+                tool_name: "Write",
+                tool_input: { file_path: "src/runtime.ts", content: "export const changed = true;\n" },
+            }, { cwd }));
+            assert.deepEqual(Object.keys(output).sort(), ["systemMessage"]);
+            assert.match(String(output.systemMessage ?? ""), /Deep-interview is active \(phase: intent-first\)/);
+            assert.match(String(output.systemMessage ?? ""), /implementation\/write tools are blocked/);
+            assert.match(String(output.systemMessage ?? ""), /requirements\/spec mode/);
+            assert.equal(output.decision, undefined);
+            assert.equal(output.reason, undefined);
+            assert.equal(output.hookSpecificOutput, undefined);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("emits parseable no-op JSON stdout for inactive Stop CLI runs", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-cli-stop-noop-json-"));
         try {
@@ -439,6 +609,31 @@ describe("codex native hook dispatch", () => {
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("emits no-op JSON stdout for Stop payloads with no runtime output", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-cli-stop-null-output-"));
+        try {
+            const result = spawnSync(process.execPath, [nativeHookScriptPath()], {
+                cwd,
+                input: JSON.stringify({
+                    hook_event_name: "Stop",
+                    cwd,
+                    session_id: "sess-cli-stop-null-output",
+                    thread_id: "thread-cli-stop-null-output",
+                    turn_id: "turn-cli-stop-null-output",
+                    stop_hook_active: true,
+                }),
+                encoding: "utf-8",
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            assert.equal(result.status, 0, result.stderr || result.stdout);
+            assert.equal(result.stderr, "");
+            assert.deepEqual(parseSingleJsonStdout(result.stdout), {});
+            assert.equal(existsSync(join(cwd, ".omx", "state")), false);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("returns empty JSON for oversized Stop stdin without parsing or creating inactive state", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-cli-stop-oversized-"));
         try {
@@ -567,6 +762,79 @@ describe("codex native hook dispatch", () => {
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("does not block Stop on stale session autopilot mirror when canonical skill state is inactive", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stale-autopilot-mirror-"));
+        try {
+            const sessionId = "sess-stale-autopilot-mirror";
+            await writeJson(join(cwd, ".omx", "state", "session.json"), { session_id: sessionId, cwd });
+            await writeJson(join(cwd, ".omx", "state", "skill-active-state.json"), {
+                version: 1,
+                active: false,
+                skill: "",
+                phase: "cancelled",
+                active_skills: [],
+            });
+            await writeJson(join(cwd, ".omx", "state", "sessions", sessionId, "autopilot-state.json"), {
+                active: true,
+                mode: "autopilot",
+                current_phase: "ultragoal",
+                session_id: sessionId,
+            });
+            await writeJson(join(cwd, ".omx", "state", "sessions", sessionId, "skill-active-state.json"), {
+                version: 1,
+                active: true,
+                skill: "autopilot",
+                phase: "ultragoal",
+                session_id: sessionId,
+                active_skills: [{ skill: "autopilot", phase: "ultragoal", active: true, session_id: sessionId }],
+            });
+            const stdout = runNativeHookCli({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: sessionId,
+                thread_id: "thread-stale-autopilot-mirror",
+            }, { cwd });
+            assert.deepEqual(parseSingleJsonStdout(stdout), {});
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("includes blocking state source and canonical agreement in Stop diagnostics", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-autopilot-diagnostic-"));
+        try {
+            const sessionId = "sess-autopilot-diagnostic";
+            await writeJson(join(cwd, ".omx", "state", "session.json"), { session_id: sessionId, cwd });
+            await writeJson(join(cwd, ".omx", "state", "skill-active-state.json"), {
+                version: 1,
+                active: true,
+                skill: "autopilot",
+                phase: "ultragoal",
+                session_id: sessionId,
+                active_skills: [{ skill: "autopilot", phase: "ultragoal", active: true, session_id: sessionId }],
+            });
+            await writeJson(join(cwd, ".omx", "state", "sessions", sessionId, "autopilot-state.json"), {
+                active: true,
+                mode: "autopilot",
+                current_phase: "ultragoal",
+                session_id: sessionId,
+            });
+            const output = parseSingleJsonStdout(runNativeHookCli({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: sessionId,
+                thread_id: "thread-autopilot-diagnostic",
+            }, { cwd }));
+            assert.equal(output.decision, "block");
+            assert.match(String(output.reason ?? ""), /state: \.omx\/state\/sessions\/sess-autopilot-diagnostic\/autopilot-state\.json/);
+            assert.match(String(output.reason ?? ""), /canonical: canonical_agrees/);
+            assert.equal(output.statePath, ".omx/state/sessions/sess-autopilot-diagnostic/autopilot-state.json");
+            assert.equal(output.canonicalDisagreement, "canonical_agrees");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("emits exactly one parseable JSON object for active Stop CLI continuation", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-cli-stop-json-"));
         try {
@@ -1153,77 +1421,181 @@ describe("codex native hook dispatch", () => {
             await rm(cwd, { recursive: true, force: true });
         }
     });
-    it("keeps a self-parented native role thread as subagent evidence", async () => {
-        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-self-parented-subagent-"));
+    it("suppresses child-agent SessionStart and Stop before the canonical leader session is reconciled (#2831)", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-subagent-no-canonical-"));
+        const originalCodexHome = process.env.CODEX_HOME;
         try {
-            const stateDir = join(cwd, ".omx", "state");
-            const canonicalSessionId = "omx-autopilot-session";
-            const nativeRoleThreadId = "codex-architect-thread";
-            await mkdir(join(stateDir, "sessions", canonicalSessionId), { recursive: true });
-            await writeSessionStart(cwd, canonicalSessionId, {
-                nativeSessionId: nativeRoleThreadId,
+            process.env.CODEX_HOME = join(cwd, "codex-home");
+            await writeJson(join(process.env.CODEX_HOME, ".omx-config.json"), {
+                notifications: {
+                    enabled: true,
+                    verbosity: "session",
+                    telegram: { enabled: true, botToken: "123:abc", chatId: "456" },
+                },
             });
-            const transcriptPath = join(cwd, "architect-subagent-rollout.jsonl");
+            const stateDir = join(cwd, ".omx", "state");
+            const leaderNativeSessionId = "codex-leader-thread-no-canonical";
+            const childNativeSessionId = "codex-child-thread-no-canonical";
+            await mkdir(join(cwd, ".omx", "hooks"), { recursive: true });
+            await writeFile(join(cwd, ".omx", "hooks", "record-lifecycle.mjs"), [
+                "import { appendFileSync } from 'node:fs';",
+                "export async function onHookEvent(event) {",
+                "  appendFileSync('hook-events.jsonl', `${JSON.stringify({ event: event.event })}\\n`);",
+                "}",
+            ].join("\n"));
+            const transcriptPath = join(cwd, "no-canonical-subagent-rollout.jsonl");
             await writeFile(transcriptPath, `${JSON.stringify({
                 type: "session_meta",
                 payload: {
-                    id: nativeRoleThreadId,
+                    id: childNativeSessionId,
                     source: {
                         subagent: {
                             thread_spawn: {
-                                parent_thread_id: nativeRoleThreadId,
-                                depth: 1,
-                                agent_nickname: "Architect",
-                                agent_role: "architect",
+                                parent_thread_id: leaderNativeSessionId,
+                                agent_role: "explorer",
                             },
                         },
                     },
-                    agent_nickname: "Architect",
-                    agent_role: "architect",
                 },
             })}\n`);
             await dispatchCodexNativeHook({
                 hook_event_name: "SessionStart",
                 cwd,
-                session_id: nativeRoleThreadId,
+                session_id: childNativeSessionId,
                 transcript_path: transcriptPath,
             }, { cwd, sessionOwnerPid: process.pid });
+            assert.equal(existsSync(join(cwd, "hook-events.jsonl")), false, "child SessionStart must be suppressed even before the canonical leader session is reconciled");
+            assert.equal(existsSync(join(stateDir, "session.json")), false, "child SessionStart must not be promoted into a root/leader session");
             const tracking = JSON.parse(await readFile(join(stateDir, "subagent-tracking.json"), "utf-8"));
-            assert.equal(tracking.sessions?.[canonicalSessionId]?.leader_thread_id, undefined);
-            assert.equal(tracking.sessions?.[canonicalSessionId]?.threads?.[nativeRoleThreadId]?.kind, "subagent");
-            assert.equal(tracking.sessions?.[canonicalSessionId]?.threads?.[nativeRoleThreadId]?.mode, "architect");
+            assert.equal(tracking.sessions?.[leaderNativeSessionId]?.leader_thread_id, leaderNativeSessionId);
+            assert.equal(tracking.sessions?.[leaderNativeSessionId]?.threads?.[childNativeSessionId]?.kind, "subagent");
+            await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: childNativeSessionId,
+                thread_id: childNativeSessionId,
+                turn_id: "no-canonical-child-stop-turn",
+            }, { cwd });
+            assert.equal(existsSync(join(cwd, "hook-events.jsonl")), false, "child Stop must be suppressed when the start was recognized as subagent-scoped");
         }
         finally {
+            if (originalCodexHome === undefined) {
+                delete process.env.CODEX_HOME;
+            }
+            else {
+                process.env.CODEX_HOME = originalCodexHome;
+            }
             await rm(cwd, { recursive: true, force: true });
         }
     });
-    it("does not attach a subagent SessionStart to an unrelated canonical leader", async () => {
-        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-subagent-session-start-mismatch-"));
+    it("preserves root/leader SessionStart dispatch at session verbosity (#2831)", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-root-session-start-preserved-"));
+        const originalCodexHome = process.env.CODEX_HOME;
         try {
-            const stateDir = join(cwd, ".omx", "state");
-            const canonicalSessionId = "omx-leader-session-a";
-            const leaderNativeSessionId = "codex-leader-thread-a";
-            const unrelatedParentNativeSessionId = "codex-leader-thread-b";
-            const childNativeSessionId = "codex-child-thread-b";
-            await mkdir(join(stateDir, "sessions", canonicalSessionId), { recursive: true });
-            await writeSessionStart(cwd, canonicalSessionId, {
-                nativeSessionId: leaderNativeSessionId,
-            });
-            await writeJson(join(stateDir, "sessions", canonicalSessionId, "ralph-state.json"), {
-                active: true,
-                mode: "ralph",
-                current_phase: "executing",
-                iteration: 1,
-                max_iterations: 5,
+            process.env.CODEX_HOME = join(cwd, "codex-home");
+            await writeJson(join(process.env.CODEX_HOME, ".omx-config.json"), {
+                notifications: {
+                    enabled: true,
+                    verbosity: "session",
+                    telegram: { enabled: true, botToken: "123:abc", chatId: "456" },
+                },
             });
-            const transcriptPath = join(cwd, "unrelated-subagent-rollout.jsonl");
-            await writeFile(transcriptPath, `${JSON.stringify({
-                type: "session_meta",
-                payload: {
-                    id: childNativeSessionId,
-                    source: {
-                        subagent: {
-                            thread_spawn: {
+            await mkdir(join(cwd, ".omx", "hooks"), { recursive: true });
+            await writeFile(join(cwd, ".omx", "hooks", "record-lifecycle.mjs"), [
+                "import { appendFileSync } from 'node:fs';",
+                "export async function onHookEvent(event) {",
+                "  appendFileSync('hook-events.jsonl', `${JSON.stringify({ event: event.event })}\\n`);",
+                "}",
+            ].join("\n"));
+            await dispatchCodexNativeHook({
+                hook_event_name: "SessionStart",
+                cwd,
+                session_id: "codex-root-thread-preserved",
+            }, { cwd, sessionOwnerPid: process.pid });
+            const hookEvents = await readFile(join(cwd, "hook-events.jsonl"), "utf-8");
+            assert.match(hookEvents, /"event":"session-start"/, "root/leader SessionStart must still dispatch at session verbosity");
+        }
+        finally {
+            if (originalCodexHome === undefined) {
+                delete process.env.CODEX_HOME;
+            }
+            else {
+                process.env.CODEX_HOME = originalCodexHome;
+            }
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("keeps a self-parented native role thread as subagent evidence", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-self-parented-subagent-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            const canonicalSessionId = "omx-autopilot-session";
+            const nativeRoleThreadId = "codex-architect-thread";
+            await mkdir(join(stateDir, "sessions", canonicalSessionId), { recursive: true });
+            await writeSessionStart(cwd, canonicalSessionId, {
+                nativeSessionId: nativeRoleThreadId,
+            });
+            const transcriptPath = join(cwd, "architect-subagent-rollout.jsonl");
+            await writeFile(transcriptPath, `${JSON.stringify({
+                type: "session_meta",
+                payload: {
+                    id: nativeRoleThreadId,
+                    source: {
+                        subagent: {
+                            thread_spawn: {
+                                parent_thread_id: nativeRoleThreadId,
+                                depth: 1,
+                                agent_nickname: "Architect",
+                                agent_role: "architect",
+                            },
+                        },
+                    },
+                    agent_nickname: "Architect",
+                    agent_role: "architect",
+                },
+            })}\n`);
+            await dispatchCodexNativeHook({
+                hook_event_name: "SessionStart",
+                cwd,
+                session_id: nativeRoleThreadId,
+                transcript_path: transcriptPath,
+            }, { cwd, sessionOwnerPid: process.pid });
+            const tracking = JSON.parse(await readFile(join(stateDir, "subagent-tracking.json"), "utf-8"));
+            assert.equal(tracking.sessions?.[canonicalSessionId]?.leader_thread_id, undefined);
+            assert.equal(tracking.sessions?.[canonicalSessionId]?.threads?.[nativeRoleThreadId]?.kind, "subagent");
+            assert.equal(tracking.sessions?.[canonicalSessionId]?.threads?.[nativeRoleThreadId]?.mode, "architect");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("does not attach a subagent SessionStart to an unrelated canonical leader", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-subagent-session-start-mismatch-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            const canonicalSessionId = "omx-leader-session-a";
+            const leaderNativeSessionId = "codex-leader-thread-a";
+            const unrelatedParentNativeSessionId = "codex-leader-thread-b";
+            const childNativeSessionId = "codex-child-thread-b";
+            await mkdir(join(stateDir, "sessions", canonicalSessionId), { recursive: true });
+            await writeSessionStart(cwd, canonicalSessionId, {
+                nativeSessionId: leaderNativeSessionId,
+            });
+            await writeJson(join(stateDir, "sessions", canonicalSessionId, "ralph-state.json"), {
+                active: true,
+                mode: "ralph",
+                current_phase: "executing",
+                iteration: 1,
+                max_iterations: 5,
+            });
+            const transcriptPath = join(cwd, "unrelated-subagent-rollout.jsonl");
+            await writeFile(transcriptPath, `${JSON.stringify({
+                type: "session_meta",
+                payload: {
+                    id: childNativeSessionId,
+                    source: {
+                        subagent: {
+                            thread_spawn: {
                                 parent_thread_id: unrelatedParentNativeSessionId,
                                 depth: 1,
                                 agent_nickname: "Spinoza",
@@ -2276,6 +2648,60 @@ standardMaxRounds = 15
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("nudges next-goal prompts when a completed Codex goal cleanup step remains", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-completed-goal-prompt-"));
+        try {
+            await writeJson(join(cwd, ".omx", "goals", "performance", "latency", "state.json"), {
+                version: 1,
+                workflow: "performance-goal",
+                slug: "latency",
+                objective: "Reduce latency",
+                status: "complete",
+                completedAt: "2026-05-20T00:00:00.000Z",
+            });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                session_id: "sess-completed-goal-prompt",
+                thread_id: "thread-completed-goal-prompt",
+                prompt: "Start the next performance goal now",
+            }, { cwd });
+            const output = JSON.stringify(result.outputJson);
+            assert.match(output, /run \/goal clear/);
+            assert.match(output, /before calling create_goal/);
+            assert.match(output, /hooks only nudge and must not mutate Codex goal state/);
+            assert.doesNotMatch(output, /cleared Codex goal state/i);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("blocks Stop when a final answer starts another goal over completed state", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-completed-goal-stop-"));
+        try {
+            await writeJson(join(cwd, ".omx", "ultragoal", "goals.json"), {
+                version: 1,
+                aggregateCompletion: { status: "complete", completedAt: "2026-05-20T00:00:00.000Z" },
+                goals: [{ id: "G001-done", status: "complete", objective: "Done" }],
+            });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: "sess-completed-goal-stop",
+                thread_id: "thread-completed-goal-stop",
+                last_assistant_message: "Starting another ultragoal now; create_goal payload follows.",
+            }, { cwd });
+            const output = JSON.stringify(result.outputJson);
+            assert.equal(result.outputJson?.decision, "block");
+            assert.equal(result.outputJson?.stopReason, "completed_codex_goal_cleanup_required");
+            assert.match(output, /run \/goal clear/);
+            assert.match(output, /before calling create_goal/);
+            assert.match(output, /hooks only nudge and must not mutate Codex goal state/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("blocks ultragoal Stop for concise generic goal completion claims", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-ultragoal-generic-complete-stop-"));
         try {
@@ -4915,6 +5341,175 @@ exit 0
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("allows read-only diagnostics mentioning apply_patch while deep-interview blocks real apply_patch invocations", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-deep-interview-grep-apply-patch-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            const sessionDir = join(stateDir, "sessions", "sess-di-grep");
+            await mkdir(sessionDir, { recursive: true });
+            await writeJson(join(stateDir, "session.json"), { session_id: "sess-di-grep", cwd });
+            await writeJson(join(sessionDir, "skill-active-state.json"), {
+                version: 1,
+                active: true,
+                skill: "deep-interview",
+                phase: "planning",
+                session_id: "sess-di-grep",
+                active_skills: [{ skill: "deep-interview", phase: "planning", active: true, session_id: "sess-di-grep" }],
+            });
+            await writeJson(join(sessionDir, "deep-interview-state.json"), {
+                active: true,
+                mode: "deep-interview",
+                current_phase: "intent-first",
+                session_id: "sess-di-grep",
+            });
+            const allowedGrep = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-di-grep",
+                tool_name: "Bash",
+                tool_use_id: "tool-di-grep",
+                tool_input: { command: 'grep -n "apply_patch" dist/scripts/codex-native-hook.js' },
+            }, { cwd });
+            assert.equal(allowedGrep.outputJson, null);
+            const allowedSubshellGrep = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-di-grep",
+                tool_name: "Bash",
+                tool_use_id: "tool-di-grep-subshell",
+                tool_input: { command: '(grep -n "apply_patch" dist/scripts/codex-native-hook.js)' },
+            }, { cwd });
+            assert.equal(allowedSubshellGrep.outputJson, null);
+            // Double-quoted spans that merely mention the literal token, expand a
+            // parameter, or run a substitution that is not `apply_patch` stay allowed
+            // — the quoted-substitution fix must not over-block read-only diagnostics.
+            const allowedQuotedMention = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-di-grep",
+                tool_name: "Bash",
+                tool_use_id: "tool-di-grep-quoted-mention",
+                tool_input: { command: 'echo "${apply_patch} $(echo apply_patch)"' },
+            }, { cwd });
+            assert.equal(allowedQuotedMention.outputJson, null);
+            const blockedApplyPatch = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-di-grep",
+                tool_name: "Bash",
+                tool_use_id: "tool-di-apply-patch-invoke",
+                tool_input: { command: "apply_patch <<'EOF'\n*** Begin Patch\n*** Add File: src/leak.ts\n+export const x = 1;\n*** End Patch\nEOF" },
+            }, { cwd });
+            assert.equal(blockedApplyPatch.outputJson?.decision, "block");
+            const blockedEnvAssignmentApplyPatch = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-di-grep",
+                tool_name: "Bash",
+                tool_use_id: "tool-di-apply-patch-env-assignment",
+                tool_input: { command: "FOO=bar apply_patch <<'EOF'\n*** Begin Patch\n*** Add File: src/leak.ts\n+export const x = 1;\n*** End Patch\nEOF" },
+            }, { cwd });
+            assert.equal(blockedEnvAssignmentApplyPatch.outputJson?.decision, "block");
+            const blockedEnvWrapperApplyPatch = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-di-grep",
+                tool_name: "Bash",
+                tool_use_id: "tool-di-apply-patch-env-wrapper",
+                tool_input: { command: "env FOO=bar apply_patch <<'EOF'\n*** Begin Patch\n*** Add File: src/leak.ts\n+export const x = 1;\n*** End Patch\nEOF" },
+            }, { cwd });
+            assert.equal(blockedEnvWrapperApplyPatch.outputJson?.decision, "block");
+            const heredocBody = "\n*** Begin Patch\n*** Add File: src/leak.ts\n+export const x = 1;\n*** End Patch\nEOF";
+            const blockedRealApplyPatchForms = [
+                { id: "tool-di-apply-patch-env-i", command: `env -i apply_patch <<'EOF'${heredocBody}` },
+                { id: "tool-di-apply-patch-env-unset", command: `env -u FOO apply_patch <<'EOF'${heredocBody}` },
+                { id: "tool-di-apply-patch-env-i-assignment", command: `env -i FOO=bar apply_patch <<'EOF'${heredocBody}` },
+                { id: "tool-di-apply-patch-assignment-env", command: `FOO=bar env apply_patch <<'EOF'${heredocBody}` },
+                { id: "tool-di-apply-patch-exec-env-assignment", command: `exec env FOO=bar apply_patch <<'EOF'${heredocBody}` },
+                { id: "tool-di-apply-patch-absolute-path", command: `/usr/bin/apply_patch <<'EOF'${heredocBody}` },
+                { id: "tool-di-apply-patch-relative-path", command: `./apply_patch <<'EOF'${heredocBody}` },
+                { id: "tool-di-apply-patch-subshell", command: `(apply_patch <<'EOF'${heredocBody}\n)` },
+                { id: "tool-di-apply-patch-subshell-spaced", command: `( apply_patch <<'EOF'${heredocBody}\n)` },
+                { id: "tool-di-apply-patch-double-subshell", command: `((apply_patch <<'EOF'${heredocBody}\n))` },
+                { id: "tool-di-apply-patch-pipe-subshell", command: `true | (apply_patch <<'EOF'${heredocBody}\n)` },
+                { id: "tool-di-apply-patch-subshell-env", command: `(env apply_patch <<'EOF'${heredocBody}\n)` },
+                { id: "tool-di-apply-patch-command-substitution", command: `x=$(apply_patch <<'EOF'${heredocBody}\n)` },
+                { id: "tool-di-apply-patch-brace-group", command: `{ apply_patch <<'EOF'${heredocBody}\n}` },
+                // Command substitution runs even inside double quotes, so quoting the
+                // already-blocked `$(…)` / `` `…` `` form must not bypass the guard.
+                { id: "tool-di-apply-patch-quoted-command-substitution", command: `echo "$(apply_patch <<'EOF'${heredocBody}\n)"` },
+                { id: "tool-di-apply-patch-quoted-backtick", command: `echo "\`apply_patch <<'EOF'${heredocBody}\`"` },
+                { id: "tool-di-apply-patch-quoted-command-substitution-prefixed", command: `echo "patched: $(apply_patch <<'EOF'${heredocBody}\n) done"` },
+            ];
+            for (const form of blockedRealApplyPatchForms) {
+                const blockedForm = await dispatchCodexNativeHook({
+                    hook_event_name: "PreToolUse",
+                    cwd,
+                    session_id: "sess-di-grep",
+                    tool_name: "Bash",
+                    tool_use_id: form.id,
+                    tool_input: { command: form.command },
+                }, { cwd });
+                assert.equal(blockedForm.outputJson?.decision, "block", `expected deep-interview to block real apply_patch form: ${form.command}`);
+            }
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("allows deep-interview same-command literal variable redirects to artifacts while blocking variable redirects outside them", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-deep-interview-var-redirect-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            const sessionDir = join(stateDir, "sessions", "sess-di-var-redirect");
+            await mkdir(sessionDir, { recursive: true });
+            await writeJson(join(stateDir, "session.json"), { session_id: "sess-di-var-redirect", cwd });
+            await writeJson(join(sessionDir, "skill-active-state.json"), {
+                version: 1,
+                active: true,
+                skill: "deep-interview",
+                phase: "planning",
+                session_id: "sess-di-var-redirect",
+                active_skills: [{ skill: "deep-interview", phase: "planning", active: true, session_id: "sess-di-var-redirect" }],
+            });
+            await writeJson(join(sessionDir, "deep-interview-state.json"), {
+                active: true,
+                mode: "deep-interview",
+                current_phase: "intent-first",
+                session_id: "sess-di-var-redirect",
+            });
+            const allowedVarRedirect = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-di-var-redirect",
+                tool_name: "Bash",
+                tool_use_id: "tool-di-var-redirect-allow",
+                tool_input: { command: 'SNAP=".omx/context/example.md"\ncat > "$SNAP" <<\'EOF\'\ncontent\nEOF' },
+            }, { cwd });
+            assert.equal(allowedVarRedirect.outputJson, null);
+            const blockedVarRedirect = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-di-var-redirect",
+                tool_name: "Bash",
+                tool_use_id: "tool-di-var-redirect-block",
+                tool_input: { command: 'SNAP="src/leak.ts"\ncat > "$SNAP" <<\'EOF\'\ncontent\nEOF' },
+            }, { cwd });
+            assert.equal(blockedVarRedirect.outputJson?.decision, "block");
+            const blockedUnresolvedVarRedirect = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-di-var-redirect",
+                tool_name: "Bash",
+                tool_use_id: "tool-di-var-redirect-unresolved",
+                tool_input: { command: 'cat > "$SNAP" <<\'EOF\'\ncontent\nEOF' },
+            }, { cwd });
+            assert.equal(blockedUnresolvedVarRedirect.outputJson?.decision, "block");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("allows deep-interview apply_patch artifact writes from freeform patch text while blocking outside paths", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-deep-interview-apply-patch-"));
         try {
@@ -5006,6 +5601,127 @@ exit 0
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("allows Ralplan read-only inspection and planning artifact writes while blocking implementation targets", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-ralplan-guard-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            const sessionId = "sess-ralplan-guard";
+            const sessionDir = join(stateDir, "sessions", sessionId);
+            await mkdir(sessionDir, { recursive: true });
+            await writeJson(join(stateDir, "session.json"), { session_id: sessionId, cwd });
+            await writeJson(join(sessionDir, "skill-active-state.json"), {
+                version: 1,
+                active: true,
+                skill: "ralplan",
+                phase: "planning",
+                session_id: sessionId,
+                active_skills: [{ skill: "ralplan", phase: "planning", active: true, session_id: sessionId }],
+            });
+            await writeJson(join(sessionDir, "ralplan-state.json"), {
+                active: true,
+                mode: "ralplan",
+                current_phase: "planning",
+                session_id: sessionId,
+            });
+            const preToolUse = async (tool_name, tool_use_id, tool_input) => dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: sessionId,
+                tool_name,
+                tool_use_id,
+                tool_input,
+            }, { cwd });
+            const readOnlyCommands = [
+                "git status --short",
+                "ls -1 .omx/plans",
+                "find .omx/plans -type f -name '*.md'",
+                "grep -RIn \"Scholastic\" doc tests .omx/plans .omx/context",
+                "rg \"Scholastic\" doc tests .omx/plans .omx/context",
+                "sed -n '1,80p' .omx/plans/demo.md",
+                "cat .omx/plans/demo.md",
+                "git status --short; ls -1 .omx/plans; grep -RIn \"Scholastic\" doc tests .omx/plans .omx/context",
+            ];
+            for (const [index, command] of readOnlyCommands.entries()) {
+                const result = await preToolUse("Bash", `tool-ralplan-read-${index}`, { command });
+                assert.equal(result.outputJson, null, `read-only command should be allowed: ${command}`);
+            }
+            for (const path of [
+                ".omx/context/findings.md",
+                ".omx/plans/issue-2863.md",
+                ".omx/specs/issue-2863.md",
+                ".omx/state/required-planning-state.json",
+            ]) {
+                const writeResult = await preToolUse("Write", `tool-ralplan-write-${path}`, { file_path: path, content: "ok" });
+                assert.equal(writeResult.outputJson, null, `Write should be allowed for ${path}`);
+            }
+            const allowedPatchAdd = await preToolUse("apply_patch", "tool-ralplan-patch-add", {
+                input: "*** Begin Patch\n*** Add File: .omx/plans/issue-2863.md\n+# Plan\n*** End Patch\n",
+            });
+            assert.equal(allowedPatchAdd.outputJson, null);
+            const allowedPatchUpdate = await preToolUse("ApplyPatch", "tool-ralplan-patch-update", {
+                input: "*** Begin Patch\n*** Update File: .omx/plans/issue-2863.md\n@@\n-old\n+new\n*** End Patch\n",
+            });
+            assert.equal(allowedPatchUpdate.outputJson, null);
+            const allowedRedirect = await preToolUse("Bash", "tool-ralplan-redirect-allow", {
+                command: "printf '\\nmore\\n' >> .omx/plans/issue-2863.md",
+            });
+            assert.equal(allowedRedirect.outputJson, null);
+            const allowedTee = await preToolUse("Bash", "tool-ralplan-tee-allow", {
+                command: "printf '\\nmore\\n' | tee -a .omx/specs/issue-2863.md",
+            });
+            assert.equal(allowedTee.outputJson, null);
+            const blockedRedirect = await preToolUse("Bash", "tool-ralplan-redirect-block", {
+                command: "printf 'bad' > src/implementation.ts",
+            });
+            assert.equal(blockedRedirect.outputJson?.decision, "block");
+            const redirectReason = String(blockedRedirect.outputJson?.reason ?? "");
+            assert.match(redirectReason, /Bash redirect write/);
+            assert.match(redirectReason, /src\/implementation\.ts/);
+            const blockedEdit = await preToolUse("Edit", "tool-ralplan-edit-block", {
+                file_path: "src/implementation.ts",
+                old_string: "a",
+                new_string: "b",
+            });
+            assert.equal(blockedEdit.outputJson?.decision, "block");
+            const editReason = String(blockedEdit.outputJson?.reason ?? "");
+            assert.match(editReason, /Edit path/);
+            assert.match(editReason, /src\/implementation\.ts/);
+            const blockedMixedPatch = await preToolUse("apply_patch", "tool-ralplan-patch-mixed", {
+                input: "*** Begin Patch\n*** Add File: .omx/plans/ok.md\n+ok\n*** Add File: src/leak.ts\n+leak\n*** End Patch\n",
+            });
+            assert.equal(blockedMixedPatch.outputJson?.decision, "block");
+            const mixedReason = String(blockedMixedPatch.outputJson?.reason ?? "");
+            assert.match(mixedReason, /apply_patch target/);
+            assert.match(mixedReason, /src\/leak\.ts/);
+            const blockedUnparseablePatch = await preToolUse("apply_patch", "tool-ralplan-patch-unparseable", {
+                input: "not a recognizable patch",
+            });
+            assert.equal(blockedUnparseablePatch.outputJson?.decision, "block");
+            assert.match(String(blockedUnparseablePatch.outputJson?.reason ?? ""), /apply_patch target extraction failed/);
+            const blockedUnresolvedRedirect = await preToolUse("Bash", "tool-ralplan-redirect-unresolved", {
+                command: "cat > \"$PLAN_PATH\" <<'EOF'\ncontent\nEOF",
+            });
+            assert.equal(blockedUnresolvedRedirect.outputJson?.decision, "block");
+            const unresolvedReason = String(blockedUnresolvedRedirect.outputJson?.reason ?? "");
+            assert.match(unresolvedReason, /unresolved Bash write target/);
+            assert.match(unresolvedReason, /\$PLAN_PATH/);
+            const blockedTraversal = await preToolUse("Write", "tool-ralplan-traversal-block", {
+                file_path: ".omx/plans/../../src/leak.ts",
+                content: "bad",
+            });
+            assert.equal(blockedTraversal.outputJson?.decision, "block");
+            assert.match(String(blockedTraversal.outputJson?.reason ?? ""), /\.omx\/plans\/\.\.\/\.\.\/src\/leak\.ts/);
+            const blockedAbsolute = await preToolUse("Write", "tool-ralplan-absolute-block", {
+                file_path: "/tmp/leak.ts",
+                content: "bad",
+            });
+            assert.equal(blockedAbsolute.outputJson?.decision, "block");
+            assert.match(String(blockedAbsolute.outputJson?.reason ?? ""), /\/tmp\/leak\.ts/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("allows Autopilot ralplan planning artifacts while blocking implementation writes", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-autopilot-ralplan-artifact-"));
         try {
@@ -5074,6 +5790,225 @@ exit 0
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("allows Ralplan Beads tracker metadata writes during planning", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-ralplan-beads-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            const sessionDir = join(stateDir, "sessions", "sess-ralplan-beads");
+            await mkdir(sessionDir, { recursive: true });
+            await writeJson(join(stateDir, "session.json"), { session_id: "sess-ralplan-beads", cwd });
+            await writeJson(join(sessionDir, "skill-active-state.json"), {
+                version: 1,
+                active: true,
+                skill: "ralplan",
+                phase: "planning",
+                session_id: "sess-ralplan-beads",
+                thread_id: "thread-ralplan-beads",
+                active_skills: [
+                    {
+                        skill: "ralplan",
+                        phase: "planning",
+                        active: true,
+                        session_id: "sess-ralplan-beads",
+                        thread_id: "thread-ralplan-beads",
+                    },
+                ],
+            });
+            await writeJson(join(sessionDir, "ralplan-state.json"), {
+                active: true,
+                mode: "ralplan",
+                current_phase: "planning",
+                session_id: "sess-ralplan-beads",
+                thread_id: "thread-ralplan-beads",
+            });
+            const allowedWrite = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-ralplan-beads",
+                thread_id: "thread-ralplan-beads",
+                tool_name: "Write",
+                tool_use_id: "tool-ralplan-beads-write",
+                tool_input: { file_path: ".beads/issues.db", content: "metadata" },
+            }, { cwd });
+            assert.equal(allowedWrite.outputJson, null);
+            const allowedEdit = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-ralplan-beads",
+                thread_id: "thread-ralplan-beads",
+                tool_name: "Edit",
+                tool_use_id: "tool-ralplan-beads-edit",
+                tool_input: { file_path: ".beads/tasks/issue.json", old_string: "old", new_string: "new" },
+            }, { cwd });
+            assert.equal(allowedEdit.outputJson, null);
+            const allowedPatch = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-ralplan-beads",
+                thread_id: "thread-ralplan-beads",
+                tool_name: "apply_patch",
+                tool_use_id: "tool-ralplan-beads-apply-patch",
+                tool_input: {
+                    input: "*** Begin Patch\n*** Add File: .beads/tasks/issue.json\n+{}\n*** End Patch\n",
+                },
+            }, { cwd });
+            assert.equal(allowedPatch.outputJson, null);
+            const allowedCommands = [
+                "bd --db .beads/issues.db create 'Issue title'",
+                "bd --db .beads/issues.db update OMX-1 --title 'Issue title'",
+                "bd --db .beads/issues.db edit OMX-1 --title 'Issue title'",
+                "bd --db .beads/issues.db comments add OMX-1 'evidence'",
+                "bd --db .beads/issues.db close OMX-1",
+                "bd --db .beads/issues.db reopen OMX-1",
+                "bd --db .beads/issues.db status OMX-1",
+                "bd --db .beads/issues.db dep add OMX-1 OMX-2",
+            ];
+            for (const [index, command] of allowedCommands.entries()) {
+                const result = await dispatchCodexNativeHook({
+                    hook_event_name: "PreToolUse",
+                    cwd,
+                    session_id: "sess-ralplan-beads",
+                    thread_id: "thread-ralplan-beads",
+                    tool_name: "Bash",
+                    tool_use_id: `tool-ralplan-beads-bd-${index}`,
+                    tool_input: { command },
+                }, { cwd });
+                assert.equal(result.outputJson, null, `expected Beads metadata command to be allowed: ${command}`);
+            }
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("blocks unsafe Beads tracker targets and mixed implementation writes during Autopilot ralplan planning", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-autopilot-beads-block-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            const sessionDir = join(stateDir, "sessions", "sess-autopilot-beads-block");
+            await mkdir(sessionDir, { recursive: true });
+            await writeJson(join(stateDir, "session.json"), { session_id: "sess-autopilot-beads-block", cwd });
+            await writeJson(join(sessionDir, "skill-active-state.json"), {
+                version: 1,
+                active: true,
+                skill: "autopilot",
+                phase: "ralplan",
+                session_id: "sess-autopilot-beads-block",
+                thread_id: "thread-autopilot-beads-block",
+                active_skills: [
+                    {
+                        skill: "autopilot",
+                        phase: "ralplan",
+                        active: true,
+                        session_id: "sess-autopilot-beads-block",
+                        thread_id: "thread-autopilot-beads-block",
+                    },
+                ],
+            });
+            await writeJson(join(sessionDir, "autopilot-state.json"), {
+                active: true,
+                mode: "autopilot",
+                current_phase: "ralplan",
+                session_id: "sess-autopilot-beads-block",
+                thread_id: "thread-autopilot-beads-block",
+            });
+            const blockedCommands = [
+                "bd --db /tmp/outside.db create 'Issue title'",
+                "bd --db ../outside.db create 'Issue title'",
+                "bd --db .beads create 'Issue title'",
+                "bd --db $DB create 'Issue title'",
+                "DB=.beads/issues.db bd --db $DB create 'Issue title'",
+                "env bd --db /tmp/outside.db create 'Issue title'",
+                "command bd --db /tmp/outside.db create 'Issue title'",
+                "bd --db .beads/issues.db export",
+                "bd --db .beads/issues.db create 'Issue title' > src/leak.ts",
+                "bd --db .beads/issues.db create 'Issue title'; cat > src/leak.ts",
+            ];
+            for (const [index, command] of blockedCommands.entries()) {
+                const result = await dispatchCodexNativeHook({
+                    hook_event_name: "PreToolUse",
+                    cwd,
+                    session_id: "sess-autopilot-beads-block",
+                    thread_id: "thread-autopilot-beads-block",
+                    tool_name: "Bash",
+                    tool_use_id: `tool-autopilot-beads-block-${index}`,
+                    tool_input: { command },
+                }, { cwd });
+                assert.equal(result.outputJson?.decision, "block", `expected unsafe Beads command to be blocked: ${command}`);
+            }
+            const mentionWithImplementationWrite = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-autopilot-beads-block",
+                thread_id: "thread-autopilot-beads-block",
+                tool_name: "Bash",
+                tool_use_id: "tool-autopilot-beads-mention-write",
+                tool_input: { command: "echo bd --db .beads/issues.db create > src/leak.ts" },
+            }, { cwd });
+            assert.equal(mentionWithImplementationWrite.outputJson?.decision, "block");
+            assert.match(String(mentionWithImplementationWrite.outputJson?.reason ?? ""), /src\/leak\.ts/);
+            const blockedImplementationEdit = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-autopilot-beads-block",
+                thread_id: "thread-autopilot-beads-block",
+                tool_name: "Edit",
+                tool_use_id: "tool-autopilot-beads-src-edit",
+                tool_input: { file_path: "src/implementation.ts", old_string: "a", new_string: "b" },
+            }, { cwd });
+            assert.equal(blockedImplementationEdit.outputJson?.decision, "block");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("allows Autopilot rework implementation writes while ralplan remains guarded", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-autopilot-rework-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            const sessionDir = join(stateDir, "sessions", "sess-autopilot-rework");
+            await mkdir(sessionDir, { recursive: true });
+            await writeJson(join(stateDir, "session.json"), { session_id: "sess-autopilot-rework", cwd });
+            await writeJson(join(sessionDir, "skill-active-state.json"), {
+                version: 1,
+                active: true,
+                skill: "autopilot",
+                phase: "rework",
+                session_id: "sess-autopilot-rework",
+                thread_id: "thread-autopilot-rework",
+                active_skills: [
+                    {
+                        skill: "autopilot",
+                        phase: "rework",
+                        active: true,
+                        session_id: "sess-autopilot-rework",
+                        thread_id: "thread-autopilot-rework",
+                    },
+                ],
+            });
+            await writeJson(join(sessionDir, "autopilot-state.json"), {
+                active: true,
+                mode: "autopilot",
+                current_phase: "rework",
+                review_cycle: 2,
+                review_verdict: { clean: false, recommendation: "REQUEST_CHANGES", findings: ["src/implementation.ts"] },
+                session_id: "sess-autopilot-rework",
+                thread_id: "thread-autopilot-rework",
+            });
+            const allowedImplementationEdit = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-autopilot-rework",
+                thread_id: "thread-autopilot-rework",
+                tool_name: "Edit",
+                tool_use_id: "tool-autopilot-rework-src-edit",
+                tool_input: { file_path: "src/implementation.ts", old_string: "a", new_string: "b" },
+            }, { cwd });
+            assert.equal(allowedImplementationEdit.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("allows null-device fd redirects while deep-interview blocks real Bash writes", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-deep-interview-null-redirect-"));
         try {
@@ -5215,6 +6150,173 @@ exit 0
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("records native subagent capacity exhaustion from spawn_agent PostToolUse output", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-subagent-capacity-record-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PostToolUse",
+                cwd,
+                session_id: "sess-subagent-capacity-record",
+                thread_id: "thread-subagent-capacity-record",
+                turn_id: "turn-subagent-capacity-record",
+                tool_name: "multi_agent_v1.spawn_agent",
+                tool_response: {
+                    error: "collab spawn failed: agent thread limit reached",
+                },
+            }, { cwd });
+            assert.equal(result.omxEventName, "post-tool-use");
+            assert.equal(result.outputJson, null);
+            const blocker = JSON.parse(await readFile(join(cwd, ".omx", "state", "native-subagent-capacity-blocker.json"), "utf-8"));
+            assert.equal(blocker.reason, "agent_thread_limit_reached");
+            assert.equal(blocker.session_id, "sess-subagent-capacity-record");
+            assert.equal(blocker.thread_id, "thread-subagent-capacity-record");
+            assert.equal(blocker.tool_name, "multi_agent_v1.spawn_agent");
+            assert.match(String(blocker.error_summary), /agent thread limit reached/);
+            assert.ok(Date.parse(String(blocker.expires_at)) > Date.parse(String(blocker.observed_at)));
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("blocks close_agent cleanup after recent native subagent capacity exhaustion", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-subagent-capacity-close-block-"));
+        try {
+            await dispatchCodexNativeHook({
+                hook_event_name: "PostToolUse",
+                cwd,
+                session_id: "sess-subagent-capacity-close-block",
+                thread_id: "thread-subagent-capacity-close-block",
+                turn_id: "turn-subagent-capacity-close-block",
+                tool_name: "multi_agent_v1.spawn_agent",
+                tool_response: "collab spawn failed: agent thread limit reached",
+            }, { cwd });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-subagent-capacity-close-block",
+                thread_id: "thread-subagent-capacity-close-block",
+                tool_name: "multi_agent_v1.close_agent",
+                tool_input: { target: "019ecc36-stale" },
+            }, { cwd });
+            assert.equal(result.omxEventName, "pre-tool-use");
+            assert.equal(result.outputJson?.decision, "block");
+            assert.match(JSON.stringify(result.outputJson), /agent thread limit reached/);
+            assert.match(JSON.stringify(result.outputJson), /multi_agent_v1\.close_agent/);
+            assert.match(JSON.stringify(result.outputJson), /multi_tool_use\.parallel/);
+            assert.match(JSON.stringify(result.outputJson), /bounded capacity blocker/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("emits schema-safe PreToolUse CLI stdout for close_agent capacity blocks", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-cli-subagent-capacity-close-block-"));
+        try {
+            parseSingleJsonStdout(runNativeHookCli({
+                hook_event_name: "PostToolUse",
+                cwd,
+                session_id: "sess-cli-subagent-capacity-close-block",
+                thread_id: "thread-cli-subagent-capacity-close-block",
+                turn_id: "turn-cli-subagent-capacity-close-block",
+                tool_name: "multi_agent_v1.spawn_agent",
+                tool_response: "collab spawn failed: agent thread limit reached",
+            }, { cwd }));
+            const output = parseSingleJsonStdout(runNativeHookCli({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-cli-subagent-capacity-close-block",
+                thread_id: "thread-cli-subagent-capacity-close-block",
+                tool_name: "multi_agent_v1.close_agent",
+                tool_input: { target: "019ecc36-stale" },
+            }, { cwd }));
+            assert.deepEqual(Object.keys(output).sort(), ["systemMessage"]);
+            assert.match(String(output.systemMessage ?? ""), /agent thread limit reached/);
+            assert.match(String(output.systemMessage ?? ""), /Do not call multi_agent_v1\.close_agent/);
+            assert.equal(output.decision, undefined);
+            assert.equal(output.hookSpecificOutput, undefined);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("blocks parallel close_agent cleanup after recent native subagent capacity exhaustion", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-subagent-capacity-parallel-close-block-"));
+        try {
+            await dispatchCodexNativeHook({
+                hook_event_name: "PostToolUse",
+                cwd,
+                session_id: "sess-subagent-capacity-parallel-close-block",
+                thread_id: "thread-subagent-capacity-parallel-close-block",
+                tool_name: "multi_agent_v1.spawn_agent",
+                tool_response: "agent thread limit reached",
+            }, { cwd });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-subagent-capacity-parallel-close-block",
+                thread_id: "thread-subagent-capacity-parallel-close-block",
+                tool_name: "multi_tool_use.parallel",
+                tool_input: {
+                    tool_uses: [
+                        { recipient_name: "multi_agent_v1.close_agent", parameters: { target: "stale-1" } },
+                        { recipient_name: "multi_agent_v1.close_agent", parameters: { target: "stale-2" } },
+                    ],
+                },
+            }, { cwd });
+            assert.equal(result.outputJson?.decision, "block");
+            assert.match(JSON.stringify(result.outputJson), /Do not call multi_agent_v1\.close_agent/);
+            assert.match(JSON.stringify(result.outputJson), /do not batch close_agent through multi_tool_use\.parallel/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("does not block close_agent without a recent native capacity blocker", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-subagent-capacity-close-no-blocker-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-subagent-capacity-close-no-blocker",
+                thread_id: "thread-subagent-capacity-close-no-blocker",
+                tool_name: "multi_agent_v1.close_agent",
+                tool_input: { target: "completed-agent" },
+            }, { cwd });
+            assert.equal(result.omxEventName, "pre-tool-use");
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("does not block close_agent when the native capacity blocker is expired", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-subagent-capacity-close-expired-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            await mkdir(stateDir, { recursive: true });
+            await writeJson(join(stateDir, "native-subagent-capacity-blocker.json"), {
+                schema_version: 1,
+                reason: "agent_thread_limit_reached",
+                session_id: "sess-subagent-capacity-close-expired",
+                error_summary: "agent thread limit reached",
+                observed_at: "2026-06-20T00:00:00.000Z",
+                expires_at: "2026-06-20T00:30:00.000Z",
+                cwd,
+            });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-subagent-capacity-close-expired",
+                thread_id: "thread-subagent-capacity-close-expired",
+                tool_name: "multi_agent_v1.close_agent",
+                tool_input: { target: "completed-agent" },
+            }, { cwd });
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("warns on PreToolUse for vague sloppy fallback implementation framing", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-slop-warn-"));
         try {