oh-my-codex 0.17.3 → 0.18.0

package/src/scripts/codex-native-pre-post.ts

@@ -103,8 +103,8 @@ export function normalizePostToolUsePayload(
   const exitCode = safeInteger(parsedToolResponse?.exit_code)
     ?? safeInteger(parsedToolResponse?.exitCode)
     ?? null;
-  const rawText = safeString(rawToolResponse).trim();
-  const stdoutText = safeString(parsedToolResponse?.stdout).trim() || rawText;
+  const rawToolResponseText = safeString(rawToolResponse).trim();
+  const stdoutText = safeString(parsedToolResponse?.stdout).trim() || rawToolResponseText;
   const stderrText = safeString(parsedToolResponse?.stderr).trim();
 
   return {
@@ -149,30 +149,49 @@ type OmxParityCommand =
   | "trace"
   | "code-intel";
 
+function joinNonEmptyText(parts: string[]): string {
+  return parts
+    .filter(Boolean)
+    .join("\n")
+    .trim();
+}
+
+function structuredMcpTransportText(normalized: NormalizedPostToolUsePayload): string {
+  return joinNonEmptyText([
+    safeString(normalized.parsedToolResponse?.error),
+    safeString(normalized.parsedToolResponse?.message),
+    safeString(normalized.parsedToolResponse?.details),
+  ]);
+}
+
+function hasMcpTransportContext(text: string): boolean {
+  return /\bmcp\b/i.test(text)
+    || /\bomx-(?:state|memory|trace|code-intel)-server\b/i.test(text);
+}
+
+function hasMcpTransportFailurePattern(text: string): boolean {
+  return MCP_TRANSPORT_FAILURE_PATTERNS.some((pattern) => pattern.test(text));
+}
+
 export function detectMcpTransportFailure(
   payload: CodexHookPayload,
 ): McpTransportFailureSignal | null {
   const normalized = normalizePostToolUsePayload(payload);
   if (normalized.isBash) return null;
-  const combined = [
+
+  const isMcpTool = isMcpLikeToolName(normalized.toolName);
+  const structuredText = structuredMcpTransportText(normalized);
+  const rawText = joinNonEmptyText([
     normalized.stderrText,
     normalized.stdoutText,
-    safeString(normalized.parsedToolResponse?.error),
-    safeString(normalized.parsedToolResponse?.message),
-    safeString(normalized.parsedToolResponse?.details),
-  ]
-    .filter(Boolean)
-    .join("\n")
-    .trim();
+  ]);
+  const combined = isMcpTool
+    ? joinNonEmptyText([rawText, structuredText])
+    : structuredText;
 
-  const mcpContextDetected = isMcpLikeToolName(normalized.toolName)
-    || /\bmcp\b/i.test(combined)
-    || /\bomx-(?:state|memory|trace|code-intel)-server\b/i.test(combined);
-  if (!mcpContextDetected) return null;
   if (!combined) return null;
-  if (!MCP_TRANSPORT_FAILURE_PATTERNS.some((pattern) => pattern.test(combined))) {
-    return null;
-  }
+  if (!isMcpTool && !hasMcpTransportContext(structuredText)) return null;
+  if (!hasMcpTransportFailurePattern(combined)) return null;
 
   return {
     toolName: normalized.toolName,
@@ -976,15 +995,75 @@ function buildSloppyFallbackPreToolUseOutput(commandText: string): Record<string
   };
 }
 
+function removeHereDocBodies(command: string): string {
+  const lines = command.split(/\r?\n/);
+  const retained: string[] = [];
+  let pendingDelimiter: string | null = null;
+
+  for (const line of lines) {
+    if (pendingDelimiter) {
+      if (line.trim() === pendingDelimiter) {
+        pendingDelimiter = null;
+      }
+      continue;
+    }
+
+    retained.push(line);
+    const match = /<<-?\s*(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_.-]+))/.exec(line);
+    if (match) pendingDelimiter = match[1] || match[2] || match[3] || null;
+  }
+
+  return retained.join("\n");
+}
+
 function commandInvokesOmxQuestion(command: string): boolean {
-  const tokens = tokenizeShellCommand(command)?.map((token) => token.toLowerCase()) ?? [];
-  for (let index = 0; index < tokens.length; index += 1) {
-    const rawToken = tokens[index] || '';
-    const token = rawToken.replace(/\\/g, '/').split('/').pop() || '';
-    if ((token === 'omx' || token === 'omx.js') && tokens[index + 1] === 'question') return true;
-    if ((token === 'node' || token === 'node.exe') && /(?:^|\/)omx\.js$/.test(tokens[index + 1] || '') && tokens[index + 2] === 'question') return true;
+  const tokens = tokenizeShellCommandWithBoundaries(removeHereDocBodies(command))
+    ?.map((token) => ({ ...token, value: token.value.toLowerCase() }))
+    ?? [];
+
+  for (let commandStart = 0; commandStart < tokens.length; commandStart = nextCommandStart(tokens, commandStart)) {
+    const commandEnd = nextCommandStart(tokens, commandStart);
+    let index = commandStart;
+
+    while (index < commandEnd && isInlineShellEnvAssignment(tokens[index]?.value ?? "")) {
+      index += 1;
+    }
+
+    while (index < commandEnd && isEnvExecutableToken(tokens[index]?.value ?? "")) {
+      index += 1;
+      while (index < commandEnd) {
+        const token = tokens[index]?.value ?? "";
+        if (token === "--") {
+          index += 1;
+          break;
+        }
+        if (isInlineShellEnvAssignment(token)) {
+          index += 1;
+          continue;
+        }
+        if (token === "-i" || token === "--ignore-environment" || token.startsWith("--unset=")) {
+          index += 1;
+          continue;
+        }
+        if (token.startsWith("-")) {
+          index += envOptionConsumesNextValue(token) ? 2 : 1;
+          continue;
+        }
+        break;
+      }
+    }
+
+    const rawToken = tokens[index]?.value || "";
+    const token = rawToken.replace(/\\/g, "/").split("/").pop() || "";
+    if ((token === "omx" || token === "omx.js") && tokens[index + 1]?.value === "question") return true;
+    if (
+      (token === "node" || token === "node.exe")
+      && /(?:^|\/)omx\.js$/.test(tokens[index + 1]?.value || "")
+      && tokens[index + 2]?.value === "question"
+    ) return true;
   }
-  return /\bomx\s+question\b/i.test(command) || /\bomx\.js['"]?\s+question\b/i.test(command);
+
+  return false;
 }
 
 function isQuestionReturnPaneAssignment(token: string): boolean {

package/src/scripts/notify-dispatcher.ts

@@ -52,6 +52,21 @@ function resolveNotifyEntrypoint(command: readonly string[]): string | undefined
 	return command.slice(1).find((arg) => !arg.startsWith("-"));
 }
 
+function getPreviousNotifyWrapperValue(
+	command: readonly string[],
+): string | undefined {
+	for (let index = 0; index < command.length; index += 1) {
+		const part = command[index];
+		if (part === "--previous-notify") {
+			return command[index + 1];
+		}
+		if (part.startsWith("--previous-notify=")) {
+			return part.slice("--previous-notify=".length);
+		}
+	}
+	return undefined;
+}
+
 function isOmxManagedNotifyCommand(command: readonly string[] | null | undefined): boolean {
 	if (!command) return false;
 	const entrypoint = resolveNotifyEntrypoint(command);
@@ -62,12 +77,94 @@ function isOmxManagedNotifyCommand(command: readonly string[] | null | undefined
 	return /(?:^|[\\/])oh-my-codex(?:[\\/]|$)/.test(entrypoint);
 }
 
+function isOmxDispatcherMetadataCommand(command: readonly string[] | null | undefined): boolean {
+	if (!command) return false;
+	const entrypoint = resolveNotifyEntrypoint(command);
+	if (!entrypoint || !/(?:^|[\\/])notify-dispatcher\.js$/.test(entrypoint)) {
+		return false;
+	}
+	const metadataIndex = command.indexOf("--metadata");
+	const metadataPath = metadataIndex >= 0 ? command[metadataIndex + 1] : undefined;
+	return typeof metadataPath === "string" && /(?:^|[\\/])(?:\.omx[\\/])?notify-dispatch\.json$/.test(metadataPath);
+}
+
+function isOmxManagedPayloadText(value: string): boolean {
+	const containsManagedPackageNotify =
+		/(?:^|[\\/])notify-(?:hook|dispatcher)\.js(?:\s|$|["'])/.test(
+			value,
+		) && /(?:^|[\\/])oh-my-codex(?:[\\/]|$)/.test(value);
+	const containsDispatcherMetadataNotify =
+		/(?:^|[\\/])notify-dispatcher\.js(?:\s|$|["'])/.test(value) &&
+		/--metadata(?:\s|=)/.test(value) &&
+		/(?:^|[\\/])(?:\.omx[\\/])?notify-dispatch\.json(?:\s|$|["'])/.test(value);
+	return containsManagedPackageNotify || containsDispatcherMetadataNotify;
+}
+
+function parseJsonString(value: string): unknown | undefined {
+	const trimmed = value.trim();
+	if (!trimmed) return undefined;
+	const first = trimmed[0];
+	if (first !== "[" && first !== "{" && first !== '"') return undefined;
+	try {
+		return JSON.parse(trimmed) as unknown;
+	} catch {
+		return undefined;
+	}
+}
+
+function containsOmxManagedNotifyPayload(value: unknown, depth = 0): boolean {
+	if (depth > 8 || value == null) return false;
+	if (typeof value === "string") {
+		const parsed = parseJsonString(value);
+		if (parsed !== undefined && parsed !== value) {
+			return containsOmxManagedNotifyPayload(parsed, depth + 1);
+		}
+		return isOmxManagedPayloadText(value);
+	}
+	if (Array.isArray(value)) {
+		if (value.every((item) => typeof item === "string")) {
+			const command = value as string[];
+			return (
+				isOmxManagedNotifyCommand(command) ||
+				isOmxDispatcherMetadataCommand(command) ||
+				isOmxManagedPreviousNotifyWrapper(command)
+			);
+		}
+		return value.some((item) => containsOmxManagedNotifyPayload(item, depth + 1));
+	}
+	if (typeof value === "object") {
+		const record = value as Record<string, unknown>;
+		return [
+			record.previousNotify,
+			record.previous_notify,
+			record.notify,
+			record.command,
+			record.argv,
+			record.args,
+		].some((item) => containsOmxManagedNotifyPayload(item, depth + 1));
+	}
+	return false;
+}
+
+function isOmxManagedPreviousNotifyWrapper(
+	command: readonly string[] | null | undefined,
+): boolean {
+	if (!command) return false;
+	if (!command.some((part) => part === "turn-ended")) return false;
+	const previousNotify = getPreviousNotifyWrapperValue(command);
+	if (!previousNotify) return false;
+
+	return containsOmxManagedNotifyPayload(previousNotify);
+}
+
 function isManagedPreviousNotify(
 	previousNotify: readonly string[] | null | undefined,
 	metadata: NotifyDispatcherMetadata | null,
 ): boolean {
 	return (
 		isOmxManagedNotifyCommand(previousNotify) ||
+		isOmxDispatcherMetadataCommand(previousNotify) ||
+		isOmxManagedPreviousNotifyWrapper(previousNotify) ||
 		sameCommand(previousNotify, metadata?.omxNotify) ||
 		sameCommand(previousNotify, metadata?.dispatcherNotify)
 	);

package/src/scripts/notify-hook/team-dispatch.ts

@@ -726,12 +726,14 @@ function resolveWorkerCliForRequest(request, config) {
 
 function capturedPaneContainsTrigger(captured, trigger) {
   if (!captured || !trigger) return false;
-  return normalizeTmuxCapture(captured).includes(normalizeTmuxCapture(trigger));
+  const normalizeForDraftMatch = (value) => normalizeTmuxCapture(value).replace(/-\s+/g, '-');
+  return normalizeForDraftMatch(captured).includes(normalizeForDraftMatch(trigger));
 }
 
 function capturedPaneContainsTriggerNearTail(captured, trigger, nonEmptyTailLines = 24) {
   if (!captured || !trigger) return false;
-  const normalizedTrigger = normalizeTmuxCapture(trigger);
+  const normalizeForDraftMatch = (value) => normalizeTmuxCapture(value).replace(/-\s+/g, '-');
+  const normalizedTrigger = normalizeForDraftMatch(trigger);
   if (!normalizedTrigger) return false;
   const lines = safeString(captured)
     .split('\n')
@@ -739,7 +741,13 @@ function capturedPaneContainsTriggerNearTail(captured, trigger, nonEmptyTailLine
     .filter((line) => line.length > 0);
   if (lines.length === 0) return false;
   const tail = lines.slice(-Math.max(1, nonEmptyTailLines)).join(' ');
-  return normalizeTmuxCapture(tail).includes(normalizedTrigger);
+  return normalizeForDraftMatch(tail).includes(normalizedTrigger);
+}
+
+function buildJoinedCapturePaneArgv(paneTarget, tailLines = 80) {
+  // Join wrapped visual lines so long path-like trigger text split by tmux
+  // remains comparable with the original trigger.
+  return ['capture-pane', '-J', '-t', paneTarget, '-p', '-S', `-${tailLines}`];
 }
 
 const INJECT_VERIFY_DELAY_MS = 250;
@@ -791,7 +799,7 @@ async function injectDispatchRequest(request, config, cwd, stateDir) {
   if (attemptCountAtStart >= 1) {
     try {
       // Narrow capture (8 lines) to scope check to input area, not scrollback output
-      const preCapture = await runProcess('tmux', buildCapturePaneArgv(resolution.paneTarget, 8), 2000);
+      const preCapture = await runProcess('tmux', buildJoinedCapturePaneArgv(resolution.paneTarget, 8), 2000);
       preCaptureHasTrigger = capturedPaneContainsTrigger(preCapture.stdout, request.trigger_message);
     } catch {
       preCaptureHasTrigger = false;
@@ -830,8 +838,8 @@ async function injectDispatchRequest(request, config, cwd, stateDir) {
   // Post-injection verification: confirm the trigger text was consumed.
   // Fixes #391: without this, dispatch marks 'notified' even when the worker
   // pane is sitting on an unsent draft (C-m was not effectively applied).
-  const verifyNarrowArgv = buildCapturePaneArgv(resolution.paneTarget, 8);
-  const verifyWideArgv = buildCapturePaneArgv(resolution.paneTarget);
+  const verifyNarrowArgv = buildJoinedCapturePaneArgv(resolution.paneTarget, 8);
+  const verifyWideArgv = buildJoinedCapturePaneArgv(resolution.paneTarget);
   for (let round = 0; round < INJECT_VERIFY_ROUNDS; round++) {
     await new Promise((r) => setTimeout(r, INJECT_VERIFY_DELAY_MS));
     try {
@@ -842,6 +850,19 @@ async function injectDispatchRequest(request, config, cwd, stateDir) {
       // full-scrollback false positives.
       const narrowCap = await runProcess('tmux', verifyNarrowArgv, 2000);
       const wideCap = await runProcess('tmux', verifyWideArgv, 2000);
+      const triggerInNarrow = capturedPaneContainsTrigger(narrowCap.stdout, request.trigger_message);
+      const triggerNearTail = capturedPaneContainsTriggerNearTail(wideCap.stdout, request.trigger_message);
+      if (triggerInNarrow || triggerNearTail) {
+        // Draft is still visible, so C-m has not actually submitted it yet.
+        // Do not let transient spinner/active-task text mask an unsent draft.
+        await sendPaneInput({
+          paneTarget: resolution.paneTarget,
+          prompt: request.trigger_message,
+          submitKeyPresses,
+          typePrompt: false,
+        }).catch(() => {});
+        continue;
+      }
       // Worker is actively processing (mirrors sync path tmux-session.ts:1292-1294)
       if (paneHasActiveTask(wideCap.stdout)) {
         runtimeExec({ command: 'MarkDelivered', request_id: request.request_id }, stateDir, request.team_name);
@@ -862,8 +883,6 @@ async function injectDispatchRequest(request, config, cwd, stateDir) {
       if (request.to_worker !== 'leader-fixed' && !paneLooksReady(wideCap.stdout)) {
         continue;
       }
-      const triggerInNarrow = capturedPaneContainsTrigger(narrowCap.stdout, request.trigger_message);
-      const triggerNearTail = capturedPaneContainsTriggerNearTail(wideCap.stdout, request.trigger_message);
       if (!triggerInNarrow && !triggerNearTail) {
         runtimeExec({ command: 'MarkDelivered', request_id: request.request_id }, stateDir, request.team_name);
         return {

package/src/scripts/notify-hook/team-leader-nudge.ts

@@ -11,14 +11,14 @@ import { asNumber, safeString, isTerminalPhase } from './utils.js';
 import { readJsonIfExists, getScopedStateDirsForCurrentSession } from './state-io.js';
 import { runProcess } from './process-runner.js';
 import { logTmuxHookEvent } from './log.js';
-import { evaluatePaneInjectionReadiness, sendPaneInput } from './team-tmux-guard.js';
+import { evaluatePaneInjectionReadiness, queuePaneInput, sendPaneInput } from './team-tmux-guard.js';
 import { resolvePaneTarget } from './tmux-injection.js';
 import { listNotifyCanonicalActiveTeams } from './active-team.js';
 import {
   classifyLeaderActionState,
   resolveLeaderNudgeIntent,
 } from './orchestration-intent.js';
-import { DEFAULT_MARKER } from '../tmux-hook-engine.js';
+import { DEFAULT_MARKER, paneHasActiveTask } from '../tmux-hook-engine.js';
 import { isLeaderRuntimeStale } from '../../team/leader-activity.js';
 import { appendTeamDeliveryLog } from '../../team/delivery-log.js';
 import { writeTeamLeaderAttention } from '../../team/state.js';
@@ -967,14 +967,27 @@ export async function maybeNudgeTeamLeader({
     }
 
     try {
-      const sendResult = await sendPaneInput({
-        paneTarget: tmuxTarget,
-        prompt: markedText,
-        submitKeyPresses: 2,
-        submitDelayMs: 100,
-      });
-      if (!sendResult.ok) {
-        throw new Error(sendResult.error || sendResult.reason);
+      const leaderHasActiveTask = paneHasActiveTask(paneGuard.paneCapture);
+      let deliveryMode = 'sent';
+      if (leaderHasActiveTask) {
+        const sendResult = await queuePaneInput({
+          paneTarget: tmuxTarget,
+          prompt: markedText,
+        });
+        if (!sendResult.ok) {
+          throw new Error(sendResult.error || sendResult.reason);
+        }
+        deliveryMode = 'queued';
+      } else {
+        const sendResult = await sendPaneInput({
+          paneTarget: tmuxTarget,
+          prompt: markedText,
+          submitKeyPresses: 2,
+          submitDelayMs: 100,
+        });
+        if (!sendResult.ok) {
+          throw new Error(sendResult.error || sendResult.reason);
+        }
       }
       nudgeState.last_nudged_by_team[teamName] = {
         at: nowIso,
@@ -1005,6 +1018,7 @@ export async function maybeNudgeTeamLeader({
           message_count: messages.length,
           stalled_for_ms: undefined,
           missing_signal_workers: progressSnapshot.missingSignalWorkers,
+          delivery: deliveryMode,
         });
       } catch { /* ignore */ }
       await appendTeamDeliveryLog(logsDir, {
@@ -1013,7 +1027,7 @@ export async function maybeNudgeTeamLeader({
         team: teamName,
         to_worker: 'leader-fixed',
         transport: 'send-keys',
-        result: 'sent',
+        result: deliveryMode,
         reason: nudgeReason,
         orchestration_intent: orchestrationIntent,
       }).catch(() => {});

package/src/scripts/notify-hook/team-tmux-guard.ts

@@ -182,6 +182,48 @@ export async function sendPaneInput({
   }
 }
 
+export async function queuePaneInput({
+  paneTarget,
+  prompt,
+  submitDelayMs = 80,
+}: any): Promise<any> {
+  const sendResult = await sendPaneInput({
+    paneTarget,
+    prompt,
+    submitKeyPresses: 0,
+  });
+  if (!sendResult.ok) return sendResult;
+
+  const target = safeString(paneTarget).trim();
+  const submitArgv = [
+    ['send-keys', '-t', target, 'Tab'],
+    ['send-keys', '-t', target, 'C-m'],
+  ];
+  try {
+    await runProcess('tmux', submitArgv[0], 3000);
+    if (submitDelayMs > 0) {
+      await new Promise((resolve) => setTimeout(resolve, submitDelayMs));
+    }
+    await runProcess('tmux', submitArgv[1], 3000);
+    return {
+      ok: true,
+      sent: true,
+      reason: 'queued',
+      paneTarget: target,
+      argv: { typeArgv: sendResult.argv?.typeArgv || null, submitArgv },
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      sent: false,
+      reason: 'queue_failed',
+      paneTarget: target,
+      argv: { typeArgv: sendResult.argv?.typeArgv || null, submitArgv },
+      error: error instanceof Error ? error.message : safeString(error),
+    };
+  }
+}
+
 export async function checkPaneReadyForTeamSendKeys(paneTarget: any): Promise<any> {
   return evaluatePaneInjectionReadiness(paneTarget);
 }

package/src/scripts/notify-hook/team-worker-stop.ts

@@ -8,12 +8,12 @@
 
 import { appendFile, mkdir, rename, writeFile } from 'fs/promises';
 import { dirname, join } from 'path';
-import { DEFAULT_MARKER } from '../tmux-hook-engine.js';
+import { DEFAULT_MARKER, paneHasActiveTask } from '../tmux-hook-engine.js';
 import { appendTeamDeliveryLog } from '../../team/delivery-log.js';
 import { safeString, asNumber } from './utils.js';
 import { readJsonIfExists } from './state-io.js';
 import { logTmuxHookEvent } from './log.js';
-import { evaluatePaneInjectionReadiness, sendPaneInput } from './team-tmux-guard.js';
+import { evaluatePaneInjectionReadiness, queuePaneInput, sendPaneInput } from './team-tmux-guard.js';
 import { resolvePaneTarget } from './tmux-injection.js';
 import { readTeamWorkersForIdleCheck } from './team-worker.js';
 
@@ -185,17 +185,28 @@ export async function maybeNudgeLeaderForAllowedWorkerStop({
     + DEFAULT_MARKER;
 
   try {
-    const sendResult = await sendPaneInput({
-      paneTarget: tmuxTarget,
-      prompt,
-      submitKeyPresses: 2,
-      submitDelayMs: 100,
-    });
-    if (!sendResult.ok) throw new Error(sendResult.error || sendResult.reason || 'send_failed');
+    const leaderHasActiveTask = paneHasActiveTask(paneGuard.paneCapture);
+    let deliveryMode = 'sent';
+    if (leaderHasActiveTask) {
+      const sendResult = await queuePaneInput({
+        paneTarget: tmuxTarget,
+        prompt,
+      });
+      if (!sendResult.ok) throw new Error(sendResult.error || sendResult.reason || 'send_failed');
+      deliveryMode = 'queued';
+    } else {
+      const sendResult = await sendPaneInput({
+        paneTarget: tmuxTarget,
+        prompt,
+        submitKeyPresses: 2,
+        submitDelayMs: 100,
+      });
+      if (!sendResult.ok) throw new Error(sendResult.error || sendResult.reason || 'send_failed');
+    }
 
     await writeStopNudgeState(statePath, {
       ...nextState,
-      delivery: 'sent',
+      delivery: deliveryMode,
       leader_pane_id: leaderPaneId || null,
       tmux_target: tmuxTarget,
     });
@@ -205,7 +216,7 @@ export async function maybeNudgeLeaderForAllowedWorkerStop({
       type: 'worker_stop_leader_nudge',
       worker: workerName,
       to_worker: 'leader-fixed',
-      delivery: 'sent',
+      delivery: deliveryMode,
       created_at: nowIso,
       source_type: SOURCE_TYPE,
     });
@@ -225,10 +236,10 @@ export async function maybeNudgeLeaderForAllowedWorkerStop({
       from_worker: workerName,
       to_worker: 'leader-fixed',
       transport: 'send-keys',
-      result: 'sent',
+      result: deliveryMode,
       reason: 'worker_stop_allowed',
     }).catch(() => {});
-    return { ok: true, result: 'sent' };
+    return { ok: true, result: deliveryMode };
   } catch (err) {
     await recordDeferred({
       stateDir,

package/src/scripts/run-provider-advisor.ts

@@ -83,6 +83,16 @@ function shouldUseClaudeIssuePermissionsBypass(provider: string, prompt: string)
   return ISSUE_WORK_PROMPT_PATTERNS.some((pattern) => pattern.test(trimmed));
 }
 
+function buildProviderLaunchArgs(provider: string, prompt: string, originalTask: string): string[] {
+  const promptArgs = provider === 'claude'
+    ? ['-p', '--', prompt]
+    : ['-p', prompt];
+
+  return shouldUseClaudeIssuePermissionsBypass(provider, originalTask)
+    ? [CLAUDE_SKIP_PERMISSIONS_FLAG, ...promptArgs]
+    : promptArgs;
+}
+
 function buildSummary(exitCode: number, output: string): string {
   if (exitCode === 0) {
     return 'Provider completed successfully. Review the raw output for details.';
@@ -165,9 +175,7 @@ async function main(): Promise<void> {
 
   ensureBinary(binary);
 
-  const launchArgs = shouldUseClaudeIssuePermissionsBypass(provider, originalTask)
-    ? [CLAUDE_SKIP_PERMISSIONS_FLAG, '-p', prompt]
-    : ['-p', prompt];
+  const launchArgs = buildProviderLaunchArgs(provider, prompt, originalTask);
 
   const run = spawnSync(binary, launchArgs, {
     encoding: 'utf8',

package/src/scripts/smoke-packed-install.ts

@@ -20,6 +20,8 @@ export {
 export const PACKED_INSTALL_SMOKE_CORE_COMMANDS = [
   ['--help'],
   ['version'],
+  ['api', '--help'],
+  ['sparkshell', '--help'],
 ] as const;
 
 function usage(): string {

package/templates/catalog-manifest.json

@@ -108,6 +108,13 @@
       "core": false,
       "internalRequired": false
     },
+    {
+      "name": "best-practice-research",
+      "category": "planning",
+      "status": "active",
+      "core": false,
+      "internalRequired": false
+    },
     {
       "name": "analyze",
       "category": "shortcut",