buzz-acp base_prompt promises auth env vars the agent's own terminal may not have

[jdrolls]

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:

{"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 <path-to-buzz-dev-mcp> 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):

• [Bug] Hermes agent does not work out of the box — managed session missing BUZZ_PRIVATE_KEY and BUZZ_RELAY_URL #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.
• security: keep BUZZ_PRIVATE_KEY out of agent-controlled processes #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.

[iroiro147]

Shipped: #4282

One-line fix to base_prompt.md — now names the Buzz MCP shell tool as the auth carrier (instead of only listing env vars), and tells the agent to re-run through the MCP shell tool on auth_error instead of trying to export credentials itself.

Wording is a direct adaptation of your suggested copy with light tightening. Verified by inspecting build_mcp_servers that the env vars do land inside the MCP server config — so the only broken path is the runtime's own built-in terminal.

Validation: cargo check · clippy · all 661 buzz-acp tests passing.