@jini-ai/daemon 0.3.8 → 0.5.0

package/dist/agent-executor.js

@@ -81,10 +81,10 @@
  * byte-identical to pre-gap-4 behavior — every `'failed'` outcome
  * resumable:false). OD's ~20-vendor-CLI text-matching failure classifier was
  * deliberately never ported (see `run/core/failure-taxonomy.ts`'s own doc and
- * `source-map.md`). The real zero-config classifier lives in `@jini-ai/daemon`'s
+ * `archived provenance ledger`). The real zero-config classifier lives in `@jini-ai/daemon`'s
  * `run/core/retry.ts` (`resumableFromProcessExit`/`classifyProcessExitFailure`)
  * and is wired in by `@jini-ai/server`'s `createLocalNodeDaemon` — see that
- * package's own source-map.md, and `run/core/retry.ts`'s own doc for the
+ * package's own archived provenance ledger, and `run/core/retry.ts`'s own doc for the
  * classification policy and its 2026-07-22 merge-time reconciliation against
  * a second, independently-built (and rejected) classifier that once lived in
  * this module.
@@ -118,7 +118,8 @@ const SUPPORTED_STREAM_FORMATS = [
  * @complexity O(1) — fixed membership check.
  * @overallScore 100/100
  */
-export function isSupportedStreamFormat(value) {
+export function isSupportedStreamFormat(args) {
+    const { value } = args;
     return SUPPORTED_STREAM_FORMATS.includes(value);
 }
 /**
@@ -142,14 +143,15 @@ export function isSupportedStreamFormat(value) {
  * @complexity O(1) — fixed field checks.
  * @overallScore 100/100
  */
-export function assessAgentExecutorCompatibility(def) {
-    const streamFormat = def.streamFormat;
-    if (!isSupportedStreamFormat(streamFormat)) {
+export function assessAgentExecutorCompatibility({ def }) {
+    const format = { value: def.streamFormat };
+    if (!isSupportedStreamFormat(format)) {
         return {
             supported: false,
-            reason: `AgentExecutor: agent "${def.id}" has streamFormat "${streamFormat}", which is not implemented in v1 — only ${SUPPORTED_STREAM_FORMATS.join(', ')} are supported`,
+            reason: `AgentExecutor: agent "${def.id}" has streamFormat "${format.value}", which is not implemented in v1 — only ${SUPPORTED_STREAM_FORMATS.join(', ')} are supported`,
         };
     }
+    const streamFormat = format.value;
     if (streamFormat !== 'acp-json-rpc' &&
         def.promptViaStdin !== true &&
         def.promptViaFile !== true &&
@@ -171,8 +173,8 @@ export function assessAgentExecutorCompatibility(def) {
  * @complexity O(1).
  * @overallScore 100/100
  */
-export function isAgentExecutorSupported(def) {
-    return assessAgentExecutorCompatibility(def).supported;
+export function isAgentExecutorSupported({ def }) {
+    return assessAgentExecutorCompatibility({ def: def }).supported;
 }
 /**
  * Selects and constructs the real stream-parser handler for a supported
@@ -194,13 +196,13 @@ export function isAgentExecutorSupported(def) {
 function createStreamHandlerForDef(def, streamFormat, onEvent) {
     switch (streamFormat) {
         case 'claude-stream-json':
-            return createClaudeStreamHandler(onEvent);
+            return createClaudeStreamHandler({ onEvent: onEvent });
         case 'copilot-stream-json':
-            return createCopilotStreamHandler(onEvent);
+            return createCopilotStreamHandler({ onEvent: onEvent });
         case 'qoder-stream-json':
-            return createQoderStreamHandler(onEvent);
+            return createQoderStreamHandler({ onEvent: onEvent });
         case 'json-event-stream':
-            return createJsonEventStreamHandler(def.eventParser ?? '', onEvent);
+            return createJsonEventStreamHandler({ kind: def.eventParser ?? '', onEvent: onEvent });
     }
 }
 function isRecord(value) {
@@ -224,7 +226,7 @@ function asOptionalNumber(value) {
  * original "omit the whole `usage` field rather than emit an empty object" behavior.
  * @complexity O(1).
  */
-export function extractUsageTokens(rawUsage) {
+export function extractUsageTokens({ rawUsage }) {
     if (!rawUsage)
         return undefined;
     const inputTokens = asOptionalNumber(rawUsage.input_tokens);
@@ -250,7 +252,7 @@ export function extractUsageTokens(rawUsage) {
  */
 function translateUsagePayload(rawEvent) {
     const rawUsage = isRecord(rawEvent.usage) ? rawEvent.usage : undefined;
-    const usage = extractUsageTokens(rawUsage);
+    const usage = extractUsageTokens({ rawUsage: rawUsage });
     const costUsd = asOptionalNumber(rawEvent.costUsd);
     const durationMs = asOptionalNumber(rawEvent.durationMs);
     return {
@@ -260,7 +262,7 @@ function translateUsagePayload(rawEvent) {
         ...(durationMs !== undefined ? { durationMs } : {}),
     };
 }
-export function translateStatusEvent(rawEvent) {
+export function translateStatusEvent({ rawEvent }) {
     const model = asOptionalString(rawEvent.model);
     const ttftMs = asOptionalNumber(rawEvent.ttftMs);
     const detail = asOptionalString(rawEvent.detail);
@@ -308,7 +310,7 @@ function translateToolInputDeltaEvent(rawEvent) {
         },
     };
 }
-export function translateToolResultEvent(rawEvent) {
+export function translateToolResultEvent({ rawEvent }) {
     const isError = typeof rawEvent.isError === 'boolean' ? rawEvent.isError : undefined;
     return {
         kind: 'agent',
@@ -326,7 +328,7 @@ function translateUsageEvent(rawEvent) {
 function translateRawEvent(rawEvent) {
     return { kind: 'agent', payload: { type: 'raw', line: asString(rawEvent.line) } };
 }
-export function translateErrorEvent(rawEvent) {
+export function translateErrorEvent({ rawEvent }) {
     const code = asOptionalString(rawEvent.code);
     const message = asString(rawEvent.message, 'Unknown agent error');
     return {
@@ -334,7 +336,7 @@ export function translateErrorEvent(rawEvent) {
         payload: { message, ...(code !== undefined ? { error: { code, message } } : {}) },
     };
 }
-export function translateTurnEndEvent(rawEvent) {
+export function translateTurnEndEvent({ rawEvent }) {
     // Claude-specific per-turn boundary. Not forwarded as an 'agent'
     // event (no RunAgentPayload variant represents it) — run() reacts to
     // it directly to close stdin (or, for gap 3, decide whether to inject
@@ -350,17 +352,17 @@ export function translateTurnEndEvent(rawEvent) {
  * `translateAgentRuntimeEvent` itself is just a lookup plus the two upfront guards.
  */
 const EVENT_TYPE_TRANSLATORS = {
-    status: translateStatusEvent,
+    status: rawEvent => translateStatusEvent({ rawEvent }),
     text_delta: translateTextDeltaEvent,
     thinking_start: translateThinkingStartEvent,
     thinking_delta: translateThinkingDeltaEvent,
     tool_use: translateToolUseEvent,
     tool_input_delta: translateToolInputDeltaEvent,
-    tool_result: translateToolResultEvent,
+    tool_result: rawEvent => translateToolResultEvent({ rawEvent }),
     usage: translateUsageEvent,
     raw: translateRawEvent,
-    error: translateErrorEvent,
-    turn_end: translateTurnEndEvent,
+    error: rawEvent => translateErrorEvent({ rawEvent }),
+    turn_end: rawEvent => translateTurnEndEvent({ rawEvent }),
 };
 /**
  * Narrows one parser-emitted `{type, ...}` record into this engine's
@@ -384,7 +386,7 @@ const EVENT_TYPE_TRANSLATORS = {
  * @complexity O(1) — one table lookup, no iteration.
  * @overallScore 100/100
  */
-export function translateAgentRuntimeEvent(rawEvent) {
+export function translateAgentRuntimeEvent({ rawEvent }) {
     if (!isRecord(rawEvent) || typeof rawEvent.type !== 'string') {
         return { kind: 'ignored' };
     }
@@ -394,7 +396,7 @@ export function translateAgentRuntimeEvent(rawEvent) {
 /** Thrown by `AgentExecutor.run()` on every failure path — never a bare `Error`, so callers can branch on `.code` instead of parsing `.message`. */
 export class AgentExecutorError extends Error {
     code;
-    constructor(code, message) {
+    constructor({ code, message }) {
         super(message);
         this.name = 'AgentExecutorError';
         this.code = code;
@@ -435,7 +437,8 @@ const BASELINE_AGENT_ENV_KEYS = [
     // run /login" despite real credentials existing on disk/keychain. Confirmed by bisection against
     // a real authenticated `claude` install: `BASELINE_AGENT_ENV_KEYS` alone fails, adding back every
     // `CLAUDE_CODE_*`/`CLAUDECODE` var still fails, `LOGNAME`/`SSH_AUTH_SOCK` alone still fail, but
-    // `USER` alone flips it to success. See tovu-learnings.md §9 for the full investigation trail.
+    // `USER` alone flips it to success. Login lookup requires the user identity
+    // as well as the home directory.
     'USER',
     'SystemRoot', 'windir', 'ComSpec', 'PATHEXT', // Windows-only; harmless no-ops elsewhere
 ];
@@ -485,13 +488,13 @@ async function terminateChildTree(deps, child) {
     if (child.pid == null)
         return;
     const processes = await deps.listProcessSnapshots();
-    const pids = deps.collectProcessTreePids(processes, [child.pid]);
-    await deps.stopProcesses(pids);
+    const pids = deps.collectProcessTreePids({ processes, rootPids: [child.pid] });
+    await deps.stopProcesses({ pids });
 }
 /** Default sink when a host does not supply `onCleanupFailure`: still observable, never silent. Redacted per SEC-007 (a spawn/permission error can embed paths/host detail). */
 function defaultCleanupFailureSink(context) {
     // eslint-disable-next-line no-console
-    console.error(`[@jini-ai/daemon] agent-executor: process-tree cleanup failed for run "${context.runId}" (${context.phase}, pid=${context.pid})`, redactSecrets(errorMessage(context.error)));
+    console.error(`[@jini-ai/daemon] agent-executor: process-tree cleanup failed for run "${context.runId}" (${context.phase}, pid=${context.pid})`, redactSecrets({ input: errorMessage(context.error) }));
 }
 /**
  * Reports a contained post-close failure through the host's sink, absorbing a throwing sink.
@@ -599,6 +602,31 @@ function receivedJournalEntry(channel, content) {
     return { content, provenance: { source: 'agent', channel }, trust: 'untrusted' };
 }
 const JINI_MCP_SERVER_KEY = 'jini';
+/** The run-error code a run gets when its CLI reports the injected `jini` bridge as anything but connected. */
+export const MCP_BRIDGE_UNAVAILABLE = 'MCP_BRIDGE_UNAVAILABLE';
+/**
+ * Judges a CLI's startup report of the injected bridge. Returns the bridge's status (`'missing'`
+ * when the list omits it) when it is not `'connected'`, and `undefined` when it is connected or
+ * when `rawEvent` is not an init status carrying an MCP server list (nothing to judge).
+ *
+ * `'pending'` counts as a failure on purpose: the CLI decides which MCP tools a session has at
+ * startup, so a bridge that is not connected by then never joins this run.
+ * @param rawEvent - One parsed stream event, as `@jini-ai/agent-runtime`'s parser emits it.
+ * @complexity O(n) in the number of reported servers.
+ */
+export function unavailableJiniBridgeStatus({ rawEvent }) {
+    if (!isRecord(rawEvent) || rawEvent.type !== 'status' || rawEvent.label !== 'initializing')
+        return undefined;
+    if (!Array.isArray(rawEvent.mcpServers))
+        return undefined;
+    const bridge = rawEvent.mcpServers.find((server) => isRecord(server) && server.name === JINI_MCP_SERVER_KEY);
+    const status = isRecord(bridge) ? String(bridge.status) : 'missing';
+    return status === 'connected' ? undefined : status;
+}
+/** The user-readable reason a run stopped because its bridge did not connect. */
+function bridgeUnavailableMessage(status) {
+    return `The assistant's tools did not load (MCP bridge "${JINI_MCP_SERVER_KEY}" status: ${status}). The run was stopped instead of continuing without them.`;
+}
 /**
  * Builds this run's `mcpServers.jini` entry — pure and synchronous, so every field mapping is
  * directly assertable without touching the filesystem. The credential arrives already resolved:
@@ -606,17 +634,19 @@ const JINI_MCP_SERVER_KEY = 'jini';
  * `writeMcpJsonForRun`'s job, which keeps the effect out of this function.
  *
  * @param runId - The run this entry scopes its child to.
- * @param options - `command`/`args`/`daemonUrl` from the host's injection options.
+ * @param options - `command`/`args`/`daemonUrl`/`env` from the host's injection options.
  * @param credential - The already-resolved bearer token, or `undefined` to omit `JINI_DAEMON_TOKEN`
  * entirely. Omitting produces byte-identical output to before this parameter existed.
  * @complexity O(1).
  * @overallScore 100/100
  */
-export function buildMcpJsonServerEntry(runId, options, credential) {
+export function buildMcpJsonServerEntry({ runId, options }, { credential } = {}) {
+    const hostEnv = Object.entries(options.env ?? {}).filter(([key]) => !key.startsWith('JINI_'));
     return {
         command: options.command,
         args: options.args !== undefined ? [...options.args] : [],
         env: {
+            ...Object.fromEntries(hostEnv),
             JINI_RUN_ID: runId,
             JINI_DAEMON_URL: options.daemonUrl,
             ...(credential !== undefined ? { JINI_DAEMON_TOKEN: credential } : {}),
@@ -634,7 +664,7 @@ export function buildMcpJsonServerEntry(runId, options, credential) {
  * @complexity O(1) plus `JSON.parse`/`JSON.stringify`'s own cost on a small config file.
  * @overallScore 100/100
  */
-export function mergeMcpJsonContent(existingRaw, serverEntry) {
+export function mergeMcpJsonContent({ existingRaw, serverEntry }) {
     let doc = {};
     if (existingRaw !== undefined) {
         try {
@@ -671,7 +701,7 @@ export function mergeMcpJsonContent(existingRaw, serverEntry) {
  * @complexity O(1).
  * @overallScore 100/100
  */
-export function buildAcpMcpBridgeServers(entry) {
+export function buildAcpMcpBridgeServers({ entry }) {
     return [
         {
             type: 'stdio',
@@ -719,7 +749,7 @@ const ENV_CONTENT_VAR_BY_STRATEGY = {
  * @complexity O(1) plus `JSON.parse`/`JSON.stringify` over a small config document.
  * @overallScore 100/100
  */
-export function mergeEnvContentMcpConfig(existingRaw, entry) {
+export function mergeEnvContentMcpConfig({ existingRaw, entry }) {
     let doc = {};
     if (existingRaw !== undefined && existingRaw.length > 0) {
         try {
@@ -780,7 +810,7 @@ export function mergeEnvContentMcpConfig(existingRaw, entry) {
  * @complexity O(1) plus `JSON.parse`/`JSON.stringify` over a small config document.
  * @overallScore 100/100
  */
-export function mergeEnvContentInstructions(existingRaw, instructionsFilePath) {
+export function mergeEnvContentInstructions({ existingRaw, instructionsFilePath }) {
     let doc = {};
     if (existingRaw !== undefined && existingRaw.length > 0) {
         try {
@@ -825,6 +855,10 @@ function escapeTomlBasicString(value) {
 function tomlString(value) {
     return `"${escapeTomlBasicString(value)}"`;
 }
+/** A TOML key: bare when TOML allows it, quoted otherwise — host-supplied bridge env names are not guaranteed bare-safe. */
+function tomlKey(key) {
+    return /^[A-Za-z0-9_-]+$/.test(key) ? key : tomlString(key);
+}
 /**
  * Codex's per-tool deadline for the Jini bridge, in seconds: `@jini-ai/mcp`'s
  * `DEFAULT_DELEGATED_TOOL_TIMEOUT_MS` (6 min, mirrored because this package does not depend on
@@ -843,19 +877,19 @@ const CODEX_TOOL_TIMEOUT_SEC = 6 * 60 + 40;
  * Confirmed against a real installed Codex CLI (0.151.0), not assumed from docs: round-tripping
  * `codex mcp add <name> --env K=V -- <cmd> <args>` against a scratch `CODEX_HOME` and reading back
  * `config.toml` produced exactly this shape (`command`/`args` as TOML strings/array in the main
- * table, env vars in a nested `.env` table) — see `source-map.md` for the transcript.
+ * table, env vars in a nested `.env` table) — see `archived provenance ledger` for the transcript.
  * @param entry - The shared bridge entry from {@link buildMcpJsonServerEntry}.
  * @returns A TOML fragment with no leading/trailing blank-line padding — {@link buildCodexHomeConfigToml} owns spacing when combining it with existing content.
  * @complexity O(n) in the number of argv/env entries.
  * @overallScore 100/100
  */
-export function buildCodexMcpServerToml(entry) {
+export function buildCodexMcpServerToml({ entry }) {
     const argsLiteral = entry.args.map(tomlString).join(', ');
     const serverTable = `[mcp_servers.${JINI_MCP_SERVER_KEY}]\ncommand = ${tomlString(entry.command)}\nargs = [${argsLiteral}]\n` +
         `tool_timeout_sec = ${CODEX_TOOL_TIMEOUT_SEC}\n`;
     const envLines = Object.entries(entry.env)
         .filter((pair) => typeof pair[1] === 'string')
-        .map(([key, value]) => `${key} = ${tomlString(value)}`);
+        .map(([key, value]) => `${tomlKey(key)} = ${tomlString(value)}`);
     if (envLines.length === 0)
         return serverTable;
     return `${serverTable}\n[mcp_servers.${JINI_MCP_SERVER_KEY}.env]\n${envLines.join('\n')}\n`;
@@ -975,10 +1009,10 @@ function stripExistingJiniMcpServerTable(existingRaw) {
  * @returns The full text to write to the scratch `CODEX_HOME`'s `config.toml`.
  * @complexity O(n) in the existing config's length.
  */
-export function buildCodexHomeConfigToml(existingRaw, entry) {
+export function buildCodexHomeConfigToml({ existingRaw, entry }) {
     const base = stripExistingJiniMcpServerTable(existingRaw ?? '');
     const separator = base.length === 0 ? '' : base.endsWith('\n') ? '\n' : '\n\n';
-    return `${base}${separator}${buildCodexMcpServerToml(entry)}`;
+    return `${base}${separator}${buildCodexMcpServerToml({ entry: entry })}`;
 }
 /**
  * Where `'codex-toml'` reads the operator's REAL Codex config from, to seed a run's scratch copy —
@@ -992,7 +1026,7 @@ export function buildCodexHomeConfigToml(existingRaw, entry) {
  * @complexity O(1).
  * @overallScore 100/100
  */
-export function resolveSourceCodexHomeDir(hostEnv) {
+export function resolveSourceCodexHomeDir({ hostEnv }) {
     const override = hostEnv.CODEX_HOME;
     return override !== undefined && override.trim().length > 0 ? override : join(homedir(), '.codex');
 }
@@ -1021,12 +1055,12 @@ export function buildMcpBridgeDelivery(input) {
     const { cwd, runId, strategy, options, credential } = input;
     if (options === undefined || strategy === undefined)
         return null;
-    const serverEntry = buildMcpJsonServerEntry(runId, options, credential);
+    const serverEntry = buildMcpJsonServerEntry({ runId: runId, options: options }, credential === undefined ? {} : { credential });
     switch (strategy) {
         case 'claude-mcp-json':
             return { kind: 'claude-mcp-json', mcpJsonPath: mcpJsonPathForRun(cwd, runId), serverEntry };
         case 'acp-merge':
-            return { kind: 'acp-merge', mcpServers: buildAcpMcpBridgeServers(serverEntry) };
+            return { kind: 'acp-merge', mcpServers: buildAcpMcpBridgeServers({ entry: serverEntry }) };
         case 'opencode-env-content':
         case 'mimo-env-content':
             return { kind: 'env-content', envVarName: ENV_CONTENT_VAR_BY_STRATEGY[strategy], serverEntry };
@@ -1036,13 +1070,13 @@ export function buildMcpBridgeDelivery(input) {
             return { kind: 'env-passthrough', serverEntry };
     }
 }
-function defaultReadMcpJsonFile(path) {
+function defaultReadMcpJsonFile({ path }) {
     return fsPromises.readFile(path, 'utf8');
 }
-function defaultWriteMcpJsonFile(path, content) {
+function defaultWriteMcpJsonFile({ path, content }) {
     return fsPromises.writeFile(path, content, 'utf8');
 }
-function defaultRemoveMcpJsonFile(path) {
+function defaultRemoveMcpJsonFile({ path }) {
     return fsPromises.rm(path, { force: true });
 }
 /**
@@ -1102,19 +1136,19 @@ async function writeMcpJsonForRun(cwd, delivery, options) {
     const writeFileFn = options.writeFile ?? defaultWriteMcpJsonFile;
     let existingRaw;
     try {
-        existingRaw = await readFileFn(join(cwd, '.mcp.json'));
+        existingRaw = await readFileFn({ path: join(cwd, '.mcp.json') });
     }
     catch {
         // No existing file (ENOENT — the common case) or unreadable for any other reason: both
         // degrade to "start fresh", matching mergeMcpJsonContent's own doc.
         existingRaw = undefined;
     }
-    await writeFileFn(delivery.mcpJsonPath, mergeMcpJsonContent(existingRaw, delivery.serverEntry));
+    await writeFileFn({ path: delivery.mcpJsonPath, content: mergeMcpJsonContent({ existingRaw: existingRaw, serverEntry: delivery.serverEntry }) });
 }
-function defaultMkdtempCodexHome(prefix) {
+function defaultMkdtempCodexHome({ prefix }) {
     return fsPromises.mkdtemp(join(tmpdir(), prefix));
 }
-function defaultRemoveCodexHomeDir(path) {
+function defaultRemoveCodexHomeDir({ path }) {
     return fsPromises.rm(path, { recursive: true, force: true });
 }
 function resolveCodexHomeSeams(options) {
@@ -1161,21 +1195,21 @@ async function prepareCodexHomeForRun(runId, entry, sourceCodexHomeDir, seams) {
     // too, not just path separators, so a run id like `../../etc/evil` cannot leave even a cosmetic
     // `..` substring in the mkdtemp prefix.
     const safeRunId = runId.replace(/[^A-Za-z0-9_-]/g, '-').slice(0, 80) || 'run';
-    const dir = await seams.mkdtemp(`jini-codex-home-${safeRunId}-`);
+    const dir = await seams.mkdtemp({ prefix: `jini-codex-home-${safeRunId}-` });
     try {
         let existingConfigRaw;
         try {
-            existingConfigRaw = await seams.readFile(join(sourceCodexHomeDir, 'config.toml'));
+            existingConfigRaw = await seams.readFile({ path: join(sourceCodexHomeDir, 'config.toml') });
         }
         catch {
             // No config yet (fresh Codex install) or unreadable — start from just this run's block,
             // matching writeMcpJsonForRun's identical "missing file" handling.
             existingConfigRaw = undefined;
         }
-        await seams.writeFile(join(dir, 'config.toml'), buildCodexHomeConfigToml(existingConfigRaw, entry));
+        await seams.writeFile({ path: join(dir, 'config.toml'), content: buildCodexHomeConfigToml({ existingRaw: existingConfigRaw, entry: entry }) });
         try {
-            const authRaw = await seams.readFile(join(sourceCodexHomeDir, 'auth.json'));
-            await seams.writeFile(join(dir, 'auth.json'), authRaw);
+            const authRaw = await seams.readFile({ path: join(sourceCodexHomeDir, 'auth.json') });
+            await seams.writeFile({ path: join(dir, 'auth.json'), content: authRaw });
         }
         catch {
             // No stored login (or unreadable) — the spawned CLI runs unauthenticated. Confirmed above:
@@ -1183,7 +1217,7 @@ async function prepareCodexHomeForRun(runId, entry, sourceCodexHomeDir, seams) {
         }
     }
     catch (err) {
-        await seams.removeDir(dir).catch(() => {
+        await seams.removeDir({ path: dir }).catch(() => {
             // Best-effort only — the original error below is what the caller must see either way.
         });
         throw err;
@@ -1191,14 +1225,14 @@ async function prepareCodexHomeForRun(runId, entry, sourceCodexHomeDir, seams) {
     return {
         path: dir,
         cleanup: async () => {
-            await seams.removeDir(dir);
+            await seams.removeDir({ path: dir });
         },
     };
 }
-function defaultMkdtempClaudeConfigDir(prefix) {
+function defaultMkdtempClaudeConfigDir({ prefix }) {
     return fsPromises.mkdtemp(join(tmpdir(), prefix));
 }
-function defaultRemoveClaudeConfigDir(path) {
+function defaultRemoveClaudeConfigDir({ path }) {
     return fsPromises.rm(path, { recursive: true, force: true });
 }
 function resolveClaudeConfigDirSeams(options) {
@@ -1221,7 +1255,7 @@ function resolveClaudeConfigDirSeams(options) {
  * default, `~/.claude`.
  * @complexity O(1).
  */
-export function resolveSourceClaudeConfigDir(hostEnv) {
+export function resolveSourceClaudeConfigDir({ hostEnv }) {
     const override = hostEnv.CLAUDE_CONFIG_DIR;
     return override !== undefined && override.trim().length > 0 ? override : join(homedir(), '.claude');
 }
@@ -1274,12 +1308,12 @@ export function resolveSourceClaudeConfigDir(hostEnv) {
  */
 async function prepareClaudeConfigDirForRun(runId, sourceConfigDir, seams) {
     const safeRunId = runId.replace(/[^A-Za-z0-9_-]/g, '-').slice(0, 80) || 'run';
-    const dir = await seams.mkdtemp(`jini-claude-config-${safeRunId}-`);
+    const dir = await seams.mkdtemp({ prefix: `jini-claude-config-${safeRunId}-` });
     try {
         const credentialsPath = join(sourceConfigDir, '.credentials.json');
         let credentialsRaw;
         try {
-            credentialsRaw = await seams.readFile(credentialsPath);
+            credentialsRaw = await seams.readFile({ path: credentialsPath });
         }
         catch {
             // No file-based credential to copy (the common macOS-Keychain-only case) — see this
@@ -1287,11 +1321,11 @@ async function prepareClaudeConfigDirForRun(runId, sourceConfigDir, seams) {
             credentialsRaw = undefined;
         }
         if (credentialsRaw !== undefined) {
-            await seams.writeFile(join(dir, '.credentials.json'), credentialsRaw);
+            await seams.writeFile({ path: join(dir, '.credentials.json'), content: credentialsRaw });
         }
     }
     catch (err) {
-        await seams.removeDir(dir).catch(() => {
+        await seams.removeDir({ path: dir }).catch(() => {
             // Best-effort only — the original error below is what the caller must see either way.
         });
         throw err;
@@ -1299,7 +1333,7 @@ async function prepareClaudeConfigDirForRun(runId, sourceConfigDir, seams) {
     return {
         path: dir,
         cleanup: async () => {
-            await seams.removeDir(dir);
+            await seams.removeDir({ path: dir });
         },
     };
 }
@@ -1357,7 +1391,7 @@ function bufferedStdoutTruncationNotice(droppedBytes, maxBytes) {
  * **Deliberately un-hygiened for v1**: no ANSI/terminal-control-sequence
  * stripping is applied (there is no Jini equivalent of OD's
  * `TerminalControlSequenceStripper` yet) — a documented decision, not an
- * oversight; see `packages/daemon/source-map.md`'s 2026-07-21 addition for
+ * oversight; see `packages/daemon/archived provenance ledger`'s 2026-07-21 addition for
  * the reasoning.
  *
  * *When* those chunks leave is the def's call, via `def.stdoutPolicy`:
@@ -1405,6 +1439,10 @@ function wireChildLifecycle(ctx) {
     // consumed by a turn-end injection decision. See `ContinuationOptions`'s doc for why this is
     // only ever acted on when a host has explicitly allowlisted the tool's name.
     let pendingToolUse;
+    // Bridge guard (see `expectsJiniBridge`): checked on the first init frame only. Once the bridge is
+    // found unavailable, the child is being stopped and nothing it still prints is forwarded.
+    let bridgeChecked = !ctx.expectsJiniBridge;
+    let bridgeUnavailable = false;
     // `def.stdoutPolicy` read once, up front, so the per-chunk handler below is a single boolean
     // test rather than a repeated union narrowing. `undefined` (every def but antigravity) means
     // live — see this function's own doc.
@@ -1454,7 +1492,7 @@ function wireChildLifecycle(ctx) {
         });
         stdin.write(`${line}\n`, 'utf8');
         if (journal)
-            enqueueEmit(() => journal.record(runId, sentJournalEntry(content)));
+            enqueueEmit(() => journal.record({ runId: runId, entry: sentJournalEntry(content) }));
     }
     /**
      * Decides, per `turn_end`, whether to auto-resolve a pending tool_use through the injected
@@ -1467,7 +1505,7 @@ function wireChildLifecycle(ctx) {
         const shouldInject = stopReason === 'tool_use' &&
             toolUse !== undefined &&
             continuation !== undefined &&
-            resolveContinuationTransport(def) === 'stdin-injection' &&
+            resolveContinuationTransport({ def: def }) === 'stdin-injection' &&
             continuation.autonomousToolNames.has(toolUse.name);
         if (!shouldInject) {
             closeStdinOnce();
@@ -1490,40 +1528,50 @@ function wireChildLifecycle(ctx) {
             // the CPU-starved-and-silent condition the watchdog exists to catch. Resumed in `finally` so a
             // genuinely stalled stretch *after* this tool settles is still caught — see
             // `RunLifecycle.suspendSlowRunNotice`'s own doc.
-            lifecycle.suspendSlowRunNotice(runId);
+            lifecycle.suspendSlowRunNotice({ runId: runId });
             try {
-                const result = await continuation.toolExecutor.execute(continuation.principal, run, toolUse.name, toolUse.input);
-                content = resultContent(result);
+                const result = await continuation.toolExecutor.execute({ principal: continuation.principal, run: run, toolId: toolUse.name, input: toolUse.input });
+                content = resultContent({ result: result });
                 isError = result.status !== 'completed';
-                media = extractResultMedia(result.output).media;
+                media = extractResultMedia({ output: result.output }).media;
             }
             catch (error) {
                 content = errorMessage(error);
                 isError = true;
             }
             finally {
-                lifecycle.resumeSlowRunNotice(runId);
+                lifecycle.resumeSlowRunNotice({ runId: runId });
             }
-            await lifecycle.emit(runId, {
-                event: 'agent',
-                data: {
-                    type: 'tool_result',
-                    toolUseId: toolUse.id,
-                    content,
-                    ...(isError ? { isError: true } : {}),
-                    ...(media.length > 0 ? { media } : {}),
-                },
-            });
+            await lifecycle.emit({ runId: runId, input: {
+                    event: 'agent',
+                    data: {
+                        type: 'tool_result',
+                        toolUseId: toolUse.id,
+                        content,
+                        ...(isError ? { isError: true } : {}),
+                        ...(media.length > 0 ? { media } : {}),
+                    },
+                } });
             injectToolResultLine(toolUse.id, content, isError);
         });
     }
     const streamHandler = streamFormat === 'plain'
         ? null
         : createStreamHandlerForDef(def, streamFormat, (rawEvent) => {
-            const translation = translateAgentRuntimeEvent(rawEvent);
+            if (bridgeUnavailable)
+                return;
+            const translation = translateAgentRuntimeEvent({ rawEvent: rawEvent });
             if (translation.kind === 'agent') {
                 if (translation.sessionId !== undefined)
                     capturedSessionId = translation.sessionId;
+                if (!bridgeChecked && translation.payload.type === 'status' && translation.payload.label === 'initializing') {
+                    bridgeChecked = true;
+                    const bridgeStatus = unavailableJiniBridgeStatus({ rawEvent: rawEvent });
+                    if (bridgeStatus !== undefined) {
+                        stopForUnavailableBridge(translation.payload, bridgeStatus);
+                        return;
+                    }
+                }
                 if (translation.payload.type === 'tool_use') {
                     pendingToolUse = { id: translation.payload.id, name: translation.payload.name, input: translation.payload.input };
                     toolCallSeen = true;
@@ -1532,15 +1580,28 @@ function wireChildLifecycle(ctx) {
                     translation.payload.delta.length > 0) {
                     userVisibleOutputSeen = true;
                 }
-                enqueueEmit(() => lifecycle.emit(runId, { event: 'agent', data: translation.payload }));
+                enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'agent', data: translation.payload } }));
             }
             else if (translation.kind === 'error') {
-                enqueueEmit(() => lifecycle.emit(runId, { event: 'error', data: translation.payload }));
+                enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'error', data: translation.payload } }));
             }
             else if (translation.kind === 'turn-end') {
                 handleTurnEnd(translation.stopReason);
             }
         });
+    /**
+     * Ends a run whose CLI started without the `jini` bridge: emits the init status and a
+     * {@link MCP_BRIDGE_UNAVAILABLE} error, then stops the child's process tree before the model can
+     * answer with no host tools. The close handler then finishes the run `'failed'` whatever exit code
+     * the child reports.
+     */
+    function stopForUnavailableBridge(initStatus, bridgeStatus) {
+        bridgeUnavailable = true;
+        const message = bridgeUnavailableMessage(bridgeStatus);
+        enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'agent', data: initStatus } }));
+        enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'error', data: { message, error: { code: MCP_BRIDGE_UNAVAILABLE, message } } } }));
+        void terminateChildTreeBestEffort(ctx, child, runId, 'cancel', ctx.onCleanupFailure);
+    }
     /**
      * Emits the accumulated `'until-close'` stdout — sanitized — as exactly one raw `'stdout'` echo
      * plus one `text_delta`, through the same `enqueueEmit` FIFO queue every other emit uses, so the
@@ -1555,7 +1616,7 @@ function wireChildLifecycle(ctx) {
     function flushBufferedStdout() {
         if (bufferedStdout.length === 0 && droppedStdoutBytes === 0)
             return;
-        const safe = sanitizeBufferedStdout ? sanitizeBufferedStdout(bufferedStdout) : bufferedStdout;
+        const safe = sanitizeBufferedStdout ? sanitizeBufferedStdout({ fullText: bufferedStdout }) : bufferedStdout;
         bufferedStdout = '';
         bufferedStdoutBytes = 0;
         const text = droppedStdoutBytes > 0
@@ -1564,13 +1625,13 @@ function wireChildLifecycle(ctx) {
         droppedStdoutBytes = 0;
         if (text.length === 0)
             return;
-        enqueueEmit(() => lifecycle.emit(runId, { event: 'stdout', data: { chunk: text } }));
-        enqueueEmit(() => lifecycle.emit(runId, { event: 'agent', data: { type: 'text_delta', delta: text } }));
+        enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'stdout', data: { chunk: text } } }));
+        enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'agent', data: { type: 'text_delta', delta: text } } }));
     }
     child.stdout?.on('data', (chunk) => {
         const text = chunk.toString('utf8');
         if (journal)
-            enqueueEmit(() => journal.record(runId, receivedJournalEntry('stdout', text)));
+            enqueueEmit(() => journal.record({ runId: runId, entry: receivedJournalEntry('stdout', text) }));
         if (streamFormat === 'plain') {
             if (text.length > 0)
                 userVisibleOutputSeen = true;
@@ -1592,20 +1653,20 @@ function wireChildLifecycle(ctx) {
                 bufferedStdoutBytes += chunkBytes;
                 return;
             }
-            enqueueEmit(() => lifecycle.emit(runId, { event: 'stdout', data: { chunk: text } }));
-            enqueueEmit(() => lifecycle.emit(runId, { event: 'agent', data: { type: 'text_delta', delta: text } }));
+            enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'stdout', data: { chunk: text } } }));
+            enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'agent', data: { type: 'text_delta', delta: text } } }));
             return;
         }
-        enqueueEmit(() => lifecycle.emit(runId, { event: 'stdout', data: { chunk: text } }));
+        enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'stdout', data: { chunk: text } } }));
         // Non-null: `streamHandler` is only ever null when `streamFormat === 'plain'` (see its
         // construction above), the branch this statement is provably unreachable from.
-        streamHandler.feed(text);
+        streamHandler.feed({ chunk: text });
     });
     child.stderr?.on('data', (chunk) => {
         const text = chunk.toString('utf8');
         if (journal)
-            enqueueEmit(() => journal.record(runId, receivedJournalEntry('stderr', text)));
-        enqueueEmit(() => lifecycle.emit(runId, { event: 'stderr', data: { chunk: text } }));
+            enqueueEmit(() => journal.record({ runId: runId, entry: receivedJournalEntry('stderr', text) }));
+        enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'stderr', data: { chunk: text } } }));
     });
     // EPIPE-tolerant: a fast-exiting child that closes its stdin read end
     // before every queued write lands must not crash the host process with
@@ -1617,10 +1678,10 @@ function wireChildLifecycle(ctx) {
     // EventEmitter throws on an unheard 'error' otherwise. The real outcome
     // is still decided by 'close' below.
     child.on('error', () => { });
-    const unsubscribeCancel = lifecycle.onCancelRequested(runId, () => {
-        cancelRequested = true;
-        void terminateChildTreeBestEffort(ctx, child, runId, 'cancel', ctx.onCleanupFailure);
-    });
+    const unsubscribeCancel = lifecycle.onCancelRequested({ runId: runId, listener: () => {
+            cancelRequested = true;
+            void terminateChildTreeBestEffort(ctx, child, runId, 'cancel', ctx.onCleanupFailure);
+        } });
     child.on('close', (code, signal) => {
         void (async () => {
             // Not wrapped in try/catch: all 4 supported parser factories'
@@ -1640,8 +1701,9 @@ function wireChildLifecycle(ctx) {
             // Both of the next two steps are guarded: neither a failed cleanup nor a rejecting host
             // classifier may prevent the terminal transition below — see each helper's own doc.
             await cleanupStagedFilesSafely(ctx);
-            const status = classifyRunCloseStatus({ cancelRequested, code, signal });
-            const resumable = status === 'failed' && classifyFailure !== undefined
+            const status = bridgeUnavailable ? 'failed' : classifyRunCloseStatus({ cancelRequested, code }, { signal });
+            // A bridge failure is not resumable: resuming would start the same CLI with the same bridge.
+            const resumable = status === 'failed' && !bridgeUnavailable && classifyFailure !== undefined
                 ? await classifyFailureSafely(ctx, classifyFailure, {
                     runId,
                     agentId: def.id,
@@ -1650,21 +1712,14 @@ function wireChildLifecycle(ctx) {
                     sideEffects: { userVisibleOutputSeen, toolCallSeen },
                 })
                 : false;
-            await lifecycle.finish({
-                runId,
-                status,
-                code,
-                signal: signal ?? null,
-                resumable,
-                ...(capturedSessionId !== undefined ? { sessionRef: capturedSessionId } : {}),
-            });
+            await lifecycle.finish({ runId, status, code, signal: signal ?? null, resumable }, { ...(capturedSessionId !== undefined ? { sessionRef: capturedSessionId } : {}) });
         })();
     });
     return {
         closeStdinOnce,
         recordSentBytes(content) {
             if (journal)
-                enqueueEmit(() => journal.record(runId, sentJournalEntry(content)));
+                enqueueEmit(() => journal.record({ runId: runId, entry: sentJournalEntry(content) }));
         },
     };
 }
@@ -1705,9 +1760,9 @@ function translateAcpError(payload) {
  * @param sink - The driver-specific effects to apply.
  * @complexity O(1).
  */
-export function applyAgentTranslationSideEffects(payload, sessionId, sink) {
+export function applyAgentTranslationSideEffects({ payload, sessionId, sink }) {
     if (sessionId !== undefined)
-        sink.onSessionId(sessionId);
+        sink.onSessionId({ sessionId });
     if (payload.type === 'tool_use') {
         sink.onToolCall();
     }
@@ -1747,23 +1802,23 @@ function wireAcpLifecycle(ctx) {
     child.stdout?.on('data', (chunk) => {
         const text = chunk.toString('utf8');
         if (journal)
-            enqueueEmit(() => journal.record(runId, receivedJournalEntry('stdout', text)));
-        enqueueEmit(() => lifecycle.emit(runId, { event: 'stdout', data: { chunk: text } }));
+            enqueueEmit(() => journal.record({ runId: runId, entry: receivedJournalEntry('stdout', text) }));
+        enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'stdout', data: { chunk: text } } }));
     });
     child.stderr?.on('data', (chunk) => {
         const text = chunk.toString('utf8');
         if (journal)
-            enqueueEmit(() => journal.record(runId, receivedJournalEntry('stderr', text)));
-        enqueueEmit(() => lifecycle.emit(runId, { event: 'stderr', data: { chunk: text } }));
+            enqueueEmit(() => journal.record({ runId: runId, entry: receivedJournalEntry('stderr', text) }));
+        enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'stderr', data: { chunk: text } } }));
     });
     child.stdin?.on('error', () => { });
     child.on('error', () => { });
     let controller = null;
-    const unsubscribeCancel = lifecycle.onCancelRequested(runId, () => {
-        cancelRequested = true;
-        controller?.abort();
-        void terminateChildTreeBestEffort(ctx, child, runId, 'cancel', ctx.onCleanupFailure);
-    });
+    const unsubscribeCancel = lifecycle.onCancelRequested({ runId: runId, listener: () => {
+            cancelRequested = true;
+            controller?.abort();
+            void terminateChildTreeBestEffort(ctx, child, runId, 'cancel', ctx.onCleanupFailure);
+        } });
     child.on('close', (code, signal) => {
         void (async () => {
             await emitQueue;
@@ -1780,49 +1835,33 @@ function wireAcpLifecycle(ctx) {
                     sideEffects: { userVisibleOutputSeen, toolCallSeen },
                 })
                 : false;
-            await lifecycle.finish({
-                runId,
-                status,
-                code,
-                signal: signal ?? null,
-                resumable,
-                ...(capturedSessionId !== undefined ? { sessionRef: capturedSessionId } : {}),
-            });
+            await lifecycle.finish({ runId, status, code, signal: signal ?? null, resumable }, { ...(capturedSessionId !== undefined ? { sessionRef: capturedSessionId } : {}) });
         })();
     });
-    controller = ctx.attachAcpSession({
-        child,
-        prompt: ctx.prompt,
-        cwd: ctx.cwd,
-        ...(ctx.model !== undefined ? { model: ctx.model } : {}),
-        ...(ctx.imagePaths.length > 0 ? { imagePaths: [...ctx.imagePaths] } : {}),
-        ...(ctx.envFormat !== undefined ? { envFormat: ctx.envFormat } : {}),
-        // Spread-when-present rather than always: passing `mcpServers: []` is not the same as passing
-        // nothing for every downstream ACP agent, and "no bridge configured" must stay byte-identical
-        // to before this field existed.
-        ...(ctx.mcpServers !== undefined && ctx.mcpServers.length > 0 ? { mcpServers: [...ctx.mcpServers] } : {}),
-        ...(ctx.onPermissionRequest !== undefined ? { onPermissionRequest: ctx.onPermissionRequest } : {}),
-        send(event, payload) {
+    controller = ctx.attachAcpSession({ child, prompt: ctx.prompt, send({ event, payload }) {
             if (event === 'agent') {
-                const translation = translateAgentRuntimeEvent(payload);
+                const translation = translateAgentRuntimeEvent({ rawEvent: payload });
                 if (translation.kind === 'agent') {
-                    applyAgentTranslationSideEffects(translation.payload, translation.sessionId, {
-                        onSessionId: (sessionId) => { capturedSessionId = sessionId; },
-                        onToolCall: () => { toolCallSeen = true; },
-                        onUserVisibleOutput: () => { userVisibleOutputSeen = true; },
-                    });
-                    enqueueEmit(() => lifecycle.emit(runId, { event: 'agent', data: translation.payload }));
+                    applyAgentTranslationSideEffects({ payload: translation.payload, sessionId: translation.sessionId, sink: {
+                            onSessionId: ({ sessionId }) => { capturedSessionId = sessionId; },
+                            onToolCall: () => { toolCallSeen = true; },
+                            onUserVisibleOutput: () => { userVisibleOutputSeen = true; },
+                        } });
+                    enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'agent', data: translation.payload } }));
                 }
                 else if (translation.kind === 'error') {
-                    enqueueEmit(() => lifecycle.emit(runId, { event: 'error', data: translation.payload }));
+                    enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'error', data: translation.payload } }));
                 }
                 return;
             }
             if (event === 'error') {
-                enqueueEmit(() => lifecycle.emit(runId, { event: 'error', data: translateAcpError(payload) }));
+                enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'error', data: translateAcpError(payload) } }));
             }
-        },
-    });
+        } }, { cwd: ctx.cwd, ...(ctx.model !== undefined ? { model: ctx.model } : {}), ...(ctx.imagePaths.length > 0 ? { imagePaths: [...ctx.imagePaths] } : {}), ...(ctx.envFormat !== undefined ? { envFormat: ctx.envFormat } : {}),
+        // Spread-when-present rather than always: passing `mcpServers: []` is not the same as passing
+        // nothing for every downstream ACP agent, and "no bridge configured" must stay byte-identical
+        // to before this field existed.
+        ...(ctx.mcpServers !== undefined && ctx.mcpServers.length > 0 ? { mcpServers: [...ctx.mcpServers] } : {}), ...(ctx.onPermissionRequest !== undefined ? { onPermissionRequest: ctx.onPermissionRequest } : {}) });
     return controller;
 }
 /**
@@ -1867,23 +1906,23 @@ function wirePiRpcLifecycle(ctx) {
     child.stdout?.on('data', (chunk) => {
         const text = chunk.toString('utf8');
         if (journal)
-            enqueueEmit(() => journal.record(runId, receivedJournalEntry('stdout', text)));
-        enqueueEmit(() => lifecycle.emit(runId, { event: 'stdout', data: { chunk: text } }));
+            enqueueEmit(() => journal.record({ runId: runId, entry: receivedJournalEntry('stdout', text) }));
+        enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'stdout', data: { chunk: text } } }));
     });
     child.stderr?.on('data', (chunk) => {
         const text = chunk.toString('utf8');
         if (journal)
-            enqueueEmit(() => journal.record(runId, receivedJournalEntry('stderr', text)));
-        enqueueEmit(() => lifecycle.emit(runId, { event: 'stderr', data: { chunk: text } }));
+            enqueueEmit(() => journal.record({ runId: runId, entry: receivedJournalEntry('stderr', text) }));
+        enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'stderr', data: { chunk: text } } }));
     });
     child.stdin?.on('error', () => { });
     child.on('error', () => { });
     let session = null;
-    const unsubscribeCancel = lifecycle.onCancelRequested(runId, () => {
-        cancelRequested = true;
-        session?.abort();
-        void terminateChildTreeBestEffort(ctx, child, runId, 'cancel', ctx.onCleanupFailure);
-    });
+    const unsubscribeCancel = lifecycle.onCancelRequested({ runId: runId, listener: () => {
+            cancelRequested = true;
+            session?.abort();
+            void terminateChildTreeBestEffort(ctx, child, runId, 'cancel', ctx.onCleanupFailure);
+        } });
     child.on('close', (code, signal) => {
         void (async () => {
             await emitQueue;
@@ -1900,25 +1939,11 @@ function wirePiRpcLifecycle(ctx) {
                     sideEffects: { userVisibleOutputSeen, toolCallSeen },
                 })
                 : false;
-            await lifecycle.finish({
-                runId,
-                status,
-                code,
-                signal: signal ?? null,
-                resumable,
-                ...(capturedSessionId !== undefined ? { sessionRef: capturedSessionId } : {}),
-            });
+            await lifecycle.finish({ runId, status, code, signal: signal ?? null, resumable }, { ...(capturedSessionId !== undefined ? { sessionRef: capturedSessionId } : {}) });
         })();
     });
-    session = ctx.attachPiRpcSession({
-        child: ctx.child,
-        prompt: ctx.prompt,
-        cwd: ctx.cwd,
-        ...(ctx.model !== undefined ? { model: ctx.model } : {}),
-        ...(ctx.imagePaths.length > 0 ? { imagePaths: [...ctx.imagePaths] } : {}),
-        ...(ctx.uploadRoot !== undefined ? { uploadRoot: ctx.uploadRoot } : {}),
-        send(_channel, payload) {
-            const translation = translateAgentRuntimeEvent(payload);
+    session = ctx.attachPiRpcSession({ child: ctx.child, prompt: ctx.prompt, send({ payload }) {
+            const translation = translateAgentRuntimeEvent({ rawEvent: payload });
             if (translation.kind === 'agent') {
                 if (translation.sessionId !== undefined)
                     capturedSessionId = translation.sessionId;
@@ -1929,13 +1954,12 @@ function wirePiRpcLifecycle(ctx) {
                     translation.payload.delta.length > 0) {
                     userVisibleOutputSeen = true;
                 }
-                enqueueEmit(() => lifecycle.emit(runId, { event: 'agent', data: translation.payload }));
+                enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'agent', data: translation.payload } }));
             }
             else if (translation.kind === 'error') {
-                enqueueEmit(() => lifecycle.emit(runId, { event: 'error', data: translation.payload }));
+                enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'error', data: translation.payload } }));
             }
-        },
-    });
+        } }, { cwd: ctx.cwd, ...(ctx.model !== undefined ? { model: ctx.model } : {}), ...(ctx.imagePaths.length > 0 ? { imagePaths: [...ctx.imagePaths] } : {}), ...(ctx.uploadRoot !== undefined ? { uploadRoot: ctx.uploadRoot } : {}) });
     return session;
 }
 /**
@@ -1997,8 +2021,8 @@ function resolveProcessDeps(options) {
         createCommandInvocation: options.createCommandInvocation ?? createCommandInvocation,
         spawn: options.spawn ?? nodeSpawn,
         listProcessSnapshots: options.listProcessSnapshots ?? listProcessSnapshots,
-        collectProcessTreePids: options.collectProcessTreePids ?? collectProcessTreePids,
-        stopProcesses: options.stopProcesses ?? stopProcesses,
+        collectProcessTreePids: options.collectProcessTreePids ?? (({ processes, rootPids }) => collectProcessTreePids(processes, rootPids)),
+        stopProcesses: options.stopProcesses ?? (({ pids }) => stopProcesses(pids)),
     };
 }
 /** Resolves the two remaining defaultable options — see {@link resolveAgentRuntimeDeps}'s doc. Pure. */
@@ -2009,23 +2033,23 @@ function resolveMiscExecutorDeps(options) {
     };
 }
 /** Phase 1: registry lookup + `assessAgentExecutorCompatibility` guard. */
-export async function resolveDefAndStreamFormat(input, deps) {
-    const def = deps.getAgentDef(input.agentId);
+export async function resolveDefAndStreamFormat({ input, deps }) {
+    const def = deps.getAgentDef({ id: input.agentId });
     if (!def) {
-        return deps.failBeforeSpawn(input.runId, 'AGENT_NOT_FOUND', `AgentExecutor: unknown agentId "${input.agentId}"`);
+        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_NOT_FOUND', message: `AgentExecutor: unknown agentId "${input.agentId}"` });
     }
-    const compatibility = assessAgentExecutorCompatibility(def);
+    const compatibility = assessAgentExecutorCompatibility({ def: def });
     if (!compatibility.supported) {
-        return deps.failBeforeSpawn(input.runId, 'AGENT_RUNTIME_UNSUPPORTED', compatibility.reason);
+        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_RUNTIME_UNSUPPORTED', message: compatibility.reason });
     }
     return { def, streamFormat: compatibility.streamFormat };
 }
 /** Phase 2: image-prompt-delivery augmentation + argv-budget guard for argv-bound defs. */
-export async function resolveImageDeliveryAndArgvBudget(input, deps) {
-    const imageDelivery = applyImagePromptDelivery(input.def.imageDelivery, input.prompt, input.imagePaths, input.extraAllowedDirs);
-    const argvBudgetError = checkPromptArgvBudget(input.def, imageDelivery.prompt);
+export async function resolveImageDeliveryAndArgvBudget({ input, deps }) {
+    const imageDelivery = applyImagePromptDelivery({ imageDelivery: input.def.imageDelivery, prompt: input.prompt, imagePaths: input.imagePaths, extraAllowedDirs: input.extraAllowedDirs });
+    const argvBudgetError = checkPromptArgvBudget({ def: input.def, composed: imageDelivery.prompt });
     if (argvBudgetError) {
-        return deps.failBeforeSpawn(input.runId, 'AGENT_PROMPT_TOO_LARGE', argvBudgetError.message);
+        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_PROMPT_TOO_LARGE', message: argvBudgetError.message });
     }
     return imageDelivery;
 }
@@ -2034,44 +2058,44 @@ export async function resolveImageDeliveryAndArgvBudget(input, deps) {
  * caller-supplied escape hatch verbatim, or the deny-by-default `BASELINE_AGENT_ENV_KEYS` allowlist.
  * Pure.
  */
-export function resolveRunEnv(input, hostEnv) {
+export function resolveRunEnv({ input, hostEnv }) {
     return input.env !== undefined ? toStringEnvRecord(input.env) : buildAgentEnv(hostEnv, input.credentialEnv);
 }
 /** Phase 3b: launch-path resolution + binary-not-resolved guard. */
-export async function resolveLaunch(input, deps) {
-    const launch = deps.resolveAgentLaunch(input.def, input.resolvedEnv);
+export async function resolveLaunch({ input, deps }) {
+    const launch = deps.resolveAgentLaunch({ def: input.def }, { configuredEnv: input.resolvedEnv });
     if (!launch.launchPath) {
-        return deps.failBeforeSpawn(input.runId, 'AGENT_BINARY_NOT_RESOLVED', `AgentExecutor: could not resolve an executable for agent "${input.def.id}" (bin "${input.def.bin}")`);
+        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_BINARY_NOT_RESOLVED', message: `AgentExecutor: could not resolve an executable for agent "${input.def.id}" (bin "${input.def.bin}")` });
     }
     // Narrowed by the guard above; `resolveAgentLaunch`'s own return type still declares
     // `launchPath: string | null` since it can't know this call site already checked.
     return launch;
 }
 /** Phase 4a: stage a `promptViaFile` def's prompt to a temp file (a no-op for every other def). */
-export async function stagePromptFile(input, deps) {
+export async function stagePromptFile({ input, deps }) {
     try {
-        return await deps.preparePromptFileForAgent(input.def, input.prompt, input.runId);
+        return await deps.preparePromptFileForAgent({ def: input.def, prompt: input.prompt, label: input.runId });
     }
     catch (err) {
-        return deps.failBeforeSpawn(input.runId, 'AGENT_SPAWN_FAILED', `AgentExecutor: could not stage a prompt file for agent "${input.def.id}": ${errorMessage(err)}`);
+        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: could not stage a prompt file for agent "${input.def.id}": ${errorMessage(err)}` });
     }
 }
 /** Phase 4b: stage a `needsAgentLogFile` def's diagnostic-log path (a no-op for every other def). */
-export async function stageLogFile(input, deps) {
+export async function stageLogFile({ input, deps }) {
     try {
-        return await deps.prepareAgentLogFile(input.def, input.runId);
+        return await deps.prepareAgentLogFile({ def: input.def, label: input.runId });
     }
     catch (err) {
         await (input.preparedPromptFile ? input.preparedPromptFile.cleanup() : Promise.resolve());
-        return deps.failBeforeSpawn(input.runId, 'AGENT_SPAWN_FAILED', `AgentExecutor: could not stage a log file for agent "${input.def.id}": ${errorMessage(err)}`);
+        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: could not stage a log file for agent "${input.def.id}": ${errorMessage(err)}` });
     }
 }
 /** Phase 5: resolves this run's MCP bridge delivery (credential resolution + {@link buildMcpBridgeDelivery}). */
-export async function resolveMcpBridgeForRun(input, deps) {
+export async function resolveMcpBridgeForRun({ input, deps }) {
     try {
         // Awaited here rather than inside `buildMcpBridgeDelivery` so that function stays pure and
         // synchronous. `undefined` when the host supplied no resolver, which omits the token entirely.
-        const credential = deps.mcpJsonInjection !== undefined ? await deps.mcpJsonInjection.credential?.(input.runId) : undefined;
+        const credential = deps.mcpJsonInjection !== undefined ? await deps.mcpJsonInjection.credential?.({ runId: input.runId }) : undefined;
         return buildMcpBridgeDelivery({
             cwd: input.cwd,
             runId: input.runId,
@@ -2084,7 +2108,7 @@ export async function resolveMcpBridgeForRun(input, deps) {
         // Spawning a child that cannot authenticate would produce a run whose every bridged tool call
         // 401s, so a rejecting credential resolver fails the run before spawn instead.
         await deps.cleanupStagedFiles();
-        return deps.failBeforeSpawn(input.runId, 'AGENT_SPAWN_FAILED', `AgentExecutor: could not resolve the MCP bridge credential for agent "${input.def.id}": ${errorMessage(err)}`);
+        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: could not resolve the MCP bridge credential for agent "${input.def.id}": ${errorMessage(err)}` });
     }
 }
 /**
@@ -2108,11 +2132,11 @@ export async function resolveMcpBridgeForRun(input, deps) {
  * @complexity O(1) plus `mergeEnvContentMcpConfig`'s and `mergeEnvContentInstructions`'s own `JSON.parse`/`JSON.stringify` cost.
  * @overallScore 100/100
  */
-export function computeChildEnv(spawnEnv, mcpBridge, codexHomeDir, systemPromptEnvOverrides, stagedInstructionsFile, claudeConfigDir) {
+export function computeChildEnv({ spawnEnv, mcpBridge }, { codexHomeDir, systemPromptEnvOverrides, stagedInstructionsFile, claudeConfigDir } = {}) {
     const envContentApplied = mcpBridge?.kind === 'env-content'
         ? {
             ...spawnEnv,
-            [mcpBridge.envVarName]: mergeEnvContentMcpConfig(spawnEnv[mcpBridge.envVarName], mcpBridge.serverEntry),
+            [mcpBridge.envVarName]: mergeEnvContentMcpConfig({ existingRaw: spawnEnv[mcpBridge.envVarName], entry: mcpBridge.serverEntry }),
         }
         : spawnEnv;
     // `'env-passthrough'` (antigravity): no document, no named carrier variable — the bridge
@@ -2125,7 +2149,7 @@ export function computeChildEnv(spawnEnv, mcpBridge, codexHomeDir, systemPromptE
         ? envPassthroughApplied
         : {
             ...envPassthroughApplied,
-            [stagedInstructionsFile.varName]: mergeEnvContentInstructions(envPassthroughApplied[stagedInstructionsFile.varName], stagedInstructionsFile.path),
+            [stagedInstructionsFile.varName]: mergeEnvContentInstructions({ existingRaw: envPassthroughApplied[stagedInstructionsFile.varName], instructionsFilePath: stagedInstructionsFile.path }),
         };
     const codexHomeApplied = codexHomeDir === undefined ? instructionsApplied : { ...instructionsApplied, CODEX_HOME: codexHomeDir };
     // Finding 1 of SEC-assistant-env-isolation-2026-09-07: same "only set when staged" shape as
@@ -2146,7 +2170,7 @@ export function computeChildEnv(spawnEnv, mcpBridge, codexHomeDir, systemPromptE
  * session id, with no prompt/log file staged and no claude-mcp-json bridge, is exactly the common
  * case for a resumed turn.
  */
-export function computeRuntimeContext(preparedPromptFile, preparedLogFile, mcpBridge, resumeSessionId, newSessionId) {
+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.
@@ -2187,13 +2211,18 @@ function computeSystemPromptOverlay(promptAugmenter, agentId, runtimeContext) {
         turnIndex: runtimeContext?.hasPriorAssistantTurn ? 1 : 0,
     });
 }
-/** Phase 9a: the def's `buildArgs` 4th argument — `undefined` when the run selects no model/reasoning/permissionMode/overlay/tool-restriction at all (byte-identical to omitting the argument). Pure. */
-export function buildAgentBuildArgsOptions(input, systemPromptOverlay) {
+/** 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. */
+export function buildAgentBuildArgsOptions({ input, systemPromptOverlay }) {
+    const permissionMode = input.permissionMode ?? 'restricted';
+    if (permissionMode !== 'restricted' && permissionMode !== 'bypass') {
+        throw new AgentExecutorError({ code: 'AGENT_PERMISSION_MODE_INVALID', message: 'AgentExecutor: permissionMode must be restricted or bypass' });
+    }
     const hasOverlay = systemPromptOverlay !== undefined && systemPromptOverlay !== null;
     const options = {
         ...(input.model !== undefined ? { model: input.model } : {}),
         ...(input.reasoning !== undefined ? { reasoning: input.reasoning } : {}),
-        ...(input.permissionMode !== undefined ? { permissionMode: input.permissionMode } : {}),
+        permissionMode,
         ...(input.disallowedTools !== undefined ? { disallowedTools: input.disallowedTools } : {}),
         ...(input.allowedTools !== undefined ? { allowedTools: input.allowedTools } : {}),
         ...(input.settingSources !== undefined ? { settingSources: input.settingSources } : {}),
@@ -2314,10 +2343,15 @@ export function resolveSystemPromptOverlayDelivery(input) {
  * therefore only ever reach the 7 defs whose `buildArgs` reads its first argument at all — the
  * other 17 declare it `_prompt` and discard it, which is exactly how the overlay used to go missing.
  */
-export async function buildRunArgs(input, deps) {
+export async function buildRunArgs({ input, deps }) {
     try {
         const delivery = input.overlayDelivery;
-        const args = input.def.buildArgs(delivery.prompt, [...(input.imagePaths ?? [])], input.imageDelivery.extraAllowedDirs === undefined ? undefined : [...input.imageDelivery.extraAllowedDirs], buildAgentBuildArgsOptions(input.runInput, input.systemPromptOverlay), input.runtimeContext);
+        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 }),
+            ...(input.runtimeContext === undefined ? {} : { runtimeContext: input.runtimeContext }),
+        });
         // `'append-flag'` delivery's extra argv (empty for every other def/strategy) is appended after
         // whatever the def's own `buildArgs` returned — safe because it is only ever non-empty for a
         // `promptViaStdin` def with no trailing positional argv (`claude`/`pi` today; see
@@ -2329,11 +2363,11 @@ export async function buildRunArgs(input, deps) {
     }
     catch (err) {
         await deps.releaseStagedResources();
-        return deps.failBeforeSpawn(input.runId, 'AGENT_SPAWN_FAILED', `AgentExecutor: could not build launch arguments for agent "${input.def.id}": ${errorMessage(err)}`);
+        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: could not build launch arguments for agent "${input.def.id}": ${errorMessage(err)}` });
     }
 }
 /** Phase 10: mechanism 1 of 5's one effect — stages this run's own `.mcp.json`, returning the path `cleanupStagedFiles` should later remove (`undefined` for every other mechanism / unconfigured host). */
-export async function writeMcpJsonIfNeeded(input, deps) {
+export async function writeMcpJsonIfNeeded({ input, deps }) {
     if (input.mcpBridge?.kind !== 'claude-mcp-json' || deps.mcpJsonInjection === undefined) {
         return undefined;
     }
@@ -2343,7 +2377,7 @@ export async function writeMcpJsonIfNeeded(input, deps) {
     }
     catch (err) {
         await deps.releaseStagedResources();
-        return deps.failBeforeSpawn(input.runId, 'AGENT_SPAWN_FAILED', `AgentExecutor: could not write .mcp.json for agent "${input.def.id}": ${errorMessage(err)}`);
+        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: could not write .mcp.json for agent "${input.def.id}": ${errorMessage(err)}` });
     }
 }
 /**
@@ -2364,7 +2398,7 @@ export async function writeMcpJsonIfNeeded(input, deps) {
  * @complexity O(1) plus one directory creation and one file write.
  * @overallScore 100/100
  */
-export async function prepareSystemPromptOverlayFileIfNeeded(input, deps) {
+export async function prepareSystemPromptOverlayFileIfNeeded({ input, deps }) {
     if (input.def.systemPromptDelivery?.strategy !== 'config-instructions-file' ||
         typeof input.overlay !== 'string' ||
         input.overlay.length === 0) {
@@ -2384,7 +2418,7 @@ export async function prepareSystemPromptOverlayFileIfNeeded(input, deps) {
     }
     catch (err) {
         await deps.releaseStagedResources();
-        return deps.failBeforeSpawn(input.runId, 'AGENT_SPAWN_FAILED', `AgentExecutor: could not stage a system-prompt overlay file for agent "${input.def.id}": ${errorMessage(err)}`);
+        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)}` });
     }
 }
 /**
@@ -2397,16 +2431,16 @@ export async function prepareSystemPromptOverlayFileIfNeeded(input, deps) {
  * @complexity O(1) plus {@link prepareCodexHomeForRun}'s own cost.
  * @overallScore 100/100
  */
-export async function prepareCodexHomeIfNeeded(input, deps) {
+export async function prepareCodexHomeIfNeeded({ input, deps }) {
     if (input.mcpBridge?.kind !== 'codex-toml' || deps.mcpJsonInjection === undefined) {
         return null;
     }
     try {
-        return await prepareCodexHomeForRun(input.runId, input.mcpBridge.serverEntry, resolveSourceCodexHomeDir(deps.hostEnv), resolveCodexHomeSeams(deps.mcpJsonInjection));
+        return await prepareCodexHomeForRun(input.runId, input.mcpBridge.serverEntry, resolveSourceCodexHomeDir({ hostEnv: deps.hostEnv }), resolveCodexHomeSeams(deps.mcpJsonInjection));
     }
     catch (err) {
         await deps.releaseStagedResources();
-        return deps.failBeforeSpawn(input.runId, 'AGENT_SPAWN_FAILED', `AgentExecutor: could not stage a CODEX_HOME for agent "${input.def.id}": ${errorMessage(err)}`);
+        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: could not stage a CODEX_HOME for agent "${input.def.id}": ${errorMessage(err)}` });
     }
 }
 /**
@@ -2432,25 +2466,25 @@ export async function prepareCodexHomeIfNeeded(input, deps) {
  * @param deps.hostEnv - The daemon's own environment, threaded through to {@link resolveSourceClaudeConfigDir} rather than read from a module-level `process.env`, matching {@link prepareCodexHomeIfNeeded}'s identical testability reasoning.
  * @complexity O(1) plus {@link prepareClaudeConfigDirForRun}'s own cost.
  */
-export async function prepareClaudeConfigDirIfNeeded(input, deps) {
+export async function prepareClaudeConfigDirIfNeeded({ input, deps }) {
     if (input.def.id !== 'claude' || !deps.enabled) {
         return null;
     }
     try {
-        return await prepareClaudeConfigDirForRun(input.runId, resolveSourceClaudeConfigDir(deps.hostEnv), resolveClaudeConfigDirSeams(deps.claudeConfigDirIsolation));
+        return await prepareClaudeConfigDirForRun(input.runId, resolveSourceClaudeConfigDir({ hostEnv: deps.hostEnv }), resolveClaudeConfigDirSeams(deps.claudeConfigDirIsolation));
     }
     catch (err) {
         await deps.releaseStagedResources();
-        return deps.failBeforeSpawn(input.runId, 'AGENT_SPAWN_FAILED', `AgentExecutor: could not stage a CLAUDE_CONFIG_DIR for agent "${input.def.id}": ${errorMessage(err)}`);
+        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: could not stage a CLAUDE_CONFIG_DIR for agent "${input.def.id}": ${errorMessage(err)}` });
     }
 }
 /** 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(input.def, input.launchPath, input.args) ??
-        checkWindowsDirectExeCommandLineBudget(input.def, input.launchPath, input.args);
+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(input.runId, 'AGENT_PROMPT_TOO_LARGE', windowsBudgetError.message);
+        await deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_PROMPT_TOO_LARGE', message: windowsBudgetError.message });
     }
 }
 /**
@@ -2472,7 +2506,7 @@ export async function guardWindowsCommandLineBudget(input, deps) {
  * which are safe to make asynchronous since no child (and hence no listener race) exists yet.
  * @complexity O(1) plus `spawn`'s own cost.
  */
-export function spawnAgentChildProcess(input, deps) {
+export function spawnAgentChildProcess({ input, deps }) {
     try {
         return {
             kind: 'ok',
@@ -2489,27 +2523,28 @@ export function spawnAgentChildProcess(input, deps) {
     }
 }
 /** Named predicate replacing an inline `streamFormat === 'acp-json-rpc' || streamFormat === 'pi-rpc'` check — the two formats that own their own prompt/event protocol and skip `wireChildLifecycle`. */
-export function isStdinDrivenFormat(streamFormat) {
+export function isStdinDrivenFormat(args) {
+    const { streamFormat } = args;
     return streamFormat !== 'acp-json-rpc' && streamFormat !== 'pi-rpc';
 }
 /** Phase 13: awaits spawn confirmation, routing a failure through the same `failBeforeSpawn` shape every earlier guard uses. */
-export async function confirmChildSpawned(input, deps) {
+export async function confirmChildSpawned({ input, deps }) {
     try {
         await waitForSpawnOrError(input.child);
     }
     catch (err) {
         await deps.releaseStagedResources();
-        await deps.failBeforeSpawn(input.runId, 'AGENT_SPAWN_FAILED', `AgentExecutor: failed to spawn agent "${input.def.id}": ${errorMessage(err)}`);
+        await deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: failed to spawn agent "${input.def.id}": ${errorMessage(err)}` });
     }
 }
 /** Phase 14: starts a `runtimeLock` def's handoff watcher once a live process exists to consume the locked side effect — a no-op when the def declared no `waitForHandoff`. Deliberately not awaited; see `RuntimeLockHold.waitForHandoff`'s own doc. */
-export function armHandoffWatcher(runtimeLockHold, handoffInput, release) {
+export function armHandoffWatcher({ runtimeLockHold, handoffInput, release }) {
     if (!runtimeLockHold?.waitForHandoff)
         return;
     void runtimeLockHold.waitForHandoff(handoffInput).then(release, release);
 }
 /** Phase 15 (ACP branch): attaches the ACP session, escalating process-tree teardown and failing the run through `failBeforeSpawn` on an attach-time throw. */
-export async function runAcpDispatch(input, deps) {
+export async function runAcpDispatch({ input, deps }) {
     try {
         wireAcpLifecycle({
             runId: input.runId,
@@ -2541,11 +2576,11 @@ export async function runAcpDispatch(input, deps) {
         // fired-and-forgotten (SEC-007: "await where lifecycle ordering allows it").
         await terminateChildTreeBestEffort({ listProcessSnapshots: deps.listProcessSnapshots, collectProcessTreePids: deps.collectProcessTreePids, stopProcesses: deps.stopProcesses }, input.child, input.runId, 'acp-attach-failure', deps.onCleanupFailure);
         await deps.releaseStagedResources();
-        await deps.failBeforeSpawn(input.runId, 'AGENT_SPAWN_FAILED', `AgentExecutor: could not attach ACP session for agent "${input.agentId}": ${errorMessage(err)}`);
+        await deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: could not attach ACP session for agent "${input.agentId}": ${errorMessage(err)}` });
     }
 }
 /** Phase 15 (pi-rpc branch): same discipline as {@link runAcpDispatch}, for the one `'pi-rpc'` def. */
-export async function runPiRpcDispatch(input, deps) {
+export async function runPiRpcDispatch({ input, deps }) {
     try {
         wirePiRpcLifecycle({
             runId: input.runId,
@@ -2572,10 +2607,11 @@ export async function runPiRpcDispatch(input, deps) {
         // fire-and-forget (SEC-007).
         await terminateChildTreeBestEffort({ listProcessSnapshots: deps.listProcessSnapshots, collectProcessTreePids: deps.collectProcessTreePids, stopProcesses: deps.stopProcesses }, input.child, input.runId, 'pi-rpc-attach-failure', deps.onCleanupFailure);
         await deps.releaseStagedResources();
-        await deps.failBeforeSpawn(input.runId, 'AGENT_SPAWN_FAILED', `AgentExecutor: could not attach pi-rpc session for agent "${input.agentId}": ${errorMessage(err)}`);
+        await deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: could not attach pi-rpc session for agent "${input.agentId}": ${errorMessage(err)}` });
     }
 }
-export function createAgentExecutor(options) {
+export function createAgentExecutor(requiredArgs, optionalArgs = {}) {
+    const options = { ...requiredArgs, ...optionalArgs };
     const lifecycle = options.lifecycle;
     const { getAgentDef: getAgentDefFn, resolveAgentLaunch: resolveAgentLaunchFn, ensureAgentCapabilities: ensureAgentCapabilitiesFn, applyAgentLaunchEnv: applyAgentLaunchEnvFn, attachAcpSession: attachAcpSessionFn, attachPiRpcSession: attachPiRpcSessionFn, preparePromptFileForAgent: preparePromptFileForAgentFn, prepareAgentLogFile: prepareAgentLogFileFn, } = resolveAgentRuntimeDeps(options);
     const { createCommandInvocation: createCommandInvocationFn, spawn: spawnFn, listProcessSnapshots: listProcessSnapshotsFn, collectProcessTreePids: collectProcessTreePidsFn, stopProcesses: stopProcessesFn, } = resolveProcessDeps(options);
@@ -2599,16 +2635,16 @@ export function createAgentExecutor(options) {
      * @complexity O(1) plus `lifecycle.finish()`'s own cost.
      * @overallScore 100/100
      */
-    async function failBeforeSpawn(runId, code, message) {
+    async function failBeforeSpawn({ runId, code, message }) {
         // The reason goes on the run's own stream before `end`, not only into the thrown error: the
         // thrown error reaches the server log, while a chat client sees only this stream. Without it
         // the user got a bare "Run failed". Best-effort: a stream that will not take the event must not
         // stop the run from finishing.
         await lifecycle
-            .emit(runId, { event: 'error', data: { message: `The assistant could not start: ${message.replace(/^AgentExecutor:\s*/, '')}` } })
+            .emit({ runId: runId, input: { event: 'error', data: { message: `The assistant could not start: ${message.replace(/^AgentExecutor:\s*/, '')}` } } })
             .catch(() => undefined);
         await lifecycle.finish({ runId, status: 'failed', code: null, signal: null, resumable: false });
-        throw new AgentExecutorError(code, message);
+        throw new AgentExecutorError({ code: code, message: message });
     }
     /**
      * `AgentExecutor.run()` — see that interface method's own doc for the
@@ -2621,8 +2657,12 @@ export function createAgentExecutor(options) {
      * @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(input) {
-        const { def, streamFormat } = await resolveDefAndStreamFormat({ runId: input.runId, agentId: input.agentId }, { getAgentDef: getAgentDefFn, failBeforeSpawn });
+    async function run(requiredArgs, optionalArgs = {}) {
+        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`
@@ -2633,7 +2673,7 @@ export function createAgentExecutor(options) {
         // 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({ runId: input.runId, def, prompt: input.prompt, imagePaths: input.imagePaths, extraAllowedDirs: input.extraAllowedDirs }, { failBeforeSpawn });
+        const imageDelivery = await resolveImageDeliveryAndArgvBudget({ input: { runId: input.runId, def, prompt: input.prompt, imagePaths: input.imagePaths, extraAllowedDirs: input.extraAllowedDirs }, deps: { failBeforeSpawn } });
         // 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
@@ -2652,7 +2692,10 @@ export function createAgentExecutor(options) {
         // 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(null, null, null, input.resumeSessionId, input.newSessionId);
+        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 overlayDelivery = resolveSystemPromptOverlayDelivery({
             defId: def.id,
@@ -2666,14 +2709,14 @@ export function createAgentExecutor(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, process.env) };
-        const launch = await resolveLaunch({ runId: input.runId, def, resolvedEnv }, { resolveAgentLaunch: resolveAgentLaunchFn, failBeforeSpawn });
-        const spawnEnv = applyAgentLaunchEnvFn({ ...resolvedEnv }, launch);
+        const resolvedEnv = { ...(def.env ?? {}), ...resolveRunEnv({ input: input, hostEnv: process.env }) };
+        const launch = await resolveLaunch({ input: { runId: input.runId, def, resolvedEnv }, deps: { resolveAgentLaunch: resolveAgentLaunchFn, failBeforeSpawn } });
+        const spawnEnv = applyAgentLaunchEnvFn({ env: { ...resolvedEnv }, launch });
         // 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;
         // never rejects (a failed probe keeps the safe no-optional-flags baseline).
-        await ensureAgentCapabilitiesFn(def, launch.launchPath, spawnEnv);
+        await ensureAgentCapabilitiesFn({ def, launchPath: launch.launchPath, env: spawnEnv });
         // Stage a promptViaFile def's (grok-build) prompt to a temp file before buildArgs runs — its
         // buildArgs throws without runtimeContext.promptFilePath. A no-op (returns null) for every
         // def without promptViaFile: true (preparePromptFileForAgent's own guard).
@@ -2681,13 +2724,13 @@ export function createAgentExecutor(options) {
         // `overlayDelivery.prompt`, not `imageDelivery.prompt`: for a `promptViaFile` def this file IS
         // the prompt transport — its `buildArgs` declares `_prompt` and passes only the path — so the
         // overlay has to be in the bytes written here or the CLI never sees it at all.
-        const preparedPromptFile = await stagePromptFile({ runId: input.runId, def, prompt: overlayDelivery.prompt }, { preparePromptFileForAgent: preparePromptFileForAgentFn, failBeforeSpawn });
+        const preparedPromptFile = await stagePromptFile({ input: { runId: input.runId, def, prompt: overlayDelivery.prompt }, deps: { preparePromptFileForAgent: preparePromptFileForAgentFn, failBeforeSpawn } });
         // Stage a needsAgentLogFile def's (antigravity) diagnostic-log path, on the same terms and at
         // the same point as the prompt file above: before buildArgs, since buildArgs is what turns the
         // path into a `--log-file <path>` argument. A no-op (returns null) for every def without
         // `needsAgentLogFile: true` (prepareAgentLogFile's own guard). Sequenced after the prompt file
         // rather than concurrently so the failure path above has exactly one thing to clean up.
-        const preparedLogFile = await stageLogFile({ runId: input.runId, def, preparedPromptFile }, { prepareAgentLogFile: prepareAgentLogFileFn, failBeforeSpawn });
+        const preparedLogFile = await stageLogFile({ input: { runId: input.runId, def, preparedPromptFile }, deps: { prepareAgentLogFile: prepareAgentLogFileFn, failBeforeSpawn } });
         // Cleaned up after the child exits (wireChildLifecycle/wireAcpLifecycle/wirePiRpcLifecycle's
         // close handlers) and on every pre-spawn/spawn-failure path below — a leaked temp file
         // containing the full prompt, or whatever the CLI chose to write into its log, is a
@@ -2732,7 +2775,7 @@ export function createAgentExecutor(options) {
             if (writtenMcpJsonPath !== undefined) {
                 const mcpJsonFileToRemove = writtenMcpJsonPath;
                 writtenMcpJsonPath = undefined;
-                await removeMcpJsonFileFn(mcpJsonFileToRemove);
+                await removeMcpJsonFileFn({ path: mcpJsonFileToRemove });
             }
             if (preparedCodexHome) {
                 const codexHomeToRemove = preparedCodexHome;
@@ -2755,8 +2798,11 @@ export function createAgentExecutor(options) {
         // resolving here means the per-run bearer credential is minted exactly once no matter which of
         // 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({ runId: input.runId, cwd: input.cwd, def }, { mcpJsonInjection, cleanupStagedFiles, failBeforeSpawn });
-        const runtimeContext = computeRuntimeContext(preparedPromptFile, preparedLogFile, mcpBridge, input.resumeSessionId, input.newSessionId);
+        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 }),
+        });
         // 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
@@ -2787,60 +2833,65 @@ export function createAgentExecutor(options) {
         // `Error` — breaking this driver's "never a bare throw, always an `AgentExecutorError`" contract
         // — and left the run `'running'` forever while still holding the process-global mutex and both
         // staged files, so no later run of that def could ever acquire the lock either.
-        const { args, envOverrides: systemPromptEnvOverrides } = await buildRunArgs({ runId: input.runId, def, imageDelivery, imagePaths: input.imagePaths, runInput: input, systemPromptOverlay, overlayDelivery, runtimeContext }, { releaseStagedResources, failBeforeSpawn });
+        const { args, envOverrides: systemPromptEnvOverrides } = await buildRunArgs({ input: { runId: input.runId, def, imageDelivery, imagePaths: input.imagePaths, runInput: input, systemPromptOverlay, overlayDelivery, runtimeContext }, deps: { releaseStagedResources, failBeforeSpawn } });
         // Mechanism 1 of 5's one effect — stage this run's own MCP config file (run-scoped, see
         // `mcpJsonPathForRun`) before spawn so the `--mcp-config <path>` argv buildArgs just produced
         // 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({ runId: input.runId, cwd: input.cwd, def, mcpBridge }, { mcpJsonInjection, releaseStagedResources, failBeforeSpawn });
+        writtenMcpJsonPath = await writeMcpJsonIfNeeded({ input: { runId: input.runId, cwd: input.cwd, 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({ runId: input.runId, def, mcpBridge }, { mcpJsonInjection, hostEnv: process.env, releaseStagedResources, failBeforeSpawn });
+        preparedCodexHome = await prepareCodexHomeIfNeeded({ input: { runId: input.runId, def, mcpBridge }, deps: { mcpJsonInjection, hostEnv: process.env, 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
         // `prepareClaudeConfigDirIfNeeded`'s own doc for why). Placed here only to stay adjacent to the
         // other pre-`computeChildEnv` staging steps; `claude.ts`'s `buildArgs` needs no argv change for
         // this (CLAUDE_CONFIG_DIR is an env var, not a flag), same as CODEX_HOME.
-        preparedClaudeConfigDir = await prepareClaudeConfigDirIfNeeded({ runId: input.runId, def }, {
-            enabled: claudeConfigDirIsolationEnabled,
-            claudeConfigDirIsolation,
-            hostEnv: process.env,
-            releaseStagedResources,
-            failBeforeSpawn,
-        });
+        preparedClaudeConfigDir = await prepareClaudeConfigDirIfNeeded({ input: { runId: input.runId, def }, deps: {
+                enabled: claudeConfigDirIsolationEnabled,
+                claudeConfigDirIsolation,
+                hostEnv: process.env,
+                releaseStagedResources,
+                failBeforeSpawn,
+            } });
         // `'config-instructions-file'`'s one effect — stage the overlay to a temp file so
         // `computeChildEnv` below has a real path to merge into that def's `instructions` array. A
         // no-op (`null`) for every other def/strategy or a run with no overlay at all. Independent of
         // `mcpBridge`/`preparedCodexHome` above (a different strategy field entirely), so placed here
         // only to stay adjacent to the other pre-`computeChildEnv` staging steps, not for any ordering
         // requirement between them.
-        preparedSystemPromptOverlayFile = await prepareSystemPromptOverlayFileIfNeeded({ runId: input.runId, def, overlay: systemPromptOverlay }, { releaseStagedResources, failBeforeSpawn });
+        preparedSystemPromptOverlayFile = await prepareSystemPromptOverlayFileIfNeeded({ input: { runId: input.runId, def, overlay: systemPromptOverlay }, deps: { releaseStagedResources, failBeforeSpawn } });
         // Computed only now, not right after `mcpBridge` resolution: mechanism 5's directory path is
         // not known until the staging step directly above actually runs `mkdtemp` (see
         // `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, mcpBridge, preparedCodexHome?.path, systemPromptEnvOverrides, preparedSystemPromptOverlayFile && def.systemPromptDelivery?.strategy === 'config-instructions-file'
-            ? { varName: def.systemPromptDelivery.varName, path: preparedSystemPromptOverlayFile.path }
-            : undefined, preparedClaudeConfigDir?.path);
+        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 }),
+        });
         // 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
         // quote-escaped. Both are no-ops off-Windows / for non-argv-bound defs.
-        await guardWindowsCommandLineBudget({ runId: input.runId, def, launchPath: launch.launchPath, args }, { releaseStagedResources, failBeforeSpawn });
+        await guardWindowsCommandLineBudget({ input: { runId: input.runId, def, launchPath: launch.launchPath, args }, deps: { releaseStagedResources, failBeforeSpawn } });
         const invocation = createCommandInvocationFn({ command: launch.launchPath, args, env: childEnv });
         // Kept a synchronous call (no `await`) on purpose — see `spawnAgentChildProcess`'s own doc for
         // the microtask-timing race this avoids. The error branch's own cleanup/failBeforeSpawn calls are
         // async, which is fine: no child exists yet on that path, so nothing is racing a listener.
-        const spawnResult = spawnAgentChildProcess({ cwd: input.cwd, childEnv, invocation }, { spawn: spawnFn });
+        const spawnResult = spawnAgentChildProcess({ input: { cwd: input.cwd, childEnv, invocation }, deps: { spawn: spawnFn } });
         if (spawnResult.kind === 'error') {
             await releaseStagedResources();
-            return failBeforeSpawn(input.runId, 'AGENT_SPAWN_FAILED', `AgentExecutor: spawn threw synchronously for agent "${def.id}": ${errorMessage(spawnResult.error)}`);
+            return failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: spawn threw synchronously for agent "${def.id}": ${errorMessage(spawnResult.error)}` });
         }
         const child = spawnResult.child;
         // Registered before the spawn-confirmation await below, for the same reason
@@ -2850,11 +2901,12 @@ export function createAgentExecutor(options) {
         // 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 stdinHandle = isStdinDrivenFormat(streamFormat)
+        const formatForStdin = { streamFormat };
+        const stdinHandle = isStdinDrivenFormat(formatForStdin)
             ? wireChildLifecycle({
                 runId: input.runId,
                 def,
-                streamFormat,
+                streamFormat: formatForStdin.streamFormat,
                 child,
                 lifecycle,
                 listProcessSnapshots: listProcessSnapshotsFn,
@@ -2866,75 +2918,76 @@ export function createAgentExecutor(options) {
                 continuation,
                 classifyFailure,
                 bufferedStdoutMaxBytes,
+                expectsJiniBridge: writtenMcpJsonPath !== undefined,
             })
             : null;
-        await confirmChildSpawned({ runId: input.runId, def, child }, { releaseStagedResources, failBeforeSpawn });
+        await confirmChildSpawned({ input: { runId: input.runId, def, child }, deps: { releaseStagedResources, failBeforeSpawn } });
         // Now — and only now — is there a live process that could consume the locked side effect, so
         // this is where a def's handoff watcher starts. Deliberately not awaited: the whole point is to
         // release the lock as soon as the child confirms the handoff, in parallel with this run
         // continuing. Rejection releases too — a lock stuck open because a watcher threw is strictly
         // worse than releasing early (see `RuntimeLockHold.waitForHandoff`'s own doc).
-        armHandoffWatcher(runtimeLockHold, { logFilePath: preparedLogFile?.path, model: selectedModel, processExited: processExitedController.signal }, releaseRuntimeLock);
+        armHandoffWatcher({ runtimeLockHold: runtimeLockHold, handoffInput: { logFilePath: preparedLogFile?.path, model: selectedModel, processExited: processExitedController.signal }, release: releaseRuntimeLock });
         if (streamFormat === 'acp-json-rpc') {
-            await runAcpDispatch({
-                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,
-                model: input.model,
-                imagePaths: input.imagePaths ?? [],
-                envFormat: def.acpMcpEnvFormat,
-                mcpBridge,
-            }, {
-                lifecycle,
-                attachAcpSession: attachAcpSessionFn,
-                onPermissionRequest: options.acpPermissionHandler,
-                listProcessSnapshots: listProcessSnapshotsFn,
-                collectProcessTreePids: collectProcessTreePidsFn,
-                stopProcesses: stopProcessesFn,
-                onCleanupFailure: onCleanupFailureFn,
-                cleanupStagedFiles,
-                journal,
-                classifyFailure,
-                releaseStagedResources,
-                failBeforeSpawn,
-            });
+            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,
+                    model: input.model,
+                    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;
         }
         if (streamFormat === 'pi-rpc') {
-            await runPiRpcDispatch({
-                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,
-                imagePaths: input.imagePaths ?? [],
-                uploadRoot: input.uploadRoot,
-            }, {
-                lifecycle,
-                attachPiRpcSession: attachPiRpcSessionFn,
-                listProcessSnapshots: listProcessSnapshotsFn,
-                collectProcessTreePids: collectProcessTreePidsFn,
-                stopProcesses: stopProcessesFn,
-                onCleanupFailure: onCleanupFailureFn,
-                cleanupStagedFiles,
-                journal,
-                classifyFailure,
-                releaseStagedResources,
-                failBeforeSpawn,
-            });
+            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,
+                    imagePaths: input.imagePaths ?? [],
+                    uploadRoot: input.uploadRoot,
+                }, deps: {
+                    lifecycle,
+                    attachPiRpcSession: attachPiRpcSessionFn,
+                    listProcessSnapshots: listProcessSnapshotsFn,
+                    collectProcessTreePids: collectProcessTreePidsFn,
+                    stopProcesses: stopProcessesFn,
+                    onCleanupFailure: onCleanupFailureFn,
+                    cleanupStagedFiles,
+                    journal,
+                    classifyFailure,
+                    releaseStagedResources,
+                    failBeforeSpawn,
+                } });
             return;
         }
         // The overlay reaches stdin only for a def that declares stdin as its prompt transport. The