oh-my-codex 0.20.1 → 0.20.2

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

@@ -6,18 +6,22 @@ import { pathToFileURL } from "url";
 import { readModeStateForActiveDecision, readModeStateForSession, updateModeState } from "../modes/base.js";
 import { redactAuthSecrets } from "../auth/redact.js";
 import { SKILL_ACTIVE_STATE_FILE, extractSessionIdFromInitializedStatePath, getSkillActiveStatePathsForStateDir, listActiveSkills, readSkillActiveState, readVisibleSkillActiveStateForStateDir, } from "../state/skill-active.js";
-import { isTrustedSubagentThread, readSubagentSessionSummary, readSubagentSessionLedger, readSubagentTrackingState, recordSubagentTurnForSession, } from "../subagents/tracker.js";
+import { isTrustedSubagentThread, OMX_ADAPTED_PROVENANCE, attestLeaderThread, readSubagentSessionSummary, readSubagentSessionLedger, readSubagentTrackingState, readSubagentTrackingStateStrict, recordSubagentTurn, recordSubagentTurnForSession, resolveInstalledRoleName, } from "../subagents/tracker.js";
+import { bindAndPublishAdaptedRole, NATIVE_SUBAGENT_ROLE_ROUTING_MARKER_TTL_MS, recoverAdaptedRoleBindings, } from "../subagents/adapted-role-binding.js";
+import { readRoleRoutingMarker, writeRoleRoutingMarker } from "../subagents/role-routing-marker.js";
 import { resolveCanonicalTeamStateRoot, resolveWorkerNotifyTeamStateRootPath } from "../team/state-root.js";
 import { inferTerminalLifecycleOutcome } from "../runtime/run-outcome.js";
-import { appendToLog, isSessionStale, isSessionStateUsable, readSessionState, readUsableSessionState, reconcileNativeSessionStart, } from "../hooks/session.js";
+import { appendPromptSessionProvenanceRejection, appendToLog, isSessionPointerLaunchAbort, isSessionStale, isSessionStateUsable, normalizeSessionId, readSessionPointer, readSessionState, readUsableSessionState, reconcileNativeSessionStart, resolveSessionPointerContext, } from "../hooks/session.js";
+import { evaluateResolvedPromptTurn, extractSelectedTargetOwnerEvidence, preflightSelectedTargetOwner, } from "../hooks/prompt-session-provenance.js";
 import { appendTeamEvent, readTeamLeaderAttention, readTeamConfig, readTeamManifestV2, readTeamPhase, writeTeamLeaderAttention, writeTeamPhase, } from "../team/state.js";
-import { codexAgentsDir, omxNotepadPath, projectCodexAgentsDir, resolveProjectMemoryPath } from "../utils/paths.js";
+import { omxNotepadPath, resolveProjectMemoryPath } from "../utils/paths.js";
 import { findGitLayout } from "../utils/git-layout.js";
-import { getBaseStateDir, getStateFilePath, getStatePath, getAuthoritativeActiveStatePaths } from "../mcp/state-paths.js";
-import { detectKeywords, detectPrimaryKeyword, recordSkillActivation, } from "../hooks/keyword-detector.js";
+import { getAuthoritativeActiveStatePaths, getBaseStateDir, getStateFilePath, getStatePath, resolveWritableStateScope, WRITABLE_STATE_SCOPE_ERRORS, } from "../mcp/state-paths.js";
+import { classifyKeywordInput, recordSkillActivation, } from "../hooks/keyword-detector.js";
 import { buildDeepInterviewConfigInstruction } from "../hooks/deep-interview-config-instruction.js";
 import { readTeamModeConfig } from "../config/team-mode.js";
 import { detectNativeStopStallPattern, loadAutoNudgeConfig, normalizeAutoNudgeSignatureText, resolveEffectiveAutoNudgeResponse, } from "./notify-hook/auto-nudge.js";
+import { probeActualTmuxInstanceEvidence, tmuxEvidenceBindsCandidate } from "./notify-hook/managed-tmux.js";
 import { SLOPPY_FALLBACK_GROUNDING_PATTERNS, SLOPPY_FALLBACK_IMPLEMENTATION_CONTEXT_PATTERNS, SLOPPY_FALLBACK_PHRASE_PATTERNS, buildNativePostToolUseOutput, buildNativePreToolUseOutput, commandInvokesApplyPatch, detectMcpTransportFailure, hasAnyPattern, } from "./codex-native-pre-post.js";
 import { handleTeamWorkerPostToolUseSuccess } from "./notify-hook/team-worker-posttooluse.js";
 import { maybeNudgeLeaderForAllowedWorkerStop } from "./notify-hook/team-worker-stop.js";
@@ -29,9 +33,8 @@ import { getNotificationConfig, getVerbosity } from "../notifications/config.js"
 import { reconcileHudForPromptSubmit } from "../hud/reconcile.js";
 import { onPreCompact as buildWikiPreCompactContext, onSessionStart as buildWikiSessionStartContext, } from "../wiki/lifecycle.js";
 import { readAutoresearchCompletionStatus, readAutoresearchModeStateForActiveDecision } from "../autoresearch/skill-validation.js";
-import { AGENT_DEFINITIONS } from "../agents/definitions.js";
 import { deriveAutopilotChildPhase, normalizeAutopilotPhase } from "../autopilot/fsm.js";
-import { CONDUCTOR_ORCHESTRATION_METADATA_PREFIXES, LEADER_CONDUCTOR_BLOCK, LEADER_CONDUCTOR_REUSE_AND_LEDGER_GUIDANCE, NATIVE_SUBAGENT_SUPPORT_BLOCKER_FILE, actionKindForConductorArtifact, authorizeConductorAction, buildUnsupportedNativeSubagentGuidance, classifyConductorArtifactKind, isUnsupportedNativeSubagentEvidence, resolveNativeSubagentSupportStatus, } from "../leader/contract.js";
+import { CONDUCTOR_ORCHESTRATION_METADATA_PREFIXES, LEADER_CONDUCTOR_BLOCK, LEADER_CONDUCTOR_REUSE_AND_LEDGER_GUIDANCE, NATIVE_SUBAGENT_SUPPORT_BLOCKER_FILE, actionKindForConductorArtifact, authorizeConductorAction, buildRoleRoutingUnavailableGuidance, buildUnsupportedNativeSubagentGuidance, classifyConductorArtifactKind, isNativeSubagentSpawnToolName, isRoleRoutingUnavailableEvidence, isUnsupportedNativeSubagentEvidence, parseRoleIntentCorrelationToken, resolveNativeSubagentSupportStatus, } from "../leader/contract.js";
 import { readRunState } from "../runtime/run-state.js";
 import { evaluateRalphCompletionAuditEvidence, isRalphCompletePhase } from "../ralph/completion-audit.js";
 import { buildCodexGoalTerminalCleanupNotice, } from "../goal-workflows/codex-goal-snapshot.js";
@@ -89,9 +92,6 @@ const RALPH_LIVE_RISK_PATTERNS = [
     /\b(?:database|db|terraform|kubectl|kubernetes|aws|gcp|azure|external|destructive)\b/i,
     /\b(?:telegram|vps|service|restart|send|notify|notification|notifications|cron)\b/i,
 ];
-const KNOWN_TYPED_AGENT_ROLES = new Set(Object.keys(AGENT_DEFINITIONS));
-let installedTypedAgentRoleNamesCacheKey = "";
-let installedTypedAgentRoleNamesCache = new Set();
 const RALPH_TASK_TEXT_FIELDS = [
     "task_description",
     "taskDescription",
@@ -115,6 +115,18 @@ const MAX_SESSION_META_LINE_BYTES = 256 * 1024;
 function safeString(value) {
     return typeof value === "string" ? value : "";
 }
+async function resolveVerifiedOwnerOmxSessionId() {
+    const candidate = normalizeSessionId(process.env.OMX_SESSION_ID);
+    if (!candidate)
+        return undefined;
+    const evidence = await probeActualTmuxInstanceEvidence(process.env.TMUX_PANE);
+    return tmuxEvidenceBindsCandidate(evidence, candidate) ? candidate : undefined;
+}
+function isImplicitWritableScopeFailure(error) {
+    return error instanceof Error
+        && (error.message === WRITABLE_STATE_SCOPE_ERRORS.unboundEnvironment
+            || error.message === WRITABLE_STATE_SCOPE_ERRORS.unusableSession);
+}
 function safeObject(value) {
     return value && typeof value === "object" ? value : {};
 }
@@ -219,6 +231,14 @@ function readBoundedFirstLineSync(path) {
         closeSync(fd);
     }
 }
