ai-sdk-provider-claude-code 3.0.0 → 3.1.0

package/README.md

@@ -269,6 +269,28 @@ console.log(result.object); // Guaranteed to match schema
 - 🔧 Tool management (MCP servers, permissions)
 - 🧩 Callbacks (hooks, canUseTool)
 
+## Agent SDK Options (Advanced)
+
+This provider now exposes additional Agent SDK options directly (e.g. `betas`, `sandbox`,
+`plugins`, `resumeSessionAt`, `enableFileCheckpointing`, `maxBudgetUsd`, `tools`,
+`allowDangerouslySkipPermissions`).
+
+For newer SDK options, use the `sdkOptions` escape hatch. It **overrides** explicit settings,
+but provider-managed fields are ignored (`model`, `abortController`, `prompt`, `outputFormat`).
+If you set `sdkOptions.resume`, it also drives the streaming prompt `session_id` so the SDK
+and prompt target the same session.
+
+```ts
+const model = claudeCode('sonnet', {
+  betas: ['context-1m-2025-08-07'],
+  sandbox: { enabled: true },
+  sdkOptions: {
+    maxBudgetUsd: 1,
+    resume: 'session-abc',
+  },
+});
+```
+
 ## Image Inputs (Streaming Only)
 
 - Enable streaming input (`streamingInput: 'always'` or provide `canUseTool`) before sending images.
@@ -278,6 +300,37 @@ console.log(result.object); // Guaranteed to match schema
 - Use realistic image payloads—very small placeholders may result in the model asking for a different image.
 - `examples/images.ts` accepts a local image path and converts it to a data URL on the fly: `npx tsx examples/images.ts /absolute/path/to/image.png`.
 
+## Skills Support
+
+Claude Code supports **Skills** - custom tools and capabilities defined in your user or project settings. To enable skills, configure both `settingSources` and `allowedTools`:
+
+```typescript
+import { claudeCode } from 'ai-sdk-provider-claude-code';
+import { streamText } from 'ai';
+
+const result = await streamText({
+  model: claudeCode('sonnet', {
+    settingSources: ['user', 'project'],
+    allowedTools: ['Skill', 'Read', 'Write', 'Bash'],
+  }),
+  prompt: 'Use my /custom-skill to help with this task',
+});
+```
+
+**Requirements:**
+
+- `settingSources` - Where to load skills from (`'user'`, `'project'`, `'local'`)
+- `allowedTools` must include `'Skill'` to invoke skills
+
+**Where to define Skills:**
+
+- User: `~/.claude/skills/your-skill/SKILL.md`
+- Project: `.claude/skills/your-skill/SKILL.md`
+
+**Validation:** If you add `'Skill'` to `allowedTools` but forget to set `settingSources`, a validation warning will alert you that skills won't load.
+
+See [examples/skills-management.ts](examples/skills-management.ts) for more examples.
+
 ## Limitations
 
 - Requires Node.js ≥ 18

package/dist/index.cjs

