feat(gemini): support mid-session model change

[junmo-kim]

Summary

• Consolidate Gemini model definitions into shared/src/modes.ts as a single source of truth (GEMINI_MODEL_LABELS → GEMINI_MODEL_PRESETS derived via Object.keys(), DEFAULT_GEMINI_MODEL)
• Enable mid-session model switching for Gemini sessions, matching the existing Claude model change UX
• Introduce supportsModelChange() flavor capability function to replace hardcoded isClaudeFlavor() checks

Motivation

Gemini sessions have no way to change models mid-conversation — the model change UI, API endpoint, and RPC handler are all gated to Claude-only. Additionally, Gemini model definitions are spread across three locations (config.ts, types.ts, AcpStdioTransport.ts).

This PR consolidates model definitions and extends model selection support to Gemini sessions, consistent with the existing Claude implementation.

Related issues: #302, #221, #326, #123

Design notes

• Model input is not validated against presets — arbitrary model strings are accepted, consistent with the existing Claude handler pattern. This allows users to specify custom/preview models via environment variables or local config.
• Model changes take effect on the next local/remote launcher restart, not mid-conversation. This is an inherent limitation of the Gemini CLI architecture (--model is a process start argument) and matches the Claude behavior.

Test plan

• runGemini.test.ts: model change via RPC — success, null (Default), validation error, and selective response cases (6 tests)
• modelOptions.test.ts: flavor-based model option generation for both Claude and Gemini (4 tests)
• Existing claudeModelOptions.test.ts passes (no regression)
• TypeScript type checks pass across cli, hub, web
• E2E: Playwright — new session form shows 6 Gemini model options, Effort auto-hides
• E2E: Live — active Gemini session model change via settings UI, POST /model → 200 confirmed

[github-actions]

Findings

• [Major] Selecting Default does not actually clear an explicit Gemini session model. In set-session-config, the null path is converted back to runtimeConfig.model, and that value is returned in applied.model, so the hub persists the previous concrete model and resume keeps treating it as explicit. Evidence cli/src/gemini/runGemini.ts:151, context hub/src/sync/sessionCache.ts:279.
  Suggested fix:

  let sessionModel: string | null = persistedModel ?? null
  let resolvedModel = sessionModel ?? runtimeConfig.model
  
  if (config.model !== undefined) {
      sessionModel = resolveModel(config.model)
      resolvedModel = sessionModel ?? runtimeConfig.model
      applied.model = sessionModel
  }
  
  sessionInstance.setModel(sessionModel)

• [Major] Custom Gemini models disappear from the composer selector. The new Gemini branch only mirrors MODEL_OPTIONS.gemini, so a session started from a custom env/local model has no selected option, and Cmd/Ctrl+M immediately jumps to Default, overwriting the custom model on first toggle. Evidence web/src/components/AssistantChat/modelOptions.ts:7, context web/src/components/AssistantChat/HappyComposer.tsx:544.
  Suggested fix:

  function getGeminiModelOptions(currentModel?: string | null): ModelOption[] {
      const options = MODEL_OPTIONS.gemini.map((m) => ({
          value: m.value === 'auto' ? null : m.value,
          label: m.label
      }))
      const normalized = currentModel?.trim() || null
      if (normalized && !options.some((option) => option.value === normalized)) {
          options.splice(1, 0, { value: normalized, label: normalized })
      }
      return options
  }

Summary
Review mode: initial. Two regressions in the Gemini model-change flow: Default cannot clear a persisted explicit model, and custom Gemini models are no longer preserved in the composer UI.

Testing
Not run (automation): bun is unavailable in this runner (/bin/bash: bun: command not found). Existing added tests do not cover clearing a persisted Gemini model or preserving a custom Gemini model in the composer selector.

HAPI Bot

[github-actions]

[MAJOR] null is turned back into runtimeConfig.model here, so the hub never sees a cleared preference. After a session has ever been started with an explicit Gemini model, choosing Default keeps persisting that concrete value and resume continues launching with it.

Suggested fix:

let sessionModel: string | null = persistedModel ?? null
let resolvedModel = sessionModel ?? runtimeConfig.model

if (config.model !== undefined) {
    sessionModel = resolveModel(config.model)
    resolvedModel = sessionModel ?? runtimeConfig.model
    applied.model = sessionModel
}

sessionInstance.setModel(sessionModel)

[github-actions]

[MAJOR] This helper ignores currentModel for Gemini, so custom models coming from env/local config are missing from the option list. In the composer that means no selected radio for the active model, and Cmd/Ctrl+M jumps straight to Default, overwriting the custom value on the first toggle.

Suggested fix:

