fix: preserve mappings under a managed model allowlist

Choosing one of `ExitPlanMode`'s "clear context" options restarts
Claude's conversation with only the plan. The ACP session ID and the
turn stay the same, and the adapter resets its context count to 0, but
it didn't tell the client. Clients kept showing the old context's usage
until the fresh context first reported its own, so nothing on the client
side showed that the context had been cleared.

`publishSessionState` now sends a `usage_update` for the empty fresh
context (`used: 0`, the fresh session's context window as `size`) right
after the `current_mode_update` and `config_option_update` it already
sends. `used: 0` slightly understates the fresh context, which already
holds the system prompt and the plan, until Claude's next usage report.

Testing:
- `npm run build`, `npm run test:run`, and `npm run check` pass.
- `clear-context-coordinator.test.ts` checks the update's order and
values.

src/acp-agent.ts

@@ -12218,15 +12218,15 @@ export class ClaudeAcpAgent {
         }
       }
 
-      // Apply user's `availableModels` allowlist from settings.json before any
+      // Apply the effective `availableModels` allowlist before any
       // downstream model handling. `initializationResult.models` is already
       // policy-filtered by the CLI; we rebuild the picker from the allowlist
       // so the user's exact spellings (and `modelOverrides` targets) are the
       // values passed to `setModel`, keeping configOptions, the current-model
       // resolver, and the stored modelInfos consistent with what the user
       // configured. Managed `deniedModels` drops entries the CLI would refuse.
-      const settingsAvailableModels = settingsManager.getSettings().availableModels;
-      const settingsModelOverrides = settingsManager.getSettings().modelOverrides;
+      const { availableModels: settingsAvailableModels, modelOverrides: settingsModelOverrides } =
+        settingsManager.getModelSelectionSettings(configuredSettingsObject);
       const settingsAllowedModels = Array.isArray(settingsAvailableModels)
         ? applyAvailableModelsAllowlist(
             initializationResult.models,

src/clear-context-coordinator.ts

@@ -45,6 +45,7 @@ export type ClearContextSession<Turn extends ClearContextTurn = ClearContextTurn
   turnQueue?: Turn[];
   pendingExitPlanContextReset?: ClearContextReset;
   contextUsedTokens?: number;
+  contextWindowSize: number;
   sentUserUuids?: Set<string>;
   input: { push(message: SDKUserMessage): unknown };
 };
@@ -61,10 +62,13 @@ export type ClearContextCoordinatorHost<
   ): Promise<Session>;
   applyFastMode(session: Session, enabled: boolean): Promise<void>;
   applyUltracode(session: Session, enabled: boolean): Promise<void>;
+  /** Publishes the fresh context's mode, config options, and usage: the
+   *  context starts empty in a window of `contextWindowSize` tokens. */
   publishSessionState(
     sessionId: string,
     mode: PermissionMode,
     configOptions: SessionConfigOption[],
+    contextWindowSize: number,
   ): Promise<void>;
   continuationMessage(sessionId: string, plan: string, promptUuid: string): SDKUserMessage;
   ensureConsumer(session: Session, sessionId: string): void;
@@ -165,7 +169,12 @@ export async function continuePlanInFreshContext<
   freshSession.contextUsedTokens = 0;
 
   try {
-    await host.publishSessionState(sessionId, reset.mode, freshSession.configOptions);
+    await host.publishSessionState(
+      sessionId,
+      reset.mode,
+      freshSession.configOptions,
+      freshSession.contextWindowSize,
+    );
   } catch (error) {
     host.logError("Failed to publish clear-context session state:", error);
   }

src/exit-plan.ts

