@anthropic-ai/claude-agent-sdk 0.2.87 → 0.2.89

package/manifest.json

@@ -1,46 +1,46 @@
 {
-  "version": "2.1.87",
-  "buildDate": "2026-03-29T01:45:06Z",
+  "version": "2.1.89",
+  "buildDate": "2026-03-31T23:01:10Z",
   "platforms": {
     "darwin-arm64": {
       "binary": "claude",
-      "checksum": "80b51562db1a51bfb654aec1fea6a04106daa0bc1525d88c9c74741ff5d9469a",
-      "size": 196638704
+      "checksum": "f903a5e53f845b1ac5566296b713193827665f28da16300fdca7539cb0669a7f",
+      "size": 196886384
     },
     "darwin-x64": {
       "binary": "claude",
-      "checksum": "c1a4cde29e74e4c3952ead69f90a37a2388aa097d7c567a81ca3669a309e9226",
-      "size": 198132816
+      "checksum": "1322c5eecec8047e9cd7114f7d547ef6a9596563d6bbc7e594167d0f8bc8b406",
+      "size": 198397008
     },
     "linux-arm64": {
       "binary": "claude",
-      "checksum": "193c5e9c091eadde302fa23af46c8d646b7263f74fa06ed32746e504bd09df18",
-      "size": 228461120
+      "checksum": "428301f56cf0139e6fbfa55e13be3f0f032ac1eb5ddb8849fbc703ee220c1cca",
+      "size": 228657728
     },
     "linux-x64": {
       "binary": "claude",
-      "checksum": "b1a5b89469862adee0e4dc28cab5a8314bc4d0117e19ab26a7b7ff7ce9b59bd5",
-      "size": 228280960
+      "checksum": "903cb3c96b314d86856632c8702f5cdf971b804d0b19ef87446573bcd1d7df1c",
+      "size": 228473472
     },
     "linux-arm64-musl": {
       "binary": "claude",
-      "checksum": "38e56d4a62778f429b1caa875a4a6e53db8eda256091f58afb5cf2043e492131",
-      "size": 221579712
+      "checksum": "7cb5fd60f3d2366672857077f3bd0f93ab83dffebd8f93c70344afa58bdb91ec",
+      "size": 221776320
     },
     "linux-x64-musl": {
       "binary": "claude",
-      "checksum": "aba2c3a8927c53f981a4ad2b18915b2a1a1511b3b4e3b5e8797d23dbb0bf5eea",
-      "size": 222906816
+      "checksum": "60941916f0a5656a5952a0f2f54228f574f8756ea503119f858724ad43c9b28d",
+      "size": 223099328
     },
     "win32-x64": {
       "binary": "claude.exe",
-      "checksum": "c722ff8836e7a90b5c62fd5cb6549887dc314e7e8d9551c01df1718d9198ecdf",
-      "size": 238222496
+      "checksum": "2e312000b538f11d13f1dfc52d4131996895b9a07bd8897d8f9153635d4ea092",
+      "size": 238557856
     },
     "win32-arm64": {
       "binary": "claude.exe",
-      "checksum": "5c3e5f706685963c83cdc5dd2ec86a89e5a897bd6ec82298311abb43280ffa30",
-      "size": 234785440
+      "checksum": "5f1d597c542aac3a11f557e12c92d0c49220ab77e741014b0599a572d81ca679",
+      "size": 235014304
     }
   }
 }

package/manifest.zst.json

