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

package/manifest.json

@@ -1,46 +1,46 @@
 {
-  "version": "2.1.86",
-  "buildDate": "2026-03-27T20:34:42Z",
+  "version": "2.1.89",
+  "buildDate": "2026-03-31T23:01:10Z",
   "platforms": {
     "darwin-arm64": {
       "binary": "claude",
-      "checksum": "76fafee995269784b1bf80b514c3b354394288fb794bed01ef20168874e088ea",
-      "size": 196638704
+      "checksum": "f903a5e53f845b1ac5566296b713193827665f28da16300fdca7539cb0669a7f",
+      "size": 196886384
     },
     "darwin-x64": {
       "binary": "claude",
-      "checksum": "de96f6966648ecd93c345fab4b3be944e93ba4140f1cda7fe45ffed93133b67e",
-      "size": 198132816
+      "checksum": "1322c5eecec8047e9cd7114f7d547ef6a9596563d6bbc7e594167d0f8bc8b406",
+      "size": 198397008
     },
     "linux-arm64": {
       "binary": "claude",
-      "checksum": "c04aebe3de140679b4cce158812d6f011b7e9c483496ccb0472cf38cc1714afe",
-      "size": 228461120
+      "checksum": "428301f56cf0139e6fbfa55e13be3f0f032ac1eb5ddb8849fbc703ee220c1cca",
+      "size": 228657728
     },
     "linux-x64": {
       "binary": "claude",
-      "checksum": "adce02c5f94a85b6ca231c8aeef533707597cd387e8934776455b87d10a3051b",
-      "size": 228280960
+      "checksum": "903cb3c96b314d86856632c8702f5cdf971b804d0b19ef87446573bcd1d7df1c",
+      "size": 228473472
     },
     "linux-arm64-musl": {
       "binary": "claude",
-      "checksum": "ded1933ce0f2bb55156b397fa622ca2782caa48ed99ed117ee20481f638e0293",
-      "size": 221579712
+      "checksum": "7cb5fd60f3d2366672857077f3bd0f93ab83dffebd8f93c70344afa58bdb91ec",
+      "size": 221776320
     },
     "linux-x64-musl": {
       "binary": "claude",
-      "checksum": "fb86c40f52a39c71393db93b9fa5f5c048be67c5a087a03e35e1e304c127c8c5",
-      "size": 222906816
+      "checksum": "60941916f0a5656a5952a0f2f54228f574f8756ea503119f858724ad43c9b28d",
+      "size": 223099328
     },
     "win32-x64": {
       "binary": "claude.exe",
-      "checksum": "9b9281621d0d5aa4aba3e3e9c5a6efdfe37a897fb9ba33a87e4562ec9df6453f",
-      "size": 238222496
+      "checksum": "2e312000b538f11d13f1dfc52d4131996895b9a07bd8897d8f9153635d4ea092",
+      "size": 238557856
     },
     "win32-arm64": {
       "binary": "claude.exe",
-      "checksum": "4f6eaa82b5eefd79b1ed56d6d6ffa3229c508c974f51ae43b6c38f5e2fdafe5f",
-      "size": 234785440
+      "checksum": "5f1d597c542aac3a11f557e12c92d0c49220ab77e741014b0599a572d81ca679",
+      "size": 235014304
     }
   }
 }

package/manifest.zst.json

@@ -1,54 +1,54 @@
 {
-  "version": "2.1.86",
-  "buildDate": "2026-03-27T20:34:43Z",
+  "version": "2.1.89",
+  "buildDate": "2026-03-31T23:01:11Z",
   "platforms": {
     "darwin-arm64": {
       "binary": "claude.zst",
-      "checksum": "fe4d250299ff4789e4c3a1172c97720c62fefed52496b66652325815fec58949",
-      "size": 40735714,
+      "checksum": "ee6870995b94768b165410dc18e5523d840b149657ed52dba45e6dfef075da48",
+      "size": 40741984,
       "bundle": {
-        "checksum": "0315d453553df95189f14ddfb15d7d0d9df97121673cc685bb3b1bdcfe0214fb",
-        "size": 40733484
+        "checksum": "0eaf878b84a8f2f2d86bb5c8dd1f25a20ed37fd34c8bc7f7e65e057f2e38389c",
+        "size": 40746913
       }
     },
     "darwin-x64": {
       "binary": "claude.zst",
-      "checksum": "8b1ef96634369e58cd480276c030a55c39bd66cb33b703a5f35c818a922c4d69",
-      "size": 42395229,
+      "checksum": "d698b7101ad599a6d98c4bad7ced35e24e789693a70abdd1dc42064b5a9a7701",
+      "size": 42386954,
       "bundle": {
-        "checksum": "4fe4d244397a50ccb33f2a3600cc342f0f6ec1731983c748ec6ebe8b57342488",
-        "size": 42396667
+        "checksum": "cb030dd63605eac527e83bb436578ad7472c1da01bb59abfa6596bf5a054eea2",
+        "size": 42383339
       }
     },
     "linux-arm64": {
       "binary": "claude.zst",
-      "checksum": "480cf52b5380fb9013902fe893ec58553f848f34bd979788f20106ff0ee61b1b",
-      "size": 50420732
+      "checksum": "09ba9e09dee846d924f8a0ec28f7fabd127260d1a5b8e9d3e896fdbeb17a4ff5",
+      "size": 50422513
     },
     "linux-x64": {
       "binary": "claude.zst",
-      "checksum": "0866db2a7ef4ccaad987f834639770299a9a740ed82a5cc53eb2db304e881986",
-      "size": 50935311
+      "checksum": "5a909d13f308be6c7bb341ca7a0b0de6ce048fc336f4bbe8ab6fdddc45f0d5ec",
+      "size": 50918863
     },
     "linux-arm64-musl": {
       "binary": "claude.zst",
-      "checksum": "05e6b45654b57c6cd26e80157c8112f0d24abfee053c0aa926b297ec608fcd78",
-      "size": 49030009
+      "checksum": "7399c3c9d4d79651de9a3db2df6064bede6f5027ef2fdde6dfbf32b4eb0c35d7",
+      "size": 49008572
     },
     "linux-x64-musl": {
       "binary": "claude.zst",
-      "checksum": "5154b2d20634a180b6d7b4e74afcf87125663d6fe5ccfc0553a6a6dd6e7b17ab",
-      "size": 49670272
+      "checksum": "5c68a381a31ed52494b2bb77d8969fa8a97aaedd8fb3636e32cf81fa2a1e9b3c",
+      "size": 49687404
     },
     "win32-x64": {
       "binary": "claude.exe.zst",
-      "checksum": "a231ea48462175772d5af60bb13b70ef1f0748f63e426edf05f0b50d88c70e6c",
-      "size": 52576784
+      "checksum": "41572f32d4b3cd8b24fa7a367d56bd7fdbcb21ca07c515d25ff44228e7c8cb6a",
+      "size": 52644178
     },
     "win32-arm64": {
       "binary": "claude.exe.zst",
-      "checksum": "d566cde2014177d00862b66dc971121cf4569e11f7763ce28e5f34132308cb73",
-      "size": 50754734
+      "checksum": "536c03ee45cb9c4e29d42fb81c8d64d499972664348d924c54663b0f8558f8de",
+      "size": 50813305
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anthropic-ai/claude-agent-sdk",
-  "version": "0.2.86",
+  "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.86"
+  "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;
 };
 
 /**