@vellumai/assistant 0.8.8 → 0.8.9-staging.2

package/src/cli/lib/search-plugins.ts

@@ -1,10 +1,17 @@
 /**
- * Search for plugin directories in the canonical GitHub source.
+ * Search the installable plugin catalog in the canonical GitHub source.
  *
- * Lists `vellum-ai/vellum-assistant/experimental/plugins/` at the configured
- * git ref and filters the directory entries by case-insensitive ECMAScript
- * regex. A plain query like `"memory"` matches anywhere in the name; anchors
- * like `"^simple"` work without escaping.
+ * The catalog is the union of two sources, both fetched from the repo at the
+ * configured git ref:
+ *   1. First-party plugins — directories under
+ *      `vellum-ai/vellum-assistant/experimental/plugins/`.
+ *   2. Whitelisted external ecosystem plugins — entries in the curated
+ *      `experimental/plugins/marketplace.json` manifest (see
+ *      {@link ./plugin-marketplace}).
+ *
+ * Entries are filtered by case-insensitive ECMAScript regex against the
+ * plugin name. A plain query like `"memory"` matches anywhere in the name;
+ * anchors like `"^simple"` work without escaping.
  *
  * Designed for direct programmatic use. The CLI command
  * `assistant plugins search <query>` is a thin wrapper that supplies
@@ -15,6 +22,10 @@
 
 import type { FetchLike } from "./install-from-github.js";
 import { DEFAULT_PLUGIN_REF } from "./install-from-github.js";
+import {
+  fetchMarketplaceEntries,
+  type MarketplaceEntry,
+} from "./plugin-marketplace.js";
 
 // Re-export the dep-injection type so callers can grab everything they need
 // from one module rather than reaching into `install-from-github.js`.
@@ -50,12 +61,33 @@ export interface SearchPluginsDeps {
   readonly fetch: FetchLike;
 }
 
-/** One matching plugin directory. */
+/** Where a catalog match comes from. */
+export type PluginMatchSource =
+  | { readonly kind: "first-party" }
+  | {
+      readonly kind: "github";
+      /** `owner/repo` of the external plugin repository. */
+      readonly repo: string;
+      /** Directory within the repo, when the plugin is not at the root. */
+      readonly path?: string;
+      /** Pinned git ref the plugin is fetched from. */
+      readonly ref: string;
+    };
+
+/** One matching catalog entry. */
 export interface PluginSearchMatch {
-  /** Directory name under `experimental/plugins/`. */
+  /** Install name — `assistant plugins install <name>` resolves to it. */
   readonly name: string;
-  /** Path within the repo (e.g. `experimental/plugins/<name>`). */
+  /**
+   * Human-readable origin of the entry: the repo-relative path for
+   * first-party plugins (e.g. `experimental/plugins/<name>`) or a
+   * `github:owner/repo@ref` locator for external ones.
+   */
   readonly path: string;
+  /** Short description, when known (external entries only today). */
+  readonly description?: string;
+  /** Discriminated origin, so callers can render/install accordingly. */
+  readonly source: PluginMatchSource;
 }
 
 /** Search result envelope. */
