@anthropic-ai/claude-agent-sdk 0.3.221 → 0.3.223

package/manifest.json

@@ -1,52 +1,51 @@
 {
-  "version": "2.1.221",
-  "commit": "6efaf12e8b43dc7dbe50e0955c76dc4174a15876",
-  "buildDate": "2026-08-03T21:08:11Z",
+  "version": "2.1.223",
+  "commit": "4535f69721056abf01650c73ee8a91c69ba00838",
+  "buildDate": "2026-08-05T21:55:19Z",
   "platforms": {
     "darwin-arm64": {
       "binary": "claude",
-      "checksum": "7a181f36ed0fc4fbac6cee4ecf2b615eff93d8b434221fff5d7c878dc5ebf380",
-      "size": 270518240
+      "checksum": "fcbe0b8d47570c501302dd1ad31cc26ac2810f022c45fa253936a6961dee32bf",
+      "size": 272553824
     },
     "darwin-x64": {
       "binary": "claude",
-      "checksum": "f408b9f7e46439f6e34a3687ff67433fc6bc189f40220ce4f0a1e829e58f0a52",
-      "size": 280087584
+      "checksum": "350e657428a6d34f7cf71f6738c5ebb6a1952ccb12fc1747f64297e065b1846f",
+      "size": 282118560
     },
     "linux-arm64": {
       "binary": "claude",
-      "checksum": "d3c59d6bcc4adcf4cd85abca3bc13fa1131a34cb32f982bdf030d83a3b11e700",
-      "size": 285457336
+      "checksum": "60e83d8db0e894d0e54413e5e7daa256d180db660f51e139a51b614fc30cf3ac",
+      "size": 287423416
     },
     "linux-x64": {
       "binary": "claude",
-      "checksum": "60db8e88d42c24b5199c92cfd56ec88370c510c3789c6f364af748354f087ada",
-      "size": 288705544
+      "checksum": "98226474f802e3094d6a86c5ade8883c16206d0fcb5c400b7401c800063e99d7",
+      "size": 290728968
     },
     "linux-arm64-musl": {
       "binary": "claude",
-      "checksum": "85985afd58d33578efd217788dd9e5cbbc0177ad00e638d9316c6fd89640f3ff",
-      "size": 278771048
+      "checksum": "f41692eab23ebcd836d342fbc494d8783b1f19efb13d04fbf8461d2806ccb586",
+      "size": 280737128
     },
     "linux-x64-musl": {
       "binary": "claude",
-      "checksum": "15b068e06eafff9b64583b46cdc065ac18b0d0d13950c2a83c6ee854f301a32f",
-      "size": 283312720
+      "checksum": "8a4e561e8af19746d2defcf1a5661f5c0384c9c26dadd87d45e11b67802ad147",
+      "size": 285336144
     },
     "win32-x64": {
       "binary": "claude.exe",
-      "checksum": "0f73196359a07f9ad435a8c83ca7c741b9f2adbc0ad9b05f71a0c2f4aabe906a",
-      "size": 278279328
+      "checksum": "a708ba811c4cc46907df358e22f2aa6da3dbc28192747e4d3c4a0869752fe722",
+      "size": 280233632
     },
     "win32-arm64": {
       "binary": "claude.exe",
-      "checksum": "1407585e0c33a70061d6ea7cb873b8582dcedbe928d2118982676f1951576a58",
-      "size": 272952480
+      "checksum": "8efb44f04fda50fac3c7602276903e44ff82d48f1a29a41f1a5d98891a01864b",
+      "size": 274906784
     }
   },
   "sdkCompat": {
     "testedWrapperVersions": [
-      "0.3.181",
       "0.3.182",
       "0.3.183",
       "0.3.185",
@@ -75,7 +74,8 @@
       "0.3.215",
       "0.3.217",
       "0.3.218",
-      "0.3.220"
+      "0.3.220",
+      "0.3.221"
     ],
     "harnessSchema": 1
   }

package/manifest.zst.json

@@ -1,60 +1,59 @@
 {
-  "version": "2.1.221",
-  "commit": "6efaf12e8b43dc7dbe50e0955c76dc4174a15876",
-  "buildDate": "2026-08-03T21:10:16Z",
+  "version": "2.1.223",
+  "commit": "4535f69721056abf01650c73ee8a91c69ba00838",
+  "buildDate": "2026-08-05T21:57:22Z",
   "platforms": {
     "darwin-arm64": {
       "binary": "claude.zst",
-      "checksum": "3cc00a82f60d6be3d57a13360ac4cb544c44420c744238df7ff03956e3323184",
-      "size": 54310824,
+      "checksum": "66736b64309852d44c184d5e3b431dd291581a6be9850715a8d3c3ce2aba4a61",
+      "size": 54612115,
       "bundle": {
-        "checksum": "e3627fb90b70c823fd6b1afea5b3747ba8a66925dcc7f20f89b1eaa14c1e5af0",
-        "size": 54313524
+        "checksum": "1aa06b34b3da404d607488aa9a4b946a4f3b0383d549615928a5355f83af89a5",
+        "size": 54613585
       }
     },
     "darwin-x64": {
       "binary": "claude.zst",
-      "checksum": "b000bac7919e0e5314369a888286eef1f51e7ae7c299725d1ad669b89186aa82",
-      "size": 58952796,
+      "checksum": "17278d93f4cd9bf7b6243f2d69ae60f7e14bd41672c461857fcb959cce787866",
+      "size": 59287050,
       "bundle": {
-        "checksum": "5c9b3639bce10bec691a944c105890d1f96c5e69ddadc2d7759bd5ab64ec83b8",
-        "size": 58953965
+        "checksum": "1e115e67b3b9230b0f5877e038b40ed0df9cf6a2cd390e4a3da207d028c9c998",
+        "size": 59285846
       }
     },
     "linux-arm64": {
       "binary": "claude.zst",
-      "checksum": "4ddd9f096f81f25deecf63cc4c74bfa1c54ed31510b808f44fc5d8182d326bec",
-      "size": 63194178
+      "checksum": "50cefaeb32af65d8da9036f152110357101c24e8705ac0fb311daf37b6b0a574",
+      "size": 63439231
     },
     "linux-x64": {
       "binary": "claude.zst",
-      "checksum": "d8a43ae3cea71283d1d228937735c47f5b533829ce7a725ee081a5a72510ab41",
-      "size": 64369245
+      "checksum": "5f3ccf27ecbf3eca26611380ec5c4bd922fb20fd12a1749744922ff595661aad",
+      "size": 64854874
     },
     "linux-arm64-musl": {
       "binary": "claude.zst",
-      "checksum": "7a7a529aaf23aaf6e2a05430342a43db2c7ab4b881731e1b91adbe95916673db",
-      "size": 61825337
+      "checksum": "de4dcb573dfc16096bc19cdae9eb64e4f66306d018ac69feb3aa4b1bdf9eab2a",
+      "size": 62226768
     },
     "linux-x64-musl": {
       "binary": "claude.zst",
-      "checksum": "ec32162ba30a8dff3f90f147a2c73db5cc46c5b47daf30337433928d26549738",
-      "size": 63188804
+      "checksum": "acc2132f74191d17baa52ebbedae63bab7dd9f0b841444a24f3437f771b4edee",
+      "size": 63735968
     },
     "win32-x64": {
       "binary": "claude.exe.zst",
-      "checksum": "4a68cb0cbe8e4e726c49d48df1465f38d026492367151be64d48dc6d7ea3bd6f",
-      "size": 64602024
+      "checksum": "a3b7fa65d3b4cc5624314c0a3af20aa1a4876bf2bdc0e3d68f2b75516ad4887a",
+      "size": 65087938
     },
     "win32-arm64": {
       "binary": "claude.exe.zst",
-      "checksum": "abd504266dbf91d10ba61da699ea22ca00b99d7e91e62f9e520d99eb90c9eedf",
-      "size": 62745683
+      "checksum": "28c57b3dbb7d6f01b152f0947a5cbe382f77cdac026ef3a22cb8430fc06ac1d4",
+      "size": 63251656
     }
   },
   "sdkCompat": {
     "testedWrapperVersions": [
-      "0.3.181",
       "0.3.182",
       "0.3.183",
       "0.3.185",
@@ -83,7 +82,8 @@
       "0.3.215",
       "0.3.217",
       "0.3.218",
-      "0.3.220"
+      "0.3.220",
+      "0.3.221"
     ],
     "harnessSchema": 1
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anthropic-ai/claude-agent-sdk",
-  "version": "0.3.221",
+  "version": "0.3.223",
   "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.221",
-    "@anthropic-ai/claude-agent-sdk-linux-arm64": "0.3.221",
-    "@anthropic-ai/claude-agent-sdk-linux-x64-musl": "0.3.221",
-    "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": "0.3.221",
-    "@anthropic-ai/claude-agent-sdk-darwin-x64": "0.3.221",
-    "@anthropic-ai/claude-agent-sdk-darwin-arm64": "0.3.221",
-    "@anthropic-ai/claude-agent-sdk-win32-x64": "0.3.221",
-    "@anthropic-ai/claude-agent-sdk-win32-arm64": "0.3.221"
+    "@anthropic-ai/claude-agent-sdk-linux-x64": "0.3.223",
+    "@anthropic-ai/claude-agent-sdk-linux-arm64": "0.3.223",
+    "@anthropic-ai/claude-agent-sdk-linux-x64-musl": "0.3.223",
+    "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": "0.3.223",
+    "@anthropic-ai/claude-agent-sdk-darwin-x64": "0.3.223",
+    "@anthropic-ai/claude-agent-sdk-darwin-arm64": "0.3.223",
+    "@anthropic-ai/claude-agent-sdk-win32-x64": "0.3.223",
+    "@anthropic-ai/claude-agent-sdk-win32-arm64": "0.3.223"
   },
   "files": [
     "sdk.mjs",
@@ -80,5 +80,5 @@
     "manifest.json",
     "manifest.zst.json"
   ],
-  "claudeCodeVersion": "2.1.221"
+  "claudeCodeVersion": "2.1.223"
 }

package/sdk-tools.d.ts

@@ -2432,13 +2432,37 @@ export interface SendFeedbackInput {
    */
   title: string;
   /**
-   * Factual, reproducible report: what was attempted, what happened, exact error text if short, repro steps. No speculation, no secrets.
+   * Labeled bullets, in order: **What happened:** (observed vs. expected, exact error text if short); **What the user said:** (quoted, or "User didn't comment; observed by the model."); **Repro:** (minimal steps); **Evidence:** (request IDs, timestamps, paths, versions — omit if none); optionally a final **Cause:** only if verified in-session. One to three lines per bullet. No narrative paragraphs, no speculation, no secrets.
    */
   details: string;
   /**
    * Optional short tag naming the part of Claude Code this is about (e.g. "hooks config", "/help", "file editing"). Leave blank if unclear.
    */
   area?: string;
+  /**
+   * When the report is about MODEL BEHAVIOR (not a product bug), the closest failure mode — or `other` when it is a model-behavior issue that fits no listed value. Omit only when the report is a product/tool bug with no model-behavior component.
+   */
+  failure_mode?:
+    | "instruction_following"
+    | "destructive_actions"
+    | "code_quality"
+    | "repetition_and_looping"
+    | "model_regression"
+    | "overconfidence_and_hallucination"
+    | "context_and_memory"
+    | "overeager"
+    | "over_correction"
+    | "stopping_short"
+    | "dispute_or_decline"
+    | "subagent_overspawn"
+    | "tone_or_preachiness"
+    | "excessive_questions"
+    | "unwanted_scope"
+    | "other";
+  /**
+   * What kind of task the session was doing when the issue occurred — or `other` when it is a clear task that fits no listed value. Omit only if genuinely unclear.
+   */
+  task_category?: "code_edit" | "debug" | "explain" | "plan" | "shell" | "search" | "review" | "other";
 }
 export interface ClaudeDesignInput {
   /**

package/sdk.d.ts

@@ -1810,9 +1810,62 @@ export declare type Options = {
     /**
      * When resuming, only resume messages up to and including the message with this UUID.
      * Use with `resume`. This allows you to resume from a specific point in the conversation.
-     * The message ID should be from `SDKAssistantMessage.uuid`.
+     * Accepts any chain-entry UUID — typically `SDKAssistantMessage.uuid`, but
+     * end-turn tool sessions and transcript-only appends need a later entry's
+     * UUID (see `resumeDropsTurn` for the fork-point guidance).
      */
     resumeSessionAt?: string;
+    /**
+     * With `resumeSessionAt`: declares the prompt UUID of the turn this
+     * truncating resume intends to discard. The CLI validates at fork time
+     * that every entry past the `resumeSessionAt` point is attributable to
+     * that turn, and refuses the resume (an `error_during_execution` result
+     * whose message starts with `Resume rejected by --resume-drops-turn:`)
+     * when the discarded range contains anything else — e.g. a queued user
+     * message or task notification the session absorbed mid-turn that the
+     * caller's view of the conversation had not yet observed. Omit to keep
+     * the unvalidated truncation behavior.
+     *
+     * Consumers MUST map a refusal (match on the message prefix above) to
+     * their rewind-recovery path — clear the pending fork target and resume
+     * plainly, keeping the evidence — not retry: the refusal is
+     * deterministic, so re-sending the same fork request fails forever.
+     *
+     * End-turn tool sessions (`outputFormat: {type: 'json_schema'}`, or any
+     * MCP tool using `_meta['claude/endTurn']`): a completed turn there ends
+     * on a successful tool_result carrier — with no trailing assistant
+     * message — followed by a `structured_output` attachment holding the
+     * turn's actual output (the carrier's data is a placeholder). Fork at
+     * the LAST entry of the turn being kept — the `structured_output`
+     * attachment when present, else the carrier — not the last assistant
+     * UUID; `resumeSessionAt` accepts any chain UUID. Forking earlier
+     * leaves the carrier or attachment in the discarded range, and the
+     * validator deliberately refuses: both are the kept turn's own payload,
+     * and dropping either would discard kept-turn output (the attachment is
+     * its sole persisted copy) or leave its tool_use dangling.
+     *
+     * The same fork-past-your-appends rule applies to plain (non-synthetic)
+     * `shouldQuery: false` transcript appends (e.g. CCD bash mode): they
+     * persist as bare user entries, so a fork point that leaves one in the
+     * discarded range refuses. Fork at or after your own last append.
+     *
+     * PRINT/HEADLESS LANE ONLY: the pair is consumed exclusively by the
+     * headless boot path (print-mode CLI, Agent SDK, ProcessTransport). An
+     * interactive `claude --resume` boot and background-job worker boots
+     * ignore both options — the resume loads the full chain with no
+     * truncation, no guard, and no error — so callers must not pass the
+     * pair outside print mode and expect an armed guard (rejecting it on
+     * those lanes is tracked follow-up work).
+     *
+     * General rule subsuming all of the above: fork at the KEPT turn's last
+     * chain entry, whatever it is — `resumeSessionAt` accepts any chain
+     * UUID. This also covers interrupted turns that completed one or more
+     * tools before Esc: the completed (non-error) tool_result in the tail
+     * is kept-turn payload and deliberately refuses at an assistant-UUID
+     * fork point, while the marker / cancel-batch entries after it are
+     * skippable — so fork at the last entry and the refusal never fires.
+     */
+    resumeDropsTurn?: string;
     /**
      * Sandbox settings for command execution isolation.
      *
@@ -4080,6 +4133,8 @@ export declare type SDKMessageOrigin = {
     subkind?: 'scheduled-trigger';
 } | {
     kind: 'coordinator';
+} | {
+    kind: 'unclassified';
 } | {
     kind: 'observer';
     from: string;
@@ -4107,13 +4162,17 @@ export declare type SDKMirrorErrorMessage = {
 };
 
 /**
- * Emitted when the primary model ends the stream with stop_reason "refusal" and the turn is retried once on a fallback model with the swap made persistent for the session (direction: "retry"). "revert" and "sticky" are retained in the enum for SDK-consumer compat and are no longer emitted.
+ * Emitted when the primary model ends the stream with stop_reason "refusal" and the turn is retried once on a fallback model (direction: "retry"). When `scope` is "session" (or absent — older CLIs), the swap is made persistent for the session; when `scope` is "local", only that subagent/side-question response came from the fallback model and the session model is unchanged. "revert" and "sticky" are retained in the enum for SDK-consumer compat and are no longer emitted.
  */
 export declare type SDKModelRefusalFallbackMessage = {
     type: 'system';
     subtype: 'model_refusal_fallback';
     trigger: 'refusal';
     direction: 'retry' | 'revert' | 'sticky';
+    /**
+     * 'session': the main thread fell back and the session model is swapped. 'local': a subagent / side-question (/btw) / background fork fell back — only that response came from the fallback model and the session model is unchanged. Absent from older CLIs (treat as 'session').
+     */
+    scope?: 'session' | 'local';
     original_model: string;
     fallback_model: string;
     request_id: string | null;
@@ -4185,7 +4244,7 @@ export declare type SDKPermissionDenial = {
 };
 
 /**
- * Emitted when a tool call is auto-denied without an interactive permission prompt (e.g. auto-mode classifier, dontAsk mode, headless-agent auto-deny, or a deny rule). The 'ask' path surfaces via a can_use_tool control_request; this event covers the 'deny' short-circuit in canUseTool so SDK hosts can render the denial instead of only seeing an is_error tool_result. PreToolUse hook denies bypass canUseTool and are not covered here.
+ * Emitted when a tool call is auto-denied without an interactive permission prompt (e.g. auto-mode classifier, dontAsk mode, headless-agent auto-deny, or a deny rule). With a permission prompt surface (stdio/SDK canUseTool), the 'ask' path surfaces via a can_use_tool control_request and this event covers the 'deny' short-circuit. Without one (bare -p / SDK query() with no canUseTool), 'ask' decisions are terminal, so this event also covers those implicit denials. Best-effort advisory: in rare races a denial can book without a frame or a frame can lack a booking twin — result.permission_denials is the authoritative record. Denials that resolve before canUseTool runs — PreToolUse hook denies, and deny-rule overrides of hook allow/ask decisions — are not covered here, and neither is the MCP --permission-prompt-tool surface (the prompt tool is the host there).
  */
 export declare type SDKPermissionDeniedMessage = {
     type: 'system';
@@ -4296,8 +4355,17 @@ export declare type SDKResultError = {
     is_error: boolean;
     num_turns: number;
     stop_reason: string | null;
+    /**
+     * Cumulative estimated cost in USD for this query() call, covering the same query-pipeline calls as modelUsage and sharing its lifecycle: cumulative across turns in streaming-input sessions — each result carries the running total so far, so read the latest result rather than summing across results. Crash/startup-error results may carry zeroed values, resumed sessions start fresh, and a mid-session /clear resets the running total. An estimate, not a billing statement.
+     */
     total_cost_usd: number;
+    /**
+     * MAIN AGENT LOOP ONLY — excludes Task subagent, sidechain, and auxiliary model calls, and is per-turn in streaming-input sessions. Prefer modelUsage for token/cost accounting.
+     */
     usage: NonNullableUsage;
+    /**
+     * Per-model totals for every model call made through the query pipeline during this query() call — main loop, Task subagents, sidechains, and internal calls such as compaction and Workflow agents. Cumulative across turns in streaming-input sessions: each result carries the running total so far, so read the latest result rather than summing across results. Internal helper calls outside the query pipeline (e.g. the permission classifier, token-count probes) are excluded; crash/startup-error results may carry zeroed usage, resumed sessions start fresh, and a mid-session /clear resets the running total. The correct field for token/cost accounting; treat it as an estimate, not a billing statement.
+     */
     modelUsage: Record<string, ModelUsage>;
     permission_denials: SDKPermissionDenial[];
     errors: string[];
@@ -4329,8 +4397,17 @@ export declare type SDKResultSuccess = {
     num_turns: number;
     result: string;
     stop_reason: string | null;
+    /**
+     * Cumulative estimated cost in USD for this query() call, covering the same query-pipeline calls as modelUsage and sharing its lifecycle: cumulative across turns in streaming-input sessions — each result carries the running total so far, so read the latest result rather than summing across results. Crash/startup-error results may carry zeroed values, resumed sessions start fresh, and a mid-session /clear resets the running total. An estimate, not a billing statement.
+     */
     total_cost_usd: number;
+    /**
+     * MAIN AGENT LOOP ONLY — excludes Task subagent, sidechain, and auxiliary model calls, and is per-turn in streaming-input sessions. Prefer modelUsage for token/cost accounting.
+     */
     usage: NonNullableUsage;
+    /**
+     * Per-model totals for every model call made through the query pipeline during this query() call — main loop, Task subagents, sidechains, and internal calls such as compaction and Workflow agents. Cumulative across turns in streaming-input sessions: each result carries the running total so far, so read the latest result rather than summing across results. Internal helper calls outside the query pipeline (e.g. the permission classifier, token-count probes) are excluded; crash/startup-error results may carry zeroed usage, resumed sessions start fresh, and a mid-session /clear resets the running total. The correct field for token/cost accounting; treat it as an estimate, not a billing statement.
+     */
     modelUsage: Record<string, ModelUsage>;
     permission_denials: SDKPermissionDenial[];
     structured_output?: unknown;
@@ -5548,7 +5625,7 @@ export declare interface Settings {
             } | {
                 source: 'github';
                 /**
-                 * GitHub repository in owner/repo format
+                 * GitHub repository in owner/repo format. ONLY in the managed-settings policy lists (strictKnownMarketplaces / blockedMarketplaces) the owner-wildcard form "owner/*" matches every repository under exactly that owner. Everywhere else (marketplace add, extraKnownMarketplaces, known_marketplaces.json) the value must name a single repository — a wildcard is taken literally and fails to clone.
                  */
                 repo: string;
                 /**
@@ -5731,7 +5808,7 @@ export declare interface Settings {
         };
     };
     /**
-     * Enterprise strict list of allowed marketplace sources. When set in managed settings, ONLY these exact sources can be added as marketplaces. The check happens BEFORE downloading, so blocked sources never touch the filesystem. Note: this is a policy gate only — it does NOT register marketplaces. To pre-register allowed marketplaces for users, also set extraKnownMarketplaces.
+     * Enterprise strict list of allowed marketplace sources. When set in managed settings, ONLY these sources can be added as marketplaces. Entries match exactly, except that a github entry may use the owner-wildcard form {"source":"github","repo":"owner/*"} to allow every repository under that owner. The check happens BEFORE downloading, so blocked sources never touch the filesystem. Note: this is a policy gate only — it does NOT register marketplaces. To pre-register allowed marketplaces for users, also set extraKnownMarketplaces.
      */
     strictKnownMarketplaces?: ({
         source: 'url';
@@ -5748,7 +5825,7 @@ export declare interface Settings {
     } | {
         source: 'github';
         /**
-         * GitHub repository in owner/repo format
+         * GitHub repository in owner/repo format. ONLY in the managed-settings policy lists (strictKnownMarketplaces / blockedMarketplaces) the owner-wildcard form "owner/*" matches every repository under exactly that owner. Everywhere else (marketplace add, extraKnownMarketplaces, known_marketplaces.json) the value must name a single repository — a wildcard is taken literally and fails to clone.
          */
         repo: string;
         /**
@@ -5921,7 +5998,7 @@ export declare interface Settings {
         };
     })[];
     /**
-     * Enterprise blocklist of marketplace sources. When set in managed settings, these exact sources are blocked from being added as marketplaces. The check happens BEFORE downloading, so blocked sources never touch the filesystem.
+     * Enterprise blocklist of marketplace sources. When set in managed settings, these sources are blocked from being added as marketplaces. Entries match exactly, except that a github entry may use the owner-wildcard form {"source":"github","repo":"owner/*"} to block every repository under that owner. The check happens BEFORE downloading, so blocked sources never touch the filesystem.
      */
     blockedMarketplaces?: ({
         source: 'url';
@@ -5938,7 +6015,7 @@ export declare interface Settings {
     } | {
         source: 'github';
         /**
-         * GitHub repository in owner/repo format
+         * GitHub repository in owner/repo format. ONLY in the managed-settings policy lists (strictKnownMarketplaces / blockedMarketplaces) the owner-wildcard form "owner/*" matches every repository under exactly that owner. Everywhere else (marketplace add, extraKnownMarketplaces, known_marketplaces.json) the value must name a single repository — a wildcard is taken literally and fails to clone.
          */
         repo: string;
         /**