Connect an agent in one flow: versions first, one approval, watcher included

Merged
JO
3d ago
+279-23

Companion to basecamp/bc3#13784, from Adrien's migration report on Bring your agents to Basecamp.

His setup hit four rough edges:

  1. His CLI was 0.11.0, which has neither auth agent connect nor connect.
  2. His plugin was 0.7.2, so the legacy basecamp-connect skill was removed before the new one existed.
  3. He had to approve twice: Basecamp's instructions page connected over HTTP into ~/.basecamp-agent/credentials.json, which the CLI can't read, so auth agent connect connected a second time.
  4. The watcher came as a separate step.

bc3#13784 makes the instructions page CLI-first, and this PR makes the CLI side match it.

basecamp-connect skill

  • Before anything: require CLI 0.13.0 or later, running basecamp upgrade when it's older. Remove the legacy skill: symlinks are deleted, a real directory only after asking. Removing it here is safe because the skill doing the removing is installed.
  • First-time setup:
    • On a computer with no profiles, auth status answers "no profiles are configured". The skill now treats that as a free profile, and never runs profile create for an agent, since that signs in a person.
    • If the instructions page left a ~/.basecamp-agent/credentials.json, the skill says before connecting that connecting replaces it, so the person approves once more.
    • --operator <id> is named for non-personal agents.
    • New step 5: start the connector right after setup.

Doctor and the post-upgrade notice

  • A plugin/CLI mismatch now names the side to move:
    • plugin behind: claude plugin update basecamp-cli@37signals, then restart Claude Code;
    • CLI behind: basecamp upgrade;
    • plugin still under the old basecamp@37signals key, which the notice used to miss entirely: basecamp setup claude.
  • Versions that are equal by semver (v0.13.0, 0.13.0) no longer count as a mismatch.

README

  • New section "Connecting an agent to this computer": the version it needs, basecamp connect setup and its scriptable steps, connecting once, and updating the plugin (then restarting) before removing an older skill.

Review
Two rounds of adversarial review, by separate Opus agents. One change came out of it: importing the old credentials file (piped jq into auth login --with-client-credentials) was tried and dropped. It broke on read-only agents, a missing jq and stale files, and it contradicted the skill's own credential rules.

Verification

  • New harness tests for the mismatch hint and PluginUpdateNotice: legacy key, plugin behind, semver-equal, dev build. Each failed against a stub of the old behavior before the change.
  • bin/ci is green locally, including skill drift.
  • Not run: the connect skill evals (make -C skill-evals eval-connect).

Not in this PR

  • The Codex version check still says basecamp setup codex in both directions.
  • The "no profiles are configured" error still points at basecamp profile create.