ai-sdk-provider-claude-code 3.3.6 → 3.4.1

package/docs/ai-sdk-v4/GUIDE.md

@@ -252,7 +252,7 @@ const gitOnlyClaude = createClaudeCode({
 
 // Mix built-in and MCP tools
 const mixedClaude = createClaudeCode({
-  allowedTools: ['Read', 'Bash(npm test:*)', 'mcp__filesystem__read_file', 'mcp__git__status'],
+  allowedTools: ['Read', 'Bash(npm test:*)', 'mcp__filesystem__read_text_file', 'mcp__git__status'],
 });
 ```
 

package/docs/ai-sdk-v5/GUIDE.md

@@ -148,6 +148,15 @@ const response = await generateText({
 
 `resume` continues a previous CLI session instead of starting a new one.
 
+You can also pass a deterministic `sessionId` for correlation and tracking:
+
+```typescript
+const result = await generateText({
+  model: claudeCode('sonnet', { sessionId: 'my-custom-session-id' }),
+  messages: [{ role: 'user', content: [{ type: 'text', text: 'Hello' }] }],
+});
+```
+
 ---
 
 ## Key Changes in v5
@@ -247,8 +256,11 @@ const result = await generateText({
 | `mcpServers`                 | `object`                                  | `undefined` | MCP server configuration                                           |
 | `env`                        | `Record<string, string>`                  | `undefined` | Environment variables passed to CLI                                |
 | `resume`                     | `string`                                  | `undefined` | Resume an existing session                                         |
+| `sessionId`                  | `string`                                  | `undefined` | Use a specific session ID for tracking and correlation             |
 | `hooks`                      | `object`                                  | `undefined` | Lifecycle hooks (e.g., PreToolUse, PostToolUse)                    |
 | `canUseTool`                 | `(name, input, opts) => Promise`          | `undefined` | Runtime permission callback. Requires streaming input at SDK level |
+| `debug`                      | `boolean`                                 | `undefined` | Enable SDK-level debug logging                                     |
+| `debugFile`                  | `string`                                  | `undefined` | Path to a file for SDK debug log output                            |
 
 ### Custom Configuration
 
@@ -424,6 +436,17 @@ try {
 }
 ```
 
+#### SDK Debug Logging
+
+Separate from the provider-level verbose/logger system, you can enable the underlying Agent SDK's own debug logging. This captures lower-level SDK internals and can be written to a file:
+
+```typescript
+const model = claudeCode('sonnet', {
+  debug: true, // Enable SDK debug output
+  debugFile: '/tmp/sdk.log', // Write SDK debug logs to file
+});
+```
+
 ### Tool Management
 
 Control which tools Claude Code can use with either `allowedTools` (allowlist) or `disallowedTools` (denylist). These flags work for **both built-in Claude tools and MCP tools**, providing session-only permission overrides.
@@ -450,7 +473,7 @@ const gitOnlyClaude = createClaudeCode({
 
 // Mix built-in and MCP tools
 const mixedClaude = createClaudeCode({
-  allowedTools: ['Read', 'Bash(npm test:*)', 'mcp__filesystem__read_file', 'mcp__git__status'],
+  allowedTools: ['Read', 'Bash(npm test:*)', 'mcp__filesystem__read_text_file', 'mcp__git__status'],
 });
 ```
 
@@ -579,6 +602,38 @@ Notes:
 - Tool naming for allow/deny: `mcp__<serverName>__<toolName>`; to allow an entire server: `mcp__<serverName>`.
 - Security: only allow the tools you intend; prefer allowlists in sensitive environments.
 
+#### Tool Annotations
+
+You can add MCP tool annotations to hint tool behavior. The `createCustomMcpServer` convenience helper accepts an optional `annotations` field per tool:
+
+```typescript
+import { z } from 'zod';
+import { createClaudeCode, createCustomMcpServer } from 'ai-sdk-provider-claude-code';
+
+const server = createCustomMcpServer({
+  name: 'my-tools',
+  tools: {
+    lookup: {
+      description: 'Look up a value by key',
+      inputSchema: z.object({ key: z.string() }),
+      handler: async ({ key }) => ({
+        content: [{ type: 'text', text: `value for ${key}` }],
+      }),
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+      },
+    },
+  },
+});
+
+const claude = createClaudeCode({
+  defaultSettings: { mcpServers: { 'my-tools': server } },
+});
+```
+
+Supported annotation hints: `readOnlyHint`, `destructiveHint`, `openWorldHint`, `idempotentHint`.
+
 ### Hooks and Runtime Permissions
 
 You can intercept lifecycle events and apply custom runtime permissions:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-sdk-provider-claude-code",
-  "version": "3.3.6",
+  "version": "3.4.1",
   "description": "AI SDK v6 provider for Claude via Claude Agent SDK (use Pro/Max subscription)",
   "keywords": [
     "ai-sdk",
@@ -61,19 +61,20 @@
     "example:streaming": "npm run build && npx tsx examples/streaming.ts",
     "example:conversation": "npm run build && npx tsx examples/conversation-history.ts",
     "example:config": "npm run build && npx tsx examples/custom-config.ts",
-    "example:object:basic": "npm run build && npx tsx examples/generate-object-basic.ts",
-    "example:object:nested": "npm run build && npx tsx examples/generate-object-nested.ts",
+    "example:object": "npm run build && npx tsx examples/generate-object.ts",
     "example:object:constraints": "npm run build && npx tsx examples/generate-object-constraints.ts",
     "example:tools": "npm run build && npx tsx examples/tool-management.ts",
+    "example:mcp:filesystem": "npm run build && npx tsx examples/mcp-filesystem.ts",
+    "example:mcp:exa": "npm run build && npx tsx examples/mcp-exa.ts",
     "example:timeout": "npm run build && npx tsx examples/long-running-tasks.ts",
     "example:zod4": "npm run build && npx tsx examples/zod4-compatibility-test.ts",
     "example:structured-repro": "npx tsx examples/structured-output-repro.ts",
-    "example:all": "npm run build && npm run example:basic && npm run example:streaming && npm run example:conversation && npm run example:config && npm run example:object:basic && npm run example:object:nested && npm run example:object:constraints && npm run example:tools && npm run example:timeout"
+    "example:all": "npm run build && npm run example:basic && npm run example:streaming && npm run example:conversation && npm run example:config && npm run example:object && npm run example:object:constraints && npm run example:tools && npm run example:timeout"
   },
   "dependencies": {
     "@ai-sdk/provider": "^3.0.0",
     "@ai-sdk/provider-utils": "^4.0.1",
-    "@anthropic-ai/claude-agent-sdk": "^0.2.23"
+    "@anthropic-ai/claude-agent-sdk": "^0.2.33"
   },
   "devDependencies": {
     "@edge-runtime/vm": "5.0.0",