The April 2026 Claude Code update from inside an app that ships on top of it

Two things, and they are easy to confuse. The first is the consumer-facing CLI: Claude Code the terminal app got the Opus 4.7 model on April 16, the new Visualizations renderer, Claude Cowork going GA on macOS and Windows, and Managed Agents in public beta. The second, and the one this page focuses on, is the agent SDK that powers all of it: @agentclientprotocol/claude-agent-acp jumped from v0.25.0 on April 7 to v0.29.2 on April 20. That is four minor version bumps in 13 days, and every one of them changed how a downstream app embeds the agent.

It is the npm package that implements the Agent Client Protocol on top of Anthropic's Claude SDK. When you run claude-code in a terminal, it spawns this package as a JSON-RPC subprocess and talks to it over stdio. Any app that wants to embed Claude Code as an agent (not just call the API) imports this package and runs it. Fazm imports it directly: see the dependencies block in /Users/matthewdi/fazm/acp-bridge/package.json, which pins "@agentclientprotocol/claude-agent-acp": "^0.29.2" and resolves to the v0.29.2 tarball in package-lock.json. The April 2026 update is mostly a rewrite of how this package surfaces session events.

The stock @agentclientprotocol/claude-agent-acp builds a Claude SDK query iterator and pulls items off it inside ClaudeAcpAgent. Items it does not recognize as plain text or tool calls get silently consumed and dropped. In v0.29 the Claude SDK started emitting nine types of items the agent does not forward: type="system" with subtypes compact_boundary, status, task_started, task_notification, and api_retry; type="rate_limit_event"; type="tool_progress"; type="tool_use_summary"; and type="stream_event" with a content_block of type="compaction". From inside a consumer app this is invisible until your users complain that the spinner stopped moving for 90 seconds during a compaction or that they can't tell why a tool call is taking forever. The fix is to monkeypatch session.query.next and re-emit the dropped items as ACP sessionUpdate notifications.

You don't import @agentclientprotocol/claude-agent-acp from the package root, because that auto-runs the agent. You import the inner module the package's bin script imports, then wrap the prototype methods. Fazm's patch lives at acp-bridge/src/patched-acp-entry.mjs (267 lines). It does: import { ClaudeAcpAgent, runAcp } from "@agentclientprotocol/claude-agent-acp/dist/acp-agent.js", saves the original createSession, replaces ClaudeAcpAgent.prototype.createSession with a wrapper that intercepts the query iterator, and finally calls runAcp() to start the agent normally. The Swift side passes -e patched-acp-entry.mjs to node instead of the default bin. The patched entrypoint is bundled into the .app at build time.

It lives on the SDK result object as item.value.total_cost_usd when item.value.type === "result" and subtype === "success". The stock @agentclientprotocol/claude-agent-acp consumes the result item to get the assistant's last text but throws the cost field away. Fazm captures it inside the patched session.query.next: it reads item.value.total_cost_usd, subtracts the previous session cost (stored as session._sessionCostUsd), and stores the delta as session._lastCostUsd. The patched ClaudeAcpAgent.prototype.prompt then attaches a _meta.costUsd field to its return value. From there the Swift bridge writes it into APIClient.recordLlmUsage(...) along with input/output/cache token counts. Per-query cost down to the cent is the difference between knowing whether your built-in credits will last the trial and finding out at the paywall.

Before v0.29, when you wanted Opus you sent modelId: "opus" in the session/setModel call. After v0.29 the SDK accepts "default" as the alias for the latest Opus, and "opus" is no longer a valid alias on its own. Any app that stored the user's model preference as the literal string "opus" silently broke until it migrated. Fazm's migration is one function, normalizeModelId at /Users/matthewdi/fazm/Desktop/Sources/FloatingControlBar/ShortcutSettings.swift line 174, which does: if modelId.contains("opus") { return "default" }. The unreleased CHANGELOG.json line for the next version is literally about this exact migration.

Before v0.29, an embedding app shipped a hard-coded list of supported Claude models and updated it on every Anthropic release. After v0.29 the agent emits a session/update notification with method models_available containing the full list of models the user's account has access to, scoped to whatever credit pool they are using. The downstream app builds its model picker from that payload at runtime. The Fazm release notes for v2.4.0 on April 20 say it directly: "Available AI models now populate dynamically from the agent, so newly released Claude models appear without an app update." The handler is at ACPBridge.swift line 1131 (case "models_available"). When Anthropic flipped the switch on Opus 4.7 on April 16, the new model showed up in the picker the same day with no app update required.

During the rollout window of a new Anthropic release, the SDK occasionally returns a subset of models in models_available, for example only Sonnet during the hour before Opus comes back online for a region. Fazm has a substring-matched family table at ShortcutSettings.swift that maps modelId.contains("opus") to the Smart label, modelId.contains("sonnet") to Fast, and modelId.contains("haiku") to Scary. The first version of the labeler walked the returned list and assigned Smart to whatever model came back ranked highest. For an Opus-less payload that briefly meant Smart pointed at Sonnet. v2.4.1 on April 22 anchored Smart to the opus substring so a payload with no opus model now leaves Smart undefined rather than reassigning the label.

The Anthropic API is request and response: send messages, get a single completion back. The Agent Client Protocol is a bidirectional JSON-RPC session: the agent owns conversation history, tool calling, planning, compaction, and rate-limit handling. The client is the embedding app and it gets streaming sessionUpdate notifications as the agent works. The client never re-sends history; the agent's session is the source of truth. That is why ACPBridge.swift uses one persistent session per Fazm chat thread and never injects prior turns into the system prompt. The per-query Anthropic API calls are an internal detail of the agent and the cost is the aggregate across however many tool-use rounds happened.

Visualizations is an output feature. It lets Claude render charts and diagrams inside its own response. It does not change how the agent reads what is happening on your Mac. The input side is still the agent's job, and a screenshot pipeline pays the OCR and re-segmentation cost on every turn. Fazm hands the agent the actual macOS accessibility tree (AXUIElement structures from the Accessibility API) for whatever app is in focus. That tree is structured text, not pixels. When Anthropic ships a smarter Opus, the input quality stays the same; only the model gets better at acting on it. A Visualizations chart in the response is rendered the same way regardless.

It is in the Fazm repo at acp-bridge/src/patched-acp-entry.mjs. The file is 267 lines, MIT-style, and the structure is small enough to copy into your own embedding app: import ClaudeAcpAgent and runAcp from the dist/acp-agent.js path, save originalCreateSession = ClaudeAcpAgent.prototype.createSession, replace it with a wrapper that calls the original then intercepts session.query.next, then call runAcp() at the bottom. The Swift bridge that spawns it is Desktop/Sources/Chat/ACPBridge.swift; look at the spawn logic around line 532 (acpEntry = join(__dirname, "patched-acp-entry.mjs")) for the wiring.