@@ -213,7 +213,7 @@ export class ExitPlanCoordinator<
     try {
       const clearContextHost: ClearContextCoordinatorHost<Session, Turn> = {
         ...this.host,
-        publishSessionState: async (id, mode, configOptions) => {
+        publishSessionState: async (id, mode, configOptions, contextWindowSize) => {
           await this.host.sessionUpdate({
             sessionId: id,
             update: { sessionUpdate: "current_mode_update", currentModeId: mode },
@@ -222,6 +222,12 @@ export class ExitPlanCoordinator<
             sessionId: id,
             update: { sessionUpdate: "config_option_update", configOptions },
           });
+          // Otherwise the client shows the old context's usage until the fresh
+          // context first reports its own.
+          await this.host.sessionUpdate({
+            sessionId: id,
+            update: { sessionUpdate: "usage_update", used: 0, size: contextWindowSize },
+          });
           // The approved plan becomes the session's plan once the fresh
           // context that carries it out exists. Its ExitPlanMode ended with
           // an error result, so toAcpNotifications did not publish it.

src/settings.ts

@@ -50,6 +50,7 @@ export class SettingsManager {
   private cwd: string;
   private effective: Settings = {};
   private managedDeniedModels: string[] = [];
+  private managedModelSettings: Pick<Settings, "availableModels" | "modelOverrides"> = {};
   private managedApiKeyHelper?: string;
   private watchers: fs.FSWatcher[] = [];
   private onChange?: () => void;
@@ -112,6 +113,15 @@ export class SettingsManager {
       this.managedDeniedModels = resolved.sources
         .filter((entry) => entry.source === "managed")
         .flatMap((entry) => entry.settings.deniedModels ?? []);
+      this.managedModelSettings = Object.assign(
+        {},
+        ...resolved.sources
+          .filter((entry) => entry.source === "managed")
+          .map((entry) => ({
+            availableModels: entry.settings.availableModels,
+            modelOverrides: entry.settings.modelOverrides,
+          })),
+      );
       this.managedApiKeyHelper =
         resolved.provenance.apiKeyHelper?.source === "managed"
           ? resolved.effective.apiKeyHelper
@@ -120,6 +130,7 @@ export class SettingsManager {
       this.logger.error("Failed to resolve settings:", error);
       this.effective = {};
       this.managedDeniedModels = [];
+      this.managedModelSettings = {};
       this.managedApiKeyHelper = undefined;
     }
   }
@@ -193,6 +204,28 @@ export class SettingsManager {
     );
   }
 
+  /** Model selection settings including the inline SDK settings tier. */
+  getModelSelectionSettings(
+    override?: Settings,
+  ): Pick<Settings, "availableModels" | "modelOverrides"> {
+    // The SDK unions non-managed allowlists, but a managed list owns the
+    // whole allowlist. Keep that policy when adding
+    // models the SDK did not include in its initialization result.
+    const lists = [this.effective.availableModels, override?.availableModels].filter(
+      (list): list is string[] => Array.isArray(list),
+    );
+    const managed = this.managedModelSettings;
+    return {
+      availableModels:
+        managed.availableModels ?? (lists.length > 0 ? [...new Set(lists.flat())] : undefined),
+      modelOverrides: {
+        ...this.effective.modelOverrides,
+        ...override?.modelOverrides,
+        ...managed.modelOverrides,
+      },
+    };
+  }
+
   /**
    * `deniedModels` entries from the managed tier, the only tier the CLI
    * honors them from.

src/tests/acp-agent-settings.test.ts

@@ -800,6 +800,136 @@ describe("ClaudeAcpAgent settings", () => {
       return { setModelSpy };
     }
 
+    it.each(["environment", "caller object", "caller file"])(
+      "includes configured models omitted by the SDK from %s settings",
+      async (source) => {
+        const configured = {
+          availableModels: ["claude-haiku-4-5", "claude-haiku-5-5"],
+          modelOverrides: {
+            "claude-haiku-4-5": "global.anthropic.claude-haiku-4-5-20251001-v1:0",
+            "claude-haiku-5-5": "global.anthropic.claude-haiku-5-5",
+          },
+        };
+        let settings: object | string | undefined;
+        if (source === "environment") {
+          vi.stubEnv("CLAUDE_MODEL_CONFIG", JSON.stringify(configured));
+        } else if (source === "caller file") {
+          settings = "caller-settings.json";
+          await fs.promises.writeFile(path.join(tempDir, settings), JSON.stringify(configured));
+        } else {
+          settings = configured;
+        }
+        const { setModelSpy } = mockQueryWithModels([
+          { value: "default", displayName: "Default", description: "" },
+          { value: "sonnet", displayName: "Sonnet", description: "" },
+        ]);
+        const { ClaudeAcpAgent } = await import("../acp-agent.js");
+        const agent = new ClaudeAcpAgent(createMockClient());
+        try {
+          const response = await (agent as any).createSession({
+            cwd: tempDir,
+            mcpServers: [],
+            _meta: { claudeCode: { options: { settings } } },
+          });
+          expect(querySpy.mock.calls[0][0].options.settings).toEqual(configured);
+          const ids = ["default", ...Object.values(configured.modelOverrides)];
+          expect(
+            agent.sessions[response.sessionId].models.availableModels.map(
+              (model: any) => model.modelId,
+            ),
+          ).toEqual(ids);
+          const modelOption = response.configOptions.find((option: any) => option.id === "model");
+          expect(modelOption.options.map((option: any) => option.value)).toEqual(ids);
+          await agent.setSessionConfigOption({
+            sessionId: response.sessionId,
+            configId: "model",
+            value: ids[2],
+          });
+          expect(setModelSpy).toHaveBeenLastCalledWith(ids[2]);
+          expect(agent.sessions[response.sessionId].modelInfos.map((model) => model.value)).toEqual(
+            ids,
+          );
+        } finally {
+          await agent.dispose();
+          vi.unstubAllEnvs();
+        }
+      },
+    );
+
+    it("merges file settings with caller settings after caller keys replace the env config", async () => {
+      await fs.promises.writeFile(
+        path.join(tempDir, "settings.json"),
+        JSON.stringify({
+          availableModels: ["claude-sonnet-4-6", "claude-haiku-4-5"],
+          modelOverrides: {
+            "claude-sonnet-4-6": "file-sonnet",
+            "claude-haiku-4-5": "file-haiku",
+          },
+        }),
+      );
+      vi.stubEnv(
+        "CLAUDE_MODEL_CONFIG",
+        JSON.stringify({
+          availableModels: ["claude-opus-4-6"],
+          modelOverrides: { "claude-sonnet-4-6": "env-sonnet", "claude-haiku-4-5": "env-haiku" },
+        }),
+      );
+      mockQueryWithModels([{ value: "default", displayName: "Default", description: "" }]);
+      const { ClaudeAcpAgent } = await import("../acp-agent.js");
+      const agent = new ClaudeAcpAgent(createMockClient());
+      const settings = {
+        availableModels: ["claude-haiku-4-5", "claude-haiku-5-5"],
+        modelOverrides: { "claude-haiku-4-5": "caller-haiku" },
+      };
+      try {
+        const response = await (agent as any).createSession({
+          cwd: tempDir,
+          mcpServers: [],
+          _meta: { claudeCode: { options: { settings } } },
+        });
+        expect(querySpy.mock.calls[0][0].options.settings).toEqual(settings);
+        const modelOption = response.configOptions.find((option: any) => option.id === "model");
+        expect(modelOption.options.map((option: any) => option.value)).toEqual([
+          "default",
+          "file-sonnet",
+          "caller-haiku",
+          "claude-haiku-5-5",
+        ]);
+      } finally {
+        await agent.dispose();
+        vi.unstubAllEnvs();
+      }
+    });
+
+    it.each([[], undefined])(
+      "preserves empty and absent configured allowlists: %j",
+      async (availableModels) => {
+        vi.stubEnv(
+          "CLAUDE_MODEL_CONFIG",
+          JSON.stringify({
+            availableModels,
+            modelOverrides: { "claude-haiku-4-5": "provider-haiku" },
+          }),
+        );
+        mockQueryWithModels([
+          { value: "default", displayName: "Default", description: "" },
+          { value: "sonnet", displayName: "Sonnet", description: "" },
+        ]);
+        const { ClaudeAcpAgent } = await import("../acp-agent.js");
+        const agent = new ClaudeAcpAgent(createMockClient());
+        try {
+          const response = await (agent as any).createSession({ cwd: tempDir, mcpServers: [] });
+          const modelOption = response.configOptions.find((option: any) => option.id === "model");
+          expect(modelOption.options.map((option: any) => option.value)).toEqual(
+            availableModels ? ["default"] : ["default", "sonnet"],
+          );
+        } finally {
+          await agent.dispose();
+          vi.unstubAllEnvs();
+        }
+      },
+    );
+
     it("restricts configOptions to the user's allowlist using their exact IDs", async () => {
       // Reproduces the scenario from
       // https://github.com/agentclientprotocol/claude-agent-acp/issues/620:

src/tests/clear-context-coordinator.test.ts

@@ -28,6 +28,7 @@ function testSession(overrides: Partial<TestSession> = {}): TestSession {
       },
     },
     models: { currentModelId: "default" },
+    contextWindowSize: 200_000,
     configOptions: [],
     currentAgent: "default",
     fastModeEnabled: false,
@@ -464,6 +465,7 @@ describe("ExitPlanCoordinator", () => {
     expect(order).toEqual([
       "current_mode_update",
       "config_option_update",
+      "usage_update",
       ...(supportsPlanOperations
         ? [
             "plan_update " +
@@ -476,6 +478,10 @@ describe("ExitPlanCoordinator", () => {
         : []),
       "continuation",
     ]);
+    expect(host.sessionUpdate).toHaveBeenCalledWith({
+      sessionId: "public-session",
+      update: { sessionUpdate: "usage_update", used: 0, size: 200_000 },
+    });
     if (airClient) {
       expect(host.sessionUpdate).toHaveBeenCalledWith({
         sessionId: "public-session",

src/tests/model-selection-settings.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { resolveSettings } from "@anthropic-ai/claude-agent-sdk";
+import { SettingsManager } from "../settings.js";
+
+vi.mock("@anthropic-ai/claude-agent-sdk", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@anthropic-ai/claude-agent-sdk")>()),
+  resolveSettings: vi.fn(),
+}));
+
+describe("model selection settings policy", () => {
+  let manager: SettingsManager;
+  afterEach(() => manager?.dispose());
+
+  it.each([{ availableModels: ["claude-haiku-4-5"] }, { availableModels: [] }])(
+    "keeps the managed allowlist %j and mappings above inline settings",
+    async ({ availableModels }) => {
+      const managed = {
+        availableModels,
+        modelOverrides: { "claude-haiku-4-5": "managed-haiku" },
+        deniedModels: ["claude-opus-5"],
+      };
+      vi.mocked(resolveSettings).mockResolvedValue({
+        effective: managed,
+        provenance: {},
+        sources: [{ source: "managed", settings: managed }],
+      });
+      manager = new SettingsManager(process.cwd());
+      await manager.initialize();
+      expect(
+        manager.getModelSelectionSettings({
+          availableModels: ["claude-opus-5"],
+          modelOverrides: { "claude-haiku-4-5": "inline-haiku" },
+        }),
+      ).toEqual({
+        availableModels: managed.availableModels,
+        modelOverrides: managed.modelOverrides,
+      });
+      expect(manager.getManagedDeniedModels()).toEqual(managed.deniedModels);
+    },
+  );
+
+  it("keeps managed override keys above inline keys without discarding other inline mappings", async () => {
+    const managed = { modelOverrides: { "claude-haiku-4-5": "managed-haiku" } };
+    vi.mocked(resolveSettings).mockResolvedValue({
+      effective: managed,
+      provenance: {},
+      sources: [{ source: "managed", settings: managed }],
+    });
+    manager = new SettingsManager(process.cwd());
+    await manager.initialize();
+    expect(
+      manager.getModelSelectionSettings({
+        availableModels: ["claude-haiku-4-5", "claude-sonnet-4-6"],
+        modelOverrides: {
+          "claude-haiku-4-5": "inline-haiku",
+          "claude-sonnet-4-6": "inline-sonnet",
+        },
+      }),
+    ).toEqual({
+      availableModels: ["claude-haiku-4-5", "claude-sonnet-4-6"],
+      modelOverrides: { "claude-haiku-4-5": "managed-haiku", "claude-sonnet-4-6": "inline-sonnet" },
+    });
+  });
+
+  it("preserves file and inline mappings when the managed allowlist supplies no mappings", async () => {
+    vi.mocked(resolveSettings).mockResolvedValue({
+      effective: {
+        availableModels: ["claude-haiku-4-5"],
+        modelOverrides: { "claude-haiku-4-5": "file-haiku" },
+      },
+      provenance: {},
+      sources: [
+        { source: "user", settings: { modelOverrides: { "claude-haiku-4-5": "file-haiku" } } },
+        { source: "managed", settings: { availableModels: ["claude-haiku-4-5"] } },
+      ],
+    });
+    manager = new SettingsManager(process.cwd());
+    await manager.initialize();
+    expect(manager.getModelSelectionSettings()).toEqual({
+      availableModels: ["claude-haiku-4-5"],
+      modelOverrides: { "claude-haiku-4-5": "file-haiku" },
+    });
+    expect(
+      manager.getModelSelectionSettings({
+        modelOverrides: { "claude-haiku-4-5": "inline-haiku" },
+      }),
+    ).toEqual({
+      availableModels: ["claude-haiku-4-5"],
+      modelOverrides: { "claude-haiku-4-5": "inline-haiku" },
+    });
+  });
+});