@@ -1,54 +1,54 @@
 {
-  "version": "2.1.87",
-  "buildDate": "2026-03-29T01:45:07Z",
+  "version": "2.1.89",
+  "buildDate": "2026-03-31T23:01:11Z",
   "platforms": {
     "darwin-arm64": {
       "binary": "claude.zst",
-      "checksum": "29a4dfb19fea56dc0a2ae9420d5e3fbd8a30f1b5f8a10f67376ccf50822d2f7f",
-      "size": 40737146,
+      "checksum": "ee6870995b94768b165410dc18e5523d840b149657ed52dba45e6dfef075da48",
+      "size": 40741984,
       "bundle": {
-        "checksum": "144409985ca6563fade30464dab61c1580f951092d2eb9ebecc914eb519c59c0",
-        "size": 40745941
+        "checksum": "0eaf878b84a8f2f2d86bb5c8dd1f25a20ed37fd34c8bc7f7e65e057f2e38389c",
+        "size": 40746913
       }
     },
     "darwin-x64": {
       "binary": "claude.zst",
-      "checksum": "51208c0db62ace5531841609b64ec6898dabd7c5517a5ae6710a1c1b38633aad",
-      "size": 42383431,
+      "checksum": "d698b7101ad599a6d98c4bad7ced35e24e789693a70abdd1dc42064b5a9a7701",
+      "size": 42386954,
       "bundle": {
-        "checksum": "d5209644984ac2edd1d6fda2acbcfbbf6a9add76303f4111508bbab52bca4b01",
-        "size": 42371152
+        "checksum": "cb030dd63605eac527e83bb436578ad7472c1da01bb59abfa6596bf5a054eea2",
+        "size": 42383339
       }
     },
     "linux-arm64": {
       "binary": "claude.zst",
-      "checksum": "6c04ee19b7b039556e2395766d6d004e59fe6a5b2288ce94501945575dcfee42",
-      "size": 50454874
+      "checksum": "09ba9e09dee846d924f8a0ec28f7fabd127260d1a5b8e9d3e896fdbeb17a4ff5",
+      "size": 50422513
     },
     "linux-x64": {
       "binary": "claude.zst",
-      "checksum": "4bd9662fea09e5450c6af0ad6289b1f1ac741ca225247dce8ad56c70f3da11f8",
-      "size": 50942389
+      "checksum": "5a909d13f308be6c7bb341ca7a0b0de6ce048fc336f4bbe8ab6fdddc45f0d5ec",
+      "size": 50918863
     },
     "linux-arm64-musl": {
       "binary": "claude.zst",
-      "checksum": "3c706da3d080c13edee582890bca9dc906aac30fce2a21b43e0cdca252b3bab0",
-      "size": 49018272
+      "checksum": "7399c3c9d4d79651de9a3db2df6064bede6f5027ef2fdde6dfbf32b4eb0c35d7",
+      "size": 49008572
     },
     "linux-x64-musl": {
       "binary": "claude.zst",
-      "checksum": "c47d80ba01ab2ddb9c24b1cfb4b4f15faf7277a0a5a28bb9242382550c533fdc",
-      "size": 49669703
+      "checksum": "5c68a381a31ed52494b2bb77d8969fa8a97aaedd8fb3636e32cf81fa2a1e9b3c",
+      "size": 49687404
     },
     "win32-x64": {
       "binary": "claude.exe.zst",
-      "checksum": "662ff375f3e938a06450c3f3e23834bc69ddbbf4ca601334d924760996bf5954",
-      "size": 52563492
+      "checksum": "41572f32d4b3cd8b24fa7a367d56bd7fdbcb21ca07c515d25ff44228e7c8cb6a",
+      "size": 52644178
     },
     "win32-arm64": {
       "binary": "claude.exe.zst",
-      "checksum": "aeeb7a301eb188c392d194e30d451fa7ca6b6b81dd23ff1b99c5c73471c165e7",
-      "size": 50757591
+      "checksum": "536c03ee45cb9c4e29d42fb81c8d64d499972664348d924c54663b0f8558f8de",
+      "size": 50813305
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anthropic-ai/claude-agent-sdk",
-  "version": "0.2.87",
+  "version": "0.2.89",
   "main": "sdk.mjs",
   "types": "sdk.d.ts",
   "exports": {
@@ -65,5 +65,5 @@
     "@img/sharp-win32-arm64": "^0.34.2",
     "@img/sharp-win32-x64": "^0.34.2"
   },
-  "claudeCodeVersion": "2.1.87"
+  "claudeCodeVersion": "2.1.89"
 }

package/sdk-tools.d.ts

@@ -2214,6 +2214,10 @@ export interface BashOutput {
    * Total size of the output in bytes (set when output is too large for inline)
    */
   persistedOutputSize?: number;
+  /**
+   * Model-facing note listing readFileState entries whose mtime bumped during this command (set when WRITE_COMMAND_MARKERS matches)
+   */
+  staleReadFileStateHint?: string;
 }
 export interface ExitPlanModeOutput {
   /**

package/sdk.d.ts

@@ -73,6 +73,22 @@ export declare type AgentDefinition = {
      * Maximum number of agentic turns (API round-trips) before stopping
      */
     maxTurns?: number;
+    /**
+     * Run this agent as a background task (non-blocking, fire-and-forget) when invoked
+     */
+    background?: boolean;
+    /**
+     * Scope for auto-loading agent memory files. 'user' - ~/.claude/agent-memory/<agentType>/, 'project' - .claude/agent-memory/<agentType>/, 'local' - .claude/agent-memory-local/<agentType>/
+     */
+    memory?: 'user' | 'project' | 'local';
+    /**
+     * Reasoning effort level for this agent. Either a named level or an integer
+     */
+    effort?: ('low' | 'medium' | 'high' | 'max') | number;
+    /**
+     * Permission mode controlling how tool executions are handled
+     */
+    permissionMode?: PermissionMode;
 };
 
 /**
@@ -227,6 +243,7 @@ declare namespace coreTypes {
         HookEvent,
         HookInput,
         HookJSONOutput,
+        HookPermissionDecision,
         InstructionsLoadedHookInput,
         JsonSchemaOutputFormat,
         McpClaudeAIProxyServerConfig,
@@ -246,6 +263,8 @@ declare namespace coreTypes {
         OutputFormatType,
         PermissionBehavior,
         PermissionDecisionClassification,
+        PermissionDeniedHookInput,
+        PermissionDeniedHookSpecificOutput,
         PermissionMode,
         PermissionRequestHookInput,
         PermissionRequestHookSpecificOutput,
@@ -270,6 +289,7 @@ declare namespace coreTypes {
         SDKAssistantMessage,
         SDKAuthStatusMessage,
         SDKCompactBoundaryMessage,
+        SDKDeferredToolUse,
         SDKElicitationCompleteMessage,
         SDKFilesPersistedEvent,
         SDKHookProgressMessage,
@@ -509,11 +529,12 @@ export declare type GetSessionInfoOptions = {
  * Reads a session's conversation messages from its JSONL transcript file.
  *
  * Parses the transcript, builds the conversation chain via parentUuid links,
- * and returns user/assistant messages in chronological order.
+ * and returns user/assistant messages in chronological order. Set
+ * `includeSystemMessages: true` in options to also include system messages.
  *
  * @param sessionId - UUID of the session to read
- * @param options - Optional dir, limit, and offset
- * @returns Array of user/assistant messages, or empty array if session not found
+ * @param options - Optional dir, limit, offset, and includeSystemMessages
+ * @returns Array of messages, or empty array if session not found
  */
 export declare function getSessionMessages(_sessionId: string, _options?: GetSessionMessagesOptions): Promise<SessionMessage[]>;
 
@@ -527,9 +548,40 @@ export declare type GetSessionMessagesOptions = {
     limit?: number;
     /** Number of messages to skip from the start. */
     offset?: number;
+    /**
+     * When true, include system messages (e.g., compact boundaries, informational
+     * notices) in the returned list alongside user/assistant messages.
+     * Defaults to false for backwards compatibility.
+     */
+    includeSystemMessages?: boolean;
 };
 
-export declare const HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "Notification", "UserPromptSubmit", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PermissionRequest", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "WorktreeCreate", "WorktreeRemove", "InstructionsLoaded", "CwdChanged", "FileChanged"];
+/**
+ * Reads a subagent's conversation messages from its JSONL transcript file.
+ *
+ * Parses the subagent transcript, builds the conversation chain via parentUuid
+ * links, and returns user/assistant messages in chronological order.
+ *
+ * @param sessionId - UUID of the parent session
+ * @param agentId - ID of the subagent
+ * @param options - Optional dir, limit, and offset
+ * @returns Array of user/assistant messages, or empty array if not found
+ */
+export declare function getSubagentMessages(_sessionId: string, _agentId: string, _options?: GetSubagentMessagesOptions): Promise<SessionMessage[]>;
+
+/**
+ * Options for retrieving subagent messages.
+ */
+export declare type GetSubagentMessagesOptions = {
+    /** Project directory to find the session in. If omitted, searches all projects. */
+    dir?: string;
+    /** Maximum number of messages to return. */
+    limit?: number;
+    /** Number of messages to skip from the start. */
+    offset?: number;
+};
+
+export declare const HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "Notification", "UserPromptSubmit", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PermissionRequest", "PermissionDenied", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "WorktreeCreate", "WorktreeRemove", "InstructionsLoaded", "CwdChanged", "FileChanged"];
 
 /**
  * Hook callback function for responding to events during execution.
@@ -548,12 +600,14 @@ export declare interface HookCallbackMatcher {
     timeout?: number;
 }
 
-export declare type HookEvent = 'PreToolUse' | 'PostToolUse' | 'PostToolUseFailure' | 'Notification' | 'UserPromptSubmit' | 'SessionStart' | 'SessionEnd' | 'Stop' | 'StopFailure' | 'SubagentStart' | 'SubagentStop' | 'PreCompact' | 'PostCompact' | 'PermissionRequest' | 'Setup' | 'TeammateIdle' | 'TaskCreated' | 'TaskCompleted' | 'Elicitation' | 'ElicitationResult' | 'ConfigChange' | 'WorktreeCreate' | 'WorktreeRemove' | 'InstructionsLoaded' | 'CwdChanged' | 'FileChanged';
+export declare type HookEvent = 'PreToolUse' | 'PostToolUse' | 'PostToolUseFailure' | 'Notification' | 'UserPromptSubmit' | 'SessionStart' | 'SessionEnd' | 'Stop' | 'StopFailure' | 'SubagentStart' | 'SubagentStop' | 'PreCompact' | 'PostCompact' | 'PermissionRequest' | 'PermissionDenied' | 'Setup' | 'TeammateIdle' | 'TaskCreated' | 'TaskCompleted' | 'Elicitation' | 'ElicitationResult' | 'ConfigChange' | 'WorktreeCreate' | 'WorktreeRemove' | 'InstructionsLoaded' | 'CwdChanged' | 'FileChanged';
 
-export declare type HookInput = PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | NotificationHookInput | UserPromptSubmitHookInput | SessionStartHookInput | SessionEndHookInput | StopHookInput | StopFailureHookInput | SubagentStartHookInput | SubagentStopHookInput | PreCompactHookInput | PostCompactHookInput | PermissionRequestHookInput | SetupHookInput | TeammateIdleHookInput | TaskCreatedHookInput | TaskCompletedHookInput | ElicitationHookInput | ElicitationResultHookInput | ConfigChangeHookInput | InstructionsLoadedHookInput | WorktreeCreateHookInput | WorktreeRemoveHookInput | CwdChangedHookInput | FileChangedHookInput;
+export declare type HookInput = PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | PermissionDeniedHookInput | NotificationHookInput | UserPromptSubmitHookInput | SessionStartHookInput | SessionEndHookInput | StopHookInput | StopFailureHookInput | SubagentStartHookInput | SubagentStopHookInput | PreCompactHookInput | PostCompactHookInput | PermissionRequestHookInput | SetupHookInput | TeammateIdleHookInput | TaskCreatedHookInput | TaskCompletedHookInput | ElicitationHookInput | ElicitationResultHookInput | ConfigChangeHookInput | InstructionsLoadedHookInput | WorktreeCreateHookInput | WorktreeRemoveHookInput | CwdChangedHookInput | FileChangedHookInput;
 
 export declare type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput;
 
+export declare type HookPermissionDecision = 'allow' | 'deny' | 'ask' | 'defer';
+
 export declare type InferShape<T extends AnyZodRawShape> = {
     [K in keyof T]: T[K] extends {
         _output: infer O;
@@ -620,6 +674,26 @@ export declare type ListSessionsOptions = {
     includeWorktrees?: boolean;
 };
 
+/**
+ * Lists subagent IDs for a given session by scanning the subagents directory.
+ *
+ * Subagent transcripts are stored at
+ * `~/.claude/projects/<dir>/<sessionId>/subagents/agent-<agentId>.jsonl`.
+ *
+ * @param sessionId - UUID of the session
+ * @param options - Optional dir to narrow the project search
+ * @returns Array of subagent ID strings, or empty array if none found
+ */
+export declare function listSubagents(_sessionId: string, _options?: ListSubagentsOptions): Promise<string[]>;
+
+/**
+ * Options for listing subagents.
+ */
+export declare type ListSubagentsOptions = {
+    /** Project directory to find the session in. If omitted, searches all projects. */
+    dir?: string;
+};
+
 export declare type McpClaudeAIProxyServerConfig = {
     type: 'claudeai-proxy';
     url: string;
@@ -999,6 +1073,16 @@ export declare type Options = {
      * @default true
      */
     persistSession?: boolean;
+    /**
+     * Include hook lifecycle events in the output stream.
+     * When true, `hook_started`, `hook_progress`, and `hook_response` system
+     * messages will be emitted for all hook event types (PreToolUse, PostToolUse,
+     * Stop, etc.). SessionStart and Setup hook events are always emitted
+     * regardless of this setting.
+     *
+     * @default false
+     */
+    includeHookEvents?: boolean;
     /**
      * Include partial/streaming message events in the output.
      * When true, `SDKPartialAssistantMessage` events will be emitted during streaming.
@@ -1313,6 +1397,19 @@ export declare type PermissionBehavior = 'allow' | 'deny' | 'ask';
  */
 export declare type PermissionDecisionClassification = 'user_temporary' | 'user_permanent' | 'user_reject';
 
+export declare type PermissionDeniedHookInput = BaseHookInput & {
+    hook_event_name: 'PermissionDenied';
+    tool_name: string;
+    tool_input: unknown;
+    tool_use_id: string;
+    reason: string;
+};
+
+export declare type PermissionDeniedHookSpecificOutput = {
+    hookEventName: 'PermissionDenied';
+    retry?: boolean;
+};
+
 /**
  * Permission mode for controlling how tool executions are handled. 'default' - Standard behavior, prompts for dangerous operations. 'acceptEdits' - Auto-accept file edit operations. 'bypassPermissions' - Bypass all permission checks (requires allowDangerouslySkipPermissions). 'plan' - Planning mode, no actual tool execution. 'dontAsk' - Don't prompt for permissions, deny if not pre-approved.
  */
@@ -1440,7 +1537,7 @@ export declare type PreToolUseHookInput = BaseHookInput & {
 
 export declare type PreToolUseHookSpecificOutput = {
     hookEventName: 'PreToolUse';
-    permissionDecision?: PermissionBehavior;
+    permissionDecision?: HookPermissionDecision;
     permissionDecisionReason?: string;
     updatedInput?: Record<string, unknown>;
     additionalContext?: string;
@@ -2159,6 +2256,12 @@ declare type SDKControlStopTaskRequest = {
     task_id: string;
 };
 
+export declare type SDKDeferredToolUse = {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+};
+
 /**
  * Emitted when an MCP server confirms that a URL-mode elicitation is complete.
  */
@@ -2378,6 +2481,7 @@ export declare type SDKResultSuccess = {
     modelUsage: Record<string, ModelUsage>;
     permission_denials: SDKPermissionDenial[];
     structured_output?: unknown;
+    deferred_tool_use?: SDKDeferredToolUse;
     fast_mode_state?: FastModeState;
     uuid: UUID;
     session_id: string;
@@ -2657,6 +2761,7 @@ export declare type SDKUserMessageReplay = {
     uuid: UUID;
     session_id: string;
     isReplay: true;
+    file_attachments?: unknown[];
 };
 
 export declare type SessionEndHookInput = BaseHookInput & {
@@ -2665,11 +2770,11 @@ export declare type SessionEndHookInput = BaseHookInput & {
 };
 
 /**
- * A user or assistant message from a session transcript.
+ * A message from a session transcript.
  * Returned by `getSessionMessages` for reading historical session data.
  */
 export declare type SessionMessage = {
-    type: 'user' | 'assistant';
+    type: 'user' | 'assistant' | 'system';
     uuid: string;
     session_id: string;
     message: unknown;
@@ -2743,7 +2848,7 @@ export declare interface Settings {
      */
     respectGitignore?: boolean;
     /**
-     * Number of days to retain chat transcripts (default: 30). Setting to 0 disables session persistence entirely: no transcripts are written and existing transcripts are deleted at startup.
+     * 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;
     /**
@@ -3669,9 +3774,9 @@ export declare interface Settings {
      */
     forceLoginMethod?: 'claudeai' | 'console';
     /**
-     * Organization UUID to use for OAuth login
+     * Organization UUID to require for OAuth login. Accepts a single UUID string or an array of UUIDs (any one is permitted). When set in managed settings, login fails if the authenticated account does not belong to a listed organization.
      */
-    forceLoginOrgUUID?: string;
+    forceLoginOrgUUID?: string | string[];
     /**
      * Path to a script that outputs OpenTelemetry headers
      */
@@ -3795,6 +3900,10 @@ export declare interface Settings {
      * Persisted effort level for supported models.
      */
     effortLevel?: 'low' | 'medium' | 'high';
+    /**
+     * Auto-compact window size
+     */
+    autoCompactWindow?: number;
     /**
      * Advisor model for the server-side advisor tool.
      */
@@ -4087,7 +4196,7 @@ export declare type SyncHookJSONOutput = {
     systemMessage?: string;
     reason?: string;
 
-    hookSpecificOutput?: PreToolUseHookSpecificOutput | UserPromptSubmitHookSpecificOutput | SessionStartHookSpecificOutput | SetupHookSpecificOutput | SubagentStartHookSpecificOutput | PostToolUseHookSpecificOutput | PostToolUseFailureHookSpecificOutput | NotificationHookSpecificOutput | PermissionRequestHookSpecificOutput | ElicitationHookSpecificOutput | ElicitationResultHookSpecificOutput | CwdChangedHookSpecificOutput | FileChangedHookSpecificOutput | WorktreeCreateHookSpecificOutput;
+    hookSpecificOutput?: PreToolUseHookSpecificOutput | UserPromptSubmitHookSpecificOutput | SessionStartHookSpecificOutput | SetupHookSpecificOutput | SubagentStartHookSpecificOutput | PostToolUseHookSpecificOutput | PostToolUseFailureHookSpecificOutput | PermissionDeniedHookSpecificOutput | NotificationHookSpecificOutput | PermissionRequestHookSpecificOutput | ElicitationHookSpecificOutput | ElicitationResultHookSpecificOutput | CwdChangedHookSpecificOutput | FileChangedHookSpecificOutput | WorktreeCreateHookSpecificOutput;
 };
 
 /**