Type incompatibility when @anthropic-ai/sdk >= 0.82.0 is installed alongside claude-agent-sdk

[dawidworobiec]

Description

When @anthropic-ai/sdk@0.82.0 is hoisted alongside @anthropic-ai/claude-agent-sdk@0.2.90, TypeScript produces type errors because the SDK added ToolReferenceBlockParam to the ContentBlockParam union in 0.82.0, but claude-agent-sdk's bundled types (built against ^0.74.0) don't include it. This causes a type mismatch wherever ContentBlockParam[] is passed into agent SDK functions.

Reproduction

package.json:

{
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.2.90",
    "@anthropic-ai/sdk": "^0.82.0"
  },
  "overrides": {
    "@anthropic-ai/sdk": "^0.82.0"
  }
}

Any code that passes ContentBlockParam[] from @anthropic-ai/sdk into an agent SDK entry point (e.g. userMessageContent) fails with a type error like:

Type 'ContentBlockParam' is not assignable to type 'ContentBlockParam'.
  Type 'ToolReferenceBlockParam' is not assignable to type 'ContentBlockParam'.

The two ContentBlockParam types come from different copies of @anthropic-ai/sdk — the hoisted 0.82.0 (which includes ToolReferenceBlockParam) and the agent SDK's bundled 0.74.x types (which don't).

Root Cause

claude-agent-sdk declares "@anthropic-ai/sdk": "^0.74.0" in its dependencies but its bundled .d.ts files import types from @anthropic-ai/sdk. When npm hoists a newer version (0.82.0) that has added members to union types like ContentBlockParam, the two type sets become structurally incompatible.

Workaround

Pin @anthropic-ai/sdk to ^0.81.0 (or whichever version the agent SDK was last tested against) and use an npm override to prevent a newer version from being hoisted.

Related Issues

• Missing dependency on @anthropic-ai/sdk #179 — Missing dependency on @anthropic-ai/sdk
• Missing @anthropic-ai/sdk dependency causes types to resolve as 'any' #121 — Missing @anthropic-ai/sdk dependency causes types to resolve as any
• @anthropic-ai/claude-agent-sdk is missing a dependency on @anthropic-ai/sdk anthropic-sdk-typescript#864 — Cross-repo duplicate

Suggested Fix

Either:

1. Re-export the base SDK types that consumers commonly need (Anthropic, APIError, ContentBlockParam, Model, etc.) from claude-agent-sdk so consumers don't need a separate direct dependency
2. Or tighten the @anthropic-ai/sdk peer/dependency range so breaking type additions are caught at install time