heyhank 0.1.0

package/server/worktree-tracker.ts

@@ -0,0 +1,84 @@
+import {
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  existsSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+import { HEYHANK_HOME } from "./paths.js";
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface WorktreeMapping {
+  sessionId: string;
+  repoRoot: string;
+  branch: string;
+  /** Actual git branch in the worktree (may differ from `branch` for -wt-N branches) */
+  actualBranch?: string;
+  worktreePath: string;
+  createdAt: number;
+}
+
+// ─── Paths ──────────────────────────────────────────────────────────────────
+
+const TRACKER_PATH = join(HEYHANK_HOME, "worktrees.json");
+
+// ─── Tracker ────────────────────────────────────────────────────────────────
+
+export class WorktreeTracker {
+  private mappings: WorktreeMapping[] = [];
+
+  constructor() {
+    this.load();
+  }
+
+  load(): WorktreeMapping[] {
+    try {
+      if (existsSync(TRACKER_PATH)) {
+        const raw = readFileSync(TRACKER_PATH, "utf-8");
+        this.mappings = JSON.parse(raw) as WorktreeMapping[];
+      }
+    } catch {
+      this.mappings = [];
+    }
+    return this.mappings;
+  }
+
+  private save(): void {
+    mkdirSync(dirname(TRACKER_PATH), { recursive: true });
+    writeFileSync(TRACKER_PATH, JSON.stringify(this.mappings, null, 2), "utf-8");
+  }
+
+  addMapping(mapping: WorktreeMapping): void {
+    // Remove any existing mapping for this session
+    this.mappings = this.mappings.filter((m) => m.sessionId !== mapping.sessionId);
+    this.mappings.push(mapping);
+    this.save();
+  }
+
+  removeBySession(sessionId: string): WorktreeMapping | null {
+    const idx = this.mappings.findIndex((m) => m.sessionId === sessionId);
+    if (idx === -1) return null;
+    const [removed] = this.mappings.splice(idx, 1);
+    this.save();
+    return removed;
+  }
+
+  getBySession(sessionId: string): WorktreeMapping | null {
+    return this.mappings.find((m) => m.sessionId === sessionId) || null;
+  }
+
+  getSessionsForWorktree(worktreePath: string): WorktreeMapping[] {
+    return this.mappings.filter((m) => m.worktreePath === worktreePath);
+  }
+
+  getSessionsForRepo(repoRoot: string): WorktreeMapping[] {
+    return this.mappings.filter((m) => m.repoRoot === repoRoot);
+  }
+
+  isWorktreeInUse(worktreePath: string, excludeSessionId?: string): boolean {
+    return this.mappings.some(
+      (m) => m.worktreePath === worktreePath && m.sessionId !== excludeSessionId,
+    );
+  }
+}

package/server/ws-auth.ts

@@ -0,0 +1,41 @@
+import { verifyToken } from "./middleware/managed-auth.js";
+
+export interface WsAuthResult {
+  ok: boolean;
+  status: number;
+  body?: string;
+}
+
+function getCookie(header: string | null, name: string): string | undefined {
+  if (!header) return undefined;
+  const match = header.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`));
+  return match?.[1];
+}
+
+/**
+ * Authenticate browser/terminal WebSocket upgrade requests in managed mode.
+ * Accepts token in query param or heyhank_token cookie (query takes precedence).
+ */
+export async function authenticateManagedWebSocket(req: Request): Promise<WsAuthResult> {
+  const secret = (process.env.HEYHANK_AUTH_SECRET || process.env.COMPANION_AUTH_SECRET)?.trim();
+  if (!secret) {
+    return { ok: false, status: 500, body: "Server misconfigured" };
+  }
+
+  const url = new URL(req.url);
+  const queryToken = url.searchParams.get("token");
+  const cookieToken = getCookie(req.headers.get("cookie"), "heyhank_token") || getCookie(req.headers.get("cookie"), "companion_token");
+  const token = queryToken || cookieToken;
+
+  if (!token) {
+    return { ok: false, status: 401, body: "Unauthorized" };
+  }
+
+  const valid = await verifyToken(token, secret);
+  if (!valid) {
+    return { ok: false, status: 401, body: "Unauthorized" };
+  }
+
+  return { ok: true, status: 200 };
+}
+

package/server/ws-bridge-browser-ingest.ts

@@ -0,0 +1,72 @@
+import type { BrowserOutgoingMessage } from "./session-types.js";
+import type { Session } from "./ws-bridge-types.js";
+import {
+  isDuplicateClientMessage,
+  rememberClientMessage,
+} from "./ws-bridge-replay.js";
+
+// ─── Browser Ingest Pipeline ────────────────────────────────────────────────
+// Pure functions for parsing and deduplicating browser WebSocket messages.
+// Extracted from WsBridge.handleBrowserMessage and routeBrowserMessage
+// to enable isolated testing of idempotent message scenarios.
+
+/** Message types that support client_msg_id-based deduplication. */
+export const IDEMPOTENT_BROWSER_MESSAGE_TYPES: ReadonlySet<string> = new Set([
+  "user_message",
+  "permission_response",
+  "interrupt",
+  "set_model",
+  "set_permission_mode",
+  "mcp_get_status",
+  "mcp_toggle",
+  "mcp_reconnect",
+  "mcp_set_servers",
+  "set_ai_validation",
+]);
+
+/**
+ * Parse a raw browser WebSocket message into a typed BrowserOutgoingMessage.
+ * Returns null if parsing fails (malformed JSON).
+ */
+export function parseBrowserMessage(raw: string | Buffer): BrowserOutgoingMessage | null {
+  const data = typeof raw === "string" ? raw : raw.toString("utf-8");
+  try {
+    return JSON.parse(data) as BrowserOutgoingMessage;
+  } catch {
+    console.warn(`[ws-bridge] Failed to parse browser message: ${data.substring(0, 200)}`);
+    return null;
+  }
+}
+
+/**
+ * Check if a browser message is a duplicate based on client_msg_id.
+ * Returns true if the message should be skipped.
+ *
+ * Only checks messages whose type is in `idempotentTypes` and that have
+ * a non-empty `client_msg_id` field. For non-idempotent types or messages
+ * without client_msg_id, always returns false.
+ *
+ * If not a duplicate, remembers the client_msg_id for future dedup checks.
+ */
+export function deduplicateBrowserMessage(
+  msg: BrowserOutgoingMessage,
+  idempotentTypes: ReadonlySet<string>,
+  session: Session,
+  processedIdLimit: number,
+  persistFn: (session: Session) => void,
+): boolean {
+  if (
+    !idempotentTypes.has(msg.type)
+    || !("client_msg_id" in msg)
+    || !msg.client_msg_id
+  ) {
+    return false;
+  }
+
+  if (isDuplicateClientMessage(session, msg.client_msg_id)) {
+    return true;
+  }
+
+  rememberClientMessage(session, msg.client_msg_id, processedIdLimit, persistFn);
+  return false;
+}

package/server/ws-bridge-browser.ts

@@ -0,0 +1,112 @@
+import type { ServerWebSocket } from "bun";
+import type { BrowserSocketData, Session, SocketData } from "./ws-bridge-types.js";
+import type {
+  BrowserIncomingMessage,
+  ReplayableBrowserIncomingMessage,
+} from "./session-types.js";
+
+/**
+ * Infer the CLI's current status from server-side session state.
+ * Used as a ground-truth correction after event replay to prevent
+ * stale "running"/"generating" state when `result` was pruned from
+ * the event buffer.
+ */
+function inferCliStatus(session: Session): "idle" | "running" | "compacting" | null {
+  if (session.state.is_compacting) return "compacting";
+  const last = session.messageHistory[session.messageHistory.length - 1];
+  if (!last) return "idle";
+  // `result` means the last turn completed → idle
+  if (last.type === "result") return "idle";
+  // `assistant` means CLI sent a response and is executing tools or streaming → running
+  if (last.type === "assistant") return "running";
+  // For other types (user_message, system_event), default to idle
+  return "idle";
+}
+
+export function handleSessionSubscribe(
+  session: Session,
+  ws: ServerWebSocket<SocketData> | undefined,
+  lastSeq: number,
+  sendToBrowser: (ws: ServerWebSocket<SocketData>, msg: BrowserIncomingMessage) => void,
+  isHistoryBackedEvent: (msg: ReplayableBrowserIncomingMessage) => boolean,
+): void {
+  if (!ws) return;
+  const data = ws.data as BrowserSocketData;
+  data.subscribed = true;
+  const lastAckSeq = Number.isFinite(lastSeq) ? Math.max(0, Math.floor(lastSeq)) : 0;
+  data.lastAckSeq = lastAckSeq;
+
+  if (lastAckSeq === 0 && session.messageHistory.length > 0) {
+    sendToBrowser(ws, {
+      type: "message_history",
+      messages: session.messageHistory,
+    });
+  }
+
+  if (session.eventBuffer.length === 0) return;
+  if (lastAckSeq >= session.nextEventSeq - 1) return;
+
+  const earliest = session.eventBuffer[0]?.seq ?? session.nextEventSeq;
+  const hasGap = lastAckSeq > 0 && lastAckSeq < earliest - 1;
+  if (hasGap) {
+    if (session.messageHistory.length > 0) {
+      sendToBrowser(ws, {
+        type: "message_history",
+        messages: session.messageHistory,
+      });
+    }
+    const transientMissed = session.eventBuffer
+      .filter((evt) => evt.seq > lastAckSeq && !isHistoryBackedEvent(evt.message));
+    if (transientMissed.length > 0) {
+      sendToBrowser(ws, {
+        type: "event_replay",
+        events: transientMissed,
+      });
+    }
+    // Send ground-truth status after replay to correct stale streaming state
+    sendToBrowser(ws, { type: "status_change", status: inferCliStatus(session) });
+    // Send authoritative session_phase so replayed transient phases don't leave stale cliConnected
+    sendToBrowser(ws, {
+      type: "session_phase",
+      phase: session.stateMachine.phase,
+      previousPhase: session.stateMachine.phase,
+    });
+    return;
+  }
+
+  const sentFullHistory = lastAckSeq === 0 && session.messageHistory.length > 0;
+  const missed = session.eventBuffer.filter(
+    (evt) => evt.seq > lastAckSeq && (!sentFullHistory || !isHistoryBackedEvent(evt.message)),
+  );
+  if (missed.length === 0) return;
+  sendToBrowser(ws, {
+    type: "event_replay",
+    events: missed,
+  });
+  // Send ground-truth status after replay to correct stale streaming state
+  sendToBrowser(ws, { type: "status_change", status: inferCliStatus(session) });
+  // Send authoritative session_phase so replayed transient phases don't leave stale cliConnected
+  sendToBrowser(ws, {
+    type: "session_phase",
+    phase: session.stateMachine.phase,
+    previousPhase: session.stateMachine.phase,
+  });
+}
+
+export function handleSessionAck(
+  session: Session,
+  ws: ServerWebSocket<SocketData> | undefined,
+  lastSeq: number,
+  persistSession: (session: Session) => void,
+): void {
+  const normalized = Number.isFinite(lastSeq) ? Math.max(0, Math.floor(lastSeq)) : 0;
+  if (ws) {
+    const data = ws.data as BrowserSocketData;
+    const prior = typeof data.lastAckSeq === "number" ? data.lastAckSeq : 0;
+    data.lastAckSeq = Math.max(prior, normalized);
+  }
+  if (normalized > session.lastAckSeq) {
+    session.lastAckSeq = normalized;
+    persistSession(session);
+  }
+}

package/server/ws-bridge-cli-ingest.ts

@@ -0,0 +1,81 @@
+import type { CLIMessage } from "./session-types.js";
+
+// ─── CLI Ingest Pipeline ────────────────────────────────────────────────────
+// Pure functions for parsing and deduplicating CLI (NDJSON) messages.
+// Extracted from WsBridge.handleCLIMessage to enable isolated testing
+// of reconnect/replay deduplication scenarios.
+
+/** State needed for CLI message deduplication. Matches a subset of Session. */
+export interface CLIDedupState {
+  recentCLIMessageHashes: string[];
+  recentCLIMessageHashSet: Set<string>;
+}
+
+/**
+ * Parse raw NDJSON data into individual line strings.
+ * Splits on newlines and filters blank lines.
+ */
+export function parseNDJSON(raw: string | Buffer): string[] {
+  const data = typeof raw === "string" ? raw : raw.toString("utf-8");
+  return data.split("\n").filter((l) => l.trim());
+}
+
+/**
+ * Check if a CLI message is a duplicate based on a rolling hash window.
+ * On WS reconnect, the CLI replays in-flight messages; this dedup prevents
+ * duplicates from reaching downstream handlers.
+ *
+ * - `assistant`, `result`, `system` messages: deduped by content hash (Bun.hash)
+ * - `stream_event` messages: deduped by their stable `uuid` field
+ * - All other types (keep_alive, control_request, tool_progress, etc.): never deduped
+ *
+ * Returns true if the message is a duplicate and should be skipped.
+ * Mutates the dedupState window as a side effect.
+ */
+export function isDuplicateCLIMessage(
+  msg: CLIMessage,
+  rawLine: string,
+  state: CLIDedupState,
+  windowSize: number,
+): boolean {
+  if (msg.type === "assistant" || msg.type === "result" || msg.type === "system") {
+    // Namespace with "h:" prefix to prevent collisions with uuid-based keys
+    const key = `h:${Bun.hash(rawLine).toString(36)}`;
+    if (state.recentCLIMessageHashSet.has(key)) {
+      return true;
+    }
+    state.recentCLIMessageHashes.push(key);
+    state.recentCLIMessageHashSet.add(key);
+    while (state.recentCLIMessageHashes.length > windowSize) {
+      const old = state.recentCLIMessageHashes.shift()!;
+      state.recentCLIMessageHashSet.delete(old);
+    }
+    return false;
+  }
+
+  if (msg.type === "stream_event" && (msg as { uuid?: string }).uuid) {
+    // Namespace with "u:" prefix to prevent collisions with hash-based keys.
+    // Current CLI versions (1.0+) always provide UUIDs on stream_event messages.
+    // UUID-less stream_events from older protocol versions fall through to no-dedup below.
+    const key = `u:${(msg as { uuid: string }).uuid}`;
+    if (state.recentCLIMessageHashSet.has(key)) {
+      return true;
+    }
+    state.recentCLIMessageHashes.push(key);
+    state.recentCLIMessageHashSet.add(key);
+    while (state.recentCLIMessageHashes.length > windowSize) {
+      const old = state.recentCLIMessageHashes.shift()!;
+      state.recentCLIMessageHashSet.delete(old);
+    }
+    return false;
+  }
+
+  // All other message types (keep_alive, control_request, tool_progress, etc.)
+  // are never considered duplicates — they're either stateless or handled by
+  // separate mechanisms. stream_event without uuid also falls through here;
+  // current CLI versions (1.0+) always provide UUIDs, but older protocol
+  // versions may not. In that case, reconnect replay could produce duplicate
+  // stream content in the UI — acceptable since stream_events are transient
+  // and the final assistant message is always deduplicated.
+  return false;
+}

package/server/ws-bridge-codex.ts

@@ -0,0 +1,266 @@
+import type {
+  BrowserIncomingMessage,
+  BrowserOutgoingMessage,
+  PermissionRequest,
+} from "./session-types.js";
+import type { CodexAdapter } from "./codex-adapter.js";
+import type { Session } from "./ws-bridge-types.js";
+import { appendHistory } from "./ws-bridge-persist.js";
+import { validatePermission } from "./ai-validator.js";
+import { getEffectiveAiValidation } from "./ai-validation-settings.js";
+import { heyHankBus } from "./event-bus.js";
+
+/**
+ * @deprecated This file is no longer used in production. Codex adapters are now
+ * wired through the unified `attachBackendAdapter()` pipeline in `ws-bridge.ts`.
+ * This file is kept only for its test coverage which validates Codex-specific
+ * adapter handler logic patterns. It will be removed in a future cleanup pass.
+ */
+
+export interface CodexAttachDeps {
+  persistSession: (session: Session) => void;
+  refreshGitInfo: (
+    session: Session,
+    options?: { broadcastUpdate?: boolean; notifyPoller?: boolean },
+  ) => void;
+  broadcastToBrowsers: (session: Session, msg: BrowserIncomingMessage) => void;
+  autoNamingAttempted: Set<string>;
+}
+
+export function attachCodexAdapterHandlers(
+  sessionId: string,
+  session: Session,
+  adapter: CodexAdapter,
+  deps: CodexAttachDeps,
+): void {
+  adapter.onBrowserMessage((msg) => {
+    // Track activity for idle detection — mirrors routeCLIMessage logic for
+    // Claude Code NDJSON. Without this, Codex sessions get incorrectly
+    // idle-killed because lastCliActivityTs is never updated.
+    session.lastCliActivityTs = Date.now();
+
+    if (msg.type === "session_init") {
+      // Preserve pre-populated commands/skills when adapter sends empty arrays
+      // (Codex does not provide its own commands/skills)
+      // Exclude session_id: the adapter may report its own internal session ID
+      // which differs from the HeyHank's session ID.  Allowing it to overwrite
+      // session.state.session_id causes duplicate sidebar entries.
+      const { slash_commands, skills, session_id: _cliSessionId, ...rest } = msg.session;
+      session.state = {
+        ...session.state,
+        ...rest,
+        ...(slash_commands?.length ? { slash_commands } : {}),
+        ...(skills?.length ? { skills } : {}),
+        backend_type: "codex",
+      };
+      deps.refreshGitInfo(session, { notifyPoller: true });
+      deps.persistSession(session);
+      session.stateMachine.transition("ready", "codex_session_init");
+    } else if (msg.type === "session_update") {
+      // Exclude session_id — same rationale as session_init above.
+      const { slash_commands, skills, session_id: _cliSessionId, ...rest } = msg.session;
+      session.state = {
+        ...session.state,
+        ...rest,
+        ...(slash_commands?.length ? { slash_commands } : {}),
+        ...(skills?.length ? { skills } : {}),
+        backend_type: "codex",
+      };
+      deps.refreshGitInfo(session, { notifyPoller: true });
+      deps.persistSession(session);
+    } else if (msg.type === "status_change") {
+      session.state.is_compacting = msg.status === "compacting";
+      if (msg.status === "compacting") {
+        session.stateMachine.transition("compacting", "codex_compacting_started");
+      } else {
+        session.stateMachine.transition("ready", "codex_compacting_ended");
+      }
+      deps.persistSession(session);
+    }
+
+    if (msg.type === "assistant") {
+      const assistantMsg = { ...msg, timestamp: msg.timestamp || Date.now() };
+      appendHistory(session, assistantMsg);
+      deps.persistSession(session);
+      heyHankBus.emit("message:assistant", { sessionId, message: assistantMsg });
+    } else if (msg.type === "result") {
+      appendHistory(session, msg);
+      deps.persistSession(session);
+      heyHankBus.emit("message:result", { sessionId, message: msg });
+      session.stateMachine.transition("ready", "codex_turn_completed");
+    }
+
+    if (msg.type === "assistant") {
+      const content = (msg as { message?: { content?: Array<{ type: string }> } }).message?.content;
+      const hasToolUse = content?.some((b) => b.type === "tool_use");
+      if (hasToolUse) {
+        console.log(`[ws-bridge] Broadcasting tool_use assistant to ${session.browserSockets.size} browser(s) for session ${session.id}`);
+      }
+    }
+
+    if (msg.type === "permission_cancelled") {
+      const reqId = (msg as { request_id: string }).request_id;
+      session.pendingPermissions.delete(reqId);
+      // If no more pending permissions, transition back to streaming
+      if (session.pendingPermissions.size === 0 && session.stateMachine.phase === "awaiting_permission") {
+        session.stateMachine.transition("streaming", "permission_cancelled");
+      }
+      deps.persistSession(session);
+    }
+
+    if (msg.type === "permission_request") {
+      const perm = msg.request;
+
+      // AI Validation Mode for Codex sessions
+      const aiSettings = getEffectiveAiValidation(session.state);
+      if (
+        aiSettings.enabled
+        && aiSettings.anthropicApiKey
+        && perm.tool_name !== "AskUserQuestion"
+        && perm.tool_name !== "ExitPlanMode"
+      ) {
+        // Run AI validation async — don't broadcast yet
+        handleCodexAiValidation(session, adapter, perm, deps).catch((err) => {
+          console.warn(`[ws-bridge-codex] AI validation error for tool=${perm.tool_name} request_id=${perm.request_id} session=${session.id}, falling through to manual:`, err);
+          // On error, fall through to normal permission flow
+          session.pendingPermissions.set(perm.request_id, perm);
+          session.stateMachine.transition("awaiting_permission", "ai_validation_error_fallback");
+          deps.persistSession(session);
+          deps.broadcastToBrowsers(session, msg);
+        });
+        return;
+      }
+
+      session.pendingPermissions.set(perm.request_id, perm);
+      deps.persistSession(session);
+      session.stateMachine.transition("awaiting_permission", "codex_permission_requested");
+    }
+
+    deps.broadcastToBrowsers(session, msg);
+
+    if (
+      msg.type === "result" &&
+      !(msg.data as { is_error?: boolean }).is_error &&
+      !deps.autoNamingAttempted.has(session.id)
+    ) {
+      deps.autoNamingAttempted.add(session.id);
+      const firstUserMsg = session.messageHistory.find((m) => m.type === "user_message");
+      if (firstUserMsg && firstUserMsg.type === "user_message") {
+        heyHankBus.emit("session:first-turn-completed", { sessionId: session.id, firstUserMessage: firstUserMsg.content });
+      }
+    }
+  });
+
+  adapter.onSessionMeta((meta) => {
+    if (meta.cliSessionId) {
+      heyHankBus.emit("session:cli-id-received", { sessionId: session.id, cliSessionId: meta.cliSessionId });
+    }
+    if (meta.model) session.state.model = meta.model;
+    if (meta.cwd) session.state.cwd = meta.cwd;
+    session.state.backend_type = "codex";
+    deps.refreshGitInfo(session, { broadcastUpdate: true, notifyPoller: true });
+    deps.persistSession(session);
+  });
+
+  adapter.onDisconnect(() => {
+    // Guard: only clear the adapter reference if THIS adapter is still the active
+    // one.  During relaunch, a NEW adapter is attached before the OLD one fires
+    // its disconnect callback — without this check the new adapter gets nulled out.
+    if (session.backendAdapter !== adapter) {
+      console.log(`[ws-bridge] Ignoring stale disconnect for session ${sessionId} (adapter replaced)`);
+      return;
+    }
+    for (const [reqId] of session.pendingPermissions) {
+      deps.broadcastToBrowsers(session, { type: "permission_cancelled", request_id: reqId });
+    }
+    session.pendingPermissions.clear();
+    session.backendAdapter = null;
+    deps.persistSession(session);
+    console.log(`[ws-bridge] Codex adapter disconnected for session ${sessionId}`);
+    deps.broadcastToBrowsers(session, { type: "cli_disconnected" });
+
+    // Auto-relaunch if browsers are still connected (don't leave users staring
+    // at a dead session when the transport drops mid-conversation).
+    if (session.browserSockets.size > 0) {
+      console.log(`[ws-bridge] Auto-relaunching Codex for session ${sessionId} (${session.browserSockets.size} browser(s) connected)`);
+      heyHankBus.emit("session:relaunch-needed", { sessionId });
+    }
+  });
+
+  if (session.pendingMessages.length > 0) {
+    console.log(`[ws-bridge] Flushing ${session.pendingMessages.length} queued message(s) to Codex adapter for session ${sessionId}`);
+    const queued = session.pendingMessages.splice(0);
+    for (const raw of queued) {
+      try {
+        const msg = JSON.parse(raw) as BrowserOutgoingMessage;
+        adapter.sendBrowserMessage(msg);
+      } catch {
+        console.warn(`[ws-bridge] Failed to parse queued message for Codex: ${raw.substring(0, 100)}`);
+      }
+    }
+  }
+
+  deps.broadcastToBrowsers(session, { type: "cli_connected" });
+  console.log(`[ws-bridge] Codex adapter attached for session ${sessionId}`);
+}
+
+async function handleCodexAiValidation(
+  session: Session,
+  adapter: CodexAdapter,
+  perm: PermissionRequest,
+  deps: CodexAttachDeps,
+): Promise<void> {
+  const aiSettings = getEffectiveAiValidation(session.state);
+  const result = await validatePermission(
+    perm.tool_name,
+    perm.input,
+    perm.description,
+  );
+
+  perm.ai_validation = {
+    verdict: result.verdict,
+    reason: result.reason,
+    ruleBasedOnly: result.ruleBasedOnly,
+  };
+
+  // Auto-approve safe tools
+  if (result.verdict === "safe" && aiSettings.autoApprove) {
+    deps.broadcastToBrowsers(session, {
+      type: "permission_auto_resolved",
+      request: perm,
+      behavior: "allow",
+      reason: result.reason,
+    });
+    adapter.sendBrowserMessage({
+      type: "permission_response",
+      request_id: perm.request_id,
+      behavior: "allow",
+    });
+    return;
+  }
+
+  // Auto-deny dangerous tools
+  if (result.verdict === "dangerous" && aiSettings.autoDeny) {
+    deps.broadcastToBrowsers(session, {
+      type: "permission_auto_resolved",
+      request: perm,
+      behavior: "deny",
+      reason: result.reason,
+    });
+    adapter.sendBrowserMessage({
+      type: "permission_response",
+      request_id: perm.request_id,
+      behavior: "deny",
+    });
+    return;
+  }
+
+  // Uncertain or auto-action disabled: fall through to manual
+  session.pendingPermissions.set(perm.request_id, perm);
+  session.stateMachine.transition("awaiting_permission", "ai_validation_manual_fallback");
+  deps.persistSession(session);
+  deps.broadcastToBrowsers(session, {
+    type: "permission_request",
+    request: perm,
+  });
+}

package/server/ws-bridge-controls.ts

@@ -0,0 +1,20 @@
+import type { Session } from "./ws-bridge-types.js";
+
+export function handleSetAiValidation(
+  session: Session,
+  msg: {
+    aiValidationEnabled?: boolean | null;
+    aiValidationAutoApprove?: boolean | null;
+    aiValidationAutoDeny?: boolean | null;
+  },
+): void {
+  if (msg.aiValidationEnabled !== undefined) {
+    session.state.aiValidationEnabled = msg.aiValidationEnabled;
+  }
+  if (msg.aiValidationAutoApprove !== undefined) {
+    session.state.aiValidationAutoApprove = msg.aiValidationAutoApprove;
+  }
+  if (msg.aiValidationAutoDeny !== undefined) {
+    session.state.aiValidationAutoDeny = msg.aiValidationAutoDeny;
+  }
+}