wind-agent-cli 1.37.2

package/server/modules/providers/list/opencode/opencode-runtime.provider.js

@@ -0,0 +1,434 @@
+import fsSync from 'node:fs';
+
+import crossSpawn from 'cross-spawn';
+import Database from 'better-sqlite3';
+
+import {
+  appendFilesInputTag,
+  appendImagesInputTag,
+  normalizeAttachmentDescriptors
+} from '@/shared/image-attachments.js';
+import { notifyRunFailed, notifyRunStopped } from '@/modules/notifications/index.js';
+import { createCompleteMessage, createNormalizedMessage, flattenPromptForWindowsShell, getOpenCodeDatabasePath } from '@/shared/utils.js';
+
+// cross-spawn resolves .cmd shims/PATHEXT on Windows and delegates to
+// child_process.spawn everywhere else.
+const spawnFunction = crossSpawn;
+
+const activeOpenCodeProcesses = new Map();
+
+/**
+ * Maps the UI permission mode onto OpenCode's non-interactive controls.
+ *
+ * OpenCode has no single "permission mode" flag; each mode uses a different
+ * lever of the `opencode run` CLI (verified against v1.17.13):
+ * - plan              → the built-in read-only `plan` agent (`--agent plan`).
+ * - bypassPermissions → `--auto`, which auto-approves every permission that
+ *                       is not explicitly denied in the user's config.
+ * - acceptEdits       → the OPENCODE_PERMISSION env var, whose JSON body the
+ *                       CLI merges into its permission config. Forcing
+ *                       `edit: allow` guarantees file edits go through while
+ *                       every other rule stays under the user's own config.
+ * - default           → nothing; the user's opencode.json governs. In
+ *                       non-interactive `run` mode any `ask` rule is denied.
+ *
+ * Exported for tests only.
+ */
+export function resolveOpenCodePermissionOptions(permissionMode) {
+  switch (permissionMode) {
+    case 'plan':
+      return { args: ['--agent', 'plan'], env: {} };
+    case 'bypassPermissions':
+      return { args: ['--auto'], env: {} };
+    case 'acceptEdits':
+      return { args: [], env: { OPENCODE_PERMISSION: JSON.stringify({ edit: 'allow' }) } };
+    default:
+      return { args: [], env: {} };
+  }
+}
+
+function resolveOpenCodeEffort(model, effort, modelsDefinition) {
+  const selectedModel = modelsDefinition?.OPTIONS?.find((option) => option.value === model);
+  const allowedEfforts = selectedModel?.effort?.values?.map((value) => value.value) || [];
+  return typeof effort === 'string' && effort !== 'default' && allowedEfforts.includes(effort)
+    ? effort
+    : undefined;
+}
+
+function readOpenCodeSessionId(event) {
+  if (!event || typeof event !== 'object') {
+    return null;
+  }
+
+  return event.sessionID || event.sessionId || null;
+}
+
+function readOpenCodeTokenUsage(sessionId) {
+  const dbPath = getOpenCodeDatabasePath();
+  if (!sessionId || !fsSync.existsSync(dbPath)) {
+    return null;
+  }
+
+  let db = null;
+  try {
+    db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    const columns = db.prepare('PRAGMA table_info(session)').all();
+    const columnNames = new Set(columns.map((column) => column.name));
+    const requiredColumns = ['tokens_input', 'tokens_output', 'tokens_reasoning', 'tokens_cache_read', 'tokens_cache_write'];
+    if (!requiredColumns.every((column) => columnNames.has(column))) {
+      return null;
+    }
+
+    const row = db.prepare(`
+      SELECT
+        tokens_input AS inputTokens,
+        tokens_output AS outputTokens,
+        tokens_reasoning AS reasoningTokens,
+        tokens_cache_read AS cacheReadTokens,
+        tokens_cache_write AS cacheWriteTokens
+      FROM session
+      WHERE id = ?
+    `).get(sessionId);
+
+    if (!row) {
+      return null;
+    }
+
+    const inputTokens = Number(row.inputTokens || 0) + Number(row.cacheReadTokens || 0);
+    const outputTokens = Number(row.outputTokens || 0);
+    const used = Number(row.inputTokens || 0)
+      + outputTokens
+      + Number(row.reasoningTokens || 0)
+      + Number(row.cacheReadTokens || 0)
+      + Number(row.cacheWriteTokens || 0);
+    if (used <= 0) {
+      return null;
+    }
+
+    return {
+      used,
+      inputTokens,
+      outputTokens,
+      breakdown: {
+        input: inputTokens,
+        output: outputTokens,
+      },
+    };
+  } catch {
+    return null;
+  } finally {
+    if (db) {
+      db.close();
+    }
+  }
+}
+
+async function spawnOpenCode(command, options = {}, ws, context) {
+  return new Promise((resolve, reject) => {
+    const {
+      sessionId,
+      projectPath,
+      cwd,
+      model,
+      effort,
+      sessionSummary,
+      images,
+      files,
+      permissionMode
+    } = options;
+    // Callers pass the stable app session id; the CLI resumes with the
+    // provider-native id recorded on the session row.
+    const providerSessionId = context.resolveProviderSessionId(sessionId);
+    const workingDir = cwd || projectPath || process.cwd();
+    // Process-map key: the app session id when the caller supplied one, so
+    // abort-by-app-id always works.
+    const processKey = sessionId || Date.now().toString();
+    let capturedSessionId = providerSessionId;
+    let sessionCreatedSent = false;
+    let stdoutLineBuffer = '';
+    let terminalNotificationSent = false;
+    let opencodeProcess = null;
+    // Unified lifecycle contract: exactly one terminal `complete` per run
+    // (close and error handlers can both fire for spawn failures).
+    let completeSent = false;
+
+    const notifyTerminalState = ({ code = null, error = null } = {}) => {
+      if (terminalNotificationSent) {
+        return;
+      }
+
+      terminalNotificationSent = true;
+      // Notifications are app-facing, so they carry the app session id.
+      const finalSessionId = sessionId || capturedSessionId || processKey;
+      if (code === 0 && !error) {
+        notifyRunStopped({
+          userId: ws?.userId || null,
+          provider: 'opencode',
+          sessionId: finalSessionId,
+          sessionName: sessionSummary,
+          stopReason: 'completed',
+        });
+        return;
+      }
+
+      notifyRunFailed({
+        userId: ws?.userId || null,
+        provider: 'opencode',
+        sessionId: finalSessionId,
+        sessionName: sessionSummary,
+        error: error || `OpenCode CLI exited with code ${code}`,
+      });
+    };
+
+    const registerSession = (nextSessionId) => {
+      if (!nextSessionId || capturedSessionId === nextSessionId) {
+        return;
+      }
+
+      capturedSessionId = nextSessionId;
+      // Legacy/direct callers without an app session id re-key the process
+      // under the provider-native id once it is known.
+      if (!sessionId && processKey !== capturedSessionId && opencodeProcess) {
+        activeOpenCodeProcesses.delete(processKey);
+        activeOpenCodeProcesses.set(capturedSessionId, opencodeProcess);
+      }
+      if (opencodeProcess) {
+        opencodeProcess.sessionId = capturedSessionId;
+      }
+
+      if (ws.setSessionId && typeof ws.setSessionId === 'function') {
+        ws.setSessionId(capturedSessionId);
+      }
+
+      if (!providerSessionId && !sessionCreatedSent) {
+        sessionCreatedSent = true;
+        ws.send(createNormalizedMessage({
+          kind: 'session_created',
+          newSessionId: capturedSessionId,
+          sessionId: capturedSessionId,
+          provider: 'opencode',
+        }));
+      }
+    };
+
+    const processOpenCodeOutputLine = (line) => {
+      if (!line || !line.trim()) {
+        return;
+      }
+
+      let response;
+      try {
+        response = JSON.parse(line);
+      } catch {
+        ws.send(createNormalizedMessage({
+          kind: 'stream_delta',
+          content: line,
+          sessionId: capturedSessionId || sessionId || null,
+          provider: 'opencode',
+        }));
+        return;
+      }
+
+      try {
+        registerSession(readOpenCodeSessionId(response));
+        const normalized = context.normalizeMessage(response, capturedSessionId || sessionId || null);
+        for (const msg of normalized) {
+          ws.send(msg);
+        }
+      } catch (error) {
+        const errorContent = error instanceof Error ? error.message : String(error);
+        console.error('[OpenCode] Failed to process JSON output:', errorContent);
+        ws.send(createNormalizedMessage({
+          kind: 'error',
+          content: errorContent,
+          sessionId: capturedSessionId || sessionId || null,
+          provider: 'opencode',
+        }));
+      }
+    };
+
+    void context.resolveResumeModel(sessionId, model).then(async (resolvedModel) => {
+      let effortModels = null;
+      try {
+        effortModels = await context.getProviderModels();
+      } catch (error) {
+        console.warn('[OpenCode] Unable to load provider models for effort validation:', error);
+      }
+
+      const resolvedEffort = resolveOpenCodeEffort(resolvedModel, effort, effortModels);
+      const args = ['run', '--format', 'json'];
+      // OpenCode's `run` command owns workspace selection through `--dir`.
+      // Relying on the child-process cwd alone is not enough on Linux, where
+      // the CLI can still resolve the session under the server install dir.
+      args.push('--dir', workingDir);
+      if (providerSessionId) {
+        args.push('--session', providerSessionId);
+      }
+      if (resolvedModel) {
+        args.push('--model', resolvedModel);
+      }
+      if (resolvedEffort) {
+        args.push('--variant', resolvedEffort);
+      }
+      const permissionOptions = resolveOpenCodePermissionOptions(permissionMode);
+      args.push(...permissionOptions.args);
+      const hasAttachments =
+        normalizeAttachmentDescriptors(images).length > 0
+        || normalizeAttachmentDescriptors(files).length > 0;
+      if ((command && command.trim()) || hasAttachments) {
+        // Image attachments ride along as an <images_input> path list appended
+        // to the prompt; the session history reader strips the tag back out.
+        // opencode is a .cmd shim on Windows, so the whole argument must be
+        // newline-free or cmd.exe silently truncates it at the first newline.
+        const promptWithAttachments = appendFilesInputTag(
+          appendImagesInputTag(command?.trim() || '', images),
+          files
+        );
+        args.push(flattenPromptForWindowsShell(promptWithAttachments));
+      }
+
+      opencodeProcess = spawnFunction('opencode', args, {
+        cwd: workingDir,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: { ...process.env, ...permissionOptions.env },
+      });
+
+      activeOpenCodeProcesses.set(processKey, opencodeProcess);
+      opencodeProcess.sessionId = processKey;
+      opencodeProcess.stdin.end();
+
+      opencodeProcess.stdout.on('data', (data) => {
+        stdoutLineBuffer += data.toString();
+        const completeLines = stdoutLineBuffer.split(/\r?\n/);
+        stdoutLineBuffer = completeLines.pop() || '';
+
+        completeLines.forEach((line) => {
+          processOpenCodeOutputLine(line.trim());
+        });
+      });
+
+      opencodeProcess.stderr.on('data', (data) => {
+        const stderrText = data.toString();
+        if (!stderrText.trim()) {
+          return;
+        }
+
+        ws.send(createNormalizedMessage({
+          kind: 'error',
+          content: stderrText,
+          sessionId: capturedSessionId || sessionId || null,
+          provider: 'opencode',
+        }));
+      });
+
+      opencodeProcess.on('close', async (code) => {
+        const finalSessionId = sessionId || capturedSessionId || processKey;
+        activeOpenCodeProcesses.delete(finalSessionId);
+        activeOpenCodeProcesses.delete(processKey);
+
+        if (stdoutLineBuffer.trim()) {
+          processOpenCodeOutputLine(stdoutLineBuffer.trim());
+          stdoutLineBuffer = '';
+        }
+
+        // OpenCode's own database is keyed by the provider-native id.
+        const tokenBudget = readOpenCodeTokenUsage(capturedSessionId);
+        if (tokenBudget) {
+          ws.send(createNormalizedMessage({
+            kind: 'status',
+            text: 'token_budget',
+            tokenBudget,
+            sessionId: finalSessionId,
+            provider: 'opencode',
+          }));
+        }
+
+        // Terminal complete — skipped for aborted runs (abort-session
+        // already sent the aborted complete on this run's behalf).
+        if (!completeSent && !opencodeProcess.aborted) {
+          completeSent = true;
+          ws.send(createCompleteMessage({ provider: 'opencode', sessionId: finalSessionId, exitCode: code }));
+        }
+
+        if (code === 0) {
+          notifyTerminalState({ code });
+          resolve();
+          return;
+        }
+
+        if (code === 127 || code === null) {
+          const installed = await context.isProviderInstalled();
+          if (!installed) {
+            ws.send(createNormalizedMessage({
+              kind: 'error',
+              content: 'OpenCode CLI is not installed. Install it from https://opencode.ai/docs/',
+              sessionId: finalSessionId,
+              provider: 'opencode',
+            }));
+          }
+        }
+
+        notifyTerminalState({ code });
+        reject(new Error(code === null ? 'OpenCode CLI process was terminated' : `OpenCode CLI exited with code ${code}`));
+      });
+
+      opencodeProcess.on('error', async (error) => {
+        const finalSessionId = sessionId || capturedSessionId || processKey;
+        activeOpenCodeProcesses.delete(finalSessionId);
+        activeOpenCodeProcesses.delete(processKey);
+
+        const installed = await context.isProviderInstalled();
+        const errorContent = !installed
+          ? 'OpenCode CLI is not installed. Install it from https://opencode.ai/docs/'
+          : error.message;
+
+        ws.send(createNormalizedMessage({
+          kind: 'error',
+          content: errorContent,
+          sessionId: finalSessionId,
+          provider: 'opencode',
+        }));
+        if (!completeSent && !opencodeProcess.aborted) {
+          completeSent = true;
+          ws.send(createCompleteMessage({ provider: 'opencode', sessionId: finalSessionId, exitCode: 1 }));
+        }
+        notifyTerminalState({ error });
+        reject(error);
+      });
+    }).catch(reject);
+  });
+}
+
+function abortOpenCodeSession(sessionId) {
+  const process = activeOpenCodeProcesses.get(sessionId);
+  if (!process) {
+    return false;
+  }
+
+  // The abort handler sends the terminal complete (aborted: true); flag the
+  // process so its close handler does not emit a second one.
+  process.aborted = true;
+  process.kill('SIGTERM');
+  activeOpenCodeProcesses.delete(sessionId);
+  return true;
+}
+
+function isOpenCodeSessionActive(sessionId) {
+  return activeOpenCodeProcesses.has(sessionId);
+}
+
+function getActiveOpenCodeSessions() {
+  return Array.from(activeOpenCodeProcesses.keys());
+}
+
+export const opencodeRuntime = {
+  run: spawnOpenCode,
+  abort: abortOpenCodeSession,
+};
+
+export {
+  spawnOpenCode,
+  abortOpenCodeSession,
+  isOpenCodeSessionActive,
+  getActiveOpenCodeSessions,
+};

