heyhank 0.1.0

package/server/claude-adapter.ts

@@ -0,0 +1,889 @@
+/**
+ * Claude Code Backend Adapter
+ *
+ * Translates between the Claude Code NDJSON WebSocket protocol and
+ * HeyHank's BrowserIncomingMessage/BrowserOutgoingMessage types.
+ *
+ * This allows the bridge (and by extension the browser) to be completely
+ * unaware of which backend is running -- it sees the same message types
+ * regardless of whether Claude Code or Codex is the backend.
+ */
+
+import { randomUUID } from "node:crypto";
+import type { ServerWebSocket } from "bun";
+import type { IBackendAdapter } from "./backend-adapter.js";
+import type {
+  BrowserIncomingMessage,
+  BrowserOutgoingMessage,
+  CLIMessage,
+  CLISystemMessage,
+  CLISystemInitMessage,
+  CLIAssistantMessage,
+  CLIResultMessage,
+  CLIStreamEventMessage,
+  CLIToolProgressMessage,
+  CLIToolUseSummaryMessage,
+  CLIControlRequestMessage,
+  CLIControlResponseMessage,
+  CLIAuthStatusMessage,
+  CLIControlCancelRequestMessage,
+  CLIStreamlinedTextMessage,
+  CLIStreamlinedToolUseSummaryMessage,
+  CLIPromptSuggestionMessage,
+  CLICompactBoundaryMessage,
+  CLITaskNotificationMessage,
+  CLIFilesPersistedMessage,
+  CLIHookStartedMessage,
+  CLIHookProgressMessage,
+  CLIHookResponseMessage,
+  PermissionRequest,
+  McpServerDetail,
+  SessionState,
+} from "./session-types.js";
+import type { SocketData } from "./ws-bridge-types.js";
+import type { PendingControlRequest } from "./ws-bridge-types.js";
+import type { RecorderManager } from "./recorder.js";
+import { parseNDJSON, isDuplicateCLIMessage } from "./ws-bridge-cli-ingest.js";
+import type { CLIDedupState } from "./ws-bridge-cli-ingest.js";
+import { reportProtocolDrift } from "./protocol-monitor.js";
+
+// --- Constants ----------------------------------------------------------------
+
+/** Number of recent CLI message hashes to track for deduplication on WS reconnect. */
+const CLI_DEDUP_WINDOW = 2000;
+
+// --- Claude Code Adapter ------------------------------------------------------
+
+export class ClaudeAdapter implements IBackendAdapter {
+  private sessionId: string;
+
+  // WebSocket to the Claude Code CLI process
+  private cliSocket: ServerWebSocket<SocketData> | null = null;
+
+  // Callbacks registered by the bridge via on*() methods
+  private browserMessageCb: ((msg: BrowserIncomingMessage) => void) | null = null;
+  private sessionMetaCb: ((meta: { cliSessionId?: string; model?: string; cwd?: string }) => void) | null = null;
+  private disconnectCb: (() => void) | null = null;
+
+  // Pending NDJSON messages queued before CLI WebSocket connects
+  private pendingMessages: string[] = [];
+
+  // Async control request/response pairs (e.g. MCP status queries)
+  private pendingControlRequests = new Map<string, PendingControlRequest>();
+
+  // CLI message deduplication state (rolling hash window)
+  private dedupState: CLIDedupState = {
+    recentCLIMessageHashes: [],
+    recentCLIMessageHashSet: new Set(),
+  };
+
+  // Optional recorder for raw protocol messages
+  private recorder: RecorderManager | null;
+
+  // Callback to update session.lastCliActivityTs from the bridge
+  private onActivityUpdate: (() => void) | null;
+
+  private protocolDriftSeen = new Set<string>();
+  private parseErrorSeen = new Set<string>();
+
+  constructor(
+    sessionId: string,
+    opts?: {
+      recorder?: RecorderManager | null;
+      onActivityUpdate?: () => void;
+    },
+  ) {
+    this.sessionId = sessionId;
+    this.recorder = opts?.recorder ?? null;
+    this.onActivityUpdate = opts?.onActivityUpdate ?? null;
+  }
+
+  // -- WebSocket lifecycle ----------------------------------------------------
+
+  /**
+   * Called when the CLI WebSocket connects. Stores the socket reference and
+   * flushes any NDJSON messages that were queued before the connection.
+   */
+  attachWebSocket(ws: ServerWebSocket<SocketData>): void {
+    this.cliSocket = ws;
+
+    // Flush pending messages
+    if (this.pendingMessages.length > 0) {
+      console.log(
+        `[claude-adapter] Flushing ${this.pendingMessages.length} queued message(s) for session ${this.sessionId}`,
+      );
+      const queued = this.pendingMessages.splice(0);
+      for (const ndjson of queued) {
+        this.sendRaw(ndjson);
+      }
+    }
+  }
+
+  /**
+   * Called when the CLI WebSocket closes. Guards against stale socket references
+   * (a new WS may have opened before the old one closed).
+   */
+  detachWebSocket(ws: ServerWebSocket<SocketData>): void {
+    // Only detach if this is the current socket -- ignore stale close events
+    if (this.cliSocket !== ws) return;
+    this.cliSocket = null;
+    this.disconnectCb?.();
+  }
+
+  // -- IBackendAdapter: Event registration ------------------------------------
+
+  onBrowserMessage(cb: (msg: BrowserIncomingMessage) => void): void {
+    this.browserMessageCb = cb;
+  }
+
+  onSessionMeta(cb: (meta: { cliSessionId?: string; model?: string; cwd?: string }) => void): void {
+    this.sessionMetaCb = cb;
+  }
+
+  onDisconnect(cb: () => void): void {
+    this.disconnectCb = cb;
+  }
+
+  // -- IBackendAdapter: Transport state ---------------------------------------
+
+  isConnected(): boolean {
+    return this.cliSocket !== null;
+  }
+
+  async disconnect(): Promise<void> {
+    // Clear pending control requests to prevent memory leaks from
+    // unresolved promises (CLI won't respond after disconnect)
+    this.pendingControlRequests.clear();
+    if (this.cliSocket) {
+      try {
+        this.cliSocket.close();
+      } catch {
+        // Socket may already be closed
+      }
+      this.cliSocket = null;
+    }
+  }
+
+  /**
+   * Handle transport-level close (used when WS proxy drops).
+   * Clears the socket reference without triggering the disconnect callback,
+   * allowing the CLI to reconnect.
+   */
+  handleTransportClose(): void {
+    this.cliSocket = null;
+  }
+
+  // -- IBackendAdapter: Raw message ingestion from CLI ------------------------
+
+  /**
+   * Called when raw NDJSON data arrives from the CLI WebSocket.
+   * Parses lines, deduplicates, and routes each message.
+   */
+  handleRawMessage(data: string): void {
+    // Record raw incoming CLI message before any parsing
+    this.recorder?.record(
+      this.sessionId, "in", data, "cli", "claude", "",
+    );
+
+    const lines = parseNDJSON(data);
+    for (const line of lines) {
+      let msg: CLIMessage;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        reportProtocolDrift(
+          this.parseErrorSeen,
+          {
+            backend: "claude",
+            sessionId: this.sessionId,
+            direction: "incoming",
+            messageKind: "parse_error",
+            messageName: "ndjson",
+            rawPreview: line,
+          },
+          (message) => this.browserMessageCb?.({ type: "error", message }),
+        );
+        continue;
+      }
+
+      if (isDuplicateCLIMessage(msg, line, this.dedupState, CLI_DEDUP_WINDOW)) {
+        continue;
+      }
+
+      this.routeCLIMessage(msg);
+    }
+  }
+
+  // -- IBackendAdapter: send() -- browser -> CLI translation ------------------
+
+  send(msg: BrowserOutgoingMessage): boolean {
+    switch (msg.type) {
+      case "user_message":
+        return this.handleOutgoingUserMessage(msg);
+
+      case "permission_response":
+        return this.handleOutgoingPermissionResponse(msg);
+
+      case "interrupt":
+        return this.handleOutgoingInterrupt();
+
+      case "set_model":
+        return this.handleOutgoingSetModel(msg.model);
+
+      case "set_permission_mode":
+        return this.handleOutgoingSetPermissionMode(msg.mode);
+
+      case "set_ai_validation":
+        // AI validation state is managed at the bridge/session level, not
+        // forwarded to the CLI. Return true to indicate acceptance.
+        return true;
+
+      case "mcp_get_status":
+        return this.handleOutgoingMcpGetStatus();
+
+      case "mcp_toggle":
+        return this.handleOutgoingMcpToggle(msg.serverName, msg.enabled);
+
+      case "mcp_reconnect":
+        return this.handleOutgoingMcpReconnect(msg.serverName);
+
+      case "mcp_set_servers":
+        return this.handleOutgoingMcpSetServers(msg.servers);
+
+      case "end_session":
+        return this.handleOutgoingEndSession((msg as { reason?: string }).reason);
+
+      case "stop_task":
+        return this.handleOutgoingStopTask((msg as { task_id: string }).task_id);
+
+      case "update_environment_variables":
+        return this.handleOutgoingUpdateEnvVars((msg as { variables: Record<string, string> }).variables);
+
+      case "session_subscribe":
+      case "session_ack":
+        // These are handled at the bridge level -- never forwarded to the backend.
+        return false;
+
+      default:
+        return false;
+    }
+  }
+
+  // -- Outgoing message handlers (browser -> NDJSON) --------------------------
+
+  private handleOutgoingUserMessage(
+    msg: { type: "user_message"; content: string; session_id?: string; images?: { media_type: string; data: string }[] },
+  ): boolean {
+    // Build content: if images are present, use content block array; otherwise plain string
+    let content: string | unknown[];
+    if (msg.images?.length) {
+      const blocks: unknown[] = [];
+      for (const img of msg.images) {
+        blocks.push({
+          type: "image",
+          source: { type: "base64", media_type: img.media_type, data: img.data },
+        });
+      }
+      blocks.push({ type: "text", text: msg.content });
+      content = blocks;
+    } else {
+      content = msg.content;
+    }
+
+    const ndjson = JSON.stringify({
+      type: "user",
+      message: { role: "user", content },
+      parent_tool_use_id: null,
+      session_id: msg.session_id || "",
+    });
+    this.sendToBackend(ndjson);
+    return true;
+  }
+
+  private handleOutgoingPermissionResponse(
+    msg: {
+      type: "permission_response";
+      request_id: string;
+      behavior: "allow" | "deny";
+      updated_input?: Record<string, unknown>;
+      updated_permissions?: unknown[];
+      message?: string;
+    },
+  ): boolean {
+    if (msg.behavior === "allow") {
+      const response: Record<string, unknown> = {
+        behavior: "allow",
+        updatedInput: msg.updated_input ?? {},
+      };
+      if (msg.updated_permissions?.length) {
+        response.updatedPermissions = msg.updated_permissions;
+      }
+      const ndjson = JSON.stringify({
+        type: "control_response",
+        response: {
+          subtype: "success",
+          request_id: msg.request_id,
+          response,
+        },
+      });
+      this.sendToBackend(ndjson);
+    } else {
+      const ndjson = JSON.stringify({
+        type: "control_response",
+        response: {
+          subtype: "success",
+          request_id: msg.request_id,
+          response: {
+            behavior: "deny",
+            message: msg.message || "Denied by user",
+          },
+        },
+      });
+      this.sendToBackend(ndjson);
+    }
+    return true;
+  }
+
+  private handleOutgoingInterrupt(): boolean {
+    const ndjson = JSON.stringify({
+      type: "control_request",
+      request_id: randomUUID(),
+      request: { subtype: "interrupt" },
+    });
+    this.sendToBackend(ndjson);
+    return true;
+  }
+
+  private handleOutgoingSetModel(model: string): boolean {
+    const ndjson = JSON.stringify({
+      type: "control_request",
+      request_id: randomUUID(),
+      request: { subtype: "set_model", model },
+    });
+    this.sendToBackend(ndjson);
+    return true;
+  }
+
+  private handleOutgoingSetPermissionMode(mode: string): boolean {
+    const ndjson = JSON.stringify({
+      type: "control_request",
+      request_id: randomUUID(),
+      request: { subtype: "set_permission_mode", mode },
+    });
+    this.sendToBackend(ndjson);
+    return true;
+  }
+
+  private handleOutgoingMcpGetStatus(): boolean {
+    this.sendControlRequest(
+      { subtype: "mcp_status" },
+      {
+        subtype: "mcp_status",
+        resolve: (response) => {
+          const servers = (response as { mcpServers?: McpServerDetail[] }).mcpServers ?? [];
+          this.browserMessageCb?.({ type: "mcp_status", servers });
+        },
+      },
+    );
+    return true;
+  }
+
+  private handleOutgoingMcpToggle(serverName: string, enabled: boolean): boolean {
+    this.sendControlRequest({ subtype: "mcp_toggle", serverName, enabled });
+    // Refresh MCP status after a delay to pick up the change
+    setTimeout(() => this.handleOutgoingMcpGetStatus(), 500);
+    return true;
+  }
+
+  private handleOutgoingMcpReconnect(serverName: string): boolean {
+    this.sendControlRequest({ subtype: "mcp_reconnect", serverName });
+    // Refresh MCP status after a delay to pick up the reconnection
+    setTimeout(() => this.handleOutgoingMcpGetStatus(), 1000);
+    return true;
+  }
+
+  private handleOutgoingMcpSetServers(servers: Record<string, unknown>): boolean {
+    this.sendControlRequest({ subtype: "mcp_set_servers", servers });
+    // Refresh MCP status after a delay to pick up the new server config
+    setTimeout(() => this.handleOutgoingMcpGetStatus(), 2000);
+    return true;
+  }
+
+  private handleOutgoingEndSession(reason?: string): boolean {
+    this.sendControlRequest({ subtype: "end_session", ...(reason ? { reason } : {}) });
+    return true;
+  }
+
+  private handleOutgoingStopTask(taskId: string): boolean {
+    this.sendControlRequest({ subtype: "stop_task", task_id: taskId });
+    return true;
+  }
+
+  private handleOutgoingUpdateEnvVars(variables: Record<string, string>): boolean {
+    const ndjson = JSON.stringify({
+      type: "update_environment_variables",
+      variables,
+    });
+    this.sendToBackend(ndjson);
+    return true;
+  }
+
+  // -- CLI message routing (NDJSON -> BrowserIncomingMessage) -----------------
+
+  private routeCLIMessage(msg: CLIMessage): void {
+    // Track activity for idle detection (skip keepalives -- they don't indicate real work)
+    if (msg.type !== "keep_alive") {
+      this.onActivityUpdate?.();
+    }
+
+    switch (msg.type) {
+      case "system":
+        this.handleSystemMessage(msg);
+        break;
+
+      case "assistant":
+        this.handleAssistantMessage(msg);
+        break;
+
+      case "result":
+        this.handleResultMessage(msg);
+        break;
+
+      case "stream_event":
+        this.handleStreamEvent(msg);
+        break;
+
+      case "control_request":
+        this.handleControlRequest(msg);
+        break;
+
+      case "control_response":
+        this.handleControlResponse(msg);
+        break;
+
+      case "tool_progress":
+        this.handleToolProgress(msg);
+        break;
+
+      case "tool_use_summary":
+        this.handleToolUseSummary(msg);
+        break;
+
+      case "auth_status":
+        this.handleAuthStatus(msg);
+        break;
+
+      case "keep_alive":
+        // Silently consume keepalives
+        break;
+
+      case "user":
+        // CLI echoes back user messages (including tool_result blocks from
+        // subagents). These are purely informational — the bridge already
+        // persists user messages from the browser side. Silently drop them
+        // to avoid rendering raw tool_result JSON in the chat UI.
+        break;
+
+      case "rate_limit_event":
+        // Rate-limit status from Claude API (allowed/throttled). Silently
+        // consumed — no user-facing action needed.
+        break;
+
+      case "control_cancel_request":
+        this.handleControlCancelRequest(msg as CLIControlCancelRequestMessage);
+        break;
+
+      case "streamlined_text":
+        this.handleStreamlinedText(msg as CLIStreamlinedTextMessage);
+        break;
+
+      case "streamlined_tool_use_summary":
+        this.handleStreamlinedToolUseSummary(msg as CLIStreamlinedToolUseSummaryMessage);
+        break;
+
+      case "prompt_suggestion":
+        this.handlePromptSuggestion(msg as CLIPromptSuggestionMessage);
+        break;
+
+      default:
+        reportProtocolDrift(
+          this.protocolDriftSeen,
+          {
+            backend: "claude",
+            sessionId: this.sessionId,
+            direction: "incoming",
+            messageKind: "message",
+            messageName: (msg as { type?: string }).type || "unknown",
+            rawPreview: JSON.stringify(msg),
+          },
+          (message) => this.browserMessageCb?.({ type: "error", message }),
+        );
+        break;
+    }
+  }
+
+  // -- System message handling ------------------------------------------------
+
+  private handleSystemMessage(msg: CLISystemMessage): void {
+    if (msg.subtype === "init") {
+      this.handleSystemInit(msg as CLISystemInitMessage);
+      return;
+    }
+
+    if (msg.subtype === "status") {
+      const statusMsg = msg as { subtype: "status"; status: "compacting" | null; permissionMode?: string; uuid: string; session_id: string };
+      // Include permissionMode in the emitted message so the bridge can update session state
+      const statusChange: Record<string, unknown> = {
+        type: "status_change",
+        status: statusMsg.status ?? null,
+      };
+      if (statusMsg.permissionMode) {
+        statusChange.permissionMode = statusMsg.permissionMode;
+      }
+      this.browserMessageCb?.(statusChange as BrowserIncomingMessage);
+      return;
+    }
+
+    if (msg.subtype === "compact_boundary") {
+      const m = msg as CLICompactBoundaryMessage;
+      this.emitSystemEvent({
+        subtype: "compact_boundary",
+        compact_metadata: m.compact_metadata,
+        uuid: m.uuid,
+        session_id: m.session_id,
+      });
+      return;
+    }
+
+    if (msg.subtype === "task_notification") {
+      const m = msg as CLITaskNotificationMessage;
+      this.emitSystemEvent({
+        subtype: "task_notification",
+        task_id: m.task_id,
+        status: m.status,
+        output_file: m.output_file,
+        summary: m.summary,
+        uuid: m.uuid,
+        session_id: m.session_id,
+      });
+      return;
+    }
+
+    if (msg.subtype === "files_persisted") {
+      const m = msg as CLIFilesPersistedMessage;
+      this.emitSystemEvent({
+        subtype: "files_persisted",
+        files: m.files,
+        failed: m.failed,
+        processed_at: m.processed_at,
+        uuid: m.uuid,
+        session_id: m.session_id,
+      });
+      return;
+    }
+
+    if (msg.subtype === "hook_started") {
+      const m = msg as CLIHookStartedMessage;
+      this.emitSystemEvent({
+        subtype: "hook_started",
+        hook_id: m.hook_id,
+        hook_name: m.hook_name,
+        hook_event: m.hook_event,
+        uuid: m.uuid,
+        session_id: m.session_id,
+      });
+      return;
+    }
+
+    if (msg.subtype === "hook_progress") {
+      const m = msg as CLIHookProgressMessage;
+      // hook_progress is transient -- emitted but not persisted in message history.
+      // The bridge handler decides on persistence based on message type.
+      this.emitSystemEvent({
+        subtype: "hook_progress",
+        hook_id: m.hook_id,
+        hook_name: m.hook_name,
+        hook_event: m.hook_event,
+        stdout: m.stdout,
+        stderr: m.stderr,
+        output: m.output,
+        uuid: m.uuid,
+        session_id: m.session_id,
+      });
+      return;
+    }
+
+    if (msg.subtype === "hook_response") {
+      const m = msg as CLIHookResponseMessage;
+      this.emitSystemEvent({
+        subtype: "hook_response",
+        hook_id: m.hook_id,
+        hook_name: m.hook_name,
+        hook_event: m.hook_event,
+        output: m.output,
+        stdout: m.stdout,
+        stderr: m.stderr,
+        exit_code: m.exit_code,
+        outcome: m.outcome,
+        uuid: m.uuid,
+        session_id: m.session_id,
+      });
+      return;
+    }
+
+    // Unknown system subtypes are intentionally ignored until we map them.
+  }
+
+  private handleSystemInit(msg: CLISystemInitMessage): void {
+    // Emit session metadata so the bridge can update session state
+    this.sessionMetaCb?.({
+      cliSessionId: msg.session_id,
+      model: msg.model,
+      cwd: msg.cwd,
+    });
+
+    // Emit session_init to browsers with CLI-provided fields only.
+    // The bridge's attachBackendAdapter handler will merge these into the
+    // canonical session state (which owns git info, cost, etc.) and broadcast.
+    this.browserMessageCb?.({
+      type: "session_init",
+      session: {
+        session_id: msg.session_id,
+        model: msg.model,
+        cwd: msg.cwd,
+        tools: msg.tools,
+        permissionMode: msg.permissionMode,
+        claude_code_version: msg.claude_code_version,
+        mcp_servers: msg.mcp_servers,
+        agents: msg.agents ?? [],
+        slash_commands: msg.slash_commands ?? [],
+        skills: msg.skills ?? [],
+      } as SessionState,
+    });
+
+    // Flush any NDJSON messages queued before the CLI was initialized
+    // (e.g. user sent a message while the CLI was still starting up).
+    if (this.pendingMessages.length > 0) {
+      console.log(
+        `[claude-adapter] Flushing ${this.pendingMessages.length} queued message(s) after init for session ${this.sessionId}`,
+      );
+      const queued = this.pendingMessages.splice(0);
+      for (const ndjson of queued) {
+        this.sendRaw(ndjson);
+      }
+    }
+  }
+
+  // -- Assistant, result, stream ----------------------------------------------
+
+  private handleAssistantMessage(msg: CLIAssistantMessage): void {
+    this.browserMessageCb?.({
+      type: "assistant",
+      message: msg.message,
+      parent_tool_use_id: msg.parent_tool_use_id,
+      timestamp: Date.now(),
+    });
+  }
+
+  private handleResultMessage(msg: CLIResultMessage): void {
+    this.browserMessageCb?.({
+      type: "result",
+      data: msg,
+    });
+  }
+
+  private handleStreamEvent(msg: CLIStreamEventMessage): void {
+    this.browserMessageCb?.({
+      type: "stream_event",
+      event: msg.event,
+      parent_tool_use_id: msg.parent_tool_use_id,
+    });
+  }
+
+  // -- Control request (permission) -------------------------------------------
+
+  private handleControlRequest(msg: CLIControlRequestMessage): void {
+    if (msg.request.subtype === "can_use_tool") {
+      const perm: PermissionRequest = {
+        request_id: msg.request_id,
+        tool_name: msg.request.tool_name,
+        input: msg.request.input,
+        permission_suggestions: msg.request.permission_suggestions,
+        description: msg.request.description,
+        tool_use_id: msg.request.tool_use_id,
+        agent_id: msg.request.agent_id,
+        title: msg.request.title,
+        display_name: msg.request.display_name,
+        blocked_path: msg.request.blocked_path,
+        decision_reason: msg.request.decision_reason,
+        timestamp: Date.now(),
+      };
+
+      this.browserMessageCb?.({
+        type: "permission_request",
+        request: perm,
+      });
+    }
+  }
+
+  // -- Control cancel request ------------------------------------------------
+
+  private handleControlCancelRequest(msg: CLIControlCancelRequestMessage): void {
+    // Clean up any pending async control request in the adapter
+    this.pendingControlRequests.delete(msg.request_id);
+    // Emit permission_cancelled so the bridge removes from pendingPermissions
+    this.browserMessageCb?.({
+      type: "permission_cancelled",
+      request_id: msg.request_id,
+    });
+  }
+
+  // -- Streamlined messages (simplified output mode) -------------------------
+
+  private handleStreamlinedText(msg: CLIStreamlinedTextMessage): void {
+    this.browserMessageCb?.({
+      type: "streamlined_text",
+      text: msg.text,
+    } as BrowserIncomingMessage);
+  }
+
+  private handleStreamlinedToolUseSummary(msg: CLIStreamlinedToolUseSummaryMessage): void {
+    this.browserMessageCb?.({
+      type: "streamlined_tool_use_summary",
+      tool_summary: msg.tool_summary,
+    } as BrowserIncomingMessage);
+  }
+
+  // -- Prompt suggestions ----------------------------------------------------
+
+  private handlePromptSuggestion(msg: CLIPromptSuggestionMessage): void {
+    this.browserMessageCb?.({
+      type: "prompt_suggestion",
+      suggestions: msg.suggestions,
+    } as BrowserIncomingMessage);
+  }
+
+  // -- Control response (for pending control requests like MCP status) --------
+
+  private handleControlResponse(msg: CLIControlResponseMessage): void {
+    const reqId = msg.response.request_id;
+    const pending = this.pendingControlRequests.get(reqId);
+    if (!pending) return;
+    this.pendingControlRequests.delete(reqId);
+    if (msg.response.subtype === "error") {
+      console.warn(
+        `[claude-adapter] Control request ${pending.subtype} failed: ${msg.response.error}`,
+      );
+      return;
+    }
+    pending.resolve(msg.response.response ?? {});
+  }
+
+  // -- Tool progress & summary ------------------------------------------------
+
+  private handleToolProgress(msg: CLIToolProgressMessage): void {
+    this.browserMessageCb?.({
+      type: "tool_progress",
+      tool_use_id: msg.tool_use_id,
+      tool_name: msg.tool_name,
+      elapsed_time_seconds: msg.elapsed_time_seconds,
+    });
+  }
+
+  private handleToolUseSummary(msg: CLIToolUseSummaryMessage): void {
+    this.browserMessageCb?.({
+      type: "tool_use_summary",
+      summary: msg.summary,
+      tool_use_ids: msg.preceding_tool_use_ids,
+    });
+  }
+
+  // -- Auth status ------------------------------------------------------------
+
+  private handleAuthStatus(msg: CLIAuthStatusMessage): void {
+    this.browserMessageCb?.({
+      type: "auth_status",
+      isAuthenticating: msg.isAuthenticating,
+      output: msg.output,
+      error: msg.error,
+    });
+  }
+
+  // -- Helpers ----------------------------------------------------------------
+
+  /**
+   * Emit a system_event BrowserIncomingMessage to browsers.
+   */
+  private emitSystemEvent(
+    event: Extract<BrowserIncomingMessage, { type: "system_event" }>["event"],
+  ): void {
+    this.browserMessageCb?.({
+      type: "system_event",
+      event,
+      timestamp: Date.now(),
+    });
+  }
+
+  /**
+   * Send a control_request to the CLI and optionally track the pending response.
+   */
+  private sendControlRequest(
+    request: Record<string, unknown>,
+    onResponse?: { subtype: string; resolve: (response: unknown) => void },
+  ): void {
+    const requestId = randomUUID();
+    if (onResponse) {
+      this.pendingControlRequests.set(requestId, onResponse);
+    }
+    const ndjson = JSON.stringify({
+      type: "control_request",
+      request_id: requestId,
+      request,
+    });
+    this.sendToBackend(ndjson);
+  }
+
+  /**
+   * Send a raw NDJSON string to the CLI, bypassing the BrowserOutgoingMessage
+   * translation layer. Used for Claude-specific control requests (e.g. initialize)
+   * that don't map to a BrowserOutgoingMessage type.
+   */
+  sendRawNDJSON(ndjson: string): void {
+    this.sendToBackend(ndjson);
+  }
+
+  /**
+   * Send an NDJSON string to the CLI. If the CLI socket is not yet connected,
+   * queues the message for later delivery (flushed in attachWebSocket).
+   */
+  private sendToBackend(ndjson: string): void {
+    if (!this.cliSocket) {
+      console.log(
+        `[claude-adapter] CLI not yet connected for session ${this.sessionId}, queuing message`,
+      );
+      this.pendingMessages.push(ndjson);
+      return;
+    }
+    this.sendRaw(ndjson);
+  }
+
+  /**
+   * Low-level send: writes NDJSON to the CLI socket with newline delimiter.
+   * Records the outgoing message. Assumes cliSocket is non-null.
+   */
+  private sendRaw(ndjson: string): void {
+    // Record raw outgoing CLI message
+    this.recorder?.record(
+      this.sessionId, "out", ndjson, "cli", "claude", "",
+    );
+    try {
+      // NDJSON requires a newline delimiter
+      this.cliSocket!.send(ndjson + "\n");
+    } catch (err) {
+      console.error(
+        `[claude-adapter] Failed to send to CLI for session ${this.sessionId}:`,
+        err,
+      );
+    }
+  }
+}