ai-sdk-provider-claude-code 2.0.5 → 2.2.0

package/README.md

@@ -9,7 +9,7 @@
 
 # AI SDK Provider for Claude Code SDK
 
-> **Latest Release**: Version 2.x uses the Claude Agent SDK with explicit configuration defaults. Version 1.x is the previous stable release. For AI SDK v4 support, use the `ai-sdk-v4` tag or version 0.2.x.
+> **Latest Release**: Version 2.x uses the Claude Agent SDK with native structured outputs support (v2.2.0+). For AI SDK v4 support, use the `ai-sdk-v4` tag or version 0.2.x.
 
 **ai-sdk-provider-claude-code** lets you use Claude via the [Vercel AI SDK](https://sdk.vercel.ai/docs) through the official `@anthropic-ai/claude-agent-sdk` and the Claude Code CLI.
 
@@ -45,12 +45,69 @@ npm install ai-sdk-provider-claude-code@ai-sdk-v4 ai@^4.3.16
 
 ## Zod Compatibility
 
-This package supports both **Zod 3** and **Zod 4**:
+This package is **tested and compatible with both Zod 3 and Zod 4**, but there's an important peer dependency consideration:
 
-- ✅ **Zod 4** (Recommended): `npm install zod@^4.0.0`
-- ✅ **Zod 3** (Still supported): `npm install zod@^3.0.0`
+### Current Status
 
-The package uses Zod for schema validation and works seamlessly with both versions. All 302 tests pass with both Zod 3 and Zod 4. See `examples/zod4-compatibility-test.ts` for comprehensive compatibility tests.
+- ✅ **Zod 3** (fully supported, no warnings)
+- ⚠️ **Zod 4** (functional, but requires `--legacy-peer-deps`)
+
+While this package declares support for both versions (`peerDependencies: "zod": "^3.0.0 || ^4.0.0"`), the underlying `@anthropic-ai/claude-agent-sdk` currently only declares support for Zod 3 (`peerDependencies: "zod": "^3.24.1"`).
+
+**All 302 tests pass with both Zod 3 and Zod 4.** See `examples/zod4-compatibility-test.ts` for comprehensive compatibility verification.
+
+### Installation Instructions
+
+**With Zod 3 (recommended for now):**
+
+```bash
+npm install ai-sdk-provider-claude-code ai zod@^3.0.0
+```
+
+**With Zod 4 (requires package manager-specific flags):**
+
+For **npm**:
+
+```bash
+npm install ai-sdk-provider-claude-code ai zod@^4.0.0 --legacy-peer-deps
+```
+
+For **pnpm**:
+
+```bash
+pnpm install ai-sdk-provider-claude-code ai zod@^4.0.0 --no-strict-peer-dependencies
+# Or configure it project-wide:
+pnpm config set strict-peer-dependencies false
+```
+
+For **Yarn** (Berry/v2+):
+
+```bash
+yarn add ai-sdk-provider-claude-code ai zod@^4.0.0
+# Yarn's peer resolution typically doesn't error here
+```
+
+### For Package Developers
+
+If you're developing with this package in your repository, add a configuration file to avoid needing the flag on every install:
+
+**For npm** (`.npmrc`):
+
+```ini
+# .npmrc
+legacy-peer-deps=true
+```
+
+**For pnpm** (`.npmrc`):
+
+```ini
+# .npmrc
+strict-peer-dependencies=false
+```
+
+> **Note**: The `.npmrc` file in this repository is committed for CI/development consistency but is **not included in the published package** (it's excluded via the `files` field in `package.json`). End users will still need to use the appropriate flags when installing with Zod 4.
+
+> **Temporary Workaround**: This configuration is needed until `@anthropic-ai/claude-agent-sdk` adds official Zod 4 support to their peer dependencies. Track progress in the [claude-agent-sdk repository](https://github.com/anthropics/anthropic-sdk-typescript).
 
 ## Installation
 
@@ -207,12 +264,44 @@ If you're upgrading from version 1.x:
 - Explicit configuration over implicit defaults
 - Future-proof alignment with Claude Agent SDK design
 
+## Structured Outputs
+
+This provider supports **native structured outputs** via the Claude Agent SDK (v0.1.45+). When using `generateObject()` or `streamObject()`, the SDK guarantees schema-compliant JSON responses through constrained decoding.
+
+```typescript
+import { generateObject } from 'ai';
+import { claudeCode } from 'ai-sdk-provider-claude-code';
+import { z } from 'zod';
+
+const result = await generateObject({
+  model: claudeCode('sonnet'),
+  schema: z.object({
+    name: z.string(),
+    age: z.number(),
+    email: z.string().email(),
+  }),
+  prompt: 'Generate a user profile for a software developer',
+});
+
+console.log(result.object); // Guaranteed to match schema
+// { name: "Alex Chen", age: 28, email: "alex@example.com" }
+```
+
+**Benefits:**
+
+- ✅ **Guaranteed schema compliance** - Constrained decoding ensures valid output
+- ✅ **No JSON parsing errors** - SDK handles all validation
+- ✅ **No prompt engineering** - Schema enforcement is native to the SDK
+- ✅ **Better performance** - No retry/extraction logic needed
+
+> **Note:** A schema is required for JSON output. Using `responseFormat: { type: 'json' }` without a schema is not supported by Claude Code (matching Anthropic's official provider behavior). An `unsupported-setting` warning will be emitted and the call will be treated as plain text. Always use `generateObject()` or `streamObject()` with a Zod schema for guaranteed JSON output.
+
 ## Core Features
 
 - 🚀 Vercel AI SDK compatibility
 - 🔄 Streaming support
 - 💬 Multi-turn conversations
-- 🎯 Object generation with JSON schemas
+- 🎯 Native structured outputs with guaranteed schema compliance
 - 🛑 AbortSignal support
 - 🔧 Tool management (MCP servers, permissions)
 - 🧩 Callbacks (hooks, canUseTool)