oh-my-codex 0.14.4 → 0.15.1

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

@@ -1,20 +1,49 @@
 import assert from "node:assert/strict";
 import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { chmod, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { afterEach, beforeEach, describe, it } from "node:test";
 import { buildManagedCodexHooksConfig } from "../../config/codex-hooks.js";
+import { DOCUMENT_REFRESH_EXEMPTION_PREFIX } from "../../document-refresh/enforcer.js";
 import { initTeamState, readTeamLeaderAttention, readTeamPhase, writeTeamLeaderAttention, } from "../../team/state.js";
 import { dispatchCodexNativeHook, isCodexNativeHookMainModule, mapCodexHookEventToOmxEvent, resolveSessionOwnerPidFromAncestry, } from "../codex-native-hook.js";
 import { writeSessionStart } from "../../hooks/session.js";
 import { resetTriageConfigCache } from "../../hooks/triage-config.js";
+import { executeStateOperation } from "../../state/operations.js";
+function nativeHookScriptPath() {
+    return join(process.cwd(), "dist", "scripts", "codex-native-hook.js");
+}
+function parseSingleJsonStdout(stdout) {
+    const trimmed = stdout.trim();
+    assert.notEqual(trimmed, "");
+    assert.equal(trimmed.split("\n").length, 1);
+    return JSON.parse(trimmed);
+}
+function runNativeHookCli(payload, options = {}) {
+    return execFileSync(process.execPath, [nativeHookScriptPath()], {
+        cwd: options.cwd ?? process.cwd(),
+        input: typeof payload === "string" ? payload : JSON.stringify(payload),
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+        env: options.env ?? process.env,
+    });
+}
 async function writeJson(path, value) {
     await mkdir(dirname(path), { recursive: true }).catch(() => { });
     await writeFile(path, JSON.stringify(value, null, 2));
 }
+async function writeActiveAutopilotSession(cwd, sessionId) {
+    await writeJson(join(cwd, ".omx", "state", "session.json"), {
+        session_id: sessionId,
+    });
+    await writeJson(join(cwd, ".omx", "state", "sessions", sessionId, "autopilot-state.json"), {
+        active: true,
+        current_phase: "execution",
+    });
+}
 async function writeHookCounterPlugin(cwd) {
     const markerPath = join(cwd, ".omx", "stop-hook-counter.json");
     await mkdir(join(cwd, ".omx", "hooks"), { recursive: true });
@@ -67,6 +96,9 @@ const TEAM_ENV_KEYS = [
     "OMX_TEAM_STATE_ROOT",
     "OMX_TEAM_LEADER_CWD",
     "OMX_SESSION_ID",
+    "OMX_QUESTION_RETURN_PANE",
+    "OMX_LEADER_PANE_ID",
+    "TMUX",
     "TMUX_PANE",
 ];
 const priorTeamEnv = new Map();
@@ -103,10 +135,15 @@ describe("codex native hook config", () => {
         const preToolUse = config.hooks.PreToolUse[0];
         assert.equal(preToolUse.matcher, "Bash");
         assert.match(String(preToolUse.hooks?.[0]?.command || ""), /codex-native-hook\.js"?$/);
+        assert.equal(preToolUse.hooks?.[0]?.statusMessage, undefined);
         const postToolUse = config.hooks.PostToolUse[0];
         assert.equal(postToolUse.matcher, undefined);
         assert.match(String(postToolUse.hooks?.[0]?.command || ""), /codex-native-hook\.js"?$/);
-        assert.equal(postToolUse.hooks?.[0]?.statusMessage, "Running OMX tool review");
+        assert.equal(postToolUse.hooks?.[0]?.statusMessage, undefined);
+        const userPromptSubmit = config.hooks.UserPromptSubmit[0];
+        assert.equal(userPromptSubmit.matcher, undefined);
+        assert.match(String(userPromptSubmit.hooks?.[0]?.command || ""), /codex-native-hook\.js"?$/);
+        assert.equal(userPromptSubmit.hooks?.[0]?.statusMessage, undefined);
         const stop = config.hooks.Stop[0];
         assert.equal(stop.hooks?.[0]?.timeout, 30);
     });
@@ -120,18 +157,124 @@ describe("codex native hook dispatch", () => {
         assert.equal(isCodexNativeHookMainModule(pathToFileURL("/tmp/omx native/other-script.js").href, "/tmp/omx native/codex-native-hook.js"), false);
     });
     it("emits deterministic JSON stdout when CLI stdin is malformed", () => {
-        const stdout = execFileSync(process.execPath, [join(process.cwd(), "dist", "scripts", "codex-native-hook.js")], {
-            cwd: process.cwd(),
-            input: "{",
-            encoding: "utf-8",
-            stdio: ["pipe", "pipe", "pipe"],
-        });
-        const output = JSON.parse(stdout.trim());
+        const stdout = runNativeHookCli("{");
+        const output = parseSingleJsonStdout(stdout);
         assert.equal(output.decision, "block");
         assert.equal(output.reason, "OMX native hook received malformed JSON input. Preserve runtime state, inspect the emitting hook payload yourself, and retry with valid JSON.");
         assert.equal(output.hookSpecificOutput?.hookEventName, "Unknown");
         assert.match(String(output.hookSpecificOutput?.additionalContext ?? ""), /stdin JSON parsing failed inside codex-native-hook:/);
     });
+    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 {
+            const stdout = runNativeHookCli({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: "sess-cli-stop-noop-json",
+                thread_id: "thread-cli-stop-noop-json",
+                turn_id: "turn-cli-stop-noop-json",
+            }, { cwd });
+            const output = parseSingleJsonStdout(stdout);
+            assert.deepEqual(output, {});
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("does not crash Stop hook dispatch when the exec follow-up queue is malformed", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-stop-exec-followup-corrupt-"));
+        try {
+            const session = await writeSessionStart(cwd, "sess-exec-followup-corrupt");
+            const queuePath = join(cwd, ".omx", "state", "sessions", session.session_id, "exec-followups.json");
+            await mkdir(dirname(queuePath), { recursive: true });
+            await writeFile(queuePath, '{"version":1,"records":[', "utf-8");
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: session.session_id,
+            });
+            assert.equal(result.hookEventName, "Stop");
+            assert.equal(result.outputJson, null);
+            const queueDirEntries = await readdir(dirname(queuePath));
+            assert.ok(queueDirEntries.some((entry) => entry.startsWith("exec-followups.json.corrupt-")));
+            const auditPath = join(cwd, ".omx", "logs", `exec-followups-${new Date().toISOString().slice(0, 10)}.jsonl`);
+            assert.match(await readFile(auditPath, "utf-8"), /exec_followup_queue_corrupt_recovered/);
+        }
+        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 {
+            await writeActiveAutopilotSession(cwd, "sess-cli-stop-json");
+            const stdout = runNativeHookCli({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: "sess-cli-stop-json",
+                thread_id: "thread-cli-stop-json",
+                turn_id: "turn-cli-stop-json",
+            }, { cwd });
+            const output = parseSingleJsonStdout(stdout);
+            assert.equal(output.decision, "block");
+            assert.equal(output.stopReason, "autopilot_execution");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("keeps noisy Stop hook plugin stdout out of native Stop CLI stdout", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-cli-stop-noisy-plugin-"));
+        try {
+            await writeActiveAutopilotSession(cwd, "sess-cli-stop-noisy-plugin");
+            await mkdir(join(cwd, ".omx", "hooks"), { recursive: true });
+            await writeFile(join(cwd, ".omx", "hooks", "noisy.mjs"), `export async function onHookEvent(event) {
+  if (event.event === "stop") console.log("PLUGIN_NOISE");
+}
+`, "utf-8");
+            const stdout = runNativeHookCli({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: "sess-cli-stop-noisy-plugin",
+                thread_id: "thread-cli-stop-noisy-plugin",
+                turn_id: "turn-cli-stop-noisy-plugin",
+            }, { cwd });
+            assert.doesNotMatch(stdout, /PLUGIN_NOISE/);
+            const output = parseSingleJsonStdout(stdout);
+            assert.equal(output.decision, "block");
+            assert.equal(output.stopReason, "autopilot_execution");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("emits deterministic Stop JSON stdout when Stop dispatch fails", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-cli-stop-dispatch-failure-"));
+        try {
+            const stdout = runNativeHookCli({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: "sess-cli-stop-dispatch-failure",
+                thread_id: "thread-cli-stop-dispatch-failure",
+                turn_id: "turn-cli-stop-dispatch-failure",
+            }, {
+                cwd,
+                env: {
+                    ...process.env,
+                    NODE_ENV: "test",
+                    OMX_NATIVE_HOOK_TEST_THROW_STOP_DISPATCH: "1",
+                },
+            });
+            const output = parseSingleJsonStdout(stdout);
+            assert.equal(output.decision, "block");
+            assert.equal(output.stopReason, "native_stop_dispatch_failure");
+            assert.match(String(output.reason), /failed before normal continuation handling/);
+            assert.match(String(output.systemMessage), /test-induced Stop dispatch failure/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("maps Codex events onto OMX logical surfaces", () => {
         assert.equal(mapCodexHookEventToOmxEvent("SessionStart"), "session-start");
         assert.equal(mapCodexHookEventToOmxEvent("UserPromptSubmit"), "keyword-detector");
@@ -139,7 +282,7 @@ describe("codex native hook dispatch", () => {
         assert.equal(mapCodexHookEventToOmxEvent("PostToolUse"), "post-tool-use");
         assert.equal(mapCodexHookEventToOmxEvent("Stop"), "stop");
     });
-    it("writes SessionStart state against the long-lived session owner pid and stays quiet for clean sessions", async () => {
+    it("writes SessionStart state against the long-lived session owner pid and injects environment context", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-session-start-"));
         try {
             const result = await dispatchCodexNativeHook({
@@ -151,7 +294,11 @@ describe("codex native hook dispatch", () => {
                 sessionOwnerPid: 43210,
             });
             assert.equal(result.omxEventName, "session-start");
-            assert.equal(result.outputJson, null);
+            const additionalContext = String(result.outputJson?.hookSpecificOutput?.additionalContext ?? "");
+            assert.match(additionalContext, /\[Execution environment\]/);
+            assert.match(additionalContext, /native-hook \/ Codex App outside tmux/);
+            assert.match(additionalContext, /omx team, omx hud, and omx quest(?:ion) need an attached tmux OMX CLI shell|omx team and omx hud need an attached tmux OMX CLI shell/);
+            assert.match(additionalContext, /not available from this outside-tmux surface/);
             const sessionState = JSON.parse(await readFile(join(cwd, ".omx", "state", "session.json"), "utf-8"));
             assert.equal(sessionState.session_id, "sess-start-1");
             assert.equal(sessionState.native_session_id, "sess-start-1");
@@ -203,6 +350,172 @@ describe("codex native hook dispatch", () => {
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("keeps subagent SessionStart from replacing the canonical leader session", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-subagent-session-start-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            const canonicalSessionId = "omx-leader-session";
+            const leaderNativeSessionId = "codex-leader-thread";
+            const childNativeSessionId = "codex-child-thread";
+            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, "subagent-rollout.jsonl");
+            await writeFile(transcriptPath, `${JSON.stringify({
+                type: "session_meta",
+                payload: {
+                    id: childNativeSessionId,
+                    source: {
+                        subagent: {
+                            thread_spawn: {
+                                parent_thread_id: leaderNativeSessionId,
+                                depth: 1,
+                                agent_nickname: "Hegel",
+                                agent_role: "critic",
+                            },
+                        },
+                    },
+                    agent_nickname: "Hegel",
+                    agent_role: "critic",
+                },
+            })}\n`);
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "SessionStart",
+                cwd,
+                session_id: childNativeSessionId,
+                transcript_path: transcriptPath,
+            }, { cwd, sessionOwnerPid: process.pid });
+            const sessionState = JSON.parse(await readFile(join(stateDir, "session.json"), "utf-8"));
+            assert.equal(sessionState.session_id, canonicalSessionId);
+            assert.equal(sessionState.native_session_id, leaderNativeSessionId);
+            assert.equal(existsSync(join(stateDir, "sessions", childNativeSessionId, "ralph-state.json")), false);
+            assert.ok(result.outputJson);
+            const leaderRalph = JSON.parse(await readFile(join(stateDir, "sessions", canonicalSessionId, "ralph-state.json"), "utf-8"));
+            assert.equal(leaderRalph.active, true);
+            assert.equal(leaderRalph.current_phase, "executing");
+            const tracking = JSON.parse(await readFile(join(stateDir, "subagent-tracking.json"), "utf-8"));
+            assert.equal(tracking.sessions?.[canonicalSessionId]?.leader_thread_id, leaderNativeSessionId);
+            assert.equal(tracking.sessions?.[canonicalSessionId]?.threads?.[childNativeSessionId]?.kind, "subagent");
+            assert.equal(tracking.sessions?.[canonicalSessionId]?.threads?.[childNativeSessionId]?.mode, "critic");
+            assert.equal(tracking.sessions?.[leaderNativeSessionId]?.leader_thread_id, leaderNativeSessionId);
+            assert.equal(tracking.sessions?.[leaderNativeSessionId]?.threads?.[childNativeSessionId]?.kind, "subagent");
+            assert.equal(tracking.sessions?.[leaderNativeSessionId]?.threads?.[childNativeSessionId]?.mode, "critic");
+        }
+        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",
+                                agent_role: "critic",
+                            },
+                        },
+                    },
+                    agent_nickname: "Spinoza",
+                    agent_role: "critic",
+                },
+            })}\n`);
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "SessionStart",
+                cwd,
+                session_id: childNativeSessionId,
+                transcript_path: transcriptPath,
+            }, { cwd, sessionOwnerPid: process.pid });
+            const sessionState = JSON.parse(await readFile(join(stateDir, "session.json"), "utf-8"));
+            assert.equal(sessionState.session_id, canonicalSessionId);
+            assert.equal(sessionState.native_session_id, leaderNativeSessionId);
+            assert.equal(existsSync(join(stateDir, "subagent-tracking.json")), false);
+            assert.equal(existsSync(join(stateDir, "sessions", childNativeSessionId)), false);
+            assert.equal(result.outputJson, null);
+            const leaderRalph = JSON.parse(await readFile(join(stateDir, "sessions", canonicalSessionId, "ralph-state.json"), "utf-8"));
+            assert.equal(leaderRalph.active, true);
+            assert.equal(leaderRalph.current_phase, "executing");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("describes attached tmux runtime in SessionStart context when TMUX is present", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-session-start-tmux-"));
+        process.env.TMUX = "/tmp/tmux-attached";
+        process.env.TMUX_PANE = "%11";
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "SessionStart",
+                cwd,
+                session_id: "sess-start-tmux-1",
+            }, {
+                cwd,
+                sessionOwnerPid: process.pid,
+            });
+            const additionalContext = String(result.outputJson?.hookSpecificOutput?.additionalContext ?? "");
+            assert.match(additionalContext, /\[Execution environment\]/);
+            assert.match(additionalContext, /attached tmux runtime/);
+            assert.match(additionalContext, /omx team, omx hud, and omx quest(?:ion) are directly usable in this session/);
+            assert.match(additionalContext, /visible renderer available from the current pane/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("describes direct CLI outside tmux in SessionStart context when the launch source is cli", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-session-start-cli-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "SessionStart",
+                cwd,
+                session_id: "sess-start-cli-1",
+                source: "cli",
+            }, {
+                cwd,
+                sessionOwnerPid: process.pid,
+            });
+            const additionalContext = String(result.outputJson?.hookSpecificOutput?.additionalContext ?? "");
+            assert.match(additionalContext, /\[Execution environment\]/);
+            assert.match(additionalContext, /direct CLI outside tmux/);
+            assert.doesNotMatch(additionalContext, /native-hook \/ Codex App outside tmux/);
+            assert.match(additionalContext, /omx team, omx hud, and omx quest(?:ion) need an attached tmux OMX CLI shell|omx team and omx hud need an attached tmux OMX CLI shell/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("passes the canonical OMX session id when UserPromptSubmit revives HUD", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-hud-session-revive-"));
         try {
@@ -393,6 +706,8 @@ describe("codex native hook dispatch", () => {
             assert.equal(sessionState.session_id, "codex-native-new");
             assert.equal(sessionState.native_session_id, "codex-native-new");
             const additionalContext = String(result.outputJson?.hookSpecificOutput?.additionalContext ?? "");
+            assert.match(additionalContext, /\[Execution environment\]/);
+            assert.match(additionalContext, /native-hook \/ Codex App outside tmux/);
             assert.match(additionalContext, /\[Priority notes\]/);
             assert.match(additionalContext, /Preserve durable project guidance/);
             assert.doesNotMatch(additionalContext, /stale UI rework context snapshot/);
@@ -448,6 +763,29 @@ describe("codex native hook dispatch", () => {
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("records plugin-prefixed keyword activation from UserPromptSubmit payloads", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-plugin-prefixed-"));
+        try {
+            await mkdir(join(cwd, ".omx", "state"), { recursive: true });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                session_id: "sess-plugin-1",
+                thread_id: "thread-plugin-1",
+                turn_id: "turn-plugin-1",
+                prompt: "$oh-my-codex:ralplan implement issue #1307",
+            }, { cwd });
+            assert.equal(result.omxEventName, "keyword-detector");
+            assert.equal(result.skillState?.skill, "ralplan");
+            const message = String(result.outputJson?.hookSpecificOutput?.additionalContext || "");
+            assert.match(message, /\$oh-my-codex:ralplan" -> ralplan/);
+            assert.match(message, /skill: ralplan activated and initial state initialized at \.omx\/state\/sessions\/sess-plugin-1\/ralplan-state\.json; write subsequent updates via omx_state MCP\./);
+            assert.equal(existsSync(join(cwd, ".omx", "state", "sessions", "sess-plugin-1", "ralplan-state.json")), true);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("normalizes the Korean keyboard typo for ulw during UserPromptSubmit activation", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-ulw-ko-"));
         try {
@@ -596,6 +934,29 @@ describe("codex native hook dispatch", () => {
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("clarifies that plugin-prefixed prompt-side $ralph activation does not invoke the PRD-gated CLI path", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-plugin-ralph-routing-"));
+        try {
+            await mkdir(join(cwd, ".omx", "state"), { recursive: true });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                session_id: "sess-plugin-ralph-msg",
+                thread_id: "thread-plugin-ralph-msg",
+                turn_id: "turn-plugin-ralph-msg",
+                prompt: "$oh-my-codex:ralph continue verification",
+            }, { cwd });
+            assert.equal(result.omxEventName, "keyword-detector");
+            assert.equal(result.skillState?.skill, "ralph");
+            const message = String(result.outputJson?.hookSpecificOutput?.additionalContext || "");
+            assert.match(message, /\$oh-my-codex:ralph" -> ralph/);
+            assert.match(message, /skill: ralph activated and initial state initialized at \.omx\/state\/sessions\/sess-plugin-ralph-msg\/ralph-state\.json; write subsequent updates via omx_state MCP\./);
+            assert.match(message, /Prompt-side `\$ralph` activation seeds Ralph workflow state only; it does not invoke `omx ralph`\./);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("keeps bare keep-going continuation on the active autopilot skill instead of denying with generic ralph overlap", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-autopilot-bare-continuation-"));
         try {
@@ -642,7 +1003,7 @@ describe("codex native hook dispatch", () => {
             await rm(cwd, { recursive: true, force: true });
         }
     });
-    it("clarifies that prompt-side deep-interview activation must use omx question", async () => {
+    it("clarifies outside-tmux prompt-side deep-interview activation without pretending omx question is directly available", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-deep-interview-routing-"));
         try {
             await mkdir(join(cwd, ".omx", "state"), { recursive: true });
@@ -659,19 +1020,45 @@ describe("codex native hook dispatch", () => {
             const message = String(result.outputJson?.hookSpecificOutput?.additionalContext || "");
             assert.match(message, /\$deep-interview" -> deep-interview/);
             assert.match(message, /skill: deep-interview activated and initial state initialized at \.omx\/state\/sessions\/sess-deep-interview-msg\/deep-interview-state\.json; write subsequent updates via omx_state MCP\./);
-            assert.match(message, /Deep-interview must ask each interview round via `omx question`/);
-            assert.match(message, /do not fall back to `request_user_input` or plain-text questioning/i);
-            assert.match(message, /After starting `omx question` in a background terminal, wait for that terminal to finish and read the JSON answer before continuing the interview\./);
-            assert.match(message, /If bare `omx question` is unavailable in this reused session, use the current-session CLI bridge command:/);
-            assert.match(message, /'.+' '.+dist\/cli\/omx\.js' question/);
+            assert.match(message, /Deep-interview is active, but this session is not attached to tmux/);
+            assert.match(message, /Do not invoke `omx question`, `omx hud`, or `omx team`/);
+            assert.match(message, /native structured question tool when available/);
+            assert.match(message, /ask exactly one concise plain-text question/);
+            assert.match(message, /no tmux question obligation should be created outside tmux/);
             assert.doesNotMatch(message, /OMX_QUESTION_RETURN_PANE=/);
             assert.doesNotMatch(message, /preserve the leader pane/i);
-            assert.match(message, /Stop remains blocked while a deep-interview question obligation is pending\./);
         }
         finally {
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("uses native fallback deep-interview guidance on Windows outside tmux", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-deep-interview-routing-win32-"));
+        const originalPlatform = Object.getOwnPropertyDescriptor(process, "platform");
+        try {
+            Object.defineProperty(process, "platform", { value: "win32", configurable: true });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                session_id: "sess-deep-interview-msg-win32",
+                thread_id: "thread-deep-interview-msg-win32",
+                turn_id: "turn-deep-interview-msg-win32",
+                prompt: "$deep-interview gather requirements",
+            }, { cwd });
+            assert.equal(result.omxEventName, "keyword-detector");
+            assert.equal(result.skillState?.skill, "deep-interview");
+            const message = String(result.outputJson?.hookSpecificOutput?.additionalContext || "");
+            assert.match(message, /Deep-interview is active, but this session is not attached to tmux/);
+            assert.match(message, /native structured question tool when available/);
+            assert.doesNotMatch(message, /OMX_QUESTION_RETURN_PANE=/);
+            assert.doesNotMatch(message, /current-session CLI bridge command/);
+        }
+        finally {
+            if (originalPlatform)
+                Object.defineProperty(process, "platform", originalPlatform);
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("includes leader-pane preservation guidance when a pane hint is available", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-deep-interview-pane-hint-"));
         try {
@@ -697,11 +1084,51 @@ describe("codex native hook dispatch", () => {
             assert.equal(result.omxEventName, "keyword-detector");
             assert.equal(result.skillState?.skill, "deep-interview");
             const message = String(result.outputJson?.hookSpecificOutput?.additionalContext || "");
-            assert.match(message, /OMX_QUESTION_RETURN_PANE='%77'/);
-            assert.match(message, /preserve the leader pane/i);
-            assert.match(message, /OMX_QUESTION_RETURN_PANE=%77/);
+            assert.match(message, /not attached to tmux/);
+            assert.match(message, /native structured question tool when available/);
+            assert.match(message, /tmux return bridge \(%77\) is recorded/);
+            assert.doesNotMatch(message, /current-session CLI bridge command/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("uses native fallback guidance on Windows when a pane hint is available", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-deep-interview-pane-hint-win32-"));
+        const originalPlatform = Object.getOwnPropertyDescriptor(process, "platform");
+        try {
+            Object.defineProperty(process, "platform", { value: "win32", configurable: true });
+            const sessionId = "sess-deep-interview-pane-hint-win32";
+            const sessionDir = join(cwd, ".omx", "state", "sessions", sessionId);
+            await mkdir(sessionDir, { recursive: true });
+            await writeJson(join(sessionDir, "deep-interview-state.json"), {
+                active: true,
+                mode: "deep-interview",
+                current_phase: "intent-first",
+                started_at: "2026-04-21T10:00:00.000Z",
+                updated_at: "2026-04-21T10:00:00.000Z",
+                tmux_pane_id: "%77",
+            });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                session_id: sessionId,
+                thread_id: "thread-deep-interview-pane-hint-win32",
+                turn_id: "turn-deep-interview-pane-hint-win32",
+                prompt: "$deep-interview gather requirements",
+            }, { cwd });
+            assert.equal(result.omxEventName, "keyword-detector");
+            assert.equal(result.skillState?.skill, "deep-interview");
+            const message = String(result.outputJson?.hookSpecificOutput?.additionalContext || "");
+            assert.match(message, /not attached to tmux/);
+            assert.match(message, /native structured question tool when available/);
+            assert.match(message, /tmux return bridge \(%77\) is recorded/);
+            assert.doesNotMatch(message, /OMX_QUESTION_RETURN_PANE=/);
+            assert.doesNotMatch(message, /PowerShell\/background-terminal/);
         }
         finally {
+            if (originalPlatform)
+                Object.defineProperty(process, "platform", originalPlatform);
             await rm(cwd, { recursive: true, force: true });
         }
     });
@@ -840,13 +1267,35 @@ export async function onHookEvent(event) {
             await rm(cwd, { recursive: true, force: true });
         }
     });
-    it("nudges $team prompt-submit routing toward omx team runtime usage", async () => {
-        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-team-"));
+    it("does not emit UserPromptSubmit routing context for unknown plugin-prefixed $tokens", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-unknown-plugin-token-"));
         try {
             await mkdir(join(cwd, ".omx", "state"), { recursive: true });
             const result = await dispatchCodexNativeHook({
                 hook_event_name: "UserPromptSubmit",
                 cwd,
+                session_id: "sess-unknown-plugin-1",
+                thread_id: "thread-unknown-plugin-1",
+                turn_id: "turn-unknown-plugin-1",
+                prompt: "$oh-my-codex:maer-thinking 다시 설명해봐",
+            }, { cwd });
+            assert.equal(result.omxEventName, "keyword-detector");
+            assert.equal(result.skillState, null);
+            assert.equal(result.outputJson, null);
+            assert.equal(existsSync(join(cwd, ".omx", "state", "skill-active-state.json")), false);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("denies direct $team prompt activation from Codex App/native outside tmux", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-team-native-block-"));
+        try {
+            await mkdir(join(cwd, ".omx", "state"), { recursive: true });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                source: "codex-app",
                 session_id: "sess-team-1",
                 thread_id: "thread-team-1",
                 turn_id: "turn-team-1",
@@ -854,53 +1303,125 @@ export async function onHookEvent(event) {
             }, { cwd });
             assert.equal(result.omxEventName, "keyword-detector");
             assert.equal(result.skillState?.skill, "team");
-            assert.match(JSON.stringify(result.outputJson), /skill: team activated and initial state initialized at \.omx\/state\/team-state\.json; write subsequent updates via omx_state MCP\./);
-            assert.match(JSON.stringify(result.outputJson), /Use the durable OMX team runtime via `omx team \.\.\.`/);
-            assert.match(JSON.stringify(result.outputJson), /If you need runtime syntax, run `omx team --help` yourself\./);
-            const state = JSON.parse(await readFile(join(cwd, ".omx", "state", "team-state.json"), "utf-8"));
-            assert.equal(state.mode, "team");
-            assert.equal(state.active, true);
-            assert.equal(state.current_phase, "starting");
+            assert.equal(result.skillState?.active, false);
+            assert.match(String(result.skillState?.transition_error || ""), /cannot activate the tmux-only `team` workflow directly/);
+            const message = String(result.outputJson?.hookSpecificOutput?.additionalContext ?? "");
+            assert.match(message, /denied workflow keyword "\$team" -> team/);
+            assert.match(message, /attached tmux shell first/);
+            assert.equal(existsSync(join(cwd, ".omx", "state", "team-state.json")), false);
         }
         finally {
             await rm(cwd, { recursive: true, force: true });
         }
     });
-    it("returns actionable denial guidance for unsupported workflow overlaps on prompt submit", async () => {
-        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-transition-deny-"));
+    it("still denies direct $team prompt activation from Codex App/native outside tmux when a tmux return bridge exists", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-team-native-bridge-block-"));
         try {
-            await mkdir(join(cwd, ".omx", "state"), { recursive: true });
-            await dispatchCodexNativeHook({
-                hook_event_name: "UserPromptSubmit",
-                cwd,
-                session_id: "sess-deny-1",
-                thread_id: "thread-deny-1",
-                turn_id: "turn-deny-1",
-                prompt: "$team ship this fix",
-            }, { cwd });
-            const denied = await dispatchCodexNativeHook({
+            await mkdir(join(cwd, ".omx", "state", "sessions", "sess-team-bridge"), { recursive: true });
+            await writeJson(join(cwd, ".omx", "state", "sessions", "sess-team-bridge", "ralph-state.json"), {
+                mode: "ralph",
+                active: true,
+                tmux_pane_id: "%42",
+            });
+            const result = await dispatchCodexNativeHook({
                 hook_event_name: "UserPromptSubmit",
                 cwd,
-                session_id: "sess-deny-1",
-                thread_id: "thread-deny-1",
-                turn_id: "turn-deny-2",
-                prompt: "$autopilot also run this",
+                source: "codex-app",
+                session_id: "sess-team-bridge",
+                thread_id: "thread-team-bridge",
+                turn_id: "turn-team-bridge",
+                prompt: "$team ship this fix with verification",
             }, { cwd });
-            assert.match(JSON.stringify(denied.outputJson), /denied workflow keyword/i);
-            assert.match(JSON.stringify(denied.outputJson), /Unsupported workflow overlap: team \+ autopilot\./);
-            assert.match(JSON.stringify(denied.outputJson), /`omx state clear --mode <mode>`/);
-            assert.match(JSON.stringify(denied.outputJson), /`omx_state\.\*` MCP tools/);
-            assert.equal(existsSync(join(cwd, ".omx", "state", "sessions", "sess-deny-1", "autopilot-state.json")), false);
+            assert.equal(result.omxEventName, "keyword-detector");
+            assert.equal(result.skillState?.skill, "team");
+            assert.equal(result.skillState?.active, false);
+            const message = String(result.outputJson?.hookSpecificOutput?.additionalContext ?? "");
+            assert.match(message, /attached tmux shell first/);
+            assert.equal(existsSync(join(cwd, ".omx", "state", "team-state.json")), false);
         }
         finally {
             await rm(cwd, { recursive: true, force: true });
         }
     });
-    it("surfaces transition success output for allowlisted prompt-submit handoffs", async () => {
-        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-transition-success-"));
+    it("keeps direct CLI outside-tmux $team prompt guidance compatible with manual shell launch", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-team-cli-guidance-"));
         try {
-            const sessionDir = join(cwd, ".omx", "state", "sessions", "sess-handoff-1");
-            await mkdir(sessionDir, { recursive: true });
+            await mkdir(join(cwd, ".omx", "state"), { recursive: true });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                source: "cli",
+                session_id: "sess-team-cli-guidance",
+                thread_id: "thread-team-cli-guidance",
+                turn_id: "turn-team-cli-guidance",
+                prompt: "$team ship this fix with verification",
+            }, { cwd });
+            const message = String(result.outputJson?.hookSpecificOutput?.additionalContext ?? "");
+            assert.match(message, /run `omx team \.\.\.` yourself from shell/);
+            assert.doesNotMatch(message, /not directly available here/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("keeps $team prompt-submit routing directly tmux-capable when already inside tmux", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-team-tmux-"));
+        process.env.TMUX = "/tmp/tmux-live";
+        process.env.TMUX_PANE = "%5";
+        try {
+            await mkdir(join(cwd, ".omx", "state"), { recursive: true });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                session_id: "sess-team-tmux-1",
+                thread_id: "thread-team-tmux-1",
+                turn_id: "turn-team-tmux-1",
+                prompt: "$team ship this fix with verification",
+            }, { cwd });
+            const message = String(result.outputJson?.hookSpecificOutput?.additionalContext ?? "");
+            assert.match(message, /Use the durable OMX team runtime via `omx team \.\.\.`/);
+            assert.match(message, /run `omx team --help` yourself/);
+            assert.doesNotMatch(message, /not directly available here/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("returns actionable denial guidance for unsupported workflow overlaps on prompt submit", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-transition-deny-"));
+        try {
+            await mkdir(join(cwd, ".omx", "state"), { recursive: true });
+            await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                session_id: "sess-deny-1",
+                thread_id: "thread-deny-1",
+                turn_id: "turn-deny-1",
+                prompt: "$team ship this fix",
+            }, { cwd });
+            const denied = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                session_id: "sess-deny-1",
+                thread_id: "thread-deny-1",
+                turn_id: "turn-deny-2",
+                prompt: "$autopilot also run this",
+            }, { cwd });
+            assert.match(JSON.stringify(denied.outputJson), /denied workflow keyword/i);
+            assert.match(JSON.stringify(denied.outputJson), /Unsupported workflow overlap: team \+ autopilot\./);
+            assert.match(JSON.stringify(denied.outputJson), /`omx state clear --mode <mode>`/);
+            assert.match(JSON.stringify(denied.outputJson), /`omx_state\.\*` MCP tools/);
+            assert.equal(existsSync(join(cwd, ".omx", "state", "sessions", "sess-deny-1", "autopilot-state.json")), false);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("surfaces transition success output for allowlisted prompt-submit handoffs", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-transition-success-"));
+        try {
+            const sessionDir = join(cwd, ".omx", "state", "sessions", "sess-handoff-1");
+            await mkdir(sessionDir, { recursive: true });
             await writeJson(join(sessionDir, "deep-interview-state.json"), {
                 active: true,
                 mode: "deep-interview",
@@ -955,6 +1476,30 @@ export async function onHookEvent(event) {
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("keeps the planning skill active for mixed plugin-prefixed and bare workflow invocations together", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-plugin-planning-precedence-"));
+        try {
+            await mkdir(join(cwd, ".omx", "state"), { recursive: true });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                session_id: "sess-plugin-multi-1",
+                thread_id: "thread-plugin-multi-1",
+                turn_id: "turn-plugin-multi-1",
+                prompt: "$oh-my-codex:ralplan $team $oh-my-codex:ralph ship this fix",
+            }, { cwd });
+            const message = String(result.outputJson?.hookSpecificOutput?.additionalContext || '');
+            assert.match(message, /\$oh-my-codex:ralplan" -> ralplan/);
+            assert.match(message, /\$team" -> team/);
+            assert.match(message, /\$oh-my-codex:ralph" -> ralph/);
+            assert.doesNotMatch(message, /mode transiting:/);
+            assert.match(message, /planning preserved over simultaneous execution follow-up; deferred skills: team, ralph\./);
+            assert.match(message, /skill: ralplan activated and initial state initialized at \.omx\/state\/sessions\/sess-plugin-multi-1\/ralplan-state\.json; write subsequent updates via omx_state MCP\./);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("runs prompt-submit HUD reconciliation as a best-effort tmux-only side effect", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-hud-reconcile-"));
         const originalTmux = process.env.TMUX;
@@ -1072,6 +1617,99 @@ esac
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("allows PowerShell env bridge forms for omx question return panes", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-question-powershell-allow-"));
+        try {
+            const commands = [
+                `$env:OMX_QUESTION_RETURN_PANE=$env:TMUX_PANE; omx question --json --input '{"question":"Q?","options":["A"],"allow_other":true}'`,
+                `$env:OMX_QUESTION_RETURN_PANE='%42'; node ./dist/cli/omx.js question --json --input '{"question":"Q?","options":["A"],"allow_other":true}'`,
+                `$env:OMX_LEADER_PANE_ID="%43"; omx question --json --input '{"question":"Q?","options":["A"],"allow_other":true}'`,
+            ];
+            for (const [index, command] of commands.entries()) {
+                const result = await dispatchCodexNativeHook({
+                    hook_event_name: "PreToolUse",
+                    cwd,
+                    tool_name: "Bash",
+                    tool_use_id: `tool-question-powershell-allow-${index}`,
+                    tool_input: { command },
+                }, { cwd });
+                assert.equal(result.omxEventName, "pre-tool-use");
+                assert.equal(result.outputJson, null);
+            }
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("allows Bash omx question when a valid inherited OMX_QUESTION_RETURN_PANE bridge is already exported", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-question-env-allow-"));
+        const originalReturnPane = process.env.OMX_QUESTION_RETURN_PANE;
+        try {
+            process.env.OMX_QUESTION_RETURN_PANE = "%42";
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                tool_name: "Bash",
+                tool_use_id: "tool-question-env-allow",
+                tool_input: { command: `omx question --json --input '{"question":"Q?","options":["A"],"allow_other":true}'` },
+            }, { cwd });
+            assert.equal(result.omxEventName, "pre-tool-use");
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            if (originalReturnPane === undefined)
+                delete process.env.OMX_QUESTION_RETURN_PANE;
+            else
+                process.env.OMX_QUESTION_RETURN_PANE = originalReturnPane;
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("allows Bash omx question when a valid inherited OMX_LEADER_PANE_ID bridge is already exported", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-question-leader-env-allow-"));
+        const originalLeaderPane = process.env.OMX_LEADER_PANE_ID;
+        try {
+            process.env.OMX_LEADER_PANE_ID = "%43";
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                tool_name: "Bash",
+                tool_use_id: "tool-question-leader-env-allow",
+                tool_input: { command: `omx question --json --input '{"question":"Q?","options":["A"],"allow_other":true}'` },
+            }, { cwd });
+            assert.equal(result.omxEventName, "pre-tool-use");
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            if (originalLeaderPane === undefined)
+                delete process.env.OMX_LEADER_PANE_ID;
+            else
+                process.env.OMX_LEADER_PANE_ID = originalLeaderPane;
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("still blocks Bash omx question when an inherited OMX_QUESTION_RETURN_PANE value is malformed", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-question-env-malformed-"));
+        const originalReturnPane = process.env.OMX_QUESTION_RETURN_PANE;
+        try {
+            process.env.OMX_QUESTION_RETURN_PANE = "not-a-pane";
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                tool_name: "Bash",
+                tool_use_id: "tool-question-env-malformed",
+                tool_input: { command: `omx question --json --input '{"question":"Q?","options":["A"],"allow_other":true}'` },
+            }, { cwd });
+            assert.equal(result.omxEventName, "pre-tool-use");
+            assert.equal(result.outputJson?.decision, "block");
+        }
+        finally {
+            if (originalReturnPane === undefined)
+                delete process.env.OMX_QUESTION_RETURN_PANE;
+            else
+                process.env.OMX_QUESTION_RETURN_PANE = originalReturnPane;
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("blocks Bash node omx.js question when the command does not preserve the leader-pane return hint", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-question-node-block-"));
         try {
@@ -1089,6 +1727,173 @@ esac
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("blocks native/App Bash omx question with bridge-specific outside-tmux guidance", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-question-native-block-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                source: "codex-app",
+                session_id: "sess-question-native-block",
+                tool_name: "Bash",
+                tool_use_id: "tool-question-native-block",
+                tool_input: { command: `omx question --json --input '{"question":"Q?","options":["A"],"allow_other":true}'` },
+            }, { cwd });
+            assert.equal(result.omxEventName, "pre-tool-use");
+            assert.equal(result.outputJson?.decision, "block");
+            assert.equal(result.outputJson?.hookSpecificOutput, undefined);
+            assert.match(String(result.outputJson?.reason || ""), /Codex App\/native outside-tmux Bash sessions/);
+            assert.match(String(result.outputJson?.systemMessage || ""), /native structured question tool/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("blocks native/App Bash omx question even when the command preserves a tmux return bridge", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-question-native-allow-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                source: "codex-app",
+                session_id: "sess-question-native-bridge-block",
+                tool_name: "Bash",
+                tool_use_id: "tool-question-native-bridge-block",
+                tool_input: { command: `OMX_QUESTION_RETURN_PANE=$TMUX_PANE omx question --json --input '{"question":"Q?","options":["A"],"allow_other":true}'` },
+            }, { cwd });
+            assert.equal(result.omxEventName, "pre-tool-use");
+            assert.equal(result.outputJson?.decision, "block");
+            assert.match(String(result.outputJson?.systemMessage || ""), /native structured question tool/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("blocks native/App Bash omx question when a valid inherited OMX_QUESTION_RETURN_PANE bridge is already exported", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-question-native-env-allow-"));
+        const originalReturnPane = process.env.OMX_QUESTION_RETURN_PANE;
+        try {
+            process.env.OMX_QUESTION_RETURN_PANE = "%42";
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                source: "codex-app",
+                session_id: "sess-question-native-env-allow",
+                tool_name: "Bash",
+                tool_use_id: "tool-question-native-env-allow",
+                tool_input: { command: `omx question --json --input '{"question":"Q?","options":["A"],"allow_other":true}'` },
+            }, { cwd });
+            assert.equal(result.omxEventName, "pre-tool-use");
+            assert.equal(result.outputJson?.decision, "block");
+        }
+        finally {
+            if (originalReturnPane === undefined)
+                delete process.env.OMX_QUESTION_RETURN_PANE;
+            else
+                process.env.OMX_QUESTION_RETURN_PANE = originalReturnPane;
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("blocks Bash omx hud from Codex App/native outside tmux without PreToolUse additionalContext", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-hud-native-block-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                source: "codex-app",
+                session_id: "sess-hud-native-block",
+                tool_name: "Bash",
+                tool_use_id: "tool-hud-native-block",
+                tool_input: { command: "omx hud --tmux" },
+            }, { cwd });
+            assert.equal(result.omxEventName, "pre-tool-use");
+            assert.equal(result.outputJson?.decision, "block");
+            assert.equal(result.outputJson?.hookSpecificOutput, undefined);
+            assert.match(String(result.outputJson?.systemMessage || ""), /attached tmux shell first/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("blocks Bash omx team from Codex App/native outside tmux", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-team-native-block-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                source: "codex-app",
+                session_id: "sess-team-native-block",
+                tool_name: "Bash",
+                tool_use_id: "tool-team-native-block",
+                tool_input: { command: "omx team status my-team" },
+            }, { cwd });
+            assert.equal(result.omxEventName, "pre-tool-use");
+            assert.equal(result.outputJson?.decision, "block");
+            assert.equal(result.outputJson?.hookSpecificOutput, undefined);
+            assert.match(String(result.outputJson?.reason || ""), /cannot be launched directly from Codex App\/native outside-tmux Bash sessions/);
+            assert.match(String(result.outputJson?.systemMessage || ""), /launch OMX CLI from an attached tmux shell first/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("blocks Bash node omx.js team from Codex App/native outside tmux", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-team-node-native-block-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                source: "codex-app",
+                session_id: "sess-team-node-native-block",
+                tool_name: "Bash",
+                tool_use_id: "tool-team-node-native-block",
+                tool_input: { command: "node ./dist/cli/omx.js team status my-team" },
+            }, { cwd });
+            assert.equal(result.omxEventName, "pre-tool-use");
+            assert.equal(result.outputJson?.decision, "block");
+            assert.match(String(result.outputJson?.systemMessage || ""), /Codex App\/native outside-tmux sessions/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("preserves direct CLI outside-tmux omx team Bash behavior", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-team-cli-outside-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                source: "cli",
+                session_id: "sess-team-cli-outside",
+                tool_name: "Bash",
+                tool_use_id: "tool-team-cli-outside",
+                tool_input: { command: "omx team status my-team" },
+            }, { cwd });
+            assert.equal(result.omxEventName, "pre-tool-use");
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("preserves source-less outside-tmux omx team Bash behavior when no native session evidence exists", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-team-cli-nosource-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                session_id: "sess-team-cli-nosource",
+                tool_name: "Bash",
+                tool_use_id: "tool-team-cli-nosource",
+                tool_input: { command: "omx team status my-team" },
+            }, { cwd });
+            assert.equal(result.omxEventName, "pre-tool-use");
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("returns a destructive-command caution on PreToolUse for rm -rf dist", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-danger-"));
         try {
@@ -1128,7 +1933,7 @@ esac
             await rm(cwd, { recursive: true, force: true });
         }
     });
-    it("blocks PreToolUse git commit when the inline message is not Lore-compliant", async () => {
+    it("blocks PreToolUse git commit with supported response shape when the inline message is not Lore-compliant", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-git-commit-invalid-"));
         try {
             const result = await dispatchCodexNativeHook({
@@ -1144,13 +1949,6 @@ esac
                 reason: "git commit is blocked until the inline commit message satisfies the Lore format and includes the required OmX co-author trailer.",
                 hookSpecificOutput: {
                     hookEventName: "PreToolUse",
-                    additionalContext: [
-                        "Lore-format git commit enforcement triggered.",
-                        "- Add a blank line after the subject before the narrative body.",
-                        "- Add a narrative body paragraph explaining the decision context.",
-                        "- Add at least one Lore trailer such as `Constraint:`, `Confidence:`, or `Tested:`.",
-                        "- Add the required co-author trailer: `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
-                    ].join("\n"),
                 },
                 systemMessage: [
                     "git commit is blocked until the inline commit message follows the Lore protocol and includes `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
@@ -1160,6 +1958,9 @@ esac
                     "- Add the required co-author trailer: `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
                 ].join("\n"),
             });
+            const hookSpecificOutput = result.outputJson
+                .hookSpecificOutput ?? {};
+            assert.equal("additionalContext" in hookSpecificOutput, false);
         }
         finally {
             await rm(cwd, { recursive: true, force: true });
@@ -1232,13 +2033,6 @@ esac
                 reason: "git commit is blocked until the inline commit message satisfies the Lore format and includes the required OmX co-author trailer.",
                 hookSpecificOutput: {
                     hookEventName: "PreToolUse",
-                    additionalContext: [
-                        "Lore-format git commit enforcement triggered.",
-                        "- Add a blank line after the subject before the narrative body.",
-                        "- Add a narrative body paragraph explaining the decision context.",
-                        "- Add at least one Lore trailer such as `Constraint:`, `Confidence:`, or `Tested:`.",
-                        "- Add the required co-author trailer: `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
-                    ].join("\n"),
                 },
                 systemMessage: [
                     "git commit is blocked until the inline commit message follows the Lore protocol and includes `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
@@ -1269,13 +2063,6 @@ esac
                 reason: "git commit is blocked until the inline commit message satisfies the Lore format and includes the required OmX co-author trailer.",
                 hookSpecificOutput: {
                     hookEventName: "PreToolUse",
-                    additionalContext: [
-                        "Lore-format git commit enforcement triggered.",
-                        "- Add a blank line after the subject before the narrative body.",
-                        "- Add a narrative body paragraph explaining the decision context.",
-                        "- Add at least one Lore trailer such as `Constraint:`, `Confidence:`, or `Tested:`.",
-                        "- Add the required co-author trailer: `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
-                    ].join("\n"),
                 },
                 systemMessage: [
                     "git commit is blocked until the inline commit message follows the Lore protocol and includes `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
@@ -1306,13 +2093,6 @@ esac
                 reason: "git commit is blocked until the inline commit message satisfies the Lore format and includes the required OmX co-author trailer.",
                 hookSpecificOutput: {
                     hookEventName: "PreToolUse",
-                    additionalContext: [
-                        "Lore-format git commit enforcement triggered.",
-                        "- Add a blank line after the subject before the narrative body.",
-                        "- Add a narrative body paragraph explaining the decision context.",
-                        "- Add at least one Lore trailer such as `Constraint:`, `Confidence:`, or `Tested:`.",
-                        "- Add the required co-author trailer: `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
-                    ].join("\n"),
                 },
                 systemMessage: [
                     "git commit is blocked until the inline commit message follows the Lore protocol and includes `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
@@ -1343,13 +2123,6 @@ esac
                 reason: "git commit is blocked until the inline commit message satisfies the Lore format and includes the required OmX co-author trailer.",
                 hookSpecificOutput: {
                     hookEventName: "PreToolUse",
-                    additionalContext: [
-                        "Lore-format git commit enforcement triggered.",
-                        "- Add a blank line after the subject before the narrative body.",
-                        "- Add a narrative body paragraph explaining the decision context.",
-                        "- Add at least one Lore trailer such as `Constraint:`, `Confidence:`, or `Tested:`.",
-                        "- Add the required co-author trailer: `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
-                    ].join("\n"),
                 },
                 systemMessage: [
                     "git commit is blocked until the inline commit message follows the Lore protocol and includes `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
@@ -1380,13 +2153,6 @@ esac
                 reason: "git commit is blocked until the inline commit message satisfies the Lore format and includes the required OmX co-author trailer.",
                 hookSpecificOutput: {
                     hookEventName: "PreToolUse",
-                    additionalContext: [
-                        "Lore-format git commit enforcement triggered.",
-                        "- Add a blank line after the subject before the narrative body.",
-                        "- Add a narrative body paragraph explaining the decision context.",
-                        "- Add at least one Lore trailer such as `Constraint:`, `Confidence:`, or `Tested:`.",
-                        "- Add the required co-author trailer: `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
-                    ].join("\n"),
                 },
                 systemMessage: [
                     "git commit is blocked until the inline commit message follows the Lore protocol and includes `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
@@ -1417,13 +2183,6 @@ esac
                 reason: "git commit is blocked until the inline commit message satisfies the Lore format and includes the required OmX co-author trailer.",
                 hookSpecificOutput: {
                     hookEventName: "PreToolUse",
-                    additionalContext: [
-                        "Lore-format git commit enforcement triggered.",
-                        "- Add a blank line after the subject before the narrative body.",
-                        "- Add a narrative body paragraph explaining the decision context.",
-                        "- Add at least one Lore trailer such as `Constraint:`, `Confidence:`, or `Tested:`.",
-                        "- Add the required co-author trailer: `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
-                    ].join("\n"),
                 },
                 systemMessage: [
                     "git commit is blocked until the inline commit message follows the Lore protocol and includes `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
@@ -1454,13 +2213,6 @@ esac
                 reason: "git commit is blocked until the inline commit message satisfies the Lore format and includes the required OmX co-author trailer.",
                 hookSpecificOutput: {
                     hookEventName: "PreToolUse",
-                    additionalContext: [
-                        "Lore-format git commit enforcement triggered.",
-                        "- Add a blank line after the subject before the narrative body.",
-                        "- Add a narrative body paragraph explaining the decision context.",
-                        "- Add at least one Lore trailer such as `Constraint:`, `Confidence:`, or `Tested:`.",
-                        "- Add the required co-author trailer: `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
-                    ].join("\n"),
                 },
                 systemMessage: [
                     "git commit is blocked until the inline commit message follows the Lore protocol and includes `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
@@ -1491,13 +2243,6 @@ esac
                 reason: "git commit is blocked until the inline commit message satisfies the Lore format and includes the required OmX co-author trailer.",
                 hookSpecificOutput: {
                     hookEventName: "PreToolUse",
-                    additionalContext: [
-                        "Lore-format git commit enforcement triggered.",
-                        "- Add a blank line after the subject before the narrative body.",
-                        "- Add a narrative body paragraph explaining the decision context.",
-                        "- Add at least one Lore trailer such as `Constraint:`, `Confidence:`, or `Tested:`.",
-                        "- Add the required co-author trailer: `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
-                    ].join("\n"),
                 },
                 systemMessage: [
                     "git commit is blocked until the inline commit message follows the Lore protocol and includes `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
@@ -1528,13 +2273,6 @@ esac
                 reason: "git commit is blocked until the inline commit message satisfies the Lore format and includes the required OmX co-author trailer.",
                 hookSpecificOutput: {
                     hookEventName: "PreToolUse",
-                    additionalContext: [
-                        "Lore-format git commit enforcement triggered.",
-                        "- Add a blank line after the subject before the narrative body.",
-                        "- Add a narrative body paragraph explaining the decision context.",
-                        "- Add at least one Lore trailer such as `Constraint:`, `Confidence:`, or `Tested:`.",
-                        "- Add the required co-author trailer: `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
-                    ].join("\n"),
                 },
                 systemMessage: [
                     "git commit is blocked until the inline commit message follows the Lore protocol and includes `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
@@ -1565,10 +2303,6 @@ esac
                 reason: "git commit is blocked until the inline commit message satisfies the Lore format and includes the required OmX co-author trailer.",
                 hookSpecificOutput: {
                     hookEventName: "PreToolUse",
-                    additionalContext: [
-                        "Lore-format git commit enforcement triggered.",
-                        "- Use inline `git commit -m ...` paragraphs for Lore-format commits in this path; file/editor/reuse/fixup message sources are not inspectable safely from pre-tool-use enforcement.",
-                    ].join("\n"),
                 },
                 systemMessage: [
                     "git commit is blocked until the inline commit message follows the Lore protocol and includes `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
@@ -1584,87 +2318,383 @@ esac
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-git-commit-missing-omx-coauthor-"));
         try {
             const result = await dispatchCodexNativeHook({
-                hook_event_name: "PreToolUse",
+                hook_event_name: "PreToolUse",
+                cwd,
+                tool_name: "Bash",
+                tool_use_id: "tool-git-commit-missing-omx-coauthor",
+                tool_input: {
+                    command: [
+                        'git commit',
+                        '-m "Prevent invalid history from bypassing Lore enforcement"',
+                        '-m "The native pre-tool-use hook now blocks inline git commit messages that skip Lore trailers or the required OmX co-author trailer."',
+                        '-m "Constraint: Native PreToolUse can only inspect the Bash command text"',
+                        '-m "Tested: node --test dist/scripts/__tests__/codex-native-hook.test.js"',
+                    ].join(" "),
+                },
+            }, { cwd });
+            assert.equal(result.omxEventName, "pre-tool-use");
+            assert.deepEqual(result.outputJson, {
+                decision: "block",
+                reason: "git commit is blocked until the inline commit message satisfies the Lore format and includes the required OmX co-author trailer.",
+                hookSpecificOutput: {
+                    hookEventName: "PreToolUse",
+                },
+                systemMessage: [
+                    "git commit is blocked until the inline commit message follows the Lore protocol and includes `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
+                    "- Add the required co-author trailer: `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
+                ].join("\n"),
+            });
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("stays silent on PreToolUse for Lore-compliant git commit with OmX co-author trailer", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-git-commit-valid-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                tool_name: "Bash",
+                tool_use_id: "tool-git-commit-valid",
+                tool_input: {
+                    command: [
+                        'git commit',
+                        '-m "Prevent invalid history from bypassing Lore enforcement"',
+                        '-m "The native pre-tool-use hook now blocks inline git commit messages that skip Lore trailers or the required OmX co-author trailer."',
+                        '-m "Constraint: Native PreToolUse can only inspect the Bash command text"',
+                        '-m "Tested: node --test dist/scripts/__tests__/codex-native-hook.test.js"',
+                        '-m "Co-authored-by: OmX <omx@oh-my-codex.dev>"',
+                    ].join(" "),
+                },
+            }, { cwd });
+            assert.equal(result.omxEventName, "pre-tool-use");
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("warns on PreToolUse git commit when mapped source changes lack staged docs refresh", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-document-refresh-warn-"));
+        try {
+            execFileSync("git", ["init"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["config", "user.email", "test@example.com"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["config", "user.name", "Test User"], { cwd, stdio: "ignore" });
+            await mkdir(join(cwd, "src", "scripts"), { recursive: true });
+            await writeFile(join(cwd, "src", "scripts", "codex-native-hook.ts"), "export const hook = 1;\n", "utf-8");
+            await writeFile(join(cwd, "README.md"), "base\n", "utf-8");
+            execFileSync("git", ["add", "README.md", "src/scripts/codex-native-hook.ts"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["commit", "-m", "init"], { cwd, stdio: "ignore" });
+            await writeFile(join(cwd, "src", "scripts", "codex-native-hook.ts"), "export const hook = 2;\n", "utf-8");
+            execFileSync("git", ["add", "src/scripts/codex-native-hook.ts"], { cwd, stdio: "ignore" });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                tool_name: "Bash",
+                tool_use_id: "tool-git-commit-doc-refresh-warn",
+                tool_input: {
+                    command: [
+                        'git commit',
+                        '-m "Keep native hooks aligned with docs"',
+                        '-m "Update the stop hook internals without refreshing the operator docs yet."',
+                        '-m "Constraint: native hook warning MVP must remain non-blocking on commit path"',
+                        '-m "Tested: node --test dist/scripts/__tests__/codex-native-hook.test.js"',
+                        '-m "Co-authored-by: OmX <omx@oh-my-codex.dev>"',
+                    ].join(" "),
+                },
+            }, { cwd });
+            assert.equal(result.omxEventName, "pre-tool-use");
+            assert.equal(result.outputJson?.decision, undefined);
+            assert.equal(result.outputJson?.hookSpecificOutput?.hookEventName, "PreToolUse");
+            assert.match(JSON.stringify(result.outputJson), /Document-refresh warning/);
+            assert.match(JSON.stringify(result.outputJson), /docs\/codex-native-hooks\.md/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("does not warn on PreToolUse when relevant docs are staged", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-document-refresh-docs-"));
+        try {
+            await mkdir(join(cwd, "src", "scripts"), { recursive: true });
+            await mkdir(join(cwd, "docs"), { recursive: true });
+            execFileSync("git", ["init"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["config", "user.email", "test@example.com"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["config", "user.name", "Test User"], { cwd, stdio: "ignore" });
+            await writeFile(join(cwd, "src", "scripts", "codex-native-hook.ts"), "export const hook = 1;\n", "utf-8");
+            await writeFile(join(cwd, "docs", "codex-native-hooks.md"), "initial\n", "utf-8");
+            execFileSync("git", ["add", "src/scripts/codex-native-hook.ts", "docs/codex-native-hooks.md"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["commit", "-m", "init"], { cwd, stdio: "ignore" });
+            await writeFile(join(cwd, "src", "scripts", "codex-native-hook.ts"), "export const hook = 2;\n", "utf-8");
+            await writeFile(join(cwd, "docs", "codex-native-hooks.md"), "updated\n", "utf-8");
+            execFileSync("git", ["add", "src/scripts/codex-native-hook.ts", "docs/codex-native-hooks.md"], { cwd, stdio: "ignore" });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                tool_name: "Bash",
+                tool_use_id: "tool-git-commit-doc-refresh-docs",
+                tool_input: {
+                    command: [
+                        'git commit',
+                        '-m "Keep native hooks aligned with docs"',
+                        '-m "Update the stop hook internals and refresh the native hook docs together."',
+                        '-m "Constraint: native hook warning MVP must remain non-blocking on commit path"',
+                        '-m "Tested: node --test dist/scripts/__tests__/codex-native-hook.test.js"',
+                        '-m "Co-authored-by: OmX <omx@oh-my-codex.dev>"',
+                    ].join(" "),
+                },
+            }, { cwd });
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("does not run commit-path document-refresh against payload cwd when git -C targets another repo", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-document-refresh-chdir-"));
+        const otherRepo = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-document-refresh-other-"));
+        try {
+            await mkdir(join(cwd, "src", "scripts"), { recursive: true });
+            execFileSync("git", ["init"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["config", "user.email", "test@example.com"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["config", "user.name", "Test User"], { cwd, stdio: "ignore" });
+            await writeFile(join(cwd, "src", "scripts", "codex-native-hook.ts"), "export const hook = 1;\n", "utf-8");
+            execFileSync("git", ["add", "src/scripts/codex-native-hook.ts"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["commit", "-m", "init"], { cwd, stdio: "ignore" });
+            await writeFile(join(cwd, "src", "scripts", "codex-native-hook.ts"), "export const hook = 2;\n", "utf-8");
+            execFileSync("git", ["add", "src/scripts/codex-native-hook.ts"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["init"], { cwd: otherRepo, stdio: "ignore" });
+            execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: otherRepo, stdio: "ignore" });
+            execFileSync("git", ["config", "user.name", "Test User"], { cwd: otherRepo, stdio: "ignore" });
+            await writeFile(join(otherRepo, "README.md"), "base\n", "utf-8");
+            execFileSync("git", ["add", "README.md"], { cwd: otherRepo, stdio: "ignore" });
+            execFileSync("git", ["commit", "-m", "init"], { cwd: otherRepo, stdio: "ignore" });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                tool_name: "Bash",
+                tool_use_id: "tool-git-commit-doc-refresh-chdir",
+                tool_input: {
+                    command: [
+                        `git -C ${JSON.stringify(otherRepo)}`,
+                        'commit',
+                        '-m "Keep native hooks aligned with docs"',
+                        '-m "Document-refresh check should not inspect the caller cwd when commit targets another repo."',
+                        '-m "Constraint: alternate git targets are skipped unless hook-side repo resolution is added explicitly"',
+                        '-m "Tested: node --test dist/scripts/__tests__/codex-native-hook.test.js"',
+                        '-m "Co-authored-by: OmX <omx@oh-my-codex.dev>"',
+                    ].join(" "),
+                },
+            }, { cwd });
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+            await rm(otherRepo, { recursive: true, force: true });
+        }
+    });
+    it("suppresses PreToolUse document-refresh warning when commit message includes an exemption", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-document-refresh-exempt-"));
+        try {
+            await mkdir(join(cwd, "src", "scripts"), { recursive: true });
+            execFileSync("git", ["init"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["config", "user.email", "test@example.com"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["config", "user.name", "Test User"], { cwd, stdio: "ignore" });
+            await writeFile(join(cwd, "src", "scripts", "codex-native-hook.ts"), "export const hook = 1;\n", "utf-8");
+            execFileSync("git", ["add", "src/scripts/codex-native-hook.ts"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["commit", "-m", "init"], { cwd, stdio: "ignore" });
+            await writeFile(join(cwd, "src", "scripts", "codex-native-hook.ts"), "export const hook = 2;\n", "utf-8");
+            execFileSync("git", ["add", "src/scripts/codex-native-hook.ts"], { cwd, stdio: "ignore" });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                tool_name: "Bash",
+                tool_use_id: "tool-git-commit-doc-refresh-exempt",
+                tool_input: {
+                    command: [
+                        'git commit',
+                        '-m "Keep native hooks aligned with docs"',
+                        '-m "Update the stop hook internals without docs refresh because behavior is internal-only."',
+                        '-m "Constraint: native hook warning MVP must remain non-blocking on commit path"',
+                        `-m "${DOCUMENT_REFRESH_EXEMPTION_PREFIX} internal-only behavior verified"`,
+                        '-m "Tested: node --test dist/scripts/__tests__/codex-native-hook.test.js"',
+                        '-m "Co-authored-by: OmX <omx@oh-my-codex.dev>"',
+                    ].join(" "),
+                },
+            }, { cwd });
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("returns PostToolUse remediation guidance for command-not-found output", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-posttool-failure-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PostToolUse",
+                cwd,
+                tool_name: "Bash",
+                tool_use_id: "tool-fail",
+                tool_input: { command: "foo --version" },
+                tool_response: "{\"exit_code\":127,\"stdout\":\"\",\"stderr\":\"bash: foo: command not found\"}",
+            }, { cwd });
+            assert.equal(result.omxEventName, "post-tool-use");
+            assert.deepEqual(result.outputJson, {
+                decision: "block",
+                reason: "The Bash output indicates a command/setup failure that should be fixed before retrying.",
+                hookSpecificOutput: {
+                    hookEventName: "PostToolUse",
+                    additionalContext: "Bash reported `command not found`, `permission denied`, or a missing file/path. Verify the command, dependency installation, PATH, file permissions, and referenced paths before retrying.",
+                },
+            });
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("stays silent when successful search output contains old Bash failure text", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-posttool-successful-search-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PostToolUse",
+                cwd,
+                tool_name: "Bash",
+                tool_use_id: "tool-search-log",
+                tool_input: { command: "rg 'command not found' .omx/logs" },
+                tool_response: JSON.stringify({
+                    exit_code: 0,
+                    stdout: "old-session.log: bash: foo: command not found",
+                    stderr: "",
+                }),
+            }, { cwd });
+            assert.equal(result.omxEventName, "post-tool-use");
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("stays silent when Bash stdout only contains failure-like source text", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-posttool-failure-source-text-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PostToolUse",
+                cwd,
+                tool_name: "Bash",
+                tool_use_id: "tool-source-text",
+                tool_input: { command: "sed -n '1,40p' hook-source.ts" },
+                tool_response: "const text = 'bash: foo: command not found';\nconst detail = 'permission denied';",
+            }, { cwd });
+            assert.equal(result.omxEventName, "post-tool-use");
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("stays silent for rc-zero build logs that mention missing grep paths", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-posttool-build-log-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PostToolUse",
+                cwd,
+                tool_name: "Bash",
+                tool_use_id: "tool-build-log",
+                tool_input: { command: "npm run build" },
+                tool_response: JSON.stringify({
+                    exit_code: 0,
+                    stdout: "build passed\nnote: grep fixture says no such file or directory",
+                    stderr: "",
+                }),
+            }, { cwd });
+            assert.equal(result.omxEventName, "post-tool-use");
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("does not treat Bash output containing MCP transport text as MCP transport death", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-posttool-mcp-source-text-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PostToolUse",
+                cwd,
+                tool_name: "Bash",
+                tool_use_id: "tool-mcp-source-text",
+                tool_input: { command: "sed -n '580,620p' codex-native-pre-post.ts" },
+                tool_response: JSON.stringify({
+                    exit_code: 0,
+                    stdout: "reason: 'MCP transport closed before response over stdio pipe closed'",
+                    stderr: "",
+                }),
+            }, { cwd });
+            assert.equal(result.omxEventName, "post-tool-use");
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("stays silent when successful output includes prior hook context text", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-posttool-recursive-context-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PostToolUse",
                 cwd,
                 tool_name: "Bash",
-                tool_use_id: "tool-git-commit-missing-omx-coauthor",
-                tool_input: {
-                    command: [
-                        'git commit',
-                        '-m "Prevent invalid history from bypassing Lore enforcement"',
-                        '-m "The native pre-tool-use hook now blocks inline git commit messages that skip Lore trailers or the required OmX co-author trailer."',
-                        '-m "Constraint: Native PreToolUse can only inspect the Bash command text"',
-                        '-m "Tested: node --test dist/scripts/__tests__/codex-native-hook.test.js"',
-                    ].join(" "),
-                },
+                tool_use_id: "tool-hook-context",
+                tool_input: { command: "cat transcript.txt" },
+                tool_response: JSON.stringify({
+                    exit_code: 0,
+                    stdout: "Bash reported `command not found`, `permission denied`, or a missing file/path. Verify the command, dependency installation, PATH, file permissions, and referenced paths before retrying.",
+                    stderr: "",
+                }),
             }, { cwd });
-            assert.equal(result.omxEventName, "pre-tool-use");
-            assert.deepEqual(result.outputJson, {
-                decision: "block",
-                reason: "git commit is blocked until the inline commit message satisfies the Lore format and includes the required OmX co-author trailer.",
-                hookSpecificOutput: {
-                    hookEventName: "PreToolUse",
-                    additionalContext: [
-                        "Lore-format git commit enforcement triggered.",
-                        "- Add the required co-author trailer: `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
-                    ].join("\n"),
-                },
-                systemMessage: [
-                    "git commit is blocked until the inline commit message follows the Lore protocol and includes `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
-                    "- Add the required co-author trailer: `Co-authored-by: OmX <omx@oh-my-codex.dev>`.",
-                ].join("\n"),
-            });
+            assert.equal(result.omxEventName, "post-tool-use");
+            assert.equal(result.outputJson, null);
         }
         finally {
             await rm(cwd, { recursive: true, force: true });
         }
     });
-    it("stays silent on PreToolUse for Lore-compliant git commit with OmX co-author trailer", async () => {
-        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-git-commit-valid-"));
+    it("stays silent when successful Bash output quotes MCP transport warnings", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-posttool-bash-mcp-quote-"));
         try {
             const result = await dispatchCodexNativeHook({
-                hook_event_name: "PreToolUse",
+                hook_event_name: "PostToolUse",
                 cwd,
                 tool_name: "Bash",
-                tool_use_id: "tool-git-commit-valid",
-                tool_input: {
-                    command: [
-                        'git commit',
-                        '-m "Prevent invalid history from bypassing Lore enforcement"',
-                        '-m "The native pre-tool-use hook now blocks inline git commit messages that skip Lore trailers or the required OmX co-author trailer."',
-                        '-m "Constraint: Native PreToolUse can only inspect the Bash command text"',
-                        '-m "Tested: node --test dist/scripts/__tests__/codex-native-hook.test.js"',
-                        '-m "Co-authored-by: OmX <omx@oh-my-codex.dev>"',
-                    ].join(" "),
-                },
+                tool_use_id: "tool-bash-mcp-quote",
+                tool_input: { command: "cat diagnostic-log.txt" },
+                tool_response: JSON.stringify({
+                    exit_code: 0,
+                    stdout: "diagnostic log quoted: MCP transport closed; stdio pipe closed before response",
+                    stderr: "",
+                }),
             }, { cwd });
-            assert.equal(result.omxEventName, "pre-tool-use");
+            assert.equal(result.omxEventName, "post-tool-use");
             assert.equal(result.outputJson, null);
         }
         finally {
             await rm(cwd, { recursive: true, force: true });
         }
     });
-    it("returns PostToolUse remediation guidance for command-not-found output", async () => {
-        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-posttool-failure-"));
+    it("stays silent when Bash hard-failure text has no parsed exit code", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-posttool-bash-unparsed-failure-"));
         try {
             const result = await dispatchCodexNativeHook({
                 hook_event_name: "PostToolUse",
                 cwd,
                 tool_name: "Bash",
-                tool_use_id: "tool-fail",
-                tool_input: { command: "foo --version" },
-                tool_response: "{\"exit_code\":127,\"stdout\":\"\",\"stderr\":\"bash: foo: command not found\"}",
+                tool_use_id: "tool-bash-unparsed-failure",
+                tool_input: { command: "cat captured-output.txt" },
+                tool_response: "captured transcript says: bash: foo: command not found",
             }, { cwd });
             assert.equal(result.omxEventName, "post-tool-use");
-            assert.deepEqual(result.outputJson, {
-                decision: "block",
-                reason: "The Bash output indicates a command/setup failure that should be fixed before retrying.",
-                hookSpecificOutput: {
-                    hookEventName: "PostToolUse",
-                    additionalContext: "Bash reported `command not found`, `permission denied`, or a missing file/path. Verify the command, dependency installation, PATH, file permissions, and referenced paths before retrying.",
-                },
-            });
+            assert.equal(result.outputJson, null);
         }
         finally {
             await rm(cwd, { recursive: true, force: true });
@@ -2116,7 +3146,17 @@ esac
         const prevLeaderCwd = process.env.OMX_TEAM_LEADER_CWD;
         try {
             await initTeamState("worker-stop-team", "worker stop fallback", "executor", 1, cwd, undefined, { ...process.env, OMX_SESSION_ID: "sess-stop-team-worker" });
+            const workerCwd = join(cwd, ".omx", "team", "worker-stop-team", "worktrees", "worker-1");
             const workerDir = join(cwd, ".omx", "state", "team", "worker-stop-team", "workers", "worker-1");
+            await mkdir(workerCwd, { recursive: true });
+            await writeJson(join(workerDir, "identity.json"), {
+                name: "worker-1",
+                index: 1,
+                role: "executor",
+                assigned_tasks: ["1"],
+                worktree_path: workerCwd,
+                team_state_root: join(cwd, ".omx", "state"),
+            });
             await writeJson(join(workerDir, "status.json"), {
                 state: "idle",
                 current_task_id: "1",
@@ -2135,9 +3175,9 @@ esac
             process.env.OMX_TEAM_LEADER_CWD = cwd;
             const result = await dispatchCodexNativeHook({
                 hook_event_name: "Stop",
-                cwd: join(cwd, ".omx", "team", "worker-stop-team", "worktrees", "worker-1"),
+                cwd: workerCwd,
                 session_id: "sess-stop-team-worker",
-            }, { cwd: join(cwd, ".omx", "team", "worker-stop-team", "worktrees", "worker-1") });
+            }, { cwd: workerCwd });
             assert.deepEqual(result.outputJson, {
                 decision: "block",
                 reason: "OMX team worker worker-1 is still assigned non-terminal task 1 (in_progress); continue the current assigned task or report a concrete blocker before stopping.",
@@ -2161,6 +3201,79 @@ esac
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("suppresses identical team worker Stop replays but re-blocks fresh turns and task state changes", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-team-worker-repeat-"));
+        try {
+            await initTeamState("worker-repeat-team", "worker stop repeat guard", "executor", 1, cwd, undefined, { ...process.env, OMX_SESSION_ID: "sess-stop-team-worker-repeat" });
+            const stateDir = join(cwd, ".omx", "state");
+            const workerDir = join(stateDir, "team", "worker-repeat-team", "workers", "worker-1");
+            const taskPath = join(stateDir, "team", "worker-repeat-team", "tasks", "task-1.json");
+            const workerCwd = join(cwd, ".omx", "team", "worker-repeat-team", "worktrees", "worker-1");
+            await mkdir(workerCwd, { recursive: true });
+            await writeJson(join(workerDir, "identity.json"), {
+                name: "worker-1",
+                index: 1,
+                role: "executor",
+                assigned_tasks: ["1"],
+                worktree_path: workerCwd,
+                team_state_root: stateDir,
+            });
+            await writeJson(join(workerDir, "status.json"), {
+                state: "idle",
+                current_task_id: "1",
+                updated_at: new Date().toISOString(),
+            });
+            await writeJson(taskPath, {
+                id: "1",
+                subject: "hook task",
+                description: "finish hook task",
+                status: "in_progress",
+                owner: "worker-1",
+                created_at: new Date().toISOString(),
+            });
+            process.env.OMX_TEAM_WORKER = "worker-repeat-team/worker-1";
+            process.env.OMX_TEAM_STATE_ROOT = stateDir;
+            process.env.OMX_TEAM_LEADER_CWD = cwd;
+            const basePayload = {
+                hook_event_name: "Stop",
+                cwd: workerCwd,
+                session_id: "sess-stop-team-worker-repeat",
+                thread_id: "thread-stop-team-worker-repeat",
+                turn_id: "turn-stop-team-worker-repeat-1",
+                last_assistant_message: "I need to stop before this task is done.",
+            };
+            const expectedInProgress = {
+                decision: "block",
+                reason: "OMX team worker worker-1 is still assigned non-terminal task 1 (in_progress); continue the current assigned task or report a concrete blocker before stopping.",
+                stopReason: "team_worker_worker-1_1_in_progress",
+                systemMessage: "OMX team worker worker-1 is still assigned task 1 (in_progress).",
+            };
+            const first = await dispatchCodexNativeHook(basePayload, { cwd: workerCwd });
+            const replay = await dispatchCodexNativeHook({ ...basePayload, stop_hook_active: true }, { cwd: workerCwd });
+            const freshTurn = await dispatchCodexNativeHook({ ...basePayload, turn_id: "turn-stop-team-worker-repeat-2", stop_hook_active: true }, { cwd: workerCwd });
+            await writeJson(taskPath, {
+                id: "1",
+                subject: "hook task",
+                description: "finish hook task",
+                status: "blocked",
+                owner: "worker-1",
+                created_at: new Date().toISOString(),
+            });
+            const stateChanged = await dispatchCodexNativeHook({ ...basePayload, turn_id: "turn-stop-team-worker-repeat-2", stop_hook_active: true }, { cwd: workerCwd });
+            assert.deepEqual(first.outputJson, expectedInProgress);
+            assert.deepEqual(replay.outputJson, null);
+            assert.deepEqual(freshTurn.outputJson, expectedInProgress);
+            assert.deepEqual(stateChanged.outputJson, {
+                decision: "block",
+                reason: "OMX team worker worker-1 is still assigned non-terminal task 1 (blocked); continue the current assigned task or report a concrete blocker before stopping.",
+                stopReason: "team_worker_worker-1_1_blocked",
+                systemMessage: "OMX team worker worker-1 is still assigned task 1 (blocked).",
+            });
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("does not block Stop for a team worker when assigned task is terminal", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-team-worker-terminal-"));
         const prevTeamWorker = process.env.OMX_TEAM_WORKER;
@@ -2280,6 +3393,38 @@ esac
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("honors terminal team run-state before later canonical-team Stop fallback", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-team-terminal-run-state-canonical-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            const sessionId = "sess-stop-team-terminal-run-state";
+            await initTeamState("terminal-run-state-team", "terminal team stop canonical fallback regression", "executor", 1, cwd, undefined, { ...process.env, OMX_SESSION_ID: sessionId });
+            await mkdir(join(stateDir, "sessions", sessionId), { recursive: true });
+            await writeJson(join(stateDir, "session.json"), { session_id: sessionId, cwd });
+            await writeJson(join(stateDir, "sessions", sessionId, "run-state.json"), {
+                version: 1,
+                mode: "team",
+                active: false,
+                outcome: "finish",
+                lifecycle_outcome: "finished",
+                current_phase: "complete",
+                completed_at: "2026-04-27T12:00:00.000Z",
+                updated_at: "2026-04-27T12:00:00.000Z",
+            });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: sessionId,
+                thread_id: "thread-stop-team-terminal-run-state",
+                turn_id: "turn-stop-team-terminal-run-state-1",
+            }, { cwd });
+            assert.equal(result.omxEventName, "stop");
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("re-fires canonical-team Stop output for a later fresh Stop reply when coarse mode state is missing", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-team-canonical-refire-"));
         try {
@@ -3072,6 +4217,105 @@ esac
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("returns a non-blocking Stop document-refresh warning before auto-nudge when Ralph is not active", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-document-refresh-"));
+        try {
+            await mkdir(join(cwd, "src", "scripts"), { recursive: true });
+            execFileSync("git", ["init"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["config", "user.email", "test@example.com"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["config", "user.name", "Test User"], { cwd, stdio: "ignore" });
+            await writeFile(join(cwd, "src", "scripts", "codex-native-hook.ts"), "export const hook = 1;\n", "utf-8");
+            execFileSync("git", ["add", "src/scripts/codex-native-hook.ts"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["commit", "-m", "init"], { cwd, stdio: "ignore" });
+            await writeFile(join(cwd, "src", "scripts", "codex-native-hook.ts"), "export const hook = 2;\n", "utf-8");
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: "sess-stop-doc-refresh",
+                last_assistant_message: "Launch-ready: yes",
+            }, { cwd });
+            assert.equal(result.omxEventName, "stop");
+            assert.equal(result.outputJson?.decision, undefined);
+            assert.equal(result.outputJson?.hookSpecificOutput?.hookEventName, "Stop");
+            assert.match(JSON.stringify(result.outputJson), /Document-refresh warning/);
+            assert.match(JSON.stringify(result.outputJson), /staged \+ unstaged changes/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("does not warn on ordinary non-terminal Stop attempts before auto-nudge", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-document-refresh-nonterminal-"));
+        try {
+            await mkdir(join(cwd, "src", "scripts"), { recursive: true });
+            execFileSync("git", ["init"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["config", "user.email", "test@example.com"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["config", "user.name", "Test User"], { cwd, stdio: "ignore" });
+            await writeFile(join(cwd, "src", "scripts", "codex-native-hook.ts"), "export const hook = 1;\n", "utf-8");
+            execFileSync("git", ["add", "src/scripts/codex-native-hook.ts"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["commit", "-m", "init"], { cwd, stdio: "ignore" });
+            await writeFile(join(cwd, "src", "scripts", "codex-native-hook.ts"), "export const hook = 2;\n", "utf-8");
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: "sess-stop-doc-refresh-nonterminal",
+                last_assistant_message: "Continuing implementation; next I will run focused tests.",
+            }, { cwd });
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("dedupes identical Stop document-refresh warnings during active Stop-hook replays", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-document-refresh-dedupe-"));
+        try {
+            await mkdir(join(cwd, "src", "scripts"), { recursive: true });
+            execFileSync("git", ["init"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["config", "user.email", "test@example.com"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["config", "user.name", "Test User"], { cwd, stdio: "ignore" });
+            await writeFile(join(cwd, "src", "scripts", "codex-native-hook.ts"), "export const hook = 1;\n", "utf-8");
+            execFileSync("git", ["add", "src/scripts/codex-native-hook.ts"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["commit", "-m", "init"], { cwd, stdio: "ignore" });
+            await writeFile(join(cwd, "src", "scripts", "codex-native-hook.ts"), "export const hook = 2;\n", "utf-8");
+            const payload = {
+                hook_event_name: "Stop",
+                cwd,
+                session_id: "sess-stop-doc-refresh-dedupe",
+                last_assistant_message: "Launch-ready: yes",
+            };
+            const first = await dispatchCodexNativeHook(payload, { cwd });
+            const replay = await dispatchCodexNativeHook({ ...payload, stop_hook_active: true }, { cwd });
+            assert.match(JSON.stringify(first.outputJson), /Document-refresh warning/);
+            assert.equal(replay.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("suppresses Stop document-refresh warning when the final handoff message includes an exemption", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-document-refresh-exempt-"));
+        try {
+            await mkdir(join(cwd, "src", "scripts"), { recursive: true });
+            execFileSync("git", ["init"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["config", "user.email", "test@example.com"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["config", "user.name", "Test User"], { cwd, stdio: "ignore" });
+            await writeFile(join(cwd, "src", "scripts", "codex-native-hook.ts"), "export const hook = 1;\n", "utf-8");
+            execFileSync("git", ["add", "src/scripts/codex-native-hook.ts"], { cwd, stdio: "ignore" });
+            execFileSync("git", ["commit", "-m", "init"], { cwd, stdio: "ignore" });
+            await writeFile(join(cwd, "src", "scripts", "codex-native-hook.ts"), "export const hook = 2;\n", "utf-8");
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: "sess-stop-doc-refresh-exempt",
+                last_assistant_message: `${DOCUMENT_REFRESH_EXEMPTION_PREFIX} internal-only behavior verified`,
+            }, { cwd });
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("returns Stop continuation output while Ralph is active without an explicit session pin", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-"));
         try {
@@ -3088,9 +4332,9 @@ esac
             assert.equal(result.omxEventName, "stop");
             assert.deepEqual(result.outputJson, {
                 decision: "block",
-                reason: "OMX Ralph is still active (phase: executing); continue the task and gather fresh verification evidence before stopping.",
+                reason: "OMX Ralph is still active (phase: executing; state: .omx/state/ralph-state.json); continue the task and gather fresh verification evidence before stopping.",
                 stopReason: "ralph_executing",
-                systemMessage: "OMX Ralph is still active (phase: executing); continue the task and gather fresh verification evidence before stopping.",
+                systemMessage: "OMX Ralph is still active (phase: executing; state: .omx/state/ralph-state.json); continue the task and gather fresh verification evidence before stopping.",
             });
         }
         finally {
@@ -3116,9 +4360,9 @@ esac
             assert.equal(result.omxEventName, "stop");
             assert.deepEqual(result.outputJson, {
                 decision: "block",
-                reason: "OMX Ralph is still active (phase: executing); continue the task and gather fresh verification evidence before stopping.",
+                reason: "OMX Ralph is still active (phase: executing; state: .omx/state/sessions/sess-live-ralph/ralph-state.json); continue the task and gather fresh verification evidence before stopping.",
                 stopReason: "ralph_executing",
-                systemMessage: "OMX Ralph is still active (phase: executing); continue the task and gather fresh verification evidence before stopping.",
+                systemMessage: "OMX Ralph is still active (phase: executing; state: .omx/state/sessions/sess-live-ralph/ralph-state.json); continue the task and gather fresh verification evidence before stopping.",
             });
         }
         finally {
@@ -3143,48 +4387,138 @@ esac
                 session_id: "sess-current",
             }, { cwd });
             assert.equal(result.omxEventName, "stop");
-            assert.equal(result.outputJson, null);
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("does not block Stop from stale current-session Ralph state when session.json points to a dead owner", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-stale-current-session-ralph-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            await mkdir(join(stateDir, "sessions", "sess-dead"), { recursive: true });
+            await writeJson(join(stateDir, "session.json"), {
+                session_id: "sess-dead",
+                cwd,
+                pid: Number.MAX_SAFE_INTEGER,
+                started_at: "2026-01-01T00:00:00.000Z",
+            });
+            await writeJson(join(stateDir, "sessions", "sess-dead", "ralph-state.json"), {
+                active: true,
+                current_phase: "verifying",
+                session_id: "sess-dead",
+            });
+            await writeJson(join(stateDir, "skill-active-state.json"), {
+                active: true,
+                skill: "team",
+                phase: "team-exec",
+                active_skills: [{ skill: "team", phase: "team-exec", active: true, session_id: "sess-dead" }],
+            });
+            await writeJson(join(stateDir, "native-stop-state.json"), {
+                sessions: {
+                    "sess-dead": {
+                        last_signature: "ralph-stop|sess-dead|thread-1|no-message|verifying",
+                        updated_at: "2026-04-20T21:00:00.000Z",
+                    },
+                },
+            });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: "sess-dead",
+                thread_id: "thread-1",
+                stop_hook_active: true,
+            }, { cwd });
+            assert.equal(result.omxEventName, "stop");
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("does not hard-block Stop on stale session-scoped Ralph starting state after visible active modes are cleared", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-cleared-stale-ralph-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            const sessionId = "sess-cleared-ralph";
+            await mkdir(join(stateDir, "sessions", sessionId), { recursive: true });
+            await writeJson(join(stateDir, "sessions", sessionId, "ralph-state.json"), {
+                active: true,
+                mode: "ralph",
+                current_phase: "starting",
+                session_id: sessionId,
+            });
+            await writeJson(join(stateDir, "skill-active-state.json"), {
+                active: false,
+                skill: "ralph",
+                active_skills: [],
+            });
+            const listActive = await executeStateOperation("state_list_active", {
+                workingDirectory: cwd,
+            });
+            assert.deepEqual(listActive.payload, { active_modes: [] });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: sessionId,
+            }, { cwd });
+            assert.equal(result.omxEventName, "stop");
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("blocks Stop on visible active session-scoped Ralph starting state and reports its path", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-visible-starting-ralph-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            const sessionId = "sess-visible-ralph";
+            await mkdir(join(stateDir, "sessions", sessionId), { recursive: true });
+            await writeJson(join(stateDir, "sessions", sessionId, "ralph-state.json"), {
+                active: true,
+                mode: "ralph",
+                current_phase: "starting",
+                session_id: sessionId,
+            });
+            await writeJson(join(stateDir, "sessions", sessionId, "skill-active-state.json"), {
+                active: true,
+                skill: "ralph",
+                phase: "starting",
+                active_skills: [{ skill: "ralph", phase: "starting", active: true, session_id: sessionId }],
+            });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: sessionId,
+            }, { cwd });
+            assert.equal(result.omxEventName, "stop");
+            assert.deepEqual(result.outputJson, {
+                decision: "block",
+                reason: "OMX Ralph is still active (phase: starting; state: .omx/state/sessions/sess-visible-ralph/ralph-state.json); continue the task and gather fresh verification evidence before stopping.",
+                stopReason: "ralph_starting",
+                systemMessage: "OMX Ralph is still active (phase: starting; state: .omx/state/sessions/sess-visible-ralph/ralph-state.json); continue the task and gather fresh verification evidence before stopping.",
+            });
         }
         finally {
             await rm(cwd, { recursive: true, force: true });
         }
     });
-    it("does not block Stop from stale current-session Ralph state when session.json points to a dead owner", async () => {
-        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-stale-current-session-ralph-"));
+    it("does not block Stop from another session-scoped Ralph state when an explicit session_id has no active Ralph state", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-explicit-session-ralph-"));
         try {
             const stateDir = join(cwd, ".omx", "state");
-            await mkdir(join(stateDir, "sessions", "sess-dead"), { recursive: true });
-            await writeJson(join(stateDir, "session.json"), {
-                session_id: "sess-dead",
-                cwd,
-                pid: Number.MAX_SAFE_INTEGER,
-                started_at: "2026-01-01T00:00:00.000Z",
-            });
-            await writeJson(join(stateDir, "sessions", "sess-dead", "ralph-state.json"), {
-                active: true,
-                current_phase: "verifying",
-                session_id: "sess-dead",
-            });
-            await writeJson(join(stateDir, "skill-active-state.json"), {
+            await mkdir(join(stateDir, "sessions", "sess-other"), { recursive: true });
+            await writeJson(join(stateDir, "sessions", "sess-other", "ralph-state.json"), {
                 active: true,
-                skill: "team",
-                phase: "team-exec",
-                active_skills: [{ skill: "team", phase: "team-exec", active: true, session_id: "sess-dead" }],
-            });
-            await writeJson(join(stateDir, "native-stop-state.json"), {
-                sessions: {
-                    "sess-dead": {
-                        last_signature: "ralph-stop|sess-dead|thread-1|no-message|verifying",
-                        updated_at: "2026-04-20T21:00:00.000Z",
-                    },
-                },
+                current_phase: "starting",
+                session_id: "sess-other",
             });
             const result = await dispatchCodexNativeHook({
                 hook_event_name: "Stop",
                 cwd,
-                session_id: "sess-dead",
-                thread_id: "thread-1",
-                stop_hook_active: true,
+                session_id: "sess-current",
             }, { cwd });
             assert.equal(result.omxEventName, "stop");
             assert.equal(result.outputJson, null);
@@ -3193,20 +4527,33 @@ esac
             await rm(cwd, { recursive: true, force: true });
         }
     });
-    it("does not block Stop from another session-scoped Ralph state when an explicit session_id has no active Ralph state", async () => {
-        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-explicit-session-ralph-"));
+    it("prefers canonical run-state terminal lifecycle before stale session Ralph state during Stop", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-canonical-run-state-ralph-"));
         try {
             const stateDir = join(cwd, ".omx", "state");
-            await mkdir(join(stateDir, "sessions", "sess-other"), { recursive: true });
-            await writeJson(join(stateDir, "sessions", "sess-other", "ralph-state.json"), {
+            const sessionId = "sess-canonical-run-state-ralph";
+            await mkdir(join(stateDir, "sessions", sessionId), { recursive: true });
+            await writeJson(join(stateDir, "session.json"), { session_id: sessionId, cwd });
+            await writeJson(join(stateDir, "sessions", sessionId, "run-state.json"), {
+                version: 1,
+                mode: "ralph",
+                active: false,
+                outcome: "finish",
+                lifecycle_outcome: "finished",
+                current_phase: "complete",
+                completed_at: "2026-04-27T12:00:00.000Z",
+                updated_at: "2026-04-27T12:00:00.000Z",
+            });
+            await writeJson(join(stateDir, "sessions", sessionId, "ralph-state.json"), {
                 active: true,
-                current_phase: "starting",
-                session_id: "sess-other",
+                mode: "ralph",
+                current_phase: "verifying",
+                session_id: sessionId,
             });
             const result = await dispatchCodexNativeHook({
                 hook_event_name: "Stop",
                 cwd,
-                session_id: "sess-current",
+                session_id: sessionId,
             }, { cwd });
             assert.equal(result.omxEventName, "stop");
             assert.equal(result.outputJson, null);
@@ -3308,9 +4655,9 @@ esac
             };
             const expected = {
                 decision: "block",
-                reason: "OMX Ralph is still active (phase: executing); continue the task and gather fresh verification evidence before stopping.",
+                reason: "OMX Ralph is still active (phase: executing; state: .omx/state/ralph-state.json); continue the task and gather fresh verification evidence before stopping.",
                 stopReason: "ralph_executing",
-                systemMessage: "OMX Ralph is still active (phase: executing); continue the task and gather fresh verification evidence before stopping.",
+                systemMessage: "OMX Ralph is still active (phase: executing; state: .omx/state/ralph-state.json); continue the task and gather fresh verification evidence before stopping.",
             };
             const first = await dispatchCodexNativeHook(payload, { cwd });
             const replay = await dispatchCodexNativeHook({
@@ -4421,6 +5768,333 @@ describe("codex native hook triage integration", () => {
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("injects LIGHT/researcher advisory and writes state for an official-doc lookup prompt", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-triage-light-researcher-"));
+        try {
+            await mkdir(join(cwd, ".omx", "state"), { recursive: true });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                session_id: "triage-researcher-1",
+                thread_id: "thread-triage-researcher-1",
+                turn_id: "turn-triage-researcher-1",
+                prompt: "Find the official docs and version compatibility notes for this SDK",
+            }, { cwd });
+            const additionalContext = String(result.outputJson?.hookSpecificOutput?.additionalContext ?? "");
+            assert.match(additionalContext, /external documentation\/reference research request/);
+            assert.match(additionalContext, /Prefer the researcher role surface/);
+            assert.doesNotMatch(additionalContext, /skill: researcher activated/);
+            assert.equal(existsSync(join(cwd, ".omx", "state", "skill-active-state.json")), false);
+            const stateFile = join(cwd, ".omx", "state", "sessions", "triage-researcher-1", "prompt-routing-state.json");
+            assert.equal(existsSync(stateFile), true);
+            const state = JSON.parse(await readFile(stateFile, "utf-8"));
+            assert.equal(state.last_triage?.lane, "LIGHT");
+            assert.equal(state.last_triage?.destination, "researcher");
+            assert.equal(state.last_triage?.reason, "external_reference_research");
+            assert.equal(state.suppress_followup, true);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("routes Korean external lookup phrasing to researcher without treating it as workflow activation", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-triage-light-researcher-ko-"));
+        try {
+            await mkdir(join(cwd, ".omx", "state"), { recursive: true });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                session_id: "triage-researcher-ko-1",
+                thread_id: "thread-triage-researcher-ko-1",
+                turn_id: "turn-triage-researcher-ko-1",
+                prompt: "OpenAI Responses API 공식 문서 찾아줘",
+            }, { cwd });
+            const additionalContext = String(result.outputJson?.hookSpecificOutput?.additionalContext ?? "");
+            assert.match(additionalContext, /Prefer the researcher role surface/);
+            assert.equal(result.skillState, null);
+            const stateFile = join(cwd, ".omx", "state", "sessions", "triage-researcher-ko-1", "prompt-routing-state.json");
+            const state = JSON.parse(await readFile(stateFile, "utf-8"));
+            assert.equal(state.last_triage?.lane, "LIGHT");
+            assert.equal(state.last_triage?.destination, "researcher");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("routes official-doc question prompts to researcher instead of explore", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-triage-question-researcher-"));
+        try {
+            await mkdir(join(cwd, ".omx", "state"), { recursive: true });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                session_id: "triage-question-researcher-1",
+                thread_id: "thread-triage-question-researcher-1",
+                turn_id: "turn-triage-question-researcher-1",
+                prompt: "where can I find official docs for OpenAI Responses API?",
+            }, { cwd });
+            const additionalContext = String(result.outputJson?.hookSpecificOutput?.additionalContext ?? "");
+            assert.doesNotMatch(additionalContext, /Prefer the explore role surface/);
+            assert.match(additionalContext, /Prefer the researcher role surface/);
+            const stateFile = join(cwd, ".omx", "state", "sessions", "triage-question-researcher-1", "prompt-routing-state.json");
+            const state = JSON.parse(await readFile(stateFile, "utf-8"));
+            assert.equal(state.last_triage?.lane, "LIGHT");
+            assert.equal(state.last_triage?.destination, "researcher");
+            assert.equal(state.last_triage?.reason, "external_reference_research");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("routes endpoint-shaped official-doc lookups to researcher instead of local explore", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-triage-endpoint-researcher-"));
+        try {
+            await mkdir(join(cwd, ".omx", "state"), { recursive: true });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                session_id: "triage-endpoint-researcher-1",
+                thread_id: "thread-triage-endpoint-researcher-1",
+                turn_id: "turn-triage-endpoint-researcher-1",
+                prompt: "find official docs for api/v1/responses",
+            }, { cwd });
+            const additionalContext = String(result.outputJson?.hookSpecificOutput?.additionalContext ?? "");
+            assert.doesNotMatch(additionalContext, /Prefer the explore role surface/);
+            assert.match(additionalContext, /Prefer the researcher role surface/);
+            const stateFile = join(cwd, ".omx", "state", "sessions", "triage-endpoint-researcher-1", "prompt-routing-state.json");
+            const state = JSON.parse(await readFile(stateFile, "utf-8"));
+            assert.equal(state.last_triage?.lane, "LIGHT");
+            assert.equal(state.last_triage?.destination, "researcher");
+            assert.equal(state.last_triage?.reason, "external_reference_research");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("routes dotted technology official-doc lookups to researcher instead of local explore", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-triage-dotted-tech-researcher-"));
+        try {
+            await mkdir(join(cwd, ".omx", "state"), { recursive: true });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                session_id: "triage-dotted-tech-researcher-1",
+                thread_id: "thread-triage-dotted-tech-researcher-1",
+                turn_id: "turn-triage-dotted-tech-researcher-1",
+                prompt: "find official docs for Node.js",
+            }, { cwd });
+            const additionalContext = String(result.outputJson?.hookSpecificOutput?.additionalContext ?? "");
+            assert.doesNotMatch(additionalContext, /Prefer the explore role surface/);
+            assert.match(additionalContext, /Prefer the researcher role surface/);
+            const stateFile = join(cwd, ".omx", "state", "sessions", "triage-dotted-tech-researcher-1", "prompt-routing-state.json");
+            const state = JSON.parse(await readFile(stateFile, "utf-8"));
+            assert.equal(state.last_triage?.lane, "LIGHT");
+            assert.equal(state.last_triage?.destination, "researcher");
+            assert.equal(state.last_triage?.reason, "external_reference_research");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("routes URL-shaped official-doc lookups with repo paths to researcher instead of local routes", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-triage-url-path-researcher-"));
+        try {
+            await mkdir(join(cwd, ".omx", "state"), { recursive: true });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                session_id: "triage-url-path-researcher-1",
+                thread_id: "thread-triage-url-path-researcher-1",
+                turn_id: "turn-triage-url-path-researcher-1",
+                prompt: "find official docs for github.com/org/repo/src/foo.ts",
+            }, { cwd });
+            const additionalContext = String(result.outputJson?.hookSpecificOutput?.additionalContext ?? "");
+            assert.doesNotMatch(additionalContext, /Prefer the executor role surface/);
+            assert.doesNotMatch(additionalContext, /Prefer the explore role surface/);
+            assert.match(additionalContext, /Prefer the researcher role surface/);
+            const stateFile = join(cwd, ".omx", "state", "sessions", "triage-url-path-researcher-1", "prompt-routing-state.json");
+            const state = JSON.parse(await readFile(stateFile, "utf-8"));
+            assert.equal(state.last_triage?.lane, "LIGHT");
+            assert.equal(state.last_triage?.destination, "researcher");
+            assert.equal(state.last_triage?.reason, "external_reference_research");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("keeps implementation-shaped official-doc prompts on HEAVY instead of researcher", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-triage-researcher-implementation-"));
+        try {
+            await mkdir(join(cwd, ".omx", "state"), { recursive: true });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                session_id: "triage-researcher-implementation-1",
+                thread_id: "thread-triage-researcher-implementation-1",
+                turn_id: "turn-triage-researcher-implementation-1",
+                prompt: "implement auth using official docs for the SDK",
+            }, { cwd });
+            const additionalContext = String(result.outputJson?.hookSpecificOutput?.additionalContext ?? "");
+            assert.doesNotMatch(additionalContext, /Prefer the researcher role surface/);
+            assert.match(additionalContext, /multi-step goal with no workflow keyword/);
+            const stateFile = join(cwd, ".omx", "state", "sessions", "triage-researcher-implementation-1", "prompt-routing-state.json");
+            const state = JSON.parse(await readFile(stateFile, "utf-8"));
+            assert.equal(state.last_triage?.lane, "HEAVY");
+            assert.equal(state.last_triage?.destination, "autopilot");
+            assert.equal(state.last_triage?.reason, "implementation_research_goal");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("keeps planning-shaped official-doc prompts on HEAVY instead of researcher", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-triage-researcher-planning-"));
+        try {
+            await mkdir(join(cwd, ".omx", "state"), { recursive: true });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                session_id: "triage-researcher-planning-1",
+                thread_id: "thread-triage-researcher-planning-1",
+                turn_id: "turn-triage-researcher-planning-1",
+                prompt: "research and plan auth migration using official docs for the SDK",
+            }, { cwd });
+            const additionalContext = String(result.outputJson?.hookSpecificOutput?.additionalContext ?? "");
+            assert.doesNotMatch(additionalContext, /Prefer the researcher role surface/);
+            assert.match(additionalContext, /multi-step goal with no workflow keyword/);
+            const stateFile = join(cwd, ".omx", "state", "sessions", "triage-researcher-planning-1", "prompt-routing-state.json");
+            const state = JSON.parse(await readFile(stateFile, "utf-8"));
+            assert.equal(state.last_triage?.lane, "HEAVY");
+            assert.equal(state.last_triage?.destination, "autopilot");
+            assert.equal(state.last_triage?.reason, "implementation_research_goal");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("keeps local source lookup prompts off researcher", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-triage-local-source-explore-"));
+        try {
+            await mkdir(join(cwd, ".omx", "state"), { recursive: true });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                session_id: "triage-local-source-1",
+                thread_id: "thread-triage-local-source-1",
+                turn_id: "turn-triage-local-source-1",
+                prompt: "search source for parseConfig in src/config.ts",
+            }, { cwd });
+            const additionalContext = String(result.outputJson?.hookSpecificOutput?.additionalContext ?? "");
+            assert.doesNotMatch(additionalContext, /Prefer the researcher role surface/);
+            assert.match(additionalContext, /Prefer the executor role surface/);
+            const stateFile = join(cwd, ".omx", "state", "sessions", "triage-local-source-1", "prompt-routing-state.json");
+            const state = JSON.parse(await readFile(stateFile, "utf-8"));
+            assert.equal(state.last_triage?.lane, "LIGHT");
+            assert.equal(state.last_triage?.destination, "executor");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("keeps anchored local API usage prompts on executor instead of researcher", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-triage-local-api-executor-"));
+        try {
+            await mkdir(join(cwd, ".omx", "state"), { recursive: true });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                session_id: "triage-local-api-1",
+                thread_id: "thread-triage-local-api-1",
+                turn_id: "turn-triage-local-api-1",
+                prompt: "find API usage in src/foo.ts",
+            }, { cwd });
+            const additionalContext = String(result.outputJson?.hookSpecificOutput?.additionalContext ?? "");
+            assert.doesNotMatch(additionalContext, /Prefer the researcher role surface/);
+            assert.match(additionalContext, /Prefer the executor role surface/);
+            const stateFile = join(cwd, ".omx", "state", "sessions", "triage-local-api-1", "prompt-routing-state.json");
+            const state = JSON.parse(await readFile(stateFile, "utf-8"));
+            assert.equal(state.last_triage?.lane, "LIGHT");
+            assert.equal(state.last_triage?.destination, "executor");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("keeps project-scoped local API usage prompts on explore instead of researcher", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-triage-project-api-explore-"));
+        try {
+            await mkdir(join(cwd, ".omx", "state"), { recursive: true });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                session_id: "triage-project-api-1",
+                thread_id: "thread-triage-project-api-1",
+                turn_id: "turn-triage-project-api-1",
+                prompt: "find API usage in this project",
+            }, { cwd });
+            const additionalContext = String(result.outputJson?.hookSpecificOutput?.additionalContext ?? "");
+            assert.doesNotMatch(additionalContext, /Prefer the researcher role surface/);
+            assert.match(additionalContext, /Prefer the explore role surface/);
+            const stateFile = join(cwd, ".omx", "state", "sessions", "triage-project-api-1", "prompt-routing-state.json");
+            const state = JSON.parse(await readFile(stateFile, "utf-8"));
+            assert.equal(state.last_triage?.lane, "LIGHT");
+            assert.equal(state.last_triage?.destination, "explore");
+            assert.equal(state.last_triage?.reason, "local_reference_lookup");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("keeps repository changelog lookup prompts on explore despite generic docs terms", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-triage-repo-changelog-explore-"));
+        try {
+            await mkdir(join(cwd, ".omx", "state"), { recursive: true });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                session_id: "triage-repo-changelog-1",
+                thread_id: "thread-triage-repo-changelog-1",
+                turn_id: "turn-triage-repo-changelog-1",
+                prompt: "find changelog in this repository",
+            }, { cwd });
+            const additionalContext = String(result.outputJson?.hookSpecificOutput?.additionalContext ?? "");
+            assert.doesNotMatch(additionalContext, /Prefer the researcher role surface/);
+            assert.match(additionalContext, /Prefer the explore role surface/);
+            const stateFile = join(cwd, ".omx", "state", "sessions", "triage-repo-changelog-1", "prompt-routing-state.json");
+            const state = JSON.parse(await readFile(stateFile, "utf-8"));
+            assert.equal(state.last_triage?.lane, "LIGHT");
+            assert.equal(state.last_triage?.destination, "explore");
+            assert.equal(state.last_triage?.reason, "local_reference_lookup");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("routes anchored read-only questions through explore before executor", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-triage-anchored-question-explore-"));
+        try {
+            await mkdir(join(cwd, ".omx", "state"), { recursive: true });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "UserPromptSubmit",
+                cwd,
+                session_id: "triage-anchored-question-1",
+                thread_id: "thread-triage-anchored-question-1",
+                turn_id: "turn-triage-anchored-question-1",
+                prompt: "what does src/foo.ts do?",
+            }, { cwd });
+            const additionalContext = String(result.outputJson?.hookSpecificOutput?.additionalContext ?? "");
+            assert.doesNotMatch(additionalContext, /Prefer the executor role surface/);
+            assert.match(additionalContext, /Prefer the explore role surface/);
+            const stateFile = join(cwd, ".omx", "state", "sessions", "triage-anchored-question-1", "prompt-routing-state.json");
+            const state = JSON.parse(await readFile(stateFile, "utf-8"));
+            assert.equal(state.last_triage?.lane, "LIGHT");
+            assert.equal(state.last_triage?.destination, "explore");
+            assert.equal(state.last_triage?.reason, "question_or_explanation");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     // ── Group 6: PASS (no triage injection, no state) ────────────────────────
     it("produces no triage advisory and no state for trivial greeting prompts", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-triage-pass-hello-"));