feat(web-shell): add model-specific reasoning controls

docs/design/webshell-qwen38-max-reasoning-options.md

@@ -0,0 +1,72 @@
+# Model reasoning controls registry
+
+## Goal
+
+Expose model-specific Thinking and reasoning-effort controls without teaching
+clients about individual model ids. A built-in Core registry declares which
+controls each exact bare model id supports and their defaults.
+
+`qwen3.8-max` supports `low`, `medium`, and `xhigh`; its default is
+`xhigh`. `qwen3.8-max-preview`, runtime snapshots, and aliases are
+deliberately excluded.
+
+## Design
+
+The registry independently declares optional `thinking` and `effort`
+capabilities. An effort registration contains its ordered supported tiers and
+default. The first registration is `qwen3.8-max`: Thinking defaults on and
+Effort supports `low`, `medium`, and `xhigh`, defaulting to `xhigh`.
+
+These defaults are not UI-only. When a registered model has no stored
+preference and no provider-provided reasoning state, resolution writes the
+defaults into the generation config, so every surface (CLI, daemon, ACP,
+channels) sends `reasoning: { effort: 'xhigh' }` to `qwen3.8-max` instead of
+omitting the field and leaving the tier to the server's default.
+
+The ACP session `configOptions` snapshot is the source of truth for live
+sessions. The agent dynamically advertises the registered `thought_level`
+options for the active model:
+
+- `thinking`: `on` or `off`
+- `effort`: `low`, `medium`, or `xhigh`
+
+Changes travel through a daemon session config-option mutation and are echoed
+as ACP `config_option_update` notifications. Web clients update their cached
+connection state from both the attach snapshot and live notifications.
+The ACP session also observes Core model changes, so model switches initiated
+by slash commands or workspace reloads re-apply the active model's preferences
+and publish the same config and model notifications as the session API.
+
+The daemon's workspace model catalog carries the same optional capability
+metadata so a composer can render controls before a session exists. Older
+daemons omit both the capability metadata and `session_reasoning_control`, so
+clients retain the model-only picker.
+
+Persisted values live in `model.reasoningPreferences`, keyed by exact bare
+model id. Each entry can store `thinkingEnabled` and `effort`. Missing or
+invalid values use the registry defaults and never inherit the global
+`model.reasoningEffort`; the global setting remains unchanged for unregistered
+models. Turning thinking off does not erase the tier. TUI `/effort` keeps its
+five-tier picker but normalizes a selection to the registered model's supported
+subset before storing it.
+
+Before a live session exists, WebShell merges the selected model's preference
+into the map through the workspace settings API. Once attached, it uses the
+session mutation so the current session and future sessions stay in sync. A
+failed post-write settings reload is surfaced as an update error rather than
+leaving the composer on stale state.
+
+## UI behavior
+
+The existing model chip remains the only entry point. For a model with
+reasoning controls, the popover's first level renders each registered section
+independently (Thinking, then Effort) and moves the searchable model list
+behind a second-level "Model" submenu; models without reasoning controls keep
+the flat searchable list. This supports Thinking-only, Effort-only, and
+combined models. Effort rows remain visible but disabled while Thinking is off
+when both controls exist.
+Changing an option keeps the popover open. During an active response the
+controls remain available; the new value applies to the next request.
+
+Older daemons that do not advertise `session_reasoning_control` keep the
+existing model-only popover.

integration-tests/cli/acp-integration.test.ts

