@jini-ai/daemon 0.6.8 → 0.6.10

package/dist/agent-executor/launch.js

@@ -139,7 +139,9 @@ function waitForSpawnOrError(child) {
  */
 function resolveAgentRuntimeDeps(options) {
     const runtimeOptions = options.runtimeState ? { state: options.runtimeState } : {};
-    const envOptions = options.hostEnv ? { env: options.hostEnv } : {};
+    // `createAgentExecutor` always resolves both before calling here (host env falls back to the
+    // process env, the pi shutdown grace to its env override or 5000 ms), so neither is optional.
+    const envOptions = { env: options.hostEnv };
     const lookupDef = options.getAgentDef ?? getAgentDef;
     return {
         getAgentDef: (input) => {
@@ -154,7 +156,7 @@ function resolveAgentRuntimeDeps(options) {
         applyAgentLaunchEnv: options.applyAgentLaunchEnv ?? ((input, optional = {}) => applyAgentLaunchEnv(input, { appendPathDirs: userToolchainBinDirs({}, { ...runtimeOptions, ...envOptions }), ...optional })),
         attachAcpSession: options.attachAcpSession ?? attachAcpSession,
         attachPiRpcSession: (required, optional = {}) => (options.attachPiRpcSession ?? attachPiRpcSession)(required, {
-            ...optional, ...(options.piGracefulShutdownMs !== undefined ? { gracefulShutdownMs: options.piGracefulShutdownMs } : {}),
+            ...optional, gracefulShutdownMs: options.piGracefulShutdownMs,
         }),
         preparePromptFileForAgent: options.preparePromptFileForAgent ?? preparePromptFileForAgent,
         prepareAgentLogFile: options.prepareAgentLogFile ?? prepareAgentLogFile,
@@ -283,6 +285,16 @@ export function computeChildEnv({ spawnEnv, mcpBridge }, { codexHomeDir, systemP
     const claudeConfigDirApplied = claudeConfigDir === undefined ? codexHomeApplied : { ...codexHomeApplied, CLAUDE_CONFIG_DIR: claudeConfigDir };
     return systemPromptEnvOverrides === undefined ? claudeConfigDirApplied : { ...claudeConfigDirApplied, ...systemPromptEnvOverrides };
 }
+/** Session fields use the same nonempty-string rule as the CLI buildArgs boundary. */
+function sessionRuntimeContext({ resumeSessionId, newSessionId }, _options = {}) {
+    // Matches claude.ts buildArgs' own `typeof x === 'string' && x` truthiness check, so an empty
+    // string or explicit `null` (no resume target yet) is treated as absent here too, rather than
+    // manufacturing a context that carries a session field the def would ignore anyway.
+    return {
+        ...(typeof resumeSessionId === 'string' && resumeSessionId.length > 0 ? { resumeSessionId } : {}),
+        ...(typeof newSessionId === 'string' && newSessionId.length > 0 ? { newSessionId } : {}),
+    };
+}
 /**
  * Phase 6b: the `RuntimeContext` `buildArgs` receives — `undefined` unless a file, bridge path, or
  * session id was staged. Pure.
@@ -295,37 +307,42 @@ export function computeChildEnv({ spawnEnv, mcpBridge }, { codexHomeDir, systemP
  * case for a resumed turn.
  */
 export function computeRuntimeContext({ preparedPromptFile, preparedLogFile, mcpBridge }, { resumeSessionId, newSessionId } = {}) {
-    // Matches claude.ts buildArgs' own `typeof x === 'string' && x` truthiness check, so an empty
-    // string or explicit `null` (no resume target yet) is treated as absent here too, rather than
-    // manufacturing a context that carries a session field the def would ignore anyway.
-    const hasResumeSessionId = typeof resumeSessionId === 'string' && resumeSessionId.length > 0;
-    const hasNewSessionId = typeof newSessionId === 'string' && newSessionId.length > 0;
-    if (!preparedPromptFile
-        && !preparedLogFile
-        && mcpBridge?.kind !== 'claude-mcp-json'
-        && !hasResumeSessionId
-        && !hasNewSessionId) {
-        return undefined;
-    }
-    return {
+    const context = {
         ...(preparedPromptFile ? { promptFilePath: preparedPromptFile.path } : {}),
         ...(preparedLogFile ? { agentLogFilePath: preparedLogFile.path } : {}),
         // Safe to pass before the file exists: `writeMcpJsonForRun` runs after buildArgs but still
         // before spawn, so the path is real by the time the child process starts.
         ...(mcpBridge?.kind === 'claude-mcp-json' ? { mcpJsonPath: mcpBridge.mcpJsonPath } : {}),
-        ...(hasResumeSessionId ? { resumeSessionId } : {}),
-        ...(hasNewSessionId ? { newSessionId } : {}),
+        ...sessionRuntimeContext({ resumeSessionId, newSessionId }, {}),
     };
+    return Object.keys(context).length === 0 ? undefined : context;
 }
 /**
  * Phase 8: the host's `PromptAugmenter.systemOverlay()` result, if configured — see
  * `CreateAgentExecutorOptions.promptAugmenter`'s doc for `turnIndex`'s coarse 0/1 proxy.
  */
-function computeSystemPromptOverlay(promptAugmenter, agentId, runtimeContext) {
-    return promptAugmenter?.systemOverlay?.({
-        agentId,
-        turnIndex: runtimeContext?.hasPriorAssistantTurn ? 1 : 0,
-    });
+function computeSystemPromptOverlay(promptAugmenter, agentId) {
+    // Always turn 0: the only prior-turn signal, `RuntimeContext.hasPriorAssistantTurn`, is never
+    // populated by `computeRuntimeContext` (it carries staged-file, MCP and session-id fields only).
+    return promptAugmenter?.systemOverlay?.({ agentId, turnIndex: 0 });
+}
+/** Native policy forwarding also enforces parity's permission and tool-access prerequisites. */
+function nativeBuildOptions({ input, permissionMode }, _options = {}) {
+    return {
+        ...(input.nativeToolAccess !== undefined ? { nativeToolAccess: input.nativeToolAccess } : {}),
+        ...(input.nativeCapabilities ? { nativeCapabilities: input.nativeCapabilities } : {}),
+        ...(input.cliParity === true && permissionMode === 'bypass' && input.nativeToolAccess !== false ? { cliParity: true } : {}),
+    };
+}
+/** Preserve explicit empty restrictions and settings: they have meaning to the native CLI. */
+function settingsBuildOptions({ input }, _options = {}) {
+    return {
+        ...(input.disallowedTools !== undefined ? { disallowedTools: input.disallowedTools } : {}),
+        ...(input.allowedTools !== undefined ? { allowedTools: input.allowedTools } : {}),
+        ...(input.settingSources !== undefined ? { settingSources: input.settingSources } : {}),
+        ...(input.settings !== undefined ? { settings: input.settings } : {}),
+        ...(input.chromeIntegration !== undefined ? { chromeIntegration: input.chromeIntegration } : {}),
+    };
 }
 /** Phase 9a: the def's `buildArgs` 4th argument. Historically omitted when every override was absent;
  * that let defs silently enable auto-approval. Always supply the validated restricted default now. Pure. */
@@ -339,13 +356,30 @@ export function buildAgentBuildArgsOptions({ input, systemPromptOverlay }) {
         ...(input.model !== undefined ? { model: input.model } : {}),
         ...(input.reasoning !== undefined ? { reasoning: input.reasoning } : {}),
         permissionMode,
-        ...(input.disallowedTools !== undefined ? { disallowedTools: input.disallowedTools } : {}),
-        ...(input.allowedTools !== undefined ? { allowedTools: input.allowedTools } : {}),
-        ...(input.settingSources !== undefined ? { settingSources: input.settingSources } : {}),
-        ...(input.settings !== undefined ? { settings: input.settings } : {}),
+        ...nativeBuildOptions({ input, permissionMode }, {}),
+        ...settingsBuildOptions({ input }, {}),
         ...(hasOverlay ? { systemPromptOverlay } : {}),
     };
-    return Object.keys(options).length === 0 ? undefined : options;
+    return options;
+}
+function hasSystemPromptOverlay(args, _options = {}) {
+    return typeof args.overlay === 'string' && args.overlay.length > 0;
+}
+function appendFlagOverlay({ defId, systemPromptDelivery, overlay, prompt }, { state } = {}) {
+    const capabilityKey = systemPromptDelivery.capabilityKey;
+    // `!== false`, not a truthiness check: mirrors `claude.ts`'s own pre-existing
+    // `agentCapabilities.get('claude') || {}` gate exactly (moved here, not changed) — an
+    // undetected/never-probed capability defaults to allowed, and only an EXPLICIT `false` (the
+    // `--help` probe ran and did not find the flag) withholds it. `capabilityKey === undefined`
+    // (e.g. `pi`'s existing `--append-system-prompt`, trusted unconditionally) always passes, same
+    // as an absent key.
+    const capabilityOk = capabilityKey === undefined || (state?.capabilities ?? agentCapabilities).get(defId)?.[capabilityKey] !== false;
+    return { promptPrefix: '', prompt, extraArgs: capabilityOk ? [systemPromptDelivery.flag, overlay] : [], envOverrides: {} };
+}
+function isContinuingOverlaySession({ resumesSessionViaCli, resumesSessionViaAcpLoad, resumeSessionId }, _options = {}) {
+    return (resumesSessionViaCli === true || resumesSessionViaAcpLoad === true) &&
+        typeof resumeSessionId === 'string' &&
+        resumeSessionId.length > 0;
 }
 /**
  * **The single dispatch point from a computed system-prompt overlay to its delivery mechanism** —
@@ -391,20 +425,13 @@ export function buildAgentBuildArgsOptions({ input, systemPromptOverlay }) {
  * @overallScore 100/100
  */
 export function resolveSystemPromptOverlayDelivery(input, { state } = {}) {
-    const { defId, systemPromptDelivery, resumesSessionViaCli, resumesSessionViaAcpLoad, overlay, prompt, resumeSessionId } = input;
-    if (typeof overlay !== 'string' || overlay.length === 0) {
+    const { defId, systemPromptDelivery, resumesSessionViaCli, resumesSessionViaAcpLoad, prompt, resumeSessionId } = input;
+    if (!hasSystemPromptOverlay(input, {})) {
         return { promptPrefix: '', prompt, extraArgs: [], envOverrides: {} };
     }
+    const overlay = input.overlay;
     if (systemPromptDelivery?.strategy === 'append-flag') {
-        const capabilityKey = systemPromptDelivery.capabilityKey;
-        // `!== false`, not a truthiness check: mirrors `claude.ts`'s own pre-existing
-        // `agentCapabilities.get('claude') || {}` gate exactly (moved here, not changed) — an
-        // undetected/never-probed capability defaults to allowed, and only an EXPLICIT `false` (the
-        // `--help` probe ran and did not find the flag) withholds it. `capabilityKey === undefined`
-        // (e.g. `pi`'s existing `--append-system-prompt`, trusted unconditionally) always passes, same
-        // as an absent key.
-        const capabilityOk = capabilityKey === undefined || (state?.capabilities ?? agentCapabilities).get(defId)?.[capabilityKey] !== false;
-        return { promptPrefix: '', prompt, extraArgs: capabilityOk ? [systemPromptDelivery.flag, overlay] : [], envOverrides: {} };
+        return appendFlagOverlay({ defId, systemPromptDelivery, overlay, prompt }, { state });
     }
     if (systemPromptDelivery?.strategy === 'env-var') {
         // No capability gate, unlike `'append-flag'`: an unrecognized env var is inert to a CLI (it
@@ -425,10 +452,7 @@ export function resolveSystemPromptOverlayDelivery(input, { state } = {}) {
         // `imageDelivery`'s doc calls out for its own native-vs-fallback split.
         return { promptPrefix: '', prompt, extraArgs: [], envOverrides: {} };
     }
-    const isContinuingExistingSession = (resumesSessionViaCli === true || resumesSessionViaAcpLoad === true) &&
-        typeof resumeSessionId === 'string' &&
-        resumeSessionId.length > 0;
-    if (isContinuingExistingSession) {
+    if (isContinuingOverlaySession({ resumesSessionViaCli, resumesSessionViaAcpLoad, resumeSessionId }, {})) {
         return { promptPrefix: '', prompt, extraArgs: [], envOverrides: {} };
     }
     // KNOWN TRADE-OFF, deliberate: for a resume-capable def with no `'append-flag'`/`'env-var'`
@@ -465,7 +489,7 @@ export async function buildRunArgs({ input, deps }) {
         const options = buildAgentBuildArgsOptions({ input: input.runInput, systemPromptOverlay: input.systemPromptOverlay });
         const args = input.def.buildArgs({ prompt: delivery.prompt, imagePaths: [...(input.imagePaths ?? [])] }, {
             ...(input.imageDelivery.extraAllowedDirs === undefined ? {} : { extraAllowedDirs: [...input.imageDelivery.extraAllowedDirs] }),
-            ...(options === undefined ? {} : { options }),
+            options,
             ...(input.runtimeContext === undefined ? {} : { runtimeContext: input.runtimeContext }),
         });
         // `'append-flag'` delivery's extra argv (empty for every other def/strategy) is appended after
@@ -497,6 +521,7 @@ export async function buildRunArgs({ input, deps }) {
  * a defensive extra.
  * @param input.def - Only used for its `id`, in the failure message, and its `systemPromptDelivery` declaration.
  * @param input.overlay - The computed `PromptAugmenter.systemOverlay()` result for this run.
+ * @param deps.mkdtemp - Creates the run-scoped directory from a prefix; default a fresh `mkdtemp` under `os.tmpdir()`.
  * @complexity O(1) plus one directory creation and one file write.
  * @overallScore 100/100
  */
@@ -508,7 +533,7 @@ export async function prepareSystemPromptOverlayFileIfNeeded({ input, deps }) {
     }
     try {
         const safeRunId = input.runId.replace(/[^A-Za-z0-9_-]/g, '-').slice(0, 80) || 'run';
-        const dir = await fsPromises.mkdtemp(join(tmpdir(), `jini-system-prompt-overlay-${safeRunId}-`));
+        const dir = await (deps.mkdtemp ?? defaultMkdtempInTmpdir)(`jini-system-prompt-overlay-${safeRunId}-`);
         const filePath = join(dir, 'overlay.md');
         await fsPromises.writeFile(filePath, input.overlay, { encoding: 'utf8', mode: 0o600 });
         return {
@@ -523,13 +548,18 @@ export async function prepareSystemPromptOverlayFileIfNeeded({ input, deps }) {
         return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: could not stage a system-prompt overlay file for agent "${input.def.id}": ${errorMessage(err)}` });
     }
 }
+/** A fresh, randomly named directory under `os.tmpdir()`: the real staging location. */
+function defaultMkdtempInTmpdir(prefix) {
+    return fsPromises.mkdtemp(join(tmpdir(), prefix));
+}
 /** Phase 11: post-`buildArgs` guard for argv-bound defs whose resolved binary is a Windows shim/.exe — a no-op off-Windows and for non-argv-bound defs. */
 export async function guardWindowsCommandLineBudget({ input, deps }) {
     const windowsBudgetError = checkWindowsCmdShimCommandLineBudget({ def: input.def, resolvedBin: input.launchPath, args: input.args }) ??
         checkWindowsDirectExeCommandLineBudget({ def: input.def, resolvedBin: input.launchPath, args: input.args });
     if (windowsBudgetError) {
         await deps.releaseStagedResources();
-        await deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_PROMPT_TOO_LARGE', message: windowsBudgetError.message });
+        // `failBeforeSpawn` always rejects (`Promise<never>`); returning it propagates that rejection.
+        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_PROMPT_TOO_LARGE', message: windowsBudgetError.message });
     }
 }
 /**
@@ -579,9 +609,40 @@ export async function confirmChildSpawned({ input, deps }) {
     }
     catch (err) {
         await deps.releaseStagedResources();
-        await deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: failed to spawn agent "${input.def.id}": ${errorMessage(err)}` });
+        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: failed to spawn agent "${input.def.id}": ${errorMessage(err)}` });
     }
 }
+/** Only include declared capability restrictions; absence has a distinct downstream contract. */
+function nativeCapabilityInput({ input }, _options = {}) {
+    return { ...(input.nativeCapabilities !== undefined ? { nativeCapabilities: input.nativeCapabilities } : {}) };
+}
+/** Correlation projects retained stdout, so exact-byte journals need a separate blob writer. */
+function validateStdoutJournalOptions(options, _options = {}) {
+    if (options.delegatedResultCorrelation && options.journal && !options.stdoutJournalBlobs) {
+        throw new Error('delegated result correlation with a byte journal requires stdoutJournalBlobs');
+    }
+}
+/** Model discovery consumes the exact spawn environment and caller-supplied settings. */
+function launchModelContext({ input, launch, spawnEnv }, _options = {}) {
+    return {
+        executable: launch.launchPath, cwd: input.cwd, env: spawnEnv,
+        ...(input.model && input.model !== 'default' ? { model: input.model } : {}),
+        ...(input.resumeSessionId ? { resumeSessionId: input.resumeSessionId } : {}),
+        ...(input.settingSources ? { settingSources: input.settingSources } : {}),
+        ...(input.settings ? { settings: input.settings } : {}),
+    };
+}
+/** Paths are available only after staging; retain the strategy gate for instructions files. */
+function stagedChildEnvOptions({ def, preparedCodexHome, preparedClaudeConfigDir, preparedSystemPromptOverlayFile, systemPromptEnvOverrides }, _options = {}) {
+    return {
+        ...(preparedCodexHome === null ? {} : { codexHomeDir: preparedCodexHome.path }),
+        systemPromptEnvOverrides,
+        ...(preparedSystemPromptOverlayFile && def.systemPromptDelivery?.strategy === 'config-instructions-file'
+            ? { stagedInstructionsFile: { varName: def.systemPromptDelivery.varName, path: preparedSystemPromptOverlayFile.path } }
+            : {}),
+        ...(preparedClaudeConfigDir === null ? {} : { claudeConfigDir: preparedClaudeConfigDir.path }),
+    };
+}
 /**
  * Creates the `AgentExecutor` reference implementation: an in-process
  * `RunLifecycle` driver over real (by default) `@jini-ai/agent-runtime`
@@ -609,6 +670,7 @@ export function createAgentExecutor(requiredArgs, optionalArgs = {}) {
     const { getAgentDef: getAgentDefFn, resolveAgentLaunch: resolveAgentLaunchFn, ensureAgentCapabilities: ensureAgentCapabilitiesFn, applyAgentLaunchEnv: applyAgentLaunchEnvFn, attachAcpSession: attachAcpSessionFn, attachPiRpcSession: attachPiRpcSessionFn, preparePromptFileForAgent: preparePromptFileForAgentFn, prepareAgentLogFile: prepareAgentLogFileFn, } = resolveAgentRuntimeDeps({ ...options, hostEnv });
     const { createCommandInvocation: createCommandInvocationFn, spawn: spawnFn, listProcessSnapshots: listProcessSnapshotsFn, collectProcessTreePids: collectProcessTreePidsFn, stopProcesses: stopProcessesFn, } = resolveProcessDeps(options);
     const { onCleanupFailure: onCleanupFailureFn, bufferedStdoutMaxBytes } = resolveMiscExecutorDeps(options);
+    validateStdoutJournalOptions(options);
     const journal = options.journal;
     const continuation = options.continuation;
     const classifyFailure = options.classifyFailure;
@@ -647,38 +709,29 @@ export function createAgentExecutor(requiredArgs, optionalArgs = {}) {
      */
     const liveRunInputs = new Map();
     /** `AgentExecutor.sendUserMessage()` — see that interface method's own doc. @complexity O(1). */
-    async function sendUserMessage({ runId, text }) {
+    async function sendUserMessage({ runId, text }, { imageContents } = {}) {
         const deliver = liveRunInputs.get(runId);
-        return deliver ? deliver(text) : 'not-running';
+        return deliver ? deliver(text, imageContents) : 'not-running';
     }
-    /**
-     * `AgentExecutor.run()` — see that interface method's own doc for the
-     * public contract. Implementation note on shape: every guard below
-     * returns `failBeforeSpawn(...)` directly (a `Promise<never>`, valid
-     * wherever `Promise<void>` is expected) rather than `await`-then-`return`,
-     * so each failure path reads as a single, obviously-terminal statement.
-     * @param input - `{runId, agentId, prompt, cwd, model?, reasoning?, imagePaths?, extraAllowedDirs?, uploadRoot?, env?}` — `runId` must already be `lifecycle.start()`-ed.
-     * @throws {@link AgentExecutorError} — see index.ts module doc's Invariant; never a bare `Error`.
-     * @complexity O(1) setup (registry lookup, launch resolution, one spawn call); steady-state cost thereafter belongs to {@link wireChildLifecycle}.
-     * @overallScore 100/100
-     */
-    async function run(requiredArgs, optionalArgs = {}) {
+    /** Validates launch input and selects the definition synchronously before yielding. */
+    async function prepareRunContext({ requiredArgs, optionalArgs }, _options = {}) {
         const input = { ...requiredArgs, ...optionalArgs, permissionMode: optionalArgs.permissionMode ?? 'restricted' };
         if (input.permissionMode !== 'restricted' && input.permissionMode !== 'bypass') {
             return failBeforeSpawn({ runId: input.runId, code: 'AGENT_PERMISSION_MODE_INVALID', message: 'AgentExecutor: permissionMode must be restricted or bypass' });
         }
-        const { def, streamFormat } = await resolveDefAndStreamFormat({ input: { runId: input.runId, agentId: input.agentId }, deps: { getAgentDef: getAgentDefFn, failBeforeSpawn } });
-        // Computed once, before anything downstream ever looks at "the prompt" or "the allowed
-        // dirs" — a no-op (`{prompt: input.prompt, extraAllowedDirs: input.extraAllowedDirs}`,
-        // literally unchanged) unless `def.imageDelivery === 'prompt-path'` AND `input.imagePaths`
-        // is non-empty, so this can never affect a 'native'-delivery def (ACP, pi-rpc, qoder) or a
-        // run with no attachments. See `image-prompt-delivery.ts`'s own doc for the full mechanism;
-        // every use of `input.prompt`/`input.extraAllowedDirs` below that reflects what the CLI
-        // actually receives reads `imageDelivery.*` instead — the two ACP/pi-rpc `wire*Lifecycle`
-        // calls further down deliberately keep reading `input.prompt` verbatim, since those two
-        // defs' own native protocol already delivers the image and must never also get this
-        // treatment (the double-delivery hazard this mechanism exists to avoid).
-        const imageDelivery = await resolveImageDeliveryAndArgvBudget({ input: { runId: input.runId, def, prompt: input.prompt, imagePaths: input.imagePaths, extraAllowedDirs: input.extraAllowedDirs }, deps: { failBeforeSpawn } });
+        // Lookup runs before the first await so a subsequent registry replacement cannot change this run's definition.
+        const resolved = await resolveDefAndStreamFormat({ input, deps: { getAgentDef: getAgentDefFn, failBeforeSpawn } });
+        return { input, ...resolved };
+    }
+    async function enforceNativeToolPolicy({ input, def }, _options = {}) {
+        // Never silently ignore a host's locked native-tool policy on another CLI.
+        // Parity cannot override an explicit lock or a restricted run.
+        input.cliParity = input.cliParity === true && input.permissionMode === 'bypass' && input.nativeToolAccess !== false;
+        if ((input.nativeToolAccess !== undefined && !input.cliParity || Object.values(input.nativeCapabilities ?? {}).some(value => value === false)) && def.supportsNativeToolAccess !== true) {
+            return failBeforeSpawn({ runId: input.runId, code: 'NATIVE_TOOL_POLICY_UNSUPPORTED', message: 'This CLI has no native-tool policy and audit adapter. Choose a CLI with native-tool policy support.' });
+        }
+    }
+    function resolveRunOverlay({ input, def, imageDelivery }, _options = {}) {
         // Phase 8, hoisted deliberately above EVERY step that writes or sends the prompt. Four
         // different channels carry a prompt in this driver, and they do not all run at the same point:
         // the `promptViaFile` staging below writes its file BEFORE `buildArgs`, `buildArgs` itself runs
@@ -687,21 +740,18 @@ export function createAgentExecutor(requiredArgs, optionalArgs = {}) {
         // inside `buildRunArgs`) could only ever reach `buildArgs`, so the 17 defs that discard that
         // argument, plus grok-build's staged file, silently received no overlay at all.
         //
-        // `computeSystemPromptOverlay`'s third argument is the pre-staging `RuntimeContext`: it reads
-        // only `hasPriorAssistantTurn`, which `computeRuntimeContext` never populates from any of the
+        // `computeSystemPromptOverlay` reads no `RuntimeContext` at all: the one field it could use,
+        // `hasPriorAssistantTurn`, is never populated by `computeRuntimeContext` from any of the
         // staged-file/MCP inputs added to the fuller context built further down, so nothing between
-        // here and there can change the overlay this returns. Passing the narrower context makes that
-        // independence explicit rather than relying on the ordering staying lucky.
+        // here and there can change the overlay this returns. The pre-staging context below is kept
+        // for the overlay delivery's `resumeSessionId` only.
         //
         // `turnIndex` is a coarse 0/1 proxy (no exact turn counter exists on this driver) — sufficient
         // because every `PromptAugmenter.systemOverlay()` implementation this seam has today wants the
         // same overlay on every turn, not a first-turn-only one; a caller that needs finer-grained turn
         // numbering can track it itself and ignore this arg.
-        const preStagingRuntimeContext = computeRuntimeContext({ preparedPromptFile: null, preparedLogFile: null, mcpBridge: null }, {
-            ...(input.resumeSessionId === undefined ? {} : { resumeSessionId: input.resumeSessionId }),
-            ...(input.newSessionId === undefined ? {} : { newSessionId: input.newSessionId }),
-        });
-        const systemPromptOverlay = computeSystemPromptOverlay(promptAugmenter, def.id, preStagingRuntimeContext);
+        const preStagingRuntimeContext = computeRuntimeContext({ preparedPromptFile: null, preparedLogFile: null, mcpBridge: null }, sessionRuntimeContext(input, {}));
+        const systemPromptOverlay = computeSystemPromptOverlay(promptAugmenter, def.id);
         const overlayDelivery = resolveSystemPromptOverlayDelivery({
             defId: def.id,
             systemPromptDelivery: def.systemPromptDelivery,
@@ -711,30 +761,187 @@ export function createAgentExecutor(requiredArgs, optionalArgs = {}) {
             prompt: imageDelivery.prompt,
             resumeSessionId: preStagingRuntimeContext?.resumeSessionId,
         }, options.runtimeState ? { state: options.runtimeState } : {});
+        return { systemPromptOverlay, overlayDelivery };
+    }
+    async function resolveRunLaunch({ input, def }, _options = {}) {
         // The def's own declared env (e.g. claude's `ENABLE_TOOL_SEARCH=false`) is a default the run's
         // env can override. Detection already spawns with it (`detection.ts`); without this the run
         // spawn silently dropped it. Declared by the def itself, so it never widens SEC-001's allowlist.
-        const resolvedEnv = { ...(def.env ?? {}), ...resolveRunEnv({ input: input, hostEnv }) };
+        const defaults = { ...(def.env ?? {}) };
+        // Eager loading was cheap only for the isolated bridge. Let the user's CLI decide in parity.
+        if (input.cliParity)
+            delete defaults.ENABLE_TOOL_SEARCH;
+        const resolvedEnv = { ...defaults, ...resolveRunEnv({ input: input, hostEnv }) };
         const launch = await resolveLaunch({ input: { runId: input.runId, def, resolvedEnv }, deps: { resolveAgentLaunch: resolveAgentLaunchFn, failBeforeSpawn } });
         const spawnEnv = applyAgentLaunchEnvFn({ env: { ...resolvedEnv }, launch });
-        // Resolve from the launch environment before staging or sending any prompt. Pin the same
-        // concrete ID that the picker displays; an opaque native route cannot silently start a run.
+        return { launch, spawnEnv };
+    }
+    async function selectRunModel({ input, def, launch, spawnEnv }, _options = {}) {
+        // Locked runs pin the picker's concrete ID before any prompt is sent. Trusted parity keeps
+        // the CLI's own configured default and effort, without requiring discovery to succeed.
+        if (input.cliParity && input.model === 'default')
+            delete input.model;
         let modelCatalog;
-        try {
-            const selectModel = options.resolveModelForLaunch ?? ((input) => resolveModelForLaunch(input, options.runtimeState ? { deps: getRuntimeModelDiscoveryDeps({ state: options.runtimeState }) } : {}));
-            const selection = await selectModel({ def, context: {
-                    executable: launch.launchPath, cwd: input.cwd, env: spawnEnv,
-                    ...(input.model && input.model !== 'default' ? { model: input.model } : {}),
-                    ...(input.resumeSessionId ? { resumeSessionId: input.resumeSessionId } : {}),
-                    ...(input.settingSources ? { settingSources: input.settingSources } : {}),
-                    ...(input.settings ? { settings: input.settings } : {}),
-                } });
-            input.model = selection.model;
-            modelCatalog = selection.catalog;
-        }
-        catch {
-            return failBeforeSpawn({ runId: input.runId, code: 'AGENT_MODEL_UNRESOLVED', message: 'AgentExecutor: pick a concrete model; the starting model could not be resolved for this launch.' });
+        if (!input.cliParity) {
+            try {
+                const selectModel = options.resolveModelForLaunch ?? ((input) => resolveModelForLaunch(input, options.runtimeState ? { deps: getRuntimeModelDiscoveryDeps({ state: options.runtimeState }) } : {}));
+                const selection = await selectModel({ def, context: launchModelContext({ input, launch, spawnEnv }, {}) });
+                input.model = selection.model;
+                modelCatalog = selection.catalog;
+            }
+            catch {
+                return failBeforeSpawn({ runId: input.runId, code: 'AGENT_MODEL_UNRESOLVED', message: 'AgentExecutor: pick a concrete model; the starting model could not be resolved for this launch.' });
+            }
         }
+        return modelCatalog;
+    }
+    function bridgeProbeEntryForRun({ mcpBridge }, _options = {}) {
+        // probeMcpBridge itself strips the run credential and swaps in a diagnostic run id.
+        return mcpBridge?.kind === 'claude-mcp-json' && mcpJsonInjection?.probeOnFailure !== false
+            ? mcpBridge.serverEntry
+            : undefined;
+    }
+    function wireRunInput({ input, def, streamFormat, child, modelCatalog, cleanupStagedFiles, writtenMcpJsonPath, mcpBridge }, _options = {}) {
+        const formatForStdin = { streamFormat };
+        const stdinHandle = isStdinDrivenFormat(formatForStdin)
+            ? wireChildLifecycle({
+                ...(input.model ? { startingModel: input.model } : {}),
+                ...(modelCatalog ? { modelCatalog } : {}),
+                runId: input.runId,
+                def,
+                streamFormat: formatForStdin.streamFormat,
+                child,
+                lifecycle,
+                listProcessSnapshots: listProcessSnapshotsFn,
+                collectProcessTreePids: collectProcessTreePidsFn,
+                stopProcesses: stopProcessesFn,
+                onCleanupFailure: onCleanupFailureFn,
+                cleanupStagedFiles,
+                journal,
+                ...(options.delegatedResultCorrelation ? { delegatedResultCorrelation: options.delegatedResultCorrelation } : {}),
+                ...(options.stdoutJournalBlobs ? { stdoutJournalBlobs: options.stdoutJournalBlobs } : {}),
+                continuation,
+                classifyFailure,
+                bufferedStdoutMaxBytes,
+                expectsJiniBridge: writtenMcpJsonPath !== undefined,
+                bridgeProbeEntry: bridgeProbeEntryForRun({ mcpBridge }, {}),
+                probeMcpBridge: options.probeMcpBridge ?? probeMcpBridge,
+            })
+            : null;
+        // Registered with the lifecycle wiring above, before the spawn-confirmation await, so a child
+        // that closes immediately never leaves a stale entry behind.
+        const runId = input.runId;
+        liveRunInputs.set(runId, stdinHandle ? stdinHandle.sendUserMessage : async () => 'unsupported');
+        child.once('close', () => liveRunInputs.delete(runId));
+        return stdinHandle;
+    }
+    async function dispatchAcpPrompt({ input, def, child, modelCatalog, cleanupStagedFiles, releaseStagedResources, mcpBridge, overlayDelivery }, _options = {}) {
+        await runAcpDispatch({ input: {
+                runId: input.runId,
+                agentId: def.id,
+                child,
+                // `overlayDelivery.promptPrefix` applied to `input.prompt`, NOT `overlayDelivery.prompt`:
+                // this call site deliberately sends the raw input prompt rather than the image-delivery
+                // rewrite (see `resolveImageDeliveryAndArgvBudget`'s call site above — an ACP def delivers
+                // images natively and must never also get `'prompt-path'`'s appended paths), and the prefix
+                // is the part of the overlay decision that applies to whatever prompt text a transport was
+                // already sending. `''` for `reasonix` (env-var) and any resumed ACP session, so those keep
+                // sending byte-identical text and never receive the overlay twice.
+                prompt: `${overlayDelivery.promptPrefix}${input.prompt}`,
+                cwd: input.cwd,
+                permissionMode: input.permissionMode,
+                cliParity: input.cliParity,
+                model: input.model,
+                ...(modelCatalog ? { modelCatalog } : {}),
+                imagePaths: input.imagePaths ?? [],
+                envFormat: def.acpMcpEnvFormat,
+                mcpBridge,
+            }, deps: {
+                lifecycle,
+                attachAcpSession: attachAcpSessionFn,
+                onPermissionRequest: options.acpPermissionHandler,
+                listProcessSnapshots: listProcessSnapshotsFn,
+                collectProcessTreePids: collectProcessTreePidsFn,
+                stopProcesses: stopProcessesFn,
+                onCleanupFailure: onCleanupFailureFn,
+                cleanupStagedFiles,
+                journal,
+                classifyFailure,
+                releaseStagedResources,
+                failBeforeSpawn,
+            } });
+    }
+    async function dispatchPiPrompt({ input, def, child, modelCatalog, cleanupStagedFiles, releaseStagedResources, overlayDelivery }, _options = {}) {
+        await runPiRpcDispatch({ input: {
+                runId: input.runId,
+                agentId: def.id,
+                child,
+                // Same reasoning as the ACP call site above. `pi` declares an `'append-flag'` strategy,
+                // so its prefix is `''` and this stays byte-identical to the raw prompt — the overlay
+                // rides `--append-system-prompt` instead, exactly once.
+                prompt: `${overlayDelivery.promptPrefix}${input.prompt}`,
+                cwd: input.cwd,
+                model: input.model,
+                ...(modelCatalog ? { modelCatalog } : {}),
+                imagePaths: input.imagePaths ?? [],
+                uploadRoot: input.uploadRoot,
+            }, deps: {
+                lifecycle,
+                attachPiRpcSession: attachPiRpcSessionFn,
+                listProcessSnapshots: listProcessSnapshotsFn,
+                collectProcessTreePids: collectProcessTreePidsFn,
+                stopProcesses: stopProcessesFn,
+                onCleanupFailure: onCleanupFailureFn,
+                cleanupStagedFiles,
+                journal,
+                classifyFailure,
+                releaseStagedResources,
+                failBeforeSpawn,
+            } });
+    }
+    function dispatchStdinPrompt({ input, def, child, overlayDelivery, imageDelivery, stdinHandle }, _options = {}) {
+        // The overlay reaches stdin only for a def that declares stdin as its prompt transport. The
+        // four `plain`-format defs that do not (`aider`/`antigravity`/`deepseek` put the prompt in
+        // argv, `grok-build` in a staged file) are still written to and closed here exactly as before,
+        // because this driver always spawns with `stdio: ['pipe','pipe','pipe']` and their CLIs need
+        // the EOF — but their prompt already carried the overlay through argv or the staged file, so
+        // sending the overlaid text here too would deliver it twice. This is the one place the
+        // resolver's own `''`-prefix rule is not sufficient on its own: those four defs are on the
+        // fallback strategy, so their prefix is genuinely non-empty; what makes stdin the wrong
+        // channel for them is the def's declared transport, not the strategy.
+        const stdinPrompt = def.promptViaStdin === true ? overlayDelivery.prompt : imageDelivery.prompt;
+        if (input.imageContents !== undefined)
+            stdinHandle.imageContents = input.imageContents;
+        writePromptToStdin(def, child, stdinPrompt, stdinHandle);
+    }
+    /**
+     * `AgentExecutor.run()` — see that interface method's own doc for the
+     * public contract. Implementation note on shape: every guard below
+     * returns `failBeforeSpawn(...)` directly (a `Promise<never>`, valid
+     * wherever `Promise<void>` is expected) rather than `await`-then-`return`,
+     * so each failure path reads as a single, obviously-terminal statement.
+     * @param input - `{runId, agentId, prompt, cwd, model?, reasoning?, imagePaths?, extraAllowedDirs?, uploadRoot?, env?}` — `runId` must already be `lifecycle.start()`-ed.
+     * @throws {@link AgentExecutorError} — see index.ts module doc's Invariant; never a bare `Error`.
+     * @complexity O(1) setup (registry lookup, launch resolution, one spawn call); steady-state cost thereafter belongs to {@link wireChildLifecycle}.
+     * @overallScore 100/100
+     */
+    async function run(requiredArgs, optionalArgs = {}) {
+        const { input, def, streamFormat } = await prepareRunContext({ requiredArgs, optionalArgs }, {});
+        // Computed once, before anything downstream ever looks at "the prompt" or "the allowed
+        // dirs" — a no-op (`{prompt: input.prompt, extraAllowedDirs: input.extraAllowedDirs}`,
+        // literally unchanged) unless `def.imageDelivery === 'prompt-path'` AND `input.imagePaths`
+        // is non-empty, so this can never affect a 'native'-delivery def (ACP, pi-rpc, qoder) or a
+        // run with no attachments. See `image-prompt-delivery.ts`'s own doc for the full mechanism;
+        // every use of `input.prompt`/`input.extraAllowedDirs` below that reflects what the CLI
+        // actually receives reads `imageDelivery.*` instead — the two ACP/pi-rpc `wire*Lifecycle`
+        // calls further down deliberately keep reading `input.prompt` verbatim, since those two
+        // defs' own native protocol already delivers the image and must never also get this
+        // treatment (the double-delivery hazard this mechanism exists to avoid).
+        await enforceNativeToolPolicy({ input, def }, {});
+        const imageDelivery = await resolveImageDeliveryAndArgvBudget({ input: { runId: input.runId, def, prompt: input.prompt, imagePaths: input.imagePaths, extraAllowedDirs: input.extraAllowedDirs }, deps: { failBeforeSpawn } });
+        const { systemPromptOverlay, overlayDelivery } = resolveRunOverlay({ input, def, imageDelivery }, {});
+        const { launch, spawnEnv } = await resolveRunLaunch({ input, def }, {});
+        const modelCatalog = await selectRunModel({ input, def, launch, spawnEnv }, {});
         // Fill the def's `--help` capability gate before `buildArgs` reads it. Without this, only a
         // host that happened to call `detectAgents` in THIS process ever had the gate filled, so e.g.
         // `claude` never got `--include-partial-messages` (no streamed text). Probes once per binary;
@@ -822,10 +1029,7 @@ export function createAgentExecutor(requiredArgs, optionalArgs = {}) {
         // the five mechanisms ends up carrying it. `null` for an unconfigured host or a def declaring
         // no strategy — see `buildMcpBridgeDelivery`'s doc.
         const mcpBridge = await resolveMcpBridgeForRun({ input: { runId: input.runId, cwd: input.cwd, def }, deps: { mcpJsonInjection, cleanupStagedFiles, failBeforeSpawn } });
-        const runtimeContext = computeRuntimeContext({ preparedPromptFile: preparedPromptFile, preparedLogFile: preparedLogFile, mcpBridge: mcpBridge }, {
-            ...(input.resumeSessionId === undefined ? {} : { resumeSessionId: input.resumeSessionId }),
-            ...(input.newSessionId === undefined ? {} : { newSessionId: input.newSessionId }),
-        });
+        const runtimeContext = computeRuntimeContext({ preparedPromptFile: preparedPromptFile, preparedLogFile: preparedLogFile, mcpBridge: mcpBridge }, sessionRuntimeContext(input, {}));
         // A `runtimeLock` def's buildArgs mutates process-global state its own CLI reads back at
         // startup, so the mutex must be held from before buildArgs until the spawned child has
         // demonstrably consumed it — see `RuntimeLock`'s own doc for the concrete race. Undefined for
@@ -862,13 +1066,13 @@ export function createAgentExecutor(requiredArgs, optionalArgs = {}) {
         // points at a real file. Skipped entirely for the other four mechanisms and whenever no bridge
         // was resolved at all. `writtenMcpJsonPath` is set only once the write actually happens, so
         // `cleanupStagedFiles` knows there is a live-token file to remove afterward.
-        writtenMcpJsonPath = await writeMcpJsonIfNeeded({ input: { runId: input.runId, cwd: input.cwd, def, mcpBridge }, deps: { mcpJsonInjection, releaseStagedResources, failBeforeSpawn } });
+        writtenMcpJsonPath = await writeMcpJsonIfNeeded({ input: { runId: input.runId, cwd: input.cwd, nativeToolAccess: input.nativeToolAccess, ...nativeCapabilityInput({ input }, {}), def, mcpBridge }, deps: { mcpJsonInjection, releaseStagedResources, failBeforeSpawn } });
         // Mechanism 5 of 5's one effect — stage this run's scratch `CODEX_HOME` directory. Skipped
         // entirely for the other four mechanisms and whenever no bridge was resolved at all.
         // `codex.ts`'s `buildArgs` needs no argv change for this (CODEX_HOME is an env var, not a flag),
         // so — unlike the `.mcp.json` staging above — this can run after `buildArgs` with no ordering
         // constraint of its own; it is placed here only to keep the two staging steps adjacent.
-        preparedCodexHome = await prepareCodexHomeIfNeeded({ input: { runId: input.runId, def, mcpBridge }, deps: { mcpJsonInjection, hostEnv, releaseStagedResources, failBeforeSpawn } });
+        preparedCodexHome = await prepareCodexHomeIfNeeded({ input: { runId: input.runId, nativeToolAccess: input.nativeToolAccess, ...nativeCapabilityInput({ input }, {}), def, mcpBridge }, deps: { mcpJsonInjection, hostEnv: input.cliParity ? spawnEnv : hostEnv, releaseStagedResources, failBeforeSpawn } });
         // Finding 1 of SEC-assistant-env-isolation-2026-09-07's one effect — stage this run's scratch
         // `CLAUDE_CONFIG_DIR` directory. Unconditional for a `claude`-id run (unlike CODEX_HOME above,
         // this does not depend on `mcpJsonInjection` being configured at all — see
@@ -894,14 +1098,9 @@ export function createAgentExecutor(requiredArgs, optionalArgs = {}) {
         // `McpBridgeDelivery`'s `'codex-toml'` variant doc for why it cannot be pre-computed the way
         // `'claude-mcp-json'`'s deterministic path is). Nothing between the old, earlier call site and
         // here ever read `childEnv`, so moving the call cost nothing.
-        const childEnv = computeChildEnv({ spawnEnv: spawnEnv, mcpBridge: mcpBridge }, {
-            ...(preparedCodexHome === null ? {} : { codexHomeDir: preparedCodexHome.path }),
-            systemPromptEnvOverrides,
-            ...(preparedSystemPromptOverlayFile && def.systemPromptDelivery?.strategy === 'config-instructions-file'
-                ? { stagedInstructionsFile: { varName: def.systemPromptDelivery.varName, path: preparedSystemPromptOverlayFile.path } }
-                : {}),
-            ...(preparedClaudeConfigDir === null ? {} : { claudeConfigDir: preparedClaudeConfigDir.path }),
-        });
+        const childEnv = computeChildEnv({ spawnEnv, mcpBridge }, stagedChildEnvOptions({
+            def, preparedCodexHome, preparedClaudeConfigDir, preparedSystemPromptOverlayFile, systemPromptEnvOverrides,
+        }, {}));
         // Post-buildArgs guard for argv-bound defs whose resolved binary is a
         // Windows .cmd/.bat shim or a direct .exe: a prompt under the raw byte
         // budget can still expand past CreateProcess's command-line cap once
@@ -924,38 +1123,8 @@ export function createAgentExecutor(requiredArgs, optionalArgs = {}) {
         // grandchild inheriting them can delay arbitrarily). A spawn that never produced a process at
         // all emits no `'exit'`, and is covered instead by `releaseStagedResources` on the reject path.
         child.once('exit', releaseRuntimeLock);
-        const formatForStdin = { streamFormat };
-        const stdinHandle = isStdinDrivenFormat(formatForStdin)
-            ? wireChildLifecycle({
-                startingModel: input.model,
-                modelCatalog,
-                runId: input.runId,
-                def,
-                streamFormat: formatForStdin.streamFormat,
-                child,
-                lifecycle,
-                listProcessSnapshots: listProcessSnapshotsFn,
-                collectProcessTreePids: collectProcessTreePidsFn,
-                stopProcesses: stopProcessesFn,
-                onCleanupFailure: onCleanupFailureFn,
-                cleanupStagedFiles,
-                journal,
-                continuation,
-                classifyFailure,
-                bufferedStdoutMaxBytes,
-                expectsJiniBridge: writtenMcpJsonPath !== undefined,
-                // probeMcpBridge itself strips the run credential and swaps in a diagnostic run id.
-                bridgeProbeEntry: mcpBridge?.kind === 'claude-mcp-json' && mcpJsonInjection?.probeOnFailure !== false
-                    ? mcpBridge.serverEntry
-                    : undefined,
-                probeMcpBridge: options.probeMcpBridge ?? probeMcpBridge,
-            })
-            : null;
-        // Registered with the lifecycle wiring above, before the spawn-confirmation await, so a child
-        // that closes immediately never leaves a stale entry behind.
+        const stdinHandle = wireRunInput({ input, def, streamFormat, child, modelCatalog, cleanupStagedFiles, writtenMcpJsonPath, mcpBridge }, {});
         const runId = input.runId;
-        liveRunInputs.set(runId, stdinHandle ? stdinHandle.sendUserMessage : async () => 'unsupported');
-        child.once('close', () => liveRunInputs.delete(runId));
         try {
             await confirmChildSpawned({ input: { runId: input.runId, def, child }, deps: { releaseStagedResources, failBeforeSpawn } });
         }
@@ -970,83 +1139,12 @@ export function createAgentExecutor(requiredArgs, optionalArgs = {}) {
         // worse than releasing early (see `RuntimeLockHold.waitForHandoff`'s own doc).
         armHandoffWatcher({ runtimeLockHold: runtimeLockHold, handoffInput: { logFilePath: preparedLogFile?.path, model: selectedModel, processExited: processExitedController.signal }, release: releaseRuntimeLock });
         if (streamFormat === 'acp-json-rpc') {
-            await runAcpDispatch({ input: {
-                    runId: input.runId,
-                    agentId: def.id,
-                    child,
-                    // `overlayDelivery.promptPrefix` applied to `input.prompt`, NOT `overlayDelivery.prompt`:
-                    // this call site deliberately sends the raw input prompt rather than the image-delivery
-                    // rewrite (see `resolveImageDeliveryAndArgvBudget`'s call site above — an ACP def delivers
-                    // images natively and must never also get `'prompt-path'`'s appended paths), and the prefix
-                    // is the part of the overlay decision that applies to whatever prompt text a transport was
-                    // already sending. `''` for `reasonix` (env-var) and any resumed ACP session, so those keep
-                    // sending byte-identical text and never receive the overlay twice.
-                    prompt: `${overlayDelivery.promptPrefix}${input.prompt}`,
-                    cwd: input.cwd,
-                    permissionMode: input.permissionMode,
-                    model: input.model,
-                    modelCatalog,
-                    imagePaths: input.imagePaths ?? [],
-                    envFormat: def.acpMcpEnvFormat,
-                    mcpBridge,
-                }, deps: {
-                    lifecycle,
-                    attachAcpSession: attachAcpSessionFn,
-                    onPermissionRequest: options.acpPermissionHandler,
-                    listProcessSnapshots: listProcessSnapshotsFn,
-                    collectProcessTreePids: collectProcessTreePidsFn,
-                    stopProcesses: stopProcessesFn,
-                    onCleanupFailure: onCleanupFailureFn,
-                    cleanupStagedFiles,
-                    journal,
-                    classifyFailure,
-                    releaseStagedResources,
-                    failBeforeSpawn,
-                } });
-            return;
+            return dispatchAcpPrompt({ input, def, child, modelCatalog, cleanupStagedFiles, releaseStagedResources, mcpBridge, overlayDelivery }, {});
         }
         if (streamFormat === 'pi-rpc') {
-            await runPiRpcDispatch({ input: {
-                    runId: input.runId,
-                    agentId: def.id,
-                    child,
-                    // Same reasoning as the ACP call site above. `pi` declares an `'append-flag'` strategy,
-                    // so its prefix is `''` and this stays byte-identical to the raw prompt — the overlay
-                    // rides `--append-system-prompt` instead, exactly once.
-                    prompt: `${overlayDelivery.promptPrefix}${input.prompt}`,
-                    cwd: input.cwd,
-                    model: input.model,
-                    modelCatalog,
-                    imagePaths: input.imagePaths ?? [],
-                    uploadRoot: input.uploadRoot,
-                }, deps: {
-                    lifecycle,
-                    attachPiRpcSession: attachPiRpcSessionFn,
-                    listProcessSnapshots: listProcessSnapshotsFn,
-                    collectProcessTreePids: collectProcessTreePidsFn,
-                    stopProcesses: stopProcessesFn,
-                    onCleanupFailure: onCleanupFailureFn,
-                    cleanupStagedFiles,
-                    journal,
-                    classifyFailure,
-                    releaseStagedResources,
-                    failBeforeSpawn,
-                } });
-            return;
+            return dispatchPiPrompt({ input, def, child, modelCatalog, cleanupStagedFiles, releaseStagedResources, overlayDelivery }, {});
         }
-        // The overlay reaches stdin only for a def that declares stdin as its prompt transport. The
-        // four `plain`-format defs that do not (`aider`/`antigravity`/`deepseek` put the prompt in
-        // argv, `grok-build` in a staged file) are still written to and closed here exactly as before,
-        // because this driver always spawns with `stdio: ['pipe','pipe','pipe']` and their CLIs need
-        // the EOF — but their prompt already carried the overlay through argv or the staged file, so
-        // sending the overlaid text here too would deliver it twice. This is the one place the
-        // resolver's own `''`-prefix rule is not sufficient on its own: those four defs are on the
-        // fallback strategy, so their prefix is genuinely non-empty; what makes stdin the wrong
-        // channel for them is the def's declared transport, not the strategy.
-        const stdinPrompt = def.promptViaStdin === true ? overlayDelivery.prompt : imageDelivery.prompt;
-        if (input.imageContents !== undefined)
-            stdinHandle.imageContents = input.imageContents;
-        writePromptToStdin(def, child, stdinPrompt, stdinHandle);
+        dispatchStdinPrompt({ input, def, child, overlayDelivery, imageDelivery, stdinHandle }, {});
     }
     return { run, sendUserMessage };
 }