@vellumai/assistant 0.12.0 → 0.12.1-staging.1

package/src/config/__tests__/platform-identity.test.ts

@@ -0,0 +1,117 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import {
+  setPlatformAssistantId,
+  setPlatformOrganizationId,
+  setPlatformUserId,
+} from "../env.js";
+import {
+  fetchPlatformIdentityIds,
+  PLATFORM_IDENTITY_VALIDATE_PATH,
+  resolvePlatformAssistantId,
+} from "../platform-identity.js";
+
+const BASE_URL = "https://platform.vellum.ai";
+const ASSISTANT_ID = "11111111-2222-4333-8444-555555555555";
+const ORG_ID = "22222222-3333-4444-8555-666666666666";
+const USER_ID = "33333333-4444-4555-8666-777777777777";
+
+describe("fetchPlatformIdentityIds", () => {
+  const originalFetch = globalThis.fetch;
+  const fetchCalls: Array<{ url: string; init?: RequestInit }> = [];
+  let fetchImpl: (
+    input: RequestInfo | URL,
+    init?: RequestInit,
+  ) => Promise<Response> = async () =>
+    new Response("not found", { status: 404 });
+
+  beforeEach(() => {
+    fetchCalls.length = 0;
+    fetchImpl = async () => new Response("not found", { status: 404 });
+    globalThis.fetch = (async (
+      input: RequestInfo | URL,
+      init?: RequestInit,
+    ) => {
+      const url = typeof input === "string" ? input : input.toString();
+      fetchCalls.push({ url, init });
+      return fetchImpl(input, init);
+    }) as unknown as typeof fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  test("returns the three ids from a successful validate response", async () => {
+    fetchImpl = async () =>
+      new Response(
+        JSON.stringify({
+          assistant_id: ASSISTANT_ID,
+          organization_id: ORG_ID,
+          user_id: USER_ID,
+          name: "Example Assistant",
+        }),
+        { status: 200 },
+      );
+
+    await expect(
+      fetchPlatformIdentityIds(BASE_URL, "assistant-key"),
+    ).resolves.toEqual({
+      assistantId: ASSISTANT_ID,
+      organizationId: ORG_ID,
+      userId: USER_ID,
+    });
+    expect(fetchCalls[0]?.url).toBe(
+      `${BASE_URL}${PLATFORM_IDENTITY_VALIDATE_PATH}`,
+    );
+    expect(fetchCalls[0]?.init?.method).toBe("POST");
+    const headers = new Headers(fetchCalls[0]?.init?.headers);
+    expect(headers.get("Authorization")).toBe("Api-Key assistant-key");
+  });
+
+  test("strips a trailing slash from the base URL", async () => {
+    fetchImpl = async () =>
+      new Response(
+        JSON.stringify({
+          assistant_id: ASSISTANT_ID,
+          organization_id: ORG_ID,
+          user_id: USER_ID,
+        }),
+        { status: 200 },
+      );
+
+    await fetchPlatformIdentityIds(`${BASE_URL}/`, "assistant-key");
+    expect(fetchCalls[0]?.url).toBe(
+      `${BASE_URL}${PLATFORM_IDENTITY_VALIDATE_PATH}`,
+    );
+  });
+
+  test("returns null on 401 without throwing", async () => {
+    fetchImpl = async () => new Response("no", { status: 401 });
+    await expect(
+      fetchPlatformIdentityIds(BASE_URL, "assistant-key"),
+    ).resolves.toBeNull();
+  });
+
+  test("returns null on a network error without throwing", async () => {
+    fetchImpl = async () => {
+      throw new Error("network down");
+    };
+    await expect(
+      fetchPlatformIdentityIds(BASE_URL, "assistant-key"),
+    ).resolves.toBeNull();
+  });
+});
+
+describe("resolvePlatformAssistantId", () => {
+  afterEach(() => {
+    setPlatformAssistantId(undefined);
+    setPlatformOrganizationId(undefined);
+    setPlatformUserId(undefined);
+  });
+
+  test("returns the in-memory override", async () => {
+    setPlatformAssistantId(ASSISTANT_ID);
+    await expect(resolvePlatformAssistantId()).resolves.toBe(ASSISTANT_ID);
+  });
+});

package/src/config/__tests__/platform-rehydration.test.ts

@@ -39,15 +39,34 @@ describe("rehydratePlatformCredentials", () => {
   const originalPlatformUrlEnv = process.env.VELLUM_PLATFORM_URL;
   const originalOrgEnv = process.env.PLATFORM_ORGANIZATION_ID;
   const originalUserEnv = process.env.PLATFORM_USER_ID;
+  const originalAssistantApiKeyEnv = process.env.ASSISTANT_API_KEY;
+  const originalFetch = globalThis.fetch;
+  const fetchCalls: Array<{ url: string; init?: RequestInit }> = [];
+  let fetchImpl: (
+    input: RequestInfo | URL,
+    init?: RequestInit,
+  ) => Promise<Response> = async () =>
+    new Response("not found", { status: 404 });
 
   beforeEach(() => {
     mockSecureKeys = {};
     throwForKey = undefined;
+    fetchCalls.length = 0;
+    fetchImpl = async () => new Response("not found", { status: 404 });
+    globalThis.fetch = (async (
+      input: RequestInfo | URL,
+      init?: RequestInit,
+    ) => {
+      const url = typeof input === "string" ? input : input.toString();
+      fetchCalls.push({ url, init });
+      return fetchImpl(input, init);
+    }) as unknown as typeof fetch;
     // Env vars take precedence over the rehydrated overrides for some fields;
     // clear them so the credential-store values are what we observe.
     delete process.env.VELLUM_PLATFORM_URL;
     delete process.env.PLATFORM_ORGANIZATION_ID;
     delete process.env.PLATFORM_USER_ID;
+    delete process.env.ASSISTANT_API_KEY;
     // Reset in-memory overrides between tests.
     setPlatformBaseUrl(undefined);
     setPlatformAssistantId(undefined);
@@ -56,6 +75,7 @@ describe("rehydratePlatformCredentials", () => {
   });
 
   afterEach(() => {
+    globalThis.fetch = originalFetch;
     if (originalPlatformUrlEnv === undefined) {
       delete process.env.VELLUM_PLATFORM_URL;
     } else {
@@ -71,6 +91,11 @@ describe("rehydratePlatformCredentials", () => {
     } else {
       process.env.PLATFORM_USER_ID = originalUserEnv;
     }
+    if (originalAssistantApiKeyEnv === undefined) {
+      delete process.env.ASSISTANT_API_KEY;
+    } else {
+      process.env.ASSISTANT_API_KEY = originalAssistantApiKeyEnv;
+    }
     setPlatformBaseUrl(undefined);
     setPlatformAssistantId(undefined);
     setPlatformOrganizationId(undefined);
@@ -122,4 +147,72 @@ describe("rehydratePlatformCredentials", () => {
 
     expect(getPlatformAssistantId()).toBe(ASSISTANT_ID);
   });
+
+  test("trades the assistant API key for ids via platform validate", async () => {
+    mockSecureKeys[credentialKey("vellum", "platform_base_url")] = PROD_URL;
+    mockSecureKeys[credentialKey("vellum", "assistant_api_key")] =
+      "assistant-key";
+    fetchImpl = async () =>
+      new Response(
+        JSON.stringify({
+          assistant_id: ASSISTANT_ID,
+          organization_id: ORG_ID,
+          user_id: USER_ID,
+        }),
+        { status: 200 },
+      );
+
+    await rehydratePlatformCredentials();
+
+    expect(fetchCalls).toHaveLength(1);
+    expect(fetchCalls[0]?.url).toBe(
+      `${PROD_URL}/v1/internal/assistants/validate/`,
+    );
+    const headers = new Headers(fetchCalls[0]?.init?.headers);
+    expect(headers.get("Authorization")).toBe("Api-Key assistant-key");
+    expect(getPlatformAssistantId()).toBe(ASSISTANT_ID);
+    expect(getPlatformOrganizationId()).toBe(ORG_ID);
+    expect(getPlatformUserId()).toBe(USER_ID);
+  });
+
+  test("validate ids win over vault leftovers", async () => {
+    mockSecureKeys[credentialKey("vellum", "platform_base_url")] = PROD_URL;
+    mockSecureKeys[credentialKey("vellum", "assistant_api_key")] =
+      "assistant-key";
+    mockSecureKeys[credentialKey("vellum", "platform_assistant_id")] =
+      "asst-from-vault";
+    fetchImpl = async () =>
+      new Response(
+        JSON.stringify({
+          assistant_id: ASSISTANT_ID,
+          organization_id: ORG_ID,
+          user_id: USER_ID,
+        }),
+        { status: 200 },
+      );
+
+    await rehydratePlatformCredentials();
+
+    expect(getPlatformAssistantId()).toBe(ASSISTANT_ID);
+  });
+
+  test("falls back to the credential store when validate is unreachable", async () => {
+    mockSecureKeys[credentialKey("vellum", "platform_base_url")] = PROD_URL;
+    mockSecureKeys[credentialKey("vellum", "assistant_api_key")] =
+      "assistant-key";
+    mockSecureKeys[credentialKey("vellum", "platform_assistant_id")] =
+      ASSISTANT_ID;
+    mockSecureKeys[credentialKey("vellum", "platform_organization_id")] =
+      ORG_ID;
+    mockSecureKeys[credentialKey("vellum", "platform_user_id")] = USER_ID;
+    fetchImpl = async () => {
+      throw new Error("network down");
+    };
+
+    await rehydratePlatformCredentials();
+
+    expect(getPlatformAssistantId()).toBe(ASSISTANT_ID);
+    expect(getPlatformOrganizationId()).toBe(ORG_ID);
+    expect(getPlatformUserId()).toBe(USER_ID);
+  });
 });

package/src/config/acp-agent-write.ts

@@ -0,0 +1,43 @@
+/**
+ * Raw-config helper shared by the config PATCH and SET routes, the paths that
+ * write a coding agent's entry.
+ */
+
+import { isPlainObject } from "../util/object.js";
+
+/**
+ * Clearing a leaf of a coding agent's entry is a write of `null` - a PATCH of
+ * `{ acp: { agents: { <id>: { model: null } } } }` or a
+ * `config set acp.agents.<id>.model null`. The deep-merge assigns that literal
+ * `null` because the stored value is a scalar, and a SET writes it verbatim by
+ * design. Both `command` and `model` are optional strings in `AcpConfigSchema`,
+ * so a persisted `null` makes every later `loadConfig()` warn and take its
+ * salvage path, dropping the whole `acp` section with the agents defined in it.
+ * Clearing means removing the key, so drop it here on every write path.
+ *
+ * A cleared `command` then reads as an omitted one: a bundled id inherits the
+ * profile's command, and an id that has no profile fails the agents refinement
+ * with a message naming the id, which tells the user more than zod's "expected
+ * string, received null".
+ */
+export function scrubNulledAcpAgentLeaves(raw: Record<string, unknown>): void {
+  const acp = raw.acp;
+  if (!isPlainObject(acp)) {
+    return;
+  }
+  const agents = acp.agents;
+  if (!isPlainObject(agents)) {
+    return;
+  }
+  for (const entry of Object.values(agents)) {
+    if (!isPlainObject(entry)) {
+      continue;
+    }
+    if (entry.command === null) {
+      delete entry.command;
+    }
+    if (entry.model === null) {
+      delete entry.model;
+    }
+  }
+}

package/src/config/acp-defaults.test.ts

@@ -13,15 +13,17 @@ describe("DEFAULT_ACP_AGENT_PROFILES", () => {
     ]);
   });
 
-  test("claude profile uses the @agentclientprotocol adapter binary", () => {
+  test("claude profile uses the @agentclientprotocol adapter binary on opus", () => {
     expect(DEFAULT_ACP_AGENT_PROFILES.claude).toEqual({
       command: "claude-agent-acp",
       args: [],
       description: "Claude Code (via @agentclientprotocol/claude-agent-acp)",
+      model: "opus",
     });
   });
 
   test("codex profile uses the @agentclientprotocol adapter binary", () => {
+    // No model: Codex aliases are its own, so the adapter's default stands.
     expect(DEFAULT_ACP_AGENT_PROFILES.codex).toEqual({
       command: "codex-acp",
       args: [],
@@ -44,11 +46,19 @@ describe("DEFAULT_ACP_AGENT_PROFILES", () => {
 describe("DEFAULT_AGENT_NPM_PACKAGES", () => {
   test("is keyed by command name with the canonical npm package", () => {
     expect(DEFAULT_AGENT_NPM_PACKAGES).toEqual({
-      "claude-agent-acp": "@agentclientprotocol/claude-agent-acp",
-      "codex-acp": "@agentclientprotocol/codex-acp",
+      "claude-agent-acp": "@agentclientprotocol/claude-agent-acp@0.75.1",
+      "codex-acp": "@agentclientprotocol/codex-acp@1.10.0",
     });
   });
 
+  test("every package spec pins an exact version", () => {
+    // A bare name would let a clean install resolve whatever npm calls
+    // latest, which is what the repo's pinning rule exists to prevent.
+    for (const spec of Object.values(DEFAULT_AGENT_NPM_PACKAGES)) {
+      expect(spec).toMatch(/^@?[^@]+@\d+\.\d+\.\d+$/);
+    }
+  });
+
   test("every default profile's command has a matching npm package", () => {
     for (const profile of Object.values(DEFAULT_ACP_AGENT_PROFILES)) {
       expect(DEFAULT_AGENT_NPM_PACKAGES[profile.command]).toBeDefined();

package/src/config/acp-defaults.ts

@@ -1,5 +1,11 @@
 import type { AcpAgentConfig } from "./acp-schema.js";
 
+/**
+ * A bundled profile always names its command; a user entry for the same id
+ * may omit `command` and inherit this one.
+ */
+export type AcpAgentProfile = AcpAgentConfig & { command: string };
+
 // Shared frozen empty args array — these defaults are read by every ACP spawn,
 // so a single accidental `args.push(...)` from one caller would corrupt every
 // subsequent read. Cast through `unknown` because `AcpAgentConfig.args` is
@@ -13,17 +19,22 @@ const FROZEN_EMPTY_ARGS = Object.freeze([] as string[]) as unknown as string[];
  * falls back to this map so common agents like `claude` and `codex` Just Work
  * without requiring per-user config.
  *
- * Keyed by agent id. Deeply frozen — the outer object, each profile, and the
- * `args` arrays — so mutation throws in strict mode rather than silently
+ * A profile's `model` is the model a session of that agent starts on when the
+ * ask names none, and is the rung `acp.agents.<id>.model` fills: a user config
+ * entry that names a model overrides it, one that omits it inherits it.
+ *
+ * Keyed by agent id. Deeply frozen: the outer object, each profile, and the
+ * `args` arrays, so mutation throws in strict mode rather than silently
  * corrupting the shared defaults.
  */
 export const DEFAULT_ACP_AGENT_PROFILES: Readonly<
-  Record<string, AcpAgentConfig>
+  Record<string, AcpAgentProfile>
 > = Object.freeze({
   claude: Object.freeze({
     command: "claude-agent-acp",
     args: FROZEN_EMPTY_ARGS,
     description: "Claude Code (via @agentclientprotocol/claude-agent-acp)",
+    model: "opus",
   }),
   codex: Object.freeze({
     command: "codex-acp",
@@ -33,15 +44,21 @@ export const DEFAULT_ACP_AGENT_PROFILES: Readonly<
 });
 
 /**
- * Single source of truth for adapter binary → npm package name. Automatic
+ * Single source of truth for adapter binary → npm package spec. Automatic
  * installation and the resolver's install hints use this map, so a new
  * adapter only needs one entry here.
  *
  * Keyed by command name (not agent id) so the mapping follows the binary
  * regardless of how a user's config aliases an agent.
+ *
+ * Values carry an exact version, so a clean install lands the adapter version
+ * the daemon was tested against instead of whatever npm calls latest today.
+ * An adapter already on PATH is left alone: installation runs only when
+ * preflight found no binary at all, so this never moves a version the user
+ * installed themselves.
  */
 export const DEFAULT_AGENT_NPM_PACKAGES: Readonly<Record<string, string>> =
   Object.freeze({
-    "claude-agent-acp": "@agentclientprotocol/claude-agent-acp",
-    "codex-acp": "@agentclientprotocol/codex-acp",
+    "claude-agent-acp": "@agentclientprotocol/claude-agent-acp@0.75.1",
+    "codex-acp": "@agentclientprotocol/codex-acp@1.10.0",
   });

package/src/config/acp-schema.test.ts

@@ -0,0 +1,81 @@
+/**
+ * Covers the ACP config leaf that carries model selection, the per-agent
+ * `model`. It is optional with no `.default()`, so an absent value must stay
+ * absent after parsing: the bundled profile supplies the model a session
+ * starts on, and a key materialized as `undefined` would shadow it.
+ *
+ * `command` is optional in the same shape, so an entry for a bundled id can
+ * carry a model and nothing else; the record's own check keeps a command
+ * required for every id that has no bundled profile to inherit one from.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { AcpAgentConfigSchema, AcpConfigSchema } from "./acp-schema.js";
+
+describe("AcpConfigSchema", () => {
+  test("populates defaults for an empty config", () => {
+    expect(AcpConfigSchema.parse({})).toEqual({
+      maxConcurrentSessions: 4,
+      agents: {},
+    });
+  });
+});
+
+describe("AcpConfigSchema agents", () => {
+  test("a bundled id's entry may omit command and name only a model", () => {
+    const parsed = AcpConfigSchema.parse({
+      agents: { claude: { model: "sonnet" } },
+    });
+
+    expect(parsed.agents).toEqual({ claude: { args: [], model: "sonnet" } });
+    expect("command" in parsed.agents.claude!).toBe(false);
+  });
+
+  test("an id with no bundled profile needs a command", () => {
+    const result = AcpConfigSchema.safeParse({
+      agents: { mine: { model: "sonnet" } },
+    });
+
+    expect(result.success).toBe(false);
+    if (result.success) {
+      return;
+    }
+    expect(result.error.issues.map((issue) => issue.path)).toEqual([
+      ["agents", "mine", "command"],
+    ]);
+    expect(result.error.issues[0]?.message).toContain("acp.agents.mine");
+  });
+
+  test("an id naming an Object.prototype member inherits no command", () => {
+    expect(
+      AcpConfigSchema.safeParse({ agents: { constructor: { model: "x" } } })
+        .success,
+    ).toBe(false);
+  });
+});
+
+describe("AcpAgentConfigSchema", () => {
+  test("round-trips a per-agent model override", () => {
+    expect(
+      AcpAgentConfigSchema.parse({
+        command: "claude-agent-acp",
+        model: "opus",
+      }),
+    ).toEqual({ command: "claude-agent-acp", args: [], model: "opus" });
+  });
+
+  test("leaves model unset when omitted, so a bundled profile's shows through", () => {
+    const parsed = AcpAgentConfigSchema.parse({ command: "claude-agent-acp" });
+
+    expect(parsed.model).toBeUndefined();
+    expect("model" in parsed).toBe(false);
+  });
+
+  test("rejects a non-string model", () => {
+    expect(
+      AcpAgentConfigSchema.safeParse({ command: "claude-agent-acp", model: 3 })
+        .success,
+    ).toBe(false);
+  });
+});

package/src/config/acp-schema.ts

@@ -1,8 +1,15 @@
 import { z } from "zod";
 
-const AcpAgentConfigSchema = z
+import { DEFAULT_ACP_AGENT_PROFILES } from "./acp-defaults.js";
+
+export const AcpAgentConfigSchema = z
   .object({
-    command: z.string().describe("Command to spawn the ACP agent process"),
+    command: z
+      .string()
+      .optional()
+      .describe(
+        "Command to spawn the ACP agent process. Required unless the id has a bundled profile, whose command is inherited when this is unset",
+      ),
     args: z
       .array(z.string())
       .default([])
@@ -15,6 +22,12 @@ const AcpAgentConfigSchema = z
       .record(z.string(), z.string())
       .optional()
       .describe("Environment variables set for the agent process"),
+    model: z
+      .string()
+      .optional()
+      .describe(
+        "Model sessions of this agent start on when the ask names none (an adapter-reported alias such as 'opus' or 'sonnet' for Claude, not an Assistant catalog id). Overrides the bundled profile's value; unset inherits it.",
+      ),
   })
   .describe("Configuration for an individual ACP agent");
 
@@ -30,6 +43,21 @@ export const AcpConfigSchema = z
       ),
     agents: z
       .record(z.string(), AcpAgentConfigSchema)
+      .superRefine((agents, ctx) => {
+        for (const [id, agent] of Object.entries(agents)) {
+          if (
+            agent.command !== undefined ||
+            Object.hasOwn(DEFAULT_ACP_AGENT_PROFILES, id)
+          ) {
+            continue;
+          }
+          ctx.addIssue({
+            code: "custom",
+            path: [id, "command"],
+            message: `acp.agents.${id} needs a command: only the bundled ids (${Object.keys(DEFAULT_ACP_AGENT_PROFILES).join(", ")}) inherit one`,
+          });
+        }
+      })
       .default({})
       .describe("Map of agent names to their configurations"),
   })

package/src/config/bundled-skills/acp/SKILL.md

@@ -23,6 +23,18 @@ Use `acp_spawn` to delegate a coding task to an external agent. The agent runs a
 
 Users can refer to agents by natural names: "claude code", "codex cli", and "openai codex" all resolve to the canonical `claude` and `codex` ids (unless the user's config defines an agent literally keyed by that name, which always wins).
 
+## Choosing a model
+
+Claude runs on Opus unless the user names a model; every other agent starts on its own default.
+
+When the user does name one, pass it as `model` on `acp_spawn`. Model names are the agent's own vocabulary, not Assistant model ids: an alias such as `default`, `sonnet`, `opus`, `haiku`, `fable`, or `opusplan` for Claude, or a full model id. Pass what the user said and let the agent resolve it.
+
+The spawn result reports `requestedModel` and `effectiveModel`. Treat `effectiveModel` as authoritative for the top-level ACP session. Never infer that model from the task text or from a nested subagent. When `requestedModel` is non-null and differs from `effectiveModel`, state which model the session is actually running on and relay `modelWarning` when present.
+
+If the agent refuses the model, or advertises no model selector, the spawn result says so: relay it in one sentence and carry on, because the session is live on the agent's own model.
+
+A session runs on the model it started on, so a different model means a new `acp_spawn`. A standing default per agent lives in the config at `acp.agents.<id>.model`.
+
 ## When the user names Claude Code or Codex
 
 If they name Claude Code or Codex without asking you to run it here (for example they say that tool will do the work), offer once, in one short sentence, that you can connect and run it in this conversation. Then continue with whatever they were doing.
@@ -35,21 +47,23 @@ If they name Claude Code or Codex without asking you to run it here (for example
 
 ACP is always available - default profiles for `claude` and `codex` ship out-of-box, so no config edit is needed to start. First-time setup is just making the adapter binary available, then spawning:
 
-1. Install the adapter binary if it's missing. This happens automatically: when `acp_spawn` finds the agent's binary missing from PATH, the assistant installs it once via a sandboxed bun global install and proceeds in the same call (see "Automatic adapter availability" below).
+1. Install the adapter binary if it's missing. This happens automatically: when `acp_spawn` finds the agent's binary missing from PATH, the assistant installs the pinned version via a sandboxed bun global install and proceeds in the same call (see "Automatic adapter availability" below).
 
 2. Call `acp_spawn`. Do NOT run `vellum sleep && vellum wake` - that kills the conversation.
 
 ## Automatic adapter availability
 
-When `acp_spawn` finds the agent's binary missing from PATH, the assistant installs it once via a sandboxed bun global install and then runs the real installed binary. The install runs in a fresh empty temporary directory (never the task's project directory), with known secrets stripped from the installer environment and the registry pinned to the public npm registry, so a malicious project directory cannot hijack package resolution or capture a token. After this one-time install, the adapter is a normal trusted binary on PATH and every later spawn (and resume) uses it directly.
+When an agent's binary is missing from PATH, the assistant installs the adapter version it was built against via a sandboxed bun global install and then runs the real installed binary. The install runs in a fresh empty temporary directory (never the task's project directory), with known secrets stripped from the installer environment and the registry pinned to the public npm registry, so a malicious project directory cannot hijack package resolution or capture a token.
+
+An adapter already on PATH is left alone, whoever installed it: the install runs only when preflight found no binary at all.
 
 Only the allowlisted out-of-box packages are ever installed this way (`@agentclientprotocol/claude-agent-acp`, `@agentclientprotocol/codex-acp`); user-configured agents with custom commands are never installed automatically.
 
-Manual installation is fallback guidance for unusual setups: bun unavailable, restricted global installs, or an auto-install failure (the failure reason is surfaced in the tool result).
+Manual installation is fallback guidance for unusual setups: bun unavailable, restricted global installs, or an auto-install failure (the failure reason is surfaced in the tool result). Install the pinned version below rather than `@latest`, so the adapter matches what the assistant was built against.
 
 ```bash
-bun add -g @agentclientprotocol/claude-agent-acp   # claude
-bun add -g @agentclientprotocol/codex-acp          # codex
+bun add -g @agentclientprotocol/claude-agent-acp@0.75.1   # claude
+bun add -g @agentclientprotocol/codex-acp@1.10.0          # codex
 ```
 
 ## Claude setup
@@ -84,20 +98,14 @@ Do NOT put API keys (or any secret) in the workspace config file - secrets never
 
 - Two agents are supported out-of-box: `claude` (via the `claude-agent-acp` adapter) and `codex` (via the `codex-acp` adapter).
 - NEVER use `claude`, `claude -p`, `claude --acp`, or the bare `codex` CLI as the ACP `command`. Claude and Codex only speak the protocol through their dedicated `*-acp` adapters.
-- Default profiles for both ship out-of-box. Users only need an `agents.<id>` entry in config if they want to override the defaults (e.g. point to a custom binary path or pass extra args/env). An `acp.agents.<id>` entry replaces the bundled default entirely (no field merge), so any override must spell out the full `command` and `args`, not just the field being changed.
+- Default profiles for both ship out-of-box. Users only need an `agents.<id>` entry in config if they want to override the defaults (e.g. point to a custom binary path or pass extra args/env). An entry that still runs the bundled adapter, whether it omits `command` or names the same binary by name or full path, inherits the `command`, `description` and `model` it leaves out, so a single-field change such as `acp.agents.claude.model` is all it takes. An entry that points the id at a different binary stands on its own, so it must spell out everything it needs, `command` included.
 - NEVER change an existing ACP config to use a different command. If the config already has `claude-agent-acp` or `codex-acp`, leave it alone.
 
 ## Updating an adapter
 
-Adapters are installed automatically when missing. To update an installed adapter, ask the user first and use its owning package manager. For bun installations:
-
-```bash
-bun add -g @agentclientprotocol/claude-agent-acp@latest
-# or
-bun add -g @agentclientprotocol/codex-acp@latest
-```
+Adapter upgrades ship with Assistant releases: the pinned version is what a missing adapter is installed at. An adapter already on PATH is never replaced, so a user who upgrades one themselves keeps that version.
 
-Codex uses the adapter's bundled dependency by default, within the version range declared by the adapter. If `CODEX_PATH` selects a separate CLI, update that installation separately. Verify the required model with a fresh `acp_spawn` call after updating.
+Codex uses the adapter's bundled dependency by default, within the version range declared by the adapter. If `CODEX_PATH` selects a separate CLI, update that installation separately.
 
 ## When to use acp_steer vs acp_spawn
 

package/src/config/bundled-skills/acp/TOOLS.json

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "acp_spawn",
-      "description": "Spawn an external coding agent (e.g. Claude Code, Codex) via ACP to work on a task. Default profiles ship for `claude` (`claude-agent-acp`) and `codex` (`codex-acp`); the assistant resolves the agent id to the right binary. The agent runs as a subprocess and streams results back. Use this when you want to delegate a coding task to an external agent that has its own tools, file editing, and terminal access. If a default agent's binary is missing, the assistant installs it once via a sandboxed bun global install and proceeds in the same call; if that fails (e.g. bun unavailable), an actionable install hint is returned - do NOT alter `agents.<id>.command` to swap binaries.",
+      "description": "Spawn an external coding agent (e.g. Claude Code, Codex) via ACP to work on a task. Default profiles ship for `claude` (`claude-agent-acp`) and `codex` (`codex-acp`); the assistant resolves the agent id to the right binary. The result reports `requestedModel` and the adapter-reported `effectiveModel`; treat `effectiveModel` as authoritative for the top-level ACP session. The agent runs as a subprocess and streams results back. Use this when you want to delegate a coding task to an external agent that has its own tools, file editing, and terminal access. If a default agent's binary is missing, the assistant installs it once via a sandboxed bun global install and proceeds in the same call; if that fails (e.g. bun unavailable), an actionable install hint is returned - do NOT alter `agents.<id>.command` to swap binaries.",
       "category": "orchestration",
       "risk": "high",
       "input_schema": {
@@ -20,6 +20,10 @@
           "cwd": {
             "type": "string",
             "description": "Working directory for the agent. This determines where the agent runs and where its session is stored. Set this to the project/repo root the user wants the agent to work in. Defaults to current conversation's working directory."
+          },
+          "model": {
+            "type": "string",
+            "description": "Model the agent should run on, passed ONLY when the user named one (e.g. 'opus' for Claude). Left off, a Claude session runs on Opus and every other agent on its own default. If the agent refuses the value, or advertises no model selector, the result says so and the session runs on its own model."
           }
         },
         "required": ["task"]