test(opencode): retry temp cleanup while Windows holds the ripgrep download

A session created without a model or reasoning effort read Codex defaults
without its cwd, so a trusted project's .codex/config.toml was ignored and
the global values were sent as explicit overrides. Read the effective config
for the session cwd first and keep getUserSavedConfig as the fallback for
older Codex builds.

Co-authored-by: 3ae3ae <ogyshjsm@naver.com>

CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.10.1 - 2026-09-29
+
+### Added
+
+- Added Claude Sonnet 5.5 for Claude Code 2.1.284 and newer ([#5583](https://github.com/getpaseo/paseo/pull/5583) by [@yangqi](https://github.com/yangqi))
+
+### Fixed
+
+- Fixed OpenCode chats failing with "Variant unavailable" after switching to a model without the selected thinking level ([#5587](https://github.com/getpaseo/paseo/pull/5587))
+- Fixed rewinding a Codex chat dropping its custom provider and Paseo tools ([#5345](https://github.com/getpaseo/paseo/pull/5345) by [@zbaibg](https://github.com/zbaibg))
+- Fixed streamed replies joining lines of code blocks and Mermaid diagrams until the chat reloads ([#5577](https://github.com/getpaseo/paseo/pull/5577))
+- Fixed a subagent opened from a split pane opening in a different pane ([#5451](https://github.com/getpaseo/paseo/pull/5451))
+- Fixed archiving a custom Codex provider's agent leaving its session in Import session ([#5572](https://github.com/getpaseo/paseo/pull/5572))
+- Fixed the `/` menu of a custom Codex provider with its own `CODEX_HOME` listing the daemon's prompts instead of its own ([#5450](https://github.com/getpaseo/paseo/pull/5450))
+- Fixed a background `send_agent_prompt` returning `idle` for a prompt the agent accepted ([#5386](https://github.com/getpaseo/paseo/pull/5386))
+- Fixed Windows file-link tooltips showing the full path for files inside the workspace ([#1987](https://github.com/getpaseo/paseo/pull/1987))
+- Fixed terminal profiles that run `cursor-agent` showing the generic terminal icon ([#5379](https://github.com/getpaseo/paseo/pull/5379))
+
 ## 0.10.0 - 2026-09-28
 
 ### Added

packages/app/e2e/browser/chat-outline.spec.ts

@@ -17,12 +17,14 @@ import {
   hoverChatOutlinePrompt,
   chatOutlineRail,
   movePointerOffChatOutline,
+  observePromptIndexRequests,
   pointAtChatOutlineRowEdge,
   pressEnterOnFocusedPrompt,
   splitCurrentPanelRight,
   withStreamingMarkdownOutline,
   expectReadingStreamedMarkdown,
 } from "../support/helpers/chat-outline";
+import { createCreationScenario } from "../support/helpers/creation";
 import {
   expectTimelineAtMaximumScrollWithPromptVisible,
   expectTimelinePromptNotMounted,
@@ -266,3 +268,21 @@ test.describe("desktop chat outline", () => {
     }
   });
 });
+
+test("indexes a new agent's prompts only once the agent exists", async ({ page }) => {
+  const promptIndex = await observePromptIndexRequests(page);
+  const creation = await createCreationScenario(page);
+  try {
+    await page.setViewportSize(WIDE_VIEWPORT);
+    await creation.openAgentDraft();
+    await creation.submitPrompt("Start an agent with an outline.");
+    await creation.expectPromptVisible();
+
+    const agentIds = await creation.agentIds();
+    expect(agentIds).toHaveLength(1);
+    await promptIndex.waitForRequestFor(agentIds[0]!);
+    expect(promptIndex.requestedAgentIds()).toEqual(agentIds);
+  } finally {
+    await creation.cleanup();
+  }
+});

packages/app/e2e/browser/composer-autocomplete.spec.ts

@@ -10,6 +10,7 @@ import { daemonWsRoutePattern } from "../support/helpers/daemon-port";
 import { getServerId } from "../support/helpers/server-id";
 import { switchWorkspaceViaSidebar } from "../support/helpers/workspace-ui";
 import { expectMobileAgentSidebarVisible } from "../support/helpers/sidebar";
+import { expectNewWorkspaceProjectSelected } from "../support/helpers/new-workspace";
 
 const TEST_COMMANDS = [
   {
@@ -338,6 +339,16 @@ function expectPopoverFramesStable(frames: PopoverFrame[]): void {
   ).toBeUndefined();
 }
 
+function recordCommandRequestsByAgentId(page: Page): string[] {
+  const requests: string[] = [];
+  const record = ({ payload }: { payload: string | Buffer }) => {
+    if (typeof payload !== "string" || !payload.includes("list_commands_request")) return;
+    if (!payload.includes("draftConfig")) requests.push(payload);
+  };
+  page.on("websocket", (socket) => socket.on("framesent", record));
+  return requests;
+}
+
 function expectPopoverDoesNotDisappearAfterFirstVisible(frames: PopoverFrame[]): void {
   const firstVisibleIndex = frames.findIndex(
     (frame) =>
@@ -359,6 +370,25 @@ function expectPopoverDoesNotDisappearAfterFirstVisible(frames: PopoverFrame[]):
 }
 
 test.describe("Composer autocomplete", () => {
+  test("keeps New workspace off the running-agent command list before a project is chosen", async ({
+    page,
+  }) => {
+    const commandRequestsByAgentId = recordCommandRequestsByAgentId(page);
+
+    await page.goto("/new");
+    await expectNewWorkspaceProjectSelected(page, "Choose project");
+    await composerLocator(page).fill("/");
+
+    const popover = page
+      .getByTestId("composer-autocomplete-popover")
+      .filter({ visible: true })
+      .first();
+    await expect(popover).toContainText("Choose a project to see commands", { timeout: 30_000 });
+    await expect(popover).not.toContainText("/clear");
+    await expect(popover).not.toContainText("/exit");
+    expect(commandRequestsByAgentId).toEqual([]);
+  });
+
   test("stays visible after returning from app-wide routes", async ({ page }) => {
     await installListCommandsStub(page);
     const serverId = getServerId();

packages/app/e2e/browser/context-window-meter.spec.ts

@@ -0,0 +1,71 @@
+import type { Locator } from "@playwright/test";
+import { expect, test } from "../support/fixtures";
+import { expectComposerVisible } from "../support/helpers/composer";
+import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
+
+// Where the progress arc is painted, as its centroid relative to the ring's centre in pixels.
+// Reads the rendered pixels, so any rotation that does not reach the screen counts as none.
+async function progressArcCentroid(meter: Locator): Promise<{ x: number; y: number }> {
+  const ring = meter.locator("svg");
+  const progressColor = await ring
+    .locator("circle")
+    .last()
+    .evaluate((circle) => getComputedStyle(circle).stroke);
+  const screenshot = await ring.screenshot();
+  return ring.evaluate(
+    async (_svg, { png, color }) => {
+      const image = await createImageBitmap(
+        await (await fetch(`data:image/png;base64,${png}`)).blob(),
+      );
+      const canvas = new OffscreenCanvas(image.width, image.height);
+      const context = canvas.getContext("2d")!;
+      context.drawImage(image, 0, 0);
+      const { data } = context.getImageData(0, 0, image.width, image.height);
+      const [r, g, b] = color.match(/\d+/g)!.map(Number);
+      let sumX = 0;
+      let sumY = 0;
+      let count = 0;
+      for (let y = 0; y < image.height; y += 1) {
+        for (let x = 0; x < image.width; x += 1) {
+          const i = (y * image.width + x) * 4;
+          const distance =
+            Math.abs(data[i] - r) + Math.abs(data[i + 1] - g) + Math.abs(data[i + 2] - b);
+          if (distance < 40) {
+            sumX += x;
+            sumY += y;
+            count += 1;
+          }
+        }
+      }
+      if (count === 0) {
+        throw new Error(`No pixels painted in the progress colour ${color}`);
+      }
+      return { x: sumX / count - image.width / 2, y: sumY / count - image.height / 2 };
+    },
+    { png: screenshot.toString("base64"), color: progressColor },
+  );
+}
+
+test.describe("context window meter", () => {
+  test("draws usage clockwise from twelve o'clock", async ({ page }) => {
+    test.setTimeout(180_000);
+    // 32,000 of the mock's 128,000-token window: a quarter, from twelve to three o'clock.
+    const session = await seedMockAgentWorkspace({
+      repoPrefix: "context-window-meter-",
+      title: "Context window meter e2e",
+      initialPrompt: "emit 32000 byte file agent stream payload",
+    });
+    try {
+      await openAgentRoute(page, session);
+      await expectComposerVisible(page);
+      const meter = page.getByTestId("context-window-meter");
+      await expect(meter).toHaveAccessibleName(/25%/, { timeout: 30_000 });
+
+      const centroid = await progressArcCentroid(meter);
+      expect(centroid.x).toBeGreaterThan(1);
+      expect(centroid.y).toBeLessThan(-1);
+    } finally {
+      await session.cleanup();
+    }
+  });
+});

packages/app/e2e/browser/opencode-model-switch.real.spec.ts

@@ -0,0 +1,78 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { test, expect, type Page } from "../support/fixtures";
+import { launchAgent, cleanupRewindFlow, type AgentHandle } from "../support/helpers/rewind-flow";
+import { submitMessage } from "../support/helpers/composer";
+
+const binary = process.env.OPENCODE_TEST_BINARY ?? "opencode";
+test.use({
+  e2eDaemonConfig: {
+    version: 1,
+    agents: { providers: { opencode: { enabled: true, command: [binary] } } },
+  },
+});
+
+async function selectMedium(page: Page) {
+  await page
+    .getByRole("button", { name: /^Select thinking option/ })
+    .filter({ visible: true })
+    .click();
+  await page.getByText("Medium", { exact: true }).filter({ visible: true }).click();
+  await expect(
+    page
+      .getByRole("button", { name: "Select thinking option (Medium)", exact: true })
+      .filter({ visible: true }),
+  ).toBeVisible();
+}
+async function selectLongcat(page: Page) {
+  await page
+    .getByRole("button", { name: /^Select model \(/ })
+    .filter({ visible: true })
+    .click();
+  await page
+    .getByText("LongCat 2.5 Preview Free", { exact: true })
+    .filter({ visible: true })
+    .click();
+}
+async function askForReply(handle: AgentHandle) {
+  await submitMessage(handle.page, "Reply exactly OK. Do not use tools.");
+  return handle.client.waitForFinish(handle.agentId, 120_000);
+}
+
+test("switching an existing OpenCode session clears unsupported thinking", async ({
+  page,
+}, testInfo) => {
+  test.setTimeout(240_000);
+  const cwd = mkdtempSync(path.join(tmpdir(), "paseo-variant-ui-"));
+  let handle: AgentHandle | undefined;
+  try {
+    handle = await launchAgent({
+      page,
+      cwd,
+      provider: "opencode",
+      mode: "full-access",
+      providerConfig: { model: "opencode/space-bunny-free" },
+    });
+    await selectMedium(page);
+    expect((await askForReply(handle)).status).toBe("idle");
+    await selectLongcat(page);
+    await expect(
+      page.getByRole("button", { name: /^Select thinking option/ }).filter({ visible: true }),
+    ).toHaveCount(0);
+    const finish = await askForReply(handle);
+    const screenshot = testInfo.outputPath("model-switch.png");
+    await page.screenshot({ path: screenshot });
+    await testInfo.attach("After switching to Longcat", {
+      path: screenshot,
+      contentType: "image/png",
+    });
+    expect(finish.status).toBe("idle");
+    expect(finish.final?.lastError).toBeFalsy();
+    await expect(
+      page.getByTestId("assistant-message").filter({ visible: true }).last(),
+    ).toContainText("OK");
+  } finally {
+    await cleanupRewindFlow({ handle, cwd });
+  }
+});

packages/app/e2e/support/helpers/chat-outline.ts

@@ -3,6 +3,7 @@ import { openSettings } from "./app";
 import { openSettingsSection } from "./settings";
 import { runWorkspaceActionFromCommandCenter } from "./command-center-workspace-actions";
 import { seedMockAgentWorkspace, type MockAgentWorkspace } from "./mock-agent";
+import { loadSessionMessageReaders } from "./new-workspace";
 
 export async function withStreamingMarkdownOutline(
   run: (agent: MockAgentWorkspace) => Promise<void>,
@@ -229,3 +230,22 @@ async function requireBoundingBox(
   }
   return box;
 }
+
+export async function observePromptIndexRequests(page: Page) {
+  const frames = await loadSessionMessageReaders();
+  const agentIds: string[] = [];
+  page.on("websocket", (socket) => {
+    socket.on("framesent", ({ payload }) => {
+      const request = frames.client(payload);
+      if (request?.type === "agent.timeline.list_prompts.request") {
+        agentIds.push(request.agentId);
+      }
+    });
+  });
+  return {
+    async waitForRequestFor(agentId: string) {
+      await expect.poll(() => agentIds).toContain(agentId);
+    },
+    requestedAgentIds: () => [...new Set(agentIds)],
+  };
+}

packages/app/e2e/support/helpers/creation.ts

@@ -206,6 +206,12 @@ export async function createCreationScenario(page: Page) {
         )
         .toBe(count);
     },
+    async agentIds() {
+      await requests.settled();
+      return (await project.client.fetchAgents()).entries
+        .filter(({ agent }) => agent.workspaceId === workspaceId)
+        .map(({ agent }) => agent.id);
+    },
     async expectAgentTitle(title: string) {
       await expect
         .poll(

packages/app/src/agent-stream/chat-outline/model.test.ts

@@ -12,7 +12,6 @@ describe("chat outline prompt index epoch", () => {
   it("accepts only the authoritative timeline epoch", () => {
     expect(shouldAcceptPromptIndexEpoch("epoch-2", "epoch-2")).toBe(true);
     expect(shouldAcceptPromptIndexEpoch("epoch-2", "epoch-1")).toBe(false);
-    expect(shouldAcceptPromptIndexEpoch(null, "epoch-1")).toBe(true);
   });
 });
 

packages/app/src/agent-stream/chat-outline/model.ts

@@ -2,11 +2,8 @@ import type { AgentTimelinePromptIndexPayload } from "@getpaseo/client/internal/
 
 export type ChatOutlinePrompt = AgentTimelinePromptIndexPayload["prompts"][number];
 
-export function shouldAcceptPromptIndexEpoch(
-  timelineEpoch: string | null,
-  indexEpoch: string,
-): boolean {
-  return timelineEpoch === null || timelineEpoch === indexEpoch;
+export function shouldAcceptPromptIndexEpoch(timelineEpoch: string, indexEpoch: string): boolean {
+  return timelineEpoch === indexEpoch;
 }
 
 /**

packages/app/src/agent-stream/chat-outline/use-chat-outline.test.tsx

@@ -37,6 +37,31 @@ describe("useChatOutline", () => {
     runtime.subscribeAgentTimeline.mockClear();
   });
 
+  it("waits for a served timeline before requesting its prompt index", async () => {
+    runtime.listAgentTimelinePrompts.mockResolvedValue({ epoch: "epoch-1", prompts: [] });
+    const viewportRef = createRef<StreamViewportHandle>();
+    const { rerender } = renderHook(
+      ({ agentId, timelineEpoch }) =>
+        useChatOutline({
+          agentId,
+          serverId: "server-1",
+          timelineEpoch,
+          tail: [],
+          head: [],
+          enabled: true,
+          viewportRef,
+          onJumpError: vi.fn(),
+        }),
+      { initialProps: { agentId: "draft_msg_1", timelineEpoch: null as string | null } },
+    );
+
+    expect(runtime.listAgentTimelinePrompts).not.toHaveBeenCalled();
+
+    rerender({ agentId: "agent-1", timelineEpoch: "epoch-1" });
+    await waitFor(() => expect(runtime.listAgentTimelinePrompts).toHaveBeenCalledTimes(1));
+    expect(runtime.listAgentTimelinePrompts).toHaveBeenCalledWith("agent-1");
+  });
+
   it("drops a late prompt index after the authoritative timeline epoch changes", async () => {
     const first = deferred<{ epoch: string; prompts: [] }>();
     const second = deferred<{

packages/app/src/agent-stream/chat-outline/use-chat-outline.ts

@@ -77,8 +77,10 @@ export function useChatOutline({
 
   useEffect(() => setIndex(null), [agentId, enabled, serverId, timelineEpoch]);
 
+  // Only a timeline the daemon has served can be indexed. A draft's optimistic stream has no
+  // epoch, and its id names no agent the daemon knows.
   useEffect(() => {
-    if (!isWeb || !enabled) {
+    if (!isWeb || !enabled || timelineEpoch === null) {
       setIndex(null);
       return;
     }

packages/app/src/agent-stream/presentation.test.ts

@@ -210,6 +210,17 @@ describe("stream presentation through installed plugins", () => {
     expect(result.head).toMatchObject([{ text: "```ts\nconst a = 1;\n\nconst b = 2;" }]);
   });
 
+  // Codex streams a line break and the next line's indent as their own chunks.
+  it("keeps a line break when a chunk ends in the next line's indent", () => {
+    const harness = streamHarness();
+    harness.send(assistant("```mermaid\nflowchart TD\n    A[Start] --> B[Review]\n"));
+    harness.send(assistant("   "));
+    const result = harness.send(assistant(" B --> C[Finish]\n```"));
+    expect(result.head).toMatchObject([
+      { text: "```mermaid\nflowchart TD\n    A[Start] --> B[Review]\n    B --> C[Finish]\n```" },
+    ]);
+  });
+
   // One rendering path: a fetched message is the same block group as a streamed one,
   // which is what lets find, scroll-to-message and history reveal address it by id.
   // A link reference definition stays with the paragraph that uses it, so the split

packages/app/src/agent-stream/presentation.ts

@@ -112,8 +112,10 @@ export function createStreamPresentation() {
       const index = prefix.length + offset;
       let blockText = text;
       if (offset === textBlocks.length - 1) {
-        const trailingNewlines = /\n+$/.exec(item.text)?.[0] ?? "";
-        blockText += trailingNewlines;
+        // The split drops trailing blank lines, including a line break followed only
+        // by the next line's indent. Keep them so the next append continues that line.
+        const trailingBlankLines = /\n\s*$/.exec(item.text)?.[0] ?? "";
+        blockText += trailingBlankLines;
       }
       const existing = previous?.[index];
       const id = `${item.id}:block:${index}`;

packages/app/src/components/context-window-meter.tsx

@@ -117,7 +117,6 @@ export function ContextWindowMeter({
           width={geometry.svgSize}
           height={geometry.svgSize}
           viewBox={`0 0 ${geometry.svgSize} ${geometry.svgSize}`}
-          style={styles.svg}
           accessibilityElementsHidden
           importantForAccessibility="no-hide-descendants"
         >
@@ -158,7 +157,6 @@ export function ContextWindowMeter({
             width={svgSize}
             height={svgSize}
             viewBox={`0 0 ${svgSize} ${svgSize}`}
-            style={styles.svg}
             accessibilityElementsHidden
             importantForAccessibility="no-hide-descendants"
           >
@@ -180,6 +178,8 @@ export function ContextWindowMeter({
               strokeLinecap="round"
               strokeDasharray={circumference}
               strokeDashoffset={dashOffset}
+              // SVG strokes start at three o'clock; the ring reads clockwise from twelve.
+              transform={`rotate(-90 ${center} ${center})`}
             />
           </Svg>
           {showPercentage ? (
@@ -226,9 +226,6 @@ const styles = StyleSheet.create((theme) => ({
     gap: theme.spacing[1],
     borderRadius: theme.borderRadius.full,
   },
-  svg: {
-    transform: [{ rotate: "-90deg" }],
-  },
   percentageLabel: {
     color: theme.colors.foregroundMuted,
     fontSize: theme.fontSize.base,

packages/app/src/components/workspace-setup-dialog.tsx

@@ -462,7 +462,7 @@ export function WorkspaceSetupDialog() {
             cwd={sourceDirectory}
             clearDraft={chatDraft.clear}
             autoFocus
-            commandDraftConfig={composerState?.commandDraftConfig}
+            commandDraft={composerState?.commandDraft}
             agentControls={agentControlsWithDisabled}
             inputWrapperStyle={styles.composerInputWrapper}
           />

packages/app/src/composer/draft/input-draft.live.test.tsx

@@ -198,12 +198,15 @@ describe("useAgentInputDraft live contract", () => {
     });
 
     expect(getLatest().composerState?.agentControls.selectedProvider).toBe("codex");
-    expect(getLatest().composerState?.commandDraftConfig).toEqual({
-      provider: "codex",
-      cwd: "/repo",
-      modeId: "auto",
-      model: "gpt-5.4",
-      thinkingOptionId: "high",
+    expect(getLatest().composerState?.commandDraft).toEqual({
+      status: "ready",
+      config: {
+        provider: "codex",
+        cwd: "/repo",
+        modeId: "auto",
+        model: "gpt-5.4",
+        thinkingOptionId: "high",
+      },
     });
 
     const hydratedTextReplacement = getLatest().textReplacement;

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

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "vitest";
 import { hasDraftContent, resolveDraftKey } from "./input-draft-core";
 import {
-  buildDraftCommandConfig,
+  buildDraftCommandTarget,
   resolveEffectiveComposerModelId,
   resolveEffectiveComposerThinkingOptionId,
 } from "@/provider-selection/provider-selection";
@@ -124,46 +124,55 @@ describe("resolveEffectiveComposerThinkingOptionId", () => {
   });
 });
 
-describe("buildDraftComposerCommandConfig", () => {
-  it("returns undefined when cwd is empty", () => {
+describe("buildDraftCommandTarget", () => {
+  const codexSelection = {
+    provider: "codex",
+    modelId: "gpt-5.4",
+    modeId: "auto",
+    thinkingOptionId: "high",
+    availableModels: [],
+    modeOptions: [{ id: "auto", label: "Auto" }],
+  };
+
+  it("needs a project when cwd is empty", () => {
     expect(
-      buildDraftCommandConfig({
-        selection: {
-          provider: "codex",
-          modelId: "gpt-5.4",
-          modeId: "",
-          thinkingOptionId: "",
-          availableModels: [],
-          modeOptions: [],
-        },
+      buildDraftCommandTarget({
+        selection: codexSelection,
         cwd: "  ",
         effectiveModelId: "gpt-5.4",
         effectiveThinkingOptionId: "high",
       }),
-    ).toBeUndefined();
+    ).toEqual({ status: "needs-project" });
+  });
+
+  it("needs a provider when none is selected", () => {
+    expect(
+      buildDraftCommandTarget({
+        selection: { ...codexSelection, provider: null },
+        cwd: "/repo",
+        effectiveModelId: "",
+        effectiveThinkingOptionId: "",
+      }),
+    ).toEqual({ status: "needs-provider" });
   });
 
   it("builds the draft command config from derived composer state", () => {
     expect(
-      buildDraftCommandConfig({
-        selection: {
-          provider: "codex",
-          modelId: "gpt-5.4",
-          modeId: "auto",
-          thinkingOptionId: "high",
-          availableModels: [],
-          modeOptions: [{ id: "auto", label: "Auto" }],
-        },
+      buildDraftCommandTarget({
+        selection: codexSelection,
         cwd: "/repo",
         effectiveModelId: "gpt-5.4",
         effectiveThinkingOptionId: "high",
       }),
     ).toEqual({
-      provider: "codex",
-      cwd: "/repo",
-      modeId: "auto",
-      model: "gpt-5.4",
-      thinkingOptionId: "high",
+      status: "ready",
+      config: {
+        provider: "codex",
+        cwd: "/repo",
+        modeId: "auto",
+        model: "gpt-5.4",
+        thinkingOptionId: "high",
+      },
     });
   });
 });

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

@@ -2,7 +2,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { UserComposerAttachment } from "@/attachments/types";
 import type { TextReplacement } from "@/composer/types";
 import type { DraftAgentControlsProps } from "@/composer/agent-controls";
-import type { DraftCommandConfig } from "@/hooks/use-agent-commands-query";
+import type { DraftCommandTarget } from "@/hooks/use-agent-commands-query";
 import {
   useAgentFormState,
   type CreateAgentInitialValues,
@@ -16,7 +16,7 @@ import {
   type DraftKeyInput,
 } from "@/composer/draft/input-draft-core";
 import {
-  buildDraftCommandConfig,
+  buildDraftCommandTarget,
   resolveEffectiveComposerModelId,
   resolveEffectiveComposerThinkingOptionId,
   type ProviderSelectionState,
@@ -50,7 +50,7 @@ type DraftComposerState = UseAgentFormStateResult & {
   effectiveThinkingOptionId: string;
   featureValues: Record<string, unknown> | undefined;
   agentControls: DraftAgentControlsProps;
-  commandDraftConfig: DraftCommandConfig | undefined;
+  commandDraft: DraftCommandTarget;
 };
 
 export interface AgentInputDraft {
@@ -287,19 +287,16 @@ export function useAgentInputDraft(input: UseAgentInputDraftInput): AgentInputDr
     [applyProfileFeatureValues, formState],
   );
 
-  const commandDraftConfig = useMemo(
+  const commandDraft = useMemo(
     () =>
-      composerOptions
-        ? buildDraftCommandConfig({
-            selection: providerSelection,
-            cwd: workingDir,
-            effectiveModelId,
-            effectiveThinkingOptionId,
-            featureValues: draftFeatureValues,
-          })
-        : undefined,
+      buildDraftCommandTarget({
+        selection: providerSelection,
+        cwd: workingDir,
+        effectiveModelId,
+        effectiveThinkingOptionId,
+        featureValues: draftFeatureValues,
+      }),
     [
-      composerOptions,
       effectiveModelId,
       effectiveThinkingOptionId,
       draftFeatureValues,
@@ -325,10 +322,10 @@ export function useAgentInputDraft(input: UseAgentInputDraftInput): AgentInputDr
         onSetFeature: setDraftFeatureValue,
         onApplyAgentProfile: applyDraftAgentProfile,
       }),
-      commandDraftConfig,
+      commandDraft,
     };
   }, [
-    commandDraftConfig,
+    commandDraft,
     composerOptions,
     effectiveModelId,
     effectiveThinkingOptionId,
@@ -358,7 +355,6 @@ export const __private__ = {
   resolveDraftKey,
   resolveEffectiveComposerModelId,
   resolveEffectiveComposerThinkingOptionId,
-  buildDraftCommandConfig,
-  buildDraftComposerCommandConfig: buildDraftCommandConfig,
+  buildDraftCommandTarget,
   buildDraftAgentControls,
 };

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

@@ -682,7 +682,7 @@ export function WorkspaceDraftAgentTab({
             autoFocus={shouldAutoFocusWorkspaceDraftComposer({ isPaneFocused, isSubmitting })}
             autoFocusKey={String(draftInput.attachmentFocusRequestId)}
             onFocusInput={handleFocusInputCallback}
-            commandDraftConfig={composerState.commandDraftConfig}
+            commandDraft={composerState.commandDraft}
             agentControls={composerAgentControls}
             isCompactLayout={isCompactComposerLayout}
           />

packages/app/src/composer/index.tsx

@@ -62,7 +62,7 @@ import {
 } from "./input/input";
 import type { ImageAttachment, MessagePayload, TextReplacement } from "./types";
 import { ICON_SIZE, type Theme } from "@/styles/theme";
-import type { DraftCommandConfig } from "@/hooks/use-agent-commands-query";
+import type { DraftCommandTarget } from "@/hooks/use-agent-commands-query";
 import { encodeImages } from "@/utils/encode-images";
 import { focusWithRetries } from "@/utils/web-focus";
 import {
@@ -973,8 +973,8 @@ interface ComposerProps {
   autoFocusKey?: string;
   /** Callback to expose a focus function to parent components (desktop only). */
   onFocusInput?: (focus: () => void) => void;
-  /** Optional draft context for listing commands before an agent exists. */
-  commandDraftConfig?: DraftCommandConfig;
+  /** Draft context for listing commands before an agent exists. Omitted for running agents. */
+  commandDraft?: DraftCommandTarget;
   /** Called when a message is about to be sent (any path: keyboard, dictation, queued). */
   onMessageSent?: () => void;
   onComposerHeightChange?: (height: number) => void;
@@ -1264,7 +1264,7 @@ function ComposerContentImpl({
   autoFocus = false,
   autoFocusKey,
   onFocusInput,
-  commandDraftConfig,
+  commandDraft,
   onMessageSent,
   onComposerHeightChange,
   onAttentionInputFocus,
@@ -2346,7 +2346,7 @@ function ComposerContentImpl({
       setUserInput: replaceUserInput,
       serverId,
       agentId,
-      draftConfig: commandDraftConfig,
+      draft: commandDraft,
       canExecuteClientSlashCommand: buildOutgoingAttachments(attachments).length === 0,
       onClientSlashCommand: runClientSlashCommand,
       pluginClientSlashCommands,
@@ -2355,7 +2355,7 @@ function ComposerContentImpl({
       replaceUserInput,
       serverId,
       agentId,
-      commandDraftConfig,
+      commandDraft,
       buildOutgoingAttachments,
       attachments,
       runClientSlashCommand,

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

@@ -7,6 +7,7 @@ import {
   useAgentCommandsQuery,
   type AgentSlashCommand,
   type DraftCommandConfig,
+  type DraftCommandTarget,
 } from "./use-agent-commands-query";
 import { orderAutocompleteOptions } from "@/components/ui/autocomplete-utils";
 import { useAutocomplete } from "./use-autocomplete";
@@ -34,7 +35,7 @@ interface UseAgentAutocompleteInput {
   setUserInput: (nextValue: string) => void;
   serverId: string;
   agentId: string;
-  draftConfig?: DraftCommandConfig;
+  draft?: DraftCommandTarget;
   onAutocompleteApplied?: () => void;
   onClientSlashCommand?: (command: ClientSlashCommand) => void;
   canExecuteClientSlashCommand?: boolean;
@@ -117,18 +118,13 @@ type AvailableCommand =
   | { source: "plugin"; command: PluginClientSlashCommand }
   | { source: "provider"; command: AgentSlashCommand };
 
-function normalizeDraftCommandConfig(
-  draftConfig?: DraftCommandConfig,
-): DraftCommandConfig | undefined {
-  if (!draftConfig) {
+function resolveDraftQueryConfig(draft?: DraftCommandTarget): DraftCommandConfig | undefined {
+  if (draft?.status !== "ready") {
     return undefined;
   }
 
+  const draftConfig = draft.config;
   const cwd = draftConfig.cwd.trim();
-  if (!cwd) {
-    return undefined;
-  }
-
   const modeId = draftConfig.modeId?.trim() ?? "";
   const model = draftConfig.model?.trim() ?? "";
   const thinkingOptionId = draftConfig.thinkingOptionId?.trim() ?? "";
@@ -337,6 +333,35 @@ function resolveAutocompleteErrorMessage(args: {
   return undefined;
 }
 
+// A draft's agentId is a draft key the daemon does not know, so a draft lists
+// commands by its config only, and not at all until that config is complete.
+function resolveDraftCommandContext(draft: DraftCommandTarget | undefined) {
+  const queryDraftConfig = resolveDraftQueryConfig(draft);
+  const isDraftContext = draft !== undefined;
+  return {
+    isDraftContext,
+    queryDraftConfig,
+    canListCommands: !isDraftContext || queryDraftConfig !== undefined,
+  };
+}
+
+function resolveAutocompleteEmptyText(args: {
+  mode: AutocompleteMode;
+  draft: DraftCommandTarget | undefined;
+  t: TFunction;
+}): string {
+  if (args.mode === "file") {
+    return args.t("agentAutocomplete.noFiles");
+  }
+  if (args.draft?.status === "needs-project") {
+    return args.t("agentAutocomplete.chooseProjectForCommands");
+  }
+  if (args.draft?.status === "needs-provider") {
+    return args.t("agentAutocomplete.chooseModelForCommands");
+  }
+  return args.t("agentAutocomplete.noCommands");
+}
+
 export function useAgentAutocomplete(input: UseAgentAutocompleteInput): AgentAutocompleteResult {
   const { t } = useTranslation();
   const {
@@ -345,7 +370,7 @@ export function useAgentAutocomplete(input: UseAgentAutocompleteInput): AgentAut
     setUserInput,
     serverId,
     agentId,
-    draftConfig,
+    draft,
     onAutocompleteApplied,
     onClientSlashCommand,
     canExecuteClientSlashCommand,
@@ -380,13 +405,10 @@ export function useAgentAutocomplete(input: UseAgentAutocompleteInput): AgentAut
     return () => clearTimeout(timer);
   }, [fileFilterQuery]);
 
-  const normalizedDraftConfig = useMemo(
-    () => normalizeDraftCommandConfig(draftConfig),
-    [draftConfig],
+  const { isDraftContext, queryDraftConfig, canListCommands } = useMemo(
+    () => resolveDraftCommandContext(draft),
+    [draft],
   );
-
-  const isDraftContext = normalizedDraftConfig !== undefined;
-  const queryDraftConfig = normalizedDraftConfig;
   const canLoadCommands = resolveCanLoadCommands({ serverId, agentId, isDraftContext });
 
   const agentCwd = useSessionStore(
@@ -410,17 +432,14 @@ export function useAgentAutocomplete(input: UseAgentAutocompleteInput): AgentAut
     autocompleteCwd,
   });
 
-  const {
-    commands,
-    isLoading: isCommandsLoading,
-    isError,
-    error,
-  } = useAgentCommandsQuery({
+  const commandsQuery = useAgentCommandsQuery({
     serverId,
     agentId,
-    enabled: mode === "command" && canLoadCommands,
+    enabled: mode === "command" && canLoadCommands && canListCommands,
     draftConfig: queryDraftConfig,
   });
+  const { commands, isError, error } = commandsQuery;
+  const isCommandsLoading = canListCommands && commandsQuery.isLoading;
 
   const isVisible = canShowAutocomplete && !(mode === "command" && isCommandsLoading);
 
@@ -587,8 +606,7 @@ export function useAgentAutocomplete(input: UseAgentAutocompleteInput): AgentAut
     mode === "file"
       ? t("agentAutocomplete.searchingWorkspace")
       : t("agentAutocomplete.loadingCommands");
-  const emptyText =
-    mode === "file" ? t("agentAutocomplete.noFiles") : t("agentAutocomplete.noCommands");
+  const emptyText = resolveAutocompleteEmptyText({ mode, draft, t });
 
   return {
     isVisible,

packages/app/src/hooks/use-agent-commands-query.ts

@@ -17,6 +17,12 @@ export interface AgentSlashCommand {
 
 export type DraftCommandConfig = AgentCommandsDraftConfig;
 
+/** What a draft composer can list commands for, before an agent exists. */
+export type DraftCommandTarget =
+  | { status: "ready"; config: DraftCommandConfig }
+  | { status: "needs-project" }
+  | { status: "needs-provider" };
+
 interface ListAgentCommandsOptions {
   agentId: string;
   draftConfig?: DraftCommandConfig;

packages/app/src/i18n/resources/ar.ts

@@ -1522,6 +1522,8 @@ export const ar: TranslationResources = {
     noFiles: "لم يتم العثور على ملفات أو أدلة",
     noCommands: "لم يتم العثور على أي أوامر",
     failedToLoad: "فشل التحميل",
+    chooseProjectForCommands: "اختر مشروعًا لعرض الأوامر",
+    chooseModelForCommands: "اختر نموذجًا لعرض الأوامر",
   },
   loadOlderHistory: {
     failed: "تعذر تحميل السجل الأقدم",

packages/app/src/i18n/resources/en.ts

@@ -1547,6 +1547,8 @@ export const en = {
     noFiles: "No files or directories found",
     noCommands: "No commands found",
     failedToLoad: "Failed to load",
+    chooseProjectForCommands: "Choose a project to see commands",
+    chooseModelForCommands: "Select a model to see commands",
   },
   loadOlderHistory: {
     failed: "Couldn't load older history",

packages/app/src/i18n/resources/es.ts

@@ -1568,6 +1568,8 @@ export const es: TranslationResources = {
     noFiles: "No se encontraron archivos ni directorios",
     noCommands: "No se encontraron comandos",
     failedToLoad: "No se pudo cargar",
+    chooseProjectForCommands: "Elige un proyecto para ver los comandos",
+    chooseModelForCommands: "Selecciona un modelo para ver los comandos",
   },
   loadOlderHistory: {
     failed: "No se pudo cargar el historial anterior",

packages/app/src/i18n/resources/fr.ts

@@ -1572,6 +1572,8 @@ export const fr: TranslationResources = {
     noFiles: "Aucun fichier ou répertoire trouvé",
     noCommands: "Aucune commande trouvée",
     failedToLoad: "Échec du chargement",
+    chooseProjectForCommands: "Choisissez un projet pour voir les commandes",
+    chooseModelForCommands: "Sélectionnez un modèle pour voir les commandes",
   },
   loadOlderHistory: {
     failed: "Impossible de charger l'ancien historique",

packages/app/src/i18n/resources/ja.ts

@@ -1539,6 +1539,8 @@ export const ja: TranslationResources = {
     noFiles: "ファイルまたはディレクトリが見つかりません",
     noCommands: "コマンドが見つかりません",
     failedToLoad: "読み込みに失敗しました",
+    chooseProjectForCommands: "コマンドを表示するにはプロジェクトを選択してください",
+    chooseModelForCommands: "コマンドを表示するにはモデルを選択してください",
   },
   loadOlderHistory: {
     failed: "古い履歴を読み込めませんでした",

packages/app/src/i18n/resources/ko.ts

@@ -1532,6 +1532,8 @@ export const ko: TranslationResources = {
     noFiles: "파일 또는 디렉터리를 찾을 수 없습니다",
     noCommands: "명령을 찾을 수 없습니다",
     failedToLoad: "불러오지 못했습니다",
+    chooseProjectForCommands: "명령을 보려면 프로젝트를 선택하세요",
+    chooseModelForCommands: "명령을 보려면 모델을 선택하세요",
   },
   loadOlderHistory: {
     failed: "이전 기록을 불러올 수 없습니다",

packages/app/src/i18n/resources/pt-BR.ts

@@ -1553,6 +1553,8 @@ export const ptBR: TranslationResources = {
     noFiles: "Nenhum arquivo ou diretório encontrado",
     noCommands: "Nenhum comando encontrado",
     failedToLoad: "Falha ao carregar",
+    chooseProjectForCommands: "Escolha um projeto para ver os comandos",
+    chooseModelForCommands: "Selecione um modelo para ver os comandos",
   },
   loadOlderHistory: {
     failed: "Não foi possível carregar o histórico mais antigo",

packages/app/src/i18n/resources/ru.ts

@@ -1551,6 +1551,8 @@ export const ru: TranslationResources = {
     noFiles: "Файлы и каталоги не найдены",
     noCommands: "Команды не найдены",
     failedToLoad: "Не удалось загрузить",
+    chooseProjectForCommands: "Выберите проект, чтобы увидеть команды",
+    chooseModelForCommands: "Выберите модель, чтобы увидеть команды",
   },
   loadOlderHistory: {
     failed: "Не удалось загрузить старую историю.",

packages/app/src/i18n/resources/zh-CN.ts

@@ -1505,6 +1505,8 @@ export const zhCN: TranslationResources = {
     noFiles: "没有找到文件或目录",
     noCommands: "没有找到 commands",
     failedToLoad: "加载失败",
+    chooseProjectForCommands: "选择项目以查看命令",
+    chooseModelForCommands: "选择模型以查看命令",
   },
   loadOlderHistory: {
     failed: "无法加载更早历史",

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

@@ -5,7 +5,7 @@ import type {
   ProviderSnapshotEntry,
 } from "@getpaseo/protocol/agent-types";
 import type { AgentProviderDefinition } from "@getpaseo/protocol/provider-manifest";
-import type { DraftCommandConfig } from "@/hooks/use-agent-commands-query";
+import type { DraftCommandTarget } from "@/hooks/use-agent-commands-query";
 import { i18n } from "@/i18n/i18next";
 import { compareMatchScores, scoreTextFields } from "@getpaseo/protocol/search/text-match";
 import { filterSelectableModels } from "./model-catalog";
@@ -286,19 +286,22 @@ export function resolveEffectiveComposerThinkingOptionId(
   return selectedModelDefinition?.defaultThinkingOptionId ?? "";
 }
 
-export function buildDraftCommandConfig(input: {
+export function buildDraftCommandTarget(input: {
   selection: ProviderSelectionState;
   cwd: string;
   effectiveModelId: string;
   effectiveThinkingOptionId: string;
   featureValues?: Record<string, unknown>;
-}): DraftCommandConfig | undefined {
+}): DraftCommandTarget {
   const cwd = input.cwd.trim();
-  if (!input.selection.provider || !cwd) {
-    return undefined;
+  if (!cwd) {
+    return { status: "needs-project" };
+  }
+  if (!input.selection.provider) {
+    return { status: "needs-provider" };
   }
 
-  return {
+  const config = {
     provider: input.selection.provider,
     cwd,
     ...(input.selection.modeOptions.length > 0 && input.selection.modeId !== ""
@@ -310,6 +313,7 @@ export function buildDraftCommandConfig(input: {
       : {}),
     ...(input.featureValues ? { featureValues: input.featureValues } : {}),
   };
+  return { status: "ready", config };
 }
 
 export function resolveSubmissionReadiness(input: {

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

@@ -2422,7 +2422,7 @@ export function NewWorkspaceScreen({
       clearDraft={handleClearDraft}
       autoFocus
       autoFocusKey={launchFocusKey}
-      commandDraftConfig={composerState?.commandDraftConfig}
+      commandDraft={composerState?.commandDraft}
       agentControls={agentControlsWithDisabled}
     />
   );

packages/cli/tests/15-provider.test.ts

@@ -82,10 +82,15 @@ const EXPECTED_CLAUDE_MODELS = [
     model: "Opus 4.8",
     descriptionFragment: "Previous release",
   },
+  {
+    id: "claude-sonnet-5-5",
+    model: "Sonnet 5.5",
+    descriptionFragment: "Best for everyday tasks",
+  },
   {
     id: "claude-sonnet-5",
     model: "Sonnet 5",
-    descriptionFragment: "Best for everyday tasks",
+    descriptionFragment: "Previous release",
   },
   {
     id: "claude-opus-4-7[1m]",
@@ -430,7 +435,7 @@ try {
       "--quiet should print the same ordered model IDs returned by --json",
     );
     assert(
-      claudeModelsFromJson.some((m) => m.id === "claude-sonnet-5"),
+      claudeModelsFromJson.some((m) => m.id === "claude-sonnet-5-5"),
       "captured --json output should include the current Claude everyday model id",
     );
     console.log("✓ provider models --quiet outputs model IDs only\n");

packages/client/examples/agents-and-providers.ts

@@ -58,10 +58,23 @@ export async function runFollowUp(url: string, agentId: string): Promise<string
 
   try {
     await client.connect();
-    const result = await client.agents.ref(agentId).run("Summarize your progress and next step.");
+    const result = await client.agents.ref(agentId).run("Summarize your progress and next step.", {
+      activeTurnBehavior: "interrupt",
+    });
     if (result.status !== "idle") throw new Error(result.error ?? result.status);
     return result.lastMessage;
   } finally {
     await client.close();
   }
 }
+
+export async function steerAgent(url: string, agentId: string, prompt: string): Promise<void> {
+  const client = createClient(url);
+
+  try {
+    await client.connect();
+    await client.agents.ref(agentId).send(prompt, { activeTurnBehavior: "steer" });
+  } finally {
+    await client.close();
+  }
+}

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

@@ -6906,6 +6906,70 @@ test("creation reconnect observation uses connection-owned subscriptions and rel
   expect(phases).toEqual(["accepted", "failed"]);
 });
 
+test("uploadFile started while connecting waits for the connection and uploads", async () => {
+  const mock = createMockTransport();
+  const client = new DaemonClient({
+    url: "ws://test",
+    clientId: "upload-while-connecting",
+    logger: createMockLogger(),
+    reconnect: { enabled: false },
+    suppressSendErrors: true,
+    transportFactory: () => mock.transport,
+  });
+  clients.push(client);
+  const connection = client.connect();
+  expect(client.getConnectionState().status).toBe("connecting");
+
+  const upload = client.uploadFile({
+    fileName: "notes.txt",
+    mimeType: "text/plain",
+    bytes: new TextEncoder().encode("hello world"),
+    modifiedAt: "2026-05-02T00:00:00.000Z",
+    requestId: "req-upload-connecting",
+    chunkSize: 5,
+  });
+  void upload.catch(() => undefined);
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  mock.triggerOpen();
+  await connection;
+
+  await vi.waitFor(() => {
+    const frames = mock.sent
+      .filter((frame) => typeof frame !== "string")
+      .map(assertUint8Array)
+      .map(decodeFileTransferFrame);
+    expect(frames.map((frame) => frame.opcode)).toEqual([
+      FileTransferOpcode.FileBegin,
+      FileTransferOpcode.FileChunk,
+      FileTransferOpcode.FileChunk,
+      FileTransferOpcode.FileChunk,
+      FileTransferOpcode.FileEnd,
+    ]);
+  });
+  const requestIndex = mock.sent.findIndex(
+    (frame) =>
+      typeof frame === "string" && parseSentFrame(frame).requestId === "req-upload-connecting",
+  );
+  expect(parseSentFrame(mock.sent[requestIndex])).toMatchObject({ type: "file.upload.request" });
+  expect(requestIndex).toBeLessThan(mock.sent.findIndex((frame) => typeof frame !== "string"));
+
+  const file = {
+    type: "uploaded_file" as const,
+    id: "upload_req-upload-connecting",
+    fileName: "notes.txt",
+    mimeType: "text/plain",
+    size: 11,
+    path: "/tmp/paseo-uploads/upload_req-upload-connecting/notes.txt",
+  };
+  mock.triggerMessage(
+    wrapSessionMessage({
+      type: "file.upload.response",
+      payload: { requestId: "req-upload-connecting", file, error: null },
+    }),
+  );
+  await expect(upload).resolves.toEqual({ requestId: "req-upload-connecting", file, error: null });
+});
+
 test("uploadFile stops sending chunks when the connection closes between sends", async () => {
   const mock = createMockTransport();
   const client = new DaemonClient({

packages/client/src/daemon-client.ts

@@ -425,6 +425,7 @@ export interface DaemonClientTrace {
 
 export interface SendMessageOptions {
   messageId?: string;
+  /** What happens when the agent is mid-turn. The daemon interrupts the turn when omitted. */
   activeTurnBehavior?: ActiveTurnBehavior;
   images?: Array<{ data: string; mimeType: string }>;
   attachments?: SendAgentMessageRequest["attachments"];
@@ -1169,7 +1170,7 @@ function toReasonCode(reason: string | null | undefined): string | null {
 }
 
 interface PendingSend {
-  message: SessionInboundMessage;
+  send: () => void;
   resolve: () => void;
   reject: (error: Error) => void;
   timeoutHandle: ReturnType<typeof setTimeout>;
@@ -1797,12 +1798,23 @@ export class DaemonClient {
    * This prevents waiters from hanging forever when called during connection.
    */
   private sendSessionMessageOrThrow(message: SessionInboundMessage): Promise<void> {
+    return this.sendWhenConnected(() => {
+      const payload = SessionInboundMessageSchema.parse(message);
+      this.sendJsonMessage("session", payload.type, { type: "session", message: payload });
+    });
+  }
+
+  /** Resolves once connected, waiting out a connection that is still being established. */
+  private whenConnected(): Promise<void> {
+    return this.sendWhenConnected(() => undefined);
+  }
+
+  private sendWhenConnected(send: () => void): Promise<void> {
     const status = this.connectionState.status;
 
     // If connected, send immediately
     if (this.transport && status === "connected") {
-      const payload = SessionInboundMessageSchema.parse(message);
-      this.sendJsonMessage("session", payload.type, { type: "session", message: payload });
+      send();
       return Promise.resolve();
     }
 
@@ -1823,7 +1835,7 @@ export class DaemonClient {
           );
         }, DEFAULT_SEND_QUEUE_TIMEOUT_MS);
 
-        this.pendingSendQueue.push({ message, resolve, reject, timeoutHandle });
+        this.pendingSendQueue.push({ send, resolve, reject, timeoutHandle });
       });
     }
 
@@ -1842,8 +1854,7 @@ export class DaemonClient {
       clearTimeout(pending.timeoutHandle);
       try {
         if (this.transport && this.connectionState.status === "connected") {
-          const payload = SessionInboundMessageSchema.parse(pending.message);
-          this.sendJsonMessage("session", payload.type, { type: "session", message: payload });
+          pending.send();
           pending.resolve();
         } else {
           pending.reject(new DaemonConnectionError("Connection lost before message could be sent"));
@@ -4846,6 +4857,8 @@ export class DaemonClient {
     if (!bytes) {
       throw new Error("File bytes are required.");
     }
+    // The file frames bypass the send queue, so start only on an open connection.
+    await this.whenConnected();
     const uploadTransport = this.transport;
     const resolvedRequestId = this.createRequestId(input.requestId);
     const modifiedAt = input.modifiedAt ?? new Date().toISOString();

packages/client/src/index.test.ts

@@ -744,13 +744,17 @@ test("agent handles delegate create, send, timeline refetch, archive, and local
   expect(updatedAgents).toEqual(["Updated"]);
   expect(agent.current()).toEqual(updatedAgent);
 
-  const sendPromise = agent.send("hello", { messageId: "message-sdk" });
+  const sendPromise = agent.send("hello", {
+    messageId: "message-sdk",
+    activeTurnBehavior: "steer",
+  });
   const sendRequest = parseSentSessionMessage(ws.sent.at(-1));
   expect(sendRequest).toMatchObject({
     type: "send_agent_message_request",
     agentId: "agent_sdk",
     text: "hello",
     messageId: "message-sdk",
+    activeTurnBehavior: "steer",
   });
 
   ws.message(
@@ -768,6 +772,7 @@ test("agent handles delegate create, send, timeline refetch, archive, and local
 
   const runPromise = agent.run("finish the task", {
     messageId: "run-message-sdk",
+    activeTurnBehavior: "interrupt",
     timeoutMs: 30_000,
   });
   const runSendRequest = parseSentSessionMessage(ws.sent.at(-1));
@@ -776,6 +781,7 @@ test("agent handles delegate create, send, timeline refetch, archive, and local
     agentId: "agent_sdk",
     text: "finish the task",
     messageId: "run-message-sdk",
+    activeTurnBehavior: "interrupt",
   });
   ws.message(
     sessionMessage({

packages/client/src/index.ts

@@ -24,7 +24,6 @@ import type {
   ProjectPlacementPayload,
   WorkspaceProjectDescriptorPayload,
   RefreshProvidersSnapshotResponseMessage,
-  SendAgentMessageRequest,
   SessionOutboundMessage,
   WorkspaceDescriptorPayload,
   WorkspaceCreateRequest,
@@ -55,6 +54,7 @@ import type {
   FetchAgentTimelineDirection,
   FetchAgentTimelinePayload,
   FetchAgentTimelineProjection,
+  SendMessageOptions,
   WaitForFinishResult,
 } from "./daemon-client.js";
 
@@ -276,11 +276,7 @@ export interface PaseoAgentTimelineRefetchOptions {
   requestId?: string;
 }
 
-export interface PaseoAgentSendOptions {
-  messageId?: string;
-  images?: Array<{ data: string; mimeType: string }>;
-  attachments?: SendAgentMessageRequest["attachments"];
-}
+export type PaseoAgentSendOptions = SendMessageOptions;
 
 export interface PaseoAgentRunOptions extends PaseoAgentSendOptions {
   timeoutMs?: number;

packages/plugin/src/skill-examples.test.ts

@@ -0,0 +1,40 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+import { describe, expect, it } from "vitest";
+
+const repository = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+const skill = readFileSync(path.join(repository, "skills/paseo-plugin/SKILL.md"), "utf8");
+
+function sectionCode(heading: string): string {
+  const section = skill.slice(skill.indexOf(`\n## ${heading}\n`));
+  const code = /```tsx\n([\s\S]*?)\n```/.exec(section)?.[1];
+  if (!code) throw new Error(`No tsx example under "${heading}"`);
+  return code;
+}
+
+// Checks the example as a plugin client file, with the same options as the plugin examples.
+function typeErrors(code: string): string[] {
+  const configPath = path.join(repository, "packages/plugin/tsconfig.examples.json");
+  const { config } = ts.readConfigFile(configPath, ts.sys.readFile);
+  const { options } = ts.parseJsonConfigFileContent(config, ts.sys, path.dirname(configPath));
+  const file = path.join(repository, "plugin-examples/skill-example/client/example.tsx");
+  const host = ts.createCompilerHost(options);
+  const getSourceFile = host.getSourceFile;
+  host.getSourceFile = (name, language, ...rest) =>
+    path.resolve(name) === file
+      ? ts.createSourceFile(name, code, language)
+      : getSourceFile.call(host, name, language, ...rest);
+  host.fileExists = (name) => path.resolve(name) === file || ts.sys.fileExists(name);
+  const program = ts.createProgram([file], options, host);
+  return ts
+    .getPreEmitDiagnostics(program)
+    .map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"));
+}
+
+describe("paseo-plugin skill examples", () => {
+  it("composer pill example typechecks against the plugin SDK", () => {
+    expect(typeErrors(sectionCode("Add a composer pill"))).toEqual([]);
+  });
+});

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

@@ -4851,6 +4851,53 @@ test("persists live mode, model, and thinking changes without an external snapsh
   expect(persisted?.runtimeInfo?.model).toBe("gpt-5.4");
 });
 
+test("model changes persist the resolved thinking and fresh provider handle before another turn", async () => {
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-model-selection-"));
+  class ModelSession extends TestAgentSession {
+    selection = { model: "source", thinkingOptionId: "medium" as string | undefined };
+    async setModel(model: string | null) {
+      this.selection = { model: model ?? "default", thinkingOptionId: undefined };
+      this.pushEvent({
+        type: "thinking_option_changed",
+        provider: "codex",
+        thinkingOptionId: null,
+      });
+    }
+    describePersistence() {
+      return { provider: "codex" as const, sessionId: this.id, metadata: { ...this.selection } };
+    }
+  }
+  class ModelClient extends TestAgentClient {
+    async createSession(config: AgentSessionConfig) {
+      return new ModelSession(config);
+    }
+  }
+  const storage = new AgentStorage(join(workdir, "agents"), logger);
+  const manager = new AgentManager({
+    clients: { codex: new ModelClient() },
+    registry: storage,
+    logger,
+  });
+  try {
+    const agent = await manager.createAgent(
+      { provider: "codex", cwd: workdir, model: "source", thinkingOptionId: "medium" },
+      undefined,
+      { workspaceId: undefined },
+    );
+    await manager.setAgentModel(agent.id, "target");
+    await manager.flush();
+    const stored = await storage.get(agent.id);
+    expect(stored?.config?.model).toBe("target");
+    expect(stored?.config?.thinkingOptionId).toBeUndefined();
+    expect(stored?.persistence?.metadata?.model).toBe("target");
+    expect(stored?.persistence?.metadata?.thinkingOptionId).toBeUndefined();
+  } finally {
+    for (const agent of manager.listAgents()) await manager.closeAgent(agent.id);
+    await manager.flush();
+    rmSync(workdir, { recursive: true, force: true });
+  }
+});
+
 test("later explicit config mutations win over events emitted by earlier mutations", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-config-mutation-order-"));
   class ConfigMutationSession extends TestAgentSession {

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

@@ -1943,6 +1943,7 @@ export class AgentManager {
     if (agent.runtimeInfo) {
       agent.runtimeInfo = { ...agent.runtimeInfo, model: normalizedModelId };
     }
+    this.refreshSessionPersistence(agent);
     this.touchUpdatedAt(agent);
     this.emitState(agent);
   }

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

@@ -449,6 +449,63 @@ describe("PluginAgentClientRegistry", () => {
     expect(eventsOfType(events, "turn_failed")).toHaveLength(1);
   });
 
+  test("leaves a completed session without a failure when its plugin provider is removed", async () => {
+    const harness = createProviderHarness();
+    const registry = new PluginAgentClientRegistry(createTestLogger());
+    registry.replace([harness.registration]);
+    const session = await registry.clients()[harness.registration.id]!.createSession({
+      provider: harness.registration.id,
+      cwd: "/workspace",
+    });
+    const events: AgentStreamEvent[] = [];
+    session.subscribe((event) => events.push(event));
+
+    await session.run("hello", { clientMessageId: "completed-message" });
+    expect(eventsOfType(events, "turn_completed")).toHaveLength(1);
+
+    registry.replace([]);
+    await harness.waitForClose();
+
+    expect(eventsOfType(events, "turn_failed")).toEqual([]);
+    await expect(
+      session.startTurn("after reload", { clientMessageId: "after-reload" }),
+    ).rejects.toBeInstanceOf(StaleProviderSessionError);
+  });
+
+  test("fails an accepted turn that has not started when its plugin provider is removed", async () => {
+    const harness = createProviderHarness({
+      handleInput: async (input, emit) => {
+        if (input.type !== "session.prompt") return false;
+        emit({
+          type: "session.prompt_result",
+          sessionId: input.sessionId,
+          clientMessageId: input.prompt.clientMessageId,
+          result: { type: "turn", turnId: "accepted-turn" },
+        });
+        return true;
+      },
+    });
+    const registry = new PluginAgentClientRegistry(createTestLogger());
+    registry.replace([harness.registration]);
+    const session = await registry.clients()[harness.registration.id]!.createSession({
+      provider: harness.registration.id,
+      cwd: "/workspace",
+    });
+    const events: AgentStreamEvent[] = [];
+    session.subscribe((event) => events.push(event));
+
+    await expect(
+      session.startTurn("hello", { clientMessageId: "accepted-message" }),
+    ).resolves.toEqual({ turnId: "accepted-turn" });
+
+    registry.replace([]);
+    await harness.waitForClose();
+
+    expect(eventsOfType(events, "turn_failed")).toEqual([
+      expect.objectContaining({ error: "Provider connection closed" }),
+    ]);
+  });
+
   test("closes a stale session after its plugin provider is replaced", async () => {
     const old = createProviderHarness();
     const next = createProviderHarness();

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

@@ -547,6 +547,7 @@ class ProviderRuntimeSession {
     string,
     Deferred<Extract<ProviderEvent, { type: "session.prompt_result" }>>
   >();
+  private readonly activeTurnIds = new Set<string>();
   private terminal = false;
   config: ProviderConfigState = { models: [], modes: [], thinkingOptions: [], settings: [] };
   commands: Array<{ name: string; description: string; argumentHint?: string }> = [];
@@ -702,6 +703,7 @@ class ProviderRuntimeSession {
       return;
     }
     if (event.type === "session.prompt_result") {
+      if (event.result.type === "turn") this.activeTurnIds.add(event.result.turnId);
       this.prompts.get(event.clientMessageId)?.resolve(event);
       return;
     }
@@ -720,14 +722,16 @@ class ProviderRuntimeSession {
   }
 
   connectionClosed(error = new Error("Provider connection closed")): void {
-    if (!this.terminal) {
-      this.terminal = true;
+    // Closing fails only an interrupted turn. An idle session goes stale, and its next prompt
+    // reopens it from persistence.
+    if (!this.terminal && this.activeTurnIds.size > 0) {
       this.publish({
         type: "session.runtime_failed",
         sessionId: this.id,
         error: { message: error.message },
       });
     }
+    this.terminal = true;
     this.rejectPending(error);
   }
 
@@ -751,6 +755,10 @@ class ProviderRuntimeSession {
   }
 
   private publish(event: ProviderEvent): void {
+    if (event.type === "session.turn") {
+      if (event.state === "started") this.activeTurnIds.add(event.turnId);
+      else this.activeTurnIds.delete(event.turnId);
+    }
     if (event.type === "session.config") this.config = event.config;
     if (event.type === "session.commands") this.commands = [...event.commands];
     if (event.type === "session.persistence" && this.restoration === "core") {

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

@@ -497,7 +497,7 @@ describe("ClaudeAgentClient.fetchCatalog", () => {
       const client = new ClaudeAgentClient({
         logger,
         resolveBinary: async () => "/test/claude/bin",
-        resolveVersion: async () => "2.1.219",
+        resolveVersion: async () => "2.1.284",
         runtimeSettings: { env: { CLAUDE_CONFIG_DIR: emptyConfigDir } },
       });
       const { models } = await client.fetchCatalog({
@@ -516,6 +516,8 @@ describe("ClaudeAgentClient.fetchCatalog", () => {
       expect(getThinkingIds("claude-opus-4-8")).toContain("ultracode");
       expect(getThinkingIds("claude-sonnet-5")).toContain("xhigh");
       expect(getThinkingIds("claude-sonnet-5")).toContain("ultracode");
+      expect(getThinkingIds("claude-sonnet-5-5")).toContain("xhigh");
+      expect(getThinkingIds("claude-sonnet-5-5")).not.toContain("off");
       expect(getThinkingIds("claude-opus-4-7[1m]")).toContain("ultracode");
       expect(getThinkingIds("claude-opus-4-7")).toContain("ultracode");
       expect(getThinkingIds("claude-sonnet-4-6")).not.toContain("ultracode");
@@ -1289,6 +1291,26 @@ describe("ClaudeAgentSession features", () => {
     await session.close();
   });
 
+  test("rejects disabled thinking on Sonnet 5.5, which only runs with adaptive thinking", 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-5",
+    });
+
+    await expect(session.setThinkingOption?.("off")).rejects.toThrow(
+      "Thinking option 'off' is not available for model 'claude-sonnet-5-5'",
+    );
+
+    await session.close();
+  });
+
   test("rejects an initial disabled-thinking config for an unsupported model", async () => {
     const { queryFactory } = createQueryMock();
     const client = new ClaudeAgentClient({

packages/server/src/server/agent/providers/claude/model-manifest.ts

@@ -93,10 +93,19 @@ export const CLAUDE_MODEL_MANIFEST = [
     supportsThinkingDisabled: true,
     supportsFastMode: true,
   },
+  {
+    id: "claude-sonnet-5-5",
+    label: "Sonnet 5.5",
+    description: "Sonnet 5.5 · Best for everyday tasks",
+    minimumClaudeCodeVersion: "2.1.284",
+    defaultThinkingOptionId: "medium",
+    contextWindowMaxTokens: 1_000_000,
+    effortLevels: CLAUDE_EFFORT_LEVELS.xhigh,
+  },
   {
     id: "claude-sonnet-5",
     label: "Sonnet 5",
-    description: "Sonnet 5 · Best for everyday tasks",
+    description: "Sonnet 5 · Previous release",
     contextWindowMaxTokens: 200_000,
     effortLevels: CLAUDE_EFFORT_LEVELS.xhigh,
     supportsThinkingDisabled: true,

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

@@ -39,7 +39,7 @@ async function createClaudeConfigDirWithRawSettings(settings: string): Promise<s
   return configDir;
 }
 
-function createCatalogClient(claudeCodeVersion = "2.1.280"): ClaudeAgentClient {
+function createCatalogClient(claudeCodeVersion = "2.1.284"): ClaudeAgentClient {
   return new ClaudeAgentClient({
     logger: createTestLogger(),
     resolveVersion: async () => claudeCodeVersion,
@@ -57,6 +57,7 @@ describe("getClaudeModels", () => {
       "claude-fable-5[1m]",
       "claude-opus-4-8[1m]",
       "claude-opus-4-8",
+      "claude-sonnet-5-5",
       "claude-sonnet-5",
       "claude-sonnet-5[1m]",
       "claude-opus-4-7[1m]",
@@ -90,6 +91,7 @@ describe("getClaudeModels", () => {
         ["claude-fable-5[1m]", 1_000_000],
         ["claude-opus-4-8[1m]", 1_000_000],
         ["claude-opus-4-8", 200_000],
+        ["claude-sonnet-5-5", 1_000_000],
         ["claude-sonnet-5", 200_000],
         ["claude-sonnet-5[1m]", 1_000_000],
         ["claude-opus-4-7[1m]", 1_000_000],
@@ -116,6 +118,9 @@ describe("getClaudeModels", () => {
     expect(getClaudeModels("2.1.279").find((model) => model.isDefault)?.id).toBe("claude-opus-5");
     expect(getClaudeModels("2.1.280").map((model) => model.id)).toContain("claude-opus-5-5");
     expect(getClaudeModels("2.1.280").find((model) => model.isDefault)?.id).toBe("claude-opus-5-5");
+
+    expect(getClaudeModels("2.1.283").map((model) => model.id)).not.toContain("claude-sonnet-5-5");
+    expect(getClaudeModels("2.1.284").map((model) => model.id)).toContain("claude-sonnet-5-5");
   });
 
   it("derives thinking options from model effort capabilities", () => {
@@ -178,6 +183,8 @@ describe("getClaudeModels", () => {
   it.each([
     ["claude-opus-5-5", false, "medium"],
     ["claude-opus-5-5-20260401", false, "medium"],
+    ["claude-sonnet-5-5", false, "medium"],
+    ["claude-sonnet-5-5-20260928", false, "medium"],
     ["claude-opus-5", true, "high"],
     ["claude-opus-5-20260724", true, "high"],
     ["claude-sonnet-5", true, "high"],
@@ -467,6 +474,16 @@ describe("normalizeClaudeRuntimeModelId", () => {
       "claude-opus-5",
     );
   });
+
+  it("does not collapse a prefixed Sonnet 5.5 onto Sonnet 5", () => {
+    expect(normalizeClaudeRuntimeModelId("anthropic/claude-sonnet-5-5")).toBe("claude-sonnet-5-5");
+    expect(normalizeClaudeRuntimeModelId("us.anthropic.claude-sonnet-5-5-20260928-v1:0")).toBe(
+      "claude-sonnet-5-5",
+    );
+    expect(normalizeClaudeRuntimeModelId("us.anthropic.claude-sonnet-5-20260101-v1:0")).toBe(
+      "claude-sonnet-5",
+    );
+  });
 });
 
 describe("parseClaudeCodeVersion", () => {
@@ -600,6 +617,42 @@ describe("Claude Opus 5.5 catalog", () => {
   });
 });
 
+describe("Claude Sonnet 5.5 catalog", () => {
+  it("offers one Sonnet 5.5 entry with a 1M context window", () => {
+    const sonnet55Models = getClaudeModels()
+      .filter((model) => model.id.startsWith("claude-sonnet-5-5"))
+      .map(({ id, label, contextWindowMaxTokens }) => ({ id, label, contextWindowMaxTokens }));
+
+    expect(sonnet55Models).toEqual([
+      { id: "claude-sonnet-5-5", label: "Sonnet 5.5", contextWindowMaxTokens: 1_000_000 },
+    ]);
+  });
+
+  it("offers every effort level except off, because Sonnet 5.5 cannot disable thinking", () => {
+    const sonnet55 = getClaudeModels().find((model) => model.id === "claude-sonnet-5-5");
+
+    expect(sonnet55?.thinkingOptions?.map((option) => option.id)).toEqual([
+      "low",
+      "medium",
+      "high",
+      "xhigh",
+      "max",
+      CLAUDE_ULTRACODE_THINKING_OPTION_ID,
+    ]);
+    expect(sonnet55?.defaultThinkingOptionId).toBe("medium");
+    expect(
+      sonnet55?.thinkingOptions?.filter((option) => option.isDefault).map((option) => option.id),
+    ).toEqual(["medium"]);
+  });
+
+  it("resolves suffixed and dated Sonnet 5.5 IDs to the single catalog entry", () => {
+    expect(findClaudeModel("claude-sonnet-5-5[1m]")?.id).toBe("claude-sonnet-5-5");
+    expect(findClaudeModel("claude-sonnet-5-5-20260928")?.id).toBe("claude-sonnet-5-5");
+    expect(findClaudeModel("claude-sonnet-5-5-20260928[1m]")?.id).toBe("claude-sonnet-5-5");
+    expect(findClaudeModel("claude-sonnet-5-5[1m]")?.contextWindowMaxTokens).toBe(1_000_000);
+  });
+});
+
 describe("claudeManifestModelSupportsFastMode", () => {
   it("keeps fast mode strict to first-party manifest model IDs", () => {
     expect(normalizeClaudeManifestModelId("openrouter/anthropic/claude-opus-4-8")).toBeNull();
@@ -610,6 +663,7 @@ describe("claudeManifestModelSupportsFastMode", () => {
   it("supports fast mode on Opus 5 but not on other Claude 5 models", () => {
     expect(claudeManifestModelSupportsFastMode("claude-opus-5-5")).toBe(true);
     expect(claudeManifestModelSupportsFastMode("claude-opus-5")).toBe(true);
+    expect(claudeManifestModelSupportsFastMode("claude-sonnet-5-5")).toBe(false);
     expect(claudeManifestModelSupportsFastMode("claude-sonnet-5")).toBe(false);
     expect(claudeManifestModelSupportsFastMode("claude-fable-5")).toBe(false);
     expect(claudeManifestModelSupportsFastMode("claude-fable-5-1")).toBe(false);

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

@@ -1117,6 +1117,42 @@ describe("Codex app-server provider", () => {
     });
   });
 
+  test("starts a session without a model on the project's Codex model and effort", async () => {
+    const cwd = "/workspace/project";
+    const appServer = createFakeCodexAppServer({
+      "config/read": (params) => ({
+        config:
+          (params as { cwd?: unknown }).cwd === cwd
+            ? { model: "project-model", model_reasoning_effort: "high" }
+            : { model: "global-model", model_reasoning_effort: "low" },
+      }),
+      getUserSavedConfig: () => ({
+        config: { model: "global-model", modelReasoningEffort: "low" },
+      }),
+    });
+    const session = new CodexAppServerAgentSession(
+      createConfig({ cwd, model: undefined }),
+      null,
+      createTestLogger(),
+      async () => appServer.child,
+    );
+
+    try {
+      await session.startTurn("use project defaults");
+
+      await expect(appServer.waitForRequest("thread/start")).resolves.toMatchObject({
+        model: "project-model",
+      });
+      await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
+        model: "project-model",
+        effort: "high",
+      });
+      appServer.assertNoErrors();
+    } finally {
+      await session.close();
+    }
+  });
+
   test("preserves cwd-resolved Codex writable roots under an explicit workflow mode", async () => {
     const appServer = createFakeCodexAppServer({
       "config/read": () => ({

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

@@ -3100,10 +3100,32 @@ const CodexNotificationSchema = z.union([
     ),
 ]);
 
+// config/read resolves the effective layered config, including a trusted project's
+// .codex/config.toml when given its cwd; getUserSavedConfig predates it.
 async function readCodexConfiguredDefaults(
   client: CodexAppServerClient,
   logger: Logger,
+  cwd: string | null,
 ): Promise<CodexConfiguredDefaults> {
+  let configReadDefaults: CodexConfiguredDefaults = {};
+  try {
+    const response = toObjectRecord(await client.request("config/read", { cwd }));
+    const config = toObjectRecord(response?.config);
+    const modelValue = typeof config?.model === "string" ? config.model : undefined;
+    const thinkingOptionValue =
+      typeof config?.model_reasoning_effort === "string" ? config.model_reasoning_effort : null;
+    configReadDefaults = {
+      model: normalizeCodexModelId(modelValue),
+      thinkingOptionId: normalizeCodexThinkingOptionId(thinkingOptionValue),
+    };
+  } catch (error) {
+    logger.debug({ error }, "Failed to read Codex config defaults");
+  }
+
+  if (configReadDefaults.model && configReadDefaults.thinkingOptionId) {
+    return configReadDefaults;
+  }
+
   let savedConfigDefaults: CodexConfiguredDefaults = {};
   try {
     const response = toObjectRecord(await client.request("getUserSavedConfig", {}));
@@ -3119,26 +3141,7 @@ async function readCodexConfiguredDefaults(
     logger.debug({ error }, "Failed to read Codex saved config defaults");
   }
 
-  if (savedConfigDefaults.model && savedConfigDefaults.thinkingOptionId) {
-    return savedConfigDefaults;
-  }
-
-  let configReadDefaults: CodexConfiguredDefaults = {};
-  try {
-    const response = toObjectRecord(await client.request("config/read", {}));
-    const config = toObjectRecord(response?.config);
-    const modelValue = typeof config?.model === "string" ? config.model : undefined;
-    const thinkingOptionValue =
-      typeof config?.model_reasoning_effort === "string" ? config.model_reasoning_effort : null;
-    configReadDefaults = {
-      model: normalizeCodexModelId(modelValue),
-      thinkingOptionId: normalizeCodexThinkingOptionId(thinkingOptionValue),
-    };
-  } catch (error) {
-    logger.debug({ error }, "Failed to read Codex config defaults");
-  }
-
-  return mergeCodexConfiguredDefaults(savedConfigDefaults, configReadDefaults);
+  return mergeCodexConfiguredDefaults(configReadDefaults, savedConfigDefaults);
 }
 
 interface CodexSkillPromptBlock {
@@ -5119,7 +5122,11 @@ export class CodexAppServerAgentSession implements AgentSession {
     let model = this.config.model;
     let thinkingOptionId = normalizeCodexThinkingOptionId(this.config.thinkingOptionId);
     if (!model || !thinkingOptionId) {
-      configuredDefaults = await readCodexConfiguredDefaults(this.client, this.logger);
+      configuredDefaults = await readCodexConfiguredDefaults(
+        this.client,
+        this.logger,
+        this.config.cwd ?? null,
+      );
     }
     if (!model) {
       model = configuredDefaults.model;
@@ -7323,7 +7330,7 @@ export class CodexAppServerAgentClient implements AgentClient {
       const parsedResponse = CodexModelListResponseSchema.safeParse(rawResponse);
       const models = parsedResponse.success ? (parsedResponse.data.data ?? []) : [];
       const configuredDefaults = await runProviderRefreshActivity(context, "config/read", () =>
-        readCodexConfiguredDefaults(client!, this.logger),
+        readCodexConfiguredDefaults(client!, this.logger, null),
       );
       const configuredDefaultModelId = configuredDefaults.model;
       const configuredDefaultThinkingOptionId = configuredDefaults.thinkingOptionId;

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

@@ -333,6 +333,76 @@ describe("OpenCodeAgentClient adapter smoke tests", () => {
     model: TEST_MODEL,
   });
 
+  test.each([
+    { variants: { medium: {}, custom: {} }, selected: "medium", expected: "medium" },
+    { variants: { custom: {} }, selected: "custom", expected: "custom" },
+    { variants: { high: {} }, selected: "medium", expected: undefined },
+    { variants: {}, selected: "medium", expected: undefined },
+  ])(
+    "model switches resolve the retained variant: $selected / $variants",
+    async ({ variants, selected, expected }) => {
+      const cwd = tmpCwd();
+      const runtime = new TestOpenCodeHarness();
+      const upstream = new TestOpenCodeClient();
+      upstream.providerListResponse = {
+        data: {
+          connected: ["test"],
+          all: [
+            {
+              id: "test",
+              name: "Test",
+              source: "api",
+              models: { target: { name: "Target", variants } },
+            },
+          ],
+        },
+      };
+      runtime.enqueueClient(upstream);
+      const client = new OpenCodeAgentClient(logger, undefined, {
+        serverManager: runtime,
+        createClient: runtime.createClient,
+      });
+      const session = await client.createSession({
+        provider: "opencode",
+        cwd,
+        model: "test/source",
+        thinkingOptionId: selected,
+      });
+      const events: AgentStreamEvent[] = [];
+      session.subscribe((event) => events.push(event));
+      try {
+        await session.setModel!("test/target");
+        expect((await session.getRuntimeInfo()).thinkingOptionId).toBe(expected ?? null);
+        expect(events).toContainEqual({
+          type: "thinking_option_changed",
+          provider: "opencode",
+          thinkingOptionId: expected ?? null,
+        });
+        upstream.sessionPromptAsyncEvents = [
+          { type: "session.idle", properties: { sessionID: "session-1" } },
+        ];
+        await collectTurnEvents(streamSession(session, "Use the selected model"));
+        expect(upstream.calls.sessionPromptAsync).toEqual([
+          expect.objectContaining({
+            model: { providerID: "test", modelID: "target" },
+            ...(expected ? { variant: expected } : {}),
+          }),
+        ]);
+        if (!expected) expect(upstream.calls.sessionPromptAsync[0]).not.toHaveProperty("variant");
+        await session.setThinkingOption!("medium");
+        await expect(session.setModel!("test/missing")).rejects.toThrow(
+          "OpenCode model unavailable",
+        );
+        upstream.providerListResponse = { error: "Catalog unavailable" };
+        await expect(session.setModel!("test/source")).rejects.toThrow("Catalog unavailable");
+        expect((await session.getRuntimeInfo()).model).toBe("test/target");
+      } finally {
+        await session.close();
+        rmSync(cwd, { recursive: true, force: true });
+      }
+    },
+  );
+
   test("usage reference follows the active OpenCode model and OAuth account", async () => {
     const cwd = tmpCwd();
     const runtime = new TestOpenCodeHarness();
@@ -386,7 +456,13 @@ describe("OpenCodeAgentClient adapter smoke tests", () => {
     expect(events).toContainEqual({
       type: "model_changed",
       provider: "opencode",
-      runtimeInfo: { provider: "opencode", sessionId, model: "openai/gpt-5", modeId: null },
+      runtimeInfo: {
+        provider: "opencode",
+        sessionId,
+        model: "openai/gpt-5",
+        modeId: null,
+        thinkingOptionId: null,
+      },
     });
     await session.close();
     rmSync(cwd, { recursive: true, force: true });

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

@@ -3616,6 +3616,7 @@ class OpenCodeAgentSession implements AgentSession {
       sessionId: this.sessionId,
       model: this.config.model ?? null,
       modeId: this.currentMode,
+      thinkingOptionId: this.config.thinkingOptionId ?? null,
     };
   }
 
@@ -3627,12 +3628,32 @@ class OpenCodeAgentSession implements AgentSession {
   }
 
   async setModel(modelId: string | null): Promise<void> {
+    await this.reconnectIfServerExited();
     const normalizedModelId =
       typeof modelId === "string" && modelId.trim().length > 0 ? modelId : null;
+    let variant = this.config.thinkingOptionId;
+    if (!normalizedModelId) {
+      variant = undefined;
+    } else if (variant) {
+      const model = this.parseModel(normalizedModelId);
+      const response = await this.client.provider.list({ directory: this.config.cwd });
+      if (response.error)
+        throw new Error(`Failed to fetch OpenCode providers: ${JSON.stringify(response.error)}`);
+      const provider = response.data?.all.find((entry) => entry.id === model?.providerID);
+      const target = model && provider?.models[model.modelID];
+      if (!target) throw new Error(`OpenCode model unavailable: ${normalizedModelId}`);
+      if (!Object.hasOwn(target.variants ?? {}, variant)) variant = undefined;
+    }
     this.config.model = normalizedModelId ?? undefined;
+    this.config.thinkingOptionId = variant;
     this.selectedModelContextWindowMaxTokens = this.resolveConfiguredModelContextWindowMaxTokens(
       this.config.model,
     );
+    this.notifySubscribers({
+      type: "thinking_option_changed",
+      provider: "opencode",
+      thinkingOptionId: variant ?? null,
+    });
   }
 
   async setThinkingOption(thinkingOptionId: string | null): Promise<void> {

packages/server/src/server/agent/providers/opencode-bridge.local.e2e.test.ts

@@ -355,7 +355,8 @@ test.each([
       await resumed?.close();
       await original?.close();
       await client.shutdown();
-      await rm(root, { recursive: true, force: true });
+      // OpenCode can still hold its ripgrep download open on Windows right after shutdown.
+      await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
     }
   },
   240_000,

packages/server/src/server/agent/providers/opencode/tool-call-detail-parser.ts

@@ -221,6 +221,15 @@ function deriveOpencodeTaskDetail(
   };
 }
 
+function toOpencodeEditInput(value: { filePath: string; oldString?: string; newString?: string }) {
+  return {
+    filePath: value.filePath,
+    oldString: nonEmptyString(value.oldString),
+    newString: nonEmptyString(value.newString),
+    unifiedDiff: undefined,
+  };
+}
+
 const OpencodeEditInputSchema = z.union([
   z
     .object({
@@ -229,12 +238,12 @@ const OpencodeEditInputSchema = z.union([
       newString: z.string().optional(),
     })
     .passthrough()
-    .transform((value) => ({
-      filePath: value.filePath,
-      oldString: nonEmptyString(value.oldString),
-      newString: nonEmptyString(value.newString),
-      unifiedDiff: undefined,
-    })),
+    .transform(toOpencodeEditInput),
+  // OpenCode v2's edit tool names the file `path`.
+  z
+    .object({ path: z.string(), oldString: z.string(), newString: z.string() })
+    .passthrough()
+    .transform((value) => toOpencodeEditInput({ ...value, filePath: value.path })),
   ToolEditInputSchema,
 ]);
 

packages/server/src/server/agent/providers/opencode/v2/agent.test.ts

@@ -7,6 +7,89 @@ import { OpenCodeV2AgentClient } from "./agent.js";
 import { V2Harness } from "../test-utils/v2-harness.js";
 
 describe("OpenCode v2 session lifecycle", () => {
+  test.each([
+    { variants: ["medium", "custom"], selected: "medium", expected: "medium" },
+    { variants: ["custom"], selected: "custom", expected: "custom" },
+    { variants: ["high"], selected: "medium", expected: undefined },
+    { variants: [], selected: "medium", expected: undefined },
+    { variants: ["medium"], selected: "default", expected: undefined },
+  ])(
+    "model switches retain only supported variants: $selected / $variants",
+    async ({ variants, selected, expected }) => {
+      const harness = new V2Harness();
+      const target: ModelInfo = {
+        id: "target",
+        modelID: "target",
+        providerID: "test",
+        name: "Target",
+        capabilities: { tools: true, input: ["text"], output: ["text"] },
+        variants: variants.map((id) => ({ id })),
+        time: { released: 1 },
+        cost: [],
+        status: "active",
+        enabled: true,
+        limit: { context: 200000, output: 10000 },
+      };
+      harness.info.model = { providerID: "test", id: "source", variant: selected };
+      harness.api.model.list = async () => ({ location: harness.info.location, data: [target] });
+      harness.api.session.switchModel = async ({ model }) => {
+        harness.info.model = model;
+      };
+      const client = new OpenCodeV2AgentClient({
+        logger: createTestLogger(),
+        runtime: harness.runtime,
+      });
+      const session = await client.createSession({
+        provider: "opencode",
+        cwd: "/tmp/project",
+        model: "test/source",
+        thinkingOptionId: selected,
+      });
+      const events: AgentStreamEvent[] = [];
+      session.subscribe((event) => events.push(event));
+      try {
+        await session.setModel!("test/target");
+        expect(await session.getRuntimeInfo()).toMatchObject({
+          model: "test/target",
+          thinkingOptionId: expected ?? null,
+        });
+        expect(session.describePersistence().metadata?.thinkingOptionId).toBe(expected);
+        expect(events).toContainEqual({
+          type: "thinking_option_changed",
+          provider: "opencode",
+          thinkingOptionId: expected ?? null,
+        });
+        await expect(session.setModel!("test/missing")).rejects.toThrow(
+          "OpenCode model unavailable",
+        );
+        harness.api.session.switchModel = async () => {
+          throw new Error("Switch failed");
+        };
+        await expect(session.setModel!("test/target")).rejects.toThrow("Switch failed");
+        expect(session.describePersistence().metadata?.thinkingOptionId).toBe(expected);
+        expect(harness.info.model).toEqual({
+          providerID: "test",
+          id: "target",
+          ...(expected ? { variant: expected } : {}),
+        });
+        harness.api.session.switchModel = async ({ model }) => {
+          harness.info.model = model;
+        };
+        harness.api.model.default = async () => ({ location: harness.info.location, data: target });
+        await session.setThinkingOption!("unsupported");
+        await session.setModel!(null);
+        expect((await session.getRuntimeInfo()).thinkingOptionId).toBeNull();
+        harness.api.model.list = async () => {
+          throw new Error("Catalog unavailable");
+        };
+        await expect(session.setModel!("test/source")).rejects.toThrow("Catalog unavailable");
+        expect((await session.getRuntimeInfo()).model).toBe("test/target");
+      } finally {
+        await session.close();
+      }
+    },
+  );
+
   test("restores each same-directory agent environment on reconnect and resume", async () => {
     const first = new V2Harness();
     const second = new V2Harness();
@@ -535,85 +618,4 @@ describe("OpenCode v2 session lifecycle", () => {
       await session.close();
     }
   });
-
-  test("switching to a model without the current variant sends the next prompt without it", async () => {
-    const harness = offeringModels({
-      "opencode/space-bunny-free": ["low", "medium", "high"],
-      "opencode/longcat-2.5-preview-free": [],
-      "opencode/muse-spark-free": ["minimal", "medium"],
-    });
-    const client = new OpenCodeV2AgentClient({
-      logger: createTestLogger(),
-      runtime: harness.runtime,
-    });
-    const session = await client.createSession({
-      provider: "opencode",
-      cwd: "/tmp/project",
-      model: "opencode/space-bunny-free",
-      thinkingOptionId: "medium",
-    });
-    const thinkingChanges: Array<string | null> = [];
-    session.subscribe((event) => {
-      if (event.type === "thinking_option_changed") thinkingChanges.push(event.thinkingOptionId);
-    });
-    try {
-      await session.setModel!("opencode/muse-spark-free");
-      expect(await session.getRuntimeInfo!()).toMatchObject({ thinkingOptionId: "medium" });
-
-      await session.setModel!("opencode/longcat-2.5-preview-free");
-      await session.run("hello");
-      expect(harness.prompts).toEqual(["hello"]);
-      expect(await session.getRuntimeInfo!()).toMatchObject({
-        model: "opencode/longcat-2.5-preview-free",
-        thinkingOptionId: null,
-      });
-      expect(thinkingChanges).toEqual([null]);
-    } finally {
-      await session.close();
-    }
-  });
 });
-
-// Behaves like an OpenCode v2 server: switching to any listed model succeeds,
-// and a prompt fails when the session's variant is not one its model offers.
-function offeringModels(variantsByModel: Record<string, string[]>): V2Harness {
-  const harness = new V2Harness();
-  const catalog: ModelInfo[] = Object.entries(variantsByModel).map(([ref, variants]) => {
-    const [providerID, id] = ref.split("/");
-    return {
-      id,
-      modelID: id,
-      providerID,
-      name: id,
-      capabilities: { tools: true, input: ["text"], output: ["text"] },
-      variants: variants.map((variant) => ({ id: variant })),
-      time: { released: 0 },
-      cost: [],
-      status: "active",
-      enabled: true,
-      limit: { context: 1000, output: 1000 },
-    };
-  });
-  harness.api.model.list = async (input) => ({
-    location: { directory: input?.location?.directory ?? harness.info.location.directory },
-    data: catalog,
-  });
-  harness.api.session.create = async (input = {}) => {
-    harness.creates.push(input);
-    harness.info.model = input.model;
-    return harness.info;
-  };
-  harness.api.session.switchModel = async ({ model }) => {
-    harness.info.model = model;
-  };
-  harness.prompt = async (input) => {
-    const model = harness.info.model;
-    const offered = catalog.find(
-      (entry) => entry.providerID === model?.providerID && entry.id === model?.id,
-    );
-    if (model?.variant && !offered?.variants.some((variant) => variant.id === model.variant))
-      throw new Error(`Variant unavailable for ${model.providerID}/${model.id}: ${model.variant}`);
-    harness.prompts.push(input.text);
-  };
-  return harness;
-}

packages/server/src/server/agent/providers/opencode/v2/session.ts

@@ -3,7 +3,7 @@ import { SessionTurns } from "./turns.js";
 import { V2Timeline } from "./timeline.js";
 import { waitForLocationReady, awaitPaseoPlugin } from "./readiness.js";
 
-import type { ModelRef, SessionInfo, SessionMessageInfo } from "@opencode/client";
+import type { SessionInfo, SessionMessageInfo } from "@opencode/client";
 
 import { setTimeout as delay } from "node:timers/promises";
 import type { Logger } from "pino";
@@ -276,36 +276,48 @@ export class OpenCodeV2Session implements AgentSession {
   }
   async setModel(model: string | null) {
     await this.reconnectIfExited();
-    const selected = model
-      ? modelRef(model)
-      : (await this.client.model.default({ location: { directory: this.config.cwd } })).data;
+    const location = { directory: this.config.cwd };
+    const selected = model ? modelRef(model) : (await this.client.model.default({ location })).data;
     if (!selected) throw new Error("OpenCode has no default model");
-    // OpenCode rejects a prompt whose variant the model does not offer, so the
-    // current variant only carries over to a model that has it.
-    const variant = await this.offeredVariant(selected, this.config.thinkingOptionId);
-    await this.client.session.switchModel({
-      sessionID: this.id,
-      model: { id: selected.id, providerID: selected.providerID, variant },
-    });
+    const catalog = await this.client.model.list({ location });
+    const target = catalog.data.find(
+      (entry) =>
+        entry.enabled && entry.providerID === selected.providerID && entry.id === selected.id,
+    );
+    if (!target)
+      throw new Error(`OpenCode model unavailable: ${selected.providerID}/${selected.id}`);
+    const retainedVariant = this.config.thinkingOptionId;
+    const variant =
+      retainedVariant !== "default" && target.variants.some((entry) => entry.id === retainedVariant)
+        ? retainedVariant
+        : undefined;
+    const nextModel = {
+      id: selected.id,
+      providerID: selected.providerID,
+      ...(variant ? { variant } : {}),
+    };
+    await this.client.session.switchModel({ sessionID: this.id, model: nextModel });
+    this.info.model = nextModel;
     this.config.model = model ?? undefined;
-    if (variant !== this.config.thinkingOptionId) {
-      this.config.thinkingOptionId = variant;
-      this.emit({ type: "thinking_option_changed", provider: "opencode", thinkingOptionId: null });
-    }
+    this.config.thinkingOptionId = variant;
+    this.emit({
+      type: "thinking_option_changed",
+      provider: "opencode",
+      thinkingOptionId: variant ?? null,
+    });
     this.emit({
       type: "model_changed",
       provider: "opencode",
-      runtimeInfo: await this.getRuntimeInfo(),
+      runtimeInfo: {
+        provider: "opencode",
+        sessionId: this.id,
+        model: `${selected.providerID}/${selected.id}`,
+        modeId: this.info.agent ?? null,
+        thinkingOptionId: variant ?? null,
+      },
     });
   }
-  private async offeredVariant(model: ModelRef, variant: string | undefined) {
-    if (!variant) return undefined;
-    const { data } = await this.client.model.list({ location: { directory: this.config.cwd } });
-    const offered = data.find(
-      (entry) => entry.providerID === model.providerID && entry.id === model.id,
-    );
-    return offered?.variants.some((entry) => entry.id === variant) ? variant : undefined;
-  }
+
   async setThinkingOption(variant: string | null) {
     await this.reconnectIfExited();
     const model = this.info.model;

packages/server/src/server/agent/providers/opencode/v2/timeline.test.ts

@@ -0,0 +1,56 @@
+import type { SessionMessageAssistant } from "@opencode/client";
+import { expect, test } from "vitest";
+import { V2Timeline } from "./timeline.js";
+
+function assistant(content: SessionMessageAssistant["content"]): SessionMessageAssistant {
+  return {
+    id: "answer",
+    type: "assistant",
+    agent: "build",
+    model: { providerID: "test", id: "model" },
+    time: { created: 2 },
+    content,
+  };
+}
+
+test("a completed edit carries the replaced and replacement text", () => {
+  // Captured from OpenCode 2.0.18, whose edit tool takes `path` instead of `filePath`.
+  const edit = assistant([
+    {
+      type: "tool",
+      id: "call-edit",
+      name: "edit",
+      executed: false,
+      state: {
+        status: "completed",
+        input: { path: "a.txt", oldString: "beta", newString: "BETA" },
+        content: [{ type: "text", text: "Edited a.txt (1 replacement)" }],
+        metadata: {
+          files: [
+            {
+              file: "a.txt",
+              patch:
+                "Index: a.txt\n===================================================================\n--- a.txt\n+++ a.txt\n@@ -1,3 +1,3 @@\n alpha\n-beta\n+BETA\n gamma\n",
+              status: "modified",
+              additions: 1,
+              deletions: 1,
+            },
+          ],
+          truncated: false,
+        },
+      },
+      time: { created: 2, ran: 2, completed: 2 },
+    },
+  ]);
+
+  expect(new V2Timeline().messages([edit])).toMatchObject([
+    {
+      item: {
+        type: "tool_call",
+        name: "edit",
+        status: "completed",
+        detail: { type: "edit", filePath: "a.txt", oldString: "beta", newString: "BETA" },
+      },
+    },
+  ]);
+});

packages/server/src/server/plugins/lifecycle.e2e.test.ts

@@ -423,6 +423,55 @@ test("a clean daemon shutdown leaves a completed plugin-provider agent without a
   expect(persisted?.attentionReason ?? null).not.toBe("error");
 }, 60_000);
 
+test("reloading a plugin leaves a completed plugin-provider agent without an error", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "plugin-provider-reload-"));
+  onTestFinished(() => rm(root, { recursive: true, force: true }));
+  const pluginDirectory = await createProviderPlugin(root);
+  const workspace = path.join(root, "workspace");
+  await mkdir(workspace, { recursive: true });
+
+  const daemon = await createTestPaseoDaemon({
+    paseoHomeRoot: path.join(root, "daemon"),
+    staticDir: path.join(root, "static"),
+    pluginsEnabled: true,
+    plugins: {
+      "shutdown-provider-plugin": { source: "directory", path: pluginDirectory, enabled: true },
+    },
+  });
+  const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws`, appVersion: "0.9.1" });
+  onTestFinished(async () => {
+    await client.close();
+    await daemon.close();
+  });
+  await client.connect();
+  await client.fetchAgents({ subscribe: {} });
+
+  const agent = await client.createAgent({
+    provider: PROVIDER_ID,
+    model: "shutdown-model",
+    cwd: workspace,
+    title: "Reload provider agent",
+  });
+  await client.sendMessage(agent.id, "hello");
+  expect((await client.waitForFinish(agent.id, 30_000)).status).toBe("idle");
+
+  const reloaded = await client.reloadPlugin("shutdown-provider-plugin");
+  expect(reloaded.status).toBe("running");
+
+  const afterReload = await daemon.daemon.agentStorage.get(agent.id);
+  expect(afterReload?.lastError ?? null).toBeNull();
+  expect(afterReload?.attentionReason ?? null).not.toBe("error");
+  const timeline = await client.fetchAgentTimeline(agent.id, {
+    direction: "tail",
+    limit: 0,
+    projection: "canonical",
+  });
+  expect(JSON.stringify(timeline.entries)).not.toContain("Provider connection closed");
+
+  await client.sendMessage(agent.id, "after reload");
+  expect((await client.waitForFinish(agent.id, 30_000)).status).toBe("idle");
+}, 60_000);
+
 test("a provider that never acknowledges session.close does not hold the daemon open", async () => {
   const root = await mkdtemp(path.join(tmpdir(), "plugin-provider-stuck-close-"));
   onTestFinished(() => rm(root, { recursive: true, force: true }));

skills/paseo-plugin/SKILL.md

@@ -468,34 +468,70 @@ The callback receives the same context as the matching Command Center item plus
 A pill is a per-agent button in the composer track bar next to Tasks and Subagents. Add and remove pills from the client entry lifecycle. `addComposerPill` exists on `PluginClientContext`.
 
 ```tsx
+import type { PluginButtonRegistration, PluginClientContext } from "@getpaseo/plugin/client";
+
 export function contributeClient(client: PluginClientContext) {
-  const pills = new Map<string, () => void>();
-  const unsubscribe = client.paseo.agents.subscribe((update) => {
-    if (update.kind !== "upsert" || !update.agent.workspaceId) return;
-    const { id: agentId, workspaceId } = update.agent;
-    pills.get(agentId)?.();
+  const pills = new Map<string, PluginButtonRegistration>();
+  const lifetime = new AbortController();
+  const register = (agent: { id: string; workspaceId?: string | null }) => {
+    if (lifetime.signal.aborted || !agent.workspaceId) return;
+    const agentId = agent.id;
+    const workspaceId = agent.workspaceId;
+    pills.get(agentId)?.remove();
     pills.set(
       agentId,
       client.addComposerPill({
         id: "review",
-        title: "Open review",
         workspaceId,
         agentId,
-        Component: ReviewPill,
-        async onPress() {
-          client.openPanel("review", { workspaceId, agentId });
+        button: {
+          title: "Open review",
+          icon: "Scan",
+          label: "Review",
+          behavior: {
+            kind: "action",
+            onPress() {
+              client.openPanel("review", { workspaceId, agentId });
+            },
+          },
         },
       }),
     );
-  });
+  };
+  const removeAll = () => {
+    for (const pill of pills.values()) pill.remove();
+    pills.clear();
+  };
+  // An owned list subscription delivers existing agents, then updates, and a fresh snapshot after a reconnect.
+  void client.paseo.agents
+    .list({ subscribe: {}, signal: lifetime.signal })
+    .then(({ subscription }) => {
+      subscription.subscribe({
+        snapshot: ({ entries }) => {
+          removeAll();
+          for (const { agent } of entries) register(agent);
+        },
+        update: (message) => {
+          if (message.type !== "agent_update") return;
+          const update = message.payload;
+          if (update.kind === "upsert") return register(update.agent);
+          pills.get(update.agentId)?.remove();
+          pills.delete(update.agentId);
+        },
+      });
+      return undefined;
+    })
+    .catch((error) => {
+      if (!lifetime.signal.aborted) console.error("Agent observation failed", error);
+    });
   return () => {
-    unsubscribe();
-    for (const remove of pills.values()) remove();
+    lifetime.abort();
+    removeAll();
   };
 }
 ```
 
-Call `contributeClient(client)` from `index.client.tsx`, or move its body into that entry. The component owns its icon and text; Paseo owns the pressable, chrome, pending state, error reporting, and placement. Removal functions are idempotent, and Paseo removes every pill when the plugin, client entrypoint, or host connection is torn down.
+Call `contributeClient(client)` from `index.client.tsx`, or move its body into that entry. The `button` descriptor sets the icon, label, and behavior; Paseo owns the pressable, chrome, pending state, error reporting, and placement. `addComposerPill` returns a registration with `update()` and `remove()`. `remove()` is idempotent, and Paseo removes every pill when the plugin, client entrypoint, or host connection is torn down.
 
 ## Transform and render timeline items