package/server/modules/providers/list/opencode/opencode-runtime.provider.test.js

@@ -0,0 +1,261 @@
+import assert from 'node:assert/strict';
+import { chmod, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import {
+  opencodeRuntime,
+  resolveOpenCodePermissionOptions,
+} from './opencode-runtime.provider.js';
+import { OpenCodeSessionsProvider } from './opencode-sessions.provider.js';
+
+const sessionsProvider = new OpenCodeSessionsProvider();
+const runtimeContext = {
+  resolveProviderSessionId: (sessionId) => sessionId || null,
+  resolveResumeModel: async (_sessionId, requestedModel) => requestedModel || undefined,
+  getProviderModels: async () => ({ OPTIONS: [], DEFAULT: '' }),
+  normalizeMessage: (raw, sessionId) => sessionsProvider.normalizeMessage(raw, sessionId),
+  isProviderInstalled: async () => true,
+};
+
+const findEnvKey = (name) =>
+  Object.keys(process.env).find((key) => key.toLowerCase() === name.toLowerCase()) || name;
+
+async function createFakeOpenCodeExecutable(binDir) {
+  const scriptPath = path.join(binDir, 'opencode.js');
+  await writeFile(scriptPath, `
+const capturePath = process.env.OPENCODE_ARGS_CAPTURE;
+if (capturePath) {
+  require('node:fs').writeFileSync(capturePath, JSON.stringify({
+    args: process.argv.slice(2),
+    permissionEnv: process.env.OPENCODE_PERMISSION ?? null,
+  }));
+}
+
+const events = [
+  { type: 'text', sessionID: 'open-live-1', text: 'assistant response' },
+  { type: 'step_finish', sessionID: 'open-live-1' },
+];
+
+for (const event of events) {
+  console.log(JSON.stringify(event));
+}
+`, 'utf8');
+
+  if (process.platform === 'win32') {
+    const commandPath = path.join(binDir, 'opencode.cmd');
+    await writeFile(commandPath, '@echo off\r\nnode "%~dp0opencode.js" %*\r\n', 'utf8');
+    return;
+  }
+
+  const commandPath = path.join(binDir, 'opencode');
+  await writeFile(commandPath, '#!/bin/sh\nnode "$(dirname "$0")/opencode.js" "$@"\n', 'utf8');
+  await chmod(commandPath, 0o755);
+}
+
+test('spawnOpenCode emits session_created before normalized live messages for new sessions', async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'opencode-cli-live-'));
+  const argsCapturePath = path.join(tempRoot, 'opencode-args.json');
+  const pathKey = findEnvKey('PATH');
+  const pathExtKey = findEnvKey('PATHEXT');
+  const previousPath = process.env[pathKey];
+  const previousPathExt = process.env[pathExtKey];
+  const previousArgsCapture = process.env.OPENCODE_ARGS_CAPTURE;
+  const messages = [];
+  const writer = {
+    userId: null,
+    sessionId: null,
+    send(message) {
+      messages.push(message);
+    },
+    setSessionId(sessionId) {
+      this.sessionId = sessionId;
+    },
+  };
+
+  try {
+    await createFakeOpenCodeExecutable(tempRoot);
+    process.env[pathKey] = `${tempRoot}${path.delimiter}${previousPath || ''}`;
+    process.env.OPENCODE_ARGS_CAPTURE = argsCapturePath;
+    if (process.platform === 'win32') {
+      process.env[pathExtKey] = previousPathExt?.toUpperCase().includes('.CMD')
+        ? previousPathExt
+        : `.COM;.EXE;.BAT;.CMD${previousPathExt ? `;${previousPathExt}` : ''}`;
+    }
+
+    await opencodeRuntime.run('Hi', { cwd: tempRoot }, writer, runtimeContext);
+
+    const sessionCreatedIndex = messages.findIndex((message) => message.kind === 'session_created');
+    const assistantDeltaIndex = messages.findIndex((message) =>
+      message.kind === 'stream_delta' && message.content === 'assistant response',
+    );
+    const streamEnd = messages.find((message) => message.kind === 'stream_end');
+    const complete = messages.find((message) => message.kind === 'complete');
+
+    assert.notEqual(sessionCreatedIndex, -1);
+    assert.notEqual(assistantDeltaIndex, -1);
+    assert.ok(sessionCreatedIndex < assistantDeltaIndex);
+    assert.equal(messages[sessionCreatedIndex].newSessionId, 'open-live-1');
+    assert.equal(writer.sessionId, 'open-live-1');
+    assert.equal(streamEnd?.sessionId, 'open-live-1');
+    assert.equal(complete?.sessionId, 'open-live-1');
+    assert.equal(messages.some((message) => message.kind === 'error'), false);
+
+    const capture = JSON.parse(await readFile(argsCapturePath, 'utf8'));
+    const launchedArgs = capture.args;
+    assert.ok(Array.isArray(launchedArgs));
+    assert.deepEqual(launchedArgs.slice(0, 4), ['run', '--format', 'json', '--dir']);
+    assert.equal(launchedArgs[4], tempRoot);
+    // No permission mode requested → no permission flags and no env override.
+    assert.equal(launchedArgs.includes('--auto'), false);
+    assert.equal(launchedArgs.includes('--agent'), false);
+    assert.equal(capture.permissionEnv, null);
+
+    const attachmentOnlyCapturePath = path.join(tempRoot, 'opencode-attachment-only.json');
+    process.env.OPENCODE_ARGS_CAPTURE = attachmentOnlyCapturePath;
+    await opencodeRuntime.run(
+      '',
+      {
+        cwd: tempRoot,
+        files: [{
+          path: path.join(tempRoot, 'brief.pdf'),
+          name: 'brief.pdf',
+          mimeType: 'application/pdf',
+        }],
+      },
+      writer,
+      runtimeContext,
+    );
+    const attachmentOnlyCapture = JSON.parse(await readFile(attachmentOnlyCapturePath, 'utf8'));
+    const attachmentPrompt = attachmentOnlyCapture.args[attachmentOnlyCapture.args.length - 1];
+    assert.match(attachmentPrompt, /<files_input>/);
+    assert.match(attachmentPrompt, /brief\.pdf/);
+  } finally {
+    if (previousPath === undefined) {
+      delete process.env[pathKey];
+    } else {
+      process.env[pathKey] = previousPath;
+    }
+
+    if (previousPathExt === undefined) {
+      delete process.env[pathExtKey];
+    } else {
+      process.env[pathExtKey] = previousPathExt;
+    }
+
+    if (previousArgsCapture === undefined) {
+      delete process.env.OPENCODE_ARGS_CAPTURE;
+    } else {
+      process.env.OPENCODE_ARGS_CAPTURE = previousArgsCapture;
+    }
+
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+test('resolveOpenCodePermissionOptions maps UI permission modes onto OpenCode controls', () => {
+  assert.deepEqual(resolveOpenCodePermissionOptions('plan'), {
+    args: ['--agent', 'plan'],
+    env: {},
+  });
+  assert.deepEqual(resolveOpenCodePermissionOptions('bypassPermissions'), {
+    args: ['--auto'],
+    env: {},
+  });
+  assert.deepEqual(resolveOpenCodePermissionOptions('acceptEdits'), {
+    args: [],
+    env: { OPENCODE_PERMISSION: '{"edit":"allow"}' },
+  });
+  // default and anything unknown leave the user's own opencode config in charge.
+  assert.deepEqual(resolveOpenCodePermissionOptions('default'), { args: [], env: {} });
+  assert.deepEqual(resolveOpenCodePermissionOptions(undefined), { args: [], env: {} });
+});
+
+test('spawnOpenCode passes permission mode flags and env to the CLI', async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'opencode-cli-perms-'));
+  const pathKey = findEnvKey('PATH');
+  const pathExtKey = findEnvKey('PATHEXT');
+  const previousPath = process.env[pathKey];
+  const previousPathExt = process.env[pathExtKey];
+  const previousArgsCapture = process.env.OPENCODE_ARGS_CAPTURE;
+  const writer = {
+    userId: null,
+    sessionId: null,
+    send() {},
+    setSessionId(sessionId) {
+      this.sessionId = sessionId;
+    },
+  };
+
+  try {
+    await createFakeOpenCodeExecutable(tempRoot);
+    process.env[pathKey] = `${tempRoot}${path.delimiter}${previousPath || ''}`;
+    if (process.platform === 'win32') {
+      process.env[pathExtKey] = previousPathExt?.toUpperCase().includes('.CMD')
+        ? previousPathExt
+        : `.COM;.EXE;.BAT;.CMD${previousPathExt ? `;${previousPathExt}` : ''}`;
+    }
+
+    const scenarios = [
+      {
+        permissionMode: 'plan',
+        expectArgs: ['--agent', 'plan'],
+        expectPermissionEnv: null,
+      },
+      {
+        permissionMode: 'bypassPermissions',
+        expectArgs: ['--auto'],
+        expectPermissionEnv: null,
+      },
+      {
+        permissionMode: 'acceptEdits',
+        expectArgs: [],
+        expectPermissionEnv: '{"edit":"allow"}',
+      },
+    ];
+
+    for (const scenario of scenarios) {
+      const argsCapturePath = path.join(tempRoot, `opencode-args-${scenario.permissionMode}.json`);
+      process.env.OPENCODE_ARGS_CAPTURE = argsCapturePath;
+
+      await opencodeRuntime.run(
+        'Hi',
+        { cwd: tempRoot, permissionMode: scenario.permissionMode },
+        writer,
+        runtimeContext,
+      );
+
+      const capture = JSON.parse(await readFile(argsCapturePath, 'utf8'));
+      for (const expectedArg of scenario.expectArgs) {
+        assert.ok(
+          capture.args.includes(expectedArg),
+          `${scenario.permissionMode}: expected "${expectedArg}" in ${JSON.stringify(capture.args)}`,
+        );
+      }
+      // The prompt stays the last positional argument, after any permission flags.
+      assert.equal(capture.args[capture.args.length - 1], 'Hi');
+      assert.equal(capture.permissionEnv, scenario.expectPermissionEnv);
+    }
+  } finally {
+    if (previousPath === undefined) {
+      delete process.env[pathKey];
+    } else {
+      process.env[pathKey] = previousPath;
+    }
+
+    if (previousPathExt === undefined) {
+      delete process.env[pathExtKey];
+    } else {
+      process.env[pathExtKey] = previousPathExt;
+    }
+
+    if (previousArgsCapture === undefined) {
+      delete process.env.OPENCODE_ARGS_CAPTURE;
+    } else {
+      process.env.OPENCODE_ARGS_CAPTURE = previousArgsCapture;
+    }
+
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+});