wind-agent-cli 1.37.2 → 1.38.0

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

@@ -1,1068 +1,1068 @@
-/**
- * Claude SDK Integration
- *
- * This module provides SDK-based integration with Claude using the @anthropic-ai/claude-agent-sdk.
- * It mirrors the interface of claude-cli.js but uses the SDK internally for better performance
- * and maintainability.
- *
- * Key features:
- * - Direct SDK integration without child processes
- * - Session management with abort capability
- * - Options mapping between CLI and SDK formats
- * - WebSocket message streaming
- */
-
-import crypto from 'crypto';
-import { promises as fs } from 'fs';
-import os from 'os';
-import path from 'path';
-
-import { query } from '@anthropic-ai/claude-agent-sdk';
-
-import {
-  appendFilesInputTag,
-  buildClaudeUserContent,
-  normalizeImageDescriptors
-} from '@/shared/image-attachments.js';
-import { CLAUDE_PREDEFINED_MODELS } from '@/modules/providers/list/claude/claude-models.provider.js';
-import { resolveClaudeCodeExecutablePath } from '@/shared/claude-cli-path.js';
-import {
-  createNotificationEvent,
-  notifyBackgroundWorkCompleted,
-  notifyRunFailed,
-  notifyRunStopped,
-  notifyUserIfEnabled
-} from '@/modules/notifications/index.js';
-import { createCompleteMessage, createNormalizedMessage } from '@/shared/utils.js';
-
-const activeSessions = new Map();
-const pendingToolApprovals = new Map();
-// Sessions cancelled via abort-session. The abort handler already sent the
-// terminal `complete` (aborted: true) to the client, so the run loop must not
-// emit a second one when its generator winds down.
-const abortedSessionIds = new Set();
-// Query instances interrupted because a newer run took over their session id
-// (see addSession). Their run loops must stay silent on wind-down: the map
-// entry, the abort flag, and all client-facing events belong to the new run.
-const supersededInstances = new WeakSet();
-
-const TOOL_APPROVAL_TIMEOUT_MS = parseInt(process.env.CLAUDE_TOOL_APPROVAL_TIMEOUT_MS, 10) || 55000;
-
-// How long background work is allowed to keep running after a turn ends. This drives
-// two halves of the same behaviour:
-//
-//  1. Passed to the spawned CLI as CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS, which is how
-//     long it waits for still-running background *agents* before killing them.
-//  2. A backstop on how long we hold the SDK's stdin open after a turn's `result`.
-//     The SDK closes stdin as soon as a turn ends, and the CLI reads that EOF as
-//     "print wind-down" — killing background *shells* after a short grace period,
-//     which the ceiling above does not cover. Holding stdin open also lets the CLI
-//     push follow-up turns (background-task completions, Monitor notifications,
-//     scheduled wake-ups).
-//
-// The hold normally ends long before this: a turn with nothing outstanding closes
-// stdin immediately, background work releases it as soon as it reports back, and a
-// new turn supersedes the previous hold. This ceiling only catches background work
-// that never reports at all, so an abandoned session cannot leak a CLI process
-// forever. The timer resets on every message, so it measures silence, not total time.
-const BG_WAIT_CEILING_MS = 30 * 60 * 1000;
-
-const TOOLS_REQUIRING_INTERACTION = new Set(['AskUserQuestion', 'ExitPlanMode']);
-
-function resolveClaudeEffort(model, effort, modelsDefinition = CLAUDE_PREDEFINED_MODELS) {
-  const selectedModel = modelsDefinition?.OPTIONS?.find((option) => option.value === model) || null;
-  const allowedEfforts = selectedModel?.effort?.values
-    ?.map((value) => value.value) || [];
-  return typeof effort === 'string' && effort !== 'default' && allowedEfforts.includes(effort)
-    ? effort
-    : undefined;
-}
-
-function createRequestId() {
-  if (typeof crypto.randomUUID === 'function') {
-    return crypto.randomUUID();
-  }
-  return crypto.randomBytes(16).toString('hex');
-}
-
-function waitForToolApproval(requestId, options = {}) {
-  const { timeoutMs = TOOL_APPROVAL_TIMEOUT_MS, signal, onCancel, metadata } = options;
-
-  return new Promise(resolve => {
-    let settled = false;
-
-    const finalize = (decision) => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      resolve(decision);
-    };
-
-    let timeout;
-
-    const cleanup = () => {
-      pendingToolApprovals.delete(requestId);
-      if (timeout) clearTimeout(timeout);
-      if (signal && abortHandler) {
-        signal.removeEventListener('abort', abortHandler);
-      }
-    };
-
-    // timeoutMs 0 = wait indefinitely (interactive tools)
-    if (timeoutMs > 0) {
-      timeout = setTimeout(() => {
-        onCancel?.('timeout');
-        finalize(null);
-      }, timeoutMs);
-    }
-
-    const abortHandler = () => {
-      onCancel?.('cancelled');
-      finalize({ cancelled: true });
-    };
-
-    if (signal) {
-      if (signal.aborted) {
-        onCancel?.('cancelled');
-        finalize({ cancelled: true });
-        return;
-      }
-      signal.addEventListener('abort', abortHandler, { once: true });
-    }
-
-    const resolver = (decision) => {
-      finalize(decision);
-    };
-    // Attach metadata for getPendingApprovalsForSession lookup
-    if (metadata) {
-      Object.assign(resolver, metadata);
-    }
-    pendingToolApprovals.set(requestId, resolver);
-  });
-}
-
-function resolveToolApproval(requestId, decision) {
-  const resolver = pendingToolApprovals.get(requestId);
-  if (resolver) {
-    resolver(decision);
-  }
-}
-
-// Match stored permission entries against a tool + input combo.
-// This only supports exact tool names and the Bash(command:*) shorthand
-// used by the UI; it intentionally does not implement full glob semantics,
-// introduced to stay consistent with the UI's "Allow rule" format.
-function matchesToolPermission(entry, toolName, input) {
-  if (!entry || !toolName) {
-    return false;
-  }
-
-  if (entry === toolName) {
-    return true;
-  }
-
-  const bashMatch = entry.match(/^Bash\((.+):\*\)$/);
-  if (toolName === 'Bash' && bashMatch) {
-    const allowedPrefix = bashMatch[1];
-    let command = '';
-
-    if (typeof input === 'string') {
-      command = input.trim();
-    } else if (input && typeof input === 'object' && typeof input.command === 'string') {
-      command = input.command.trim();
-    }
-
-    if (!command) {
-      return false;
-    }
-
-    return command.startsWith(allowedPrefix);
-  }
-
-  return false;
-}
-
-function mapCliOptionsToSDK(options = {}) {
-  const { providerSessionId, cwd, toolsSettings, permissionMode, effort } = options;
-
-  const sdkOptions = {};
-
-  // Forward all host env vars (e.g. ANTHROPIC_BASE_URL) to the subprocess.
-  // Since SDK 0.2.113, options.env replaces process.env instead of overlaying it.
-  sdkOptions.env = { ...process.env, CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS: String(BG_WAIT_CEILING_MS) };
-
-  // Resolve the executable eagerly on Windows because the SDK uses raw child_process.spawn,
-  // which does not reliably follow npm's shell wrappers like cross-spawn does.
-  sdkOptions.pathToClaudeCodeExecutable = resolveClaudeCodeExecutablePath(process.env.CLAUDE_CLI_PATH);
-
-  if (cwd) {
-    sdkOptions.cwd = cwd;
-  }
-
-  if (permissionMode && permissionMode !== 'default') {
-    sdkOptions.permissionMode = permissionMode;
-  }
-
-  const settings = toolsSettings || {
-    allowedTools: [],
-    disallowedTools: [],
-    skipPermissions: false
-  };
-
-  if (settings.skipPermissions && permissionMode !== 'plan') {
-    sdkOptions.permissionMode = 'bypassPermissions';
-  }
-
-  let allowedTools = [...(settings.allowedTools || [])];
-
-  if (permissionMode === 'plan') {
-    const planModeTools = ['Read', 'Task', 'exit_plan_mode', 'TodoRead', 'TodoWrite', 'WebFetch', 'WebSearch'];
-    for (const tool of planModeTools) {
-      if (!allowedTools.includes(tool)) {
-        allowedTools.push(tool);
-      }
-    }
-  }
-
-  sdkOptions.allowedTools = allowedTools;
-
-  // Use the tools preset to make all default built-in tools available (including AskUserQuestion).
-  // This was introduced in SDK 0.1.57. Omitting this preserves existing behavior (all tools available),
-  // but being explicit ensures forward compatibility and clarity.
-  sdkOptions.tools = { type: 'preset', preset: 'claude_code' };
-
-  sdkOptions.disallowedTools = settings.disallowedTools || [];
-
-  sdkOptions.model = options.model || CLAUDE_PREDEFINED_MODELS.DEFAULT;
-
-  const resolvedEffort = resolveClaudeEffort(
-    sdkOptions.model,
-    effort,
-    options.effortModels || CLAUDE_PREDEFINED_MODELS,
-  );
-  if (resolvedEffort) {
-    sdkOptions.effort = resolvedEffort;
-  }
-
-  sdkOptions.systemPrompt = {
-    type: 'preset',
-    preset: 'claude_code'
-  };
-
-  sdkOptions.settingSources = ['project', 'user', 'local'];
-
-  // The SDK resumes with the provider-native session id, never the app id.
-  if (providerSessionId) {
-    sdkOptions.resume = providerSessionId;
-  }
-
-  return sdkOptions;
-}
-
-/**
- * Adds a session to the active sessions map
- * @param {string} sessionId - Session identifier
- * @param {Object} queryInstance - SDK query instance
- * @param {Object} writer - WebSocket writer for reconnect support
- * @param {Function} releaseInput - Closes the held stdin stream so the CLI can exit
- */
-function addSession(sessionId, queryInstance, writer = null, releaseInput = null) {
-  const existing = activeSessions.get(sessionId);
-  // A different live instance under the same key means an earlier run was
-  // superseded without being stopped (e.g. an abort that raced run setup and
-  // found nothing to interrupt). Overwriting it here would strand its
-  // generator forever — this map entry is the only handle for interrupting
-  // it. Stop it directly rather than via abortClaudeSDKSession, whose
-  // session-keyed abortedSessionIds flag would be consumed by the new run
-  // and suppress its terminal `complete`.
-  const superseding = Boolean(
-    existing && existing.status === 'active' && existing.instance && existing.instance !== queryInstance
-  );
-  if (superseding) {
-    supersededInstances.add(existing.instance);
-    Promise.resolve()
-      .then(() => existing.instance.interrupt())
-      .catch((error) => {
-        console.error(`Error interrupting superseded run for session ${sessionId}:`, error?.message || error);
-      });
-    existing.releaseInput?.();
-  }
-  const carried = superseding ? null : existing;
-  activeSessions.set(sessionId, {
-    instance: queryInstance,
-    startTime: carried?.startTime || Date.now(),
-    status: 'active',
-    writer,
-    // Re-registered mid-run once the provider session id lands; keep the closer.
-    releaseInput: releaseInput || carried?.releaseInput || null
-  });
-}
-
-/**
- * Removes a session from the active sessions map
- * @param {string} sessionId - Session identifier
- */
-function removeSession(sessionId) {
-  activeSessions.delete(sessionId);
-}
-
-/**
- * Gets a session from the active sessions map
- * @param {string} sessionId - Session identifier
- * @returns {Object|undefined} Session data or undefined
- */
-function getSession(sessionId) {
-  return activeSessions.get(sessionId);
-}
-
-/**
- * Gets all active session IDs
- * @returns {Array<string>} Array of active session IDs
- */
-function getAllSessions() {
-  return Array.from(activeSessions.keys());
-}
-
-/**
- * Transforms SDK messages to WebSocket format expected by frontend
- * @param {Object} sdkMessage - SDK message object
- * @returns {Object} Transformed message ready for WebSocket
- */
-function transformMessage(sdkMessage) {
-  // Extract parent_tool_use_id for subagent tool grouping
-  if (sdkMessage.parent_tool_use_id) {
-    return {
-      ...sdkMessage,
-      parentToolUseId: sdkMessage.parent_tool_use_id
-    };
-  }
-  return sdkMessage;
-}
-
-function readNumber(value) {
-  const parsed = Number(value);
-  return Number.isFinite(parsed) ? parsed : 0;
-}
-
-/**
- * Extracts token usage from SDK messages.
- * Prefers per-step `message.usage` (Claude message payload), then falls back
- * to result-level usage/modelUsage for compatibility across SDK versions.
- * @param {Object} sdkMessage - SDK stream message
- * @returns {Object|null} Token budget object or null
- */
-function extractTokenBudget(sdkMessage) {
-  if (!sdkMessage || typeof sdkMessage !== 'object') {
-    return null;
-  }
-
-  const messageUsage = sdkMessage.message?.usage || sdkMessage.usage;
-  if (messageUsage && typeof messageUsage === 'object') {
-    const directInputTokens = readNumber(messageUsage.input_tokens ?? messageUsage.inputTokens);
-    const cacheCreationTokens = readNumber(messageUsage.cache_creation_input_tokens ?? messageUsage.cacheCreationInputTokens ?? messageUsage.cacheCreationTokens);
-    const cacheReadTokens = readNumber(messageUsage.cache_read_input_tokens ?? messageUsage.cacheReadInputTokens ?? messageUsage.cacheReadTokens);
-    const cacheTokens = cacheCreationTokens + cacheReadTokens;
-    const inputTokens = directInputTokens + cacheTokens;
-    const outputTokens = readNumber(messageUsage.output_tokens ?? messageUsage.outputTokens);
-    const totalUsed = inputTokens + outputTokens;
-    const contextWindow = parseInt(process.env.CONTEXT_WINDOW, 10) || 160000;
-
-    return {
-      used: totalUsed,
-      total: contextWindow,
-      inputTokens,
-      outputTokens,
-      cacheReadTokens,
-      cacheCreationTokens,
-      cacheTokens,
-      breakdown: {
-        input: inputTokens,
-        output: outputTokens,
-      },
-    };
-  }
-
-  if (!sdkMessage.modelUsage || typeof sdkMessage.modelUsage !== 'object') {
-    return null;
-  }
-
-  // Fallback for older SDK messages with only modelUsage
-  const modelKey = Object.keys(sdkMessage.modelUsage)[0];
-  const modelData = sdkMessage.modelUsage[modelKey];
-
-  if (!modelData || typeof modelData !== 'object') {
-    return null;
-  }
-
-  const inputTokens = readNumber(modelData.cumulativeInputTokens ?? modelData.inputTokens);
-  const outputTokens = readNumber(modelData.cumulativeOutputTokens ?? modelData.outputTokens);
-  const totalUsed = inputTokens + outputTokens;
-  const contextWindow = parseInt(process.env.CONTEXT_WINDOW, 10) || 160000;
-
-  return {
-    used: totalUsed,
-    total: contextWindow,
-    inputTokens,
-    outputTokens,
-    breakdown: {
-      input: inputTokens,
-      output: outputTokens,
-    },
-  };
-}
-
-// Tool calls that leave work running past the end of a turn. Bash only counts
-// when it is explicitly backgrounded; the rest defer or watch work by nature.
-const DEFERRED_WORK_TOOLS = new Set(['Monitor', 'ScheduleWakeup', 'CronCreate', 'TaskCreate']);
-
-/**
- * Detects tool calls that keep working after the turn's `result` arrives.
- *
- * Only turns that start background work need their CLI process held open; every
- * other turn can let it exit immediately, as it did before the hold existed.
- *
- * @param {Object} sdkMessage - SDK stream message
- * @returns {boolean} True when the message launches work that outlives the turn
- */
-function startsBackgroundWork(sdkMessage) {
-  const content = sdkMessage?.message?.content;
-  if (!Array.isArray(content)) {
-    return false;
-  }
-
-  return content.some((block) => {
-    if (block?.type !== 'tool_use') {
-      return false;
-    }
-    if (block.name === 'Bash') {
-      return block.input?.run_in_background === true;
-    }
-    return DEFERRED_WORK_TOOLS.has(block.name);
-  });
-}
-
-/**
- * Builds the SDK user messages for one turn.
- *
- * Always returns SDKUserMessage records rather than a bare string: a string
- * prompt makes the SDK flag the query as single-turn and close stdin the moment
- * the turn's `result` arrives, which kills the CLI's background tasks. Plain
- * text turns carry string content; turns with image attachments carry the
- * prompt text plus one base64 `image` block per attachment (read from the
- * global `~/.cloudcli/assets` folder).
- *
- * @param {string} command - User prompt
- * @param {Array} images - Image descriptors ({ path, name?, mimeType? })
- * @param {Array} files - Non-image attachment descriptors
- * @param {string} cwd - Project working directory attachment paths resolve against
- * @returns {Promise<Array<Object>>} SDKUserMessage records for the turn
- */
-async function buildPromptMessages(command, images, files, cwd) {
-  const promptWithFiles = appendFilesInputTag(command, files);
-  const content = normalizeImageDescriptors(images).length === 0
-    ? promptWithFiles
-    : await buildClaudeUserContent(promptWithFiles, images, cwd);
-
-  return [{
-    type: 'user',
-    message: {
-      role: 'user',
-      content
-    },
-    parent_tool_use_id: null,
-    timestamp: new Date().toISOString()
-  }];
-}
-
-/**
- * Wraps prompt messages in an async iterable that yields them and then parks.
- *
- * The SDK closes the CLI's stdin as soon as its input iterable is exhausted (and
- * immediately on `result` for string prompts). The CLI reads that EOF as the end
- * of the run and kills anything still going in the background, so the iterable
- * has to stay pending until we actually want the process gone.
- *
- * @param {Array<Object>} messages - SDKUserMessage records to send
- * @returns {{ stream: AsyncIterable, release: () => void }} Stream plus its closer
- */
-function createHeldPromptStream(messages) {
-  let release;
-  const held = new Promise((resolve) => { release = resolve; });
-
-  const stream = (async function* () {
-    for (const message of messages) {
-      yield message;
-    }
-    // Keeps stdin open — the CLI stays alive until release() is called.
-    await held;
-  })();
-
-  return { stream, release };
-}
-
-/**
- * Loads MCP server configurations from ~/.claude.json
- * @param {string} cwd - Current working directory for project-specific configs
- * @returns {Object|null} MCP servers object or null if none found
- */
-async function loadMcpConfig(cwd) {
-  try {
-    const claudeConfigPath = path.join(os.homedir(), '.claude.json');
-
-    // Check if config file exists
-    try {
-      await fs.access(claudeConfigPath);
-    } catch (error) {
-      // File doesn't exist, return null
-      // No config file
-      return null;
-    }
-
-    // Read and parse config file
-    let claudeConfig;
-    try {
-      const configContent = await fs.readFile(claudeConfigPath, 'utf8');
-      claudeConfig = JSON.parse(configContent);
-    } catch (error) {
-      console.error('Failed to parse ~/.claude.json:', error.message);
-      return null;
-    }
-
-    // Extract MCP servers (merge global and project-specific)
-    let mcpServers = {};
-
-    // Add global MCP servers
-    if (claudeConfig.mcpServers && typeof claudeConfig.mcpServers === 'object') {
-      mcpServers = { ...claudeConfig.mcpServers };
-      // Global MCP servers loaded
-    }
-
-    // Add/override with project-specific MCP servers
-    if (claudeConfig.claudeProjects && cwd) {
-      const projectConfig = claudeConfig.claudeProjects[cwd];
-      if (projectConfig && projectConfig.mcpServers && typeof projectConfig.mcpServers === 'object') {
-        mcpServers = { ...mcpServers, ...projectConfig.mcpServers };
-        // Project MCP servers merged
-      }
-    }
-
-    // Return null if no servers found
-    if (Object.keys(mcpServers).length === 0) {
-      return null;
-    }
-    return mcpServers;
-  } catch (error) {
-    console.error('Error loading MCP config:', error.message);
-    return null;
-  }
-}
-
-/**
- * Executes a Claude query using the SDK
- * @param {string} command - User prompt/command
- * @param {Object} options - Query options
- * @param {Object} ws - WebSocket connection
- * @param {Object} context - Provider-scoped model, session, and auth lookups
- * @returns {Promise<void>}
- */
-async function queryClaudeSDK(command, options = {}, ws, context) {
-  const { sessionId, sessionSummary } = options;
-  // Callers pass the stable app session id; the SDK only understands the
-  // provider-native id recorded on the session row.
-  const providerSessionId = context.resolveProviderSessionId(sessionId);
-  // Provider-native id as the SDK reports it (starts as the resume id, or is
-  // captured from the stream for brand-new sessions).
-  let capturedSessionId = providerSessionId;
-  let sessionCreatedSent = false;
-  // Process-map key: the app session id when the caller supplied one, else
-  // the provider-native id once captured (legacy/direct API callers).
-  const sessionKey = () => sessionId || capturedSessionId || null;
-
-  const emitNotification = (event) => {
-    notifyUserIfEnabled({
-      userId: ws?.userId || null,
-      writer: ws,
-      event
-    });
-  };
-
-  // Closes the held stdin stream so the CLI can wind down. Replaced once the
-  // stream exists; the finally block calls it no matter how the run ends.
-  let releasePromptStream = () => {};
-  let idleReleaseTimer = null;
-  // The client is told the turn is over as soon as `result` lands, even though
-  // the process lingers, so the UI never waits out the idle hold.
-  let turnCompleteSent = false;
-  // Set when a turn starts background work, cleared when the next `result`
-  // arrives — only turns with work still outstanding hold their process open.
-  let backgroundWorkPending = false;
-  // True while the process is being held open for background work, so a later
-  // `result` can be recognised as that work reporting back.
-  let heldForBackgroundWork = false;
-
-  // A new turn supersedes any earlier one still holding this session's process
-  // open, so held runs cannot stack up across a conversation.
-  if (sessionKey()) {
-    getSession(sessionKey())?.releaseInput?.();
-  }
-
-  // Arms (or re-arms) the idle countdown that eventually closes stdin.
-  const scheduleRelease = () => {
-    if (idleReleaseTimer) {
-      clearTimeout(idleReleaseTimer);
-      idleReleaseTimer = null;
-    }
-    idleReleaseTimer = setTimeout(() => {
-      idleReleaseTimer = null;
-      releasePromptStream();
-    }, BG_WAIT_CEILING_MS);
-    // Never let the hold keep the server process alive on its own.
-    idleReleaseTimer.unref?.();
-  };
-
-  // Hoisted above the try so the catch's cleanup can tell whether this run
-  // still owns the activeSessions entry (or was superseded by a newer run).
-  let queryInstance = null;
-
-  try {
-    const resolvedModel = await context.resolveResumeModel(sessionId, options.model);
-    let effortModels = CLAUDE_PREDEFINED_MODELS;
-    try {
-      effortModels = await context.getProviderModels();
-    } catch (error) {
-      console.warn('[Claude SDK] Unable to load provider models for effort validation:', error);
-    }
-
-    const sdkOptions = mapCliOptionsToSDK({
-      ...options,
-      providerSessionId,
-      model: resolvedModel || options.model,
-      effortModels,
-    });
-
-    const mcpServers = await loadMcpConfig(options.cwd);
-    if (mcpServers) {
-      sdkOptions.mcpServers = mcpServers;
-    }
-
-    // Every turn uses streaming input so stdin stays open past the turn's
-    // `result`. The message list is reusable, but each query attempt needs its
-    // own stream because an async generator cannot be replayed once consumed.
-    const promptMessages = await buildPromptMessages(command, options.images, options.files, options.cwd);
-
-    sdkOptions.hooks = {
-      Notification: [{
-        matcher: '',
-        hooks: [async (input) => {
-          const message = typeof input?.message === 'string' ? input.message : 'Claude requires your attention.';
-          // Notifications are app-facing, so they carry the app session id.
-          emitNotification(createNotificationEvent({
-            provider: 'claude',
-            sessionId: sessionId || capturedSessionId || null,
-            kind: 'action_required',
-            code: 'agent.notification',
-            meta: { message, sessionName: sessionSummary },
-            severity: 'warning',
-            requiresUserAction: true,
-            dedupeKey: `claude:hook:notification:${sessionId || capturedSessionId || 'none'}:${message}`
-          }));
-          return {};
-        }]
-      }]
-    };
-
-    // Caveat: in 'auto' and 'bypassPermissions' modes the SDK resolves approval
-    // at the permission-mode step and skips this callback, so interactive tools
-    // (AskUserQuestion, ExitPlanMode) won't reach the UI — the classifier/bypass
-    // auto-approves them and the model acts on a generated answer. Move these
-    // tools to a PreToolUse hook (runs before the mode check) if we need them
-    // to work in those modes.
-    sdkOptions.canUseTool = async (toolName, input, context) => {
-      const requiresInteraction = TOOLS_REQUIRING_INTERACTION.has(toolName);
-
-      if (!requiresInteraction) {
-        if (sdkOptions.permissionMode === 'bypassPermissions') {
-          return { behavior: 'allow', updatedInput: input };
-        }
-
-        const isDisallowed = (sdkOptions.disallowedTools || []).some(entry =>
-          matchesToolPermission(entry, toolName, input)
-        );
-        if (isDisallowed) {
-          return { behavior: 'deny', message: 'Tool disallowed by settings' };
-        }
-
-        const isAllowed = (sdkOptions.allowedTools || []).some(entry =>
-          matchesToolPermission(entry, toolName, input)
-        );
-        if (isAllowed) {
-          return { behavior: 'allow', updatedInput: input };
-        }
-      }
-
-      const requestId = createRequestId();
-      ws.send(createNormalizedMessage({ kind: 'permission_request', requestId, toolName, input, sessionId: capturedSessionId || sessionId || null, provider: 'claude' }));
-      emitNotification(createNotificationEvent({
-        provider: 'claude',
-        sessionId: sessionId || capturedSessionId || null,
-        kind: 'action_required',
-        code: 'permission.required',
-        meta: { toolName, sessionName: sessionSummary },
-        severity: 'warning',
-        requiresUserAction: true,
-        dedupeKey: `claude:permission:${sessionId || capturedSessionId || 'none'}:${requestId}`
-      }));
-
-      const decision = await waitForToolApproval(requestId, {
-        timeoutMs: requiresInteraction ? 0 : undefined,
-        signal: context?.signal,
-        metadata: {
-          // Keyed by the app session id so `chat.subscribe` can look pending
-          // approvals up directly; provider id only for legacy callers.
-          _sessionId: sessionId || capturedSessionId || null,
-          _toolName: toolName,
-          _input: input,
-          _receivedAt: new Date(),
-        },
-        onCancel: (reason) => {
-          ws.send(createNormalizedMessage({ kind: 'permission_cancelled', requestId, reason, sessionId: capturedSessionId || sessionId || null, provider: 'claude' }));
-        }
-      });
-      if (!decision) {
-        return { behavior: 'deny', message: 'Permission request timed out' };
-      }
-
-      if (decision.cancelled) {
-        return { behavior: 'deny', message: 'Permission request cancelled' };
-      }
-
-      if (decision.allow) {
-        if (decision.rememberEntry && typeof decision.rememberEntry === 'string') {
-          if (!sdkOptions.allowedTools.includes(decision.rememberEntry)) {
-            sdkOptions.allowedTools.push(decision.rememberEntry);
-          }
-          if (Array.isArray(sdkOptions.disallowedTools)) {
-            sdkOptions.disallowedTools = sdkOptions.disallowedTools.filter(entry => entry !== decision.rememberEntry);
-          }
-        }
-        return { behavior: 'allow', updatedInput: decision.updatedInput ?? input };
-      }
-
-      return { behavior: 'deny', message: decision.message ?? 'User denied tool use' };
-    };
-
-    let heldPrompt = createHeldPromptStream(promptMessages);
-    releasePromptStream = heldPrompt.release;
-    try {
-      queryInstance = query({
-        prompt: heldPrompt.stream,
-        options: sdkOptions
-      });
-    } catch (hookError) {
-      // Older/newer SDK versions may not accept hook shapes yet.
-      // Keep notification behavior operational via runtime events even if hook registration fails.
-      console.warn('Failed to initialize Claude query with hooks, retrying without hooks:', hookError?.message || hookError);
-      delete sdkOptions.hooks;
-      // Discard the abandoned stream and build a fresh one for the retry.
-      heldPrompt.release();
-      heldPrompt = createHeldPromptStream(promptMessages);
-      releasePromptStream = heldPrompt.release;
-      queryInstance = query({
-        prompt: heldPrompt.stream,
-        options: sdkOptions
-      });
-    }
-
-    // Track the query instance for abort capability
-    if (sessionKey()) {
-      addSession(sessionKey(), queryInstance, ws, releasePromptStream);
-    }
-
-    // Process streaming messages
-    console.log('Starting async generator loop for session:', capturedSessionId || 'NEW');
-    for await (const message of queryInstance) {
-      // Capture session ID from first message
-      if (message.session_id && !capturedSessionId) {
-
-        capturedSessionId = message.session_id;
-        addSession(sessionKey(), queryInstance, ws, releasePromptStream);
-
-        // Set session ID on writer
-        if (ws.setSessionId && typeof ws.setSessionId === 'function') {
-          ws.setSessionId(capturedSessionId);
-        }
-
-        // Send session-created event only once for sessions with nothing to resume
-        if (!providerSessionId && !sessionCreatedSent) {
-          sessionCreatedSent = true;
-          ws.send(createNormalizedMessage({ kind: 'session_created', newSessionId: capturedSessionId, sessionId: capturedSessionId, provider: 'claude' }));
-        }
-      } else {
-        // session_id already captured
-      }
-
-      // Transform and normalize message via adapter
-      const transformedMessage = transformMessage(message);
-      const sid = capturedSessionId || sessionId || null;
-
-      // Use adapter to normalize SDK events into NormalizedMessage[]
-      const normalized = context.normalizeMessage(transformedMessage, sid);
-      for (const msg of normalized) {
-        // Preserve parentToolUseId from SDK wrapper for subagent tool grouping
-        if (transformedMessage.parentToolUseId && !msg.parentToolUseId) {
-          msg.parentToolUseId = transformedMessage.parentToolUseId;
-        }
-        ws.send(msg);
-      }
-
-      // Extract and send token budget updates from assistant/result usage payloads
-      const tokenBudgetData = extractTokenBudget(message);
-      if (tokenBudgetData) {
-        ws.send(createNormalizedMessage({ kind: 'status', text: 'token_budget', tokenBudget: tokenBudgetData, sessionId: capturedSessionId || sessionId || null, provider: 'claude' }));
-      }
-
-      if (startsBackgroundWork(message)) {
-        backgroundWorkPending = true;
-      }
-
-      if (message.type === 'result') {
-        // The turn is done as far as the client is concerned.
-        const abortPending = sessionKey() ? abortedSessionIds.has(sessionKey()) : false;
-        if (!turnCompleteSent && !abortPending) {
-          turnCompleteSent = true;
-          ws.send(createCompleteMessage({ provider: 'claude', sessionId: capturedSessionId || sessionId || null, exitCode: 0 }));
-          notifyRunStopped({
-            userId: ws?.userId || null,
-            provider: 'claude',
-            sessionId: sessionId || capturedSessionId || null,
-            sessionName: sessionSummary,
-            stopReason: 'completed'
-          });
-        } else if (heldForBackgroundWork && !abortPending) {
-          // A result after the turn already reported complete means the work we
-          // held the process open for has finished and pushed a follow-up turn.
-          notifyBackgroundWorkCompleted({
-            userId: ws?.userId || null,
-            provider: 'claude',
-            sessionId: sessionId || capturedSessionId || null,
-            sessionName: sessionSummary
-          });
-        }
-        if (backgroundWorkPending) {
-          // Work started during this turn is still running. Hold the process
-          // open so it can finish and report back in a follow-up turn; the
-          // ceiling is only a backstop for work that never reports.
-          backgroundWorkPending = false;
-          heldForBackgroundWork = true;
-          scheduleRelease();
-        } else {
-          // Either nothing was backgrounded, or the background work just
-          // reported in — let the CLI exit now, as it always has.
-          heldForBackgroundWork = false;
-          releasePromptStream();
-        }
-      } else if (idleReleaseTimer) {
-        // Background activity after the turn — push the countdown back out.
-        scheduleRelease();
-      }
-    }
-
-    // Clean up session on completion — only while this run still owns the map
-    // entry. A superseding run may have replaced it, and deleting here would
-    // strand that run.
-    if (sessionKey() && getSession(sessionKey())?.instance === queryInstance) {
-      removeSession(sessionKey());
-    }
-
-    // A superseded run winds down silently: the map entry, the abort flag,
-    // and all client-facing events belong to the run that replaced it.
-    const superseded = supersededInstances.has(queryInstance);
-
-    // Send the terminal completion event — skipped for aborted runs, whose
-    // terminal `complete` (aborted: true) was already sent by abort-session, and
-    // for runs that already reported completion when their `result` arrived.
-    const wasAborted = !superseded && sessionKey() ? abortedSessionIds.delete(sessionKey()) : false;
-    if (!turnCompleteSent && !superseded) {
-      turnCompleteSent = true;
-      if (!wasAborted) {
-        ws.send(createCompleteMessage({ provider: 'claude', sessionId: capturedSessionId || sessionId || null, exitCode: 0 }));
-      }
-      notifyRunStopped({
-        userId: ws?.userId || null,
-        provider: 'claude',
-        sessionId: sessionId || capturedSessionId || null,
-        sessionName: sessionSummary,
-        stopReason: wasAborted ? 'aborted' : 'completed'
-      });
-    }
-    // Complete
-
-  } catch (error) {
-    console.error('SDK query error:', error);
-
-    // Clean up session on error — only while this run still owns the map entry
-    // (a superseding run may have replaced it).
-    if (sessionKey() && getSession(sessionKey())?.instance === queryInstance) {
-      removeSession(sessionKey());
-    }
-
-    if (supersededInstances.has(queryInstance)) {
-      // Interrupted because a newer run took over this session id; that run
-      // owns the abort flag and all further client-facing events.
-      return;
-    }
-
-    const wasAborted = sessionKey() ? abortedSessionIds.delete(sessionKey()) : false;
-    if (wasAborted) {
-      // The abort already produced the terminal complete; a generator throw
-      // caused by interrupt() is expected noise, not a user-facing error.
-      return;
-    }
-
-    // Check if Claude CLI is installed for a clearer error message
-    const installed = await context.isProviderInstalled();
-    const errorContent = !installed
-      ? 'Claude Code is not installed. Please install it first: https://docs.anthropic.com/en/docs/claude-code'
-      : error.message;
-
-    // Send error to WebSocket, then the terminal complete. A run that already
-    // reported completion and then failed during its post-turn hold still
-    // surfaces the error, but must not emit a second terminal complete.
-    ws.send(createNormalizedMessage({ kind: 'error', content: errorContent, sessionId: capturedSessionId || sessionId || null, provider: 'claude' }));
-    if (!turnCompleteSent) {
-      ws.send(createCompleteMessage({ provider: 'claude', sessionId: capturedSessionId || sessionId || null, exitCode: 1 }));
-    }
-    notifyRunFailed({
-      userId: ws?.userId || null,
-      provider: 'claude',
-      sessionId: sessionId || capturedSessionId || null,
-      sessionName: sessionSummary,
-      error
-    });
-  } finally {
-    // Always close stdin — otherwise an aborted or failed run leaves the CLI
-    // process (and its MCP servers) alive until the server exits.
-    if (idleReleaseTimer) {
-      clearTimeout(idleReleaseTimer);
-      idleReleaseTimer = null;
-    }
-    releasePromptStream();
-  }
-}
-
-/**
- * Aborts an active SDK session
- * @param {string} sessionId - Session identifier
- * @returns {boolean} True if session was aborted, false if not found
- */
-async function abortClaudeSDKSession(sessionId) {
-  const session = getSession(sessionId);
-
-  if (!session) {
-    console.log(`Session ${sessionId} not found`);
-    return false;
-  }
-
-  try {
-    console.log(`Aborting SDK session: ${sessionId}`);
-
-    // Mark before interrupting so the run loop knows not to emit its own
-    // terminal complete (the abort handler sends the aborted one).
-    abortedSessionIds.add(sessionId);
-
-    // Call interrupt() on the query instance
-    await session.instance.interrupt();
-
-    // Release the held stdin stream; without this the CLI stays up for the rest
-    // of the post-turn hold even though the user cancelled.
-    session.releaseInput?.();
-
-    // Update session status
-    session.status = 'aborted';
-
-    // Clean up session
-    removeSession(sessionId);
-
-    return true;
-  } catch (error) {
-    console.error(`Error aborting session ${sessionId}:`, error);
-    // The run keeps going; let it emit its own terminal complete.
-    abortedSessionIds.delete(sessionId);
-    return false;
-  }
-}
-
-/**
- * Checks if an SDK session is currently active
- * @param {string} sessionId - Session identifier
- * @returns {boolean} True if session is active
- */
-function isClaudeSDKSessionActive(sessionId) {
-  const session = getSession(sessionId);
-  return session && session.status === 'active';
-}
-
-/**
- * Gets all active SDK session IDs
- * @returns {Array<string>} Array of active session IDs
- */
-function getActiveClaudeSDKSessions() {
-  return getAllSessions();
-}
-
-/**
- * Get pending tool approvals for a specific session.
- * @param {string} sessionId - The session ID
- * @returns {Array} Array of pending permission request objects
- */
-function getPendingApprovalsForSession(sessionId) {
-  const pending = [];
-  for (const [requestId, resolver] of pendingToolApprovals.entries()) {
-    if (resolver._sessionId === sessionId) {
-      pending.push({
-        requestId,
-        toolName: resolver._toolName || 'UnknownTool',
-        input: resolver._input,
-        context: resolver._context,
-        sessionId,
-        receivedAt: resolver._receivedAt || new Date(),
-      });
-    }
-  }
-  return pending;
-}
-
-/**
- * Reconnect a session's WebSocketWriter to a new raw WebSocket.
- * Called when client reconnects (e.g. page refresh) while SDK is still running.
- * @param {string} sessionId - The session ID
- * @param {Object} newRawWs - The new raw WebSocket connection
- * @returns {boolean} True if writer was successfully reconnected
- */
-function reconnectSessionWriter(sessionId, newRawWs) {
-  const session = getSession(sessionId);
-  if (!session?.writer?.updateWebSocket) return false;
-  session.writer.updateWebSocket(newRawWs);
-  console.log(`[RECONNECT] Writer swapped for session ${sessionId}`);
-  return true;
-}
-
-export const claudeRuntime = {
-  run: queryClaudeSDK,
-  abort: abortClaudeSDKSession,
-  permissions: {
-    resolve: resolveToolApproval,
-    listPending: getPendingApprovalsForSession,
-  },
-};
-
-// Export public API
-export {
-  queryClaudeSDK,
-  abortClaudeSDKSession,
-  isClaudeSDKSessionActive,
-  getActiveClaudeSDKSessions,
-  resolveToolApproval,
-  getPendingApprovalsForSession,
-  reconnectSessionWriter
-};
+/**
+ * Claude SDK Integration
+ *
+ * This module provides SDK-based integration with Claude using the @anthropic-ai/claude-agent-sdk.
+ * It mirrors the interface of claude-cli.js but uses the SDK internally for better performance
+ * and maintainability.
+ *
+ * Key features:
+ * - Direct SDK integration without child processes
+ * - Session management with abort capability
+ * - Options mapping between CLI and SDK formats
+ * - WebSocket message streaming
+ */
+
+import crypto from 'crypto';
+import { promises as fs } from 'fs';
+import os from 'os';
+import path from 'path';
+
+import { query } from '@anthropic-ai/claude-agent-sdk';
+
+import {
+  appendFilesInputTag,
+  buildClaudeUserContent,
+  normalizeImageDescriptors
+} from '@/shared/image-attachments.js';
+import { CLAUDE_PREDEFINED_MODELS } from '@/modules/providers/list/claude/claude-models.provider.js';
+import { resolveClaudeCodeExecutablePath } from '@/shared/claude-cli-path.js';
+import {
+  createNotificationEvent,
+  notifyBackgroundWorkCompleted,
+  notifyRunFailed,
+  notifyRunStopped,
+  notifyUserIfEnabled
+} from '@/modules/notifications/index.js';
+import { createCompleteMessage, createNormalizedMessage } from '@/shared/utils.js';
+
+const activeSessions = new Map();
+const pendingToolApprovals = new Map();
+// Sessions cancelled via abort-session. The abort handler already sent the
+// terminal `complete` (aborted: true) to the client, so the run loop must not
+// emit a second one when its generator winds down.
+const abortedSessionIds = new Set();
+// Query instances interrupted because a newer run took over their session id
+// (see addSession). Their run loops must stay silent on wind-down: the map
+// entry, the abort flag, and all client-facing events belong to the new run.
+const supersededInstances = new WeakSet();
+
+const TOOL_APPROVAL_TIMEOUT_MS = parseInt(process.env.CLAUDE_TOOL_APPROVAL_TIMEOUT_MS, 10) || 55000;
+
+// How long background work is allowed to keep running after a turn ends. This drives
+// two halves of the same behaviour:
+//
+//  1. Passed to the spawned CLI as CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS, which is how
+//     long it waits for still-running background *agents* before killing them.
+//  2. A backstop on how long we hold the SDK's stdin open after a turn's `result`.
+//     The SDK closes stdin as soon as a turn ends, and the CLI reads that EOF as
+//     "print wind-down" — killing background *shells* after a short grace period,
+//     which the ceiling above does not cover. Holding stdin open also lets the CLI
+//     push follow-up turns (background-task completions, Monitor notifications,
+//     scheduled wake-ups).
+//
+// The hold normally ends long before this: a turn with nothing outstanding closes
+// stdin immediately, background work releases it as soon as it reports back, and a
+// new turn supersedes the previous hold. This ceiling only catches background work
+// that never reports at all, so an abandoned session cannot leak a CLI process
+// forever. The timer resets on every message, so it measures silence, not total time.
+const BG_WAIT_CEILING_MS = 30 * 60 * 1000;
+
+const TOOLS_REQUIRING_INTERACTION = new Set(['AskUserQuestion', 'ExitPlanMode']);
+
+function resolveClaudeEffort(model, effort, modelsDefinition = CLAUDE_PREDEFINED_MODELS) {
+  const selectedModel = modelsDefinition?.OPTIONS?.find((option) => option.value === model) || null;
+  const allowedEfforts = selectedModel?.effort?.values
+    ?.map((value) => value.value) || [];
+  return typeof effort === 'string' && effort !== 'default' && allowedEfforts.includes(effort)
+    ? effort
+    : undefined;
+}
+
+function createRequestId() {
+  if (typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  return crypto.randomBytes(16).toString('hex');
+}
+
+function waitForToolApproval(requestId, options = {}) {
+  const { timeoutMs = TOOL_APPROVAL_TIMEOUT_MS, signal, onCancel, metadata } = options;
+
+  return new Promise(resolve => {
+    let settled = false;
+
+    const finalize = (decision) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(decision);
+    };
+
+    let timeout;
+
+    const cleanup = () => {
+      pendingToolApprovals.delete(requestId);
+      if (timeout) clearTimeout(timeout);
+      if (signal && abortHandler) {
+        signal.removeEventListener('abort', abortHandler);
+      }
+    };
+
+    // timeoutMs 0 = wait indefinitely (interactive tools)
+    if (timeoutMs > 0) {
+      timeout = setTimeout(() => {
+        onCancel?.('timeout');
+        finalize(null);
+      }, timeoutMs);
+    }
+
+    const abortHandler = () => {
+      onCancel?.('cancelled');
+      finalize({ cancelled: true });
+    };
+
+    if (signal) {
+      if (signal.aborted) {
+        onCancel?.('cancelled');
+        finalize({ cancelled: true });
+        return;
+      }
+      signal.addEventListener('abort', abortHandler, { once: true });
+    }
+
+    const resolver = (decision) => {
+      finalize(decision);
+    };
+    // Attach metadata for getPendingApprovalsForSession lookup
+    if (metadata) {
+      Object.assign(resolver, metadata);
+    }
+    pendingToolApprovals.set(requestId, resolver);
+  });
+}
+
+function resolveToolApproval(requestId, decision) {
+  const resolver = pendingToolApprovals.get(requestId);
+  if (resolver) {
+    resolver(decision);
+  }
+}
+
+// Match stored permission entries against a tool + input combo.
+// This only supports exact tool names and the Bash(command:*) shorthand
+// used by the UI; it intentionally does not implement full glob semantics,
+// introduced to stay consistent with the UI's "Allow rule" format.
+function matchesToolPermission(entry, toolName, input) {
+  if (!entry || !toolName) {
+    return false;
+  }
+
+  if (entry === toolName) {
+    return true;
+  }
+
+  const bashMatch = entry.match(/^Bash\((.+):\*\)$/);
+  if (toolName === 'Bash' && bashMatch) {
+    const allowedPrefix = bashMatch[1];
+    let command = '';
+
+    if (typeof input === 'string') {
+      command = input.trim();
+    } else if (input && typeof input === 'object' && typeof input.command === 'string') {
+      command = input.command.trim();
+    }
+
+    if (!command) {
+      return false;
+    }
+
+    return command.startsWith(allowedPrefix);
+  }
+
+  return false;
+}
+
+function mapCliOptionsToSDK(options = {}) {
+  const { providerSessionId, cwd, toolsSettings, permissionMode, effort } = options;
+
+  const sdkOptions = {};
+
+  // Forward all host env vars (e.g. ANTHROPIC_BASE_URL) to the subprocess.
+  // Since SDK 0.2.113, options.env replaces process.env instead of overlaying it.
+  sdkOptions.env = { ...process.env, CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS: String(BG_WAIT_CEILING_MS) };
+
+  // Resolve the executable eagerly on Windows because the SDK uses raw child_process.spawn,
+  // which does not reliably follow npm's shell wrappers like cross-spawn does.
+  sdkOptions.pathToClaudeCodeExecutable = resolveClaudeCodeExecutablePath(process.env.CLAUDE_CLI_PATH);
+
+  if (cwd) {
+    sdkOptions.cwd = cwd;
+  }
+
+  if (permissionMode && permissionMode !== 'default') {
+    sdkOptions.permissionMode = permissionMode;
+  }
+
+  const settings = toolsSettings || {
+    allowedTools: [],
+    disallowedTools: [],
+    skipPermissions: false
+  };
+
+  if (settings.skipPermissions && permissionMode !== 'plan') {
+    sdkOptions.permissionMode = 'bypassPermissions';
+  }
+
+  let allowedTools = [...(settings.allowedTools || [])];
+
+  if (permissionMode === 'plan') {
+    const planModeTools = ['Read', 'Task', 'exit_plan_mode', 'TodoRead', 'TodoWrite', 'WebFetch', 'WebSearch'];
+    for (const tool of planModeTools) {
+      if (!allowedTools.includes(tool)) {
+        allowedTools.push(tool);
+      }
+    }
+  }
+
+  sdkOptions.allowedTools = allowedTools;
+
+  // Use the tools preset to make all default built-in tools available (including AskUserQuestion).
+  // This was introduced in SDK 0.1.57. Omitting this preserves existing behavior (all tools available),
+  // but being explicit ensures forward compatibility and clarity.
+  sdkOptions.tools = { type: 'preset', preset: 'claude_code' };
+
+  sdkOptions.disallowedTools = settings.disallowedTools || [];
+
+  sdkOptions.model = options.model || CLAUDE_PREDEFINED_MODELS.DEFAULT;
+
+  const resolvedEffort = resolveClaudeEffort(
+    sdkOptions.model,
+    effort,
+    options.effortModels || CLAUDE_PREDEFINED_MODELS,
+  );
+  if (resolvedEffort) {
+    sdkOptions.effort = resolvedEffort;
+  }
+
+  sdkOptions.systemPrompt = {
+    type: 'preset',
+    preset: 'claude_code'
+  };
+
+  sdkOptions.settingSources = ['project', 'user', 'local'];
+
+  // The SDK resumes with the provider-native session id, never the app id.
+  if (providerSessionId) {
+    sdkOptions.resume = providerSessionId;
+  }
+
+  return sdkOptions;
+}
+
+/**
+ * Adds a session to the active sessions map
+ * @param {string} sessionId - Session identifier
+ * @param {Object} queryInstance - SDK query instance
+ * @param {Object} writer - WebSocket writer for reconnect support
+ * @param {Function} releaseInput - Closes the held stdin stream so the CLI can exit
+ */
+function addSession(sessionId, queryInstance, writer = null, releaseInput = null) {
+  const existing = activeSessions.get(sessionId);
+  // A different live instance under the same key means an earlier run was
+  // superseded without being stopped (e.g. an abort that raced run setup and
+  // found nothing to interrupt). Overwriting it here would strand its
+  // generator forever — this map entry is the only handle for interrupting
+  // it. Stop it directly rather than via abortClaudeSDKSession, whose
+  // session-keyed abortedSessionIds flag would be consumed by the new run
+  // and suppress its terminal `complete`.
+  const superseding = Boolean(
+    existing && existing.status === 'active' && existing.instance && existing.instance !== queryInstance
+  );
+  if (superseding) {
+    supersededInstances.add(existing.instance);
+    Promise.resolve()
+      .then(() => existing.instance.interrupt())
+      .catch((error) => {
+        console.error(`Error interrupting superseded run for session ${sessionId}:`, error?.message || error);
+      });
+    existing.releaseInput?.();
+  }
+  const carried = superseding ? null : existing;
+  activeSessions.set(sessionId, {
+    instance: queryInstance,
+    startTime: carried?.startTime || Date.now(),
+    status: 'active',
+    writer,
+    // Re-registered mid-run once the provider session id lands; keep the closer.
+    releaseInput: releaseInput || carried?.releaseInput || null
+  });
+}
+
+/**
+ * Removes a session from the active sessions map
+ * @param {string} sessionId - Session identifier
+ */
+function removeSession(sessionId) {
+  activeSessions.delete(sessionId);
+}
+
+/**
+ * Gets a session from the active sessions map
+ * @param {string} sessionId - Session identifier
+ * @returns {Object|undefined} Session data or undefined
+ */
+function getSession(sessionId) {
+  return activeSessions.get(sessionId);
+}
+
+/**
+ * Gets all active session IDs
+ * @returns {Array<string>} Array of active session IDs
+ */
+function getAllSessions() {
+  return Array.from(activeSessions.keys());
+}
+
+/**
+ * Transforms SDK messages to WebSocket format expected by frontend
+ * @param {Object} sdkMessage - SDK message object
+ * @returns {Object} Transformed message ready for WebSocket
+ */
+function transformMessage(sdkMessage) {
+  // Extract parent_tool_use_id for subagent tool grouping
+  if (sdkMessage.parent_tool_use_id) {
+    return {
+      ...sdkMessage,
+      parentToolUseId: sdkMessage.parent_tool_use_id
+    };
+  }
+  return sdkMessage;
+}
+
+function readNumber(value) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+/**
+ * Extracts token usage from SDK messages.
+ * Prefers per-step `message.usage` (Claude message payload), then falls back
+ * to result-level usage/modelUsage for compatibility across SDK versions.
+ * @param {Object} sdkMessage - SDK stream message
+ * @returns {Object|null} Token budget object or null
+ */
+function extractTokenBudget(sdkMessage) {
+  if (!sdkMessage || typeof sdkMessage !== 'object') {
+    return null;
+  }
+
+  const messageUsage = sdkMessage.message?.usage || sdkMessage.usage;
+  if (messageUsage && typeof messageUsage === 'object') {
+    const directInputTokens = readNumber(messageUsage.input_tokens ?? messageUsage.inputTokens);
+    const cacheCreationTokens = readNumber(messageUsage.cache_creation_input_tokens ?? messageUsage.cacheCreationInputTokens ?? messageUsage.cacheCreationTokens);
+    const cacheReadTokens = readNumber(messageUsage.cache_read_input_tokens ?? messageUsage.cacheReadInputTokens ?? messageUsage.cacheReadTokens);
+    const cacheTokens = cacheCreationTokens + cacheReadTokens;
+    const inputTokens = directInputTokens + cacheTokens;
+    const outputTokens = readNumber(messageUsage.output_tokens ?? messageUsage.outputTokens);
+    const totalUsed = inputTokens + outputTokens;
+    const contextWindow = parseInt(process.env.CONTEXT_WINDOW, 10) || 160000;
+
+    return {
+      used: totalUsed,
+      total: contextWindow,
+      inputTokens,
+      outputTokens,
+      cacheReadTokens,
+      cacheCreationTokens,
+      cacheTokens,
+      breakdown: {
+        input: inputTokens,
+        output: outputTokens,
+      },
+    };
+  }
+
+  if (!sdkMessage.modelUsage || typeof sdkMessage.modelUsage !== 'object') {
+    return null;
+  }
+
+  // Fallback for older SDK messages with only modelUsage
+  const modelKey = Object.keys(sdkMessage.modelUsage)[0];
+  const modelData = sdkMessage.modelUsage[modelKey];
+
+  if (!modelData || typeof modelData !== 'object') {
+    return null;
+  }
+
+  const inputTokens = readNumber(modelData.cumulativeInputTokens ?? modelData.inputTokens);
+  const outputTokens = readNumber(modelData.cumulativeOutputTokens ?? modelData.outputTokens);
+  const totalUsed = inputTokens + outputTokens;
+  const contextWindow = parseInt(process.env.CONTEXT_WINDOW, 10) || 160000;
+
+  return {
+    used: totalUsed,
+    total: contextWindow,
+    inputTokens,
+    outputTokens,
+    breakdown: {
+      input: inputTokens,
+      output: outputTokens,
+    },
+  };
+}
+
+// Tool calls that leave work running past the end of a turn. Bash only counts
+// when it is explicitly backgrounded; the rest defer or watch work by nature.
+const DEFERRED_WORK_TOOLS = new Set(['Monitor', 'ScheduleWakeup', 'CronCreate', 'TaskCreate']);
+
+/**
+ * Detects tool calls that keep working after the turn's `result` arrives.
+ *
+ * Only turns that start background work need their CLI process held open; every
+ * other turn can let it exit immediately, as it did before the hold existed.
+ *
+ * @param {Object} sdkMessage - SDK stream message
+ * @returns {boolean} True when the message launches work that outlives the turn
+ */
+function startsBackgroundWork(sdkMessage) {
+  const content = sdkMessage?.message?.content;
+  if (!Array.isArray(content)) {
+    return false;
+  }
+
+  return content.some((block) => {
+    if (block?.type !== 'tool_use') {
+      return false;
+    }
+    if (block.name === 'Bash') {
+      return block.input?.run_in_background === true;
+    }
+    return DEFERRED_WORK_TOOLS.has(block.name);
+  });
+}
+
+/**
+ * Builds the SDK user messages for one turn.
+ *
+ * Always returns SDKUserMessage records rather than a bare string: a string
+ * prompt makes the SDK flag the query as single-turn and close stdin the moment
+ * the turn's `result` arrives, which kills the CLI's background tasks. Plain
+ * text turns carry string content; turns with image attachments carry the
+ * prompt text plus one base64 `image` block per attachment (read from the
+ * global `~/.cloudcli/assets` folder).
+ *
+ * @param {string} command - User prompt
+ * @param {Array} images - Image descriptors ({ path, name?, mimeType? })
+ * @param {Array} files - Non-image attachment descriptors
+ * @param {string} cwd - Project working directory attachment paths resolve against
+ * @returns {Promise<Array<Object>>} SDKUserMessage records for the turn
+ */
+async function buildPromptMessages(command, images, files, cwd) {
+  const promptWithFiles = appendFilesInputTag(command, files);
+  const content = normalizeImageDescriptors(images).length === 0
+    ? promptWithFiles
+    : await buildClaudeUserContent(promptWithFiles, images, cwd);
+
+  return [{
+    type: 'user',
+    message: {
+      role: 'user',
+      content
+    },
+    parent_tool_use_id: null,
+    timestamp: new Date().toISOString()
+  }];
+}
+
+/**
+ * Wraps prompt messages in an async iterable that yields them and then parks.
+ *
+ * The SDK closes the CLI's stdin as soon as its input iterable is exhausted (and
+ * immediately on `result` for string prompts). The CLI reads that EOF as the end
+ * of the run and kills anything still going in the background, so the iterable
+ * has to stay pending until we actually want the process gone.
+ *
+ * @param {Array<Object>} messages - SDKUserMessage records to send
+ * @returns {{ stream: AsyncIterable, release: () => void }} Stream plus its closer
+ */
+function createHeldPromptStream(messages) {
+  let release;
+  const held = new Promise((resolve) => { release = resolve; });
+
+  const stream = (async function* () {
+    for (const message of messages) {
+      yield message;
+    }
+    // Keeps stdin open — the CLI stays alive until release() is called.
+    await held;
+  })();
+
+  return { stream, release };
+}
+
+/**
+ * Loads MCP server configurations from ~/.claude.json
+ * @param {string} cwd - Current working directory for project-specific configs
+ * @returns {Object|null} MCP servers object or null if none found
+ */
+async function loadMcpConfig(cwd) {
+  try {
+    const claudeConfigPath = path.join(os.homedir(), '.claude.json');
+
+    // Check if config file exists
+    try {
+      await fs.access(claudeConfigPath);
+    } catch (error) {
+      // File doesn't exist, return null
+      // No config file
+      return null;
+    }
+
+    // Read and parse config file
+    let claudeConfig;
+    try {
+      const configContent = await fs.readFile(claudeConfigPath, 'utf8');
+      claudeConfig = JSON.parse(configContent);
+    } catch (error) {
+      console.error('Failed to parse ~/.claude.json:', error.message);
+      return null;
+    }
+
+    // Extract MCP servers (merge global and project-specific)
+    let mcpServers = {};
+
+    // Add global MCP servers
+    if (claudeConfig.mcpServers && typeof claudeConfig.mcpServers === 'object') {
+      mcpServers = { ...claudeConfig.mcpServers };
+      // Global MCP servers loaded
+    }
+
+    // Add/override with project-specific MCP servers
+    if (claudeConfig.claudeProjects && cwd) {
+      const projectConfig = claudeConfig.claudeProjects[cwd];
+      if (projectConfig && projectConfig.mcpServers && typeof projectConfig.mcpServers === 'object') {
+        mcpServers = { ...mcpServers, ...projectConfig.mcpServers };
+        // Project MCP servers merged
+      }
+    }
+
+    // Return null if no servers found
+    if (Object.keys(mcpServers).length === 0) {
+      return null;
+    }
+    return mcpServers;
+  } catch (error) {
+    console.error('Error loading MCP config:', error.message);
+    return null;
+  }
+}
+
+/**
+ * Executes a Claude query using the SDK
+ * @param {string} command - User prompt/command
+ * @param {Object} options - Query options
+ * @param {Object} ws - WebSocket connection
+ * @param {Object} context - Provider-scoped model, session, and auth lookups
+ * @returns {Promise<void>}
+ */
+async function queryClaudeSDK(command, options = {}, ws, context) {
+  const { sessionId, sessionSummary } = options;
+  // Callers pass the stable app session id; the SDK only understands the
+  // provider-native id recorded on the session row.
+  const providerSessionId = context.resolveProviderSessionId(sessionId);
+  // Provider-native id as the SDK reports it (starts as the resume id, or is
+  // captured from the stream for brand-new sessions).
+  let capturedSessionId = providerSessionId;
+  let sessionCreatedSent = false;
+  // Process-map key: the app session id when the caller supplied one, else
+  // the provider-native id once captured (legacy/direct API callers).
+  const sessionKey = () => sessionId || capturedSessionId || null;
+
+  const emitNotification = (event) => {
+    notifyUserIfEnabled({
+      userId: ws?.userId || null,
+      writer: ws,
+      event
+    });
+  };
+
+  // Closes the held stdin stream so the CLI can wind down. Replaced once the
+  // stream exists; the finally block calls it no matter how the run ends.
+  let releasePromptStream = () => {};
+  let idleReleaseTimer = null;
+  // The client is told the turn is over as soon as `result` lands, even though
+  // the process lingers, so the UI never waits out the idle hold.
+  let turnCompleteSent = false;
+  // Set when a turn starts background work, cleared when the next `result`
+  // arrives — only turns with work still outstanding hold their process open.
+  let backgroundWorkPending = false;
+  // True while the process is being held open for background work, so a later
+  // `result` can be recognised as that work reporting back.
+  let heldForBackgroundWork = false;
+
+  // A new turn supersedes any earlier one still holding this session's process
+  // open, so held runs cannot stack up across a conversation.
+  if (sessionKey()) {
+    getSession(sessionKey())?.releaseInput?.();
+  }
+
+  // Arms (or re-arms) the idle countdown that eventually closes stdin.
+  const scheduleRelease = () => {
+    if (idleReleaseTimer) {
+      clearTimeout(idleReleaseTimer);
+      idleReleaseTimer = null;
+    }
+    idleReleaseTimer = setTimeout(() => {
+      idleReleaseTimer = null;
+      releasePromptStream();
+    }, BG_WAIT_CEILING_MS);
+    // Never let the hold keep the server process alive on its own.
+    idleReleaseTimer.unref?.();
+  };
+
+  // Hoisted above the try so the catch's cleanup can tell whether this run
+  // still owns the activeSessions entry (or was superseded by a newer run).
+  let queryInstance = null;
+
+  try {
+    const resolvedModel = await context.resolveResumeModel(sessionId, options.model);
+    let effortModels = CLAUDE_PREDEFINED_MODELS;
+    try {
+      effortModels = await context.getProviderModels();
+    } catch (error) {
+      console.warn('[Claude SDK] Unable to load provider models for effort validation:', error);
+    }
+
+    const sdkOptions = mapCliOptionsToSDK({
+      ...options,
+      providerSessionId,
+      model: resolvedModel || options.model,
+      effortModels,
+    });
+
+    const mcpServers = await loadMcpConfig(options.cwd);
+    if (mcpServers) {
+      sdkOptions.mcpServers = mcpServers;
+    }
+
+    // Every turn uses streaming input so stdin stays open past the turn's
+    // `result`. The message list is reusable, but each query attempt needs its
+    // own stream because an async generator cannot be replayed once consumed.
+    const promptMessages = await buildPromptMessages(command, options.images, options.files, options.cwd);
+
+    sdkOptions.hooks = {
+      Notification: [{
+        matcher: '',
+        hooks: [async (input) => {
+          const message = typeof input?.message === 'string' ? input.message : 'Claude requires your attention.';
+          // Notifications are app-facing, so they carry the app session id.
+          emitNotification(createNotificationEvent({
+            provider: 'claude',
+            sessionId: sessionId || capturedSessionId || null,
+            kind: 'action_required',
+            code: 'agent.notification',
+            meta: { message, sessionName: sessionSummary },
+            severity: 'warning',
+            requiresUserAction: true,
+            dedupeKey: `claude:hook:notification:${sessionId || capturedSessionId || 'none'}:${message}`
+          }));
+          return {};
+        }]
+      }]
+    };
+
+    // Caveat: in 'auto' and 'bypassPermissions' modes the SDK resolves approval
+    // at the permission-mode step and skips this callback, so interactive tools
+    // (AskUserQuestion, ExitPlanMode) won't reach the UI — the classifier/bypass
+    // auto-approves them and the model acts on a generated answer. Move these
+    // tools to a PreToolUse hook (runs before the mode check) if we need them
+    // to work in those modes.
+    sdkOptions.canUseTool = async (toolName, input, context) => {
+      const requiresInteraction = TOOLS_REQUIRING_INTERACTION.has(toolName);
+
+      if (!requiresInteraction) {
+        if (sdkOptions.permissionMode === 'bypassPermissions') {
+          return { behavior: 'allow', updatedInput: input };
+        }
+
+        const isDisallowed = (sdkOptions.disallowedTools || []).some(entry =>
+          matchesToolPermission(entry, toolName, input)
+        );
+        if (isDisallowed) {
+          return { behavior: 'deny', message: 'Tool disallowed by settings' };
+        }
+
+        const isAllowed = (sdkOptions.allowedTools || []).some(entry =>
+          matchesToolPermission(entry, toolName, input)
+        );
+        if (isAllowed) {
+          return { behavior: 'allow', updatedInput: input };
+        }
+      }
+
+      const requestId = createRequestId();
+      ws.send(createNormalizedMessage({ kind: 'permission_request', requestId, toolName, input, sessionId: capturedSessionId || sessionId || null, provider: 'claude' }));
+      emitNotification(createNotificationEvent({
+        provider: 'claude',
+        sessionId: sessionId || capturedSessionId || null,
+        kind: 'action_required',
+        code: 'permission.required',
+        meta: { toolName, sessionName: sessionSummary },
+        severity: 'warning',
+        requiresUserAction: true,
+        dedupeKey: `claude:permission:${sessionId || capturedSessionId || 'none'}:${requestId}`
+      }));
+
+      const decision = await waitForToolApproval(requestId, {
+        timeoutMs: requiresInteraction ? 0 : undefined,
+        signal: context?.signal,
+        metadata: {
+          // Keyed by the app session id so `chat.subscribe` can look pending
+          // approvals up directly; provider id only for legacy callers.
+          _sessionId: sessionId || capturedSessionId || null,
+          _toolName: toolName,
+          _input: input,
+          _receivedAt: new Date(),
+        },
+        onCancel: (reason) => {
+          ws.send(createNormalizedMessage({ kind: 'permission_cancelled', requestId, reason, sessionId: capturedSessionId || sessionId || null, provider: 'claude' }));
+        }
+      });
+      if (!decision) {
+        return { behavior: 'deny', message: 'Permission request timed out' };
+      }
+
+      if (decision.cancelled) {
+        return { behavior: 'deny', message: 'Permission request cancelled' };
+      }
+
+      if (decision.allow) {
+        if (decision.rememberEntry && typeof decision.rememberEntry === 'string') {
+          if (!sdkOptions.allowedTools.includes(decision.rememberEntry)) {
+            sdkOptions.allowedTools.push(decision.rememberEntry);
+          }
+          if (Array.isArray(sdkOptions.disallowedTools)) {
+            sdkOptions.disallowedTools = sdkOptions.disallowedTools.filter(entry => entry !== decision.rememberEntry);
+          }
+        }
+        return { behavior: 'allow', updatedInput: decision.updatedInput ?? input };
+      }
+
+      return { behavior: 'deny', message: decision.message ?? 'User denied tool use' };
+    };
+
+    let heldPrompt = createHeldPromptStream(promptMessages);
+    releasePromptStream = heldPrompt.release;
+    try {
+      queryInstance = query({
+        prompt: heldPrompt.stream,
+        options: sdkOptions
+      });
+    } catch (hookError) {
+      // Older/newer SDK versions may not accept hook shapes yet.
+      // Keep notification behavior operational via runtime events even if hook registration fails.
+      console.warn('Failed to initialize Claude query with hooks, retrying without hooks:', hookError?.message || hookError);
+      delete sdkOptions.hooks;
+      // Discard the abandoned stream and build a fresh one for the retry.
+      heldPrompt.release();
+      heldPrompt = createHeldPromptStream(promptMessages);
+      releasePromptStream = heldPrompt.release;
+      queryInstance = query({
+        prompt: heldPrompt.stream,
+        options: sdkOptions
+      });
+    }
+
+    // Track the query instance for abort capability
+    if (sessionKey()) {
+      addSession(sessionKey(), queryInstance, ws, releasePromptStream);
+    }
+
+    // Process streaming messages
+    console.log('Starting async generator loop for session:', capturedSessionId || 'NEW');
+    for await (const message of queryInstance) {
+      // Capture session ID from first message
+      if (message.session_id && !capturedSessionId) {
+
+        capturedSessionId = message.session_id;
+        addSession(sessionKey(), queryInstance, ws, releasePromptStream);
+
+        // Set session ID on writer
+        if (ws.setSessionId && typeof ws.setSessionId === 'function') {
+          ws.setSessionId(capturedSessionId);
+        }
+
+        // Send session-created event only once for sessions with nothing to resume
+        if (!providerSessionId && !sessionCreatedSent) {
+          sessionCreatedSent = true;
+          ws.send(createNormalizedMessage({ kind: 'session_created', newSessionId: capturedSessionId, sessionId: capturedSessionId, provider: 'claude' }));
+        }
+      } else {
+        // session_id already captured
+      }
+
+      // Transform and normalize message via adapter
+      const transformedMessage = transformMessage(message);
+      const sid = capturedSessionId || sessionId || null;
+
+      // Use adapter to normalize SDK events into NormalizedMessage[]
+      const normalized = context.normalizeMessage(transformedMessage, sid);
+      for (const msg of normalized) {
+        // Preserve parentToolUseId from SDK wrapper for subagent tool grouping
+        if (transformedMessage.parentToolUseId && !msg.parentToolUseId) {
+          msg.parentToolUseId = transformedMessage.parentToolUseId;
+        }
+        ws.send(msg);
+      }
+
+      // Extract and send token budget updates from assistant/result usage payloads
+      const tokenBudgetData = extractTokenBudget(message);
+      if (tokenBudgetData) {
+        ws.send(createNormalizedMessage({ kind: 'status', text: 'token_budget', tokenBudget: tokenBudgetData, sessionId: capturedSessionId || sessionId || null, provider: 'claude' }));
+      }
+
+      if (startsBackgroundWork(message)) {
+        backgroundWorkPending = true;
+      }
+
+      if (message.type === 'result') {
+        // The turn is done as far as the client is concerned.
+        const abortPending = sessionKey() ? abortedSessionIds.has(sessionKey()) : false;
+        if (!turnCompleteSent && !abortPending) {
+          turnCompleteSent = true;
+          ws.send(createCompleteMessage({ provider: 'claude', sessionId: capturedSessionId || sessionId || null, exitCode: 0 }));
+          notifyRunStopped({
+            userId: ws?.userId || null,
+            provider: 'claude',
+            sessionId: sessionId || capturedSessionId || null,
+            sessionName: sessionSummary,
+            stopReason: 'completed'
+          });
+        } else if (heldForBackgroundWork && !abortPending) {
+          // A result after the turn already reported complete means the work we
+          // held the process open for has finished and pushed a follow-up turn.
+          notifyBackgroundWorkCompleted({
+            userId: ws?.userId || null,
+            provider: 'claude',
+            sessionId: sessionId || capturedSessionId || null,
+            sessionName: sessionSummary
+          });
+        }
+        if (backgroundWorkPending) {
+          // Work started during this turn is still running. Hold the process
+          // open so it can finish and report back in a follow-up turn; the
+          // ceiling is only a backstop for work that never reports.
+          backgroundWorkPending = false;
+          heldForBackgroundWork = true;
+          scheduleRelease();
+        } else {
+          // Either nothing was backgrounded, or the background work just
+          // reported in — let the CLI exit now, as it always has.
+          heldForBackgroundWork = false;
+          releasePromptStream();
+        }
+      } else if (idleReleaseTimer) {
+        // Background activity after the turn — push the countdown back out.
+        scheduleRelease();
+      }
+    }
+
+    // Clean up session on completion — only while this run still owns the map
+    // entry. A superseding run may have replaced it, and deleting here would
+    // strand that run.
+    if (sessionKey() && getSession(sessionKey())?.instance === queryInstance) {
+      removeSession(sessionKey());
+    }
+
+    // A superseded run winds down silently: the map entry, the abort flag,
+    // and all client-facing events belong to the run that replaced it.
+    const superseded = supersededInstances.has(queryInstance);
+
+    // Send the terminal completion event — skipped for aborted runs, whose
+    // terminal `complete` (aborted: true) was already sent by abort-session, and
+    // for runs that already reported completion when their `result` arrived.
+    const wasAborted = !superseded && sessionKey() ? abortedSessionIds.delete(sessionKey()) : false;
+    if (!turnCompleteSent && !superseded) {
+      turnCompleteSent = true;
+      if (!wasAborted) {
+        ws.send(createCompleteMessage({ provider: 'claude', sessionId: capturedSessionId || sessionId || null, exitCode: 0 }));
+      }
+      notifyRunStopped({
+        userId: ws?.userId || null,
+        provider: 'claude',
+        sessionId: sessionId || capturedSessionId || null,
+        sessionName: sessionSummary,
+        stopReason: wasAborted ? 'aborted' : 'completed'
+      });
+    }
+    // Complete
+
+  } catch (error) {
+    console.error('SDK query error:', error);
+
+    // Clean up session on error — only while this run still owns the map entry
+    // (a superseding run may have replaced it).
+    if (sessionKey() && getSession(sessionKey())?.instance === queryInstance) {
+      removeSession(sessionKey());
+    }
+
+    if (supersededInstances.has(queryInstance)) {
+      // Interrupted because a newer run took over this session id; that run
+      // owns the abort flag and all further client-facing events.
+      return;
+    }
+
+    const wasAborted = sessionKey() ? abortedSessionIds.delete(sessionKey()) : false;
+    if (wasAborted) {
+      // The abort already produced the terminal complete; a generator throw
+      // caused by interrupt() is expected noise, not a user-facing error.
+      return;
+    }
+
+    // Check if Claude CLI is installed for a clearer error message
+    const installed = await context.isProviderInstalled();
+    const errorContent = !installed
+      ? 'Claude Code is not installed. Please install it first: https://docs.anthropic.com/en/docs/claude-code'
+      : error.message;
+
+    // Send error to WebSocket, then the terminal complete. A run that already
+    // reported completion and then failed during its post-turn hold still
+    // surfaces the error, but must not emit a second terminal complete.
+    ws.send(createNormalizedMessage({ kind: 'error', content: errorContent, sessionId: capturedSessionId || sessionId || null, provider: 'claude' }));
+    if (!turnCompleteSent) {
+      ws.send(createCompleteMessage({ provider: 'claude', sessionId: capturedSessionId || sessionId || null, exitCode: 1 }));
+    }
+    notifyRunFailed({
+      userId: ws?.userId || null,
+      provider: 'claude',
+      sessionId: sessionId || capturedSessionId || null,
+      sessionName: sessionSummary,
+      error
+    });
+  } finally {
+    // Always close stdin — otherwise an aborted or failed run leaves the CLI
+    // process (and its MCP servers) alive until the server exits.
+    if (idleReleaseTimer) {
+      clearTimeout(idleReleaseTimer);
+      idleReleaseTimer = null;
+    }
+    releasePromptStream();
+  }
+}
+
+/**
+ * Aborts an active SDK session
+ * @param {string} sessionId - Session identifier
+ * @returns {boolean} True if session was aborted, false if not found
+ */
+async function abortClaudeSDKSession(sessionId) {
+  const session = getSession(sessionId);
+
+  if (!session) {
+    console.log(`Session ${sessionId} not found`);
+    return false;
+  }
+
+  try {
+    console.log(`Aborting SDK session: ${sessionId}`);
+
+    // Mark before interrupting so the run loop knows not to emit its own
+    // terminal complete (the abort handler sends the aborted one).
+    abortedSessionIds.add(sessionId);
+
+    // Call interrupt() on the query instance
+    await session.instance.interrupt();
+
+    // Release the held stdin stream; without this the CLI stays up for the rest
+    // of the post-turn hold even though the user cancelled.
+    session.releaseInput?.();
+
+    // Update session status
+    session.status = 'aborted';
+
+    // Clean up session
+    removeSession(sessionId);
+
+    return true;
+  } catch (error) {
+    console.error(`Error aborting session ${sessionId}:`, error);
+    // The run keeps going; let it emit its own terminal complete.
+    abortedSessionIds.delete(sessionId);
+    return false;
+  }
+}
+
+/**
+ * Checks if an SDK session is currently active
+ * @param {string} sessionId - Session identifier
+ * @returns {boolean} True if session is active
+ */
+function isClaudeSDKSessionActive(sessionId) {
+  const session = getSession(sessionId);
+  return session && session.status === 'active';
+}
+
+/**
+ * Gets all active SDK session IDs
+ * @returns {Array<string>} Array of active session IDs
+ */
+function getActiveClaudeSDKSessions() {
+  return getAllSessions();
+}
+
+/**
+ * Get pending tool approvals for a specific session.
+ * @param {string} sessionId - The session ID
+ * @returns {Array} Array of pending permission request objects
+ */
+function getPendingApprovalsForSession(sessionId) {
+  const pending = [];
+  for (const [requestId, resolver] of pendingToolApprovals.entries()) {
+    if (resolver._sessionId === sessionId) {
+      pending.push({
+        requestId,
+        toolName: resolver._toolName || 'UnknownTool',
+        input: resolver._input,
+        context: resolver._context,
+        sessionId,
+        receivedAt: resolver._receivedAt || new Date(),
+      });
+    }
+  }
+  return pending;
+}
+
+/**
+ * Reconnect a session's WebSocketWriter to a new raw WebSocket.
+ * Called when client reconnects (e.g. page refresh) while SDK is still running.
+ * @param {string} sessionId - The session ID
+ * @param {Object} newRawWs - The new raw WebSocket connection
+ * @returns {boolean} True if writer was successfully reconnected
+ */
+function reconnectSessionWriter(sessionId, newRawWs) {
+  const session = getSession(sessionId);
+  if (!session?.writer?.updateWebSocket) return false;
+  session.writer.updateWebSocket(newRawWs);
+  console.log(`[RECONNECT] Writer swapped for session ${sessionId}`);
+  return true;
+}
+
+export const claudeRuntime = {
+  run: queryClaudeSDK,
+  abort: abortClaudeSDKSession,
+  permissions: {
+    resolve: resolveToolApproval,
+    listPending: getPendingApprovalsForSession,
+  },
+};
+
+// Export public API
+export {
+  queryClaudeSDK,
+  abortClaudeSDKSession,
+  isClaudeSDKSessionActive,
+  getActiveClaudeSDKSessions,
+  resolveToolApproval,
+  getPendingApprovalsForSession,
+  reconnectSessionWriter
+};