function getGeminiModelOptions(currentModel?: string | null): ModelOption[] {
    const options = MODEL_OPTIONS.gemini.map((m) => ({
        value: m.value === 'auto' ? null : m.value,
        label: m.label
    }))
    const normalized = currentModel?.trim() || null
    if (normalized && !options.some((option) => option.value === normalized)) {
        options.splice(1, 0, { value: normalized, label: normalized })
    }
    return options
}

[github-actions]

Findings

• [Major] Gemini sessions now persist the resolved runtime model as an explicit session preference, so sessions started on Default stop behaving like Default after the first keepalive. syncSessionMode() writes resolvedModel into the session object, AgentSessionBase includes that in keepalives, and the hub stores it for resume. Evidence cli/src/gemini/runGemini.ts:108, context cli/src/agent/sessionBase.ts:127, hub/src/sync/sessionCache.ts:184, hub/src/sync/syncEngine.ts:402.
  Suggested fix:

  let sessionModel: string | null = persistedModel ?? null
  let resolvedModel = sessionModel ?? runtimeConfig.model
  
  const syncSessionMode = () => {
      const sessionInstance = sessionWrapperRef.current
      if (!sessionInstance) return
      sessionInstance.setPermissionMode(currentPermissionMode)
      sessionInstance.setModel(sessionModel)
  }
  
  if (config.model !== undefined) {
      sessionModel = resolveModel(config.model)
      resolvedModel = sessionModel ?? runtimeConfig.model
      applied.model = sessionModel
  }

Summary
Review mode: follow-up after new commits. One major regression remains unresolved: the Gemini CLI still writes the resolved runtime model into keepalive state, so the hub persists it as an explicit session model and resume no longer behaves like Default.

Testing
Not run (automation): bun is unavailable in this runner (/bin/bash: bun: command not found). Added tests still do not cover keepalive/resume persistence when a Gemini session stays on Default.

HAPI Bot

[github-actions]

[MAJOR] syncSessionMode() is still storing resolvedModel in the session, so the keepalive path reports a concrete Gemini model even when the session is supposed to be on Default. The hub then persists that value and resume starts treating the fallback/env/local runtime model as an explicit session override.

Suggested fix:

let sessionModel: string | null = persistedModel ?? null
let resolvedModel = sessionModel ?? runtimeConfig.model

const syncSessionMode = () => {
    const sessionInstance = sessionWrapperRef.current
    if (!sessionInstance) return
    sessionInstance.setPermissionMode(currentPermissionMode)
    sessionInstance.setModel(sessionModel)
}

if (config.model !== undefined) {
    sessionModel = resolveModel(config.model)
    resolvedModel = sessionModel ?? runtimeConfig.model
    applied.model = sessionModel
}

[github-actions]

Findings

• [Minor] Gemini Default is now labeled as Gemini 2.5 Pro, but the CLI still resolves the effective default from GEMINI_MODEL_ENV or ~/.gemini config before falling back to gemini-2.5-pro. That makes both the new-session selector and the composer menu advertise the wrong model whenever a machine has a custom/default Gemini config. Evidence web/src/components/NewSession/types.ts:28, context cli/src/gemini/utils/config.ts:97, cli/src/gemini/utils/config.ts:100, cli/src/gemini/utils/config.ts:103.
  Suggested fix:

  gemini: [
      { value: 'auto', label: 'Default' },
      ...GEMINI_MODEL_PRESETS.map((m) => ({ value: m, label: GEMINI_MODEL_LABELS[m] })),
  ],

Summary
Review mode: follow-up after new commits. One minor correctness issue remains: the new Gemini Default label can misreport which model will actually run, because runtime resolution still prefers env/local Gemini config over the shared fallback constant. No other high-confidence issues found in the updated diff.

Testing
Not run (automation): bun unavailable in this runner (/bin/bash: bun: command not found).

HAPI Bot

[github-actions]

[MINOR] Default (${GEMINI_MODEL_LABELS[DEFAULT_GEMINI_MODEL]}) hardcodes Gemini 2.5 Pro into the UI, but resolveGeminiRuntimeConfig() still prefers GEMINI_MODEL_ENV and ~/.gemini config before it falls back to DEFAULT_GEMINI_MODEL (cli/src/gemini/utils/config.ts:97-105). After this change, users on a machine with a custom Gemini default will see the wrong model in both the create-session form and the composer menu, because modelOptions.ts reuses MODEL_OPTIONS.gemini.

Suggested fix:

gemini: [
    { value: 'auto', label: 'Default' },
    ...GEMINI_MODEL_PRESETS.map((m) => ({ value: m, label: GEMINI_MODEL_LABELS[m] })),
],

[github-actions]

Findings

