Acp

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).

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 it once 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.

Only the allowlisted out-of-box packages are ever installed this way (@agentclientprotocol/claude-agent-acp, @zed-industries/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).

bun add -g @agentclientprotocol/claude-agent-acp   # claude
bun add -g @zed-industries/codex-acp               # 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 retry the spawn yourself. Add at most one short sentence pointing at the card ("Click Connect Claude Code to sign in — I'll pick it back up once you're connected"), then stop and wait. Keep it terse and never say where the card is (no "above"/"below"/"at the bottom" — its placement is a UI detail you can't see): do not narrate that a card appeared, explain how the sign-in works, or say "nothing to paste" (the cloud flow does paste a key).

Fallback (headless environments where no inline card can appear): the user runs claude setup-token on a machine where they are logged in to Claude, then stores the result via the secure prompt: