Repository navigation
Description
Related: #300 (the ACP session that will spawn one), #166 (per-harness client config), #16 (Harness attachment), ADR-0010, ADR-0003.
Why
ADR-0010 has ai-buddy spawn a Harness as a subprocess in ACP mode and hold it for as long as the app runs. Nothing has been decided about how that subprocess is authenticated, and the answer differs per Harness: Claude Code has a subscription login and an API key path, opencode has its own credential store, and the others differ again. Today the only credential the app owns is the Director API key, kept in the OS secret store behind SecretStore (src-tauri/src/secrets.rs) — a single key for one HTTP Completer, which is not the shape of this problem.
The failure this spike exists to prevent: ai-buddy inventing a credential surface. Asking a user to paste a token that their Harness CLI already holds would duplicate a secret, put a second copy in our Keychain item, and make us the thing that leaks it. ADR-0003's reasoning applies — the Harness owns what it owns — but it was written about desktop control, not credentials, and nobody has extended it.
What to answer
- Does an already-logged-in CLI carry its login into a subprocess we spawn? For each of the five Harnesses, whether a user who has authenticated their CLI normally gets an authenticated ACP subprocess for free, and what that depends on: environment, a credential file, a keychain item, a daemon. This is the question that decides whether the rest matters.
- What each Harness reads when it is not already logged in. An env var, a file, an interactive flow that cannot run headless — and what happens when it is spawned with none of them.
- What a subscription login means for a spawned process. ADR-0003 notes the computer-use capability is gated behind a Pro or Max subscription. Whether a subscription session survives being spawned this way, and whether spawning it is within the vendor's terms, is worth knowing before we build on it.
- Where the boundary should sit. The candidate positions: ai-buddy holds nothing and requires a pre-authenticated CLI; ai-buddy passes through an env var the user supplies per launch; ai-buddy stores a per-Harness credential in
SecretStorebeside the Director key. Argue them, and recommend one. - What the user is told when it fails. An unauthenticated Harness is the most likely first-run state, and the Chat surface already has to explain having no Director. What it should say, and how it knows the difference between "not attached", "attached but not authenticated", and "attached and refused".
- What we must never do. State it plainly enough to hold a future pull request to: no prompting for a password, no reading another tool's credential file, no copying a token into our own store to be helpful.
Deliverable
A comment on this issue with the findings and one recommendation, per the shape #293's spike used. If the answer is a decision rather than a note, it becomes an ADR — likely an amendment to ADR-0010's consequences rather than a new record, since that is where spawning was decided.
Nothing is built here. Any code this implies is #300's or #166's.
Tests
None. This is a spike.
— Claude Code, on @omesser's behalf.
Metadata
Metadata
Assignees
Labels
Projects
- StatusShow more project fieldsDone
Activity
omesser commentedon Sep 6, 2026
The answer
ANTHROPIC_API_KEYis used whenever present, with no prompt, so a helpful passthrough moves a Max subscriber onto metered API billing without telling them.1. Does an existing login carry into a subprocess we spawn?
Yes, on all five. The mechanism is the same everywhere: a credential file under
$HOME, or a keychain item, opened by the process when it starts.~/.claude/.credentials.json(0600); that file on Linux and Windows--bare~/.local/share/opencode/auth.json$HOMEpath, so cwd does not reach it~/.hermes/.envand~/.hermes/config.yaml~/.pi/agent/auth.jsonrpc.mdis silentauth.json, then env~/.grok/auth.json(0600)Hermes is the only project that answers the question directly. "Provider resolution uses Hermes' normal runtime resolver, so ACP inherits the currently configured provider and credentials", and "ACP mode uses the same Hermes configuration as the CLI" (ACP feature docs).
opencode and Pi are inference from documented mechanics, and I am marking them as such. opencode's ACP page says "OpenCode works the same via ACP as it does in the terminal. All features are supported" (acp), and its credential path is home-relative (providers). Pi's
rpc.mddoes not mention authentication at all. Neither says "a subprocess spawned by another app is authenticated". The paths carry no cwd dependency, which is the whole basis for expecting it to work.Claude Code documents the two ways it breaks, and both are things we would have to do to ourselves (authentication, headless):
CLAUDE_CONFIG_DIRset to something other than the user's own moves both the credentials file and the keychain entry key.--barenever reads OAuth credentials or the system keychain. Anthropic auth becomes strictlyANTHROPIC_API_KEYorapiKeyHelper.Verified locally against Claude Code
2.1.263. The Keychain item the docs decline to name is a generic password with serviceClaude Code-credentialsand the OS username as the account. I read its metadata, never its value, and nothing in ai-buddy should read either.Grok is the one Harness with a daemon in the picture.
grok leadermanages running leader processes and every subcommand takes--leader-socket, defaulting to~/.grok/leader.sock. No source I found says whether credentials pass through it. Listed under Uncertain.2. What each reads when it is not logged in, and what happens with none of it
ANTHROPIC_AUTH_TOKEN,ANTHROPIC_API_KEY,apiKeyHelper,CLAUDE_CODE_OAUTH_TOKEN, then subscription OAuth-por--bare. Exact error string not documentedauth.json;/connectis the login path~/.hermes/.env, orhermes model--setup) to first-run ACP clientsauth.json, then provider env varsconfig.tomlmodel key, then session token, thenXAI_API_KEY1, which also covers network and runtime errors. Interactive opens a browserACP has a first-class answer to this and most of these agents do not use it. The spec puts
authMethodson theinitializeresponse, defines anauthenticaterequest "called when the agent requires authentication before allowing session creation", and letssession/newreturn anauth_requirederror (authentication, schema). The numeric error code is not documented. Hermes advertises a method, andpi-acpadvertises one backed by--terminal-login. opencode's ACP page mentions none of it.Grok's exit code is the worst case for us.
1means authentication failure, network error, or runtime error, so exit status alone cannot tell the user which of the three happened. That is the concrete reason question 5 needs a probe rather than a return code.3. What a subscription login means for a spawned process
The session survives. It is a file or keychain read, not a terminal-bound session, on every one of the five.
The terms are where this gets interesting, and Anthropic has thought about exactly our case. From legal and compliance, under "Authentication and credential use":
And the carve-out, in the same section:
That is conditioned on the binary being unmodified, and on not removing, disabling or restricting any authentication method built into it. The permitted shape is the shape this spike recommends, and the forbidden shape is candidate three. We did not have to reason our way to the boundary; the vendor drew it.
The tension I will not paper over. Consumer Terms §3 bars accessing the Services "through automated or non-human means, whether through a bot, script, or otherwise", except via an API key "or where we otherwise explicitly permit it". The carve-out above reads as that explicit permission for the unmodified binary under the user's own login. It was plainly written about a developer at a keyboard. ADR-0008 has us waking the Director on an exponential backoff with nobody watching, which is automated traffic on a subscription seat by any plain reading. I do not think the text settles it. It is the first decision below.
ADR-0003's Pro or Max gate is a different gate. That one is about the computer-use capability. This is about who may hold the token. They are unrelated and should not be conflated in review.
The other four vendors say nothing usable. opencode, Pi and Hermes are clients for third-party providers, so the terms that bind are the provider's. Both opencode and Pi offer Claude Pro/Max OAuth, which means Anthropic's clause reaches through them at one remove and lands on the same answer.
x.ai/legal/terms-of-servicereturned HTTP 403 to every automated fetch, so xAI's position is unverified rather than silent.4. Where the boundary should sit
ANTHROPIC_API_KEY"is always used when present" in non-interactive mode with no prompt, so a passthrough meant to help silently moves a Max subscriber onto metered billing.SecretStore.KeyringStorealready round-trips on all three platforms.Recommend the first.
The argument that decides it is not about risk, it is about who makes the request.
SecretStorefits the Director key because ai-buddy is the HTTP client there:src-tauri/src/model.rsbuilds the request and puts the key in the header. With a Harness, ai-buddy is never the HTTP client. The Harness talks to the provider and we talk ACP over a pipe. A credential we store and never send is pure liability with no corresponding capability.director-api-keystays the only account in the store. Per-Harness accounts would need per-Harness set, clear, fingerprint and precedence handling, five times over, for a value we would then have to inject into a child environment where it overrides the login the user already has.Holding nothing still means inheriting the environment ai-buddy was launched with. That is the default behavior of spawning a child and it is not a decision we make. What matters is that we add nothing to it and remove nothing from it.
5. What the user is told when it fails
src/chat.htmlalready draws two empty states andattached()insrc/chat.js:121already picks between them, on the grounds that "never configured is a thing to attach, switched off is a thing to turn back on". Attachment adds a third distinction on the same principle.empty-none, which already names the five by name.authMethodsoninitialize, orauth_requiredfromsession/new, where the Harness implements them. A pre-flight probe where it does not.end_turnstop reason.Wake::Failed, andStaticDirectortakes the turn.The command, per Harness, and this is the whole of the not-authenticated state's copy:
claude auth login,opencodethen/connect,hermes setup --portal,pithen/login,grok login.A probe is how we tell "not authenticated" from "refused" without touching a credential.
claude auth status --jsonreturnsloggedIn,authMethod,subscriptionTypeandapiProvider, and no credential value. I verified the field names locally on2.1.263. It is not in the published docs, so treat it as observed rather than promised, and let a missing or unparseable answer fall through to the refused state instead of asserting anything.Two rules the copy has to keep. ai-buddy never renders the login flow, because Anthropic requires sign-in to complete through their own flow. And ai-buddy never spawns a Harness in a mode that can open a browser on its own, because bare
grokdoes exactly that on first launch, and a mascot that opens a browser tab unasked is the worst version of this feature.6. What we must never do
Stated so a reviewer can quote a numbered line at a pull request.
~/.claude/.credentials.json, theClaude Code-credentialsKeychain item,~/.local/share/opencode/auth.json,~/.hermes/.env,~/.pi/agent/auth.json,~/.grok/auth.json.SecretStore.director-api-keyremains the only account ai-buddy owns.ANTHROPIC_API_KEYin particular overrides a subscription login with no prompt in non-interactive mode.CLAUDE_CONFIG_DIR, and never pass--bare. Both cut the child off from the login the user already has.key_fingerprintinmodel.rsexists for a key we own, not one we borrowed.Rejected
~/.claude/.credentials.jsonto detect login stateclaude auth status --jsonanswers the same question without opening the file.authMethodsandauth_requiredare already in the spec. Three of five agents do not implement them, and that is a gap we route around rather than block on.Decisions for @omesser
Uncertain
grok leaderand--leader-socket ~/.grok/leader.sockexist. Nothing documents what a second leader means for a spawned child. This is the one place the issue's "daemon" option might be real, and feat(harness): Fill the Completer seam with an ACP session/prompt #300 will trip over it before anything else does.claude auth status --jsonis a stable surface. It is not in the published docs. If it moves, the not-authenticated state degrades to the refused state, which is why the fallback matters more than the probe.claude -p, not documented forgrokheadless. It is documented for baregrok. Worth ten minutes with a scratch$HOMEbefore feat(harness): Fill the Completer seam with an ACP session/prompt #300 spawns anything.x.ai/legal/terms-of-servicereturned 403. Unverified, not silent.opencode acpadvertisesauthMethods. Not documented either way, and it decides whether opencode gets the protocol path or the probe path.~/.ai-buddyas cwd changes what opencode loads. Config discovery "first looks for a config file in the current directory, then traverses up to the nearest Git directory". Credentials are unaffected, since those are home-relative. Model and provider selection may not be. That belongs to Attaching real harnesses: per-harness MCP client config for Claude Code, opencode, Hermes, Pi, and Grok #166, and I am flagging it here because ADR-0010 picked that cwd for an unrelated reason.— Claude Code, on @omesser's behalf.
docs(harness): Record that the Harness authenticates itself and ai-bu…