oh-my-codex 0.14.4 → 0.15.1

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

@@ -1,31 +1,35 @@
 import { execFileSync } from "child_process";
-import { existsSync, readFileSync } from "fs";
+import { closeSync, existsSync, openSync, readFileSync, readSync } from "fs";
 import { mkdir, readFile, readdir, writeFile } from "fs/promises";
-import { join, resolve } from "path";
+import { join, relative, resolve } from "path";
 import { pathToFileURL } from "url";
 import { readModeState, readModeStateForSession, updateModeState } from "../modes/base.js";
 import { listActiveSkills, readVisibleSkillActiveState, } from "../state/skill-active.js";
-import { readSubagentSessionSummary } from "../subagents/tracker.js";
-import { resolveCanonicalTeamStateRoot } from "../team/state-root.js";
-import { isSessionStateUsable, readSessionState, readUsableSessionState, reconcileNativeSessionStart, } from "../hooks/session.js";
+import { readSubagentSessionSummary, recordSubagentTurnForSession, } from "../subagents/tracker.js";
+import { resolveCanonicalTeamStateRoot, resolveWorkerNotifyTeamStateRootPath } from "../team/state-root.js";
+import { appendToLog, isSessionStateUsable, readSessionState, readUsableSessionState, reconcileNativeSessionStart, } from "../hooks/session.js";
 import { appendTeamEvent, readTeamLeaderAttention, readTeamManifestV2, readTeamPhase, writeTeamLeaderAttention, writeTeamPhase, } from "../team/state.js";
 import { omxNotepadPath, omxProjectMemoryPath } from "../utils/paths.js";
+import { findGitLayout } from "../utils/git-layout.js";
 import { getStateFilePath, getStatePath } from "../mcp/state-paths.js";
 import { detectKeywords, detectPrimaryKeyword, recordSkillActivation, } from "../hooks/keyword-detector.js";
 import { detectNativeStopStallPattern, loadAutoNudgeConfig, normalizeAutoNudgeSignatureText, resolveEffectiveAutoNudgeResponse, } from "./notify-hook/auto-nudge.js";
 import { buildNativePostToolUseOutput, buildNativePreToolUseOutput, detectMcpTransportFailure, } from "./codex-native-pre-post.js";
+import { handleTeamWorkerPostToolUseSuccess } from "./notify-hook/team-worker-posttooluse.js";
+import { resolveCodexExecutionSurface, } from "./codex-execution-surface.js";
 import { buildNativeHookEvent, } from "../hooks/extensibility/events.js";
 import { dispatchHookEvent } from "../hooks/extensibility/dispatcher.js";
 import { reconcileHudForPromptSubmit } from "../hud/reconcile.js";
-import { shellEscapeSingle } from "../hud/tmux.js";
 import { onSessionStart as buildWikiSessionStartContext } from "../wiki/lifecycle.js";
 import { readAutoresearchCompletionStatus, readAutoresearchModeState } from "../autoresearch/skill-validation.js";
-import { shouldContinueRun } from "../runtime/run-loop.js";
+import { readRunState } from "../runtime/run-state.js";
+import { getRunContinuationSnapshot, shouldContinueRun } from "../runtime/run-loop.js";
 import { triagePrompt } from "../hooks/triage-heuristic.js";
 import { readTriageConfig } from "../hooks/triage-config.js";
 import { readTriageState, writeTriageState, shouldSuppressFollowup, promptSignature, } from "../hooks/triage-state.js";
 import { isPendingDeepInterviewQuestionEnforcement, reconcileDeepInterviewQuestionEnforcementFromAnsweredRecords, } from "../question/deep-interview.js";
-import { resolveOmxCliEntryPath } from "../utils/paths.js";
+import { buildDocumentRefreshAdvisoryOutput, evaluateFinalHandoffDocumentRefresh, isFinalHandoffDocumentRefreshCandidate, } from "../document-refresh/enforcer.js";
+import { buildExecFollowupStopOutput } from "../exec/followup.js";
 const TERMINAL_MODE_PHASES = new Set(["complete", "failed", "cancelled"]);
 const SKILL_STOP_BLOCKERS = new Set(["ralplan"]);
 const TEAM_TERMINAL_TASK_STATUSES = new Set(["completed", "failed"]);
@@ -49,12 +53,125 @@ const SHORT_FOLLOWUP_PRIORITY_PATTERNS = [
     /(?:按照|按|基于)(?:这个|上述|当前)?(?:plan|计划|方案)/u,
     /\b(?:follow up|latest request|this turn|current turn|newest request)\b/i,
 ];
+const MAX_SESSION_META_LINE_BYTES = 256 * 1024;
 function safeString(value) {
     return typeof value === "string" ? value : "";
 }
 function safeObject(value) {
     return value && typeof value === "object" ? value : {};
 }
