claude_agent 0.7.11 → 0.7.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.claude/rules/testing.md +51 -10
- data/.claude/settings.json +1 -0
- data/ARCHITECTURE.md +237 -0
- data/CHANGELOG.md +52 -0
- data/CLAUDE.md +2 -0
- data/README.md +47 -1
- data/Rakefile +17 -0
- data/SPEC.md +314 -133
- data/lib/claude_agent/client/commands.rb +225 -0
- data/lib/claude_agent/client.rb +4 -204
- data/lib/claude_agent/content_blocks/generic_block.rb +39 -0
- data/lib/claude_agent/content_blocks/image_content_block.rb +54 -0
- data/lib/claude_agent/content_blocks/server_tool_result_block.rb +22 -0
- data/lib/claude_agent/content_blocks/server_tool_use_block.rb +48 -0
- data/lib/claude_agent/content_blocks/text_block.rb +19 -0
- data/lib/claude_agent/content_blocks/thinking_block.rb +19 -0
- data/lib/claude_agent/content_blocks/tool_result_block.rb +25 -0
- data/lib/claude_agent/content_blocks/tool_use_block.rb +134 -0
- data/lib/claude_agent/content_blocks.rb +8 -335
- data/lib/claude_agent/control_protocol/commands.rb +304 -0
- data/lib/claude_agent/control_protocol/lifecycle.rb +113 -0
- data/lib/claude_agent/control_protocol/messaging.rb +166 -0
- data/lib/claude_agent/control_protocol/primitives.rb +168 -0
- data/lib/claude_agent/control_protocol/request_handling.rb +231 -0
- data/lib/claude_agent/control_protocol.rb +27 -861
- data/lib/claude_agent/event_handler.rb +1 -0
- data/lib/claude_agent/get_session_info.rb +86 -0
- data/lib/claude_agent/hooks.rb +23 -2
- data/lib/claude_agent/list_sessions.rb +22 -13
- data/lib/claude_agent/message_parser.rb +27 -4
- data/lib/claude_agent/messages/conversation.rb +138 -0
- data/lib/claude_agent/messages/generic.rb +39 -0
- data/lib/claude_agent/messages/hook_lifecycle.rb +158 -0
- data/lib/claude_agent/messages/result.rb +80 -0
- data/lib/claude_agent/messages/streaming.rb +84 -0
- data/lib/claude_agent/messages/system.rb +67 -0
- data/lib/claude_agent/messages/task_lifecycle.rb +240 -0
- data/lib/claude_agent/messages/tool_lifecycle.rb +95 -0
- data/lib/claude_agent/messages.rb +11 -827
- data/lib/claude_agent/options/serializer.rb +194 -0
- data/lib/claude_agent/options.rb +11 -176
- data/lib/claude_agent/sandbox_settings.rb +3 -0
- data/lib/claude_agent/session.rb +0 -204
- data/lib/claude_agent/session_mutations.rb +148 -0
- data/lib/claude_agent/types/mcp.rb +30 -0
- data/lib/claude_agent/types/models.rb +146 -0
- data/lib/claude_agent/types/operations.rb +38 -0
- data/lib/claude_agent/types/sessions.rb +50 -0
- data/lib/claude_agent/types/tools.rb +32 -0
- data/lib/claude_agent/types.rb +6 -264
- data/lib/claude_agent/v2_session.rb +207 -0
- data/lib/claude_agent/version.rb +1 -1
- data/lib/claude_agent.rb +37 -3
- data/sig/claude_agent.rbs +146 -13
- metadata +33 -1
data/SPEC.md
CHANGED
|
@@ -3,11 +3,11 @@
|
|
|
3
3
|
This document provides a comprehensive specification of the Claude Agent SDK, comparing feature parity across the official TypeScript and Python SDKs with this Ruby implementation.
|
|
4
4
|
|
|
5
5
|
**Reference Versions:**
|
|
6
|
-
- TypeScript SDK: v0.2.
|
|
7
|
-
- Python SDK:
|
|
6
|
+
- TypeScript SDK: v0.2.75 (npm package)
|
|
7
|
+
- Python SDK: from GitHub (commit 9880677)
|
|
8
8
|
- Ruby SDK: This repository
|
|
9
9
|
|
|
10
|
-
**Last Updated:** 2026-
|
|
10
|
+
**Last Updated:** 2026-03-13
|
|
11
11
|
|
|
12
12
|
---
|
|
13
13
|
|
|
@@ -69,6 +69,7 @@ Configuration options for SDK queries and clients.
|
|
|
69
69
|
| `env` | ✅ | ✅ | ✅ | Environment variables |
|
|
70
70
|
| `sandbox` | ✅ | ✅ | ✅ | Sandbox settings |
|
|
71
71
|
| `settingSources` | ✅ | ✅ | ✅ | Which settings to load |
|
|
72
|
+
| `settings` | ✅ | ✅ | ✅ | Additional settings (path or object) |
|
|
72
73
|
| `plugins` | ✅ | ✅ | ✅ | Plugin configurations |
|
|
73
74
|
| `betas` | ✅ | ✅ | ✅ | Beta features (e.g., context-1m-2025-08-07) |
|
|
74
75
|
| `abortController` | ✅ | ❌ | ✅ | Cancellation controller |
|
|
@@ -81,6 +82,9 @@ Configuration options for SDK queries and clients.
|
|
|
81
82
|
| `promptSuggestions` | ✅ | ❌ | ✅ | Enable prompt suggestion after each turn (v0.2.47) |
|
|
82
83
|
| `debug` | ✅ | ❌ | ✅ | Enable verbose debug logging |
|
|
83
84
|
| `debugFile` | ✅ | ❌ | ✅ | Write debug logs to specific file path |
|
|
85
|
+
| `toolConfig` | ✅ | ❌ | ✅ | Tool behavior config (e.g., askUserQuestion preview format) |
|
|
86
|
+
| `onElicitation` | ✅ | ❌ | ✅ | MCP elicitation request handler callback |
|
|
87
|
+
| `agentProgressSummaries` | ✅ | ❌ | ✅ | Progress summaries for subagents (v0.2.72) |
|
|
84
88
|
|
|
85
89
|
---
|
|
86
90
|
|
|
@@ -88,28 +92,30 @@ Configuration options for SDK queries and clients.
|
|
|
88
92
|
|
|
89
93
|
Messages exchanged between SDK and CLI.
|
|
90
94
|
|
|
91
|
-
| Message Type
|
|
92
|
-
|
|
93
|
-
| `UserMessage`
|
|
94
|
-
| `UserMessageReplay`
|
|
95
|
-
| `AssistantMessage`
|
|
96
|
-
| `SystemMessage`
|
|
97
|
-
| `ResultMessage`
|
|
98
|
-
| `StreamEvent`
|
|
99
|
-
| `CompactBoundaryMessage`
|
|
100
|
-
| `StatusMessage`
|
|
101
|
-
| `ToolProgressMessage`
|
|
102
|
-
| `HookStartedMessage`
|
|
103
|
-
| `HookProgressMessage`
|
|
104
|
-
| `HookResponseMessage`
|
|
105
|
-
| `AuthStatusMessage`
|
|
106
|
-
| `TaskNotificationMessage`
|
|
107
|
-
| `ToolUseSummaryMessage`
|
|
108
|
-
| `TaskStartedMessage`
|
|
109
|
-
| `TaskProgressMessage`
|
|
110
|
-
| `RateLimitEvent`
|
|
111
|
-
| `PromptSuggestionMessage`
|
|
112
|
-
| `FilesPersistedEvent`
|
|
95
|
+
| Message Type | TypeScript | Python | Ruby | Notes |
|
|
96
|
+
|------------------------------|:----------:|:------:|:----:|------------------------------------|
|
|
97
|
+
| `UserMessage` | ✅ | ✅ | ✅ | User input |
|
|
98
|
+
| `UserMessageReplay` | ✅ | ❌ | ✅ | Replayed user message on resume |
|
|
99
|
+
| `AssistantMessage` | ✅ | ✅ | ✅ | Claude response |
|
|
100
|
+
| `SystemMessage` | ✅ | ✅ | ✅ | System/init messages |
|
|
101
|
+
| `ResultMessage` | ✅ | ✅ | ✅ | Final result with usage |
|
|
102
|
+
| `StreamEvent` | ✅ | ✅ | ✅ | Partial streaming events |
|
|
103
|
+
| `CompactBoundaryMessage` | ✅ | ❌ | ✅ | Conversation compaction marker |
|
|
104
|
+
| `StatusMessage` | ✅ | ❌ | ✅ | Status updates (compacting) |
|
|
105
|
+
| `ToolProgressMessage` | ✅ | ❌ | ✅ | Long-running tool progress |
|
|
106
|
+
| `HookStartedMessage` | ✅ | ❌ | ✅ | Hook execution started |
|
|
107
|
+
| `HookProgressMessage` | ✅ | ❌ | ✅ | Hook progress during execution |
|
|
108
|
+
| `HookResponseMessage` | ✅ | ❌ | ✅ | Hook execution output |
|
|
109
|
+
| `AuthStatusMessage` | ✅ | ❌ | ✅ | Authentication status |
|
|
110
|
+
| `TaskNotificationMessage` | ✅ | ✅ | ✅ | Background task completion |
|
|
111
|
+
| `ToolUseSummaryMessage` | ✅ | ❌ | ✅ | Summary of tool use (collapsed) |
|
|
112
|
+
| `TaskStartedMessage` | ✅ | ✅ | ✅ | Subagent task registered (v0.2.45) |
|
|
113
|
+
| `TaskProgressMessage` | ✅ | ✅ | ✅ | Background task progress (v0.2.51) |
|
|
114
|
+
| `RateLimitEvent` | ✅ | ✅ | ✅ | Rate limit status changes |
|
|
115
|
+
| `PromptSuggestionMessage` | ✅ | ❌ | ✅ | Suggested next prompt (v0.2.47) |
|
|
116
|
+
| `FilesPersistedEvent` | ✅ | ❌ | ✅ | File persistence confirmation |
|
|
117
|
+
| `ElicitationCompleteMessage` | ✅ | ❌ | ✅ | MCP elicitation completed |
|
|
118
|
+
| `LocalCommandOutputMessage` | ✅ | ❌ | ✅ | Local command output |
|
|
113
119
|
|
|
114
120
|
### Message Fields
|
|
115
121
|
|
|
@@ -131,7 +137,8 @@ Messages exchanged between SDK and CLI.
|
|
|
131
137
|
| `errors` | ✅ | ❌ | ✅ | Error messages |
|
|
132
138
|
| `uuid` | ✅ | ❌ | ✅ | Message UUID |
|
|
133
139
|
| `session_id` | ✅ | ✅ | ✅ | Session ID |
|
|
134
|
-
| `stop_reason` | ✅ |
|
|
140
|
+
| `stop_reason` | ✅ | ✅ | ✅ | Why model stopped |
|
|
141
|
+
| `fast_mode_state` | ✅ | ❌ | ✅ | Fast mode status |
|
|
135
142
|
|
|
136
143
|
#### Result Subtypes
|
|
137
144
|
|
|
@@ -147,12 +154,12 @@ Messages exchanged between SDK and CLI.
|
|
|
147
154
|
|
|
148
155
|
| Field | TypeScript | Python | Ruby | Notes |
|
|
149
156
|
|---------------|:----------:|:------:|:----:|-----------------------------|
|
|
150
|
-
| `task_id` | ✅ |
|
|
151
|
-
| `tool_use_id` | ✅ |
|
|
152
|
-
| `status` | ✅ |
|
|
153
|
-
| `output_file` | ✅ |
|
|
154
|
-
| `summary` | ✅ |
|
|
155
|
-
| `usage` | ✅ |
|
|
157
|
+
| `task_id` | ✅ | ✅ | ✅ | Task identifier |
|
|
158
|
+
| `tool_use_id` | ✅ | ✅ | ✅ | Correlating tool call ID |
|
|
159
|
+
| `status` | ✅ | ✅ | ✅ | completed/failed/stopped |
|
|
160
|
+
| `output_file` | ✅ | ✅ | ✅ | Path to task output |
|
|
161
|
+
| `summary` | ✅ | ✅ | ✅ | Task summary |
|
|
162
|
+
| `usage` | ✅ | ✅ | ✅ | Tokens/tool counts/duration |
|
|
156
163
|
|
|
157
164
|
#### ToolProgressMessage
|
|
158
165
|
|
|
@@ -199,6 +206,64 @@ Messages exchanged between SDK and CLI.
|
|
|
199
206
|
| `stdout` | ✅ | ❌ | ✅ | Standard output so far |
|
|
200
207
|
| `stderr` | ✅ | ❌ | ✅ | Standard error so far |
|
|
201
208
|
|
|
209
|
+
#### TaskStartedMessage
|
|
210
|
+
|
|
211
|
+
| Field | TypeScript | Python | Ruby | Notes |
|
|
212
|
+
|---------------|:----------:|:------:|:----:|-------------------------|
|
|
213
|
+
| `task_id` | ✅ | ✅ | ✅ | Task identifier |
|
|
214
|
+
| `tool_use_id` | ✅ | ✅ | ✅ | Correlating tool use ID |
|
|
215
|
+
| `description` | ✅ | ✅ | ✅ | Task description |
|
|
216
|
+
| `task_type` | ✅ | ✅ | ✅ | Task type (e.g., bash) |
|
|
217
|
+
| `prompt` | ✅ | ❌ | ✅ | Task prompt (v0.2.75) |
|
|
218
|
+
|
|
219
|
+
#### TaskProgressMessage
|
|
220
|
+
|
|
221
|
+
| Field | TypeScript | Python | Ruby | Notes |
|
|
222
|
+
|------------------|:----------:|:------:|:----:|---------------------------------------------------|
|
|
223
|
+
| `task_id` | ✅ | ✅ | ✅ | Task identifier |
|
|
224
|
+
| `tool_use_id` | ✅ | ✅ | ✅ | Correlating tool use ID |
|
|
225
|
+
| `description` | ✅ | ✅ | ✅ | Current progress description |
|
|
226
|
+
| `usage` | ✅ | ✅ | ✅ | Cumulative {total_tokens, tool_uses, duration_ms} |
|
|
227
|
+
| `last_tool_name` | ✅ | ✅ | ✅ | Last tool executed |
|
|
228
|
+
| `summary` | ✅ | ❌ | ✅ | AI-generated progress summary (v0.2.72) |
|
|
229
|
+
|
|
230
|
+
#### AuthStatusMessage
|
|
231
|
+
|
|
232
|
+
| Field | TypeScript | Python | Ruby | Notes |
|
|
233
|
+
|--------------------|:----------:|:------:|:----:|-------------------------|
|
|
234
|
+
| `isAuthenticating` | ✅ | ❌ | ✅ | Authentication active |
|
|
235
|
+
| `output` | ✅ | ❌ | ✅ | Auth output messages |
|
|
236
|
+
| `error` | ✅ | ❌ | ✅ | Auth error message |
|
|
237
|
+
|
|
238
|
+
#### ToolUseSummaryMessage
|
|
239
|
+
|
|
240
|
+
| Field | TypeScript | Python | Ruby | Notes |
|
|
241
|
+
|--------------------------|:----------:|:------:|:----:|-------------------------------|
|
|
242
|
+
| `summary` | ✅ | ❌ | ✅ | Summary text |
|
|
243
|
+
| `preceding_tool_use_ids` | ✅ | ❌ | ✅ | Tool use IDs being summarized |
|
|
244
|
+
|
|
245
|
+
#### RateLimitEvent
|
|
246
|
+
|
|
247
|
+
| Field | TypeScript | Python | Ruby | Notes |
|
|
248
|
+
|-------------------|:----------:|:------:|:----:|---------------------------------|
|
|
249
|
+
| `rate_limit_info` | ✅ | ✅ | ✅ | Rate limit details object |
|
|
250
|
+
|
|
251
|
+
Rate limit info contains: `status`, `resetsAt`, `rateLimitType`, `utilization`, `isUsingOverage`, `overageStatus`, `overageResetsAt`, `overageDisabledReason` (v0.2.49+), `surpassedThreshold`.
|
|
252
|
+
|
|
253
|
+
#### PromptSuggestionMessage
|
|
254
|
+
|
|
255
|
+
| Field | TypeScript | Python | Ruby | Notes |
|
|
256
|
+
|--------------|:----------:|:------:|:----:|-------------------------|
|
|
257
|
+
| `suggestion` | ✅ | ❌ | ✅ | Suggested next prompt |
|
|
258
|
+
|
|
259
|
+
#### FilesPersistedEvent
|
|
260
|
+
|
|
261
|
+
| Field | TypeScript | Python | Ruby | Notes |
|
|
262
|
+
|----------------|:----------:|:------:|:----:|--------------------------------------------|
|
|
263
|
+
| `files` | ✅ | ❌ | ✅ | Successfully persisted {filename, file_id} |
|
|
264
|
+
| `failed` | ✅ | ❌ | ✅ | Failed files {filename, error} |
|
|
265
|
+
| `processed_at` | ✅ | ❌ | ✅ | Processing timestamp |
|
|
266
|
+
|
|
202
267
|
---
|
|
203
268
|
|
|
204
269
|
## 3. Content Blocks
|
|
@@ -240,28 +305,29 @@ Bidirectional control protocol for SDK-CLI communication.
|
|
|
240
305
|
|
|
241
306
|
### Control Request Types
|
|
242
307
|
|
|
243
|
-
| Request Subtype | TypeScript | Python | Ruby | Notes
|
|
244
|
-
|
|
245
|
-
| `initialize` | ✅ | ✅ | ✅ | Initialize session with hooks/MCP
|
|
246
|
-
| `interrupt` | ✅ | ✅ | ✅ | Interrupt current operation
|
|
247
|
-
| `can_use_tool` | ✅ | ✅ | ✅ | Permission callback
|
|
248
|
-
| `hook_callback` | ✅ | ✅ | ✅ | Execute hook callback
|
|
249
|
-
| `set_permission_mode` | ✅ | ✅ | ✅ | Change permission mode
|
|
250
|
-
| `set_model` | ✅ | ✅ | ✅ | Change model
|
|
251
|
-
| `set_max_thinking_tokens` | ✅ | ❌ | ✅ | Change thinking tokens limit
|
|
252
|
-
| `rewind_files` | ✅ | ✅ | ✅ | Rewind file checkpoints
|
|
253
|
-
| `mcp_message` | ✅ | ✅ | ✅ | Route MCP message
|
|
254
|
-
| `mcp_set_servers` | ✅ | ❌ | ✅ | Dynamically set MCP servers
|
|
255
|
-
| `mcp_status` | ✅ | ✅ | ✅ | Get MCP server status
|
|
256
|
-
| `mcp_reconnect` | ✅ |
|
|
257
|
-
| `mcp_toggle` | ✅ |
|
|
258
|
-
| `stop_task` | ✅ |
|
|
259
|
-
| `mcp_authenticate` | ✅ | ❌ | ✅ | Authenticate MCP server (v0.2.52)
|
|
260
|
-
| `mcp_clear_auth` | ✅ | ❌ | ✅ | Clear MCP server auth (v0.2.52)
|
|
261
|
-
| `supported_commands` | ✅ | ❌ | ✅ | Get available slash commands
|
|
262
|
-
| `supported_models` | ✅ | ❌ | ✅ | Get available models
|
|
263
|
-
| `account_info` | ✅ | ❌ | ✅ | Get account information
|
|
264
|
-
| `apply_flag_settings` | ✅ | ❌ | ✅ | Merge settings into flag layer
|
|
308
|
+
| Request Subtype | TypeScript | Python | Ruby | Notes |
|
|
309
|
+
|---------------------------|:----------:|:------:|:----:|--------------------------------------------|
|
|
310
|
+
| `initialize` | ✅ | ✅ | ✅ | Initialize session with hooks/MCP |
|
|
311
|
+
| `interrupt` | ✅ | ✅ | ✅ | Interrupt current operation |
|
|
312
|
+
| `can_use_tool` | ✅ | ✅ | ✅ | Permission callback |
|
|
313
|
+
| `hook_callback` | ✅ | ✅ | ✅ | Execute hook callback |
|
|
314
|
+
| `set_permission_mode` | ✅ | ✅ | ✅ | Change permission mode |
|
|
315
|
+
| `set_model` | ✅ | ✅ | ✅ | Change model |
|
|
316
|
+
| `set_max_thinking_tokens` | ✅ | ❌ | ✅ | Change thinking tokens limit |
|
|
317
|
+
| `rewind_files` | ✅ | ✅ | ✅ | Rewind file checkpoints (supports dry_run) |
|
|
318
|
+
| `mcp_message` | ✅ | ✅ | ✅ | Route MCP message |
|
|
319
|
+
| `mcp_set_servers` | ✅ | ❌ | ✅ | Dynamically set MCP servers |
|
|
320
|
+
| `mcp_status` | ✅ | ✅ | ✅ | Get MCP server status |
|
|
321
|
+
| `mcp_reconnect` | ✅ | ✅ | ✅ | Reconnect to MCP server |
|
|
322
|
+
| `mcp_toggle` | ✅ | ✅ | ✅ | Enable/disable MCP server |
|
|
323
|
+
| `stop_task` | ✅ | ✅ | ✅ | Stop a running background task |
|
|
324
|
+
| `mcp_authenticate` | ✅ | ❌ | ✅ | Authenticate MCP server (v0.2.52) |
|
|
325
|
+
| `mcp_clear_auth` | ✅ | ❌ | ✅ | Clear MCP server auth (v0.2.52) |
|
|
326
|
+
| `supported_commands` | ✅ | ❌ | ✅ | Get available slash commands |
|
|
327
|
+
| `supported_models` | ✅ | ❌ | ✅ | Get available models |
|
|
328
|
+
| `account_info` | ✅ | ❌ | ✅ | Get account information |
|
|
329
|
+
| `apply_flag_settings` | ✅ | ❌ | ✅ | Merge settings into flag layer |
|
|
330
|
+
| `supported_agents` | ✅ | ❌ | ✅ | Get available subagents (v0.2.63) |
|
|
265
331
|
|
|
266
332
|
### Return Types
|
|
267
333
|
|
|
@@ -274,17 +340,20 @@ Bidirectional control protocol for SDK-CLI communication.
|
|
|
274
340
|
| `InitializationResult` | ✅ | ❌ | ✅ | Full init response |
|
|
275
341
|
| `McpSetServersResult` | ✅ | ❌ | ✅ | Set servers result |
|
|
276
342
|
| `RewindFilesResult` | ✅ | ✅ | ✅ | Rewind result |
|
|
343
|
+
| `AgentInfo` | ✅ | ❌ | ✅ | Available agent info |
|
|
277
344
|
|
|
278
345
|
#### ModelInfo Fields
|
|
279
346
|
|
|
280
|
-
| Field | TypeScript | Python | Ruby | Notes
|
|
281
|
-
|
|
282
|
-
| `value` | ✅ | ❌ | ✅ | Model identifier
|
|
283
|
-
| `displayName` | ✅ | ❌ | ✅ | Human-readable name
|
|
284
|
-
| `description` | ✅ | ❌ | ✅ | Model description
|
|
285
|
-
| `supportsEffort` | ✅ | ❌ | ✅ | Whether model supports effort
|
|
286
|
-
| `supportedEffortLevels` | ✅ | ❌ | ✅ | Available effort levels
|
|
287
|
-
| `supportsAdaptiveThinking` | ✅ | ❌ | ✅ | Whether adaptive thinking works
|
|
347
|
+
| Field | TypeScript | Python | Ruby | Notes |
|
|
348
|
+
|----------------------------|:----------:|:------:|:----:|--------------------------------------------|
|
|
349
|
+
| `value` | ✅ | ❌ | ✅ | Model identifier |
|
|
350
|
+
| `displayName` | ✅ | ❌ | ✅ | Human-readable name |
|
|
351
|
+
| `description` | ✅ | ❌ | ✅ | Model description |
|
|
352
|
+
| `supportsEffort` | ✅ | ❌ | ✅ | Whether model supports effort |
|
|
353
|
+
| `supportedEffortLevels` | ✅ | ❌ | ✅ | Available effort levels |
|
|
354
|
+
| `supportsAdaptiveThinking` | ✅ | ❌ | ✅ | Whether adaptive thinking works |
|
|
355
|
+
| `supportsFastMode` | ✅ | ❌ | ✅ | Whether model supports fast mode (v0.2.69) |
|
|
356
|
+
| `supportsAutoMode` | ✅ | ❌ | ✅ | Whether model supports auto mode (v0.2.75) |
|
|
288
357
|
|
|
289
358
|
#### McpServerStatus Fields
|
|
290
359
|
|
|
@@ -292,11 +361,49 @@ Bidirectional control protocol for SDK-CLI communication.
|
|
|
292
361
|
|--------------|:----------:|:------:|:----:|------------------------------------|
|
|
293
362
|
| `name` | ✅ | ✅ | ✅ | Server name |
|
|
294
363
|
| `status` | ✅ | ✅ | ✅ | Connection status |
|
|
295
|
-
| `serverInfo` | ✅ |
|
|
296
|
-
| `error` | ✅ |
|
|
297
|
-
| `config` | ✅ |
|
|
298
|
-
| `scope` | ✅ |
|
|
299
|
-
| `tools` | ✅ |
|
|
364
|
+
| `serverInfo` | ✅ | ✅ | ✅ | Server name/version |
|
|
365
|
+
| `error` | ✅ | ✅ | ✅ | Error message (when failed) |
|
|
366
|
+
| `config` | ✅ | ✅ | ✅ | Server configuration |
|
|
367
|
+
| `scope` | ✅ | ✅ | ✅ | Config scope (project, user, etc.) |
|
|
368
|
+
| `tools` | ✅ | ✅ | ✅ | Tools with annotations |
|
|
369
|
+
|
|
370
|
+
#### InitializationResult Fields
|
|
371
|
+
|
|
372
|
+
| Field | TypeScript | Python | Ruby | Notes |
|
|
373
|
+
|---------------------------|:----------:|:------:|:----:|-----------------------------------|
|
|
374
|
+
| `commands` | ✅ | ❌ | ✅ | Available slash commands |
|
|
375
|
+
| `output_style` | ✅ | ❌ | ✅ | Current output style |
|
|
376
|
+
| `available_output_styles` | ✅ | ❌ | ✅ | All available output styles |
|
|
377
|
+
| `models` | ✅ | ❌ | ✅ | Available models (ModelInfo[]) |
|
|
378
|
+
| `account` | ✅ | ❌ | ✅ | Account information (AccountInfo) |
|
|
379
|
+
| `agents` | ✅ | ❌ | ✅ | Available agents (AgentInfo[]) |
|
|
380
|
+
| `fast_mode_state` | ✅ | ❌ | ✅ | Fast mode status (v0.2.75) |
|
|
381
|
+
|
|
382
|
+
#### RewindFilesResult Fields
|
|
383
|
+
|
|
384
|
+
| Field | TypeScript | Python | Ruby | Notes |
|
|
385
|
+
|----------------|:----------:|:------:|:----:|-------------------------------|
|
|
386
|
+
| `canRewind` | ✅ | ✅ | ✅ | Whether rewind is possible |
|
|
387
|
+
| `error` | ✅ | ❌ | ✅ | Error message if can't rewind |
|
|
388
|
+
| `filesChanged` | ✅ | ❌ | ✅ | List of changed file paths |
|
|
389
|
+
| `insertions` | ✅ | ❌ | ✅ | Number of line insertions |
|
|
390
|
+
| `deletions` | ✅ | ❌ | ✅ | Number of line deletions |
|
|
391
|
+
|
|
392
|
+
#### McpSetServersResult Fields
|
|
393
|
+
|
|
394
|
+
| Field | TypeScript | Python | Ruby | Notes |
|
|
395
|
+
|-----------|:----------:|:------:|:----:|-----------------------------------|
|
|
396
|
+
| `added` | ✅ | ❌ | ✅ | Server names that were added |
|
|
397
|
+
| `removed` | ✅ | ❌ | ✅ | Server names that were removed |
|
|
398
|
+
| `errors` | ✅ | ❌ | ✅ | Map of server name to error |
|
|
399
|
+
|
|
400
|
+
#### AgentInfo Fields
|
|
401
|
+
|
|
402
|
+
| Field | TypeScript | Python | Ruby | Notes |
|
|
403
|
+
|---------------|:----------:|:------:|:----:|------------------------------------|
|
|
404
|
+
| `name` | ✅ | ❌ | ✅ | Agent type identifier |
|
|
405
|
+
| `description` | ✅ | ❌ | ✅ | When to use this agent |
|
|
406
|
+
| `model` | ✅ | ❌ | ✅ | Model alias (inherits if omitted) |
|
|
300
407
|
|
|
301
408
|
---
|
|
302
409
|
|
|
@@ -313,7 +420,7 @@ Event hooks for intercepting and modifying SDK behavior.
|
|
|
313
420
|
| `PostToolUseFailure` | ✅ | ✅ | ✅ | After tool failure (Py v0.1.26) |
|
|
314
421
|
| `Notification` | ✅ | ✅ | ✅ | System notifications (Py v0.1.29) |
|
|
315
422
|
| `UserPromptSubmit` | ✅ | ✅ | ✅ | User message submitted |
|
|
316
|
-
| `SessionStart` | ✅ |
|
|
423
|
+
| `SessionStart` | ✅ | ✅ | ✅ | Session starts |
|
|
317
424
|
| `SessionEnd` | ✅ | ❌ | ✅ | Session ends |
|
|
318
425
|
| `Stop` | ✅ | ✅ | ✅ | Agent stops |
|
|
319
426
|
| `SubagentStart` | ✅ | ✅ | ✅ | Subagent starts (Py v0.1.29) |
|
|
@@ -323,9 +430,12 @@ Event hooks for intercepting and modifying SDK behavior.
|
|
|
323
430
|
| `Setup` | ✅ | ❌ | ✅ | Initial setup/maintenance |
|
|
324
431
|
| `TeammateIdle` | ✅ | ❌ | ✅ | Teammate idle (v0.2.33) |
|
|
325
432
|
| `TaskCompleted` | ✅ | ❌ | ✅ | Task completed (v0.2.33) |
|
|
433
|
+
| `Elicitation` | ✅ | ❌ | ✅ | MCP elicitation request |
|
|
434
|
+
| `ElicitationResult` | ✅ | ❌ | ✅ | MCP elicitation response |
|
|
326
435
|
| `ConfigChange` | ✅ | ❌ | ✅ | Config file changed (v0.2.49) |
|
|
327
436
|
| `WorktreeCreate` | ✅ | ❌ | ✅ | Worktree creation (v0.2.50) |
|
|
328
437
|
| `WorktreeRemove` | ✅ | ❌ | ✅ | Worktree removal (v0.2.50) |
|
|
438
|
+
| `InstructionsLoaded` | ✅ | ❌ | ✅ | CLAUDE.md file loaded (v0.2.69) |
|
|
329
439
|
|
|
330
440
|
### Hook Input Types
|
|
331
441
|
|
|
@@ -346,9 +456,23 @@ Event hooks for intercepting and modifying SDK behavior.
|
|
|
346
456
|
| `SetupHookInput` | ✅ | ❌ | ✅ |
|
|
347
457
|
| `TeammateIdleHookInput` | ✅ | ❌ | ✅ |
|
|
348
458
|
| `TaskCompletedHookInput` | ✅ | ❌ | ✅ |
|
|
459
|
+
| `ElicitationHookInput` | ✅ | ❌ | ✅ |
|
|
460
|
+
| `ElicitationResultHookInput` | ✅ | ❌ | ✅ |
|
|
349
461
|
| `ConfigChangeHookInput` | ✅ | ❌ | ✅ |
|
|
350
462
|
| `WorktreeCreateHookInput` | ✅ | ❌ | ✅ |
|
|
351
463
|
| `WorktreeRemoveHookInput` | ✅ | ❌ | ✅ |
|
|
464
|
+
| `InstructionsLoadedHookInput` | ✅ | ❌ | ✅ |
|
|
465
|
+
|
|
466
|
+
#### BaseHookInput Fields
|
|
467
|
+
|
|
468
|
+
| Field | TypeScript | Python | Ruby | Notes |
|
|
469
|
+
|-------------------|:----------:|:------:|:----:|--------------------------------------------------|
|
|
470
|
+
| `session_id` | ✅ | ✅ | ✅ | Session identifier |
|
|
471
|
+
| `transcript_path` | ✅ | ✅ | ✅ | Path to session transcript |
|
|
472
|
+
| `cwd` | ✅ | ✅ | ✅ | Working directory |
|
|
473
|
+
| `permission_mode` | ✅ | ❌ | ✅ | Current permission mode |
|
|
474
|
+
| `agent_id` | ✅ | ✅ | ✅ | Subagent ID (when in subagent context) (v0.2.69) |
|
|
475
|
+
| `agent_type` | ✅ | ✅ | ✅ | Agent type name (v0.2.69) |
|
|
352
476
|
|
|
353
477
|
#### StopHookInput Fields
|
|
354
478
|
|
|
@@ -443,6 +567,20 @@ Event-specific fields returned via `hookSpecificOutput`:
|
|
|
443
567
|
|---------------------|:----------:|:------:|:----:|----------------------------------|
|
|
444
568
|
| `additionalContext` | ✅ | ✅ | ✅ | Context string returned to model |
|
|
445
569
|
|
|
570
|
+
#### ElicitationHookSpecificOutput
|
|
571
|
+
|
|
572
|
+
| Field | TypeScript | Python | Ruby | Notes |
|
|
573
|
+
|-----------|:----------:|:------:|:----:|----------------------------------|
|
|
574
|
+
| `action` | ✅ | ❌ | ✅ | accept/decline/cancel |
|
|
575
|
+
| `content` | ✅ | ❌ | ✅ | Response content for form mode |
|
|
576
|
+
|
|
577
|
+
#### ElicitationResultHookSpecificOutput
|
|
578
|
+
|
|
579
|
+
| Field | TypeScript | Python | Ruby | Notes |
|
|
580
|
+
|-----------|:----------:|:------:|:----:|----------------------------------|
|
|
581
|
+
| `action` | ✅ | ❌ | ✅ | accept/decline/cancel |
|
|
582
|
+
| `content` | ✅ | ❌ | ✅ | Response content |
|
|
583
|
+
|
|
446
584
|
### Hook Matcher
|
|
447
585
|
|
|
448
586
|
| Field | TypeScript | Python | Ruby |
|
|
@@ -508,15 +646,15 @@ Permission handling and updates.
|
|
|
508
646
|
|
|
509
647
|
### ToolPermissionContext
|
|
510
648
|
|
|
511
|
-
| Field | TypeScript | Python | Ruby | Notes
|
|
512
|
-
|
|
513
|
-
| `signal` | ✅ | ✅ | ✅ | Abort signal
|
|
514
|
-
| `suggestions` | ✅ | ✅ | ✅ | Permission suggestions
|
|
515
|
-
| `blockedPath` | ✅ | ❌ | ✅ | Blocked file path
|
|
516
|
-
| `decisionReason` | ✅ | ❌ | ✅ | Why permission triggered
|
|
517
|
-
| `toolUseID` | ✅ | ❌ | ✅ | Tool call ID
|
|
518
|
-
| `agentID` | ✅ | ❌ | ✅ | Subagent ID if applicable
|
|
519
|
-
| `description` | ✅ | ❌ | ✅ | Human-readable tool description |
|
|
649
|
+
| Field | TypeScript | Python | Ruby | Notes |
|
|
650
|
+
|------------------|:----------:|:------:|:----:|--------------------------------------------------|
|
|
651
|
+
| `signal` | ✅ | ✅ | ✅ | Abort signal |
|
|
652
|
+
| `suggestions` | ✅ | ✅ | ✅ | Permission suggestions |
|
|
653
|
+
| `blockedPath` | ✅ | ❌ | ✅ | Blocked file path |
|
|
654
|
+
| `decisionReason` | ✅ | ❌ | ✅ | Why permission triggered |
|
|
655
|
+
| `toolUseID` | ✅ | ❌ | ✅ | Tool call ID |
|
|
656
|
+
| `agentID` | ✅ | ❌ | ✅ | Subagent ID if applicable |
|
|
657
|
+
| `description` | ✅ | ❌ | ✅ | Human-readable tool description (v0.2.75) |
|
|
520
658
|
|
|
521
659
|
---
|
|
522
660
|
|
|
@@ -561,6 +699,14 @@ Model Context Protocol server support.
|
|
|
561
699
|
| `name` | ✅ | ✅ | ✅ |
|
|
562
700
|
| `instance` | ✅ | ✅ | ✅ |
|
|
563
701
|
|
|
702
|
+
#### claudeai-proxy
|
|
703
|
+
|
|
704
|
+
| Field | TypeScript | Python | Ruby |
|
|
705
|
+
|--------|:----------:|:------:|:----:|
|
|
706
|
+
| `type` | ✅ | ❌ | ✅ |
|
|
707
|
+
| `url` | ✅ | ❌ | ✅ |
|
|
708
|
+
| `id` | ✅ | ❌ | ✅ |
|
|
709
|
+
|
|
564
710
|
### SDK MCP Server
|
|
565
711
|
|
|
566
712
|
| Feature | TypeScript | Python | Ruby | Notes |
|
|
@@ -589,46 +735,53 @@ Session management and resumption.
|
|
|
589
735
|
|
|
590
736
|
| Feature | TypeScript | Python | Ruby | Notes |
|
|
591
737
|
|------------------------|:----------:|:------:|:----:|--------------------------------------------------|
|
|
592
|
-
| `listSessions()` | ✅ |
|
|
593
|
-
| `getSessionMessages()` | ✅ |
|
|
738
|
+
| `listSessions()` | ✅ | ✅ | ✅ | List past sessions with metadata (v0.2.53) |
|
|
739
|
+
| `getSessionMessages()` | ✅ | ✅ | ✅ | Read session transcript messages (v0.2.59) |
|
|
740
|
+
| `getSessionInfo()` | ✅ | ❌ | ✅ | Get single session metadata (v0.2.75) |
|
|
741
|
+
| `renameSession()` | ✅ | ✅ | ✅ | Rename a session (v0.2.74) |
|
|
742
|
+
| `tagSession()` | ✅ | ✅ | ✅ | Tag a session (v0.2.75) |
|
|
594
743
|
|
|
595
744
|
#### ListSessionsOptions
|
|
596
745
|
|
|
597
|
-
| Field
|
|
598
|
-
|
|
599
|
-
| `dir`
|
|
600
|
-
| `limit`
|
|
746
|
+
| Field | TypeScript | Python | Ruby | Notes |
|
|
747
|
+
|--------------------|:----------:|:------:|:----:|-----------------------------------------------|
|
|
748
|
+
| `dir` | ✅ | ✅ | ✅ | Project directory (includes worktrees) |
|
|
749
|
+
| `limit` | ✅ | ✅ | ✅ | Maximum number of sessions to return |
|
|
750
|
+
| `includeWorktrees` | ✅ | ✅ | ✅ | Include git worktree sessions (default: true) |
|
|
751
|
+
| `offset` | ✅ | ❌ | ✅ | Pagination offset (v0.2.75) |
|
|
601
752
|
|
|
602
753
|
#### GetSessionMessagesOptions
|
|
603
754
|
|
|
604
755
|
| Field | TypeScript | Python | Ruby | Notes |
|
|
605
756
|
|----------|:----------:|:------:|:----:|----------------------------------------------|
|
|
606
|
-
| `dir` | ✅ |
|
|
607
|
-
| `limit` | ✅ |
|
|
608
|
-
| `offset` | ✅ |
|
|
757
|
+
| `dir` | ✅ | ✅ | ✅ | Project directory to find session in |
|
|
758
|
+
| `limit` | ✅ | ✅ | ✅ | Maximum number of messages to return |
|
|
759
|
+
| `offset` | ✅ | ✅ | ✅ | Number of messages to skip from the start |
|
|
609
760
|
|
|
610
761
|
#### SessionMessage Fields
|
|
611
762
|
|
|
612
763
|
| Field | TypeScript | Python | Ruby | Notes |
|
|
613
764
|
|----------------------|:----------:|:------:|:----:|----------------------------------|
|
|
614
|
-
| `type` | ✅ |
|
|
615
|
-
| `uuid` | ✅ |
|
|
616
|
-
| `session_id` | ✅ |
|
|
617
|
-
| `message` | ✅ |
|
|
618
|
-
| `parent_tool_use_id` | ✅ |
|
|
765
|
+
| `type` | ✅ | ✅ | ✅ | 'user' or 'assistant' |
|
|
766
|
+
| `uuid` | ✅ | ✅ | ✅ | Message UUID |
|
|
767
|
+
| `session_id` | ✅ | ✅ | ✅ | Session ID |
|
|
768
|
+
| `message` | ✅ | ✅ | ✅ | Raw message content |
|
|
769
|
+
| `parent_tool_use_id` | ✅ | ✅ | ✅ | Parent tool use ID (always null) |
|
|
619
770
|
|
|
620
771
|
#### SDKSessionInfo Fields
|
|
621
772
|
|
|
622
773
|
| Field | TypeScript | Python | Ruby | Notes |
|
|
623
774
|
|----------------|:----------:|:------:|:----:|-------------------------------------|
|
|
624
|
-
| `sessionId` | ✅ |
|
|
625
|
-
| `summary` | ✅ |
|
|
626
|
-
| `lastModified` | ✅ |
|
|
627
|
-
| `fileSize` | ✅ |
|
|
628
|
-
| `customTitle` | ✅ |
|
|
629
|
-
| `firstPrompt` | ✅ |
|
|
630
|
-
| `gitBranch` | ✅ |
|
|
631
|
-
| `cwd` | ✅ |
|
|
775
|
+
| `sessionId` | ✅ | ✅ | ✅ | Session UUID |
|
|
776
|
+
| `summary` | ✅ | ✅ | ✅ | Display title/summary |
|
|
777
|
+
| `lastModified` | ✅ | ✅ | ✅ | Last modified time (ms since epoch) |
|
|
778
|
+
| `fileSize` | ✅ | ✅ | ✅ | Session file size in bytes |
|
|
779
|
+
| `customTitle` | ✅ | ✅ | ✅ | User-set title via /rename |
|
|
780
|
+
| `firstPrompt` | ✅ | ✅ | ✅ | First meaningful user prompt |
|
|
781
|
+
| `gitBranch` | ✅ | ✅ | ✅ | Git branch at end of session |
|
|
782
|
+
| `cwd` | ✅ | ✅ | ✅ | Working directory for session |
|
|
783
|
+
| `tag` | ✅ | ❌ | ✅ | User-set tag (v0.2.75) |
|
|
784
|
+
| `createdAt` | ✅ | ❌ | ✅ | Creation time in ms (v0.2.75) |
|
|
632
785
|
|
|
633
786
|
### V2 Session API (Unstable)
|
|
634
787
|
|
|
@@ -667,17 +820,18 @@ Sandbox configuration for command execution isolation.
|
|
|
667
820
|
|
|
668
821
|
### SandboxSettings
|
|
669
822
|
|
|
670
|
-
| Field
|
|
671
|
-
|
|
672
|
-
| `enabled`
|
|
673
|
-
| `autoAllowBashIfSandboxed`
|
|
674
|
-
| `excludedCommands`
|
|
675
|
-
| `allowUnsandboxedCommands`
|
|
676
|
-
| `network`
|
|
677
|
-
| `ignoreViolations`
|
|
678
|
-
| `enableWeakerNestedSandbox`
|
|
679
|
-
| `
|
|
680
|
-
| `
|
|
823
|
+
| Field | TypeScript | Python | Ruby |
|
|
824
|
+
|----------------------------------|:----------:|:------:|:----:|
|
|
825
|
+
| `enabled` | ✅ | ✅ | ✅ |
|
|
826
|
+
| `autoAllowBashIfSandboxed` | ✅ | ✅ | ✅ |
|
|
827
|
+
| `excludedCommands` | ✅ | ✅ | ✅ |
|
|
828
|
+
| `allowUnsandboxedCommands` | ✅ | ✅ | ✅ |
|
|
829
|
+
| `network` | ✅ | ✅ | ✅ |
|
|
830
|
+
| `ignoreViolations` | ✅ | ✅ | ✅ |
|
|
831
|
+
| `enableWeakerNestedSandbox` | ✅ | ✅ | ✅ |
|
|
832
|
+
| `enableWeakerNetworkIsolation` | ✅ | ❌ | ✅ |
|
|
833
|
+
| `ripgrep` | ✅ | ❌ | ✅ |
|
|
834
|
+
| `filesystem` | ✅ | ❌ | ✅ |
|
|
681
835
|
|
|
682
836
|
### SandboxFilesystemConfig
|
|
683
837
|
|
|
@@ -740,8 +894,11 @@ Public API surface for SDK clients.
|
|
|
740
894
|
|
|
741
895
|
| Feature | TypeScript | Python | Ruby | Notes |
|
|
742
896
|
|------------------------|:----------:|:------:|:----:|--------------------------------------------|
|
|
743
|
-
| `listSessions()` | ✅ |
|
|
744
|
-
| `getSessionMessages()` | ✅ |
|
|
897
|
+
| `listSessions()` | ✅ | ✅ | ✅ | List past sessions with metadata (v0.2.53) |
|
|
898
|
+
| `getSessionMessages()` | ✅ | ✅ | ✅ | Read session transcript (v0.2.59) |
|
|
899
|
+
| `getSessionInfo()` | ✅ | ❌ | ✅ | Get single session metadata (v0.2.75) |
|
|
900
|
+
| `renameSession()` | ✅ | ✅ | ✅ | Rename a session (v0.2.74) |
|
|
901
|
+
| `tagSession()` | ✅ | ✅ | ✅ | Tag a session (v0.2.75) |
|
|
745
902
|
|
|
746
903
|
### Query Interface
|
|
747
904
|
|
|
@@ -764,25 +921,26 @@ Public API surface for SDK clients.
|
|
|
764
921
|
| `accountInfo()` | ✅ | ❌ | ✅ | Get account info |
|
|
765
922
|
| `rewindFiles()` | ✅ | ✅ | ✅ | Rewind file changes |
|
|
766
923
|
| `setMcpServers()` | ✅ | ❌ | ✅ | Dynamic MCP servers |
|
|
767
|
-
| `reconnectMcpServer()` | ✅ |
|
|
768
|
-
| `toggleMcpServer()` | ✅ |
|
|
769
|
-
| `stopTask()` | ✅ |
|
|
924
|
+
| `reconnectMcpServer()` | ✅ | ✅ | ✅ | Reconnect MCP server |
|
|
925
|
+
| `toggleMcpServer()` | ✅ | ✅ | ✅ | Enable/disable MCP |
|
|
926
|
+
| `stopTask()` | ✅ | ✅ | ✅ | Stop running task |
|
|
770
927
|
| `streamInput()` | ✅ | ✅ | ✅ | Stream user input |
|
|
771
928
|
| `initializationResult()` | ✅ | ✅ | ✅ | Full init response (Py: `get_server_info()`) |
|
|
772
929
|
| `close()` | ✅ | ✅ | ✅ | Close query/session |
|
|
930
|
+
| `supportedAgents()` | ✅ | ❌ | ✅ | Get available subagents (v0.2.63) |
|
|
773
931
|
|
|
774
932
|
### Client Class
|
|
775
933
|
|
|
776
|
-
| Feature | TypeScript | Python | Ruby | Notes
|
|
777
|
-
|
|
778
|
-
| Multi-turn client | ❌ | ✅ `ClaudeSDKClient` | ✅ `ClaudeAgent::Client` | Interactive sessions
|
|
779
|
-
| `connect()` | N/A | ✅ | ✅ | Start session
|
|
780
|
-
| `disconnect()` | N/A | ✅ | ✅ | End session
|
|
781
|
-
| `send_message()` | N/A | ✅ | ✅ | Send user message
|
|
782
|
-
| `receive_response()` | N/A | ✅ | ✅ | Receive until result
|
|
783
|
-
| `stream_input()` | N/A | ❌ | ✅ | Stream input messages
|
|
784
|
-
| `abort!()` | N/A | ❌ | ✅ | Abort operations
|
|
785
|
-
| Control methods | N/A | Partial | ✅ | interrupt, setPermissionMode, setModel, rewindFiles, mcpStatus
|
|
934
|
+
| Feature | TypeScript | Python | Ruby | Notes |
|
|
935
|
+
|----------------------|:----------:|:-------------------:|:-----------------------:|----------------------------------------------------------------------------------------------------------------------|
|
|
936
|
+
| Multi-turn client | ❌ | ✅ `ClaudeSDKClient` | ✅ `ClaudeAgent::Client` | Interactive sessions |
|
|
937
|
+
| `connect()` | N/A | ✅ | ✅ | Start session |
|
|
938
|
+
| `disconnect()` | N/A | ✅ | ✅ | End session |
|
|
939
|
+
| `send_message()` | N/A | ✅ | ✅ | Send user message |
|
|
940
|
+
| `receive_response()` | N/A | ✅ | ✅ | Receive until result |
|
|
941
|
+
| `stream_input()` | N/A | ❌ | ✅ | Stream input messages |
|
|
942
|
+
| `abort!()` | N/A | ❌ | ✅ | Abort operations |
|
|
943
|
+
| Control methods | N/A | Partial | ✅ | Python: interrupt, setPermissionMode, setModel, rewindFiles, mcpStatus, reconnectMcp, toggleMcp, stopTask; Ruby: all |
|
|
786
944
|
|
|
787
945
|
### Transport
|
|
788
946
|
|
|
@@ -810,7 +968,7 @@ Public API surface for SDK clients.
|
|
|
810
968
|
- Source is bundled/minified, but `sdk.d.ts` provides complete type definitions
|
|
811
969
|
- Includes unstable V2 session API
|
|
812
970
|
- `executable`/`executableArgs` are JS-specific (`node`/`bun`/`deno`)
|
|
813
|
-
- Does NOT have `
|
|
971
|
+
- Does NOT have `user`, `init`/`initOnly`/`maintenance` as typed Options (use `extraArgs` or `settingSources`)
|
|
814
972
|
- `ApiKeySource` includes `'oauth'`
|
|
815
973
|
- v0.2.45: Added `TaskStartedMessage`, `RateLimitEvent` message types
|
|
816
974
|
- v0.2.47: Added `promptSuggestions` option and `PromptSuggestionMessage`
|
|
@@ -822,26 +980,49 @@ Public API surface for SDK clients.
|
|
|
822
980
|
- v0.2.54 – v0.2.58: CLI parity updates (no new SDK-facing features)
|
|
823
981
|
- v0.2.59: Added `getSessionMessages()` for reading session transcript history with pagination (limit/offset)
|
|
824
982
|
- v0.2.61 – v0.2.62: CLI parity updates (no new SDK-facing features)
|
|
983
|
+
- v0.2.63: Added `supportedAgents()` method on Query, fixed `pathToClaudeCodeExecutable` PATH resolution
|
|
984
|
+
- v0.2.64 – v0.2.68: CLI parity updates (no new SDK-facing features)
|
|
985
|
+
- v0.2.69: Added `toolConfig` option (askUserQuestion preview format), `supportsFastMode` in ModelInfo, `agent_id`/`agent_type` on BaseHookInput, `InstructionsLoaded` hook event
|
|
986
|
+
- v0.2.70: Made `AgentToolInput.subagent_type` optional (defaults to general-purpose), fixed HTTP MCP servers
|
|
987
|
+
- v0.2.71: CLI parity update; `settings` now a typed Option (string path or `Settings` object)
|
|
988
|
+
- v0.2.72: Added `agentProgressSummaries` option for periodic AI-generated progress summaries
|
|
989
|
+
- v0.2.73: Fixed `options.env` being overridden by `~/.claude/settings.json`
|
|
990
|
+
- v0.2.74: Added `renameSession()` for renaming session files
|
|
991
|
+
- v0.2.75: Added `tag`/`createdAt` fields on `SDKSessionInfo`; `getSessionInfo()` for single-session lookup; `offset` on `listSessions` for pagination; `tagSession()` for tagging sessions; `supportsAutoMode` in `ModelInfo`; `description` on `SDKControlPermissionRequest`; `prompt` on `SDKTaskStartedMessage`; `fast_mode_state` on `SDKControlInitializeResponse`; `queued_to_running` status on `AgentToolOutput`
|
|
992
|
+
- Includes `Elicitation`/`ElicitationResult` hook events, `onElicitation` option, `ElicitationCompleteMessage`, `LocalCommandOutputMessage`, `FastModeState` (undocumented in changelog, present in types)
|
|
825
993
|
|
|
826
994
|
### Python SDK
|
|
827
995
|
- Full source available with `Transport` abstract class
|
|
828
|
-
- Partial control protocol: query and client support interrupt, setPermissionMode, setModel, rewindFiles, mcpStatus
|
|
996
|
+
- Partial control protocol: query and client support interrupt, setPermissionMode, setModel, rewindFiles, mcpStatus, reconnectMcpServer, toggleMcpServer, stopTask
|
|
829
997
|
- Has `CLINotFoundError`, `CLIConnectionError`, `ProcessError`, `CLIJSONDecodeError`, `MessageParseError` error types
|
|
830
|
-
-
|
|
998
|
+
- Has `TaskStartedMessage`, `TaskProgressMessage`, `TaskNotificationMessage` typed message classes (v0.1.46+)
|
|
999
|
+
- Has `stop_reason` field on ResultMessage (v0.1.46+)
|
|
1000
|
+
- Has `SDKSessionInfo`, `SessionMessage` types with `list_sessions()`/`get_session_messages()` functions (v0.1.46+)
|
|
1001
|
+
- Has `McpServerStatus` with all fields (name, status, serverInfo, error, config, scope, tools) (v0.1.46+)
|
|
1002
|
+
- Has `agent_id`/`agent_type` on tool-lifecycle hook inputs (v0.1.46+)
|
|
1003
|
+
- Has `add_mcp_server()`/`remove_mcp_server()` client methods for runtime MCP management (v0.1.46+)
|
|
1004
|
+
- Has `include_worktrees` parameter on `list_sessions()` (v0.1.46+)
|
|
1005
|
+
- Missing hooks: SessionEnd, Setup, TeammateIdle, TaskCompleted, Elicitation, ElicitationResult, ConfigChange, WorktreeCreate, WorktreeRemove, InstructionsLoaded
|
|
831
1006
|
- Missing permission modes: `dontAsk`
|
|
832
|
-
- Missing options: `allowDangerouslySkipPermissions`, `persistSession`, `resumeSessionAt`, `sessionId`, `strictMcpConfig`, `init`/`initOnly`/`maintenance`, `debug`/`debugFile`, `promptSuggestions`
|
|
1007
|
+
- Missing options: `allowDangerouslySkipPermissions`, `persistSession`, `resumeSessionAt`, `sessionId`, `strictMcpConfig`, `init`/`initOnly`/`maintenance`, `debug`/`debugFile`, `promptSuggestions`, `onElicitation`, `toolConfig`, `agentProgressSummaries`, `agent` (main thread agent)
|
|
833
1008
|
- `ToolPermissionContext` missing `blockedPath`, `decisionReason`, `toolUseID`, `agentID`, `description`
|
|
834
|
-
- Has `
|
|
1009
|
+
- Has `rename_session()`/`tag_session()` for session mutation
|
|
1010
|
+
- Has `RateLimitEvent`/`RateLimitInfo` types with full field coverage
|
|
835
1011
|
- Has SDK MCP server support with `tool()` helper and annotations
|
|
1012
|
+
- Missing `getSessionInfo()`, `offset` on `list_sessions`, `tag`/`createdAt` on `SDKSessionInfo`
|
|
836
1013
|
- Added `thinking` config and `effort` option in v0.1.36
|
|
837
1014
|
- Handles `rate_limit_event` and unknown message types gracefully (v0.1.40)
|
|
838
1015
|
- Client has `get_server_info()` for accessing the initialization result (v0.1.31+)
|
|
839
|
-
- v0.1.
|
|
1016
|
+
- v0.1.45 – v0.1.48: Major catch-up with TypeScript SDK (task messages, session APIs, MCP control methods, stop_reason)
|
|
1017
|
+
- v0.1.48: Fixed fine-grained tool streaming regression
|
|
1018
|
+
- Added `RateLimitEvent` message type with `RateLimitInfo`
|
|
1019
|
+
- Added `rename_session()` and `tag_session()` session management functions
|
|
1020
|
+
- Missing: `onElicitation`, `Elicitation`/`ElicitationResult` hooks, `ElicitationCompleteMessage`, `LocalCommandOutputMessage`, `FastModeState`, `InstructionsLoaded` hook, `agentProgressSummaries`, `getSessionInfo()`
|
|
840
1021
|
|
|
841
1022
|
### Ruby SDK (This Repository)
|
|
842
|
-
- Feature parity with TypeScript SDK v0.2.
|
|
1023
|
+
- Feature parity with TypeScript SDK v0.2.75
|
|
843
1024
|
- Ruby-idiomatic patterns (Data.define, snake_case)
|
|
844
1025
|
- Complete control protocol, hook, and V2 Session API support
|
|
845
1026
|
- Dedicated Client class for multi-turn conversations
|
|
846
1027
|
- `executable`/`executableArgs` marked N/A (JS runtime options)
|
|
847
|
-
-
|
|
1028
|
+
- Full v0.2.75 parity: `agentProgressSummaries`, `getSessionInfo()`, `renameSession()`, `tagSession()`, `offset` on `listSessions`, `tag`/`createdAt` on `SessionInfo`, `supportsAutoMode` on `ModelInfo`
|