+function selectAuthoritativeTaskName(threadSpawn, subagent, payload) {
+    for (const obj of [threadSpawn, subagent, payload]) {
+        if (obj && typeof obj === "object" && "task_name" in obj) {
+            return { present: true, value: obj.task_name };
+        }
+    }
+    return { present: false, value: undefined };
+}
 function readNativeSubagentSessionStartMetadata(transcriptPath) {
     const normalizedPath = transcriptPath.trim();
     if (!normalizedPath)
@@ -237,40 +257,100 @@ function readNativeSubagentSessionStartMetadata(transcriptPath) {
         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();
+        const agentNicknameCarrierValues = [
+            threadSpawn.agent_nickname ?? threadSpawn.agentNickname,
+            subagent.agent_nickname ?? subagent.agentNickname,
+            payload.agent_nickname ?? payload.agentNickname,
+        ];
+        const agentNickname = safeString(agentNicknameCarrierValues[0]).trim();
+        const authoritativeTaskName = selectAuthoritativeTaskName(threadSpawn, subagent, payload);
+        const correlationToken = authoritativeTaskName.present
+            ? parseRoleIntentCorrelationToken(authoritativeTaskName.value)
+            : undefined;
+        const agentRole = safeString(threadSpawn.agent_role
+            ?? threadSpawn.agentRole
+            ?? threadSpawn.agent_type
+            ?? threadSpawn.agentType
+            ?? payload.agent_role
+            ?? payload.agentRole
+            ?? payload.agent_type
+            ?? payload.agentType).trim();
         return {
             parentThreadId,
             ...(agentNickname ? { agentNickname } : {}),
             ...(agentRole ? { agentRole } : {}),
+            ...(correlationToken ? { correlationToken } : {}),
         };
     }
     catch {
         return null;
     }
 }
