Upgrade the Claude ACP adapter (upstream sync)

This is a runbook for syncing our fork of @anthropic-ai/claude-agent-acp (the upstream Zed/agentclientprotocol ACP agent) that lives in packages/agent/src/adapters/claude/ with a newer upstream release. The fork is heavily diverged. The job is to port the valuable upstream changes (SDK bumps, bug fixes, new SDK-message handling) while preserving every intentional divergence — not to make the fork identical to upstream.

UPSTREAM.md (this directory) is the source of truth for the fork point, last-synced version/commit, the file mapping, the PostHog-only code, and the intentional divergences. Read it first, update it last.

This file is a runbook, not an auto-registered slash command. Invoke it by telling Claude to "follow the upgrade skill in the claude adapter dir." Move it to .claude/skills/<name>/SKILL.md if you ever want it runnable as /<name>.

Inputs you need before starting

1. Upstream source checkout — a local git clone of github.com/agentclientprotocol/claude-agent-acp. You need its history to diff. If the user hasn't given the path, ask for it (it's usually somewhere like ~/Cloud/claude-agent-acp). Do not guess.
2. This repo — the fork under packages/agent/.

Process

0. Orient (read, don't write)

• Read UPSTREAM.md. Note Last sync (commit + version), the pinned SDK versions, the File Mapping, PostHog-Only Code (Do Not Sync), and Intentional Divergences.
• In the upstream checkout, list the change set since the last sync and skim the changelog:
  • git -C <upstream> log --oneline <last-sync-sha>..HEAD
  • git -C <upstream> show <upstream>/CHANGELOG.md:CHANGELOG.md (or just read CHANGELOG.md)
• Confirm the new target version + HEAD sha and the target SDK versions from the upstream package.json.

1. Triage every commit

Bucket each commit since the last sync:

• Port — bug fixes and new feature / SDK-message handling that are not in the PostHog-only list and don't fight a divergence.
• Dep bump — record the target SDK versions; the diff tells you if code changes ride along.
• Skip — chore(main): release …, actions/* CI bumps, pure dependabot dev-dep bumps, and anything matching the PostHog-only / divergence lists.

Read intent from source diffs (exclude tests + JSON first):

git -C <upstream> show <sha> -- src/ ':(exclude)src/tests/*' ':(exclude)*.json'

A dependabot SDK-bump commit often also carries real code (new message handling). Don't assume "deps" == "no code".

2. Map upstream → fork

Upstream is one large src/acp-agent.ts; our fork is split. Use the File Mapping in UPSTREAM.md. Rough guide:

Upstream	Fork
acp-agent.ts prompt loop, lifecycle, cancel	claude-agent.ts
inline message/stream/result/system conversion	conversion/sdk-to-acp.ts
inline prompt→SDK conversion	conversion/acp-to-sdk.ts
tools.ts (tool_use→ACP, PostToolUse hook)	conversion/tool-use-to-acp.ts, hooks.ts
model alias resolution	session/models.ts, session/model-config.ts
options / system prompt	session/options.ts
permissions	permissions/*

For each upstream change, rg the fork for the touched symbol first — the fork usually already has a diverged version of it, so you're editing, not adding.

3. Bump dependencies

In packages/agent/package.json, set @anthropic-ai/claude-agent-sdk, @agentclientprotocol/sdk, and @anthropic-ai/sdk to the upstream package.json versions, then pnpm install from the repo root. (packages/shared pins its own older @agentclientprotocol/sdk; leave it unless a cross-package type error forces a bump.)

4. Find the breaking-change surface

Run pnpm --filter agent typecheck. The errors are your ACP/SDK breaking-change list. Gotchas seen in past syncs:

• The ACP SDK ships name-mangled generated types. dist/schema/*.gen.d.ts shows enum literals as n (e.g. StopReason = "…" | "n" | "cancelled"). Don't trust grep there. Read the hand-written dist/acp.d.ts, or download the exact target to inspect cleanly:

  cd /tmp && npm pack @agentclientprotocol/sdk@<ver> && tar xzf *.tgz
  rg -n "type StopReason|deleteSession|SessionModelState" package/dist/schema/types.gen.d.ts package/dist/acp.d.ts
  

• node -e "require('<pkg>/package.json')" may fail on the SDKs (exports map blocks the subpath). Read node_modules/<pkg>/package.json directly for the installed version.
• An ACP SDK bump can break code outside the claude adapter. The whole packages/agent package must typecheck — expect to also fix adapters/codex/* and server/agent-server.ts. Keep those fixes minimal and behavior-preserving (e.g. when ACP removed the models response field, the codex adapter derived the model id from configOptions instead).

5. Port in phases — bug fixes first, then features

For each ported change:

• Preserve divergences (see UPSTREAM.md → Intentional Divergences + PostHog-only). The big ones: single-session this.session (not this.sessions[id]); interruptReason on cancel; gateway models via fetchGatewayModels (not initializationResult.models); _posthog/* ext notifications; the "Unsupported slash command" gate on knownSlashCommands; SYSTEM_REMINDER stripping; plan / questions / MCP-metadata machinery.
• New SDK system subtypes are safe by default. handleSystemMessage ends in default: break, and the prompt-loop top-level switch (message.type) only unreachable()s unknown top-level types. So a new subtype won't crash the loop — port real handling only where there's user value (e.g. permission_denied → failed tool_call, tool_progress → in_progress, commands_changed → available_commands_update, mirror_error → log).
• When upstream reads new fields (stop_details, getContextUsage, thinking), confirm the installed SDK .d.ts actually has them before porting. Skip ports the fork can't use (e.g. the fork doesn't read MAX_THINKING_TOKENS, so upstream's resolveThinkingConfig was N/A).
• Typecheck after each logical group, not just at the end.

6. Verify (all of it)

pnpm --filter agent typecheck
pnpm --filter agent build
npx biome check --write <changed files>      # biome is the formatter/linter, not prettier/eslint
pnpm typecheck                                # whole repo: confirms apps/code compiles vs the new ACP SDK
pnpm --filter agent test
pnpm --filter code test

• The apps/code renderer unit tests analytics.test.ts and panelLayoutStore.test.ts are flaky — they sometimes throw in getElectronTRPC / electron-trpc ipcLink depending on test ordering. If they fail, re-run; a clean rerun (or git stash + run on the clean tree) passing confirms it's the known flake, not your change.

7. Update UPSTREAM.md (do this last)

• Bump Last sync (version + HEAD sha + date) and the pinned SDK versions.
• Add ## Changes Ported in v<X> Sync (one bullet per change, with PR # and short sha) and ## Skipped in v<X> Sync (with the reason for each skip).
• If a port made a former divergence match upstream, move it out of the Intentional Divergences table.

Fork facts worth remembering

• Single session. The agent owns one this.session (from BaseAcpAgent), not a sessions map. Upstream's per-session refactors usually collapse to "just use this.session".
• Prompt loop is a persistent consumer (since the v0.54.1 sync, upstream #780): prompt() enqueues a Turn deferred; runConsumer drains the query stream for the session's life, settles turns at their terminal result, and captures query + session.queryGeneration so the fork-only refreshSession() can retire it (bump generation → abort wake-up → end input). Steer mode, interruptReason, per-turn broadcast-at-activation and the unsupported-slash-command gate all live inside it — port upstream prompt-loop changes into the consumer, not a per-prompt loop.
• ACP connection classes are the deprecated ones on purpose. The fork stays on AgentSideConnection/ClientSideConnection (still shipped in ACP 1.x) because they carry the extMethod/extNotification surface _posthog/* uses; permission requests reach the client via the class's generic request(..., { cancellationSignal }). Don't port the agent() builder without a plan for the extension surface.
• Renderer uses config options only. Model/mode/effort selection is SessionConfigOption end to end; the renderer never reads the legacy models response field or calls unstable_setSessionModel. That's why upstream's ACP-0.24/0.25 model-state removals are safe to follow.
• toolUseCache is never cleared in the fork (created once in the constructor), so long sessions accumulate — keep the prune-at-tool_result behavior, and make any PostToolUse hook close over the data it needs rather than re-reading the cache.
• Conversion is split out. claude-agent.ts calls handleSystemMessage / handleStreamEvent / handleResultMessage / handleUserAssistantMessage from conversion/sdk-to-acp.ts. Upstream inlines all of this in acp-agent.ts.
• Don't commit or push unless the user explicitly asks. Leave the work on the current branch.