oh-my-codex 0.13.2 → 0.14.0

package/src/scripts/notify-hook/auto-nudge.ts

@@ -21,6 +21,8 @@ import { logTmuxHookEvent } from './log.js';
 import { evaluatePaneInjectionReadiness, mapPaneInjectionReadinessReason, sendPaneInput } from './team-tmux-guard.js';
 import { stripOrchestrationIntentTags } from './orchestration-intent.js';
 import { buildCapturePaneArgv, DEFAULT_MARKER, tmuxHookExplicitlyDisablesInjection } from '../tmux-hook-engine.js';
+import { readAutoresearchCompletionStatus } from '../../autoresearch/skill-validation.js';
+import { persistDeepInterviewModeState } from '../../hooks/keyword-detector.js';
 import {
   isManagedOmxSession,
   resolveManagedCurrentPane,
@@ -36,6 +38,7 @@ export const DEEP_INTERVIEW_INPUT_LOCK_MESSAGE = 'Deep interview is active; auto
 export const DEFAULT_AUTO_NUDGE_RESPONSE = 'continue with the current task only if it is already authorized';
 const DEEP_INTERVIEW_ERROR_PATTERNS = [' error', ' failed', ' failure', ' exception', 'unable to continue', 'cannot continue', 'could not continue'];
 const DEEP_INTERVIEW_ABORT_PATTERNS = ['aborted', 'cancelled', 'canceled'];
+const DEEP_INTERVIEW_SUCCESS_PATTERNS = ['interview completed', 'interview complete', 'interview finished', 'final summary ready'];
 const DEEP_INTERVIEW_ABORT_INPUTS = new Set(['abort', 'cancel', 'stop']);
 const DEEP_INTERVIEW_BLOCKED_APPROVAL_PREFIXES = new Set(['next i should']);
 const SKILL_PHASES = new Set(['planning', 'executing', 'reviewing', 'completing']);
@@ -99,6 +102,10 @@ function hasAnySubstring(text, patterns) {
   return patterns.some((pattern) => lower.includes(pattern));
 }
 
+function looksLikeDeepInterviewSuccess(text) {
+  return hasAnySubstring(text, DEEP_INTERVIEW_SUCCESS_PATTERNS);
+}
+
 export function isDeepInterviewAutoApprovalLocked(skillState) {
   return Boolean(
     skillState
@@ -188,6 +195,78 @@ async function persistSkillActiveState(stateDir, sessionId, state) {
   await writeScopedJson(stateDir, SKILL_ACTIVE_STATE_FILE, sessionId, state).catch(() => {});
 }
 
+function cloneSkillActiveState(state) {
+  if (!state || typeof state !== 'object') return null;
+  return {
+    ...state,
+    input_lock: state.input_lock
+      ? {
+        ...state.input_lock,
+        blocked_inputs: Array.isArray(state.input_lock.blocked_inputs)
+          ? [...state.input_lock.blocked_inputs]
+          : state.input_lock.blocked_inputs,
+      }
+      : state.input_lock,
+  };
+}
+
+export async function syncSkillStateFromTurn(stateDir, payload) {
+  const lastMessage = safeString(payload['last-assistant-message'] || payload.last_assistant_message || '');
+  const latestUserInput = latestUserInputFromPayload(payload);
+  const invocationSessionId = resolveInvocationSessionId(payload);
+  let skillState = await loadSkillActiveState(stateDir, invocationSessionId);
+  let releaseReason = null;
+
+  if (!skillState) {
+    return { invocationSessionId, skillState: null, releaseReason };
+  }
+
+  const previousSkillState = cloneSkillActiveState(skillState);
+  const previousPhase = normalizeSkillPhase(skillState.phase);
+  const inferredPhase = inferSkillPhaseFromText(lastMessage, previousPhase);
+  const explicitDeepInterviewSuccess = skillState.skill === 'deep-interview' && looksLikeDeepInterviewSuccess(lastMessage);
+  const nextPhase = skillState.skill === 'deep-interview'
+    && inferredPhase === 'completing'
+    && previousPhase !== 'completing'
+    && !explicitDeepInterviewSuccess
+    ? previousPhase
+    : inferredPhase;
+  skillState.phase = nextPhase;
+  skillState.active = nextPhase !== 'completing';
+
+  if (skillState.skill === 'autoresearch') {
+    const completion = await readAutoresearchCompletionStatus(payload.cwd || process.cwd(), invocationSessionId);
+    skillState.validation_mode = completion.validationMode;
+    skillState.autoresearch_completion_reason = completion.reason;
+    skillState.completion_artifact_path = completion.artifactPath;
+    if (completion.complete) {
+      skillState.phase = 'completing';
+      skillState.active = false;
+    } else if (inferredPhase === 'completing') {
+      skillState.phase = previousPhase === 'completing' ? 'reviewing' : previousPhase;
+      skillState.active = true;
+    }
+  }
+
+  const nowIso = new Date().toISOString();
+  skillState.updated_at = nowIso;
+  releaseReason = inferDeepInterviewReleaseReason({ skillState, latestUserInput, lastMessage });
+  if (releaseReason && isDeepInterviewAutoApprovalLocked(skillState)) {
+    releaseDeepInterviewInputLock(skillState, releaseReason, nowIso);
+  }
+  await persistSkillActiveState(stateDir, invocationSessionId, skillState);
+
+  if (skillState.skill === 'deep-interview' || previousSkillState?.skill === 'deep-interview') {
+    await persistDeepInterviewModeState(stateDir, skillState, nowIso, previousSkillState, {
+      sessionId: invocationSessionId,
+      threadId: safeString(payload?.['thread-id'] || payload?.thread_id || ''),
+      turnId: safeString(payload?.['turn-id'] || payload?.turn_id || ''),
+    });
+  }
+
+  return { invocationSessionId, skillState, releaseReason };
+}
+
 
 export async function isDeepInterviewStateActive(stateDir, sessionId) {
   const modeState = await readScopedJsonIfExists(stateDir, 'deep-interview-state.json', sessionId, null);
@@ -479,8 +558,10 @@ export async function resolveNudgePaneTarget(stateDir: any, cwd = '', payload: a
         if (!anchoredPane) continue;
         const managedPane = await resolveManagedPaneFromAnchor(anchoredPane, cwd, payload, { allowTeamWorker });
         if (managedPane) return managedPane;
-        const verdict = await verifyManagedPaneTarget(anchoredPane, cwd, payload, { allowTeamWorker });
-        if (verdict.ok) return anchoredPane;
+        if (allowTeamWorker) {
+          const verdict = await verifyManagedPaneTarget(anchoredPane, cwd, payload, { allowTeamWorker });
+          if (verdict.ok) return anchoredPane;
+        }
       } catch {
         // skip malformed state
       }
@@ -516,21 +597,9 @@ export async function maybeAutoNudge({ cwd, stateDir, logsDir, payload }) {
   }
 
   const lastMessage = safeString(payload['last-assistant-message'] || payload.last_assistant_message || '');
-  const latestUserInput = latestUserInputFromPayload(payload);
-  const invocationSessionId = resolveInvocationSessionId(payload);
-  let skillState = await loadSkillActiveState(stateDir, invocationSessionId);
-  let releaseReason = null;
+  const { invocationSessionId, skillState, releaseReason } = await syncSkillStateFromTurn(stateDir, payload);
 
   try {
-    if (skillState) {
-      const inferredPhase = inferSkillPhaseFromText(lastMessage, skillState.phase);
-      skillState.phase = inferredPhase;
-      skillState.active = inferredPhase !== 'completing';
-      skillState.updated_at = new Date().toISOString();
-      releaseReason = inferDeepInterviewReleaseReason({ skillState, latestUserInput, lastMessage });
-      await persistSkillActiveState(stateDir, invocationSessionId, skillState);
-    }
-
     const nudgeStatePath = await getScopedStatePath(stateDir, 'auto-nudge-state.json', invocationSessionId);
     let nudgeState = await readScopedJsonIfExists(stateDir, 'auto-nudge-state.json', invocationSessionId, null);
     if (!nudgeState || typeof nudgeState !== 'object') {
@@ -618,8 +687,10 @@ export async function maybeAutoNudge({ cwd, stateDir, logsDir, payload }) {
       return;
     }
 
-    const deepInterviewLockActive = isDeepInterviewAutoApprovalLocked(skillState) && !releaseReason;
-    if (deepInterviewLockActive) {
+    const blockedAutoApproval = isDeepInterviewAutoApprovalLocked(skillState)
+      && !releaseReason
+      && isBlockedAutoApprovalInput(effectiveResponse, skillState.input_lock?.blocked_inputs);
+    if (blockedAutoApproval) {
       const blockedMessage = skillState.input_lock?.message || DEEP_INTERVIEW_INPUT_LOCK_MESSAGE;
       await logTmuxHookEvent(logsDir, {
         timestamp: new Date().toISOString(),
@@ -628,9 +699,7 @@ export async function maybeAutoNudge({ cwd, stateDir, logsDir, payload }) {
         response: effectiveResponse,
         source,
         blocked_by: 'deep-interview-lock',
-        block_kind: isBlockedAutoApprovalInput(effectiveResponse, skillState.input_lock?.blocked_inputs)
-          ? 'blocked-auto-approval'
-          : 'input-lock-active',
+        block_kind: 'blocked-auto-approval',
         message: blockedMessage,
         suppressed: true,
       }).catch(() => {});

package/src/scripts/notify-hook/managed-tmux.ts

@@ -248,7 +248,7 @@ export async function verifyManagedPaneTarget(paneId: string, cwd: string, paylo
 }
 
 
-async function readManagedPaneCommandState(paneTarget: string): Promise<{ currentCommand: string; startCommand: string }> {
+async function readManagedPaneCommandState(paneTarget: string): Promise<{ currentCommand: string; startCommand: string; lookupFailed: boolean }> {
   try {
     const [currentResult, startResult] = await Promise.all([
       runProcess('tmux', ['display-message', '-p', '-t', paneTarget, '#{pane_current_command}'], 2000),
@@ -257,9 +257,10 @@ async function readManagedPaneCommandState(paneTarget: string): Promise<{ curren
     return {
       currentCommand: safeString(currentResult.stdout).trim().toLowerCase(),
       startCommand: safeString(startResult.stdout).trim().toLowerCase(),
+      lookupFailed: false,
     };
   } catch {
-    return { currentCommand: '', startCommand: '' };
+    return { currentCommand: '', startCommand: '', lookupFailed: true };
   }
 }
 
@@ -268,6 +269,59 @@ function paneLooksLikeManagedAgent({ currentCommand, startCommand }: { currentCo
   if (startCommand.includes('codex')) return true;
   return currentCommand === 'codex' || currentCommand === 'node' || currentCommand === 'npx';
 }
+
+function paneLooksLikeRetainableManagedAnchor({ currentCommand, startCommand }: { currentCommand: string; startCommand: string }): boolean {
+  if (/\bomx\b.*\bhud\b.*--watch/i.test(startCommand)) return false;
+  if (currentCommand === 'codex') return true;
+  if ((currentCommand === 'node' || currentCommand === 'npx') && startCommand.includes('codex')) return true;
+  return false;
+}
+
+function paneLooksLikeDetachedManagedWrapperFallback({ currentCommand, startCommand }: { currentCommand: string; startCommand: string }): boolean {
+  if (/\bomx\b.*\bhud\b.*--watch/i.test(startCommand)) return false;
+  return currentCommand === 'node' || currentCommand === 'npx';
+}
+
+interface ManagedSessionPaneRow {
+  paneId: string;
+  active: boolean;
+  currentCommand: string;
+  startCommand: string;
+}
+
+function parseManagedSessionPaneRows(stdout: string): ManagedSessionPaneRow[] {
+  return safeString(stdout)
+    .trim()
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      const [paneId = '', activeRaw = '0', rawCurrentCommand = '', rawStartCommand = ''] = line.split('\t');
+      return {
+        paneId: safeString(paneId).trim(),
+        active: safeString(activeRaw).trim() === '1',
+        currentCommand: safeString(rawCurrentCommand).trim().toLowerCase(),
+        startCommand: safeString(rawStartCommand).trim().toLowerCase(),
+      };
+    })
+    .filter((row) => row.paneId !== '');
+}
+
+function selectManagedSessionPane(
+  rows: ManagedSessionPaneRow[],
+  { allowWrapperFallback = false }: { allowWrapperFallback?: boolean } = {},
+): string {
+  const nonHudRows = rows.filter((row) => !/\bomx\b.*\bhud\b.*--watch/i.test(row.startCommand));
+  const canonicalRows = nonHudRows.filter((row) => paneLooksLikeRetainableManagedAnchor(row));
+  const activeCanonical = canonicalRows.find((row) => row.active);
+  if (activeCanonical) return activeCanonical.paneId;
+  if (canonicalRows[0]?.paneId) return canonicalRows[0].paneId;
+  if (!allowWrapperFallback) return '';
+
+  const wrapperFallbackRows = nonHudRows.filter((row) => paneLooksLikeDetachedManagedWrapperFallback(row));
+  const activeWrapperFallback = wrapperFallbackRows.find((row) => row.active);
+  if (activeWrapperFallback) return activeWrapperFallback.paneId;
+  return wrapperFallbackRows[0]?.paneId || '';
+}
 export async function resolveManagedCurrentPane(cwd: string, payload: any, { allowTeamWorker = false } = {}): Promise<string> {
   const paneTarget = safeString(process.env.TMUX_PANE || '').trim();
   if (!paneTarget) return '';
@@ -286,22 +340,10 @@ export async function resolveManagedSessionPane(cwd: string, payload: any): Prom
   try {
     const panesResult = await runProcess(
       'tmux',
-      ['list-panes', '-s', '-t', expectedSession, '-F', '#{pane_id}\t#{pane_current_command}\t#{pane_start_command}'],
+      ['list-panes', '-s', '-t', expectedSession, '-F', '#{pane_id}\t#{pane_active}\t#{pane_current_command}\t#{pane_start_command}'],
       2000,
     );
-    const panes = safeString(panesResult.stdout)
-      .trim()
-      .split('\n')
-      .filter(Boolean);
-    for (const line of panes) {
-      const [candidatePaneId, rawCurrentCommand = '', rawStartCommand = ''] = line.split('\t');
-      const startCommand = safeString(rawStartCommand).toLowerCase();
-      const currentCommand = safeString(rawCurrentCommand).trim().toLowerCase();
-      if (!candidatePaneId) continue;
-      if (/\bomx\b.*\bhud\b.*--watch/i.test(startCommand)) continue;
-      if (startCommand.includes('codex')) return candidatePaneId;
-      if (currentCommand === 'codex') return candidatePaneId;
-    }
+    return selectManagedSessionPane(parseManagedSessionPaneRows(panesResult.stdout));
   } catch {
     // best effort only
   }
@@ -315,29 +357,26 @@ export async function resolveManagedPaneFromAnchor(anchorPane: string, cwd: stri
   const verdict = await verifyManagedPaneTarget(paneTarget, cwd, payload, { allowTeamWorker });
   if (!verdict.ok) return '';
 
+  const commandState = await readManagedPaneCommandState(paneTarget);
+  if (commandState.lookupFailed) return paneTarget;
+  if (paneLooksLikeRetainableManagedAnchor(commandState)) return paneTarget;
+
   try {
-    const sessionResult = await runProcess('tmux', ['display-message', '-p', '-t', paneTarget, '#S'], 2000);
-    const sessionName = safeString(sessionResult.stdout).trim();
-    if (!sessionName) return paneTarget;
+    const sessionName = safeString(verdict.paneSessionName || verdict.managedContext?.expectedTmuxSessionName).trim();
+    if (!sessionName) return '';
 
     const panesResult = await runProcess(
       'tmux',
-      ['list-panes', '-s', '-t', sessionName, '-F', '#{pane_id}\t#{pane_current_command}\t#{pane_start_command}'],
+      ['list-panes', '-s', '-t', sessionName, '-F', '#{pane_id}\t#{pane_active}\t#{pane_current_command}\t#{pane_start_command}'],
       2000,
     );
-    const panes = safeString(panesResult.stdout).trim().split('\n').filter(Boolean);
-    for (const line of panes) {
-      const [candidatePaneId, rawCurrentCommand = '', rawStartCommand = ''] = line.split('\t');
-      const startCommand = safeString(rawStartCommand).toLowerCase();
-      const currentCommand = safeString(rawCurrentCommand).trim().toLowerCase();
-      if (!candidatePaneId) continue;
-      if (/\bomx\b.*\bhud\b.*--watch/i.test(startCommand)) continue;
-      if (startCommand.includes('codex')) return candidatePaneId;
-      if (currentCommand === 'codex') return candidatePaneId;
-    }
+    const selectedPane = selectManagedSessionPane(parseManagedSessionPaneRows(panesResult.stdout), {
+      allowWrapperFallback: paneLooksLikeDetachedManagedWrapperFallback(commandState),
+    });
+    if (selectedPane) return selectedPane;
   } catch {
     // best effort only
   }
 
-  return paneTarget;
+  return '';
 }

package/src/scripts/notify-hook/ralph-session-resume.ts

@@ -7,7 +7,7 @@ import { resolveCodexPane } from '../tmux-hook-engine.js';
 import { safeString } from './utils.js';
 
 const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
-const RALPH_TERMINAL_PHASES = new Set(['complete', 'failed', 'cancelled']);
+const RALPH_TERMINAL_PHASES = new Set(['blocked_on_user', 'complete', 'failed', 'cancelled']);
 const RALPH_RESUME_LOCK_STALE_MS = 10_000;
 const RALPH_RESUME_LOCK_TIMEOUT_MS = 5_000;
 const RALPH_RESUME_LOCK_RETRY_MS = 25;

package/src/scripts/notify-hook.ts

@@ -40,7 +40,13 @@ import {
 import { isLeaderStale, resolveLeaderStalenessThresholdMs, maybeNudgeTeamLeader } from './notify-hook/team-leader-nudge.js';
 import { drainPendingTeamDispatch } from './notify-hook/team-dispatch.js';
 import { handleTmuxInjection } from './notify-hook/tmux-injection.js';
-import { maybeAutoNudge, resolveNudgePaneTarget, isDeepInterviewStateActive } from './notify-hook/auto-nudge.js';
+import {
+  maybeAutoNudge,
+  resolveNudgePaneTarget,
+  isDeepInterviewStateActive,
+  isDeepInterviewInputLockActive,
+  syncSkillStateFromTurn,
+} from './notify-hook/auto-nudge.js';
 import { isManagedOmxSession } from './notify-hook/managed-tmux.js';
 import { logNotifyHookEvent } from './notify-hook/log.js';
 import { reconcileRalphSessionResume } from './notify-hook/ralph-session-resume.js';
@@ -238,14 +244,19 @@ async function main() {
   }
 
   // 1. Log the turn
+  const normalizedInputMessages = normalizeInputMessages(payload);
+  const latestInputPreview = safeString(
+    normalizedInputMessages.length > 0
+      ? normalizedInputMessages[normalizedInputMessages.length - 1]
+      : '',
+  ).slice(0, 200);
   const logEntry = {
     timestamp: new Date().toISOString(),
     type: payload.type || 'agent-turn-complete',
     thread_id: payload['thread-id'] || payload.thread_id,
     turn_id: payload['turn-id'] || payload.turn_id,
-    input_preview: (payload['input-messages'] || payload.input_messages || [])
-      .map((m: any) => m.slice(0, 100))
-      .join('; '),
+    input_preview: latestInputPreview,
+    input_message_count: normalizedInputMessages.length,
     output_preview: (payload['last-assistant-message'] || payload.last_assistant_message || '')
       .slice(0, 200),
   };
@@ -473,7 +484,14 @@ async function main() {
     // Non-fatal: keyword detector module may not be built yet
   }
 
+  try {
+    await syncSkillStateFromTurn(stateDir, payload);
+  } catch {
+    // Non-fatal: lifecycle sync should not block the hook
+  }
+
   const deepInterviewStateActive = await isDeepInterviewStateActive(stateDir, getEffectiveSessionId());
+  const deepInterviewInputLockActive = await isDeepInterviewInputLockActive(stateDir, getEffectiveSessionId());
 
   // 4.55. Notify leader when individual worker transitions to idle (worker session only)
   if (isTeamWorker && parsedTeamWorker && !deepInterviewStateActive) {
@@ -642,7 +660,7 @@ async function main() {
 
   // 9. Auto-nudge: detect Codex stall patterns and automatically send a continuation prompt.
   //    Works for both leader and worker contexts.
-  if (!deepInterviewStateActive) {
+  if (!deepInterviewStateActive || deepInterviewInputLockActive) {
     try {
       await maybeAutoNudge({ cwd, stateDir, logsDir, payload });
     } catch {

package/src/scripts/sync-prompt-guidance-fragments.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { existsSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 
 async function read(path: string): Promise<string> { return await readFile(path, 'utf-8'); }
@@ -12,6 +13,7 @@ function replaceBetween(text: string, startMarker: string, endMarker: string, re
 
 async function main(): Promise<void> {
   const op = (await read('docs/prompt-guidance-fragments/core-operating-principles.md')).trim();
+  const sr = (await read('docs/prompt-guidance-fragments/leader-specialist-routing.md')).trim();
   const vs = (await read('docs/prompt-guidance-fragments/core-verification-and-sequencing.md')).trim();
   const exC = (await read('docs/prompt-guidance-fragments/executor-constraints.md')).trim();
   const exO = (await read('docs/prompt-guidance-fragments/executor-output.md')).trim();
@@ -22,8 +24,10 @@ async function main(): Promise<void> {
   const vfI = (await read('docs/prompt-guidance-fragments/verifier-investigation.md')).trim();
 
   for (const file of ['AGENTS.md', 'templates/AGENTS.md']) {
+    if (!existsSync(file)) continue;
     let text = await read(file);
     text = replaceBetween(text, '<!-- OMX:GUIDANCE:OPERATING:START -->', '<!-- OMX:GUIDANCE:OPERATING:END -->', op);
+    text = replaceBetween(text, '<!-- OMX:GUIDANCE:SPECIALIST-ROUTING:START -->', '<!-- OMX:GUIDANCE:SPECIALIST-ROUTING:END -->', sr);
     text = replaceBetween(text, '<!-- OMX:GUIDANCE:VERIFYSEQ:START -->', '<!-- OMX:GUIDANCE:VERIFYSEQ:END -->', vs);
     await writeFile(file, text);
   }

package/templates/AGENTS.md

@@ -10,6 +10,7 @@ USE CODEX NATIVE SUBAGENTS FOR INDEPENDENT PARALLEL SUBTASKS WHEN THAT IMPROVES
 You are running with oh-my-codex (OMX), a coordination layer for Codex CLI.
 This AGENTS.md is the top-level operating contract for the workspace.
 Role prompts under `prompts/*.md` are narrower execution surfaces. They must follow this file, not override it.
+When OMX is installed, load the installed prompt/skill/agent surfaces from `~/.codex/prompts`, `~/.codex/skills`, and `~/.codex/agents` (or the project-local `./.codex/...` equivalents when project scope is active).
 
 <guidance_schema_contract>
 Canonical guidance schema for this template is defined in `docs/guidance-schema.md`.
@@ -38,6 +39,11 @@ Keep runtime marker contracts stable and non-destructive when overlays are appli
 <!-- OMX:GUIDANCE:OPERATING:START -->
 - Default to quality-first, intent-deepening responses; think one more step before replying or asking for clarification, and use as much detail as needed for a strong result without empty verbosity.
 - Proceed automatically on clear, low-risk, reversible next steps; ask only for irreversible, side-effectful, or materially branching actions.
+- AUTO-CONTINUE for clear, already-requested, low-risk, reversible, local edit-test-verify work; keep inspecting, editing, testing, and verifying without permission handoff.
+- ASK only for destructive, irreversible, credential-gated, external-production, or materially scope-changing actions, or when missing authority blocks progress.
+- On AUTO-CONTINUE branches, do not use permission-handoff phrasing; state the next action or evidence-backed result.
+- Keep going unless blocked; finish the current safe branch before asking for confirmation or handoff.
+- Ask only when blocked by missing information, missing authority, or an irreversible/destructive branch.
 - Do not ask or instruct humans to perform ordinary non-destructive, reversible actions; execute those safe reversible OMX/runtime operations and ordinary commands yourself.
 - Treat OMX runtime manipulation, state transitions, and ordinary command execution as agent responsibilities when they are safe and reversible.
 - Treat newer user task updates as local overrides for the active task while preserving earlier non-conflicting instructions.
@@ -176,12 +182,25 @@ Rules:
 <model_routing>
 Match role to task shape:
 - Low complexity: `explore`, `style-reviewer`, `writer`
+- Research/discovery: `explore` for repo lookup, `researcher` for official docs/reference gathering, `dependency-expert` for SDK/API/package evaluation
 - Standard: `executor`, `debugger`, `test-engineer`
 - High complexity: `architect`, `executor`, `critic`
 
 For Codex native child agents, model routing defaults to inheritance/current repo defaults unless the caller has a concrete reason to override it.
 </model_routing>
 
+<specialist_routing>
+Leader/workflow routing contract:
+<!-- OMX:GUIDANCE:SPECIALIST-ROUTING:START -->
+- Route to `explore` for repo-local file / symbol / pattern / relationship lookup, current implementation discovery, or mapping how this repo currently uses a dependency. `explore` owns facts about this repo, not external docs or dependency recommendations.
+- Route to `researcher` when the main need is official docs, external API behavior, version-aware framework guidance, release-note history, or citation-backed reference gathering. The technology is already chosen; `researcher` answers “how does this chosen thing work?” and is not the default dependency-comparison role.
+- Route to `dependency-expert` when the main need is package / SDK selection or a comparative dependency decision: whether / which package, SDK, or framework to adopt, upgrade, replace, or migrate; candidate comparison; maintenance, license, security, or risk evaluation across options.
+- Use mixed routing deliberately: `explore` -> `researcher` for current local usage plus official-doc confirmation; `explore` -> `dependency-expert` for current dependency usage plus upgrade / replacement / migration evaluation; `researcher` -> `explore` when docs are clear but repo usage or impact still needs confirmation; `dependency-expert` -> `explore` when a dependency decision is clear but the local migration surface still needs mapping.
+- Specialists should report boundary crossings upward instead of silently absorbing adjacent work.
+- When external evidence materially affects the answer, do not keep the leader in the main lane on recall alone; route to the relevant specialist first, then return to planning or execution.
+<!-- OMX:GUIDANCE:SPECIALIST-ROUTING:END -->
+</specialist_routing>
+
 ---
 
 <agent_catalog>
@@ -193,50 +212,43 @@ Key roles:
 - `executor` — implementation and refactoring
 - `verifier` — completion evidence and validation
 
+Research/discovery specialists:
+- `explore` — first-stop repository lookup and symbol/file mapping
+- `researcher` — official docs, references, and external fact gathering
+- `dependency-expert` — SDK/API/package evaluation before adopting or changing dependencies
+
 Specialists remain available through the role catalog and native child-agent surfaces when the task clearly benefits from them.
 </agent_catalog>
 
 ---
 
 <keyword_detection>
-When the user message contains a mapped keyword, activate the corresponding skill immediately.
-Do not ask for confirmation.
+Keyword routing is implemented primarily by native `UserPromptSubmit` hooks and the generated keyword registry. Treat hook-injected routing context as authoritative for the current turn, then load the named `SKILL.md` or prompt file as instructed.
 
-Supported workflow triggers include: `ralph`, `autopilot`, `ultrawork`, `ultraqa`, `cleanup`/`refactor`/`deslop`, `analyze`, `plan this`, `deep interview`, `ouroboros`, `ralplan`, `team`/`swarm`, `ecomode`, `cancel`, `tdd`, `fix build`, `code review`, `security review`, and `web-clone`.
-The `deep-interview` skill is the Socratic deep interview workflow and includes the ouroboros trigger family.
+Fallback behavior when hook context is unavailable:
+- Explicit `$name` invocations run left-to-right and override implicit keywords.
+- Bare skill names do not activate skills by themselves; skill-name activation requires explicit `$skill` invocation. Natural-language routing phrases may still map to a workflow when they are not just the bare skill name. Examples: `analyze` / `investigate` → `$analyze` for read-only deep analysis with ranked synthesis, explicit confidence, and concrete file references; `deep interview`, `interview`, `don't assume`, or `ouroboros` → `$deep-interview`; `ralplan` / `consensus plan` → `$ralplan`; `cancel`, `stop`, or `abort` → `$cancel`.
+- Keep the detailed keyword list in `src/hooks/keyword-registry.ts`; do not duplicate that table here.
 
-| Keyword(s) | Skill | Action |
-|-------------|-------|--------|
 Runtime availability gate:
 - Treat `autopilot`, `ralph`, `ultrawork`, `ultraqa`, `team`/`swarm`, and `ecomode` as **OMX runtime workflows**, not generic prompt aliases.
-- Auto-activate those runtime workflows only when the current session is actually running under OMX CLI/runtime (for example, launched via `omx`, with OMX session overlay/runtime state available, or when the user explicitly asks to run `omx ...` in the shell).
+- Auto-activate runtime workflows only when the current session is actually running under OMX CLI/runtime (for example, launched via `omx`, with OMX session overlay/runtime state available, or when the user explicitly asks to run `omx ...` in the shell).
 - In Codex App or plain Codex sessions without OMX runtime, do **not** treat those keywords alone as activation. Explain that they require OMX CLI runtime support, and continue with the nearest App-safe surface (`deep-interview`, `ralplan`, `plan`, or native subagents) unless the user explicitly wants you to launch OMX from the shell.
+- When deep-interview is active in OMX CLI/runtime, ask interview rounds via `omx question`; do not substitute `request_user_input` or ad hoc plain-text questioning, and respect Stop-hook blocking while a deep-interview question obligation is pending.
+
+<triage_routing>
+## Triage: advisory prompt-routing context
+
+The keyword detector is the first and deterministic routing surface. Triage runs only when no keyword matches.
 
-| Keyword(s) | Skill | Action |
-|-------------|-------|--------|
-| "ralph", "don't stop", "must complete", "keep going" | `$ralph` | Runtime-only: read `~/.codex/skills/ralph/SKILL.md`, execute persistence loop only inside OMX CLI/runtime |
-| "autopilot", "build me", "I want a" | `$autopilot` | Runtime-only: read `~/.codex/skills/autopilot/SKILL.md`, execute autonomous pipeline only inside OMX CLI/runtime |
-| "ultrawork", "ulw", "parallel" | `$ultrawork` | Runtime-only: read `~/.codex/skills/ultrawork/SKILL.md`, execute parallel agents only inside OMX CLI/runtime |
-| "ultraqa" | `$ultraqa` | Runtime-only: read `~/.codex/skills/ralph/SKILL.md`, run persistent completion and verification loop only inside OMX CLI/runtime (UltraQA compatibility alias) |
-| "analyze", "investigate" | `$analyze` | Read `~/.codex/skills/analyze/SKILL.md`, run read-only deep analysis with ranked synthesis, explicit confidence, and concrete file references |
-| "plan this", "plan the", "let's plan" | `$plan` | Read `~/.codex/skills/plan/SKILL.md`, start planning workflow |
-| "interview", "deep interview", "gather requirements", "interview me", "don't assume", "ouroboros" | `$deep-interview` | Read `~/.codex/skills/deep-interview/SKILL.md`, run Ouroboros-inspired Socratic ambiguity-gated interview workflow |
-| "ralplan", "consensus plan" | `$ralplan` | Read `~/.codex/skills/ralplan/SKILL.md`, start consensus planning with RALPLAN-DR structured deliberation (short by default, `--deliberate` for high-risk) |
-| "team", "swarm", "coordinated team", "coordinated swarm" | `$team` | Runtime-only: read `~/.codex/skills/team/SKILL.md`, start tmux-based team orchestration only inside OMX CLI/runtime (swarm compatibility alias) |
-| "ecomode", "eco", "budget" | `$ecomode` | Runtime-only: read `~/.codex/skills/ultrawork/SKILL.md`, execute cost-aware parallel workflow only inside OMX CLI/runtime (ecomode compatibility alias) |
-| "cancel", "stop", "abort" | `$cancel` | Read `~/.codex/skills/cancel/SKILL.md`, cancel active modes |
-| "tdd", "test first" | `$tdd` | Read `~/.codex/prompts/test-engineer.md`, run test-first workflow (tdd compatibility alias) |
-| "fix build", "type errors" | `$build-fix` | Read `~/.codex/prompts/build-fixer.md`, fix build errors with minimal diff (build-fix compatibility alias) |
-| "review code", "code review", "code-review" | `$code-review` | Read `~/.codex/skills/code-review/SKILL.md`, run code review |
-| "security review" | `$security-review` | Read `~/.codex/skills/security-review/SKILL.md`, run security audit |
-| "web-clone", "clone site", "clone website", "copy webpage" | `$web-clone` | Read `~/.codex/skills/web-clone/SKILL.md`, start website cloning pipeline |
-
-Detection rules:
-- Keywords are case-insensitive and match anywhere in the user message.
-- Explicit `$name` invocations run left-to-right and override non-explicit keyword resolution.
-- If multiple non-explicit keywords match, use the most specific match.
-- Runtime-only keywords must pass the runtime availability gate before activation.
-- The rest of the user message becomes the task description.
+When active, triage emits **advisory prompt-routing context** — a developer-context string that the model may follow. It does not activate a skill or workflow by itself. It is a best-effort hint, not a guarantee.
+
+Note: `explore`, `executor`, and `designer` are agent role-prompt files under `prompts/`, not workflow skills.
+
+Explicit keywords remain the deterministic control surface when you want explicit, guaranteed routing — use them whenever exact behavior matters.
+
+To opt out per prompt with phrases such as `no workflow`, `just chat`, or `plain answer` — the triage layer will suppress context injection for that prompt.
+</triage_routing>
 
 Ralph / Ralplan execution gate:
 - Enforce **ralplan-first** when ralph is active and planning is not complete.
@@ -374,6 +386,8 @@ Do not cancel while recoverable work remains.
 ---
 
 <state_management>
+Hooks own normal skill-active and workflow-state persistence under `.omx/state/`.
+
 OMX persists runtime state under `.omx/`:
 - `.omx/state/` — mode state
 - `.omx/notepad.md` — session notes
@@ -383,11 +397,8 @@ OMX persists runtime state under `.omx/`:
 
 Available MCP groups include state/memory tools, code-intel tools, and trace tools.
 
-Mode lifecycle requirements:
-- Write state on start.
-- Update state on phase or iteration change.
-- Mark inactive with `completed_at` on completion.
-- Clear state on cancel/abort cleanup.
+Agents may use OMX state/MCP tools for explicit lifecycle transitions, recovery, checkpointing, cancellation cleanup, or compaction resilience.
+Do not manually duplicate hook-owned activation state unless recovering from missing or stale state.
 </state_management>
 
 ---

package/templates/catalog-manifest.json

@@ -45,6 +45,13 @@
       "core": false,
       "internalRequired": false
     },
+    {
+      "name": "autoresearch",
+      "category": "execution",
+      "status": "active",
+      "core": false,
+      "internalRequired": false
+    },
     {
       "name": "swarm",
       "category": "execution",