@anthropic-ai/claude-agent-sdk 0.3.246 → 0.3.248

package/manifest.json

@@ -1,53 +1,51 @@
 {
-  "version": "2.1.246",
-  "commit": "1ba9d2211ae14e591bd1d60451c217c51f415e86",
-  "buildDate": "2026-08-25T18:46:33Z",
+  "version": "2.1.248",
+  "commit": "8c9482ad0510ad5e3c88f0ebe6f035ec148f73e2",
+  "buildDate": "2026-08-27T19:38:50Z",
   "platforms": {
     "darwin-arm64": {
       "binary": "claude",
-      "checksum": "7b09f01cb76a38e0e3a7c47c5d698d382162a5ff26538fc778683770caf9218b",
-      "size": 230824016
+      "checksum": "a3f276daa51919f378bcd797d44f8e3d09653c2858123157d272de38952efeef",
+      "size": 206463136
     },
     "darwin-x64": {
       "binary": "claude",
-      "checksum": "336625850986371487de7ece776d583f36cc3b3bc7178fcfbde3656d010289fb",
-      "size": 239710512
+      "checksum": "35c21b09d049a4d040c511cd9f73de01df83aa1d4b35a43ae1353bde413b42bc",
+      "size": 215124048
     },
     "linux-arm64": {
       "binary": "claude",
-      "checksum": "f98296e6e61c507589d1a973b262976b734700ec4e055cb64afdbf6d9a337db7",
-      "size": 247389632
+      "checksum": "76655a3731274f36236632b9acbcb9bef7055de20041c411b761856043fbc0df",
+      "size": 223141128
     },
     "linux-x64": {
       "binary": "claude",
-      "checksum": "1a0a662dc1bb938eaec38545abce9a4a69113d7d7f7c5e1a553ea276617b906a",
-      "size": 247905800
+      "checksum": "3edee3cb054bd6823674fd60d5c0e442825b28ee8fbf815af2d16bf0de072e16",
+      "size": 223599960
     },
     "linux-arm64-musl": {
       "binary": "claude",
-      "checksum": "8f7d77a91b95dbeda31393463b2ac7d2b490c577486829b732ce1ac41a747034",
-      "size": 240072248
+      "checksum": "ca9cabd7c636889de73c399d31be4f115fd2737c64482ada7bf4b1c0d51448f3",
+      "size": 215889472
     },
     "linux-x64-musl": {
       "binary": "claude",
-      "checksum": "81de46c50d987b99d2a1b4f3b11f3acf8c6deb57bef2a41f8e770837ddcf52fb",
-      "size": 241667960
+      "checksum": "155e1aa56d0c7e2aaae92788c414e7c43315220289bbd38f7a89ba33d07ff48f",
+      "size": 217575288
     },
     "win32-x64": {
       "binary": "claude.exe",
-      "checksum": "9f07f1ecaf26231fc2fac489e7c5214140d38fd14764938a2c8c46f31931d204",
-      "size": 250948768
+      "checksum": "c322169422b45ec4bbfeae3aae6cfd6367a622b0d12f06ba9766e18bb8eca2af",
+      "size": 226708128
     },
     "win32-arm64": {
       "binary": "claude.exe",
-      "checksum": "911036439b49e81c5801092764e803207fc56b4e690afadb743f51220c2f8201",
-      "size": 242062496
+      "checksum": "d3ee9756700a4e7642216e04f1a57baba9633732de9d85a4b7918c4731e4b572",
+      "size": 217812640
     }
   },
   "sdkCompat": {
     "testedWrapperVersions": [
-      "0.3.209",
-      "0.3.210",
       "0.3.211",
       "0.3.212",
       "0.3.214",

package/manifest.zst.json

@@ -1,61 +1,59 @@
 {
-  "version": "2.1.246",
-  "commit": "1ba9d2211ae14e591bd1d60451c217c51f415e86",
-  "buildDate": "2026-08-25T18:47:52Z",
+  "version": "2.1.248",
+  "commit": "8c9482ad0510ad5e3c88f0ebe6f035ec148f73e2",
+  "buildDate": "2026-08-27T19:40:05Z",
   "platforms": {
     "darwin-arm64": {
       "binary": "claude.zst",
-      "checksum": "1978b0b0167e7c077ae2536ed757a4dc22226540e3390bbc0884dc2ed3b9a0e3",
-      "size": 68186320,
+      "checksum": "b29c2c80dd0e93a692fdfd910204b04b61cc98983634bfb7d7ee3882809b4568",
+      "size": 63732872,
       "bundle": {
-        "checksum": "beec443ec1fc0f6989e5ddcf25b032cdccceb8ca76e86b4ce90808ce88aacc89",
-        "size": 68190259
+        "checksum": "19cdcfee1314ed0958a7805ce4dd000b4651d0cecca5f6bbcd9ef68976628a32",
+        "size": 63735676
       }
     },
     "darwin-x64": {
       "binary": "claude.zst",
-      "checksum": "b6269818f05c61f86029a018c39ed0903a5d69ad0eed6c0f05df7a79dd10c6ae",
-      "size": 72456477,
+      "checksum": "bb04d8fa542d01b96b6ddee76560667c50eeefb4cfb3b7ad5b9dc58d36dbfa5f",
+      "size": 67819333,
       "bundle": {
-        "checksum": "0f2691f9212e25422ed694d2eb6890030f27d1574b46af7d92d8b239127d3cba",
-        "size": 72465121
+        "checksum": "2db3fd3b76a70a421703ebfc23afee17cb40dfbf8b0bd46a5288dc041723e3d6",
+        "size": 67817366
       }
     },
     "linux-arm64": {
       "binary": "claude.zst",
-      "checksum": "68915f3c07ad0090466282d580df4f4a11b339cee26888ed25f9446bbbef5c91",
-      "size": 77461718
+      "checksum": "eb1343b9092ddfbaf39bc44afeaf596e0d62516aadcf00c32626753c267cd90d",
+      "size": 73072310
     },
     "linux-x64": {
       "binary": "claude.zst",
-      "checksum": "7fb5cc4ea9eb02c777a4d6363907957253fec6ee79617d145a142fbcc7e8c438",
-      "size": 78105392
+      "checksum": "c6e7e88189b5c8319e32b92ea53813eec683dcdfe187257d502b7e57d8e0f33a",
+      "size": 73704780
     },
     "linux-arm64-musl": {
       "binary": "claude.zst",
-      "checksum": "74583317118d09d3a263593b18420e7c67cd49844f59cc6b403377b2bf27bbe6",
-      "size": 75912733
+      "checksum": "68ef3296006335ab24a0eca03332e97d2e0e92909773c6629b559f2bb5d04503",
+      "size": 71555622
     },
     "linux-x64-musl": {
       "binary": "claude.zst",
-      "checksum": "8527572efb30d0e23a84f0871cc61d586f21400fcd3ca9e82f30c754bf6dfa10",
-      "size": 76577839
+      "checksum": "28dee5aabacf56bd7d0a984c89da642fae2e37e6782951efadcebe160fba00e5",
+      "size": 72211859
     },
     "win32-x64": {
       "binary": "claude.exe.zst",
-      "checksum": "4b49b5f1c4227009a57886d94f41fa887dafe0eaa4cb36252aed3954da663418",
-      "size": 80499903
+      "checksum": "efd339adce351a3406b9583c1ce1c2cace7c2745000d8adcb420477459edfc83",
+      "size": 76106262
     },
     "win32-arm64": {
       "binary": "claude.exe.zst",
-      "checksum": "d01182540877177cdf600be238069a11479f31b2fb4f76b736108b38e0e1ccd0",
-      "size": 77290190
+      "checksum": "d11e5d07414acaa8afd744bcc042da56406091a1b6ed9783591abeddd9f32272",
+      "size": 72889557
     }
   },
   "sdkCompat": {
     "testedWrapperVersions": [
-      "0.3.209",
-      "0.3.210",
       "0.3.211",
       "0.3.212",
       "0.3.214",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anthropic-ai/claude-agent-sdk",
-  "version": "0.3.246",
+  "version": "0.3.248",
   "main": "sdk.mjs",
   "types": "sdk.d.ts",
   "exports": {
@@ -57,14 +57,14 @@
     "zod": "^4.0.0"
   },
   "optionalDependencies": {
-    "@anthropic-ai/claude-agent-sdk-linux-x64": "0.3.246",
-    "@anthropic-ai/claude-agent-sdk-linux-arm64": "0.3.246",
-    "@anthropic-ai/claude-agent-sdk-linux-x64-musl": "0.3.246",
-    "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": "0.3.246",
-    "@anthropic-ai/claude-agent-sdk-darwin-x64": "0.3.246",
-    "@anthropic-ai/claude-agent-sdk-darwin-arm64": "0.3.246",
-    "@anthropic-ai/claude-agent-sdk-win32-x64": "0.3.246",
-    "@anthropic-ai/claude-agent-sdk-win32-arm64": "0.3.246"
+    "@anthropic-ai/claude-agent-sdk-linux-x64": "0.3.248",
+    "@anthropic-ai/claude-agent-sdk-linux-arm64": "0.3.248",
+    "@anthropic-ai/claude-agent-sdk-linux-x64-musl": "0.3.248",
+    "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": "0.3.248",
+    "@anthropic-ai/claude-agent-sdk-darwin-x64": "0.3.248",
+    "@anthropic-ai/claude-agent-sdk-darwin-arm64": "0.3.248",
+    "@anthropic-ai/claude-agent-sdk-win32-x64": "0.3.248",
+    "@anthropic-ai/claude-agent-sdk-win32-arm64": "0.3.248"
   },
   "files": [
     "sdk.mjs",
@@ -80,5 +80,5 @@
     "manifest.json",
     "manifest.zst.json"
   ],
-  "claudeCodeVersion": "2.1.246"
+  "claudeCodeVersion": "2.1.248"
 }

package/sdk-tools.d.ts

@@ -103,22 +103,6 @@ export type ToolOutputSchemas =
 export type AgentOutput =
   | {
       agentId: string;
-      /**
-       * @internal Count of leading harness-authored content blocks (hand-back provenance bookkeeping; not a stable consumer field)
-       */
-      harnessNoteCount?: number;
-      /**
-       * @internal Count of trailing harness-authored content blocks (hand-back provenance bookkeeping; not a stable consumer field)
-       */
-      harnessTailCount?: number;
-      /**
-       * @internal Fingerprint binding the harness section counts to the exact content they were computed against; a hook rewrite invalidates the counts rather than misplacing rewritten bytes
-       */
-      harnessSectionHash?: string;
-      /**
-       * @internal The handoff review was skipped because the provenance frame covers this delivery (tengu_auto_mode_config.classifyHandoff: false); the tool_result mapper MUST compose the frame when set, regardless of a fresh flag read
-       */
-      handoffReviewSkipped?: boolean;
       agentType?: string;
       content: {
         type: "text";
@@ -464,6 +448,7 @@ export type ArtifactOutput =
       artifacts: {
         title: string;
         url: string;
+        favicon?: string;
         updatedAt?: string;
         rel?: "mine" | "shared";
       }[];
@@ -3078,7 +3063,7 @@ export interface ArtifactInput {
    */
   file_path?: string;
   /**
-   * Browser-tab icon: one or two emoji (e.g. "📊"). No markup. Required to publish. Keep stable across redeploys; change only on a hard topic pivot.
+   * Browser-tab icon: one or two emoji (e.g. "📊"). No markup. Required on a page's first publish; omit on a redeploy (same file path this session, or `url`) to keep the artifact's icon — pass a new one only when the user asks.
    */
   favicon?: string;
   /**
@@ -3237,7 +3222,7 @@ export interface BashOutput {
    */
   ghRateLimitHint?: string;
   /**
-   * @internal Structured classification of git/gh operations detected in this command (commit/push/merge/rebase/PR). Client-facing — lets clients render git activity without re-parsing stdout; not surfaced to the model.
+   * Structured classification of git/gh operations detected in this command (commit/push/merge/rebase/PR). Client-facing — lets clients render git activity without re-parsing stdout; not surfaced to the model.
    */
   gitOperation?: {
     commit?: {

package/sdk.d.ts

@@ -499,8 +499,9 @@ declare namespace coreTypes {
  * Creates an MCP server instance that can be used with the SDK transport.
  * This allows SDK users to define custom tools that run in the same process.
  *
- * Tool calls are bounded by the MCP tool-call timeout — the MCP_TOOL_TIMEOUT
- * env var (ms), effectively unbounded by default.
+ * Tool calls are bounded by the MCP tool-call timeout — `options.timeout`
+ * (ms) for this server, else the MCP_TOOL_TIMEOUT env var, effectively
+ * unbounded by default.
  */
 export declare function createSdkMcpServer(_options: CreateSdkMcpServerOptions): McpSdkServerConfigWithInstance;
 
@@ -523,6 +524,15 @@ declare type CreateSdkMcpServerOptions = {
      * works and is OR'd with this.
      */
     alwaysLoad?: boolean;
+    /**
+     * Per-server tool-call timeout in milliseconds. Overrides the
+     * MCP_TOOL_TIMEOUT environment variable for this server. Hard wall-clock
+     * limit per call; progress notifications do not extend it. Values below
+     * 1000ms are ignored (falls through to MCP_TOOL_TIMEOUT or the default).
+     * Applies when the server is first registered; changing it for an
+     * already-registered server has no effect until it is removed and re-added.
+     */
+    timeout?: number;
 };
 
 export declare type CwdChangedHookInput = BaseHookInput & {
@@ -1075,6 +1085,10 @@ export declare type McpHttpServerConfig = {
 export declare type McpSdkServerConfig = {
     type: 'sdk';
     name: string;
+    /**
+     * Per-server tool-call timeout in milliseconds. Overrides the MCP_TOOL_TIMEOUT environment variable for this server. Hard wall-clock limit per call; progress notifications do not extend it. Values below 1000ms are ignored (falls through to MCP_TOOL_TIMEOUT or the default). Applies when the server is first registered; changing it for an already-registered server has no effect until it is removed and re-added.
+     */
+    timeout?: number;
 };
 
 /**
@@ -3154,7 +3168,7 @@ export declare type SDKAuthStatusMessage = {
 };
 
 /**
- * The full set of live background tasks, emitted whenever membership changes (start, completion, kill, a foreground agent being backgrounded). A level signal, unlike the task_started/task_notification edge bookends: consumers that only need 'is background work running' should replace their set with each payload rather than pairing edges, so a missed bookend cannot wedge a stale running indicator. Ordering relative to the bookends for the same transition is unspecified (in practice the level precedes them) and the payload carries ids only, so do not correlate it with the edge stream. The level is per-process: nothing is emitted at startup, so consumers must reset to the empty set whenever the session's CLI process (re)starts and let the next membership change repopulate it. A host that re-initializes an already-running process (a repeated `initialize` control request, e.g. after reconnecting) is sent a snapshot of the current set right behind the success response to that request, even when it is empty, so it need not wait for a change; CLIs that predate this send nothing there.
+ * The full set of live background tasks, emitted whenever membership changes (start, completion, kill, a foreground agent being backgrounded) or an entry's `ambient` flag flips. A level signal, unlike the task_started/task_notification edge bookends: consumers that only need 'is background work running' should replace their set with each payload rather than pairing edges, so a missed bookend cannot wedge a stale running indicator. Ordering relative to the bookends for the same transition is unspecified (in practice the level precedes them) and the payload carries ids only, so do not correlate it with the edge stream. The level is per-process: nothing is emitted at startup, so consumers must reset to the empty set whenever the session's CLI process (re)starts and let the next membership change repopulate it. A host that re-initializes an already-running process (a repeated `initialize` control request, e.g. after reconnecting) is sent a snapshot of the current set right behind the success response to that request, even when it is empty, so it need not wait for a change; CLIs that predate this send nothing there.
  */
 export declare type SDKBackgroundTasksChangedMessage = {
     type: 'system';
@@ -3166,6 +3180,10 @@ export declare type SDKBackgroundTasksChangedMessage = {
         task_id: string;
         task_type: string;
         description: string;
+        /**
+         * True for housekeeping tasks the CLI does not surface as user work (every skip_transcript task, plus auto-started live-update watchers); hosts should exclude them from activity indicators.
+         */
+        ambient?: boolean;
     }[];
     uuid: UUID;
     session_id: string;
@@ -3721,6 +3739,15 @@ declare type SDKControlInitializeRequest = {
     subtype: 'initialize';
     hooks?: Partial<Record<coreTypes.HookEvent, SDKHookCallbackMatcher[]>>;
     sdkMcpServers?: string[];
+    /**
+     * Settings for the SDK-hosted MCP servers named in sdkMcpServers, keyed by server name. Sent as a separate field so a CLI that predates it ignores it; entries whose name is not in sdkMcpServers, and values that do not match this shape, are ignored rather than rejected. Applied when the server is first registered.
+     */
+    sdkMcpServerConfigs?: Record<string, {
+        /**
+         * Per-server tool-call timeout in milliseconds. Overrides the MCP_TOOL_TIMEOUT environment variable for this server. Hard wall-clock limit per call; progress notifications do not extend it. Values below 1000ms are ignored (falls through to MCP_TOOL_TIMEOUT or the default). Applies when the server is first registered; changing it for an already-registered server has no effect until it is removed and re-added.
+         */
+        timeout?: number;
+    }>;
     jsonSchema?: Record<string, unknown>;
     systemPrompt?: string[];
     appendSystemPrompt?: string;
@@ -3793,6 +3820,7 @@ export declare type SDKControlInitializeResponse = {
 
 
 
+
 };
 
 /**
@@ -4864,6 +4892,7 @@ export declare type SDKSystemMessage = {
 
     fast_mode_state?: FastModeState;
     fast_mode_disabled_reason?: FastModeDisabledReason;
+
     /**
      * The effort level the session will send on its next request — after env overrides, session state, org caps and model-support downgrades; the same value get_settings reports as applied.effort. null when no effort parameter will be sent (a model without effort, CLAUDE_CODE_EFFORT_LEVEL=unset, or an internal numeric budget). Present on Remote Control bridge init frames (terminal- and Desktop/VS Code-hosted sessions); absent on hosts that do not publish it and on CLIs that predate the field. Re-emitted inits carry the current value — the newest frame wins.
      */
@@ -4877,6 +4906,8 @@ export declare type SDKSystemMessage = {
 
 
 
+
+
     uuid: UUID;
     session_id: string;
 };
@@ -4895,6 +4926,10 @@ export declare type SDKTaskNotificationMessage = {
         duration_ms: number;
     };
     skip_transcript?: boolean;
+    /**
+     * True for housekeeping tasks the CLI does not surface as user work (every skip_transcript task, plus auto-started live-update watchers); hosts should exclude them from activity indicators.
+     */
+    ambient?: boolean;
     uuid: UUID;
     session_id: string;
 };
@@ -4949,6 +4984,10 @@ export declare type SDKTaskStartedMessage = {
      * Ambient/housekeeping task. Consumers should hide this from the inline transcript; it may still appear in a tasks panel.
      */
     skip_transcript?: boolean;
+    /**
+     * True for housekeeping tasks the CLI does not surface as user work (every skip_transcript task, plus auto-started live-update watchers); hosts should exclude them from activity indicators.
+     */
+    ambient?: boolean;
     uuid: UUID;
     session_id: string;
 };
@@ -5055,6 +5094,7 @@ export declare type SDKUserMessage = {
 
 
 
+
     uuid?: UUID;
     session_id?: string;
     /**
@@ -5105,6 +5145,7 @@ export declare type SDKUserMessageReplay = {
 
 
 
+
     uuid: UUID;
     session_id: string;
     isReplay: true;
@@ -5440,6 +5481,10 @@ export declare interface Settings {
      * Number of days to retain chat transcripts before automatic cleanup (default: 30). Minimum 1. Use a large value for long retention; use --no-session-persistence to disable transcript writes entirely.
      */
     cleanupPeriodDays?: number;
+    /**
+     * Retention ceiling in days for session transcripts created or last written by a desktop-host surface (Claude Desktop, Cowork), which are otherwise exempt from the cleanupPeriodDays sweep. 0 (the default) means no ceiling: such transcripts are kept until deleted another way. Unlike cleanupPeriodDays, 0 is allowed because this setting never disables writes — it only bounds an exemption from deletion. The ceiling is a hard cap: it also bounds an active archive grace, so the grace window of a release marker never keeps files past the ceiling. Ignored when cleanupPeriodDays is managed by org policy. A ceiling at or below cleanupPeriodDays effectively disables the exemption: those transcripts age out on the regular cleanupPeriodDays schedule, so the effective retention is whichever of the two periods is longer.
+     */
+    desktopSessionCleanupPeriodDays?: number;
     /**
      * Set to false to turn off syncing of the skills you have enabled on claude.ai. In your user settings (or managed settings): nothing more is downloaded, previously synced skills (~/.claude/skills/synced) can no longer be run, are hidden from every session started afterwards, and are moved to ~/.claude/skills/.trash at the next launch (deleted after cleanupPeriodDays; re-downloaded, not restored, if you re-enable). In .claude/settings.local.json or --settings: downloads stop and synced skills are blocked and hidden for sessions in that workspace or invocation only (nothing is moved). Not read from project settings (.claude/settings.json). Only false is honored — the feature is enabled server-side for your account, so setting true does not turn it on early. While it is on, synced skills are available in every session, re-synced every 10 minutes, and removed when you disable them on claude.ai. Only applies when signed in with your Claude account.
      */
@@ -7469,11 +7514,22 @@ export declare interface Settings {
         verbs: string[];
     };
     /**
-     * Override spinner tips. tips: array of tip strings. excludeDefault: if true, only show custom tips (default: false).
+     * Add your organization's own tips to the spinner tip rotation. tips: strings or {id, text, cooldownSessions?, priority?} objects; tipsFile: a JSON file of the same; label: prefix shown before your tips; excludeDefault: if true, only show your tips (default: false).
      */
     spinnerTipsOverride?: {
         excludeDefault?: boolean;
-        tips: string[];
+        tips?: (string | {
+            [k: string]: unknown;
+        })[];
+        /**
+         * Absolute or ~/ local path to a JSON file holding an array of tips (same shapes as `tips`); honored from user, --settings and on-disk managed settings only. Read once per CLI process (restart to pick up edits).
+         */
+        tipsFile?: string;
+        /**
+         * Prefix shown before your tips in the spinner (default "Tip")
+         */
+        label?: string;
+        [k: string]: unknown;
     };
     /**
      * Whether to disable syntax highlighting in diffs