🤖 feat: split Exec sub-agent AI defaults

docs/agents/index.mdx

@@ -185,6 +185,17 @@ task({
 
 Only agents with `subagent.runnable: true` can be used this way.
 
+### Run-context AI defaults
+
+The same agent identity can use different default model and thinking settings depending on how it runs:
+
+- **UI defaults** (`agentAiDefaults`) apply when you select the agent directly in the UI, such as choosing Exec in the chat input.
+- **Subagent defaults** (`subagentAiDefaults`) apply when that agent is spawned through the `task` tool.
+
+Subagent defaults inherit from UI defaults per field. If the subagent model is unset, Mux uses the matching UI agent model; if subagent thinking is unset, Mux uses the matching UI agent thinking level. You can override one subagent field and keep the other inherited.
+
+Mux resolves the subagent model and thinking level when the `task` call creates the child workspace. Those resolved values are stored with that child workspace, so changing defaults later affects future subagent tasks only.
+
 ## Examples
 
 ### Security Audit Agent

src/browser/contexts/ThinkingContext.test.tsx

@@ -4,18 +4,26 @@ import { act, cleanup, render, waitFor } from "@testing-library/react";
 import React from "react";
 import { ThinkingProvider } from "./ThinkingContext";
 import { APIProvider, type APIClient } from "@/browser/contexts/API";
+import { AgentProvider, type AgentContextValue } from "@/browser/contexts/AgentContext";
+import { ProjectProvider } from "@/browser/contexts/ProjectContext";
+import { ProviderOptionsProvider } from "@/browser/contexts/ProviderOptionsContext";
+import { RouterProvider } from "@/browser/contexts/RouterContext";
+import { useWorkspaceContext, WorkspaceProvider } from "@/browser/contexts/WorkspaceContext";
 import { useThinkingLevel } from "@/browser/hooks/useThinkingLevel";
+import type { FrontendWorkspaceMetadata } from "@/common/types/workspace";
+import type { RecursivePartial } from "@/browser/testUtils";
+
+let currentClientMock: RecursivePartial<APIClient> = {};
+let metadataMap = new Map<string, FrontendWorkspaceMetadata>();
 import {
   getModelKey,
   getProjectScopeId,
   getThinkingLevelByModelKey,
   getThinkingLevelKey,
 } from "@/common/constants/storage";
-import type { RecursivePartial } from "@/browser/testUtils";
+import { useSendMessageOptions } from "@/browser/hooks/useSendMessageOptions";
 import { updatePersistedState } from "@/browser/hooks/usePersistedState";
 
-let currentClientMock: RecursivePartial<APIClient> = {};
-
 // Setup basic DOM environment for testing-library
 const dom = new GlobalWindow();
 /* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access */
@@ -34,6 +42,13 @@ interface TestProps {
   workspaceId: string;
 }
 
+type WorkspaceUpdateAgentAISettingsArgs = Parameters<
+  APIClient["workspace"]["updateAgentAISettings"]
+>[0];
+type WorkspaceUpdateAgentAISettingsResult = Awaited<
+  ReturnType<APIClient["workspace"]["updateAgentAISettings"]>
+>;
+
 const TestComponent: React.FC<TestProps> = (props) => {
   const [thinkingLevel] = useThinkingLevel();
   return (
@@ -43,10 +58,161 @@ const TestComponent: React.FC<TestProps> = (props) => {
   );
 };
 
+const agentContextValue: AgentContextValue = {
+  agentId: "exec",
+  setAgentId: () => undefined,
+  currentAgent: undefined,
+  agents: [],
+  loaded: true,
+  loadFailed: false,
+  refresh: () => Promise.resolve(),
+  refreshing: false,
+  disableWorkspaceAgents: false,
+  setDisableWorkspaceAgents: () => undefined,
+};
+
+const ThinkingSetterComponent: React.FC = () => {
+  const [, setThinkingLevel] = useThinkingLevel();
+  return (
+    <button data-testid="set-thinking-medium" onClick={() => setThinkingLevel("medium")}>
+      Set thinking
+    </button>
+  );
+};
+
+const SendOptionsComponent: React.FC<{ workspaceId: string }> = (props) => {
+  const options = useSendMessageOptions(props.workspaceId);
+  return <div data-testid="base-model">{options.baseModel}</div>;
+};
+
 function renderWithAPI(children: React.ReactNode) {
   return render(<APIProvider client={currentClientMock as APIClient}>{children}</APIProvider>);
 }
 
+function createWorkspaceMetadata(
+  overrides: Partial<FrontendWorkspaceMetadata> & Pick<FrontendWorkspaceMetadata, "id">
+): FrontendWorkspaceMetadata {
+  return {
+    projectPath: "/tmp/project",
+    projectName: "project",
+    name: "main",
+    namedWorkspacePath: "/tmp/project/main",
+    createdAt: "2026-01-01T00:00:00.000Z",
+    runtimeConfig: { type: "local", srcBaseDir: "/tmp/.mux/src" },
+    ...overrides,
+  };
+}
+
+function setWorkspaceMetadata(metadata: FrontendWorkspaceMetadata) {
+  metadataMap = new Map([[metadata.id, metadata]]);
+}
+
+function createEmptyAsyncIterable<T>(): AsyncIterable<T> {
+  return {
+    async *[Symbol.asyncIterator](): AsyncIterator<T> {
+      await Promise.resolve();
+      if (Date.now() < 0) yield undefined as T;
+    },
+  };
+}
+
+function WorkspaceMetadataGate(props: {
+  workspaceId: string;
+  modelOverride?: string | null;
+  thinkingOverride?: "off" | null;
+  children: React.ReactNode;
+}) {
+  const { workspaceMetadata } = useWorkspaceContext();
+  if (!workspaceMetadata.has(props.workspaceId)) {
+    return null;
+  }
+
+  if (props.modelOverride !== undefined) {
+    if (props.modelOverride == null) {
+      window.localStorage.removeItem(getModelKey(props.workspaceId));
+    } else {
+      updatePersistedState(getModelKey(props.workspaceId), props.modelOverride);
+    }
+  }
+
+  if (props.thinkingOverride !== undefined) {
+    if (props.thinkingOverride == null) {
+      window.localStorage.removeItem(getThinkingLevelKey(props.workspaceId));
+    } else {
+      updatePersistedState(getThinkingLevelKey(props.workspaceId), props.thinkingOverride);
+    }
+  }
+
+  return <>{props.children}</>;
+}
+
+function createWorkspaceClient(): APIClient {
+  const workspaceOverrides = currentClientMock.workspace ?? {};
+  const projectOverrides = currentClientMock.projects ?? {};
+  const serverOverrides = currentClientMock.server ?? {};
+
+  return {
+    ...currentClientMock,
+    workspace: {
+      list: () => Promise.resolve(Array.from(metadataMap.values())),
+      onMetadata: () => Promise.resolve(createEmptyAsyncIterable()),
+      onChat: () => Promise.resolve(createEmptyAsyncIterable()),
+      getSessionUsage: () => Promise.resolve(undefined),
+      updateAgentAISettings: mock(() =>
+        Promise.resolve({ success: true as const, data: undefined })
+      ),
+      activity: {
+        list: () => Promise.resolve({}),
+        subscribe: () => Promise.resolve(createEmptyAsyncIterable()),
+        ...workspaceOverrides.activity,
+      },
+      truncateHistory: () => Promise.resolve({ success: true as const, data: undefined }),
+      interruptStream: () => Promise.resolve({ success: true as const, data: undefined }),
+      ...workspaceOverrides,
+    },
+    projects: {
+      list: () => Promise.resolve([]),
+      listBranches: () => Promise.resolve({ branches: ["main"], recommendedTrunk: "main" }),
+      secrets: {
+        get: () => Promise.resolve([]),
+        ...projectOverrides.secrets,
+      },
+      ...projectOverrides,
+    },
+    server: {
+      getLaunchProject: () => Promise.resolve(null),
+      ...serverOverrides,
+    },
+  } as unknown as APIClient;
+}
+
+function renderWithWorkspaceMetadata(props: {
+  workspaceId: string;
+  modelOverride?: string | null;
+  thinkingOverride?: "off" | null;
+  children: React.ReactNode;
+}) {
+  // Use the real WorkspaceProvider so this file does not poison other Bun test files
+  // by replacing the whole WorkspaceContext module globally.
+  return render(
+    <APIProvider client={createWorkspaceClient()}>
+      <RouterProvider>
+        <ProjectProvider>
+          <WorkspaceProvider>
+            <WorkspaceMetadataGate
+              workspaceId={props.workspaceId}
+              modelOverride={props.modelOverride}
+              thinkingOverride={props.thinkingOverride}
+            >
+              {props.children}
+            </WorkspaceMetadataGate>
+          </WorkspaceProvider>
+        </ProjectProvider>
+      </RouterProvider>
+    </APIProvider>
+  );
+}
+
 describe("ThinkingContext", () => {
   // Make getDefaultModel deterministic.
   // (getDefaultModel reads from the global "model-default" localStorage key.)
@@ -61,15 +227,138 @@ describe("ThinkingContext", () => {
         ),
       },
     };
+    metadataMap = new Map();
     window.localStorage.clear();
     window.localStorage.setItem("model-default", JSON.stringify("openai:default"));
   });
 
   afterEach(() => {
     cleanup();
+    metadataMap = new Map();
     currentClientMock = {};
   });
 
+  test("uses metadata model before global default but keeps explicit model", async () => {
+    const cases = [
+      { workspaceId: "ws-model-metadata", override: null, expected: "openai:gpt-5.5" },
+      {
+        workspaceId: "ws-model-explicit",
+        override: "anthropic:explicit-model",
+        expected: "anthropic:explicit-model",
+      },
+    ];
+
+    for (const testCase of cases) {
+      const metadata = createWorkspaceMetadata({
+        id: testCase.workspaceId,
+        aiSettings: { model: "openai:gpt-5.5", thinkingLevel: "high" },
+      });
+      setWorkspaceMetadata(metadata);
+
+      const view = renderWithWorkspaceMetadata({
+        workspaceId: testCase.workspaceId,
+        modelOverride: testCase.override,
+        children: (
+          <ProviderOptionsProvider>
+            <AgentProvider value={agentContextValue}>
+              <ThinkingProvider workspaceId={testCase.workspaceId}>
+                <SendOptionsComponent workspaceId={testCase.workspaceId} />
+              </ThinkingProvider>
+            </AgentProvider>
+          </ProviderOptionsProvider>
+        ),
+      });
+
+      await waitFor(() => {
+        expect(view.getByTestId("base-model").textContent).toBe(testCase.expected);
+      });
+      cleanup();
+    }
+  });
+
+  test("setting thinking uses metadata model before global default", async () => {
+    const workspaceId = "ws-set-thinking-metadata-model";
+    const updateAgentAISettings = mock<
+      (args: WorkspaceUpdateAgentAISettingsArgs) => Promise<WorkspaceUpdateAgentAISettingsResult>
+    >(() =>
+      Promise.resolve({
+        success: true as const,
+        data: undefined,
+      })
+    );
+    currentClientMock = {
+      workspace: { updateAgentAISettings },
+    };
+
+    setWorkspaceMetadata(
+      createWorkspaceMetadata({
+        id: workspaceId,
+        aiSettings: { model: "metadataModel:abc", thinkingLevel: "high" },
+      })
+    );
+
+    const view = renderWithWorkspaceMetadata({
+      workspaceId,
+      modelOverride: null,
+      children: (
+        <ThinkingProvider workspaceId={workspaceId}>
+          <ThinkingSetterComponent />
+        </ThinkingProvider>
+      ),
+    });
+
+    const button = await view.findByTestId("set-thinking-medium");
+    act(() => {
+      button.click();
+    });
+
+    await waitFor(() => {
+      expect(updateAgentAISettings).toHaveBeenCalledWith({
+        workspaceId,
+        agentId: "exec",
+        aiSettings: { model: "metadataModel:abc", thinkingLevel: "medium" },
+      });
+    });
+  });
+
+  test("uses metadata thinking before off but keeps explicit thinking", async () => {
+    const cases = [
+      {
+        workspaceId: "ws-thinking-metadata",
+        override: null,
+        expected: "high:ws-thinking-metadata",
+      },
+      {
+        workspaceId: "ws-thinking-explicit",
+        override: "off" as const,
+        expected: "off:ws-thinking-explicit",
+      },
+    ];
+
+    for (const testCase of cases) {
+      const metadata = createWorkspaceMetadata({
+        id: testCase.workspaceId,
+        aiSettings: { model: "openai:gpt-5.5", thinkingLevel: "high" },
+      });
+      setWorkspaceMetadata(metadata);
+
+      const view = renderWithWorkspaceMetadata({
+        workspaceId: testCase.workspaceId,
+        thinkingOverride: testCase.override,
+        children: (
+          <ThinkingProvider workspaceId={testCase.workspaceId}>
+            <TestComponent workspaceId={testCase.workspaceId} />
+          </ThinkingProvider>
+        ),
+      });
+
+      await waitFor(() => {
+        expect(view.getByTestId("thinking").textContent).toBe(testCase.expected);
+      });
+      cleanup();
+    }
+  });
+
   test("switching models does not remount children", async () => {
     const workspaceId = "ws-1";