oh-my-codex 0.18.13 → 0.18.15

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

@@ -12,7 +12,7 @@ import { appendToLog, isSessionStateUsable, readSessionState, readUsableSessionS
 import { appendTeamEvent, readTeamLeaderAttention, readTeamConfig, readTeamManifestV2, readTeamPhase, writeTeamLeaderAttention, writeTeamPhase, } from "../team/state.js";
 import { omxNotepadPath, resolveProjectMemoryPath } from "../utils/paths.js";
 import { findGitLayout } from "../utils/git-layout.js";
-import { getBaseStateDir, getStateFilePath, getStatePath } from "../mcp/state-paths.js";
+import { getBaseStateDir, getStateFilePath, getStatePath, getAuthoritativeActiveStatePaths } from "../mcp/state-paths.js";
 import { detectKeywords, detectPrimaryKeyword, recordSkillActivation, } from "../hooks/keyword-detector.js";
 import { buildDeepInterviewConfigInstruction } from "../hooks/deep-interview-config-instruction.js";
 import { readTeamModeConfig } from "../config/team-mode.js";
@@ -30,6 +30,7 @@ import { readAutoresearchCompletionStatus, readAutoresearchModeStateForActiveDec
 import { normalizeAutopilotPhase } from "../autopilot/fsm.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";
 import { getRunContinuationSnapshot, shouldContinueRun } from "../runtime/run-loop.js";
 import { parseUltragoalSteeringDirective, steerUltragoal, } from "../ultragoal/artifacts.js";
 import { triagePrompt } from "../hooks/triage-heuristic.js";
@@ -45,6 +46,8 @@ const SKILL_STOP_BLOCKERS = new Set(["ralplan"]);
 const TEAM_STOP_BLOCKING_TASK_STATUSES = new Set(["pending", "in_progress", "blocked"]);
 const TEAM_WORKER_TERMINAL_RUN_STATES = new Set(["done", "complete", "completed", "failed", "stopped", "cancelled"]);
 const NATIVE_STOP_STATE_FILE = "native-stop-state.json";
+const NATIVE_SUBAGENT_CAPACITY_BLOCKER_FILE = "native-subagent-capacity-blocker.json";
+const NATIVE_SUBAGENT_CAPACITY_BLOCKER_TTL_MS = 30 * 60_000;
 const ORDINARY_STOP_NO_PROGRESS_DEFAULT_MAX_REPEATS = 8;
 const RALPH_ORPHANED_STARTING_STALE_MS = 15 * 60_000;
 const ORDINARY_STOP_NO_PROGRESS_DEFAULT_IDLE_MS = 10 * 60_000;
@@ -381,6 +384,20 @@ function readHookEventName(payload) {
     }
     return null;
 }
+function sanitizeCodexHookOutput(hookEventName, output) {
+    if (!output || hookEventName !== "PreToolUse")
+        return output;
+    const systemMessage = safeString(output.systemMessage).trim();
+    if (systemMessage)
+        return { systemMessage };
+    const reason = safeString(output.reason).trim();
+    const hookSpecificOutput = output.hookSpecificOutput;
+    const additionalContext = hookSpecificOutput && typeof hookSpecificOutput === "object"
+        ? safeString(hookSpecificOutput.additionalContext).trim()
+        : "";
+    const derivedSystemMessage = [reason, additionalContext].filter(Boolean).join("\n\n");
+    return derivedSystemMessage ? { systemMessage: derivedSystemMessage } : {};
+}
 export function mapCodexHookEventToOmxEvent(hookEventName) {
     switch (hookEventName) {
         case "SessionStart":
@@ -1812,6 +1829,76 @@ function isStopExempt(payload) {
         || value.includes("compact")
         || value.includes("limit"));
 }
+async function readModeStateWithStopSource(mode, cwd, sessionId) {
+    const paths = await getAuthoritativeActiveStatePaths(mode, cwd, sessionId?.trim() || undefined).catch(() => []);
+    const path = paths[0];
+    if (!path)
+        return null;
+    const state = await readJsonIfExists(path);
+    return state ? { state, path } : null;
+}
+async function readRawSkillActiveState(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf-8"));
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function canonicalStopDisagreement(modeState, canonicalState, mode, sessionId) {
+    if (!canonicalState)
+        return "canonical_state_missing";
+    const normalizedSessionId = safeString(sessionId).trim();
+    const activeEntry = listRawActiveSkillEntries(canonicalState).find((entry) => {
+        if (entry.skill !== mode)
+            return false;
+        const entrySessionId = safeString(entry.session_id ?? canonicalState.session_id).trim();
+        return normalizedSessionId ? entrySessionId === normalizedSessionId || entrySessionId === "" : true;
+    });
+    if (!activeEntry)
+        return "canonical_inactive";
+    if (mode === "autopilot") {
+        const phase = safeString(modeState.current_phase ?? modeState.currentPhase).trim();
+        const canonicalPhase = safeString(activeEntry.phase ?? canonicalState.phase).trim();
+        if (phase && canonicalPhase && normalizeAutopilotPhase(phase) !== normalizeAutopilotPhase(canonicalPhase)) {
+            return `canonical_phase:${canonicalPhase}`;
+        }
+    }
+    return "canonical_agrees";
+}
+function listRawActiveSkillEntries(state) {
+    if (!state)
+        return [];
+    const entries = [];
+    if (Array.isArray(state.active_skills)) {
+        for (const candidate of state.active_skills) {
+            if (!candidate || typeof candidate !== "object")
+                continue;
+            const raw = candidate;
+            const skill = safeString(raw.skill).trim();
+            if (!skill || raw.active === false)
+                continue;
+            entries.push({
+                ...raw,
+                skill,
+                phase: safeString(raw.phase).trim() || undefined,
+                session_id: safeString(raw.session_id).trim() || undefined,
+                thread_id: safeString(raw.thread_id).trim() || undefined,
+            });
+        }
+    }
+    const topLevelSkill = safeString(state.skill).trim();
+    if (state.active === true && topLevelSkill) {
+        entries.push({
+            skill: topLevelSkill,
+            phase: safeString(state.phase).trim() || undefined,
+            session_id: safeString(state.session_id).trim() || undefined,
+            thread_id: safeString(state.thread_id).trim() || undefined,
+        });
+    }
+    return entries;
+}
 async function buildModeBasedStopOutput(mode, cwd, sessionId) {
     if (await readCanonicalTerminalRunStateForStop(cwd, sessionId, mode)) {
         return null;
@@ -1819,18 +1906,40 @@ async function buildModeBasedStopOutput(mode, cwd, sessionId) {
     if (mode === "autopilot" && await readAutopilotDeepInterviewQuestionWaitState(cwd, sessionId)) {
         return null;
     }
-    const state = await readModeStateForActiveDecision(mode, sessionId?.trim() || undefined, cwd);
+    const sourcedState = await readModeStateWithStopSource(mode, cwd, sessionId);
+    const state = sourcedState?.state ?? null;
     if (!state || !shouldContinueRun(state))
         return null;
+    const rootCanonicalState = await readRawSkillActiveState(getSkillActiveStatePathsForStateDir(getBaseStateDir(cwd)).rootPath);
+    const canonicalDisagreement = rootCanonicalState
+        ? canonicalStopDisagreement(state, rootCanonicalState, mode, sessionId)
+        : "canonical_state_missing";
+    if (canonicalDisagreement === "canonical_inactive")
+        return null;
     const phase = formatPhase(state.current_phase);
+    if (!rootCanonicalState || mode !== "autopilot") {
+        const systemMessage = mode === "autopilot" && phase.toLowerCase().replace(/_/g, "-") === "code-review"
+            ? "OMX autopilot is still active (phase: code-review). Run the required $code-review step before completing or clearing Autopilot state."
+            : `OMX ${mode} is still active (phase: ${phase}).`;
+        return {
+            decision: "block",
+            reason: `OMX ${mode} is still active (phase: ${phase}); continue the task and gather fresh verification evidence before stopping.`,
+            stopReason: `${mode}_${phase}`,
+            systemMessage,
+        };
+    }
+    const statePath = sourcedState ? formatStopStatePath(cwd, sourcedState.path) : "unknown";
+    const diagnostic = `state: ${statePath}; canonical: ${canonicalDisagreement}`;
     const systemMessage = mode === "autopilot" && phase.toLowerCase().replace(/_/g, "-") === "code-review"
-        ? "OMX autopilot is still active (phase: code-review). Run the required $code-review step before completing or clearing Autopilot state."
-        : `OMX ${mode} is still active (phase: ${phase}).`;
+        ? `OMX autopilot is still active (phase: code-review; ${diagnostic}). Run the required $code-review step before completing or clearing Autopilot state.`
+        : `OMX ${mode} is still active (phase: ${phase}; ${diagnostic}).`;
     return {
         decision: "block",
-        reason: `OMX ${mode} is still active (phase: ${phase}); continue the task and gather fresh verification evidence before stopping.`,
+        reason: `OMX ${mode} is still active (phase: ${phase}; ${diagnostic}); continue the task and gather fresh verification evidence before stopping.`,
         stopReason: `${mode}_${phase}`,
         systemMessage,
+        statePath,
+        canonicalDisagreement,
     };
 }
 export function looksLikeGoalCompletionPrompt(text) {
@@ -1873,6 +1982,112 @@ function reportsBlockedUltragoalCompletedAggregateMicrogoalLoop(goal) {
         && /microgoal/i.test(evidence)
         && /\b(?:unreconcilable|mismatch|loop|already complete|already completed|blocks?)\b/i.test(evidence);
 }
+function sentenceWindowAround(text, start, end) {
+    const rawBefore = text.slice(Math.max(0, start - 80), start);
+    const rawAfter = text.slice(end, Math.min(text.length, end + 80));
+    const before = rawBefore.slice(Math.max(rawBefore.lastIndexOf("\n"), rawBefore.lastIndexOf("."), rawBefore.lastIndexOf("!"), rawBefore.lastIndexOf("?")) + 1);
+    const sentenceEndOffsets = [rawAfter.indexOf("\n"), rawAfter.indexOf("."), rawAfter.indexOf("!"), rawAfter.indexOf("?")].filter((index) => index >= 0);
+    const after = sentenceEndOffsets.length > 0 ? rawAfter.slice(0, Math.min(...sentenceEndOffsets)) : rawAfter;
+    return `${before}${text.slice(start, end)}${after}`;
+}
+function isNegatedGoalAttemptWindow(window) {
+    return /\b(?:do\s+not|don't|never|must\s+not|should\s+not|cannot|can't|not|no)\b.{0,50}\b(?:start|create|begin|new|another|goal|ultragoal|performance[-\s]goal|autoresearch[-\s]goal)\b/i.test(window)
+        || /\b(?:without|instead\s+of)\b.{0,30}\b(?:start|create|begin|new|another)?\b.{0,30}\b(?:goal|ultragoal|performance[-\s]goal|autoresearch[-\s]goal)\b/i.test(window)
+        || /\b(?:goal|ultragoal|performance[-\s]goal|autoresearch[-\s]goal)\b.{0,30}\b(?:is|was|already)\b.{0,30}\b(?:documented|complete|completed|done|unavailable|not\s+needed)\b/i.test(window);
+}
+function looksLikeGoalCreationAttempt(text) {
+    const candidatePattern = /\b(?:start|create|begin|new|another|goal|ultragoal|performance[-\s]goal|autoresearch[-\s]goal)\b/gi;
+    for (const match of text.matchAll(candidatePattern)) {
+        const start = match.index ?? 0;
+        const end = start + match[0].length;
+        const window = sentenceWindowAround(text, start, end);
+        if (isNegatedGoalAttemptWindow(window))
+            continue;
+        if (/(?:\b(?:start|create|begin|new|another)\b.{0,80}\b(?:goal|ultragoal|performance[-\s]goal|autoresearch[-\s]goal)\b|\b(?:goal|ultragoal|performance[-\s]goal|autoresearch[-\s]goal)\b.{0,80}\b(?:start|create|begin|new|another)\b)/i.test(window))
+            return true;
+    }
+    return false;
+}
+function looksLikeCreateGoalAttempt(text) {
+    const candidatePattern = /\bcreate_goal\s*(?:\(|\b)/gi;
+    for (const match of text.matchAll(candidatePattern)) {
+        const start = match.index ?? 0;
+        const end = start + match[0].length;
+        const window = sentenceWindowAround(text, start, end);
+        if (/(?:\bno\s+create_goal\s+attempt\b|\b(?:do\s+not|don't|never|must\s+not|should\s+not|cannot|can't|not)\b.{0,40}\bcreate_goal\b|\bwithout\s+create_goal\b|\bfailed\s+to\s+call\s+create_goal\b|\bcreate_goal\s+(?:is|was)\s+(?:unavailable|not\s+available|not\s+called)\b)/i.test(window)) {
+            continue;
+        }
+        if (/\b(?:call|calling|called|invoke|invoking|start|starting|create|creating|begin|beginning|attempt|attempting|try|trying|continue\s+to|proceed\s+to)\b.{0,80}\bcreate_goal\b/i.test(window)
+            || /\bcreate_goal\b.{0,80}\b(?:payload|call|tool|now|next|follows|follow|start|starting|create|creating|begin|beginning|attempt|attempting)\b/i.test(window)
+            || /\bcreate_goal\s*\(/i.test(match[0])) {
+            return true;
+        }
+    }
+    return false;
+}
+function looksLikeCompletedGoalCleanupAttempt(text) {
+    return looksLikeGoalCreationAttempt(text) || looksLikeCreateGoalAttempt(text);
+}
+function hasFreshNativeGoalCleanupEvidence(text) {
+    return /\b(?:get_goal|Codex goal|native goal|active goal|thread goal)\b.{0,120}\b(?:reports?|returns?|shows?|status|state|still|attached|pending|cleanup|required|requires?)\b.{0,120}\b(?:complete|completed|attached|pending|cleanup|required|clear)\b/i.test(text)
+        || /\b(?:complete|completed|attached|pending|cleanup|required|clear)\b.{0,120}\b(?:get_goal|Codex goal|native goal|active goal|thread goal)\b/i.test(text)
+        || /\b(?:pending[-_ ]cleanup|native[-_ ]goal[-_ ]cleanup|completed[-_ ]codex[-_ ]goal[-_ ]cleanup)\b/i.test(text);
+}
+async function findCompletedGoalWorkflowCleanupNotice(cwd) {
+    const ultragoal = await readJsonIfExists(join(cwd, ".omx", "ultragoal", "goals.json"));
+    const aggregateCompletion = safeObject(ultragoal?.aggregateCompletion);
+    const ultragoals = Array.isArray(ultragoal?.goals) ? ultragoal.goals.map(safeObject) : [];
+    if (safeString(aggregateCompletion.status) === "complete" || (ultragoals.length > 0 && ultragoals.every((goal) => safeString(goal.status) === "complete"))) {
+        return buildCodexGoalTerminalCleanupNotice("Ultragoal completion");
+    }
+    const performanceRoot = join(cwd, ".omx", "goals", "performance");
+    for (const entry of await readdir(performanceRoot, { withFileTypes: true }).catch(() => [])) {
+        if (!entry.isDirectory())
+            continue;
+        const state = await readJsonIfExists(join(performanceRoot, entry.name, "state.json"));
+        if (state?.workflow === "performance-goal" && safeString(state.status) === "complete") {
+            return buildCodexGoalTerminalCleanupNotice("Performance-goal completion");
+        }
+    }
+    const autoresearchRoot = join(cwd, ".omx", "goals", "autoresearch");
+    for (const entry of await readdir(autoresearchRoot, { withFileTypes: true }).catch(() => [])) {
+        if (!entry.isDirectory())
+            continue;
+        const mission = await readJsonIfExists(join(autoresearchRoot, entry.name, "mission.json"));
+        if (mission?.workflow === "autoresearch-goal" && safeString(mission.status) === "complete") {
+            return buildCodexGoalTerminalCleanupNotice("Autoresearch-goal completion");
+        }
+    }
+    return null;
+}
+async function buildCompletedGoalCleanupPromptWarning(cwd, prompt) {
+    if (!looksLikeCompletedGoalCleanupAttempt(prompt))
+        return null;
+    const notice = await findCompletedGoalWorkflowCleanupNotice(cwd);
+    if (!notice)
+        return null;
+    return `${notice} Do not continue into create_goal until cleanup is explicit; hooks only nudge and must not mutate Codex goal state.`;
+}
+async function buildCompletedGoalCleanupStopOutput(payload, cwd) {
+    const text = [
+        safeString(payload.last_user_message ?? payload.lastUserMessage),
+        safeString(payload.last_assistant_message ?? payload.lastAssistantMessage),
+    ].join("\n");
+    if (!looksLikeCompletedGoalCleanupAttempt(text))
+        return null;
+    if (!hasFreshNativeGoalCleanupEvidence(text))
+        return null;
+    const notice = await findCompletedGoalWorkflowCleanupNotice(cwd);
+    if (!notice)
+        return null;
+    const systemMessage = `${notice} Do not continue into create_goal until cleanup is explicit; hooks only nudge and must not mutate Codex goal state.`;
+    return {
+        decision: "block",
+        reason: systemMessage,
+        stopReason: "completed_codex_goal_cleanup_required",
+        systemMessage,
+    };
+}
 async function findActiveGoalWorkflowReconciliationRequirement(cwd) {
     const ultragoal = await readJsonIfExists(join(cwd, ".omx", "ultragoal", "goals.json"));
     const aggregateCompletion = safeObject(ultragoal?.aggregateCompletion);
@@ -2088,6 +2303,125 @@ function readPayloadThreadId(payload) {
 function readPayloadTurnId(payload) {
     return safeString(payload.turn_id ?? payload.turnId).trim();
 }
+function nativeSubagentCapacityBlockerPath(stateDir) {
+    return join(stateDir, NATIVE_SUBAGENT_CAPACITY_BLOCKER_FILE);
+}
+function stringifyUnknown(value) {
+    if (typeof value === "string")
+        return value;
+    if (value === undefined || value === null)
+        return "";
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function payloadEvidenceText(payload) {
+    return [
+        safeString(payload.tool_name),
+        stringifyUnknown(payload.tool_response),
+        stringifyUnknown(payload.response),
+        stringifyUnknown(payload.error),
+        stringifyUnknown(payload.message),
+    ].filter(Boolean).join("\n");
+}
+function isNativeSubagentCapacityFailure(payload) {
+    const evidence = payloadEvidenceText(payload);
+    if (!/\bagent thread limit reached\b/i.test(evidence))
+        return false;
+    const toolName = safeString(payload.tool_name).trim();
+    return !toolName || /(?:spawn_agent|multi_agent|subagent|collab|agent)/i.test(toolName);
+}
+function summarizeCapacityFailure(text) {
+    const normalized = text.replace(/\s+/g, " ").trim();
+    if (!normalized)
+        return "agent thread limit reached";
+    const match = normalized.match(/[^.?!\n\r]*agent thread limit reached[^.?!\n\r]*/i);
+    return (match?.[0] ?? normalized).slice(0, 500);
+}
+async function recordNativeSubagentCapacityBlocker(cwd, stateDir, payload) {
+    if (!isNativeSubagentCapacityFailure(payload))
+        return;
+    const nowMs = Date.now();
+    const blocker = {
+        schema_version: 1,
+        reason: "agent_thread_limit_reached",
+        ...(readPayloadSessionId(payload) ? { session_id: readPayloadSessionId(payload) } : {}),
+        ...(readPayloadThreadId(payload) ? { thread_id: readPayloadThreadId(payload) } : {}),
+        ...(readPayloadTurnId(payload) ? { turn_id: readPayloadTurnId(payload) } : {}),
+        ...(safeString(payload.tool_name).trim() ? { tool_name: safeString(payload.tool_name).trim() } : {}),
+        error_summary: summarizeCapacityFailure(payloadEvidenceText(payload)),
+        observed_at: new Date(nowMs).toISOString(),
+        expires_at: new Date(nowMs + NATIVE_SUBAGENT_CAPACITY_BLOCKER_TTL_MS).toISOString(),
+    };
+    await mkdir(stateDir, { recursive: true });
+    await writeFile(nativeSubagentCapacityBlockerPath(stateDir), JSON.stringify({
+        ...blocker,
+        cwd,
+    }, null, 2));
+}
+function isFreshNativeSubagentCapacityBlocker(blocker, cwd, payload, nowMs = Date.now()) {
+    if (!blocker)
+        return false;
+    if (safeString(blocker.reason) !== "agent_thread_limit_reached")
+        return false;
+    const expiresAtMs = Date.parse(safeString(blocker.expires_at));
+    if (!Number.isFinite(expiresAtMs) || expiresAtMs <= nowMs)
+        return false;
+    const blockerCwd = safeString(blocker.cwd).trim();
+    if (blockerCwd) {
+        try {
+            if (resolve(blockerCwd) !== resolve(cwd))
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    const blockerSessionId = safeString(blocker.session_id).trim();
+    const payloadSessionId = readPayloadSessionId(payload);
+    return !blockerSessionId || !payloadSessionId || blockerSessionId === payloadSessionId;
+}
+function inputContainsCloseAgentRequest(value) {
+    if (typeof value === "string")
+        return /\bclose_agent\b/i.test(value);
+    if (!value || typeof value !== "object")
+        return false;
+    try {
+        return /\bclose_agent\b/i.test(JSON.stringify(value));
+    }
+    catch {
+        return false;
+    }
+}
+function isCloseAgentToolUse(payload) {
+    const toolName = safeString(payload.tool_name).trim();
+    if (/\bclose_agent\b/i.test(toolName))
+        return true;
+    if (/multi_tool_use\.parallel/i.test(toolName) && inputContainsCloseAgentRequest(payload.tool_input))
+        return true;
+    return inputContainsCloseAgentRequest(payload.tool_input) && /multi_agent|agent|tool_use/i.test(toolName);
+}
+async function buildNativeSubagentCapacityCloseGuardOutput(payload, cwd, stateDir) {
+    if (!isCloseAgentToolUse(payload))
+        return null;
+    const blocker = await readJsonIfExists(nativeSubagentCapacityBlockerPath(stateDir));
+    if (!isFreshNativeSubagentCapacityBlocker(blocker, cwd, payload))
+        return null;
+    const evidence = safeString(blocker.error_summary).trim() || "agent thread limit reached";
+    return {
+        decision: "block",
+        reason: "Native subagent capacity was exhausted recently; model-level close_agent cleanup is blocked because close_agent can hang indefinitely on stale handles.",
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            additionalContext: `OMX blocked ${safeString(payload.tool_name).trim() || "close_agent"} before it could start: a recent native subagent capacity failure was recorded (${evidence}). `
+                + "Do not call multi_agent_v1.close_agent, and do not batch close_agent through multi_tool_use.parallel, as stale native handles can hang the whole turn. "
+                + "Treat this as a bounded capacity blocker: persist/report the blocker evidence, avoid further native subagent cleanup from the model turn, and recover via runtime-level cleanup or a fresh Codex session.",
+        },
+    };
+}
 async function resolveInternalSessionIdForPayload(cwd, payloadSessionId, stateDir) {
     const currentSession = stateDir
         ? await readUsableSessionStateFromStateDir(cwd, stateDir)
@@ -2096,12 +2430,15 @@ async function resolveInternalSessionIdForPayload(cwd, payloadSessionId, stateDi
     if (!canonicalSessionId)
         return payloadSessionId;
     const nativeSessionId = safeString(currentSession?.native_session_id).trim();
+    const ownerOmxSessionId = safeString(currentSession?.owner_omx_session_id).trim();
     if (!payloadSessionId)
         return canonicalSessionId;
     if (payloadSessionId === canonicalSessionId)
         return canonicalSessionId;
     if (nativeSessionId && payloadSessionId === nativeSessionId)
         return canonicalSessionId;
+    if (ownerOmxSessionId && payloadSessionId === ownerOmxSessionId)
+        return canonicalSessionId;
     return payloadSessionId;
 }
 async function readUsableSessionStateFromStateDir(cwd, stateDir) {
@@ -2134,6 +2471,7 @@ const RALPLAN_ALLOWED_WRITE_PREFIXES = [
     ".omx/plans",
     ".omx/specs",
     ".omx/state",
+    ".beads",
 ];
 const PLANNING_MODE_IMPLEMENTATION_TOOL_NAMES = new Set([
     "Write",
@@ -2182,6 +2520,9 @@ function isAutopilotRalplanLikePhase(phase) {
 function canAutopilotSkillMirrorSupplyRalplanPhase(phase) {
     return phase === "" || normalizeAutopilotPhase(phase) === "ralplan";
 }
+function isAutopilotReviewReworkPhase(phase) {
+    return normalizeAutopilotPhase(phase) === "rework";
+}
 function hasExplicitExecutionHandoffSkill(state, sessionId, threadId) {
     return listActiveSkills(state ?? {}).some((entry) => (RALPLAN_EXECUTION_HANDOFF_SKILLS.has(entry.skill)
         && matchesSkillStopContext(entry, state ?? {}, sessionId, threadId)));
@@ -2208,6 +2549,134 @@ function isAllowedDeepInterviewArtifactPath(cwd, rawPath) {
 function isAllowedRalplanArtifactPath(cwd, rawPath) {
     return isAllowedPlanningArtifactPath(cwd, rawPath, RALPLAN_ALLOWED_WRITE_PREFIXES);
 }
+function shellTokenizeLiteralCommand(command) {
+    const tokens = [];
+    let current = "";
+    let quote = null;
+    let escaping = false;
+    for (const char of command.trim()) {
+        if (escaping) {
+            current += char;
+            escaping = false;
+            continue;
+        }
+        if (quote === '"' && char === "\\") {
+            escaping = true;
+            continue;
+        }
+        if (quote) {
+            if (char === quote)
+                quote = null;
+            else
+                current += char;
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quote = char;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            if (current) {
+                tokens.push(current);
+                current = "";
+            }
+            continue;
+        }
+        if (/[;&|<>`$(){}\n\r]/.test(char))
+            return null;
+        current += char;
+    }
+    if (escaping || quote)
+        return null;
+    if (current)
+        tokens.push(current);
+    return tokens;
+}
+function findLiteralBdExecutableIndex(tokens) {
+    if (tokens[0] === "bd")
+        return 0;
+    if (tokens[0] === "command" || tokens[0] === "builtin" || tokens[0] === "exec" || tokens[0] === "nohup") {
+        return tokens[1] === "bd" ? 1 : -1;
+    }
+    if (tokens[0] !== "env")
+        return -1;
+    for (let index = 1; index < tokens.length; index += 1) {
+        const token = tokens[index] ?? "";
+        if (token === "bd")
+            return index;
+        if (/^[A-Za-z_][A-Za-z0-9_]*=.*/.test(token))
+            continue;
+        if (token.startsWith("-"))
+            continue;
+        return -1;
+    }
+    return -1;
+}
+function isAllowedRalplanBeadsDbPath(cwd, rawPath) {
+    const trimmed = rawPath.trim().replace(/^['"]|['"]$/g, "");
+    if (!trimmed || trimmed.includes("\0"))
+        return false;
+    let relativePath;
+    try {
+        const absolute = resolve(cwd, trimmed);
+        relativePath = relative(cwd, absolute).replace(/\\/g, "/");
+    }
+    catch {
+        return false;
+    }
+    return relativePath.startsWith(".beads/") && relativePath.length > ".beads/".length;
+}
+function classifyRalplanBeadsMetadataCommand(cwd, command) {
+    const trimmedCommand = command.trim();
+    const startsWithBd = /^(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"$`]*"|'[^']*'|[^\s"'$`;&|<>]+)\s+)*bd(?:\s|$)/.test(trimmedCommand);
+    const hasCompoundBd = /[;&|()]\s*bd(?:\s|$)/.test(command);
+    const tokens = shellTokenizeLiteralCommand(command);
+    const bdExecutableIndex = tokens ? findLiteralBdExecutableIndex(tokens) : -1;
+    if (!startsWithBd && !hasCompoundBd && bdExecutableIndex === -1)
+        return { present: false, allowed: false };
+    if (!tokens || bdExecutableIndex !== 0) {
+        return { present: true, allowed: false, reason: "Beads tracker command must be a single literal bd invocation" };
+    }
+    let dbPath = "";
+    let dbValueIndex = -1;
+    for (let index = 1; index < tokens.length; index += 1) {
+        const token = tokens[index] ?? "";
+        if (token === "--db") {
+            dbPath = tokens[index + 1] ?? "";
+            dbValueIndex = index + 1;
+            break;
+        }
+        if (token.startsWith("--db=")) {
+            dbPath = token.slice("--db=".length);
+            dbValueIndex = index;
+            break;
+        }
+    }
+    if (!dbPath) {
+        return { present: true, allowed: false, reason: "Beads tracker command is missing a literal --db .beads/<db> target" };
+    }
+    if (!isAllowedRalplanBeadsDbPath(cwd, dbPath)) {
+        return { present: true, allowed: false, reason: `Beads tracker db target ${dbPath} is outside repo-local .beads metadata` };
+    }
+    const operationTokens = tokens
+        .slice(dbValueIndex + 1)
+        .filter((token) => token && !token.startsWith("-"));
+    const operation = operationTokens[0] ?? "";
+    const suboperation = operationTokens[1] ?? "";
+    if (["create", "update", "edit", "close", "reopen", "status", "dep"].includes(operation)) {
+        return { present: true, allowed: true };
+    }
+    if (operation === "comments" && suboperation === "add") {
+        return { present: true, allowed: true };
+    }
+    return {
+        present: true,
+        allowed: false,
+        reason: operation
+            ? `Beads tracker operation ${operation}${suboperation ? ` ${suboperation}` : ""} is not allowed during planning`
+            : "Beads tracker command is missing an allowed metadata operation",
+    };
+}
 function readPreToolUseCommand(payload) {
     const toolInput = safeObject(payload.tool_input);
     return safeString(toolInput.command).trim();
@@ -2314,6 +2783,22 @@ function extractDeepInterviewCommandWriteTargets(command) {
     }
     return targets;
 }
+function formatPlanningWriteBlockDetail(operationClass, target, allowedPrefixes) {
+    const targetDetail = target ? `target ${target}` : "target <unresolved>";
+    return `${operationClass} ${targetDetail} is not under allowed planning artifact paths (${allowedPrefixes.join(", ")})`;
+}
+function isUnresolvedVariableTarget(target) {
+    const normalized = target.trim().replace(/^['"]|['"]$/g, "");
+    return /^\$\{?[A-Za-z_][A-Za-z0-9_]*\}?$/.test(normalized);
+}
+function describeImplementationToolBlock(toolName, blockedPath, pathCount) {
+    if (pathCount === 0) {
+        const operationClass = isApplyPatchToolName(toolName) ? "apply_patch target extraction failed" : `${toolName} path`;
+        return `${operationClass} target <unresolved>; only planning artifact paths are allowed (${RALPLAN_ALLOWED_WRITE_PREFIXES.join(", ")})`;
+    }
+    const operationClass = isApplyPatchToolName(toolName) ? "apply_patch target" : `${toolName} path`;
+    return formatPlanningWriteBlockDetail(operationClass, blockedPath, RALPLAN_ALLOWED_WRITE_PREFIXES);
+}
 function isAllowedDeepInterviewBashWrite(cwd, command) {
     if (!commandHasDeepInterviewWriteIntent(command))
         return true;
@@ -2400,6 +2885,8 @@ async function readActiveRalplanStateForPreToolUse(cwd, stateDir, sessionId, thr
     if (!hasActiveAutopilotSkill)
         return null;
     const autopilotStatePhase = safeString(autopilotState.current_phase ?? autopilotState.currentPhase).trim().toLowerCase();
+    if (isAutopilotReviewReworkPhase(autopilotStatePhase))
+        return null;
     if (!canAutopilotSkillMirrorSupplyRalplanPhase(autopilotStatePhase))
         return null;
     const hasRalplanScopedAutopilotSkill = listActiveSkills(canonicalState).some((entry) => (entry.skill === "autopilot"
@@ -2410,12 +2897,37 @@ async function readActiveRalplanStateForPreToolUse(cwd, stateDir, sessionId, thr
     return hasActiveAutopilotSkill ? autopilotState : null;
 }
 function isAllowedRalplanBashWrite(cwd, command) {
+    const beadsCommand = classifyRalplanBeadsMetadataCommand(cwd, command);
+    const targets = extractDeepInterviewCommandWriteTargets(command);
+    const hasAllowedTargets = targets.length > 0
+        && targets.every((target) => isAllowedRalplanArtifactPath(cwd, target));
+    if (beadsCommand.present) {
+        return beadsCommand.allowed && (targets.length === 0 || hasAllowedTargets);
+    }
     if (!commandHasDeepInterviewWriteIntent(command))
         return true;
     if (/\bomx\s+(?:state\s+(?:write|read|clear)|question)\b/.test(command))
         return true;
+    return hasAllowedTargets;
+}
+function buildRalplanBashBlockedDetail(cwd, command) {
     const targets = extractDeepInterviewCommandWriteTargets(command);
-    return targets.length > 0 && targets.every((target) => isAllowedRalplanArtifactPath(cwd, target));
+    const blockedTarget = targets.find((target) => !isAllowedRalplanArtifactPath(cwd, target));
+    if (blockedTarget && isUnresolvedVariableTarget(blockedTarget)) {
+        return `unresolved Bash write target ${blockedTarget} is not under allowed planning artifact paths or metadata paths (${RALPLAN_ALLOWED_WRITE_PREFIXES.join(", ")})`;
+    }
+    if (blockedTarget) {
+        const operationClass = /\btee\s+(?:-a\s+)?/.test(command) ? "Bash tee write" : "Bash redirect write";
+        return `${operationClass} target ${blockedTarget} is not under allowed planning artifact paths or metadata paths (${RALPLAN_ALLOWED_WRITE_PREFIXES.join(", ")})`;
+    }
+    const beadsCommand = classifyRalplanBeadsMetadataCommand(cwd, command);
+    if (beadsCommand.present && !beadsCommand.allowed) {
+        return beadsCommand.reason ?? "Beads tracker command is not an allowed planning metadata mutation";
+    }
+    if (beadsCommand.present) {
+        return "Beads tracker command also performs an implementation write outside allowed planning metadata";
+    }
+    return "Bash write intent did not identify an allowed planning artifact path or metadata path";
 }
 async function buildRalplanPreToolUseBoundaryOutput(payload, cwd, stateDir, resolvedSessionId) {
     const sessionId = safeString(resolvedSessionId ?? readPayloadSessionId(payload)).trim();
@@ -2431,23 +2943,20 @@ async function buildRalplanPreToolUseBoundaryOutput(payload, cwd, stateDir, reso
     if (toolName === "Bash") {
         blocked = !isAllowedRalplanBashWrite(cwd, command);
         if (blocked) {
-            const targets = extractDeepInterviewCommandWriteTargets(command);
-            const blockedTarget = targets.find((target) => !isAllowedRalplanArtifactPath(cwd, target));
-            blockedDetail = blockedTarget
-                ? `write target ${blockedTarget} is not under allowed planning artifact paths (${RALPLAN_ALLOWED_WRITE_PREFIXES.join(", ")})`
-                : "Bash write intent did not identify an allowed planning artifact path";
+            blockedDetail = buildRalplanBashBlockedDetail(cwd, command);
         }
     }
     else if (PLANNING_MODE_IMPLEMENTATION_TOOL_NAMES.has(toolName)) {
-        if (pathCandidates.length === 0) {
+        const toolPathCandidates = collectImplementationToolPathCandidates(payload, toolName, pathCandidates);
+        if (toolPathCandidates.length === 0) {
             blocked = true;
-            blockedDetail = `${toolName} did not include a file path; only planning artifact paths are allowed`;
+            blockedDetail = describeImplementationToolBlock(toolName, undefined, toolPathCandidates.length);
         }
         else {
-            const blockedPath = pathCandidates.find((candidate) => !isAllowedRalplanArtifactPath(cwd, candidate));
+            const blockedPath = toolPathCandidates.find((candidate) => !isAllowedRalplanArtifactPath(cwd, candidate));
             blocked = blockedPath !== undefined;
             if (blockedPath !== undefined) {
-                blockedDetail = `path ${blockedPath} is not under allowed planning artifact paths (${RALPLAN_ALLOWED_WRITE_PREFIXES.join(", ")})`;
+                blockedDetail = describeImplementationToolBlock(toolName, blockedPath, toolPathCandidates.length);
             }
         }
     }
@@ -2465,7 +2974,7 @@ async function buildRalplanPreToolUseBoundaryOutput(payload, cwd, stateDir, reso
         hookSpecificOutput: {
             hookEventName: "PreToolUse",
             additionalContext: `${planningModeDescription}. `
-                + "Write only planning artifacts under `.omx/context/`, `.omx/plans/`, `.omx/specs/`, or required `.omx/state/` files. "
+                + "Write only planning artifacts under `.omx/context/`, `.omx/plans/`, `.omx/specs/`, required `.omx/state/` files, or tracker metadata under `.beads/`. "
                 + "Do not edit implementation files or run implementation-focused writes from planning phases. "
                 + `To execute, first process an explicit handoff such as ${formatExecutionHandoffList(cwd)}, which must emit terminal planning state before implementation begins.`,
         },
@@ -2533,6 +3042,20 @@ function modeStateMatchesSkillStopContext(state, cwd, sessionId) {
     }
     return true;
 }
+function modeStateHasExplicitMatchingCwd(state, cwd) {
+    const stateCwd = safeString(state.cwd
+        ?? state.workingDirectory
+        ?? state.working_directory
+        ?? state.project_path).trim();
+    if (!stateCwd)
+        return false;
+    try {
+        return resolve(stateCwd) === resolve(cwd);
+    }
+    catch {
+        return false;
+    }
+}
 async function readBlockingSkillForStop(cwd, stateDir, sessionId, threadId, requiredSkill) {
     const canonicalState = await readVisibleSkillActiveStateForStateDir(stateDir, sessionId);
     const visibleEntries = canonicalState ? listActiveSkills(canonicalState) : [];
@@ -2613,14 +3136,59 @@ function rootModeStateIsCanonicalForStopContext(state, cwd, sessionId, threadId)
         return false;
     return true;
 }
+function hasExplicitSessionScope(state) {
+    return safeString(state.owner_omx_session_id
+        ?? state.session_id
+        ?? state.codex_session_id
+        ?? state.owner_codex_session_id).trim() !== "";
+}
+async function readStateTimestampMs(state, path) {
+    return parseTimestampMs(state.updated_at)
+        ?? parseTimestampMs(state.completed_at)
+        ?? parseTimestampMs(state.created_at)
+        ?? await stat(path).then((info) => info.mtimeMs, () => null);
+}
+async function unscopedRootRalplanStateIsNewerTerminalPlanningCompletion(rootState, rootPath, sessionPath, cwd, threadId) {
+    if (hasExplicitSessionScope(rootState))
+        return false;
+    const stateThreadId = safeString(rootState.owner_codex_thread_id ?? rootState.thread_id).trim();
+    if (threadId && stateThreadId && stateThreadId !== threadId)
+        return false;
+    if (!modeStateHasExplicitMatchingCwd(rootState, cwd))
+        return false;
+    const phase = safeString(rootState.current_phase ?? rootState.currentPhase).trim().toLowerCase();
+    if (phase !== "complete" && phase !== "completed")
+        return false;
+    const planningComplete = rootState.planning_complete === true || rootState.planningComplete === true;
+    const latestPlanPath = safeString(rootState.latest_plan_path ?? rootState.latestPlanPath).trim();
+    if (!planningComplete || !latestPlanPath)
+        return false;
+    const sessionState = await readJsonIfExists(sessionPath);
+    if (!sessionState)
+        return false;
+    const sessionPhase = safeString(sessionState.current_phase ?? sessionState.currentPhase).trim().toLowerCase();
+    if (sessionPhase && TERMINAL_MODE_PHASES.has(sessionPhase))
+        return false;
+    const rootTimestamp = await readStateTimestampMs(rootState, rootPath);
+    const sessionTimestamp = await readStateTimestampMs(sessionState, sessionPath);
+    if (rootTimestamp === null || sessionTimestamp === null)
+        return false;
+    return rootTimestamp > sessionTimestamp;
+}
 async function shouldIgnoreSessionSkillBlockerForCanonicalInactiveRoot(cwd, stateDir, skill, sessionId, threadId) {
-    const rootModeState = await readJsonIfExists(join(stateDir, `${skill}-state.json`));
+    const rootModeStatePath = join(stateDir, `${skill}-state.json`);
+    const rootModeState = await readJsonIfExists(rootModeStatePath);
     if (!rootModeState)
         return false;
-    if (!rootModeStateIsCanonicalForStopContext(rootModeState, cwd, sessionId, threadId))
-        return false;
     if (!isTerminalOrInactiveModeState(rootModeState))
         return false;
+    const canonicalRoot = rootModeStateIsCanonicalForStopContext(rootModeState, cwd, sessionId, threadId)
+        && (skill !== "ralplan" || modeStateHasExplicitMatchingCwd(rootModeState, cwd));
+    const freshUnscopedRoot = canonicalRoot || skill !== "ralplan"
+        ? false
+        : await unscopedRootRalplanStateIsNewerTerminalPlanningCompletion(rootModeState, rootModeStatePath, join(stateDir, "sessions", sessionId, `${skill}-state.json`), cwd, threadId);
+    if (!canonicalRoot && !freshUnscopedRoot)
+        return false;
     const { rootPath } = getSkillActiveStatePathsForStateDir(stateDir);
     const rootSkillState = await readSkillActiveState(rootPath);
     return rootSkillStateHasNoActiveSkillForStopContext(rootSkillState, skill, sessionId, threadId);
@@ -3392,7 +3960,8 @@ export async function dispatchCodexNativeHook(payload, options = {}) {
         && shouldSuppressSubagentLifecycleHookDispatch();
     if (hookEventName === "UserPromptSubmit") {
         const prompt = readPromptText(payload);
-        goalWorkflowAdditionalContext = await buildGoalWorkflowReconciliationPromptWarning(cwd, prompt).catch(() => null);
+        goalWorkflowAdditionalContext = await buildCompletedGoalCleanupPromptWarning(cwd, prompt).catch(() => null)
+            ?? await buildGoalWorkflowReconciliationPromptWarning(cwd, prompt).catch(() => null);
         ultragoalSteeringAdditionalContext = prompt && !isSubagentPromptSubmit
             ? 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;
@@ -3550,9 +4119,11 @@ export async function dispatchCodexNativeHook(payload, options = {}) {
             : "";
         outputJson = await buildDeepInterviewPreToolUseBoundaryOutput(payload, cwd, stateDir, preToolUseSessionId)
             ?? await buildRalplanPreToolUseBoundaryOutput(payload, cwd, stateDir, preToolUseSessionId)
+            ?? await buildNativeSubagentCapacityCloseGuardOutput(payload, cwd, stateDir)
             ?? buildNativePreToolUseOutput(payload);
     }
     else if (hookEventName === "PostToolUse") {
+        await recordNativeSubagentCapacityBlocker(cwd, stateDir, payload).catch(() => { });
         if (detectMcpTransportFailure(payload)) {
             await markTeamTransportFailure(cwd, payload);
         }
@@ -3562,7 +4133,7 @@ export async function dispatchCodexNativeHook(payload, options = {}) {
     else if (hookEventName === "Stop") {
         outputJson = await buildStopHookOutput(payload, cwd, stateDir, {
             skipRalphStopBlock: isSubagentStop,
-        });
+        }) ?? await buildCompletedGoalCleanupStopOutput(payload, cwd);
     }
     return {
         hookEventName,
@@ -3659,6 +4230,9 @@ function buildMalformedStdinHookOutput(parseError, rawInput, cwd = process.cwd()
     const reason = "OMX native hook received malformed JSON input. Preserve runtime state, inspect the emitting hook payload yourself, and retry with valid JSON.";
     const systemMessage = `${reason} stdin JSON parsing failed inside codex-native-hook: ${parseError.message}.`;
     const inferredHookEventName = inferHookEventNameFromMalformedInput(rawInput);
+    if (inferredHookEventName === "PreToolUse") {
+        return { systemMessage };
+    }
     if (inferredHookEventName === "Stop" || (!inferredHookEventName && hasNativeStopRuntimeSurface(cwd))) {
         return {
             decision: "block",
@@ -3694,10 +4268,13 @@ async function buildOversizedStopActiveWorkflowOutput(cwd) {
     };
 }
 async function buildOversizedStdinHookOutput(rawHookEventName, cwd) {
+    const systemMessage = `OMX native hook rejected oversized stdin JSON before parsing; maxBytes=${MAX_NATIVE_STDIN_JSON_BYTES}.`;
+    if (rawHookEventName === "PreToolUse") {
+        return { systemMessage };
+    }
     if (rawHookEventName === "Stop") {
         return await buildOversizedStopActiveWorkflowOutput(cwd) ?? {};
     }
-    const systemMessage = `OMX native hook rejected oversized stdin JSON before parsing; maxBytes=${MAX_NATIVE_STDIN_JSON_BYTES}.`;
     return {
         continue: false,
         stopReason: "native_hook_stdin_oversized",
@@ -3777,9 +4354,9 @@ export async function runCodexNativeHookCli() {
         }
         const result = await dispatchCodexNativeHook(payload);
         if (result.outputJson) {
-            writeNativeHookJsonStdout(result.outputJson);
+            writeNativeHookJsonStdout(sanitizeCodexHookOutput(result.hookEventName, result.outputJson) ?? {});
         }
-        else if (result.hookEventName === "Stop") {
+        else if (result.hookEventName !== "PreCompact" && result.hookEventName !== "PostCompact") {
             writeNativeHookJsonStdout({});
         }
     }