open-claude-agent-sdk 0.50.0 fixes broken clean installs

open-claude-agent-sdk v0.50.0 came out on September 19. The headline is a bug fix: from v0.25.0 on, importing the package on a clean install failed with this error:

import { query } from 'open-claude-agent-sdk';
// Error: Cannot find package '@anthropic-ai/claude-agent-sdk'

If you only installed this package, without the official SDK next to it, you were affected. The release also brings the API in line with the official @anthropic-ai/claude-agent-sdk 0.3.276 and fixes several bugs found in a full review of the code.

How to upgrade

npm install [email protected]

If you use TypeScript, also add the official SDK as a dev dependency. This package reuses its types but never loads it at runtime, and --omit=optional skips its bundled CLI binary:

npm install -D @anthropic-ai/claude-agent-sdk --omit=optional

Breaking changes

• abort() now stops for real. It rejects the iteration with AbortError and kills the CLI, the same as the official SDK. Before, it only sent an interrupt, and you still got a final result. If you want a graceful stop, use q.interrupt().
• Some unsupported helpers are removed: startup, resolveSettings, filterEscalatingDefaultMode and the sessionStore helpers. query() never supported them.

What was wrong

The package's entry point re-exported a few runtime values, such as AbortError and some constants, straight from the official SDK. The official SDK was only a dev dependency, so it wasn't there on a clean install, and the import failed.

Those values are now defined in this package. The session helpers (listSessions, getSessionInfo, forkSession and others) are also its own code now instead of re-exports. That fixed two more bugs: listSessions returned nothing under Node, and sessions in long project paths were never found. The official SDK is now an optional peer dependency, used for types only.

To keep this from happening again, CI now packs the package, installs it in an empty project without the official SDK, and imports every entry point under Node.

How it slipped through

Honestly, I stopped paying close attention. At one point Anthropic decided the Claude Agent SDK could only be used through the API, and after that I lost a lot of my motivation to work on this project.

It kept going anyway. I have a Claude Code skill that updates the SDK to match each new official release, and for the most part it did the job well. But there was a stretch, around the later Opus 4.6 days and into Opus 4.7, when the models felt noticeably worse to me. They cut corners everywhere. The bug arrived in v0.25.0 on April 24, about a week after Opus 4.7 came out, so my guess is it came from that period: a re-export that looked fine, passed the tests on my machine (where the official SDK was always installed), and nobody double-checked.

What finally caught it was a full review of the code against the official SDK. That's also why this release has more fixes than usual.

Other fixes

• Permissions: without a canUseTool callback, permission requests were quietly allowed. They now fail, as they do in the official SDK.
• Hangs: a canUseTool or hook callback that called a query method waited forever. It doesn't anymore.
• MCP: servers added mid-session with setMcpServers() were never registered. Now they are.

Catching up with the official SDK

This release matches official SDK 0.3.276. It adds the projectConfigRoot option, passes more detail to canUseTool callbacks (which MCP server a tool came from, its title and the matching ask rule), and improves how getSessionMessages handles messages queued during a tool call and parallel tool calls.

Each behavior change comes with a test that runs against both this package and the official SDK and compares the results.

The full list of changes is in the v0.49.0...v0.50.0 comparison.