@@ -467,6 +467,27 @@ var claudeCodeSettingsSchema = import_zod.z.object({
   resume: import_zod.z.string().optional(),
   allowedTools: import_zod.z.array(import_zod.z.string()).optional(),
   disallowedTools: import_zod.z.array(import_zod.z.string()).optional(),
+  betas: import_zod.z.array(import_zod.z.string()).optional(),
+  allowDangerouslySkipPermissions: import_zod.z.boolean().optional(),
+  enableFileCheckpointing: import_zod.z.boolean().optional(),
+  maxBudgetUsd: import_zod.z.number().min(0).optional(),
+  plugins: import_zod.z.array(
+    import_zod.z.object({
+      type: import_zod.z.string(),
+      path: import_zod.z.string()
+    }).passthrough()
+  ).optional(),
+  resumeSessionAt: import_zod.z.string().optional(),
+  sandbox: import_zod.z.any().refine((val) => val === void 0 || typeof val === "object", {
+    message: "sandbox must be an object"
+  }).optional(),
+  tools: import_zod.z.union([
+    import_zod.z.array(import_zod.z.string()),
+    import_zod.z.object({
+      type: import_zod.z.literal("preset"),
+      preset: import_zod.z.literal("claude_code")
+    })
+  ]).optional(),
   settingSources: import_zod.z.array(import_zod.z.enum(["user", "project", "local"])).optional(),
   streamingInput: import_zod.z.enum(["auto", "always", "off"]).optional(),
   // Hooks and tool-permission callback (permissive validation of shapes)
@@ -532,7 +553,8 @@ var claudeCodeSettingsSchema = import_zod.z.object({
     message: "stderr must be a function"
   }).optional(),
   strictMcpConfig: import_zod.z.boolean().optional(),
-  extraArgs: import_zod.z.record(import_zod.z.string(), import_zod.z.union([import_zod.z.string(), import_zod.z.null()])).optional()
+  extraArgs: import_zod.z.record(import_zod.z.string(), import_zod.z.union([import_zod.z.string(), import_zod.z.null()])).optional(),
+  sdkOptions: import_zod.z.record(import_zod.z.string(), import_zod.z.any()).optional()
 }).strict();
 function validateModelId(modelId) {
   const knownModels = ["opus", "sonnet", "haiku"];
@@ -587,6 +609,11 @@ function validateSettings(settings) {
     if (validSettings.disallowedTools) {
       validateToolNames(validSettings.disallowedTools, "disallowed");
     }
+    if (validSettings.allowedTools?.includes("Skill") && !validSettings.settingSources) {
+      warnings.push(
+        "allowedTools includes 'Skill' but settingSources is not set. Skills require settingSources (e.g., ['user', 'project']) to load skill definitions."
+      );
+    }
     return { valid: true, warnings, errors };
   } catch (error) {
     errors.push(`Validation error: ${error instanceof Error ? error.message : String(error)}`);
@@ -609,7 +636,9 @@ function validateSessionId(sessionId) {
 
 // src/logger.ts
 var defaultLogger = {
+  // eslint-disable-next-line no-console
   debug: (message) => console.debug(`[DEBUG] ${message}`),
+  // eslint-disable-next-line no-console
   info: (message) => console.info(`[INFO] ${message}`),
   warn: (message) => console.warn(`[WARN] ${message}`),
   error: (message) => console.error(`[ERROR] ${message}`)
@@ -691,6 +720,7 @@ function isAbortError(err) {
   return false;
 }
 var STREAMING_FEATURE_WARNING = "Claude Agent SDK features (hooks/MCP/images) require streaming input. Set `streamingInput: 'always'` or provide `canUseTool` (auto streams only when canUseTool is set).";
+var SDK_OPTIONS_BLOCKLIST = /* @__PURE__ */ new Set(["model", "abortController", "prompt", "outputFormat"]);
 function createEmptyUsage() {
   return {
     inputTokens: {
@@ -795,6 +825,25 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
     const mapped = modelMap[this.modelId];
     return mapped ?? this.modelId;
   }
+  getSanitizedSdkOptions() {
+    if (!this.settings.sdkOptions || typeof this.settings.sdkOptions !== "object") {
+      return void 0;
+    }
+    const sanitized = { ...this.settings.sdkOptions };
+    const blockedKeys = Array.from(SDK_OPTIONS_BLOCKLIST).filter((key) => key in sanitized);
+    if (blockedKeys.length > 0) {
+      this.logger.warn(
+        `[claude-code] sdkOptions includes provider-managed fields (${blockedKeys.join(
+          ", "
+        )}); these will be ignored.`
+      );
+      blockedKeys.forEach((key) => delete sanitized[key]);
+    }
+    return sanitized;
+  }
+  getEffectiveResume(sdkOptions) {
+    return sdkOptions?.resume ?? this.settings.resume ?? this.sessionId;
+  }
   extractToolUses(content) {
     if (!Array.isArray(content)) {
       return [];
@@ -928,11 +977,11 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
     }
     return warnings;
   }
-  createQueryOptions(abortController, responseFormat) {
+  createQueryOptions(abortController, responseFormat, stderrCollector, sdkOptions, effectiveResume) {
     const opts = {
       model: this.getModel(),
       abortController,
-      resume: this.settings.resume ?? this.sessionId,
+      resume: effectiveResume ?? this.settings.resume ?? this.sessionId,
       pathToClaudeCodeExecutable: this.settings.pathToClaudeCodeExecutable,
       maxTurns: this.settings.maxTurns,
       maxThinkingTokens: this.settings.maxThinkingTokens,
@@ -944,6 +993,14 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
       continue: this.settings.continue,
       allowedTools: this.settings.allowedTools,
       disallowedTools: this.settings.disallowedTools,
+      betas: this.settings.betas,
+      allowDangerouslySkipPermissions: this.settings.allowDangerouslySkipPermissions,
+      enableFileCheckpointing: this.settings.enableFileCheckpointing,
+      maxBudgetUsd: this.settings.maxBudgetUsd,
+      plugins: this.settings.plugins,
+      resumeSessionAt: this.settings.resumeSessionAt,
+      sandbox: this.settings.sandbox,
+      tools: this.settings.tools,
       mcpServers: this.settings.mcpServers,
       canUseTool: this.settings.canUseTool
     };
@@ -982,9 +1039,6 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
     if (this.settings.forkSession !== void 0) {
       opts.forkSession = this.settings.forkSession;
     }
-    if (this.settings.stderr !== void 0) {
-      opts.stderr = this.settings.stderr;
-    }
     if (this.settings.strictMcpConfig !== void 0) {
       opts.strictMcpConfig = this.settings.strictMcpConfig;
     }
@@ -994,8 +1048,24 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
     if (this.settings.hooks) {
       opts.hooks = this.settings.hooks;
     }
-    if (this.settings.env !== void 0) {
-      opts.env = { ...process.env, ...this.settings.env };
+    const sdkOverrides = sdkOptions ? sdkOptions : void 0;
+    const sdkEnv = sdkOverrides && typeof sdkOverrides.env === "object" && sdkOverrides.env !== null ? sdkOverrides.env : void 0;
+    const sdkStderr = sdkOverrides && typeof sdkOverrides.stderr === "function" ? sdkOverrides.stderr : void 0;
+    if (sdkOverrides) {
+      const rest = { ...sdkOverrides };
+      delete rest.env;
+      delete rest.stderr;
+      Object.assign(opts, rest);
+    }
+    const userStderrCallback = sdkStderr ?? this.settings.stderr;
+    if (stderrCollector || userStderrCallback) {
+      opts.stderr = (data) => {
+        if (stderrCollector) stderrCollector(data);
+        if (userStderrCallback) userStderrCallback(data);
+      };
+    }
+    if (this.settings.env !== void 0 || sdkEnv !== void 0) {
+      opts.env = { ...process.env, ...this.settings.env, ...sdkEnv };
     }
     if (responseFormat?.type === "json" && responseFormat.schema) {
       opts.outputFormat = {
@@ -1005,7 +1075,7 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
     }
     return opts;
   }
-  handleClaudeCodeError(error, messagesPrompt) {
+  handleClaudeCodeError(error, messagesPrompt, collectedStderr) {
     if (isAbortError(error)) {
       throw error;
     }
@@ -1021,7 +1091,10 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
       "unauthorized",
       "auth failed",
       "please login",
-      "claude login"
+      "claude login",
+      "/login",
+      // CLI returns "Please run /login"
+      "invalid api key"
     ];
     const errorMessage = isErrorWithMessage(error) && error.message ? error.message.toLowerCase() : "";
     const exitCode = isErrorWithCode(error) && typeof error.exitCode === "number" ? error.exitCode : void 0;
@@ -1041,11 +1114,13 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
       });
     }
     const isRetryable = errorCode === "ENOENT" || errorCode === "ECONNREFUSED" || errorCode === "ETIMEDOUT" || errorCode === "ECONNRESET";
+    const stderrFromError = isErrorWithCode(error) && typeof error.stderr === "string" ? error.stderr : void 0;
+    const stderr = stderrFromError || collectedStderr || void 0;
     return createAPICallError({
       message: isErrorWithMessage(error) && error.message ? error.message : "Claude Code SDK error",
       code: errorCode || void 0,
       exitCode,
-      stderr: isErrorWithCode(error) && typeof error.stderr === "string" ? error.stderr : void 0,
+      stderr,
       promptExcerpt: messagesPrompt.substring(0, 200),
       isRetryable
     });
@@ -1077,7 +1152,19 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
       abortListener = () => abortController.abort(options.abortSignal?.reason);
       options.abortSignal.addEventListener("abort", abortListener, { once: true });
     }
-    const queryOptions = this.createQueryOptions(abortController, options.responseFormat);
+    let collectedStderr = "";
+    const stderrCollector = (data) => {
+      collectedStderr += data;
+    };
+    const sdkOptions = this.getSanitizedSdkOptions();
+    const effectiveResume = this.getEffectiveResume(sdkOptions);
+    const queryOptions = this.createQueryOptions(
+      abortController,
+      options.responseFormat,
+      stderrCollector,
+      sdkOptions,
+      effectiveResume
+    );
     let text = "";
     let structuredOutput;
     let usage = createEmptyUsage();
@@ -1095,7 +1182,9 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
       });
     }
     const modeSetting = this.settings.streamingInput ?? "auto";
-    const wantsStreamInput = modeSetting === "always" || modeSetting === "auto" && !!this.settings.canUseTool;
+    const effectiveCanUseTool = sdkOptions?.canUseTool ?? this.settings.canUseTool;
+    const effectivePermissionPromptToolName = sdkOptions?.permissionPromptToolName ?? this.settings.permissionPromptToolName;
+    const wantsStreamInput = modeSetting === "always" || modeSetting === "auto" && !!effectiveCanUseTool;
     if (!wantsStreamInput && hasImageParts) {
       warnings.push({
         type: "other",
@@ -1108,7 +1197,7 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
       done = () => resolve(void 0);
     });
     try {
-      if (this.settings.canUseTool && this.settings.permissionPromptToolName) {
+      if (effectiveCanUseTool && effectivePermissionPromptToolName) {
         throw new Error(
           "canUseTool requires streamingInput mode ('auto' or 'always') and cannot be used with permissionPromptToolName (SDK constraint). Set streamingInput: 'auto' (or 'always') and remove permissionPromptToolName, or remove canUseTool."
         );
@@ -1116,11 +1205,11 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
       const sdkPrompt = wantsStreamInput ? toAsyncIterablePrompt(
         messagesPrompt,
         outputStreamEnded,
-        this.settings.resume ?? this.sessionId,
+        effectiveResume,
         streamingContentParts
       ) : messagesPrompt;
       this.logger.debug(
-        `[claude-code] Executing query with streamingInput: ${wantsStreamInput}, session: ${this.settings.resume ?? this.sessionId ?? "new"}`
+        `[claude-code] Executing query with streamingInput: ${wantsStreamInput}, session: ${effectiveResume ?? "new"}`
       );
       const response = (0, import_claude_agent_sdk.query)({
         prompt: sdkPrompt,
@@ -1135,6 +1224,10 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
           this.setSessionId(message.session_id);
           costUsd = message.total_cost_usd;
           durationMs = message.duration_ms;
+          if ("is_error" in message && message.is_error === true) {
+            const errorMessage = "result" in message && typeof message.result === "string" ? message.result : "Claude Code CLI returned an error";
+            throw Object.assign(new Error(errorMessage), { exitCode: 1 });
+          }
           if (message.subtype === "error_max_structured_output_retries") {
             throw new Error(
               "Failed to generate valid structured output after maximum retries. The model could not produce a response matching the required schema."
@@ -1180,7 +1273,7 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
           message: CLAUDE_CODE_TRUNCATION_WARNING
         });
       } else {
-        throw this.handleClaudeCodeError(error, messagesPrompt);
+        throw this.handleClaudeCodeError(error, messagesPrompt, collectedStderr);
       }
     } finally {
       if (options.abortSignal && abortListener) {
@@ -1231,7 +1324,19 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
       abortListener = () => abortController.abort(options.abortSignal?.reason);
       options.abortSignal.addEventListener("abort", abortListener, { once: true });
     }
-    const queryOptions = this.createQueryOptions(abortController, options.responseFormat);
+    let collectedStderr = "";
+    const stderrCollector = (data) => {
+      collectedStderr += data;
+    };
+    const sdkOptions = this.getSanitizedSdkOptions();
+    const effectiveResume = this.getEffectiveResume(sdkOptions);
+    const queryOptions = this.createQueryOptions(
+      abortController,
+      options.responseFormat,
+      stderrCollector,
+      sdkOptions,
+      effectiveResume
+    );
     if (queryOptions.includePartialMessages === void 0) {
       queryOptions.includePartialMessages = true;
     }
@@ -1245,7 +1350,9 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
       });
     }
     const modeSetting = this.settings.streamingInput ?? "auto";
-    const wantsStreamInput = modeSetting === "always" || modeSetting === "auto" && !!this.settings.canUseTool;
+    const effectiveCanUseTool = sdkOptions?.canUseTool ?? this.settings.canUseTool;
+    const effectivePermissionPromptToolName = sdkOptions?.permissionPromptToolName ?? this.settings.permissionPromptToolName;
+    const wantsStreamInput = modeSetting === "always" || modeSetting === "auto" && !!effectiveCanUseTool;
     if (!wantsStreamInput && hasImageParts) {
       warnings.push({
         type: "other",
@@ -1307,7 +1414,7 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
         let hasReceivedStreamEvents = false;
         try {
           controller.enqueue({ type: "stream-start", warnings });
-          if (this.settings.canUseTool && this.settings.permissionPromptToolName) {
+          if (effectiveCanUseTool && effectivePermissionPromptToolName) {
             throw new Error(
               "canUseTool requires streamingInput mode ('auto' or 'always') and cannot be used with permissionPromptToolName (SDK constraint). Set streamingInput: 'auto' (or 'always') and remove permissionPromptToolName, or remove canUseTool."
             );
@@ -1315,11 +1422,11 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
           const sdkPrompt = wantsStreamInput ? toAsyncIterablePrompt(
             messagesPrompt,
             outputStreamEnded,
-            this.settings.resume ?? this.sessionId,
+            effectiveResume,
             streamingContentParts
           ) : messagesPrompt;
           this.logger.debug(
-            `[claude-code] Starting stream query with streamingInput: ${wantsStreamInput}, session: ${this.settings.resume ?? this.sessionId ?? "new"}`
+            `[claude-code] Starting stream query with streamingInput: ${wantsStreamInput}, session: ${effectiveResume ?? "new"}`
           );
           const response = (0, import_claude_agent_sdk.query)({
             prompt: sdkPrompt,
@@ -1590,6 +1697,10 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
               }
             } else if (message.type === "result") {
               done();
+              if ("is_error" in message && message.is_error === true) {
+                const errorMessage = "result" in message && typeof message.result === "string" ? message.result : "Claude Code CLI returned an error";
+                throw Object.assign(new Error(errorMessage), { exitCode: 1 });
+              }
               if (message.subtype === "error_max_structured_output_retries") {
                 throw new Error(
                   "Failed to generate valid structured output after maximum retries. The model could not produce a response matching the required schema."
@@ -1748,7 +1859,7 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
           if (isAbortError(error)) {
             errorToEmit = options.abortSignal?.aborted ? options.abortSignal.reason : error;
           } else {
-            errorToEmit = this.handleClaudeCodeError(error, messagesPrompt);
+            errorToEmit = this.handleClaudeCodeError(error, messagesPrompt, collectedStderr);
           }
           controller.enqueue({
             type: "error",