clawtap/docs/superpowers/specs/2026-03-26-adapter-identity-fix-design.md

Adapter Identity Fix — Design Spec

Date: 2026-03-26 Status: Draft

Problem

When opening a historical session without explicit adapter info (URL direct access, browser refresh, push notification), the frontend guesses the adapter from localStorage and initializes model/permissionMode/effort from the wrong adapter's prefs. The server later corrects the adapter via SESSION_CREATED, but model/prefs are never corrected → wrong UI state.

Root Cause

useChat eagerly initializes everything (adapter, model, permissionMode, effort, adapterConfig) at mount time before knowing the correct adapter. When the adapter is unknown, it guesses wrong.

Design Principle

Don't guess. Wait.

If the adapter is known (from prop or URL) → initialize immediately. If the adapter is unknown → show loading → wait for server SESSION_CREATED → then initialize.

Server is the single source of truth for adapter identity.

Changes

Change 1: useChat — defer initialization until adapter is confirmed

File: src/hooks/useChat.ts

Current:

const resolvedAdapter = initialAdapter || localStorage.getItem(STORAGE.ADAPTER) || 'claude';
const initialPrefs = loadAdapterPrefs(resolvedAdapter);
const [model, setModel] = useState(initialPrefs.model || '');
// ... all initialized immediately with possibly wrong adapter

New:

// adapter is either known from prop/URL, or null (wait for server)
const [selectedAdapter, setSelectedAdapter] = useState<string | null>(initialAdapter || null);

// model/prefs initialized only after adapter is confirmed
const [model, setModel] = useState<string>('');
const [permissionMode, setPermissionMode] = useState<string>('default');
const [effort, setEffort] = useState<string>('');

When SESSION_CREATED arrives:

case WS.SESSION_CREATED:
  setSessionId(msg.sessionId);
  if (msg.adapter) {
    setSelectedAdapter(msg.adapter);
    // Load correct prefs now that we know the adapter
    const prefs = loadAdapterPrefs(msg.adapter);
    setModel(prefs.model || '');
    setPermissionMode(msg.permissionMode || prefs.permissionMode || 'default');
    setEffort(prefs.effort || '');
  }
  break;

If initialAdapter was provided (session list click), everything initializes immediately at mount — no waiting, no loading state.

Change 2: ChatView — show loading when adapter unknown

File: src/components/ChatView.tsx

If selectedAdapter is null (waiting for server), render a loading indicator instead of the chat UI:

if (!selectedAdapter) {
  return <LoadingAnimation size="md" label="Connecting..." />;
}

This only happens for path B (URL) and C (notification). Path A (session list) always has adapter → no loading.

Change 3: URL includes adapter when available

File: src/App.tsx

navigateTo() includes adapter in URL when known:

const url = view.sessionId
  ? `/?view=chat&session=${view.sessionId}${view.adapter ? `&adapter=${view.adapter}` : ''}`
  : '/';

URL parser reads adapter from URL:

const sessionId = params.get('session');
const adapter = params.get('adapter');
if (sessionId) {
  openChat(sessionId, undefined, adapter || undefined);
}

Push notification service worker also includes adapter in URL if available.

Change 4: SERVER SESSION_CREATED includes adapter + cwd

File: server/session-manager.ts

sendSessionCreated() includes adapter name (already done) and cwd:

send(conn, {
  type: WS.SESSION_CREATED,
  sessionId,
  adapter: adapterName,
  cwd: sessionObj?.cwd || resolvedCwd,
  permissionMode: sessionObj?.permissionMode,
});

The cwd allows the frontend to show the correct project name in the header even when opened from URL (which doesn't have cwd).

Change 5: handleQuery verifies adapter on resumeSession

File: server/session-manager.ts

When handleQuery receives a QUERY with a sessionId (resume path), verify the adapter:

if (sessionId) {
  const resolvedName = await resolveAdapterForSession(sessionId);
  if (resolvedName) adapterName = resolvedName; // override client's adapter with truth
  handle = await adapter.resumeSession(sessionId, cwd, { permissionMode });
}

Change 6: Active sessions tab shows adapter badge

File: src/components/SessionsView.tsx

Add adapter brand badge to active session cards (same pattern as project sessions list).

Flow After Fix

Path A (Session List Click):

adapter = 'gemini' (from server API) → useChat initializes immediately → no loading
→ WS RECONNECT → server confirms → messages load → render

Path B (URL Direct) / Path C (Push Notification):

adapter = null (unknown) → useChat does NOT initialize prefs → ChatView shows loading
→ WS RECONNECT → server SESSION_CREATED { adapter: 'gemini', cwd: '...' }
→ useChat sets adapter, loads correct prefs → loading disappears → messages load → render

Path B with adapter in URL:

URL: ?session=UUID&adapter=gemini
adapter = 'gemini' (from URL) → useChat initializes immediately → no loading
→ WS RECONNECT → server confirms → messages load → render

Verification

1. Session list → Gemini session: Loads immediately, correct adapter/model/messages
2. URL ?session=UUID (no adapter): Shows loading → then correct adapter/messages
3. URL ?session=UUID&adapter=gemini: Loads immediately, no flash
4. Browser refresh on chat: Adapter from URL → immediate load
5. Push notification click: Loading → then correct session
6. Two tabs same session: Both show correct adapter, messages sync
7. Send from Tab A: Tab B sees user message + thinking + response
8. Active sessions tab: Shows adapter badge
9. New Chat (all adapters): Still works correctly