@@ -791,20 +791,26 @@ function setupAcpTest(
     // Track which permission requests we've seen
     const planModeRequests: PermissionRequest[] = [];
 
-    const { sendRequest, cleanup, stderr, sessionUpdates, permissionRequests, agent } =
-      setupAcpTest(rig, {
-        permissionHandler: (request) => {
-          // Track all permission requests for later verification
-          // Auto-approve exit plan mode requests with "proceed_always" to trigger auto-edit mode
-          if (request.toolCall?.kind === 'switch_mode') {
-            planModeRequests.push(request);
-            // Return proceed_always to switch to auto-edit mode
-            return { optionId: 'proceed_always' };
-          }
-          // Auto-approve all other requests
-          return { optionId: 'proceed_once' };
-        },
-      });
+    const {
+      sendRequest,
+      cleanup,
+      stderr,
+      sessionUpdates,
+      permissionRequests,
+      agent,
+    } = setupAcpTest(rig, {
+      permissionHandler: (request) => {
+        // Track all permission requests for later verification
+        // Auto-approve exit plan mode requests with "proceed_always" to trigger auto-edit mode
+        if (request.toolCall?.kind === 'switch_mode') {
+          planModeRequests.push(request);
+          // Return proceed_always to switch to auto-edit mode
+          return { optionId: 'proceed_always' };
+        }
+        // Auto-approve all other requests
+        return { optionId: 'proceed_once' };
+      },
+    });
 
     try {
       // Initialize

integration-tests/cli/qwen-serve-routes.test.ts

@@ -365,6 +365,7 @@ describe('qwen serve — capabilities envelope', () => {
       'workspace_file_read_cursor',
       'workspace_file_write',
       'session_approval_mode_control',
+      'session_reasoning_control',
       'workspace_tool_toggle',
       'workspace_skill_toggle',
       'workspace_skill_batch_toggle',

packages/acp-bridge/src/bridge.test.ts

@@ -14214,6 +14214,120 @@ describe('createAcpSessionBridge', () => {
     });
   });
 
+  describe('setSessionConfigOption', () => {
+    /** Set up a channel where the agent records setSessionConfigOption calls. */
+    async function setup(response: Record<string, unknown> = {}) {
+      const configOptionCalls: Array<{
+        sessionId: string;
+        configId: string;
+        value: string;
+      }> = [];
+      const factory: ChannelFactory = async () => {
+        const { clientStream, agentStream } = createInMemoryChannel();
+        const fakeAgent = new FakeAgent();
+        const augmented = new Proxy(fakeAgent, {
+          get(target, prop) {
+            if (prop === 'setSessionConfigOption') {
+              return async (req: {
+                sessionId: string;
+                configId: string;
+                value: string;
+              }) => {
+                configOptionCalls.push({ ...req });
+                return response;
+              };
+            }
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return (target as any)[prop];
+          },
+        });
+        new AgentSideConnection(() => augmented as Agent, agentStream);
+        return {
+          stream: clientStream,
+          exited: new Promise<
+            | { exitCode: number | null; signalCode: NodeJS.Signals | null }
+            | undefined
+          >(() => {}),
+          kill: async () => {},
+          killSync: () => {},
+        };
+      };
+      const bridge = makeBridge({ channelFactory: factory });
+      const session = await bridge.spawnOrAttach({ workspaceCwd: WS_A });
+      return { bridge, session, configOptionCalls };
+    }
+
+    it('forwards configId and value and overrides body sessionId', async () => {
+      const { bridge, session, configOptionCalls } = await setup({
+        configOptions: [],
+      });
+      const response = await bridge.setSessionConfigOption(session.sessionId, {
+        sessionId: 'spoofed',
+        configId: 'effort',
+        value: 'medium',
+      });
+      expect(response).toEqual({ configOptions: [] });
+      expect(configOptionCalls[0]).toEqual({
+        sessionId: session.sessionId,
+        configId: 'effort',
+        value: 'medium',
+      });
+      await bridge.shutdown();
+    });
+
+    it('publishes settings_changed for model.reasoningPreferences', async () => {
+      const { bridge, session } = await setup({ configOptions: [] });
+      const abort = new AbortController();
+      const iter = bridge.subscribeEvents(session.sessionId, {
+        signal: abort.signal,
+      });
+      await bridge.setSessionConfigOption(session.sessionId, {
+        sessionId: session.sessionId,
+        configId: 'thinking',
+        value: 'off',
+      });
+      const it = iter[Symbol.asyncIterator]();
+      const next = await it.next();
+      expect(next.value?.type).toBe('settings_changed');
+      expect(next.value?.data).toEqual({
+        key: 'model.reasoningPreferences',
+      });
+      abort.abort();
+      await bridge.shutdown();
+    });
+
+    it('rejects unregistered client ids', async () => {
+      const { bridge, session } = await setup();
+      await expect(
+        bridge.setSessionConfigOption(
+          session.sessionId,
+          {
+            sessionId: session.sessionId,
+            configId: 'effort',
+            value: 'low',
+          },
+          { clientId: 'client-not-issued' },
+        ),
+      ).rejects.toBeInstanceOf(InvalidClientIdError);
+      await bridge.shutdown();
+    });
+
+    it('throws SessionNotFoundError for unknown session ids', async () => {
+      const bridge = makeBridge({
+        channelFactory: async () => {
+          throw new Error('factory should not be called');
+        },
+      });
+      await expect(
+        bridge.setSessionConfigOption('unknown', {
+          sessionId: 'unknown',
+          configId: 'thinking',
+          value: 'off',
+        }),
+      ).rejects.toBeInstanceOf(SessionNotFoundError);
+    });
+  });
+
   describe('executeShellCommand permission policy', () => {
     function mockShellExecute(output = 'ok') {
       return vi.spyOn(ShellExecutionService, 'execute').mockResolvedValue({

packages/acp-bridge/src/bridge.ts

@@ -8627,6 +8627,34 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge {
       return response;
     },
 
+    async setSessionConfigOption(sessionId, req, context) {
+      const entry = byId.get(sessionId);
+      if (!entry) throw new SessionNotFoundError(sessionId);
+      const originatorClientId = resolveTrustedClientId(
+        entry,
+        context?.clientId,
+      );
+      const response = await Promise.race([
+        withTimeout(
+          entry.connection.setSessionConfigOption({ ...req, sessionId }),
+          initTimeoutMs,
+          'setSessionConfigOption',
+        ),
+        getTransportClosedReject(entry),
+      ]);
+      // Thinking/effort roundtrips persist `model.reasoningPreferences`
+      // child-side; broadcast settings_changed like setSessionModel does for
+      // `model.name` so other attached clients reload their settings caches.
+      if (req.configId === 'thinking' || req.configId === 'effort') {
+        broadcastWorkspaceEvent({
+          type: 'settings_changed',
+          data: { key: 'model.reasoningPreferences' },
+          ...(originatorClientId ? { originatorClientId } : {}),
+        });
+      }
+      return response;
+    },
+
     async setSessionLanguage(sessionId, params, context) {
       const entry = byId.get(sessionId);
       if (!entry) throw new SessionNotFoundError(sessionId);

packages/acp-bridge/src/bridgeTypes.ts

@@ -15,6 +15,8 @@ import type {
   PromptResponse,
   RequestPermissionResponse,
   ResumeSessionResponse,
+  SetSessionConfigOptionRequest,
+  SetSessionConfigOptionResponse,
   SetSessionModelRequest,
   SetSessionModelResponse,
   SessionUpdate,
@@ -1545,6 +1547,13 @@ export interface AcpSessionBridge {
     context?: BridgeClientRequestContext,
   ): Promise<SetSessionModelResponse>;
 
+  /** Update one ACP session configuration option. */
+  setSessionConfigOption(
+    sessionId: string,
+    req: SetSessionConfigOptionRequest,
+    context?: BridgeClientRequestContext,
+  ): Promise<SetSessionConfigOptionResponse>;
+
   /**
    * Switch UI language and optionally LLM output language for a live
    * session, then broadcast a `language_changed` event.  When

packages/acp-bridge/src/status.ts

@@ -499,6 +499,21 @@ export interface ServeWorkspaceProviderCurrent {
   visionModelId?: string;
 }
 
+export type ServeModelReasoningEffort =
+  | 'low'
+  | 'medium'
+  | 'high'
+  | 'xhigh'
+  | 'max';
+
+export interface ServeModelReasoningControls {
+  thinking?: { defaultEnabled: boolean };
+  effort?: {
+    supported: ServeModelReasoningEffort[];
+    default: ServeModelReasoningEffort;
+  };
+}
+
 export interface ServeWorkspaceProviderModel {
   modelId: string;
   baseModelId: string;
@@ -513,6 +528,7 @@ export interface ServeWorkspaceProviderModel {
   };
   baseUrl?: string;
   envKey?: string;
+  reasoningControls?: ServeModelReasoningControls;
   isCurrent: boolean;
   isRuntime: boolean;
 }
@@ -531,6 +547,7 @@ export interface ServeWorkspaceProvidersStatus {
   acpChannelLive?: boolean;
   current?: ServeWorkspaceProviderCurrent;
   approvalMode?: string;
+  modelConfigScope?: 'workspace' | 'user';
   providers: ServeWorkspaceProviderStatus[];
   errors?: ServeStatusCell[];
 }