fix: persisted options keep their full shape, and every legacy snapshot gains controls

Draft setups and form preferences validated option values as booleans,
strings or null, but the options they now receive come from agents and
profiles and can be objects, arrays or numbers. One such value failed
validation and wiped the whole saved layout or the saved preferences. Both
schemas now accept any JSON value.

The legacy-daemon translation skipped the snapshots carried by
agent_created, agent_resumed and timeline responses, so a created agent or
a timeline refresh left the SDK handle without options and controls.

The profile journey asserted the create request's options field; the wire
field is providerOptions.

docs/providers.md

@@ -30,6 +30,65 @@ at session startup. See [provider configuration](custom-providers.md#provider-op
 for defaults and merge rules, and the [SDK guide](../public-docs/sdk/provider-options.md)
 for native keys and examples.
 
+### Options flow
+
+`options` on the agent snapshot is the only option state. Controls describe how to draw an
+option and read `options`; they hold no value of their own. Any option can be read and set with
+or without a control.
+
+- **Create and resume.** The provider opens with the options it is given and emits nothing about
+  them while opening. `openOptionsPatch` carries every option the session ended up with that
+  differs from what it was given, including a setting nobody asked for (a native default such as
+  Cursor opening with Fast on). It is set before `createSession`/`resumeSession` resolves and the
+  daemon stores it before the agent is published. A reopened agent resumes that state, so a
+  native default the provider later changes does not follow. `options` on the snapshot is what
+  the session opened with, and afterwards it moves only through an apply or an `options_changed`.
+  Editing a provider default in `config.json` affects agents the next time they open.
+- **Live apply.** `applyOptions` receives the keys the patch touches, resolved against the
+  `config.json` defaults. A removal arrives as the default the key falls back to, or `null` when
+  there is none; the provider returns the setting to its own default if it can, or throws to
+  reject. A key the running session cannot apply (one the provider reads only when it opens) is
+  rejected too, so a stored option always describes what runs. Claude reads most options when it
+  starts its query, and replacing a started query would end its background work, so after the
+  first prompt only Fast can change. Codex fixes its approval policy and sandbox when the thread
+  starts, so it applies only `service_tier` and `plan_mode` live. A session with no
+  `applyOptions` rejects every patch; the daemon enforces this. The provider returns the options
+  it ended up with when they differ from the request. The daemon
+  stores the patch and that result in one step after the call resolves, onto the agent's options
+  as they are at that moment, so the last write wins. Throwing rejects the whole patch and
+  none of it is stored. Emit nothing from inside the call. If the provider's own state moved
+  before it refused, it reports the moved values once as `options_changed` after the call has
+  ended, because the stored options must match what runs.
+- **Old data converts in the agent manager.** Codex used to take `fast_mode`; it takes
+  `service_tier` now. `AgentManager` runs `convertLegacyOptions` (`option-controls.ts`) on an
+  agent's own options when it creates, resumes, imports, reloads or applies to it, and on draft
+  controls, before defaults merge and before anything is stored (`true` is `"fast"`, `false` is
+  `"default"`, and a `service_tier` in the same input wins). The manager converts for the adapter
+  behind the provider id, following `derivedFromProviderId`, so a custom provider with
+  `extends: "codex"` is converted too. Configured defaults convert in the provider registry. A
+  stored record keeps `fast_mode` until the agent is next opened or applied to, and is stored
+  converted from then on. Nothing past the manager sees `fast_mode` for Codex. Codex resolves
+  `"fast"` to the model's Fast tier and reports the id it runs through `openOptionsPatch` or the
+  `applyOptions` result like any other value. The `featureValues` to `options` fold is separate
+  and provider-agnostic; it stays at the protocol and legacy edges.
+- **Clients draw from the daemon's answer.** The app reads `controls` and `options` from the
+  agent snapshot for a running or closed agent. A draft and a profile form send everything they
+  would create with (seed, the provider's last-used control values once the provider has said it
+  still draws them, and the user's edits) in `provider.controls.list.request` and draw only what
+  comes back, so an alias such as a legacy Fast profile's `service_tier: "fast"` is resolved once,
+  by the daemon. A toggle shows over the last answer until its own answer arrives. The draft's
+  layers live in a plain model (`agent-controls/draft-options-model.ts`): applying a profile
+  replaces provider and options in one step, while choosing a provider by hand starts over. A
+  profile saves its stored options plus the form's edits, so options no control draws survive an
+  edit. A daemon without `server_info.features.providerOptionControls` sends `features` and
+  `featureValues`; `packages/client/src/compat/legacy-provider-options.ts` is the one place that
+  turns those into `controls` and `options` and back, so nothing in the app branches on it. A
+  create that carries options first lists the controls for its own provider, model, mode and
+  thinking level, since which options are controls differs by model, and sends those as
+  `featureValues`; callers do not prime anything.
+- **Provider-initiated changes.** A setting the provider changes on its own is an
+  `options_changed` event. The daemon stores and forwards it and does not push the old value back.
+
 Exact MCP preapproval is a separate daemon-owned contract. A new provider must fail
 closed for Hub unattended execution until it can approve one exact injected MCP
 server and tool identity without approving native tools.
@@ -115,7 +174,7 @@ Submitted user-message wire items carry the same Paseo ID in `messageId` and `cl
 
 Provider adapters must terminalize every transient timeline row before emitting the turn's terminal event. Codex may omit the completed `contextCompaction` item when a turn ends during compaction, so its adapter closes any pending root compaction before forwarding `turn_completed`, `turn_failed`, or `turn_canceled`. A terminal turn must never leave the client showing an operation as still loading.
 
-Draft metadata lookups should avoid creating provider sessions when the upstream provider has top-level APIs for that metadata. Prefer `AgentClient.fetchCatalog`, `listCommands`, or `listFeatures` over creating a scratch `AgentSession`; scratch sessions can show up as empty native sessions in provider import/history UIs. `fetchCatalog` is the single discovery API for models and modes — provider implementations may use one process, separate upstream calls, or static data internally, but callers outside the provider do not get separate runtime model/mode probes. Draft command listing and scratch-session feature listing require an explicit draft model. Do not resolve a default model through catalog discovery. A client-level `listFeatures` implementation may return features from an incomplete, model-less draft and owns which features are valid in that state.
+Draft metadata lookups should avoid creating provider sessions when the upstream provider has top-level APIs for that metadata. Prefer `AgentClient.fetchCatalog`, `listCommands`, or `listControls` over creating a scratch `AgentSession`; scratch sessions can show up as empty native sessions in provider import/history UIs. `fetchCatalog` is the single discovery API for models and modes — provider implementations may use one process, separate upstream calls, or static data internally, but callers outside the provider do not get separate runtime model/mode probes. Draft command listing and scratch-session control listing require an explicit draft model. Do not resolve a default model through catalog discovery. A client-level `listControls` implementation may return controls from an incomplete, model-less draft and owns which features are valid in that state.
 
 Provider session import has its own contract. The picker calls `listImportableSessions` and receives rows only: provider handle, cwd, title, prompt previews, and last activity. Import calls `importSession({ providerHandleId, cwd })` for the selected row and must not call listing again. The provider returns the resumed session, storage config, persistence handle, and hydrated timeline for that one native session; `AgentManager.importProviderSession` seeds the daemon timeline and publishes the Paseo agent only after it is ready.
 
@@ -478,7 +537,7 @@ interface AgentSession {
   readonly provider: AgentProvider;
   readonly id: string | null;
   readonly capabilities: AgentCapabilityFlags;
-  readonly features?: AgentFeature[];
+  readonly controls?: AgentOptionControl[];
   run(prompt: AgentPromptInput, options?: AgentRunOptions): Promise<AgentRunResult>;
   startTurn(prompt: AgentPromptInput, options?: AgentRunOptions): Promise<{ turnId: string }>;
   steerActiveTurn?(prompt: AgentPromptInput, options: SteerActiveTurnOptions): Promise<SteerResult>;
@@ -500,7 +559,7 @@ interface AgentSession {
   listCommands?(): Promise<AgentSlashCommand[]>;
   setModel?(modelId: string | null): Promise<void>;
   setThinkingOption?(thinkingOptionId: string | null): Promise<void | AgentProviderNotice>;
-  setFeature?(featureId: string, value: unknown): Promise<void>;
+  applyOptions?(options: ProviderOptions): Promise<void>;
   tryHandleOutOfBand?(prompt: AgentPromptInput): {
     run(ctx: { emit: (event: AgentStreamEvent) => void }): Promise<void>;
   } | null;

packages/app/e2e/browser/agent-profile-modeless-preferences.spec.ts

@@ -62,7 +62,7 @@ async function readProviderFeaturePreferences(page: Page, provider: string): Pro
       const raw = localStorage.getItem(preferencesKey);
       if (!raw) return null;
       const preferences = JSON.parse(raw) as FormPreferences;
-      return preferences.providerPreferences?.[providerId]?.featureValues ?? null;
+      return preferences.providerPreferences?.[providerId]?.options ?? null;
     },
     { preferencesKey: CREATE_AGENT_PREFERENCES_KEY, providerId: provider },
   );
@@ -145,7 +145,7 @@ test.describe("Agent profiles repair modeless provider preferences", () => {
         provider: featureProviderId,
         model: featureModelId,
         modeId: "bypassPermissions",
-        featureValues: { fast_mode: true },
+        options: { fast_mode: true },
       },
     ]);
     const provider = await seedModelProvider({
@@ -181,7 +181,7 @@ test.describe("Agent profiles repair modeless provider preferences", () => {
       expect(createAgentRequest).toMatchObject({
         config: {
           provider: featureProviderId,
-          featureValues: { fast_mode: true },
+          providerOptions: { fast_mode: true },
         },
       });
     } finally {

packages/app/src/agent-commands/cache/index.ts

@@ -18,7 +18,7 @@ export interface AgentCommandsDraftConfig {
   modeId?: string;
   model?: string;
   thinkingOptionId?: string;
-  featureValues?: Record<string, unknown>;
+  providerOptions?: Record<string, unknown>;
 }
 
 export function normalizeAgentCommandsCwd(cwd: string): string {
@@ -98,7 +98,7 @@ export function draftAgentCommandsQueryKey(input: {
     "thinking",
     draftConfig.thinkingOptionId ?? null,
     "features",
-    draftConfig.featureValues ?? null,
+    draftConfig.providerOptions ?? null,
   ] as const;
 }
 

packages/app/src/agent-controls/draft-options-model.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it } from "vitest";
+import type { AgentOptionControl } from "@getpaseo/protocol/agent-types";
+import { isControlActive } from "./option-controls";
+import {
+  draftControlsRequest,
+  openDraftOptions,
+  ownDraftOptions,
+  viewDraftOptions,
+} from "./draft-options-model";
+
+const SPEED: AgentOptionControl = {
+  type: "select",
+  key: "service_tier",
+  label: "Speed",
+  defaultValue: "default",
+  choices: [
+    { value: "default", label: "Standard" },
+    { value: "priority", label: "Fast" },
+  ],
+};
+const WEB_SEARCH: AgentOptionControl = { type: "toggle", key: "web_search", label: "Web search" };
+
+function answer(
+  provider: string,
+  requestKey: string,
+  options: Record<string, unknown>,
+  controls = [SPEED, WEB_SEARCH],
+) {
+  return { provider, requestKey, controls, options };
+}
+
+describe("draft options model", () => {
+  it("draws a legacy Fast profile as the Fast tier the daemon resolved", () => {
+    const model = openDraftOptions({ provider: "codex", seed: { service_tier: "fast" } });
+    model.applyResolved(answer("codex", "k1", { service_tier: "priority" }));
+
+    const view = viewDraftOptions(model.getState(), { provider: "codex", requestKey: "k1" });
+
+    expect(view?.options).toEqual({ service_tier: "priority" });
+    expect(view && isControlActive(SPEED, view.options)).toBe(true);
+    // The daemon still gets the stored value to resolve, and so does create.
+    expect(ownDraftOptions(model.getState())).toEqual({ service_tier: "fast" });
+  });
+
+  it("applying a profile from another provider keeps its options through the provider change", () => {
+    const model = openDraftOptions({ provider: "claude" });
+    model.applyResolved(answer("claude", "k1", {}));
+
+    model.applyProfile({
+      provider: "codex",
+      options: { sandbox_mode: "read-only", service_tier: "fast" },
+    });
+    // The form follows the profile to its provider.
+    model.observeProvider("codex");
+
+    expect(ownDraftOptions(model.getState())).toEqual({
+      sandbox_mode: "read-only",
+      service_tier: "fast",
+    });
+    expect(model.getState().resolved).toBeNull();
+  });
+
+  it("choosing another provider by hand starts the options over", () => {
+    const model = openDraftOptions({ provider: "codex", seed: { sandbox_mode: "read-only" } });
+    model.setOption("web_search", true);
+
+    model.observeProvider("claude");
+
+    expect(ownDraftOptions(model.getState())).toBeUndefined();
+    expect(model.getState().resolved).toBeNull();
+  });
+
+  it("never pairs a manually chosen provider with the previous provider's options", () => {
+    const model = openDraftOptions({ provider: "claude" });
+    model.applyResolved(answer("claude", "k1", { fast_mode: true }));
+    model.setOption("fast_mode", true);
+    const form = { provider: "claude", cwd: "/repo" };
+    expect(draftControlsRequest(model.getState(), form)).toMatchObject({
+      provider: "claude",
+      providerOptions: { fast_mode: true },
+    });
+
+    // The form shows OpenCode on its next render; the model has not observed it yet.
+    expect(draftControlsRequest(model.getState(), { ...form, provider: "opencode" })).toBeNull();
+
+    model.observeProvider("opencode");
+    const request = draftControlsRequest(model.getState(), { ...form, provider: "opencode" });
+    expect(request).toEqual({ provider: "opencode", cwd: "/repo" });
+  });
+
+  it("keeps a draft's seed when the first provider is chosen", () => {
+    const model = openDraftOptions({ provider: null, seed: { web_search: true } });
+
+    model.observeProvider("claude");
+
+    expect(ownDraftOptions(model.getState())).toEqual({ web_search: true });
+  });
+
+  it("sends a remembered value to the daemon, and draws only what comes back", () => {
+    const model = openDraftOptions({ provider: "codex" });
+    model.setRemembered({ service_tier: "fast", retired: true });
+    // Nothing is known about the provider's controls yet.
+    expect(ownDraftOptions(model.getState())).toBeUndefined();
+
+    model.applyResolved(answer("codex", "k1", { service_tier: "default" }));
+    expect(ownDraftOptions(model.getState())).toEqual({ service_tier: "fast" });
+    // The answer to the first request does not show the remembered value as if it applied.
+    expect(
+      viewDraftOptions(model.getState(), { provider: "codex", requestKey: "k2" })?.options,
+    ).toEqual({ service_tier: "default" });
+
+    model.applyResolved(answer("codex", "k2", { service_tier: "priority" }));
+    expect(
+      viewDraftOptions(model.getState(), { provider: "codex", requestKey: "k2" })?.options,
+    ).toEqual({ service_tier: "priority" });
+  });
+
+  it("does not let a remembered value override the seed", () => {
+    const model = openDraftOptions({ provider: "codex", seed: { service_tier: "default" } });
+    model.applyResolved(answer("codex", "k1", { service_tier: "default" }));
+    model.setRemembered({ service_tier: "fast" });
+
+    expect(ownDraftOptions(model.getState())).toEqual({ service_tier: "default" });
+  });
+
+  it("lays a toggle over the previous answer until the new one arrives", () => {
+    const model = openDraftOptions({ provider: "claude" });
+    model.applyResolved(answer("claude", "k1", { web_search: false }));
+
+    model.setOption("web_search", true);
+
+    expect(
+      viewDraftOptions(model.getState(), { provider: "claude", requestKey: "k2" })?.options,
+    ).toEqual({ web_search: true });
+    model.applyResolved(answer("claude", "k2", { web_search: true }));
+    expect(
+      viewDraftOptions(model.getState(), { provider: "claude", requestKey: "k2" })?.options,
+    ).toEqual({ web_search: true });
+  });
+
+  it("draws nothing for a provider the answer is not for", () => {
+    const model = openDraftOptions({ provider: "claude" });
+    model.applyResolved(answer("claude", "k1", {}));
+
+    expect(viewDraftOptions(model.getState(), { provider: "codex", requestKey: "k1" })).toBe(
+      undefined,
+    );
+  });
+});

packages/app/src/agent-controls/draft-options-model.ts

@@ -0,0 +1,168 @@
+import type {
+  AgentOptionControl,
+  AgentSessionConfig,
+  ProviderOptions,
+} from "@getpaseo/protocol/agent-types";
+
+/**
+ * The options of one draft agent, as a plain model (see docs/forms.md). It owns which layers
+ * make up the draft's options; the daemon owns what they mean. Every layer is sent to the daemon
+ * (`ownDraftOptions`) and the UI draws what comes back (`viewDraftOptions`), so no alias,
+ * default or legacy key is resolved here.
+ *
+ * - `seed`: options the draft started from (a profile, a forked agent).
+ * - `remembered`: the provider's last-used control values.
+ * - `edits`: toggles made in this draft.
+ *
+ * Choosing a provider by hand starts the options over; applying a profile replaces the provider
+ * and the options in one step, so the provider change that follows does not clear them.
+ */
+export interface ResolvedDraftOptions {
+  provider: string;
+  /** Names the request that produced this answer; see `viewDraftOptions`. */
+  requestKey: string;
+  controls: AgentOptionControl[];
+  options: ProviderOptions;
+}
+
+export interface DraftOptionsState {
+  provider: string | null;
+  seed: ProviderOptions;
+  remembered: ProviderOptions;
+  edits: ProviderOptions;
+  resolved: ResolvedDraftOptions | null;
+}
+
+export interface DraftOptionsModel {
+  getState: () => DraftOptionsState;
+  subscribe: (listener: () => void) => () => void;
+  /** The provider the draft's form now has. A different one than the model's is a manual choice. */
+  observeProvider: (provider: string | null) => void;
+  applyProfile: (profile: { provider: string; options: ProviderOptions }) => void;
+  setRemembered: (remembered: ProviderOptions) => void;
+  setOption: (key: string, value: unknown) => void;
+  applyResolved: (resolved: ResolvedDraftOptions) => void;
+}
+
+export function openDraftOptions(input: {
+  provider: string | null;
+  seed?: ProviderOptions;
+}): DraftOptionsModel {
+  let state: DraftOptionsState = {
+    provider: input.provider,
+    seed: input.seed ?? {},
+    remembered: {},
+    edits: {},
+    resolved: null,
+  };
+  const listeners = new Set<() => void>();
+
+  function publish(update: (current: DraftOptionsState) => DraftOptionsState): void {
+    const next = update(state);
+    if (next === state) return;
+    state = next;
+    for (const listener of listeners) listener();
+  }
+
+  return {
+    getState: () => state,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    observeProvider: (provider) =>
+      publish((current) => {
+        if (provider === current.provider) return current;
+        // The first provider a draft picks does not discard what it was opened with.
+        if (current.provider === null) return { ...current, provider };
+        return { ...current, provider, seed: {}, edits: {}, resolved: null };
+      }),
+    applyProfile: (profile) =>
+      publish((current) => ({
+        ...current,
+        provider: profile.provider,
+        seed: profile.options,
+        edits: {},
+        resolved: current.provider === profile.provider ? current.resolved : null,
+      })),
+    setRemembered: (remembered) => publish((current) => ({ ...current, remembered })),
+    setOption: (key, value) =>
+      publish((current) =>
+        Object.is(current.edits[key], value)
+          ? current
+          : { ...current, edits: { ...current.edits, [key]: value } },
+      ),
+    applyResolved: (resolved) => publish((current) => ({ ...current, resolved })),
+  };
+}
+
+/**
+ * Everything the draft would create with, for the daemon to resolve. A last-used value applies
+ * once the provider has told us it still draws a control for that key, and never over the seed.
+ */
+export function ownDraftOptions(state: DraftOptionsState): ProviderOptions | undefined {
+  const controlKeys = new Set((state.resolved?.controls ?? []).map((control) => control.key));
+  const remembered = Object.fromEntries(
+    Object.entries(state.remembered).filter(
+      ([key]) => controlKeys.has(key) && !(key in state.seed),
+    ),
+  );
+  const own = { ...state.seed, ...remembered, ...state.edits };
+  return Object.keys(own).length > 0 ? own : undefined;
+}
+
+export type DraftControlsRequest = Pick<
+  AgentSessionConfig,
+  "provider" | "cwd" | "modeId" | "model" | "thinkingOptionId" | "providerOptions"
+>;
+
+/**
+ * The listing request for the draft's form, built from one snapshot of the model. The form
+ * reaches a new provider before the model has observed it, and the model still holds the
+ * previous provider's options until it does; that render has no request, so a request never
+ * pairs one provider with another's options.
+ */
+export function draftControlsRequest(
+  state: DraftOptionsState,
+  form: {
+    provider: string | null;
+    cwd: string;
+    modeId?: string | null;
+    modelId?: string | null;
+    thinkingOptionId?: string | null;
+  },
+): DraftControlsRequest | null {
+  if (!form.provider || !form.cwd || form.provider !== state.provider) return null;
+  const providerOptions = ownDraftOptions(state);
+  return {
+    provider: form.provider,
+    cwd: form.cwd,
+    ...(form.modeId ? { modeId: form.modeId } : {}),
+    ...(form.modelId ? { model: form.modelId } : {}),
+    ...(form.thinkingOptionId ? { thinkingOptionId: form.thinkingOptionId } : {}),
+    ...(providerOptions ? { providerOptions } : {}),
+  };
+}
+
+/**
+ * What the controls draw: the daemon's answer for this provider. The last answer stays up while
+ * a newer request is in flight, with the toggles made since laid over it, so a switch does not
+ * wait for the round trip. It never carries a seed or remembered value the daemon has not
+ * resolved.
+ */
+export function viewDraftOptions(
+  state: DraftOptionsState,
+  current: { provider: string | null; requestKey: string },
+): { controls: AgentOptionControl[]; options: ProviderOptions } | undefined {
+  const { resolved } = state;
+  if (!resolved || resolved.provider !== current.provider) return undefined;
+  return {
+    controls: resolved.controls,
+    options:
+      resolved.requestKey === current.requestKey
+        ? resolved.options
+        : { ...resolved.options, ...state.edits },
+  };
+}

packages/app/src/agent-controls/option-controls.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import type { AgentOptionControl } from "@getpaseo/protocol/agent-types";
+import {
+  getControlTooltip,
+  isControlActive,
+  readSelectOption,
+  readToggleOption,
+} from "./option-controls";
+
+const speed: AgentOptionControl = {
+  type: "select",
+  key: "service_tier",
+  label: "Speed",
+  defaultValue: "default",
+  choices: [
+    { value: "default", label: "Normal" },
+    { value: "priority", label: "Fast" },
+  ],
+};
+const fast: AgentOptionControl = { type: "toggle", key: "fast_mode", label: "Fast" };
+
+describe("option controls", () => {
+  it("reads a select from options and falls back to the control's default", () => {
+    if (speed.type !== "select") throw new Error("select expected");
+    expect(readSelectOption(speed, { service_tier: "priority" })).toBe("priority");
+    expect(readSelectOption(speed, {})).toBe("default");
+    expect(readSelectOption(speed, { service_tier: "unknown-tier" })).toBe("default");
+  });
+
+  it("reads a toggle from options and is off when unset", () => {
+    if (fast.type !== "toggle") throw new Error("toggle expected");
+    expect(readToggleOption(fast, { fast_mode: true })).toBe(true);
+    expect(readToggleOption(fast, {})).toBe(false);
+  });
+
+  it("is active when the option differs from the control's default", () => {
+    expect(isControlActive(speed, { service_tier: "priority" })).toBe(true);
+    expect(isControlActive(speed, { service_tier: "default" })).toBe(false);
+    expect(isControlActive(speed, {})).toBe(false);
+    expect(isControlActive(fast, { fast_mode: true })).toBe(true);
+    expect(isControlActive(fast, {})).toBe(false);
+  });
+
+  it("prefers a control's tooltip over its label", () => {
+    expect(getControlTooltip({ label: "Plan", tooltip: "Toggle plan mode" })).toBe(
+      "Toggle plan mode",
+    );
+    expect(getControlTooltip({ label: "Custom" })).toBe("Custom");
+  });
+});

packages/app/src/agent-controls/option-controls.ts

@@ -0,0 +1,47 @@
+import type {
+  AgentOptionControl,
+  AgentOptionSelectControl,
+  AgentOptionToggleControl,
+  ProviderOptions,
+} from "@getpaseo/protocol/agent-types";
+
+/**
+ * The composer's option controls. A control only describes how to draw one option key; the
+ * value is read from `options`, which the daemon resolved (defaults, aliases, what runs).
+ */
+export interface ComposerOptionControls {
+  controls: AgentOptionControl[];
+  options: ProviderOptions;
+  onSetOption: (key: string, value: unknown) => void;
+}
+
+export function readToggleOption(
+  control: AgentOptionToggleControl,
+  options: ProviderOptions,
+): boolean {
+  const value = options[control.key];
+  return typeof value === "boolean" ? value : (control.defaultValue ?? false);
+}
+
+/** The selected choice's value, or the control's default when the option names no choice. */
+export function readSelectOption(
+  control: AgentOptionSelectControl,
+  options: ProviderOptions,
+): string | null {
+  const value = options[control.key];
+  if (typeof value === "string" && control.choices.some((choice) => choice.value === value)) {
+    return value;
+  }
+  return control.defaultValue ?? null;
+}
+
+/** Whether the option is set to something other than the control's default. */
+export function isControlActive(control: AgentOptionControl, options: ProviderOptions): boolean {
+  if (control.type === "toggle") return readToggleOption(control, options);
+  const value = readSelectOption(control, options);
+  return value !== null && value !== control.defaultValue;
+}
+
+export function getControlTooltip(control: Pick<AgentOptionControl, "label" | "tooltip">): string {
+  return control.tooltip ?? control.label;
+}

packages/app/src/agent-profiles/internal/materialize-profile.test.ts

@@ -23,7 +23,7 @@ describe("materializeAgentProfile", () => {
           model: "claude-opus-5",
           modeId: "plan",
           thinkingOptionId: "think-hard",
-          featureValues: { web_search: true },
+          options: { web_search: true },
         }),
       ),
     ).toEqual({
@@ -31,7 +31,7 @@ describe("materializeAgentProfile", () => {
       modelId: "claude-opus-5",
       modeId: "plan",
       thinkingOptionId: "think-hard",
-      featureValues: { web_search: true },
+      options: { web_search: true },
     });
   });
 
@@ -41,7 +41,7 @@ describe("materializeAgentProfile", () => {
       modelId: "",
       modeId: "",
       thinkingOptionId: "",
-      featureValues: {},
+      options: {},
     });
   });
 
@@ -61,7 +61,7 @@ describe("toAgentConfigApply", () => {
             model: "claude-opus-5",
             modeId: "plan",
             thinkingOptionId: "think-hard",
-            featureValues: { web_search: true },
+            options: { web_search: true },
           }),
         ),
       ),
@@ -69,7 +69,7 @@ describe("toAgentConfigApply", () => {
       modelId: "claude-opus-5",
       modeId: "plan",
       thinkingOptionId: "think-hard",
-      featureValues: { web_search: true },
+      options: { web_search: true },
     });
   });
 
@@ -81,8 +81,8 @@ describe("toAgentConfigApply", () => {
 
   it("omits an empty feature map so the agent keeps its own feature values", () => {
     expect(
-      toAgentConfigApply(materializeAgentProfile(profile({ featureValues: {} }))),
+      toAgentConfigApply(materializeAgentProfile(profile({ options: {} }))),
-    ).not.toHaveProperty("featureValues");
+    ).not.toHaveProperty("options");
   });
 
   it("never carries a provider, which a running agent cannot change", () => {

packages/app/src/agent-profiles/internal/materialize-profile.ts

@@ -12,7 +12,7 @@ export interface MaterializedAgentProfile {
   modelId: string;
   modeId: string;
   thinkingOptionId: string;
-  featureValues: Record<string, unknown>;
+  options: Record<string, unknown>;
 }
 
 function trimmed(value: string | undefined): string {
@@ -25,7 +25,7 @@ export function materializeAgentProfile(profile: AgentProfile): MaterializedAgen
     modelId: trimmed(profile.model),
     modeId: trimmed(profile.modeId),
     thinkingOptionId: trimmed(profile.thinkingOptionId),
-    featureValues: profile.featureValues ?? {},
+    options: profile.options ?? {},
   };
 }
 
@@ -52,8 +52,6 @@ export function toAgentConfigApply(profile: MaterializedAgentProfile): AgentConf
     ...(profile.modelId ? { modelId: profile.modelId } : {}),
     ...(profile.modeId ? { modeId: profile.modeId } : {}),
     ...(profile.thinkingOptionId ? { thinkingOptionId: profile.thinkingOptionId } : {}),
-    ...(Object.keys(profile.featureValues).length > 0
+    ...(Object.keys(profile.options).length > 0 ? { options: profile.options } : {}),
-      ? { featureValues: profile.featureValues }
-      : {}),
   };
 }

packages/app/src/agent-profiles/internal/profile-form-model.test.ts

@@ -1,7 +1,7 @@
 import type { ProviderSnapshotEntry } from "@getpaseo/protocol/agent-types";
 import { describe, expect, it } from "vitest";
 import {
-  buildFeatureRequestKey,
+  buildControlsRequestKey,
   openAgentProfileForm,
   type AgentProfileFormModel,
 } from "./profile-form-model";
@@ -173,7 +173,7 @@ describe("openAgentProfileForm", () => {
         model: "claude-opus-5",
         modeId: "plan",
         thinkingOptionId: "think-hard",
-        featureValues: { webSearch: true },
+        options: { webSearch: true },
         notes: "Visual work only.",
       },
     });
@@ -229,10 +229,11 @@ describe("openAgentProfileForm", () => {
       selectClaude(model);
       model.setModel("claude-opus-5", { label: "Opus 5" });
       model.setThinking("think-hard", { label: "Think hard" });
-      model.applyFeatures(model.getState().featureRequestKey ?? "", [
+      model.applyControls(model.getState().controlsRequestKey ?? "", {
-        { type: "toggle", id: "webSearch", label: "Web search", value: false },
+        controls: [{ type: "toggle", key: "webSearch", label: "Web search" }],
-      ]);
+        options: { webSearch: false },
-      model.setFeatureValue("webSearch", true);
+      });
+      model.setOption("webSearch", true);
 
       model.setProvider("codex", { label: "Codex" });
       const state = model.getState();
@@ -242,8 +243,9 @@ describe("openAgentProfileForm", () => {
       expect(state.modelDisplay).toEqual({ label: "GPT-5.2 Codex" });
       expect(state.thinkingOptionId).toBe("");
       expect(state.thinkingDisplay).toBeNull();
-      expect(state.featureValues).toEqual({});
+      expect(state.options).toEqual({});
-      expect(state.features).toEqual([]);
+      expect(state.optionEdits).toEqual({});
+      expect(state.controls).toEqual([]);
       expect(state.name).toBe("Test writer");
     });
 
@@ -334,23 +336,28 @@ describe("openAgentProfileForm", () => {
     });
   });
 
-  describe("features", () => {
+  const WEB_SEARCH_CONTROLS = {
-    it("asks for features per provider/model/mode/thinking combination", () => {
+    controls: [{ type: "toggle" as const, key: "webSearch", label: "Web search" }],
+    options: { webSearch: false },
+  };
+
+  describe("controls", () => {
+    it("asks for controls per provider/model/mode/thinking combination", () => {
       const model = openWithCatalog({ mode: "create" });
       selectClaude(model);
 
-      expect(model.getState().featureRequest).toEqual({
+      expect(model.getState().controlsRequest).toEqual({
         provider: "claude",
         model: "claude-opus-5",
         modeId: "plan",
         thinkingOptionId: "think",
       });
-      const firstKey = model.getState().featureRequestKey;
+      const firstKey = model.getState().controlsRequestKey;
 
       model.setModel("claude-haiku-4-5", { label: "Haiku 4.5" });
 
-      expect(model.getState().featureRequestKey).not.toBe(firstKey);
+      expect(model.getState().controlsRequestKey).not.toBe(firstKey);
-      expect(model.getState().featureRequest).toEqual({
+      expect(model.getState().controlsRequest).toEqual({
         provider: "claude",
         model: "claude-haiku-4-5",
         modeId: "plan",
@@ -361,77 +368,168 @@ describe("openAgentProfileForm", () => {
     it("moves from pending to complete only for the current request", () => {
       const model = openWithCatalog({ mode: "create" });
       selectClaude(model);
-      const key = model.getState().featureRequestKey ?? "";
+      const key = model.getState().controlsRequestKey ?? "";
-      expect(model.getState().featureResolution).toBe("pending");
+      expect(model.getState().controlsResolution).toBe("pending");
 
-      model.applyFeatures("stale-key", [
+      model.applyControls("stale-key", {
-        { type: "toggle", id: "webSearch", label: "Web search", value: false },
+        controls: [{ type: "toggle", key: "webSearch", label: "Web search" }],
-      ]);
+        options: { webSearch: false },
-      expect(model.getState().featureResolution).toBe("pending");
+      });
-      expect(model.getState().features).toEqual([]);
+      expect(model.getState().controlsResolution).toBe("pending");
+      expect(model.getState().controls).toEqual([]);
 
-      model.applyFeatures(key, [
+      model.applyControls(key, {
-        { type: "toggle", id: "webSearch", label: "Web search", value: false },
+        controls: [{ type: "toggle", key: "webSearch", label: "Web search" }],
-      ]);
+        options: { webSearch: false },
-      expect(model.getState().featureResolution).toBe("complete");
+      });
-      expect(model.getState().disclosure.showFeaturesField).toBe(true);
+      expect(model.getState().controlsResolution).toBe("complete");
+      expect(model.getState().disclosure.showControlsField).toBe(true);
     });
 
-    it("reflects a set feature value back into the rendered feature", () => {
+    it("reflects a set option back into the rendered controls", () => {
+      const model = openWithCatalog({ mode: "create" });
+      model.setName("Searcher");
+      selectClaude(model);
+      model.applyControls(model.getState().controlsRequestKey ?? "", WEB_SEARCH_CONTROLS);
+
+      model.setOption("webSearch", true);
+
+      expect(model.getState().controls[0]).toMatchObject({ key: "webSearch" });
+      expect(model.getState().controlOptions).toEqual({ webSearch: true });
+      expect(model.getState().submitValue?.options).toEqual({ webSearch: true });
+    });
+
+    it("keeps stored options while the controls are still pending", () => {
+      const model = openAgentProfileForm({
+        mode: "edit",
+        profile: { id: "p1", name: "UI work", provider: "claude", options: { webSearch: true } },
+      });
+      model.applyProviderCatalog(ENTRIES);
+
+      expect(model.getState().controlsResolution).toBe("pending");
+      expect(model.getState().submitValue?.options).toEqual({ webSearch: true });
+    });
+
+    it("keeps options no control draws, so editing a profile does not drop them", () => {
+      const model = openAgentProfileForm({
+        mode: "edit",
+        profile: {
+          id: "p1",
+          name: "UI work",
+          provider: "claude",
+          options: { webSearch: true, sandbox_mode: "read-only" },
+        },
+      });
+      model.applyProviderCatalog(ENTRIES);
+      model.applyControls(model.getState().controlsRequestKey ?? "", WEB_SEARCH_CONTROLS);
+      model.setOption("webSearch", false);
+
+      expect(model.getState().submitValue?.options).toEqual({
+        webSearch: false,
+        sandbox_mode: "read-only",
+      });
+    });
+
+    it("draws the options the daemon resolved from the stored ones, then the edits", () => {
+      const model = openAgentProfileForm({
+        mode: "edit",
+        profile: { id: "p1", name: "Fast", provider: "codex", options: { service_tier: "fast" } },
+      });
+      model.applyProviderCatalog(ENTRIES);
+
+      // The request carries the stored options so the daemon can resolve the legacy tier.
+      expect(model.getState().controlsRequest?.providerOptions).toEqual({ service_tier: "fast" });
+
+      model.applyControls(model.getState().controlsRequestKey ?? "", {
+        controls: [
+          {
+            type: "select",
+            key: "service_tier",
+            label: "Speed",
+            defaultValue: "default",
+            choices: [
+              { value: "default", label: "Standard" },
+              { value: "priority", label: "Fast" },
+            ],
+          },
+        ],
+        options: { service_tier: "priority" },
+      });
+
+      expect(model.getState().controlOptions).toEqual({ service_tier: "priority" });
+      // Nothing was edited, so the stored value is saved as it was.
+      expect(model.getState().submitValue?.options).toEqual({ service_tier: "fast" });
+    });
+
+    it("sends an edit to the daemon with the stored options, and draws the answer", () => {
+      const model = openAgentProfileForm({
+        mode: "edit",
+        profile: {
+          id: "p1",
+          name: "Fast",
+          provider: "codex",
+          options: { service_tier: "fast", sandbox_mode: "read-only" },
+        },
+      });
+      model.applyProviderCatalog(ENTRIES);
+      const speed = {
+        controls: [
+          {
+            type: "select" as const,
+            key: "service_tier",
+            label: "Speed",
+            defaultValue: "default",
+            choices: [
+              { value: "default", label: "Standard" },
+              { value: "priority", label: "Fast" },
+            ],
+          },
+        ],
+        options: { service_tier: "priority", sandbox_mode: "read-only" },
+      };
+      model.applyControls(model.getState().controlsRequestKey ?? "", speed);
+
+      model.setOption("service_tier", "default");
+
+      // The controls stay up while the daemon answers, with the toggle laid over the last answer.
+      expect(model.getState().controls).toHaveLength(1);
+      expect(model.getState().controlOptions).toMatchObject({ service_tier: "default" });
+      // The request carries everything the profile would save, so the daemon resolves it.
+      expect(model.getState().controlsRequest?.providerOptions).toEqual({
+        service_tier: "default",
+        sandbox_mode: "read-only",
+      });
+      expect(model.getState().controlsResolution).toBe("pending");
+
+      model.applyControls(model.getState().controlsRequestKey ?? "", {
+        ...speed,
+        options: { service_tier: "default", sandbox_mode: "read-only" },
+      });
+      expect(model.getState().controlsResolution).toBe("complete");
+      expect(model.getState().controlOptions).toEqual({
+        service_tier: "default",
+        sandbox_mode: "read-only",
+      });
+    });
+
+    it("draws no controls for the previous model while another model's answer is pending", () => {
       const model = openWithCatalog({ mode: "create" });
       selectClaude(model);
-      model.applyFeatures(model.getState().featureRequestKey ?? "", [
+      model.applyControls(model.getState().controlsRequestKey ?? "", WEB_SEARCH_CONTROLS);
-        { type: "toggle", id: "webSearch", label: "Web search", value: false },
-      ]);
 
-      model.setFeatureValue("webSearch", true);
+      model.setModel("claude-haiku-4-5", { label: "Haiku 4.5" });
 
-      expect(model.getState().features[0]).toMatchObject({ id: "webSearch", value: true });
+      expect(model.getState().controls).toEqual([]);
-      expect(model.getState().featureValues).toEqual({ webSearch: true });
-    });
-
-    it("keeps stored feature values while the feature list is still pending", () => {
-      const model = openAgentProfileForm({
-        mode: "edit",
-        profile: {
-          id: "p1",
-          name: "UI work",
-          provider: "claude",
-          featureValues: { webSearch: true },
-        },
-      });
-      model.applyProviderCatalog(ENTRIES);
-
-      expect(model.getState().featureResolution).toBe("pending");
-      expect(model.getState().submitValue?.featureValues).toEqual({ webSearch: true });
-    });
-
-    it("prunes stored values the provider no longer reports", () => {
-      const model = openAgentProfileForm({
-        mode: "edit",
-        profile: {
-          id: "p1",
-          name: "UI work",
-          provider: "claude",
-          featureValues: { webSearch: true, retiredFlag: true },
-        },
-      });
-      model.applyProviderCatalog(ENTRIES);
-      model.applyFeatures(model.getState().featureRequestKey ?? "", [
-        { type: "toggle", id: "webSearch", label: "Web search", value: false },
-      ]);
-
-      expect(model.getState().featureValues).toEqual({ webSearch: true });
     });
 
     it("resolves an unavailable feature listing without showing the field", () => {
       const model = openWithCatalog({ mode: "create" });
       selectClaude(model);
 
-      model.applyFeaturesUnavailable(model.getState().featureRequestKey ?? "");
+      model.applyControlsUnavailable(model.getState().controlsRequestKey ?? "");
 
-      expect(model.getState().featureResolution).toBe("complete");
+      expect(model.getState().controlsResolution).toBe("complete");
-      expect(model.getState().disclosure.showFeaturesField).toBe(false);
+      expect(model.getState().disclosure.showControlsField).toBe(false);
     });
   });
 
@@ -464,15 +562,15 @@ describe("openAgentProfileForm", () => {
   });
 });
 
-describe("buildFeatureRequestKey", () => {
+describe("buildControlsRequestKey", () => {
   it("is null without a provider", () => {
-    expect(buildFeatureRequestKey(null)).toBeNull();
+    expect(buildControlsRequestKey(null)).toBeNull();
   });
 
   it("separates the fields so a value cannot bleed across positions", () => {
-    expect(buildFeatureRequestKey({ provider: "claude", model: "a|b" })).toBe("claude|a|b||");
+    expect(buildControlsRequestKey({ provider: "claude", model: "a|b" })).toBe("claude|a|b||");
-    expect(buildFeatureRequestKey({ provider: "claude", modeId: "a" })).not.toBe(
+    expect(buildControlsRequestKey({ provider: "claude", modeId: "a" })).not.toBe(
-      buildFeatureRequestKey({ provider: "claude", model: "a" }),
+      buildControlsRequestKey({ provider: "claude", model: "a" }),
     );
   });
 });

packages/app/src/agent-profiles/internal/profile-form-model.ts

@@ -1,5 +1,6 @@
 import type {
-  AgentFeature,
+  AgentOptionControl,
+  ProviderOptions,
   AgentMode,
   AgentModelDefinition,
   AgentSelectOption,
@@ -7,7 +8,6 @@ import type {
 } from "@getpaseo/protocol/agent-types";
 import type { AgentProfile } from "@getpaseo/protocol/messages";
 import { formatAgentModeLabel, formatThinkingOptionLabel } from "@/agent-controls/labels";
-import { applyFeatureValues, pruneFeatureValues } from "@/hooks/feature-preferences";
 import { filterSelectableModels } from "@/provider-selection/model-catalog";
 
 /**
@@ -57,11 +57,15 @@ export interface AgentProfileFormSnapshot {
 }
 
 /**
- * The inputs a feature listing needs. Features are provider-scoped and change
+ * The inputs a controls listing needs. Controls are provider-scoped and change
- * with model/mode/thinking, so every one of those is part of the request.
+ * with model/mode/thinking, so every one of those is part of the request. The
+ * profile's own options ride along so the daemon can resolve them (a legacy
+ * `service_tier: "fast"` is drawn as the model's Fast tier); they are the same
+ * for the life of one provider, so they are not part of the key.
  */
-export interface AgentProfileFeatureRequest {
+export interface AgentProfileControlsRequest {
   provider: string;
+  providerOptions?: ProviderOptions;
   model?: string;
   modeId?: string;
   thinkingOptionId?: string;
@@ -73,7 +77,7 @@ export interface AgentProfileFormDisclosure {
   showModelField: boolean;
   showModeField: boolean;
   showThinkingField: boolean;
-  showFeaturesField: boolean;
+  showControlsField: boolean;
 }
 
 export interface AgentProfileFormState {
@@ -86,13 +90,18 @@ export interface AgentProfileFormState {
   modelId: string;
   modeId: string;
   thinkingOptionId: string;
-  featureValues: Record<string, unknown>;
+  /** The options the profile was opened with, including ones no control draws. */
+  options: ProviderOptions;
+  /** Changes made in this form, over `options`. */
+  optionEdits: ProviderOptions;
 
   providerOptions: AgentProfileFormOption[];
   modelOptions: AgentProfileFormOption[];
   modeOptions: AgentProfileFormOption[];
   thinkingOptions: AgentProfileFormOption[];
-  features: AgentFeature[];
+  controls: AgentOptionControl[];
+  /** What the controls show: the options the daemon resolved from `options`, then the edits. */
+  controlOptions: ProviderOptions;
 
   providerDisplay: AgentProfileFormDisplay | null;
   modelDisplay: AgentProfileFormDisplay | null;
@@ -100,9 +109,9 @@ export interface AgentProfileFormState {
   thinkingDisplay: AgentProfileFormDisplay | null;
 
   catalogResolution: AgentProfileResolutionStatus;
-  featureResolution: AgentProfileResolutionStatus;
+  controlsResolution: AgentProfileResolutionStatus;
-  featureRequest: AgentProfileFeatureRequest | null;
+  controlsRequest: AgentProfileControlsRequest | null;
-  featureRequestKey: string | null;
+  controlsRequestKey: string | null;
 
   disclosure: AgentProfileFormDisclosure;
   isSubmitting: boolean;
@@ -118,9 +127,12 @@ export interface AgentProfileFormModel {
   /** Late input: the host-scoped provider catalog. Never touches selections. */
   applyProviderCatalog: (entries: readonly ProviderSnapshotEntry[]) => void;
   /** Late input: the feature list for one request. Stale keys are ignored. */
-  applyFeatures: (requestKey: string, features: readonly AgentFeature[]) => void;
+  applyControls: (
+    requestKey: string,
+    resolved: { controls: readonly AgentOptionControl[]; options: ProviderOptions },
+  ) => void;
   /** Resolve a request that produced no usable features (provider error). */
-  applyFeaturesUnavailable: (requestKey: string) => void;
+  applyControlsUnavailable: (requestKey: string) => void;
   setName: (value: string) => void;
   setAppearance: (value: { icon: string; color: string }) => void;
   setNotes: (value: string) => void;
@@ -128,7 +140,7 @@ export interface AgentProfileFormModel {
   setModel: (modelId: string, display: AgentProfileFormDisplay | null) => void;
   setMode: (modeId: string, display: AgentProfileFormDisplay | null) => void;
   setThinking: (thinkingOptionId: string, display: AgentProfileFormDisplay | null) => void;
-  setFeatureValue: (featureId: string, value: unknown) => void;
+  setOption: (key: string, value: unknown) => void;
   setSubmitting: (value: boolean) => void;
   setSubmitError: (value: string | null) => void;
 }
@@ -312,19 +324,29 @@ function refineDisplay(
   return current ?? { label: selectedId };
 }
 
-function buildFeatureRequest(state: AgentProfileFormState): AgentProfileFeatureRequest | null {
+function buildControlsRequest(state: AgentProfileFormState): AgentProfileControlsRequest | null {
   if (!state.provider) {
     return null;
   }
+  const ownOptions = ownOptionsOf(state);
   return {
     provider: state.provider,
     ...(state.modelId ? { model: state.modelId } : {}),
     ...(state.modeId ? { modeId: state.modeId } : {}),
     ...(state.thinkingOptionId ? { thinkingOptionId: state.thinkingOptionId } : {}),
+    ...(Object.keys(ownOptions).length > 0 ? { providerOptions: ownOptions } : {}),
   };
 }
 
-export function buildFeatureRequestKey(request: AgentProfileFeatureRequest | null): string | null {
+/** Everything the profile would save as its options; the daemon resolves them for the form. */
+function ownOptionsOf(
+  state: Pick<AgentProfileFormState, "options" | "optionEdits">,
+): ProviderOptions {
+  return { ...state.options, ...state.optionEdits };
+}
+
+/** The part of a request that decides which controls exist; options only change their values. */
+function buildControlsScopeKey(request: AgentProfileControlsRequest | null): string | null {
   if (!request) {
     return null;
   }
@@ -336,12 +358,25 @@ export function buildFeatureRequestKey(request: AgentProfileFeatureRequest | nul
   ].join("|");
 }
 
+export function buildControlsRequestKey(
+  request: AgentProfileControlsRequest | null,
+): string | null {
+  if (!request) {
+    return null;
+  }
+  const scope = buildControlsScopeKey(request);
+  return request.providerOptions
+    ? `${scope}|${JSON.stringify(Object.entries(request.providerOptions).sort(([a], [b]) => a.localeCompare(b)))}`
+    : scope;
+}
+
 function buildSubmitValue(state: AgentProfileFormState): AgentProfileValue | null {
   const name = state.name.trim();
   const notes = state.notes.trim();
   if (!name || !state.provider) {
     return null;
   }
+  const options = ownOptionsOf(state);
   return {
     name,
     ...(state.icon ? { icon: state.icon } : {}),
@@ -350,16 +385,16 @@ function buildSubmitValue(state: AgentProfileFormState): AgentProfileValue | nul
     ...(state.modelId ? { model: state.modelId } : {}),
     ...(state.modeId ? { modeId: state.modeId } : {}),
     ...(state.thinkingOptionId ? { thinkingOptionId: state.thinkingOptionId } : {}),
-    ...(Object.keys(state.featureValues).length > 0 ? { featureValues: state.featureValues } : {}),
+    ...(Object.keys(options).length > 0 ? { options } : {}),
     ...(notes ? { notes } : {}),
   };
 }
 
-function resolveFeatureStatus(
+function resolveControlsStatus(
-  featureRequestKey: string | null,
+  controlsRequestKey: string | null,
   featuresAreCurrent: boolean,
 ): AgentProfileResolutionStatus {
-  if (featureRequestKey === null) {
+  if (controlsRequestKey === null) {
     return "idle";
   }
   return featuresAreCurrent ? "complete" : "pending";
@@ -392,25 +427,27 @@ function buildInitialState(snapshot: AgentProfileFormSnapshot): AgentProfileForm
     modelId,
     modeId: profile.modeId ?? "",
     thinkingOptionId: profile.thinkingOptionId ?? "",
-    featureValues: { ...profile.featureValues },
+    options: { ...profile.options },
+    optionEdits: {},
     providerOptions: [],
     modelOptions: [],
     modeOptions: [],
     thinkingOptions: [],
-    features: [],
+    controls: [],
+    controlOptions: {},
     providerDisplay: seedDisplay(provider),
     modelDisplay: seedDisplay(modelId),
     modeDisplay: seedDisplay(profile.modeId),
     thinkingDisplay: seedDisplay(profile.thinkingOptionId),
     catalogResolution: "idle",
-    featureResolution: "idle",
+    controlsResolution: "idle",
-    featureRequest: null,
+    controlsRequest: null,
-    featureRequestKey: null,
+    controlsRequestKey: null,
     disclosure: {
       showModelField: false,
       showModeField: false,
       showThinkingField: false,
-      showFeaturesField: false,
+      showControlsField: false,
     },
     isSubmitting: false,
     submitError: null,
@@ -422,8 +459,10 @@ function buildInitialState(snapshot: AgentProfileFormSnapshot): AgentProfileForm
 export function openAgentProfileForm(snapshot: AgentProfileFormSnapshot): AgentProfileFormModel {
   let entries: readonly ProviderSnapshotEntry[] = [];
   let catalogResolution: AgentProfileResolutionStatus = "idle";
-  let resolvedFeatureKey: string | null = null;
+  let resolvedControlsKey: string | null = null;
-  let resolvedFeatures: AgentFeature[] = [];
+  let resolvedScopeKey: string | null = null;
+  let resolvedControls: AgentOptionControl[] = [];
+  let resolvedOptions: ProviderOptions = {};
   let listeners = new Set<() => void>();
   let closed = false;
 
@@ -436,14 +475,23 @@ export function openAgentProfileForm(snapshot: AgentProfileFormSnapshot): AgentP
       modes,
     });
     const thinking = resolveThinkingOptions(entries, next.provider, next.modelId);
-    const featureRequest = buildFeatureRequest(next);
+    const controlsRequest = buildControlsRequest(next);
-    const featureRequestKey = buildFeatureRequestKey(featureRequest);
+    const controlsRequestKey = buildControlsRequestKey(controlsRequest);
+    const controlsScopeKey = buildControlsScopeKey(controlsRequest);
     const featuresAreCurrent =
-      featureRequestKey !== null && featureRequestKey === resolvedFeatureKey;
+      controlsRequestKey !== null && controlsRequestKey === resolvedControlsKey;
-    const features = featuresAreCurrent
+    // A toggle changes only the options, so the controls stay up while the daemon answers and the
-      ? applyFeatureValues(resolvedFeatures, next.featureValues)
+    // toggle shows over the last answer. A change of provider, model, mode or thinking draws none
-      : [];
+    // until its own answer arrives.
-    const featureResolution = resolveFeatureStatus(featureRequestKey, featuresAreCurrent);
+    const controlsApply = controlsScopeKey !== null && controlsScopeKey === resolvedScopeKey;
+    const controls = controlsApply ? resolvedControls : [];
+    let controlOptions: ProviderOptions = next.options;
+    if (controlsApply) {
+      controlOptions = featuresAreCurrent
+        ? resolvedOptions
+        : { ...resolvedOptions, ...next.optionEdits };
+    }
+    const controlsResolution = resolveControlsStatus(controlsRequestKey, featuresAreCurrent);
 
     const withOptions: AgentProfileFormState = {
       ...next,
@@ -451,7 +499,8 @@ export function openAgentProfileForm(snapshot: AgentProfileFormSnapshot): AgentP
       modelOptions: buildModelOptions(models),
       modeOptions: buildModeOptions(modes),
       thinkingOptions: buildThinkingOptions(thinking),
-      features,
+      controls,
+      controlOptions,
       providerDisplay: refineDisplay(
         next.providerDisplay,
         next.provider,
@@ -479,9 +528,9 @@ export function openAgentProfileForm(snapshot: AgentProfileFormSnapshot): AgentP
         })(),
       ),
       catalogResolution,
-      featureResolution,
+      controlsResolution,
-      featureRequest,
+      controlsRequest,
-      featureRequestKey,
+      controlsRequestKey,
     };
 
     // A field appears once the catalog can populate it, and stays visible while
@@ -492,7 +541,7 @@ export function openAgentProfileForm(snapshot: AgentProfileFormSnapshot): AgentP
       showModeField: hasProvider && (modes.length > 0 || Boolean(withOptions.modeId)),
       showThinkingField:
         hasProvider && (thinking.length > 0 || Boolean(withOptions.thinkingOptionId)),
-      showFeaturesField: hasProvider && features.length > 0,
+      showControlsField: hasProvider && controls.length > 0,
     };
     const canSubmit =
       withOptions.name.trim().length > 0 &&
@@ -531,23 +580,24 @@ export function openAgentProfileForm(snapshot: AgentProfileFormSnapshot): AgentP
       catalogResolution = "complete";
       publish((current) => current);
     },
-    applyFeatures: (requestKey, features) => {
+    applyControls: (requestKey, resolved) => {
-      if (requestKey !== state.featureRequestKey) {
+      if (requestKey !== state.controlsRequestKey) {
         return;
       }
-      resolvedFeatureKey = requestKey;
+      resolvedControlsKey = requestKey;
-      resolvedFeatures = [...features];
+      resolvedScopeKey = buildControlsScopeKey(state.controlsRequest);
-      publish((current) => ({
+      resolvedControls = [...resolved.controls];
-        ...current,
+      resolvedOptions = resolved.options;
-        featureValues: pruneFeatureValues(current.featureValues, resolvedFeatures),
+      publish((current) => current);
-      }));
     },
-    applyFeaturesUnavailable: (requestKey) => {
+    applyControlsUnavailable: (requestKey) => {
-      if (requestKey !== state.featureRequestKey) {
+      if (requestKey !== state.controlsRequestKey) {
         return;
       }
-      resolvedFeatureKey = requestKey;
+      resolvedControlsKey = requestKey;
-      resolvedFeatures = [];
+      resolvedScopeKey = buildControlsScopeKey(state.controlsRequest);
+      resolvedControls = [];
+      resolvedOptions = {};
       publish((current) => current);
     },
     setName: (value) => publish((current) => ({ ...current, name: value })),
@@ -572,7 +622,8 @@ export function openAgentProfileForm(snapshot: AgentProfileFormSnapshot): AgentP
           modeDisplay: null,
           thinkingOptionId: "",
           thinkingDisplay: null,
-          featureValues: {},
+          options: {},
+          optionEdits: {},
         };
       }),
     setModel: (modelId, display) =>
@@ -598,10 +649,10 @@ export function openAgentProfileForm(snapshot: AgentProfileFormSnapshot): AgentP
       publish((current) => ({ ...current, modeId, modeDisplay: display })),
     setThinking: (thinkingOptionId, display) =>
       publish((current) => ({ ...current, thinkingOptionId, thinkingDisplay: display })),
-    setFeatureValue: (featureId, value) =>
+    setOption: (key, value) =>
       publish((current) => ({
         ...current,
-        featureValues: { ...current.featureValues, [featureId]: value },
+        optionEdits: { ...current.optionEdits, [key]: value },
       })),
     setSubmitting: (value) => publish((current) => ({ ...current, isSubmitting: value })),
     setSubmitError: (value) => publish((current) => ({ ...current, submitError: value })),

packages/app/src/agent-profiles/internal/profile-summary.ts

@@ -47,7 +47,7 @@ export function buildAgentProfileTags(input: {
     tags.push({ id: "thinking", label: formatThinkingOptionLabel({ id: thinkingOptionId }) });
   }
 
-  const featureCount = Object.keys(input.profile.featureValues ?? {}).length;
+  const featureCount = Object.keys(input.profile.options ?? {}).length;
   if (featureCount > 0) {
     tags.push({ id: "features", label: input.formatFeatureCount(featureCount) });
   }

packages/app/src/agent-profiles/internal/use-agent-profile-picker.ts

@@ -117,9 +117,7 @@ export function useAgentProfilePicker(
           modelId: resolved.modelId,
           modeId: resolved.modeId,
           thinkingOptionId: resolved.thinkingOptionId,
-          ...(Object.keys(resolved.featureValues).length > 0
+          ...(Object.keys(resolved.options).length > 0 ? { options: resolved.options } : {}),
-            ? { featureValues: resolved.featureValues }
-            : {}),
         }),
       ).catch((error) => {
         console.warn("[useAgentProfilePicker] persist profile selection failed", error);

packages/app/src/agent-profiles/internal/use-profile-form-inputs.ts

@@ -27,7 +27,7 @@ export function useAgentProfileFormCatalog(input: {
   }, [entries, input.model]);
 }
 
-export function useAgentProfileFormFeatures(input: {
+export function useAgentProfileFormControls(input: {
   serverId: string;
   model: AgentProfileFormModel;
   state: AgentProfileFormState;
@@ -35,14 +35,14 @@ export function useAgentProfileFormFeatures(input: {
   const { t } = useTranslation();
   const client = useHostRuntimeClient(input.serverId);
   const isConnected = useHostRuntimeIsConnected(input.serverId);
-  const request = input.state.featureRequest;
+  const request = input.state.controlsRequest;
-  const requestKey = input.state.featureRequestKey;
+  const requestKey = input.state.controlsRequestKey;
 
   // `dataShape: "value"` and not `"list"`: a list shape keeps the previous
   // page's data while the next request is in flight, which would hand the
   // features of one provider/model combination to the key of another.
-  const featuresQuery = useFetchQuery({
+  const controlsQuery = useFetchQuery({
-    queryKey: ["agentProfileFeatures", input.serverId, requestKey],
+    queryKey: ["agentProfileControls", input.serverId, requestKey],
     dataShape: "value",
     staleTimeMs: 5 * 60 * 1000,
     enabled: Boolean(client && isConnected && request),
@@ -51,28 +51,28 @@ export function useAgentProfileFormFeatures(input: {
       if (!client || !request) {
         throw new Error(t("workspace.terminal.hostDisconnected"));
       }
-      const payload = await client.listProviderFeatures({ ...request, cwd: HOME_SCOPE_CWD });
+      const payload = await client.listProviderControls({ ...request, cwd: HOME_SCOPE_CWD });
       if (payload.error) {
         throw new Error(payload.error);
       }
-      return payload.features ?? [];
+      return { controls: payload.controls ?? [], options: payload.options ?? {} };
     },
   });
 
-  const { data, isError } = featuresQuery;
+  const { data, isError } = controlsQuery;
   const { model } = input;
 
   useEffect(() => {
     if (!requestKey || !data) {
       return;
     }
-    model.applyFeatures(requestKey, data);
+    model.applyControls(requestKey, data);
   }, [data, model, requestKey]);
 
   useEffect(() => {
     if (!requestKey || !isError) {
       return;
     }
-    model.applyFeaturesUnavailable(requestKey);
+    model.applyControlsUnavailable(requestKey);
   }, [isError, model, requestKey]);
 }

packages/app/src/agent-profiles/settings/agent-profile-edit-modal.tsx

@@ -2,7 +2,8 @@ import { useCallback, useEffect, useMemo, useRef, useState, type ReactElement }
 import { Text, View } from "react-native";
 import { useTranslation } from "react-i18next";
 import { StyleSheet } from "react-native-unistyles";
-import type { AgentFeature } from "@getpaseo/protocol/agent-types";
+import type { AgentOptionControl, ProviderOptions } from "@getpaseo/protocol/agent-types";
+import { readSelectOption, readToggleOption } from "@/agent-controls/option-controls";
 import type { AgentProfile } from "@getpaseo/protocol/messages";
 import { AdaptiveModalSheet, type SheetHeader } from "@/components/adaptive-modal-sheet";
 import { Button } from "@/components/ui/button";
@@ -25,7 +26,7 @@ import type {
 } from "../internal/profile-form-model";
 import {
   useAgentProfileFormCatalog,
-  useAgentProfileFormFeatures,
+  useAgentProfileFormControls,
 } from "../internal/use-profile-form-inputs";
 import {
   useAgentProfileFormModel,
@@ -141,7 +142,7 @@ function OpenAgentProfileEditModal({
   const model = useAgentProfileFormModel(snapshot);
   const state = useAgentProfileFormState(model);
   useAgentProfileFormCatalog({ serverId, model });
-  useAgentProfileFormFeatures({ serverId, model, state });
+  useAgentProfileFormControls({ serverId, model, state });
 
   const sheetHeader = useMemo<SheetHeader>(
     () => ({
@@ -328,16 +329,17 @@ function OpenAgentProfileEditModal({
           />
         ) : null}
 
-        {state.disclosure.showFeaturesField ? (
+        {state.disclosure.showControlsField ? (
           <Field
             label={t("settings.host.agentProfiles.featuresLabel")}
             testID="agent-profile-features-field"
           >
             <View style={styles.featureCard} testID="agent-profile-features-card">
-              {state.features.map((feature, index) => (
+              {state.controls.map((control, index) => (
-                <AgentProfileFeatureRow
+                <AgentProfileControlRow
-                  key={feature.id}
+                  key={control.key}
-                  feature={feature}
+                  control={control}
+                  options={state.controlOptions}
                   isFirst={index === 0}
                   disabled={state.isSubmitting}
                   size={controlSize}
@@ -400,14 +402,16 @@ function OpenAgentProfileEditModal({
   );
 }
 
-function AgentProfileFeatureRow({
+function AgentProfileControlRow({
-  feature,
+  control,
+  options,
   isFirst,
   disabled,
   size,
   model,
 }: {
-  feature: AgentFeature;
+  control: AgentOptionControl;
+  options: ProviderOptions;
   isFirst: boolean;
   disabled: boolean;
   size: FieldControlSize;
@@ -418,74 +422,75 @@ function AgentProfileFeatureRow({
     [isFirst],
   );
   const handleToggle = useCallback(
-    (value: boolean) => model.setFeatureValue(feature.id, value),
+    (value: boolean) => model.setOption(control.key, value),
-    [feature.id, model],
+    [control.key, model],
   );
   const handleSelect = useCallback(
-    (value: string) => model.setFeatureValue(feature.id, value),
+    (value: string) => model.setOption(control.key, value),
-    [feature.id, model],
+    [control.key, model],
   );
   const selectOptions = useMemo<SelectFieldOption<string>[]>(
     () =>
-      feature.type === "select"
+      control.type === "select"
-        ? feature.options.map((option) => ({
+        ? control.choices.map((choice) => ({
-            id: option.id,
+            id: choice.value,
-            value: option.id,
+            value: choice.value,
-            label: option.label,
+            label: choice.label,
-            ...(option.description ? { description: option.description } : {}),
+            ...(choice.description ? { description: choice.description } : {}),
-            testID: `agent-profile-feature-option-${feature.id}-${option.id}`,
+            testID: `agent-profile-feature-option-${control.key}-${choice.value}`,
           }))
         : [],
-    [feature],
+    [control],
   );
+  const selectedValue = control.type === "select" ? readSelectOption(control, options) : null;
   const selectedDisplay = useMemo<SelectFieldDisplay | null>(() => {
-    if (feature.type !== "select" || !feature.value) {
+    if (control.type !== "select" || !selectedValue) {
       return null;
     }
-    const option = feature.options.find((candidate) => candidate.id === feature.value);
+    const choice = control.choices.find((candidate) => candidate.value === selectedValue);
-    return { label: option?.label ?? feature.value };
+    return { label: choice?.label ?? selectedValue };
-  }, [feature]);
+  }, [control, selectedValue]);
 
-  if (feature.type === "select") {
+  if (control.type === "select") {
     return (
-      <View style={rowStyle} testID={`agent-profile-feature-row-${feature.id}`}>
+      <View style={rowStyle} testID={`agent-profile-feature-row-${control.key}`}>
         <SelectField
-          label={feature.label}
+          label={control.label}
-          value={feature.value}
+          value={selectedValue}
           selectedDisplay={selectedDisplay}
           options={selectOptions}
           onChange={handleSelect}
-          placeholder={feature.label}
+          placeholder={control.label}
-          emptyText={feature.label}
+          emptyText={control.label}
           disabled={disabled}
-          {...(feature.description ? { hint: feature.description } : {})}
+          {...(control.description ? { hint: control.description } : {})}
-          title={feature.label}
+          title={control.label}
           size={size}
-          testID={`agent-profile-feature-field-${feature.id}`}
+          testID={`agent-profile-feature-field-${control.key}`}
-          triggerTestID={`agent-profile-feature-trigger-${feature.id}`}
+          triggerTestID={`agent-profile-feature-trigger-${control.key}`}
         />
       </View>
     );
   }
 
   return (
-    <View style={rowStyle} testID={`agent-profile-feature-row-${feature.id}`}>
+    <View style={rowStyle} testID={`agent-profile-feature-row-${control.key}`}>
       <View style={styles.featureMeta}>
         <Text style={styles.featureLabel} numberOfLines={1}>
-          {feature.label}
+          {control.label}
         </Text>
-        {feature.description ? (
+        {control.description ? (
           <Text style={styles.featureDescription} numberOfLines={2}>
-            {feature.description}
+            {control.description}
           </Text>
         ) : null}
       </View>
       <Switch
-        value={feature.value === true}
+        value={readToggleOption(control, options)}
         onValueChange={handleToggle}
         disabled={disabled}
-        accessibilityLabel={feature.label}
+        accessibilityLabel={control.label}
-        testID={`agent-profile-feature-switch-${feature.id}`}
+        testID={`agent-profile-feature-switch-${control.key}`}
       />
     </View>
   );

packages/app/src/agent-stream/view.tsx

@@ -1304,7 +1304,8 @@ function collectAgentSetupDiffs(left: AgentScreenAgent, right: AgentScreenAgent)
   if (left.runtimeInfo?.thinkingOptionId !== right.runtimeInfo?.thinkingOptionId) {
     reasons.push("agent.runtimeInfo.thinkingOptionId");
   }
-  if (left.features !== right.features) reasons.push("agent.features");
+  if (left.options !== right.options) reasons.push("agent.options");
+  if (left.controls !== right.controls) reasons.push("agent.controls");
   return reasons;
 }
 

packages/app/src/client-slash-commands/index.test.ts

@@ -40,16 +40,7 @@ function createAgent(overrides: Partial<Agent> = {}): Agent {
     cwd: "/repo",
     model: "agent-model",
     thinkingOptionId: "think-hard",
-    features: [
+    options: { "web-search": true, effort: "high" },
-      { type: "toggle", id: "web-search", label: "Web search", value: true },
-      {
-        type: "select",
-        id: "effort",
-        label: "Effort",
-        value: "high",
-        options: [{ id: "high", label: "High" }],
-      },
-    ],
     parentAgentId: null,
     labels: {},
     ...overrides,
@@ -114,7 +105,7 @@ describe("buildDraftAgentSetup", () => {
       modeId: "mode-current",
       model: "agent-model",
       thinkingOptionId: "think-hard",
-      featureValues: {
+      providerOptions: {
         "web-search": true,
         effort: "high",
       },

packages/app/src/client-slash-commands/index.ts

@@ -65,17 +65,12 @@ export function resolveClientSlashCommand(input: {
 }
 
 export function buildDraftAgentSetup(agent: Agent): WorkspaceDraftTabSetup {
-  const featureValues: Record<string, unknown> = {};
-  for (const feature of agent.features ?? []) {
-    featureValues[feature.id] = feature.value;
-  }
-
   return {
     provider: agent.provider,
     cwd: agent.cwd,
     modeId: agent.currentModeId ?? agent.runtimeInfo?.modeId ?? null,
     model: agent.model ?? agent.runtimeInfo?.model ?? null,
     thinkingOptionId: agent.thinkingOptionId ?? agent.runtimeInfo?.thinkingOptionId ?? null,
-    featureValues,
+    providerOptions: { ...agent.options },
   };
 }

packages/app/src/command-center/agent-control-contributions.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it } from "vitest";
-import type { AgentFeature, AgentMode, AgentSelectOption } from "@getpaseo/protocol/agent-types";
+import type {
+  AgentMode,
+  AgentOptionControl,
+  AgentSelectOption,
+} from "@getpaseo/protocol/agent-types";
 import type { ProviderSelectorProvider } from "@/provider-selection/provider-selection";
 import type { CommandCenterContribution } from "./contributions";
 import {
@@ -31,7 +35,7 @@ const ICONS: AgentControlContributionSource["icons"] = {
   thinking: TestIcon,
   planMode: TestIcon,
   mode: () => TestIcon,
-  feature: () => TestIcon,
+  control: () => TestIcon,
 };
 
 function provider(input: {
@@ -65,8 +69,8 @@ function provider(input: {
   };
 }
 
-function toggleFeature(id: string, value = false, icon?: string): AgentFeature {
+function toggleControl(key: string, icon?: string): AgentOptionControl {
-  return { type: "toggle", id, label: id, value, icon };
+  return { type: "toggle", key, label: key, icon };
 }
 
 function makeSource(
@@ -75,7 +79,7 @@ function makeSource(
     models?: Partial<AgentControlContributionSource["models"]>;
     thinking?: Partial<AgentControlContributionSource["thinking"]>;
     modes?: Partial<NonNullable<AgentControlContributionSource["modes"]>>;
-    features?: Partial<AgentControlContributionSource["features"]>;
+    optionControls?: Partial<AgentControlContributionSource["optionControls"]>;
   } = {},
 ): AgentControlContributionSource {
   return {
@@ -104,10 +108,11 @@ function makeSource(
       select: () => undefined,
       ...overrides.modes,
     },
-    features: {
+    optionControls: {
-      list: [],
+      controls: [],
-      set: () => undefined,
+      options: {},
-      ...overrides.features,
+      onSetOption: () => undefined,
+      ...overrides.optionControls,
     },
   };
 }
@@ -133,7 +138,7 @@ describe("Command Center agent-control contributions", () => {
     const contributions = buildAgentControlContributions({
       ...makeSource({
         models: { providers: [provider({ id: "claude", label: "Claude" })] },
-        features: { list: [toggleFeature("plan_mode", true)] },
+        optionControls: { controls: [toggleControl("plan_mode")], options: { plan_mode: true } },
       }),
       modes: undefined,
     });
@@ -323,9 +328,10 @@ describe("Command Center agent-control contributions", () => {
           selectedId: "default",
           defaultModeId: "default",
         },
-        features: {
+        optionControls: {
-          list: [toggleFeature("plan_mode", true, "list-todo")],
+          controls: [toggleControl("plan_mode", "list-todo")],
-          set: (id, value) => {
+          options: { plan_mode: true },
+          onSetOption: (id, value) => {
             calls.push([id, value]);
           },
         },
@@ -341,9 +347,10 @@ describe("Command Center agent-control contributions", () => {
     const calls: [string, unknown][] = [];
     const contributions = buildAgentControlContributions(
       makeSource({
-        features: {
+        optionControls: {
-          list: [toggleFeature("fast_mode", false, "zap"), toggleFeature("auto_accept", true)],
+          controls: [toggleControl("fast_mode", "zap"), toggleControl("auto_accept")],
-          set: (id, value) => {
+          options: { fast_mode: false, auto_accept: true },
+          onSetOption: (id, value) => {
             calls.push([id, value]);
           },
         },
@@ -376,7 +383,7 @@ describe("Command Center agent-control contributions", () => {
           selectedId: "default",
           defaultModeId: "default",
         },
-        features: { list: [toggleFeature("fast_mode")] },
+        optionControls: { controls: [toggleControl("fast_mode")], options: {} },
       }),
     );
     const ranks = new Map<string, number>();

packages/app/src/command-center/agent-control-contributions.ts

@@ -1,9 +1,10 @@
 import type {
-  AgentFeature,
   AgentMode,
+  AgentOptionControl,
   AgentProvider,
   AgentSelectOption,
 } from "@getpaseo/protocol/agent-types";
+import { readToggleOption, type ComposerOptionControls } from "@/agent-controls/option-controls";
 import type { ProviderSelectorProvider } from "@/provider-selection/provider-selection";
 import { formatAgentModeLabel, formatThinkingOptionLabel } from "@/agent-controls/labels";
 import {
@@ -61,7 +62,7 @@ export interface AgentControlContributionIcons {
   thinking: CommandCenterIcon;
   planMode: CommandCenterIcon;
   mode(modeId: string): CommandCenterIcon;
-  feature(feature: AgentFeature): CommandCenterIcon;
+  control(control: AgentOptionControl): CommandCenterIcon;
 }
 
 interface CommandCenterChoice {
@@ -105,10 +106,7 @@ export interface AgentControlContributionSource {
     defaultModeId: string | null;
     select(modeId: string): void | Promise<void>;
   };
-  features: {
+  optionControls: ComposerOptionControls;
-    list: readonly AgentFeature[];
-    set(featureId: string, value: unknown): void | Promise<void>;
-  };
 }
 
 function buildContributions(
@@ -242,18 +240,19 @@ function toggleChoices(input: {
 }
 
 function buildPlanModeGroup(source: AgentControlContributionSource): CommandCenterChoiceGroup {
-  const planFeature = source.features.list.find(
+  const { controls, options, onSetOption } = source.optionControls;
-    (feature) => feature.id === PLAN_MODE_FEATURE_ID && feature.type === "toggle",
+  const planControl = controls.find(
+    (control) => control.key === PLAN_MODE_FEATURE_ID && control.type === "toggle",
   );
   let choices: CommandCenterChoice[] = [];
-  if (planFeature?.type === "toggle") {
+  if (planControl?.type === "toggle") {
     choices = toggleChoices({
       source,
       key: "plan",
-      icon: source.icons.feature(planFeature),
+      icon: source.icons.control(planControl),
-      isOn: planFeature.value,
+      isOn: readToggleOption(planControl, options),
-      turnOn: () => source.features.set(PLAN_MODE_FEATURE_ID, true),
+      turnOn: () => onSetOption(PLAN_MODE_FEATURE_ID, true),
-      turnOff: () => source.features.set(PLAN_MODE_FEATURE_ID, false),
+      turnOff: () => onSetOption(PLAN_MODE_FEATURE_ID, false),
     });
   } else if (source.modes) {
     const modes = source.modes;
@@ -280,18 +279,19 @@ function buildPlanModeGroup(source: AgentControlContributionSource): CommandCent
 }
 
 function buildFastModeGroup(source: AgentControlContributionSource): CommandCenterChoiceGroup {
-  const fastFeature = source.features.list.find(
+  const { controls, options, onSetOption } = source.optionControls;
-    (feature) => feature.id === FAST_MODE_FEATURE_ID && feature.type === "toggle",
+  const fastControl = controls.find(
+    (control) => control.key === FAST_MODE_FEATURE_ID && control.type === "toggle",
   );
   const choices =
-    fastFeature?.type === "toggle"
+    fastControl?.type === "toggle"
       ? toggleChoices({
           source,
           key: "fast",
-          icon: source.icons.feature(fastFeature),
+          icon: source.icons.control(fastControl),
-          isOn: fastFeature.value,
+          isOn: readToggleOption(fastControl, options),
-          turnOn: () => source.features.set(FAST_MODE_FEATURE_ID, true),
+          turnOn: () => onSetOption(FAST_MODE_FEATURE_ID, true),
-          turnOff: () => source.features.set(FAST_MODE_FEATURE_ID, false),
+          turnOff: () => onSetOption(FAST_MODE_FEATURE_ID, false),
         })
       : [];
   return {

packages/app/src/command-center/agent-control-registration.tsx

@@ -1,11 +1,6 @@
 import { useMemo } from "react";
 import { useTranslation } from "react-i18next";
-import type {
+import type { AgentMode, AgentProvider, AgentSelectOption } from "@getpaseo/protocol/agent-types";
-  AgentFeature,
-  AgentMode,
-  AgentProvider,
-  AgentSelectOption,
-} from "@getpaseo/protocol/agent-types";
 import type { AgentProviderDefinition } from "@getpaseo/protocol/provider-manifest";
 import {
   getAgentFeatureIcon,
@@ -14,6 +9,7 @@ import {
   ThinkingIcon,
 } from "@/agent-controls/icons";
 import { useProviderIcons } from "@/components/provider-icons";
+import type { ComposerOptionControls } from "@/agent-controls/option-controls";
 import type { ProviderSelectorProvider } from "@/provider-selection/provider-selection";
 import {
   buildAgentControlContributions,
@@ -44,15 +40,15 @@ export interface AgentControlCommandCenterSource {
     selectedId: string | null | undefined;
     select(modeId: string): void | Promise<void>;
   };
-  features: {
+  /** Absent when the surface cannot change options (the agent has no client). */
-    list: readonly AgentFeature[] | undefined;
+  optionControls: ComposerOptionControls | null;
-    set?: (featureId: string, value: unknown) => void | Promise<void>;
-  };
 }
 
-function ignoreAgentFeatureChange(): void {
+const NO_OPTION_CONTROLS: ComposerOptionControls = {
-  return;
+  controls: [],
-}
+  options: {},
+  onSetOption: () => undefined,
+};
 
 function resolveDefaultModeId(
   provider: string | null | undefined,
@@ -87,7 +83,7 @@ export function useAgentControlCommandCenterActions(input: {
 }): void {
   const { t } = useTranslation();
   const { controls } = input;
-  const { features, models, modes, thinking } = controls;
+  const { optionControls, models, modes, thinking } = controls;
   const getProviderIcon = useProviderIcons(controls.serverId);
   const actions = useMemo(
     () =>
@@ -104,7 +100,7 @@ export function useAgentControlCommandCenterActions(input: {
             getCommandCenterIcon(
               getAgentModeIcon(controls.provider ?? "", modeId, controls.providerDefinitions),
             ),
-          feature: (feature) => getCommandCenterIcon(getAgentFeatureIcon(feature.icon)),
+          control: (control) => getCommandCenterIcon(getAgentFeatureIcon(control.icon)),
         },
         models: {
           providers: models.providers,
@@ -123,10 +119,7 @@ export function useAgentControlCommandCenterActions(input: {
           modes?.select,
           resolveDefaultModeId(controls.provider, controls.providerDefinitions),
         ),
-        features: {
+        optionControls: optionControls ?? NO_OPTION_CONTROLS,
-          list: features.set ? (features.list ?? []) : [],
-          set: features.set ?? ignoreAgentFeatureChange,
-        },
       }),
     [
       getProviderIcon,
@@ -134,8 +127,7 @@ export function useAgentControlCommandCenterActions(input: {
       controls.provider,
       controls.providerDefinitions,
       controls.serverId,
-      features.list,
+      optionControls,
-      features.set,
       models.providers,
       models.select,
       models.selectedModelId,

packages/app/src/composer/agent-controls/index.tsx

@@ -25,6 +25,13 @@ import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { useShallow } from "zustand/shallow";
 import { Settings2 } from "lucide-react-native";
 import { getAgentFeatureIcon, ThinkingIcon } from "@/agent-controls/icons";
+import {
+  getControlTooltip,
+  isControlActive,
+  readSelectOption,
+  readToggleOption,
+  type ComposerOptionControls,
+} from "@/agent-controls/option-controls";
 import { formatThinkingOptionLabel } from "@/agent-controls/labels";
 import { ComboboxTrigger } from "@/components/ui/combobox-trigger";
 import { CombinedModelSelector } from "@/components/combined-model-selector";
@@ -47,7 +54,8 @@ import {
 import { AdaptiveModalSheet, type SheetHeader } from "@/components/adaptive-modal-sheet";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
 import type {
-  AgentFeature,
+  AgentOptionControl,
+  ProviderOptions,
   AgentMode,
   AgentModelDefinition,
   AgentProvider,
@@ -55,8 +63,6 @@ import type {
 import type { AgentProviderDefinition } from "@getpaseo/protocol/provider-manifest";
 import {
   getFeatureHighlightColor,
-  isFeatureActive,
-  getFeatureTooltip,
   getAgentControlHintKey,
   resolveAgentModelSelection,
 } from "@/composer/agent-controls/utils";
@@ -101,6 +107,7 @@ interface AgentControlOption {
 type AgentControlSelector = "provider" | "mode" | "model" | "thinking" | `feature-${string}`;
 
 const EMPTY_AGENT_PROVIDER_DEFINITIONS: AgentProviderDefinition[] = [];
+const EMPTY_OPTIONS: ProviderOptions = {};
 
 interface ControlledAgentControlsProps {
   provider: string;
@@ -122,8 +129,7 @@ interface ControlledAgentControlsProps {
   onEditAgentProfiles?: () => void;
   onCreateAgentProfile?: (seed: AgentProfileSeed) => void;
   onEditAgentProfile?: (profileId: string) => void;
-  features?: AgentFeature[];
+  optionControls?: ComposerOptionControls;
-  onSetFeature?: (featureId: string, value: unknown) => void;
   onDropdownClose?: () => void;
   onModelSelectorOpen?: () => void;
   onRetryModelProvider?: (provider: AgentProvider) => void;
@@ -150,8 +156,7 @@ export interface DraftAgentControlsProps {
   selectedThinkingOptionId: string;
   onSelectThinkingOption: (thinkingOptionId: string) => void;
   onApplyAgentProfile: DraftAgentProfileControls["applyProfile"];
-  features?: AgentFeature[];
+  optionControls?: ComposerOptionControls;
-  onSetFeature?: (featureId: string, value: unknown) => void;
   onDropdownClose?: () => void;
   onModelSelectorOpen?: () => void;
   onRetryModelProvider?: (provider: AgentProvider) => void;
@@ -212,7 +217,8 @@ function getModeProviderDefinitions(modeControl: AgentModeControlValue | null) {
 }
 
 function getFeatureIconColor(
-  feature: AgentFeature,
+  control: AgentOptionControl,
+  options: ProviderOptions,
   palette: {
     blue: { 400: string };
     green: { 400: string };
@@ -220,11 +226,11 @@ function getFeatureIconColor(
   },
   foregroundMuted: string,
 ): string {
-  if (!isFeatureActive(feature)) {
+  if (!isControlActive(control, options)) {
     return foregroundMuted;
   }
 
-  switch (getFeatureHighlightColor(feature.id)) {
+  switch (getFeatureHighlightColor(control.key)) {
     case "blue":
       return palette.blue[400];
     case "green":
@@ -242,20 +248,20 @@ function resolveHasAnyControl({
   providerOptions,
   canSelectModel,
   thinkingOptions,
-  features,
+  controls,
   hasMode,
 }: {
   providerOptions: AgentControlOption[] | undefined;
   canSelectModel: boolean;
   thinkingOptions: AgentControlOption[] | undefined;
-  features: AgentFeature[] | undefined;
+  controls: readonly AgentOptionControl[] | undefined;
   hasMode: boolean;
 }) {
   return (
     Boolean(providerOptions?.length) ||
     canSelectModel ||
     Boolean(thinkingOptions?.length) ||
-    Boolean(features?.length) ||
+    Boolean(controls?.length) ||
     hasMode
   );
 }
@@ -393,7 +399,8 @@ type AgentControlsSlice = {
   cwd: string | null;
   runtimeModelId: string | null;
   model: string | null | undefined;
-  features: AgentFeature[] | undefined;
+  options: ProviderOptions | undefined;
+  controls: AgentOptionControl[] | undefined;
   runtimeThinkingOptionId: string | null;
   thinkingOptionId: string | null | undefined;
   lastUsage: unknown;
@@ -413,7 +420,8 @@ function selectAgentControlsSlice(
     cwd: currentAgent.cwd,
     runtimeModelId: currentAgent.runtimeInfo?.model ?? null,
     model: currentAgent.model,
-    features: currentAgent.features,
+    options: currentAgent.options,
+    controls: currentAgent.controls,
     runtimeThinkingOptionId: currentAgent.runtimeInfo?.thinkingOptionId ?? null,
     thinkingOptionId: currentAgent.thinkingOptionId,
     lastUsage: currentAgent.lastUsage,
@@ -493,8 +501,7 @@ function ControlledAgentControls({
   onEditAgentProfiles,
   onCreateAgentProfile,
   onEditAgentProfile,
-  features,
+  optionControls,
-  onSetFeature,
   onDropdownClose,
   onModelSelectorOpen,
   onRetryModelProvider,
@@ -546,20 +553,21 @@ function ControlledAgentControls({
     providerOptions,
     canSelectModel,
     thinkingOptions,
-    features,
+    controls: optionControls?.controls,
     hasMode: modeControl !== null && modeControl !== undefined,
   });
   const featureControls = useMemo(
     () =>
-      (features ?? []).map((feature) => {
+      (optionControls?.controls ?? []).map((control) => {
-        if (feature.type === "toggle") return { type: "toggle" as const };
+        if (control.type === "toggle") return { type: "toggle" as const };
-        const selectedOption = feature.options.find((option) => option.id === feature.value);
+        const selected = readSelectOption(control, optionControls?.options ?? {});
+        const choice = control.choices.find((candidate) => candidate.value === selected);
         return {
           type: "select" as const,
-          label: selectedOption?.label ?? feature.label,
+          label: choice?.label ?? control.label,
         };
       }),
-    [features],
+    [optionControls],
   );
   const controlPresence = useMemo(
     () => ({
@@ -743,8 +751,7 @@ function ControlledAgentControls({
             selectedModelId={selectedModelId}
             thinkingOptions={formattedThinkingOptions}
             selectedThinkingOptionId={selectedThinkingOptionId}
-            features={features}
+            optionControls={optionControls}
-            onSetFeature={onSetFeature}
             onApplyAgentProfile={onApplyAgentProfile}
             onEditAgentProfiles={onEditAgentProfiles}
             onCreateAgentProfile={onCreateAgentProfile}
@@ -792,8 +799,7 @@ function ControlledAgentControls({
             provider={provider}
             selectedModelId={selectedModelId}
             selectedThinkingOptionId={selectedThinkingOptionId}
-            features={features}
+            optionControls={optionControls}
-            onSetFeature={onSetFeature}
             onApplyAgentProfile={onApplyAgentProfile}
             onEditAgentProfiles={onEditAgentProfiles}
             onCreateAgentProfile={onCreateAgentProfile}
@@ -838,8 +844,7 @@ interface DesktopAgentControlsContentProps {
   selectedModelId?: string;
   thinkingOptions?: AgentControlOption[];
   selectedThinkingOptionId?: string;
-  features?: AgentFeature[];
+  optionControls?: ComposerOptionControls;
-  onSetFeature?: (featureId: string, value: unknown) => void;
   onApplyAgentProfile?: (profileId: string) => void;
   onEditAgentProfiles?: () => void;
   onCreateAgentProfile?: (seed: AgentProfileSeed) => void;
@@ -900,8 +905,7 @@ function DesktopAgentControlsContent(props: DesktopAgentControlsContentProps) {
     selectedModelId,
     thinkingOptions,
     selectedThinkingOptionId,
-    features,
+    optionControls,
-    onSetFeature,
     onApplyAgentProfile,
     onEditAgentProfiles,
     onCreateAgentProfile,
@@ -1057,7 +1061,7 @@ function DesktopAgentControlsContent(props: DesktopAgentControlsContentProps) {
 
       {modeControl ? <AgentModeControl {...modeControl} onClose={onDropdownClose} /> : null}
 
-      {presentation.aggregateFeatures && features?.length ? (
+      {presentation.aggregateFeatures && optionControls?.controls.length ? (
         <>
           <Pressable
             onPress={handleOpenFeatures}
@@ -1077,27 +1081,29 @@ function DesktopAgentControlsContent(props: DesktopAgentControlsContentProps) {
             onClose={handleCloseSheet}
             testID="agent-features-sheet"
           >
-            {features.map((feature) => (
+            {optionControls.controls.map((control) => (
               <SheetFeatureItem
-                key={`feature-${feature.id}`}
+                key={`feature-${control.key}`}
-                feature={feature}
+                control={control}
+                options={optionControls.options}
                 disabled={disabled}
                 openSelector={openSelector}
                 handleOpenChange={handleNestedOpenChange}
-                onSetFeature={onSetFeature}
+                onSetOption={optionControls.onSetOption}
               />
             ))}
           </AdaptiveModalSheet>
         </>
       ) : (
-        features?.map((feature) => (
+        optionControls?.controls.map((control) => (
           <DesktopFeatureItem
-            key={`feature-${feature.id}`}
+            key={`feature-${control.key}`}
-            feature={feature}
+            control={control}
+            options={optionControls.options}
             disabled={disabled}
             openSelector={openSelector}
             handleOpenChange={handleOpenChange}
-            onSetFeature={onSetFeature}
+            onSetOption={optionControls.onSetOption}
             onActionComplete={onDropdownClose}
           />
         ))
@@ -1110,8 +1116,7 @@ interface SheetAgentControlsContentProps {
   provider: string;
   selectedModelId?: string;
   selectedThinkingOptionId?: string;
-  features?: AgentFeature[];
+  optionControls?: ComposerOptionControls;
-  onSetFeature?: (featureId: string, value: unknown) => void;
   onApplyAgentProfile?: (profileId: string) => void;
   onEditAgentProfiles?: () => void;
   onCreateAgentProfile?: (seed: AgentProfileSeed) => void;
@@ -1154,8 +1159,7 @@ function SheetAgentControlsContent(props: SheetAgentControlsContentProps) {
     provider,
     selectedModelId,
     selectedThinkingOptionId,
-    features,
+    optionControls,
-    onSetFeature,
     onApplyAgentProfile,
     onEditAgentProfiles,
     onCreateAgentProfile,
@@ -1188,6 +1192,7 @@ function SheetAgentControlsContent(props: SheetAgentControlsContentProps) {
   } = props;
 
   const thinkingAnchorRef = useRef<View | null>(null);
+  const sheetOptions = optionControls?.options ?? EMPTY_OPTIONS;
 
   const hasThinking = comboboxThinkingOptions.length > 0;
 
@@ -1238,14 +1243,15 @@ function SheetAgentControlsContent(props: SheetAgentControlsContentProps) {
 
       {modeControl ? <AgentModeControl {...modeControl} surface="sheet" /> : null}
 
-      {(features ?? []).map((feature) => (
+      {(optionControls?.controls ?? []).map((control) => (
         <SheetFeatureItem
-          key={`feature-${feature.id}`}
+          key={`feature-${control.key}`}
-          feature={feature}
+          control={control}
+          options={sheetOptions}
           disabled={disabled}
           openSelector={openSelector}
           handleOpenChange={handleOpenChange}
-          onSetFeature={onSetFeature}
+          onSetOption={optionControls?.onSetOption}
         />
       ))}
     </View>
@@ -1279,22 +1285,24 @@ function SheetAgentControlsContent(props: SheetAgentControlsContentProps) {
 }
 
 function DesktopFeatureItem({
-  feature,
+  control,
+  options,
   disabled,
   openSelector,
   handleOpenChange,
-  onSetFeature,
+  onSetOption,
   onActionComplete,
 }: {
-  feature: AgentFeature;
+  control: AgentOptionControl;
+  options: ProviderOptions;
   disabled: boolean;
   openSelector: AgentControlSelector | null;
   handleOpenChange: (selector: AgentControlSelector) => (nextOpen: boolean) => void;
-  onSetFeature?: (featureId: string, value: unknown) => void;
+  onSetOption?: (key: string, value: unknown) => void;
   onActionComplete?: () => void;
 }) {
   const { theme } = useUnistyles();
-  const featureSelector: AgentControlSelector = `feature-${feature.id}`;
+  const featureSelector: AgentControlSelector = `feature-${control.key}`;
   const featureAnchorRef = useRef<View>(null);
 
   const handleFeatureOpenChange = useMemo(
@@ -1307,120 +1315,117 @@ function DesktopFeatureItem({
   );
 
   const handleTogglePress = useCallback(() => {
-    if (feature.type === "toggle") {
+    if (control.type === "toggle") {
-      onSetFeature?.(feature.id, !feature.value);
+      onSetOption?.(control.key, !readToggleOption(control, options));
       onActionComplete?.();
     }
-  }, [feature, onActionComplete, onSetFeature]);
+  }, [control, onActionComplete, onSetOption, options]);
 
   const handleSelectOption = useCallback(
-    (optionId: string) => {
+    (choiceValue: string) => {
-      onSetFeature?.(feature.id, optionId);
+      onSetOption?.(control.key, choiceValue);
     },
-    [feature.id, onSetFeature],
+    [control.key, onSetOption],
   );
   const comboboxOptions = useMemo<ComboboxOption[]>(
     () =>
-      feature.type === "select"
+      control.type === "select"
-        ? feature.options.map((option) => ({ id: option.id, label: option.label }))
+        ? control.choices.map((choice) => ({ id: choice.value, label: choice.label }))
         : [],
-    [feature],
+    [control],
   );
 
-  if (feature.type === "toggle") {
+  const FeatureIcon = getAgentFeatureIcon(control.icon);
-    const FeatureIcon = getAgentFeatureIcon(feature.icon);
+  const iconColor = getFeatureIconColor(
+    control,
+    options,
+    theme.colors.palette,
+    theme.colors.foregroundMuted,
+  );
+
+  if (control.type === "toggle") {
     return (
       <Tooltip delayDuration={0} enabledOnDesktop enabledOnMobile={false}>
         <TooltipTrigger asChild triggerRefProp="ref">
           <AgentControlTrigger
             icon={FeatureIcon}
-            iconColor={getFeatureIconColor(
+            iconColor={iconColor}
-              feature,
-              theme.colors.palette,
-              theme.colors.foregroundMuted,
-            )}
             surface="toolbar"
-            label={feature.label}
+            label={control.label}
             showToolbarLabel={false}
             disabled={disabled}
             onPress={handleTogglePress}
-            accessibilityLabel={getFeatureTooltip(feature)}
+            accessibilityLabel={getControlTooltip(control)}
-            testID={`agent-feature-${feature.id}`}
+            testID={`agent-feature-${control.key}`}
           />
         </TooltipTrigger>
         <TooltipContent side="top" align="center" offset={8}>
-          <Text style={styles.tooltipText}>{getFeatureTooltip(feature)}</Text>
+          <Text style={styles.tooltipText}>{getControlTooltip(control)}</Text>
         </TooltipContent>
       </Tooltip>
     );
   }
 
-  if (feature.type === "select") {
+  const selectedValue = readSelectOption(control, options);
-    const FeatureIcon = getAgentFeatureIcon(feature.icon);
+  const selectedChoice = control.choices.find((choice) => choice.value === selectedValue);
-    const selectedOption = feature.options.find((o) => o.id === feature.value);
+  const iconOnly = control.desktopTrigger === "icon";
-    const iconOnly = feature.desktopTrigger === "icon";
+  const tooltip = iconOnly
-    const tooltip = iconOnly
+    ? `${control.label}: ${selectedChoice?.label ?? control.label}`
-      ? `${feature.label}: ${selectedOption?.label ?? feature.label}`
+    : getControlTooltip(control);
-      : getFeatureTooltip(feature);
+  return (
-    return (
+    <>
-      <>
+      <Tooltip delayDuration={0} enabledOnDesktop enabledOnMobile={false}>
-        <Tooltip delayDuration={0} enabledOnDesktop enabledOnMobile={false}>
+        <TooltipTrigger asChild triggerRefProp="ref">
-          <TooltipTrigger asChild triggerRefProp="ref">
+          <AgentControlTrigger
-            <AgentControlTrigger
+            ref={featureAnchorRef}
-              ref={featureAnchorRef}
+            icon={FeatureIcon}
-              icon={FeatureIcon}
+            iconColor={iconColor}
-              iconColor={getFeatureIconColor(
+            surface="toolbar"
-                feature,
+            label={control.label}
-                theme.colors.palette,
+            value={selectedChoice?.label ?? control.label}
-                theme.colors.foregroundMuted,
+            showToolbarLabel={!iconOnly}
-              )}
+            open={openSelector === featureSelector}
-              surface="toolbar"
+            disabled={disabled}
-              label={feature.label}
+            onPress={handleSelectPress}
-              value={selectedOption?.label ?? feature.label}
+            accessibilityLabel={tooltip}
-              showToolbarLabel={!iconOnly}
+            testID={`agent-feature-${control.key}`}
-              open={openSelector === featureSelector}
+          />
-              disabled={disabled}
+        </TooltipTrigger>
-              onPress={handleSelectPress}
+        <TooltipContent side="top" align="center" offset={8}>
-              accessibilityLabel={tooltip}
+          <Text style={styles.tooltipText}>{tooltip}</Text>
-              testID={`agent-feature-${feature.id}`}
+        </TooltipContent>
-            />
+      </Tooltip>
-          </TooltipTrigger>
+      <Combobox
-          <TooltipContent side="top" align="center" offset={8}>
+        options={comboboxOptions}
-            <Text style={styles.tooltipText}>{tooltip}</Text>
+        value={String(selectedValue)}
-          </TooltipContent>
+        onSelect={handleSelectOption}
-        </Tooltip>
+        open={openSelector === featureSelector}
-        <Combobox
+        onOpenChange={handleFeatureOpenChange}
-          options={comboboxOptions}
+        anchorRef={featureAnchorRef}
-          value={String(feature.value)}
+        desktopPlacement="top-start"
-          onSelect={handleSelectOption}
+      />
-          open={openSelector === featureSelector}
+    </>
-          onOpenChange={handleFeatureOpenChange}
+  );
-          anchorRef={featureAnchorRef}
-          desktopPlacement="top-start"
-        />
-      </>
-    );
-  }
-
-  return null;
 }
 
 function SheetFeatureItem({
-  feature,
+  control,
+  options,
   disabled,
   openSelector,
   handleOpenChange,
-  onSetFeature,
+  onSetOption,
 }: {
-  feature: AgentFeature;
+  control: AgentOptionControl;
+  options: ProviderOptions;
   disabled: boolean;
   openSelector: AgentControlSelector | null;
   handleOpenChange: (selector: AgentControlSelector) => (nextOpen: boolean) => void;
-  onSetFeature?: (featureId: string, value: unknown) => void;
+  onSetOption?: (key: string, value: unknown) => void;
 }) {
   const { theme } = useUnistyles();
   const { t } = useTranslation();
-  const featureSelector: AgentControlSelector = `feature-${feature.id}`;
+  const featureSelector: AgentControlSelector = `feature-${control.key}`;
   const featureAnchorRef = useRef<View>(null);
 
   const handleFeatureOpenChange = useMemo(
@@ -1431,97 +1436,71 @@ function SheetFeatureItem({
     () => handleFeatureOpenChange(openSelector !== featureSelector),
     [featureSelector, handleFeatureOpenChange, openSelector],
   );
-  const sheetHeader = useMemo<SheetHeader>(() => ({ title: feature.label }), [feature.label]);
+  const sheetHeader = useMemo<SheetHeader>(() => ({ title: control.label }), [control.label]);
 
   const handleSelectOption = useCallback(
-    (optionId: string) => {
+    (choiceValue: string) => {
-      onSetFeature?.(feature.id, feature.type === "toggle" ? optionId === "true" : optionId);
+      onSetOption?.(control.key, control.type === "toggle" ? choiceValue === "true" : choiceValue);
     },
-    [feature.id, feature.type, onSetFeature],
+    [control.key, control.type, onSetOption],
   );
   const comboboxOptions = useMemo<ComboboxOption[]>(() => {
-    if (feature.type === "select") {
+    if (control.type === "select") {
-      return feature.options.map((option) => ({ id: option.id, label: option.label }));
+      return control.choices.map((choice) => ({ id: choice.value, label: choice.label }));
     }
     return [
       { id: "true", label: t("agentControls.features.on") },
       { id: "false", label: t("agentControls.features.off") },
     ];
-  }, [feature, t]);
+  }, [control, t]);
 
-  if (feature.type === "toggle") {
+  const FeatureIcon = getAgentFeatureIcon(control.icon);
-    const FeatureIcon = getAgentFeatureIcon(feature.icon);
+  const iconColor = getFeatureIconColor(
-    return (
+    control,
-      <>
+    options,
-        <AgentControlTrigger
+    theme.colors.palette,
-          ref={featureAnchorRef}
+    theme.colors.foregroundMuted,
-          icon={FeatureIcon}
+  );
-          iconColor={getFeatureIconColor(
+  let selectedValue: string;
-            feature,
+  let displayValue: string;
-            theme.colors.palette,
+  if (control.type === "toggle") {
-            theme.colors.foregroundMuted,
+    const isOn = readToggleOption(control, options);
-          )}
+    selectedValue = String(isOn);
-          surface="sheet"
+    displayValue = isOn ? t("agentControls.features.on") : t("agentControls.features.off");
-          label={feature.label}
+  } else {
-          value={feature.value ? t("agentControls.features.on") : t("agentControls.features.off")}
+    const selected = readSelectOption(control, options);
-          open={openSelector === featureSelector}
+    selectedValue = String(selected);
-          disabled={disabled}
+    displayValue =
-          onPress={handleSelectPress}
+      control.choices.find((choice) => choice.value === selected)?.label ?? control.label;
-          accessibilityLabel={getFeatureTooltip(feature)}
-          testID={`agent-feature-${feature.id}`}
-        />
-        <Combobox
-          options={comboboxOptions}
-          value={String(feature.value)}
-          onSelect={handleSelectOption}
-          open={openSelector === featureSelector}
-          onOpenChange={handleFeatureOpenChange}
-          anchorRef={featureAnchorRef}
-          presentation="push"
-          searchable={false}
-          header={sheetHeader}
-        />
-      </>
-    );
   }
-
+  return (
-  if (feature.type === "select") {
+    <>
-    const FeatureIcon = getAgentFeatureIcon(feature.icon);
+      <AgentControlTrigger
-    const selectedOption = feature.options.find((o) => o.id === feature.value);
+        ref={featureAnchorRef}
-    return (
+        icon={FeatureIcon}
-      <>
+        iconColor={iconColor}
-        <AgentControlTrigger
+        surface="sheet"
-          ref={featureAnchorRef}
+        label={control.label}
-          icon={FeatureIcon}
+        value={displayValue}
-          iconColor={getFeatureIconColor(
+        open={openSelector === featureSelector}
-            feature,
+        disabled={disabled}
-            theme.colors.palette,
+        onPress={handleSelectPress}
-            theme.colors.foregroundMuted,
+        accessibilityLabel={getControlTooltip(control)}
-          )}
+        testID={`agent-feature-${control.key}`}
-          surface="sheet"
+      />
-          label={feature.label}
+      <Combobox
-          value={selectedOption?.label ?? feature.label}
+        options={comboboxOptions}
-          open={openSelector === featureSelector}
+        value={selectedValue}
-          disabled={disabled}
+        onSelect={handleSelectOption}
-          onPress={handleSelectPress}
+        open={openSelector === featureSelector}
-          accessibilityLabel={getFeatureTooltip(feature)}
+        onOpenChange={handleFeatureOpenChange}
-          testID={`agent-feature-${feature.id}`}
+        anchorRef={featureAnchorRef}
-        />
+        presentation="push"
-        <Combobox
+        searchable={control.type === "toggle" ? false : undefined}
-          options={comboboxOptions}
+        header={sheetHeader}
-          value={String(feature.value)}
+      />
-          onSelect={handleSelectOption}
+    </>
-          open={openSelector === featureSelector}
+  );
-          onOpenChange={handleFeatureOpenChange}
-          anchorRef={featureAnchorRef}
-          presentation="push"
-          header={sheetHeader}
-        />
-      </>
-    );
-  }
-
-  return null;
 }
 
 function ThinkingComboboxOption({
@@ -1549,6 +1528,18 @@ function ThinkingComboboxOption({
   );
 }
 
+function useAgentOptionControls(
+  agent: { controls?: AgentOptionControl[]; options?: ProviderOptions } | null | undefined,
+  onSetOption: ComposerOptionControls["onSetOption"],
+): ComposerOptionControls {
+  const controls = agent?.controls;
+  const options = agent?.options;
+  return useMemo(
+    () => ({ controls: controls ?? [], options: options ?? EMPTY_OPTIONS, onSetOption }),
+    [controls, onSetOption, options],
+  );
+}
+
 export const AgentControls = memo(function AgentControls({
   agentId,
   serverId,
@@ -1700,8 +1691,8 @@ export const AgentControls = memo(function AgentControls({
     [activeModelId, agentId, agentProvider, client, toast, updatePreferences],
   );
 
-  const handleSetFeature = useCallback(
+  const handleSetOption = useCallback(
-    (featureId: string, value: unknown) => {
+    (key: string, value: unknown) => {
       if (!client || !agentProvider) {
         return;
       }
@@ -1710,22 +1701,24 @@ export const AgentControls = memo(function AgentControls({
           preferences: current,
           provider: agentProvider,
           updates: {
-            featureValues: {
+            options: {
-              [featureId]: value,
+              [key]: value,
             },
           },
         }),
       ).catch((error) => {
-        console.warn("[AgentControls] persist feature preference failed", error);
+        console.warn("[AgentControls] persist option preference failed", error);
       });
-      void client.setAgentFeature(agentId, featureId, value).catch((error) => {
+      void client.setAgentOptions(agentId, { [key]: value }).catch((error) => {
-        console.warn("[AgentControls] setAgentFeature failed", error);
+        console.warn("[AgentControls] setAgentOptions failed", error);
         toast.error(toErrorMessage(error));
       });
     },
     [agentId, agentProvider, client, toast, updatePreferences],
   );
 
+  const agentOptionControls = useAgentOptionControls(agent, handleSetOption);
+
   const commandCenterControls = useMemo<AgentControlCommandCenterSource>(
     () => ({
       serverId,
@@ -1744,21 +1737,18 @@ export const AgentControls = memo(function AgentControls({
         select: handleSelectThinkingOption,
       },
       modes: commandCenterModes,
-      features: {
+      optionControls: client ? agentOptionControls : null,
-        list: agent?.features,
-        set: handleSetFeature,
-      },
     }),
     [
       activeModelId,
-      agent?.features,
+      agentOptionControls,
+      client,
       agentId,
       agentModelSelectorProviders,
       agentProvider,
       commandCenterModes,
       handleSelectCommandCenterModel,
       handleSelectThinkingOption,
-      handleSetFeature,
       modeProviderDefinitions,
       modelSelection.selectedThinkingId,
       modelSelection.thinkingOptions,
@@ -1807,8 +1797,7 @@ export const AgentControls = memo(function AgentControls({
         thinkingOptions={thinkingOptions.length > 0 ? thinkingOptions : undefined}
         selectedThinkingOptionId={modelSelection.selectedThinkingId ?? undefined}
         onSelectThinkingOption={handleSelectThinkingOption}
-        features={agent.features}
+        optionControls={agentOptionControls}
-        onSetFeature={handleSetFeature}
         isModelLoading={snapshotIsLoading || selectedProviderIsLoading}
         onModelSelectorOpen={handleModelSelectorOpen}
         onRetryModelProvider={handleRetryModelProvider}
@@ -1840,8 +1829,7 @@ export function DraftAgentControls({
   selectedThinkingOptionId,
   onSelectThinkingOption,
   onApplyAgentProfile,
-  features,
+  optionControls,
-  onSetFeature,
   onDropdownClose,
   onModelSelectorOpen,
   onRetryModelProvider,
@@ -1927,8 +1915,7 @@ export function DraftAgentControls({
         thinkingOptions={mappedThinkingOptions.length > 0 ? mappedThinkingOptions : undefined}
         selectedThinkingOptionId={effectiveSelectedThinkingOption}
         onSelectThinkingOption={onSelectThinkingOption}
-        features={features}
+        optionControls={optionControls}
-        onSetFeature={onSetFeature}
         onDropdownClose={onDropdownClose}
         onModelSelectorOpen={onModelSelectorOpen}
         onRetryModelProvider={onRetryModelProvider}

packages/app/src/composer/agent-controls/utils.test.ts

@@ -1,9 +1,7 @@
 import { describe, expect, it } from "vitest";
 import {
   getFeatureHighlightColor,
-  getFeatureTooltip,
   getAgentControlHintKey,
-  isFeatureActive,
   normalizeModelId,
   resolveAgentModelSelection,
 } from "./utils";
@@ -17,51 +15,12 @@ describe("getAgentControlHintKey", () => {
 });
 
 describe("feature metadata helpers", () => {
-  it("prefers explicit feature tooltip copy", () => {
-    expect(
-      getFeatureTooltip({
-        label: "Plan",
-        tooltip: "Toggle plan mode",
-      }),
-    ).toBe("Toggle plan mode");
-  });
-
-  it("falls back to the feature label when no tooltip is provided", () => {
-    expect(
-      getFeatureTooltip({
-        label: "Custom",
-      }),
-    ).toBe("Custom");
-  });
-
   it("maps feature highlight colors by feature id", () => {
     expect(getFeatureHighlightColor("fast_mode")).toBe("yellow");
     expect(getFeatureHighlightColor("service_tier")).toBe("yellow");
     expect(getFeatureHighlightColor("plan_mode")).toBe("blue");
     expect(getFeatureHighlightColor("other")).toBe("default");
   });
-
-  it("treats a select feature as active when a non-default option is selected", () => {
-    const speed = {
-      type: "select" as const,
-      id: "service_tier",
-      label: "Speed",
-      options: [
-        { id: "default", label: "Normal", isDefault: true },
-        { id: "fast", label: "Fast" },
-      ],
-    };
-    expect(isFeatureActive({ ...speed, value: "default" })).toBe(false);
-    expect(isFeatureActive({ ...speed, value: "fast" })).toBe(true);
-    expect(
-      isFeatureActive({
-        type: "toggle",
-        id: "fast_mode",
-        label: "Fast",
-        value: true,
-      }),
-    ).toBe(true);
-  });
 });
 
 describe("normalizeModelId", () => {

packages/app/src/composer/agent-controls/utils.ts

@@ -1,4 +1,4 @@
-import type { AgentFeature, AgentModelDefinition } from "@getpaseo/protocol/agent-types";
+import type { AgentModelDefinition } from "@getpaseo/protocol/agent-types";
 import { i18n } from "@/i18n/i18next";
 import { formatThinkingOptionLabel } from "@/agent-controls/labels";
 import {
@@ -35,16 +35,6 @@ export function normalizeModelId(modelId: string | null | undefined): string | n
   return normalized;
 }
 
-export function getFeatureTooltip(feature: Pick<AgentFeature, "label" | "tooltip">): string {
-  return feature.tooltip ?? feature.label;
-}
-
-export function isFeatureActive(feature: AgentFeature): boolean {
-  if (feature.type === "toggle") return feature.value;
-  const selectedOption = feature.options.find((option) => option.id === feature.value);
-  return selectedOption !== undefined && !selectedOption.isDefault;
-}
-
 export function getFeatureHighlightColor(featureId: string): FeatureHighlightColor {
   switch (featureId) {
     case FAST_MODE_FEATURE_ID:

packages/app/src/composer/draft/input-draft-core.ts

@@ -20,12 +20,11 @@ export function resolveDraftKey(input: {
 
 export function buildDraftAgentControls(input: {
   formState: UseAgentFormStateResult;
-  features?: DraftAgentControlsProps["features"];
+  optionControls?: DraftAgentControlsProps["optionControls"];
-  onSetFeature?: DraftAgentControlsProps["onSetFeature"];
   onApplyAgentProfile: DraftAgentControlsProps["onApplyAgentProfile"];
   onDropdownClose?: DraftAgentControlsProps["onDropdownClose"];
 }): DraftAgentControlsProps {
-  const { formState, features, onSetFeature, onApplyAgentProfile, onDropdownClose } = input;
+  const { formState, optionControls, onApplyAgentProfile, onDropdownClose } = input;
   return {
     providerDefinitions: formState.providerDefinitions,
     selectedProvider: formState.selectedProvider,
@@ -43,8 +42,7 @@ export function buildDraftAgentControls(input: {
     selectedThinkingOptionId: formState.selectedThinkingOptionId,
     onSelectThinkingOption: formState.setThinkingOptionFromUser,
     onApplyAgentProfile,
-    features,
+    optionControls,
-    onSetFeature,
     onDropdownClose,
     onModelSelectorOpen: formState.refetchProviderModelsIfStale,
     onRetryModelProvider: formState.refreshProviderModels,

packages/app/src/composer/draft/input-draft.ts

@@ -8,7 +8,7 @@ import {
   type CreateAgentInitialValues,
   type UseAgentFormStateResult,
 } from "@/hooks/use-agent-form-state";
-import { useDraftAgentFeatures } from "@/hooks/use-draft-agent-features";
+import { useDraftProviderOptions } from "@/hooks/use-draft-provider-options";
 import {
   buildDraftAgentControls,
   hasDraftContent,
@@ -35,7 +35,7 @@ type AttachmentUpdater =
 interface AgentInputDraftComposerOptions {
   initialServerId: string | null;
   initialValues?: CreateAgentInitialValues;
-  initialFeatureValues?: Record<string, unknown>;
+  initialProviderOptions?: Record<string, unknown>;
   isVisible?: boolean;
   lockedWorkingDir?: string;
 }
@@ -50,7 +50,7 @@ type DraftComposerState = UseAgentFormStateResult & {
   effectiveModeId: string;
   effectiveModelId: string;
   effectiveThinkingOptionId: string;
-  featureValues: Record<string, unknown> | undefined;
+  providerOptions: Record<string, unknown> | undefined;
   agentControls: DraftAgentControlsProps;
   commandDraft: DraftCommandTarget;
 };
@@ -274,26 +274,25 @@ export function useAgentInputDraft(input: UseAgentInputDraftInput): AgentInputDr
   );
 
   const {
-    features: draftFeatures,
+    optionControls: draftOptionControls,
-    featureValues: draftFeatureValues,
+    options: draftOptions,
-    setFeatureValue: setDraftFeatureValue,
+    applyProfile: applyProfileOptions,
-    applyProfileFeatureValues,
+  } = useDraftProviderOptions({
-  } = useDraftAgentFeatures({
     serverId: formState.selectedServerId,
     provider: formState.selectedProvider,
     cwd: workingDir,
     modeId: formState.selectedMode,
     modelId: effectiveModelId,
     thinkingOptionId: effectiveThinkingOptionId,
-    initialFeatureValues: composerOptions?.initialFeatureValues,
+    initialOptions: composerOptions?.initialProviderOptions,
   });
 
   const applyDraftAgentProfile = useCallback(
     (profile: Parameters<typeof formState.applyProfileFromUser>[0]) => {
       formState.applyProfileFromUser(profile);
-      applyProfileFeatureValues(profile.featureValues);
+      applyProfileOptions({ provider: profile.provider, options: profile.options });
     },
-    [applyProfileFeatureValues, formState],
+    [applyProfileOptions, formState],
   );
 
   const commandDraft = useMemo(
@@ -303,15 +302,9 @@ export function useAgentInputDraft(input: UseAgentInputDraftInput): AgentInputDr
         cwd: workingDir,
         effectiveModelId,
         effectiveThinkingOptionId,
-        featureValues: draftFeatureValues,
+        providerOptions: draftOptions,
       }),
-    [
+    [effectiveModelId, effectiveThinkingOptionId, draftOptions, providerSelection, workingDir],
-      effectiveModelId,
-      effectiveThinkingOptionId,
-      draftFeatureValues,
-      providerSelection,
-      workingDir,
-    ],
   );
 
   const composerState = useMemo<DraftComposerState | null>(() => {
@@ -325,11 +318,10 @@ export function useAgentInputDraft(input: UseAgentInputDraftInput): AgentInputDr
       effectiveModeId,
       effectiveModelId,
       effectiveThinkingOptionId,
-      featureValues: draftFeatureValues,
+      providerOptions: draftOptions,
       agentControls: buildDraftAgentControls({
         formState,
-        features: draftFeatures,
+        optionControls: draftOptionControls,
-        onSetFeature: setDraftFeatureValue,
         onApplyAgentProfile: applyDraftAgentProfile,
       }),
       commandDraft,
@@ -340,11 +332,10 @@ export function useAgentInputDraft(input: UseAgentInputDraftInput): AgentInputDr
     effectiveModeId,
     effectiveModelId,
     effectiveThinkingOptionId,
-    draftFeatures,
+    draftOptionControls,
-    draftFeatureValues,
+    draftOptions,
     applyDraftAgentProfile,
     formState,
-    setDraftFeatureValue,
     workingDir,
   ]);
 

packages/app/src/composer/draft/workspace-tab.tsx

@@ -1,3 +1,4 @@
+import type { ComposerOptionControls } from "@/agent-controls/option-controls";
 import { useCallback, useEffect, useMemo, useRef } from "react";
 import { Keyboard, ScrollView, StyleSheet as RNStyleSheet, Text, View } from "react-native";
 import { useTranslation } from "react-i18next";
@@ -65,7 +66,7 @@ interface AutoSubmitConfig {
   modeId: string | null;
   model: string | null;
   thinkingOptionId: string | null;
-  featureValues: Record<string, unknown>;
+  providerOptions: Record<string, unknown>;
 }
 
 function resolveAutoSubmitConfig(
@@ -74,7 +75,7 @@ function resolveAutoSubmitConfig(
     modeId?: string | null;
     model?: string | null;
     thinkingOptionId?: string | null;
-    featureValues?: Record<string, unknown>;
+    providerOptions?: Record<string, unknown>;
   } | null,
 ): AutoSubmitConfig | null {
   if (!pending) return null;
@@ -83,7 +84,7 @@ function resolveAutoSubmitConfig(
     modeId: pending.modeId ?? null,
     model: pending.model ?? null,
     thinkingOptionId: pending.thinkingOptionId ?? null,
-    featureValues: pending.featureValues ?? {},
+    providerOptions: pending.providerOptions ?? {},
   };
 }
 
@@ -131,7 +132,7 @@ async function submitDraftCreateRequest(input: {
     effectiveModeId: string;
     effectiveModelId: string | null;
     effectiveThinkingOptionId: string | null;
-    featureValues: Record<string, unknown> | undefined;
+    providerOptions: Record<string, unknown> | undefined;
   };
   hostDisconnectedMessage: string;
   selectModelMessage: string;
@@ -170,7 +171,7 @@ async function submitDraftCreateRequest(input: {
     model: autoSubmitConfig?.model ?? (composerState.effectiveModelId || undefined),
     thinkingOptionId:
       autoSubmitConfig?.thinkingOptionId ?? (composerState.effectiveThinkingOptionId || undefined),
-    featureValues: autoSubmitConfig?.featureValues ?? composerState.featureValues,
+    providerOptions: autoSubmitConfig?.providerOptions ?? composerState.providerOptions,
   });
 
   const attachmentsArray = Array.isArray(attachments) ? attachments : undefined;
@@ -204,7 +205,7 @@ function buildDraftAgentSnapshot(input: {
     effectiveThinkingOptionId: string | null;
     effectiveModeId: string;
     selectedProvider: string | null;
-    agentControls: { features?: Agent["features"] };
+    agentControls: { optionControls?: ComposerOptionControls };
   };
   selectModelMessage: string;
 }): Agent {
@@ -241,7 +242,8 @@ function buildDraftAgentSnapshot(input: {
     title: "Agent",
     cwd: workspaceDirectory,
     model,
-    features: composerState.agentControls.features,
+    options: composerState.agentControls.optionControls?.options,
+    controls: composerState.agentControls.optionControls?.controls,
     thinkingOptionId,
     parentAgentId: null,
     labels: {},
@@ -333,7 +335,7 @@ export function WorkspaceDraftAgentTab({
     composer: {
       initialServerId: serverId,
       initialValues: draftInitialValues,
-      initialFeatureValues: draftSetup?.featureValues,
+      initialProviderOptions: draftSetup?.providerOptions,
       isVisible: true,
       lockedWorkingDir: draftWorkingDirectory ?? undefined,
     },
@@ -351,8 +353,7 @@ export function WorkspaceDraftAgentTab({
   const draftModeOptions = composerState.modeOptions;
   const draftSelectedMode = composerState.selectedMode;
   const draftSetMode = composerState.setModeFromUser;
-  const draftFeatures = composerState.agentControls.features;
+  const draftOptionControls = composerState.agentControls.optionControls;
-  const draftOnSetFeature = composerState.agentControls.onSetFeature;
 
   const clearDraftInput = draftInput.clear;
   const replaceDraftText = draftInput.replaceText;
@@ -521,10 +522,7 @@ export function WorkspaceDraftAgentTab({
         selectedId: draftSelectedMode,
         select: draftSetMode,
       },
-      features: {
+      optionControls: draftOptionControls ?? null,
-        list: draftFeatures,
-        set: draftOnSetFeature,
-      },
     },
   });
   const isReadyForPendingAutoSubmit = Boolean(

packages/app/src/create-agent-preferences/preferences.test.ts

@@ -80,7 +80,7 @@ describe("create agent preferences", () => {
         modelId: "gpt-5.5",
         modeId: "full-access",
         thinkingOptionId: "high",
-        featureValues: { fast_mode: true },
+        options: { fast_mode: true },
       }),
     );
 
@@ -95,7 +95,7 @@ describe("create agent preferences", () => {
           model: "gpt-5.5",
           mode: "full-access",
           thinkingByModel: { "gpt-5.5": "high" },
-          featureValues: { fast_mode: true },
+          options: { fast_mode: true },
         },
       },
     });
@@ -119,7 +119,7 @@ describe("create agent preferences", () => {
           model: "gpt-5.6",
           mode: undefined,
           thinkingByModel: undefined,
-          featureValues: undefined,
+          options: undefined,
         },
       }),
     ).toEqual({
@@ -167,13 +167,13 @@ describe("create agent preferences", () => {
         modelId: "one-minute-stream",
         modeId: "approval-test",
         thinkingOptionId: "",
-        featureValues: {},
+        options: {},
       }),
     ).toEqual({
       provider: "mock",
       providerPreferences: {
         pi: { model: "anthropic/sonnet" },
-        mock: { model: "one-minute-stream", mode: "approval-test", featureValues: {} },
+        mock: { model: "one-minute-stream", mode: "approval-test", options: {} },
       },
     });
   });
@@ -208,6 +208,29 @@ describe("create agent preferences", () => {
     });
   });
 
+  it("reads preferences saved as featureValues as options", () => {
+    expect(
+      parseFormPreferences({
+        provider: "codex",
+        providerPreferences: { codex: { featureValues: { service_tier: "priority" } } },
+      }),
+    ).toEqual({
+      provider: "codex",
+      providerPreferences: { codex: { options: { service_tier: "priority" } } },
+    });
+  });
+
+  it("keeps options that are not booleans or strings, such as a profile's sandbox settings", () => {
+    const options = {
+      sandbox_workspace_write: { network_access: true, writable_roots: ["/tmp"] },
+      max_turns: 3,
+    };
+
+    expect(
+      parseFormPreferences({ provider: "codex", providerPreferences: { codex: { options } } }),
+    ).toEqual({ provider: "codex", providerPreferences: { codex: { options } } });
+  });
+
   it("rejects unknown persisted fields outside the explicit legacy shape", () => {
     expect(parseFormPreferences({ provider: "codex", surprise: true })).toEqual({});
   });

packages/app/src/create-agent-preferences/preferences.ts

@@ -1,13 +1,14 @@
 import { z } from "zod";
 import type { AgentProvider } from "@getpaseo/protocol/agent-types";
 
-const featureValuesSchema = z.record(z.string(), z.union([z.boolean(), z.string(), z.null()]));
+const optionsSchema = z.record(z.string(), z.json());
 
 export interface ProviderPreferences {
   model?: string;
   mode?: string;
   thinkingByModel?: Record<string, string>;
-  featureValues?: Record<string, unknown>;
+  /** Last-used values of the provider's option controls, by option key. */
+  options?: Record<string, unknown>;
 }
 
 export type LaunchTarget = { kind: "chat" } | { kind: "terminal"; profileId: string };
@@ -20,12 +21,23 @@ export interface FormPreferences {
   launchTarget?: LaunchTarget;
 }
 
-const providerPreferencesSchema: z.ZodType<ProviderPreferences> = z.strictObject({
+// COMPAT(providerOptionControls): added in v0.15.0, remove after 2027-05-01. Preferences written
-  model: z.string().optional(),
+// before the rename stored the same record as `featureValues`.
-  mode: z.string().optional(),
+function renameLegacyFeatureValues(value: unknown): unknown {
-  thinkingByModel: z.record(z.string(), z.string()).optional(),
+  if (typeof value !== "object" || value === null || !("featureValues" in value)) return value;
-  featureValues: featureValuesSchema.optional(),
+  const { featureValues, ...rest } = value as { featureValues: unknown } & Record<string, unknown>;
-});
+  return "options" in rest ? rest : { ...rest, options: featureValues };
+}
+
+const providerPreferencesSchema: z.ZodType<ProviderPreferences> = z.preprocess(
+  renameLegacyFeatureValues,
+  z.strictObject({
+    model: z.string().optional(),
+    mode: z.string().optional(),
+    thinkingByModel: z.record(z.string(), z.string()).optional(),
+    options: optionsSchema.optional(),
+  }),
+);
 
 const launchTargetSchema: z.ZodType<LaunchTarget> = z.discriminatedUnion("kind", [
   z.strictObject({ kind: z.literal("chat") }),
@@ -116,7 +128,7 @@ function applyProviderPreferenceUpdates(
 ): ProviderPreferences {
   const next: ProviderPreferences = { ...existing };
   const nextThinkingByModel = mergeDefinedRecord(existing.thinkingByModel, updates.thinkingByModel);
-  const nextFeatureValues = mergeDefinedRecord(existing.featureValues, updates.featureValues);
+  const nextOptions = mergeDefinedRecord(existing.options, updates.options);
 
   if (updates.model !== undefined) {
     next.model = updates.model;
@@ -129,8 +141,8 @@ function applyProviderPreferenceUpdates(
   if (nextThinkingByModel !== undefined) {
     next.thinkingByModel = nextThinkingByModel;
   }
-  if (nextFeatureValues !== undefined) {
+  if (nextOptions !== undefined) {
-    next.featureValues = nextFeatureValues;
+    next.options = nextOptions;
   }
 
   return next;
@@ -161,7 +173,7 @@ export function mergeCreateAgentSelectionPreferences(args: {
   modelId?: string | null;
   modeId?: string | null;
   thinkingOptionId?: string | null;
-  featureValues?: Record<string, unknown>;
+  options?: Record<string, unknown>;
 }): FormPreferences {
   if (!args.provider) {
     return args.preferences;
@@ -170,7 +182,7 @@ export function mergeCreateAgentSelectionPreferences(args: {
   const modelId = args.modelId?.trim() ?? "";
   const modeId = args.modeId?.trim() ?? "";
   const thinkingOptionId = args.thinkingOptionId?.trim() ?? "";
-  const featureValues = featureValuesSchema.safeParse(args.featureValues);
+  const options = optionsSchema.safeParse(args.options);
 
   return mergeProviderPreferences({
     preferences: args.preferences,
@@ -179,7 +191,7 @@ export function mergeCreateAgentSelectionPreferences(args: {
       model: modelId || undefined,
       mode: args.modeId === undefined ? undefined : modeId || null,
       ...(modelId && thinkingOptionId ? { thinkingByModel: { [modelId]: thinkingOptionId } } : {}),
-      ...(featureValues.success ? { featureValues: featureValues.data } : {}),
+      ...(options.success ? { options: options.data } : {}),
     },
   });
 }
@@ -192,7 +204,7 @@ export function applyAgentProfilePreferences(args: {
   modelId: string;
   modeId: string;
   thinkingOptionId: string;
-  featureValues: Record<string, unknown>;
+  options: Record<string, unknown>;
 }): FormPreferences {
   let next = args.preferences;
   if (args.previousProvider) {
@@ -215,7 +227,7 @@ export function applyAgentProfilePreferences(args: {
       ...(args.modelId && args.thinkingOptionId
         ? { thinkingByModel: { [args.modelId]: args.thinkingOptionId } }
         : {}),
-      featureValues: args.featureValues,
+      options: args.options,
     },
   });
 }

packages/app/src/hooks/feature-preferences.test.ts

@@ -1,53 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { resolveFeatureValues } from "./feature-preferences";
-
-describe("feature-preferences", () => {
-  const features = [
-    {
-      type: "toggle" as const,
-      id: "fast_mode",
-      label: "Fast",
-      value: false,
-    },
-    {
-      type: "toggle" as const,
-      id: "plan_mode",
-      label: "Plan",
-      value: false,
-    },
-  ];
-
-  it("restores persisted values for available features", () => {
-    expect(
-      resolveFeatureValues({
-        features,
-        persistedFeatureValues: {
-          fast_mode: true,
-          unknown_feature: true,
-        },
-        localFeatureValues: {},
-      }),
-    ).toEqual({
-      fast_mode: true,
-    });
-  });
-
-  it("prefers local values over persisted values", () => {
-    expect(
-      resolveFeatureValues({
-        features,
-        persistedFeatureValues: {
-          fast_mode: true,
-          plan_mode: false,
-        },
-        localFeatureValues: {
-          fast_mode: false,
-        },
-      }),
-    ).toEqual({
-      fast_mode: false,
-      plan_mode: false,
-    });
-  });
-});

packages/app/src/hooks/feature-preferences.ts

@@ -1,60 +0,0 @@
-import type { AgentFeature } from "@getpaseo/protocol/agent-types";
-
-export function pruneFeatureValues(
-  featureValues: Record<string, unknown>,
-  features: AgentFeature[],
-): Record<string, unknown> {
-  const allowedFeatureIds = new Set(features.map((feature) => feature.id));
-  let changed = false;
-  const next: Record<string, unknown> = {};
-
-  for (const [featureId, value] of Object.entries(featureValues)) {
-    if (!allowedFeatureIds.has(featureId)) {
-      changed = true;
-      continue;
-    }
-    next[featureId] = value;
-  }
-
-  return changed ? next : featureValues;
-}
-
-export function applyFeatureValues(
-  features: AgentFeature[],
-  featureValues: Record<string, unknown>,
-): AgentFeature[] {
-  if (Object.keys(featureValues).length === 0) {
-    return features;
-  }
-
-  return features.map((feature) => {
-    if (!Object.prototype.hasOwnProperty.call(featureValues, feature.id)) {
-      return feature;
-    }
-
-    return {
-      ...feature,
-      value: featureValues[feature.id],
-    } as AgentFeature;
-  });
-}
-
-export function resolveFeatureValues(args: {
-  features: AgentFeature[];
-  persistedFeatureValues: Record<string, unknown>;
-  localFeatureValues: Record<string, unknown>;
-}): Record<string, unknown> {
-  const next: Record<string, unknown> = {};
-
-  for (const feature of args.features) {
-    if (Object.prototype.hasOwnProperty.call(args.localFeatureValues, feature.id)) {
-      next[feature.id] = args.localFeatureValues[feature.id];
-      continue;
-    }
-    if (Object.prototype.hasOwnProperty.call(args.persistedFeatureValues, feature.id)) {
-      next[feature.id] = args.persistedFeatureValues[feature.id];
-    }
-  }
-
-  return next;
-}

packages/app/src/hooks/use-agent-autocomplete.ts

@@ -128,14 +128,14 @@ function resolveDraftQueryConfig(draft?: DraftCommandTarget): DraftCommandConfig
   const modeId = draftConfig.modeId?.trim() ?? "";
   const model = draftConfig.model?.trim() ?? "";
   const thinkingOptionId = draftConfig.thinkingOptionId?.trim() ?? "";
-  const featureValues = draftConfig.featureValues;
+  const providerOptions = draftConfig.providerOptions;
   return {
     provider: draftConfig.provider,
     cwd,
     ...(modeId ? { modeId } : {}),
     ...(model ? { model } : {}),
     ...(thinkingOptionId ? { thinkingOptionId } : {}),
-    ...(featureValues && Object.keys(featureValues).length > 0 ? { featureValues } : {}),
+    ...(providerOptions && Object.keys(providerOptions).length > 0 ? { providerOptions } : {}),
   };
 }
 

packages/app/src/hooks/use-agent-form-state.ts

@@ -352,7 +352,7 @@ export function useAgentFormState(options: UseAgentFormStateOptions): UseAgentFo
           modelId: model,
           modeId,
           thinkingOptionId,
-          featureValues: profile.featureValues,
+          options: profile.options,
         });
       }).catch((error) => {
         console.warn("[useAgentFormState] persist profile preference failed", error);

packages/app/src/hooks/use-agent-screen-state-machine.ts

@@ -1,9 +1,6 @@
 import { useRef } from "react";
-import type {
+import type { AgentCapabilityFlags, AgentProvider } from "@getpaseo/protocol/agent-types";
-  AgentCapabilityFlags,
+import type { Agent } from "@/stores/session-store";
-  AgentFeature,
-  AgentProvider,
-} from "@getpaseo/protocol/agent-types";
 import type { ViewedTimelineStatus } from "@/timeline/viewed-timeline-sync";
 
 export interface AgentScreenAgent {
@@ -22,7 +19,8 @@ export interface AgentScreenAgent {
     modeId?: string | null;
     thinkingOptionId?: string | null;
   } | null;
-  features?: readonly AgentFeature[];
+  options?: Agent["options"];
+  controls?: Agent["controls"];
   lastError?: string | null;
   projectPlacement?: {
     projectKey?: string;

packages/app/src/hooks/use-draft-agent-features.ts

@@ -1,159 +0,0 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { useQuery } from "@tanstack/react-query";
-import { useTranslation } from "react-i18next";
-import type { AgentProvider, AgentSessionConfig } from "@getpaseo/protocol/agent-types";
-import { useHostRuntimeClient, useHostRuntimeIsConnected } from "@/runtime/host-runtime";
-import { mergeProviderPreferences, useFormPreferences } from "./use-form-preferences";
-import {
-  applyFeatureValues,
-  pruneFeatureValues,
-  resolveFeatureValues,
-} from "./feature-preferences";
-
-type DraftFeatureConfig = Pick<
-  AgentSessionConfig,
-  "provider" | "cwd" | "modeId" | "model" | "thinkingOptionId"
->;
-
-export function useDraftAgentFeatures(input: {
-  serverId: string | null | undefined;
-  provider: AgentProvider | null;
-  cwd: string | null | undefined;
-  modeId: string | null | undefined;
-  modelId: string | null | undefined;
-  thinkingOptionId: string | null | undefined;
-  initialFeatureValues?: Record<string, unknown>;
-}) {
-  const { t } = useTranslation();
-  const { serverId, provider, cwd, modeId, modelId, thinkingOptionId, initialFeatureValues } =
-    input;
-  const [localFeatureValues, setLocalFeatureValues] = useState<Record<string, unknown>>(
-    () => initialFeatureValues ?? {},
-  );
-  const client = useHostRuntimeClient(serverId ?? "");
-  const isConnected = useHostRuntimeIsConnected(serverId ?? "");
-  const { preferences, updatePreferences } = useFormPreferences();
-  const normalizedCwd = cwd?.trim() || "";
-  const normalizedProvider = provider ?? null;
-  const previousProviderRef = useRef<AgentProvider | null>(normalizedProvider);
-  const persistedFeatureValues = useMemo(
-    () => (provider ? (preferences.providerPreferences?.[provider]?.featureValues ?? {}) : {}),
-    [preferences.providerPreferences, provider],
-  );
-
-  const draftConfig = useMemo<DraftFeatureConfig | null>(() => {
-    if (!normalizedProvider || !normalizedCwd) {
-      return null;
-    }
-
-    return {
-      provider: normalizedProvider,
-      cwd: normalizedCwd,
-      ...(modeId ? { modeId } : {}),
-      ...(modelId ? { model: modelId } : {}),
-      ...(thinkingOptionId ? { thinkingOptionId } : {}),
-    };
-  }, [modeId, modelId, normalizedCwd, normalizedProvider, thinkingOptionId]);
-
-  const featuresQuery = useQuery({
-    queryKey: [
-      "providerFeatures",
-      serverId ?? null,
-      normalizedProvider,
-      normalizedCwd || null,
-      modeId ?? null,
-      modelId ?? null,
-      thinkingOptionId ?? null,
-    ],
-    enabled: Boolean(serverId && client && isConnected && draftConfig),
-    staleTime: 5 * 60 * 1000,
-    queryFn: async () => {
-      if (!client || !draftConfig) {
-        throw new Error(t("workspace.terminal.hostDisconnected"));
-      }
-      const payload = await client.listProviderFeatures(draftConfig);
-      if (payload.error) {
-        throw new Error(payload.error);
-      }
-      return payload.features ?? [];
-    },
-  });
-  const availableFeaturesRaw = featuresQuery.data;
-  const availableFeatures = useMemo(() => availableFeaturesRaw ?? [], [availableFeaturesRaw]);
-  const featureValues = useMemo(
-    () =>
-      resolveFeatureValues({
-        features: availableFeatures,
-        persistedFeatureValues,
-        localFeatureValues,
-      }),
-    [availableFeatures, localFeatureValues, persistedFeatureValues],
-  );
-
-  const features = useMemo(() => {
-    return applyFeatureValues(availableFeatures, featureValues);
-  }, [availableFeatures, featureValues]);
-
-  useEffect(() => {
-    const previousProvider = previousProviderRef.current;
-    previousProviderRef.current = normalizedProvider;
-    if (previousProvider === null) {
-      return;
-    }
-    if (previousProvider !== normalizedProvider) {
-      setLocalFeatureValues({});
-    }
-  }, [normalizedProvider]);
-
-  useEffect(() => {
-    if (availableFeaturesRaw === undefined) {
-      return;
-    }
-    const next = pruneFeatureValues(localFeatureValues, availableFeatures);
-    if (next !== localFeatureValues) {
-      setLocalFeatureValues(next);
-    }
-  }, [availableFeatures, availableFeaturesRaw, localFeatureValues]);
-
-  const effectiveFeatureValues = Object.keys(featureValues).length > 0 ? featureValues : undefined;
-  const setFeatureValue = useCallback(
-    (featureId: string, value: unknown) => {
-      setLocalFeatureValues((current) => {
-        if (Object.is(current[featureId], value)) {
-          return current;
-        }
-
-        return { ...current, [featureId]: value };
-      });
-      if (!provider) {
-        return;
-      }
-      void updatePreferences((current) =>
-        mergeProviderPreferences({
-          preferences: current,
-          provider,
-          updates: {
-            featureValues: {
-              [featureId]: value,
-            },
-          },
-        }),
-      ).catch((error) => {
-        console.warn("[useDraftAgentFeatures] persist feature preference failed", error);
-      });
-    },
-    [provider, updatePreferences],
-  );
-
-  const applyProfileFeatureValues = useCallback((values: Record<string, unknown>) => {
-    setLocalFeatureValues(values);
-  }, []);
-
-  return {
-    features,
-    featureValues: effectiveFeatureValues,
-    isLoading: featuresQuery.isLoading,
-    setFeatureValue,
-    applyProfileFeatureValues,
-  };
-}

packages/app/src/hooks/use-draft-provider-options.ts

@@ -0,0 +1,109 @@
+import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { useTranslation } from "react-i18next";
+import type { AgentProvider, ProviderOptions } from "@getpaseo/protocol/agent-types";
+import {
+  draftControlsRequest,
+  openDraftOptions,
+  ownDraftOptions,
+  viewDraftOptions,
+} from "@/agent-controls/draft-options-model";
+import type { ComposerOptionControls } from "@/agent-controls/option-controls";
+import { useFetchQuery } from "@/data/query";
+import { useHostRuntimeClient, useHostRuntimeIsConnected } from "@/runtime/host-runtime";
+import { mergeProviderPreferences, useFormPreferences } from "./use-form-preferences";
+
+/**
+ * Adapter between a draft's options model and the screen: it sends the model's complete options
+ * to the daemon, hands the answer back, and persists the user's toggles as last-used values.
+ */
+export function useDraftProviderOptions(input: {
+  serverId: string | null | undefined;
+  provider: AgentProvider | null;
+  cwd: string | null | undefined;
+  modeId: string | null | undefined;
+  modelId: string | null | undefined;
+  thinkingOptionId: string | null | undefined;
+  initialOptions?: ProviderOptions;
+}) {
+  const { t } = useTranslation();
+  const { serverId, provider, cwd, modeId, modelId, thinkingOptionId, initialOptions } = input;
+  const [model] = useState(() => openDraftOptions({ provider, seed: initialOptions }));
+  const state = useSyncExternalStore(model.subscribe, model.getState, model.getState);
+  const client = useHostRuntimeClient(serverId ?? "");
+  const isConnected = useHostRuntimeIsConnected(serverId ?? "");
+  const { preferences, updatePreferences } = useFormPreferences();
+  const normalizedCwd = cwd?.trim() || "";
+  const persisted = preferences.providerPreferences?.[provider ?? ""]?.options;
+
+  useEffect(() => model.observeProvider(provider), [model, provider]);
+  useEffect(() => model.setRemembered(persisted ?? {}), [model, persisted]);
+
+  const ownOptions = ownDraftOptions(state);
+  const draftConfig = useMemo(
+    () =>
+      draftControlsRequest(state, {
+        provider,
+        cwd: normalizedCwd,
+        modeId,
+        modelId,
+        thinkingOptionId,
+      }),
+    [modeId, modelId, normalizedCwd, provider, state, thinkingOptionId],
+  );
+  const queryKey = useMemo(
+    () => ["providerControls", serverId ?? null, draftConfig],
+    [draftConfig, serverId],
+  );
+  const requestKey = JSON.stringify(queryKey);
+
+  const { data } = useFetchQuery({
+    queryKey,
+    dataShape: "value",
+    staleTimeMs: 5 * 60 * 1000,
+    enabled: Boolean(serverId && client && isConnected && draftConfig),
+    queryFn: async () => {
+      if (!client || !draftConfig) {
+        throw new Error(t("workspace.terminal.hostDisconnected"));
+      }
+      const payload = await client.listProviderControls(draftConfig);
+      if (payload.error) {
+        throw new Error(payload.error);
+      }
+      return { controls: payload.controls ?? [], options: payload.options ?? {} };
+    },
+  });
+
+  useEffect(() => {
+    if (provider && data) model.applyResolved({ provider, requestKey, ...data });
+  }, [data, model, provider, requestKey]);
+
+  const setOption = useCallback(
+    (key: string, value: unknown) => {
+      model.setOption(key, value);
+      if (!provider) return;
+      void updatePreferences((current) =>
+        mergeProviderPreferences({
+          preferences: current,
+          provider,
+          updates: { options: { [key]: value } },
+        }),
+      ).catch((error) => {
+        console.warn("[useDraftProviderOptions] persist option preference failed", error);
+      });
+    },
+    [model, provider, updatePreferences],
+  );
+
+  const view = viewDraftOptions(state, { provider, requestKey });
+  const viewControls = view?.controls;
+  const viewOptions = view?.options;
+  const optionControls = useMemo<ComposerOptionControls | undefined>(
+    () =>
+      viewControls && viewOptions
+        ? { controls: viewControls, options: viewOptions, onSetOption: setOption }
+        : undefined,
+    [setOption, viewControls, viewOptions],
+  );
+
+  return { optionControls, options: ownOptions, applyProfile: model.applyProfile };
+}

packages/app/src/hooks/use-fork-agent.ts

@@ -36,7 +36,7 @@ export type ForkAgentSource = Pick<
   | "model"
   | "thinkingOptionId"
   | "runtimeInfo"
-  | "features"
+  | "options"
   | "projectPlacement"
 >;
 
@@ -95,18 +95,13 @@ function buildForkDraftSetup(agent: ForkAgentSource): WorkspaceDraftTabSetup | u
     return undefined;
   }
 
-  const featureValues: Record<string, unknown> = {};
-  for (const feature of agent.features ?? []) {
-    featureValues[feature.id] = feature.value;
-  }
-
   return {
     provider: agent.provider,
     cwd: agent.cwd,
     modeId: agent.currentModeId ?? agent.runtimeInfo?.modeId ?? null,
     model: agent.model ?? agent.runtimeInfo?.model ?? null,
     thinkingOptionId: agent.thinkingOptionId ?? agent.runtimeInfo?.thinkingOptionId ?? null,
-    featureValues,
+    providerOptions: { ...agent.options },
   };
 }
 

packages/app/src/hooks/use-form-preferences.test.ts

@@ -63,7 +63,7 @@ describe("mergeProviderPreferences", () => {
           providerPreferences: {
             codex: {
               model: "gpt-5.4",
-              featureValues: {
+              options: {
                 fast_mode: true,
               },
             },
@@ -71,7 +71,7 @@ describe("mergeProviderPreferences", () => {
         },
         provider: "codex",
         updates: {
-          featureValues: {
+          options: {
             plan_mode: true,
           },
         },
@@ -81,7 +81,7 @@ describe("mergeProviderPreferences", () => {
       providerPreferences: {
         codex: {
           model: "gpt-5.4",
-          featureValues: {
+          options: {
             fast_mode: true,
             plan_mode: true,
           },

packages/app/src/panels/agent-panel.tsx

@@ -118,7 +118,8 @@ interface ChatAgentStateShape {
   model?: Agent["model"];
   thinkingOptionId?: Agent["thinkingOptionId"];
   runtimeInfo?: Agent["runtimeInfo"];
-  features?: Agent["features"];
+  options?: Agent["options"];
+  controls?: Agent["controls"];
   lastError?: Agent["lastError"] | null;
 }
 
@@ -177,7 +178,8 @@ function selectChatAgentState(
     model: agent.model,
     thinkingOptionId: agent.thinkingOptionId,
     runtimeInfo: agent.runtimeInfo,
-    features: agent.features,
+    options: agent.options,
+    controls: agent.controls,
     lastError: agent.lastError ?? null,
     archivedAt: agent.archivedAt ?? null,
     requiresAttention: agent.requiresAttention ?? false,
@@ -204,7 +206,8 @@ function buildChatAgentFromState(
     model: state.model,
     thinkingOptionId: state.thinkingOptionId,
     runtimeInfo: state.runtimeInfo,
-    features: state.features,
+    options: state.options,
+    controls: state.controls,
     lastError: state.lastError ?? null,
     projectPlacement,
   };
@@ -637,7 +640,8 @@ function AgentPanelBody({
           model: agentState.model,
           thinkingOptionId: agentState.thinkingOptionId,
           runtimeInfo: agentState.runtimeInfo,
-          features: agentState.features,
+          options: agentState.options,
+          controls: agentState.controls,
           lastError: agentState.lastError ?? null,
           projectPlacement,
         }

packages/app/src/provider-selection/provider-selection.ts

@@ -312,7 +312,7 @@ export function buildDraftCommandTarget(input: {
   cwd: string;
   effectiveModelId: string;
   effectiveThinkingOptionId: string;
-  featureValues?: Record<string, unknown>;
+  providerOptions?: Record<string, unknown>;
 }): DraftCommandTarget {
   const cwd = input.cwd.trim();
   if (!cwd) {
@@ -332,7 +332,7 @@ export function buildDraftCommandTarget(input: {
     ...(input.effectiveThinkingOptionId
       ? { thinkingOptionId: input.effectiveThinkingOptionId }
       : {}),
-    ...(input.featureValues ? { featureValues: input.featureValues } : {}),
+    ...(input.providerOptions ? { providerOptions: input.providerOptions } : {}),
   };
   return { status: "ready", config };
 }

packages/app/src/provider-selection/resolve-agent-form.test.ts

@@ -284,7 +284,7 @@ describe("mergeSelectedComposerPreferences", () => {
             codex: {
               mode: "full-access",
               thinkingByModel: { "gpt-5.4-mini": "medium" },
-              featureValues: { fast_mode: true },
+              options: { fast_mode: true },
             },
             claude: { model: "claude-sonnet-4-6" },
           },
@@ -299,7 +299,7 @@ describe("mergeSelectedComposerPreferences", () => {
           model: "gpt-5.4",
           mode: "full-access",
           thinkingByModel: { "gpt-5.4-mini": "medium" },
-          featureValues: { fast_mode: true },
+          options: { fast_mode: true },
         },
         claude: { model: "claude-sonnet-4-6" },
       },

packages/app/src/screens/new-workspace-screen.tsx

@@ -271,7 +271,7 @@ interface WorkspaceDraftSubmissionConfig {
   modeId: string | null;
   model: string | null;
   thinkingOptionId: string | null;
-  featureValues: Record<string, unknown> | undefined;
+  providerOptions: Record<string, unknown> | undefined;
   target: WorkspaceTabTarget;
 }
 
@@ -374,7 +374,7 @@ function buildWorkspaceDraftSetupFromComposer(input: {
     modeId: input.composerState.effectiveModeId || null,
     model: input.composerState.effectiveModelId || null,
     thinkingOptionId: input.composerState.effectiveThinkingOptionId || null,
-    featureValues: input.composerState.featureValues ?? {},
+    providerOptions: input.composerState.providerOptions ?? {},
   };
 }
 
@@ -454,7 +454,7 @@ async function createWorkspaceChatAgent(input: CreateChatAgentInput): Promise<Su
       modeId: composerState.effectiveModeId || undefined,
       model: composerState.effectiveModelId || undefined,
       thinkingOptionId: composerState.effectiveThinkingOptionId || undefined,
-      featureValues: composerState.featureValues,
+      providerOptions: composerState.providerOptions,
     },
     initialPrompt: text,
     clientMessageId: `${input.draftId}:initial-message`,
@@ -534,7 +534,7 @@ function buildComposerConfig(input: {
   return {
     initialServerId: serverId || null,
     initialValues: buildComposerInitialValues({ initialSetup }),
-    initialFeatureValues: initialSetup?.featureValues,
+    initialProviderOptions: initialSetup?.providerOptions,
     isVisible: true,
     lockedWorkingDir: workingDir,
   };
@@ -567,7 +567,7 @@ function resolveWorkspaceDraftSubmissionConfig(input: {
       modeId: initialSetup.modeId,
       model: initialSetup.model,
       thinkingOptionId: initialSetup.thinkingOptionId,
-      featureValues: initialSetup.featureValues,
+      providerOptions: initialSetup.providerOptions,
       target: { kind: "draft", draftId, setup: initialSetup },
     };
   }
@@ -577,7 +577,7 @@ function resolveWorkspaceDraftSubmissionConfig(input: {
     modeId: composerState.effectiveModeId || null,
     model: composerState.effectiveModelId || null,
     thinkingOptionId: composerState.effectiveThinkingOptionId || null,
-    featureValues: composerState.featureValues,
+    providerOptions: composerState.providerOptions,
     target: { kind: "draft", draftId },
   };
 }
@@ -635,7 +635,7 @@ function submitWorkspaceDraft(input: SubmitDraftInput): SubmitOutcome {
     ...(submission.modeId ? { modeId: submission.modeId } : {}),
     ...(submission.model ? { model: submission.model } : {}),
     ...(submission.thinkingOptionId ? { thinkingOptionId: submission.thinkingOptionId } : {}),
-    ...(submission.featureValues ? { featureValues: submission.featureValues } : {}),
+    ...(submission.providerOptions ? { providerOptions: submission.providerOptions } : {}),
     allowEmptyText: true,
     agentCreation: input.agentCreation,
   });

packages/app/src/screens/new-workspace/background-handoff.test.ts

@@ -69,7 +69,7 @@ describe("createWorkspaceAgentInBackground", () => {
           modeId: null,
           model: null,
           thinkingOptionId: null,
-          featureValues: {},
+          providerOptions: {},
         },
       });
     });
@@ -89,7 +89,7 @@ describe("createWorkspaceAgentInBackground", () => {
         modeId: null,
         model: null,
         thinkingOptionId: null,
-        featureValues: {},
+        providerOptions: {},
       },
     });
 

packages/app/src/screens/workspace/workspace-draft-agent-config.ts

@@ -6,7 +6,7 @@ export function buildWorkspaceDraftAgentConfig(input: {
   modeId?: string;
   model?: string;
   thinkingOptionId?: string;
-  featureValues?: Record<string, unknown>;
+  providerOptions?: Record<string, unknown>;
 }): AgentSessionConfig {
   return {
     provider: input.provider,
@@ -14,6 +14,6 @@ export function buildWorkspaceDraftAgentConfig(input: {
     ...(input.modeId ? { modeId: input.modeId } : {}),
     ...(input.model ? { model: input.model } : {}),
     ...(input.thinkingOptionId ? { thinkingOptionId: input.thinkingOptionId } : {}),
-    ...(input.featureValues ? { featureValues: input.featureValues } : {}),
+    ...(input.providerOptions ? { providerOptions: input.providerOptions } : {}),
   };
 }

packages/app/src/stores/session-store.ts

@@ -26,7 +26,8 @@ import type { ComposerAttachment } from "@/attachments/types";
 import type { AgentLifecycleStatus } from "@getpaseo/protocol/agent-lifecycle";
 import type {
   AgentPermissionRequest,
-  AgentFeature,
+  AgentOptionControl,
+  ProviderOptions,
   AgentProvider,
   AgentMode,
   AgentCapabilityFlags,
@@ -91,7 +92,8 @@ export interface Agent {
   cwd: string;
   workspaceId?: string;
   model: string | null;
-  features?: AgentFeature[];
+  options?: ProviderOptions;
+  controls?: AgentOptionControl[];
   thinkingOptionId?: string | null;
   requiresAttention?: boolean;
   attentionReason?: "finished" | "error" | "permission" | null;

packages/app/src/stores/workspace-draft-submission-store.ts

@@ -23,7 +23,7 @@ export interface PendingWorkspaceDraftSubmission {
   modeId?: string;
   model?: string;
   thinkingOptionId?: string;
-  featureValues?: Record<string, unknown>;
+  providerOptions?: Record<string, unknown>;
   allowEmptyText?: boolean;
 }
 

packages/app/src/stores/workspace-layout-persistence.test.ts

@@ -95,6 +95,53 @@ it("keeps the saved layout when the shell publishes its layout mode before hydra
   );
 });
 
+it("keeps every saved layout when a draft tab's setup carries a nested provider option", async () => {
+  const values = new Map<string, string>();
+  const storage: StateStorage = {
+    getItem: (name) => values.get(name) ?? null,
+    setItem: (name, value) => {
+      values.set(name, value);
+    },
+    removeItem: (name) => {
+      values.delete(name);
+    },
+  };
+  const store = createWorkspaceLayoutStore(undefined, storage);
+  await store.persist.rehydrate();
+  store.getState().openTab({
+    workspaceKey: "server:kept",
+    target: { kind: "agent", agentId: "agent-1" },
+    intent: "reveal",
+  });
+  store.getState().openTab({
+    workspaceKey: "server:forked",
+    target: {
+      kind: "draft",
+      draftId: "draft-1",
+      setup: {
+        provider: "codex",
+        cwd: "/repo",
+        modeId: null,
+        model: null,
+        thinkingOptionId: null,
+        providerOptions: { sandbox_workspace_write: { network_access: true }, max_turns: 3 },
+      },
+    },
+    intent: "reveal",
+  });
+
+  const restored = createWorkspaceLayoutStore(undefined, storage);
+  await restored.persist.rehydrate();
+
+  expect(Object.keys(restored.getState().layoutByWorkspace).sort()).toEqual([
+    "server:forked",
+    "server:kept",
+  ]);
+  expect(JSON.stringify(restored.getState().layoutByWorkspace["server:forked"])).toContain(
+    "network_access",
+  );
+});
+
 it.each([1, 2])(
   "restores the agent pane after parked focus in storage version %i",
   async (version) => {

packages/app/src/stores/workspace-layout-storage.ts

@@ -1,14 +1,25 @@
 import { z } from "zod";
 import type { SplitNode, WorkspaceLayout } from "./workspace-layout-actions";
 
-const WorkspaceDraftTabSetupStorageSchema = z.strictObject({
+// COMPAT(providerOptionControls): added in v0.15.0, remove after 2027-05-01. Layouts saved before
-  provider: z.string(),
+// the rename stored the same record as `featureValues`.
-  cwd: z.string(),
+function renameLegacyFeatureValues(value: unknown): unknown {
-  modeId: z.string().nullable(),
+  if (typeof value !== "object" || value === null || !("featureValues" in value)) return value;
-  model: z.string().nullable(),
+  const { featureValues, ...rest } = value as { featureValues: unknown } & Record<string, unknown>;
-  thinkingOptionId: z.string().nullable(),
+  return "providerOptions" in rest ? rest : { ...rest, providerOptions: featureValues };
-  featureValues: z.record(z.string(), z.union([z.boolean(), z.string(), z.null()])),
+}
-});
+
+const WorkspaceDraftTabSetupStorageSchema = z.preprocess(
+  renameLegacyFeatureValues,
+  z.strictObject({
+    provider: z.string(),
+    cwd: z.string(),
+    modeId: z.string().nullable(),
+    model: z.string().nullable(),
+    thinkingOptionId: z.string().nullable(),
+    providerOptions: z.record(z.string(), z.json()),
+  }),
+);
 const WorkspaceTabTargetStorageSchema = z.discriminatedUnion("kind", [
   z.strictObject({ kind: z.literal("new_tab") }),
   z.strictObject({

packages/app/src/stores/workspace-layout-store.test.ts

@@ -4551,7 +4551,6 @@ describe("compact workspace sheet", () => {
             title: agent.id,
             cwd: "/repo",
             model: null,
-            features: undefined,
             thinkingOptionId: undefined,
             requiresAttention: false,
             attentionReason: null,

packages/app/src/stores/workspace-subagents-integration.test.ts

@@ -63,7 +63,6 @@ const AGENT_DEFAULTS: Agent = {
   cwd: WORKSPACE_DIRECTORY,
   workspaceId: WORKSPACE_ID,
   model: null,
-  features: undefined,
   thinkingOptionId: undefined,
   requiresAttention: false,
   attentionReason: null,

packages/app/src/subagents/select.test.ts

@@ -41,7 +41,6 @@ const AGENT_DEFAULTS: Agent = {
   title: "Agent",
   cwd: "/tmp/project",
   model: null,
-  features: undefined,
   thinkingOptionId: undefined,
   requiresAttention: false,
   attentionReason: null,

packages/app/src/subagents/sheet-tab.test.tsx

@@ -60,7 +60,6 @@ const AGENT_DEFAULTS: Agent = {
   cwd: "/repo/worktree",
   workspaceId: WORKSPACE_ID,
   model: null,
-  features: undefined,
   thinkingOptionId: undefined,
   requiresAttention: false,
   attentionReason: null,

packages/app/src/utils/agent-snapshots.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 import type { AgentSnapshotPayload } from "@getpaseo/protocol/messages";
 import { PARENT_AGENT_ID_LABEL } from "@getpaseo/protocol/agent-labels";
+import { isControlActive, readSelectOption } from "@/agent-controls/option-controls";
 import { normalizeAgentSnapshot, projectAgentSnapshot } from "./agent-snapshots";
 
 function createSnapshot(
@@ -32,10 +33,39 @@ function createSnapshot(
     persistence: input.persistence ?? null,
     title: input.title ?? null,
     labels: (input.labels ?? {}) as AgentSnapshotPayload["labels"],
+    ...(input.controls ? { controls: input.controls } : {}),
+    ...(input.options ? { options: input.options } : {}),
   };
 }
 
 describe("normalizeAgentSnapshot", () => {
+  it("keeps a closed agent's stored options and controls, so its Fast control draws", () => {
+    const speed = {
+      type: "select" as const,
+      key: "service_tier",
+      label: "Speed",
+      defaultValue: "default",
+      choices: [
+        { value: "default", label: "Normal" },
+        { value: "priority", label: "Fast" },
+      ],
+    };
+    const agent = normalizeAgentSnapshot(
+      createSnapshot({
+        status: "closed",
+        controls: [speed],
+        options: { service_tier: "priority", sandbox_mode: "read-only" },
+      }),
+      "server-1",
+    );
+
+    expect(agent.status).toBe("closed");
+    expect(agent.controls).toEqual([speed]);
+    expect(agent.options).toEqual({ service_tier: "priority", sandbox_mode: "read-only" });
+    expect(readSelectOption(speed, agent.options ?? {})).toBe("priority");
+    expect(isControlActive(speed, agent.options ?? {})).toBe(true);
+  });
+
   it("round-trips identified active turns through the canonical snapshot boundary", () => {
     const snapshot = createSnapshot({
       status: "running",

packages/app/src/utils/agent-snapshots.ts

@@ -64,7 +64,8 @@ export function projectAgentSnapshot(agent: Agent): AgentSnapshotPayload {
     cwd: agent.cwd,
     ...(agent.workspaceId ? { workspaceId: agent.workspaceId } : {}),
     model: agent.model,
-    ...(agent.features ? { features: agent.features } : {}),
+    ...(agent.options ? { options: agent.options } : {}),
+    ...(agent.controls ? { controls: agent.controls } : {}),
     thinkingOptionId: agent.thinkingOptionId ?? null,
     createdAt: agent.createdAt.toISOString(),
     updatedAt: agent.updatedAt.toISOString(),
@@ -127,7 +128,8 @@ export function normalizeAgentSnapshot(snapshot: AgentSnapshotPayload, serverId:
     cwd: snapshot.cwd,
     workspaceId: snapshot.workspaceId,
     model: snapshot.model ?? null,
-    features: snapshot.features,
+    options: snapshot.options,
+    controls: snapshot.controls,
     thinkingOptionId: snapshot.thinkingOptionId ?? null,
     requiresAttention: snapshot.requiresAttention ?? false,
     attentionReason: snapshot.attentionReason ?? null,

packages/app/src/workspace-tabs/identity.ts

@@ -92,7 +92,7 @@ export function normalizeWorkspaceDraftTabSetup(
     thinkingOptionId: trimOptionalString(
       typeof record.thinkingOptionId === "string" ? record.thinkingOptionId : null,
     ),
-    featureValues: isPlainRecord(record.featureValues) ? { ...record.featureValues } : {},
+    providerOptions: isPlainRecord(record.providerOptions) ? { ...record.providerOptions } : {},
   };
 }
 
@@ -171,7 +171,7 @@ function workspaceDraftTabSetupsEqual(
     left.modeId === right.modeId &&
     left.model === right.model &&
     left.thinkingOptionId === right.thinkingOptionId &&
-    recordsShallowEqual(left.featureValues, right.featureValues)
+    recordsShallowEqual(left.providerOptions, right.providerOptions)
   );
 }
 

packages/app/src/workspace-tabs/model.ts

@@ -8,7 +8,7 @@ export interface WorkspaceDraftTabSetup {
   modeId: string | null;
   model: string | null;
   thinkingOptionId: string | null;
-  featureValues: Record<string, unknown>;
+  providerOptions: Record<string, unknown>;
 }
 
 export interface WorkspaceWorkingDiffTabTarget {

packages/client/src/compat/legacy-provider-options.ts

@@ -0,0 +1,217 @@
+import { controlsFromFeatures, optionsFromFeatures } from "@getpaseo/protocol/option-controls";
+import type {
+  AgentProfile,
+  AgentSnapshotPayload,
+  MutableDaemonConfig,
+  ListProviderFeaturesResponseMessage,
+  ProviderControlsListResponseMessage,
+  ServerInfoStatusPayload,
+  SessionInboundMessage,
+  SessionOutboundMessage,
+} from "@getpaseo/protocol/messages";
+
+/**
+ * COMPAT(providerOptionControls): added in v0.15.0, remove after 2027-05-01 once daemon floor >=
+ * v0.15.0.
+ *
+ * A daemon without `server_info.features.providerOptionControls` sends `features` (a control with
+ * its value attached) and takes composer values as `featureValues`. This is the one place that
+ * turns that into the shape everyone else uses: `controls` over `options`, written through
+ * `providerOptions`.
+ */
+export function usesLegacyProviderOptions(info: ServerInfoStatusPayload): boolean {
+  return info.features?.providerOptionControls !== true;
+}
+
+export class LegacyProviderOptions {
+  /** Gives agent snapshots `controls` and `options`, built from their `features`. */
+  normalize(message: SessionOutboundMessage): SessionOutboundMessage {
+    switch (message.type) {
+      case "agent_update":
+        if (message.payload.kind !== "upsert") return message;
+        return {
+          ...message,
+          payload: { ...message.payload, agent: this.snapshot(message.payload.agent) },
+        };
+      case "agent_status":
+        return {
+          ...message,
+          payload: { ...message.payload, info: this.snapshot(message.payload.info) },
+        };
+      case "fetch_agents_response":
+        return {
+          ...message,
+          payload: {
+            ...message.payload,
+            entries: message.payload.entries.map((entry) => ({
+              ...entry,
+              agent: this.snapshot(entry.agent),
+            })),
+          },
+        };
+      case "fetch_agent_response":
+      case "agent.create.response":
+      case "cancel_agent_response":
+        return {
+          ...message,
+          payload: {
+            ...message.payload,
+            agent: message.payload.agent && this.snapshot(message.payload.agent),
+          },
+        } as SessionOutboundMessage;
+      case "workspace.create.response":
+        return {
+          ...message,
+          payload: {
+            ...message.payload,
+            ...(message.payload.agent ? { agent: this.snapshot(message.payload.agent) } : {}),
+          },
+        };
+      case "wait_for_finish_response":
+        return {
+          ...message,
+          payload: {
+            ...message.payload,
+            final: message.payload.final && this.snapshot(message.payload.final),
+          },
+        };
+      case "get_daemon_config_response":
+      case "set_daemon_config_response":
+        return {
+          ...message,
+          payload: { ...message.payload, config: this.daemonConfig(message.payload.config) },
+        };
+      case "fetch_agent_timeline_response":
+        return {
+          ...message,
+          payload: {
+            ...message.payload,
+            agent: message.payload.agent && this.snapshot(message.payload.agent),
+          },
+        };
+      case "status":
+        return this.status(message);
+      default:
+        return message;
+    }
+  }
+
+  private status(
+    message: Extract<SessionOutboundMessage, { type: "status" }>,
+  ): SessionOutboundMessage {
+    const { payload } = message;
+    if (payload.status === "agent_created" || payload.status === "agent_resumed") {
+      const { agent } = payload as unknown as { agent: AgentSnapshotPayload };
+      return { ...message, payload: { ...payload, agent: this.snapshot(agent) } };
+    }
+    if (payload.status === "daemon_config_changed") {
+      const config = payload.config as MutableDaemonConfig;
+      return { ...message, payload: { ...payload, config: this.daemonConfig(config) } };
+    }
+    return message;
+  }
+
+  /**
+   * Splits a create's options for a legacy daemon: the ids it lists as features for that very
+   * config go out as `featureValues`, which is where it reads them, and the rest stay
+   * `providerOptions`. Which options are features depends on the model, mode and thinking level
+   * as well as the provider, so the ids come from a listing for this config, never from memory.
+   */
+  routeCreateConfig<
+    T extends {
+      providerOptions?: Record<string, unknown>;
+      featureValues?: Record<string, unknown>;
+    },
+  >(config: T, featureIds: ReadonlySet<string>): T {
+    if (!config.providerOptions) return config;
+    const featureValues: Record<string, unknown> = {};
+    const providerOptions: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(config.providerOptions)) {
+      (featureIds.has(key) ? featureValues : providerOptions)[key] = value;
+    }
+    const { providerOptions: _options, ...rest } = config;
+    return {
+      ...(rest as T),
+      ...(Object.keys(providerOptions).length > 0 ? { providerOptions } : {}),
+      ...(Object.keys(featureValues).length > 0
+        ? { featureValues: { ...config.featureValues, ...featureValues } }
+        : {}),
+    };
+  }
+
+  /** Sends options as `featureValues`, which is where a legacy daemon reads them. */
+  prepare(message: SessionInboundMessage): SessionInboundMessage {
+    switch (message.type) {
+      case "agent.config.apply.request": {
+        const { options, ...config } = message.config;
+        if (!options) return message;
+        return {
+          ...message,
+          config: { ...config, featureValues: { ...config.featureValues, ...options } },
+        };
+      }
+      case "list_commands_request": {
+        if (!message.draftConfig?.providerOptions) return message;
+        const { providerOptions, ...draftConfig } = message.draftConfig;
+        return {
+          ...message,
+          draftConfig: {
+            ...draftConfig,
+            featureValues: { ...draftConfig.featureValues, ...providerOptions },
+          },
+        };
+      }
+      case "set_daemon_config_request":
+        if (!message.config.agentProfiles) return message;
+        return {
+          ...message,
+          config: {
+            ...message.config,
+            agentProfiles: message.config.agentProfiles.map(profileWithFeatureValues),
+          },
+        };
+      default:
+        return message;
+    }
+  }
+
+  /** The legacy answer to a controls listing, in the shape of the current response. */
+  controlsResponse(
+    legacy: ListProviderFeaturesResponseMessage["payload"],
+  ): ProviderControlsListResponseMessage["payload"] {
+    const { features, ...rest } = legacy;
+    return {
+      ...rest,
+      ...(features
+        ? { controls: controlsFromFeatures(features), options: optionsFromFeatures(features) }
+        : {}),
+    };
+  }
+
+  private daemonConfig(config: MutableDaemonConfig): MutableDaemonConfig {
+    if (!config.agentProfiles) return config;
+    return { ...config, agentProfiles: config.agentProfiles.map(profileWithOptions) };
+  }
+
+  private readonly snapshot = (agent: AgentSnapshotPayload): AgentSnapshotPayload => {
+    if (agent.controls || !agent.features) return agent;
+    return {
+      ...agent,
+      controls: controlsFromFeatures(agent.features),
+      options: optionsFromFeatures(agent.features),
+    };
+  };
+}
+
+/** A legacy daemon stores a profile's options under `featureValues`. */
+function profileWithOptions(profile: AgentProfile): AgentProfile {
+  if (profile.options || !profile.featureValues) return profile;
+  const { featureValues, ...rest } = profile;
+  return { ...rest, options: featureValues };
+}
+
+function profileWithFeatureValues(profile: AgentProfile): AgentProfile {
+  if (!profile.options) return profile;
+  const { options, ...rest } = profile;
+  return { ...rest, featureValues: options };
+}

packages/client/src/daemon-client.test.ts

@@ -8924,3 +8924,394 @@ test("routed channels inherit an origin without drain support", async () => {
   expect(route.supportsDrain).toBe(false);
   route.close();
 });
+
+describe("provider options across daemon versions", () => {
+  const agentSnapshot = {
+    id: "agent-1",
+    provider: "codex",
+    cwd: "/repo",
+    model: null,
+    thinkingOptionId: null,
+    effectiveThinkingOptionId: null,
+    createdAt: "2026-04-30T00:00:00.000Z",
+    updatedAt: "2026-04-30T00:00:00.000Z",
+    lastUserMessageAt: null,
+    status: "idle",
+    capabilities: {
+      supportsStreaming: false,
+      supportsSessionPersistence: false,
+      supportsDynamicModes: false,
+      supportsMcpServers: false,
+      supportsReasoningStream: false,
+      supportsToolInvocations: false,
+    },
+    currentModeId: null,
+    availableModes: [],
+    pendingPermissions: [],
+    persistence: null,
+    title: null,
+    labels: {},
+    requiresAttention: false,
+    attentionReason: null,
+  };
+  const speedFeature = {
+    type: "select",
+    id: "service_tier",
+    label: "Speed",
+    value: "priority",
+    options: [
+      { id: "default", label: "Normal", isDefault: true },
+      { id: "priority", label: "Fast" },
+    ],
+  };
+
+  async function connect(features: Record<string, boolean>) {
+    const mock = createMockTransport();
+    const client = new DaemonClient({
+      url: "ws://test",
+      clientId: "provider_options",
+      transportFactory: () => mock.transport,
+      reconnect: { enabled: false },
+    });
+    clients.push(client);
+    const connecting = client.connect();
+    mock.triggerOpen({ features });
+    await connecting;
+    const sentMessages = () =>
+      mock.sent.map(
+        (frame) => (JSON.parse(frame as string) as { message: Record<string, unknown> }).message,
+      );
+    return { mock, client, sentMessages };
+  }
+
+  test("a legacy create and a timeline read return the agent with controls over options", async () => {
+    const { mock, client, sentMessages } = await connect({});
+    const legacyAgent = { ...agentSnapshot, features: [speedFeature] };
+    const answerLast = (reply: (requestId: string) => Record<string, unknown>) => {
+      const sent = sentMessages();
+      const requestId = String(sent[sent.length - 1].requestId);
+      mock.triggerMessage(wrapSessionMessage(reply(requestId) as never));
+    };
+
+    const creating = client.createAgent({ provider: "codex", cwd: "/repo" });
+    answerLast((requestId) => ({
+      type: "status",
+      payload: { status: "agent_created", requestId, agentId: "agent-1", agent: legacyAgent },
+    }));
+    const created = await creating;
+
+    const reading = client.fetchAgentTimeline("agent-1");
+    answerLast((requestId) => ({
+      type: "fetch_agent_timeline_response",
+      payload: {
+        requestId,
+        agentId: "agent-1",
+        agent: legacyAgent,
+        direction: "tail",
+        projection: "projected",
+        epoch: "epoch-1",
+        reset: false,
+        staleCursor: false,
+        gap: false,
+        window: { minSeq: 0, maxSeq: 0, nextSeq: 1 },
+        startCursor: null,
+        endCursor: null,
+        hasOlder: false,
+        hasNewer: false,
+        entries: [],
+        error: null,
+      },
+    }));
+    const timeline = await reading;
+
+    expect(created.options).toEqual({ service_tier: "priority" });
+    expect(created.controls).toEqual([expect.objectContaining({ key: "service_tier" })]);
+    expect(timeline.agent?.options).toEqual({ service_tier: "priority" });
+    expect(timeline.agent?.controls).toEqual([expect.objectContaining({ key: "service_tier" })]);
+  });
+
+  test("a legacy daemon's features arrive as controls over options", async () => {
+    const { mock, client } = await connect({});
+    const received: Array<{ controls?: unknown; options?: unknown }> = [];
+    client.on("agent_update", (message) => {
+      if (message.payload.kind === "upsert") received.push(message.payload.agent);
+    });
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "agent_update",
+        payload: { kind: "upsert", agent: { ...agentSnapshot, features: [speedFeature] } },
+      }),
+    );
+    expect(received).toEqual([
+      expect.objectContaining({
+        options: { service_tier: "priority" },
+        controls: [
+          expect.objectContaining({
+            type: "select",
+            key: "service_tier",
+            defaultValue: "default",
+            choices: [
+              { value: "default", label: "Normal" },
+              { value: "priority", label: "Fast" },
+            ],
+          }),
+        ],
+      }),
+    ]);
+  });
+
+  test("a legacy daemon takes option writes as feature writes", async () => {
+    const { client, sentMessages, mock } = await connect({});
+    const write = client.setAgentOptions("agent-1", { service_tier: "default" });
+    const [request] = sentMessages();
+    expect(request).toMatchObject({
+      type: "set_agent_feature_request",
+      agentId: "agent-1",
+      featureId: "service_tier",
+      value: "default",
+    });
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "set_agent_feature_response",
+        payload: { requestId: request.requestId, agentId: "agent-1", accepted: true, error: null },
+      }),
+    );
+    await write;
+  });
+
+  test("a current daemon takes option writes as one options patch", async () => {
+    const { client, sentMessages, mock } = await connect({ providerOptionControls: true });
+    const write = client.setAgentOptions("agent-1", { service_tier: null, sandbox_mode: "x" });
+    const [request] = sentMessages();
+    expect(request).toMatchObject({
+      type: "agent.config.apply.request",
+      agentId: "agent-1",
+      config: { options: { service_tier: null, sandbox_mode: "x" } },
+    });
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "agent.config.apply.response",
+        payload: { requestId: request.requestId, agentId: "agent-1", accepted: true, error: null },
+      }),
+    );
+    await write;
+  });
+
+  test("a legacy draft listing answers with controls and options", async () => {
+    const { client, sentMessages, mock } = await connect({});
+    const listing = client.listProviderControls({
+      provider: "codex",
+      cwd: "/repo",
+      providerOptions: { service_tier: "default" },
+    });
+    const [request] = sentMessages();
+    expect(request).toMatchObject({
+      type: "list_provider_features_request",
+      draftConfig: { provider: "codex", featureValues: { service_tier: "default" } },
+    });
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "list_provider_features_response",
+        payload: {
+          provider: "codex",
+          features: [{ ...speedFeature, value: "default" }],
+          error: null,
+          fetchedAt: "2026-04-30T00:00:00.000Z",
+          requestId: request.requestId,
+        },
+      }),
+    );
+    await expect(listing).resolves.toMatchObject({
+      provider: "codex",
+      options: { service_tier: "default" },
+      controls: [expect.objectContaining({ key: "service_tier" })],
+    });
+  });
+
+  test("a legacy daemon's profiles are read and saved by their options", async () => {
+    const { client, sentMessages, mock } = await connect({});
+    const reading = client.getDaemonConfig();
+    const [read] = sentMessages();
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "get_daemon_config_response",
+        payload: {
+          requestId: read.requestId,
+          config: {
+            mcp: { injectIntoAgents: true },
+            agentProfiles: [
+              {
+                id: "p1",
+                name: "Fast",
+                provider: "codex",
+                featureValues: { service_tier: "fast" },
+              },
+            ],
+          },
+        },
+      }),
+    );
+    const { config } = await reading;
+    expect(config.agentProfiles?.[0]).toMatchObject({ options: { service_tier: "fast" } });
+    expect(config.agentProfiles?.[0]).not.toHaveProperty("featureValues");
+
+    void client.patchDaemonConfig({ agentProfiles: config.agentProfiles }).catch(() => {});
+    const written = sentMessages().find((message) => message.type === "set_daemon_config_request");
+    expect(written).toMatchObject({
+      config: { agentProfiles: [{ featureValues: { service_tier: "fast" } }] },
+    });
+    expect(written).not.toMatchObject({ config: { agentProfiles: [{ options: {} }] } });
+  });
+
+  test("a legacy daemon applies a profile's options as feature values", async () => {
+    const { client, sentMessages } = await connect({});
+    void client.applyAgentConfig("agent-1", { options: { service_tier: "fast" } }).catch(() => {});
+    const [request] = sentMessages();
+    expect(request).toMatchObject({
+      type: "agent.config.apply.request",
+      config: { featureValues: { service_tier: "fast" } },
+    });
+  });
+
+  test("a cold legacy create lists the provider's features before routing its options", async () => {
+    const { client, sentMessages, mock } = await connect({});
+    void client
+      .createAgent({
+        config: {
+          provider: "claude",
+          cwd: "/repo",
+          providerOptions: { fast_mode: true, sandbox_mode: "read-only" },
+        },
+      })
+      .catch(() => {});
+    await vi.waitFor(() => expect(sentMessages()).toHaveLength(1));
+    const [listing] = sentMessages();
+    expect(listing).toMatchObject({
+      type: "list_provider_features_request",
+      draftConfig: { provider: "claude", cwd: "/repo" },
+    });
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "list_provider_features_response",
+        payload: {
+          provider: "claude",
+          features: [{ type: "toggle", id: "fast_mode", label: "Fast", value: false }],
+          error: null,
+          fetchedAt: "2026-04-30T00:00:00.000Z",
+          requestId: listing.requestId,
+        },
+      }),
+    );
+    await vi.waitFor(() => expect(sentMessages()).toHaveLength(2));
+    expect(sentMessages()[1].config).toMatchObject({
+      featureValues: { fast_mode: true },
+      providerOptions: { sandbox_mode: "read-only" },
+    });
+  });
+
+  test("a legacy workspace create routes its agent's options from its own model's controls", async () => {
+    const { client, sentMessages, mock } = await connect({ creationLifecycle: true });
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "agent_update",
+        payload: {
+          kind: "upsert",
+          agent: { ...agentSnapshot, provider: "codex", model: "mini", features: [] },
+        },
+      }),
+    );
+    void client
+      .createWorkspace({
+        source: { kind: "directory", path: "/repo" },
+        agent: {
+          config: {
+            provider: "codex",
+            cwd: "/repo",
+            model: "gpt-5.5",
+            providerOptions: { service_tier: "fast" },
+          },
+        },
+      } as never)
+      .catch(() => {});
+    await vi.waitFor(() => expect(sentMessages()).toHaveLength(1));
+    const [listing] = sentMessages();
+    expect(listing).toMatchObject({
+      type: "list_provider_features_request",
+      draftConfig: { provider: "codex", cwd: "/repo", model: "gpt-5.5" },
+    });
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "list_provider_features_response",
+        payload: {
+          provider: "codex",
+          features: [speedFeature],
+          error: null,
+          fetchedAt: "2026-04-30T00:00:00.000Z",
+          requestId: listing.requestId,
+        },
+      }),
+    );
+    const sentTypes = () => sentMessages().map((message) => message.type);
+    await vi.waitFor(() => expect(sentTypes()).toContain("workspace.create.request"));
+    const created = sentMessages()[sentTypes().indexOf("workspace.create.request")];
+    expect(created).toMatchObject({
+      agent: { config: { featureValues: { service_tier: "fast" } } },
+    });
+  });
+
+  test("a legacy create lists the controls of its own model, whatever a snapshot showed", async () => {
+    const { client, sentMessages, mock } = await connect({});
+    // A Haiku agent has no Fast control; that says nothing about Opus.
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "agent_update",
+        payload: {
+          kind: "upsert",
+          agent: { ...agentSnapshot, provider: "claude", model: "haiku", features: [] },
+        },
+      }),
+    );
+    void client
+      .createAgent({
+        config: {
+          provider: "claude",
+          cwd: "/repo",
+          model: "opus",
+          modeId: "plan",
+          thinkingOptionId: "high",
+          providerOptions: { fast_mode: true, sandbox_mode: "read-only" },
+        },
+      })
+      .catch(() => {});
+    await vi.waitFor(() => expect(sentMessages()).toHaveLength(1));
+    const [listing] = sentMessages();
+    expect(listing).toMatchObject({
+      type: "list_provider_features_request",
+      draftConfig: {
+        provider: "claude",
+        cwd: "/repo",
+        model: "opus",
+        modeId: "plan",
+        thinkingOptionId: "high",
+      },
+    });
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "list_provider_features_response",
+        payload: {
+          provider: "claude",
+          features: [{ type: "toggle", id: "fast_mode", label: "Fast", value: false }],
+          error: null,
+          fetchedAt: "2026-04-30T00:00:00.000Z",
+          requestId: listing.requestId,
+        },
+      }),
+    );
+    await vi.waitFor(() => expect(sentMessages()).toHaveLength(2));
+    expect(sentMessages()[1].config).toMatchObject({
+      model: "opus",
+      featureValues: { fast_mode: true },
+      providerOptions: { sandbox_mode: "read-only" },
+    });
+  });
+});

packages/client/src/daemon-client.ts

@@ -102,6 +102,7 @@ import type {
   WorkspaceSetupStatusResponseMessage,
   ListCommandsResponse,
   ListProviderFeaturesResponseMessage,
+  ProviderControlsListResponseMessage,
   ListProviderModelsResponseMessage,
   ListProviderModesResponseMessage,
   ListAvailableProvidersResponse,
@@ -184,6 +185,10 @@ import {
   normalizeProviderSnapshotUpdateMessage,
   normalizeProvidersSnapshotPayload,
 } from "./compat/normalize-provider-models.js";
+import {
+  LegacyProviderOptions,
+  usesLegacyProviderOptions,
+} from "./compat/legacy-provider-options.js";
 import { TerminalStreamRouter, type TerminalStreamEvent } from "./terminal-stream-router.js";
 import type {
   BrowserAutomationExecuteRequest,
@@ -598,6 +603,7 @@ export interface FileUploadInput {
 export type FileUploadResult = FileUploadResponse["payload"];
 type FileDownloadTokenPayload = FileDownloadTokenResponse["payload"];
 type ListProviderFeaturesPayload = ListProviderFeaturesResponseMessage["payload"];
+export type ListProviderControlsPayload = ProviderControlsListResponseMessage["payload"];
 type ListProviderModelsPayload = ListProviderModelsResponseMessage["payload"];
 type ListProviderModesPayload = ListProviderModesResponseMessage["payload"];
 type ListAvailableProvidersPayload = ListAvailableProvidersResponse["payload"];
@@ -624,7 +630,7 @@ type WriteProjectConfigPayload = Extract<
 type ListCommandsPayload = ListCommandsResponse["payload"];
 type ListCommandsDraftConfig = Pick<
   AgentSessionConfig,
-  "provider" | "cwd" | "modeId" | "model" | "thinkingOptionId" | "featureValues"
+  "provider" | "cwd" | "modeId" | "model" | "thinkingOptionId" | "featureValues" | "providerOptions"
 >;
 export interface WriteProjectConfigInput {
   repoRoot: string;
@@ -2089,17 +2095,13 @@ export class DaemonClient {
   }
 
   private sendSessionPayload(payload: SessionInboundMessage): Promise<void> {
-    return this.sendJsonMessage(
+    const wire = this.legacyProviderOptions()?.prepare(payload) ?? payload;
-      "session",
+    return this.sendJsonMessage("session", payload.type, { type: "session", message: wire }, () => {
-      payload.type,
+      if (!("requestId" in payload) || typeof payload.requestId !== "string") return;
-      { type: "session", message: payload },
+      for (const waiter of this.waiters) {
-      () => {
+        if (waiter.requestId === payload.requestId) waiter.submitted = true;
-        if (!("requestId" in payload) || typeof payload.requestId !== "string") return;
+      }
-        for (const waiter of this.waiters) {
+    });
-          if (waiter.requestId === payload.requestId) waiter.submitted = true;
-        }
-      },
-    );
   }
 
   private sendTransportFrame(
@@ -3267,14 +3269,44 @@ export class DaemonClient {
       );
     }
     if (options.background !== undefined) this.requireBackgroundWorkspaces();
+    const config = resolveAgentConfig(options);
     const result = await this.creations.createAgent({
       ...options,
-      config: resolveAgentConfig(options),
+      config: this.carriesLegacyOptions(config)
+        ? await this.routeLegacyCreateConfig(config)
+        : config,
     });
     if (result.error || !result.agent) throw new Error(result.error ?? "Agent creation failed");
     return result.agent;
   }
 
+  /**
+   * A legacy daemon reads control options as `featureValues`, and which options are controls
+   * depends on the config (Claude's differ by model), so a create that carries options first lists
+   * the controls for its own config. Callers never prime anything.
+   */
+  private carriesLegacyOptions(config: AgentSessionConfig): boolean {
+    return (
+      this.legacyProviderOptions() !== null && Object.keys(config.providerOptions ?? {}).length > 0
+    );
+  }
+
+  private async routeLegacyCreateConfig(config: AgentSessionConfig): Promise<AgentSessionConfig> {
+    const payload = await this.listProviderFeatures({
+      provider: config.provider,
+      cwd: config.cwd || "~",
+      ...(config.modeId ? { modeId: config.modeId } : {}),
+      ...(config.model ? { model: config.model } : {}),
+      ...(config.thinkingOptionId ? { thinkingOptionId: config.thinkingOptionId } : {}),
+      featureValues: config.providerOptions,
+    });
+    if (payload.error) throw new Error(payload.error);
+    return this.legacyOptions.routeCreateConfig(
+      config,
+      new Set((payload.features ?? []).map((feature) => feature.id)),
+    );
+  }
+
   private async createLegacyAgent(
     options: CreateAgentRequestOptions,
   ): Promise<AgentSnapshotPayload> {
@@ -4065,6 +4097,24 @@ export class DaemonClient {
     }
   }
 
+  /**
+   * Changes the agent's own provider options: top-level keys replace, `null` removes the key.
+   * A daemon without `providerOptionControls` takes each key as a feature write.
+   */
+  async setAgentOptions(
+    agentId: string,
+    patch: Record<string, unknown>,
+  ): Promise<AgentProviderNotice | null> {
+    if (this.legacyProviderOptions()) {
+      // COMPAT(providerOptionControls): added in v0.15.0, remove after 2027-05-01.
+      for (const [featureId, value] of Object.entries(patch)) {
+        await this.setAgentFeature(agentId, featureId, value);
+      }
+      return null;
+    }
+    return this.applyAgentConfig(agentId, { options: patch });
+  }
+
   async setAgentThinkingOption(
     agentId: string,
     thinkingOptionId: string | null,
@@ -5008,12 +5058,14 @@ export class DaemonClient {
     if (input.background !== undefined || input.callerAgentId) this.requireBackgroundWorkspaces();
     if (input.agent?.background !== undefined)
       throw new Error("Configure background on the workspace, not its initial agent.");
+    let agentConfig = input.agent ? resolveAgentConfig(input.agent) : undefined;
+    if (agentConfig && this.carriesLegacyOptions(agentConfig)) {
+      agentConfig = await this.routeLegacyCreateConfig(agentConfig);
+    }
     const result = await this.creations.createWorkspace({
       ...input,
       requestId: resolvedRequestId,
-      ...(input.agent
+      ...(input.agent && agentConfig ? { agent: { ...input.agent, config: agentConfig } } : {}),
-        ? { agent: { ...input.agent, config: resolveAgentConfig(input.agent) } }
-        : {}),
     });
     return {
       ...result,
@@ -5494,6 +5546,36 @@ export class DaemonClient {
     });
   }
 
+  /**
+   * The controls a draft agent would show and the options it would run with: `config.json`
+   * defaults merged with the draft's own `providerOptions`, resolved by the daemon.
+   */
+  async listProviderControls(
+    draftConfig: ListCommandsDraftConfig,
+    options?: { requestId?: string },
+  ): Promise<ListProviderControlsPayload> {
+    const legacy = this.legacyProviderOptions();
+    if (legacy) {
+      const { providerOptions, ...rest } = draftConfig;
+      const payload = await this.listProviderFeatures(
+        {
+          ...rest,
+          // A legacy daemon reads the options it exposes as features, whatever the others are.
+          ...(providerOptions ? { featureValues: providerOptions } : {}),
+        },
+        options,
+      );
+      return legacy.controlsResponse(payload);
+    }
+    return this.sendCorrelatedSessionRequest({
+      requestId: options?.requestId,
+      message: { type: "provider.controls.list.request", draftConfig },
+      responseType: "provider.controls.list.response",
+      timeout: 90000,
+    });
+  }
+
+  /** @deprecated Use `listProviderControls`. */
   async listProviderFeatures(
     draftConfig: ListCommandsDraftConfig,
     options?: { requestId?: string },
@@ -6747,6 +6829,14 @@ export class DaemonClient {
     return requestId ?? crypto.randomUUID();
   }
 
+  private readonly legacyOptions = new LegacyProviderOptions();
+
+  /** The translation for a daemon without `providerOptionControls`; null for a current one. */
+  private legacyProviderOptions(): LegacyProviderOptions | null {
+    const info = this.lastServerInfoMessage;
+    return info && usesLegacyProviderOptions(info) ? this.legacyOptions : null;
+  }
+
   getLastServerInfoMessage(): ServerInfoStatusPayload | null {
     return this.lastServerInfoMessage;
   }
@@ -7308,6 +7398,7 @@ export class DaemonClient {
 
   private handleSessionMessage(msg: SessionOutboundMessage): void {
     msg = this.owned.normalize(msg);
+    msg = this.legacyProviderOptions()?.normalize(msg) ?? msg;
     if (
       msg.type === "providers_snapshot_update" &&
       this.config.providerSnapshots !== "wire" &&

packages/client/src/index.test.ts

@@ -1601,7 +1601,12 @@ test("config actions delegate to existing daemon config RPCs", async () => {
 });
 
 test("agent config maps provider/model and provider-native options to the daemon", async () => {
-  const { client, ws } = await connectClient();
+  const { client, ws } = await connectClient({
+    providerUsageList: true,
+    providersSnapshotCwd: true,
+    ownedSubscriptions: true,
+    providerOptionControls: true,
+  });
   const createdAgent = createAgent({
     model: "gpt-5.4",
     currentModeId: "full-access",
@@ -1633,8 +1638,8 @@ test("agent config maps provider/model and provider-native options to the daemon
       model: "gpt-5.4",
       modeId: "full-access",
       thinkingOptionId: "high",
-      featureValues: { webSearch: true },
       providerOptions: {
+        webSearch: true,
         approval_policy: "never",
         sandbox_mode: "workspace-write",
         sandbox_workspace_write: {

packages/client/src/index.ts

@@ -20,6 +20,8 @@ import type {
   ListCommandsResponse,
   ListProviderFeaturesRequestMessage,
   ListProviderFeaturesResponseMessage,
+  ProviderControlsListRequestMessage,
+  ProviderControlsListResponseMessage,
   ListProviderModelsResponseMessage,
   ProjectListRequestMessage,
   ProjectListResponseMessage,
@@ -239,8 +241,12 @@ export interface PaseoAgentConfig {
   provider: string;
   modeId?: PaseoAgentSessionConfig["modeId"];
   thinkingOptionId?: PaseoAgentSessionConfig["thinkingOptionId"];
+  /** @deprecated Put these in `options`; they are folded into it on send. */
   featureValues?: PaseoProviderFeatureValues;
-  /** JSON-safe provider-native settings, validated by the selected provider. */
+  /**
+   * JSON-safe provider settings, validated by the selected provider. They include the settings the
+   * provider offers a composer control for, such as `service_tier` or `fast_mode`.
+   */
   options?: PaseoAgentSessionConfig["providerOptions"];
   systemPrompt?: PaseoAgentSessionConfig["systemPrompt"];
   toolPolicy?: PaseoAgentSessionConfig["toolPolicy"];
@@ -364,7 +370,12 @@ export interface PaseoAgentHandle {
   readonly activeTurn: NonNullable<PaseoAgent["activeTurn"]> | null;
   readonly lastUsage: NonNullable<PaseoAgent["lastUsage"]> | null;
   readonly lastError: NonNullable<PaseoAgent["lastError"]> | null;
+  /** @deprecated Use `controls` and `options`. */
   readonly features: NonNullable<PaseoAgent["features"]> | null;
+  /** The provider options the agent runs with: `config.json` defaults merged with its own. */
+  readonly options: NonNullable<PaseoAgent["options"]> | null;
+  /** How the provider wants its options drawn. Controls hold no value; read `options`. */
+  readonly controls: NonNullable<PaseoAgent["controls"]> | null;
   readonly runtimeInfo: NonNullable<PaseoAgent["runtimeInfo"]> | null;
   readonly archivedAt: NonNullable<PaseoAgent["archivedAt"]> | null;
   readonly timeline: PaseoAgentTimelineHandle;
@@ -377,6 +388,12 @@ export interface PaseoAgentHandle {
   reload(options?: { requestId?: string }): Promise<PaseoAgentRefetchResult | null>;
   send(text: string, options?: PaseoAgentSendOptions): Promise<void>;
   respondToPermission(options: PaseoAgentRespondToPermissionOptions): Promise<void>;
+  /**
+   * Changes the agent's own options: top-level keys replace, `null` removes the key so the
+   * `config.json` default (or the provider's own default) applies again. Resolves once the
+   * provider has applied the patch; a provider that cannot apply a key live rejects it.
+   */
+  setOptions(patch: Record<string, unknown>): Promise<void>;
   /** Sends a prompt and resolves when that turn finishes or needs attention. */
   run(text: string, options?: PaseoAgentRunOptions): Promise<PaseoAgentRunResult>;
   /** Waits for the current turn, including one started with `prompt`. */
@@ -413,14 +430,21 @@ export interface PaseoAgentActions {
 
 export type PaseoProviderModelsResult = ListProviderModelsResponseMessage["payload"];
 export type PaseoProviderModesResult = ListProviderModesResponseMessage["payload"];
-type PaseoProviderFeaturesDraft = ListProviderFeaturesRequestMessage["draftConfig"];
+type PaseoProviderControlsDraft = ProviderControlsListRequestMessage["draftConfig"];
-export interface PaseoProviderFeaturesInput extends Omit<
+export interface PaseoProviderControlsInput extends Omit<
-  PaseoProviderFeaturesDraft,
+  PaseoProviderControlsDraft,
   "provider" | "model"
 > {
   /** Provider and model in `provider/model` format. */
   provider: string;
 }
+export type PaseoProviderControlsResult = ProviderControlsListResponseMessage["payload"];
+/** @deprecated Use `PaseoProviderControlsInput`. */
+export type PaseoProviderFeaturesInput = Omit<
+  ListProviderFeaturesRequestMessage["draftConfig"],
+  "provider" | "model"
+> & { provider: string };
+/** @deprecated Use `PaseoProviderControlsResult`. */
 export type PaseoProviderFeaturesResult = ListProviderFeaturesResponseMessage["payload"];
 export type PaseoProviderAvailabilityResult = ListAvailableProvidersResponse["payload"];
 export type PaseoProviderSnapshotResult = GetProvidersSnapshotResponseMessage["payload"];
@@ -459,6 +483,15 @@ export interface PaseoProviderActions {
     provider: PaseoAgentProvider,
     options?: PaseoProviderListOptions,
   ): Promise<PaseoProviderModesResult>;
+  /**
+   * The controls a draft agent would show and the options it would run with, resolved by the
+   * daemon from `config.json` defaults and the draft's own `providerOptions`.
+   */
+  listControls(
+    draftConfig: PaseoProviderControlsInput,
+    options?: { requestId?: string },
+  ): Promise<PaseoProviderControlsResult>;
+  /** @deprecated Use `listControls`. */
   listFeatures(
     draftConfig: PaseoProviderFeaturesInput,
     options?: { requestId?: string },
@@ -543,7 +576,14 @@ function toDaemonAgentCreateOptions(
   serverId?: string,
 ): CreateAgentRequestOptions {
   const { config: agentConfig, cwd, parent, title, prompt, ...requestOptions } = options;
-  const { provider: providerModel, options: providerOptions, ...runtimeConfig } = agentConfig;
+  const {
+    provider: providerModel,
+    options: ownOptions,
+    featureValues,
+    ...runtimeConfig
+  } = agentConfig;
+  // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. An explicit option wins.
+  const providerOptions = featureValues ? { ...featureValues, ...ownOptions } : ownOptions;
   const { provider, model } = parseProviderModel(providerModel);
   const relationship = parent ? encodeParent(parent, serverId) : {};
   return {
@@ -776,6 +816,10 @@ export function createPaseoApi(
         const { provider, model } = parseProviderModel(providerModel);
         return daemonClient.listProviderFeatures({ ...draftConfig, provider, model }, options);
       },
+      listControls: ({ provider: providerModel, ...draftConfig }, options) => {
+        const { provider, model } = parseProviderModel(providerModel);
+        return daemonClient.listProviderControls({ ...draftConfig, provider, model }, options);
+      },
       listAvailable: (options) => daemonClient.listAvailableProviders(options),
       snapshot: (options) => daemonClient.getProvidersSnapshot(options),
       waitForReady: (options) =>
@@ -975,6 +1019,12 @@ function createAgentHandleFactory(
       get features() {
         return current?.features ?? null;
       },
+      get options() {
+        return current?.options ?? null;
+      },
+      get controls() {
+        return current?.controls ?? null;
+      },
       get runtimeInfo() {
         return current?.runtimeInfo ?? null;
       },
@@ -996,6 +1046,9 @@ function createAgentHandleFactory(
       send: async (text, options) => {
         await daemonClient.sendAgentMessage(id, text, options);
       },
+      setOptions: async (patch) => {
+        await daemonClient.setAgentOptions(id, patch);
+      },
       respondToPermission: async ({ requestId, response }) => {
         await daemonClient.respondToPermission(id, requestId, response);
       },

packages/protocol/src/agent-profile.ts

@@ -21,7 +21,10 @@ export const AgentProfileSchema = z
     model: z.string().optional(),
     modeId: z.string().optional(),
     thinkingOptionId: z.string().optional(),
+    // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. Read as `options`.
     featureValues: z.record(z.string(), z.unknown()).optional(),
+    /** Provider options applied when the profile creates an agent. */
+    options: z.record(z.string(), z.unknown()).optional(),
     /** Free text, surfaced to orchestrating agents by the `list_profiles` MCP tool. */
     notes: z.string().optional(),
   })

packages/protocol/src/agent-types.ts

@@ -1,5 +1,12 @@
 import type { AgentMessage } from "./agent-message.js";
-import type { AgentAttachment } from "./messages.js";
+import type {
+  AgentAttachment,
+  AgentOptionChoiceSchema,
+  AgentOptionControlSchema,
+  AgentOptionSelectControlSchema,
+  AgentOptionToggleControlSchema,
+} from "./messages.js";
+import type { z } from "zod";
 
 export type AgentProvider = string;
 
@@ -154,6 +161,20 @@ export interface AgentFeatureSelect {
 
 export type AgentFeature = AgentFeatureToggle | AgentFeatureSelect;
 
+export type AgentOptionChoice = z.infer<typeof AgentOptionChoiceSchema>;
+
+/** `key` is the top-level provider option key the control reads and writes. */
+export type AgentOptionToggleControl = z.infer<typeof AgentOptionToggleControlSchema>;
+
+/** `defaultValue` is the choice an unset option stands for. */
+export type AgentOptionSelectControl = z.infer<typeof AgentOptionSelectControlSchema>;
+
+/**
+ * A provider's description of a composer control over one top-level option key.
+ * The control carries no value: it is read from the agent's effective options.
+ */
+export type AgentOptionControl = z.infer<typeof AgentOptionControlSchema>;
+
 export interface AgentCapabilityFlags {
   [capability: string]: boolean | undefined;
   supportsStreaming: boolean;
@@ -523,6 +544,10 @@ export interface AgentSessionConfig {
   modeId?: string;
   model?: string;
   thinkingOptionId?: string;
+  /**
+   * @deprecated COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01.
+   * Folded into `providerOptions` at the daemon's edge; the daemon never reads it internally.
+   */
   featureValues?: Record<string, unknown>;
   title?: string | null;
   providerOptions?: ProviderOptions;

packages/protocol/src/messages.ts

@@ -361,6 +361,39 @@ export const AgentFeatureSchema = z.discriminatedUnion("type", [
   AgentFeatureSelectSchema,
 ]);
 
+export const AgentOptionChoiceSchema = z.object({
+  value: z.string(),
+  label: z.string(),
+  description: z.string().optional(),
+});
+
+export const AgentOptionToggleControlSchema = z.object({
+  type: z.literal("toggle"),
+  key: z.string(),
+  label: z.string(),
+  description: z.string().optional(),
+  tooltip: z.string().optional(),
+  icon: z.string().optional(),
+  defaultValue: z.boolean().optional(),
+});
+
+export const AgentOptionSelectControlSchema = z.object({
+  type: z.literal("select"),
+  key: z.string(),
+  label: z.string(),
+  description: z.string().optional(),
+  tooltip: z.string().optional(),
+  icon: z.string().optional(),
+  desktopTrigger: z.enum(["icon", "label"]).optional(),
+  defaultValue: z.string().optional(),
+  choices: z.array(AgentOptionChoiceSchema),
+});
+
+export const AgentOptionControlSchema = z.discriminatedUnion("type", [
+  AgentOptionToggleControlSchema,
+  AgentOptionSelectControlSchema,
+]);
+
 const AgentModelDefinitionSchema = z.object({
   provider: AgentProviderSchema,
   id: z.string(),
@@ -490,6 +523,7 @@ const AgentSessionConfigSchema = z.object({
   modeId: z.string().optional(),
   model: z.string().optional(),
   thinkingOptionId: z.string().optional(),
+  // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. Folded into providerOptions.
   featureValues: z.record(z.string(), z.unknown()).optional(),
   title: z.string().trim().min(1).max(MAX_EXPLICIT_AGENT_TITLE_CHARS).optional().nullable(),
   providerOptions: ProviderOptionsSchema.optional(),
@@ -866,7 +900,11 @@ export const AgentSnapshotPayloadSchema = z.object({
   cwd: z.string(),
   workspaceId: z.string().optional(),
   model: z.string().nullable(),
+  // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. Built from controls + options.
   features: z.array(AgentFeatureSchema).optional(),
+  /** Effective provider options: `config.json` defaults deep-merged with the agent's own. */
+  options: ProviderOptionsSchema.optional(),
+  controls: z.array(AgentOptionControlSchema).optional(),
   thinkingOptionId: z.string().nullable().optional(),
   effectiveThinkingOptionId: z.string().nullable().optional(),
   createdAt: z.string(),
@@ -2055,7 +2093,10 @@ export const AgentConfigApplySchema = z.object({
   modelId: z.string().nullable().optional(),
   modeId: z.string().optional(),
   thinkingOptionId: z.string().nullable().optional(),
+  // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. Maps to an options patch.
   featureValues: z.record(z.string(), z.unknown()).optional(),
+  /** Patch of the agent's own options: replaces top-level keys; `null` removes the key. */
+  options: ProviderOptionsSchema.optional(),
 });
 
 export type AgentConfigApply = z.infer<typeof AgentConfigApplySchema>;
@@ -2971,7 +3012,9 @@ const ListCommandsDraftConfigSchema = z.object({
   modeId: z.string().optional(),
   model: z.string().optional(),
   thinkingOptionId: z.string().optional(),
+  // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. Folded into providerOptions.
   featureValues: z.record(z.string(), z.unknown()).optional(),
+  providerOptions: ProviderOptionsSchema.optional(),
 });
 
 export const ListProviderFeaturesRequestMessageSchema = z.object({
@@ -2980,6 +3023,12 @@ export const ListProviderFeaturesRequestMessageSchema = z.object({
   requestId: z.string(),
 });
 
+export const ProviderControlsListRequestMessageSchema = z.object({
+  type: z.literal("provider.controls.list.request"),
+  draftConfig: ListCommandsDraftConfigSchema,
+  requestId: z.string(),
+});
+
 export const ListCommandsRequestSchema = z.object({
   type: z.literal("list_commands_request"),
   agentId: z.string(),
@@ -3157,6 +3206,7 @@ export const HubExecutionAgentCreateRequestSchema = z.object({
   model: z.string().optional(),
   modeId: z.string().optional(),
   thinkingOptionId: z.string().optional(),
+  // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. Folded into providerOptions.
   featureValues: z.record(z.string(), z.unknown()).optional(),
   providerOptions: ProviderOptionsSchema.optional(),
   toolPolicy: ToolPolicySchema.optional(),
@@ -3357,6 +3407,7 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
   ListProviderModelsRequestMessageSchema,
   ListProviderModesRequestMessageSchema,
   ListProviderFeaturesRequestMessageSchema,
+  ProviderControlsListRequestMessageSchema,
   ListAvailableProvidersRequestMessageSchema,
   GetProvidersSnapshotRequestMessageSchema,
   RefreshProvidersSnapshotRequestMessageSchema,
@@ -3836,6 +3887,7 @@ export const ServerInfoStatusPayloadSchema = z
         selectiveAgentTimeline: z.boolean().optional(),
         explicitEventSubscriptions: z.boolean().optional(),
         ownedSubscriptions: z.boolean().optional(),
+        providerOptionControls: z.boolean().optional(),
         binaryChunkingV1: z.boolean().optional(),
         workspaceSetupObservation: z.boolean().optional(),
         workspaceSortTimes: z.boolean().optional(),
@@ -6303,6 +6355,19 @@ export const ListProviderModesResponseMessageSchema = z.object({
   }),
 });
 
+export const ProviderControlsListResponseMessageSchema = z.object({
+  type: z.literal("provider.controls.list.response"),
+  payload: z.object({
+    provider: AgentProviderSchema,
+    controls: z.array(AgentOptionControlSchema).optional(),
+    /** Effective options for the draft: `config.json` defaults merged with the draft's own. */
+    options: ProviderOptionsSchema.optional(),
+    error: z.string().nullable().optional(),
+    fetchedAt: z.string(),
+    requestId: z.string(),
+  }),
+});
+
 export const ListProviderFeaturesResponseMessageSchema = z.object({
   type: z.literal("list_provider_features_response"),
   payload: z.object({
@@ -7195,6 +7260,7 @@ export const SessionOutboundMessageSchema = z.discriminatedUnion("type", [
   ListProviderModelsResponseMessageSchema,
   ListProviderModesResponseMessageSchema,
   ListProviderFeaturesResponseMessageSchema,
+  ProviderControlsListResponseMessageSchema,
   ListAvailableProvidersResponseSchema,
   GetProvidersSnapshotResponseMessageSchema,
   ProvidersSnapshotUpdateMessageSchema,
@@ -7449,6 +7515,12 @@ export type ListProviderModelsRequestMessage = z.infer<
   typeof ListProviderModelsRequestMessageSchema
 >;
 export type ListProviderModesRequestMessage = z.infer<typeof ListProviderModesRequestMessageSchema>;
+export type ProviderControlsListRequestMessage = z.infer<
+  typeof ProviderControlsListRequestMessageSchema
+>;
+export type ProviderControlsListResponseMessage = z.infer<
+  typeof ProviderControlsListResponseMessageSchema
+>;
 export type ListProviderFeaturesRequestMessage = z.infer<
   typeof ListProviderFeaturesRequestMessageSchema
 >;

packages/protocol/src/option-controls.ts

@@ -0,0 +1,107 @@
+import type {
+  AgentFeature,
+  AgentOptionControl,
+  AgentOptionSelectControl,
+  ProviderOptions,
+} from "./agent-types.js";
+
+// COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01.
+// `features` are controls with their value attached. The daemon builds them for apps that
+// predate controls, and the client package rebuilds controls and options from them when it
+// talks to a daemon that predates controls. Both directions live here so they stay inverse.
+
+function selectedChoice(control: AgentOptionSelectControl, options: ProviderOptions) {
+  const value = options[control.key];
+  if (typeof value === "string") {
+    const choice = control.choices.find((candidate) => candidate.value === value);
+    if (choice) return choice.value;
+  }
+  return control.defaultValue ?? null;
+}
+
+function describe(control: { description?: string; tooltip?: string; icon?: string }): {
+  description?: string;
+  tooltip?: string;
+  icon?: string;
+} {
+  return {
+    ...(control.description !== undefined ? { description: control.description } : {}),
+    ...(control.tooltip !== undefined ? { tooltip: control.tooltip } : {}),
+    ...(control.icon !== undefined ? { icon: control.icon } : {}),
+  };
+}
+
+function featureFromControl(control: AgentOptionControl, effective: ProviderOptions): AgentFeature {
+  if (control.type === "toggle") {
+    const value = effective[control.key];
+    return {
+      type: "toggle",
+      id: control.key,
+      label: control.label,
+      ...describe(control),
+      value: typeof value === "boolean" ? value : (control.defaultValue ?? false),
+    };
+  }
+  return {
+    type: "select",
+    id: control.key,
+    label: control.label,
+    ...describe(control),
+    ...(control.desktopTrigger ? { desktopTrigger: control.desktopTrigger } : {}),
+    value: selectedChoice(control, effective),
+    options: control.choices.map((choice) => ({
+      id: choice.value,
+      label: choice.label,
+      ...(choice.description ? { description: choice.description } : {}),
+      ...(choice.value === control.defaultValue ? { isDefault: true } : {}),
+    })),
+  };
+}
+
+/** Apps that predate controls render `features`; build them from controls + effective options. */
+export function featuresFromControls(input: {
+  controls: readonly AgentOptionControl[] | undefined;
+  options: ProviderOptions | undefined;
+}): AgentFeature[] {
+  const { controls, options } = input;
+  const effective = options ?? {};
+  return (controls ?? []).map((control) => featureFromControl(control, effective));
+}
+
+/** A recorded feature's value is not carried over: controls hold no state, only `options` do. */
+function controlFromFeature(feature: AgentFeature): AgentOptionControl {
+  const descriptor = {
+    key: feature.id,
+    label: feature.label,
+    ...describe(feature),
+  };
+  if (feature.type === "toggle") {
+    return { type: "toggle", ...descriptor };
+  }
+  const defaultChoice = feature.options.find((option) => option.isDefault);
+  return {
+    type: "select",
+    ...descriptor,
+    ...(feature.desktopTrigger ? { desktopTrigger: feature.desktopTrigger } : {}),
+    ...(defaultChoice ? { defaultValue: defaultChoice.id } : {}),
+    choices: feature.options.map((option) => ({
+      value: option.id,
+      label: option.label,
+      ...(option.description ? { description: option.description } : {}),
+    })),
+  };
+}
+
+/** Agent records and daemons that predate controls carry `features`; their descriptors become controls. */
+export function controlsFromFeatures(
+  features: readonly AgentFeature[] | undefined,
+): AgentOptionControl[] {
+  return (features ?? []).map(controlFromFeature);
+}
+
+/** The options a list of `features` stands for: each feature's value under its id. */
+export function optionsFromFeatures(
+  features: readonly AgentFeature[] | undefined,
+): ProviderOptions {
+  return Object.fromEntries((features ?? []).map((feature) => [feature.id, feature.value]));
+}

packages/protocol/src/schedule/types.ts

@@ -34,6 +34,7 @@ export const ScheduleTargetSchema = z.discriminatedUnion("type", [
       isolation: z.enum(["local", "worktree"]).optional(),
       title: z.string().trim().min(1).nullable().optional(),
       providerOptions: z.record(z.string(), z.unknown()).optional(),
+      // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. Folded into providerOptions.
       featureValues: z.record(z.string(), z.unknown()).optional(),
       systemPrompt: z.string().optional(),
       mcpServers: z.record(z.string(), z.unknown()).optional(),

packages/server/src/server/agent/agent-manager.test.ts

@@ -23,6 +23,7 @@ import { AgentStorage } from "./agent-storage.js";
 import { InMemoryAgentTimelineStore } from "./agent-timeline-store.js";
 import { limitAgentTimelineItemContent } from "./agent-timeline-content.js";
 import { toAgentPayload } from "./agent-projections.js";
+import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
 import { projectTimelineRows } from "./timeline-projection.js";
 import { getOpenAgentTabLabel, PARENT_AGENT_ID_LABEL } from "@getpaseo/protocol/agent-labels";
 import { startAgentRun } from "./agent-prompt.js";
@@ -38,7 +39,7 @@ import type {
 import type {
   AgentClient,
   AgentCreateSessionOptions,
-  AgentFeature,
+  AgentOptionControl,
   AgentLaunchContext,
   AgentPromptInput,
   AgentProvider,
@@ -57,6 +58,7 @@ import type {
 } from "./agent-sdk-types.js";
 import type { PaseoToolCatalog } from "./tools/types.js";
 import type { ProviderDefinition } from "./provider-registry.js";
+import { mergeProviderOptions } from "./provider-options.js";
 
 const DESKTOP_OPEN_AGENT_TAB_LABEL = getOpenAgentTabLabel("desktop-client");
 const MOBILE_OPEN_AGENT_TAB_LABEL = getOpenAgentTabLabel("mobile-client");
@@ -182,13 +184,8 @@ class RecordingTimelineStore implements AgentTimelineStore {
   }
 }
 
-function createFeature(args: { id: string; label: string; value: boolean }): AgentFeature {
+function createControl(args: { key: string; label: string }): AgentOptionControl {
-  return {
+  return { type: "toggle", key: args.key, label: args.label };
-    type: "toggle",
-    id: args.id,
-    label: args.label,
-    value: args.value,
-  };
 }
 
 function expectArchivedAgentRecord(
@@ -2332,7 +2329,7 @@ test("listDraftCommands uses explicit model config without default model fetchin
   ]);
 });
 
-test("listDraftFeatures does not start a fallback session without a model", async () => {
+test("listDraftControls does not start a fallback session without a model", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-draft-features-"));
   const storagePath = join(workdir, "agents");
   const storage = new AgentStorage(storagePath, logger);
@@ -2365,18 +2362,21 @@ test("listDraftFeatures does not start a fallback session without a model", asyn
     logger,
   });
 
-  await expect(manager.listDraftFeatures({ provider: "codex", cwd: workdir })).resolves.toEqual([]);
+  await expect(manager.listDraftControls({ provider: "codex", cwd: workdir })).resolves.toEqual({
+    controls: [],
+    options: {},
+  });
 
   expect(client.fetchCatalogCalls).toBe(0);
   expect(client.createSessionCalls).toBe(0);
   expect(client.availabilityCalls).toBe(0);
 });
 
-test("listDraftFeatures uses client feature listing without a model", async () => {
+test("listDraftControls uses client feature listing without a model", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-draft-features-"));
   const storagePath = join(workdir, "agents");
   const storage = new AgentStorage(storagePath, logger);
-  const draftFeature = createFeature({ id: "auto_accept", label: "Auto Accept", value: false });
+  const draftControl = createControl({ key: "auto_accept", label: "Auto Accept" });
   class DraftFeatureClient extends TestAgentClient {
     fetchCatalogCalls = 0;
     createSessionCalls = 0;
@@ -2398,9 +2398,9 @@ test("listDraftFeatures uses client feature listing without a model", async () =
       return await super.createSession(config);
     }
 
-    async listFeatures(config: AgentSessionConfig): Promise<AgentFeature[]> {
+    async listControls(config: AgentSessionConfig): Promise<AgentOptionControl[]> {
       this.featureConfigs.push(config);
-      return [draftFeature];
+      return [draftControl];
     }
   }
   const client = new DraftFeatureClient();
@@ -2412,9 +2412,13 @@ test("listDraftFeatures uses client feature listing without a model", async () =
     logger,
   });
 
-  await expect(manager.listDraftFeatures({ provider: "codex", cwd: workdir })).resolves.toEqual([
+  await expect(
-    draftFeature,
+    manager.listDraftControls({
-  ]);
+      provider: "codex",
+      cwd: workdir,
+      providerOptions: { auto_accept: true },
+    }),
+  ).resolves.toEqual({ controls: [draftControl], options: { auto_accept: true } });
 
   expect(client.fetchCatalogCalls).toBe(0);
   expect(client.createSessionCalls).toBe(0);
@@ -2423,15 +2427,28 @@ test("listDraftFeatures uses client feature listing without a model", async () =
     {
       provider: "codex",
       cwd: workdir,
+      providerOptions: { auto_accept: true },
     },
   ]);
+
+  // Options without a control come back too.
+  await expect(
+    manager.listDraftControls({
+      provider: "codex",
+      cwd: workdir,
+      providerOptions: { auto_accept: true, sandbox_mode: "workspace-write" },
+    }),
+  ).resolves.toEqual({
+    controls: [draftControl],
+    options: { auto_accept: true, sandbox_mode: "workspace-write" },
+  });
 });
 
-test("listDraftFeatures uses explicit model config without default model fetching", async () => {
+test("listDraftControls uses explicit model config without default model fetching", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-draft-features-"));
   const storagePath = join(workdir, "agents");
   const storage = new AgentStorage(storagePath, logger);
-  const draftFeature = createFeature({ id: "fast_mode", label: "Fast mode", value: false });
+  const draftControl = createControl({ key: "web_search", label: "Fast mode" });
   class DraftFeatureClient extends TestAgentClient {
     fetchCatalogCalls = 0;
     createSessionCalls = 0;
@@ -2447,9 +2464,9 @@ test("listDraftFeatures uses explicit model config without default model fetchin
       return await super.createSession(config);
     }
 
-    async listFeatures(config: AgentSessionConfig): Promise<AgentFeature[]> {
+    async listControls(config: AgentSessionConfig): Promise<AgentOptionControl[]> {
       this.featureConfigs.push(config);
-      return [draftFeature];
+      return [draftControl];
     }
   }
   const client = new DraftFeatureClient();
@@ -2461,13 +2478,13 @@ test("listDraftFeatures uses explicit model config without default model fetchin
     logger,
   });
 
-  const features = await manager.listDraftFeatures({
+  const draft = await manager.listDraftControls({
     provider: "codex",
     cwd: workdir,
     model: "gpt-5.4",
   });
 
-  expect(features).toEqual([draftFeature]);
+  expect(draft).toEqual({ controls: [draftControl], options: {} });
   expect(client.fetchCatalogCalls).toBe(0);
   expect(client.createSessionCalls).toBe(0);
   expect(client.featureConfigs).toEqual([
@@ -4550,6 +4567,46 @@ test("resumeAgentFromPersistence keeps metadata config, applies overrides, and p
   });
 });
 
+test("importProviderSession reports the defaults the session launched with, not defaults edited during the import", async () => {
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-import-options-"));
+  let tier = "default";
+  class ImportClient extends TestAgentClient {
+    effectiveOptions(own: ProviderOptions | undefined): ProviderOptions {
+      return { service_tier: tier, ...own };
+    }
+
+    async importSession(input: ImportProviderSessionInput) {
+      // The user edits the default in config.json after the provider has launched.
+      tier = "fast";
+      return {
+        session: new TestAgentSession({ provider: "codex", cwd: workdir }),
+        config: { provider: "codex" as const, cwd: workdir },
+        persistence: {
+          provider: "codex" as const,
+          sessionId: input.providerHandleId,
+          nativeHandle: input.providerHandleId,
+          metadata: { provider: "codex", cwd: workdir },
+        },
+        timeline: [],
+      };
+    }
+  }
+  const manager = new AgentManager({
+    clients: { codex: new ImportClient() },
+    registry: new AgentStorage(join(workdir, "agents"), logger),
+    logger,
+  });
+
+  const imported = await manager.importProviderSession({
+    provider: "codex",
+    providerHandleId: "thread-selected",
+    cwd: workdir,
+    workspaceId: "ws-imported",
+  });
+
+  expect(imported.effectiveOptions).toEqual({ service_tier: "default" });
+});
+
 test("importProviderSession imports the selected session without listing and publishes ready state", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-import-session-"));
   const storagePath = join(workdir, "agents");
@@ -9984,16 +10041,13 @@ test("respondToPermission updates currentModeId after plan approval", async () =
   expect(client.resumedModeId).toBe("acceptEdits");
 });
 
-test("respondToPermission refreshes features and runtime info after provider-managed plan approval", async () => {
+test("respondToPermission applies provider option changes and refreshes runtime info after provider-managed plan approval", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-test-"));
   const storagePath = join(workdir, "agents");
   const storage = new AgentStorage(storagePath, logger);
 
   class RefreshingPermissionSession extends TestAgentSession {
-    private featureState: AgentFeature[] = [
+    private planMode = true;
-      createFeature({ id: "fast_mode", label: "Fast", value: true }),
-      createFeature({ id: "plan_mode", label: "Plan", value: true }),
-    ];
     private modeId = "auto";
     private pending = [
       {
@@ -10005,8 +10059,11 @@ test("respondToPermission refreshes features and runtime info after provider-man
       },
     ];
 
-    get features(): AgentFeature[] {
+    get controls(): AgentOptionControl[] {
-      return this.featureState;
+      return [
+        createControl({ key: "web_search", label: "Fast" }),
+        createControl({ key: "plan_mode", label: "Plan" }),
+      ];
     }
 
     override async getRuntimeInfo() {
@@ -10015,7 +10072,7 @@ test("respondToPermission refreshes features and runtime info after provider-man
         sessionId: this.id,
         model: "gpt-5.4",
         modeId: this.modeId,
-        extra: { collaborationMode: this.features[1]?.value ? "Plan" : "Code" },
+        extra: { collaborationMode: this.planMode ? "Plan" : "Code" },
       };
     }
 
@@ -10030,10 +10087,12 @@ test("respondToPermission refreshes features and runtime info after provider-man
     override async respondToPermission(): Promise<void> {
       this.modeId = "auto";
       this.pending = [];
-      this.featureState = [
+      this.planMode = false;
-        createFeature({ id: "fast_mode", label: "Fast", value: true }),
+      this.pushEvent({
-        createFeature({ id: "plan_mode", label: "Plan", value: false }),
+        type: "options_changed",
-      ];
+        provider: this.provider,
+        patch: { plan_mode: false },
+      });
     }
   }
 
@@ -10056,6 +10115,7 @@ test("respondToPermission refreshes features and runtime info after provider-man
     {
       provider: "codex",
       cwd: workdir,
+      providerOptions: { web_search: true, plan_mode: true },
     },
     undefined,
     { workspaceId: undefined },
@@ -10080,20 +10140,14 @@ test("respondToPermission refreshes features and runtime info after provider-man
 
   const updated = manager.getAgent(snapshot.id);
   expect(updated?.pendingPermissions.size).toBe(0);
-  expect(updated?.features).toEqual([
+  expect(updated?.effectiveOptions).toEqual({ web_search: true, plan_mode: false });
-    createFeature({ id: "fast_mode", label: "Fast", value: true }),
-    createFeature({ id: "plan_mode", label: "Plan", value: false }),
-  ]);
   expect(updated?.runtimeInfo).toMatchObject({
     model: "gpt-5.4",
     extra: { collaborationMode: "Code" },
   });
 
   const persisted = await storage.get(snapshot.id);
-  expect(persisted?.features).toEqual([
+  expect(persisted?.config?.providerOptions).toEqual({ web_search: true, plan_mode: false });
-    createFeature({ id: "fast_mode", label: "Fast", value: true }),
-    createFeature({ id: "plan_mode", label: "Plan", value: false }),
-  ]);
 });
 
 test("respondToPermission emits refreshed state before permission_resolved", async () => {
@@ -10102,9 +10156,6 @@ test("respondToPermission emits refreshed state before permission_resolved", asy
   const storage = new AgentStorage(storagePath, logger);
 
   class OrderedPermissionSession extends TestAgentSession {
-    private featureState: AgentFeature[] = [
-      createFeature({ id: "fast_mode", label: "Fast", value: true }),
-    ];
     private modeId = "plan";
     private pending = [
       {
@@ -10116,8 +10167,8 @@ test("respondToPermission emits refreshed state before permission_resolved", asy
       },
     ];
 
-    get features(): AgentFeature[] {
+    get controls(): AgentOptionControl[] {
-      return this.featureState;
+      return [createControl({ key: "web_search", label: "Fast" })];
     }
 
     override async getRuntimeInfo() {
@@ -10138,6 +10189,11 @@ test("respondToPermission emits refreshed state before permission_resolved", asy
     }
 
     override async respondToPermission(): Promise<void> {
+      this.pushEvent({
+        type: "options_changed",
+        provider: this.provider,
+        patch: { web_search: false },
+      });
       this.pushEvent({
         type: "permission_resolved",
         provider: this.provider,
@@ -10145,7 +10201,6 @@ test("respondToPermission emits refreshed state before permission_resolved", asy
         resolution: { behavior: "allow" },
       });
       this.modeId = "acceptEdits";
-      this.featureState = [createFeature({ id: "fast_mode", label: "Fast", value: false })];
       this.pending = [];
     }
   }
@@ -10169,6 +10224,7 @@ test("respondToPermission emits refreshed state before permission_resolved", asy
     {
       provider: "codex",
       cwd: workdir,
+      providerOptions: { web_search: true },
     },
     undefined,
     { workspaceId: undefined },
@@ -10180,9 +10236,8 @@ test("respondToPermission emits refreshed state before permission_resolved", asy
       return;
     }
     if (event.type === "agent_state" && event.agent.id === snapshot.id) {
-      const fastMode = event.agent.features?.find((feature) => feature.id === "fast_mode");
       seen.push(
-        `state:${event.agent.currentModeId}:${String(fastMode?.type === "toggle" ? fastMode.value : null)}`,
+        `state:${event.agent.currentModeId}:${String(event.agent.effectiveOptions?.web_search)}`,
       );
       return;
     }
@@ -12695,3 +12750,478 @@ test("an out-of-band command racing idle cleanup waits for the resumed runtime",
   expect(h.commands).toEqual(["/maintenance"]);
   expect(h.prompts).toEqual([]);
 });
+
+describe("agent options", () => {
+  class OptionsSession extends TestAgentSession {
+    readonly applied: ProviderOptions[] = [];
+    rejectWith: Error | null = null;
+    applyGate: Promise<void> | null = null;
+    /** What the session says it ended up with after the next apply. */
+    ended: Record<string, unknown> = {};
+    openOptionsPatch: Record<string, unknown> = {};
+
+    async applyOptions(options: ProviderOptions): Promise<Record<string, unknown>> {
+      if (this.rejectWith) throw this.rejectWith;
+      await this.applyGate;
+      this.applied.push(options);
+      return this.ended;
+    }
+  }
+
+  class OptionsClient extends TestAgentClient {
+    session: OptionsSession | null = null;
+    openOptionsPatch: Record<string, unknown> = {};
+
+    // Stands in for the `config.json` provider defaults the registry wrapper merges in.
+    effectiveOptions(own: ProviderOptions | undefined): ProviderOptions {
+      return { service_tier: "default", ...own };
+    }
+
+    override async createSession(config: AgentSessionConfig): Promise<AgentSession> {
+      this.session = new OptionsSession(config);
+      this.session.openOptionsPatch = this.openOptionsPatch;
+      return this.session;
+    }
+  }
+
+  async function createOptionsAgent(
+    providerOptions?: ProviderOptions,
+    openOptionsPatch: Record<string, unknown> = {},
+  ) {
+    const workdir = mkdtempSync(join(tmpdir(), "agent-manager-options-"));
+    const storage = new AgentStorage(join(workdir, "agents"), logger);
+    const client = new OptionsClient();
+    client.openOptionsPatch = openOptionsPatch;
+    const manager = new AgentManager({ clients: { codex: client }, registry: storage, logger });
+    const agent = await manager.createAgent(
+      { provider: "codex", cwd: workdir, ...(providerOptions ? { providerOptions } : {}) },
+      undefined,
+      { workspaceId: undefined },
+    );
+    return { manager, client, storage, agentId: agent.id };
+  }
+
+  test("config.json defaults show as effective options without entering the agent's own options", async () => {
+    const { manager, agentId } = await createOptionsAgent({ web_search: true });
+
+    const agent = manager.getAgent(agentId);
+    expect(agent?.config.providerOptions).toEqual({ web_search: true });
+    expect(agent?.effectiveOptions).toEqual({ service_tier: "default", web_search: true });
+    expect(toAgentPayload(agent!).options).toEqual({ service_tier: "default", web_search: true });
+  });
+
+  test("setAgentOptions hands the provider only the keys the patch sets", async () => {
+    const { manager, client, storage, agentId } = await createOptionsAgent({ web_search: true });
+
+    await manager.setAgentOptions(agentId, { service_tier: "fast" });
+
+    expect(client.session?.applied).toEqual([{ service_tier: "fast" }]);
+    const agent = manager.getAgent(agentId);
+    expect(agent?.config.providerOptions).toEqual({ web_search: true, service_tier: "fast" });
+    expect(agent?.effectiveOptions).toEqual({ service_tier: "fast", web_search: true });
+    await manager.flush();
+    expect((await storage.get(agentId))?.config?.providerOptions).toEqual({
+      web_search: true,
+      service_tier: "fast",
+    });
+  });
+
+  test("a patch key is resolved against the configured defaults, merging nested objects", async () => {
+    const workdir = mkdtempSync(join(tmpdir(), "agent-manager-options-"));
+    const client = new OptionsClient();
+    client.effectiveOptions = (own) =>
+      mergeProviderOptions({ sandbox: { enabled: true, failIfUnavailable: true } }, own) ?? {};
+    const manager = new AgentManager({
+      clients: { codex: client },
+      registry: new AgentStorage(join(workdir, "agents"), logger),
+      logger,
+    });
+    const agent = await manager.createAgent({ provider: "codex", cwd: workdir }, undefined, {
+      workspaceId: undefined,
+    });
+
+    await manager.setAgentOptions(agent.id, {
+      sandbox: { network: { allowedDomains: ["a.test"] } },
+    });
+
+    expect(client.session?.applied).toEqual([
+      {
+        sandbox: {
+          enabled: true,
+          failIfUnavailable: true,
+          network: { allowedDomains: ["a.test"] },
+        },
+      },
+    ]);
+    expect(manager.getAgent(agent.id)?.config.providerOptions).toEqual({
+      sandbox: { network: { allowedDomains: ["a.test"] } },
+    });
+    // The snapshot shows what the provider was given, defaults included, and keeps showing it.
+    await manager.markAgentUnread(agent.id);
+    expect(manager.getAgent(agent.id)?.effectiveOptions).toEqual({
+      sandbox: {
+        enabled: true,
+        failIfUnavailable: true,
+        network: { allowedDomains: ["a.test"] },
+      },
+    });
+  });
+
+  test("setAgentOptions sends a removal to the provider like any change, as the default it falls back to", async () => {
+    const { manager, client, agentId } = await createOptionsAgent({ service_tier: "fast" });
+
+    await manager.setAgentOptions(agentId, { service_tier: null });
+
+    expect(client.session?.applied).toEqual([{ service_tier: "default" }]);
+    const agent = manager.getAgent(agentId);
+    expect(agent?.config.providerOptions).toBeUndefined();
+    expect(agent?.effectiveOptions).toEqual({ service_tier: "default" });
+  });
+
+  test("a removal with no default is sent as null", async () => {
+    const { manager, client, agentId } = await createOptionsAgent({ web_search: true });
+
+    await manager.setAgentOptions(agentId, { web_search: null });
+
+    expect(client.session?.applied).toEqual([{ web_search: null }]);
+    expect(manager.getAgent(agentId)?.config.providerOptions).toBeUndefined();
+  });
+
+  test("a value the provider kept through a removal is stored", async () => {
+    const { manager, client, agentId } = await createOptionsAgent({ web_search: true });
+    client.session!.ended = { web_search: true };
+
+    await manager.setAgentOptions(agentId, { web_search: null });
+
+    const agent = manager.getAgent(agentId);
+    expect(agent?.config.providerOptions).toEqual({ web_search: true });
+    expect(agent?.effectiveOptions).toEqual({ service_tier: "default", web_search: true });
+  });
+
+  test("what the provider ended up with is stored together with the patch", async () => {
+    const { manager, client, agentId } = await createOptionsAgent();
+    client.session!.ended = { service_tier: "slow" };
+
+    await manager.setAgentOptions(agentId, { service_tier: "fast", plan_mode: true });
+
+    expect(manager.getAgent(agentId)?.config.providerOptions).toEqual({
+      service_tier: "slow",
+      plan_mode: true,
+    });
+  });
+
+  test("the difference a session opened with is stored before the agent is published", async () => {
+    const workdir = mkdtempSync(join(tmpdir(), "agent-manager-options-"));
+    const client = new OptionsClient();
+    client.openOptionsPatch = { service_tier: "slow", web_search: null };
+    const manager = new AgentManager({
+      clients: { codex: client },
+      registry: new AgentStorage(join(workdir, "agents"), logger),
+      logger,
+    });
+    const published: Array<ProviderOptions | undefined> = [];
+    manager.subscribe((event) => {
+      if (event.type === "agent_state") published.push(event.agent.config.providerOptions);
+    });
+
+    const agent = await manager.createAgent(
+      { provider: "codex", cwd: workdir, providerOptions: { web_search: true } },
+      undefined,
+      { workspaceId: undefined },
+    );
+
+    expect(agent.config.providerOptions).toEqual({ service_tier: "slow" });
+    expect(published.length).toBeGreaterThan(0);
+    expect(published.every((options) => options?.service_tier === "slow")).toBe(true);
+  });
+
+  test("a default edited while the session is opening does not change the opening snapshot", async () => {
+    const workdir = mkdtempSync(join(tmpdir(), "agent-manager-options-"));
+    const client = new OptionsClient();
+    let tier = "default";
+    client.effectiveOptions = (own) => ({ service_tier: tier, ...own });
+    const open = client.createSession.bind(client);
+    client.createSession = async (config) => {
+      const session = await open(config);
+      // The user edits the default in config.json after the provider has launched.
+      tier = "fast";
+      return session;
+    };
+    const manager = new AgentManager({
+      clients: { codex: client },
+      registry: new AgentStorage(join(workdir, "agents"), logger),
+      logger,
+    });
+
+    const agent = await manager.createAgent({ provider: "codex", cwd: workdir }, undefined, {
+      workspaceId: undefined,
+    });
+
+    expect(agent.effectiveOptions).toEqual({ service_tier: "default" });
+  });
+
+  test("an option the session dropped when opening does not come back from a configured default", async () => {
+    const { manager, agentId } = await createOptionsAgent(undefined, { service_tier: null });
+
+    const agent = manager.getAgent(agentId);
+    expect(agent?.effectiveOptions).toEqual({});
+    await manager.markAgentUnread(agentId);
+    expect(toAgentPayload(manager.getAgent(agentId)!).options).toEqual({});
+  });
+
+  test("an option without a control is settable through the patch and readable in the snapshot", async () => {
+    const { manager, client, storage, agentId } = await createOptionsAgent();
+
+    await manager.setAgentOptions(agentId, { sandbox_mode: "read-only" });
+
+    expect(client.session?.applied).toEqual([{ sandbox_mode: "read-only" }]);
+    const agent = manager.getAgent(agentId);
+    expect(agent?.config.providerOptions).toEqual({ sandbox_mode: "read-only" });
+    expect(toAgentPayload(agent!).options).toEqual({
+      service_tier: "default",
+      sandbox_mode: "read-only",
+    });
+    await manager.flush();
+    expect((await storage.get(agentId))?.config?.providerOptions).toEqual({
+      sandbox_mode: "read-only",
+    });
+  });
+
+  test("concurrent patches both land: each is applied to the options as they are when its provider call resolves", async () => {
+    const { manager, client, agentId } = await createOptionsAgent();
+    let release!: () => void;
+    client.session!.applyGate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+
+    const slow = manager.setAgentOptions(agentId, { sandbox_mode: "read-only" });
+    client.session!.applyGate = null;
+    await manager.setAgentOptions(agentId, { web_search: true });
+    release();
+    await slow;
+
+    expect(manager.getAgent(agentId)?.config.providerOptions).toEqual({
+      sandbox_mode: "read-only",
+      web_search: true,
+    });
+  });
+
+  test("a stored agent that is not loaded still reports its effective options", async () => {
+    const { manager, agentId } = await createOptionsAgent({ web_search: true });
+    await manager.closeAgent(agentId);
+    const states: ManagedAgent[] = [];
+    manager.subscribe(
+      (event) => {
+        if (event.type === "agent_state" && event.agent.id === agentId) states.push(event.agent);
+      },
+      { replayState: false },
+    );
+
+    await manager.markAgentUnread(agentId);
+
+    expect(states.at(-1)?.effectiveOptions).toEqual({ service_tier: "default", web_search: true });
+  });
+
+  test("editing a provider default does not change the options of a loaded agent", async () => {
+    const { manager, client, agentId } = await createOptionsAgent({ web_search: true });
+    expect(manager.getAgent(agentId)?.effectiveOptions).toEqual({
+      service_tier: "default",
+      web_search: true,
+    });
+
+    // The user edits the default in config.json while the agent is running.
+    client.effectiveOptions = (own) => ({ service_tier: "fast", ...own });
+    await manager.markAgentUnread(agentId);
+
+    const agent = manager.getAgent(agentId);
+    expect(agent?.effectiveOptions).toEqual({ service_tier: "default", web_search: true });
+    expect(toAgentPayload(agent!).options).toEqual({ service_tier: "default", web_search: true });
+  });
+
+  test("a provider that rejects an option leaves the stored options unchanged", async () => {
+    const { manager, client, agentId } = await createOptionsAgent({ web_search: false });
+    client.session!.rejectWith = new Error("fast mode unavailable");
+
+    await expect(manager.setAgentOptions(agentId, { web_search: true })).rejects.toThrow(
+      "fast mode unavailable",
+    );
+
+    expect(manager.getAgent(agentId)?.config.providerOptions).toEqual({ web_search: false });
+  });
+
+  test("a provider whose session cannot apply options rejects a patch and stores nothing", async () => {
+    // Like a provider with no live option support: the session has no `applyOptions`.
+    class NoOptionsSession extends TestAgentSession {
+      constructor(config: AgentSessionConfig) {
+        super(config);
+        Object.defineProperty(this, "applyOptions", { value: undefined });
+      }
+    }
+    class NoOptionsClient extends TestAgentClient {
+      override async createSession(config: AgentSessionConfig): Promise<AgentSession> {
+        return new NoOptionsSession(config);
+      }
+    }
+    const workdir = mkdtempSync(join(tmpdir(), "agent-manager-no-options-"));
+    const manager = new AgentManager({
+      clients: { codex: new NoOptionsClient() },
+      registry: new AgentStorage(join(workdir, "agents"), logger),
+      logger,
+    });
+    const agent = await manager.createAgent(
+      { provider: "codex", cwd: workdir, providerOptions: { web_search: false } },
+      undefined,
+      { workspaceId: undefined },
+    );
+
+    await expect(manager.setAgentOptions(agent.id, { web_search: true })).rejects.toThrow(
+      /web_search.*cannot change on a running session/,
+    );
+
+    expect(manager.getAgent(agent.id)?.config.providerOptions).toEqual({ web_search: false });
+  });
+
+  test("agent.create.before hook featureValues fold into providerOptions", async () => {
+    const workdir = mkdtempSync(join(tmpdir(), "agent-manager-hook-"));
+    const storage = new AgentStorage(join(workdir, "agents"), logger);
+    const client = new OptionsClient();
+    const manager = new AgentManager({
+      clients: { codex: client },
+      registry: storage,
+      logger,
+      pluginLifecycle: {
+        emit: () => {},
+        before: async (_name, request) => ({
+          ...request,
+          config: { ...request.config, featureValues: { web_search: true } },
+        }),
+      },
+    });
+
+    const created = await manager.createAgent({ provider: "codex", cwd: workdir }, undefined, {
+      workspaceId: undefined,
+    });
+
+    expect(manager.getAgent(created.id)?.config.providerOptions).toEqual({ web_search: true });
+    expect(manager.getAgent(created.id)?.config).not.toHaveProperty("featureValues");
+  });
+
+  test("agent.create.before hook featureValues edit overrides an option the create already set", async () => {
+    const workdir = mkdtempSync(join(tmpdir(), "agent-manager-hook-"));
+    const storage = new AgentStorage(join(workdir, "agents"), logger);
+    const client = new OptionsClient();
+    const manager = new AgentManager({
+      clients: { codex: client },
+      registry: storage,
+      logger,
+      pluginLifecycle: {
+        emit: () => {},
+        // A plugin written against the previous SDK: flips one value, leaves the rest.
+        before: async (name, request) =>
+          name === "agent.create.before"
+            ? {
+                ...request,
+                config: {
+                  ...request.config,
+                  featureValues: { ...request.config.featureValues, web_search: true },
+                },
+              }
+            : request,
+      },
+    });
+
+    const created = await manager.createAgent(
+      { provider: "codex", cwd: workdir, providerOptions: { web_search: false, plan_mode: true } },
+      undefined,
+      { workspaceId: undefined },
+    );
+
+    expect(manager.getAgent(created.id)?.config.providerOptions).toEqual({
+      web_search: true,
+      plan_mode: true,
+    });
+  });
+
+  test("agent.create.before hook leaving featureValues untouched keeps providerOptions edits", async () => {
+    const workdir = mkdtempSync(join(tmpdir(), "agent-manager-hook-"));
+    const storage = new AgentStorage(join(workdir, "agents"), logger);
+    const client = new OptionsClient();
+    const manager = new AgentManager({
+      clients: { codex: client },
+      registry: storage,
+      logger,
+      pluginLifecycle: {
+        emit: () => {},
+        before: async (name, request) =>
+          name === "agent.create.before"
+            ? {
+                ...request,
+                config: {
+                  ...request.config,
+                  providerOptions: { ...request.config.providerOptions, plan_mode: false },
+                },
+              }
+            : request,
+      },
+    });
+
+    const created = await manager.createAgent(
+      { provider: "codex", cwd: workdir, providerOptions: { web_search: false, plan_mode: true } },
+      undefined,
+      { workspaceId: undefined },
+    );
+
+    expect(manager.getAgent(created.id)?.config.providerOptions).toEqual({
+      web_search: false,
+      plan_mode: false,
+    });
+  });
+
+  describe.each([
+    {
+      name: "deletes a key",
+      edit: (values: Record<string, unknown> | undefined) => {
+        const { web_search: _removed, ...rest } = values ?? {};
+        return { featureValues: rest };
+      },
+      expected: { plan_mode: true },
+    },
+    {
+      name: "empties featureValues",
+      edit: () => ({ featureValues: {} }),
+      expected: {},
+    },
+    {
+      name: "drops featureValues",
+      edit: () => ({ featureValues: undefined }),
+      expected: {},
+    },
+  ])("agent.create.before hook that $name", ({ edit, expected }) => {
+    test("removes those options from the new agent", async () => {
+      const workdir = mkdtempSync(join(tmpdir(), "agent-manager-hook-"));
+      const manager = new AgentManager({
+        clients: { codex: new OptionsClient() },
+        registry: new AgentStorage(join(workdir, "agents"), logger),
+        logger,
+        pluginLifecycle: {
+          emit: () => {},
+          before: async (name, request) =>
+            name === "agent.create.before"
+              ? {
+                  ...request,
+                  config: { ...request.config, ...edit(request.config.featureValues) },
+                }
+              : request,
+        },
+      });
+
+      const created = await manager.createAgent(
+        { provider: "codex", cwd: workdir, providerOptions: { web_search: true, plan_mode: true } },
+        undefined,
+        { workspaceId: undefined },
+      );
+
+      expect(manager.getAgent(created.id)?.config.providerOptions).toEqual(expected);
+    });
+  });
+});

packages/server/src/server/agent/agent-manager.ts

@@ -1,4 +1,5 @@
 import type { AttachedAgentTool, PluginAgentToolsRuntime } from "../plugins/agent-tools.js";
+import { ProviderOptionsValidationError } from "./provider-options.js";
 import type { AgentToolResult } from "@getpaseo/plugin/server";
 import type { RuntimeCleanupCandidate } from "./idle-runtime-cleanup/index.js";
 import { ensureAgentLoaded } from "./agent-loading.js";
@@ -33,7 +34,7 @@ import {
   type AgentCreateSessionOptions,
   type AgentResumePurpose,
   type AgentResumeSessionOptions,
-  type AgentFeature,
+  type AgentOptionControl,
   type AgentLaunchContext,
   type AgentSlashCommand,
   type AgentMode,
@@ -59,7 +60,16 @@ import {
   type ListImportableSessionsOptions,
 } from "./agent-sdk-types.js";
 import { buildArchivedAgentRecord, type ArchivedStoredAgentRecord } from "./agent-archive.js";
+import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
 import { toStoredAgentRecord } from "./agent-projections.js";
+import {
+  applyProviderOptionsPatch,
+  exposeFeatureValuesToHook,
+  convertLegacyOptions,
+  resolveAdapter,
+  foldHookFeatureValues,
+  type ProviderOptionsPatch,
+} from "./option-controls.js";
 import type { StoredAgentRecord, AgentStorage } from "./agent-storage.js";
 import type { AgentOwner } from "./agent-owner.js";
 import {
@@ -210,9 +220,6 @@ function buildStoredAgentConfig(record: StoredAgentRecord): AgentSessionConfig {
   if (record.config.thinkingOptionId != null) {
     config.thinkingOptionId = record.config.thinkingOptionId;
   }
-  if (record.config.featureValues != null) {
-    config.featureValues = record.config.featureValues;
-  }
   if (record.config.providerOptions != null) {
     config.providerOptions = record.config.providerOptions;
   }
@@ -428,7 +435,9 @@ interface ManagedAgentBase {
   createdAt: Date;
   updatedAt: Date;
   availableModes: AgentMode[];
-  features?: AgentFeature[];
+  controls?: AgentOptionControl[];
+  /** `config.json` defaults deep-merged with `config.providerOptions`; refreshed on every state emit. */
+  effectiveOptions?: ProviderOptions;
   currentModeId: string | null;
   pendingPermissions: Map<string, AgentPermissionRequest>;
   bufferedPermissionResolutions: Map<
@@ -1243,11 +1252,17 @@ export class AgentManager {
     }
   }
 
-  async listDraftFeatures(config: AgentSessionConfig): Promise<AgentFeature[]> {
+  async listDraftControls(
+    config: AgentSessionConfig,
+  ): Promise<{ controls: AgentOptionControl[]; options: ProviderOptions }> {
     const normalizedConfig = await this.normalizeConfig(config, { resolveDefaultModel: false });
     const client = this.requireClient(normalizedConfig.provider);
-    if (!normalizedConfig.model && !client.listFeatures) {
+    const options = this.effectiveOptionsFor(
-      return [];
+      normalizedConfig.provider,
+      normalizedConfig.providerOptions,
+    );
+    if (!normalizedConfig.model && !client.listControls) {
+      return { controls: [], options };
     }
     const available = await client.isAvailable();
     if (!available) {
@@ -1256,13 +1271,18 @@ export class AgentManager {
       );
     }
 
-    if (client.listFeatures) {
+    if (client.listControls) {
-      return await client.listFeatures(normalizedConfig);
+      return { controls: await client.listControls(normalizedConfig), options };
     }
 
     const session = await client.createSession(normalizedConfig);
     try {
-      return session.features ?? [];
+      // The options a session opens with, as create would report them, so the controls'
+      // selection matches what the first turn runs with.
+      return {
+        controls: session.controls ?? [],
+        options: this.openedEffectiveOptions({ session, launchedOptions: options }),
+      };
     } finally {
       try {
         await session.close();
@@ -1360,12 +1380,23 @@ export class AgentManager {
   ): Promise<ManagedAgent> {
     this.assertAcceptingAgentRegistrations();
     const resolvedAgentId = validateAgentId(agentId ?? this.idFactory(), "createAgent");
+    config = this.withConvertedOptions(config);
     if (this.pluginLifecycle && !config.internal) {
+      const sent = exposeFeatureValuesToHook(config);
       const request = await this.pluginLifecycle.before("agent.create.before", {
-        config,
+        config: sent,
         env: options.env,
       });
-      config = { ...request.config, internal: config.internal };
+      // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. A plugin written
+      // against the previous SDK edits `config.featureValues`.
+      config = {
+        ...foldHookFeatureValues({
+          returned: request.config,
+          sent,
+          convert: (values) => this.convertLegacyOptions(request.config.provider, values),
+        }),
+        internal: config.internal,
+      };
       options = { ...options, env: request.env };
     }
     await this.deleteAgentState(resolvedAgentId);
@@ -1395,9 +1426,11 @@ export class AgentManager {
     );
     const providerLaunchConfig = this.resolveProviderLaunchConfig(launchConfig, launchContext);
     const createOptions = this.buildCreateSessionOptions(options);
+    const launchedOptions = this.launchOptionsFor({ client, own: storedConfig.providerOptions });
     const session = await client.createSession(providerLaunchConfig, launchContext, createOptions);
     await this.requireExternalMcpSupport(session, providerLaunchConfig, launchContext);
     const agent = await this.registerSession(session, storedConfig, resolvedAgentId, {
+      launchedOptions,
       labels: options.labels,
       initialTitle: options.initialTitle,
       workspaceId: options.workspaceId,
@@ -1520,6 +1553,7 @@ export class AgentManager {
       },
     );
     const providerLaunchConfig = this.resolveProviderLaunchConfig(launchConfig, launchContext);
+    const launchedOptions = this.launchOptionsFor({ client, own: storedConfig.providerOptions });
     const session = await client.resumeSession(
       handle,
       providerLaunchConfig,
@@ -1528,6 +1562,7 @@ export class AgentManager {
     );
     await this.requireExternalMcpSupport(session, providerLaunchConfig, launchContext);
     return this.registerSession(session, storedConfig, resolvedAgentId, {
+      launchedOptions,
       ...options,
       launchEnv,
       persistence: handle,
@@ -1583,6 +1618,7 @@ export class AgentManager {
       },
     );
     const providerLaunchConfig = this.resolveProviderLaunchConfig(launchConfig, launchContext);
+    const launchedOptions = this.launchOptionsFor({ client, own: storedConfig.providerOptions });
     const imported = await client.importSession(
       {
         providerHandleId: input.providerHandleId,
@@ -1601,6 +1637,7 @@ export class AgentManager {
 
       handedToRegistration = true;
       const agent = await this.registerSession(imported.session, importedConfig, resolvedAgentId, {
+        launchedOptions,
         labels: input.labels,
         workspaceId: input.workspaceId,
         timelineRows,
@@ -1706,6 +1743,7 @@ export class AgentManager {
       this.assertAcceptingAgentRegistrations();
 
       this.paseoToolPolicies.set(agentId, paseoToolPolicy);
+      const launchedOptions = this.launchOptionsFor({ client, own: storedConfig.providerOptions });
       session = handle
         ? await client.resumeSession(handle, providerLaunchConfig, launchContext)
         : await client.createSession(providerLaunchConfig, launchContext);
@@ -1724,6 +1762,7 @@ export class AgentManager {
       // Preserve existing labels and timeline during reload.
       handedToRegistration = true;
       return this.registerSession(session, storedConfig, agentId, {
+        launchedOptions,
         labels: existing.labels,
         workspaceId: existing.workspaceId,
         owner: existing.owner,
@@ -2161,7 +2200,11 @@ export class AgentManager {
         createdAt: new Date(record.createdAt),
         updatedAt,
         availableModes: [],
-        features: record.features,
+        controls: record.controls,
+        effectiveOptions: this.effectiveOptionsFor(
+          record.provider,
+          record.config?.providerOptions ?? undefined,
+        ),
         currentModeId: record.lastModeId ?? null,
         pendingPermissions: new Map(),
         bufferedPermissionResolutions: new Map(),
@@ -2254,20 +2297,109 @@ export class AgentManager {
     return notice;
   }
 
-  async setAgentFeature(agentId: string, featureId: string, value: unknown): Promise<void> {
+  /**
+   * Applies an options patch to a running agent (see `AgentSession.applyOptions`). The provider
+   * gets each key the patch touches, resolved against the `config.json` defaults, with `null`
+   * where nothing is set. The patch and whatever the provider says it ended up with are stored in
+   * one step once the provider accepts, over the options as they are at that moment, so concurrent
+   * writes to one agent resolve by arrival order.
+   */
+  async setAgentOptions(agentId: string, requested: ProviderOptionsPatch): Promise<void> {
     const agent = this.requireAgent(agentId);
-
+    const patch = this.convertLegacyOptions(agent.provider, requested);
-    if (!agent.session.setFeature) {
+    let ended: ProviderOptionsPatch = {};
-      throw new Error("Agent session does not support setting features");
+    let sent: ProviderOptionsPatch = {};
+    if (Object.keys(patch).length > 0) {
+      // A provider that cannot apply options to a running agent must not store them either.
+      if (!agent.session.applyOptions) {
+        throw new ProviderOptionsValidationError(
+          agent.provider,
+          Object.keys(patch).map((key) => ({
+            path: [key],
+            message: "cannot change on a running session; it applies when the agent is opened",
+          })),
+        );
+      }
+      const set = Object.fromEntries(Object.entries(patch).filter(([, value]) => value != null));
+      const resolved = this.effectiveOptionsFor(agent.provider, set);
+      sent = Object.fromEntries(Object.keys(patch).map((key) => [key, resolved[key] ?? null]));
+      ended = (await agent.session.applyOptions(sent)) ?? {};
+      // Changes the provider made on its own while applying are older than its final answer.
+      await this.drainSessionEvents(agentId);
     }
-
+    this.storeOptionsPatch({ agent, patch: { ...patch, ...ended } });
-    await agent.session.setFeature(featureId, value);
+    this.updateEffectiveOptions({ agent, sent, reported: ended });
-    await this.drainSessionEvents(agentId);
-    agent.config.featureValues = { ...agent.config.featureValues, [featureId]: value };
     this.touchUpdatedAt(agent);
     this.emitState(agent);
   }
 
+  /** The config as the opened session left it: its own difference from the options it was given. */
+  private withOpenedOptions(input: {
+    config: AgentSessionConfig;
+    session: AgentSession;
+  }): AgentSessionConfig {
+    const { config } = input;
+    const opened = input.session.openOptionsPatch;
+    if (!opened || Object.keys(opened).length === 0) return config;
+    const own = applyProviderOptionsPatch({ options: config.providerOptions, patch: opened });
+    return { ...config, providerOptions: Object.keys(own).length > 0 ? own : undefined };
+  }
+
+  private storeOptionsPatch(input: { agent: ManagedAgent; patch: ProviderOptionsPatch }): void {
+    const { agent } = input;
+    const own = applyProviderOptionsPatch({
+      options: agent.config.providerOptions,
+      patch: input.patch,
+    });
+    agent.config.providerOptions = Object.keys(own).length > 0 ? own : undefined;
+  }
+
+  /**
+   * What the running session has: the options it opened with, moved only by what an apply sent
+   * it (defaults merged in, `null` where a removal left nothing) and by what the provider reports
+   * back. The agent's own stored options keep only the raw patch.
+   */
+  private updateEffectiveOptions(input: {
+    agent: ManagedAgent;
+    sent: ProviderOptionsPatch;
+    reported: ProviderOptionsPatch;
+  }): void {
+    input.agent.effectiveOptions = applyProviderOptionsPatch({
+      options: input.agent.effectiveOptions,
+      patch: { ...input.sent, ...input.reported },
+    });
+  }
+
+  /**
+   * Defaults merge into what the session was given; what it reports it ended up with comes
+   * after, so an option it dropped does not come back from a default.
+   */
+  private openedEffectiveOptions(input: {
+    session: AgentSession;
+    launchedOptions: ProviderOptions;
+  }): ProviderOptions {
+    return applyProviderOptionsPatch({
+      options: input.launchedOptions,
+      patch: input.session.openOptionsPatch ?? {},
+    });
+  }
+
+  /** The options a client opens with: its own defaults merged under the agent's. */
+  private launchOptionsFor(input: {
+    client: AgentClient;
+    own: ProviderOptions | undefined;
+  }): ProviderOptions {
+    return input.client.effectiveOptions?.(input.own) ?? input.own ?? {};
+  }
+
+  private effectiveOptionsFor(
+    provider: AgentProvider,
+    own: ProviderOptions | undefined,
+  ): ProviderOptions {
+    const client = this.clients.get(provider);
+    return client ? this.launchOptionsFor({ client, own }) : (own ?? {});
+  }
+
   async setTitle(agentId: string, title: string): Promise<void> {
     const agent = this.requireAgent(agentId);
     const normalizedTitle = title.trim();
@@ -3780,9 +3912,9 @@ export class AgentManager {
 
   private async registerSession(
     session: AgentSession,
-    config: AgentSessionConfig,
+    openedConfig: AgentSessionConfig,
     agentId: string,
-    options?: {
+    options: {
       createdAt?: Date;
       updatedAt?: Date;
       lastUserMessageAt?: Date | null;
@@ -3800,6 +3932,12 @@ export class AgentManager {
        * attention come from what was already recorded, and installing the session is not
        * activity in it.
        */
+      /**
+       * The effective options the opening resolved before the session started. Registration
+       * starts from these rather than reading the defaults again, which may have been edited
+       * while the provider was opening.
+       */
+      launchedOptions: ProviderOptions;
       restoring?: boolean;
       initialTitle?: string | null;
       publishWhenReady?: boolean;
@@ -3811,6 +3949,7 @@ export class AgentManager {
     let registered = false;
     try {
       this.assertAcceptingAgentRegistrations();
+      const config = this.withOpenedOptions({ config: openedConfig, session });
       const resolvedAgentId = validateAgentId(agentId, "registerSession");
       if (this.agents.has(resolvedAgentId)) {
         throw new Error(`Agent with id ${resolvedAgentId} already exists`);
@@ -3832,6 +3971,10 @@ export class AgentManager {
         resolvedAgentId,
         session,
         config,
+        effectiveOptions: this.openedEffectiveOptions({
+          session,
+          launchedOptions: options.launchedOptions,
+        }),
         now,
         durableTimelineHasRows,
         options,
@@ -3976,6 +4119,7 @@ export class AgentManager {
     resolvedAgentId: string;
     session: AgentSession;
     config: AgentSessionConfig;
+    effectiveOptions: ProviderOptions;
     now: Date;
     durableTimelineHasRows: boolean;
     options:
@@ -3995,7 +4139,15 @@ export class AgentManager {
         }
       | undefined;
   }): ActiveManagedAgent {
-    const { resolvedAgentId, session, config, now, durableTimelineHasRows, options } = params;
+    const {
+      resolvedAgentId,
+      session,
+      config,
+      effectiveOptions,
+      now,
+      durableTimelineHasRows,
+      options,
+    } = params;
     return {
       id: resolvedAgentId,
       provider: config.provider,
@@ -4006,6 +4158,8 @@ export class AgentManager {
       session,
       capabilities: session.capabilities,
       config,
+      // What the session opened with. Provider defaults edited later reach it when it next opens.
+      effectiveOptions,
       runtimeInfo: undefined,
       lifecycle: "initializing",
       createdAt: options?.createdAt ?? now,
@@ -4311,7 +4465,7 @@ export class AgentManager {
       agent.pendingPermissions.clear();
     }
 
-    this.syncFeaturesFromSession(agent);
+    this.syncControls(agent);
     await this.refreshRuntimeInfo(agent, options);
   }
 
@@ -4657,6 +4811,18 @@ export class AgentManager {
     );
   }
 
+  private onStreamOptionsChanged(params: {
+    agent: ActiveManagedAgent;
+    patch: ProviderOptionsPatch;
+    flags: StreamEventFlags;
+  }): void {
+    const { agent, patch, flags } = params;
+    this.storeOptionsPatch({ agent, patch });
+    this.updateEffectiveOptions({ agent, sent: {}, reported: patch });
+    flags.shouldDispatchEvent = false;
+    this.emitState(agent);
+  }
+
   private dispatchStreamEventByType(params: {
     agent: ActiveManagedAgent;
     event: AgentStreamEvent;
@@ -4708,6 +4874,9 @@ export class AgentManager {
         flags.shouldDispatchEvent = false;
         this.emitState(agent);
         return undefined;
+      case "options_changed":
+        this.onStreamOptionsChanged({ agent, patch: event.patch, flags });
+        return undefined;
       case "timeline":
         return this.onStreamTimelineEvent({ agent, event, options, flags });
       case "turn_completed":
@@ -5183,7 +5352,7 @@ export class AgentManager {
       this.enqueueBackgroundPersist(agent);
     }
 
-    this.syncFeaturesFromSession(agent);
+    this.syncControls(agent);
 
     this.logger.trace(
       {
@@ -5205,9 +5374,9 @@ export class AgentManager {
     });
   }
 
-  private syncFeaturesFromSession(agent: ManagedAgent): void {
+  private syncControls(agent: ManagedAgent): void {
-    if ("session" in agent && agent.session?.features) {
+    if ("session" in agent && agent.session?.controls) {
-      agent.features = agent.session.features;
+      agent.controls = agent.session.controls;
     }
   }
 
@@ -5454,7 +5623,7 @@ export class AgentManager {
     config: AgentSessionConfig,
     options: NormalizeConfigOptions = {},
   ): Promise<AgentSessionConfig> {
-    const normalized: AgentSessionConfig = { ...config };
+    const normalized: AgentSessionConfig = { ...this.withConvertedOptions(config) };
 
     // Always resolve cwd to absolute path for consistent history file lookup
     if (normalized.cwd) {
@@ -5526,6 +5695,30 @@ export class AgentManager {
     }
   }
 
+  /** The adapter a provider id runs on: a custom provider is named by the one it extends. */
+  private adapterOf(provider: AgentProvider): AgentProvider {
+    return resolveAdapter({
+      provider,
+      extendsOf: (id) => this.providerDefinitions.get(id)?.derivedFromProviderId,
+    });
+  }
+
+  /**
+   * Options older data carries are converted for the adapter the provider runs on, before
+   * defaults merge and before anything is stored; nothing past the manager sees the old keys.
+   */
+  private convertLegacyOptions<T extends ProviderOptions | undefined>(
+    provider: AgentProvider,
+    options: T,
+  ): T {
+    return convertLegacyOptions({ provider: this.adapterOf(provider), options }) as T;
+  }
+
+  private withConvertedOptions(config: AgentSessionConfig): AgentSessionConfig {
+    const providerOptions = this.convertLegacyOptions(config.provider, config.providerOptions);
+    return providerOptions === config.providerOptions ? config : { ...config, providerOptions };
+  }
+
   private async prepareSessionConfig(
     config: AgentSessionConfig,
     agentId: string,

packages/server/src/server/agent/agent-projections.test.ts

@@ -10,7 +10,7 @@ import {
 } from "./agent-projections.js";
 import type { AgentSession } from "./agent-sdk-types.js";
 import type {
-  AgentFeature,
+  AgentOptionControl,
   ImportableProviderSession,
   AgentPermissionRequest,
   AgentPersistenceHandle,
@@ -128,16 +128,6 @@ function createPermission(overrides: Partial<AgentPermissionRequest> = {}): Agen
   return { ...base, ...overrides };
 }
 
-function createFeature(overrides: Partial<AgentFeature> = {}): AgentFeature {
-  return {
-    type: "toggle",
-    id: "fast_mode",
-    label: "Fast mode",
-    value: true,
-    ...overrides,
-  };
-}
-
 describe("toStoredAgentRecord", () => {
   it("captures lifecycle metadata, config, and persistence", () => {
     const agent = createManagedAgent({
@@ -407,6 +397,50 @@ describe("toAgentPayload", () => {
     });
   });
 
+  it("projects a closed agent's stored controls and options", () => {
+    const controls: AgentOptionControl[] = [
+      {
+        type: "select",
+        key: "service_tier",
+        label: "Speed",
+        defaultValue: "default",
+        choices: [
+          { value: "default", label: "Normal" },
+          { value: "priority", label: "Fast" },
+        ],
+      },
+    ];
+    const record = toStoredAgentRecord(
+      createManagedAgent({
+        provider: "codex",
+        lifecycle: "closed",
+        controls,
+        config: {
+          provider: "codex",
+          providerOptions: { service_tier: "priority", sandbox_mode: "read-only" },
+        },
+      }),
+    );
+
+    const payload = buildStoredAgentPayload(record, ["codex"]);
+
+    expect(payload.status).toBe("closed");
+    expect(payload.controls).toEqual(controls);
+    expect(payload.options).toEqual({ service_tier: "priority", sandbox_mode: "read-only" });
+    expect(payload.features).toEqual([
+      {
+        type: "select",
+        id: "service_tier",
+        label: "Speed",
+        value: "priority",
+        options: [
+          { id: "default", label: "Normal", isDefault: true },
+          { id: "priority", label: "Fast" },
+        ],
+      },
+    ]);
+  });
+
   it("carries a stored lastError onto the payload", () => {
     const record = toStoredAgentRecord(
       createManagedAgent({ provider: "codex", config: { provider: "codex" }, lastError: "boom" }),
@@ -474,13 +508,44 @@ describe("toAgentPayload", () => {
     });
   });
 
-  it("includes features in the snapshot payload", () => {
+  it("projects controls, effective options, and legacy features from the same source", () => {
-    const features = [createFeature()];
+    const controls: AgentOptionControl[] = [
-    const agent = createManagedAgent({ features });
+      { type: "toggle", key: "fast_mode", label: "Fast mode" },
+      {
+        type: "select",
+        key: "service_tier",
+        label: "Speed",
+        defaultValue: "default",
+        choices: [
+          { value: "default", label: "Normal" },
+          { value: "fast", label: "Fast" },
+        ],
+      },
+    ];
+    // `config.json` supplies fast_mode; the agent itself sets nothing for service_tier.
+    // Options without a control are part of the snapshot too.
+    const agent = createManagedAgent({
+      controls,
+      effectiveOptions: { fast_mode: true, sandbox_mode: "workspace-write" },
+    });
 
     const payload = toAgentPayload(agent);
 
-    expect(payload.features).toEqual(features);
+    expect(payload.controls).toEqual(controls);
+    expect(payload.options).toEqual({ fast_mode: true, sandbox_mode: "workspace-write" });
+    expect(payload.features).toEqual([
+      { type: "toggle", id: "fast_mode", label: "Fast mode", value: true },
+      {
+        type: "select",
+        id: "service_tier",
+        label: "Speed",
+        value: "default",
+        options: [
+          { id: "default", label: "Normal", isDefault: true },
+          { id: "fast", label: "Fast" },
+        ],
+      },
+    ]);
   });
 });
 

packages/server/src/server/agent/agent-projections.ts

@@ -7,7 +7,7 @@ import type {
 import type { SerializableAgentConfig, StoredAgentRecord } from "./agent-storage.js";
 import type {
   AgentCapabilityFlags,
-  AgentFeature,
+  AgentOptionControl,
   AgentMetadata,
   AgentMode,
   AgentPermissionRequest,
@@ -18,7 +18,9 @@ import type {
   AgentUsage,
   ImportableProviderSession,
 } from "./agent-sdk-types.js";
+import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
 import type { ManagedAgent } from "./agent-manager.js";
+import { featuresFromControls } from "@getpaseo/protocol/option-controls";
 import type { JsonValue } from "../json-utils.js";
 import {
   isStoredAgentProviderAvailable,
@@ -97,7 +99,7 @@ export function toStoredAgentRecord(
     config: config ?? null,
     launchEnv: agent.launchEnv ? { ...agent.launchEnv } : undefined,
     runtimeInfo,
-    features: normalizeFeatures(agent.features),
+    controls: normalizeControls(agent.controls),
     persistence,
     lastError: agent.lastError ?? undefined,
     requiresAttention: agent.attention.requiresAttention,
@@ -143,7 +145,12 @@ export function toAgentPayload(
     capabilities: cloneCapabilities(agent.capabilities),
     currentModeId: agent.currentModeId,
     availableModes: cloneAvailableModes(agent.availableModes),
-    features: normalizeFeatures(agent.features),
+    // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01.
+    features: featuresFromControls({ controls: agent.controls, options: agent.effectiveOptions }),
+    ...(agent.effectiveOptions
+      ? { options: sanitizeEffectiveOptions(agent.effectiveOptions) }
+      : {}),
+    controls: normalizeControls(agent.controls),
     pendingPermissions: sanitizePendingPermissions(agent.pendingPermissions),
     persistence: projectPersistenceHandleForWire(agent.persistence),
     title: options?.title ?? null,
@@ -206,6 +213,21 @@ function buildStoredPersistenceHandle(
   return toAgentPersistenceHandle(validProviders, record.persistence);
 }
 
+function buildStoredOptionControls(
+  record: StoredAgentRecord,
+): Pick<AgentSnapshotPayload, "features" | "options" | "controls"> {
+  const controls = normalizeControls(record.controls);
+  const options = record.config?.providerOptions
+    ? sanitizeEffectiveOptions(record.config.providerOptions)
+    : undefined;
+  return {
+    // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01.
+    features: featuresFromControls({ controls, options }),
+    ...(options ? { options } : {}),
+    controls,
+  };
+}
+
 export function buildStoredAgentPayload(
   record: StoredAgentRecord,
   validProviders: Iterable<AgentProvider>,
@@ -227,6 +249,7 @@ export function buildStoredAgentPayload(
   const lastUserMessageAt = record.lastUserMessageAt ? new Date(record.lastUserMessageAt) : null;
 
   const runtimeInfo = buildStoredRuntimeInfo(record);
+  const optionControls = buildStoredOptionControls(record);
   const providerAvailable = isStoredAgentProviderAvailable(record, validProviders);
   const persistence = projectPersistenceHandleForWire(
     buildStoredPersistenceHandle(record, validProviders),
@@ -251,6 +274,7 @@ export function buildStoredAgentPayload(
     capabilities: defaultCapabilities,
     currentModeId: record.lastModeId ?? null,
     availableModes: [],
+    ...optionControls,
     pendingPermissions: [],
     persistence,
     title: record.title ?? null,
@@ -375,12 +399,6 @@ function buildSerializableConfig(config: AgentSessionConfig): SerializableAgentC
   if (config.thinkingOptionId) {
     serializable.thinkingOptionId = config.thinkingOptionId;
   }
-  if (Object.prototype.hasOwnProperty.call(config, "featureValues")) {
-    const featureValues = sanitizeMetadata(config.featureValues);
-    if (featureValues !== undefined) {
-      serializable.featureValues = featureValues;
-    }
-  }
   if (config.providerOptions !== undefined) {
     const providerOptions = sanitizeOptionalJson(config.providerOptions);
     if (providerOptions && isJsonObject(providerOptions)) {
@@ -456,8 +474,15 @@ function cloneAvailableModes(modes: AgentMode[]): AgentMode[] {
   return modes.map((mode) => ({ ...mode }));
 }
 
-function normalizeFeatures(features: AgentFeature[] | null | undefined): AgentFeature[] {
+function normalizeControls(
-  return Array.isArray(features) ? features.map((feature) => ({ ...feature })) : [];
+  controls: AgentOptionControl[] | null | undefined,
+): AgentOptionControl[] {
+  return Array.isArray(controls) ? controls.map((control) => ({ ...control })) : [];
+}
+
+function sanitizeEffectiveOptions(options: Record<string, unknown>): ProviderOptions {
+  const sanitized = sanitizeOptionalJson(options);
+  return sanitized && isJsonObject(sanitized) ? sanitized : {};
 }
 
 function sanitizeOptionalJson(value: unknown): JsonValue | undefined {

packages/server/src/server/agent/agent-sdk-types.ts

@@ -1,7 +1,7 @@
 import type {
-  AgentFeature,
+  AgentOptionControl,
-  AgentFeatureSelect,
+  AgentOptionSelectControl,
-  AgentFeatureToggle,
+  AgentOptionToggleControl,
   AgentProviderNotice,
   AgentTaskItem,
   JsonValue,
@@ -13,9 +13,9 @@ import type { AgentAttachment } from "@getpaseo/protocol/messages";
 import type { PaseoToolCatalog } from "./tools/types.js";
 
 export type {
-  AgentFeature,
+  AgentOptionControl,
-  AgentFeatureSelect,
+  AgentOptionSelectControl,
-  AgentFeatureToggle,
+  AgentOptionToggleControl,
   AgentProviderNotice,
   AgentTaskItem,
 };
@@ -148,7 +148,7 @@ export interface AgentCreateConfigParent {
 export interface ResolveAgentCreateConfigInput {
   provider: AgentProvider;
   requestedMode: string | undefined;
-  featureValues: Record<string, unknown> | undefined;
+  providerOptions: ProviderOptions | undefined;
   parent: AgentCreateConfigParent | null;
   unattended: boolean;
   availableModes: AgentMode[] | undefined;
@@ -156,13 +156,13 @@ export interface ResolveAgentCreateConfigInput {
 
 export interface ResolveAgentCreateConfigResult {
   modeId: string | undefined;
-  featureValues: Record<string, unknown> | undefined;
+  providerOptions: ProviderOptions | undefined;
 }
 
 export interface AgentCreateConfigUnattendedInput {
   modeId: string | null;
   config: AgentSessionConfig;
-  features?: AgentFeature[];
+  controls?: AgentOptionControl[];
   availableModes: AgentMode[];
 }
 
@@ -429,6 +429,14 @@ export type AgentStreamEvent =
       provider: AgentProvider;
       thinkingOptionId: string | null;
     }
+  /**
+   * The provider changed options on its own: after `createSession`/`resumeSession` or
+   * `applyOptions` it ended up different from what it was given, or later it changed a setting
+   * itself. The daemon stores the patch and forwards it; it does not undo it. `null` removes the
+   * agent's own value. Only for changes that happen on the provider's own initiative: the result
+   * of opening goes in `openOptionsPatch` and the result of `applyOptions` is its return value.
+   */
+  | { type: "options_changed"; provider: AgentProvider; patch: Record<string, unknown> }
   | {
       type: "turn_failed";
       provider: AgentProvider;
@@ -610,7 +618,6 @@ export interface AgentSessionConfig {
   modeId?: string;
   model?: string;
   thinkingOptionId?: string;
-  featureValues?: Record<string, unknown>;
   title?: string | null;
   providerOptions?: ProviderOptions;
   toolPolicy?: ToolPolicy;
@@ -679,7 +686,14 @@ export interface AgentSession {
   readonly provider: AgentProvider;
   readonly id: string | null;
   readonly capabilities: AgentCapabilityFlags;
-  readonly features?: AgentFeature[];
+  /** Composer controls over top-level option keys. Values come from the agent's effective options. */
+  readonly controls?: AgentOptionControl[];
+  /**
+   * How the session ended up different from the options it was opened with, as a patch (`null`
+   * removes a key). Set by the time `createSession`/`resumeSession` resolves; the daemon stores it
+   * before the agent is published.
+   */
+  readonly openOptionsPatch?: Record<string, unknown>;
   /** New provider-owned rows to commit on registration. streamHistory must also
    * replay them at their original timestamps; restored sessions omit old rows. */
   readonly initialTimeline?: ImportedTimelineEntry[];
@@ -714,7 +728,20 @@ export interface AgentSession {
   listCommands?(): Promise<AgentSlashCommand[]>;
   setModel?(modelId: string | null): Promise<void>;
   setThinkingOption?(thinkingOptionId: string | null): Promise<void | AgentProviderNotice>;
-  setFeature?(featureId: string, value: unknown): Promise<void>;
+  /**
+   * Apply an options patch. `options` holds only the keys the patch touches, resolved against
+   * the `config.json` defaults; `null` means nothing is set for the key, so return it to the
+   * session's own default if that can be done. Leave every other setting alone. Throw to reject a
+   * value, or a key the running session cannot apply (one the provider reads only when it
+   * opens): the daemon stores the patch only when this resolves, so a stored option always
+   * describes what runs, and the call is all-or-nothing.
+   * Emit nothing from here. Return the options the session ended up with when they differ from
+   * the request (a patch, `null` removes a key), for example a value it kept because it could not
+   * be reverted; the daemon stores it together with the patch. When a throw leaves the session's
+   * state moved anyway, report the moved values once as `options_changed` after the call has
+   * ended, so the stored options still match what runs.
+   */
+  applyOptions?(options: ProviderOptions): Promise<Record<string, unknown> | void>;
   revertConversation?(input: { messageId: string }): Promise<void>;
   revertFiles?(input: { messageId: string }): Promise<void>;
   revertBoth?(input: { messageId: string }): Promise<void>;
@@ -764,11 +791,17 @@ export interface ResolveAgentDefaultModeInput {
 export interface AgentClient {
   readonly provider: AgentProvider;
   readonly capabilities: AgentCapabilityFlags;
+  /**
+   * Create the agent with `config.providerOptions` (defaults already merged in). Emit nothing
+   * about options while creating. If the agent ended up different from the options, say so in the
+   * session's `openOptionsPatch`.
+   */
   createSession(
     config: AgentSessionConfig,
     launchContext?: AgentLaunchContext,
     options?: AgentCreateSessionOptions,
   ): Promise<AgentSession>;
+  /** Same contract as `createSession`: open with the options, report any difference in `openOptionsPatch`. */
   resumeSession(
     handle: AgentPersistenceHandle,
     overrides?: Partial<AgentSessionConfig>,
@@ -797,7 +830,9 @@ export interface AgentClient {
   resolveCreateConfig?(input: ResolveAgentCreateConfigInput): ResolveAgentCreateConfigResult;
   isCreateConfigUnattended?(input: AgentCreateConfigUnattendedInput): boolean;
   listCommands?(config: AgentSessionConfig): Promise<AgentSlashCommand[]>;
-  listFeatures?(config: AgentSessionConfig): Promise<AgentFeature[]>;
+  listControls?(config: AgentSessionConfig): Promise<AgentOptionControl[]>;
+  /** Effective options: provider defaults from `config.json` deep-merged with the agent's own. */
+  effectiveOptions?(own: ProviderOptions | undefined): ProviderOptions;
   listImportableSessions?(
     options?: ListImportableSessionsOptions,
   ): Promise<ImportableProviderSession[]>;

packages/server/src/server/agent/agent-storage.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test, beforeEach, afterEach } from "vitest";
 import os from "node:os";
 import path from "node:path";
-import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
 import { promises as fs } from "node:fs";
 
 import { createTestLogger } from "../../test-utils/test-logger.js";
@@ -44,9 +44,6 @@ function buildManagedAgentConfig(
     systemPrompt: configOverrides.systemPrompt,
     mcpServers: configOverrides.mcpServers,
   };
-  if (Object.prototype.hasOwnProperty.call(configOverrides, "featureValues")) {
-    config.featureValues = configOverrides.featureValues;
-  }
   return config;
 }
 
@@ -132,6 +129,14 @@ function createManagedAgent(overrides: ManagedAgentOverrides = {}): ManagedAgent
   };
 }
 
+function findRecordFile(baseDir: string, agentId: string): string {
+  for (const entry of readdirSync(baseDir, { withFileTypes: true })) {
+    const candidate = path.join(baseDir, entry.name, `${agentId}.json`);
+    if (entry.isDirectory() && existsSync(candidate)) return candidate;
+  }
+  throw new Error(`No stored record for ${agentId}`);
+}
+
 describe("AgentStorage", () => {
   let tmpDir: string;
   let storagePath: string;
@@ -195,62 +200,77 @@ describe("AgentStorage", () => {
     expect(persisted.config?.providerOptions).toEqual({ allowedTools: ["Read"] });
   });
 
-  test("applySnapshot stores and reloads featureValues when present", async () => {
+  test("applySnapshot stores and reloads composer values as providerOptions", async () => {
     await storage.applySnapshot(
       createManagedAgent({
-        id: "agent-feature-values",
+        id: "agent-provider-options",
-        config: {
+        config: { providerOptions: { fast_mode: true } },
-          featureValues: {
-            fast_mode: true,
-          },
-        },
-      }),
-    );
-
-    const record = await storage.get("agent-feature-values");
-    expect(record?.config?.featureValues).toEqual({ fast_mode: true });
-
-    const reloaded = new AgentStorage(storagePath, logger);
-    const persisted = await reloaded.get("agent-feature-values");
-    expect(persisted?.config?.featureValues).toEqual({ fast_mode: true });
-    expect(buildSessionConfig(persisted!).featureValues).toEqual({ fast_mode: true });
-  });
-
-  test("applySnapshot keeps featureValues absent when they were never set", async () => {
-    await storage.applySnapshot(
-      createManagedAgent({
-        id: "agent-no-feature-values",
       }),
     );
 
     const reloaded = new AgentStorage(storagePath, logger);
-    const persisted = await reloaded.get("agent-no-feature-values");
+    const persisted = await reloaded.get("agent-provider-options");
-    expect(persisted?.config?.featureValues).toBeUndefined();
+    expect(persisted?.config?.providerOptions).toEqual({ fast_mode: true });
-    expect(buildSessionConfig(persisted!).featureValues).toBeUndefined();
+    expect(buildSessionConfig(persisted!).providerOptions).toEqual({ fast_mode: true });
-  });
+    expect(buildConfigOverrides(persisted!)).toMatchObject({
-
-  test("buildConfigOverrides includes featureValues when present in stored config", async () => {
-    await storage.applySnapshot(
-      createManagedAgent({
-        id: "agent-resume-overrides",
-        config: {
-          featureValues: {
-            fast_mode: true,
-          },
-        },
-      }),
-    );
-
-    const record = await storage.get("agent-resume-overrides");
-    expect(record).not.toBeNull();
-    expect(buildConfigOverrides(record!)).toMatchObject({
       cwd: "/tmp/project",
-      featureValues: {
+      providerOptions: { fast_mode: true },
-        fast_mode: true,
-      },
     });
   });
 
+  test("a record stored with featureValues loads them in providerOptions", async () => {
+    await storage.applySnapshot(createManagedAgent({ id: "agent-legacy" }));
+    const file = findRecordFile(storagePath, "agent-legacy");
+    const stored = JSON.parse(await fs.readFile(file, "utf8"));
+    stored.config.providerOptions = { allowedTools: ["Read"], fast_mode: false };
+    stored.config.featureValues = { fast_mode: true, service_tier: "fast" };
+    delete stored.controls;
+    stored.features = [
+      { type: "toggle", id: "fast_mode", label: "Fast mode", value: true },
+      {
+        type: "select",
+        id: "service_tier",
+        label: "Speed",
+        value: "fast",
+        options: [
+          { id: "default", label: "Normal", isDefault: true },
+          { id: "fast", label: "Fast" },
+        ],
+      },
+    ];
+    await fs.writeFile(file, JSON.stringify(stored));
+
+    const reloaded = new AgentStorage(storagePath, logger);
+    const persisted = await reloaded.get("agent-legacy");
+
+    // An explicit providerOptions key wins over the same featureValues key.
+    expect(persisted?.config?.providerOptions).toEqual({
+      allowedTools: ["Read"],
+      fast_mode: false,
+      service_tier: "fast",
+    });
+    expect(persisted?.config).not.toHaveProperty("featureValues");
+    expect(persisted).not.toHaveProperty("features");
+    expect(persisted?.controls).toEqual([
+      { type: "toggle", key: "fast_mode", label: "Fast mode" },
+      {
+        type: "select",
+        key: "service_tier",
+        label: "Speed",
+        defaultValue: "default",
+        choices: [
+          { value: "default", label: "Normal" },
+          { value: "fast", label: "Fast" },
+        ],
+      },
+    ]);
+
+    await reloaded.applySnapshot(createManagedAgent({ id: "agent-legacy" }));
+    const rewritten = JSON.parse(await fs.readFile(file, "utf8"));
+    expect(rewritten.config).not.toHaveProperty("featureValues");
+    expect(rewritten).not.toHaveProperty("features");
+  });
+
   test("applySnapshot preserves original createdAt timestamp", async () => {
     const agentId = "agent-created-at";
     const firstTimestamp = new Date("2025-01-01T00:00:00.000Z");

packages/server/src/server/agent/agent-storage.ts

@@ -4,17 +4,20 @@ import { z } from "zod";
 import type { Logger } from "pino";
 
 import { writeJsonFileAtomic } from "../atomic-file.js";
-import { AgentFeatureSchema, AgentStatusSchema } from "../messages.js";
+import { AgentFeatureSchema, AgentOptionControlSchema, AgentStatusSchema } from "../messages.js";
 import { toStoredAgentRecord } from "./agent-projections.js";
 import type { ManagedAgent } from "./agent-manager.js";
 import type { AgentSessionConfig } from "./agent-sdk-types.js";
 import { AgentOwnerSchema, daemonExecutionKey, type DaemonAgentOwner } from "./agent-owner.js";
+import { controlsFromFeatures } from "@getpaseo/protocol/option-controls";
+import { foldFeatureValues } from "./option-controls.js";
 
 const SERIALIZABLE_CONFIG_SCHEMA = z
   .object({
     modeId: z.string().nullable().optional(),
     model: z.string().nullable().optional(),
     thinkingOptionId: z.string().nullable().optional(),
+    // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. Read-only; folded on parse.
     featureValues: z.record(z.string(), z.unknown()).nullable().optional(),
     providerOptions: z.record(z.string(), z.unknown()).nullable().optional(),
     toolPolicy: z
@@ -42,7 +45,7 @@ const PERSISTENCE_HANDLE_SCHEMA = z
   .nullable()
   .optional();
 
-const STORED_AGENT_SCHEMA = z.object({
+const RAW_STORED_AGENT_SCHEMA = z.object({
   id: z.string(),
   provider: z.string(),
   cwd: z.string(),
@@ -68,6 +71,8 @@ const STORED_AGENT_SCHEMA = z.object({
       extra: z.record(z.string(), z.unknown()).optional(),
     })
     .optional(),
+  controls: z.array(AgentOptionControlSchema).optional(),
+  // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. Read-only; becomes controls.
   features: z.array(AgentFeatureSchema).optional(),
   persistence: PERSISTENCE_HANDLE_SCHEMA,
   lastError: z.string().nullable().optional(),
@@ -84,14 +89,32 @@ export type SerializableAgentConfig = Pick<
   | "modeId"
   | "model"
   | "thinkingOptionId"
-  | "featureValues"
   | "providerOptions"
   | "toolPolicy"
   | "systemPrompt"
   | "mcpServers"
 >;
 
-export type StoredAgentRecord = z.infer<typeof STORED_AGENT_SCHEMA>;
+type RawStoredAgentRecord = z.infer<typeof RAW_STORED_AGENT_SCHEMA>;
+type RawStoredAgentConfig = NonNullable<RawStoredAgentRecord["config"]>;
+
+/** Records carry `providerOptions` and `controls` only; legacy fields are folded when read. */
+export type StoredAgentRecord = Omit<RawStoredAgentRecord, "config" | "features"> & {
+  config?: Omit<RawStoredAgentConfig, "featureValues"> | null;
+};
+
+// COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01.
+function foldLegacyRecordFields(record: RawStoredAgentRecord): StoredAgentRecord {
+  const { features, config, controls, ...rest } = record;
+  return {
+    ...rest,
+    ...(config ? { config: foldFeatureValues(config) } : { config }),
+    ...((controls ?? features) ? { controls: controls ?? controlsFromFeatures(features) } : {}),
+  };
+}
+
+const STORED_AGENT_SCHEMA = RAW_STORED_AGENT_SCHEMA.transform(foldLegacyRecordFields);
+
 export function parseStoredAgentRecord(value: unknown): StoredAgentRecord {
   return STORED_AGENT_SCHEMA.parse(value);
 }

packages/server/src/server/agent/create-agent-mode.ts

@@ -94,7 +94,7 @@ export function resolveDefaultAgentCreateConfig(
       availableModes: availableModeIds,
       targetUnattendedMode: input.availableModes?.find(isUnattendedMode)?.id,
     }),
-    featureValues: input.featureValues,
+    providerOptions: input.providerOptions,
   };
 }
 

packages/server/src/server/agent/create-agent/create.test.ts

@@ -147,7 +147,7 @@ test("session create applies the resolved mode from the provider create config",
   const stub = createProviderSnapshotManagerStub();
   stub.resolveCreateConfig.mockResolvedValue({
     modeId: "build",
-    featureValues: { auto_accept: true },
+    providerOptions: { auto_accept: true },
   });
   const dependencies: Parameters<typeof createAgentCommand>[0] = {
     agentManager: {
@@ -171,7 +171,7 @@ test("session create applies the resolved mode from the provider create config",
   expect(createAgent).toHaveBeenCalledWith(
     expect.objectContaining({
       modeId: "build",
-      featureValues: { auto_accept: true },
+      providerOptions: { auto_accept: true },
     }),
     undefined,
     expect.anything(),

packages/server/src/server/agent/create-agent/create.ts

@@ -22,6 +22,8 @@ import { buildAgentPrompt } from "../prompt-attachments.js";
 import { normalizeClientMessageId, resolveClientMessageId } from "../../client-message-id.js";
 import { resolveRequiredProviderModel, type ResolvedProviderModel } from "../mcp-shared.js";
 import { resolveCreateAgentIntent } from "./intent.js";
+import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
+import { foldFeatureValues, type LegacyFeatureValues } from "../option-controls.js";
 
 export interface CreateAgentCommandDependencies {
   finishSubscriptions?: FinishSubscriptions;
@@ -47,7 +49,8 @@ export interface CreateAgentFromSessionInput {
   kind: "session";
   onAgentReady?: (agent: ManagedAgent) => Promise<void>;
   agentId?: string;
-  config: AgentSessionConfig;
+  /** Wire configs from older clients can still carry `featureValues`; they are folded on entry. */
+  config: AgentSessionConfig & LegacyFeatureValues;
   workspaceId: string;
   initialPrompt?: string;
   source?: AgentPromptSource;
@@ -70,7 +73,7 @@ export interface CreateAgentFromMcpInput {
   cwd?: string;
   workspaceId?: string;
   thinking?: string;
-  features?: Record<string, unknown>;
+  providerOptions?: ProviderOptions;
   labels?: Record<string, string>;
   mode?: string;
   unattended?: boolean;
@@ -218,19 +221,19 @@ async function resolveSessionCreateAgent(
   input: CreateAgentFromSessionInput,
 ): Promise<ResolvedCreateAgent> {
   const trimmedPrompt = input.initialPrompt?.trim();
-  const builtSessionConfig = input.config;
+  const builtSessionConfig = foldFeatureValues(input.config);
   const resolvedCreateConfig = await dependencies.providerSnapshotManager.resolveCreateConfig({
     cwd: builtSessionConfig.cwd,
     provider: builtSessionConfig.provider,
     requestedMode: builtSessionConfig.modeId,
-    featureValues: builtSessionConfig.featureValues,
+    providerOptions: builtSessionConfig.providerOptions,
     parent: null,
     unattended: false,
   });
   const sessionConfig: AgentSessionConfig = {
     ...builtSessionConfig,
     modeId: resolvedCreateConfig.modeId,
-    featureValues: resolvedCreateConfig.featureValues,
+    providerOptions: resolvedCreateConfig.providerOptions,
   };
   const prompt = buildAgentPrompt(trimmedPrompt ?? "", input.images, input.attachments);
   const hasPromptContent = Array.isArray(prompt) ? prompt.length > 0 : prompt.length > 0;
@@ -323,7 +326,7 @@ async function resolveMcpCreateAgent(
       resolvedCwd: intent.cwd,
       trimmedPrompt,
       resolvedMode: resolvedCreateConfig.modeId,
-      resolvedFeatures: resolvedCreateConfig.featureValues,
+      resolvedProviderOptions: resolvedCreateConfig.providerOptions,
     }),
     createOptions: {
       ...(Object.keys(intent.labels).length > 0 ? { labels: intent.labels } : {}),
@@ -361,18 +364,23 @@ async function resolveMcpProviderCreateConfig(params: {
   provider: string;
   resolvedCwd: string;
   parentAgent: ManagedAgent | null;
-}): Promise<{ modeId?: string; featureValues?: Record<string, unknown> }> {
+}): Promise<{ modeId?: string; providerOptions?: ProviderOptions }> {
   const passthroughConfig = params.input.config;
   return params.dependencies.providerSnapshotManager.resolveCreateConfig({
     cwd: params.resolvedCwd,
     provider: params.provider,
     requestedMode: params.input.mode ?? passthroughConfig?.modeId,
-    featureValues: params.input.features ?? passthroughConfig?.featureValues,
+    providerOptions: mergeMcpProviderOptions(params.input),
     parent: params.parentAgent,
     unattended: params.input.unattended ?? false,
   });
 }
 
+function mergeMcpProviderOptions(input: CreateAgentFromMcpInput): ProviderOptions | undefined {
+  if (!input.providerOptions) return input.config?.providerOptions;
+  return { ...input.config?.providerOptions, ...input.providerOptions };
+}
+
 function buildMcpSessionConfig(params: {
   input: CreateAgentFromMcpInput;
   resolvedProviderModel: ResolvedProviderModel;
@@ -380,14 +388,14 @@ function buildMcpSessionConfig(params: {
   resolvedCwd: string;
   trimmedPrompt: string;
   resolvedMode?: string;
-  resolvedFeatures?: Record<string, unknown>;
+  resolvedProviderOptions?: ProviderOptions;
 }): AgentSessionConfig {
   const passthroughConfig = params.input.config;
   const { provisionalTitle } = resolveCreateAgentTitles({
     configTitle: passthroughConfig?.title ?? params.input.title,
     initialPrompt: params.trimmedPrompt,
   });
-  const featureValues = params.resolvedFeatures ?? passthroughConfig?.featureValues;
+  const providerOptions = params.resolvedProviderOptions ?? mergeMcpProviderOptions(params.input);
   const config: AgentSessionConfig = {
     ...passthroughConfig,
     provider: params.provider,
@@ -400,8 +408,8 @@ function buildMcpSessionConfig(params: {
   if (provisionalTitle) {
     config.title = provisionalTitle;
   }
-  if (featureValues) {
+  if (providerOptions) {
-    config.featureValues = featureValues;
+    config.providerOptions = providerOptions;
   }
   return config;
 }

packages/server/src/server/agent/mcp-server.test.ts

@@ -257,7 +257,7 @@ function buildAgentManagerSpies() {
     setAgentMode: vi.fn().mockResolvedValue(undefined),
     setAgentModel: vi.fn().mockResolvedValue(undefined),
     setAgentThinkingOption: vi.fn().mockResolvedValue(undefined),
-    setAgentFeature: vi.fn().mockResolvedValue(undefined),
+    setAgentOptions: vi.fn().mockResolvedValue(undefined),
     setLabels: vi.fn().mockResolvedValue(undefined),
     setTitle: vi.fn().mockResolvedValue(undefined),
     updateAgentMetadata: vi.fn().mockResolvedValue(undefined),
@@ -282,7 +282,7 @@ function buildAgentManagerSpies() {
     cancelAgentRun: vi.fn(),
     getPendingPermissions: vi.fn(),
     getRegisteredProviderIds: vi.fn().mockReturnValue(["claude"]),
-    listDraftFeatures: vi.fn(),
+    listDraftControls: vi.fn(),
   };
 }
 
@@ -472,9 +472,9 @@ function configureOpenCodeProviderStub(
     const opts = input as {
       provider: AgentProvider;
       requestedMode: string | undefined;
-      featureValues: Record<string, unknown> | undefined;
+      providerOptions: Record<string, unknown> | undefined;
     };
-    return { modeId: opts.requestedMode, featureValues: opts.featureValues };
+    return { modeId: opts.requestedMode, providerOptions: opts.providerOptions };
   });
 }
 
@@ -1805,7 +1805,7 @@ describe("create_agent MCP tool", () => {
       lifecycle: "idle",
       currentModeId: null,
       availableModes: [],
-      config: { title: "Feature test", featureValues: { fast_mode: true } },
+      config: { title: "Feature test", providerOptions: { fast_mode: true } },
     } as ManagedAgent);
 
     const server = await createAgentMcpServer({
@@ -1834,7 +1834,7 @@ describe("create_agent MCP tool", () => {
       expect.objectContaining({
         provider: "codex",
         model: "gpt-5.4",
-        featureValues: { fast_mode: true },
+        providerOptions: { fast_mode: true },
       }),
       undefined,
       { workspaceId: "workspace-created" },
@@ -3039,12 +3039,12 @@ describe("create_agent MCP tool", () => {
       lifecycle: "idle",
       currentModeId: null,
       availableModes: [],
-      config: { title: "Child", featureValues: { fast_mode: true } },
+      config: { title: "Child", providerOptions: { fast_mode: true } },
     } as ManagedAgent);
     const providerSnapshot = createOpenCodeManager();
     providerSnapshot.stub.resolveCreateConfig.mockImplementation(async (input) => {
-      const opts = input as { featureValues: Record<string, unknown> | undefined };
+      const opts = input as { providerOptions: Record<string, unknown> | undefined };
-      return { modeId: undefined, featureValues: opts.featureValues };
+      return { modeId: undefined, providerOptions: opts.providerOptions };
     });
 
     const server = await createAgentMcpServer({
@@ -3072,7 +3072,7 @@ describe("create_agent MCP tool", () => {
       expect.objectContaining({
         provider: "codex",
         model: "gpt-5.4",
-        featureValues: { fast_mode: true },
+        providerOptions: { fast_mode: true },
       }),
       undefined,
       {
@@ -3273,7 +3273,7 @@ describe("create_agent MCP tool", () => {
     provStub.resolveCreateConfig.mockImplementation(async (input) => {
       const opts = input as { requestedMode: string | undefined };
       expect(opts.requestedMode).toBe("dynamic");
-      return { modeId: "dynamic", featureValues: undefined };
+      return { modeId: "dynamic", providerOptions: undefined };
     });
     const server = await createAgentMcpServer({
       agentManager,
@@ -3307,12 +3307,12 @@ describe("create_agent MCP tool", () => {
       lifecycle: "idle",
       currentModeId: "build",
       availableModes: [],
-      config: { title: "Child", featureValues: { auto_accept: true } },
+      config: { title: "Child", providerOptions: { auto_accept: true } },
     } as ManagedAgent);
     const providerSnapshot = createOpenCodeManager();
     providerSnapshot.stub.resolveCreateConfig.mockResolvedValue({
       modeId: "build",
-      featureValues: { auto_accept: true },
+      providerOptions: { auto_accept: true },
     });
     const server = await createAgentMcpServer({
       agentManager,
@@ -3332,7 +3332,7 @@ describe("create_agent MCP tool", () => {
     });
 
     expect(spies.agentManager.createAgent).toHaveBeenCalledWith(
-      expect.objectContaining({ modeId: "build", featureValues: { auto_accept: true } }),
+      expect.objectContaining({ modeId: "build", providerOptions: { auto_accept: true } }),
       undefined,
       { workspaceId: "workspace-created" },
     );
@@ -3360,7 +3360,7 @@ describe("create_agent MCP tool", () => {
     const providerSnapshot = createOpenCodeManager();
     providerSnapshot.stub.resolveCreateConfig.mockResolvedValue({
       modeId: "resolver-mode",
-      featureValues: { resolver_feature: true },
+      providerOptions: { resolver_feature: true },
     });
 
     const server = await createAgentMcpServer({
@@ -3384,7 +3384,7 @@ describe("create_agent MCP tool", () => {
     expect(spies.agentManager.createAgent).toHaveBeenCalledWith(
       expect.objectContaining({
         modeId: "resolver-mode",
-        featureValues: { resolver_feature: true },
+        providerOptions: { resolver_feature: true },
       }),
       undefined,
       expect.any(Object),
@@ -4717,7 +4717,7 @@ describe("update_agent MCP tool", () => {
     expect(spies.agentManager.setAgentMode).toHaveBeenCalledWith("agent-1", "full-access");
     expect(spies.agentManager.setAgentModel).toHaveBeenCalledWith("agent-1", "gpt-5.4");
     expect(spies.agentManager.setAgentThinkingOption).toHaveBeenCalledWith("agent-1", "high");
-    expect(spies.agentManager.setAgentFeature).toHaveBeenCalledWith("agent-1", "fast_mode", true);
+    expect(spies.agentManager.setAgentOptions).toHaveBeenCalledWith("agent-1", { fast_mode: true });
     expect(spies.agentManager.updateAgentMetadata).toHaveBeenCalledWith("agent-1", {
       title: "Updated agent",
       labels: { role: "worker" },
@@ -4742,12 +4742,12 @@ describe("update_agent MCP tool", () => {
     expect(spies.agentManager.setAgentMode).not.toHaveBeenCalled();
     expect(spies.agentManager.setAgentModel).not.toHaveBeenCalled();
     expect(spies.agentManager.setAgentThinkingOption).not.toHaveBeenCalled();
-    expect(spies.agentManager.setAgentFeature).not.toHaveBeenCalled();
+    expect(spies.agentManager.setAgentOptions).not.toHaveBeenCalled();
   });
 
   it("does not update metadata when runtime settings fail", async () => {
     const { agentManager, agentStorage, spies } = createTestDeps();
-    spies.agentManager.setAgentFeature.mockRejectedValue(new Error("unsupported feature"));
+    spies.agentManager.setAgentOptions.mockRejectedValue(new Error("unsupported feature"));
     const server = await createAgentMcpServer({
       agentManager,
       agentStorage,
@@ -5065,7 +5065,7 @@ describe("create_schedule MCP tool", () => {
       config: {
         title: "Parent agent",
         model: "openai/gpt-5.5",
-        featureValues: { auto_accept: true },
+        providerOptions: { auto_accept: true },
       },
     } as ManagedAgent);
     const createOrReplace = vi.fn(async (input: CreateScheduleInput) =>
@@ -5093,7 +5093,7 @@ describe("create_schedule MCP tool", () => {
         cwd: REPO_CWD,
         modeId: "build",
         model: "openai/gpt-5.5",
-        featureValues: { auto_accept: true },
+        providerOptions: { auto_accept: true },
       },
     });
   });
@@ -5867,7 +5867,7 @@ describe("agent profile listing MCP tool", () => {
         model: "claude-test-model",
         modeId: "bypassPermissions",
         thinkingOptionId: "high",
-        featureValues: { fast_mode: true },
+        options: { fast_mode: true },
         notes: "Use for UI work: components, layout, design tokens. Not for backend.",
       },
     ];
@@ -5882,7 +5882,21 @@ describe("agent profile listing MCP tool", () => {
 
     const response = await tool.handler({});
 
-    expect(response.structuredContent).toEqual({ profiles });
+    // The config store holds profiles with `options` only; the tool reports them as stored.
+    expect(response.structuredContent).toEqual({
+      profiles: [
+        {
+          id: "ui-profile",
+          name: "UI work",
+          provider: "claude",
+          model: "claude-test-model",
+          modeId: "bypassPermissions",
+          thinkingOptionId: "high",
+          options: { fast_mode: true },
+          notes: "Use for UI work: components, layout, design tokens. Not for backend.",
+        },
+      ],
+    });
   });
 
   it("returns an empty array when no profiles are configured", async () => {
@@ -5934,14 +5948,10 @@ describe("provider MCP tools", () => {
 
   it("inspects provider features for a draft agent configuration", async () => {
     const { agentManager, agentStorage, spies } = createTestDeps();
-    spies.agentManager.listDraftFeatures.mockResolvedValue([
+    spies.agentManager.listDraftControls.mockResolvedValue({
-      {
+      controls: [{ type: "toggle", key: "fast_mode", label: "Fast mode" }],
-        type: "toggle",
+      options: { fast_mode: true },
-        id: "fast_mode",
+    });
-        label: "Fast mode",
-        value: false,
-      },
-    ]);
     const provStub = createProviderSnapshotManagerStub();
     provStub.listRegisteredProviderIds.mockReturnValue(["codex"]);
     const codexEntry = buildSnapshotEntry({
@@ -5974,13 +5984,13 @@ describe("provider MCP tools", () => {
 
     const response = await tool.handler(input);
 
-    expect(spies.agentManager.listDraftFeatures).toHaveBeenCalledWith({
+    expect(spies.agentManager.listDraftControls).toHaveBeenCalledWith({
       provider: "codex",
       cwd: expect.stringContaining("repo"),
       modeId: "full-access",
       model: "gpt-5.4",
       thinkingOptionId: "high",
-      featureValues: { fast_mode: true },
+      providerOptions: { fast_mode: true },
     });
     expect(response.structuredContent).toEqual({
       provider: "codex",
@@ -5995,7 +6005,7 @@ describe("provider MCP tools", () => {
           type: "toggle",
           id: "fast_mode",
           label: "Fast mode",
-          value: false,
+          value: true,
         },
       ],
     });
@@ -6211,14 +6221,8 @@ describe("agent snapshot MCP serialization", () => {
             description: "Default coding mode",
           },
         ],
-        features: [
+        controls: [{ type: "toggle", key: "web-search", label: "Web search" }],
-          {
+        effectiveOptions: { "web-search": true },
-            type: "toggle",
-            id: "web-search",
-            label: "Web search",
-            value: true,
-          },
-        ],
         pendingPermissions: new Map(),
         persistence: {
           provider: "codex",

packages/server/src/server/agent/option-controls.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "vitest";
+import { convertLegacyOptions, foldHookFeatureValues } from "./option-controls.js";
+
+describe("convertLegacyOptions rejects a malformed Codex fast_mode", () => {
+  test.each(["false", 1, {}])("%j", (value) => {
+    expect(() =>
+      convertLegacyOptions({ provider: "codex", options: { fast_mode: value } }),
+    ).toThrow(/fast_mode must be true, false or null/);
+  });
+});
+
+describe("convertLegacyOptions", () => {
+  test.each([
+    { legacy: true, tier: "fast" },
+    { legacy: false, tier: "default" },
+    { legacy: null, tier: null },
+  ])("Codex fast_mode: $legacy becomes service_tier: $tier", ({ legacy, tier }) => {
+    expect(
+      convertLegacyOptions({ provider: "codex", options: { fast_mode: legacy, plan_mode: true } }),
+    ).toEqual({ plan_mode: true, service_tier: tier });
+  });
+
+  test("a service_tier in the same input wins", () => {
+    expect(
+      convertLegacyOptions({
+        provider: "codex",
+        options: { service_tier: "default", fast_mode: true },
+      }),
+    ).toEqual({ service_tier: "default" });
+  });
+
+  test("other providers keep fast_mode", () => {
+    const options = { fast_mode: true };
+    expect(convertLegacyOptions({ provider: "claude", options })).toBe(options);
+  });
+});
+
+describe("foldHookFeatureValues", () => {
+  const convert = (options: Record<string, unknown>) =>
+    convertLegacyOptions({ provider: "codex", options });
+
+  test("a hook that edits featureValues.fast_mode sets service_tier", () => {
+    const sent = { providerOptions: {}, featureValues: {} };
+    const returned = { providerOptions: {}, featureValues: { fast_mode: true } };
+
+    expect(foldHookFeatureValues({ returned, sent, convert }).providerOptions).toEqual({
+      service_tier: "fast",
+    });
+  });
+
+  test("a hook that replaces the speed it was sent with fast_mode selects Fast", () => {
+    const sent = {
+      providerOptions: { service_tier: "default" },
+      featureValues: { service_tier: "default" },
+    };
+    const returned = { ...sent, featureValues: { fast_mode: true } };
+
+    expect(foldHookFeatureValues({ returned, sent, convert }).providerOptions).toEqual({
+      service_tier: "fast",
+    });
+  });
+});

packages/server/src/server/agent/option-controls.ts

@@ -0,0 +1,204 @@
+import { isDeepStrictEqual } from "node:util";
+import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
+
+/**
+ * A patch over an agent's own options: top-level keys replace, `null` removes the key so the
+ * `config.json` default (or the provider's own default) applies again.
+ */
+export type ProviderOptionsPatch = Record<string, unknown>;
+
+export function applyProviderOptionsPatch(input: {
+  options: ProviderOptions | undefined;
+  patch: ProviderOptionsPatch;
+}): ProviderOptions {
+  const { options, patch } = input;
+  const next: ProviderOptions = { ...options };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === null) {
+      delete next[key];
+    } else if (value !== undefined) {
+      next[key] = value;
+    }
+  }
+  return next;
+}
+
+/** COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. */
+export interface LegacyFeatureValues {
+  featureValues?: Record<string, unknown>;
+}
+
+/**
+ * COMPAT(codexFastPreference): added in v0.10.0, remove after 2027-03-29 once saved Fast
+ * preferences have migrated. Codex used to take `fast_mode`; it takes `service_tier` now. Old
+ * data (stored records, config.json defaults, profiles, older clients, hooks) is converted here
+ * as it enters, so nothing past this point sees `fast_mode` for Codex. A `service_tier` in the
+ * same input wins. A patch's `null` stays `null`, which removes the speed.
+ */
+interface LegacyOptionsInput<O> {
+  provider: string | undefined;
+  options: O;
+}
+
+export function convertLegacyOptions(
+  input: LegacyOptionsInput<Record<string, unknown>>,
+): Record<string, unknown>;
+export function convertLegacyOptions(
+  input: LegacyOptionsInput<Record<string, unknown> | undefined>,
+): Record<string, unknown> | undefined;
+export function convertLegacyOptions(
+  input: LegacyOptionsInput<Record<string, unknown> | undefined>,
+): Record<string, unknown> | undefined {
+  const { provider, options } = input;
+  if (provider !== "codex" || !options || !("fast_mode" in options)) return options;
+  const { fast_mode: legacy, ...rest } = options;
+  if (legacy !== undefined && legacy !== null && typeof legacy !== "boolean") {
+    throw new Error("Codex fast_mode must be true, false or null");
+  }
+  if ("service_tier" in rest || legacy === undefined) return rest;
+  if (legacy === null) return { ...rest, service_tier: null };
+  return { ...rest, service_tier: legacy ? "fast" : "default" };
+}
+
+/**
+ * The built-in adapter a provider id runs on: a custom provider is named by the one it
+ * `extends`, followed until a provider that extends nothing. `extendsOf` is where the caller
+ * reads that link (the registry's definitions, or `config.json`'s `providers` section).
+ */
+export function resolveAdapter(input: {
+  provider: string;
+  extendsOf: (provider: string) => string | null | undefined;
+}): string {
+  const seen = new Set<string>();
+  let current = input.provider;
+  for (;;) {
+    seen.add(current);
+    const base = input.extendsOf(current);
+    if (!base || seen.has(base)) return current;
+    current = base;
+  }
+}
+
+/**
+ * COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01.
+ * Older clients, stored records, profiles, and plugin hooks carry composer values in
+ * `featureValues`. This is the one place they become `providerOptions`; an explicit
+ * `providerOptions` key wins over a `featureValues` key of the same name.
+ */
+export function foldFeatureValues<
+  T extends {
+    providerOptions?: ProviderOptions | null;
+    featureValues?: Record<string, unknown> | null;
+  },
+>(config: T): Omit<T, "featureValues"> {
+  const { featureValues, ...rest } = config;
+  if (!featureValues || Object.keys(featureValues).length === 0) return rest;
+  return { ...rest, providerOptions: { ...featureValues, ...rest.providerOptions } };
+}
+
+/**
+ * COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01.
+ * A plugin written against the previous SDK reads and edits `config.featureValues`, so a
+ * hook sees a copy of the config's options there. What the hook did to that copy (set,
+ * replaced or deleted a key, or dropped the field) is applied as a patch over the options it
+ * returned; keys it left alone change nothing.
+ */
+export function exposeFeatureValuesToHook<
+  T extends { providerOptions?: ProviderOptions | null; featureValues?: Record<string, unknown> },
+>(config: T): T {
+  if (!config.providerOptions || Object.keys(config.providerOptions).length === 0) return config;
+  return { ...config, featureValues: { ...config.providerOptions } };
+}
+
+export function foldHookFeatureValues<
+  T extends {
+    providerOptions?: ProviderOptions | null;
+    featureValues?: Record<string, unknown>;
+  },
+>(input: {
+  returned: T;
+  sent: T;
+  /** Brings what the hook returned to the form of the copy it was sent. */
+  convert: (options: Record<string, unknown>) => Record<string, unknown>;
+}): Omit<T, "featureValues"> {
+  const { returned, sent, convert } = input;
+  const { featureValues, ...rest } = returned;
+  const before = sent.featureValues;
+  if (!before) {
+    // No copy was sent, so everything the hook put in `featureValues` is new.
+    return foldFeatureValues(returned);
+  }
+  // A hook may return an older key where it was sent the current one; comparing in the same
+  // form keeps a replaced value from reading as a deletion.
+  const after = convert(featureValues ?? {});
+  const patch: ProviderOptionsPatch = {};
+  for (const key of new Set([...Object.keys(before), ...Object.keys(after)])) {
+    if (isDeepStrictEqual(after[key], before[key])) continue;
+    patch[key] = key in after ? after[key] : null;
+  }
+  return {
+    ...rest,
+    providerOptions: applyProviderOptionsPatch({
+      options: rest.providerOptions ?? undefined,
+      patch,
+    }),
+  };
+}
+
+type ConvertedOptions = Record<string, unknown> | undefined;
+
+interface ProfileOptionFields {
+  provider?: string;
+  options?: Record<string, unknown>;
+  featureValues?: Record<string, unknown>;
+}
+
+/**
+ * COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01.
+ * Profiles saved before options carry `featureValues`; when one comes from storage, `options`
+ * wins over a stale `featureValues` key.
+ *
+ * A write that carries `options` is from a client that knows them: its `featureValues` fold
+ * over those. A write without `options` is from the unchanged app, whose form only knows the
+ * controls: its `featureValues` are a patch (`null` deletes) over the options stored for that
+ * profile, so options the form never shows, such as `sandbox_mode`, survive an edit. A profile
+ * moved to another provider starts from no options, because the old provider's keys mean
+ * nothing to the new one.
+ */
+export function foldProfileFeatureValues<T extends ProfileOptionFields>(input: {
+  profile: T;
+  stored: ProfileOptionFields | undefined;
+  source: "stored" | "client write";
+  /** Renames old option keys for the adapter the profile's provider runs on. */
+  convert: (provider: string, options: Record<string, unknown> | undefined) => ConvertedOptions;
+}): Omit<T, "featureValues"> {
+  const { profile, stored, source, convert } = input;
+  const { featureValues: legacyValues, ...rest } = profile;
+  // A profile is stored in the current keys, so removal and merging below see one vocabulary.
+  const provider = rest.provider ?? "";
+  const featureValues = convert(provider, legacyValues);
+  const ownOptions = convert(provider, rest.options);
+  if (source === "stored") {
+    if (featureValues) return { ...rest, options: { ...featureValues, ...ownOptions } };
+    return ownOptions ? { ...rest, options: ownOptions } : rest;
+  }
+  const base =
+    ownOptions ??
+    (stored?.provider === rest.provider ? convert(provider, stored?.options) : undefined);
+  // The form sends no `featureValues` when no control is set, which is still an edit of a
+  // profile that may hold other options.
+  if (!featureValues && !base) return rest;
+  return {
+    ...rest,
+    options: applyProviderOptionsPatch({ options: base, patch: featureValues ?? {} }),
+  };
+}
+
+/**
+ * COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01.
+ * The unchanged app reads a profile's options from `featureValues`; the config API answers with
+ * both fields.
+ */
+export function withLegacyProfileFeatureValues<T extends ProfileOptionFields>(profile: T): T {
+  return profile.options ? { ...profile, featureValues: { ...profile.options } } : profile;
+}

packages/server/src/server/agent/plugin-provider.test.ts

@@ -58,6 +58,10 @@ interface ProviderHarnessOptions {
   handleInput?: (input: ProviderInput, emit: (event: ProviderEvent) => void) => Promise<boolean>;
 }
 
+function lastConfigure(inputs: ProviderInput[]): ProviderInput | undefined {
+  return inputs.findLast((input) => input.type === "session.configure");
+}
+
 function createProviderHarness(options: ProviderHarnessOptions = {}) {
   let listener: ((event: ProviderEvent) => void) | null = null;
   let closeCount = 0;
@@ -970,7 +974,7 @@ describe("PluginAgentClientRegistry", () => {
     }
   });
 
-  test("stores only agent options while the plugin receives merged defaults", async () => {
+  test("stores the agent options and the settings the plugin opened with, not the merged config defaults", async () => {
     const logger = createTestLogger();
     const harness = createProviderHarness();
     const plugins = new PluginAgentClientRegistry(logger);
@@ -992,13 +996,174 @@ describe("PluginAgentClientRegistry", () => {
       undefined,
       { workspaceId: undefined },
     );
-    expect(toStoredAgentRecord(agent).config?.providerOptions).toEqual(own);
+    // `nested.base` comes from `config.json` and is not stored; `voice` is the plugin's own opening state.
+    expect(toStoredAgentRecord(agent).config?.providerOptions).toEqual({ ...own, voice: "direct" });
     expect(harness.inputs.find((input) => input.type === "session.open")).toMatchObject({
       config: { providerOptions: { nested: { base: true, replace: "agent" } } },
     });
     await agent.session?.close();
   });
 
+  describe("settings", () => {
+    // A plugin that keeps `voice` on "direct" whatever it is asked, and takes `loud` as given.
+    async function openStubbornVoiceSession(
+      given: Record<string, boolean | string>,
+      { refuseAfterChanging = false }: { refuseAfterChanging?: boolean } = {},
+    ) {
+      const state = { voice: "direct", loud: false };
+      let openedSessionId = "";
+      const settings = () => [
+        {
+          type: "select" as const,
+          id: "voice",
+          label: "Voice",
+          value: state.voice,
+          options: [
+            { label: "Direct", value: "direct" },
+            { label: "Other", value: "other" },
+          ],
+        },
+        { type: "toggle" as const, id: "loud", label: "Loud", value: state.loud },
+      ];
+      const emitConfig = (emit: (event: ProviderEvent) => void, sessionId: string) =>
+        emit({
+          type: "session.config",
+          sessionId,
+          config: {
+            model: "plugin-model",
+            mode: "build",
+            models: [{ id: "plugin-model", label: "Plugin model" }],
+            modes: [{ id: "build", label: "Build" }],
+            thinkingOptions: [],
+            settings: settings(),
+          },
+        });
+      const harness = createProviderHarness({
+        async handleInput(input, emit) {
+          if (input.type === "session.open") {
+            openedSessionId = input.sessionId;
+            emit({
+              type: "session.opened",
+              requestId: input.requestId,
+              sessionId: input.sessionId,
+              capabilities: CAPABILITIES,
+              restoration: "core",
+              persistence: { version: 1, data: { token: "root" } },
+              cwd: input.config.cwd,
+            });
+            emitConfig(emit, input.sessionId);
+            emit({ type: "session.ready", requestId: input.requestId, sessionId: input.sessionId });
+            return true;
+          }
+          if (input.type === "session.configure") {
+            const loud = input.changes.settings?.loud;
+            if (typeof loud === "boolean") state.loud = loud;
+            emitConfig(emit, input.sessionId);
+            emit(
+              refuseAfterChanging
+                ? { type: "request.failed", requestId: input.requestId, error: { message: "no" } }
+                : { type: "request.completed", requestId: input.requestId },
+            );
+            return true;
+          }
+          return false;
+        },
+      });
+      const plugins = new PluginAgentClientRegistry(createTestLogger());
+      plugins.replace([harness.registration]);
+      const session = await plugins.clients()["plugin-direct"]!.createSession({
+        provider: "plugin-direct",
+        cwd: tmpdir(),
+        providerOptions: given,
+      });
+      const events: AgentStreamEvent[] = [];
+      session.subscribe((event) => events.push(event));
+      const changeOnItsOwn = (change: Partial<typeof state>) => {
+        Object.assign(state, change);
+        emitConfig(harness.emit, openedSessionId);
+      };
+      return { harness, session, events, changeOnItsOwn };
+    }
+
+    test("forwards a setting the plugin changes on its own", async () => {
+      const { session, events, changeOnItsOwn } = await openStubbornVoiceSession({});
+
+      changeOnItsOwn({ loud: true });
+
+      expect(eventsOfType(events, "options_changed")).toEqual([
+        { type: "options_changed", provider: "plugin-direct", patch: { loud: true } },
+      ]);
+      await session.close();
+    });
+
+    test("a rejected apply reports what the plugin moved before refusing, since nothing is stored", async () => {
+      const { session, events } = await openStubbornVoiceSession({}, { refuseAfterChanging: true });
+
+      await expect(session.applyOptions?.({ loud: true })).rejects.toThrow("no");
+
+      expect(eventsOfType(events, "options_changed")).toEqual([
+        { type: "options_changed", provider: "plugin-direct", patch: { loud: true } },
+      ]);
+      await session.close();
+    });
+
+    test("a setting the plugin opened differently is the session's open patch, not an event", async () => {
+      const { session, events } = await openStubbornVoiceSession({ voice: "other", loud: false });
+
+      expect(session.openOptionsPatch).toEqual({ voice: "direct" });
+      expect(eventsOfType(events, "options_changed")).toEqual([]);
+      await session.close();
+    });
+
+    test("settings the plugin opened with that nobody set are in the open patch", async () => {
+      const { session, events } = await openStubbornVoiceSession({});
+
+      expect(session.openOptionsPatch).toEqual({ voice: "direct", loud: false });
+      expect(eventsOfType(events, "options_changed")).toEqual([]);
+      await session.close();
+    });
+
+    test("applying options configures only the settings it is given", async () => {
+      const { harness, session } = await openStubbornVoiceSession({});
+
+      await session.applyOptions?.({ loud: true });
+
+      const configure = lastConfigure(harness.inputs);
+      expect(configure).toMatchObject({ changes: { settings: { loud: true } } });
+      expect(
+        Object.keys((configure as { changes: { settings: object } }).changes.settings),
+      ).toEqual(["loud"]);
+      await session.close();
+    });
+
+    test("rejects a key the plugin does not report as a setting, and configures none of a mixed patch", async () => {
+      const { harness, session } = await openStubbornVoiceSession({ launch_key: "original" });
+      const configureBefore = lastConfigure(harness.inputs);
+
+      await expect(session.applyOptions?.({ loud: true, launch_key: "changed" })).rejects.toThrow(
+        /launch_key.*cannot change on a running session/,
+      );
+
+      expect(lastConfigure(harness.inputs)).toBe(configureBefore);
+
+      // The value it opened with is not a change, so a whole profile can be applied.
+      await session.applyOptions?.({ loud: true, launch_key: "original" });
+      const configure = lastConfigure(harness.inputs) as { changes: { settings: object } };
+      expect(Object.keys(configure.changes.settings)).toEqual(["loud"]);
+      await session.close();
+    });
+
+    test("applying options returns the settings that ended up different, and emits nothing", async () => {
+      const { session, events } = await openStubbornVoiceSession({});
+
+      const ended = await session.applyOptions?.({ voice: "other", loud: true });
+
+      expect(ended).toEqual({ voice: "direct" });
+      expect(eventsOfType(events, "options_changed")).toEqual([]);
+      await session.close();
+    });
+  });
+
   test.each([
     { options: { nested: { base: true, replace: "config" }, list: [1, 2], scalar: "config" } },
     { params: { nested: { base: true, replace: "config" }, list: [1, 2], scalar: "config" } },
@@ -1511,12 +1676,13 @@ describe("PluginAgentClientRegistry", () => {
     });
 
     const session = await client!.createSession({ provider: "plugin-direct", cwd: "/workspace" });
-    expect(session.features).toEqual([
+    expect(session.controls).toEqual([
-      expect.objectContaining({
+      {
         type: "select",
-        id: "voice",
+        key: "voice",
-        options: [{ id: "direct", label: "Direct", value: "direct" }],
+        label: "Voice",
-      }),
+        choices: [{ value: "direct", label: "Direct" }],
+      },
     ]);
     expect(session.describePersistence()).toMatchObject({
       provider: "plugin-direct",

packages/server/src/server/agent/plugin-provider.ts

@@ -1,8 +1,9 @@
 import { randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
 import { PluginSessionHistory } from "./plugin-session-history.js";
 import { resolve as resolvePath } from "node:path";
 import type { Logger } from "pino";
-import type { JsonValue } from "@getpaseo/protocol/agent-types";
+import type { JsonValue, ProviderOptions } from "@getpaseo/protocol/agent-types";
 import { z } from "zod";
 import {
   PROVIDER_CAPABILITIES,
@@ -31,10 +32,10 @@ import type {
   AgentCapabilityFlags,
   AgentClient,
   AgentCreateSessionOptions,
-  AgentFeature,
   AgentLaunchContext,
   AgentMode,
   AgentModelDefinition,
+  AgentOptionControl,
   AgentPermissionRequest,
   AgentPermissionResponse,
   AgentPersistenceHandle,
@@ -63,6 +64,7 @@ import {
   createProviderEnv,
   type ProviderRuntimeSettings,
 } from "./provider-launch-config.js";
+import { assertChangesAreLive } from "./provider-options.js";
 import type { RegisteredProviderDefinition } from "./provider-registry.js";
 import { runProviderTurn } from "./providers/provider-runner.js";
 import { StaleProviderSessionError } from "./stale-provider-session-error.js";
@@ -1133,6 +1135,7 @@ class PluginAgentClient implements AgentClient {
         });
       },
       bind,
+      config.settings,
     );
     bind(bridge);
     return session;
@@ -1201,6 +1204,11 @@ class PluginAgentSession implements AgentSession {
   >();
   private readonly childSnapshots = new Map<string, Map<string, TimelineTextSnapshot>>();
   private unsubscribe: (() => void) | null = null;
+  /** How the opened session differs from the settings it was given. */
+  readonly openOptionsPatch: Record<string, JsonValue>;
+  private knownSettings: Record<string, JsonValue> = {};
+  /** While `applyOptions` waits on the plugin, its `session.config` answers that call. */
+  private applyingOptions = false;
   private currentTurnId: string | null = null;
   private closed = false;
   private replay: {
@@ -1221,8 +1229,12 @@ class PluginAgentSession implements AgentSession {
       state: ProviderConfigState,
     ) => Promise<ProviderRuntimeSession>,
     private readonly onBind: (bridge: ProviderRuntimeSession) => void,
+    private readonly givenSettings: Readonly<Record<string, JsonValue>>,
   ) {
     this.subagentIdsBySession.set(bridge.id, null);
+    // Every setting the session opened with that was not given, including ones nobody set.
+    this.openOptionsPatch = this.settingDifferences(givenSettings);
+    this.knownSettings = this.currentSettings();
     for (const event of bridge.history) this.accept(event, false);
     // Opening notices arrive before the manager subscribes to the session.
     // Commit them on registration and replay the same timestamps from history.
@@ -1246,14 +1258,27 @@ class PluginAgentSession implements AgentSession {
     };
   }
 
-  get features(): AgentFeature[] {
+  /** The plugin's `settings` are its option controls; each setting id is an option key. */
-    return this.bridge.config.settings.map((setting) =>
+  get controls(): AgentOptionControl[] {
-      setting.type === "toggle"
+    return this.bridge.config.settings.map(
-        ? { ...setting }
+      (setting): AgentOptionControl =>
-        : {
+        setting.type === "toggle"
-            ...setting,
+          ? {
-            options: setting.options.map((option) => ({ ...option, id: option.value })),
+              type: "toggle",
-          },
+              key: setting.id,
+              label: setting.label,
+              ...(setting.description ? { description: setting.description } : {}),
+            }
+          : {
+              type: "select",
+              key: setting.id,
+              label: setting.label,
+              ...(setting.description ? { description: setting.description } : {}),
+              choices: setting.options.map((option) => ({
+                value: option.value,
+                label: option.label,
+              })),
+            },
     );
   }
 
@@ -1410,11 +1435,38 @@ class PluginAgentSession implements AgentSession {
     await this.bridge.configure({ thinkingOption: thinkingOptionId });
   }
 
-  async setFeature(featureId: string, value: unknown): Promise<void> {
+  async applyOptions(options: ProviderOptions): Promise<Record<string, JsonValue>> {
     this.assertReplayComplete();
-    await this.bridge.configure({
+    const before = this.currentSettings();
-      settings: { [featureId]: toJsonValue(value, `setting '${featureId}'`) },
+    // A key the plugin does not report as a setting is one it only reads when the session opens;
+    // a value equal to the one it opened with is not a change.
+    assertChangesAreLive({
+      provider: this.provider,
+      patch: options,
+      current: this.givenSettings,
+      live: Object.keys(before),
     });
+    const settings: Record<string, JsonValue> = {};
+    for (const [id, value] of Object.entries(options)) {
+      if (!(id in before)) continue;
+      settings[id] = toJsonValue(value, `setting '${id}'`);
+    }
+    if (Object.keys(settings).length === 0) return {};
+    this.applyingOptions = true;
+    try {
+      await this.bridge.configure({ settings });
+    } catch (error) {
+      // Nothing is stored for a refused patch, so what the plugin moved is reported once the
+      // call has ended.
+      this.applyingOptions = false;
+      for (const event of this.reportSettingChanges()) this.publish(event);
+      throw error;
+    } finally {
+      this.applyingOptions = false;
+    }
+    const ended = this.settingDifferences({ ...before, ...settings });
+    this.knownSettings = this.currentSettings();
+    return ended;
   }
 
   async revertConversation(input: { messageId: string }): Promise<void> {
@@ -1596,10 +1648,36 @@ class PluginAgentSession implements AgentSession {
     };
   }
 
+  private currentSettings(): Record<string, JsonValue> {
+    return Object.fromEntries(
+      this.bridge.config.settings.map((setting) => [setting.id, setting.value]),
+    );
+  }
+
+  /** Settings whose value differs from `known`: the plugin's own change or its opening state. */
+  private settingDifferences(
+    known: Readonly<Record<string, JsonValue>>,
+  ): Record<string, JsonValue> {
+    const patch: Record<string, JsonValue> = {};
+    for (const [id, value] of Object.entries(this.currentSettings())) {
+      if (!isDeepStrictEqual(known[id], value)) patch[id] = value;
+    }
+    return patch;
+  }
+
+  private reportSettingChanges(): AgentStreamEvent[] {
+    if (this.applyingOptions) return [];
+    const patch = this.settingDifferences(this.knownSettings);
+    if (Object.keys(patch).length === 0) return [];
+    this.knownSettings = this.currentSettings();
+    return [{ type: "options_changed", provider: this.provider, patch }];
+  }
+
   private translateConfig(
     event: Extract<ProviderEvent, { type: "session.config" }>,
   ): AgentStreamEvent[] {
     return [
+      ...this.reportSettingChanges(),
       {
         type: "mode_changed",
         provider: this.provider,
@@ -1852,7 +1930,8 @@ function mapSessionConfig(
     model: config.model,
     mode: config.modeId,
     thinkingOption: config.thinkingOptionId,
-    settings: toJsonObject(config.featureValues ?? {}, "provider settings"),
+    // The plugin SDK reads composer values from `settings`; they are options here.
+    settings: toJsonObject(config.providerOptions ?? {}, "provider settings"),
     providerOptions: config.providerOptions,
     title: config.title ?? undefined,
     persist,

packages/server/src/server/agent/provider-options.ts

@@ -1,4 +1,5 @@
 import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
+import { isDeepStrictEqual } from "node:util";
 import type { z } from "zod";
 
 export interface ProviderOptionIssue {
@@ -103,3 +104,26 @@ function isPlainObject(value: unknown): value is ProviderOptions {
   const prototype = Object.getPrototypeOf(value);
   return prototype === Object.prototype || prototype === null;
 }
+
+/**
+ * Rejects a live patch that changes a key the running session cannot apply (one the provider
+ * reads only when it opens). A key whose value already matches the session's is not a change.
+ */
+export function assertChangesAreLive(input: {
+  provider: string;
+  patch: ProviderOptions;
+  current: ProviderOptions | undefined;
+  live: readonly string[];
+}): void {
+  const issues = Object.entries(input.patch)
+    .filter(
+      ([key, value]) =>
+        !input.live.includes(key) &&
+        !isDeepStrictEqual(input.current?.[key] ?? null, value ?? null),
+    )
+    .map(([key]) => ({
+      path: [key],
+      message: "cannot change on a running session; it applies when the agent is opened",
+    }));
+  if (issues.length > 0) throw new ProviderOptionsValidationError(input.provider, issues);
+}

packages/server/src/server/agent/provider-registry-wrap.test.ts

@@ -25,7 +25,7 @@ const OPTIONAL_AGENT_SESSION_METHOD_NAMES = [
   "listCommands",
   "setModel",
   "setThinkingOption",
-  "setFeature",
+  "applyOptions",
   "revertConversation",
   "revertFiles",
   "revertBoth",
@@ -152,8 +152,8 @@ class FakeSession implements AgentSession {
     this.recordedCalls.push("setThinkingOption");
   }
 
-  async setFeature() {
+  async applyOptions() {
-    this.recordedCalls.push("setFeature");
+    this.recordedCalls.push("applyOptions");
   }
 
   async revertConversation() {
@@ -193,7 +193,7 @@ describe("wrapSessionProvider", () => {
     await wrapped.listCommands?.();
     await wrapped.setModel?.("sonnet");
     await wrapped.setThinkingOption?.("high");
-    await wrapped.setFeature?.("feature-1", true);
+    await wrapped.applyOptions?.({ "feature-1": true });
     await wrapped.revertConversation?.({ messageId: "message-1" });
     await wrapped.revertFiles?.({ messageId: "message-1" });
     await wrapped.revertBoth?.({ messageId: "message-1" });
@@ -208,7 +208,7 @@ describe("wrapSessionProvider", () => {
       "listCommands",
       "setModel",
       "setThinkingOption",
-      "setFeature",
+      "applyOptions",
       "revertConversation",
       "revertFiles",
       "revertBoth",

packages/server/src/server/agent/provider-registry.test.ts

@@ -4,7 +4,7 @@ import type { ToolPolicy } from "@getpaseo/protocol/agent-types";
 import { createTestLogger } from "../../test-utils/test-logger.js";
 import type {
   AgentClient,
-  AgentFeature,
+  AgentOptionControl,
   AgentModelDefinition,
   AgentMode,
   AgentSessionConfig,
@@ -392,15 +392,15 @@ vi.mock("./providers/cursor-acp-agent.js", () => ({
       return true;
     }
 
-    async listFeatures(config: AgentSessionConfig): Promise<AgentFeature[]> {
+    async listControls(config: AgentSessionConfig): Promise<AgentOptionControl[]> {
       mockState.cursorListFeaturesConfigs.push(config);
       return [
         {
           type: "select",
-          id: "fast",
+          key: "fast",
           label: "Fast",
-          value: "false",
+          defaultValue: "false",
-          options: [{ id: "false", label: "Off" }],
+          choices: [{ value: "false", label: "Off" }],
         },
       ];
     }
@@ -791,6 +791,33 @@ test("ACP provider configuration retains opaque options", () => {
   });
 });
 
+test("a saved legacy Codex Fast preference wins over a configured service_tier default", () => {
+  const registry = buildProviderRegistry(logger, {
+    providerOverrides: { codex: { options: { service_tier: "default", plan_mode: false } } },
+  });
+  const client = registry.codex.createClient(logger);
+
+  // The manager hands the registry a pre-v0.10 record's `fast_mode` already converted.
+  expect(client.effectiveOptions?.({ service_tier: "fast" })).toEqual({
+    service_tier: "fast",
+    plan_mode: false,
+  });
+  expect(client.effectiveOptions?.({})).toEqual({ service_tier: "default", plan_mode: false });
+});
+
+test("a configured legacy Codex Fast default supplies the service_tier default", () => {
+  const registry = buildProviderRegistry(logger, {
+    providerOverrides: { codex: { options: { fast_mode: true } } },
+  });
+  const client = registry.codex.createClient(logger);
+
+  // Removing an agent's own speed falls back to the configured Fast.
+  expect(client.effectiveOptions?.({})).toEqual({ service_tier: "fast" });
+  expect(client.effectiveOptions?.({ service_tier: "default" })).toEqual({
+    service_tier: "default",
+  });
+});
+
 test("cursor provider extending acp uses CursorACPAgentClient", () => {
   const registry = buildProviderRegistry(logger, {
     providerOverrides: {
@@ -823,7 +850,7 @@ test("cursor provider extending acp uses CursorACPAgentClient", () => {
   expect(mockState.constructorArgs.genericAcp).toEqual([]);
 });
 
-test("wrapped cursor client lists ACP features through the inner provider", async () => {
+test("wrapped cursor client lists ACP controls through the inner provider", async () => {
   const registry = buildProviderRegistry(logger, {
     providerOverrides: {
       cursor: {
@@ -837,17 +864,17 @@ test("wrapped cursor client lists ACP features through the inner provider", asyn
   const client = registry.cursor.createClient(logger);
 
   await expect(
-    client.listFeatures?.({
+    client.listControls?.({
       provider: "cursor",
       cwd: "/tmp/cursor",
     }),
   ).resolves.toEqual([
     {
       type: "select",
-      id: "fast",
+      key: "fast",
       label: "Fast",
-      value: "false",
+      defaultValue: "false",
-      options: [{ id: "false", label: "Off" }],
+      choices: [{ value: "false", label: "Off" }],
     },
   ]);
   expect(mockState.cursorListFeaturesConfigs).toEqual([

packages/server/src/server/agent/provider-registry.ts

@@ -48,6 +48,7 @@ import { PiRpcAgentClient } from "./providers/pi/agent.js";
 import { TraeACPAgentClient } from "./providers/trae-acp-agent.js";
 import { MockLoadTestAgentClient } from "./providers/mock-load-test-agent.js";
 import { MockSlowProviderClient } from "./providers/mock-slow-provider.js";
+import { convertLegacyOptions } from "./option-controls.js";
 import { ToolPolicyUnsupportedError, mergeProviderOptions } from "./provider-options.js";
 import {
   AGENT_PROVIDER_DEFINITIONS,
@@ -447,8 +448,11 @@ export function wrapSessionProvider(provider: AgentProvider, inner: AgentSession
     get initialTimeline() {
       return inner.initialTimeline;
     },
-    get features() {
+    get controls() {
-      return inner.features;
+      return inner.controls;
+    },
+    get openOptionsPatch() {
+      return inner.openOptionsPatch;
     },
     usageSession: inner.usageSession?.bind(inner),
     run: (prompt, options) => inner.run(prompt, options),
@@ -473,7 +477,7 @@ export function wrapSessionProvider(provider: AgentProvider, inner: AgentSession
     listCommands: inner.listCommands?.bind(inner),
     setModel: inner.setModel?.bind(inner),
     setThinkingOption: inner.setThinkingOption?.bind(inner),
-    setFeature: inner.setFeature?.bind(inner),
+    applyOptions: inner.applyOptions?.bind(inner),
     revertConversation: inner.revertConversation?.bind(inner),
     revertFiles: inner.revertFiles?.bind(inner),
     revertBoth: inner.revertBoth?.bind(inner),
@@ -487,14 +491,20 @@ function wrapClientProvider(
   profileModels: ProviderProfileModel[],
   additionalModels: ProviderProfileModel[],
   profileModelsAreAdditive: boolean,
-  providerOptions: ProviderOptions | undefined,
+  configuredOptions: ProviderOptions | undefined,
 ): AgentClient {
   const listImportableSessions = inner.listImportableSessions?.bind(inner);
   const importSession = inner.importSession?.bind(inner);
-  const listFeatures = inner.listFeatures?.bind(inner);
+  const listControls = inner.listControls?.bind(inner);
   const archiveNativeSession = inner.archiveNativeSession?.bind(inner);
   const unarchiveNativeSession = inner.unarchiveNativeSession?.bind(inner);
   const configuredModelIds = [...profileModels, ...additionalModels].map((model) => model.id);
+  // Converted where it is used, so a malformed configured default fails the call that reads it
+  // rather than the registry that holds every provider.
+  const configuredDefaults = () =>
+    convertLegacyOptions({ provider: inner.provider, options: configuredOptions });
+  const withDefaults = (own: ProviderOptions | undefined) =>
+    mergeProviderOptions(configuredDefaults(), own);
 
   return {
     provider,
@@ -509,7 +519,7 @@ function wrapClientProvider(
           {
             ...config,
             provider: inner.provider,
-            providerOptions: mergeProviderOptions(providerOptions, config.providerOptions),
+            providerOptions: withDefaults(config.providerOptions),
           },
           launchContext,
           { ...options, configuredModelIds },
@@ -526,14 +536,17 @@ function wrapClientProvider(
           {
             ...overrides,
             provider: inner.provider,
-            providerOptions: mergeProviderOptions(providerOptions, overrides?.providerOptions),
+            providerOptions: withDefaults(overrides?.providerOptions),
           },
           launchContext,
           { ...options, configuredModelIds },
         ),
       ),
     fetchCatalog: async (options, context) => {
-      const catalog = await inner.fetchCatalog({ ...options, providerOptions }, context);
+      const catalog = await inner.fetchCatalog(
+        { ...options, providerOptions: configuredDefaults() },
+        context,
+      );
       return {
         ...catalog,
         models: mergeModels(provider, profileModels, additionalModels, catalog.models, {
@@ -548,7 +561,7 @@ function wrapClientProvider(
             config: {
               ...config,
               provider: inner.provider,
-              providerOptions: mergeProviderOptions(providerOptions, config.providerOptions),
+              providerOptions: withDefaults(config.providerOptions),
             },
             env,
             signal,
@@ -557,16 +570,18 @@ function wrapClientProvider(
     resolveCreateConfig: inner.resolveCreateConfig?.bind(inner),
     resolveConfiguredModel: inner.resolveConfiguredModel?.bind(inner),
     isCreateConfigUnattended: inner.isCreateConfigUnattended?.bind(inner),
-    listFeatures: listFeatures
+    effectiveOptions: (own) => withDefaults(own) ?? {},
+    listControls: listControls
       ? async (config) =>
-          await listFeatures({
+          await listControls({
             ...config,
             provider: inner.provider,
-            providerOptions: mergeProviderOptions(providerOptions, config.providerOptions),
+            providerOptions: withDefaults(config.providerOptions),
           })
       : undefined,
     listImportableSessions: listImportableSessions
-      ? async (options) => await listImportableSessions({ ...options, providerOptions })
+      ? async (options) =>
+          await listImportableSessions({ ...options, providerOptions: configuredDefaults() })
       : undefined,
     importSession: importSession
       ? async (input, context) => {
@@ -575,10 +590,7 @@ function wrapClientProvider(
             config: {
               ...context.config,
               provider: inner.provider,
-              providerOptions: mergeProviderOptions(
+              providerOptions: withDefaults(context.config.providerOptions),
-                providerOptions,
-                context.config.providerOptions,
-              ),
             },
             storedConfig: {
               ...context.storedConfig,

packages/server/src/server/agent/provider-snapshot-manager.test.ts

@@ -1307,7 +1307,7 @@ describe("ProviderSnapshotManager public surface", () => {
             resolverInputs.push(input);
             return {
               modeId: input.parent?.isUnattended ? "child-unattended" : undefined,
-              featureValues: undefined,
+              providerOptions: undefined,
             };
           },
         }),
@@ -1338,17 +1338,17 @@ describe("ProviderSnapshotManager public surface", () => {
         cwd: "/tmp/project",
         provider: "codex",
         requestedMode: undefined,
-        featureValues: undefined,
+        providerOptions: undefined,
         parent,
         unattended: false,
       });
 
-      expect(resolved).toEqual({ modeId: "child-unattended", featureValues: undefined });
+      expect(resolved).toEqual({ modeId: "child-unattended", providerOptions: undefined });
       expect(resolverInputs).toEqual([
         {
           provider: "codex",
           requestedMode: undefined,
-          featureValues: undefined,
+          providerOptions: undefined,
           parent: {
             provider: "claude",
             modeId: "parent-unattended",
@@ -1386,7 +1386,7 @@ describe("ProviderSnapshotManager public surface", () => {
             resolverInputs.push(input);
             return {
               modeId: input.unattended ? "worker" : undefined,
-              featureValues: undefined,
+              providerOptions: undefined,
             };
           },
         }),
@@ -1397,17 +1397,17 @@ describe("ProviderSnapshotManager public surface", () => {
         cwd: "/tmp/project",
         provider: "codex",
         requestedMode: undefined,
-        featureValues: { fast_mode: true },
+        providerOptions: { fast_mode: true },
         parent: null,
         unattended: true,
       });
 
-      expect(resolved).toEqual({ modeId: "worker", featureValues: undefined });
+      expect(resolved).toEqual({ modeId: "worker", providerOptions: undefined });
       expect(resolverInputs).toEqual([
         {
           provider: "codex",
           requestedMode: undefined,
-          featureValues: { fast_mode: true },
+          providerOptions: { fast_mode: true },
           parent: null,
           unattended: true,
           availableModes: modes,
@@ -1456,7 +1456,7 @@ describe("ProviderSnapshotManager public surface", () => {
         config: {
           provider: "opencode",
           cwd: "/tmp/project",
-          featureValues: { auto_accept: true },
+          providerOptions: { auto_accept: true },
         },
       };
 
@@ -1464,12 +1464,28 @@ describe("ProviderSnapshotManager public surface", () => {
         cwd: "/tmp/project",
         provider: "opencode",
         requestedMode: "base",
-        featureValues: undefined,
+        providerOptions: undefined,
         parent,
         unattended: false,
       });
 
-      expect(resolved).toEqual({ modeId: "base", featureValues: { auto_accept: true } });
+      expect(resolved).toEqual({ modeId: "base", providerOptions: { auto_accept: true } });
+
+      // A parent whose Auto Accept comes from the provider's config.json default has no own
+      // option; it is classified on its effective options.
+      const inheriting = await manager.resolveCreateConfig({
+        cwd: "/tmp/project",
+        provider: "opencode",
+        requestedMode: "base",
+        providerOptions: undefined,
+        parent: {
+          ...parent,
+          config: { provider: "opencode", cwd: "/tmp/project" },
+          effectiveOptions: { auto_accept: true },
+        },
+        unattended: false,
+      });
+      expect(inheriting).toEqual({ modeId: "base", providerOptions: { auto_accept: true } });
     } finally {
       manager.destroy();
     }

packages/server/src/server/agent/provider-snapshot-manager.ts

@@ -1,4 +1,4 @@
-import { normalizeAgentModelCatalog } from "@getpaseo/protocol/agent-types";
+import { normalizeAgentModelCatalog, type ProviderOptions } from "@getpaseo/protocol/agent-types";
 import { createHash } from "node:crypto";
 import { EventEmitter } from "node:events";
 import { homedir } from "node:os";
@@ -160,14 +160,14 @@ export interface ResolveProviderCreateConfigOptions {
   cwd?: string | null;
   provider: AgentProvider;
   requestedMode: string | undefined;
-  featureValues: Record<string, unknown> | undefined;
+  providerOptions: ProviderOptions | undefined;
   parent: ManagedAgent | null;
   unattended: boolean;
 }
 
 export interface ResolvedProviderCreateConfig {
   modeId: string | undefined;
-  featureValues: Record<string, unknown> | undefined;
+  providerOptions: ProviderOptions | undefined;
 }
 
 interface ResolveDefaultModelOptions {
@@ -563,7 +563,7 @@ export class ProviderSnapshotManager {
     return definition.resolveCreateConfig({
       provider: input.provider,
       requestedMode: input.requestedMode,
-      featureValues: input.featureValues,
+      providerOptions: input.providerOptions,
       parent,
       unattended: input.unattended || parent?.isUnattended === true,
       availableModes: entry.modes ?? [],
@@ -744,8 +744,13 @@ export class ProviderSnapshotManager {
       modeId: parent.currentModeId,
       isUnattended: definition.isCreateConfigUnattended({
         modeId: parent.currentModeId,
-        config: parent.config,
+        // Provider defaults from `config.json` apply to the parent too, so classify on the
-        features: parent.features,
+        // effective options while the stored overrides stay as they are.
+        config: {
+          ...parent.config,
+          providerOptions: parent.effectiveOptions ?? parent.config.providerOptions,
+        },
+        controls: parent.controls,
         availableModes: parent.availableModes ?? definition.modes ?? [],
       }),
     };

packages/server/src/server/agent/providers/acp-agent.test.ts

@@ -4,7 +4,7 @@ import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import {
   AgentSideConnection,
@@ -198,7 +198,7 @@ function createSessionWithConfig(
     provider?: string;
     modeId?: string | null;
     model?: string | null;
-    featureValues?: Record<string, unknown>;
+    providerOptions?: Record<string, unknown>;
   } = {},
   logger: ReturnType<typeof createTestLogger> = createTestLogger(),
 ): ACPAgentSession {
@@ -208,7 +208,7 @@ function createSessionWithConfig(
       cwd: "/tmp/paseo-acp-test",
       modeId: config.modeId ?? undefined,
       model: config.model ?? undefined,
-      featureValues: config.featureValues,
+      providerOptions: config.providerOptions,
     },
     {
       provider: config.provider ?? "claude-acp",
@@ -300,19 +300,20 @@ function selectConfigOption(
 
 function createCopilotSessionWithConfig(
   modeId?: string | null,
-  featureValues?: Record<string, unknown>,
+  providerOptions?: Record<string, unknown>,
+  defaultCommand: string[] = ["copilot", "--acp"],
 ): ACPAgentSession {
   return new ACPAgentSession(
     {
       provider: "copilot",
       cwd: "/tmp/paseo-acp-test",
       modeId: modeId ?? undefined,
-      ...(featureValues ? { featureValues } : {}),
+      ...(providerOptions ? { providerOptions } : {}),
     },
     {
       provider: "copilot",
       logger: createTestLogger(),
-      defaultCommand: ["copilot", "--acp"],
+      defaultCommand,
       defaultModes: COPILOT_MODES,
       sessionResponseTransformer: transformCopilotSessionResponse,
       configOptionsTransformer: transformCopilotConfigOptions,
@@ -1498,7 +1499,7 @@ describe("ACPAgentSession Zed parity", () => {
   test("auto-accepts ACP permission requests when the shared feature is enabled", async () => {
     const session = createSessionWithConfig({
       provider: "cursor-acp",
-      featureValues: { auto_accept: true },
+      providerOptions: { auto_accept: true },
     });
     const events: Array<{ type: string }> = [];
 
@@ -1530,7 +1531,7 @@ describe("ACPAgentSession Zed parity", () => {
   test("does not auto-accept ACP chooser requests", async () => {
     const session = createSessionWithConfig({
       provider: "kimi-acp",
-      featureValues: { auto_accept: true },
+      providerOptions: { auto_accept: true },
     });
     const events: AgentStreamEvent[] = [];
 
@@ -1583,11 +1584,8 @@ describe("ACPAgentSession Zed parity", () => {
     internals.sessionId = "session-1";
     internals.connection = {};
 
-    await session.setFeature("auto_accept", true);
+    await session.applyOptions({ auto_accept: true });
 
-    expect(session.features).toContainEqual(
-      expect.objectContaining({ type: "toggle", id: "auto_accept", value: true }),
-    );
     await expect(
       session.requestPermission({
         sessionId: "session-1",
@@ -1605,7 +1603,7 @@ describe("ACPAgentSession Zed parity", () => {
   });
 
   test("surfaces an ACP permission when auto-accept has no allow option", async () => {
-    const session = createSessionWithConfig({ featureValues: { auto_accept: true } });
+    const session = createSessionWithConfig({ providerOptions: { auto_accept: true } });
     const events: Array<{ type: string; request?: { id: string } }> = [];
     asInternals<ACPSessionInternals>(session).sessionId = "session-1";
     session.subscribe((event) => events.push(event as { type: string; request?: { id: string } }));
@@ -1765,35 +1763,18 @@ describe("ACPAgentSession Zed parity", () => {
     const internals = asInternals<ACPSessionInternals>(session);
     internals.configOptions = [copilotAgentConfigOption("")];
 
-    expect(session.features).toEqual([
+    expect(session.controls).toEqual([
-      expect.objectContaining({
+      expect.objectContaining({ type: "toggle", key: "auto_accept" }),
-        type: "toggle",
-        id: "auto_accept",
-        value: false,
-      }),
       {
         type: "select",
-        id: "agent",
+        key: "agent",
         label: "Agent",
         description: "Use a Copilot custom agent profile",
         tooltip: "Select Copilot agent",
         icon: undefined,
-        value: "",
+        choices: [
-        options: [
+          { value: "", label: "Default", description: undefined },
-          {
+          { value: "Probe Agent", label: "Probe Agent", description: "Temporary probe agent" },
-            id: "",
-            label: "Default",
-            description: undefined,
-            isDefault: true,
-            metadata: undefined,
-          },
-          {
-            id: "Probe Agent",
-            label: "Probe Agent",
-            description: "Temporary probe agent",
-            isDefault: false,
-            metadata: undefined,
-          },
         ],
       },
     ]);
@@ -1816,15 +1797,9 @@ describe("ACPAgentSession Zed parity", () => {
       configId: "agent",
       value: "Probe Agent",
     });
-    expect(session.features).toEqual([
+    expect(session.controls).toEqual([
-      expect.objectContaining({
+      expect.objectContaining({ key: "auto_accept" }),
-        id: "auto_accept",
+      expect.objectContaining({ key: "agent" }),
-        value: false,
-      }),
-      expect.objectContaining({
-        id: "agent",
-        value: "Probe Agent",
-      }),
     ]);
   });
 
@@ -1838,26 +1813,182 @@ describe("ACPAgentSession Zed parity", () => {
       connection: { setSessionConfigOption },
     });
 
-    await session.setFeature("agent", "Probe Agent");
+    await session.applyOptions({ agent: "Probe Agent" });
 
     expect(setSessionConfigOption).toHaveBeenCalledWith({
       sessionId: "session-1",
       configId: "agent",
       value: "Probe Agent",
     });
-    expect(session.features).toEqual([
+    expect(session.controls).toEqual([
-      expect.objectContaining({
+      expect.objectContaining({ key: "auto_accept" }),
-        id: "auto_accept",
+      expect.objectContaining({ key: "agent" }),
-        value: false,
-      }),
-      expect.objectContaining({
-        id: "agent",
-        value: "Probe Agent",
-      }),
     ]);
   });
 });
 
+describe("ACPAgentSession options against an ACP agent", () => {
+  const fakeAgentPath = fileURLToPath(new URL("./test-utils/fake-acp-agent.mjs", import.meta.url));
+  const sessions: ACPAgentSession[] = [];
+
+  afterEach(async () => {
+    await Promise.all(sessions.splice(0).map((session) => session.close()));
+  });
+
+  function thoughtOption(currentValue: string): SessionConfigOption {
+    return {
+      id: "thought",
+      name: "Thinking",
+      category: "thought_level",
+      type: "select",
+      currentValue,
+      options: [
+        { value: "low", name: "Low" },
+        { value: "high", name: "High" },
+      ],
+    };
+  }
+
+  async function openSession(input: {
+    agent?: string;
+    scenario?: Record<string, unknown>;
+    providerOptions?: Record<string, unknown>;
+  }): Promise<{ session: ACPAgentSession; optionEvents: AgentStreamEvent[] }> {
+    const scenario = {
+      options: [copilotAgentConfigOption(input.agent ?? ""), thoughtOption("low")],
+      ...input.scenario,
+    };
+    await mkdir("/tmp/paseo-acp-test", { recursive: true });
+    const session = createCopilotSessionWithConfig(null, input.providerOptions, [
+      process.execPath,
+      fakeAgentPath,
+      JSON.stringify(scenario),
+    ]);
+    sessions.push(session);
+    const optionEvents: AgentStreamEvent[] = [];
+    session.subscribe((event) => {
+      if (event.type === "options_changed") optionEvents.push(event);
+    });
+    await session.initializeNewSession();
+    return { session, optionEvents };
+  }
+
+  test("a select the agent opened differently from the options is the open patch, not an event", async () => {
+    const { session, optionEvents } = await openSession({
+      providerOptions: { agent: "Probe Agent" },
+      scenario: { answers: { agent: "" } },
+    });
+
+    expect(session.openOptionsPatch).toEqual({ agent: "" });
+    expect(optionEvents).toEqual([]);
+  });
+
+  test("a select the agent opened with that nobody set is in the open patch", async () => {
+    const { session, optionEvents } = await openSession({ agent: "Probe Agent" });
+
+    expect(session.openOptionsPatch).toEqual({ agent: "Probe Agent" });
+    expect(optionEvents).toEqual([]);
+  });
+
+  test("a notification that arrives before the open write is answered is not an event", async () => {
+    const { session, optionEvents } = await openSession({
+      providerOptions: { agent: "Probe Agent" },
+      scenario: { onWrite: "notify-first" },
+    });
+
+    expect(session.openOptionsPatch).toEqual({});
+    expect(optionEvents).toEqual([]);
+  });
+
+  test("applying a patch returns the selects that ended up different and emits nothing", async () => {
+    const { session, optionEvents } = await openSession({ scenario: { answers: { agent: "" } } });
+
+    await expect(session.applyOptions({ agent: "Probe Agent" })).resolves.toEqual({ agent: "" });
+    expect(optionEvents).toEqual([]);
+  });
+
+  test("a notification that arrives before the apply write is answered is not an event", async () => {
+    const { session, optionEvents } = await openSession({ scenario: { onWrite: "notify-first" } });
+
+    await expect(session.applyOptions({ agent: "Probe Agent" })).resolves.toEqual({});
+    expect(optionEvents).toEqual([]);
+  });
+
+  test("a rejected apply reports what the agent moved before refusing, since nothing is stored", async () => {
+    const { session, optionEvents } = await openSession({
+      scenario: { onWrite: "notify-then-reject" },
+    });
+
+    await expect(session.applyOptions({ agent: "Probe Agent" })).rejects.toThrow(/write refused/);
+    expect(optionEvents).toEqual([
+      { type: "options_changed", provider: "copilot", patch: { agent: "Probe Agent" } },
+    ]);
+  });
+
+  test("overlapping applies that both fail still report what the agent moved", async () => {
+    const { session, optionEvents } = await openSession({ scenario: { onWrite: "slow-reject" } });
+
+    const first = session.applyOptions({ agent: "Probe Agent" });
+    const second = session.applyOptions({ agent: null });
+
+    await expect(first).rejects.toThrow(/write refused/);
+    await expect(second).rejects.toThrow(/write refused/);
+    expect(optionEvents).toEqual([
+      { type: "options_changed", provider: "copilot", patch: { agent: "Probe Agent" } },
+    ]);
+  });
+
+  test("a removal writes the select's empty choice and returns nothing when that took", async () => {
+    const { session, optionEvents } = await openSession({ agent: "Probe Agent" });
+
+    await expect(session.applyOptions({ agent: null })).resolves.toEqual({});
+    expect(optionEvents).toEqual([]);
+  });
+
+  test("rejects a live auto_accept the creation schema would reject, and writes nothing", async () => {
+    const { session, optionEvents } = await openSession({
+      scenario: { onWrite: "notify-then-reject" },
+    });
+
+    await expect(
+      session.applyOptions({ auto_accept: "yes", agent: "Probe Agent" }),
+    ).rejects.toThrow(/auto_accept/);
+    expect(optionEvents).toEqual([]);
+  });
+
+  test("forwards a select the agent changes on its own", async () => {
+    const { session, optionEvents } = await openSession({
+      scenario: { moves: { thought: { agent: "Probe Agent" } } },
+    });
+
+    await session.setThinkingOption("high");
+
+    await vi.waitFor(() =>
+      expect(optionEvents).toEqual([
+        { type: "options_changed", provider: "copilot", patch: { agent: "Probe Agent" } },
+      ]),
+    );
+  });
+
+  test("a select that appears after startup is reported with its native value", async () => {
+    const { session, optionEvents } = await openSession({
+      scenario: {
+        options: [thoughtOption("low")],
+        adds: { thought: [copilotAgentConfigOption("Probe Agent")] },
+      },
+    });
+    expect(session.openOptionsPatch).toEqual({});
+
+    await session.setThinkingOption("high");
+
+    await vi.waitFor(() =>
+      expect(optionEvents).toEqual([
+        { type: "options_changed", provider: "copilot", patch: { agent: "Probe Agent" } },
+      ]),
+    );
+  });
+});
+
 describe("deriveModelDefinitionsFromACP", () => {
   test("attaches shared thinking options to ACP model state", () => {
     const result = deriveModelDefinitionsFromACP(
@@ -2084,14 +2215,14 @@ describe("ACPAgentClient config features", () => {
       client.resolveCreateConfig({
         provider: "generic-acp",
         requestedMode: undefined,
-        featureValues: { provider_feature: "kept" },
+        providerOptions: { provider_feature: "kept" },
         parent: null,
         unattended: true,
         availableModes: [],
       }),
     ).toEqual({
       modeId: undefined,
-      featureValues: { provider_feature: "kept", auto_accept: true },
+      providerOptions: { provider_feature: "kept", auto_accept: true },
     });
   });
 
@@ -2106,12 +2237,12 @@ describe("ACPAgentClient config features", () => {
       client.resolveCreateConfig({
         provider: "generic-acp",
         requestedMode: undefined,
-        featureValues: { auto_accept: false },
+        providerOptions: { auto_accept: false },
         parent: null,
         unattended: true,
         availableModes: [],
       }),
-    ).toEqual({ modeId: undefined, featureValues: { auto_accept: false } });
+    ).toEqual({ modeId: undefined, providerOptions: { auto_accept: false } });
   });
 
   test("maps an unattended cross-provider parent to ACP Auto Accept", () => {
@@ -2125,7 +2256,7 @@ describe("ACPAgentClient config features", () => {
       client.resolveCreateConfig({
         provider: "generic-acp",
         requestedMode: undefined,
-        featureValues: undefined,
+        providerOptions: undefined,
         parent: {
           provider: "claude",
           modeId: "bypassPermissions",
@@ -2134,7 +2265,7 @@ describe("ACPAgentClient config features", () => {
         unattended: false,
         availableModes: [{ id: "agent", label: "Agent" }],
       }),
-    ).toEqual({ modeId: undefined, featureValues: { auto_accept: true } });
+    ).toEqual({ modeId: undefined, providerOptions: { auto_accept: true } });
   });
 
   test("treats Auto Accept as an unattended ACP configuration", () => {
@@ -2150,7 +2281,7 @@ describe("ACPAgentClient config features", () => {
         config: {
           provider: "generic-acp",
           cwd: "/tmp/acp-features",
-          featureValues: { auto_accept: true },
+          providerOptions: { auto_accept: true },
         },
         availableModes: [],
       }),
@@ -2165,22 +2296,17 @@ describe("ACPAgentClient config features", () => {
     });
 
     await expect(
-      client.listFeatures({
+      client.listControls({
         provider: "generic-acp",
         cwd: "/tmp/acp-features",
-        featureValues: { auto_accept: true },
+        providerOptions: { auto_accept: true },
       }),
     ).resolves.toEqual([
-      expect.objectContaining({
+      expect.objectContaining({ type: "toggle", key: "auto_accept", label: "Auto Accept" }),
-        type: "toggle",
-        id: "auto_accept",
-        label: "Auto Accept",
-        value: true,
-      }),
     ]);
   });
 
-  test("derives features from configured ACP select options", async () => {
+  test("derives controls from configured ACP select options", async () => {
     class TestACPAgentClient extends ACPAgentClient {
       protected override async spawnProcess(): Promise<SpawnedACPProcess> {
         return {
@@ -2206,23 +2332,18 @@ describe("ACPAgentClient config features", () => {
     });
 
     await expect(
-      client.listFeatures({
+      client.listControls({
         provider: "copilot",
         cwd: "/tmp/acp-features",
       }),
     ).resolves.toEqual([
-      expect.objectContaining({
+      expect.objectContaining({ type: "toggle", key: "auto_accept" }),
-        type: "toggle",
-        id: "auto_accept",
-        value: false,
-      }),
       expect.objectContaining({
         type: "select",
-        id: "agent",
+        key: "agent",
-        value: "Probe Agent",
+        choices: [
-        options: [
+          expect.objectContaining({ value: "", label: "Default" }),
-          expect.objectContaining({ id: "", label: "Default", isDefault: false }),
+          expect.objectContaining({ value: "Probe Agent", label: "Probe Agent" }),
-          expect.objectContaining({ id: "Probe Agent", label: "Probe Agent", isDefault: true }),
         ],
       }),
     ]);
@@ -3997,7 +4118,7 @@ describe("ACPAgentClient probe cleanup", () => {
       terminateProcess: terminator.terminate,
     });
 
-    await client.listFeatures({ provider: "copilot", cwd: "/tmp/acp-features" });
+    await client.listControls({ provider: "copilot", cwd: "/tmp/acp-features" });
 
     expect(closeSession).toHaveBeenCalledWith({ sessionId: "feature-probe-session" });
     expect(terminator.terminated).toContain(child);

packages/server/src/server/agent/providers/acp-agent.ts

@@ -1,4 +1,7 @@
+import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
 import { ACPProviderOptionsSchema } from "./acp-options.js";
+import { applyProviderOptionsPatch } from "../option-controls.js";
+import { assertChangesAreLive } from "../provider-options.js";
 import { type ChildProcess, type ChildProcessWithoutNullStreams } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
@@ -65,7 +68,7 @@ import {
   type AgentCapabilityFlags,
   type AgentClient,
   type AgentCreateConfigUnattendedInput,
-  type AgentFeature,
+  type AgentOptionControl,
   type AgentLaunchContext,
   type AgentMetadata,
   type AgentMode,
@@ -848,10 +851,10 @@ export function deriveModelDefinitionsFromACP(
   }));
 }
 
-export function deriveFeaturesFromACP(
+export function deriveControlsFromACP(
   configOptions: SessionConfigOption[] | null | undefined,
   featureOptions: ACPConfigFeatureOption[],
-): AgentFeature[] {
+): AgentOptionControl[] {
   return featureOptions.flatMap((featureOption) => {
     const option = findSelectConfigFeatureOption(configOptions, featureOption);
     if (!option) {
@@ -861,42 +864,42 @@ export function deriveFeaturesFromACP(
     return [
       {
         type: "select",
-        id: featureOption.id,
+        key: featureOption.id,
         label: featureOption.label,
         description: featureOption.description,
         tooltip: featureOption.tooltip,
         icon: featureOption.icon,
-        value: option.currentValue ?? null,
+        choices: deriveConfigFeatureSelectOptions(option, featureOption).map((choice) => ({
-        options: deriveConfigFeatureSelectOptions(option, featureOption),
+          value: choice.id,
+          label: choice.label,
+          description: choice.description,
+        })),
       },
     ];
   });
 }
 
 function isACPAutoAcceptEnabled(config: AgentSessionConfig): boolean {
-  return config.featureValues?.[ACP_AUTO_ACCEPT_FEATURE_ID] === true;
+  return config.providerOptions?.[ACP_AUTO_ACCEPT_FEATURE_ID] === true;
 }
 
-function buildACPAutoAcceptFeature(config: AgentSessionConfig): AgentFeature {
+const ACP_AUTO_ACCEPT_CONTROL: AgentOptionControl = {
-  return {
+  type: "toggle",
-    type: "toggle",
+  key: ACP_AUTO_ACCEPT_FEATURE_ID,
-    id: ACP_AUTO_ACCEPT_FEATURE_ID,
+  label: "Auto Accept",
-    label: "Auto Accept",
+  description: "Automatically approves ACP permission prompts.",
-    description: "Automatically approves ACP permission prompts.",
+  tooltip: "Auto accept permission prompts",
-    tooltip: "Auto accept permission prompts",
+  icon: "shield-check",
-    icon: "shield-check",
+};
-    value: isACPAutoAcceptEnabled(config),
-  };
-}
 
 function resolveACPCreateConfig(
   input: ResolveAgentCreateConfigInput,
 ): ResolveAgentCreateConfigResult {
   const isUnattendedCreate = input.unattended || input.parent?.isUnattended === true;
-  const featureValues =
+  const providerOptions =
-    isUnattendedCreate && input.featureValues?.[ACP_AUTO_ACCEPT_FEATURE_ID] === undefined
+    isUnattendedCreate && input.providerOptions?.[ACP_AUTO_ACCEPT_FEATURE_ID] === undefined
-      ? { ...input.featureValues, [ACP_AUTO_ACCEPT_FEATURE_ID]: true }
+      ? { ...input.providerOptions, [ACP_AUTO_ACCEPT_FEATURE_ID]: true }
-      : input.featureValues;
+      : input.providerOptions;
 
   if (
     input.requestedMode === undefined &&
@@ -904,22 +907,16 @@ function resolveACPCreateConfig(
     input.parent !== null &&
     input.parent.provider !== input.provider
   ) {
-    return { modeId: undefined, featureValues };
+    return { modeId: undefined, providerOptions };
   }
 
-  return resolveDefaultAgentCreateConfig({ ...input, featureValues });
+  return resolveDefaultAgentCreateConfig({ ...input, providerOptions });
 }
 
 function isACPCreateConfigUnattended(input: AgentCreateConfigUnattendedInput): boolean {
   return (
     isDefaultAgentCreateConfigUnattended(input) ||
-    input.config.featureValues?.[ACP_AUTO_ACCEPT_FEATURE_ID] === true ||
+    input.config.providerOptions?.[ACP_AUTO_ACCEPT_FEATURE_ID] === true
-    input.features?.some(
-      (feature) =>
-        feature.id === ACP_AUTO_ACCEPT_FEATURE_ID &&
-        feature.type === "toggle" &&
-        feature.value === true,
-    ) === true
   );
 }
 
@@ -1198,10 +1195,9 @@ export class ACPAgentClient implements AgentClient {
     }
   }
 
-  async listFeatures(config: AgentSessionConfig): Promise<AgentFeature[]> {
+  async listControls(config: AgentSessionConfig): Promise<AgentOptionControl[]> {
-    const autoAcceptFeature = buildACPAutoAcceptFeature(config);
     if (this.configFeatureOptions.length === 0) {
-      return [autoAcceptFeature];
+      return [ACP_AUTO_ACCEPT_CONTROL];
     }
 
     this.assertProvider(config);
@@ -1217,8 +1213,8 @@ export class ACPAgentClient implements AgentClient {
       probeSessionId = response.sessionId;
       const transformed = this.transformSessionResponse(response);
       return [
-        autoAcceptFeature,
+        ACP_AUTO_ACCEPT_CONTROL,
-        ...deriveFeaturesFromACP(transformed.configOptions, this.configFeatureOptions),
+        ...deriveControlsFromACP(transformed.configOptions, this.configFeatureOptions),
       ];
     } finally {
       await this.closeProbe(probe, probeSessionId);
@@ -1761,6 +1757,11 @@ export class ACPAgentSession implements AgentSession, ACPClient {
   private currentTitle: string | null = null;
   private lastActivityAt: string | null = null;
   private configOptions: SessionConfigOption[] = [];
+  /** How the opened session differs from the options it was given. */
+  openOptionsPatch: Record<string, unknown> = {};
+  /** Selects the provider moves while Paseo is opening or applying options belong to that result, not to events. */
+  private optionsTransactionDepth = 0;
+  private applying: Promise<unknown> = Promise.resolve();
   private cachedCommands: AgentSlashCommand[] = [];
   /** When the last command batch arrived; null while nothing has been published. */
   private commandsUpdatedAt: number | null = null;
@@ -2054,10 +2055,10 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     return this.currentMode;
   }
 
-  get features(): AgentFeature[] {
+  get controls(): AgentOptionControl[] {
     return [
-      buildACPAutoAcceptFeature(this.config),
+      ACP_AUTO_ACCEPT_CONTROL,
-      ...deriveFeaturesFromACP(this.configOptions, this.configFeatureOptions),
+      ...deriveControlsFromACP(this.configOptions, this.configFeatureOptions),
     ];
   }
 
@@ -2198,6 +2199,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     }
 
     const { connection, sessionId } = this;
+    const before = this.featureValues();
     const response = await this.runACPRequest(() =>
       connection.setSessionConfigOption({
         sessionId,
@@ -2212,6 +2214,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
       requestedValue: modeId,
       label: "mode",
     });
+    this.reportFeatureChanges(before);
     this.availableModes = deriveModesFromACP(this.defaultModes, null, this.configOptions).modes;
     this.pushEvent({
       type: "mode_changed",
@@ -2323,6 +2326,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     }
 
     const { connection, sessionId } = this;
+    const before = this.featureValues();
     const response = await this.runACPRequest(() =>
       connection.setSessionConfigOption({
         sessionId,
@@ -2337,6 +2341,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
       requestedValue: modelId,
       label: "model",
     });
+    this.reportFeatureChanges(before);
     this.pushEvent({
       type: "model_changed",
       provider: this.provider,
@@ -2374,6 +2379,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
       throw new Error(`${this.provider} does not expose ACP thought-level selection`);
     }
     const { connection, sessionId } = this;
+    const before = this.featureValues();
     const response = await this.runACPRequest(() =>
       connection.setSessionConfigOption({
         sessionId,
@@ -2388,6 +2394,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
       requestedValue: thinkingOptionId,
       label: "thought-level",
     });
+    this.reportFeatureChanges(before);
     this.pushEvent({
       type: "thinking_option_changed",
       provider: this.provider,
@@ -2395,14 +2402,103 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     });
   }
 
-  async setFeature(featureId: string, value: unknown): Promise<void> {
+  /**
+   * Applies only the options the patch sets; returns the selects that ended up different.
+   * Provider notifications that arrive meanwhile are part of that result. When a write is
+   * rejected, what the provider moved is reported as an event, since nothing is stored.
+   */
+  /** One apply at a time: each reconciles against the state the one before it left. */
+  applyOptions(options: ProviderOptions): Promise<Record<string, unknown>> {
+    const run = this.applying.then(() => this.applyOptionsNow(options));
+    this.applying = run.catch(() => undefined);
+    return run;
+  }
+
+  private async applyOptionsNow(options: ProviderOptions): Promise<Record<string, unknown>> {
+    assertChangesAreLive({
+      provider: this.config.provider,
+      patch: options,
+      current: this.config.providerOptions,
+      live: [ACP_AUTO_ACCEPT_FEATURE_ID, ...this.configFeatureOptions.map(({ id }) => id)],
+    });
+    ACPProviderOptionsSchema.parse(
+      applyProviderOptionsPatch({ options: this.config.providerOptions, patch: options }),
+    );
+    const before = this.featureValues();
+    const requested: Record<string, unknown> = {};
+    try {
+      await this.inOptionsTransaction(async () => {
+        for (const [id, value] of Object.entries(options)) {
+          const featureOption = this.configFeatureOptions.find((candidate) => candidate.id === id);
+          if (!featureOption) continue;
+          // A removal asks for the select's empty choice; a provider without one rejects it.
+          requested[id] = value ?? "";
+          const option = findSelectConfigFeatureOption(this.configOptions, featureOption);
+          if (!option || requested[id] !== option.currentValue) {
+            await this.setConfigFeature(id, value);
+          }
+        }
+      });
+    } catch (error) {
+      this.reportFeatureChanges(before);
+      throw error;
+    }
+    // Auto Accept is Paseo's own setting, so it changes only once every write has been accepted.
+    if (ACP_AUTO_ACCEPT_FEATURE_ID in options) {
+      this.config.providerOptions = {
+        ...this.config.providerOptions,
+        [ACP_AUTO_ACCEPT_FEATURE_ID]: options[ACP_AUTO_ACCEPT_FEATURE_ID] === true,
+      };
+    }
+    return this.featureDifferences({ ...before, ...requested });
+  }
+
+  private async inOptionsTransaction<T>(run: () => Promise<T>): Promise<T> {
+    this.optionsTransactionDepth += 1;
+    try {
+      return await run();
+    } finally {
+      this.optionsTransactionDepth -= 1;
+    }
+  }
+
+  /** The selects as the provider reports them now. */
+  private featureValues(): Record<string, string> {
+    const values: Record<string, string> = {};
+    for (const featureOption of this.configFeatureOptions) {
+      const current = findSelectConfigFeatureOption(
+        this.configOptions,
+        featureOption,
+      )?.currentValue;
+      if (current != null) values[featureOption.id] = current;
+    }
+    return values;
+  }
+
+  /** The selects whose value is not what `expected` says, including ones it does not name. */
+  private featureDifferences(expected: Record<string, unknown>): Record<string, string> {
+    return Object.fromEntries(
+      Object.entries(this.featureValues()).filter(([id, value]) => expected[id] !== value),
+    );
+  }
+
+  /** Reports the selects the provider moved on its own, compared with their values `before`. */
+  private reportFeatureChanges(before: Record<string, string>): void {
+    if (this.optionsTransactionDepth > 0) return;
+    const patch = this.featureDifferences(before);
+    if (Object.keys(patch).length > 0) {
+      this.pushEvent({ type: "options_changed", provider: this.provider, patch });
+    }
+  }
+
+  private async setConfigFeature(featureId: string, value: unknown): Promise<void> {
     if (!this.connection || !this.sessionId) {
       throw new Error("ACP session not initialized");
     }
 
     if (featureId === ACP_AUTO_ACCEPT_FEATURE_ID) {
-      this.config.featureValues = {
+      this.config.providerOptions = {
-        ...this.config.featureValues,
+        ...this.config.providerOptions,
         [ACP_AUTO_ACCEPT_FEATURE_ID]: value === true,
       };
       return;
@@ -2434,14 +2530,13 @@ export class ACPAgentSession implements AgentSession, ACPClient {
         value: requestedValue,
       }),
     );
-    const currentValue = this.applyConfigOptionResponse({
+    this.applyConfigOptionResponse({
       response,
       configId: option.id,
       category: featureOption.category,
       requestedValue,
       label: featureOption.label,
     });
-    this.config.featureValues = { ...this.config.featureValues, [featureId]: currentValue };
   }
 
   private applyConfigOptionResponse({
@@ -2986,7 +3081,11 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     return this.modeIdTransformer ? this.modeIdTransformer(modeId) : modeId;
   }
 
-  private async applyConfiguredOverrides(): Promise<void> {
+  private applyConfiguredOverrides(): Promise<void> {
+    return this.inOptionsTransaction(() => this.writeConfiguredOverrides());
+  }
+
+  private async writeConfiguredOverrides(): Promise<void> {
     const configuredModeId = this.config.modeId;
     if (configuredModeId && configuredModeId !== this.currentMode) {
       const selection = resolveACPModeSelection({
@@ -3018,13 +3117,13 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     if (this.config.thinkingOptionId && this.config.thinkingOptionId !== this.thinkingOptionId) {
       await this.setThinkingOption(this.config.thinkingOptionId);
     }
-    const configuredFeatureValues = this.config.featureValues ?? {};
+    const configuredFeatureValues = this.config.providerOptions ?? {};
     for (const featureOption of this.configFeatureOptions) {
       if (!Object.prototype.hasOwnProperty.call(configuredFeatureValues, featureOption.id)) {
         continue;
       }
       try {
-        await this.setFeature(featureOption.id, configuredFeatureValues[featureOption.id]);
+        await this.setConfigFeature(featureOption.id, configuredFeatureValues[featureOption.id]);
       } catch (error) {
         if (!this.isStaleFeatureValueError(error, featureOption.id, switchedModel)) {
           throw error;
@@ -3035,6 +3134,9 @@ export class ACPAgentSession implements AgentSession, ACPClient {
         );
       }
     }
+    // The options are the state, so every select the session opened with is reported, including
+    // ones nobody set (a native default is stored like any other value).
+    this.openOptionsPatch = this.featureDifferences(configuredFeatureValues);
   }
 
   /**
@@ -3248,6 +3350,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
   }
 
   private handleConfigOptionUpdate(update: ConfigOptionUpdate): AgentStreamEvent[] {
+    const before = this.featureValues();
     this.configOptions = this.transformConfigOptions(update.configOptions);
     const modeInfo = deriveModesFromACP(this.defaultModes, null, this.configOptions);
     const nextMode = modeInfo.currentModeId;
@@ -3258,6 +3361,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     this.currentMode = nextMode ?? this.currentMode;
     this.currentModel = nextModel ?? this.currentModel;
     this.thinkingOptionId = nextThinkingOptionId ?? this.thinkingOptionId;
+    this.reportFeatureChanges(before);
 
     const events: AgentStreamEvent[] = [];
     if (nextMode !== null) {

packages/server/src/server/agent/providers/acp-options.ts

@@ -2,6 +2,8 @@ import { z } from "zod";
 
 export const ACPProviderOptionsSchema = z
   .object({
+    // Composer control: approves permission prompts without asking.
+    auto_accept: z.boolean().optional(),
     supportsMcpServers: z.boolean().optional(),
     clientCapabilities: z
       .object({

packages/server/src/server/agent/providers/claude/agent.test.ts

@@ -18,6 +18,9 @@ import {
   resolveClaudeCodeVersion,
   toClaudeSdkMcpConfig,
 } from "./agent.js";
+import { AgentManager } from "../../agent-manager.js";
+import { ensureAgentLoaded } from "../../agent-loading.js";
+import { AgentStorage } from "../../agent-storage.js";
 import { createImportDescriptorScheduler } from "./import-descriptor-scheduler.js";
 import { claudeProjectDirSync } from "./project-dir.js";
 import { streamSession } from "../test-utils/session-stream-adapter.js";
@@ -30,6 +33,8 @@ import type {
 } from "../../agent-sdk-types.js";
 import type { AgentAttachment } from "@getpaseo/protocol/messages";
 import { buildAgentPrompt, renderPromptAttachmentAsText } from "../../prompt-attachments.js";
+import { applyProviderOptionsPatch } from "../../option-controls.js";
+import { mergeProviderOptions } from "../../provider-options.js";
 
 interface TestClaudeSession {
   translateMessageToEvents(message: SDKMessage): Promise<AgentStreamEvent[]>;
@@ -953,39 +958,39 @@ describe("ClaudeAgentSession features", () => {
     const client = new ClaudeAgentClient({ logger, resolveBinary: async () => "/test/claude/bin" });
 
     await expect(
-      client.listFeatures({
+      client.listControls({
         provider: "claude",
         cwd: process.cwd(),
         model: "claude-opus-4-8",
       }),
-    ).resolves.toEqual([expect.objectContaining({ id: "fast_mode", value: false })]);
+    ).resolves.toEqual([expect.objectContaining({ key: "fast_mode", type: "toggle" })]);
 
     await expect(
-      client.listFeatures({
+      client.listControls({
         provider: "claude",
         cwd: process.cwd(),
         model: "claude-opus-4-8[1m]",
       }),
-    ).resolves.toEqual([expect.objectContaining({ id: "fast_mode", value: false })]);
+    ).resolves.toEqual([expect.objectContaining({ key: "fast_mode", type: "toggle" })]);
 
     await expect(
-      client.listFeatures({
+      client.listControls({
         provider: "claude",
         cwd: process.cwd(),
         model: "claude-opus-4-8-20260101",
       }),
-    ).resolves.toEqual([expect.objectContaining({ id: "fast_mode", value: false })]);
+    ).resolves.toEqual([expect.objectContaining({ key: "fast_mode", type: "toggle" })]);
 
     await expect(
-      client.listFeatures({
+      client.listControls({
         provider: "claude",
         cwd: process.cwd(),
         model: "claude-opus-5",
       }),
-    ).resolves.toEqual([expect.objectContaining({ id: "fast_mode", value: false })]);
+    ).resolves.toEqual([expect.objectContaining({ key: "fast_mode", type: "toggle" })]);
 
     await expect(
-      client.listFeatures({
+      client.listControls({
         provider: "claude",
         cwd: process.cwd(),
         model: "openrouter/anthropic/claude-opus-4-8",
@@ -993,7 +998,7 @@ describe("ClaudeAgentSession features", () => {
     ).resolves.toEqual([]);
 
     await expect(
-      client.listFeatures({
+      client.listControls({
         provider: "claude",
         cwd: process.cwd(),
         model: "claude-sonnet-5",
@@ -1001,7 +1006,7 @@ describe("ClaudeAgentSession features", () => {
     ).resolves.toEqual([]);
 
     await expect(
-      client.listFeatures({
+      client.listControls({
         provider: "claude",
         cwd: process.cwd(),
         model: "claude-sonnet-4-6",
@@ -1009,6 +1014,25 @@ describe("ClaudeAgentSession features", () => {
     ).resolves.toEqual([]);
   });
 
+  test("opens with Fast off on a model that has none, so unrelated options still apply", async () => {
+    const { queryFactory } = createQueryMock();
+    const client = new ClaudeAgentClient({
+      logger,
+      queryFactory,
+      resolveBinary: async () => "/test/claude/bin",
+    });
+    const session = await client.createSession({
+      provider: "claude",
+      cwd: process.cwd(),
+      model: "claude-sonnet-5",
+      providerOptions: { fast_mode: true },
+    });
+
+    expect(session.openOptionsPatch).toEqual({ fast_mode: false });
+    await expect(session.applyOptions?.({ allowedTools: ["Read"] })).resolves.toBeUndefined();
+    await session.close();
+  });
+
   test("passes initial fast mode through Claude flag settings", async () => {
     const { queryFactory, queryMock } = createQueryMock();
     const client = new ClaudeAgentClient({
@@ -1020,7 +1044,7 @@ describe("ClaudeAgentSession features", () => {
       provider: "claude",
       cwd: process.cwd(),
       model: "claude-opus-4-8",
-      featureValues: { fast_mode: true },
+      providerOptions: { fast_mode: true },
     });
 
     await expect(
@@ -1492,7 +1516,7 @@ describe("ClaudeAgentSession features", () => {
         ensureQuery(): Promise<unknown>;
       }
     ).ensureQuery();
-    await session.setFeature?.("fast_mode", true);
+    await session.applyOptions?.({ fast_mode: true });
 
     expect(queryFactory).toHaveBeenCalledTimes(1);
     expect(queryMock.applyFlagSettings).toHaveBeenLastCalledWith({ fastMode: true });
@@ -1501,6 +1525,242 @@ describe("ClaudeAgentSession features", () => {
 
     await session.close();
   });
+
+  test("rejects a change to a launch option while the first query is starting", async () => {
+    const { queryFactory } = createQueryMock();
+    let releaseBinary!: () => void;
+    const binaryLookup = new Promise<void>((resolve) => {
+      releaseBinary = resolve;
+    });
+    let lookupStarted!: () => void;
+    const lookupEntered = new Promise<void>((resolve) => {
+      lookupStarted = resolve;
+    });
+    const client = new ClaudeAgentClient({
+      logger,
+      queryFactory,
+      resolveBinary: async () => {
+        lookupStarted();
+        await binaryLookup;
+        return "/test/claude/bin";
+      },
+    });
+    const session = await client.createSession({
+      provider: "claude",
+      cwd: process.cwd(),
+      model: "claude-opus-4-8",
+      providerOptions: { disallowedTools: ["Bash"] },
+    });
+
+    const turn = session.startTurn("hello");
+    await lookupEntered;
+    await expect(session.applyOptions?.({ disallowedTools: [] })).rejects.toThrow(
+      /disallowedTools.*cannot change on a running session/,
+    );
+    releaseBinary();
+    await turn;
+
+    expect(queryFactory.mock.calls[0]?.[0].options).toMatchObject({ disallowedTools: ["Bash"] });
+    await session.close();
+  });
+
+  test("a patch before the first prompt keeps the restrictions the session opened with", async () => {
+    const { queryFactory } = createQueryMock();
+    const client = new ClaudeAgentClient({
+      logger,
+      queryFactory,
+      resolveBinary: async () => "/test/claude/bin",
+    });
+    const session = await client.createSession({
+      provider: "claude",
+      cwd: process.cwd(),
+      model: "claude-opus-4-8",
+      providerOptions: {
+        disallowedTools: ["Bash"],
+        sandbox: { enabled: true, failIfUnavailable: true },
+      },
+    });
+
+    await session.applyOptions?.({ fast_mode: true });
+    await (session as unknown as { ensureQuery(): Promise<unknown> }).ensureQuery();
+
+    expect(queryFactory.mock.calls[0]?.[0].options).toMatchObject({
+      disallowedTools: ["Bash"],
+      sandbox: { enabled: true, failIfUnavailable: true },
+    });
+    await session.close();
+  });
+
+  test("an option Claude reads when it starts changes before the query exists and is rejected after", async () => {
+    const { queryFactory } = createQueryMock();
+    const client = new ClaudeAgentClient({
+      logger,
+      queryFactory,
+      resolveBinary: async () => "/test/claude/bin",
+    });
+    const session = await client.createSession({
+      provider: "claude",
+      cwd: process.cwd(),
+      model: "claude-opus-4-8",
+      providerOptions: { disallowedTools: ["Bash"] },
+    });
+
+    await session.applyOptions?.({ disallowedTools: ["Bash", "Write"] });
+    await (session as unknown as { ensureQuery(): Promise<unknown> }).ensureQuery();
+    expect(queryFactory.mock.calls[0]?.[0].options).toMatchObject({
+      disallowedTools: ["Bash", "Write"],
+    });
+
+    // The query now runs with these; replacing it would end its background work.
+    await expect(session.applyOptions?.({ disallowedTools: [] })).rejects.toThrow(
+      /disallowedTools.*cannot change on a running session/,
+    );
+    // The same value is not a change, and Fast still applies.
+    await expect(
+      session.applyOptions?.({ disallowedTools: ["Bash", "Write"], fast_mode: true }),
+    ).resolves.toBeUndefined();
+    expect(queryFactory).toHaveBeenCalledTimes(1);
+    await session.close();
+  });
+
+  test("switching to a model without Fast turns it off, reports that, and later patches still apply", async () => {
+    const { queryFactory, queryMock } = createQueryMock();
+    const client = new ClaudeAgentClient({
+      logger,
+      queryFactory,
+      resolveBinary: async () => "/test/claude/bin",
+    });
+    const session = await client.createSession({
+      provider: "claude",
+      cwd: process.cwd(),
+      model: "claude-opus-4-8",
+      providerOptions: { fast_mode: true },
+    });
+    const events: AgentStreamEvent[] = [];
+    session.subscribe((event) => events.push(event));
+
+    await session.setModel?.("claude-fable-5");
+
+    expect(queryMock.applyFlagSettings).toHaveBeenLastCalledWith({ fastMode: false });
+    const reported = events.filter((event) => event.type === "options_changed");
+    expect(reported).toEqual([
+      { type: "options_changed", provider: "claude", patch: { fast_mode: false } },
+    ]);
+    // With a `config.json` default of `fast_mode: true`, the agent's effective options must
+    // still read Fast as off: a removed key would let the default fill `true` back in.
+    const stored = applyProviderOptionsPatch({
+      options: { fast_mode: true },
+      patch: reported[0].patch,
+    });
+    expect(mergeProviderOptions({ fast_mode: true }, stored)).toEqual({ fast_mode: false });
+    await expect(session.applyOptions?.({ fast_mode: null })).resolves.toBeUndefined();
+    await session.close();
+  });
+
+  test("removing fast_mode turns Fast off", async () => {
+    const { queryFactory, queryMock } = createQueryMock();
+    const client = new ClaudeAgentClient({
+      logger,
+      queryFactory,
+      resolveBinary: async () => "/test/claude/bin",
+    });
+    const session = await client.createSession({
+      provider: "claude",
+      cwd: process.cwd(),
+      model: "claude-opus-4-8",
+    });
+    await (session as unknown as { ensureQuery(): Promise<unknown> }).ensureQuery();
+    await session.applyOptions?.({ fast_mode: true });
+
+    await session.applyOptions?.({ fast_mode: null });
+
+    expect(queryMock.applyFlagSettings).toHaveBeenLastCalledWith({ fastMode: false });
+    await session.close();
+  });
+
+  test("retries a fast mode change the runtime rejected", async () => {
+    const { queryFactory, queryMock } = createQueryMock();
+    const client = new ClaudeAgentClient({
+      logger,
+      queryFactory,
+      resolveBinary: async () => "/test/claude/bin",
+    });
+    const session = await client.createSession({
+      provider: "claude",
+      cwd: process.cwd(),
+      model: "claude-opus-4-8",
+    });
+    await (session as unknown as { ensureQuery(): Promise<unknown> }).ensureQuery();
+    queryMock.applyFlagSettings.mockClear();
+    queryMock.applyFlagSettings.mockRejectedValueOnce(new Error("runtime unavailable"));
+
+    await expect(session.applyOptions?.({ fast_mode: true })).rejects.toThrow(
+      "runtime unavailable",
+    );
+    await session.applyOptions?.({ fast_mode: true });
+
+    expect(queryMock.applyFlagSettings).toHaveBeenCalledTimes(2);
+    expect(queryMock.applyFlagSettings).toHaveBeenLastCalledWith({ fastMode: true });
+
+    await session.close();
+  });
+
+  test("fast mode survives a daemon restart through the stored providerOptions", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "claude-fast-restart-"));
+    const storagePath = path.join(root, "agents");
+    const makeClient = () => {
+      const mock = createQueryMock();
+      const client = new ClaudeAgentClient({
+        logger,
+        queryFactory: mock.queryFactory,
+        resolveBinary: async () => "/test/claude/bin",
+      });
+      return { ...mock, client };
+    };
+    const agentId = "00000000-0000-4000-8000-0000000000f1";
+    const before = makeClient();
+    const storage = new AgentStorage(storagePath, logger);
+    const manager = new AgentManager({
+      clients: { claude: before.client },
+      registry: storage,
+      logger,
+    });
+    try {
+      await manager.createAgent(
+        { provider: "claude", cwd: root, model: "claude-opus-4-8" },
+        agentId,
+        { workspaceId: undefined },
+      );
+      await manager.setAgentOptions(agentId, { fast_mode: true });
+      await manager.closeAgent(agentId);
+      await manager.flush();
+      await storage.flush();
+
+      const after = makeClient();
+      const restartedStorage = new AgentStorage(storagePath, logger);
+      const restarted = new AgentManager({
+        clients: { claude: after.client },
+        registry: restartedStorage,
+        logger,
+      });
+      const agent = await ensureAgentLoaded(agentId, {
+        agentManager: restarted,
+        agentStorage: restartedStorage,
+        logger,
+      });
+      const session = (agent as unknown as { session: { ensureQuery(): Promise<unknown> } | null })
+        .session;
+      await session?.ensureQuery();
+
+      expect(restarted.getAgent(agentId)?.config.providerOptions).toEqual({ fast_mode: true });
+      expect(after.queryFactory.mock.calls[0]?.[0].options.settings).toMatchObject({
+        fastMode: true,
+      });
+      await restarted.closeAgent(agentId);
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
 });
 
 describe("normalizeClaudeAskUserQuestionUpdatedInput", () => {

packages/server/src/server/agent/providers/claude/agent.ts

@@ -1,6 +1,8 @@
 import { setImmediate } from "node:timers/promises";
 import { ClaudeRuntimeSafety } from "./runtime-safety.js";
-import { validateProviderOptions } from "../../provider-options.js";
+import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
+import { applyProviderOptionsPatch } from "../../option-controls.js";
+import { assertChangesAreLive, validateProviderOptions } from "../../provider-options.js";
 import type { ChildProcess } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
@@ -65,7 +67,7 @@ import { foldSubagentObservations, type SubagentObservation } from "./subagents/
 import { observeReplayWorkflows } from "./subagents/workflow-replay-source.js";
 import { limitAgentTimelineItemContent } from "../../agent-timeline-content.js";
 import { readClaudeWorkflowResultFile } from "./subagents/workflow-output.js";
-import { buildClaudeFeatures, claudeModelSupportsFastMode } from "./feature-definitions.js";
+import { buildClaudeControls, claudeModelSupportsFastMode } from "./feature-definitions.js";
 import {
   buildBinaryDiagnosticRows,
   buildCommandResolutionDiagnosticRows,
@@ -104,7 +106,7 @@ import {
   type AgentCapabilityFlags,
   type AgentClient,
   type AgentCreateSessionOptions,
-  type AgentFeature,
+  type AgentOptionControl,
   type AgentLaunchContext,
   type AgentMetadata,
   type AgentMode,
@@ -1752,12 +1754,8 @@ export class ClaudeAgentClient implements AgentClient {
     });
   }
 
-  async listFeatures(config: AgentSessionConfig): Promise<AgentFeature[]> {
+  async listControls(config: AgentSessionConfig): Promise<AgentOptionControl[]> {
-    const claudeConfig = this.assertConfig(config);
+    return buildClaudeControls(this.assertConfig(config).model);
-    return buildClaudeFeatures({
-      modelId: claudeConfig.model,
-      fastModeEnabled: claudeConfig.featureValues?.fast_mode === true,
-    });
   }
 
   async listImportableSessions(
@@ -2380,6 +2378,8 @@ class ClaudeAgentSession implements AgentSession {
   private compactionMarkerOpen = false;
   private queryPumpPromise: Promise<void> | null = null;
   private queryRestartNeeded = false;
+  /** True from the moment a query's launch options are copied until the query exists. */
+  private queryStarting = false;
   private pendingInterruptAbort = false;
   /**
    * Whether Claude's main session is inside one of its own turns: set by system/init and by a
@@ -2397,6 +2397,7 @@ class ClaudeAgentSession implements AgentSession {
   private pendingFreshSessionId: string | null = null;
   private recentStderr = "";
   private closed = false;
+  readonly openOptionsPatch: Record<string, unknown> = {};
 
   constructor(config: ClaudeAgentConfig, options: ClaudeAgentSessionOptions) {
     this.config = config;
@@ -2440,17 +2441,21 @@ class ClaudeAgentSession implements AgentSession {
     if (this.currentMode !== "plan") {
       this.planResumeMode = this.currentMode;
     }
+
+    // Fast cannot run on this model, so the session opens with it off. Off rather than removed
+    // keeps a `config.json` default of `fast_mode: true` from filling it back in.
+    if (config.providerOptions.fast_mode === true && !claudeModelSupportsFastMode(config.model)) {
+      this.config.providerOptions = { ...config.providerOptions, fast_mode: false };
+      this.openOptionsPatch = { fast_mode: false };
+    }
   }
 
   get id(): string | null {
     return this.claudeSessionId;
   }
 
-  get features(): AgentFeature[] {
+  get controls(): AgentOptionControl[] {
-    return buildClaudeFeatures({
+    return buildClaudeControls(this.config.model);
-      modelId: this.config.model,
-      fastModeEnabled: this.config.featureValues?.fast_mode === true,
-    });
   }
 
   async getRuntimeInfo(): Promise<AgentRuntimeInfo> {
@@ -2748,8 +2753,20 @@ class ClaudeAgentSession implements AgentSession {
     await activeQuery.setModel(normalizedModelId ?? undefined);
     this.config.model = normalizedModelId ?? undefined;
     this.reconcileThinkingOptionForModel(normalizedModelId);
-    if (!claudeModelSupportsFastMode(this.config.model) && this.config.featureValues?.fast_mode) {
+    if (this.config.providerOptions.fast_mode) {
-      await this.applyFastModeFeature(false, activeQuery);
+      const supported = claudeModelSupportsFastMode(this.config.model);
+      await activeQuery.applyFlagSettings({ fastMode: supported });
+      if (!supported) {
+        // Fast cannot run on this model. Reporting it off rather than removed keeps a
+        // `config.json` default of `fast_mode: true` from filling it back in.
+        this.config.providerOptions = { ...this.config.providerOptions, fast_mode: false };
+        this.pushEvent({
+          type: "options_changed",
+          provider: "claude",
+          patch: { fast_mode: false },
+        });
+      }
+      this.cachedRuntimeInfo = null;
     }
     this.contextUsage.setInitialContextWindowMaxTokens(
       getClaudeContextWindowMaxTokens(this.config.model),
@@ -2801,31 +2818,41 @@ class ClaudeAgentSession implements AgentSession {
     }
   }
 
-  async setFeature(featureId: string, value: unknown): Promise<void> {
+  async applyOptions(options: ProviderOptions): Promise<void> {
-    if (featureId !== "fast_mode") {
+    // Every option but Fast is read when the query is built, and replacing a started query would
-      throw new Error(`Unknown Claude feature: ${featureId}`);
+    // end its background work, so once it exists only Fast can change.
+    if (this.query || this.queryStarting) {
+      assertChangesAreLive({
+        provider: "claude",
+        patch: options,
+        current: this.config.providerOptions,
+        live: ["fast_mode"],
+      });
     }
-
+    const providerOptions =
-    const enabled = Boolean(value);
+      validateProviderOptions(
-    if (enabled && !claudeModelSupportsFastMode(this.config.model)) {
+        "claude",
+        ClaudeProviderOptionsSchema,
+        applyProviderOptionsPatch({ options: this.config.providerOptions, patch: options }),
+      ) ?? {};
+    if (providerOptions.fast_mode === true && !claudeModelSupportsFastMode(this.config.model)) {
       throw new Error(
         `Claude fast mode is not available for model '${this.config.model ?? "default"}'`,
       );
     }
-
+    const fastModeChanged =
-    await this.applyFastModeFeature(enabled);
+      (providerOptions.fast_mode === true) !== (this.config.providerOptions.fast_mode === true);
-  }
+    if (fastModeChanged) {
-
+      await this.query?.applyFlagSettings({ fastMode: providerOptions.fast_mode === true });
-  private async applyFastModeFeature(enabled: boolean, query?: Query): Promise<void> {
+      this.cachedRuntimeInfo = null;
-    this.config.featureValues = {
-      ...this.config.featureValues,
-      fast_mode: enabled,
-    };
-    const activeQuery = query ?? this.query;
-    if (activeQuery) {
-      await activeQuery.applyFlagSettings({ fastMode: enabled });
     }
-    this.cachedRuntimeInfo = null;
+    // Held until the runtime accepts, so a rejected change is retried instead of skipped. Only
+    // this call's keys are applied, over the options as they are now: another patch may have
+    // landed while the runtime was answering.
+    this.config.providerOptions = applyProviderOptionsPatch({
+      options: this.config.providerOptions,
+      patch: options,
+    });
   }
 
   getPendingPermissions(): AgentPermissionRequest[] {
@@ -3517,7 +3544,15 @@ class ClaudeAgentSession implements AgentSession {
     this.persistence = null;
 
     const input = createAsyncMessageInput<SDKUserMessage>();
-    const options = await this.buildOptions(launchMode);
+    // buildOptions copies the launch options before it waits, so from here they are fixed.
+    this.queryStarting = true;
+    let options: ClaudeOptions;
+    try {
+      options = await this.buildOptions(launchMode);
+    } catch (error) {
+      this.queryStarting = false;
+      throw error;
+    }
     this.logger.debug({ options: summarizeClaudeOptionsForLog(options) }, "claude query");
     this.input = input;
     this.runtimeSafety.reset();
@@ -3535,6 +3570,7 @@ class ClaudeAgentSession implements AgentSession {
         },
       },
     );
+    this.queryStarting = false;
     const fastMode = this.resolveFastModeSetting();
     if (fastMode !== null) {
       await this.query.applyFlagSettings({ fastMode });
@@ -3654,10 +3690,9 @@ class ClaudeAgentSession implements AgentSession {
   private async buildOptions(permissionMode: PermissionMode): Promise<ClaudeOptions> {
     const { thinking, effort, ultracode } = this.resolveThinkingConfig();
     const appendedSystemPrompt = this.buildAppendedSystemPrompt();
-    const providerOptions = applyClaudeToolPolicy(
+    // `fast_mode` is a composer control the provider applies through flag settings.
-      this.config.providerOptions,
+    const { fast_mode: _fastMode, ...sdkProviderOptions } = this.config.providerOptions;
-      this.config.toolPolicy,
+    const providerOptions = applyClaudeToolPolicy(sdkProviderOptions, this.config.toolPolicy);
-    );
     const settingsOptions = await this.buildSettingsOptions(providerOptions, { ultracode });
     const sdkEnv = this.harnessEnvironment;
     assertClaudeModeCanRun(permissionMode, sdkEnv);
@@ -3776,7 +3811,7 @@ class ClaudeAgentSession implements AgentSession {
     if (!claudeModelSupportsFastMode(this.config.model)) {
       return null;
     }
-    return this.config.featureValues?.fast_mode === true;
+    return this.config.providerOptions.fast_mode === true;
   }
 
   private normalizeMcpServers(

packages/server/src/server/agent/providers/claude/feature-definitions.ts

@@ -1,9 +1,9 @@
-import type { AgentFeature, AgentFeatureToggle } from "../../agent-sdk-types.js";
+import type { AgentOptionControl, AgentOptionToggleControl } from "../../agent-sdk-types.js";
 import { claudeManifestModelSupportsFastMode } from "./model-manifest.js";
 
-export const CLAUDE_FAST_MODE_FEATURE: Omit<AgentFeatureToggle, "value"> = {
+export const CLAUDE_FAST_MODE_CONTROL: AgentOptionToggleControl = {
   type: "toggle",
-  id: "fast_mode",
+  key: "fast_mode",
   label: "Fast",
   description: "Lower latency Opus responses at higher token cost",
   tooltip: "Toggle fast mode",
@@ -14,18 +14,6 @@ export function claudeModelSupportsFastMode(modelId: string | null | undefined):
   return claudeManifestModelSupportsFastMode(modelId);
 }
 
-export function buildClaudeFeatures(input: {
+export function buildClaudeControls(modelId: string | null | undefined): AgentOptionControl[] {
-  modelId: string | null | undefined;
+  return claudeModelSupportsFastMode(modelId) ? [{ ...CLAUDE_FAST_MODE_CONTROL }] : [];
-  fastModeEnabled: boolean;
-}): AgentFeature[] {
-  if (!claudeModelSupportsFastMode(input.modelId)) {
-    return [];
-  }
-
-  return [
-    {
-      ...CLAUDE_FAST_MODE_FEATURE,
-      value: input.fastModeEnabled,
-    },
-  ];
 }

packages/server/src/server/agent/providers/claude/options.ts

@@ -45,6 +45,8 @@ const SandboxFilesystemSchema = z
 // Claude Agent SDK Options, maintained against @anthropic-ai/claude-agent-sdk 0.3.246.
 export const ClaudeProviderOptionsSchema = z
   .object({
+    /** Composer control, not a Claude SDK option: the provider reads it and keeps it out of the SDK options. */
+    fast_mode: z.boolean().optional(),
     allowedTools: z.array(z.string()).optional(),
     disallowedTools: z.array(z.string()).optional(),
     additionalDirectories: z.array(z.string()).optional(),

packages/server/src/server/agent/providers/codex-app-server-agent.features.test.ts

@@ -1,7 +1,20 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import pino from "pino";
-import { describe, expect, test } from "vitest";
+import { describe, expect, test, vi } from "vitest";
 
-import type { AgentSession, AgentSessionConfig } from "../agent-sdk-types.js";
+import { AgentManager } from "../agent-manager.js";
+import { toAgentPayload } from "../agent-projections.js";
+import { AgentStorage } from "../agent-storage.js";
+import { featuresFromControls } from "@getpaseo/protocol/option-controls";
+import { convertLegacyOptions } from "../option-controls.js";
+import type {
+  AgentClient,
+  AgentSession,
+  AgentSessionConfig,
+  AgentStreamEvent,
+} from "../agent-sdk-types.js";
 import { CodexAppServerAgentSession } from "./codex-app-server-agent.js";
 import {
   createFakeCodexAppServer,
@@ -37,23 +50,32 @@ const TEST_SPEED_MODELS = [
   serviceTiers: [{ id: "priority", name: "Fast", description: "Faster processing" }],
 }));
 
-function speedFeature(value: string) {
+function speedControl() {
   return {
     type: "select",
-    id: "service_tier",
+    key: "service_tier",
     label: "Speed",
     description: "Choose processing speed. Faster tiers increase usage.",
     tooltip: "Select speed",
     icon: "zap",
     desktopTrigger: "icon",
-    value,
+    defaultValue: "default",
-    options: [
+    choices: [
-      { id: "default", label: "Normal", isDefault: true },
+      { value: "default", label: "Normal" },
-      { id: "priority", label: "Fast" },
+      { value: "priority", label: "Fast" },
     ],
   };
 }
 
+const PLAN_CONTROL = {
+  type: "toggle",
+  key: "plan_mode",
+  label: "Plan",
+  description: "Switch Codex into planning-only collaboration mode",
+  tooltip: "Toggle plan mode",
+  icon: "list-todo",
+};
+
 const TEST_COLLABORATION_MODES: CollaborationModeRecord[] = [
   {
     name: "Code",
@@ -132,7 +154,7 @@ async function createConnectedSession(
   return harness;
 }
 
-describe("Codex app-server provider features", () => {
+describe("Codex app-server provider controls", () => {
   test("GPT-6.1 Sol offers catalog speed tiers and sends Ultrafast", async () => {
     const { session, appServer } = await createConnectedSession(
       { model: "gpt-6.1-sol" },
@@ -149,19 +171,19 @@ describe("Codex app-server provider features", () => {
       },
     );
     try {
-      expect(session.features).toContainEqual(
+      expect(session.controls).toContainEqual(
         expect.objectContaining({
-          id: "service_tier",
+          key: "service_tier",
           type: "select",
-          value: "default",
+          defaultValue: "default",
-          options: [
+          choices: [
-            { id: "default", label: "Normal", isDefault: true },
+            { value: "default", label: "Normal" },
-            { id: "priority", label: "Fast" },
+            { value: "priority", label: "Fast" },
-            { id: "ultrafast", label: "Ultrafast" },
+            { value: "ultrafast", label: "Ultrafast" },
           ],
         }),
       );
-      await session.setFeature?.("service_tier", "ultrafast");
+      await session.applyOptions?.({ service_tier: "ultrafast" });
       await session.startTurn("hello");
       await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
         serviceTier: "ultrafast",
@@ -186,16 +208,16 @@ describe("Codex app-server provider features", () => {
       },
     );
     try {
-      expect(session.features).toContainEqual(
+      expect(session.controls).toContainEqual(
         expect.objectContaining({
-          id: "service_tier",
+          key: "service_tier",
-          options: [
+          choices: [
-            { id: "default", label: "Normal", isDefault: true },
+            { value: "default", label: "Normal" },
-            { id: "future-tier", label: "Future speed" },
+            { value: "future-tier", label: "Future speed" },
           ],
         }),
       );
-      await session.setFeature?.("service_tier", "future-tier");
+      await session.applyOptions?.({ service_tier: "future-tier" });
       await session.startTurn("hello");
       await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
         model: "future-codex-model",
@@ -210,7 +232,7 @@ describe("Codex app-server provider features", () => {
     "restores %s and Normal explicitly overrides an existing thread tier",
     async (tier) => {
       const { session, appServer } = await createConnectedSession(
-        { model: "future-model", featureValues: { service_tier: tier } },
+        { model: "future-model", providerOptions: { service_tier: tier } },
         {
           models: [
             {
@@ -224,11 +246,8 @@ describe("Codex app-server provider features", () => {
         },
       );
       try {
-        expect(session.features).toContainEqual(
-          expect.objectContaining({ id: "service_tier", value: tier }),
-        );
         await session.getRuntimeInfo();
-        await session.setFeature?.("service_tier", "default");
+        await session.applyOptions?.({ service_tier: "default" });
         await session.startTurn("hello");
         await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
           serviceTier: "default",
@@ -239,17 +258,40 @@ describe("Codex app-server provider features", () => {
     },
   );
 
-  test("rejects unadvertised tiers and non-string values", async () => {
+  test.each(["priority", "ultrafast"])("restores %s from providerOptions", async (tier) => {
-    const { session } = await createConnectedSession();
+    const { session, appServer } = await createConnectedSession(
+      { model: "future-model", providerOptions: { service_tier: tier } },
+      {
+        models: [
+          {
+            id: "future-model",
+            serviceTiers: [
+              { id: "priority", name: "Fast", description: "Fast processing" },
+              { id: "ultrafast", name: "Ultrafast", description: "Ultra processing" },
+            ],
+          },
+        ],
+      },
+    );
     try {
-      for (const value of ["ultrafast", "bogus", true, null]) {
+      await session.startTurn("hello");
-        await expect(session.setFeature?.("service_tier", value)).rejects.toThrow(
+      await expect(appServer.waitForTurnStart()).resolves.toMatchObject({ serviceTier: tier });
+    } finally {
+      await session.close();
+    }
+  });
+
+  test("rejects unadvertised tiers and non-string values", async () => {
+    const { session, appServer } = await createConnectedSession();
+    try {
+      for (const value of ["ultrafast", "bogus"]) {
+        await expect(session.applyOptions?.({ service_tier: value })).rejects.toThrow(
           "is not available",
         );
       }
-      expect(session.features).toContainEqual(
+      await expect(session.applyOptions?.({ service_tier: true })).rejects.toThrow();
-        expect.objectContaining({ id: "service_tier", value: "default" }),
+      await session.startTurn("hello");
-      );
+      await expect(appServer.waitForTurnStart()).resolves.toMatchObject({ serviceTier: "default" });
     } finally {
       await session.close();
     }
@@ -257,7 +299,7 @@ describe("Codex app-server provider features", () => {
 
   test("switching to a model without the selected tier resets speed", async () => {
     const { session, appServer } = await createConnectedSession(
-      { model: "ultra-model", featureValues: { service_tier: "ultrafast" } },
+      { model: "ultra-model", providerOptions: { service_tier: "ultrafast" } },
       {
         models: [
           {
@@ -270,8 +312,14 @@ describe("Codex app-server provider features", () => {
     );
     try {
       await session.setModel("gpt-6.1-sol");
-      expect(session.features).toContainEqual(
+      expect(session.controls).toContainEqual(
-        expect.objectContaining({ id: "service_tier", value: "default" }),
+        expect.objectContaining({
+          key: "service_tier",
+          choices: [
+            { value: "default", label: "Normal" },
+            { value: "priority", label: "Fast" },
+          ],
+        }),
       );
       await session.startTurn("hello");
       await expect(appServer.waitForTurnStart()).resolves.toMatchObject({ serviceTier: "default" });
@@ -280,10 +328,47 @@ describe("Codex app-server provider features", () => {
     }
   });
 
-  test("maps legacy Fast commands to the catalog's request id", async () => {
+  test("a Fast chosen as `fast` is kept as the catalog's id, so a model with a different Fast id resets it", async () => {
+    const { session, appServer } = await createConnectedSession(
+      { model: "model-a" },
+      {
+        models: [
+          {
+            id: "model-a",
+            isDefault: true,
+            serviceTiers: [{ id: "priority", name: "Fast", description: "Faster" }],
+          },
+          {
+            id: "model-b",
+            serviceTiers: [{ id: "rapid", name: "Fast", description: "Faster" }],
+          },
+        ],
+      },
+    );
+    const events: AgentStreamEvent[] = [];
+    session.subscribe((event) => events.push(event));
+    try {
+      await expect(session.applyOptions?.({ service_tier: "fast" })).resolves.toEqual({
+        service_tier: "priority",
+      });
+
+      await session.setModel("model-b");
+
+      // The option the session reports and the tier the turn runs are the same speed.
+      expect(events.filter((event) => event.type === "options_changed")).toEqual([
+        expect.objectContaining({ patch: { service_tier: "default" } }),
+      ]);
+      await session.startTurn("hello");
+      await expect(appServer.waitForTurnStart()).resolves.toMatchObject({ serviceTier: "default" });
+    } finally {
+      await session.close();
+    }
+  });
+
+  test("`fast` maps to the catalog's request id", async () => {
     const { session, appServer } = await createConnectedSession();
     try {
-      await session.setFeature?.("fast_mode", true);
+      await session.applyOptions?.({ service_tier: "fast" });
       await session.startTurn("hello");
       await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
         serviceTier: "priority",
@@ -307,13 +392,13 @@ describe("Codex app-server provider features", () => {
   ])("exposes and sends Fast for %s", async (model) => {
     const { session, appServer } = await createConnectedSession({ model });
     try {
-      expect(session.features).toContainEqual(
+      expect(session.controls).toContainEqual(
         expect.objectContaining({
-          id: "service_tier",
+          key: "service_tier",
-          value: "default",
+          defaultValue: "default",
         }),
       );
-      await session.setFeature?.("service_tier", "priority");
+      await session.applyOptions?.({ service_tier: "priority" });
       await session.startTurn("hello");
       await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
         model,
@@ -338,12 +423,13 @@ describe("Codex app-server provider features", () => {
   ])("does not expose or restore Fast for %s", async (model) => {
     const { session, appServer } = await createConnectedSession({
       model,
-      featureValues: { fast_mode: true },
+      providerOptions: { service_tier: "fast" },
     });
+    const fresh = await createConnectedSession({ model });
     try {
-      expect(session.features.map((feature) => feature.id)).toEqual(["plan_mode"]);
+      expect(session.controls.map((control) => control.key)).toEqual(["plan_mode"]);
-      await expect(session.setFeature?.("fast_mode", true)).rejects.toThrow(
+      await expect(fresh.session.applyOptions?.({ service_tier: "fast" })).rejects.toThrow(
-        `Codex fast mode is not available for model '${model}'`,
+        `Codex speed 'fast' is not available for model '${model}'`,
       );
       await session.startTurn("hello");
       await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
@@ -351,21 +437,16 @@ describe("Codex app-server provider features", () => {
       });
     } finally {
       await session.close();
+      await fresh.session.close();
     }
   });
 
   test("restores Fast on Astra and preserves it when switching supported models", async () => {
     const { session, appServer } = await createConnectedSession({
       model: "gpt-6-astra",
-      featureValues: { fast_mode: true },
+      providerOptions: { service_tier: "fast" },
     });
     try {
-      expect(session.features).toContainEqual(
-        expect.objectContaining({
-          id: "service_tier",
-          value: "priority",
-        }),
-      );
       await session.setModel("gpt-5.6-sol");
       await session.setModel("gpt-6-astra");
       await session.startTurn("hello");
@@ -378,72 +459,33 @@ describe("Codex app-server provider features", () => {
     }
   });
 
-  test("features returns speed selector and plan toggle when supported", async () => {
+  test("controls return the speed selector and plan toggle when supported", async () => {
-    const { session } = await createConnectedSession();
+    const { session, appServer } = await createConnectedSession();
 
-    expect(session.features).toEqual([
+    expect(session.controls).toEqual([speedControl(), PLAN_CONTROL]);
-      speedFeature("default"),
-      {
-        type: "toggle",
-        id: "plan_mode",
-        label: "Plan",
-        description: "Switch Codex into planning-only collaboration mode",
-        tooltip: "Toggle plan mode",
-        icon: "list-todo",
-        value: false,
-      },
-    ]);
 
-    await session.setFeature?.("service_tier", "priority");
+    await session.applyOptions?.({ service_tier: "priority", plan_mode: true });
-    await session.setFeature?.("plan_mode", true);
+    await session.startTurn("hello");
 
-    expect(session.features).toEqual([
+    await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
-      speedFeature("priority"),
+      serviceTier: "priority",
-      {
+      collaborationMode: expect.objectContaining({ mode: "plan" }),
-        type: "toggle",
+    });
-        id: "plan_mode",
-        label: "Plan",
-        description: "Switch Codex into planning-only collaboration mode",
-        tooltip: "Toggle plan mode",
-        icon: "list-todo",
-        value: true,
-      },
-    ]);
   });
 
-  test("features returns only plan toggle when model does not support fast mode", async () => {
+  test("controls return only the plan toggle when model does not support fast mode", async () => {
     const { session } = await createConnectedSession({ model: "gpt-3.5-turbo" });
 
-    expect(session.features).toEqual([
+    expect(session.controls).toEqual([PLAN_CONTROL]);
-      {
-        type: "toggle",
-        id: "plan_mode",
-        label: "Plan",
-        description: "Switch Codex into planning-only collaboration mode",
-        tooltip: "Toggle plan mode",
-        icon: "list-todo",
-        value: false,
-      },
-    ]);
   });
 
   test("constructor ignores restored fast mode when model does not support it", async () => {
     const { session, appServer } = await createConnectedSession({
       model: "gpt-3.5-turbo",
-      featureValues: { fast_mode: true },
+      providerOptions: { service_tier: "fast" },
     });
 
-    expect(session.features).toEqual([
+    expect(session.controls).toEqual([PLAN_CONTROL]);
-      {
-        type: "toggle",
-        id: "plan_mode",
-        label: "Plan",
-        description: "Switch Codex into planning-only collaboration mode",
-        tooltip: "Toggle plan mode",
-        icon: "list-todo",
-        value: false,
-      },
-    ]);
 
     await session.startTurn("hello");
     await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
@@ -454,7 +496,7 @@ describe("Codex app-server provider features", () => {
   test("selecting Fast sends the catalog service tier", async () => {
     const { session, appServer } = await createConnectedSession();
 
-    await session.setFeature?.("service_tier", "priority");
+    await session.applyOptions?.({ service_tier: "priority" });
     await session.startTurn("hello");
 
     await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
@@ -462,12 +504,12 @@ describe("Codex app-server provider features", () => {
     });
   });
 
-  test("legacy Fast off explicitly selects Normal", async () => {
+  test("selecting Normal after Fast explicitly selects Normal", async () => {
     const { session, appServer } = await createConnectedSession({
-      featureValues: { fast_mode: true },
+      providerOptions: { service_tier: "fast" },
     });
 
-    await session.setFeature?.("fast_mode", false);
+    await session.applyOptions?.({ service_tier: "default" });
     await session.startTurn("hello");
 
     await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
@@ -475,53 +517,39 @@ describe("Codex app-server provider features", () => {
     });
   });
 
-  test("setFeature('fast_mode', true) rejects models that do not support fast mode", async () => {
+  test('applyOptions({ service_tier: "fast" }) rejects models that do not support fast mode', async () => {
     const { session } = await createConnectedSession({ model: "gpt-3.5-turbo" });
 
-    await expect(session.setFeature?.("fast_mode", true)).rejects.toThrow(
+    await expect(session.applyOptions?.({ service_tier: "fast" })).rejects.toThrow(
-      "Codex fast mode is not available for model 'gpt-3.5-turbo'",
+      "Codex speed 'fast' is not available for model 'gpt-3.5-turbo'",
     );
   });
 
-  test("setFeature invalidates runtime info", async () => {
+  test("applyOptions invalidates runtime info", async () => {
     const { session } = await createConnectedSession();
 
     await expect(session.getRuntimeInfo()).resolves.not.toMatchObject({
       extra: { collaborationMode: "Plan" },
     });
 
-    await session.setFeature?.("plan_mode", true);
+    await session.applyOptions?.({ plan_mode: true });
 
     await expect(session.getRuntimeInfo()).resolves.toMatchObject({
       extra: { collaborationMode: "Plan" },
     });
   });
 
-  test("setFeature throws for unknown feature ids", async () => {
+  test("constructor restores composer options from config.providerOptions", async () => {
-    const { session } = createSessionHarness();
-
-    await expect(session.setFeature?.("unknown_feature", true)).rejects.toThrow(
-      "Unknown Codex feature: unknown_feature",
-    );
-  });
-
-  test("constructor restores feature flags from config.featureValues", async () => {
     const { session, appServer } = await createConnectedSession({
-      featureValues: { fast_mode: true, plan_mode: true },
+      providerOptions: { service_tier: "fast", plan_mode: true },
     });
+    const events: AgentStreamEvent[] = [];
+    session.subscribe((event) => events.push(event));
 
-    expect(session.features).toEqual([
+    expect(session.controls).toEqual([speedControl(), PLAN_CONTROL]);
-      speedFeature("priority"),
+    // A saved `fast` opens as the model's Fast tier, which the open patch says.
-      {
+    expect(session.openOptionsPatch).toEqual({ service_tier: "priority" });
-        type: "toggle",
+    expect(events.filter((event) => event.type === "options_changed")).toEqual([]);
-        id: "plan_mode",
-        label: "Plan",
-        description: "Switch Codex into planning-only collaboration mode",
-        tooltip: "Toggle plan mode",
-        icon: "list-todo",
-        value: true,
-      },
-    ]);
 
     await session.startTurn("hello");
     await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
@@ -532,10 +560,36 @@ describe("Codex app-server provider features", () => {
     });
   });
 
+  test("a patch that sets another option keeps the running sandbox and an explicit speed", async () => {
+    const { session, appServer } = await createConnectedSession({
+      providerOptions: { sandbox_mode: "read-only", service_tier: "default" },
+    });
+
+    await session.applyOptions?.({ plan_mode: true });
+    await session.startTurn("hello");
+
+    await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
+      serviceTier: "default",
+      sandboxPolicy: expect.objectContaining({ type: "readOnly" }),
+    });
+  });
+
+  test("rejects a live change to the approval policy or sandbox, which the thread fixed when it started", async () => {
+    const { session } = await createConnectedSession({
+      providerOptions: { sandbox_mode: "workspace-write" },
+    });
+
+    await expect(session.applyOptions?.({ sandbox_mode: "read-only" })).rejects.toThrow(
+      /sandbox_mode.*cannot change on a running session/,
+    );
+    // The same value is not a change.
+    await expect(session.applyOptions?.({ sandbox_mode: "workspace-write" })).resolves.toEqual({});
+  });
+
   test("startTurn includes serviceTier when fast mode is enabled", async () => {
     const { session, appServer } = await createConnectedSession();
 
-    await session.setFeature?.("service_tier", "priority");
+    await session.applyOptions?.({ service_tier: "priority" });
     await session.startTurn("hello");
 
     await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
@@ -543,11 +597,351 @@ describe("Codex app-server provider features", () => {
     });
   });
 
+  test("opening on a model without the saved tier runs Normal and the open patch says so", async () => {
+    const models = [
+      { id: "plain", isDefault: true, defaultReasoningEffort: "medium", serviceTiers: [] },
+    ];
+    const { session, appServer } = await createConnectedSession(
+      { model: "plain", providerOptions: { service_tier: "priority" } },
+      { models },
+    );
+
+    expect(session.openOptionsPatch).toEqual({ service_tier: "default" });
+
+    await session.startTurn("hello");
+    await expect(appServer.waitForTurnStart()).resolves.toMatchObject({ serviceTier: "default" });
+  });
+
+  test("a saved service_tier: fast runs as the model's Fast tier and the open patch names that tier", async () => {
+    const { session, appServer } = await createConnectedSession({
+      providerOptions: { service_tier: "fast" },
+    });
+
+    expect(session.openOptionsPatch).toEqual({ service_tier: "priority" });
+
+    await session.startTurn("hello");
+    await expect(appServer.waitForTurnStart()).resolves.toMatchObject({ serviceTier: "priority" });
+  });
+
+  test("a live service_tier: fast is returned as the model's Fast tier", async () => {
+    const { session, appServer } = await createConnectedSession();
+
+    await expect(session.applyOptions?.({ service_tier: "fast" })).resolves.toEqual({
+      service_tier: "priority",
+    });
+
+    await session.startTurn("hello");
+    await expect(appServer.waitForTurnStart()).resolves.toMatchObject({ serviceTier: "priority" });
+  });
+
+  test("switching to a model without the speed tier says Normal and keeps it so on the way back", async () => {
+    const models = [
+      ...TEST_SPEED_MODELS,
+      { id: "plain", isDefault: false, defaultReasoningEffort: "medium", serviceTiers: [] },
+    ];
+    const { session, appServer } = await createConnectedSession(
+      { model: "gpt-5.4", providerOptions: { service_tier: "priority" } },
+      { models },
+    );
+    const events: AgentStreamEvent[] = [];
+    session.subscribe((event) => events.push(event));
+
+    await session.setModel?.("plain");
+    await session.setModel?.("gpt-5.4");
+
+    expect(events.filter((event) => event.type === "options_changed")).toEqual([
+      { type: "options_changed", provider: "codex", patch: { service_tier: "default" } },
+    ]);
+    await session.startTurn("hello");
+    await expect(appServer.waitForTurnStart()).resolves.toMatchObject({ serviceTier: "default" });
+  });
+
+  describe("legacy Fast (fast_mode) saved or requested before service_tier", () => {
+    function createLegacyFastHarness(
+      rawDefaults: Record<string, unknown> = {},
+      providerId = CODEX_PROVIDER,
+    ) {
+      // The provider registry converts configured defaults before it merges them.
+      const configDefaults = convertLegacyOptions({
+        provider: CODEX_PROVIDER,
+        options: rawDefaults,
+      });
+      const appServer = createFakeCodexAppServer({
+        "collaborationMode/list": () => ({ data: TEST_COLLABORATION_MODES }),
+        "model/list": () => ({ data: TEST_SPEED_MODELS }),
+      });
+      const logger = createTestLogger();
+      const openSession = async (
+        config: AgentSessionConfig,
+        resumeSessionId: string | null,
+      ): Promise<AgentSession> => {
+        const session = new CodexAppServerAgentSession(
+          // The provider registry hands sessions the `config.json` defaults merged into the agent's own options.
+          {
+            ...config,
+            provider: CODEX_PROVIDER,
+            providerOptions: { ...configDefaults, ...config.providerOptions },
+          },
+          resumeSessionId ? { sessionId: resumeSessionId } : null,
+          logger,
+          async () => appServer.child,
+        );
+        await session.connect();
+        return session;
+      };
+      const client: AgentClient = {
+        provider: providerId,
+        capabilities: {
+          supportsStreaming: true,
+          supportsSessionPersistence: true,
+          supportsDynamicModes: false,
+          supportsMcpServers: false,
+          supportsReasoningStream: false,
+          supportsToolInvocations: false,
+        },
+        isAvailable: async () => true,
+        fetchCatalog: async () => ({ models: [], modes: [] }),
+        // Stands in for the `config.json` provider defaults the registry wrapper merges in.
+        effectiveOptions: (own) => ({ ...configDefaults, ...own }),
+        createSession: (config) => openSession(config, null),
+        resumeSession: (handle, config) =>
+          openSession(
+            { ...config, provider: CODEX_PROVIDER } as AgentSessionConfig,
+            handle.sessionId,
+          ),
+      };
+      const workdir = mkdtempSync(join(tmpdir(), "codex-legacy-fast-"));
+      const storage = new AgentStorage(join(workdir, "agents"), logger);
+      const manager = new AgentManager({
+        clients: { [providerId]: client },
+        // A custom provider that extends Codex runs on the Codex adapter.
+        providerDefinitions:
+          providerId === CODEX_PROVIDER
+            ? {}
+            : { [providerId]: { enabled: true, derivedFromProviderId: CODEX_PROVIDER } },
+        registry: storage,
+        logger,
+      });
+      const turnStarts = () =>
+        appServer
+          .requests()
+          .filter((message) => message.method === "turn/start")
+          .map((message) => message.params);
+
+      async function create(providerOptions?: Record<string, unknown>) {
+        const agent = await manager.createAgent(
+          {
+            provider: providerId,
+            cwd: workdir,
+            model: "gpt-5.4",
+            ...(providerOptions ? { providerOptions } : {}),
+          },
+          undefined,
+          { workspaceId: undefined },
+        );
+        return agent.id;
+      }
+      async function resume(providerOptions: Record<string, unknown>) {
+        const agent = await manager.resumeAgentFromPersistence({
+          provider: providerId,
+          sessionId: "thread-1",
+          metadata: { cwd: workdir, model: "gpt-5.4", providerOptions },
+        });
+        return agent.id;
+      }
+      function shownSpeed(agentId: string) {
+        const payload = toAgentPayload(manager.getAgent(agentId)!);
+        const control = payload.controls?.find((candidate) => candidate.key === "service_tier");
+        const choice =
+          control?.type === "select"
+            ? control.choices.find((candidate) => candidate.value === payload.options?.service_tier)
+            : undefined;
+        return {
+          options: payload.options,
+          own: manager.getAgent(agentId)?.config.providerOptions,
+          // What a client reading `options` + `controls` selects, and what the legacy `features` show.
+          selected:
+            payload.options?.service_tier === undefined && control?.type === "select"
+              ? control.defaultValue
+              : choice?.value,
+          feature: payload.features?.find((feature) => feature.id === "service_tier")?.value,
+        };
+      }
+      async function runTurn(agentId: string, expectedTier: string) {
+        const before = turnStarts().length;
+        await manager.getAgent(agentId)!.session!.startTurn("hello");
+        await vi.waitFor(() => expect(turnStarts()).toHaveLength(before + 1));
+        const turn = turnStarts()[before]!;
+        expect(turn).toMatchObject({ serviceTier: expectedTier });
+        appServer.completeTurn({ threadId: String(turn.threadId) });
+        await vi.waitFor(() => expect(manager.getAgent(agentId)?.lifecycle).toBe("idle"));
+      }
+      return { manager, create, resume, shownSpeed, runTurn };
+    }
+
+    const FAST = { selected: "priority", feature: "priority" };
+
+    test("a saved fast_mode opens as the model's Fast tier and is stored as that tier", async () => {
+      const { manager, create, shownSpeed, runTurn } = createLegacyFastHarness();
+      const agentId = await create({ fast_mode: true });
+      await manager.flush();
+
+      expect(shownSpeed(agentId)).toMatchObject({
+        options: { service_tier: "priority" },
+        own: { service_tier: "priority" },
+        ...FAST,
+      });
+      await runTurn(agentId, "priority");
+    });
+
+    test("is shown as Fast after a stored record is resumed", async () => {
+      const { manager, resume, shownSpeed, runTurn } = createLegacyFastHarness();
+      const agentId = await resume({ fast_mode: true });
+      await manager.flush();
+
+      expect(shownSpeed(agentId)).toMatchObject({ own: { service_tier: "priority" }, ...FAST });
+      await runTurn(agentId, "priority");
+    });
+
+    test("from config.json defaults runs Fast and is shown as Fast", async () => {
+      const { create, shownSpeed, runTurn } = createLegacyFastHarness({ fast_mode: true });
+      const agentId = await create();
+
+      expect(shownSpeed(agentId)).toMatchObject(FAST);
+      await runTurn(agentId, "priority");
+    });
+
+    test("a saved fast_mode beats a configured service_tier default", async () => {
+      const { manager, resume, shownSpeed, runTurn } = createLegacyFastHarness({
+        service_tier: "default",
+      });
+      const agentId = await resume({ fast_mode: true });
+      await manager.flush();
+
+      expect(shownSpeed(agentId)).toMatchObject({ own: { service_tier: "priority" }, ...FAST });
+      await runTurn(agentId, "priority");
+    });
+
+    test("a provider extending Codex opens a saved fast_mode as Fast", async () => {
+      const { manager, resume, shownSpeed, runTurn } = createLegacyFastHarness({}, "my-codex");
+      const agentId = await resume({ fast_mode: true });
+      await manager.flush();
+
+      expect(shownSpeed(agentId)).toMatchObject({ own: { service_tier: "priority" }, ...FAST });
+      await runTurn(agentId, "priority");
+    });
+
+    test("a provider extending Codex creates with a requested fast_mode and applies a later one", async () => {
+      const { manager, create, shownSpeed, runTurn } = createLegacyFastHarness({}, "my-codex");
+      const agentId = await create({ fast_mode: false });
+      expect(shownSpeed(agentId)).toMatchObject({ own: { service_tier: "default" } });
+
+      await manager.setAgentOptions(agentId, { fast_mode: true });
+
+      expect(shownSpeed(agentId)).toMatchObject({ own: { service_tier: "priority" }, ...FAST });
+      await runTurn(agentId, "priority");
+    });
+
+    test("an older client's fast_mode runs Fast at once, and a later service_tier replaces it", async () => {
+      const { manager, create, shownSpeed, runTurn } = createLegacyFastHarness();
+      const agentId = await create();
+      expect(shownSpeed(agentId).selected).toBe("default");
+
+      await manager.setAgentOptions(agentId, { fast_mode: true });
+      expect(shownSpeed(agentId)).toMatchObject({ own: { service_tier: "priority" }, ...FAST });
+      await runTurn(agentId, "priority");
+
+      await manager.setAgentOptions(agentId, { service_tier: "default" });
+      expect(shownSpeed(agentId)).toMatchObject({
+        own: { service_tier: "default" },
+        selected: "default",
+        feature: "default",
+      });
+      await runTurn(agentId, "default");
+
+      await manager.setAgentOptions(agentId, { service_tier: "priority" });
+      expect(shownSpeed(agentId)).toMatchObject({ selected: "priority" });
+      await runTurn(agentId, "priority");
+    });
+
+    test("a request carrying both speed keys follows service_tier", async () => {
+      const { manager, create, shownSpeed, runTurn } = createLegacyFastHarness();
+      const agentId = await create({ service_tier: "priority" });
+
+      await manager.setAgentOptions(agentId, { service_tier: "default", fast_mode: true });
+
+      expect(shownSpeed(agentId)).toMatchObject({ own: { service_tier: "default" } });
+      await runTurn(agentId, "default");
+    });
+
+    test.each([
+      [CODEX_PROVIDER, "a requested legacy fast_mode", {}, { fast_mode: true }],
+      ["my-codex", "a requested legacy fast_mode", {}, { fast_mode: true }],
+      [CODEX_PROVIDER, "a configured legacy fast_mode", { fast_mode: true }, undefined],
+      [CODEX_PROVIDER, "a configured Fast alias", { service_tier: "fast" }, undefined],
+    ])(
+      "draft speed for %s with %s is the one the first turn runs with",
+      async (providerId, _name, configured, requested) => {
+        const drafting = createLegacyFastHarness(configured, providerId);
+
+        const draft = await drafting.manager.listDraftControls({
+          provider: providerId,
+          cwd: tmpdir(),
+          model: "gpt-5.4",
+          ...(requested ? { providerOptions: requested } : {}),
+        });
+        const features = featuresFromControls({ controls: draft.controls, options: draft.options });
+
+        expect(draft.options).toEqual({ service_tier: "priority" });
+        expect(draft.controls).toContainEqual(expect.objectContaining({ key: "service_tier" }));
+        expect(features).toContainEqual(
+          expect.objectContaining({ id: "service_tier", value: "priority" }),
+        );
+        // A draft session ends with its app-server; creating runs on a fresh one.
+        const creating = createLegacyFastHarness(configured, providerId);
+        const agentId = await creating.create(requested);
+        await creating.runTurn(agentId, "priority");
+      },
+    );
+
+    test.each([
+      ["a string", "false"],
+      ["a number", 1],
+    ])("a legacy fast_mode that is %s is rejected, not read as Fast", async (_name, value) => {
+      const { manager, create } = createLegacyFastHarness();
+      const agentId = await create({});
+
+      await expect(manager.setAgentOptions(agentId, { fast_mode: value })).rejects.toThrow(
+        /fast_mode must be true, false or null/,
+      );
+    });
+
+    test("an older client turning fast_mode off selects Normal", async () => {
+      const { manager, create, shownSpeed, runTurn } = createLegacyFastHarness();
+      const agentId = await create({ service_tier: "priority" });
+
+      await manager.setAgentOptions(agentId, { fast_mode: false });
+
+      expect(shownSpeed(agentId)).toMatchObject({ own: { service_tier: "default" } });
+      await runTurn(agentId, "default");
+    });
+
+    test("removing the speed returns the agent to Normal", async () => {
+      const { create, manager, shownSpeed } = createLegacyFastHarness();
+      const agentId = await create({ service_tier: "priority" });
+      expect(shownSpeed(agentId)).toMatchObject(FAST);
+
+      await manager.setAgentOptions(agentId, { service_tier: null });
+
+      expect(shownSpeed(agentId)).toMatchObject({ own: undefined, selected: "default" });
+    });
+  });
+
   test("startTurn logs a sanitized turn/start summary for fast mode observability", async () => {
     const capture = createCapturedLogger();
     const prompt = "secret prompt text should not be logged";
     const { session } = await createConnectedSession(
-      { featureValues: { fast_mode: true } },
+      { providerOptions: { service_tier: "fast" } },
       { logger: capture.logger },
     );
 
@@ -570,20 +964,10 @@ describe("Codex app-server provider features", () => {
   test("setModel clears fast mode when switching to an unsupported model", async () => {
     const { session, appServer } = await createConnectedSession();
 
-    await session.setFeature?.("service_tier", "priority");
+    await session.applyOptions?.({ service_tier: "priority" });
     await session.setModel("gpt-3.5-turbo");
 
-    expect(session.features).toEqual([
+    expect(session.controls).toEqual([PLAN_CONTROL]);
-      {
-        type: "toggle",
-        id: "plan_mode",
-        label: "Plan",
-        description: "Switch Codex into planning-only collaboration mode",
-        tooltip: "Toggle plan mode",
-        icon: "list-todo",
-        value: false,
-      },
-    ]);
     await session.startTurn("hello");
 
     await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
@@ -594,7 +978,7 @@ describe("Codex app-server provider features", () => {
   test("startTurn switches collaboration mode when plan mode is enabled", async () => {
     const { session, appServer } = await createConnectedSession();
 
-    await session.setFeature?.("plan_mode", true);
+    await session.applyOptions?.({ plan_mode: true });
     await session.startTurn("hello");
 
     await expect(appServer.waitForTurnStart()).resolves.toMatchObject({

packages/server/src/server/agent/providers/codex-app-server-agent.process-exit.test.ts

@@ -38,7 +38,7 @@ async function withPendingPlan(
     cwd: workdir,
     modeId: "auto",
     model: "gpt-5.4",
-    featureValues: { plan_mode: true },
+    providerOptions: { plan_mode: true },
   });
   const events: AgentStreamEvent[] = [];
   session.subscribe((event) => events.push(event));
@@ -526,7 +526,7 @@ test("idle provider exit preserves a synthetic plan approval across reconnect",
         cwd: workdir,
         modeId: "auto",
         model: "gpt-5.4",
-        featureValues: { plan_mode: true },
+        providerOptions: { plan_mode: true },
       },
       undefined,
       { workspaceId: undefined },

packages/server/src/server/agent/providers/codex-app-server-agent.test.ts

@@ -6188,7 +6188,7 @@ describe("Codex app-server provider", () => {
 
   test("emits a synthetic plan approval permission after a successful Codex plan turn", async () => {
     const session = createSession({
-      featureValues: { plan_mode: true, fast_mode: true },
+      providerOptions: { plan_mode: true, service_tier: "fast" },
     });
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
@@ -6258,7 +6258,7 @@ describe("Codex app-server provider", () => {
 
   test("does not complete Codex plan timeline cards while plan approval is pending", async () => {
     const session = createSession({
-      featureValues: { plan_mode: true, fast_mode: true },
+      providerOptions: { plan_mode: true, service_tier: "fast" },
     });
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
@@ -6304,7 +6304,7 @@ describe("Codex app-server provider", () => {
 
   test("replaces a pending synthetic plan approval when a later plan completes", async () => {
     const session = createSession({
-      featureValues: { plan_mode: true },
+      providerOptions: { plan_mode: true },
     });
 
     await asInternals(session).handleNotification("turn/started", {
@@ -6337,7 +6337,7 @@ describe("Codex app-server provider", () => {
 
   test("dismisses a pending synthetic plan approval after a new prompt is accepted", async () => {
     const session = createSession({
-      featureValues: { plan_mode: true },
+      providerOptions: { plan_mode: true },
     });
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
@@ -6379,7 +6379,7 @@ describe("Codex app-server provider", () => {
 
   test("makes the old plan non-actionable while a new prompt is being prepared", async () => {
     const session = createSession({
-      featureValues: { plan_mode: true },
+      providerOptions: { plan_mode: true },
     });
 
     await asInternals(session).handleNotification("turn/started", {
@@ -6433,7 +6433,7 @@ describe("Codex app-server provider", () => {
 
   test("does not dismiss a new plan approval emitted while a prompt is being accepted", async () => {
     const session = createSession({
-      featureValues: { plan_mode: true },
+      providerOptions: { plan_mode: true },
     });
 
     await asInternals(session).handleNotification("turn/started", {
@@ -6483,7 +6483,7 @@ describe("Codex app-server provider", () => {
 
   test("keeps a synthetic plan dismissed when a new prompt is rejected", async () => {
     const session = createSession({
-      featureValues: { plan_mode: true },
+      providerOptions: { plan_mode: true },
     });
 
     await asInternals(session).handleNotification("turn/started", {
@@ -7107,7 +7107,7 @@ describe("Codex app-server provider", () => {
 
   test("approving a synthetic Codex plan permission disables plan mode, preserves fast mode, and returns follow-up prompt", async () => {
     const session = createSession({
-      featureValues: { plan_mode: true, fast_mode: true },
+      providerOptions: { plan_mode: true, service_tier: "fast" },
     });
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
@@ -7138,9 +7138,10 @@ describe("Codex app-server provider", () => {
 
     expect(asInternals(session).serviceTier).toBe("fast");
     expect(asInternals(session).planModeEnabled).toBe(false);
-    expect(asInternals(session).config.featureValues).toEqual({
+    expect(events).toContainEqual({
-      plan_mode: false,
+      type: "options_changed",
-      fast_mode: true,
+      provider: "codex",
+      patch: { plan_mode: false },
     });
     // The session returns the follow-up prompt instead of calling startTurn directly.
     // The caller (session/agent-manager) is responsible for sending it through streamAgent.
@@ -7161,7 +7162,7 @@ describe("Codex app-server provider", () => {
 
   test("approving a synthetic Codex plan permission keeps fast mode disabled when it started disabled", async () => {
     const session = createSession({
-      featureValues: { plan_mode: true, fast_mode: false },
+      providerOptions: { plan_mode: true, service_tier: "default" },
     });
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
@@ -7190,11 +7191,12 @@ describe("Codex app-server provider", () => {
       selectedActionId: "implement",
     });
 
-    expect(asInternals(session).serviceTier).toBeNull();
+    expect(asInternals(session).serviceTier).toBe("default");
     expect(asInternals(session).planModeEnabled).toBe(false);
-    expect(asInternals(session).config.featureValues).toEqual({
+    expect(events).toContainEqual({
-      plan_mode: false,
+      type: "options_changed",
-      fast_mode: false,
+      provider: "codex",
+      patch: { plan_mode: false },
     });
     expect(result?.followUpPrompt).toEqual(
       expect.stringContaining("The user approved the plan. Implement it now."),
@@ -7203,7 +7205,7 @@ describe("Codex app-server provider", () => {
 
   test("follow-up implementation turn keeps fast service tier and switches back to code collaboration mode", async () => {
     const session = createSession({
-      featureValues: { plan_mode: true, fast_mode: true },
+      providerOptions: { plan_mode: true, service_tier: "fast" },
     });
     asInternals(session).collaborationModes = [
       {

packages/server/src/server/agent/providers/codex-app-server-agent.ts

@@ -1,11 +1,13 @@
-import { validateProviderOptions } from "../provider-options.js";
+import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
+import { applyProviderOptionsPatch } from "../option-controls.js";
+import { assertChangesAreLive, validateProviderOptions } from "../provider-options.js";
 import {
   getAgentStreamEventTurnId,
   type AgentPermissionAction,
   type AgentCapabilityFlags,
   type AgentClient,
   type AgentCreateSessionOptions,
-  type AgentFeature,
+  type AgentOptionControl,
   type AgentLaunchContext,
   type AgentResumeSessionOptions,
   type AgentMode,
@@ -75,7 +77,7 @@ import { createPathEquivalenceMatcher } from "../../../utils/path.js";
 import { spawnProcess } from "../../../utils/spawn.js";
 import { extractCodexTerminalSessionId, nonEmptyString } from "./tool-call-mapper-utils.js";
 import {
-  buildCodexFeatures,
+  buildCodexControls,
   CodexServiceTierSchema,
   readCodexServiceTier,
   type CodexServiceTier,
@@ -3429,7 +3431,7 @@ export class CodexAppServerAgentSession implements AgentSession {
   private readonly codexHome: string;
   private currentMode: string;
   private hasWorkflowModeOverride: boolean;
-  private readonly providerOptions: CodexProviderOptions;
+  private providerOptions: CodexProviderOptions;
   private resolvedWorkspaceWrite: NonNullable<
     CodexProviderOptions["sandbox_workspace_write"]
   > | null = null;
@@ -3453,11 +3455,14 @@ export class CodexAppServerAgentSession implements AgentSession {
   private threadRollbackAvailable = true;
   private readonly subscribers = new Set<(event: AgentStreamEvent) => void>();
   private startupEvents: AgentStreamEvent[] | null = null;
+  /** How the opened session differs from the options it was given; reported at first subscribe. */
+  openOptionsPatch: Record<string, unknown> = {};
   private nextTurnOrdinal = 0;
   private activeForegroundTurnId: string | null = null;
   private activeClientMessageId: string | null = null;
   private cachedRuntimeInfo: AgentRuntimeInfo | null = null;
-  private serviceTier: string | null = null;
+  /** The tier the options ask for; `serviceTier` is what the current model can honor. */
+  private requestedServiceTier: string | null = null;
   private speedModels: CodexModel[] = [];
   private planModeEnabled = false;
   // History read by rewind or an archived resume, held until streamHistory consumes it.
@@ -3568,10 +3573,8 @@ export class CodexAppServerAgentSession implements AgentSession {
     this.asyncQuestions = new CodexAsyncQuestions(resumeHandle?.metadata?.asyncQuestions);
     this.codexHome = deps.codexHome ?? resolveCodexHomeDir(process.env);
     this.config.thinkingOptionId = normalizeCodexThinkingOptionId(this.config.thinkingOptionId);
-    this.serviceTier = readCodexServiceTier(this.config.featureValues);
+    this.requestedServiceTier = readCodexServiceTier(this.providerOptions);
-    if (this.config.featureValues?.plan_mode) {
+    this.planModeEnabled = this.providerOptions.plan_mode === true;
-      this.planModeEnabled = true;
-    }
 
     if (this.resumeHandle?.sessionId) {
       this.currentThreadId = this.resumeHandle.sessionId;
@@ -3586,11 +3589,9 @@ export class CodexAppServerAgentSession implements AgentSession {
     return this.currentThreadId;
   }
 
-  get features(): AgentFeature[] {
+  get controls(): AgentOptionControl[] {
-    return buildCodexFeatures({
+    return buildCodexControls({
       serviceTiers: this.currentServiceTiers(),
-      serviceTier: this.serviceTier ?? "default",
-      planModeEnabled: this.planModeEnabled,
       planModeAvailable: this.hasPlanCollaborationMode(),
     });
   }
@@ -3650,7 +3651,7 @@ export class CodexAppServerAgentSession implements AgentSession {
 
       this.speedModels =
         CodexModelListResponseSchema.parse(await client.request("model/list", {})).data ?? [];
-      this.reconcileServiceTier();
+      this.normalizeSpeed();
       await this.loadResolvedWorkspaceWrite();
       await this.loadCollaborationModes();
       await this.loadSkills();
@@ -3863,24 +3864,34 @@ export class CodexAppServerAgentSession implements AgentSession {
     return selectedModel?.serviceTiers ?? [];
   }
 
-  private reconcileServiceTier(): void {
+  /**
-    const tiers = this.currentServiceTiers();
+   * A saved `service_tier: "fast"` runs as the model's Fast tier, and a tier the opening model
-    // COMPAT(codexFastPreference): added in v0.10.0, remove after 2027-03-29 once saved Fast preferences have migrated.
+   * lacks runs as Normal; the session says so in `openOptionsPatch`, so the options and the
-    if (this.serviceTier === "fast" && !tiers.some((tier) => tier.id === "fast")) {
+   * control agree (as when the model is switched later).
-      this.serviceTier = tiers.find((tier) => tier.name.toLowerCase() === "fast")?.id ?? null;
+   */
-    }
+  private normalizeSpeed(): void {
-    if (this.serviceTier !== "default" && !tiers.some((tier) => tier.id === this.serviceTier)) {
+    const requested = this.requestedServiceTier;
-      this.serviceTier = null;
+    const resolved = this.resolveServiceTier(requested);
-    }
+    if (requested === resolved) return;
-    const { fast_mode: _legacyFast, ...values } = this.config.featureValues ?? {};
+    const runs = resolved ?? "default";
-    this.config.featureValues = { ...values, service_tier: this.serviceTier ?? "default" };
+    this.providerOptions = { ...this.providerOptions, service_tier: runs };
+    this.requestedServiceTier = runs;
+    this.openOptionsPatch = { service_tier: runs };
   }
 
-  private applyFeatureValue(featureId: "plan_mode", value: boolean): void {
+  private get serviceTier(): string | null {
-    this.config.featureValues = { ...this.config.featureValues, [featureId]: value };
+    return this.resolveServiceTier(this.requestedServiceTier);
-    this.planModeEnabled = value;
+  }
-    this.refreshResolvedCollaborationMode();
+
-    this.cachedRuntimeInfo = null;
+  private resolveServiceTier(requested: string | null): string | null {
+    // Until the model list arrives there is nothing to check the request against.
+    if (this.speedModels.length === 0 || requested === "default") return requested;
+    const tiers = this.currentServiceTiers();
+    // `fast` names whichever tier the model calls Fast.
+    if (requested === "fast" && !tiers.some((tier) => tier.id === "fast")) {
+      return tiers.find((tier) => tier.name.toLowerCase() === "fast")?.id ?? null;
+    }
+    return tiers.some((tier) => tier.id === requested) ? requested : null;
   }
 
   private rememberPlanResult(item: ToolCallTimelineItem): void {
@@ -3945,7 +3956,13 @@ export class CodexAppServerAgentSession implements AgentSession {
     const planText =
       typeof params.planText === "string" ? normalizePlanMarkdown(params.planText) : "";
 
-    this.applyFeatureValue("plan_mode", false);
+    this.setPlanMode(false);
+    // The user left plan mode; their options follow so controls and reopened sessions agree.
+    this.emitEvent({
+      type: "options_changed",
+      provider: CODEX_PROVIDER,
+      patch: { plan_mode: false },
+    });
 
     return buildCodexPlanImplementationPrompt(planText);
   }
@@ -4645,9 +4662,27 @@ export class CodexAppServerAgentSession implements AgentSession {
 
   async setModel(modelId: string | null): Promise<void> {
     this.config.model = modelId ?? undefined;
-    this.reconcileServiceTier();
     this.refreshResolvedCollaborationMode();
     this.cachedRuntimeInfo = null;
+    this.dropUnavailableServiceTier();
+  }
+
+  /**
+   * A speed the new model does not offer turns into Normal and is reported, so choosing a model
+   * that does offer it again does not bring the paid tier back. It is reported as Normal rather
+   * than removed so a configured default cannot fill the old speed back in.
+   */
+  private dropUnavailableServiceTier(): void {
+    const requested = this.requestedServiceTier;
+    if (requested === null || this.speedModels.length === 0) return;
+    if (this.isServiceTierAvailable(requested)) return;
+    this.requestedServiceTier = "default";
+    this.providerOptions = { ...this.providerOptions, service_tier: "default" };
+    this.emitEvent({
+      type: "options_changed",
+      provider: CODEX_PROVIDER,
+      patch: { service_tier: "default" },
+    });
   }
 
   async setThinkingOption(thinkingOptionId: string | null): Promise<void | AgentProviderNotice> {
@@ -4659,35 +4694,53 @@ export class CodexAppServerAgentSession implements AgentSession {
     }
   }
 
-  async setFeature(featureId: string, value: unknown): Promise<void> {
+  /** Applies only the options the patch sets; the rest of the running options stay as they are. */
-    // COMPAT(codexFastPreference): added in v0.10.0, remove after 2027-03-29 once clients use service_tier.
+  async applyOptions(options: ProviderOptions): Promise<Record<string, unknown>> {
-    if (featureId === "fast_mode") {
+    // The approval policy and sandbox are sent when the thread starts, not with each turn.
-      const fast = this.currentServiceTiers().find((tier) => tier.name.toLowerCase() === "fast");
+    assertChangesAreLive({
-      if (value && !fast)
+      provider: "codex",
+      patch: options,
+      current: this.providerOptions,
+      live: ["service_tier", "plan_mode"],
+    });
+    const valid =
+      validateProviderOptions(
+        "codex",
+        CodexProviderOptionsSchema,
+        applyProviderOptionsPatch({ options: this.providerOptions, patch: options }),
+      ) ?? {};
+    const requested = "service_tier" in options ? readCodexServiceTier(options) : null;
+    let accepted = this.requestedServiceTier;
+    if ("service_tier" in options) {
+      if (requested !== accepted && !this.isServiceTierAvailable(requested)) {
         throw new Error(
-          `Codex fast mode is not available for model '${this.config.model ?? "default"}'`,
+          `Codex speed '${String(requested)}' is not available for model '${this.config.model ?? "default"}'`,
-        );
-      return this.setFeature("service_tier", value ? fast!.id : "default");
-    }
-    if (featureId === "service_tier") {
-      if (
-        typeof value !== "string" ||
-        (value !== "default" && !this.currentServiceTiers().some((tier) => tier.id === value))
-      ) {
-        throw new Error(
-          `Codex speed '${String(value)}' is not available for model '${this.config.model ?? "default"}'`,
         );
       }
-      this.serviceTier = value;
+      // The session keeps the catalog's id for the tier, so a later model switch sees what runs.
-      this.reconcileServiceTier();
+      accepted = requested && (this.resolveServiceTier(requested) ?? requested);
-      this.cachedRuntimeInfo = null;
-      return;
     }
-    if (featureId === "plan_mode") {
+    this.providerOptions = { ...valid, ...(accepted ? { service_tier: accepted } : {}) };
-      this.applyFeatureValue("plan_mode", Boolean(value));
+    this.requestedServiceTier = accepted || null;
-      return;
+    if ("plan_mode" in options) this.setPlanMode(options.plan_mode === true);
-    }
+    this.cachedRuntimeInfo = null;
-    throw new Error(`Unknown Codex feature: ${featureId}`);
+    // The catalog may name the tier differently from the request (`fast` is the Fast tier's id).
+    const tier = this.serviceTier;
+    return tier !== null && requested !== null && tier !== requested ? { service_tier: tier } : {};
+  }
+
+  private isServiceTierAvailable(tier: string | null): boolean {
+    if (tier === null || tier === "default") return true;
+    const tiers = this.currentServiceTiers();
+    const namesFast = tier === "fast" && tiers.some((entry) => entry.name.toLowerCase() === "fast");
+    return namesFast || tiers.some((entry) => entry.id === tier);
+  }
+
+  private setPlanMode(enabled: boolean): void {
+    if (this.planModeEnabled === enabled) return;
+    this.planModeEnabled = enabled;
+    this.refreshResolvedCollaborationMode();
+    this.cachedRuntimeInfo = null;
   }
 
   getPendingPermissions(): AgentPermissionRequest[] {
@@ -5340,7 +5393,6 @@ export class CodexAppServerAgentSession implements AgentSession {
   private async applyDefaultModelAndThinking(): Promise<string> {
     const { model, thinkingOptionId } = await this.resolveModelAndThinking();
     this.config.model = model;
-    this.reconcileServiceTier();
     this.config.thinkingOptionId = thinkingOptionId;
     return model;
   }
@@ -5407,7 +5459,8 @@ export class CodexAppServerAgentSession implements AgentSession {
 
   private buildCodexInnerConfig(): Record<string, unknown> | null {
     const innerConfig: Record<string, unknown> = {};
-    Object.assign(innerConfig, this.providerOptions);
+    const { service_tier: _tier, plan_mode: _plan, ...codexConfig } = this.providerOptions;
+    Object.assign(innerConfig, codexConfig);
     if (this.deps.customCodexConfig) {
       Object.assign(innerConfig, this.deps.customCodexConfig);
     }

packages/server/src/server/agent/providers/codex-feature-definitions.ts

@@ -1,4 +1,4 @@
-import type { AgentFeature, AgentFeatureToggle } from "../agent-sdk-types.js";
+import type { AgentOptionControl, AgentOptionToggleControl } from "../agent-sdk-types.js";
 
 import { z } from "zod";
 
@@ -9,51 +9,47 @@ export const CodexServiceTierSchema = z.object({
 });
 export type CodexServiceTier = z.infer<typeof CodexServiceTierSchema>;
 
-function buildCodexSpeedFeature(tiers: CodexServiceTier[], value: string): AgentFeature[] {
+function buildCodexSpeedControl(tiers: CodexServiceTier[]): AgentOptionControl[] {
   if (tiers.length === 0) return [];
   return [
     {
       type: "select",
-      id: "service_tier",
+      key: "service_tier",
       label: "Speed",
       description: "Choose processing speed. Faster tiers increase usage.",
       tooltip: "Select speed",
       icon: "zap",
       desktopTrigger: "icon",
-      value,
+      defaultValue: "default",
-      options: [
+      choices: [
-        { id: "default", label: "Normal", isDefault: true },
+        { value: "default", label: "Normal" },
-        ...tiers.map((tier) => ({ id: tier.id, label: tier.name })),
+        ...tiers.map((tier) => ({ value: tier.id, label: tier.name })),
       ],
     },
   ];
 }
 
-export const CODEX_PLAN_MODE_FEATURE: Omit<AgentFeatureToggle, "value"> = {
+export const CODEX_PLAN_MODE_CONTROL: AgentOptionToggleControl = {
   type: "toggle",
-  id: "plan_mode",
+  key: "plan_mode",
   label: "Plan",
   description: "Switch Codex into planning-only collaboration mode",
   tooltip: "Toggle plan mode",
   icon: "list-todo",
 };
 
-export function buildCodexFeatures(input: {
+export function buildCodexControls(input: {
   serviceTiers: CodexServiceTier[];
-  serviceTier: string;
-  planModeEnabled: boolean;
   planModeAvailable?: boolean;
-}): AgentFeature[] {
+}): AgentOptionControl[] {
-  const features = buildCodexSpeedFeature(input.serviceTiers, input.serviceTier);
+  const controls = buildCodexSpeedControl(input.serviceTiers);
   if (input.planModeAvailable !== false) {
-    features.push({ ...CODEX_PLAN_MODE_FEATURE, value: input.planModeEnabled });
+    controls.push({ ...CODEX_PLAN_MODE_CONTROL });
   }
-  return features;
+  return controls;
 }
 
-export function readCodexServiceTier(values: Record<string, unknown> | undefined): string | null {
+export function readCodexServiceTier(options: Record<string, unknown> | undefined): string | null {
-  const tier = values?.service_tier;
+  const tier = options?.service_tier;
-  if (typeof tier === "string") return tier;
+  return typeof tier === "string" ? tier : null;
-  // COMPAT(codexFastPreference): added in v0.10.0, remove after 2027-03-29 once saved Fast preferences have migrated.
-  return values?.fast_mode ? "fast" : null;
 }

packages/server/src/server/agent/providers/codex/options.ts

@@ -37,6 +37,9 @@ const NetworkPolicySchema = z
 // Codex config reference, maintained against Codex CLI 0.143+.
 export const CodexProviderOptionsSchema = z
   .object({
+    // Composer controls, not Codex config: the provider reads them and keeps them out of `config`.
+    service_tier: z.string().optional(),
+    plan_mode: z.boolean().optional(),
     approval_policy: ApprovalPolicySchema.optional(),
     sandbox_mode: z.enum(["read-only", "workspace-write", "danger-full-access"]).optional(),
     sandbox_workspace_write: z