• [Major] Selecting Gemini Default cannot restore the machine default once the session was started or resumed with an explicit model. resolveGeminiRuntimeConfig({ model: opts.model }) marks that startup model as explicit, and the new fallback path reuses runtimeConfig.model when model: null is selected, so the next local/remote launcher restart keeps using the old explicit model instead of env/~/.gemini/shared default. Evidence cli/src/gemini/runGemini.ts:65, cli/src/gemini/runGemini.ts:154, context cli/src/gemini/loop.ts:49, cli/src/gemini/utils/config.ts:97.
  Suggested fix:

  const runtimeConfig = resolveGeminiRuntimeConfig({ model: opts.model })
  const machineDefaultModel = resolveGeminiRuntimeConfig().model
  
  let sessionModel: string | null = persistedModel ?? null
  let resolvedModel = sessionModel ?? machineDefaultModel
  
  if (config.model !== undefined) {
      sessionModel = resolveModel(config.model)
      resolvedModel = sessionModel ?? machineDefaultModel
  }
  
  await geminiLoop({
      // ...
      model: machineDefaultModel,
  })

Summary
Review mode: follow-up after new commits. One major correctness issue remains: Gemini Default does not actually switch back to the machine/default model after a session starts with an explicit model, so subsequent local/remote relaunches keep using the stale explicit model. No other high-confidence issues found in the updated diff.

Testing
Not run (automation): bun unavailable in this runner (/bin/bash: bun: command not found). Suggested coverage: start Gemini with an explicit model, call set-session-config with model: null, then verify the next launcher restart uses env/local/default resolution.

HAPI Bot

[github-actions]

[MAJOR] Selecting Default here does not restore the machine default if the session was started or resumed with an explicit Gemini model. runtimeConfig was created from opts.model, so sessionModel = null falls back to that same explicit startup value, and geminiLoop() still uses it on the next local/remote relaunch via opts.model (cli/src/gemini/loop.ts:49-52, cli/src/gemini/utils/config.ts:97-105).

Suggested fix:

const machineDefaultModel = resolveGeminiRuntimeConfig().model
let resolvedModel = sessionModel ?? machineDefaultModel

if (config.model !== undefined) {
    sessionModel = resolveModel(config.model)
    resolvedModel = sessionModel ?? machineDefaultModel
}

await geminiLoop({
    // ...
    model: machineDefaultModel,
})

[github-actions]

Findings

• [Major] Gemini Default still relaunches with the stale startup model. runGemini() now recomputes resolvedModel correctly when model: null arrives, but geminiLoop() still falls back to its original opts.model snapshot when session.getModel() is null, so the next local/remote launcher restart reuses the startup model instead of the machine default. Evidence cli/src/gemini/loop.ts:49, context cli/src/gemini/runGemini.ts:153.
  Suggested fix:

  await geminiLoop({
      // ...
      getDefaultModel: () => resolvedModel,
  })
  
  const getCurrentModel = (): string | undefined => {
      const sessionModel = session.getModel()
      return sessionModel != null ? sessionModel : opts.getDefaultModel()
  }

Summary
Review mode: follow-up after new commits. One major correctness issue remains: selecting Gemini Default still does not update the model used for the next launcher restart, because geminiLoop() keeps falling back to its startup opts.model snapshot. No other high-confidence issues found in the updated diff.

Testing
Not run (automation): bun not installed in this runner. Suggested coverage: change Gemini to an explicit model, switch back to Default, force a local/remote relaunch, and assert the launcher uses the machine default rather than the startup model.

HAPI Bot

[github-actions]

[MAJOR] opts.model is still the startup snapshot here. After set-session-config({ model: null }), runGemini() updates resolvedModel, but session.getModel() becomes null, so the next relaunch falls back to this stale value instead of the machine default (cli/src/gemini/runGemini.ts:153). Selecting Default after an explicit Gemini model therefore still restarts with the old startup model.

Suggested fix:

await geminiLoop({
    // ...
    getDefaultModel: () => resolvedModel,
})

const getCurrentModel = (): string | undefined => {
    const sessionModel = session.getModel()
    return sessionModel != null ? sessionModel : opts.getDefaultModel()
}

[github-actions]

Findings

• No high-confidence issues found in the current diff.

Summary
Review mode: follow-up after new commits. No diff-introduced correctness, security, or maintainability regressions found on the latest head. Residual risk/testing gap: Not run in this runner because bun is unavailable, and I did not find route-level coverage added for the new Gemini POST /api/sessions/:id/model path in hub/src/web/routes/sessions.test.ts.

Testing
Not run (automation): bun not installed in this runner. Suggested coverage: add a hub route test for Gemini POST /api/sessions/:id/model, plus an integration path that switches Gemini from an explicit model back to Default and verifies the next launcher restart uses the machine default.

HAPI Bot