Skip to content

Spike: how an attached Harness authenticates, and what ai-buddy must never hold #371

Closed

Description

@omesser

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 SecretStore beside 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.

Activity

  1. added this to the V1 milestone on Sep 6, 2026
  2. omesser commented on Sep 6, 2026

    @omesser
    OwnerAuthor

    The answer

    • All five carry an existing login into a spawned subprocess. Every one keeps its credential in a home-relative file or the OS keychain, read at process start. None of them needs anything from the parent process except the same OS user.
    • So ai-buddy should hold nothing. Attachment requires a pre-authenticated CLI, and the app's only job is to spawn the binary, notice when it is not authenticated, and name the command that fixes it.
    • Anthropic has already written our rule down. Their legal page permits an end user signing in to the unmodified Claude Code binary with their own subscription, and forbids a third-party developer collecting, storing, or intermediating Claude.ai credentials. Option three is not a trade-off we get to weigh; it is prohibited for the Harness most users will attach.
    • Passing an env var through is worse than it looks. In non-interactive mode ANTHROPIC_API_KEY is used whenever present, with no prompt, so a helpful passthrough moves a Max subscriber onto metered API billing without telling them.
    • The recommendation is a decision, not a note, so it lands as an amendment to ADR-0010's consequences.
    • One thing I cannot settle, in Decisions below: whether an ambient wake on a backoff timer is "ordinary use" of a subscription seat.

    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.

    Harness Where the credential lives Carried in? What it depends on
    Claude Code macOS Keychain, falling back to ~/.claude/.credentials.json (0600); that file on Linux and Windows Yes Same OS user, default config dir, and not --bare
    opencode ~/.local/share/opencode/auth.json Yes by mechanism, never stated for ACP A $HOME path, so cwd does not reach it
    Hermes ~/.hermes/.env and ~/.hermes/config.yaml Yes, documented outright Nothing. The ACP page says so in its own words
    Pi ~/.pi/agent/auth.json Yes by mechanism, rpc.md is silent Resolution order is CLI flag, then auth.json, then env
    Grok Build ~/.grok/auth.json (0600) Yes Headless doc: cached credentials are used automatically

    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.md does 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_DIR set to something other than the user's own moves both the credentials file and the keychain entry key.
    • --bare never reads OAuth credentials or the system keychain. Anthropic auth becomes strictly ANTHROPIC_API_KEY or apiKeyHelper.

    Verified locally against Claude Code 2.1.263. The Keychain item the docs decline to name is a generic password with service Claude Code-credentials and 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 leader manages 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

    Harness Read order when there is no session Spawned with nothing
    Claude Code Bedrock/Vertex/Foundry env, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper, CLAUDE_CODE_OAUTH_TOKEN, then subscription OAuth Non-zero exit, failure printed on stdout. No browser flow under -p or --bare. Exact error string not documented
    opencode Provider env vars, then auth.json; /connect is the login path Not documented
    Hermes ~/.hermes/.env, or hermes model Not documented. It does advertise a terminal auth method (--setup) to first-run ACP clients
    Pi auth.json, then provider env vars Not documented, in any mode
    Grok Build config.toml model key, then session token, then XAI_API_KEY Headless exits 1, which also covers network and runtime errors. Interactive opens a browser

    ACP has a first-class answer to this and most of these agents do not use it. The spec puts authMethods on the initialize response, defines an authenticate request "called when the agent requires authentication before allowing session creation", and lets session/new return an auth_required error (authentication, schema). The numeric error code is not documented. Hermes advertises a method, and pi-acp advertises one backed by --terminal-login. opencode's ACP page mentions none of it.

    Grok's exit code is the worst case for us. 1 means 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":

    Anthropic does not permit third-party developers to offer Claude.ai login into their own applications, or to route requests through Free, Pro, or Max plan credentials on behalf of their users. Moreover, developers may not collect, store, or intermediate Claude.ai credentials or session tokens — sign-in to a Claude account must complete through Anthropic's own flow.

    And the carve-out, in the same section:

    Nor does it prevent an end user from signing in to the unmodified Claude Code binary with their own Claude subscription, including where a platform hosts Claude Code.

    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-service returned HTTP 403 to every automated fetch, so xAI's position is unverified rather than silent.

    4. Where the boundary should sit

    Candidate The case for Why not
    Hold nothing. Require a pre-authenticated CLI. It is what all five already support, what Anthropic's carve-out permits, and what CONTEXT.md already says a Harness is: "Supplied by the user, never bundled." Nothing to leak, rotate, migrate, or clear. The first run of an unauthenticated Harness is a dead end until the user goes to a terminal. That is question 5's whole job, and it is a copy problem rather than an architecture problem.
    Pass through an env var the user supplies per launch. Serves the user whose Harness is genuinely unconfigured, and stores nothing on disk. A per-launch env var needs somewhere to live, which is a Settings field holding a secret, which is candidate three with worse storage. Worse: 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.
    Store a per-Harness credential in SecretStore. The machinery exists, and KeyringStore already round-trips on all three platforms. Prohibited outright for Claude.ai credentials. For API keys it duplicates a secret the CLI already holds, which is the failure the issue was opened to prevent.

    Recommend the first.

    The argument that decides it is not about risk, it is about who makes the request. SecretStore fits the Director key because ai-buddy is the HTTP client there: src-tauri/src/model.rs builds 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-key stays 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.html already draws two empty states and attached() in src/chat.js:121 already 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.

    State What it means How the app knows What it says
    Not attached No Harness is configured. No process exists. Settings. No spawn is attempted. Today's empty-none, which already names the five by name.
    Attached but not authenticated The binary launched and cannot reach a model. ACP authMethods on initialize, or auth_required from session/new, where the Harness implements them. A pre-flight probe where it does not. The exact command to run, in their own terminal. Nothing to type here.
    Attached and refused The session exists and the turn failed: quota, rate limit, model access, a non-end_turn stop reason. ADR-0008 already routes this. Wake::Failed, and StaticDirector takes the turn. One line that the turn did not land. The buddy keeps walking either way.

    The command, per Harness, and this is the whole of the not-authenticated state's copy: claude auth login, opencode then /connect, hermes setup --portal, pi then /login, grok login.

    A probe is how we tell "not authenticated" from "refused" without touching a credential. claude auth status --json returns loggedIn, authMethod, subscriptionType and apiProvider, and no credential value. I verified the field names locally on 2.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 grok does 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.

    1. Never prompt for a Harness password, token, or API key. No field, no paste box, no modal.
    2. Never read another tool's credential file or keychain item. By name: ~/.claude/.credentials.json, the Claude Code-credentials Keychain item, ~/.local/share/opencode/auth.json, ~/.hermes/.env, ~/.pi/agent/auth.json, ~/.grok/auth.json.
    3. Never copy a Harness credential into SecretStore. director-api-key remains the only account ai-buddy owns.
    4. Never set a provider key into the child environment on the user's behalf. ANTHROPIC_API_KEY in particular overrides a subscription login with no prompt in non-interactive mode.
    5. Never set CLAUDE_CONFIG_DIR, and never pass --bare. Both cut the child off from the login the user already has.
    6. Never render, proxy, or intermediate a vendor login. Name the command and let the user run it.
    7. Never log, print, or fingerprint a Harness credential. key_fingerprint in model.rs exists for a key we own, not one we borrowed.
    8. Never modify, repackage, or wrap a Harness binary, and never disable one of its authentication methods. Anthropic's carve-out is conditioned on the binary being unmodified.

    Rejected

    Candidate Why not
    A Settings field per Harness for an API key Candidates two and three wearing a hat. It duplicates a secret the CLI holds and bills the user differently without saying so.
    Reading ~/.claude/.credentials.json to detect login state Rule 2, and it is unnecessary: claude auth status --json answers the same question without opening the file.
    Driving the vendor login inside our own webview Explicitly forbidden for Anthropic, and it is the exact "become the thing that leaks it" failure the issue names.
    Shipping a bundled fallback Harness so first run always works CONTEXT.md: "Supplied by the user, never bundled." It also puts us in the resale position Anthropic's terms bar.
    Auto-running the login command for the user It is an interactive browser flow that cannot run headless, and rule 6. Naming it costs one line of copy.
    Waiting for ACP to standardise this authMethods and auth_required are 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

    Decision Why the repository cannot settle it
    Whether an ambient Director wake counts as ordinary use of a subscription seat. The traffic comes from the user's own unmodified binary under their own login, which is the permitted shape. It also fires on a timer with nobody watching, which the Consumer Terms' automation clause was written about. If the answer is no, attachment cannot be the default Director for subscription users, and the reactive-only path (Summon, Poke, chat) becomes the shape of the feature. That is a product decision with a legal input, and the text does not resolve it.
    Whether attachment ships opinionated toward API-key Harness configuration. Recommending API keys sidesteps the question above and costs the user money they may already be spending on a subscription. Staying neutral means shipping into an unresolved reading of the terms.

    Uncertain

    • Whether Grok's leader process holds or brokers credentials. grok leader and --leader-socket ~/.grok/leader.sock exist. 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.
    • Whether claude auth status --json is 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.
    • Whether a headless spawn ever opens a browser. Not documented for claude -p, not documented for grok headless. It is documented for bare grok. Worth ten minutes with a scratch $HOME before feat(harness): Fill the Completer seam with an ACP session/prompt #300 spawns anything.
    • xAI's terms. Every automated fetch of x.ai/legal/terms-of-service returned 403. Unverified, not silent.
    • Whether opencode acp advertises authMethods. Not documented either way, and it decides whether opencode gets the protocol path or the probe path.
    • Whether ~/.ai-buddy as 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.

  3. moved this from Todo to In Progress in Fidgeton Sep 6, 2026
  4. added
    securitySecurity related - secrets, password, key-chain management, etc
    on Sep 6, 2026
  5. moved this from In Progress to Done in Fidgeton Sep 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    securitySecurity related - secrets, password, key-chain management, etc

    Projects

    • Status
      Done

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions