acp-provider

# ACP providers Known agents can be discovered automatically when their CLI is installed on the host: `opencode`, `omp`, `grok`, and `hermes` appear as `acp-opencode`, `acp-omp`, `acp-grok`, and `acp-hermes-agent`. Inspect the target host's catalog with `bb provider list` and `bb provider models <provider-id>` using its environment or machine selector. Agents in the official ACP registry can be added without writing JSON. `bb acp registry [--refresh] [--json]` lists them with a status: `available`, `added`, `update available`, `built in` (bb already ships it), or `manual install` (the agent ships only as a downloadable binary). `bb acp add <agent-id>` adds the agent as provider `acp-<agent-id>`, or moves an added agent to the registry's current version while keeping the fields edited by hand. `bb acp remove <agent-id>` removes it. The plugin's settings page shows the same list. An added agent is an entry in the `Custom agents` setting that runs `npx -y <package>` or `uvx <package>` on the thread's host, so the host needs Node.js or uv. The list is cached for six hours; when the registry cannot be reached the saved copy is shown with the reason. To hide a detected ACP agent, use `bb provider disable acp-opencode`, or Disable on Settings → Providers. Restore it with `bb provider enable acp-opencode`. This leaves other ACP agents and the host CLI intact. Disabled agents skip background capability probing. `bb provider list --all` includes disabled agents. Cursor project skills come from `.cursor/skills`, which can link to `.agents/skills`. BB lists these linked skills as read-only under `cursor-project`. ACP agents may reject unlisted model IDs. OpenCode requires models in its own configuration; BB discovers them there. OpenCode agents are session modes, not models selectable through BB's model field. BB asks OpenCode for its models and modes in the directory the thread will run in: the project's checkout for a new thread, the environment's directory otherwise. OpenCode's custom primary agents therefore appear in the mode menu whether they live in the OpenCode config directory or in the project's `.opencode/` directory; `bb provider models acp-opencode --project <id>` prints the same list. A new agent file shows up once the stored list is ten minutes old and is read again. The same holds for a custom agent with `dialect: "opencode"`; every other ACP agent is asked once per machine. OpenCode does not read agent files from other folders such as `.agents/agents/`; set `OPENCODE_CONFIG_DIR` (for example to `.agents`, resolved in each workspace) as a machine variable with `bb machine env set OPENCODE_CONFIG_DIR` or in a custom agent's `env`, and keep every file there a valid OpenCode agent file, because OpenCode refuses to start on one it cannot parse. Grok Build advertises models and `thought_level` options over ACP, so the picker follows the connected agent (including `xhigh` on grok-4.6). BB launches OpenCode sessions with `OPENCODE_CLIENT=acp` and `OPENCODE_ENABLE_QUESTION_TOOL=false`, overriding inherited and custom launch values. Native questions have no ACP interaction handler in BB; agents use the ask-user-question plugin’s `AskUserQuestion` tool instead. This also applies to custom agents with `dialect: "opencode"` and does not change OpenCode config files. OpenCode and Grok ACP support the core `bb thread compact` command; Cursor ACP does not expose compatible compaction. Check the actual agent's capabilities before attempting provider-specific recovery. OpenCode Go subscription usage is available in Provider usage when the selected machine has OpenCode installed and a Go subscription. Sign in to Go in OpenCode on that machine, then refresh its OpenCode tab. Verify with `bb settings usage --machine <id-or-name> --json`; the SDK equivalent is `bb.sdk.system.usageLimits({ hostId, providerId: "acp-opencode" })`. BB reports Go's five-hour, weekly, and monthly usage and reset times, not local session token totals or other OpenCode providers' subscriptions. The collector checks `OPENCODE_API_KEY`, then the active official Console account and organization in `$XDG_DATA_HOME/opencode/opencode.db`, then active v2 `credential` table API keys or official Console OAuth credentials (`opencode-go` before `opencode`), then `OPENCODE_AUTH_CONTENT` or `$XDG_DATA_HOME/opencode/auth.json`. The default data directory is `~/.local/share/opencode`. Database storage is read only; expired Console sessions must be refreshed by OpenCode. V2 OAuth requires the device login method and account/organization metadata for the official Console server. API-key login prefers the `opencode-go` credential and accepts the shared `opencode` credential when Go is subscribed. Custom launch `env` values take precedence over the host environment. A custom OpenCode wrapper must declare `dialect: "opencode"` and `providerUsage: true` to expose its usage. Missing credentials, rejected keys, and collection errors remain unavailable states rather than zero usage. Never print API keys when diagnosing setup.