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.
- clawd_code_sdk-1.0.28/PKG-INFO +532 -0
- clawd_code_sdk-1.0.28/README.md +497 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/pyproject.toml +1 -1
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/_internal/query.py +21 -41
- clawd_code_sdk-1.0.28/src/clawd_code_sdk/anthropic_stream.py +205 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/client.py +12 -27
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/__init__.py +29 -3
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/base.py +14 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/content_blocks.py +21 -4
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/context_usage.py +1 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/control.py +58 -11
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/hooks.py +2 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/messages.py +11 -8
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/options.py +3 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/output_types.py +22 -1
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/permissions.py +19 -1
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/server_info.py +4 -1
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/settings.py +13 -1
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/storage/models.py +6 -5
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/storage/replay.py +6 -8
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_agents_and_settings.py +6 -9
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_include_partial_messages.py +9 -8
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/mock_claude_server.py +11 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_session.py +25 -9
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_streaming_client.py +14 -5
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_tool_callbacks.py +4 -1
- clawd_code_sdk-1.0.26/PKG-INFO +0 -391
- clawd_code_sdk-1.0.26/README.md +0 -356
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/.gitignore +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/LICENSE +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/__init__.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/_bundled/.gitignore +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/_errors.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/_internal/__init__.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/_internal/transport/__init__.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/_internal/transport/subprocess_cli.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/_internal/transport/subprocess_utils.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/_version.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/instrumentation.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/list_sessions.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/mcp_utils.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/agents.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/anthropic_types.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/input_types.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/mcp.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/prompt_requests.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/prompts.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/session.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/system_messages.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/thinking.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/models/usage.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/py.typed +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/session.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/storage/ARCHITECTURE.md +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/storage/__init__.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/storage/helpers.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/src/clawd_code_sdk/usage.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/__init__.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/conftest.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/__init__.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_dynamic_control.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_hook_events.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_hooks.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_mcp_resources.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_mcp_tools.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_sdk_mcp_resources.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_sdk_mcp_tools.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_slash_commands.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_stderr_callback.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_storage_parsing.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_structured_output.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_subagent_invocation.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/e2e/test_tool_permissions.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/mcp_server.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_changelog.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_client.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_errors.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_image.png +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_integration.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_message_parser.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_sdk_mcp_integration.py +0 -0
- {clawd_code_sdk-1.0.26 → clawd_code_sdk-1.0.28}/tests/test_subprocess_buffering.py +0 -0
- {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.
|