buzz-acp base_prompt promises auth env vars the agent's own terminal may not have
- Dominant language
- Rust
- Stars
- 32.7k
- Forks
- 4.3k
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 253
Description
**Describe the bug**
`crates/buzz-acp/src/base_prompt.md:5` (verified on `main` @ `ac4fa13`) tells every agent:
> The `buzz` CLI is your primary interface. Auth env vars: `BUZZ_RELAY_URL`, `BUZZ_PRIVATE_KEY`, `BUZZ_AUTH_TAG`.
This is true of the MCP server that buzz-acp spawns (`build_mcp_servers` injects them into the MCP config), but **not** necessarily of the agent runtime's own built-in terminal tool. Runtimes that scrub credentials from tool subprocesses leave those variables unset — so the agent follows its instructions, runs `buzz` in its own terminal, and fails with an auth error it can't diagnose.
**Steps to reproduce** (Hermes runtime)
1. Run `buzz-acp --agent-command hermes-acp` against hermes-agent 0.19.1.
2. Mention the agent and ask it to run any `buzz` command.
3. The agent uses its built-in terminal tool and gets:
```json
{"error":"auth_error","message":"auth error: BUZZ_PRIVATE_KEY is required (use --private-key or set env var)","retryable":false}
```
Hermes strips `BUZZ_*` from tool subprocesses and refuses to re-grant them via `terminal.env_passthrough` (citing GHSA-rhgp-j443-p4rf), so the obvious operator workaround is closed too. The path that actually works is the `buzz-dev-mcp` shell tool, which does receive the injected env — but nothing in the prompt says so.
**Expected behavior**
The base prompt tells the agent which tool actually carries Buzz credentials, or states the conditional plainly.
**Actual behavior**
The agent tries its built-in terminal first, fails on auth, and (in our deployment) reported it could not reach Buzz at all. This cost several deploy cycles to diagnose from the outside, because the agent's *self-report* was "Buzz is down."
**Suggested wording**
> The `buzz` CLI is your primary interface. It is pre-authenticated **inside the Buzz MCP shell tool**; your runtime's own terminal may not carry `BUZZ_PRIVATE_KEY`. If `buzz` returns `auth_error`, re-run the command through the Buzz MCP shell tool rather than exporting credentials yourself.
Adding `--mcp-command ` to the harness quickstart would also make the working configuration discoverable.
**Version and platform**
- Buzz version: buzz-acp from `ghcr.io/block/buzz:main` @ `sha256:13ddb4c12f4c0b8147cece717a57013a45fdb1610bd072d7e383ac79a070ddd9`; prompt text re-verified on `main` @ `ac4fa13` (2026-08-01)
- OS: Ubuntu 24.04, systemd unit, `NoNewPrivileges=yes`; harness: buzz-acp + hermes-acp (hermes-agent 0.19.1) + buzz-dev-mcp
**Logs / additional context**
Related issues (searched open and closed — no duplicate found):
- #3768 is adjacent but different: there the managed session is missing the vars entirely; here the vars exist where the harness injected them, and the prompt misdirects the agent to a tool that doesn't have them.
- #2883 (keep `BUZZ_PRIVATE_KEY` out of agent-controlled processes) is the security-hardening direction — worth noting that if that lands, this line in the base prompt becomes wrong *everywhere*, not just under credential-scrubbing runtimes. The prompt fix is compatible with both worlds: point agents at the sanctioned authenticated tool instead of promising raw env vars.
Contributor guide
Assessment
This issue has not been assessed yet.