Acp

What the source does

• FilesystemDeclared5 observations
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

assistant/CLAUDE.md

assistant/src/approvals/CLAUDE.md

assistant/src/notifications/CLAUDE.md

assistant/src/runtime/CLAUDE.md

gateway/CLAUDE.md

import { executeAcpAbort } from "../../../../tools/acp/abort.js";

} from "../../../../tools/types.js";

import { executeAcpListAgents } from "../../../../tools/acp/list-agents.js";

} from "../../../../tools/types.js";

import { executeAcpSpawn } from "../../../../tools/acp/spawn.js";

Audit 0.4.1 · source sha 19bc86343b63 · 14 Oct 2026Report an issue or request a re-scan

• Publishervellum-ai GitHub organizationOwner of the repository this skill is read from
• Source foldervellum-ai/vellum-assistant/assistant/src/config/bundled-skills/acpThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict19bc86343b63A new audit runs when the source changes
• Repository statusNot archivedLast push 1 day ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Set up, authenticate, and run external coding agents (Claude Code, Codex) via the Agent Client Protocol

---
name: acp
description: Set up, authenticate, and run external coding agents (Claude Code, Codex) via the Agent Client Protocol
compatibility: "Designed for Vellum personal assistants"
metadata:
  emoji: "🔗"
  vellum:
    display-name: "ACP"
    category: "development"
    activation-hints:
      - "User names Claude Code or Codex, or wants to set up, install, configure, authenticate, connect, use, or delegate work to them"
      - "User wants an agent to work autonomously and report back later"
      - "User mentions ACP, claude-agent-acp, or codex-acp"
    avoid-when:
      - "The task is small enough to do inline and the user did not name Claude Code or Codex"
---

ACP agent orchestration - spawn external coding agents (Claude Code, Codex) 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", 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.

- Do not spawn unless they accept.
- Skip if you already offered this conversation, they declined, or they are already connected.
- This is not the missing-token card path. Do not invent setup steps.

## First-time setup

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 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 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). Install the pinned version below rather than `@latest`, so the adapter matches what the assistant was built against.

```bash
bun add -g @agentclientprotocol/[email protected]   # claude
bun add -g @agentclientprotocol/[email protected]          # codex
```

## Claude setup

The `claude-agent-acp` adapter requires a Claude **OAuth token** (`sk-ant-oat...`), NOT an API key (`sk-ant-api...`). Every spawn injects the stored token as `CLAUDE_CODE_OAUTH_TOKEN` automatically. The write path rejects an API key in this field, so never direct a user to paste an `sk-ant-api...` key here.

**Primary: the in-app Connect Claude Code flow.** When a spawn fails because the token is missing, the UI **automatically renders an inline "Connect Claude Code" card** for the failed step — one click on desktop (loopback), one paste on cloud. The card restores itself after a reload or reconnect, so it stays available. It mints and stores the OAuth token so it never enters the conversation or the workspace config.

**When a spawn fails for a missing token, do NOT prompt or instruct the user yourself.** The inline card already handles it, and the task **auto-continues** once they connect — so you don't need them to re-ask. Specifically, do NOT tell them to run `claude setup-token`, run `assistant credentials set`/`prompt`, open a terminal, or paste an `sk-ant-oat...` token — and do NOT re

Excerpt, first 6,001 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-14
   ✓SAFE B 89 / 100

   first audit · source 19bc86343b63

Questions about Acp

• github.com/vellum-ai/vellum-assistant/tree/main/assistant/src/co — the audited source at commit 19bc86343b63 and every finding aboveObserved · 14 Oct 2026

Spotted something wrong? Report a correction · Methodology