clawd-code-sdk 1.0.26__tar.gz → 1.0.28__tar.gz

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.
Files changed (83) hide show
  1. clawd_code_sdk-1.0.28/PKG-INFO +532 -0
  2. clawd_code_sdk-1.0.28/README.md +497 -0
  3. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/pyproject.toml +1 -1
  4. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/_internal/query.py +21 -41
  5. clawd_code_sdk-1.0.28/src/clawd_code_sdk/anthropic_stream.py +205 -0
  6. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/client.py +12 -27
  7. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/__init__.py +29 -3
  8. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/base.py +14 -0
  9. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/content_blocks.py +21 -4
  10. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/context_usage.py +1 -0
  11. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/control.py +58 -11
  12. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/hooks.py +2 -0
  13. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/messages.py +11 -8
  14. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/options.py +3 -0
  15. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/output_types.py +22 -1
  16. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/permissions.py +19 -1
  17. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/server_info.py +4 -1
  18. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/settings.py +13 -1
  19. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/storage/models.py +6 -5
  20. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/storage/replay.py +6 -8
  21. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_agents_and_settings.py +6 -9
  22. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_include_partial_messages.py +9 -8
  23. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/mock_claude_server.py +11 -0
  24. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_session.py +25 -9
  25. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_streaming_client.py +14 -5
  26. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_tool_callbacks.py +4 -1
  27. clawd_code_sdk-1.0.26/PKG-INFO +0 -391
  28. clawd_code_sdk-1.0.26/README.md +0 -356
  29. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/.gitignore +0 -0
  30. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/LICENSE +0 -0
  31. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/__init__.py +0 -0
  32. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/_bundled/.gitignore +0 -0
  33. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/_errors.py +0 -0
  34. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/_internal/__init__.py +0 -0
  35. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/_internal/transport/__init__.py +0 -0
  36. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/_internal/transport/subprocess_cli.py +0 -0
  37. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/_internal/transport/subprocess_utils.py +0 -0
  38. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/_version.py +0 -0
  39. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/instrumentation.py +0 -0
  40. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/list_sessions.py +0 -0
  41. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/mcp_utils.py +0 -0
  42. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/agents.py +0 -0
  43. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/anthropic_types.py +0 -0
  44. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/input_types.py +0 -0
  45. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/mcp.py +0 -0
  46. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/prompt_requests.py +0 -0
  47. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/prompts.py +0 -0
  48. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/session.py +0 -0
  49. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/system_messages.py +0 -0
  50. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/thinking.py +0 -0
  51. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/usage.py +0 -0
  52. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/py.typed +0 -0
  53. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/session.py +0 -0
  54. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/storage/ARCHITECTURE.md +0 -0
  55. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/storage/__init__.py +0 -0
  56. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/storage/helpers.py +0 -0
  57. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/usage.py +0 -0
  58. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/__init__.py +0 -0
  59. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/conftest.py +0 -0
  60. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/__init__.py +0 -0
  61. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_dynamic_control.py +0 -0
  62. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_hook_events.py +0 -0
  63. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_hooks.py +0 -0
  64. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_mcp_resources.py +0 -0
  65. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_mcp_tools.py +0 -0
  66. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_sdk_mcp_resources.py +0 -0
  67. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_sdk_mcp_tools.py +0 -0
  68. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_slash_commands.py +0 -0
  69. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_stderr_callback.py +0 -0
  70. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_storage_parsing.py +0 -0
  71. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_structured_output.py +0 -0
  72. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_subagent_invocation.py +0 -0
  73. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_tool_permissions.py +0 -0
  74. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/mcp_server.py +0 -0
  75. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_changelog.py +0 -0
  76. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_client.py +0 -0
  77. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_errors.py +0 -0
  78. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_image.png +0 -0
  79. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_integration.py +0 -0
  80. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_message_parser.py +0 -0
  81. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_sdk_mcp_integration.py +0 -0
  82. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_subprocess_buffering.py +0 -0
  83. {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_transport.py +0 -0
@@ -0,0 +1,532 @@
1
+ Metadata-Version: 2.4
2
+ Name: clawd-code-sdk
3
+ Version: 1.0.28
4
+ Summary: Python SDK for Claude Code
5
+ Project-URL: Documentation, https://github.com/phil65/claude-agent-sdk-python
6
+ Project-URL: Homepage, https://github.com/phil65/claude-agent-sdk-python
7
+ Project-URL: Issues, https://github.com/phil65/claude-agent-sdk-python/issues
8
+ Author-email: phil65 <philipptemminghoff@gmail.com>
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: ai,anthropic,claude,sdk
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Programming Language :: Python :: 3.14
18
+ Classifier: Typing :: Typed
19
+ Requires-Python: >=3.13
20
+ Requires-Dist: anthropic>=0.77.0
21
+ Requires-Dist: anyenv>=2.0.15
22
+ Requires-Dist: anyio>=4.0.0
23
+ Requires-Dist: logfire>=4.31.0
24
+ Requires-Dist: mcp>=0.1.0
25
+ Requires-Dist: python-dotenv>=1.2.1
26
+ Provides-Extra: dev
27
+ Requires-Dist: anyio[trio]>=4.0.0; extra == 'dev'
28
+ Requires-Dist: mypy>=1.0.0; extra == 'dev'
29
+ Requires-Dist: pytest-asyncio>=0.20.0; extra == 'dev'
30
+ Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
31
+ Requires-Dist: pytest-timeout>=2.4.0; extra == 'dev'
32
+ Requires-Dist: pytest>=7.0.0; extra == 'dev'
33
+ Requires-Dist: ruff>=0.1.0; extra == 'dev'
34
+ Description-Content-Type: text/markdown
35
+
36
+ # Claude Agent SDK for Python
37
+
38
+ An improved fork of the official [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/python) with stronger type safety and additional features.
39
+ (API still quite similar to the official one)
40
+
41
+ ## Installation
42
+
43
+ ```bash
44
+ uv add clawd-code-sdk
45
+ ```
46
+
47
+ **Prerequisites:**
48
+
49
+ - Python 3.13+
50
+
51
+ ## Quick Start
52
+
53
+ ```python
54
+ import anyio
55
+ from clawd_code_sdk import ClaudeSDKClient
56
+
57
+ async def main():
58
+ async for message in ClaudeSDKClient.one_shot("What is 2 + 2?"):
59
+ print(message)
60
+
61
+ anyio.run(main)
62
+ ```
63
+
64
+ ## Basic Usage
65
+
66
+ ### One-shot queries
67
+
68
+ `ClaudeSDKClient.one_shot()` is the simplest way to query Claude Code.
69
+ It handles connection lifecycle automatically and yields response messages:
70
+
71
+ ```python
72
+ from clawd_code_sdk import ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock
73
+
74
+ # Simple query
75
+ async for message in ClaudeSDKClient.one_shot("Hello Claude"):
76
+ if isinstance(message, AssistantMessage):
77
+ for block in message.content:
78
+ if isinstance(block, TextBlock):
79
+ print(block.text)
80
+
81
+ # With options
82
+ options = ClaudeAgentOptions(
83
+ system_prompt="You are a helpful assistant",
84
+ max_turns=1,
85
+ )
86
+
87
+ async for message in ClaudeSDKClient.one_shot("Tell me a joke", options=options):
88
+ print(message)
89
+ ```
90
+
91
+ ### Interactive sessions
92
+
93
+ `ClaudeSDKClient` supports bidirectional, interactive conversations with Claude
94
+ Code. Unlike `one_shot()`, it additionally enables **custom tools**, **hooks**,
95
+ and multi-turn conversations within the same session.
96
+
97
+ ```python
98
+ from clawd_code_sdk import ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock
99
+
100
+ options = ClaudeAgentOptions(max_turns=3)
101
+
102
+ async with ClaudeSDKClient(options=options) as client:
103
+ # First turn
104
+ await client.query("What is 2 + 2?")
105
+ async for message in client.receive_response():
106
+ if isinstance(message, AssistantMessage):
107
+ for block in message.content:
108
+ if isinstance(block, TextBlock):
109
+ print(block.text)
110
+
111
+ # Follow-up in the same session
112
+ await client.query("Now multiply that by 3")
113
+ async for message in client.receive_response():
114
+ print(message)
115
+ ```
116
+
117
+ ## Message Sequence
118
+
119
+ When you call `client.query()` and iterate `client.receive_response()`,
120
+ messages arrive in this order:
121
+
122
+ ```
123
+ SessionStateChangedMessage state=running # session starts processing
124
+ InitSystemMessage subtype=init # session metadata (tools, model, cwd)
125
+ StreamEvent # raw Anthropic SSE events (deltas)
126
+ StreamEvent # ...
127
+ AssistantMessage # complete assistant turn (text, thinking, tool use)
128
+ StreamEvent # more streaming if multi-turn
129
+ AssistantMessage # another complete turn
130
+ ResultSuccessMessage subtype=success # final result with usage/cost
131
+ SessionStateChangedMessage state=idle # session fully done — iterator stops here
132
+ ```
133
+
134
+ Key points:
135
+
136
+ - **`receive_response()`** automatically terminates when the session
137
+ transitions to `idle` — the authoritative signal that the CLI has fully
138
+ finished (held-back results flushed, background agents exited).
139
+ - **`StreamEvent`** wraps raw Anthropic streaming events (`message_start`,
140
+ `content_block_delta`, etc.). Useful for real-time UI updates.
141
+ - **`AssistantMessage`** contains complete content blocks (`TextBlock`,
142
+ `ThinkingBlock`, `ToolUseBlock`) — no need to reassemble from deltas.
143
+ - **Hook messages** (`HookStartedSystemMessage`, `HookResponseSystemMessage`)
144
+ may appear at any point if hooks are configured.
145
+ - **`ResultSuccessMessage`** / **`ResultErrorMessage`** carry token usage
146
+ and cost information.
147
+
148
+ ## Configuration
149
+
150
+ ### Tools
151
+
152
+ ```python
153
+ options = ClaudeAgentOptions(
154
+ tools=["Read", "Write", "Bash"], # tools available to the agent
155
+ allowed_tools=["Read", "Write", "Bash"], # auto-approved (no permission prompt)
156
+ disallowed_tools=["WebFetch"], # completely removed from context
157
+ permission_mode="acceptEdits", # auto-accept file edits
158
+ )
159
+ ```
160
+
161
+ ### Working Directory
162
+
163
+ ```python
164
+ from pathlib import Path
165
+
166
+ options = ClaudeAgentOptions(
167
+ cwd="/path/to/project", # or Path("/path/to/project")
168
+ add_dirs=["/other/project"], # additional working directories
169
+ )
170
+ ```
171
+
172
+ ### Model and Thinking
173
+
174
+ ```python
175
+ from clawd_code_sdk import ClaudeAgentOptions, ThinkingConfigEnabled
176
+
177
+ options = ClaudeAgentOptions(
178
+ model="sonnet",
179
+ fallback_model="haiku",
180
+ thinking=ThinkingConfigEnabled(budget_tokens=10_000),
181
+ effort="high",
182
+ )
183
+ ```
184
+
185
+ ### Session Management
186
+
187
+ ```python
188
+ from clawd_code_sdk import ClaudeAgentOptions, NewSession, ResumeSession, ContinueLatest
189
+
190
+ # Fresh session (default)
191
+ options = ClaudeAgentOptions(session=NewSession())
192
+
193
+ # Resume by ID
194
+ options = ClaudeAgentOptions(session=ResumeSession(session_id="abc-123"))
195
+
196
+ # Or shorthand
197
+ options = ClaudeAgentOptions(session="abc-123")
198
+
199
+ # Continue most recent
200
+ options = ClaudeAgentOptions(session=ContinueLatest())
201
+ ```
202
+
203
+ ### Structured Output
204
+
205
+ ```python
206
+ from pydantic import BaseModel
207
+
208
+ class Joke(BaseModel):
209
+ setup: str
210
+ punchline: str
211
+
212
+ options = ClaudeAgentOptions(
213
+ output_schema=Joke, # accepts Pydantic models, dataclasses, TypedDicts, or raw dicts
214
+ )
215
+ ```
216
+
217
+ ## MCP Servers
218
+
219
+ ### In-Process SDK Servers
220
+
221
+ Define tools as Python functions that run in-process — no subprocess management
222
+ or IPC overhead:
223
+
224
+ ```python
225
+ from clawd_code_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions, ClaudeSDKClient
226
+
227
+ @tool("greet", "Greet a user", {"name": str})
228
+ async def greet_user(args):
229
+ return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}
230
+
231
+ server = create_sdk_mcp_server(
232
+ name="my-tools",
233
+ version="1.0.0",
234
+ tools=[greet_user],
235
+ )
236
+
237
+ options = ClaudeAgentOptions(
238
+ mcp_servers={"tools": server},
239
+ allowed_tools=["mcp__tools__greet"],
240
+ )
241
+
242
+ async with ClaudeSDKClient(options=options) as client:
243
+ await client.query("Greet Alice")
244
+ async for msg in client.receive_response():
245
+ print(msg)
246
+ ```
247
+
248
+ ### External Servers
249
+
250
+ ```python
251
+ from clawd_code_sdk import McpStdioServerConfig, McpHttpServerConfig
252
+
253
+ options = ClaudeAgentOptions(
254
+ mcp_servers={
255
+ # Subprocess (stdio)
256
+ "git": McpStdioServerConfig(command="uvx", args=["mcp-server-git"]),
257
+ # HTTP
258
+ "remote": McpHttpServerConfig(url="https://mcp.example.com/sse"),
259
+ }
260
+ )
261
+ ```
262
+
263
+ ### Mixed Servers
264
+
265
+ SDK and external servers can be used together:
266
+
267
+ ```python
268
+ options = ClaudeAgentOptions(
269
+ mcp_servers={
270
+ "internal": sdk_server, # in-process
271
+ "git": McpStdioServerConfig(command="uvx", args=["mcp-server-git"]), # subprocess
272
+ }
273
+ )
274
+ ```
275
+
276
+ ## Hooks
277
+
278
+ Hooks are Python callbacks that the Claude Code CLI invokes at specific points
279
+ of the agent loop. They enable deterministic processing and automated feedback.
280
+
281
+ Each hook event has strongly-typed input/output types:
282
+
283
+ ```python
284
+ from clawd_code_sdk import (
285
+ ClaudeAgentOptions,
286
+ ClaudeSDKClient,
287
+ HookMatcher,
288
+ PreToolUseHookInput,
289
+ HookContext,
290
+ )
291
+
292
+ async def check_bash_command(
293
+ input_data: PreToolUseHookInput,
294
+ tool_use_id: str | None,
295
+ context: HookContext,
296
+ ):
297
+ tool_input = input_data["tool_input"]
298
+ command = tool_input.get("command", "")
299
+ if "rm -rf" in command:
300
+ return {
301
+ "hookSpecificOutput": {
302
+ "hookEventName": "PreToolUse",
303
+ "permissionDecision": "deny",
304
+ "permissionDecisionReason": "Dangerous command blocked",
305
+ }
306
+ }
307
+ return {}
308
+
309
+ options = ClaudeAgentOptions(
310
+ allowed_tools=["Bash"],
311
+ hooks={
312
+ "PreToolUse": [
313
+ HookMatcher(matcher="Bash", hooks=[check_bash_command]),
314
+ ],
315
+ },
316
+ )
317
+
318
+ async with ClaudeSDKClient(options=options) as client:
319
+ await client.query("Run echo hello")
320
+ async for msg in client.receive_response():
321
+ print(msg)
322
+ ```
323
+
324
+ ### Available Hook Events
325
+
326
+ | Event | When it fires |
327
+ |-------|---------------|
328
+ | `PreToolUse` | Before a tool executes (can deny/modify) |
329
+ | `PostToolUse` | After a tool succeeds |
330
+ | `PostToolUseFailure` | After a tool fails |
331
+ | `UserPromptSubmit` | When a user prompt is submitted |
332
+ | `Stop` / `StopFailure` | When the agent stops or fails to stop |
333
+ | `SubagentStart` / `SubagentStop` | Subagent lifecycle |
334
+ | `SessionStart` / `SessionEnd` | Session lifecycle |
335
+ | `Notification` | Agent notifications |
336
+ | `PermissionRequest` / `PermissionDenied` | Permission events |
337
+ | `PreCompact` / `PostCompact` | Context compaction |
338
+ | `Elicitation` / `ElicitationResult` | MCP elicitation |
339
+ | `TaskCreated` / `TaskCompleted` | Task lifecycle |
340
+ | `FileChanged` / `CwdChanged` | Filesystem events |
341
+
342
+ See the [Claude Code Hooks Reference](https://docs.anthropic.com/en/docs/claude-code/hooks)
343
+ for full documentation.
344
+
345
+ ## Multimodal Prompts
346
+
347
+ Send images, PDFs, and text together using typed prompt classes:
348
+
349
+ ```python
350
+ from clawd_code_sdk import (
351
+ ClaudeSDKClient,
352
+ UserImageURLPrompt,
353
+ UserDocumentPrompt,
354
+ UserPlainTextDocumentPrompt,
355
+ )
356
+
357
+ async with ClaudeSDKClient() as client:
358
+ await client.query(
359
+ UserImageURLPrompt(url="https://example.com/chart.png"),
360
+ "What does this chart show?",
361
+ )
362
+ async for msg in client.receive_response():
363
+ print(msg)
364
+ ```
365
+
366
+ ## Subagents
367
+
368
+ Define subagents with their own prompts, tools, and MCP servers:
369
+
370
+ ```python
371
+ from clawd_code_sdk import ClaudeAgentOptions, ClaudeSDKClient, AgentDefinition, McpStdioServerConfig
372
+
373
+ options = ClaudeAgentOptions(
374
+ agents={
375
+ "researcher": AgentDefinition(
376
+ description="A research agent with web access",
377
+ prompt="You are a research assistant.",
378
+ tools=["WebFetch", "Read"],
379
+ ),
380
+ "git-agent": AgentDefinition(
381
+ description="An agent with git tools",
382
+ prompt="You are a git helper.",
383
+ mcp_servers={"git": McpStdioServerConfig(command="uvx", args=["mcp-server-git"])},
384
+ ),
385
+ },
386
+ max_turns=10,
387
+ )
388
+ ```
389
+
390
+ ## Types
391
+
392
+ ### Message Types
393
+
394
+ | Type | Description |
395
+ |------|-------------|
396
+ | `AssistantMessage` | Claude's response (text, thinking, tool use) |
397
+ | `UserMessage` | Echoed user messages |
398
+ | `StreamEvent` | Raw Anthropic SSE streaming events |
399
+ | `InitSystemMessage` | Session metadata (tools, model, cwd) |
400
+ | `ResultSuccessMessage` | Successful completion with usage |
401
+ | `ResultErrorMessage` | Error completion |
402
+ | `SessionStateChangedMessage` | Session state transitions |
403
+ | `HookStartedSystemMessage` | Hook execution started |
404
+ | `HookResponseSystemMessage` | Hook execution completed |
405
+
406
+ ### Content Block Types
407
+
408
+ | Type | Appears in |
409
+ |------|------------|
410
+ | `TextBlock` | Assistant and user messages |
411
+ | `ThinkingBlock` | Assistant messages (when thinking enabled) |
412
+ | `ToolUseBlock` | Assistant messages |
413
+ | `ToolResultBlock` | User messages |
414
+ | `ImageBlock` | User messages |
415
+
416
+ The SDK provides role-specific narrowed types:
417
+
418
+ - `AssistantContentBlock` = `TextBlock | ThinkingBlock | ToolUseBlock`
419
+ - `UserContentBlock` = `TextBlock | ToolResultBlock | ImageBlock`
420
+ - `ContentBlock` = full 5-type union (for storage/serialization)
421
+
422
+ See [src/clawd_code_sdk/models/content_blocks.py](src/clawd_code_sdk/models/content_blocks.py)
423
+ for complete type definitions.
424
+
425
+ ## Error Handling
426
+
427
+ ```python
428
+ from clawd_code_sdk import (
429
+ ClaudeSDKError, # Base error
430
+ CLINotFoundError, # Claude Code not installed
431
+ CLIConnectionError, # Connection issues
432
+ ProcessError, # Process failed
433
+ CLIJSONDecodeError, # JSON parsing issues
434
+ BillingError, # Insufficient credits
435
+ RateLimitError, # Rate limited
436
+ AuthenticationError, # Invalid API key
437
+ )
438
+
439
+ try:
440
+ async for message in ClaudeSDKClient.one_shot("Hello"):
441
+ pass
442
+ except CLINotFoundError:
443
+ print("Please install Claude Code")
444
+ except ProcessError as e:
445
+ print(f"Process failed with exit code: {e.exit_code}")
446
+ ```
447
+
448
+ See [src/clawd_code_sdk/\_errors.py](src/clawd_code_sdk/_errors.py) for all error types.
449
+
450
+ ## Available Tools
451
+
452
+ See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/settings#tools-available-to-claude) for a complete list of available tools.
453
+
454
+ ## Migrating from Claude Code SDK
455
+
456
+ If you're upgrading from the Claude Code SDK (versions < 0.1.0), please see the [CHANGELOG.md](CHANGELOG.md#010) for details on breaking changes and new features, including:
457
+
458
+ - `ClaudeCodeOptions` → `ClaudeAgentOptions` rename
459
+ - Merged system prompt configuration
460
+ - Settings isolation and explicit control
461
+ - New programmatic subagents and session forking features
462
+
463
+ ## Development
464
+
465
+ If you're contributing to this project, run the initial setup script to install git hooks:
466
+
467
+ ```bash
468
+ ./scripts/initial-setup.sh
469
+ ```
470
+
471
+ This installs a pre-push hook that runs lint checks before pushing, matching the CI workflow. To skip the hook temporarily, use `git push --no-verify`.
472
+
473
+ ### Building Wheels Locally
474
+
475
+ To build wheels with the bundled Claude Code CLI:
476
+
477
+ ```bash
478
+ # Install build dependencies
479
+ pip install build twine
480
+
481
+ # Build wheel with bundled CLI
482
+ python scripts/build_wheel.py
483
+
484
+ # Build with specific version
485
+ python scripts/build_wheel.py --version 0.1.4
486
+
487
+ # Build with specific CLI version
488
+ python scripts/build_wheel.py --cli-version 2.0.0
489
+
490
+ # Clean bundled CLI after building
491
+ python scripts/build_wheel.py --clean
492
+
493
+ # Skip CLI download (use existing)
494
+ python scripts/build_wheel.py --skip-download
495
+ ```
496
+
497
+ The build script:
498
+
499
+ 1. Downloads Claude Code CLI for your platform
500
+ 2. Bundles it in the wheel
501
+ 3. Builds both wheel and source distribution
502
+ 4. Checks the package with twine
503
+
504
+ See `python scripts/build_wheel.py --help` for all options.
505
+
506
+ ### Release Workflow
507
+
508
+ The package is published to PyPI via the GitHub Actions workflow in `.github/workflows/publish.yml`. To create a new release:
509
+
510
+ 1. **Trigger the workflow** manually from the Actions tab with two inputs:
511
+ - `version`: The package version to publish (e.g., `0.1.5`)
512
+ - `claude_code_version`: The Claude Code CLI version to bundle (e.g., `2.0.0` or `latest`)
513
+
514
+ 2. **The workflow will**:
515
+ - Build platform-specific wheels for macOS, Linux, and Windows
516
+ - Bundle the specified Claude Code CLI version in each wheel
517
+ - Build a source distribution
518
+ - Publish all artifacts to PyPI
519
+ - Create a release branch with version updates
520
+ - Open a PR to main with:
521
+ - Updated `pyproject.toml` version
522
+ - Updated `src/clawd_code_sdk/_version.py`
523
+ - Updated `src/clawd_code_sdk/_cli_version.py` with bundled CLI version
524
+ - Auto-generated `CHANGELOG.md` entry
525
+
526
+ 3. **Review and merge** the release PR to update main with the new version information
527
+
528
+ The workflow tracks both the package version and the bundled CLI version separately, allowing you to release a new package version with an updated CLI without code changes.
529
+
530
+ ## License and terms
531
+
532
+ Use of this SDK is governed by Anthropic's [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms), including when you use it to power products and services that you make available to your own customers and end users, except to the extent a specific component or dependency is covered by a different license as indicated in that component's LICENSE file.