@@ -75,12 +107,28 @@ export class InvalidSearchPatternError extends Error {
 }
 
 /**
- * List directories under `experimental/plugins/` at {@link opts.ref} and
- * filter by {@link opts.query}.
- *
- * Only `type === "dir"` entries are returned — `experimental/plugins/`
- * follows a convention where each plugin lives in its own directory, so
- * loose files at the prefix are not plugins.
+ * The catalog source (GitHub) was reachable but refused or could not serve
+ * the request right now — rate limiting (HTTP 403 with the rate-limit budget
+ * exhausted, or 429) or an upstream 5xx. Distinct from a hard 404 on the
+ * plugins prefix (a real "source gone" misconfiguration): a transient
+ * upstream failure should surface as a retryable "temporarily unavailable"
+ * rather than a generic internal error, and is a candidate for serving a
+ * stale cached catalog.
+ */
+export class PluginCatalogUnavailableError extends Error {
+  /** Upstream HTTP status that triggered the failure. */
+  readonly status: number;
+  constructor(message: string, status: number) {
+    super(message);
+    this.name = "PluginCatalogUnavailableError";
+    this.status = status;
+  }
+}
+
+/**
+ * Build the catalog at {@link opts.ref} and return the entries whose name
+ * matches {@link opts.query} (case-insensitive ECMAScript regex; an empty
+ * query matches everything).
  */
 export async function searchPlugins(
   opts: SearchPluginsOptions,
@@ -92,17 +140,119 @@ export async function searchPlugins(
   // the network — keeps "user typo" cheap to recover from.
   const matcher = buildMatcher(opts.query);
 
-  const entries = await listDir(PLUGIN_SOURCE_PATH_PREFIX, ref, deps.fetch);
+  const { matches: catalog } = await loadPluginCatalog({ ref }, deps);
+  const matches = catalog.filter((m) => matcher(m.name));
+
+  return { query: opts.query, ref, matches };
+}
+
+/**
+ * Validate that {@link query} compiles as a case-insensitive ECMAScript regex,
+ * throwing {@link InvalidSearchPatternError} if not. Lets a caching caller
+ * (the daemon) reject a malformed query before loading the catalog, so a typo
+ * is a cheap deterministic 400 rather than a wasted GitHub request.
+ */
+export function assertValidSearchPattern(query: string): void {
+  buildMatcher(query);
+}
+
+/**
+ * Filter a pre-loaded {@link PluginCatalog} by {@link query}, compiling it as
+ * a case-insensitive ECMAScript regex (an empty query matches everything).
+ * Lets a caching caller (the daemon) reuse one catalog load across many
+ * searches. Throws {@link InvalidSearchPatternError} on a malformed pattern.
+ */
+export function filterPluginCatalog(
+  catalog: PluginCatalog,
+  query: string,
+): PluginSearchMatch[] {
+  const matcher = buildMatcher(query);
+  return catalog.matches.filter((m) => matcher(m.name));
+}
+
+/** The full, unfiltered catalog at a given ref. */
+export interface PluginCatalog {
+  readonly ref: string;
+  /** Every catalog entry, deduped and sorted alphabetically by name. */
+  readonly matches: readonly PluginSearchMatch[];
+}
+
+/**
+ * Build the full catalog at {@link opts.ref}: every first-party plugin
+ * directory under `experimental/plugins/` merged with every whitelisted
+ * external entry in the marketplace manifest.
+ *
+ * The result is **query-independent** — `searchPlugins` applies the regex
+ * filter in memory afterwards. That separation is what lets a long-lived
+ * caller (the daemon) cache one catalog load and serve any number of
+ * searches from it without re-hitting GitHub (see {@link ./plugin-catalog-cache}).
+ */
+export async function loadPluginCatalog(
+  opts: { readonly ref?: string },
+  deps: SearchPluginsDeps,
+): Promise<PluginCatalog> {
+  const ref = opts.ref ?? DEFAULT_PLUGIN_REF;
+
+  const [entries, marketplace] = await Promise.all([
+    listDir(PLUGIN_SOURCE_PATH_PREFIX, ref, deps.fetch),
+    fetchMarketplaceSafe(deps.fetch, ref),
+  ]);
 
   const matches: PluginSearchMatch[] = [];
+  const seen = new Set<string>();
   for (const entry of entries) {
     if (entry.type !== "dir") continue;
-    if (!matcher(entry.name)) continue;
-    matches.push({ name: entry.name, path: entry.path });
+    matches.push({
+      name: entry.name,
+      path: entry.path,
+      source: { kind: "first-party" },
+    });
+    seen.add(entry.name);
   }
+
+  for (const entry of marketplace) {
+    // First-party plugins win a name collision — the curated manifest is
+    // additive, never an override of what ships in-repo.
+    if (seen.has(entry.name)) continue;
+    matches.push(marketplaceMatch(entry));
+    seen.add(entry.name);
+  }
+
   matches.sort((a, b) => a.name.localeCompare(b.name));
 
-  return { query: opts.query, ref, matches };
+  return { ref, matches };
+}
+
+/**
+ * Project a marketplace entry onto the catalog match shape, building a
+ * `github:owner/repo[/path]@ref` locator for display.
+ */
+function marketplaceMatch(entry: MarketplaceEntry): PluginSearchMatch {
+  const { repo, path, ref } = entry.source;
+  const locator = `github:${repo}${path ? `/${path}` : ""}@${ref}`;
+  return {
+    name: entry.name,
+    path: locator,
+    description: entry.description,
+    source: { kind: "github", repo, path, ref },
+  };
+}
+
+/**
+ * Fetch the marketplace manifest, degrading to an empty whitelist on any
+ * failure. The manifest is supplementary to the first-party listing, so a
+ * missing or malformed manifest must never break the core catalog — mirroring
+ * the daemon's "never block over a subsystem failure" philosophy.
+ */
+async function fetchMarketplaceSafe(
+  fetchFn: FetchLike,
+  ref: string,
+): Promise<readonly MarketplaceEntry[]> {
+  try {
+    return await fetchMarketplaceEntries({ fetch: fetchFn }, { ref });
+  } catch {
+    return [];
+  }
 }
 
 function buildMatcher(query: string): (name: string) => boolean {
@@ -127,13 +277,17 @@ async function listDir(
 
   const res = await githubFetch(url, fetchFn);
   if (!res.ok) {
-    // Unlike `installPlugin`, where 404 on a specific plugin name is a
-    // legitimate "not found" outcome, 404 on the plugins prefix itself
-    // means the canonical source path is gone — surface it as an error
-    // rather than silently returning empty results.
-    throw new Error(
-      `GitHub contents listing failed for ${apiPath} @ ${ref}: HTTP ${res.status}`,
-    );
+    const detail = `GitHub contents listing failed for ${apiPath} @ ${ref}: HTTP ${res.status}`;
+    // Rate limiting (403 with the budget exhausted, or 429) and upstream
+    // 5xx are transient — surface them as a retryable "temporarily
+    // unavailable" so the caller can serve a stale cache and the route can
+    // map to 503 instead of a misleading 500. A 404 on the plugins prefix
+    // itself means the canonical source path is gone (a real
+    // misconfiguration), so it stays a hard error.
+    if (isTransientUpstreamStatus(res)) {
+      throw new PluginCatalogUnavailableError(detail, res.status);
+    }
+    throw new Error(detail);
   }
 
   const body = (await res.json()) as unknown;
@@ -150,10 +304,22 @@ async function listDir(
  * request. Unauthenticated — the canonical source is a public repo, mirroring
  * `installPlugin` which uses the same envelope.
  */
-async function githubFetch(
-  url: string,
-  fetchFn: FetchLike,
-): Promise<Response> {
+/**
+ * Whether a non-OK GitHub response should be treated as a transient
+ * "temporarily unavailable" failure rather than a hard error. Covers
+ * rate limiting (429, or 403 once the rate-limit budget is exhausted) and
+ * upstream server errors (5xx). A bare 403 without the rate-limit signal
+ * (e.g. a genuine permissions problem) is not treated as transient.
+ */
+function isTransientUpstreamStatus(res: Response): boolean {
+  if (res.status === 429 || res.status >= 500) return true;
+  if (res.status === 403) {
+    return res.headers.get("x-ratelimit-remaining") === "0";
+  }
+  return false;
+}
+
+async function githubFetch(url: string, fetchFn: FetchLike): Promise<Response> {
   return fetchFn(url, {
     headers: {
       Accept: "application/vnd.github+json",

package/src/config/__tests__/feature-flag-registry-guard.test.ts

@@ -85,8 +85,8 @@ describe("unified feature flag registry guard", () => {
       ) {
         violations.push(`${prefix}: missing or non-string 'description'`);
       }
-      if (typeof flag.defaultEnabled !== "boolean") {
-        violations.push(`${prefix}: missing or non-boolean 'defaultEnabled'`);
+      if (typeof flag.defaultEnabled !== "boolean" && typeof flag.defaultEnabled !== "string") {
+        violations.push(`${prefix}: missing or invalid 'defaultEnabled' (expected boolean or string)`);
       }
     }
 

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

@@ -10,6 +10,7 @@ describe("DEFAULT_ACP_AGENT_PROFILES", () => {
     expect(Object.keys(DEFAULT_ACP_AGENT_PROFILES).sort()).toEqual([
       "claude",
       "codex",
+      "gemini",
     ]);
   });
 
@@ -29,6 +30,14 @@ describe("DEFAULT_ACP_AGENT_PROFILES", () => {
     });
   });
 
+  test("gemini profile speaks native ACP via gemini --acp (no adapter binary)", () => {
+    expect(DEFAULT_ACP_AGENT_PROFILES.gemini).toEqual({
+      command: "gemini",
+      args: ["--acp"],
+      description: "Google Gemini CLI (native ACP via gemini --acp)",
+    });
+  });
+
   test("is deeply frozen so mutation throws in strict mode", () => {
     expect(Object.isFrozen(DEFAULT_ACP_AGENT_PROFILES)).toBe(true);
     for (const profile of Object.values(DEFAULT_ACP_AGENT_PROFILES)) {
@@ -46,6 +55,7 @@ describe("DEFAULT_AGENT_NPM_PACKAGES", () => {
     expect(DEFAULT_AGENT_NPM_PACKAGES).toEqual({
       "claude-agent-acp": "@agentclientprotocol/claude-agent-acp",
       "codex-acp": "@zed-industries/codex-acp",
+      gemini: "@google/gemini-cli",
     });
   });
 

package/src/config/acp-defaults.ts

@@ -30,6 +30,11 @@ export const DEFAULT_ACP_AGENT_PROFILES: Readonly<
     args: FROZEN_EMPTY_ARGS,
     description: "OpenAI Codex CLI (via @zed-industries/codex-acp)",
   }),
+  gemini: Object.freeze({
+    command: "gemini",
+    args: Object.freeze(["--acp"]) as unknown as string[],
+    description: "Google Gemini CLI (native ACP via gemini --acp)",
+  }),
 });
 
 /**
@@ -44,4 +49,5 @@ export const DEFAULT_AGENT_NPM_PACKAGES: Readonly<Record<string, string>> =
   Object.freeze({
     "claude-agent-acp": "@agentclientprotocol/claude-agent-acp",
     "codex-acp": "@zed-industries/codex-acp",
+    gemini: "@google/gemini-cli",
   });

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

@@ -7,29 +7,30 @@ metadata:
   vellum:
     display-name: "ACP"
     activation-hints:
-      - "User wants to delegate a coding task to Claude Code, Codex, or another ACP agent"
+      - "User asks to use Claude Code, Codex, or Gemini to do something"
+      - "User wants to delegate a coding task to Claude Code, Codex, Gemini, or another ACP agent"
+      - "User wants to hand a coding task to another agent and check on it later"
       - "User wants to spawn an external coding agent that runs autonomously and streams results back"
-      - "User mentions ACP, claude-agent-acp, codex-acp, or running multiple coding agents in parallel"
+      - "User mentions ACP, claude-agent-acp, codex-acp, gemini --acp, or running multiple coding agents in parallel"
     avoid-when:
-      - "Task is small enough to do inline with the assistant's own tools — no need for an external agent"
+      - "Task is small enough to do inline with the assistant's own tools - no need for an external agent"
 ---
 
-ACP agent orchestration - spawn external coding agents (Claude Code, Codex, etc.) to work on tasks via the Agent Client Protocol. Each agent runs as its own subprocess speaking ACP over stdio and streams results back into the conversation.
+ACP agent orchestration - spawn external coding agents (Claude Code, Codex, Gemini) to work on tasks via the Agent Client Protocol. Each agent runs as its own subprocess speaking ACP over stdio and streams results back into the conversation.
 
 ## Usage
 
 Use `acp_spawn` to delegate a coding task to an external agent. The agent runs as a subprocess speaking the ACP protocol over stdio and streams results back.
 
+Users can refer to agents by natural names: "claude code", "codex cli", "openai codex", "gemini cli", and "google gemini" all resolve to the canonical `claude`, `codex`, and `gemini` ids (unless the user's config defines an agent literally keyed by that name, which always wins).
+
 ## First-time setup
 
-When the user first tries to use ACP and it's not configured, set it up automatically:
+When the user first tries to use ACP and it's not enabled, set it up automatically:
 
-1. **Check if `claude-agent-acp` is installed** by running `which claude-agent-acp`. If not found, install it:
-   ```bash
-   npm i -g @agentclientprotocol/claude-agent-acp
-   ```
+1. **Enable the `acp` feature flag** (the primary enablement path). Either PATCH it via the gateway feature-flags endpoint or direct the user to toggle "ACP Coding Agents" in the client's feature flags UI. Flag changes are hot-refreshed in the assistant - no restart needed.
 
-2. **Enable ACP in the workspace config** by editing the config file to add the `acp` section. Default profiles for `claude` and `codex` ship out-of-box, so the minimal config is just:
+   As a supported alternative, edit the workspace config file to add the `acp` section. Default profiles for `claude`, `codex`, and `gemini` ship out-of-box, so the minimal config is just:
    ```json
    {
      "acp": {
@@ -38,57 +39,108 @@ When the user first tries to use ACP and it's not configured, set it up automati
      }
    }
    ```
+   If you go the config route, **wait a few seconds** for the config watcher to pick up the change (it hot-reloads automatically - no restart needed).
 
-3. **Wait a few seconds** for the config watcher to pick up the change (it hot-reloads automatically - no restart needed).
+2. Then retry the `acp_spawn` call. Do NOT run `vellum sleep && vellum wake` - that kills the conversation.
 
-4. Then retry the `acp_spawn` call. Do NOT run `vellum sleep && vellum wake` - that kills the conversation.
+No manual binary installation is needed first: missing adapter binaries are installed automatically (see below).
 
-## Codex setup
+## Automatic adapter availability
 
-To use Codex via ACP, both the `codex-acp` adapter and the underlying `codex` CLI must be on PATH:
+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 the Claude/Gemini 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.
 
-1. **Install the ACP adapter:**
-   ```bash
-   npm i -g @zed-industries/codex-acp
-   ```
-   This provides the `codex-acp` binary that the assistant spawns.
+Only the allowlisted out-of-box packages are ever installed this way (`@agentclientprotocol/claude-agent-acp`, `@zed-industries/codex-acp`, `@google/gemini-cli`); 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).
+
+```bash
+bun add -g @agentclientprotocol/claude-agent-acp   # claude
+bun add -g @zed-industries/codex-acp               # codex
+bun add -g @google/gemini-cli                       # gemini
+```
+
+## Claude setup
 
-2. **Install the Codex CLI** (version 0.111 or higher) via OpenAI's distribution channel of choice. The `codex-acp` adapter shells out to `codex` under the hood and will fail if it isn't on PATH.
+The `claude-agent-acp` adapter requires a Claude OAuth token. Store it once in the credential store and every spawn injects it as `CLAUDE_CODE_OAUTH_TOKEN` automatically:
 
-3. **Authenticate.** The `codex-acp` adapter inherits whatever auth the underlying `codex` CLI uses. Typical flows:
+```bash
+assistant credentials set --service acp --field claude_oauth_token <token>
+```
+
+When the token is missing, do NOT ask the user to paste it into chat. Collect it via the secret-request flow instead: `credential_store` with action `prompt`, service `acp`, field `claude_oauth_token`. That prompts the user through a secure UI so the token never enters the conversation or the workspace config. Users generate the token by running `claude setup-token` on a machine where they are logged in to Claude.
+
+## Codex setup
+
+The `codex-acp` adapter is installed automatically when missing, but it shells out to the underlying `codex` CLI, which must also be on PATH:
+
+1. **Install the Codex CLI** (version 0.111 or higher) via OpenAI's distribution channel of choice. The adapter will fail if `codex` isn't on PATH.
+
+2. **Authenticate.** The `codex-acp` adapter inherits whatever auth the underlying `codex` CLI uses. Typical flows:
    - `codex login` (OAuth)
    - `CODEX_API_KEY` environment variable
    - `OPENAI_API_KEY` environment variable
 
-If `codex-acp` isn't on PATH when the user asks for it, the assistant will surface the install hint via `acp_list_agents`.
+## Gemini setup
+
+Gemini CLI speaks ACP natively (`gemini --acp`) - there is no separate adapter binary. The CLI itself is installed from `@google/gemini-cli` when missing.
+
+**Authenticate** with an API key through the credential store (the primary path):
+
+```bash
+assistant credentials set --service acp --field gemini_api_key <key>
+```
+
+Or collect the key via the secret-request flow: `credential_store` with action `prompt`, service `acp`, field `gemini_api_key`. Either way the key never appears in chat or workspace config, and every spawn injects it as `GEMINI_API_KEY` automatically. The key is optional - a spawn proceeds without it when the vault has no entry.
+
+The alternative is browser OAuth: run `gemini` once interactively and complete the sign-in flow. This is impractical on hosted assistants (no browser), so prefer the credential store there.
+
+Do NOT put API keys (or any secret) in the workspace config file - secrets never belong in the workspace directory. Use the credential store instead.
+
+A workspace `acp.agents.gemini` override is only for non-secret customization (custom binary path, extra args, non-secret env vars). It must spell out the full `command` and `args` - see "Critical: correct agent command" below for the replace-not-merge rule:
+  ```json
+  {
+    "acp": {
+      "agents": {
+        "gemini": {
+          "command": "gemini",
+          "args": ["--acp"],
+          "env": { "NO_COLOR": "1" }
+        }
+      }
+    }
+  }
+  ```
 
 ## Critical: correct agent command
 
-- `claude-agent-acp` and `codex-acp` are the two supported adapter binaries today. They are what speak the ACP JSON-RPC protocol.
-- NEVER use `claude`, `claude -p`, `claude --acp`, the bare `codex` CLI, or any other command as the ACP `command`. Only the dedicated `*-acp` adapters speak the protocol.
-- Default profiles for `claude` and `codex` 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).
-- 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.
+- Three agents are supported out-of-box: `claude` (via the `claude-agent-acp` adapter), `codex` (via the `codex-acp` adapter), and `gemini` (via `gemini --acp` - Gemini speaks ACP natively, no adapter binary).
+- 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. Gemini is the exception: the `gemini` CLI itself speaks ACP when launched with `--acp`.
+- Default profiles for all three 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.
+- NEVER change an existing ACP config to use a different command. If the config already has `claude-agent-acp`, `codex-acp`, or `gemini`, leave it alone.
 
-## Updating the adapter
+## Updating an adapter
 
-If `acp_spawn` reports that an adapter is outdated, ask the user before updating. To update:
+Adapters are installed once via a bun global install. To update one to the latest version, ask the user first, then re-install it globally:
 
 ```bash
-npm i -g @agentclientprotocol/claude-agent-acp@latest
+bun add -g @agentclientprotocol/claude-agent-acp@latest
+# or
+bun add -g @zed-industries/codex-acp@latest
 # or
-npm i -g @zed-industries/codex-acp@latest
+bun add -g @google/gemini-cli@latest
 ```
 
 Then retry the `acp_spawn` call.
 
 ## When to use acp_steer vs acp_spawn
 
-- **`acp_steer` interrupts the in-flight prompt.** Use it to course-correct a running agent ("stop, do X instead"). It cancels whatever the agent is currently working on and replaces it with the new instruction.
-- **For follow-ups after the current task** ("also do Y when you're done"), do NOT use `acp_steer`. Wait for the `acp_session_completed` notification and call `acp_spawn` again with the new task. Queued follow-ups in the same session are not yet supported.
+- **On a running session, `acp_steer` interrupts the in-flight prompt.** Use it to course-correct ("stop, do X instead"). It cancels whatever the agent is currently working on and replaces it with the new instruction. Queued follow-ups behind a running prompt are not supported - wait for the `acp_session_completed` notification instead.
+- **On a completed (or assistant-restarted) session, `acp_steer` transparently resumes it.** The session is restored from persisted history via ACP session loading when the agent supports it, and the new instruction runs with the agent's full prior context. This is the primary way to do follow-up work on an existing session id - prefer it over spawning a fresh session that would lose context.
+- If resume isn't possible (the session was recorded before resume support and has no working directory, or the agent lacks the capability), the error explains why; fall back to `acp_spawn`. For claude sessions, the completion message also includes a `claude --resume <id>` CLI hint for resuming outside the assistant.
 
 ## Discoverability
 
-Use `acp_list_agents` to see what's set up and what's missing. It returns each available agent profile, whether ACP is enabled, whether the agent's binary is on PATH, and an install hint if not. This is the right tool to call when deciding between `claude` and `codex`, or when the user asks "what coding agents do I have?"
+Use `acp_list_agents` to see what's set up and what's missing. It returns each available agent profile, whether ACP is enabled, whether the agent's binary is on PATH (missing binaries are installed automatically on first spawn), and an install hint if not. This is the right tool to call when deciding between `claude`, `codex`, and `gemini`, or when the user asks "what coding agents do I have?"
 
 ## Working directory
 

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 adapter 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 binary is missing, the call returns an actionable install hint — do NOT alter `agents.<id>.command` to swap binaries. If ACP is disabled, follow the setup instructions in SKILL.md.",
+      "description": "Spawn an external coding agent (e.g. Claude Code, Codex, Gemini) via ACP to work on a task. Default profiles ship for `claude` (`claude-agent-acp`), `codex` (`codex-acp`), and `gemini` (`gemini --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. If ACP is disabled, follow the setup instructions in SKILL.md.",
       "category": "orchestration",
       "risk": "high",
       "input_schema": {
@@ -11,7 +11,7 @@
         "properties": {
           "agent": {
             "type": "string",
-            "description": "Which agent to spawn (e.g. 'claude', 'codex'). Defaults to 'claude'."
+            "description": "Which agent to spawn (e.g. 'claude', 'codex', 'gemini'). Natural names like 'claude code' or 'gemini cli' also resolve. Defaults to 'claude'."
           },
           "task": {
             "type": "string",
@@ -65,7 +65,7 @@
     },
     {
       "name": "acp_steer",
-      "description": "**Interrupts** the in-flight prompt of a running ACP session and replaces it with `instruction`. Use to redirect the agent (e.g., 'stop, do X instead'). For follow-up work that should happen *after* the current task, do NOT use this — wait for `acp_session_completed` and `acp_spawn` again.",
+      "description": "Sends `instruction` to an ACP session. On a running session this **interrupts** the in-flight prompt and replaces it - use it to redirect the agent (e.g., 'stop, do X instead'). A completed or assistant-restarted session is transparently resumed from persisted history via ACP session loading when the agent supports it, so follow-up work on an existing session id CAN go through this tool instead of spawning a new session. If resume is not possible (legacy session without a recorded working directory, or the agent lacks the capability), the error explains why; fall back to `acp_spawn`.",
       "category": "orchestration",
       "risk": "high",
       "input_schema": {
@@ -87,7 +87,7 @@
     },
     {
       "name": "acp_list_agents",
-      "description": "Lists ACP coding agents available to spawn. Each entry includes whether ACP is enabled, whether the agent's binary is on PATH, and an install command if not. Use this to decide between 'claude' and 'codex' or to surface setup steps to the user.",
+      "description": "Lists ACP coding agents available to spawn. Each entry includes whether ACP is enabled, whether the agent's binary is on PATH (missing binaries are installed automatically on first spawn), and an install command if not. Use this to decide between 'claude', 'codex', and 'gemini' or to surface setup steps to the user.",
       "category": "orchestration",
       "risk": "low",
       "input_schema": {