+function reportRoleRoutingBindingFailure(error) {
+    console.error(`[omx] SECURITY: native adapted role binding did not complete; retained binding will be recovered: ${error instanceof Error ? error.message : String(error)}`);
+}
 async function recordNativeSubagentSessionStart(cwd, canonicalSessionId, childSessionId, metadata, transcriptPath) {
     const parentThreadId = metadata.parentThreadId.trim();
     const childThreadId = childSessionId.trim();
+    const correlationSessionId = canonicalSessionId.trim() || parentThreadId;
     const trackingSessionIds = [...new Set([
             canonicalSessionId.trim(),
             parentThreadId,
         ].filter(Boolean))];
-    for (const sessionId of trackingSessionIds) {
-        if (parentThreadId && parentThreadId !== childThreadId) {
+    let adaptedRoleIntent = null;
+    if (!metadata.agentRole && correlationSessionId && parentThreadId) {
+        try {
+            const bound = bindAndPublishAdaptedRole(cwd, getBaseStateDir(cwd), {
+                correlationSessionId,
+                parentThreadId,
+                correlationToken: metadata.correlationToken,
+            }, (state, intent) => {
+                let next = state;
+                for (const sessionId of trackingSessionIds) {
+                    if (parentThreadId && parentThreadId !== childThreadId) {
+                        next = recordSubagentTurn(next, {
+                            sessionId,
+                            threadId: parentThreadId,
+                            kind: "leader",
+                        });
+                    }
+                    next = recordSubagentTurn(next, {
+                        sessionId,
+                        threadId: childThreadId,
+                        kind: "subagent",
+                        ...(parentThreadId && parentThreadId !== childThreadId ? { leaderThreadId: parentThreadId } : {}),
+                        mode: intent.role,
+                        role: intent.role,
+                        provenanceKind: intent.provenanceKind,
+                    });
+                }
+                return next;
+            });
+            adaptedRoleIntent = bound ? { role: bound.role, provenanceKind: OMX_ADAPTED_PROVENANCE } : null;
+        }
+        catch (error) {
+            reportRoleRoutingBindingFailure(error);
+            throw error;
+        }
+    }
+    if (!adaptedRoleIntent) {
+        for (const sessionId of trackingSessionIds) {
+            if (parentThreadId && parentThreadId !== childThreadId) {
+                await recordSubagentTurnForSession(cwd, {
+                    sessionId,
+                    threadId: parentThreadId,
+                    kind: "leader",
+                }).catch(() => { });
+            }
             await recordSubagentTurnForSession(cwd, {
                 sessionId,
-                threadId: parentThreadId,
-                kind: 'leader',
+                threadId: childThreadId,
+                kind: "subagent",
+                ...(parentThreadId && parentThreadId !== childThreadId ? { leaderThreadId: parentThreadId } : {}),
+                mode: metadata.agentRole,
             }).catch(() => { });
         }
-        await recordSubagentTurnForSession(cwd, {
-            sessionId,
-            threadId: childThreadId,
-            kind: 'subagent',
-            ...(parentThreadId && parentThreadId !== childThreadId ? { leaderThreadId: parentThreadId } : {}),
-            mode: metadata.agentRole,
-        }).catch(() => { });
+        refreshNativeSubagentRoleRoutingMarker(cwd, getBaseStateDir(cwd), correlationSessionId, parentThreadId);
     }
     await appendToLog(cwd, {
         event: "subagent_session_start",
@@ -349,6 +429,26 @@ async function isNativeSubagentHook(cwd, canonicalSessionId, nativeSessionId, th
         return false;
     return Object.values(trackingState.sessions).some((session) => (candidateIds.some((id) => isTrustedSubagentThread(session, id))));
 }
+async function readNativePromptThreadFacts(cwd, nativeSessionId, threadId, currentSessionState) {
+    const candidateIds = [nativeSessionId, threadId].map((value) => value.trim()).filter(Boolean);
+    if (candidateIds.length === 0)
+        return undefined;
+    const currentNativeIds = new Set([
+        safeString(currentSessionState?.native_session_id).trim(),
+        safeString(currentSessionState?.codex_session_id).trim(),
+        safeString(currentSessionState?.owner_codex_session_id).trim(),
+    ].filter(Boolean));
+    const currentTargetAnchored = Boolean(nativeSessionId && currentNativeIds.has(nativeSessionId));
+    const trackingState = await readSubagentTrackingState(cwd).catch(() => null);
+    if (!trackingState)
+        return currentTargetAnchored ? { currentTargetAnchored: true, rootOrDrift: true } : undefined;
+    const roots = Object.values(trackingState.sessions).flatMap((session) => (candidateIds.some((candidate) => isTrustedSubagentThread(session, candidate))
+        ? [session.session_id]
+        : []));
+    return roots.length > 0 || currentTargetAnchored
+        ? { trackerRootOwnerSessionIds: roots, currentTargetAnchored, rootOrDrift: currentTargetAnchored }
+        : undefined;
+}
 function shouldSuppressSubagentLifecycleHookDispatch() {
     const config = getNotificationConfig();
     if (config?.includeChildAgents === true)
@@ -494,8 +594,8 @@ function readPromptText(payload) {
         payload.userPrompt,
     ];
     for (const candidate of candidates) {
-        const value = safeString(candidate).trim();
-        if (value)
+        const value = safeString(candidate);
+        if (value.trim())
             return value;
     }
     return "";
@@ -1759,19 +1859,21 @@ function buildTeamHelpInstruction(cwd, payload) {
         nativeSessionId: safeString(payload?.session_id ?? payload?.sessionId).trim(),
     }).teamHelpInstruction;
 }
-function buildNativeOutsideTmuxTeamPromptBlockState(prompt, cwd, payload, sessionId, threadId, turnId) {
-    if (!readTeamModeConfig(cwd).enabled)
-        return null;
-    const match = detectPrimaryKeyword(prompt);
-    if (match?.skill !== "team")
-        return null;
+function isNativeOutsideTmuxUserPrompt(cwd, payload, sessionId) {
     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 environment.launcher === "native" && environment.transport === "outside-tmux";
+}
+function buildNativeOutsideTmuxTeamPromptBlockState(classification, cwd, payload, sessionId, threadId, turnId) {
+    const teamMode = readTeamModeConfig(cwd);
+    const match = classification.matches.filter((entry) => teamMode.enabled || entry.skill !== "team")[0] ?? null;
+    if (match?.skill !== "team")
+        return null;
+    if (!isNativeOutsideTmuxUserPrompt(cwd, payload, sessionId))
         return null;
     const nowIso = new Date().toISOString();
     return {
@@ -1803,13 +1905,19 @@ function buildAutopilotPromptActivationNote(skillState, options = {}) {
     const nativeSubagentSupport = resolveNativeSubagentSupportStatus({
         payload: options.payload,
         persistedSupportBlocker: readJsonSyncIfExists(nativeSubagentSupportBlockerPath(stateDir)),
+        persistedRoleRoutingMarker: readRoleRoutingMarker(stateDir, {
+            cwd: options.cwd,
+            sessionId: options.sessionId ?? "",
+        }),
         persistedCapacityBlocker: readJsonSyncIfExists(nativeSubagentCapacityBlockerPath(stateDir)),
         cwd: options.cwd,
         sessionId: options.sessionId,
     });
     const conductorGuidance = nativeSubagentSupport.status === "unsupported"
         ? buildUnsupportedNativeSubagentGuidance(nativeSubagentSupport)
-        : `${LEADER_CONDUCTOR_BLOCK} ${LEADER_CONDUCTOR_REUSE_AND_LEDGER_GUIDANCE}`;
+        : nativeSubagentSupport.status === "role_routing_unavailable"
+            ? buildRoleRoutingUnavailableGuidance(nativeSubagentSupport)
+            : `${LEADER_CONDUCTOR_BLOCK} ${LEADER_CONDUCTOR_REUSE_AND_LEDGER_GUIDANCE}`;
     return [
         `Autopilot protocol: the durable default chain is $deep-interview -> $ralplan -> $ultragoal${teamHandoff} -> $code-review -> $ultraqa (deep-interview -> ralplan -> ultragoal -> code-review -> ultraqa).`,
         "Start/resume at current_phase=deep-interview unless the task is clear and bounded; if deep-interview is intentionally skipped, persist and state an explicit deep_interview_gate.skip_reason before moving to ralplan.",
@@ -1829,7 +1937,8 @@ function formatExecutionHandoffList(cwd) {
         ? "`$ultragoal`, `$team`, or `$ralph`"
         : "`$ultragoal` or `$ralph`";
 }
-function buildAdditionalContextMessage(prompt, skillState, cwd = process.cwd(), payload) {
+function buildAdditionalContextMessage(classification, skillState, cwd = process.cwd(), payload) {
+    const prompt = classification.originalText;
     if (!prompt)
         return null;
     const promptPriorityMessage = buildPromptPriorityMessage(prompt);
@@ -1837,20 +1946,29 @@ function buildAdditionalContextMessage(prompt, skillState, cwd = process.cwd(),
         return promptPriorityMessage;
     }
     const teamMode = readTeamModeConfig(cwd);
-    const matches = detectKeywords(prompt).filter((entry) => teamMode.enabled || entry.skill !== "team");
+    const matches = classification.matches.filter((entry) => teamMode.enabled || entry.skill !== "team");
     const match = matches[0] ?? null;
     if (!match) {
+        const markedQuestionAnswer = classification.reservedInput === "omx-question-answered";
         const continuedSkill = safeString(skillState?.skill).trim();
-        if (!continuedSkill)
+        const eligibleMarkedContinuation = markedQuestionAnswer
+            && skillState?.active === true
+            && (continuedSkill === "autopilot" || continuedSkill === "deep-interview");
+        const eligibleOrdinaryContinuation = classification.reservedInput === null
+            && !classification.hasExplicitLikeInvocation
+            && skillState?.active === true
+            && Boolean(continuedSkill);
+        if (!eligibleMarkedContinuation && !eligibleOrdinaryContinuation)
             return promptPriorityMessage;
         const deepInterviewPromptActivationNote = skillState?.initialized_mode === "deep-interview"
             ? buildDeepInterviewQuestionBridgeInstruction(cwd, payload)
             : null;
         const deepInterviewConfigPromptActivationNote = buildDeepInterviewConfigInstruction(cwd, skillState);
-        const markedQuestionAnswer = /^\s*\[omx question answered\]/i.test(prompt);
         const autopilotPromptActivationNote = buildAutopilotPromptActivationNote(skillState, { markedQuestionAnswer, cwd, payload, sessionId: safeString(skillState?.session_id).trim() });
         return [
-            `OMX native UserPromptSubmit continued active workflow skill "${continuedSkill}".`,
+            markedQuestionAnswer
+                ? `OMX native UserPromptSubmit continued active workflow skill "${continuedSkill}"; workflow-like tokens inside the marked omx question answer are treated as answer text, not a new workflow activation.`
+                : `OMX native UserPromptSubmit continued active workflow skill "${continuedSkill}".`,
             promptPriorityMessage,
             skillState?.initialized_mode && skillState.initialized_state_path
                 ? buildSkillStateCliInstruction(skillState.initialized_mode, skillState.initialized_state_path)
@@ -1864,27 +1982,6 @@ function buildAdditionalContextMessage(prompt, skillState, cwd = process.cwd(),
     const detectedKeywordMessage = matches.length > 1
         ? `OMX native UserPromptSubmit detected workflow keywords ${matches.map((entry) => `"${entry.keyword}" -> ${entry.skill}`).join(", ")}.`
         : `OMX native UserPromptSubmit detected workflow keyword "${match.keyword}" -> ${match.skill}.`;
-    const continuedSkill = safeString(skillState?.skill).trim();
-    if (continuedSkill
-        && continuedSkill !== match.skill
-        && /^\s*\[omx question answered\]/i.test(prompt)) {
-        const deepInterviewPromptActivationNote = skillState?.initialized_mode === "deep-interview"
-            ? buildDeepInterviewQuestionBridgeInstruction(cwd, payload)
-            : null;
-        const deepInterviewConfigPromptActivationNote = buildDeepInterviewConfigInstruction(cwd, skillState);
-        const autopilotPromptActivationNote = buildAutopilotPromptActivationNote(skillState, { markedQuestionAnswer: true, cwd, payload, sessionId: safeString(skillState?.session_id).trim() });
-        return [
-            `OMX native UserPromptSubmit continued active workflow skill "${continuedSkill}"; workflow-like tokens inside the marked omx question answer are treated as answer text, not a new workflow activation.`,
-            promptPriorityMessage,
-            skillState?.initialized_mode && skillState.initialized_state_path
-                ? buildSkillStateCliInstruction(skillState.initialized_mode, skillState.initialized_state_path)
-                : null,
-            deepInterviewPromptActivationNote,
-            deepInterviewConfigPromptActivationNote,
-            autopilotPromptActivationNote,
-            "Follow AGENTS.md routing and preserve workflow transition and planning-safety rules.",
-        ].filter(Boolean).join(" ");
-    }
     const activeSkills = Array.isArray(skillState?.active_skills)
         ? skillState.active_skills.map((entry) => entry.skill)
         : [];
@@ -2627,31 +2724,66 @@ function readPayloadAgentRole(payload) {
         ?? threadSpawn?.agent_type
         ?? threadSpawn?.agentType).trim().toLowerCase();
 }
-function readInstalledTypedAgentRoleNames() {
-    const cacheKey = [codexAgentsDir(), projectCodexAgentsDir()].join("|");
-    if (installedTypedAgentRoleNamesCacheKey === cacheKey)
-        return installedTypedAgentRoleNamesCache;
-    const installedRoleNames = new Set();
-    for (const agentsDir of [codexAgentsDir(), projectCodexAgentsDir()]) {
-        try {
-            for (const entry of readdirSync(agentsDir, { withFileTypes: true })) {
-                if (!entry.isFile() || !entry.name.endsWith(".toml"))
-                    continue;
-                installedRoleNames.add(entry.name.slice(0, -5).trim().toLowerCase());
-            }
-        }
-        catch {
-            // Ignore missing or unreadable agent directories; built-in definitions remain authoritative.
-        }
-    }
-    installedTypedAgentRoleNamesCacheKey = cacheKey;
-    installedTypedAgentRoleNamesCache = installedRoleNames;
-    return installedTypedAgentRoleNamesCache;
+function readRequestedSpawnRole(payload) {
+    const toolName = safeString(payload.tool_name).trim();
+    if (!isNativeSubagentSpawnToolName(toolName))
+        return "";
+    const toolInput = safeObject(payload.tool_input);
+    return safeString(toolInput.agent_role
+        ?? toolInput.agentRole
+        ?? toolInput.agent_type
+        ?? toolInput.agentType).trim().toLowerCase();
 }
 function isTypedAgentRolePayload(payload) {
     const agentRole = readPayloadAgentRole(payload);
-    return agentRole !== "" && (KNOWN_TYPED_AGENT_ROLES.has(agentRole)
-        || readInstalledTypedAgentRoleNames().has(agentRole));
+    return agentRole !== "" && resolveInstalledRoleName(agentRole) !== null;
+}
+// #3181: detect a runtime-set native subagent PreToolUse. The runtime sets
+// source.subagent.thread_spawn (not agent-controlled tool arguments), so the mere
+// STRUCTURAL PRESENCE of that carrier — even if its parent id is blank, malformed, or
+// null — marks a child/subagent turn that must never be attested as the session leader.
+// This is a negative security decision, so it fails closed on any present carrier rather
+// than requiring a well-formed parent id.
+function hasSubagentThreadSpawnProvenance(payload) {
+    const source = payload.source;
+    if (!source || typeof source !== "object")
+        return false;
+    const subagent = source.subagent;
+    if (!subagent || typeof subagent !== "object")
+        return false;
+    return Object.prototype.hasOwnProperty.call(subagent, "thread_spawn");
+}
+// #3181: positive counter-evidence guard. A thread durably tracked as a subagent in ANY
+// session must never be attested as a leader, even if the current payload lacks typed-role
+// or thread_spawn provenance. This closes the source-less/untyped child escalation where a
+// child recorded at its SessionStart later self-promotes via a source-less PreToolUse.
+async function isThreadTrackedAsSubagent(cwd, threadId) {
+    const id = threadId.trim();
+    if (!id)
+        return false;
+    // Strict read: an unreadable/corrupt tracker fails closed (treated as "is a subagent")
+    // so corrupt evidence cannot let a source-less child reconcile/attest as leader.
+    const read = await readSubagentTrackingStateStrict(cwd);
+    if (!read.ok)
+        return true;
+    for (const session of Object.values(read.state.sessions)) {
+        if (session.threads?.[id]?.kind === "subagent")
+            return true;
+    }
+    return false;
+}
+function buildNativeUnknownRolePreToolUseOutput(payload) {
+    const requestedRole = readRequestedSpawnRole(payload);
+    if (!requestedRole || resolveInstalledRoleName(requestedRole) !== null)
+        return null;
+    return {
+        decision: "block",
+        reason: "Native typed-subagent dispatch denied: supplied agent_type/agent_role is unknown or not installed.",
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            additionalContext: "Use an installed OMX role for native agent_type/agent_role dispatch. On a role-routing-unavailable surface, record a validated OMX adapted role intent before spawning without fabricating agent_type.",
+        },
+    };
 }
 function readPayloadTurnId(payload) {
     return safeString(payload.turn_id ?? payload.turnId).trim();
@@ -2736,6 +2868,21 @@ async function recordNativeSubagentSupportBlocker(cwd, stateDir, payload) {
         cwd,
     }, null, 2));
 }
+function refreshNativeSubagentRoleRoutingMarker(cwd, stateDir, sessionId, parentThreadId) {
+    const marker = readRoleRoutingMarker(stateDir, {
+        cwd,
+        sessionId,
+        ...(parentThreadId ? { parentThreadId } : {}),
+    });
+    if (!marker)
+        return;
+    const nowMs = Date.now();
+    writeRoleRoutingMarker(stateDir, {
+        ...marker,
+        observed_at: new Date(nowMs).toISOString(),
+        expires_at: new Date(nowMs + NATIVE_SUBAGENT_ROLE_ROUTING_MARKER_TTL_MS).toISOString(),
+    });
+}
 function summarizeCapacityFailure(text) {
     const normalized = text.replace(/\s+/g, " ").trim();
     if (!normalized)
@@ -2824,13 +2971,13 @@ async function buildNativeSubagentCapacityCloseGuardOutput(payload, cwd, stateDi
         },
     };
 }
-async function resolveInternalSessionIdForPayload(cwd, payloadSessionId, stateDir) {
-    const currentSession = stateDir
+async function resolveInternalSessionIdForPayload(cwd, payloadSessionId, stateDir, pointerSessionState, allowUnboundPayloadFallback = true) {
+    const currentSession = pointerSessionState ?? (stateDir
         ? await readUsableSessionStateFromStateDir(cwd, stateDir)
-        : await readUsableSessionState(cwd);
+        : await readUsableSessionState(cwd));
     const canonicalSessionId = safeString(currentSession?.session_id).trim();
     if (!canonicalSessionId)
-        return payloadSessionId;
+        return allowUnboundPayloadFallback ? payloadSessionId : "";
     const nativeSessionId = safeString(currentSession?.native_session_id).trim();
     const ownerOmxSessionId = safeString(currentSession?.owner_omx_session_id).trim();
     if (!payloadSessionId)
@@ -2841,7 +2988,7 @@ async function resolveInternalSessionIdForPayload(cwd, payloadSessionId, stateDi
         return canonicalSessionId;
     if (ownerOmxSessionId && payloadSessionId === ownerOmxSessionId)
         return canonicalSessionId;
-    return payloadSessionId;
+    return allowUnboundPayloadFallback ? payloadSessionId : "";
 }
 async function readRootSessionStateFromStateDir(stateDir) {
     const sessionPath = join(stateDir, "session.json");
@@ -2945,17 +3092,6 @@ const RALPLAN_EXECUTION_HANDOFF_SKILLS = new Set([
     "ultrawork",
     "ultraqa",
 ]);
-function isActiveDeepInterviewPhase(state) {
-    if (!state || state.active !== true)
-        return false;
-    const mode = safeString(state.mode).trim();
-    if (mode && mode !== "deep-interview")
-        return false;
-    const phase = safeString(state.current_phase ?? state.currentPhase).trim().toLowerCase();
-    if (phase && (TERMINAL_MODE_PHASES.has(phase) || phase === "completing"))
-        return false;
-    return true;
-}
 function isInactiveCompletedDeepInterviewPhase(state) {
     if (!state || state.active !== false)
         return false;
@@ -6250,6 +6386,121 @@ function isCompleteRalplanTerminalWritePayload(payload, activeState, sessionId)
         return false;
     return true;
 }
+function hasUnquotedShellControlOrRedirection(command) {
+    let quote = null;
+    for (let index = 0; index < command.length; index += 1) {
+        const char = command[index] ?? "";
+        if (char === "\\" && quote !== "'") {
+            index += 1;
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quote = quote === char ? null : quote ?? char;
+            continue;
+        }
+        if (!quote && ";&|()<>\n\r".includes(char))
+            return true;
+    }
+    return false;
+}
+function suppliedSessionAliasesMatch(payload, sessionId) {
+    return [
+        payload.session_id,
+        payload.owner_omx_session_id,
+        payload.codex_session_id,
+        payload.owner_codex_session_id,
+    ].filter((value) => value !== undefined)
+        .every((value) => safeString(value).trim() === sessionId);
+}
+function hasOnlyFinishedExplicitOutcomes(payload) {
+    const values = [
+        payload.lifecycle_outcome,
+        payload.lifecycleOutcome,
+        payload.terminal_outcome,
+        payload.terminalOutcome,
+        payload.run_outcome,
+        payload.runOutcome,
+    ].filter((value) => value !== undefined);
+    return values.every((value) => inferTerminalLifecycleOutcome({ lifecycle_outcome: value }, { includeQuestionEnforcement: false }) === "finished");
+}
+function isCompleteDeepInterviewTerminalWritePayload(payload, activeState, sessionId) {
+    if (!sessionId)
+        return false;
+    const activeMode = safeString(activeState.mode).trim().toLowerCase();
+    if (activeMode && activeMode !== "deep-interview")
+        return false;
+    const activeSessionId = safeString(activeState.session_id
+        ?? activeState.owner_omx_session_id
+        ?? activeState.codex_session_id
+        ?? activeState.owner_codex_session_id).trim();
+    if (activeSessionId && activeSessionId !== sessionId)
+        return false;
+    const mode = safeString(payload.mode).trim().toLowerCase();
+    const phase = safeString(payload.current_phase ?? payload.currentPhase).trim().toLowerCase();
+    const payloadSessionId = safeString(payload.session_id).trim();
+    if (!hasOnlyFinishedExplicitOutcomes(payload))
+        return false;
+    return mode === "deep-interview"
+        && payload.active === false
+        && phase === "complete"
+        && payloadSessionId === sessionId
+        && inferTerminalLifecycleOutcome(payload, { includeQuestionEnforcement: false }) === "finished";
+}
+function isAllowedDeepInterviewTerminalStateWriteCommand(cwd, command, activeState, sessionId) {
+    const rawWords = tokenizeShellWords(normalizeShellLineContinuations(command).trim());
+    if (rawWords[0] !== "omx")
+        return false;
+    const canonicalCommand = canonicalizeOmxStateTransportCommand(command);
+    if (hasUnquotedShellControlOrRedirection(command))
+        return false;
+    if (hasUnsafeUnquotedHeredocExpansion(canonicalCommand))
+        return false;
+    if (hasUnquotedShellSubstitution(canonicalCommand))
+        return false;
+    if (splitStateScanSegments(canonicalCommand).length !== 1)
+        return false;
+    if (sourcesFileWrittenEarlierInSameCommand(cwd, canonicalCommand))
+        return false;
+    if (findUnquotedOmxStateCommandIndexes(canonicalCommand, "clear").length > 0)
+        return false;
+    if (hasDynamicNestedShellExecution(canonicalCommand))
+        return false;
+    if (extractDeepInterviewCommandWriteTargets(command).length > 0)
+        return false;
+    const operations = collectOmxStateCommandOperations(command, "write");
+    if (operations.length !== 1)
+        return false;
+    const operation = operations[0];
+    if (!operation || operation.nested || operation.commandPrefix.trim() || hasPriorExecutableCommand(operation.prefix))
+        return false;
+    const inlineInputCount = operation.args.filter((arg) => arg === "--input" || arg.startsWith("--input=")).length;
+    if (inlineInputCount !== 1 || operation.args.some((arg) => arg === "--input-file" || arg.startsWith("--input-file=")))
+        return false;
+    const inlineInput = readStateWriteFlagValue(operation.args, "--input");
+    let rawPayload = null;
+    try {
+        rawPayload = inlineInput ? safeObject(JSON.parse(inlineInput)) : null;
+    }
+    catch {
+        rawPayload = null;
+    }
+    const nestedState = safeObject(rawPayload?.state);
+    if (!rawPayload
+        || "workingDirectory" in rawPayload
+        || !suppliedSessionAliasesMatch(rawPayload, sessionId)
+        || !hasOnlyFinishedExplicitOutcomes(rawPayload)
+        || (nestedState && ("mode" in nestedState
+            || "session_id" in nestedState
+            || "workingDirectory" in nestedState
+            || "active" in nestedState
+            || "current_phase" in nestedState
+            || "currentPhase" in nestedState
+            || !suppliedSessionAliasesMatch(nestedState, sessionId)
+            || !hasOnlyFinishedExplicitOutcomes(nestedState))))
+        return false;
+    const payload = readStateWriteInputPayload(cwd, canonicalCommand, command);
+    return payload ? isCompleteDeepInterviewTerminalWritePayload(payload, activeState, sessionId) : false;
+}
 function isAllowedRalplanTerminalStateWriteCommand(cwd, command, activeState, sessionId) {
     const canonicalCommand = canonicalizeOmxStateTransportCommand(command);
     if (hasUnsafeUnquotedHeredocExpansion(canonicalCommand))
@@ -6295,13 +6546,56 @@ function commandEndsPlanningPhase(cwd, command) {
     const payload = readStateWriteInputPayload(cwd, canonicalCommand, command);
     return payload ? isPlanningPhaseDeactivationPayload(payload) : true;
 }
-function isAllowedDeepInterviewBashWrite(cwd, command) {
+function isAllowedDeepInterviewBashWrite(cwd, command, activeState, sessionId = "") {
+    const stateWriteOperations = collectOmxStateCommandOperations(command, "write");
+    const hasUnsafeRuntimeStateWrite = (words) => {
+        const stateWordIndex = words.indexOf("state");
+        const writeWordIndex = stateWordIndex >= 0 ? words.indexOf("write", stateWordIndex + 1) : -1;
+        if (writeWordIndex <= stateWordIndex)
+            return false;
+        const hasRuntimeBeforeState = words.slice(0, stateWordIndex).some((word) => {
+            const base = shellWordBaseName(word);
+            return isNodeInterpreterCommandWord(base) || base === "bun" || base === "tsx";
+        });
+        if (!hasRuntimeBeforeState)
+            return false;
+        const inlineInput = readStateWriteFlagValue(words, "--input");
+        let payload = null;
+        try {
+            const parsed = inlineInput ? safeObject(JSON.parse(inlineInput)) : null;
+            const modeOverride = readStateWriteFlagValue(words, "--mode");
+            payload = parsed
+                ? normalizeStateWriteClassificationPayload(modeOverride ? { ...parsed, mode: modeOverride } : parsed)
+                : null;
+        }
+        catch {
+            payload = null;
+        }
+        return (!payload && stateWriteOperations.length === 0)
+            || Boolean(payload && (safeString(payload.mode).trim().toLowerCase() !== "deep-interview"
+                || isPlanningPhaseDeactivationPayload(payload)));
+    };
+    const rawCommand = normalizeShellLineContinuations(command).trim();
+    if ([rawCommand, canonicalizeOmxStateTransportCommand(rawCommand)]
+        .some((candidate) => hasUnsafeRuntimeStateWrite(tokenizeShellWords(candidate))))
+        return false;
+    if (stateWriteOperations.some((operation) => operation.nested))
+        return false;
     if (isAllowedDeepInterviewRalplanHandoffCommand(cwd, command))
         return true;
     if (hasDeepInterviewRalplanHandoffStateMutation(cwd, command))
         return false;
-    if (commandEndsPlanningPhase(cwd, command))
-        return false;
+    if (commandEndsPlanningPhase(cwd, command)) {
+        return activeState
+            ? isAllowedDeepInterviewTerminalStateWriteCommand(cwd, command, activeState, sessionId)
+            : false;
+    }
+    if (stateWriteOperations.length > 0) {
+        const canonicalCommand = canonicalizeOmxStateTransportCommand(command);
+        const payload = readStateWriteInputPayload(cwd, canonicalCommand, command);
+        if (!payload || safeString(payload.mode).trim().toLowerCase() !== "deep-interview")
+            return false;
+    }
     if (commandHasUntargetedPlanningForbiddenIntent(command))
         return false;
     if (firstPlanningTmpScriptExecutionTarget(cwd, command))
@@ -6324,12 +6618,10 @@ async function readActiveDeepInterviewStateForPreToolUse(cwd, stateDir, sessionI
     const modeState = sessionId
         ? await readStopSessionPinnedState("deep-interview-state.json", cwd, sessionId, stateDir)
         : await readJsonIfExists(join(stateDir, "deep-interview-state.json"));
-    if (isActiveDeepInterviewPhase(modeState) && modeState && modeStateMatchesSkillStopContext(modeState, cwd, sessionId)) {
-        const hasActiveDeepInterviewSkill = listActiveSkills(canonicalState).some((entry) => (entry.skill === "deep-interview"
-            && matchesSkillStopContext(entry, canonicalState, sessionId, threadId)));
-        if (hasActiveDeepInterviewSkill)
-            return modeState;
-    }
+    const hasActiveDeepInterviewSkill = listActiveSkills(canonicalState).some((entry) => (entry.skill === "deep-interview"
+        && matchesSkillStopContext(entry, canonicalState, sessionId, threadId)));
+    if (hasActiveDeepInterviewSkill && modeState?.active === true)
+        return modeState;
     if (isInactiveCompletedDeepInterviewPhase(modeState))
         return null;
     const autopilotState = sessionId
@@ -6547,7 +6839,7 @@ async function buildDeepInterviewPreToolUseBoundaryOutput(payload, cwd, stateDir
     let blocked = false;
     let blockedDetail = "implementation/write tools are blocked until an explicit handoff workflow is activated";
     if (toolName === "Bash") {
-        blocked = !isAllowedDeepInterviewBashWrite(cwd, command);
+        blocked = !isAllowedDeepInterviewBashWrite(cwd, command, activeState, sessionId);
         if (blocked) {
             blockedDetail = buildDeepInterviewBashBlockedDetail(cwd, command);
         }
@@ -6661,6 +6953,11 @@ async function hasTrustedTypedSubagentProvenanceForPreToolUse(payload, cwd, stat
     if (!session)
         return false;
     const payloadThreadId = readPayloadThreadId(payload);
+    const trackedPayloadThread = payloadThreadId ? session.threads[payloadThreadId] : undefined;
+    const hasTrackedAdaptedTypedRole = payloadThreadId !== ""
+        && isTrustedSubagentThread(session, payloadThreadId)
+        && trackedPayloadThread?.provenance_kind === OMX_ADAPTED_PROVENANCE
+        && resolveInstalledRoleName(trackedPayloadThread.role ?? "") !== null;
     // Resolve the Main-root leader THREAD identity from the tracker's leader_thread_id
     // plus the canonical session's native_session_id (the leader's native thread). Only
     // genuine leader-thread identifiers may anchor the leader: owner_*_session_id are
@@ -6693,9 +6990,11 @@ async function hasTrustedTypedSubagentProvenanceForPreToolUse(payload, cwd, stat
         return false;
     // Planning boundary guards (ralplan, deep-interview) still require a recognized typed
     // agent role, so an untyped collaboration.spawn_agent child cannot write before an
-    // execution handoff/approval. Only the Main-root Conductor/Ralph executing guard opts
-    // into untyped tracker/runtime provenance (#3116, #3117).
-    if (options.allowUntypedProvenance !== true && !isTypedAgentRolePayload(payload)) {
+    // execution handoff/approval. A tracker-recorded OMX-adapted child is the equivalent
+    // of a typed role only when its own persisted role is installed and validated.
+    if (options.allowUntypedProvenance !== true
+        && !isTypedAgentRolePayload(payload)
+        && !hasTrackedAdaptedTypedRole) {
         return false;
     }
     // Tracker-backed provenance: the payload's own thread is a recorded, non-leader
@@ -7565,6 +7864,10 @@ export async function buildConductorPreToolUseWriteGuardOutput(payload, cwd, sta
     const nativeSubagentSupport = resolveNativeSubagentSupportStatus({
         payload,
         persistedSupportBlocker: await readJsonIfExists(nativeSubagentSupportBlockerPath(stateDir)),
+        persistedRoleRoutingMarker: readRoleRoutingMarker(stateDir, {
+            cwd,
+            sessionId: resolvedSessionId || readPayloadSessionId(payload),
+        }),
         persistedCapacityBlocker: await readJsonIfExists(nativeSubagentCapacityBlockerPath(stateDir)),
         cwd,
         sessionId: resolvedSessionId || readPayloadSessionId(payload),
@@ -7598,6 +7901,9 @@ export async function buildConductorPreToolUseWriteGuardOutput(payload, cwd, sta
     const unsupportedNativeGuidance = isUnsupportedNativeSubagentEvidence(nativeSubagentSupport)
         ? ` ${buildUnsupportedNativeSubagentGuidance(nativeSubagentSupport)} Treat the active conductor workflow as blocked/cancelled for native delegation recovery; do not call multi_agent_v1.close_agent.`
         : "";
+    const roleRoutingUnavailableGuidance = isRoleRoutingUnavailableEvidence(nativeSubagentSupport)
+        ? ` ${buildRoleRoutingUnavailableGuidance(nativeSubagentSupport)}`
+        : "";
     return {
         decision: "block",
         reason: `Main-root Conductor mode is active (${activeState.mode} phase: ${formatPhase(activeState.phase, "active")}); direct plan/code writes are blocked and must be delegated; ${blockedDetail}.`,
@@ -7607,6 +7913,7 @@ export async function buildConductorPreToolUseWriteGuardOutput(payload, cwd, sta
                 + "Use specialized agents for source edits and plan/spec authorship. "
                 + `Main-root Conductor may write only orchestration metadata/transport/ledger artifacts under ${CONDUCTOR_ORCHESTRATION_METADATA_PREFIXES.join(", ")}; path location alone is not authorization for substantive deliverables. `
                 + unsupportedNativeGuidance
+                + roleRoutingUnavailableGuidance
                 + " Autopilot rework and typed subagent/worker lanes are exempt from this guard.",
         },
     };
@@ -8424,7 +8731,8 @@ async function buildStopHookOutput(payload, cwd, stateDir, options = {}) {
         return null;
     }
     const sessionId = readPayloadSessionId(payload);
-    const canonicalSessionId = await resolveInternalSessionIdForPayload(cwd, sessionId);
+    const canonicalSessionId = options.canonicalSessionId
+        ?? await resolveInternalSessionIdForPayload(cwd, sessionId);
     const threadId = readPayloadThreadId(payload);
     const suppressParentWorkflowStop = shouldSuppressParentWorkflowStopForSideConversation(payload);
     if (canonicalSessionId) {
@@ -8468,7 +8776,7 @@ async function buildStopHookOutput(payload, cwd, stateDir, options = {}) {
     }
     const ralphState = options.skipRalphStopBlock === true
         ? null
-        : await readActiveRalphState(cwd, stateDir, canonicalSessionId, ralphOwnerContext);
+        : await readActiveRalphState(cwd, stateDir, sessionId || canonicalSessionId, ralphOwnerContext);
     if (!ralphState) {
         const autoresearchState = await readActiveAutoresearchState(cwd, canonicalSessionId);
         if (autoresearchState) {
@@ -8549,7 +8857,8 @@ async function buildStopHookOutput(payload, cwd, stateDir, options = {}) {
             return ordinaryNoProgressOutput;
         const autoNudgeConfig = await loadAutoNudgeConfig();
         const autoNudgePhase = await readStopAutoNudgePhase(cwd, stateDir, canonicalSessionId, threadId);
-        if (autoNudgeConfig.enabled
+        if (options.skipAutoNudge !== true
+            && autoNudgeConfig.enabled
             && detectNativeStopStallPattern(lastAssistantMessage, autoNudgeConfig.patterns, autoNudgePhase)) {
             const effectiveResponse = resolveEffectiveAutoNudgeResponse(autoNudgeConfig.response);
             return await returnPersistentStopBlock(payload, stateDir, "auto-nudge", lastAssistantMessage, {
@@ -8583,10 +8892,37 @@ async function buildStopHookOutput(payload, cwd, stateDir, options = {}) {
         systemMessage,
     }, canonicalSessionId);
 }
+async function preflightNativePromptTarget(stateDir, context) {
+    if (context.status !== "authorized")
+        return context;
+    const targetDir = join(stateDir, "sessions", context.authorization.targetSessionId);
+    const evidence = [];
+    let filenames;
+    try {
+        filenames = await readdir(targetDir);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return context;
+        return preflightSelectedTargetOwner(context, [{ ownerCodexSessionId: {} }], "native", new Date().toISOString());
+    }
+    for (const filename of filenames) {
+        if (!filename.endsWith("-state.json") && filename !== SKILL_ACTIVE_STATE_FILE)
+            continue;
+        try {
+            const value = JSON.parse(await readFile(join(targetDir, filename), "utf8"));
+            evidence.push(...extractSelectedTargetOwnerEvidence(value));
+        }
+        catch {
+            evidence.push({ ownerCodexSessionId: {} });
+        }
+    }
+    return preflightSelectedTargetOwner(context, evidence, "native", new Date().toISOString());
+}
 export async function dispatchCodexNativeHook(payload, options = {}) {
     const hookEventName = readHookEventName(payload);
     const cwd = options.cwd ?? (safeString(payload.cwd).trim() || process.cwd());
-    if (hookEventName === "Stop" && !hasNativeStopRuntimeSurface(cwd)) {
+    if (hookEventName === "PostCompact" && process.env.OMX_NATIVE_HOOK_DOCTOR_SMOKE === "1") {
         return {
             hookEventName,
             omxEventName: mapCodexHookEventToOmxEvent(hookEventName),
@@ -8594,22 +8930,70 @@ export async function dispatchCodexNativeHook(payload, options = {}) {
             outputJson: null,
         };
     }
-    // Native hooks must use the same authoritative runtime state root as HUD/MCP
-    // when boxed/team roots are active; do not bypass it with cwd/.omx/state.
-    const stateDir = getBaseStateDir(cwd);
-    if (hookEventName !== "Stop") {
-        await mkdir(stateDir, { recursive: true });
+    try {
+        recoverAdaptedRoleBindings(cwd, getBaseStateDir(cwd));
     }
+    catch {
+        // Recovery is best-effort for unrelated hook events.
+    }
+    if (hookEventName === "Stop" && !hasNativeStopRuntimeSurface(cwd)) {
+        return {
+            hookEventName,
+            omxEventName: mapCodexHookEventToOmxEvent(hookEventName),
+            skillState: null,
+            outputJson: null,
+        };
+    }
+    // Native hooks must use the exact pointer root selected for this dispatch.
+    const pointerContext = resolveSessionPointerContext(cwd);
+    const stateDir = pointerContext.baseStateDir;
     const omxEventName = mapCodexHookEventToOmxEvent(hookEventName);
     let skillState = null;
     let triageAdditionalContext = null;
     let goalWorkflowAdditionalContext = null;
     let ultragoalSteeringAdditionalContext = null;
+    let promptClassification = null;
     const nativeSessionId = safeString(payload.session_id ?? payload.sessionId).trim();
     const threadId = safeString(payload.thread_id ?? payload.threadId).trim();
     const turnId = safeString(payload.turn_id ?? payload.turnId).trim();
-    const currentSessionState = await readUsableSessionState(cwd);
+    const pointer = await readSessionPointer(pointerContext);
+    const currentSessionState = pointer.status === "usable" ? pointer.state ?? null : null;
+    let promptTurnContext = hookEventName === "UserPromptSubmit"
+        ? evaluateResolvedPromptTurn({
+            producer: "native",
+            payloadSessionId: payload.session_id ?? payload.sessionId,
+            ownerEnvSessionId: undefined,
+            selectedPointer: pointer,
+            threadFacts: await readNativePromptThreadFacts(cwd, nativeSessionId, threadId, currentSessionState),
+            nowIso: new Date().toISOString(),
+        })
+        : null;
+    if (promptTurnContext) {
+        promptTurnContext = await preflightNativePromptTarget(stateDir, promptTurnContext);
+    }
+    if (promptTurnContext?.status === "rejected") {
+        await appendPromptSessionProvenanceRejection(pointerContext, promptTurnContext.diagnostic).catch(() => { });
+        return { hookEventName, omxEventName, skillState: null, outputJson: null };
+    }
+    if (promptTurnContext?.status === "suppressed-target-child") {
+        return { hookEventName, omxEventName, skillState: null, outputJson: null };
+    }
+    if (hookEventName !== "Stop") {
+        await mkdir(stateDir, { recursive: true });
+    }
+    let allowImplicitSessionSideEffects = pointer.status === "usable" || pointer.status === "absent" || promptTurnContext?.status === "authorized";
+    let stopAuthorizationFailure = allowImplicitSessionSideEffects
+        ? null
+        : {
+            stopReason: "session_pointer_unusable",
+            reason: `OMX cannot authorize Stop while the selected session pointer is ${pointer.status}; repair the pointer evidence before continuing.`,
+        };
     let canonicalSessionId = safeString(currentSessionState?.session_id).trim();
+    if (promptTurnContext?.status === "authorized") {
+        canonicalSessionId = promptTurnContext.authorization.targetSessionId;
+    }
+    const allowPromptGlobalSideEffects = promptTurnContext?.status !== "authorized"
+        || promptTurnContext.authorization.globalSideEffects === "allow";
     let resolvedNativeSessionId = nativeSessionId;
     let skipCanonicalSessionStartContext = false;
     let isSubagentSessionStart = false;
@@ -8648,20 +9032,58 @@ export async function dispatchCodexNativeHook(payload, options = {}) {
             }
         }
         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;
+            const ownerOmxSessionId = await resolveVerifiedOwnerOmxSessionId();
+            try {
+                const sessionState = await reconcileNativeSessionStart(cwd, nativeSessionId, {
+                    context: pointerContext,
+                    pid: options.sessionOwnerPid ?? resolveSessionOwnerPid(payload),
+                    ...(ownerOmxSessionId
+                        ? { ownerOmxSessionId, ownerAliasVerified: true }
+                        : {}),
+                });
+                canonicalSessionId = safeString(sessionState.session_id).trim();
+                resolvedNativeSessionId = safeString(sessionState.native_session_id).trim() || nativeSessionId;
+                allowImplicitSessionSideEffects = true;
+                stopAuthorizationFailure = null;
+                // #3181: leader attestation is intentionally NOT performed here. This branch is
+                // reached whenever readNativeSubagentSessionStartMetadata() returns null, which
+                // conflates a genuine root start with an unreadable/malformed child transcript, so
+                // it cannot positively classify a leader (a legitimate leader may also carry no
+                // transcript). Leader attestation is performed only on the strictly-gated fresh
+                // leader PreToolUse path below, which fires before the first in-turn role-intent
+                // write. Fail closed here rather than risk a false-leader adoption.
+            }
+            catch (error) {
+                if (!isSessionPointerLaunchAbort(error))
+                    throw error;
+                canonicalSessionId = "";
+                resolvedNativeSessionId = nativeSessionId;
+                skipCanonicalSessionStartContext = true;
+                allowImplicitSessionSideEffects = false;
+                stopAuthorizationFailure = {
+                    stopReason: "session_pointer_unusable",
+                    reason: `OMX cannot authorize Stop while the selected session pointer is ${pointer.status}; repair the pointer evidence before continuing.`,
+                };
+            }
         }
     }
     else if (!canonicalSessionId) {
         canonicalSessionId = safeString(currentSessionState?.session_id).trim();
     }
     if (hookEventName === "Stop") {
-        const inheritedSessionId = safeString(process.env.OMX_SESSION_ID || process.env.CODEX_SESSION_ID).trim();
-        const stopCanonicalSessionId = await resolveInternalSessionIdForPayload(cwd, readPayloadSessionId(payload) || inheritedSessionId);
-        if (stopCanonicalSessionId) {
+        const stopPayloadSessionId = readPayloadSessionId(payload);
+        const stopCanonicalSessionId = await resolveInternalSessionIdForPayload(cwd, stopPayloadSessionId, undefined, currentSessionState, pointer.status === "absent");
+        if (stopPayloadSessionId && !stopCanonicalSessionId) {
+            canonicalSessionId = "";
+            allowImplicitSessionSideEffects = false;
+            if (!stopAuthorizationFailure) {
+                stopAuthorizationFailure = {
+                    stopReason: "session_scope_unmatched",
+                    reason: `OMX cannot authorize Stop for unmatched session id ${stopPayloadSessionId}; the selected session pointer remains authoritative.`,
+                };
+            }
+        }
+        else if (stopCanonicalSessionId) {
             canonicalSessionId = stopCanonicalSessionId;
         }
         if (canonicalSessionId && safeString(currentSessionState?.session_id).trim() === canonicalSessionId) {
@@ -8669,8 +9091,8 @@ export async function dispatchCodexNativeHook(payload, options = {}) {
                 safeString(currentSessionState?.native_session_id).trim() || resolvedNativeSessionId;
         }
     }
-    const eventSessionId = canonicalSessionId || nativeSessionId || undefined;
-    const sessionIdForState = canonicalSessionId || nativeSessionId;
+    let eventSessionId = canonicalSessionId || nativeSessionId || undefined;
+    let sessionIdForState = canonicalSessionId || null;
     let outputJson = null;
     const typedAgentRolePayload = isTypedAgentRolePayload(payload);
     const isSubagentPromptSubmit = hookEventName === "UserPromptSubmit"
@@ -8685,27 +9107,74 @@ export async function dispatchCodexNativeHook(payload, options = {}) {
             ? safeString(currentSessionState?.native_session_id).trim()
             : "")))).some(Boolean)
         : false;
+    if (isSubagentStop && stopAuthorizationFailure?.stopReason === "session_scope_unmatched") {
+        canonicalSessionId = normalizeSessionId(readPayloadSessionId(payload)) ?? "";
+        allowImplicitSessionSideEffects = true;
+        stopAuthorizationFailure = null;
+        eventSessionId = canonicalSessionId || nativeSessionId || undefined;
+        sessionIdForState = canonicalSessionId || null;
+    }
     const suppressNoisySubagentLifecycleDispatch = (isSubagentSessionStart || isSubagentStop)
         && shouldSuppressSubagentLifecycleHookDispatch();
     if (hookEventName === "UserPromptSubmit") {
         const prompt = readPromptText(payload);
-        goalWorkflowAdditionalContext = await buildCompletedGoalCleanupPromptWarning(cwd, prompt).catch(() => null)
-            ?? await buildGoalWorkflowReconciliationPromptWarning(cwd, prompt).catch(() => null);
-        ultragoalSteeringAdditionalContext = prompt && !isSubagentPromptSubmit
+        if (!isSubagentPromptSubmit) {
+            promptClassification = classifyKeywordInput(prompt);
+        }
+        goalWorkflowAdditionalContext = allowPromptGlobalSideEffects
+            ? await buildCompletedGoalCleanupPromptWarning(cwd, prompt).catch(() => null)
+                ?? await buildGoalWorkflowReconciliationPromptWarning(cwd, prompt).catch(() => null)
+            : null;
+        ultragoalSteeringAdditionalContext = prompt && !isSubagentPromptSubmit && allowImplicitSessionSideEffects && allowPromptGlobalSideEffects
             ? await applyUserPromptUltragoalSteering(cwd, prompt).catch((error) => `OMX native UserPromptSubmit rejected bounded .omx/ultragoal steering for G002-cli-and-prompt-submit-bridge: ${error instanceof Error ? error.message : String(error)}`)
             : null;
-        if (prompt && !isSubagentPromptSubmit) {
-            skillState = buildNativeOutsideTmuxTeamPromptBlockState(prompt, cwd, payload, sessionIdForState, threadId || undefined, turnId || undefined) ?? await recordSkillActivation({
+        let suppressActivationSeeding = !allowImplicitSessionSideEffects;
+        if (promptTurnContext?.status === "authorized") {
+            sessionIdForState = promptTurnContext.authorization.targetSessionId;
+        }
+        else if (prompt && !isSubagentPromptSubmit && allowImplicitSessionSideEffects) {
+            const rawHookSessionId = canonicalSessionId || nativeSessionId;
+            const normalizedHookSessionId = normalizeSessionId(rawHookSessionId);
+            const explicitHookSessionId = currentSessionState ? undefined : normalizedHookSessionId;
+            if (rawHookSessionId && !normalizedHookSessionId) {
+                suppressActivationSeeding = true;
+            }
+            else {
+                try {
+                    const writableScope = await resolveWritableStateScope(cwd, explicitHookSessionId);
+                    sessionIdForState = writableScope.sessionId ?? null;
+                }
+                catch (error) {
+                    if (!isImplicitWritableScopeFailure(error))
+                        throw error;
+                    suppressActivationSeeding = true;
+                }
+            }
+        }
+        if (prompt && promptClassification && !isSubagentPromptSubmit && !suppressActivationSeeding) {
+            skillState = buildNativeOutsideTmuxTeamPromptBlockState(promptClassification, cwd, payload, sessionIdForState || undefined, threadId || undefined, turnId || undefined) ?? await recordSkillActivation({
                 stateDir,
                 sourceCwd: cwd,
                 text: prompt,
-                sessionId: sessionIdForState,
+                classification: promptClassification,
+                allowSecondaryTeam: !isNativeOutsideTmuxUserPrompt(cwd, payload, sessionIdForState || undefined),
+                sessionId: sessionIdForState || undefined,
                 threadId,
                 turnId,
+                resolvedPromptTurnContext: promptTurnContext ?? undefined,
+                onProvenanceRejected: async (diagnostic) => {
+                    await appendPromptSessionProvenanceRejection(pointerContext, diagnostic).catch(() => { });
+                },
             });
         }
         // --- Triage classifier (advisory-only, non-keyword prompts) ---
-        if (prompt && skillState === null && !isSubagentPromptSubmit) {
+        if (prompt
+            && skillState === null
+            && !isSubagentPromptSubmit
+            && allowPromptGlobalSideEffects
+            && promptClassification?.reservedInput === null
+            && promptClassification.hasExplicitLikeInvocation === false
+            && promptClassification.matches.length === 0) {
             try {
                 if (readTriageConfig().enabled) {
                     const normalized = prompt.trim().toLowerCase();
@@ -8734,7 +9203,9 @@ export async function dispatchCodexNativeHook(payload, options = {}) {
                                 },
                                 suppress_followup: true,
                             };
-                            writeTriageState({ cwd, sessionId: sessionIdForState || null, state: newState });
+                            if (!suppressActivationSeeding) {
+                                writeTriageState({ cwd, sessionId: sessionIdForState || null, state: newState });
+                            }
                         }
                         else if (decision.lane === "LIGHT") {
                             if (decision.destination === "explore") {
@@ -8767,7 +9238,9 @@ export async function dispatchCodexNativeHook(payload, options = {}) {
                                     },
                                     suppress_followup: true,
                                 };
-                                writeTriageState({ cwd, sessionId: sessionIdForState || null, state: newState });
+                                if (!suppressActivationSeeding) {
+                                    writeTriageState({ cwd, sessionId: sessionIdForState || null, state: newState });
+                                }
                             }
                         }
                         // lane === "PASS": no context, no state write
@@ -8782,14 +9255,14 @@ export async function dispatchCodexNativeHook(payload, options = {}) {
         const skipHudReconcileForDoctorSmoke = process.env.OMX_NATIVE_HOOK_DOCTOR_SMOKE === "1";
         const skipHudReconcileForTeamWorkerPane = !isSubagentPromptSubmit
             && await isConfirmedTeamWorkerPromptSubmitPane(cwd).catch(() => false);
-        if (!skipHudReconcileForDoctorSmoke && !skipHudReconcileForTeamWorkerPane) {
+        if (allowImplicitSessionSideEffects && allowPromptGlobalSideEffects && !skipHudReconcileForDoctorSmoke && !skipHudReconcileForTeamWorkerPane) {
             const reconcileHudForPromptSubmitFn = options.reconcileHudForPromptSubmitFn ?? reconcileHudForPromptSubmit;
             const hudSessionId = resolveHudReconcileSessionId(currentSessionState, canonicalSessionId, sessionIdForState);
             const hudSessionIds = resolveHudReconcileSessionIds(currentSessionState, canonicalSessionId, sessionIdForState, nativeSessionId);
             await reconcileHudForPromptSubmitFn(cwd, { sessionId: hudSessionId, sessionIds: hudSessionIds }).catch(() => { });
         }
     }
-    if (omxEventName && !skipCanonicalSessionStartContext && !suppressNoisySubagentLifecycleDispatch) {
+    if (omxEventName && allowImplicitSessionSideEffects && allowPromptGlobalSideEffects && !skipCanonicalSessionStartContext && !suppressNoisySubagentLifecycleDispatch) {
         const baseContext = buildBaseContext(cwd, payload, hookEventName, canonicalSessionId);
         if (resolvedNativeSessionId) {
             baseContext.native_session_id = resolvedNativeSessionId;
@@ -8826,12 +9299,14 @@ export async function dispatchCodexNativeHook(payload, options = {}) {
             })
             : isSubagentPromptSubmit
                 ? null
-                : [
-                    buildAdditionalContextMessage(readPromptText(payload), skillState, cwd, payload),
-                    ultragoalSteeringAdditionalContext,
-                    goalWorkflowAdditionalContext,
-                    triageAdditionalContext,
-                ].filter((entry) => Boolean(entry)).join("\n\n") || null;
+                : promptClassification
+                    ? [
+                        buildAdditionalContextMessage(promptClassification, skillState, cwd, payload),
+                        ultragoalSteeringAdditionalContext,
+                        goalWorkflowAdditionalContext,
+                        triageAdditionalContext,
+                    ].filter((entry) => Boolean(entry)).join("\n\n") || null
+                    : null;
         if (additionalContext) {
             outputJson = {
                 hookSpecificOutput: {
@@ -8842,12 +9317,52 @@ export async function dispatchCodexNativeHook(payload, options = {}) {
         }
     }
     else if (hookEventName === "PreToolUse") {
+        // #3181 Phase-1 (PreToolUse): this hook fires before the shell tool call that runs
+        // the first in-turn `omx ralplan role-intent write`. On a fresh App/outside-tmux
+        // turn where SessionStart did not establish the pointer, reconcile the canonical
+        // pointer and attest the leader here so the first command can bootstrap. Strictly
+        // gated to a fresh (absent-pointer) LEADER turn: no canonical session yet, a present
+        // native session id, a leader-shaped thread (absent or equal to the native session
+        // id), and no subagent/typed-role provenance. Best-effort; never blocks PreToolUse.
+        if (allowImplicitSessionSideEffects
+            && !canonicalSessionId
+            && nativeSessionId
+            && readPayloadAgentRole(payload) === ""
+            && !hasSubagentThreadSpawnProvenance(payload)) {
+            const preToolUseLeaderThreadId = readPayloadThreadId(payload);
+            if (preToolUseLeaderThreadId
+                && preToolUseLeaderThreadId === nativeSessionId
+                && !(await isThreadTrackedAsSubagent(cwd, nativeSessionId))) {
+                try {
+                    const ownerOmxSessionId = await resolveVerifiedOwnerOmxSessionId();
+                    const sessionState = await reconcileNativeSessionStart(cwd, nativeSessionId, {
+                        context: pointerContext,
+                        pid: options.sessionOwnerPid ?? resolveSessionOwnerPid(payload),
+                        ...(ownerOmxSessionId ? { ownerOmxSessionId, ownerAliasVerified: true } : {}),
+                    });
+                    const bootstrapSessionId = safeString(sessionState.session_id).trim();
+                    const bootstrapLeaderThreadId = safeString(sessionState.native_session_id).trim() || nativeSessionId;
+                    if (bootstrapSessionId && bootstrapLeaderThreadId) {
+                        canonicalSessionId = bootstrapSessionId;
+                        attestLeaderThread(cwd, {
+                            sessionId: bootstrapSessionId,
+                            leaderThreadId: bootstrapLeaderThreadId,
+                            source: 'native-pretooluse',
+                        });
+                    }
+                }
+                catch {
+                    // Best-effort bootstrap; PreToolUse must never fail on this.
+                }
+            }
+        }
         const payloadSessionId = readPayloadSessionId(payload);
         const rootPointerConflict = await readLiveRootSessionPointerConflict(stateDir, payloadSessionId);
         const preToolUseSessionId = payloadSessionId
             ? await resolveInternalSessionIdForPayload(cwd, payloadSessionId, stateDir)
             : "";
-        outputJson = await buildDeepInterviewPreToolUseBoundaryOutput(payload, cwd, stateDir, preToolUseSessionId)
+        outputJson = buildNativeUnknownRolePreToolUseOutput(payload)
+            ?? await buildDeepInterviewPreToolUseBoundaryOutput(payload, cwd, stateDir, preToolUseSessionId)
             ?? await buildRalplanPreToolUseBoundaryOutput(payload, cwd, stateDir, preToolUseSessionId)
             ?? await buildPlanningRootPointerConflictPreToolUseOutput(payload, cwd, stateDir, rootPointerConflict)
             ?? await buildConductorPreToolUseWriteGuardOutput(payload, cwd, stateDir, preToolUseSessionId)
@@ -8856,18 +9371,36 @@ export async function dispatchCodexNativeHook(payload, options = {}) {
             ?? buildNativePreToolUseOutput(payload);
     }
     else if (hookEventName === "PostToolUse") {
-        await recordNativeSubagentCapacityBlocker(cwd, stateDir, payload).catch(() => { });
-        await recordNativeSubagentSupportBlocker(cwd, stateDir, payload).catch(() => { });
-        if (detectMcpTransportFailure(payload)) {
-            await markTeamTransportFailure(cwd, payload);
+        if (allowImplicitSessionSideEffects) {
+            await recordNativeSubagentCapacityBlocker(cwd, stateDir, payload).catch(() => { });
+            await recordNativeSubagentSupportBlocker(cwd, stateDir, payload).catch(() => { });
+            if (detectMcpTransportFailure(payload)) {
+                await markTeamTransportFailure(cwd, payload);
+            }
+            await handleTeamWorkerPostToolUseSuccess(payload, cwd);
         }
         outputJson = buildNativePostToolUseOutput(payload);
-        await handleTeamWorkerPostToolUseSuccess(payload, cwd);
     }
     else if (hookEventName === "Stop") {
-        outputJson = await buildStopHookOutput(payload, cwd, stateDir, {
-            skipRalphStopBlock: isSubagentStop,
-        }) ?? await buildCompletedGoalCleanupStopOutput(payload, cwd);
+        if (allowImplicitSessionSideEffects) {
+            outputJson = await buildStopHookOutput(payload, cwd, stateDir, {
+                canonicalSessionId: canonicalSessionId || undefined,
+                skipRalphStopBlock: isSubagentStop,
+                skipAutoNudge: isSubagentStop,
+            }) ?? await buildCompletedGoalCleanupStopOutput(payload, cwd);
+        }
+        else {
+            const failure = stopAuthorizationFailure ?? {
+                stopReason: "session_pointer_unusable",
+                reason: "OMX cannot authorize Stop without a writable session authority.",
+            };
+            outputJson = {
+                decision: "block",
+                stopReason: failure.stopReason,
+                reason: failure.reason,
+                systemMessage: failure.reason,
+            };
+        }
     }
     return {
         hookEventName,