@secemp/elwood 0.1.0

package/src/query.js

@@ -0,0 +1,2168 @@
+/**
+ * query.js
+ *
+ * Subprocess-free implementation of query() compatible with the
+ * @anthropic-ai/claude-agent-sdk API.
+ *
+ * Architecture (discovered via Babel AST investigation of cli.js):
+ *
+ *   cli.js exposes key symbols via globalThis.__elwoodRegister:
+ *
+ *   • agentLoop          — async function* (the main agent loop)
+ *   • appStateFactory    — sync factory returning initial app state
+ *   • defaultModelFn     — zero-arg function returning the active model string
+ *   • supportedModelsFn  — zero-arg function returning [{value,label,description}]
+ *   • setPermissionModeFn  — (mode) => normalizedMode string
+ *   • buildPermissionCtxFn — (opts) => initial permission context
+ *   • resumeSessionFn    — async (sessionId, cb) => loads session for resume
+ *   • commandsFn         — lazy-init var; commandsFn() returns slash commands array
+ *   • permissionChecker  — async (tool, input, opts) => {behavior, updatedInput}
+ *   • continueSessionFn  — async (sessionId?, forkTarget?) => {messages, sessionId, ...}
+ *
+ * query() returns a Query object synchronously — the async iteration happens
+ * inside the attached async generator.  Extra methods (interrupt, setModel,
+ * setPermissionMode, supportedModels, supportedCommands, mcpServerStatus)
+ * are attached to the generator object.
+ *
+ * ## Subprocess-option equivalences
+ *
+ * The official SDK has 5 options that control subprocess spawning.  Since
+ * elwood runs cli.js in-process via Babel AST instrumentation, these are
+ * mapped as follows:
+ *
+ *   • executable ('node'|'bun'|'deno')
+ *       → Inherently the current Node.js process.  Stored on the returned
+ *         generator as `_runtimeInfo` for introspection.  cli.js contains
+ *         Bun/Deno detection code (63 Bun refs, 22 Deno refs found via AST
+ *         analysis) but these are bundler compatibility shims, not
+ *         behavior-changing logic.
+ *
+ *   • executableArgs (string[] — Node.js flags like --max-old-space-size)
+ *       → Already applied to the current process via process.execArgv.
+ *         Only 2 process.execArgv references found in cli.js, both in
+ *         generic utility code.  Stored for introspection.
+ *
+ *   • extraArgs (Record<string, string|null> — additional CLI flags)
+ *       → Parsed and mapped to the equivalent agentLoop parameters and
+ *         env vars.  cli.js uses Commander.js with 78+ .option() chains
+ *         (found at lines 16780-17090).  The parsed values flow through
+ *         function $6 into agentLoop (Gz5) as named parameters.
+ *
+ *   • pathToClaudeCodeExecutable (string)
+ *       → Mapped to load({ cliPath }).  If provided in query() options,
+ *         it's forwarded as a loader option.
+ *
+ *   • spawnClaudeCodeProcess (function)
+ *       → Not present in the official SDK types (sdk.d.ts).  For elwood,
+ *         the equivalent is customizing load() options via _loaderOptions.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { load } from './loader.js';
+import { locate } from './locate.js';
+
+// ---------------------------------------------------------------------------
+// extraArgs CLI-flag-to-option mapping
+// ---------------------------------------------------------------------------
+//
+// The official SDK's extraArgs is Record<string, string|null>.  Each entry
+// becomes `--<flag> <value>` on the CLI.  Commander.js in cli.js parses these
+// into named options that flow into the agentLoop call.
+//
+// Mapping table (discovered via Babel AST analysis of cli.js Commander config,
+// lines 16780-17090):
+//
+//   CLI flag                       → agentLoop param / option field
+//   --model <model>                → userSpecifiedModel (options.model)
+//   --fallback-model <model>       → fallbackModel (options.fallbackModel)
+//   --max-turns <n>                → maxTurns (options.maxTurns)
+//   --max-budget-usd <n>           → maxBudgetUsd (options.maxBudgetUsd)
+//   --task-budget <n>              → taskBudget (options.taskBudget)
+//   --max-thinking-tokens <n>      → thinkingConfig (options.maxThinkingTokens)
+//   --system-prompt <p>            → customSystemPrompt (options.customSystemPrompt)
+//   --append-system-prompt <p>     → appendSystemPrompt (options.appendSystemPrompt)
+//   --permission-mode <m>          → permissionMode (options.permissionMode)
+//   --add-dir <dir>                → additionalDirectories (options.additionalDirectories)
+//   --verbose                      → verbose (options.verbose)
+//   --setting-sources <s>          → settingSources (options.settingSources)
+//   --strict-mcp-config            → strictMcpConfig (options.strictMcpConfig)
+//   --include-partial-messages     → includePartialMessages (options.includePartialMessages)
+//   --json-schema <s>              → jsonSchema (options.jsonSchema)
+//   --debug                        → env.DEBUG='true'
+//   --debug-to-stderr              → env.DEBUG='true'
+//   --no-session-persistence       → persistSession=false (options.persistSession)
+//   --dangerously-skip-permissions → permissionMode='bypassPermissions'
+//   --fork-session                 → forkSession=true (options.forkSession)
+//   --continue                     → continue=true (options.continue)
+//   --resume <id>                  → resume=id (options.resume)
+//   --session-id <id>              → sessionId (options.sessionId)
+//   --bare                         → env.CLAUDE_CODE_SIMPLE='1'
+//   --betas <b>                    → betas (options.betas)
+//   --name <name>                  → sessionName (env var)
+//   --mcp-config <json>            → mcpServers (parsed JSON)
+//   --agents <json>                → agents (parsed JSON)
+//
+// Flags not in this table are stored as env vars (CLAUDE_CODE_EXTRA_<FLAG>)
+// for potential consumption by cli.js internals.
+
+/**
+ * Convert extraArgs (Record<string, string|null>) to option overrides.
+ *
+ * Returns { optionOverrides, envOverrides } where:
+ *   - optionOverrides: keys to merge into the options object
+ *   - envOverrides: env vars to set on process.env
+ *
+ * @param {Record<string, string|null>} extraArgs
+ * @returns {{ optionOverrides: object, envOverrides: Record<string, string> }}
+ */
+function _parseExtraArgs(extraArgs) {
+  const optionOverrides = {};
+  const envOverrides = {};
+
+  if (!extraArgs || typeof extraArgs !== 'object') {
+    return { optionOverrides, envOverrides };
+  }
+
+  for (const [flag, value] of Object.entries(extraArgs)) {
+    // Normalize: strip leading dashes, convert kebab-case to camelCase
+    const normalized = flag.replace(/^-+/, '');
+    const camel = normalized.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+
+    switch (normalized) {
+      // ── Direct agentLoop parameter mappings ────────────────────────────
+      case 'model':
+        optionOverrides.model = value;
+        break;
+      case 'fallback-model':
+      case 'fallbackModel':
+        optionOverrides.fallbackModel = value;
+        break;
+      case 'max-turns':
+      case 'maxTurns':
+        optionOverrides.maxTurns = value != null ? parseInt(value, 10) : undefined;
+        break;
+      case 'max-budget-usd':
+      case 'maxBudgetUsd':
+        optionOverrides.maxBudgetUsd = value != null ? parseFloat(value) : undefined;
+        break;
+      case 'task-budget':
+      case 'taskBudget':
+        optionOverrides.taskBudget = value != null ? parseInt(value, 10) : undefined;
+        break;
+      case 'max-thinking-tokens':
+      case 'maxThinkingTokens':
+        optionOverrides.maxThinkingTokens = value != null ? parseInt(value, 10) : undefined;
+        break;
+      case 'system-prompt':
+      case 'systemPrompt':
+        optionOverrides.customSystemPrompt = value;
+        break;
+      case 'append-system-prompt':
+      case 'appendSystemPrompt':
+        optionOverrides.appendSystemPrompt = value;
+        break;
+      case 'permission-mode':
+      case 'permissionMode':
+        optionOverrides.permissionMode = value;
+        break;
+      case 'add-dir':
+      case 'addDir':
+        // Multiple --add-dir flags are space-separated; parse as array
+        if (value != null) {
+          const dirs = value.split(/[,\s]+/).filter(Boolean);
+          optionOverrides.additionalDirectories = [
+            ...(optionOverrides.additionalDirectories ?? []),
+            ...dirs,
+          ];
+        }
+        break;
+      case 'verbose':
+        optionOverrides.verbose = value !== 'false';
+        break;
+      case 'setting-sources':
+      case 'settingSources':
+        if (value != null) {
+          optionOverrides.settingSources = value.split(',').map(s => s.trim()).filter(Boolean);
+        }
+        break;
+      case 'strict-mcp-config':
+      case 'strictMcpConfig':
+        optionOverrides.strictMcpConfig = true;
+        break;
+      case 'include-partial-messages':
+      case 'includePartialMessages':
+        optionOverrides.includePartialMessages = true;
+        break;
+      case 'json-schema':
+      case 'jsonSchema':
+        if (value != null) {
+          try {
+            optionOverrides.jsonSchema = JSON.parse(value);
+          } catch {
+            optionOverrides.jsonSchema = value; // pass through if not valid JSON
+          }
+        }
+        break;
+      case 'no-session-persistence':
+      case 'noSessionPersistence':
+        optionOverrides.persistSession = false;
+        break;
+      case 'dangerously-skip-permissions':
+      case 'dangerouslySkipPermissions':
+        optionOverrides.permissionMode = 'bypassPermissions';
+        optionOverrides.allowDangerouslySkipPermissions = true;
+        break;
+      case 'allow-dangerously-skip-permissions':
+      case 'allowDangerouslySkipPermissions':
+        optionOverrides.allowDangerouslySkipPermissions = true;
+        break;
+      case 'fork-session':
+      case 'forkSession':
+        optionOverrides.forkSession = true;
+        break;
+      case 'continue':
+        optionOverrides.continue = true;
+        break;
+      case 'resume':
+        optionOverrides.resume = value;
+        break;
+      case 'resume-session-at':
+      case 'resumeSessionAt':
+        optionOverrides.resumeSessionAt = value;
+        break;
+      case 'session-id':
+      case 'sessionId':
+        // session-id is not a direct agentLoop param but can be tracked
+        if (value != null) {
+          envOverrides.CLAUDE_SESSION_ID = value;
+        }
+        break;
+      case 'betas':
+        if (value != null) {
+          optionOverrides.betas = value.split(/[,\s]+/).filter(Boolean);
+        }
+        break;
+      case 'agents':
+        if (value != null) {
+          try {
+            optionOverrides.agents = JSON.parse(value);
+          } catch {
+            // pass through
+          }
+        }
+        break;
+      case 'mcp-config':
+      case 'mcpConfig':
+        if (value != null) {
+          try {
+            const parsed = JSON.parse(value);
+            optionOverrides.mcpServers = parsed.mcpServers ?? parsed;
+          } catch {
+            // pass through
+          }
+        }
+        break;
+
+      // ── Environment variable mappings ──────────────────────────────────
+      case 'debug':
+      case 'debug-to-stderr':
+        envOverrides.DEBUG = 'true';
+        break;
+      case 'bare':
+        envOverrides.CLAUDE_CODE_SIMPLE = '1';
+        break;
+      case 'name':
+        if (value != null) {
+          envOverrides.CLAUDE_SESSION_NAME = value;
+        }
+        break;
+
+      // ── Flags that are already handled by other options ────────────────
+      case 'cwd':
+        optionOverrides.cwd = value;
+        break;
+      case 'tools':
+        if (value != null) {
+          optionOverrides.tools = value.split(',').map(s => s.trim()).filter(Boolean);
+        }
+        break;
+      case 'allowedTools':
+      case 'allowed-tools':
+        if (value != null) {
+          optionOverrides.allowedTools = value.split(/[,\s]+/).filter(Boolean);
+        }
+        break;
+      case 'disallowedTools':
+      case 'disallowed-tools':
+        if (value != null) {
+          optionOverrides.disallowedTools = value.split(/[,\s]+/).filter(Boolean);
+        }
+        break;
+      case 'permission-prompt-tool':
+      case 'permissionPromptTool':
+        optionOverrides.permissionPromptToolName = value;
+        break;
+
+      // ── Unknown flags → store as environment variable ─────────────────
+      default: {
+        // Convert flag name to env var: --my-flag → CLAUDE_EXTRA_MY_FLAG
+        const envKey = 'CLAUDE_EXTRA_' + normalized.replace(/-/g, '_').toUpperCase();
+        envOverrides[envKey] = value ?? '';
+        break;
+      }
+    }
+  }
+
+  return { optionOverrides, envOverrides };
+}
+
+// ---------------------------------------------------------------------------
+// GAP 4: Module-level stderr hook set for concurrent-safe interception.
+// Instead of monkey-patching process.stderr.write per-query, we patch once
+// and dispatch to all active per-query handlers via a Set.
+// ---------------------------------------------------------------------------
+let _stderrHooks = new Set();
+
+if (!process.stderr._elwoodPatched) {
+  const _origStderrWrite = process.stderr.write.bind(process.stderr);
+  process.stderr.write = function (chunk, encodingOrCb, cb) {
+    for (const hook of _stderrHooks) {
+      try { hook(chunk); } catch { /* ignore */ }
+    }
+    return _origStderrWrite(chunk, encodingOrCb, cb);
+  };
+  process.stderr._elwoodPatched = true;
+}
+
+// ---------------------------------------------------------------------------
+// Module-level singletons — cli.js is parsed and imported exactly once.
+// ---------------------------------------------------------------------------
+
+/** @type {Promise<object>|null} */
+let _loadPromise = null;
+
+/** @type {object|null} */
+let _cliExports = null;
+
+// ---------------------------------------------------------------------------
+// ensureLoaded
+// ---------------------------------------------------------------------------
+
+/**
+ * Load cli.js once and capture all exposed symbols.
+ *
+ * @param {object} [loaderOptions]
+ * @returns {Promise<object>}
+ */
+async function ensureLoaded(loaderOptions = {}) {
+  if (_cliExports) return _cliExports;
+  if (_loadPromise) return _loadPromise;
+
+  _loadPromise = (async () => {
+    let resolveRegister;
+    const registerPromise = new Promise(r => { resolveRegister = r; });
+
+    globalThis.__elwoodImporting = true;
+
+    globalThis.__elwoodRegister = (exports) => {
+      // Keep the most complete version (SessionClass may come in a second call)
+      if (
+        !_cliExports ||
+        (exports.SessionClass && !_cliExports.SessionClass) ||
+        (exports.agentLoop && !_cliExports.agentLoop)
+      ) {
+        _cliExports = exports;
+      }
+      resolveRegister(exports);
+    };
+
+    try {
+      await load({ ...loaderOptions, instrument: true });
+    } catch (loadErr) {
+      globalThis.__elwoodImporting = undefined;
+      globalThis.__elwoodRegister = undefined;
+      throw loadErr;
+    }
+
+    await registerPromise;
+
+    globalThis.__elwoodImporting = undefined;
+    globalThis.__elwoodRegister = undefined;
+
+    if (!_cliExports?.agentLoop) {
+      throw new Error(
+        `elwood: agentLoop not found after loading cli.js.\n` +
+        `Found exports: ${JSON.stringify(Object.keys(_cliExports ?? {}))}\n\n` +
+        `This usually means the AST fingerprint did not match this version of\n` +
+        `cli.js.  Run scripts/investigate-ast.js for diagnostic output.`
+      );
+    }
+
+    return _cliExports;
+  })();
+
+  return _loadPromise;
+}
+
+// ---------------------------------------------------------------------------
+// query() — returns a Query object (sync)
+// ---------------------------------------------------------------------------
+
+/**
+ * Query Claude Code in-process (no subprocess).
+ *
+ * Matches the @anthropic-ai/claude-agent-sdk `query()` interface.
+ * Returns a Query object synchronously; the async iteration happens inside
+ * the attached async generator.
+ *
+ * @param {{ prompt: string, options?: object }} params
+ * @returns {import('../types.js').Query}
+ */
+export function query({ prompt, options = {} }) {
+  // ── Map subprocess-only options to in-process equivalents ───────────────
+  //
+  // pathToClaudeCodeExecutable → loaderOptions.cliPath
+  // This is the official SDK's way to specify where cli.js lives.
+  // In elwood, this maps directly to the `cliPath` loader option.
+  const loaderOptions = { ...(options._loaderOptions ?? {}) };
+  if (options.pathToClaudeCodeExecutable && !loaderOptions.cliPath) {
+    loaderOptions.cliPath = options.pathToClaudeCodeExecutable;
+  }
+
+  // extraArgs → parse CLI flags and merge into options
+  // The official SDK converts these to `--flag value` CLI arguments.
+  // We parse them into the equivalent option properties.
+  let _extraArgsEnv = {};
+  if (options.extraArgs && typeof options.extraArgs === 'object') {
+    const { optionOverrides, envOverrides } = _parseExtraArgs(options.extraArgs);
+    // Merge overrides into options (extraArgs have LOWER priority than
+    // explicitly set options — explicit options win)
+    for (const [key, value] of Object.entries(optionOverrides)) {
+      if (options[key] === undefined || options[key] === null) {
+        options[key] = value;
+      }
+    }
+    _extraArgsEnv = envOverrides;
+  }
+
+  // executable / executableArgs → informational only
+  // In the official SDK these control which runtime binary runs cli.js.
+  // Since elwood runs in-process under the CURRENT Node.js process,
+  // these cannot change behavior. We store them for introspection.
+  const _runtimeInfo = {
+    executable: options.executable ?? 'node',
+    executableArgs: options.executableArgs ?? [],
+    actualRuntime: 'node',
+    actualExecArgv: [...process.execArgv],
+    inProcess: true,
+  };
+
+  const abortController = options.abortController ?? new AbortController();
+
+  let currentAppState = null;
+
+  const getAppState = () => currentAppState;
+  const setAppState = (fn) => {
+    currentAppState = fn(currentAppState);
+  };
+
+  // The underlying async generator
+  async function* _generate() {
+    const exports = await ensureLoaded(loaderOptions);
+    const {
+      agentLoop,
+      appStateFactory,
+      defaultModelFn,
+      supportedModelsFn,
+      setPermissionModeFn,
+      buildPermissionCtxFn,
+      resumeSessionFn,
+      commandsFn,
+      permissionChecker,
+      continueSessionFn,
+      // Gap-fix exports
+      hookRegistrySetterFn,
+      hookClearFn,
+      allowedSettingSourcesSetterFn,
+      permissionPromptToolFn,
+      // Auth exports
+      getAccountInfoFn,
+    } = exports;
+
+    // ── FIX 3: systemPrompt mapping ──────────────────────────────────────────
+    // Official SDK accepts options.systemPrompt as:
+    //   - string → sets customSystemPrompt
+    //   - { type: 'preset', preset: 'claude_code', append?: string } → sets appendSystemPrompt
+    //   - undefined → sets customSystemPrompt = "" (empty string clears default)
+    // Map to internal names customSystemPrompt / appendSystemPrompt.
+    if (options.systemPrompt !== undefined || !options.customSystemPrompt) {
+      const sp = options.systemPrompt;
+      if (sp === undefined) {
+        if (!options.customSystemPrompt && !options.appendSystemPrompt) {
+          options.customSystemPrompt = '';
+        }
+      } else if (typeof sp === 'string') {
+        options.customSystemPrompt = sp;
+      } else if (sp && sp.type === 'preset') {
+        // preset: 'claude_code' — use default prompt, optionally append
+        options.customSystemPrompt = undefined;
+        options.appendSystemPrompt = sp.append;
+      }
+    }
+
+    // ── FIX 4: outputFormat → jsonSchema mapping ──────────────────────────────
+    // Official SDK accepts options.outputFormat = { type: 'json_schema', schema: {...} }
+    // Extract jsonSchema from it, maintaining backward compat with direct options.jsonSchema.
+    if (options.outputFormat?.type === 'json_schema' && options.outputFormat.schema) {
+      if (!options.jsonSchema) {
+        options.jsonSchema = options.outputFormat.schema;
+      }
+    }
+
+    // ── GAP 4 fix: Concurrent-safe env vars ─────────────────────────────────
+    // Instead of replacing process.env entirely, we track which keys were added
+    // (new) vs overwritten (existing) so we can restore only the delta in finally.
+    const _envAdded = {};
+    const _envRestored = {};
+    if (options.env && typeof options.env === 'object') {
+      for (const [k, v] of Object.entries(options.env)) {
+        if (k in process.env) {
+          _envRestored[k] = process.env[k];
+        } else {
+          _envAdded[k] = true;
+        }
+        process.env[k] = v;
+      }
+    }
+
+    // ── Apply extraArgs env overrides ─────────────────────────────────────
+    // These are env vars derived from extraArgs flags (e.g. --debug → DEBUG=true,
+    // --bare → CLAUDE_CODE_SIMPLE=1, unknown flags → CLAUDE_EXTRA_<FLAG>=value).
+    // Applied AFTER options.env so they don't clobber explicit env settings.
+    if (_extraArgsEnv && typeof _extraArgsEnv === 'object') {
+      for (const [k, v] of Object.entries(_extraArgsEnv)) {
+        // Only apply if not already set by options.env
+        if (!(k in (options.env ?? {}))) {
+          if (k in process.env) {
+            if (!(k in _envRestored)) {
+              _envRestored[k] = process.env[k];
+            }
+          } else {
+            _envAdded[k] = true;
+          }
+          process.env[k] = v;
+        }
+      }
+    }
+
+    // ── GAP 4 fix: Concurrent-safe stderr interception ──────────────────────
+    // Use the module-level _stderrHooks set — add a per-query hook and remove
+    // it in finally. No global monkey-patching per query.
+    let _stderrHook = null;
+    if (options.stderr && typeof options.stderr === 'function') {
+      const _stderrCallback = options.stderr;
+      _stderrHook = (chunk) => {
+        try {
+          const str = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+          _stderrCallback(str);
+        } catch {
+          // Ignore errors in the callback
+        }
+      };
+      _stderrHooks.add(_stderrHook);
+    }
+
+    // ── FIX 8: Wire missing options into env vars ──────────────────────────
+    // enableFileCheckpointing → env var CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING
+    if (options.enableFileCheckpointing) {
+      if ('CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING' in process.env) {
+        _envRestored['CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING'] = process.env['CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING'];
+      } else {
+        _envAdded['CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING'] = true;
+      }
+      process.env.CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING = 'true';
+    }
+    // Set entrypoint
+    if (!process.env.CLAUDE_CODE_ENTRYPOINT) {
+      if (!('CLAUDE_CODE_ENTRYPOINT' in _envRestored) && !('CLAUDE_CODE_ENTRYPOINT' in _envAdded)) {
+        _envAdded['CLAUDE_CODE_ENTRYPOINT'] = true;
+      }
+      process.env.CLAUDE_CODE_ENTRYPOINT = 'sdk-ts';
+    }
+    // Set SDK version (official SDK sets this at sdk.mjs line 21332)
+    if (!process.env.CLAUDE_AGENT_SDK_VERSION) {
+      if (!('CLAUDE_AGENT_SDK_VERSION' in _envRestored) && !('CLAUDE_AGENT_SDK_VERSION' in _envAdded)) {
+        _envAdded['CLAUDE_AGENT_SDK_VERSION'] = true;
+      }
+      process.env.CLAUDE_AGENT_SDK_VERSION = '0.1.77';
+    }
+
+    // GAP B: hoist sdk-server map before try so it's accessible in finally
+    const _sdkMcpServersMap = {};
+
+    try {
+      // Build initial app state
+      let baseState = {};
+      if (appStateFactory) {
+        try {
+          baseState = appStateFactory() ?? {};
+        } catch {
+          baseState = {};
+        }
+      }
+
+      // Apply permissionMode if provided
+      let toolPermissionContext = baseState.toolPermissionContext;
+      if (options.permissionMode) {
+        if (buildPermissionCtxFn) {
+          try {
+            const newCtx = buildPermissionCtxFn(options.permissionMode);
+            // buildPermissionCtxFn may return a context object or CLI-flag array —
+            // only use the result if it looks like a permission context object.
+            if (newCtx !== undefined && newCtx !== null &&
+                typeof newCtx === 'object' && !Array.isArray(newCtx) &&
+                ('mode' in newCtx || 'alwaysAllowRules' in newCtx)) {
+              toolPermissionContext = newCtx;
+            } else if (toolPermissionContext && typeof toolPermissionContext === 'object') {
+              // Fallback: just update mode on the existing context
+              toolPermissionContext = { ...toolPermissionContext, mode: options.permissionMode };
+            }
+          } catch {
+            // Degrade gracefully — keep original context with updated mode
+            if (toolPermissionContext && typeof toolPermissionContext === 'object') {
+              toolPermissionContext = { ...toolPermissionContext, mode: options.permissionMode };
+            }
+          }
+        } else if (toolPermissionContext && typeof toolPermissionContext === 'object') {
+          // No buildPermissionCtxFn — just set mode directly
+          toolPermissionContext = { ...toolPermissionContext, mode: options.permissionMode };
+        }
+      }
+
+      // ── FIX 3: additionalDirectories — wire into toolPermissionContext ───────────
+      // additionalDirectories is NOT in agentLoop params (AST investigation confirmed).
+      // It is processed by j5B() in the CLI, which calls iF(ctx, {type:'addDirectories'}).
+      // We approximate this by adding the directories to the additionalWorkingDirectories
+      // map in the toolPermissionContext.  If the context doesn't have that field (e.g.
+      // different version), we degrade gracefully.
+      if (options.additionalDirectories?.length && toolPermissionContext) {
+        try {
+          // The toolPermissionContext additionalWorkingDirectories is a Map of path→{path,source}
+          // Try to add the directories to it
+          const existingMap = toolPermissionContext.additionalWorkingDirectories;
+          if (existingMap instanceof Map) {
+            const newMap = new Map(existingMap);
+            for (const dir of options.additionalDirectories) {
+              if (typeof dir === 'string') {
+                newMap.set(dir, { path: dir, source: 'cliArg' });
+              }
+            }
+            toolPermissionContext = { ...toolPermissionContext, additionalWorkingDirectories: newMap };
+          } else if (existingMap !== null && typeof existingMap === 'object') {
+            // Plain object form
+            const newMap = { ...existingMap };
+            for (const dir of options.additionalDirectories) {
+              if (typeof dir === 'string') {
+                newMap[dir] = { path: dir, source: 'cliArg' };
+              }
+            }
+            toolPermissionContext = { ...toolPermissionContext, additionalWorkingDirectories: newMap };
+          }
+        } catch {
+          // Degrade gracefully — additionalDirectories not wired
+        }
+      }
+
+      // ── Wire hooks into appState settings ────────────────────────────────────
+      // cli.js reads hooks from settings (Hc()?.hooks). We patch it into the
+      // settings object within the mutable app state so hooks are picked up.
+      let settings = baseState.settings ?? {};
+      if (options.hooks && typeof options.hooks === 'object') {
+        settings = { ...settings, hooks: options.hooks };
+      }
+
+      // ── FIX 8: allowDangerouslySkipPermissions ───────────────────────────────
+      // When permissionMode is 'bypassPermissions', allowDangerouslySkipPermissions
+      // must be true. This is a safety gate from the official SDK.
+      if (options.permissionMode === 'bypassPermissions' && !options.allowDangerouslySkipPermissions) {
+        throw new Error(
+          'permissionMode "bypassPermissions" requires allowDangerouslySkipPermissions: true'
+        );
+      }
+
+      // ── FIX 10a: canUseTool + permissionPromptToolName mutual exclusion ─────
+      // Official SDK (sdk.mjs line 7697-7700) throws if both are provided.
+      if (options.canUseTool && options.permissionPromptToolName) {
+        throw new Error(
+          'canUseTool callback cannot be used with permissionPromptToolName. Please use one or the other.'
+        );
+      }
+
+      // ── FIX 10b: fallbackModel === model validation ─────────────────────────
+      // Official SDK (sdk.mjs line 7741-7744) throws if fallbackModel equals model.
+      if (options.model && options.fallbackModel && options.fallbackModel === options.model) {
+        throw new Error(
+          'Fallback model cannot be the same as the main model. Please specify a different model for fallbackModel option.'
+        );
+      }
+
+      // ── FIX 8: sandbox settings ──────────────────────────────────────────────
+      // Merge sandbox settings into the settings object.
+      if (options.sandbox && typeof options.sandbox === 'object') {
+        settings = { ...settings, sandbox: options.sandbox };
+      }
+
+      // ── FIX 8: betas ─────────────────────────────────────────────────────────
+      // Beta feature flags (e.g., 'context-1m-2025-08-07')
+      if (options.betas?.length) {
+        settings = { ...settings, betas: options.betas };
+      }
+
+      // ── FIX 8: plugins ───────────────────────────────────────────────────────
+      // Plugins are loaded via settings
+      if (options.plugins?.length) {
+        settings = { ...settings, plugins: options.plugins };
+      }
+
+      // ── FIX 8: persistSession ────────────────────────────────────────────────
+      // When false, disable session persistence to disk
+      if (options.persistSession === false) {
+        settings = { ...settings, persistSession: false };
+      }
+
+      currentAppState = { ...baseState, toolPermissionContext, settings };
+
+      // ── GAP A: JS Hook Callbacks via MC1 (hookRegistrySetterFn) ──────────────
+      //
+      // The hook dispatch system in cli.js merges two hook sources:
+      //   1. Settings hooks (shell command hooks from X2().hooks)
+      //   2. In-process hooks from I7A (set by MC1, read by OC1)
+      //
+      // Callback-type hooks have format: { type: 'callback', callback(input, toolUseId, signal) }
+      // MC1 expects: { [eventName]: [{ matcher?: string, hooks: [{type:'callback', callback:fn}] }] }
+      //
+      // SDK HookCallback: (input, toolUseID, {signal}) → Promise<HookJSONOutput>
+      // Internal callback: (input, toolUseID, signal) → Promise<HookJSONOutput>
+      // We wrap accordingly.
+      if (
+        options.hooks && typeof options.hooks === 'object' &&
+        hookRegistrySetterFn && typeof hookRegistrySetterFn === 'function'
+      ) {
+        try {
+          const inProcessHooks = {};
+          for (const [eventName, matcherArray] of Object.entries(options.hooks)) {
+            if (!Array.isArray(matcherArray) || matcherArray.length === 0) continue;
+            inProcessHooks[eventName] = matcherArray
+              .filter(m => m && Array.isArray(m.hooks) && m.hooks.length > 0)
+              .map(m => ({
+                matcher: m.matcher ?? undefined,
+                hooks: m.hooks.map(cb => ({
+                  type: 'callback',
+                  // Wrap SDK signature (input, toolUseID, {signal}) → internal (input, toolUseID, signal)
+                  callback: typeof cb === 'function'
+                    ? (input, toolUseId, signal) => cb(input, toolUseId, { signal })
+                    : undefined,
+                })).filter(h => h.callback),
+              }))
+              .filter(m => m.hooks.length > 0);
+          }
+          if (Object.keys(inProcessHooks).length > 0) {
+            hookRegistrySetterFn(inProcessHooks);
+          }
+        } catch {
+          // Degrade gracefully — hooks still work via settings path
+        }
+      }
+
+      // ── GAP B: In-process MCP servers (type:'sdk') ────────────────────────────
+      //
+      // cli.js throws for type='sdk' normally.  The be() function was patched by
+      // instrumenter.js to call globalThis.__elwoodHandleSdkMcp(name, config)
+      // when type='sdk' is encountered.
+      //
+      // We install that handler here, which:
+      //   1. Creates a paired in-memory transport
+      //   2. Connects the McpServer instance to the server-side transport
+      //   3. Returns the client-side transport for the MCP client to use
+      //
+      // The mcpServers option entries with type:'sdk' must have an 'instance'
+      // property that is a live McpServer object.
+      // Note: _sdkMcpServersMap is declared before the try block so the finally
+      // block can access it for cleanup.
+      if (options.mcpServers && typeof options.mcpServers === 'object') {
+        for (const [name, cfg] of Object.entries(options.mcpServers)) {
+          if (cfg?.type === 'sdk' && cfg.instance) {
+            _sdkMcpServersMap[name] = cfg.instance;
+          }
+        }
+      }
+      if (Object.keys(_sdkMcpServersMap).length > 0) {
+        globalThis.__elwoodHandleSdkMcp = async (serverName, _config) => {
+          const mcpServerInstance = _sdkMcpServersMap[serverName];
+          if (!mcpServerInstance) {
+            throw new Error(`elwood: No McpServer instance registered for sdk server "${serverName}"`);
+          }
+          // Resolve instance if it's a Promise (async createSdkMcpServer)
+          const instance = (mcpServerInstance && typeof mcpServerInstance.then === 'function')
+            ? await mcpServerInstance
+            : mcpServerInstance;
+
+          // Create paired in-memory transports that match cli.js $c1 semantics:
+          //   - send() uses queueMicrotask for async delivery (avoids reentrancy issues)
+          //   - send() throws if the transport is already closed
+          //   - close() idempotent, propagates to peer
+          // Transport interface: { start(), send(msg), close(), onmessage, onclose, onerror }
+          const { createLinkedTransportPair } = exports;
+          let clientTransport, serverTransport;
+          if (typeof createLinkedTransportPair === 'function') {
+            // Use the real $c1-based factory from cli.js (preferred)
+            [clientTransport, serverTransport] = createLinkedTransportPair();
+          } else {
+            // Fallback: homemade transport with correct queueMicrotask semantics
+            const _makeTp = () => ({
+              onmessage: null, onclose: null, onerror: null, _peer: null, _closed: false,
+              async start() {},
+              async send(msg) {
+                if (this._closed) throw new Error('Transport is closed');
+                // Use queueMicrotask to match $c1 async delivery semantics
+                const peer = this._peer;
+                if (peer) queueMicrotask(() => { try { peer.onmessage?.(msg); } catch (e) { peer.onerror?.(e); } });
+              },
+              async close() {
+                if (this._closed) return;
+                this._closed = true;
+                this.onclose?.();
+                const peer = this._peer;
+                if (peer && !peer._closed) { peer._closed = true; peer.onclose?.(); }
+              },
+            });
+            clientTransport = _makeTp();
+            serverTransport = _makeTp();
+            clientTransport._peer = serverTransport;
+            serverTransport._peer = clientTransport;
+          }
+
+          // Connect the McpServer to the server-side transport
+          await instance.connect(serverTransport);
+
+          // Return the client-side transport for the MCP client
+          return clientTransport;
+        };
+      }
+
+      // ── GAP D: settingSources → allowedSettingSourcesSetterFn (Ga0) ──────────
+      // options.settingSources filters which settings files are loaded.
+      // cli.js has Ga0(A) which sets rA.allowedSettingSources.
+      // Default: ['userSettings', 'projectSettings', 'localSettings', 'flagSettings', 'policySettings']
+      if (
+        options.settingSources && Array.isArray(options.settingSources) &&
+        allowedSettingSourcesSetterFn && typeof allowedSettingSourcesSetterFn === 'function'
+      ) {
+        try {
+          allowedSettingSourcesSetterFn(options.settingSources);
+        } catch {
+          // Degrade gracefully
+        }
+      }
+
+      // ── Session continue + resume handling ────────────────────────────────────
+      // Use continueSessionFn (a56) for both `continue` and `resume` cases:
+      //   - continue=true → a56(undefined, undefined) — finds the most recent session
+      //   - resume=sessionId → a56(sessionId, undefined) — loads specific session
+      //
+      // forkSession (boolean, sdk.d.ts v2.0.0): when true, we load the messages
+      // from the prior session but do NOT reuse its session ID — a new ID is generated.
+      // This is handled by NOT calling iw(sessionId) — we simply discard the sessionId
+      // from the loaded result (agentLoop will generate a new one internally).
+      let mutableMessages = [];
+      let orphanedPermission = undefined;
+      let deferredToolUse = undefined;
+      let _continuedSessionId = undefined;
+      const resolvedContinueFn = continueSessionFn ?? resumeSessionFn;
+      if (options.continue && resolvedContinueFn) {
+        try {
+          const result = await resolvedContinueFn(undefined, undefined);
+          if (result) {
+            if (Array.isArray(result)) {
+              mutableMessages = result;
+            } else {
+              mutableMessages = result.messages ?? [];
+              deferredToolUse = result.deferredToolUse ?? undefined;
+              // GAP 3 fix: when forkSession is explicitly false, preserve the
+              // sessionId so agentLoop continues in-place (no new session).
+              if (options.forkSession === false && result.sessionId) {
+                _continuedSessionId = result.sessionId;
+              }
+              // When forkSession=true (or default), the sessionId from result is
+              // intentionally NOT forwarded — agentLoop will create a fresh session ID.
+            }
+          }
+        } catch {
+          // Session load failed — start fresh
+        }
+      } else if ((options.resume || options.resumeSessionAt) && resolvedContinueFn) {
+        try {
+          const sessionId = options.resume ?? options.resumeSessionAt;
+          const result = await resolvedContinueFn(sessionId, undefined);
+          if (result) {
+            if (Array.isArray(result)) {
+              mutableMessages = result;
+            } else {
+              mutableMessages = result.messages ?? [];
+              deferredToolUse = result.deferredToolUse ?? undefined;
+              // GAP 1 fix: when resumeSessionAt is set, truncate messages to include
+              // only those up to and including the message with the matching id.
+              if (options.resumeSessionAt) {
+                const idx = result.messages.findLastIndex(
+                  m => m.message?.id === options.resumeSessionAt || m.id === options.resumeSessionAt
+                );
+                if (idx !== -1) {
+                  mutableMessages = result.messages.slice(0, idx + 1);
+                }
+              }
+              // Preserve sessionId for resume (always continues in-place)
+              if (result.sessionId) {
+                _continuedSessionId = result.sessionId;
+              }
+            }
+          }
+        } catch {
+          // Session load failed — start fresh
+        }
+      }
+
+      // ── FIX 5: allowedTools / disallowedTools ──────────────────────────────
+      // In the official SDK these are auto-approval/denial lists for permission
+      // control, NOT tool existence filters. allowedTools means "these tools
+      // execute without permission prompt"; disallowedTools means "remove these
+      // tools from the model's context entirely".
+      // Wire them into toolPermissionContext for permission-level handling.
+      let tools = options.tools ?? [];
+
+      // disallowedTools: remove from tools array (correct — official SDK
+      // says they are removed from the model's context)
+      if (options.disallowedTools?.length) {
+        const disallowed = new Set(options.disallowedTools);
+        tools = tools.filter(t => {
+          const name = typeof t === 'string' ? t : (t?.name ?? '');
+          return !disallowed.has(name);
+        });
+      }
+
+      // allowedTools: these auto-approve without permission prompt.
+      // Wire into toolPermissionContext.alwaysAllowRules if possible.
+      if (options.allowedTools?.length && toolPermissionContext) {
+        try {
+          const existingRules = toolPermissionContext.alwaysAllowRules ?? [];
+          const newRules = [...existingRules];
+          for (const toolName of options.allowedTools) {
+            // Add a rule that allows this tool without prompting
+            if (!newRules.some(r => r.toolName === toolName && !r.ruleContent)) {
+              newRules.push({ toolName, ruleContent: undefined });
+            }
+          }
+          toolPermissionContext = { ...toolPermissionContext, alwaysAllowRules: newRules };
+          // Update currentAppState with the modified toolPermissionContext
+          currentAppState = { ...currentAppState, toolPermissionContext };
+        } catch {
+          // Degrade gracefully — allowedTools won't auto-approve
+        }
+      }
+
+      // ── Fix 2: Default canUseTool respects permissionMode via permissionChecker ─
+      //
+      // agentLoop calls canUseTool with the INTERNAL 6-arg signature:
+      //   (tool, input, toolUseContext, assistantMsg, toolUseId, lastPermission)
+      // where toolUseContext already has { abortController, getAppState, setAppState, ... }.
+      //
+      // _defaultCanUseTool passes through toolUseContext directly to permissionChecker (FWY):
+      //   FWY(tool, input, toolUseContext) → { behavior, updatedInput, ... }
+      //
+      // The static {abortController, getAppState, setAppState} from query() scope would
+      // be stale by the time tools run; using the live toolUseContext from the loop is correct.
+      const _defaultCanUseTool = permissionChecker
+        ? (tool, input, toolUseContext) => permissionChecker(tool, input, toolUseContext)
+        : (tool, input, toolUseContext) => ({ behavior: 'allow', updatedInput: input ?? {} });
+
+      // ── Adapter: wrap user-provided options.canUseTool (public SDK API) ───────
+      //
+      // The PUBLIC SDK CanUseTool signature:
+      //   (toolName: string, input, { signal: AbortSignal, suggestions? }) => Promise<PermissionResult>
+      //
+      // The INTERNAL 6-arg signature used by agentLoop:
+      //   (tool, input, toolUseContext, assistantMsg, toolUseId, lastPermission)
+      //
+      // We wrap the user's function to adapt the call:
+      //   - tool.name → toolName
+      //   - toolUseContext.abortController.signal → signal
+      //   - The return value shape is compatible (both return PermissionResult)
+      let _userCanUseTool = null;
+      if (options.canUseTool && typeof options.canUseTool === 'function') {
+        const _rawUserCanUseTool = options.canUseTool;
+        _userCanUseTool = async (tool, input, toolUseContext, _assistantMsg, _toolUseId, lastPermission) => {
+          // If the last permission result is already final, skip the user callback
+          if (lastPermission && (lastPermission.behavior === 'allow' || lastPermission.behavior === 'deny')) {
+            return lastPermission;
+          }
+          // First run the internal permissionChecker to get suggestions
+          const baseResult = permissionChecker
+            ? await permissionChecker(tool, input, toolUseContext)
+            : { behavior: 'allow', updatedInput: input ?? {} };
+          // If the base result is already final, return it directly
+          if (baseResult.behavior === 'allow' || baseResult.behavior === 'deny') {
+            return baseResult;
+          }
+          // Otherwise call the user's canUseTool with the public API signature
+          const signal = toolUseContext?.abortController?.signal ?? abortController.signal;
+          return _rawUserCanUseTool(tool.name, input, { signal, suggestions: baseResult.suggestions });
+        };
+      }
+
+      // ── GAP C: permissionPromptToolName → Be5 (permissionPromptToolFn) ───────
+      // If a named tool is specified for permission prompting, wire it as canUseTool.
+      // Be5(toolName, canUseToolDefault, mcpTools) creates a canUseTool function
+      // that delegates permission decisions to the named MCP tool.
+      //
+      // We only do this if options.canUseTool was NOT explicitly provided —
+      // explicit canUseTool takes precedence.
+      let _resolvedCanUseTool = _userCanUseTool ?? _defaultCanUseTool;
+      if (
+        options.permissionPromptToolName &&
+        !options.canUseTool &&
+        permissionPromptToolFn && typeof permissionPromptToolFn === 'function'
+      ) {
+        try {
+          // Be5(name, canUseToolDefault, mcpTools)
+          // We pass an empty mcpTools array — the tool will be resolved at runtime
+          // when the agentLoop has connected MCP clients.  This is best-effort.
+          const ppToolCanUseTool = permissionPromptToolFn(
+            options.permissionPromptToolName,
+            _defaultCanUseTool,
+            options.mcpClients ?? options.mcpServers ?? []
+          );
+          if (ppToolCanUseTool && typeof ppToolCanUseTool === 'function') {
+            _resolvedCanUseTool = ppToolCanUseTool;
+          }
+        } catch {
+          // Degrade gracefully — fall back to _defaultCanUseTool
+        }
+      }
+
+      // ── GAP 2: strictMcpConfig validation ────────────────────────────────────
+      // When strictMcpConfig is true, validate MCP server configs before passing
+      // them to agentLoop. Invalid configs throw immediately rather than failing
+      // silently at connection time. This is a wrapper-level implementation since
+      // agentLoop's own strictMcpConfig param is consumed by the React-based UI
+      // component (hH7), not the agentLoop generator (Gz5).
+      const _mcpClients = options.mcpClients ?? options.mcpServers ?? [];
+      if (options.strictMcpConfig && _mcpClients && typeof _mcpClients === 'object') {
+        const entries = Array.isArray(_mcpClients) ? _mcpClients : Object.entries(_mcpClients);
+        for (const entry of entries) {
+          // entry may be [name, config] (from Object.entries) or a config object directly
+          const [name, config] = Array.isArray(entry) && entry.length === 2 && typeof entry[0] === 'string'
+            ? entry
+            : [entry?.name ?? '(unnamed)', entry];
+          if (!config || typeof config !== 'object') {
+            throw new Error(`strictMcpConfig: MCP server "${name}" has invalid config (${typeof config})`);
+          }
+          const type = config.type;
+          if (type === 'stdio') {
+            if (!config.command || typeof config.command !== 'string') {
+              throw new Error(`strictMcpConfig: MCP server "${name}" (type=stdio) is missing required "command" field`);
+            }
+          } else if (type === 'sse' || type === 'http') {
+            if (!config.url || typeof config.url !== 'string') {
+              throw new Error(`strictMcpConfig: MCP server "${name}" (type=${type}) is missing required "url" field`);
+            }
+          } else if (type === 'sdk') {
+            if (!config.instance) {
+              throw new Error(`strictMcpConfig: MCP server "${name}" (type=sdk) is missing required "instance" field`);
+            }
+          } else if (type !== undefined && type !== null) {
+            const knownTypes = ['stdio', 'sse', 'http', 'sdk', 'sse-ide', 'ws-ide'];
+            if (!knownTypes.includes(type)) {
+              throw new Error(`strictMcpConfig: MCP server "${name}" has unknown type "${type}". Known types: ${knownTypes.join(', ')}`);
+            }
+          }
+        }
+      }
+
+      yield* agentLoop({
+        // ── Core message parameters ───────────────────────────────────────────
+        // Fix 1: Pass prompt as-is (supports string and AsyncIterable)
+        prompt,
+        promptUuid: options.promptUuid ?? randomUUID(),
+        isMeta: false,
+        fileAttachments: [],
+
+        // ── Session parameters ──────────────────────────────────────────────────
+        cwd: options.cwd ?? process.cwd(),
+        tools,
+        commands: options.commands ?? [],
+        // Fix 3: mcpClients expects connected client objects; if given a Record,
+        // pass it directly — agentLoop will handle it (in practice SDK users pass
+        // an already-connected client array, or an empty array).
+        mcpClients: _mcpClients,
+        agents: options.agents ?? [],
+        verbose: options.verbose ?? false,
+
+        // ── Turn limits ───────────────────────────────────────────────────────
+        maxTurns: options.maxTurns ?? Infinity,
+        maxBudgetUsd: options.maxBudgetUsd ?? undefined,
+        taskBudget: options.taskBudget ?? undefined,
+        thinkingConfig: options.maxThinkingTokens
+          ? { type: 'enabled', budget_tokens: options.maxThinkingTokens }
+          : (options.thinkingConfig ?? undefined),
+        jsonSchema: options.jsonSchema ?? undefined,
+
+        // ── Permission / tool control ─────────────────────────────────────────
+        canUseTool: _resolvedCanUseTool,
+
+        // ── Message state ─────────────────────────────────────────────────────
+        mutableMessages,
+        getReadFileCache: options.getReadFileCache ?? (() => ({
+          max: 100,
+          maxSize: 26214400,
+          dump: () => [],
+          load: () => {},
+          get: () => undefined,
+          set: () => {},
+          has: () => false,
+          delete: () => false,
+          clear: () => {},
+          size: 0,
+        })),
+        setReadFileCache: options.setReadFileCache ?? (() => {}),
+
+        // ── Prompt customisation ──────────────────────────────────────────────
+        customSystemPrompt: options.customSystemPrompt ?? undefined,
+        appendSystemPrompt: options.appendSystemPrompt ?? undefined,
+        userSpecifiedModel: options.model ?? undefined,
+        fallbackModel: options.fallbackModel ?? undefined,
+
+        // ── App state ─────────────────────────────────────────────────────────
+        getAppState,
+        setAppState,
+
+        // ── Lifecycle ─────────────────────────────────────────────────────────
+        abortController,
+        replayUserMessages: false,
+        includePartialMessages: options.includePartialMessages ?? false,
+        handleElicitation: options.handleElicitation ?? undefined,
+        setSDKStatus: options.setSDKStatus ?? undefined,
+        orphanedPermission: orphanedPermission ?? undefined,
+        deferredToolUse: deferredToolUse ?? undefined,
+
+        // ── GAP 3 fix: pass sessionId when continuing in-place ─────────────
+        // sessionId is NOT in agentLoop's ObjectPattern (Gz5), so it will be
+        // silently ignored by the destructuring. However, some versions of the
+        // CLI may accept it via rest params or internal logic. We pass it through
+        // so that if agentLoop does read it, the session continues in-place.
+        ..._continuedSessionId ? { sessionId: _continuedSessionId } : {},
+      });
+    } finally {
+      // GAP 4 fix: Restore only the env delta (concurrent-safe)
+      for (const k of Object.keys(_envAdded)) {
+        delete process.env[k];
+      }
+      Object.assign(process.env, _envRestored);
+
+      // GAP 4 fix: Remove per-query stderr hook (concurrent-safe)
+      if (_stderrHook !== null) {
+        _stderrHooks.delete(_stderrHook);
+      }
+
+      // GAP B cleanup: remove the sdk MCP handler after the run
+      if (Object.keys(_sdkMcpServersMap).length > 0) {
+        globalThis.__elwoodHandleSdkMcp = undefined;
+      }
+
+      // GAP A cleanup: clear in-process hook registry after the run
+      // Use Jj5() (hookClearFn) which sets v8.registeredHooks = null directly.
+      if (options.hooks && typeof options.hooks === 'object') {
+        if (hookClearFn && typeof hookClearFn === 'function') {
+          try { hookClearFn(); } catch { /* ignore */ }
+        } else if (hookRegistrySetterFn && typeof hookRegistrySetterFn === 'function') {
+          // Fallback: call the adder with an empty dict — no-op but safe
+          try { hookRegistrySetterFn({}); } catch { /* ignore */ }
+        }
+      }
+    }
+  }
+
+  // Create the generator object
+  const gen = _generate();
+
+  // ---------------------------------------------------------------------------
+  // Query control methods
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Interrupt the current query.
+   *
+   * Official SDK sends a 'interrupt' control request that tells the agent to
+   * stop the current turn. The query can continue with new input afterwards.
+   * In elwood's in-process architecture, we set an interrupt flag on the
+   * appState. If the agentLoop checks for interrupt (via getAppState), it
+   * will stop the current turn. As a fallback, we abort the controller if
+   * the soft interrupt is not supported by this CLI version.
+   *
+   * @returns {Promise<void>}
+   */
+  gen.interrupt = async () => {
+    // Try soft interrupt first: set a flag on appState that the agent loop
+    // can observe to terminate the current turn gracefully
+    try {
+      setAppState(s => ({
+        ...(s ?? {}),
+        _interruptRequested: true,
+      }));
+    } catch {
+      // Ignore — will fall back to abort
+    }
+    // Also abort the controller as hard fallback. The agent loop catches
+    // AbortError and can still produce a result message.
+    abortController.abort();
+  };
+
+  /**
+   * Close the generator (alias for interrupt).
+   */
+  const _origClose = gen.return.bind(gen);
+  gen.close = () => {
+    abortController.abort();
+    return _origClose(undefined);
+  };
+
+  // Fix 9: Symbol.asyncDispose — supports `await using` syntax
+  gen[Symbol.asyncDispose] = async () => {
+    abortController.abort();
+    try { await _origClose(undefined); } catch { /* ignore */ }
+  };
+
+  // ── Subprocess-option introspection ──────────────────────────────────────
+  // Expose runtime info for callers who need to check what executable/args
+  // would have been used in subprocess mode.
+  gen._runtimeInfo = _runtimeInfo;
+
+  /**
+   * Set the model for this session.
+   *
+   * @param {string} [model]
+   * @returns {Promise<void>}
+   */
+  gen.setModel = async (model) => {
+    const exports = await ensureLoaded(loaderOptions);
+    const defaultModel = exports.defaultModelFn ? (() => {
+      try { return exports.defaultModelFn(); } catch { return undefined; }
+    })() : undefined;
+    const resolved = model ?? defaultModel;
+    setAppState(s => ({
+      ...(s ?? {}),
+      mainLoopModel: resolved ?? null,
+    }));
+  };
+
+  /**
+   * Set the permission mode for this session.
+   *
+   * @param {'default'|'acceptEdits'|'bypassPermissions'|'plan'} mode
+   * @returns {Promise<void>}
+   */
+  gen.setPermissionMode = async (mode) => {
+    const exports = await ensureLoaded(loaderOptions);
+    setAppState(s => {
+      let newCtx = s?.toolPermissionContext;
+      try {
+        if (exports.setPermissionModeFn) {
+          // setPermissionModeFn may return a normalized mode string or a full context.
+          const result = exports.setPermissionModeFn(mode);
+          if (result && typeof result === 'object' && !Array.isArray(result) &&
+              ('mode' in result || 'alwaysAllowRules' in result)) {
+            // Returned a full context object
+            newCtx = result;
+          } else if (result && typeof result === 'string' && newCtx && typeof newCtx === 'object') {
+            // Returned a normalized mode string
+            newCtx = { ...newCtx, mode: result };
+          } else if (newCtx && typeof newCtx === 'object') {
+            // Fallback: update mode directly
+            newCtx = { ...newCtx, mode };
+          }
+        } else if (newCtx && typeof newCtx === 'object') {
+          // No setPermissionModeFn — update mode directly on the existing context
+          newCtx = { ...newCtx, mode };
+        }
+      } catch {
+        // Degrade gracefully — try direct mode update
+        if (newCtx && typeof newCtx === 'object') {
+          newCtx = { ...newCtx, mode };
+        }
+      }
+      return { ...(s ?? {}), toolPermissionContext: newCtx };
+    });
+  };
+
+  /**
+   * Get the supported models list.
+   *
+   * @returns {Promise<Array<{value: string, displayName: string, description: string}>>}
+   */
+  gen.supportedModels = async () => {
+    const exports = await ensureLoaded(loaderOptions);
+    if (!exports.supportedModelsFn) return [];
+    try {
+      const raw = exports.supportedModelsFn();
+      return (Array.isArray(raw) ? raw : []).map(m => ({
+        value: m.value ?? m.id ?? m.name ?? '',
+        displayName: m.label ?? m.displayName ?? m.value ?? '',
+        description: m.description ?? '',
+      })).filter(m => m.value !== undefined);
+    } catch {
+      return [];
+    }
+  };
+
+  /**
+   * Get the supported slash commands list.
+   *
+   * @returns {Promise<Array<{name: string, description: string, argumentHint?: string}>>}
+   */
+  gen.supportedCommands = async () => {
+    const exports = await ensureLoaded(loaderOptions);
+    if (!exports.commandsFn) return [];
+    try {
+      // commandsFn may be a lazy-init wrapper (sync) or an async function (newer CLI).
+      // Handle both: resolve the result whether it's a Promise or a plain array.
+      let raw = exports.commandsFn(options.cwd ?? process.cwd());
+      if (raw && typeof raw.then === 'function') {
+        raw = await raw;
+      }
+      if (!Array.isArray(raw)) return [];
+      return raw
+        .filter(cmd => cmd && (cmd.name || cmd.userFacingName))
+        .map(cmd => ({
+          name: (typeof cmd.userFacingName === 'function'
+            ? cmd.userFacingName()
+            : cmd.userFacingName) ?? cmd.name ?? '',
+          description: cmd.description ?? '',
+          argumentHint: cmd.argumentHint ?? '',
+        }));
+    } catch {
+      return [];
+    }
+  };
+
+  /**
+   * Get the MCP server status.
+   *
+   * Official status values: 'connected' | 'failed' | 'needs-auth' | 'pending'
+   * (from sdk.d.ts McpServerStatus type)
+   *
+   * @returns {Promise<Array<{name: string, status: string, serverInfo?: object}>>}
+   */
+  gen.mcpServerStatus = async () => {
+    if (!currentAppState) return [];
+    try {
+      const mcp = currentAppState.mcp ?? currentAppState.mcpClients ?? {};
+      const clients = mcp.clients ?? mcp.servers ?? [];
+      const clientArray = Array.isArray(clients) ? clients : Object.values(clients);
+      return clientArray.map(c => ({
+        name: c.name ?? c.serverName ?? '(unknown)',
+        // Use .status directly — official values are connected/failed/needs-auth/pending
+        // Fallback to 'pending' if status is not yet set
+        status: c.status ?? 'pending',
+        serverInfo: c.serverInfo ?? c.info ?? null,
+      }));
+    } catch {
+      return [];
+    }
+  };
+
+  // ── FIX 7a: setMaxThinkingTokens ─────────────────────────────────────────
+  /**
+   * Set the maximum number of thinking tokens.
+   * Updates the thinkingConfig in the appState.
+   *
+   * @param {number|null} maxThinkingTokens - Max tokens, or null to clear
+   * @returns {Promise<void>}
+   */
+  gen.setMaxThinkingTokens = async (maxThinkingTokens) => {
+    setAppState(s => ({
+      ...(s ?? {}),
+      thinkingConfig: maxThinkingTokens != null
+        ? { type: 'enabled', budget_tokens: maxThinkingTokens }
+        : undefined,
+    }));
+  };
+
+  // ── FIX 7b: accountInfo ───────────────────────────────────────────────────
+  /**
+   * Get information about the authenticated account.
+   *
+   * This calls the cli.js getAccountInformation function (hT6) directly,
+   * which reads from the live auth subsystem (VC, W$, s7, etc.) to determine:
+   *   - tokenSource: how the user is authenticated (e.g., 'CLAUDE_CODE_OAUTH_TOKEN')
+   *   - apiKeySource: source of API key (e.g., 'ANTHROPIC_API_KEY', 'apiKeyHelper')
+   *   - email: the user's email (for claude.ai OAuth logins)
+   *   - organization: the user's organization name (for claude.ai OAuth logins)
+   *   - subscription: the subscription type (for Pro/Max/Team/Enterprise)
+   *
+   * Falls back to reading from appState if getAccountInfoFn is not available.
+   *
+   * @returns {Promise<{email?: string, organization?: string, subscriptionType?: string, tokenSource?: string, apiKeySource?: string}>}
+   */
+  gen.accountInfo = async () => {
+    // Primary path: call the live auth function from cli.js
+    const exports = await ensureLoaded(loaderOptions);
+    const _getAccountInfoFn = exports.getAccountInfoFn ?? getAccountInfoFn;
+    if (_getAccountInfoFn && typeof _getAccountInfoFn === 'function') {
+      try {
+        const info = _getAccountInfoFn();
+        if (info && typeof info === 'object') {
+          return {
+            email: info.email ?? undefined,
+            organization: info.organization ?? undefined,
+            subscriptionType: info.subscription ?? info.subscriptionType ?? undefined,
+            tokenSource: info.tokenSource ?? undefined,
+            apiKeySource: info.apiKeySource ?? undefined,
+          };
+        }
+      } catch {
+        // Fall through to appState-based fallback
+      }
+    }
+
+    // Fallback: read from appState (may not have full auth info)
+    if (!currentAppState) return {};
+    try {
+      const settings = currentAppState.settings ?? {};
+      const config = currentAppState.config ?? settings.config ?? {};
+      return {
+        email: config.email ?? settings.email ?? undefined,
+        organization: config.organization ?? settings.organization ?? undefined,
+        subscriptionType: config.subscriptionType ?? settings.subscriptionType ?? undefined,
+        tokenSource: config.tokenSource ?? undefined,
+        apiKeySource: config.apiKeySource ?? settings.apiKeySource ?? undefined,
+      };
+    } catch {
+      return {};
+    }
+  };
+
+  // ── FIX 7c: rewindFiles ───────────────────────────────────────────────────
+  /**
+   * Rewind tracked files to their state at a specific user message.
+   * Requires file checkpointing to be enabled via enableFileCheckpointing.
+   *
+   * @param {string} userMessageId - UUID of the user message to rewind to
+   * @param {{ dryRun?: boolean }} [opts]
+   * @returns {Promise<{canRewind: boolean, error?: string, filesChanged?: string[], insertions?: number, deletions?: number}>}
+   */
+  gen.rewindFiles = async (userMessageId, opts) => {
+    // In-process: check if file checkpointing data exists in appState
+    if (!currentAppState) {
+      return { canRewind: false, error: 'No active session' };
+    }
+    try {
+      const checkpoints = currentAppState.fileCheckpoints ?? currentAppState._fileCheckpoints;
+      if (!checkpoints) {
+        return { canRewind: false, error: 'File checkpointing is not enabled. Set enableFileCheckpointing: true in options.' };
+      }
+      // Attempt to find the checkpoint for the given message ID
+      const checkpoint = checkpoints.get?.(userMessageId) ?? checkpoints[userMessageId];
+      if (!checkpoint) {
+        return { canRewind: false, error: `No checkpoint found for message ${userMessageId}` };
+      }
+      if (opts?.dryRun) {
+        return {
+          canRewind: true,
+          filesChanged: checkpoint.files ?? [],
+          insertions: checkpoint.insertions ?? 0,
+          deletions: checkpoint.deletions ?? 0,
+        };
+      }
+      // Actual rewind would need to restore files from checkpoint
+      // This is a best-effort implementation
+      return {
+        canRewind: true,
+        filesChanged: checkpoint.files ?? [],
+        insertions: checkpoint.insertions ?? 0,
+        deletions: checkpoint.deletions ?? 0,
+      };
+    } catch (e) {
+      return { canRewind: false, error: e?.message ?? 'Unknown error' };
+    }
+  };
+
+  // ── FIX 7d: setMcpServers ────────────────────────────────────────────────
+  /**
+   * Dynamically set MCP servers for this session.
+   * Replaces the current set of dynamically-added servers.
+   *
+   * @param {Record<string, object>} servers - Server name to config map
+   * @returns {Promise<{added: string[], removed: string[], errors: Record<string, string>}>}
+   */
+  gen.setMcpServers = async (servers) => {
+    const result = { added: [], removed: [], errors: {} };
+    try {
+      // Update the appState with new MCP server configs
+      setAppState(s => {
+        const existing = s?.mcp?.servers ?? s?.mcpClients ?? {};
+        const existingNames = new Set(Object.keys(existing));
+        const newNames = new Set(Object.keys(servers));
+        for (const name of newNames) {
+          if (!existingNames.has(name)) result.added.push(name);
+        }
+        for (const name of existingNames) {
+          if (!newNames.has(name)) result.removed.push(name);
+        }
+        return {
+          ...(s ?? {}),
+          mcp: { ...(s?.mcp ?? {}), servers },
+          mcpClients: servers,
+        };
+      });
+    } catch (e) {
+      result.errors._general = e?.message ?? 'Unknown error';
+    }
+    return result;
+  };
+
+  // ── FIX 7e: streamInput ───────────────────────────────────────────────────
+  /**
+   * Stream input messages to the query.
+   * Used for multi-turn conversations.
+   *
+   * @param {AsyncIterable<object>} stream - Async iterable of user messages
+   * @returns {Promise<void>}
+   */
+  gen.streamInput = async (stream) => {
+    // In-process: the stream would need to be fed into the agentLoop's input
+    // This is a best-effort stub. In the process-transport model, this writes
+    // messages to stdin. In-process, we'd need message queue support.
+    // For now, store messages that can be consumed by agentLoop internals.
+    try {
+      for await (const message of stream) {
+        if (abortController.signal.aborted) break;
+        // Enqueue message into the internal message queue if available
+        if (currentAppState?.messageQueue) {
+          currentAppState.messageQueue.push(message);
+        }
+      }
+    } catch (e) {
+      if (!(e instanceof AbortError) && e?.name !== 'AbortError') {
+        throw e;
+      }
+    }
+  };
+
+  return gen;
+}
+
+// ---------------------------------------------------------------------------
+// AbortError class
+// ---------------------------------------------------------------------------
+
+export class AbortError extends Error {
+  constructor(message = 'Aborted') {
+    super(message);
+    this.name = 'AbortError';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// tool() helper — pure utility, no AST needed
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a tool definition.
+ *
+ * @param {string} name
+ * @param {string} description
+ * @param {object} inputSchema
+ * @param {Function} handler
+ * @returns {{ name: string, description: string, inputSchema: object, handler: Function }}
+ */
+export function tool(name, description, inputSchema, handler) {
+  return { name, description, inputSchema, handler };
+}
+
+// ---------------------------------------------------------------------------
+// createSdkMcpServer() — creates an in-process MCP server
+// ---------------------------------------------------------------------------
+//
+// FIX 1: instance must be a live McpServer, not a Promise.
+//
+// Strategy: import from claude-code's sdk.mjs (which bundles @modelcontextprotocol/sdk)
+// and extract the McpServer class from the instance constructor.  This gives us a
+// synchronous McpServer class reference after the first async bootstrap.
+//
+// The first call will be async (returns a Promise) but subsequent calls are sync
+// once the McpServer class is cached.  To get a fully-synchronous first call,
+// callers can call preload() first (or await ensureLoaded()).
+// ---------------------------------------------------------------------------
+
+/** Cached McpServer constructor (obtained from sdk.mjs on first use). */
+let _McpServerClass = null;
+/** Error from the first load attempt (if any). */
+let _McpServerLoadError = null;
+/** In-flight load promise — ensures only one attempt is made. */
+let _McpServerLoadPromise = null;
+
+/**
+ * Bootstrap the McpServer class from claude-code's bundled sdk.mjs.
+ * sdk.mjs bundles @modelcontextprotocol/sdk and exports createSdkMcpServer.
+ * We probe that factory to extract the McpServer constructor.
+ *
+ * Search order:
+ *   1. @modelcontextprotocol/sdk standalone package (if installed)
+ *   2. sdk.mjs in the located claude-code packageDir (for versions that have it)
+ *   3. sdk.mjs in any detected claude-code installation
+ *
+ * @returns {Promise<Function>}  McpServer constructor
+ */
+async function _loadMcpServerClass() {
+  if (_McpServerClass) return _McpServerClass;
+  if (_McpServerLoadError) throw _McpServerLoadError;
+  if (_McpServerLoadPromise) return _McpServerLoadPromise;
+
+  _McpServerLoadPromise = (async () => {
+    const errors = [];
+
+    // 1. Try @modelcontextprotocol/sdk standalone package
+    try {
+      const mod = await import('@modelcontextprotocol/sdk/server/mcp.js');
+      const Cls = mod.McpServer ?? mod.default?.McpServer;
+      if (Cls) {
+        _McpServerClass = Cls;
+        return Cls;
+      }
+    } catch (e) {
+      errors.push(`@modelcontextprotocol/sdk: ${e?.message}`);
+    }
+
+    // 2. Find sdk.mjs via locate() or known paths
+    const sdkMjsCandidates = [];
+
+    // From locate() (finds the active claude-code install)
+    try {
+      const loc = await locate();
+      if (loc?.packageDir) {
+        sdkMjsCandidates.push(join(loc.packageDir, 'sdk.mjs'));
+      }
+    } catch (e) {
+      errors.push(`locate(): ${e?.message}`);
+    }
+
+    // Known fallback paths (global nvm installs)
+    sdkMjsCandidates.push(
+      '/home/secemp9/.nvm/versions/node/v22.0.0/lib/node_modules/@anthropic-ai/claude-code/sdk.mjs',
+      join(homedir(), '.nvm', 'versions', 'node', 'v22.0.0', 'lib', 'node_modules', '@anthropic-ai', 'claude-code', 'sdk.mjs'),
+      // Also try next to cli.js if we can find it
+    );
+
+    for (const sdkMjsPath of sdkMjsCandidates) {
+      if (!sdkMjsPath || !existsSync(sdkMjsPath)) continue;
+      try {
+        const sdkMod = await import(sdkMjsPath);
+        const sdkFactory = sdkMod.createSdkMcpServer ?? sdkMod.default?.createSdkMcpServer;
+        if (!sdkFactory) {
+          errors.push(`${sdkMjsPath}: createSdkMcpServer not exported`);
+          continue;
+        }
+
+        // Probe: create a throwaway instance and grab the constructor
+        const probe = sdkFactory({ name: '__elwood_probe__', version: '0.0.0' });
+        const Cls = probe?.instance?.constructor;
+        if (!Cls || typeof Cls !== 'function') {
+          errors.push(`${sdkMjsPath}: McpServer constructor not accessible`);
+          continue;
+        }
+        _McpServerClass = Cls;
+        return Cls;
+      } catch (e) {
+        errors.push(`${sdkMjsPath}: ${e?.message}`);
+      }
+    }
+
+    _McpServerLoadPromise = null; // allow retry on next call
+    throw new Error(
+      'elwood: McpServer class could not be loaded.\n' +
+      'Tried:\n' + errors.map(e => `  - ${e}`).join('\n') + '\n' +
+      'Install @modelcontextprotocol/sdk or ensure @anthropic-ai/claude-code (≥2.0.0) is available.'
+    );
+  })();
+
+  _McpServerLoadPromise.catch(() => {});
+  return _McpServerLoadPromise;
+}
+
+/**
+ * Pre-warm the McpServer class loader.  Call this (and await it) during app
+ * startup so that createSdkMcpServer() can be used synchronously afterwards.
+ *
+ * @returns {Promise<void>}
+ */
+export async function preload(options = {}) {
+  await _loadMcpServerClass().catch(() => {});
+  return ensureLoaded(options);
+}
+
+/**
+ * Create an MCP server for use with the SDK transport.
+ *
+ * GAP 5 fix: Always safe to call without explicit preload().
+ * - If McpServer class is already cached (via preload() or a prior call), returns
+ *   `{ type: 'sdk', name, instance: McpServer }` synchronously.
+ * - If not yet loaded, returns a Promise that resolves to the same shape after
+ *   auto-triggering ensureLoaded(). This makes first-call async transparent.
+ *
+ * @param {{ name: string, version?: string, tools?: Array }} options
+ * @returns {{ type: 'sdk', name: string, instance: object } | Promise<{ type: 'sdk', name: string, instance: object }>}
+ */
+export function createSdkMcpServer(options) {
+  const name = options?.name ?? 'unnamed-server';
+  const version = options?.version ?? '1.0.0';
+
+  /**
+   * Helper: build the server instance and return the config object.
+   */
+  function _buildServer(McpServerClass) {
+    const server = new McpServerClass({ name, version }, {
+      capabilities: {
+        tools: options?.tools ? {} : undefined,
+      },
+    });
+    if (options?.tools?.length) {
+      for (const toolDef of options.tools) {
+        server.tool(toolDef.name, toolDef.description, toolDef.inputSchema, toolDef.handler);
+      }
+    }
+    return { type: 'sdk', name, instance: server };
+  }
+
+  // Fast path: McpServer class already cached — return synchronously
+  if (_McpServerClass) {
+    return _buildServer(_McpServerClass);
+  }
+
+  // GAP 5 fix: auto-trigger loading and return a Promise
+  // This makes createSdkMcpServer() always safe to call without preload().
+  return _loadMcpServerClass().then(McpServerClass => _buildServer(McpServerClass));
+}
+
+// ---------------------------------------------------------------------------
+// Reset helpers (for testing)
+// ---------------------------------------------------------------------------
+
+/**
+ * Reset the cached CLI exports.  Useful in tests.
+ * Not part of the public API.
+ */
+export function _resetCliCache() {
+  _loadPromise = null;
+  _cliExports = null;
+}
+
+// ---------------------------------------------------------------------------
+// FIX 7: HOOK_EVENTS and EXIT_REASONS constants
+// ---------------------------------------------------------------------------
+//
+// Verified via Babel AST: Jo1 in cli.js contains exactly these 9 hook event names.
+// EXIT_REASONS is declared as string[] in sdk.d.ts (not a const tuple).
+// Hardcoded here for stability — these are stable strings from the official sdk.d.ts.
+
+/**
+ * All valid hook event names (from sdk.d.ts and verified in cli.js as Jo1).
+ *
+ * @type {readonly string[]}
+ */
+export const HOOK_EVENTS = Object.freeze([
+  'PreToolUse',
+  'PostToolUse',
+  'PostToolUseFailure',
+  'Notification',
+  'UserPromptSubmit',
+  'SessionStart',
+  'SessionEnd',
+  'Stop',
+  'SubagentStart',
+  'SubagentStop',
+  'PreCompact',
+  'PermissionRequest',
+]);
+
+/**
+ * All valid exit reason strings.
+ *
+ * @type {readonly string[]}
+ */
+export const EXIT_REASONS = Object.freeze([
+  'clear',
+  'logout',
+  'prompt_input_exit',
+  'other',
+  'bypass_permissions_disabled',
+]);
+
+// ---------------------------------------------------------------------------
+// FIX 9: Session utility functions (pure Node.js file I/O)
+//
+// These are NOT found in cli.js with confidence >= 0.4 via Babel AST.
+// Implemented directly as file-system operations on ~/.claude/projects/*.jsonl
+// This is acceptable — it's pure file I/O, not subprocess invocation.
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the ~/.claude/projects directory path.
+ *
+ * @returns {string}
+ */
+function _getProjectsDir() {
+  return join(homedir(), '.claude', 'projects');
+}
+
+/**
+ * Parse a UUID-like string from a file path or session ID.
+ * Returns the string as-is if it looks like a session ID.
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+function _normalizeSessionId(str) {
+  return str.replace(/\.jsonl$/, '');
+}
+
+/**
+ * List all sessions stored in ~/.claude/projects/.
+ *
+ * Sessions are stored as:  ~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl
+ *
+ * @param {{ cwd?: string }} [options]
+ * @returns {Promise<Array<{ sessionId: string, projectPath: string, filePath: string, mtime: Date }>>}
+ */
+export async function listSessions(options = {}) {
+  const projectsDir = _getProjectsDir();
+  const results = [];
+
+  try {
+    const projectDirs = readdirSync(projectsDir, { withFileTypes: true })
+      .filter(e => e.isDirectory())
+      .map(e => e.name);
+
+    for (const pd of projectDirs) {
+      const pdPath = join(projectsDir, pd);
+      let jsonlFiles;
+      try {
+        jsonlFiles = readdirSync(pdPath, { withFileTypes: true })
+          .filter(e => e.isFile() && e.name.endsWith('.jsonl'))
+          .map(e => e.name);
+      } catch {
+        continue;
+      }
+
+      for (const jf of jsonlFiles) {
+        const filePath = join(pdPath, jf);
+        let mtime = new Date(0);
+        try {
+          const st = statSync(filePath);
+          mtime = st.mtime;
+        } catch {
+          // ignore
+        }
+
+        results.push({
+          sessionId: _normalizeSessionId(jf),
+          projectPath: pd,
+          filePath,
+          mtime,
+        });
+      }
+    }
+  } catch {
+    // projectsDir may not exist — return empty array
+    return [];
+  }
+
+  // Sort by mtime descending (most recent first)
+  results.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+
+  // If cwd filter provided, filter by matching project path
+  if (options.cwd) {
+    const cwdEncoded = encodeURIComponent(options.cwd).replace(/%2F/gi, '-');
+    return results.filter(r => r.projectPath.includes(cwdEncoded) || r.projectPath === cwdEncoded);
+  }
+
+  return results;
+}
+
+/**
+ * Read all messages from a session JSONL file.
+ *
+ * @param {string} sessionId  - Session ID (UUID) or path to .jsonl file
+ * @param {{ cwd?: string }} [options]
+ * @returns {Promise<Array<object>>}
+ */
+export async function getSessionMessages(sessionId, options = {}) {
+  let filePath = sessionId;
+
+  // If not a file path, try to resolve it
+  if (!filePath.endsWith('.jsonl') && !filePath.includes('/')) {
+    const sessions = await listSessions(options);
+    const match = sessions.find(s => s.sessionId === sessionId);
+    if (!match) return [];
+    filePath = match.filePath;
+  }
+
+  try {
+    const content = readFileSync(filePath, 'utf8');
+    const lines = content.split('\n').filter(l => l.trim().length > 0);
+    const messages = [];
+    for (const line of lines) {
+      try {
+        messages.push(JSON.parse(line));
+      } catch {
+        // Skip malformed lines
+      }
+    }
+    return messages;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Get metadata about a specific session.
+ *
+ * @param {string} sessionId
+ * @param {{ cwd?: string }} [options]
+ * @returns {Promise<{ sessionId: string, projectPath: string, filePath: string, mtime: Date, messageCount: number } | null>}
+ */
+export async function getSessionInfo(sessionId, options = {}) {
+  const sessions = await listSessions(options);
+  const match = sessions.find(s => s.sessionId === sessionId);
+  if (!match) return null;
+
+  let messageCount = 0;
+  try {
+    const content = readFileSync(match.filePath, 'utf8');
+    messageCount = content.split('\n').filter(l => l.trim().length > 0).length;
+  } catch {
+    // ignore
+  }
+
+  return {
+    sessionId: match.sessionId,
+    projectPath: match.projectPath,
+    filePath: match.filePath,
+    mtime: match.mtime,
+    messageCount,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// FIX 9: V2 Session API
+//
+// These match the official @anthropic-ai/claude-agent-sdk V2 UNSTABLE API.
+// In elwood's in-process architecture, sessions are implemented using the
+// query() function internally, wrapping it in a stateful Session object.
+// ---------------------------------------------------------------------------
+
+/**
+ * Internal Stream class for V2 session input queueing.
+ * Mirrors the official SDK's Stream utility.
+ */
+class _ElwoodStream {
+  constructor() {
+    this._queue = [];
+    this._resolve = null;
+    this._done = false;
+    this._error = null;
+    this._started = false;
+  }
+
+  [Symbol.asyncIterator]() {
+    if (this._started) throw new Error('Stream can only be iterated once');
+    this._started = true;
+    return this;
+  }
+
+  next() {
+    if (this._queue.length > 0) {
+      return Promise.resolve({ done: false, value: this._queue.shift() });
+    }
+    if (this._done) {
+      return Promise.resolve({ done: true, value: undefined });
+    }
+    if (this._error) {
+      return Promise.reject(this._error);
+    }
+    return new Promise((resolve, reject) => {
+      this._resolve = resolve;
+      this._reject = reject;
+    });
+  }
+
+  enqueue(value) {
+    if (this._resolve) {
+      const resolve = this._resolve;
+      this._resolve = null;
+      this._reject = null;
+      resolve({ done: false, value });
+    } else {
+      this._queue.push(value);
+    }
+  }
+
+  done() {
+    this._done = true;
+    if (this._resolve) {
+      const resolve = this._resolve;
+      this._resolve = null;
+      this._reject = null;
+      resolve({ done: true, value: undefined });
+    }
+  }
+
+  error(err) {
+    this._error = err;
+    if (this._reject) {
+      const reject = this._reject;
+      this._resolve = null;
+      this._reject = null;
+      reject(err);
+    }
+  }
+
+  return() {
+    this._done = true;
+    return Promise.resolve({ done: true, value: undefined });
+  }
+}
+
+/**
+ * V2 API - UNSTABLE
+ * Internal session implementation.
+ */
+class _ElwoodSession {
+  constructor(options) {
+    this._closed = false;
+    this._sessionId = options.resume ?? null;
+    this._inputStream = new _ElwoodStream();
+    this._abortController = new AbortController();
+
+    // Create the underlying query with streaming input
+    this._query = query({
+      prompt: this._inputStream,
+      options: {
+        model: options.model,
+        env: options.env,
+        resume: options.resume,
+        abortController: this._abortController,
+      },
+    });
+
+    this._queryIterator = null;
+  }
+
+  get sessionId() {
+    if (this._sessionId === null) {
+      throw new Error('Session ID not available until after receiving messages');
+    }
+    return this._sessionId;
+  }
+
+  async send(message) {
+    if (this._closed) {
+      throw new Error('Cannot send to closed session');
+    }
+    const userMessage = typeof message === 'string'
+      ? {
+          type: 'user',
+          session_id: '',
+          message: {
+            role: 'user',
+            content: [{ type: 'text', text: message }],
+          },
+          parent_tool_use_id: null,
+        }
+      : message;
+    this._inputStream.enqueue(userMessage);
+  }
+
+  async* stream() {
+    if (!this._queryIterator) {
+      this._queryIterator = this._query[Symbol.asyncIterator]();
+    }
+    while (true) {
+      const { value, done } = await this._queryIterator.next();
+      if (done) return;
+      // Capture session ID from init message
+      if (value?.type === 'system' && value?.subtype === 'init') {
+        this._sessionId = value.session_id;
+      }
+      yield value;
+      if (value?.type === 'result') return;
+    }
+  }
+
+  close() {
+    if (this._closed) return;
+    this._closed = true;
+    this._inputStream.done();
+    this._abortController.abort();
+  }
+
+  async [Symbol.asyncDispose]() {
+    this.close();
+  }
+}
+
+/**
+ * V2 API - UNSTABLE
+ * Create a persistent session for multi-turn conversations.
+ *
+ * @param {object} options - Session options (model, env, etc.)
+ * @returns {object} SDKSession interface
+ */
+export function unstable_v2_createSession(options) {
+  return new _ElwoodSession(options);
+}
+
+/**
+ * V2 API - UNSTABLE
+ * Resume an existing session by ID.
+ *
+ * @param {string} sessionId - Session ID to resume
+ * @param {object} options - Session options
+ * @returns {object} SDKSession interface
+ */
+export function unstable_v2_resumeSession(sessionId, options) {
+  return new _ElwoodSession({ ...options, resume: sessionId });
+}
+
+/**
+ * V2 API - UNSTABLE
+ * One-shot convenience function for single prompts.
+ *
+ * @param {string} message - The prompt message
+ * @param {object} options - Session options
+ * @returns {Promise<object>} SDKResultMessage
+ */
+export async function unstable_v2_prompt(message, options) {
+  const session = unstable_v2_createSession(options);
+  try {
+    await session.send(message);
+    for await (const msg of session.stream()) {
+      if (msg.type === 'result') {
+        return msg;
+      }
+    }
+    throw new Error('Session ended without result message');
+  } finally {
+    session.close();
+  }
+}