+function readBoundedFirstLineSync(path) {
+    const fd = openSync(path, "r");
+    try {
+        const chunks = [];
+        const buffer = Buffer.alloc(Math.min(8192, MAX_SESSION_META_LINE_BYTES));
+        let totalBytesRead = 0;
+        while (totalBytesRead < MAX_SESSION_META_LINE_BYTES) {
+            const bytesToRead = Math.min(buffer.length, MAX_SESSION_META_LINE_BYTES - totalBytesRead);
+            const bytesRead = readSync(fd, buffer, 0, bytesToRead, totalBytesRead);
+            if (bytesRead <= 0)
+                break;
+            totalBytesRead += bytesRead;
+            const chunk = buffer.subarray(0, bytesRead);
+            const newlineOffset = chunk.indexOf(0x0a);
+            if (newlineOffset >= 0) {
+                chunks.push(Buffer.from(chunk.subarray(0, newlineOffset)));
+                break;
+            }
+            chunks.push(Buffer.from(chunk));
+        }
+        return Buffer.concat(chunks).toString("utf-8").replace(/\r$/, "");
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function readNativeSubagentSessionStartMetadata(transcriptPath) {
+    const normalizedPath = transcriptPath.trim();
+    if (!normalizedPath)
+        return null;
+    try {
+        const firstLine = readBoundedFirstLineSync(normalizedPath).trim();
+        if (!firstLine)
+            return null;
+        const firstRecord = safeObject(JSON.parse(firstLine));
+        if (safeString(firstRecord.type) !== "session_meta")
+            return null;
+        const payload = safeObject(firstRecord.payload);
+        const source = safeObject(payload.source);
+        const subagent = safeObject(source.subagent);
+        const threadSpawn = safeObject(subagent.thread_spawn);
+        const parentThreadId = safeString(threadSpawn.parent_thread_id).trim();
+        if (!parentThreadId)
+            return null;
+        const agentNickname = safeString(threadSpawn.agent_nickname ?? payload.agent_nickname).trim();
+        const agentRole = safeString(threadSpawn.agent_role ?? payload.agent_role).trim();
+        return {
+            parentThreadId,
+            ...(agentNickname ? { agentNickname } : {}),
+            ...(agentRole ? { agentRole } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function recordNativeSubagentSessionStart(cwd, canonicalSessionId, childSessionId, metadata, transcriptPath) {
+    const trackingSessionIds = [...new Set([
+            canonicalSessionId.trim(),
+            metadata.parentThreadId.trim(),
+        ].filter(Boolean))];
+    for (const sessionId of trackingSessionIds) {
+        await recordSubagentTurnForSession(cwd, {
+            sessionId,
+            threadId: metadata.parentThreadId,
+        }).catch(() => { });
+        await recordSubagentTurnForSession(cwd, {
+            sessionId,
+            threadId: childSessionId,
+            mode: metadata.agentRole,
+        }).catch(() => { });
+    }
+    await appendToLog(cwd, {
+        event: "subagent_session_start",
+        session_id: canonicalSessionId,
+        native_owner_session_id: metadata.parentThreadId,
+        native_session_id: childSessionId,
+        parent_thread_id: metadata.parentThreadId,
+        ...(metadata.agentNickname ? { agent_nickname: metadata.agentNickname } : {}),
+        ...(metadata.agentRole ? { agent_role: metadata.agentRole } : {}),
+        ...(transcriptPath ? { transcript_path: transcriptPath } : {}),
+        timestamp: new Date().toISOString(),
+    }).catch(() => { });
+}
+async function nativeSubagentSessionStartBelongsToCanonicalSession(cwd, canonicalSessionId, currentSessionState, metadata) {
+    const parentThreadId = metadata.parentThreadId.trim();
+    if (!parentThreadId)
+        return false;
+    const currentNativeSessionId = safeString(currentSessionState?.native_session_id).trim();
+    if (currentNativeSessionId && currentNativeSessionId === parentThreadId) {
+        return true;
+    }
+    const summary = await readSubagentSessionSummary(cwd, canonicalSessionId).catch(() => null);
+    if (!summary)
+        return false;
+    if (summary.leaderThreadId === parentThreadId)
+        return true;
+    return summary.allThreadIds.includes(parentThreadId);
+}
+async function recordIgnoredNativeSubagentSessionStart(cwd, canonicalSessionId, childSessionId, metadata, transcriptPath) {
+    await appendToLog(cwd, {
+        event: "subagent_session_start_ignored",
+        reason: "parent_not_in_canonical_session",
+        session_id: canonicalSessionId,
+        native_session_id: childSessionId,
+        parent_thread_id: metadata.parentThreadId,
+        ...(metadata.agentNickname ? { agent_nickname: metadata.agentNickname } : {}),
+        ...(metadata.agentRole ? { agent_role: metadata.agentRole } : {}),
+        ...(transcriptPath ? { transcript_path: transcriptPath } : {}),
+        timestamp: new Date().toISOString(),
+    }).catch(() => { });
+}
 function safePositiveInteger(value) {
     if (typeof value === "number" && Number.isInteger(value) && value > 0)
         return value;
@@ -192,6 +309,31 @@ async function readActiveAutoresearchState(cwd, sessionId) {
         return null;
     return state;
 }
+function isRalphStartingPhase(state) {
+    return safeString(state.current_phase ?? state.currentPhase).trim().toLowerCase() === "starting";
+}
+function shouldHonorCanonicalTerminalRunState(runState, mode) {
+    if (!runState)
+        return false;
+    const runMode = safeString(runState.mode).trim();
+    if (runMode && runMode !== mode)
+        return false;
+    return getRunContinuationSnapshot(runState)?.terminal === true;
+}
+async function readCanonicalTerminalRunStateForStop(cwd, sessionId, mode) {
+    if (!safeString(sessionId).trim())
+        return null;
+    const runState = await readRunState(cwd, sessionId).catch(() => null);
+    const runRecord = runState;
+    return shouldHonorCanonicalTerminalRunState(runRecord, mode) ? runRecord : null;
+}
+async function isVisibleRalphActiveForSession(cwd, sessionId) {
+    const canonicalState = await readVisibleSkillActiveState(cwd, sessionId);
+    if (!canonicalState)
+        return false;
+    return listActiveSkills(canonicalState).some((entry) => (entry.skill === "ralph"
+        && matchesSkillStopContext(entry, canonicalState, sessionId, "")));
+}
 async function readActiveRalphState(stateDir, preferredSessionId) {
     const cwd = resolve(stateDir, "..", "..");
     const [rawSessionInfo, usableSessionInfo] = await Promise.all([
@@ -213,16 +355,26 @@ async function readActiveRalphState(stateDir, preferredSessionId) {
         if (staleCurrentSessionId && sessionId === staleCurrentSessionId) {
             continue;
         }
-        const sessionScoped = await readStopSessionPinnedState("ralph-state.json", cwd, sessionId);
+        if (await readCanonicalTerminalRunStateForStop(cwd, sessionId, "ralph")) {
+            continue;
+        }
+        const sessionScopedPath = getStateFilePath("ralph-state.json", cwd, sessionId);
+        const sessionScoped = await readJsonIfExists(sessionScopedPath);
+        if (sessionScoped?.active === true
+            && isRalphStartingPhase(sessionScoped)
+            && !(await isVisibleRalphActiveForSession(cwd, sessionId))) {
+            continue;
+        }
         if (sessionScoped?.active === true && shouldContinueRun(sessionScoped)) {
-            return sessionScoped;
+            return { state: sessionScoped, path: sessionScopedPath };
         }
     }
     if (sessionCandidates.length > 0)
         return null;
-    const direct = await readJsonIfExists(join(stateDir, "ralph-state.json"));
+    const directPath = join(stateDir, "ralph-state.json");
+    const direct = await readJsonIfExists(directPath);
     if (direct?.active === true && shouldContinueRun(direct)) {
-        return direct;
+        return { state: direct, path: directPath };
     }
     return null;
 }
@@ -328,6 +480,22 @@ function tryReadGitValue(cwd, args) {
         return null;
     }
 }
+function localExcludeAlreadyIgnoresOmx(cwd) {
+    const layout = findGitLayout(cwd);
+    if (!layout)
+        return false;
+    const excludePath = join(layout.gitDir, "info", "exclude");
+    try {
+        const lines = readFileSync(excludePath, "utf-8")
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line && !line.startsWith("#"));
+        return lines.includes(".omx/") || lines.includes(".omx");
+    }
+    catch {
+        return false;
+    }
+}
 function isPathIgnoredByGit(cwd, path) {
     try {
         execFileSync("git", ["check-ignore", "-q", path], {
@@ -345,7 +513,7 @@ async function ensureOmxLocalIgnoreEntry(cwd) {
     const repoRoot = tryReadGitValue(cwd, ["rev-parse", "--show-toplevel"]);
     if (!repoRoot)
         return { changed: false };
-    if (isPathIgnoredByGit(repoRoot, ".omx/")) {
+    if (localExcludeAlreadyIgnoresOmx(repoRoot) || isPathIgnoredByGit(repoRoot, ".omx/")) {
         return { changed: false };
     }
     const excludePathValue = tryReadGitValue(repoRoot, ["rev-parse", "--git-path", "info/exclude"]);
@@ -363,8 +531,14 @@ async function ensureOmxLocalIgnoreEntry(cwd) {
     await writeFile(excludePath, next);
     return { changed: true, excludePath };
 }
-async function buildSessionStartContext(cwd, sessionId) {
+async function buildSessionStartContext(cwd, sessionId, options = {}) {
     const sections = [];
+    sections.push(buildExecutionEnvironmentSection(cwd, {
+        hookEventName: options.hookEventName,
+        payload: options.payload,
+        canonicalSessionId: options.canonicalSessionId,
+        nativeSessionId: options.nativeSessionId,
+    }));
     const localIgnoreResult = await ensureOmxLocalIgnoreEntry(cwd);
     if (localIgnoreResult.changed) {
         sections.push(`Added .omx/ to ${localIgnoreResult.excludePath} to keep local OMX state out of source control without mutating tracked repo ignores.`);
@@ -453,6 +627,79 @@ async function buildSessionStartContext(cwd, sessionId) {
     }
     return sections.length > 0 ? sections.join("\n\n") : null;
 }
+function resolveExecutionEnvironment(cwd, options = {}) {
+    const executionSurface = resolveCodexExecutionSurface(cwd, options);
+    const leaderPaneHint = resolveQuestionLeaderPaneHint(cwd, options.payload);
+    const questionBridgeHint = leaderPaneHint
+        ? `tmux return bridge recorded at ${leaderPaneHint}, but this process is not attached to tmux; prefer native/user-input fallback unless running from an attached tmux pane`
+        : "not available from this outside-tmux surface; use native structured input when available or ask one concise plain-text question";
+    if (executionSurface.transport === "attached-tmux") {
+        return {
+            kind: "attached-tmux-runtime",
+            launcher: executionSurface.launcher,
+            transport: executionSurface.transport,
+            surface: "attached tmux runtime - tmux",
+            tmuxWorkflowGuidance: "omx team, omx hud, and omx question are directly usable in this session",
+            questionGuidance: "visible renderer available from the current pane",
+            teamRuntimeInstruction: "Use the durable OMX team runtime via `omx team ...` for coordinated execution; do not replace it with in-process fanout.",
+            teamHelpInstruction: "If you need runtime syntax, run `omx team --help` yourself.",
+            deepInterviewInstruction: "Deep-interview must ask each interview round via `omx question`; do not fall back to `request_user_input` or plain-text questioning. This session is already attached to tmux, so `omx question` can open its visible renderer directly. After starting `omx question` in a background terminal, wait for that terminal to finish and read the JSON answer before continuing the interview. Stop remains blocked while a deep-interview question obligation is pending.",
+            leaderPaneHint,
+        };
+    }
+    if (leaderPaneHint) {
+        const isNativeOutsideTmux = executionSurface.launcher === "native";
+        return {
+            kind: "outside-tmux-with-bridge",
+            launcher: executionSurface.launcher,
+            transport: executionSurface.transport,
+            surface: isNativeOutsideTmux
+                ? "native-hook / Codex App outside tmux with tmux return bridge"
+                : "direct CLI outside tmux with tmux return bridge",
+            tmuxWorkflowGuidance: "omx team and omx hud need an attached tmux OMX CLI shell from this surface; omx question can use the detected bridge",
+            questionGuidance: questionBridgeHint,
+            teamRuntimeInstruction: isNativeOutsideTmux
+                ? "This session is native-hook / Codex App outside tmux; `omx team` is a CLI/tmux runtime surface, not directly available here. Launch OMX CLI from an attached tmux shell first; do not replace it with in-process fanout."
+                : "This session is direct CLI outside tmux with a tmux return bridge for `omx question`; prompt-side `$team` does not auto-start the durable tmux team runtime here. If you intentionally want the runtime, run `omx team ...` yourself from shell instead of replacing it with in-process fanout.",
+            teamHelpInstruction: isNativeOutsideTmux
+                ? "If you need runtime syntax, run `omx team --help` from an attached tmux OMX CLI shell."
+                : "If you need runtime syntax, run `omx team --help` yourself from shell.",
+            deepInterviewInstruction: `Deep-interview is active, but this session is not attached to tmux. Do not invoke \`omx question\`, \`omx hud\`, or \`omx team\` from this surface. Ask each interview round through the native structured question tool when available; otherwise ask exactly one concise plain-text question and wait for the answer. A tmux return bridge (${leaderPaneHint}) is recorded for explicit attached-tmux recovery only, not for default Codex App/native fallback.`,
+            leaderPaneHint,
+        };
+    }
+    const isNativeOutsideTmux = executionSurface.launcher === "native" && executionSurface.transport === "outside-tmux";
+    const surface = isNativeOutsideTmux
+        ? "native-hook / Codex App outside tmux"
+        : "direct CLI outside tmux";
+    const teamRuntimeInstruction = isNativeOutsideTmux
+        ? "This session is native-hook / Codex App outside tmux; `omx team` is a CLI/tmux runtime surface, not directly available here. Launch OMX CLI from an attached tmux shell first; do not replace it with in-process fanout."
+        : "This session is direct CLI outside tmux; prompt-side `$team` does not auto-start the durable tmux team runtime here. If you intentionally want the runtime, run `omx team ...` yourself from shell instead of replacing it with in-process fanout.";
+    const teamHelpInstruction = isNativeOutsideTmux
+        ? "If you need runtime syntax, run `omx team --help` from an attached tmux OMX CLI shell rather than from Codex App/native outside-tmux context."
+        : "If you need runtime syntax, run `omx team --help` yourself from shell.";
+    return {
+        kind: isNativeOutsideTmux ? "native-outside-tmux" : "direct-cli-outside-tmux",
+        launcher: executionSurface.launcher,
+        transport: executionSurface.transport,
+        surface,
+        tmuxWorkflowGuidance: "omx team, omx hud, and omx question need an attached tmux OMX CLI shell or preserved question bridge from this surface",
+        questionGuidance: questionBridgeHint,
+        teamRuntimeInstruction,
+        teamHelpInstruction,
+        deepInterviewInstruction: "Deep-interview is active, but this session is not attached to tmux. Do not invoke `omx question`, `omx hud`, or `omx team` from this surface. Ask each interview round through the native structured question tool when available; otherwise ask exactly one concise plain-text question and wait for the answer. Stop gating still applies to the interview, but no tmux question obligation should be created outside tmux.",
+        leaderPaneHint: "",
+    };
+}
+function buildExecutionEnvironmentSection(cwd, options = {}) {
+    const environment = resolveExecutionEnvironment(cwd, options);
+    return [
+        "[Execution environment]",
+        `- surface: ${environment.surface}`,
+        `- omx runtime surfaces: ${environment.tmuxWorkflowGuidance}`,
+        `- omx question: ${environment.questionGuidance}`,
+    ].join("\n");
+}
 function resolveQuestionLeaderPaneHint(cwd, payload) {
     const payloadSessionId = safeString(payload?.session_id).trim();
     const envSessionId = safeString(process.env.OMX_SESSION_ID || process.env.CODEX_SESSION_ID || process.env.SESSION_ID).trim();
@@ -480,15 +727,54 @@ function resolveQuestionLeaderPaneHint(cwd, payload) {
     return /^%\d+$/.test(envPane) ? envPane : '';
 }
 function buildDeepInterviewQuestionBridgeInstruction(cwd, payload) {
-    const omxBin = resolveOmxCliEntryPath({ cwd }) || process.argv[1] || "omx";
-    const leaderPaneHint = resolveQuestionLeaderPaneHint(cwd, payload);
-    const bridgeCommand = leaderPaneHint
-        ? `OMX_QUESTION_RETURN_PANE=${shellEscapeSingle(leaderPaneHint)} ${shellEscapeSingle(process.execPath)} ${shellEscapeSingle(omxBin)} question`
-        : `${shellEscapeSingle(process.execPath)} ${shellEscapeSingle(omxBin)} question`;
-    const enforcementNote = leaderPaneHint
-        ? ` When using Bash/background-terminal tool paths, preserve the leader pane by exporting \`OMX_QUESTION_RETURN_PANE=${leaderPaneHint}\` (or equivalent) before invoking \`omx question\`.`
-        : '';
-    return `Deep-interview must ask each interview round via \`omx question\`; do not fall back to \`request_user_input\` or plain-text questioning. After starting \`omx question\` in a background terminal, wait for that terminal to finish and read the JSON answer before continuing the interview. If bare \`omx question\` is unavailable in this reused session, use the current-session CLI bridge command: \`${bridgeCommand}\`.${enforcementNote} Stop remains blocked while a deep-interview question obligation is pending.`;
+    return resolveExecutionEnvironment(cwd, {
+        hookEventName: "UserPromptSubmit",
+        payload,
+        nativeSessionId: safeString(payload?.session_id ?? payload?.sessionId).trim(),
+    }).deepInterviewInstruction;
+}
+function buildTeamRuntimeInstruction(cwd, payload) {
+    return resolveExecutionEnvironment(cwd, {
+        hookEventName: "UserPromptSubmit",
+        payload,
+        nativeSessionId: safeString(payload?.session_id ?? payload?.sessionId).trim(),
+    }).teamRuntimeInstruction;
+}
+function buildTeamHelpInstruction(cwd, payload) {
+    return resolveExecutionEnvironment(cwd, {
+        hookEventName: "UserPromptSubmit",
+        payload,
+        nativeSessionId: safeString(payload?.session_id ?? payload?.sessionId).trim(),
+    }).teamHelpInstruction;
+}
+function buildNativeOutsideTmuxTeamPromptBlockState(prompt, cwd, payload, sessionId, threadId, turnId) {
+    const match = detectPrimaryKeyword(prompt);
+    if (match?.skill !== "team")
+        return null;
+    const environment = resolveExecutionEnvironment(cwd, {
+        hookEventName: "UserPromptSubmit",
+        payload,
+        canonicalSessionId: sessionId ?? "",
+        nativeSessionId: safeString(payload.session_id ?? payload.sessionId).trim(),
+    });
+    if (!(environment.launcher === "native" && environment.transport === "outside-tmux"))
+        return null;
+    const nowIso = new Date().toISOString();
+    return {
+        version: 1,
+        active: false,
+        skill: "team",
+        keyword: match.keyword,
+        phase: "planning",
+        activated_at: nowIso,
+        updated_at: nowIso,
+        source: "keyword-detector",
+        session_id: sessionId,
+        thread_id: threadId,
+        turn_id: turnId,
+        active_skills: [],
+        transition_error: "Codex App/native outside-tmux sessions cannot activate the tmux-only `team` workflow directly. Launch OMX CLI from an attached tmux shell first, then run `omx team ...` there.",
+    };
 }
 function buildAdditionalContextMessage(prompt, skillState, cwd = process.cwd(), payload) {
     if (!prompt)
@@ -548,9 +834,9 @@ function buildAdditionalContextMessage(prompt, skillState, cwd = process.cwd(),
                 ? `skill: ${skillState.initialized_mode} activated and initial state initialized at ${skillState.initialized_state_path}; write subsequent updates via omx_state MCP.`
                 : null,
             teamDetected
-                ? "Use the durable OMX team runtime via `omx team ...` for coordinated execution; do not replace it with in-process fanout."
+                ? buildTeamRuntimeInstruction(cwd, payload)
                 : null,
-            teamDetected ? "If you need runtime syntax, run `omx team --help` yourself." : null,
+            teamDetected ? buildTeamHelpInstruction(cwd, payload) : null,
             'Follow AGENTS.md routing and preserve workflow transition and planning-safety rules.',
         ].filter(Boolean).join(' ');
     }
@@ -568,8 +854,8 @@ function buildAdditionalContextMessage(prompt, skillState, cwd = process.cwd(),
             initializedStateMessage,
             deepInterviewPromptActivationNote,
             ultraworkPromptActivationNote,
-            "Use the durable OMX team runtime via `omx team ...` for coordinated execution; do not replace it with in-process fanout.",
-            "If you need runtime syntax, run `omx team --help` yourself.",
+            buildTeamRuntimeInstruction(cwd, payload),
+            buildTeamHelpInstruction(cwd, payload),
             "Follow AGENTS.md routing and preserve workflow transition and planning-safety rules.",
         ].filter(Boolean).join(" ");
     }
@@ -599,43 +885,16 @@ function parseTeamWorkerEnv(rawValue) {
         workerName: match[2] || "",
     };
 }
-async function readTeamStateRootFromJson(path) {
-    const parsed = await readJsonIfExists(path);
-    const value = safeString(parsed?.team_state_root).trim();
-    return value || null;
-}
 async function resolveTeamStateDirForWorkerContext(cwd, workerContext) {
-    const explicitStateRoot = safeString(process.env.OMX_TEAM_STATE_ROOT).trim();
-    if (explicitStateRoot) {
-        return resolve(cwd, explicitStateRoot);
-    }
-    const leaderCwd = safeString(process.env.OMX_TEAM_LEADER_CWD).trim();
-    const candidateStateDirs = [
-        ...(leaderCwd ? [join(resolve(leaderCwd), ".omx", "state")] : []),
-        join(cwd, ".omx", "state"),
-    ];
-    for (const candidateStateDir of candidateStateDirs) {
-        const teamRoot = join(candidateStateDir, "team", workerContext.teamName);
-        if (!existsSync(teamRoot))
-            continue;
-        const identityRoot = await readTeamStateRootFromJson(join(teamRoot, "workers", workerContext.workerName, "identity.json"));
-        if (identityRoot)
-            return resolve(cwd, identityRoot);
-        const manifestRoot = await readTeamStateRootFromJson(join(teamRoot, "manifest.v2.json"));
-        if (manifestRoot)
-            return resolve(cwd, manifestRoot);
-        const configRoot = await readTeamStateRootFromJson(join(teamRoot, "config.json"));
-        if (configRoot)
-            return resolve(cwd, configRoot);
-        return candidateStateDir;
-    }
-    return join(cwd, ".omx", "state");
+    return resolveWorkerNotifyTeamStateRootPath(cwd, workerContext, process.env);
 }
 async function buildTeamWorkerStopOutput(cwd) {
     const workerContext = parseTeamWorkerEnv(safeString(process.env.OMX_TEAM_WORKER));
     if (!workerContext)
         return null;
     const stateDir = await resolveTeamStateDirForWorkerContext(cwd, workerContext);
+    if (!stateDir)
+        return null;
     const workerRoot = join(stateDir, "team", workerContext.teamName, "workers", workerContext.workerName);
     const [identity, status] = await Promise.all([
         readJsonIfExists(join(workerRoot, "identity.json")),
@@ -716,6 +975,9 @@ async function readTeamModeStateForStop(cwd, sessionId) {
     return rootState;
 }
 async function buildTeamStopOutput(cwd, sessionId) {
+    if (await readCanonicalTerminalRunStateForStop(cwd, sessionId, "team")) {
+        return null;
+    }
     const teamState = await readTeamModeStateForStop(cwd, sessionId);
     if (teamState?.active !== true)
         return null;
@@ -943,6 +1205,12 @@ function buildRepeatableStopSignature(payload, kind, detail = "", canonicalSessi
         normalizedDetail || "no-detail",
     ].join("|");
 }
+function formatStopStatePath(cwd, statePath) {
+    const relativePath = relative(cwd, statePath);
+    if (!relativePath || relativePath.startsWith(".."))
+        return statePath;
+    return relativePath.replace(/\\/g, "/");
+}
 function readNativeStopSessionKey(payload, canonicalSessionId) {
     return resolveRepeatableStopSessionId(payload, canonicalSessionId) || readPayloadThreadId(payload) || "global";
 }
@@ -1153,6 +1421,9 @@ async function buildStopHookOutput(payload, cwd, stateDir) {
     const sessionId = readPayloadSessionId(payload);
     const canonicalSessionId = await resolveInternalSessionIdForPayload(cwd, sessionId);
     const threadId = readPayloadThreadId(payload);
+    const execFollowupOutput = await buildExecFollowupStopOutput(cwd, canonicalSessionId);
+    if (execFollowupOutput)
+        return execFollowupOutput;
     const ralphState = await readActiveRalphState(stateDir, canonicalSessionId);
     if (!ralphState) {
         const autoresearchState = await readActiveAutoresearchState(cwd, canonicalSessionId);
@@ -1170,8 +1441,9 @@ async function buildStopHookOutput(payload, cwd, stateDir) {
             }
         }
         const teamWorkerOutput = await buildTeamWorkerStopOutput(cwd);
-        if (hasTeamWorkerContext() && teamWorkerOutput)
-            return teamWorkerOutput;
+        if (hasTeamWorkerContext() && teamWorkerOutput) {
+            return await returnPersistentStopBlock(payload, stateDir, "team-worker-stop", safeString(teamWorkerOutput.stopReason), teamWorkerOutput, canonicalSessionId, { allowRepeatDuringStopHook: false });
+        }
         const autopilotOutput = await buildModeBasedStopOutput("autopilot", cwd, canonicalSessionId);
         if (autopilotOutput) {
             return await returnPersistentStopBlock(payload, stateDir, "autopilot-stop", safeString(autopilotOutput.stopReason), autopilotOutput, canonicalSessionId, { allowRepeatDuringStopHook: false });
@@ -1196,7 +1468,9 @@ async function buildStopHookOutput(payload, cwd, stateDir) {
             if (deepInterviewQuestionOutput) {
                 return await returnPersistentStopBlock(payload, stateDir, "deep-interview-question-stop", deepInterviewQuestionOutput.obligationId, deepInterviewQuestionOutput.output, canonicalSessionId);
             }
-            const canonicalTeam = await findCanonicalActiveTeamForSession(cwd, canonicalSessionId);
+            const canonicalTeam = await readCanonicalTerminalRunStateForStop(cwd, canonicalSessionId, "team")
+                ? null
+                : await findCanonicalActiveTeamForSession(cwd, canonicalSessionId);
             if (canonicalTeam) {
                 const canonicalTeamOutput = buildTeamStopOutputForPhase(canonicalTeam.teamName, canonicalTeam.phase);
                 const repeatedCanonicalTeamOutput = await returnPersistentStopBlock(payload, stateDir, "team-stop", `${canonicalTeam.teamName}|${canonicalTeam.phase}`, canonicalTeamOutput, canonicalSessionId);
@@ -1221,11 +1495,18 @@ async function buildStopHookOutput(payload, cwd, stateDir) {
                 systemMessage: "OMX native Stop detected a stall/permission-style handoff and continued the turn automatically.",
             }, canonicalSessionId);
         }
+        if (isFinalHandoffDocumentRefreshCandidate(lastAssistantMessage)) {
+            const documentRefreshWarning = evaluateFinalHandoffDocumentRefresh(cwd, lastAssistantMessage);
+            if (documentRefreshWarning) {
+                return await maybeReturnRepeatableStopOutput(payload, stateDir, buildRepeatableStopSignature(payload, "document-refresh-stop", documentRefreshWarning.triggeringPaths.join("|"), canonicalSessionId), buildDocumentRefreshAdvisoryOutput(documentRefreshWarning, "Stop"), canonicalSessionId, { allowRepeatDuringStopHook: false });
+            }
+        }
         return null;
     }
-    const currentPhase = safeString(ralphState?.current_phase).trim() || "executing";
+    const currentPhase = safeString(ralphState.state.current_phase).trim() || "executing";
+    const blockingPath = formatStopStatePath(cwd, ralphState.path);
     const stopReason = `ralph_${currentPhase}`;
-    const systemMessage = `OMX Ralph is still active (phase: ${currentPhase}); continue the task and gather fresh verification evidence before stopping.`;
+    const systemMessage = `OMX Ralph is still active (phase: ${currentPhase}; state: ${blockingPath}); continue the task and gather fresh verification evidence before stopping.`;
     return await returnPersistentStopBlock(payload, stateDir, "ralph-stop", currentPhase, {
         decision: "block",
         reason: systemMessage,
@@ -1247,12 +1528,30 @@ export async function dispatchCodexNativeHook(payload, options = {}) {
     const currentSessionState = await readUsableSessionState(cwd);
     let canonicalSessionId = safeString(currentSessionState?.session_id).trim();
     let resolvedNativeSessionId = nativeSessionId;
+    let skipCanonicalSessionStartContext = false;
     if (hookEventName === "SessionStart" && nativeSessionId) {
-        const sessionState = await reconcileNativeSessionStart(cwd, nativeSessionId, {
-            pid: options.sessionOwnerPid ?? resolveSessionOwnerPid(payload),
-        });
-        canonicalSessionId = safeString(sessionState.session_id).trim();
-        resolvedNativeSessionId = safeString(sessionState.native_session_id).trim() || nativeSessionId;
+        const transcriptPath = safeString(payload.transcript_path ?? payload.transcriptPath).trim();
+        const subagentSessionStart = readNativeSubagentSessionStartMetadata(transcriptPath);
+        if (subagentSessionStart && canonicalSessionId) {
+            const belongsToCanonicalSession = await nativeSubagentSessionStartBelongsToCanonicalSession(cwd, canonicalSessionId, currentSessionState, subagentSessionStart);
+            if (belongsToCanonicalSession) {
+                resolvedNativeSessionId = nativeSessionId;
+                await recordNativeSubagentSessionStart(cwd, canonicalSessionId, nativeSessionId, subagentSessionStart, transcriptPath);
+            }
+            else {
+                skipCanonicalSessionStartContext = true;
+                resolvedNativeSessionId =
+                    safeString(currentSessionState?.native_session_id).trim() || nativeSessionId;
+                await recordIgnoredNativeSubagentSessionStart(cwd, canonicalSessionId, nativeSessionId, subagentSessionStart, transcriptPath);
+            }
+        }
+        else {
+            const sessionState = await reconcileNativeSessionStart(cwd, nativeSessionId, {
+                pid: options.sessionOwnerPid ?? resolveSessionOwnerPid(payload),
+            });
+            canonicalSessionId = safeString(sessionState.session_id).trim();
+            resolvedNativeSessionId = safeString(sessionState.native_session_id).trim() || nativeSessionId;
+        }
     }
     else if (!canonicalSessionId) {
         canonicalSessionId = safeString(currentSessionState?.session_id).trim();
@@ -1273,7 +1572,7 @@ export async function dispatchCodexNativeHook(payload, options = {}) {
     if (hookEventName === "UserPromptSubmit") {
         const prompt = readPromptText(payload);
         if (prompt) {
-            skillState = await recordSkillActivation({
+            skillState = buildNativeOutsideTmuxTeamPromptBlockState(prompt, cwd, payload, sessionIdForState, threadId || undefined, turnId || undefined) ?? await recordSkillActivation({
                 stateDir,
                 text: prompt,
                 sessionId: sessionIdForState,
@@ -1326,6 +1625,10 @@ export async function dispatchCodexNativeHook(payload, options = {}) {
                                 triageAdditionalContext =
                                     "OMX native UserPromptSubmit triage detected a visual/style request with no workflow keyword. This is advisory prompt-routing context only. Prefer the designer role surface.";
                             }
+                            else if (decision.destination === "researcher") {
+                                triageAdditionalContext =
+                                    "OMX native UserPromptSubmit triage detected an external documentation/reference research request with no workflow keyword. This is advisory prompt-routing context only. Prefer the researcher role surface rather than repo-local explore or autopilot.";
+                            }
                             if (triageAdditionalContext !== null) {
                                 const dest = decision.destination;
                                 const newState = {
@@ -1355,7 +1658,7 @@ export async function dispatchCodexNativeHook(payload, options = {}) {
         const reconcileHudForPromptSubmitFn = options.reconcileHudForPromptSubmitFn ?? reconcileHudForPromptSubmit;
         await reconcileHudForPromptSubmitFn(cwd, { sessionId: canonicalSessionId || sessionIdForState || undefined }).catch(() => { });
     }
-    if (omxEventName) {
+    if (omxEventName && !skipCanonicalSessionStartContext) {
         const baseContext = buildBaseContext(cwd, payload, hookEventName, canonicalSessionId);
         if (resolvedNativeSessionId) {
             baseContext.native_session_id = resolvedNativeSessionId;
@@ -1372,9 +1675,14 @@ export async function dispatchCodexNativeHook(payload, options = {}) {
         });
         await dispatchHookEvent(event, { cwd });
     }
-    if (hookEventName === "SessionStart" || hookEventName === "UserPromptSubmit") {
+    if ((hookEventName === "SessionStart" && !skipCanonicalSessionStartContext) || hookEventName === "UserPromptSubmit") {
         const additionalContext = hookEventName === "SessionStart"
-            ? await buildSessionStartContext(cwd, canonicalSessionId || nativeSessionId)
+            ? await buildSessionStartContext(cwd, canonicalSessionId || nativeSessionId, {
+                hookEventName,
+                payload,
+                canonicalSessionId,
+                nativeSessionId: resolvedNativeSessionId || nativeSessionId,
+            })
             : (buildAdditionalContextMessage(readPromptText(payload), skillState, cwd, payload) ?? triageAdditionalContext);
         if (additionalContext) {
             outputJson = {
@@ -1393,6 +1701,7 @@ export async function dispatchCodexNativeHook(payload, options = {}) {
             await markTeamTransportFailure(cwd, payload);
         }
         outputJson = buildNativePostToolUseOutput(payload);
+        await handleTeamWorkerPostToolUseSuccess(payload, cwd);
     }
     else if (hookEventName === "Stop") {
         outputJson = await buildStopHookOutput(payload, cwd, stateDir);
@@ -1431,22 +1740,55 @@ async function readStdinJson() {
         };
     }
 }
+function writeNativeHookJsonStdout(output) {
+    process.stdout.write(`${JSON.stringify(output)}\n`);
+}
+function isStopDispatchFailureTestTrigger(payload) {
+    return process.env.NODE_ENV === "test"
+        && process.env.OMX_NATIVE_HOOK_TEST_THROW_STOP_DISPATCH === "1"
+        && readHookEventName(payload) === "Stop";
+}
+function buildStopDispatchFailureOutput(error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    const reason = "OMX native Stop hook failed before normal continuation handling. Continue once more, preserve runtime state, inspect the hook logs, and retry with a valid Stop JSON response.";
+    return {
+        decision: "block",
+        reason,
+        stopReason: "native_stop_dispatch_failure",
+        systemMessage: `${reason} Failure: ${detail}`,
+    };
+}
 export async function runCodexNativeHookCli() {
     const { payload, parseError } = await readStdinJson();
     if (parseError) {
-        process.stdout.write(`${JSON.stringify({
+        writeNativeHookJsonStdout({
             decision: "block",
             reason: "OMX native hook received malformed JSON input. Preserve runtime state, inspect the emitting hook payload yourself, and retry with valid JSON.",
             hookSpecificOutput: {
                 hookEventName: "Unknown",
                 additionalContext: `stdin JSON parsing failed inside codex-native-hook: ${parseError.message}. Emit valid JSON from the native hook caller before retrying.`,
             },
-        })}\n`);
+        });
         return;
     }
-    const result = await dispatchCodexNativeHook(payload);
-    if (result.outputJson) {
-        process.stdout.write(`${JSON.stringify(result.outputJson)}\n`);
+    try {
+        if (isStopDispatchFailureTestTrigger(payload)) {
+            throw new Error("test-induced Stop dispatch failure");
+        }
+        const result = await dispatchCodexNativeHook(payload);
+        if (result.outputJson) {
+            writeNativeHookJsonStdout(result.outputJson);
+        }
+        else if (result.hookEventName === "Stop") {
+            writeNativeHookJsonStdout({});
+        }
+    }
+    catch (error) {
+        if (readHookEventName(payload) !== "Stop") {
+            throw error;
+        }
+        process.stderr.write(`[omx] codex-native Stop hook dispatch failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        writeNativeHookJsonStdout(buildStopDispatchFailureOutput(error));
     }
 }
 if (isCodexNativeHookMainModule(import.meta.url, process.argv[1])) {