From bf528a1221c1dca4cce20d18ee9b9823290cd68e Mon Sep 17 00:00:00 2001 From: Ashwin Bhat Date: Wed, 19 Nov 2025 09:49:35 -0800 Subject: [PATCH 01/55] refactor: source CLI version from code in publish workflow (#350) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove the claude_code_version workflow input and instead read the CLI version directly from src/claude_agent_sdk/_cli_version.py. This allows the version to be managed separately and updated by automation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude --- .github/workflows/publish.yml | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 057a8f5..1d8d79d 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -7,11 +7,6 @@ on: description: 'Package version to publish (e.g., 0.1.4)' required: true type: string - claude_code_version: - description: 'Claude Code CLI version to bundle (e.g., 2.0.0 or latest)' - required: false - type: string - default: 'latest' jobs: test: runs-on: ubuntu-latest @@ -91,7 +86,6 @@ jobs: run: | python scripts/build_wheel.py \ --version "${{ github.event.inputs.version }}" \ - --cli-version "${{ github.event.inputs.claude_code_version }}" \ --skip-sdist \ --clean shell: bash @@ -132,9 +126,12 @@ jobs: run: | python scripts/update_version.py "${{ env.VERSION }}" - - name: Update CLI version + - name: Read CLI version from code + id: cli_version run: | - python scripts/update_cli_version.py "${{ github.event.inputs.claude_code_version }}" + CLI_VERSION=$(python -c "import re; print(re.search(r'__cli_version__ = \"([^\"]+)\"', open('src/claude_agent_sdk/_cli_version.py').read()).group(1))") + echo "cli_version=$CLI_VERSION" >> $GITHUB_OUTPUT + echo "Bundled CLI version: $CLI_VERSION" - name: Download all wheel artifacts uses: actions/download-artifact@v4 @@ -181,8 +178,8 @@ jobs: git checkout -b "$BRANCH_NAME" # Commit version changes - git add pyproject.toml src/claude_agent_sdk/_version.py src/claude_agent_sdk/_cli_version.py - git commit -m "chore: bump version to ${{ env.VERSION }} with CLI ${{ github.event.inputs.claude_code_version }}" + git add pyproject.toml src/claude_agent_sdk/_version.py + git commit -m "chore: release v${{ env.VERSION }}" - name: Update changelog with Claude continue-on-error: true @@ -207,12 +204,11 @@ jobs: ## Changes - Updated version in \`pyproject.toml\` to ${{ env.VERSION }} - Updated version in \`src/claude_agent_sdk/_version.py\` to ${{ env.VERSION }} - - Updated bundled CLI version in \`src/claude_agent_sdk/_cli_version.py\` to ${{ github.event.inputs.claude_code_version }} - Updated \`CHANGELOG.md\` with release notes ## Release Information - Published to PyPI: https://pypi.org/project/claude-agent-sdk/${{ env.VERSION }}/ - - Bundled CLI version: ${{ github.event.inputs.claude_code_version }} + - Bundled CLI version: ${{ steps.cli_version.outputs.cli_version }} - Install with: \`pip install claude-agent-sdk==${{ env.VERSION }}\` 🤖 Generated by GitHub Actions" From 84edd730417ac6de72e3ce408fa81952ebc7d14c Mon Sep 17 00:00:00 2001 From: Dickson Tsai Date: Thu, 20 Nov 2025 06:50:33 +0900 Subject: [PATCH 02/55] feat: add timeout parameter to HookMatcher (#351) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary - Adds optional `timeout` field to `HookMatcher` dataclass in `types.py` that allows users to specify a custom timeout (in seconds) for hooks - Propagates the timeout value through: - `client.py` and `_internal/client.py`: `_convert_hooks_to_internal()` method - `_internal/query.py`: hook config sent to CLI ## Test plan - [x] Verify hooks work without timeout specified (default behavior) - [x] Verify custom timeout is passed to CLI when specified in HookMatcher 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude --- src/claude_agent_sdk/_internal/client.py | 4 +++- src/claude_agent_sdk/_internal/query.py | 13 +++++++------ src/claude_agent_sdk/client.py | 4 +++- src/claude_agent_sdk/types.py | 3 +++ 4 files changed, 16 insertions(+), 8 deletions(-) diff --git a/src/claude_agent_sdk/_internal/client.py b/src/claude_agent_sdk/_internal/client.py index 6dbc877..5246627 100644 --- a/src/claude_agent_sdk/_internal/client.py +++ b/src/claude_agent_sdk/_internal/client.py @@ -31,10 +31,12 @@ class InternalClient: internal_hooks[event] = [] for matcher in matchers: # Convert HookMatcher to internal dict format - internal_matcher = { + internal_matcher: dict[str, Any] = { "matcher": matcher.matcher if hasattr(matcher, "matcher") else None, "hooks": matcher.hooks if hasattr(matcher, "hooks") else [], } + if hasattr(matcher, "timeout") and matcher.timeout is not None: + internal_matcher["timeout"] = matcher.timeout internal_hooks[event].append(internal_matcher) return internal_hooks diff --git a/src/claude_agent_sdk/_internal/query.py b/src/claude_agent_sdk/_internal/query.py index 7646010..b76bc04 100644 --- a/src/claude_agent_sdk/_internal/query.py +++ b/src/claude_agent_sdk/_internal/query.py @@ -126,12 +126,13 @@ class Query: self.next_callback_id += 1 self.hook_callbacks[callback_id] = callback callback_ids.append(callback_id) - hooks_config[event].append( - { - "matcher": matcher.get("matcher"), - "hookCallbackIds": callback_ids, - } - ) + hook_matcher_config: dict[str, Any] = { + "matcher": matcher.get("matcher"), + "hookCallbackIds": callback_ids, + } + if matcher.get("timeout") is not None: + hook_matcher_config["timeout"] = matcher.get("timeout") + hooks_config[event].append(hook_matcher_config) # Send initialize request request = { diff --git a/src/claude_agent_sdk/client.py b/src/claude_agent_sdk/client.py index f95b50b..58b851d 100644 --- a/src/claude_agent_sdk/client.py +++ b/src/claude_agent_sdk/client.py @@ -75,10 +75,12 @@ class ClaudeSDKClient: internal_hooks[event] = [] for matcher in matchers: # Convert HookMatcher to internal dict format - internal_matcher = { + internal_matcher: dict[str, Any] = { "matcher": matcher.matcher if hasattr(matcher, "matcher") else None, "hooks": matcher.hooks if hasattr(matcher, "hooks") else [], } + if hasattr(matcher, "timeout") and matcher.timeout is not None: + internal_matcher["timeout"] = matcher.timeout internal_hooks[event].append(internal_matcher) return internal_hooks diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py index 406c204..689d8bb 100644 --- a/src/claude_agent_sdk/types.py +++ b/src/claude_agent_sdk/types.py @@ -366,6 +366,9 @@ class HookMatcher: # A list of Python functions with function signature HookCallback hooks: list[HookCallback] = field(default_factory=list) + # Timeout in seconds for all hooks in this matcher (default: 60) + timeout: int | None = None + # MCP Server config class McpStdioServerConfig(TypedDict): From 179818235a48d6ea12d99cc67b85c54be3006042 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Wed, 19 Nov 2025 22:56:34 +0000 Subject: [PATCH 03/55] chore: bump bundled CLI version to 2.0.46 --- src/claude_agent_sdk/_cli_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py index 7934dd0..a582a2e 100644 --- a/src/claude_agent_sdk/_cli_version.py +++ b/src/claude_agent_sdk/_cli_version.py @@ -1,3 +1,3 @@ """Bundled Claude Code CLI version.""" -__cli_version__ = "2.0.45" +__cli_version__ = "2.0.46" From ab83878f5a11c67c06df6b8d2165afb0f419528a Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Wed, 19 Nov 2025 23:12:47 +0000 Subject: [PATCH 04/55] chore: bump bundled CLI version to 2.0.47 --- src/claude_agent_sdk/_cli_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py index a582a2e..8bf2192 100644 --- a/src/claude_agent_sdk/_cli_version.py +++ b/src/claude_agent_sdk/_cli_version.py @@ -1,3 +1,3 @@ """Bundled Claude Code CLI version.""" -__cli_version__ = "2.0.46" +__cli_version__ = "2.0.47" From b0fb5b082a35a613c753e4f8261e763d356da858 Mon Sep 17 00:00:00 2001 From: shawnm-anthropic Date: Wed, 19 Nov 2025 19:23:10 -0500 Subject: [PATCH 05/55] Add AssistantMessageError type (#352) This brings Python to parity with https://github.com/anthropics/claude-cli-internal/pull/10358. --- src/claude_agent_sdk/types.py | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py index 689d8bb..81e19ac 100644 --- a/src/claude_agent_sdk/types.py +++ b/src/claude_agent_sdk/types.py @@ -457,6 +457,16 @@ ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock # Message types +AssistantMessageError = Literal[ + "authentication_failed", + "billing_error", + "rate_limit", + "invalid_request", + "server_error", + "unknown", +] + + @dataclass class UserMessage: """User message.""" @@ -472,6 +482,7 @@ class AssistantMessage: content: list[ContentBlock] model: str parent_tool_use_id: str | None = None + error: AssistantMessageError | None = None @dataclass From 36c75374ec6829af7c97230b2aadf506f7975a63 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Fri, 21 Nov 2025 01:31:38 +0000 Subject: [PATCH 06/55] chore: bump bundled CLI version to 2.0.49 --- src/claude_agent_sdk/_cli_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py index 8bf2192..236bc2b 100644 --- a/src/claude_agent_sdk/_cli_version.py +++ b/src/claude_agent_sdk/_cli_version.py @@ -1,3 +1,3 @@ """Bundled Claude Code CLI version.""" -__cli_version__ = "2.0.47" +__cli_version__ = "2.0.49" From f446e3e42a3c1da0628d97727a20dc75c3f3b9df Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 21 Nov 2025 12:51:05 -0800 Subject: [PATCH 07/55] chore: release v0.1.9 (#353) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR updates the version to 0.1.9 after publishing to PyPI. ## Changes - Updated version in `pyproject.toml` to 0.1.9 - Updated version in `src/claude_agent_sdk/_version.py` to 0.1.9 - Updated `CHANGELOG.md` with release notes ## Release Information - Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.9/ - Bundled CLI version: 2.0.49 - Install with: `pip install claude-agent-sdk==0.1.9` 🤖 Generated by GitHub Actions --------- Co-authored-by: github-actions[bot] Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com> --- CHANGELOG.md | 6 ++++++ pyproject.toml | 2 +- src/claude_agent_sdk/_version.py | 2 +- 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7dec6a3..046e19e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +## 0.1.9 + +### Internal/Other Changes + +- Updated bundled Claude CLI to version 2.0.49 + ## 0.1.8 ### Features diff --git a/pyproject.toml b/pyproject.toml index da5aaa6..97825f6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "claude-agent-sdk" -version = "0.1.8" +version = "0.1.9" description = "Python SDK for Claude Code" readme = "README.md" requires-python = ">=3.10" diff --git a/src/claude_agent_sdk/_version.py b/src/claude_agent_sdk/_version.py index a0e39a9..16331ff 100644 --- a/src/claude_agent_sdk/_version.py +++ b/src/claude_agent_sdk/_version.py @@ -1,3 +1,3 @@ """Version information for claude-agent-sdk.""" -__version__ = "0.1.8" +__version__ = "0.1.9" From 41ceacd8076a86e6a4ada503ce5c87ddde97216a Mon Sep 17 00:00:00 2001 From: Michael Dworsky Date: Fri, 21 Nov 2025 16:46:22 -0500 Subject: [PATCH 08/55] Use CLAUDE_CODE_STREAM_CLOSE_TIMEOUT (if present) to override initialize() timeout (#354) --- src/claude_agent_sdk/_internal/query.py | 21 +++++++++++++++++---- src/claude_agent_sdk/client.py | 8 ++++++++ 2 files changed, 25 insertions(+), 4 deletions(-) diff --git a/src/claude_agent_sdk/_internal/query.py b/src/claude_agent_sdk/_internal/query.py index b76bc04..566e316 100644 --- a/src/claude_agent_sdk/_internal/query.py +++ b/src/claude_agent_sdk/_internal/query.py @@ -72,6 +72,7 @@ class Query: | None = None, hooks: dict[str, list[dict[str, Any]]] | None = None, sdk_mcp_servers: dict[str, "McpServer"] | None = None, + initialize_timeout: float = 60.0, ): """Initialize Query with transport and callbacks. @@ -81,7 +82,9 @@ class Query: can_use_tool: Optional callback for tool permission requests hooks: Optional hook configurations sdk_mcp_servers: Optional SDK MCP server instances + initialize_timeout: Timeout in seconds for the initialize request """ + self._initialize_timeout = initialize_timeout self.transport = transport self.is_streaming_mode = is_streaming_mode self.can_use_tool = can_use_tool @@ -140,7 +143,10 @@ class Query: "hooks": hooks_config if hooks_config else None, } - response = await self._send_control_request(request) + # Use longer timeout for initialize since MCP servers may take time to start + response = await self._send_control_request( + request, timeout=self._initialize_timeout + ) self._initialized = True self._initialization_result = response # Store for later access return response @@ -315,8 +321,15 @@ class Query: } await self.transport.write(json.dumps(error_response) + "\n") - async def _send_control_request(self, request: dict[str, Any]) -> dict[str, Any]: - """Send control request to CLI and wait for response.""" + async def _send_control_request( + self, request: dict[str, Any], timeout: float = 60.0 + ) -> dict[str, Any]: + """Send control request to CLI and wait for response. + + Args: + request: The control request to send + timeout: Timeout in seconds to wait for response (default 60s) + """ if not self.is_streaming_mode: raise Exception("Control requests require streaming mode") @@ -339,7 +352,7 @@ class Query: # Wait for response try: - with anyio.fail_after(60.0): + with anyio.fail_after(timeout): await event.wait() result = self.pending_control_results.pop(request_id) diff --git a/src/claude_agent_sdk/client.py b/src/claude_agent_sdk/client.py index 58b851d..742d7d6 100644 --- a/src/claude_agent_sdk/client.py +++ b/src/claude_agent_sdk/client.py @@ -140,6 +140,13 @@ class ClaudeSDKClient: if isinstance(config, dict) and config.get("type") == "sdk": sdk_mcp_servers[name] = config["instance"] # type: ignore[typeddict-item] + # Calculate initialize timeout from CLAUDE_CODE_STREAM_CLOSE_TIMEOUT env var if set + # CLAUDE_CODE_STREAM_CLOSE_TIMEOUT is in milliseconds, convert to seconds + initialize_timeout_ms = int( + os.environ.get("CLAUDE_CODE_STREAM_CLOSE_TIMEOUT", "60000") + ) + initialize_timeout = max(initialize_timeout_ms / 1000.0, 60.0) + # Create Query to handle control protocol self._query = Query( transport=self._transport, @@ -149,6 +156,7 @@ class ClaudeSDKClient: if self.options.hooks else None, sdk_mcp_servers=sdk_mcp_servers, + initialize_timeout=initialize_timeout, ) # Start reading messages and initialize From 23183a269871617ecac2abd9ed62a5ed591616eb Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Fri, 21 Nov 2025 23:16:27 +0000 Subject: [PATCH 09/55] chore: bump bundled CLI version to 2.0.50 --- src/claude_agent_sdk/_cli_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py index 236bc2b..88e186c 100644 --- a/src/claude_agent_sdk/_cli_version.py +++ b/src/claude_agent_sdk/_cli_version.py @@ -1,3 +1,3 @@ """Bundled Claude Code CLI version.""" -__cli_version__ = "2.0.49" +__cli_version__ = "2.0.50" From 7a5b413159495378100dd5612a5bf6daeaef2193 Mon Sep 17 00:00:00 2001 From: Harutaka Kawamura Date: Mon, 24 Nov 2025 08:22:12 +0900 Subject: [PATCH 10/55] Fix: Fix `HookMatcher.timeout` type to `float` (#357) According to https://www.schemastore.org/claude-code-settings.json, the `timeout` type is `number`, not `integer` Signed-off-by: harupy <17039389+harupy@users.noreply.github.com> --- src/claude_agent_sdk/types.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py index 81e19ac..4e1abba 100644 --- a/src/claude_agent_sdk/types.py +++ b/src/claude_agent_sdk/types.py @@ -367,7 +367,7 @@ class HookMatcher: hooks: list[HookCallback] = field(default_factory=list) # Timeout in seconds for all hooks in this matcher (default: 60) - timeout: int | None = None + timeout: float | None = None # MCP Server config From 493f49fad9595bbeece1ac5a00479bd25ca825f3 Mon Sep 17 00:00:00 2001 From: Noah Zweben Date: Sun, 23 Nov 2025 21:24:25 -0800 Subject: [PATCH 11/55] Added slack issue notifier for new opened issues (#356) Posts new issues to claude-agent-sdk-feedback. Can't use the default github slack bot as it's too noisy (all comments and issue updates such as comments, closing, etc...) --------- Co-authored-by: Ashwin Bhat --- .../workflows/slack-issue-notification.yml | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 .github/workflows/slack-issue-notification.yml diff --git a/.github/workflows/slack-issue-notification.yml b/.github/workflows/slack-issue-notification.yml new file mode 100644 index 0000000..675dd93 --- /dev/null +++ b/.github/workflows/slack-issue-notification.yml @@ -0,0 +1,36 @@ +name: Post new issues to Slack + +on: + issues: + types: [opened] + +jobs: + notify: + runs-on: ubuntu-latest + steps: + - name: Post to Slack + uses: slackapi/slack-github-action@91efab103c0de0a537f72a35f6b8cda0ee76bf0a # 2.1.1 + with: + method: chat.postMessage + token: ${{ secrets.SLACK_BOT_TOKEN }} + payload: | + { + "channel": "C09HY5E0K60", + "text": "New issue opened in ${{ github.repository }}", + "blocks": [ + { + "type": "section", + "text": { + "type": "mrkdwn", + "text": "*New Issue:* <${{ github.event.issue.html_url }}|#${{ github.event.issue.number }} ${{ github.event.issue.title }}>" + } + }, + { + "type": "section", + "text": { + "type": "mrkdwn", + "text": "*Author:* ${{ github.event.issue.user.login }}" + } + } + ] + } From 112f3aa95925f59ca7ff5781a6f55c233e6073be Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Mon, 24 Nov 2025 18:48:28 +0000 Subject: [PATCH 12/55] chore: bump bundled CLI version to 2.0.51 --- src/claude_agent_sdk/_cli_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py index 88e186c..2c1bfef 100644 --- a/src/claude_agent_sdk/_cli_version.py +++ b/src/claude_agent_sdk/_cli_version.py @@ -1,3 +1,3 @@ """Bundled Claude Code CLI version.""" -__cli_version__ = "2.0.50" +__cli_version__ = "2.0.51" From d15f26da9144be54d597b8ea0e3287af1974194d Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Mon, 24 Nov 2025 23:32:15 +0000 Subject: [PATCH 13/55] chore: bump bundled CLI version to 2.0.52 --- src/claude_agent_sdk/_cli_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py index 2c1bfef..d4a7749 100644 --- a/src/claude_agent_sdk/_cli_version.py +++ b/src/claude_agent_sdk/_cli_version.py @@ -1,3 +1,3 @@ """Bundled Claude Code CLI version.""" -__cli_version__ = "2.0.51" +__cli_version__ = "2.0.52" From be915896afb1a7f1b4ea218cdf3538b5fc9e7afc Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Tue, 25 Nov 2025 01:55:19 +0000 Subject: [PATCH 14/55] chore: bump bundled CLI version to 2.0.53 --- src/claude_agent_sdk/_cli_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py index d4a7749..42b4d48 100644 --- a/src/claude_agent_sdk/_cli_version.py +++ b/src/claude_agent_sdk/_cli_version.py @@ -1,3 +1,3 @@ """Bundled Claude Code CLI version.""" -__cli_version__ = "2.0.52" +__cli_version__ = "2.0.53" From e2f8d814ea1bbd44804cae329c0dd5a90f357df6 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 25 Nov 2025 12:58:54 -0500 Subject: [PATCH 15/55] chore: release v0.1.10 (#369) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR updates the version to 0.1.10 after publishing to PyPI. ## Changes - Updated version in `pyproject.toml` to 0.1.10 - Updated version in `src/claude_agent_sdk/_version.py` to 0.1.10 - Updated `CHANGELOG.md` with release notes ## Release Information - Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.10/ - Bundled CLI version: 2.0.53 - Install with: `pip install claude-agent-sdk==0.1.10` 🤖 Generated by GitHub Actions --------- Co-authored-by: github-actions[bot] Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com> --- CHANGELOG.md | 6 ++++++ pyproject.toml | 2 +- src/claude_agent_sdk/_version.py | 2 +- 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 046e19e..240d017 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +## 0.1.10 + +### Internal/Other Changes + +- Updated bundled Claude CLI to version 2.0.53 + ## 0.1.9 ### Internal/Other Changes diff --git a/pyproject.toml b/pyproject.toml index 97825f6..2abc2a4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "claude-agent-sdk" -version = "0.1.9" +version = "0.1.10" description = "Python SDK for Claude Code" readme = "README.md" requires-python = ">=3.10" diff --git a/src/claude_agent_sdk/_version.py b/src/claude_agent_sdk/_version.py index 16331ff..19a8d0f 100644 --- a/src/claude_agent_sdk/_version.py +++ b/src/claude_agent_sdk/_version.py @@ -1,3 +1,3 @@ """Version information for claude-agent-sdk.""" -__version__ = "0.1.9" +__version__ = "0.1.10" From d553184ef6d480031400bb47d78919c9ba4d911f Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Thu, 27 Nov 2025 00:01:24 +0000 Subject: [PATCH 16/55] chore: bump bundled CLI version to 2.0.55 --- src/claude_agent_sdk/_cli_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py index 42b4d48..1e1d4ba 100644 --- a/src/claude_agent_sdk/_cli_version.py +++ b/src/claude_agent_sdk/_cli_version.py @@ -1,3 +1,3 @@ """Bundled Claude Code CLI version.""" -__cli_version__ = "2.0.53" +__cli_version__ = "2.0.55" From f21f63e181a08d2100a62a4b8b58c9ff657d5b29 Mon Sep 17 00:00:00 2001 From: ollie-anthropic <159198875+ollie-anthropic@users.noreply.github.com> Date: Mon, 1 Dec 2025 01:44:59 -0800 Subject: [PATCH 17/55] Create sandbox adapter interface for Python SDK (#363) Adds programmatic sandbox configuration to the Python SDK, matching the TypeScript SDK's approach. Changes: - Add SandboxSettings, SandboxNetworkConfig, SandboxIgnoreViolations types - Add sandbox field to ClaudeAgentOptions - Merge sandbox into --settings CLI flag in SubprocessCLITransport - Export sandbox types from package __init__.py - Add comprehensive tests for sandbox settings **Important:** Filesystem and network restrictions are configured via permission rules (Read/Edit/WebFetch), not via these sandbox settings. The sandbox settings control sandbox behavior (enabled, auto-allow, excluded commands, etc.). Example usage: ```python from claude_agent_sdk import query, SandboxSettings result = query( prompt='Build and test the project', options=ClaudeAgentOptions( sandbox={ 'enabled': True, 'autoAllowBashIfSandboxed': True, 'excludedCommands': ['docker'], 'network': { 'allowLocalBinding': True, 'allowUnixSockets': ['/var/run/docker.sock'] } } ) ) ``` Co-authored-by: Claude --- src/claude_agent_sdk/__init__.py | 7 + .../_internal/transport/subprocess_cli.py | 60 ++++++- src/claude_agent_sdk/types.py | 81 ++++++++++ tests/test_transport.py | 147 ++++++++++++++++++ 4 files changed, 293 insertions(+), 2 deletions(-) diff --git a/src/claude_agent_sdk/__init__.py b/src/claude_agent_sdk/__init__.py index cde28be..8e710d5 100644 --- a/src/claude_agent_sdk/__init__.py +++ b/src/claude_agent_sdk/__init__.py @@ -39,6 +39,9 @@ from .types import ( PreCompactHookInput, PreToolUseHookInput, ResultMessage, + SandboxIgnoreViolations, + SandboxNetworkConfig, + SandboxSettings, SdkPluginConfig, SettingSource, StopHookInput, @@ -342,6 +345,10 @@ __all__ = [ "SettingSource", # Plugin support "SdkPluginConfig", + # Sandbox support + "SandboxSettings", + "SandboxNetworkConfig", + "SandboxIgnoreViolations", # MCP Server Support "create_sdk_mcp_server", "tool", diff --git a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py index 48e21de..73c1b29 100644 --- a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py +++ b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py @@ -114,6 +114,60 @@ class SubprocessCLITransport(Transport): return None + def _build_settings_value(self) -> str | None: + """Build settings value, merging sandbox settings if provided. + + Returns the settings value as either: + - A JSON string (if sandbox is provided or settings is JSON) + - A file path (if only settings path is provided without sandbox) + - None if neither settings nor sandbox is provided + """ + has_settings = self._options.settings is not None + has_sandbox = self._options.sandbox is not None + + if not has_settings and not has_sandbox: + return None + + # If only settings path and no sandbox, pass through as-is + if has_settings and not has_sandbox: + return self._options.settings + + # If we have sandbox settings, we need to merge into a JSON object + settings_obj: dict[str, Any] = {} + + if has_settings: + assert self._options.settings is not None + settings_str = self._options.settings.strip() + # Check if settings is a JSON string or a file path + if settings_str.startswith("{") and settings_str.endswith("}"): + # Parse JSON string + try: + settings_obj = json.loads(settings_str) + except json.JSONDecodeError: + # If parsing fails, treat as file path + logger.warning( + f"Failed to parse settings as JSON, treating as file path: {settings_str}" + ) + # Read the file + settings_path = Path(settings_str) + if settings_path.exists(): + with settings_path.open(encoding="utf-8") as f: + settings_obj = json.load(f) + else: + # It's a file path - read and parse + settings_path = Path(settings_str) + if settings_path.exists(): + with settings_path.open(encoding="utf-8") as f: + settings_obj = json.load(f) + else: + logger.warning(f"Settings file not found: {settings_path}") + + # Merge sandbox settings + if has_sandbox: + settings_obj["sandbox"] = self._options.sandbox + + return json.dumps(settings_obj) + def _build_command(self) -> list[str]: """Build CLI command with arguments.""" cmd = [self._cli_path, "--output-format", "stream-json", "--verbose"] @@ -163,8 +217,10 @@ class SubprocessCLITransport(Transport): if self._options.resume: cmd.extend(["--resume", self._options.resume]) - if self._options.settings: - cmd.extend(["--settings", self._options.settings]) + # Handle settings and sandbox: merge sandbox into settings if both are provided + settings_value = self._build_settings_value() + if settings_value: + cmd.extend(["--settings", settings_value]) if self._options.add_dirs: # Convert all paths to strings and add each directory diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py index 4e1abba..f37fd3c 100644 --- a/src/claude_agent_sdk/types.py +++ b/src/claude_agent_sdk/types.py @@ -419,6 +419,83 @@ class SdkPluginConfig(TypedDict): path: str +# Sandbox configuration types +class SandboxNetworkConfig(TypedDict, total=False): + """Network configuration for sandbox. + + Attributes: + allowUnixSockets: Unix socket paths accessible in sandbox (e.g., SSH agents). + allowAllUnixSockets: Allow all Unix sockets (less secure). + allowLocalBinding: Allow binding to localhost ports (macOS only). + httpProxyPort: HTTP proxy port if bringing your own proxy. + socksProxyPort: SOCKS5 proxy port if bringing your own proxy. + """ + + allowUnixSockets: list[str] + allowAllUnixSockets: bool + allowLocalBinding: bool + httpProxyPort: int + socksProxyPort: int + + +class SandboxIgnoreViolations(TypedDict, total=False): + """Violations to ignore in sandbox. + + Attributes: + file: File paths for which violations should be ignored. + network: Network hosts for which violations should be ignored. + """ + + file: list[str] + network: list[str] + + +class SandboxSettings(TypedDict, total=False): + """Sandbox settings configuration. + + This controls how Claude Code sandboxes bash commands for filesystem + and network isolation. + + **Important:** Filesystem and network restrictions are configured via permission + rules, not via these sandbox settings: + - Filesystem read restrictions: Use Read deny rules + - Filesystem write restrictions: Use Edit allow/deny rules + - Network restrictions: Use WebFetch allow/deny rules + + Attributes: + enabled: Enable bash sandboxing (macOS/Linux only). Default: False + autoAllowBashIfSandboxed: Auto-approve bash commands when sandboxed. Default: True + excludedCommands: Commands that should run outside the sandbox (e.g., ["git", "docker"]) + allowUnsandboxedCommands: Allow commands to bypass sandbox via dangerouslyDisableSandbox. + When False, all commands must run sandboxed (or be in excludedCommands). Default: True + network: Network configuration for sandbox. + ignoreViolations: Violations to ignore. + enableWeakerNestedSandbox: Enable weaker sandbox for unprivileged Docker environments + (Linux only). Reduces security. Default: False + + Example: + ```python + sandbox_settings: SandboxSettings = { + "enabled": True, + "autoAllowBashIfSandboxed": True, + "excludedCommands": ["docker"], + "network": { + "allowUnixSockets": ["/var/run/docker.sock"], + "allowLocalBinding": True + } + } + ``` + """ + + enabled: bool + autoAllowBashIfSandboxed: bool + excludedCommands: list[str] + allowUnsandboxedCommands: bool + network: SandboxNetworkConfig + ignoreViolations: SandboxIgnoreViolations + enableWeakerNestedSandbox: bool + + # Content block types @dataclass class TextBlock: @@ -569,6 +646,10 @@ class ClaudeAgentOptions: agents: dict[str, AgentDefinition] | None = None # Setting sources to load (user, project, local) setting_sources: list[SettingSource] | None = None + # Sandbox configuration for bash command isolation. + # Filesystem and network restrictions are derived from permission rules (Read/Edit/WebFetch), + # not from these sandbox settings. + sandbox: SandboxSettings | None = None # Plugin configurations for custom plugins plugins: list[SdkPluginConfig] = field(default_factory=list) # Max tokens for thinking blocks diff --git a/tests/test_transport.py b/tests/test_transport.py index a5a80d0..b834671 100644 --- a/tests/test_transport.py +++ b/tests/test_transport.py @@ -500,3 +500,150 @@ class TestSubprocessCLITransport: assert user_passed == "claude" anyio.run(_test) + + def test_build_command_with_sandbox_only(self): + """Test building CLI command with sandbox settings (no existing settings).""" + import json + + from claude_agent_sdk import SandboxSettings + + sandbox: SandboxSettings = { + "enabled": True, + "autoAllowBashIfSandboxed": True, + "network": { + "allowLocalBinding": True, + "allowUnixSockets": ["/var/run/docker.sock"], + }, + } + + transport = SubprocessCLITransport( + prompt="test", + options=make_options(sandbox=sandbox), + ) + + cmd = transport._build_command() + + # Should have --settings with sandbox merged in + assert "--settings" in cmd + settings_idx = cmd.index("--settings") + settings_value = cmd[settings_idx + 1] + + # Parse and verify + parsed = json.loads(settings_value) + assert "sandbox" in parsed + assert parsed["sandbox"]["enabled"] is True + assert parsed["sandbox"]["autoAllowBashIfSandboxed"] is True + assert parsed["sandbox"]["network"]["allowLocalBinding"] is True + assert parsed["sandbox"]["network"]["allowUnixSockets"] == [ + "/var/run/docker.sock" + ] + + def test_build_command_with_sandbox_and_settings_json(self): + """Test building CLI command with sandbox merged into existing settings JSON.""" + import json + + from claude_agent_sdk import SandboxSettings + + # Existing settings as JSON string + existing_settings = ( + '{"permissions": {"allow": ["Bash(ls:*)"]}, "verbose": true}' + ) + + sandbox: SandboxSettings = { + "enabled": True, + "excludedCommands": ["git", "docker"], + } + + transport = SubprocessCLITransport( + prompt="test", + options=make_options(settings=existing_settings, sandbox=sandbox), + ) + + cmd = transport._build_command() + + # Should have merged settings + assert "--settings" in cmd + settings_idx = cmd.index("--settings") + settings_value = cmd[settings_idx + 1] + + parsed = json.loads(settings_value) + + # Original settings should be preserved + assert parsed["permissions"] == {"allow": ["Bash(ls:*)"]} + assert parsed["verbose"] is True + + # Sandbox should be merged in + assert "sandbox" in parsed + assert parsed["sandbox"]["enabled"] is True + assert parsed["sandbox"]["excludedCommands"] == ["git", "docker"] + + def test_build_command_with_settings_file_and_no_sandbox(self): + """Test that settings file path is passed through when no sandbox.""" + transport = SubprocessCLITransport( + prompt="test", + options=make_options(settings="/path/to/settings.json"), + ) + + cmd = transport._build_command() + + # Should pass path directly, not parse it + assert "--settings" in cmd + settings_idx = cmd.index("--settings") + assert cmd[settings_idx + 1] == "/path/to/settings.json" + + def test_build_command_sandbox_minimal(self): + """Test sandbox with minimal configuration.""" + import json + + from claude_agent_sdk import SandboxSettings + + sandbox: SandboxSettings = {"enabled": True} + + transport = SubprocessCLITransport( + prompt="test", + options=make_options(sandbox=sandbox), + ) + + cmd = transport._build_command() + + assert "--settings" in cmd + settings_idx = cmd.index("--settings") + settings_value = cmd[settings_idx + 1] + + parsed = json.loads(settings_value) + assert parsed == {"sandbox": {"enabled": True}} + + def test_sandbox_network_config(self): + """Test sandbox with full network configuration.""" + import json + + from claude_agent_sdk import SandboxSettings + + sandbox: SandboxSettings = { + "enabled": True, + "network": { + "allowUnixSockets": ["/tmp/ssh-agent.sock"], + "allowAllUnixSockets": False, + "allowLocalBinding": True, + "httpProxyPort": 8080, + "socksProxyPort": 8081, + }, + } + + transport = SubprocessCLITransport( + prompt="test", + options=make_options(sandbox=sandbox), + ) + + cmd = transport._build_command() + settings_idx = cmd.index("--settings") + settings_value = cmd[settings_idx + 1] + + parsed = json.loads(settings_value) + network = parsed["sandbox"]["network"] + + assert network["allowUnixSockets"] == ["/tmp/ssh-agent.sock"] + assert network["allowAllUnixSockets"] is False + assert network["allowLocalBinding"] is True + assert network["httpProxyPort"] == 8080 + assert network["socksProxyPort"] == 8081 From 49482e1dfd591b112e6602343f17575fa88095ce Mon Sep 17 00:00:00 2001 From: Ashwin Bhat Date: Mon, 1 Dec 2025 11:40:58 -0500 Subject: [PATCH 18/55] fix: correct mypy type ignore error codes for MCP decorators (#379) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update type: ignore comments to use `untyped-decorator` instead of `misc` to match the actual mypy error codes reported in CI. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude --- src/claude_agent_sdk/__init__.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/claude_agent_sdk/__init__.py b/src/claude_agent_sdk/__init__.py index 8e710d5..407bc9a 100644 --- a/src/claude_agent_sdk/__init__.py +++ b/src/claude_agent_sdk/__init__.py @@ -218,7 +218,7 @@ def create_sdk_mcp_server( tool_map = {tool_def.name: tool_def for tool_def in tools} # Register list_tools handler to expose available tools - @server.list_tools() # type: ignore[no-untyped-call,misc] + @server.list_tools() # type: ignore[no-untyped-call,untyped-decorator] async def list_tools() -> list[Tool]: """Return the list of available tools.""" tool_list = [] @@ -264,7 +264,7 @@ def create_sdk_mcp_server( return tool_list # Register call_tool handler to execute tools - @server.call_tool() # type: ignore[misc] + @server.call_tool() # type: ignore[untyped-decorator] async def call_tool(name: str, arguments: dict[str, Any]) -> Any: """Execute a tool by name with given arguments.""" if name not in tool_map: From a2f24a310191ff50f53cc0a2a7371c9637303b58 Mon Sep 17 00:00:00 2001 From: Dalton Flanagan <6599399+dltn@users.noreply.github.com> Date: Mon, 1 Dec 2025 10:19:51 -0800 Subject: [PATCH 19/55] fix: wait for first result before closing stdin if SDK MCP present (#380) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Port SDK MCP fix from TypeScript to Python. Now, when SDK MCP servers or hooks are present, stream_input() waits for the first result message before closing stdin, allowing bidirectional control protocol communication to complete. Fixes repro in https://github.com/anthropics/claude-agent-sdk-python/issues/266. The `query()` design requires input streams to be held open by the user for SDK MCP bidirectional communication to work. This has confused a lot of folks, so we're moving towards a more explicit lifecycle design. In the meantime, this is the way we've addressed it with V1 APIs in https://github.com/anthropics/claude-agent-sdk-typescript. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude --- src/claude_agent_sdk/_internal/query.py | 36 +++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/src/claude_agent_sdk/_internal/query.py b/src/claude_agent_sdk/_internal/query.py index 566e316..e48995f 100644 --- a/src/claude_agent_sdk/_internal/query.py +++ b/src/claude_agent_sdk/_internal/query.py @@ -107,6 +107,12 @@ class Query: self._closed = False self._initialization_result: dict[str, Any] | None = None + # Track first result for proper stream closure with SDK MCP servers + self._first_result_event = anyio.Event() + self._stream_close_timeout = ( + float(os.environ.get("CLAUDE_CODE_STREAM_CLOSE_TIMEOUT", "60000")) / 1000.0 + ) # Convert ms to seconds + async def initialize(self) -> dict[str, Any] | None: """Initialize control protocol if in streaming mode. @@ -195,6 +201,10 @@ class Query: # TODO: Implement cancellation support continue + # Track results for proper stream closure + if msg_type == "result": + self._first_result_event.set() + # Regular SDK messages go to the stream await self._message_send.send(message) @@ -525,13 +535,35 @@ class Query: ) async def stream_input(self, stream: AsyncIterable[dict[str, Any]]) -> None: - """Stream input messages to transport.""" + """Stream input messages to transport. + + If SDK MCP servers or hooks are present, waits for the first result + before closing stdin to allow bidirectional control protocol communication. + """ try: async for message in stream: if self._closed: break await self.transport.write(json.dumps(message) + "\n") - # After all messages sent, end input + + # If we have SDK MCP servers or hooks that need bidirectional communication, + # wait for first result before closing the channel + has_hooks = bool(self.hooks) + if self.sdk_mcp_servers or has_hooks: + logger.debug( + f"Waiting for first result before closing stdin " + f"(sdk_mcp_servers={len(self.sdk_mcp_servers)}, has_hooks={has_hooks})" + ) + try: + with anyio.move_on_after(self._stream_close_timeout): + await self._first_result_event.wait() + logger.debug("Received first result, closing input stream") + except Exception: + logger.debug( + "Timed out waiting for first result, closing input stream" + ) + + # After all messages sent (and result received if needed), end input await self.transport.end_input() except Exception as e: logger.debug(f"Error streaming input: {e}") From 6e1769f8fdeda9256590a5a60ab413e41f867553 Mon Sep 17 00:00:00 2001 From: John Ott Date: Mon, 1 Dec 2025 12:44:57 -0800 Subject: [PATCH 20/55] feat: bundle claude code CLI for linux arm64 (#373) Currently wheels with packaged claude-code CLI are only published for windows amd64, linux x86_64 and macos arm64. For version 0.1.10, we can see the following download files are available on pypi contain the following artifacts: https://pypi.org/project/claude-agent-sdk/0.1.10/#files - claude_agent_sdk-0.1.10.tar.gz - claude_agent_sdk-0.1.10-py3-none-win_amd64.whl - claude_agent_sdk-0.1.10-py3-none-manylinux_2_17_x86_64.whl - claude_agent_sdk-0.1.10-py3-none-macosx_11_0_arm64.whl The existing publishing code should support adding a new linux arm64 wheel builder, using the Github ARM runners: https://github.blog/changelog/2025-08-07-arm64-hosted-runners-for-public-repositories-are-now-generally-available/ Unfortunately, there's no `ubuntu-latest-arm` label similar to the one we use for the other builds, so I'm using the `ubuntu-24.04-arm` label. --- .github/workflows/publish.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 1d8d79d..b831b18 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -61,7 +61,7 @@ jobs: runs-on: ${{ matrix.os }} strategy: matrix: - os: [ubuntu-latest, macos-latest, windows-latest] + os: [ubuntu-latest, ubuntu-24.04-arm, macos-latest, windows-latest] permissions: contents: write pull-requests: write From 2a53aba5b99d15ff7245aecd9885c27462c934de Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Tue, 2 Dec 2025 01:35:15 +0000 Subject: [PATCH 21/55] chore: bump bundled CLI version to 2.0.56 --- src/claude_agent_sdk/_cli_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py index 1e1d4ba..6619121 100644 --- a/src/claude_agent_sdk/_cli_version.py +++ b/src/claude_agent_sdk/_cli_version.py @@ -1,3 +1,3 @@ """Bundled Claude Code CLI version.""" -__cli_version__ = "2.0.55" +__cli_version__ = "2.0.56" From afa39dc1bffda495a9a79c1d3350b00bd0057f28 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Wed, 3 Dec 2025 05:24:28 +0000 Subject: [PATCH 22/55] chore: bump bundled CLI version to 2.0.57 --- src/claude_agent_sdk/_cli_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py index 6619121..0335a9f 100644 --- a/src/claude_agent_sdk/_cli_version.py +++ b/src/claude_agent_sdk/_cli_version.py @@ -1,3 +1,3 @@ """Bundled Claude Code CLI version.""" -__cli_version__ = "2.0.56" +__cli_version__ = "2.0.57" From 9809fb6b5404ca60d70d4cddc18c0ff195095285 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 3 Dec 2025 11:42:09 -0800 Subject: [PATCH 23/55] chore: release v0.1.11 (#383) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR updates the version to 0.1.11 after publishing to PyPI. ## Changes - Updated version in `pyproject.toml` to 0.1.11 - Updated version in `src/claude_agent_sdk/_version.py` to 0.1.11 - Updated `CHANGELOG.md` with release notes ## Release Information - Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.11/ - Bundled CLI version: 2.0.57 - Install with: `pip install claude-agent-sdk==0.1.11` 🤖 Generated by GitHub Actions --------- Co-authored-by: github-actions[bot] Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com> --- CHANGELOG.md | 6 ++++++ pyproject.toml | 2 +- src/claude_agent_sdk/_version.py | 2 +- 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 240d017..4a71177 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +## 0.1.11 + +### Internal/Other Changes + +- Updated bundled Claude CLI to version 2.0.57 + ## 0.1.10 ### Internal/Other Changes diff --git a/pyproject.toml b/pyproject.toml index 2abc2a4..2850005 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "claude-agent-sdk" -version = "0.1.10" +version = "0.1.11" description = "Python SDK for Claude Code" readme = "README.md" requires-python = ">=3.10" diff --git a/src/claude_agent_sdk/_version.py b/src/claude_agent_sdk/_version.py index 19a8d0f..c8c57ba 100644 --- a/src/claude_agent_sdk/_version.py +++ b/src/claude_agent_sdk/_version.py @@ -1,3 +1,3 @@ """Version information for claude-agent-sdk.""" -__version__ = "0.1.10" +__version__ = "0.1.11" From 243703531b68ca7ffd9439df1bb2a14304adecd4 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Wed, 3 Dec 2025 20:09:56 +0000 Subject: [PATCH 24/55] chore: bump bundled CLI version to 2.0.58 --- src/claude_agent_sdk/_cli_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py index 0335a9f..b45467a 100644 --- a/src/claude_agent_sdk/_cli_version.py +++ b/src/claude_agent_sdk/_cli_version.py @@ -1,3 +1,3 @@ """Bundled Claude Code CLI version.""" -__cli_version__ = "2.0.57" +__cli_version__ = "2.0.58" From 4e56cb12a9832eb21b3ce08282b3c68810100c30 Mon Sep 17 00:00:00 2001 From: Ashwin Bhat Date: Thu, 4 Dec 2025 09:26:01 -0800 Subject: [PATCH 25/55] feat: add SDK beta support with SdkBeta type and betas option (#390) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Port the SdkBeta type and betas option from the TypeScript SDK to enable SDK users to pass beta feature flags (e.g., 1M context window) to the CLI. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude --- src/claude_agent_sdk/__init__.py | 3 +++ src/claude_agent_sdk/_internal/transport/subprocess_cli.py | 3 +++ src/claude_agent_sdk/types.py | 5 +++++ 3 files changed, 11 insertions(+) diff --git a/src/claude_agent_sdk/__init__.py b/src/claude_agent_sdk/__init__.py index 407bc9a..4898bc0 100644 --- a/src/claude_agent_sdk/__init__.py +++ b/src/claude_agent_sdk/__init__.py @@ -42,6 +42,7 @@ from .types import ( SandboxIgnoreViolations, SandboxNetworkConfig, SandboxSettings, + SdkBeta, SdkPluginConfig, SettingSource, StopHookInput, @@ -345,6 +346,8 @@ __all__ = [ "SettingSource", # Plugin support "SdkPluginConfig", + # Beta support + "SdkBeta", # Sandbox support "SandboxSettings", "SandboxNetworkConfig", diff --git a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py index 73c1b29..6542cde 100644 --- a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py +++ b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py @@ -203,6 +203,9 @@ class SubprocessCLITransport(Transport): if self._options.fallback_model: cmd.extend(["--fallback-model", self._options.fallback_model]) + if self._options.betas: + cmd.extend(["--betas", ",".join(self._options.betas)]) + if self._options.permission_prompt_tool_name: cmd.extend( ["--permission-prompt-tool", self._options.permission_prompt_tool_name] diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py index f37fd3c..9a9800e 100644 --- a/src/claude_agent_sdk/types.py +++ b/src/claude_agent_sdk/types.py @@ -14,6 +14,9 @@ if TYPE_CHECKING: # Permission modes PermissionMode = Literal["default", "acceptEdits", "plan", "bypassPermissions"] +# SDK Beta features - see https://docs.anthropic.com/en/api/beta-headers +SdkBeta = Literal["context-1m-2025-08-07"] + # Agent definitions SettingSource = Literal["user", "project", "local"] @@ -614,6 +617,8 @@ class ClaudeAgentOptions: disallowed_tools: list[str] = field(default_factory=list) model: str | None = None fallback_model: str | None = None + # Beta features - see https://docs.anthropic.com/en/api/beta-headers + betas: list[SdkBeta] = field(default_factory=list) permission_prompt_tool_name: str | None = None cwd: str | Path | None = None cli_path: str | Path | None = None From ea0ef25e71d347a3a71b80357f34d34eb2875d1a Mon Sep 17 00:00:00 2001 From: Ashwin Bhat Date: Thu, 4 Dec 2025 09:27:02 -0800 Subject: [PATCH 26/55] feat: add tools option to ClaudeAgentOptions (#389) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add support for the `tools` option matching the TypeScript SDK, which controls the base set of available tools separately from allowed/disallowed tool filtering. Supports three modes: - Array of tool names: `["Read", "Edit", "Bash"]` - Empty array: `[]` (disables all built-in tools) - Preset object: `{"type": "preset", "preset": "claude_code"}` 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude --- examples/tools_option.py | 111 ++++++++++++++++++ .../_internal/transport/subprocess_cli.py | 12 ++ src/claude_agent_sdk/types.py | 8 ++ tests/test_transport.py | 46 ++++++++ 4 files changed, 177 insertions(+) create mode 100644 examples/tools_option.py diff --git a/examples/tools_option.py b/examples/tools_option.py new file mode 100644 index 0000000..204676f --- /dev/null +++ b/examples/tools_option.py @@ -0,0 +1,111 @@ +#!/usr/bin/env python3 +"""Example demonstrating the tools option and verifying tools in system message.""" + +import anyio + +from claude_agent_sdk import ( + AssistantMessage, + ClaudeAgentOptions, + ResultMessage, + SystemMessage, + TextBlock, + query, +) + + +async def tools_array_example(): + """Example with tools as array of specific tool names.""" + print("=== Tools Array Example ===") + print("Setting tools=['Read', 'Glob', 'Grep']") + print() + + options = ClaudeAgentOptions( + tools=["Read", "Glob", "Grep"], + max_turns=1, + ) + + async for message in query( + prompt="What tools do you have available? Just list them briefly.", + options=options, + ): + if isinstance(message, SystemMessage) and message.subtype == "init": + tools = message.data.get("tools", []) + print(f"Tools from system message: {tools}") + print() + elif isinstance(message, AssistantMessage): + for block in message.content: + if isinstance(block, TextBlock): + print(f"Claude: {block.text}") + elif isinstance(message, ResultMessage): + if message.total_cost_usd: + print(f"\nCost: ${message.total_cost_usd:.4f}") + print() + + +async def tools_empty_array_example(): + """Example with tools as empty array (disables all built-in tools).""" + print("=== Tools Empty Array Example ===") + print("Setting tools=[] (disables all built-in tools)") + print() + + options = ClaudeAgentOptions( + tools=[], + max_turns=1, + ) + + async for message in query( + prompt="What tools do you have available? Just list them briefly.", + options=options, + ): + if isinstance(message, SystemMessage) and message.subtype == "init": + tools = message.data.get("tools", []) + print(f"Tools from system message: {tools}") + print() + elif isinstance(message, AssistantMessage): + for block in message.content: + if isinstance(block, TextBlock): + print(f"Claude: {block.text}") + elif isinstance(message, ResultMessage): + if message.total_cost_usd: + print(f"\nCost: ${message.total_cost_usd:.4f}") + print() + + +async def tools_preset_example(): + """Example with tools preset (all default Claude Code tools).""" + print("=== Tools Preset Example ===") + print("Setting tools={'type': 'preset', 'preset': 'claude_code'}") + print() + + options = ClaudeAgentOptions( + tools={"type": "preset", "preset": "claude_code"}, + max_turns=1, + ) + + async for message in query( + prompt="What tools do you have available? Just list them briefly.", + options=options, + ): + if isinstance(message, SystemMessage) and message.subtype == "init": + tools = message.data.get("tools", []) + print(f"Tools from system message ({len(tools)} tools): {tools[:5]}...") + print() + elif isinstance(message, AssistantMessage): + for block in message.content: + if isinstance(block, TextBlock): + print(f"Claude: {block.text}") + elif isinstance(message, ResultMessage): + if message.total_cost_usd: + print(f"\nCost: ${message.total_cost_usd:.4f}") + print() + + +async def main(): + """Run all examples.""" + await tools_array_example() + await tools_empty_array_example() + await tools_preset_example() + + +if __name__ == "__main__": + anyio.run(main) diff --git a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py index 6542cde..26bd2ec 100644 --- a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py +++ b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py @@ -185,6 +185,18 @@ class SubprocessCLITransport(Transport): ["--append-system-prompt", self._options.system_prompt["append"]] ) + # Handle tools option (base set of tools) + if self._options.tools is not None: + tools = self._options.tools + if isinstance(tools, list): + if len(tools) == 0: + cmd.extend(["--tools", ""]) + else: + cmd.extend(["--tools", ",".join(tools)]) + else: + # Preset object - 'claude_code' preset maps to 'default' + cmd.extend(["--tools", "default"]) + if self._options.allowed_tools: cmd.extend(["--allowedTools", ",".join(self._options.allowed_tools)]) diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py index 9a9800e..391ff95 100644 --- a/src/claude_agent_sdk/types.py +++ b/src/claude_agent_sdk/types.py @@ -29,6 +29,13 @@ class SystemPromptPreset(TypedDict): append: NotRequired[str] +class ToolsPreset(TypedDict): + """Tools preset configuration.""" + + type: Literal["preset"] + preset: Literal["claude_code"] + + @dataclass class AgentDefinition: """Agent definition configuration.""" @@ -606,6 +613,7 @@ Message = UserMessage | AssistantMessage | SystemMessage | ResultMessage | Strea class ClaudeAgentOptions: """Query options for Claude SDK.""" + tools: list[str] | ToolsPreset | None = None allowed_tools: list[str] = field(default_factory=list) system_prompt: str | SystemPromptPreset | None = None mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict) diff --git a/tests/test_transport.py b/tests/test_transport.py index b834671..c634fc2 100644 --- a/tests/test_transport.py +++ b/tests/test_transport.py @@ -647,3 +647,49 @@ class TestSubprocessCLITransport: assert network["allowLocalBinding"] is True assert network["httpProxyPort"] == 8080 assert network["socksProxyPort"] == 8081 + + def test_build_command_with_tools_array(self): + """Test building CLI command with tools as array of tool names.""" + transport = SubprocessCLITransport( + prompt="test", + options=make_options(tools=["Read", "Edit", "Bash"]), + ) + + cmd = transport._build_command() + assert "--tools" in cmd + tools_idx = cmd.index("--tools") + assert cmd[tools_idx + 1] == "Read,Edit,Bash" + + def test_build_command_with_tools_empty_array(self): + """Test building CLI command with tools as empty array (disables all tools).""" + transport = SubprocessCLITransport( + prompt="test", + options=make_options(tools=[]), + ) + + cmd = transport._build_command() + assert "--tools" in cmd + tools_idx = cmd.index("--tools") + assert cmd[tools_idx + 1] == "" + + def test_build_command_with_tools_preset(self): + """Test building CLI command with tools preset.""" + transport = SubprocessCLITransport( + prompt="test", + options=make_options(tools={"type": "preset", "preset": "claude_code"}), + ) + + cmd = transport._build_command() + assert "--tools" in cmd + tools_idx = cmd.index("--tools") + assert cmd[tools_idx + 1] == "default" + + def test_build_command_without_tools(self): + """Test building CLI command without tools option (default None).""" + transport = SubprocessCLITransport( + prompt="test", + options=make_options(), + ) + + cmd = transport._build_command() + assert "--tools" not in cmd From 00332f32dcb5121d063729293263a09f92240f82 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 4 Dec 2025 10:30:12 -0800 Subject: [PATCH 27/55] chore: release v0.1.12 (#392) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR updates the version to 0.1.12 after publishing to PyPI. ## Changes - Updated version in `pyproject.toml` to 0.1.12 - Updated version in `src/claude_agent_sdk/_version.py` to 0.1.12 - Updated `CHANGELOG.md` with release notes ## Release Information - Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.12/ - Bundled CLI version: 2.0.58 - Install with: `pip install claude-agent-sdk==0.1.12` 🤖 Generated by GitHub Actions --------- Co-authored-by: github-actions[bot] Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com> Co-authored-by: Claude Co-authored-by: Ashwin Bhat --- CHANGELOG.md | 10 ++++++++++ pyproject.toml | 2 +- src/claude_agent_sdk/_version.py | 2 +- 3 files changed, 12 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4a71177..8250a32 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,15 @@ # Changelog +## 0.1.12 + +### New Features + +- **Tools option**: Added `tools` option to `ClaudeAgentOptions` for controlling the base set of available tools, matching the TypeScript SDK functionality. Supports three modes: + - Array of tool names to specify which tools should be available (e.g., `["Read", "Edit", "Bash"]`) + - Empty array `[]` to disable all built-in tools + - Preset object `{"type": "preset", "preset": "claude_code"}` to use the default Claude Code toolset +- **SDK beta support**: Added `betas` option to `ClaudeAgentOptions` for enabling Anthropic API beta features. Currently supports `"context-1m-2025-08-07"` for extended context window + ## 0.1.11 ### Internal/Other Changes diff --git a/pyproject.toml b/pyproject.toml index 2850005..f231338 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "claude-agent-sdk" -version = "0.1.11" +version = "0.1.12" description = "Python SDK for Claude Code" readme = "README.md" requires-python = ">=3.10" diff --git a/src/claude_agent_sdk/_version.py b/src/claude_agent_sdk/_version.py index c8c57ba..4acf622 100644 --- a/src/claude_agent_sdk/_version.py +++ b/src/claude_agent_sdk/_version.py @@ -1,3 +1,3 @@ """Version information for claude-agent-sdk.""" -__version__ = "0.1.11" +__version__ = "0.1.12" From 2d67166cae749d2d416dd110ab440c07f114b02e Mon Sep 17 00:00:00 2001 From: Carlos Cuevas <6290853+CarlosCuevas@users.noreply.github.com> Date: Thu, 4 Dec 2025 17:27:01 -0500 Subject: [PATCH 28/55] fix: add write lock to prevent concurrent transport writes (#391) ## TL;DR Adds a write lock to `SubprocessCLITransport` to prevent concurrent writes from parallel subagents. --- ## Overview When multiple subagents run in parallel and invoke MCP tools, the CLI sends concurrent `control_request` messages. Each handler tries to write a response back to the subprocess stdin at the same time. Trio's `TextSendStream` isn't thread-safe for concurrent access, so this causes `BusyResourceError`. This PR adds an `anyio.Lock` around all write operations (`write()`, `end_input()`, and the stdin-closing part of `close()`). The lock serializes concurrent writes so they happen one at a time. The `_ready` flag is now set inside the lock during `close()` to prevent a TOCTOU race where `write()` checks `_ready`, then `close()` sets it and closes the stream before `write()` actually sends data. --- ## Call Flow ```mermaid flowchart TD A["write()
subprocess_cli.py:505"] --> B["acquire _write_lock
subprocess_cli.py:507"] B --> C["check _ready & stream
subprocess_cli.py:509"] C --> D["_stdin_stream.send()
subprocess_cli.py:523"] E["close()
subprocess_cli.py:458"] --> F["acquire _write_lock
subprocess_cli.py:478"] F --> G["set _ready = False
subprocess_cli.py:479"] G --> H["close _stdin_stream
subprocess_cli.py:481"] I["end_input()
subprocess_cli.py:531"] --> J["acquire _write_lock
subprocess_cli.py:533"] J --> K["close _stdin_stream
subprocess_cli.py:535"] ``` --- .../_internal/transport/subprocess_cli.py | 70 +++++---- tests/test_transport.py | 133 ++++++++++++++++++ 2 files changed, 167 insertions(+), 36 deletions(-) diff --git a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py index 26bd2ec..c7c7420 100644 --- a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py +++ b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py @@ -65,6 +65,7 @@ class SubprocessCLITransport(Transport): else _DEFAULT_MAX_BUFFER_SIZE ) self._temp_files: list[str] = [] # Track temporary files for cleanup + self._write_lock: anyio.Lock = anyio.Lock() def _find_cli(self) -> str: """Find Claude Code CLI binary.""" @@ -471,8 +472,6 @@ class SubprocessCLITransport(Transport): async def close(self) -> None: """Close the transport and clean up resources.""" - self._ready = False - # Clean up temporary files first (before early return) for temp_file in self._temp_files: with suppress(Exception): @@ -480,6 +479,7 @@ class SubprocessCLITransport(Transport): self._temp_files.clear() if not self._process: + self._ready = False return # Close stderr task group if active @@ -489,21 +489,19 @@ class SubprocessCLITransport(Transport): await self._stderr_task_group.__aexit__(None, None, None) self._stderr_task_group = None - # Close streams - if self._stdin_stream: - with suppress(Exception): - await self._stdin_stream.aclose() - self._stdin_stream = None + # Close stdin stream (acquire lock to prevent race with concurrent writes) + async with self._write_lock: + self._ready = False # Set inside lock to prevent TOCTOU with write() + if self._stdin_stream: + with suppress(Exception): + await self._stdin_stream.aclose() + self._stdin_stream = None if self._stderr_stream: with suppress(Exception): await self._stderr_stream.aclose() self._stderr_stream = None - if self._process.stdin: - with suppress(Exception): - await self._process.stdin.aclose() - # Terminate and wait for process if self._process.returncode is None: with suppress(ProcessLookupError): @@ -521,37 +519,37 @@ class SubprocessCLITransport(Transport): async def write(self, data: str) -> None: """Write raw data to the transport.""" - # Check if ready (like TypeScript) - if not self._ready or not self._stdin_stream: - raise CLIConnectionError("ProcessTransport is not ready for writing") + async with self._write_lock: + # All checks inside lock to prevent TOCTOU races with close()/end_input() + if not self._ready or not self._stdin_stream: + raise CLIConnectionError("ProcessTransport is not ready for writing") - # Check if process is still alive (like TypeScript) - if self._process and self._process.returncode is not None: - raise CLIConnectionError( - f"Cannot write to terminated process (exit code: {self._process.returncode})" - ) + if self._process and self._process.returncode is not None: + raise CLIConnectionError( + f"Cannot write to terminated process (exit code: {self._process.returncode})" + ) - # Check for exit errors (like TypeScript) - if self._exit_error: - raise CLIConnectionError( - f"Cannot write to process that exited with error: {self._exit_error}" - ) from self._exit_error + if self._exit_error: + raise CLIConnectionError( + f"Cannot write to process that exited with error: {self._exit_error}" + ) from self._exit_error - try: - await self._stdin_stream.send(data) - except Exception as e: - self._ready = False # Mark as not ready (like TypeScript) - self._exit_error = CLIConnectionError( - f"Failed to write to process stdin: {e}" - ) - raise self._exit_error from e + try: + await self._stdin_stream.send(data) + except Exception as e: + self._ready = False + self._exit_error = CLIConnectionError( + f"Failed to write to process stdin: {e}" + ) + raise self._exit_error from e async def end_input(self) -> None: """End the input stream (close stdin).""" - if self._stdin_stream: - with suppress(Exception): - await self._stdin_stream.aclose() - self._stdin_stream = None + async with self._write_lock: + if self._stdin_stream: + with suppress(Exception): + await self._stdin_stream.aclose() + self._stdin_stream = None def read_messages(self) -> AsyncIterator[dict[str, Any]]: """Read and parse messages from the transport.""" diff --git a/tests/test_transport.py b/tests/test_transport.py index c634fc2..fe9b6b2 100644 --- a/tests/test_transport.py +++ b/tests/test_transport.py @@ -693,3 +693,136 @@ class TestSubprocessCLITransport: cmd = transport._build_command() assert "--tools" not in cmd + + def test_concurrent_writes_are_serialized(self): + """Test that concurrent write() calls are serialized by the lock. + + When parallel subagents invoke MCP tools, they trigger concurrent write() + calls. Without the _write_lock, trio raises BusyResourceError. + + Uses a real subprocess with the same stream setup as production: + process.stdin -> TextSendStream + """ + + async def _test(): + import sys + from subprocess import PIPE + + from anyio.streams.text import TextSendStream + + # Create a real subprocess that consumes stdin (cross-platform) + process = await anyio.open_process( + [sys.executable, "-c", "import sys; sys.stdin.read()"], + stdin=PIPE, + stdout=PIPE, + stderr=PIPE, + ) + + try: + transport = SubprocessCLITransport( + prompt="test", + options=ClaudeAgentOptions(cli_path="/usr/bin/claude"), + ) + + # Same setup as production: TextSendStream wrapping process.stdin + transport._ready = True + transport._process = MagicMock(returncode=None) + transport._stdin_stream = TextSendStream(process.stdin) + + # Spawn concurrent writes - the lock should serialize them + num_writes = 10 + errors: list[Exception] = [] + + async def do_write(i: int): + try: + await transport.write(f'{{"msg": {i}}}\n') + except Exception as e: + errors.append(e) + + async with anyio.create_task_group() as tg: + for i in range(num_writes): + tg.start_soon(do_write, i) + + # All writes should succeed - the lock serializes them + assert len(errors) == 0, f"Got errors: {errors}" + finally: + process.terminate() + await process.wait() + + anyio.run(_test, backend="trio") + + def test_concurrent_writes_fail_without_lock(self): + """Verify that without the lock, concurrent writes cause BusyResourceError. + + Uses a real subprocess with the same stream setup as production. + """ + + async def _test(): + import sys + from contextlib import asynccontextmanager + from subprocess import PIPE + + from anyio.streams.text import TextSendStream + + # Create a real subprocess that consumes stdin (cross-platform) + process = await anyio.open_process( + [sys.executable, "-c", "import sys; sys.stdin.read()"], + stdin=PIPE, + stdout=PIPE, + stderr=PIPE, + ) + + try: + transport = SubprocessCLITransport( + prompt="test", + options=ClaudeAgentOptions(cli_path="/usr/bin/claude"), + ) + + # Same setup as production + transport._ready = True + transport._process = MagicMock(returncode=None) + transport._stdin_stream = TextSendStream(process.stdin) + + # Replace lock with no-op to trigger the race condition + class NoOpLock: + @asynccontextmanager + async def __call__(self): + yield + + async def __aenter__(self): + return self + + async def __aexit__(self, *args): + pass + + transport._write_lock = NoOpLock() + + # Spawn concurrent writes - should fail without lock + num_writes = 10 + errors: list[Exception] = [] + + async def do_write(i: int): + try: + await transport.write(f'{{"msg": {i}}}\n') + except Exception as e: + errors.append(e) + + async with anyio.create_task_group() as tg: + for i in range(num_writes): + tg.start_soon(do_write, i) + + # Should have gotten errors due to concurrent access + assert len(errors) > 0, ( + "Expected errors from concurrent access, but got none" + ) + + # Check that at least one error mentions the concurrent access + error_strs = [str(e) for e in errors] + assert any("another task" in s for s in error_strs), ( + f"Expected 'another task' error, got: {error_strs}" + ) + finally: + process.terminate() + await process.wait() + + anyio.run(_test, backend="trio") From 6791efec9307d29fdbba0f3481e9219b4a6db835 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A2=A8=E6=A2=A8=E6=9E=9C?= Date: Fri, 5 Dec 2025 06:28:24 +0800 Subject: [PATCH 29/55] fix: add McpServer runtime placeholder for Pydantic 2.12+ compatibility (#385) ## Summary - Add runtime placeholder for `McpServer` type to fix Pydantic 2.12+ compatibility - `McpServer` was only imported under `TYPE_CHECKING`, causing `PydanticUserError` at runtime Fixes #384 Co-authored-by: lyrica --- src/claude_agent_sdk/types.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py index 391ff95..fa6ca35 100644 --- a/src/claude_agent_sdk/types.py +++ b/src/claude_agent_sdk/types.py @@ -10,6 +10,9 @@ from typing_extensions import NotRequired if TYPE_CHECKING: from mcp.server import Server as McpServer +else: + # Runtime placeholder for forward reference resolution in Pydantic 2.12+ + McpServer = Any # Permission modes PermissionMode = Literal["default", "acceptEdits", "plan", "bypassPermissions"] From 69a310cc3f0bbba71e3a945c10af70146fab8ce9 Mon Sep 17 00:00:00 2001 From: Ramazan Rakhmatullin <32195167+grumpygordon@users.noreply.github.com> Date: Fri, 5 Dec 2025 01:28:36 +0300 Subject: [PATCH 30/55] fix: propagate CLI errors to pending control requests (#388) ## Summary When the CLI exits with an error (e.g., invalid session ID passed to `--resume`), signal all pending control requests immediately instead of waiting for the 60-second timeout. **The fix adds 4 lines** to the exception handler in `_read_messages`: ```python # Signal all pending control requests so they fail fast instead of timing out for request_id, event in list(self.pending_control_responses.items()): if request_id not in self.pending_control_results: self.pending_control_results[request_id] = e event.set() ``` ## Problem When the CLI exits with an error, the SDK's message reader catches it but doesn't notify pending control requests. This causes `initialize()` to wait for the full 60-second timeout even though the error is known within seconds. Example scenario: 1. User passes invalid session ID via `ClaudeAgentOptions(resume="invalid-id")` 2. CLI prints `No conversation found with session ID: xxx` and exits with code 1 3. SDK message reader catches the error after ~3 seconds 4. But `initialize()` keeps waiting for 60 seconds before timing out ## Solution The existing code at `_send_control_request` lines 361-362 already handles exceptions in results: ```python if isinstance(result, Exception): raise result ``` The fix simply signals all pending control events when an error occurs, allowing them to fail fast with the actual error instead of timing out. ## Test Plan - [ ] Test with invalid session ID - should fail fast (~3s) instead of timing out (60s) - [ ] Test normal flow still works - [ ] Test multiple pending requests all get signaled Fixes #387 --- src/claude_agent_sdk/_internal/query.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/claude_agent_sdk/_internal/query.py b/src/claude_agent_sdk/_internal/query.py index e48995f..8f0ac19 100644 --- a/src/claude_agent_sdk/_internal/query.py +++ b/src/claude_agent_sdk/_internal/query.py @@ -214,6 +214,11 @@ class Query: raise # Re-raise to properly handle cancellation except Exception as e: logger.error(f"Fatal error in message reader: {e}") + # Signal all pending control requests so they fail fast instead of timing out + for request_id, event in list(self.pending_control_responses.items()): + if request_id not in self.pending_control_results: + self.pending_control_results[request_id] = e + event.set() # Put error in stream so iterators can handle it await self._message_send.send({"type": "error", "error": str(e)}) finally: From 1b3e35d14e1ec3cec6421cb9392e1bfed86c9c87 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Thu, 4 Dec 2025 23:09:33 +0000 Subject: [PATCH 31/55] chore: bump bundled CLI version to 2.0.59 --- src/claude_agent_sdk/_cli_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py index b45467a..74aa1ba 100644 --- a/src/claude_agent_sdk/_cli_version.py +++ b/src/claude_agent_sdk/_cli_version.py @@ -1,3 +1,3 @@ """Bundled Claude Code CLI version.""" -__cli_version__ = "2.0.58" +__cli_version__ = "2.0.59" From 00b5730be67d0a63cc59711c92f33a1921bf47f3 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Sat, 6 Dec 2025 00:10:43 +0000 Subject: [PATCH 32/55] chore: bump bundled CLI version to 2.0.60 --- src/claude_agent_sdk/_cli_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py index 74aa1ba..bf377f2 100644 --- a/src/claude_agent_sdk/_cli_version.py +++ b/src/claude_agent_sdk/_cli_version.py @@ -1,3 +1,3 @@ """Bundled Claude Code CLI version.""" -__cli_version__ = "2.0.59" +__cli_version__ = "2.0.60" From cf6b85fc5d913deaf1453d6c075ec8b5194b6adc Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 5 Dec 2025 16:33:33 -0800 Subject: [PATCH 33/55] chore: release v0.1.13 (#393) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR updates the version to 0.1.13 after publishing to PyPI. ## Changes - Updated version in `pyproject.toml` to 0.1.13 - Updated version in `src/claude_agent_sdk/_version.py` to 0.1.13 - Updated `CHANGELOG.md` with release notes ## Release Information - Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.13/ - Bundled CLI version: 2.0.59 - Install with: `pip install claude-agent-sdk==0.1.13` 🤖 Generated by GitHub Actions --------- Co-authored-by: github-actions[bot] Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com> Co-authored-by: Ashwin Bhat Co-authored-by: Claude --- CHANGELOG.md | 12 ++++++++++++ pyproject.toml | 2 +- src/claude_agent_sdk/_version.py | 2 +- 3 files changed, 14 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8250a32..4f674a6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,17 @@ # Changelog +## 0.1.13 + +### Bug Fixes + +- **Faster error handling**: CLI errors (e.g., invalid session ID) now propagate to pending requests immediately instead of waiting for the 60-second timeout (#388) +- **Pydantic 2.12+ compatibility**: Fixed `PydanticUserError` caused by `McpServer` type only being imported under `TYPE_CHECKING` (#385) +- **Concurrent subagent writes**: Added write lock to prevent `BusyResourceError` when multiple subagents invoke MCP tools in parallel (#391) + +### Internal/Other Changes + +- Updated bundled Claude CLI to version 2.0.59 + ## 0.1.12 ### New Features diff --git a/pyproject.toml b/pyproject.toml index f231338..be5afb6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "claude-agent-sdk" -version = "0.1.12" +version = "0.1.13" description = "Python SDK for Claude Code" readme = "README.md" requires-python = ">=3.10" diff --git a/src/claude_agent_sdk/_version.py b/src/claude_agent_sdk/_version.py index 4acf622..782d1c6 100644 --- a/src/claude_agent_sdk/_version.py +++ b/src/claude_agent_sdk/_version.py @@ -1,3 +1,3 @@ """Version information for claude-agent-sdk.""" -__version__ = "0.1.12" +__version__ = "0.1.13" From 562528621278486220496f437b33b90c34d5abc7 Mon Sep 17 00:00:00 2001 From: Ashwin Bhat Date: Sat, 6 Dec 2025 16:52:09 -0800 Subject: [PATCH 34/55] fix: move fetch-depth to publish job and use claude-opus-4-5 for changelog (#394) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The fetch-depth: 0 was on build-wheels but changelog generation happens in the publish job. Moved it to the correct location and upgraded the model for better changelog generation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude --- .github/workflows/publish.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index b831b18..b8b7e93 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -68,8 +68,6 @@ jobs: steps: - uses: actions/checkout@v4 - with: - fetch-depth: 0 # Fetch all history including tags (necessary for changelog generation) - name: Set up Python uses: actions/setup-python@v5 @@ -109,6 +107,7 @@ jobs: - uses: actions/checkout@v4 with: token: ${{ secrets.GITHUB_TOKEN }} + fetch-depth: 0 # Fetch all history including tags for changelog generation - name: Set up Python uses: actions/setup-python@v5 @@ -189,6 +188,7 @@ jobs: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} github_token: ${{ secrets.GITHUB_TOKEN }} claude_args: | + --model claude-opus-4-5 --allowedTools 'Bash(git add:*),Bash(git commit:*),Edit' - name: Push branch and create PR From db4a6f7c289139107fbb4737a7f9c38d2f1d836e Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Sun, 7 Dec 2025 10:47:47 +0000 Subject: [PATCH 35/55] chore: bump bundled CLI version to 2.0.61 --- src/claude_agent_sdk/_cli_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py index bf377f2..4cc007a 100644 --- a/src/claude_agent_sdk/_cli_version.py +++ b/src/claude_agent_sdk/_cli_version.py @@ -1,3 +1,3 @@ """Bundled Claude Code CLI version.""" -__cli_version__ = "2.0.60" +__cli_version__ = "2.0.61" From ccff8ddf48f8ee5e06258b9f70984186b9f10a71 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Tue, 9 Dec 2025 02:12:13 +0000 Subject: [PATCH 36/55] chore: bump bundled CLI version to 2.0.62 --- src/claude_agent_sdk/_cli_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py index 4cc007a..4f74ef2 100644 --- a/src/claude_agent_sdk/_cli_version.py +++ b/src/claude_agent_sdk/_cli_version.py @@ -1,3 +1,3 @@ """Bundled Claude Code CLI version.""" -__cli_version__ = "2.0.61" +__cli_version__ = "2.0.62" From b5447d999df597d52bd3153372a50d391faa18d1 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 9 Dec 2025 08:22:21 -0800 Subject: [PATCH 37/55] chore: release v0.1.14 (#398) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR updates the version to 0.1.14 after publishing to PyPI. ## Changes - Updated version in `pyproject.toml` to 0.1.14 - Updated version in `src/claude_agent_sdk/_version.py` to 0.1.14 - Updated `CHANGELOG.md` with release notes ## Release Information - Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.14/ - Bundled CLI version: 2.0.62 - Install with: `pip install claude-agent-sdk==0.1.14` 🤖 Generated by GitHub Actions --------- Co-authored-by: github-actions[bot] Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com> --- CHANGELOG.md | 6 ++++++ pyproject.toml | 2 +- src/claude_agent_sdk/_version.py | 2 +- 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4f674a6..32775ae 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +## 0.1.14 + +### Internal/Other Changes + +- Updated bundled Claude CLI to version 2.0.62 + ## 0.1.13 ### Bug Fixes diff --git a/pyproject.toml b/pyproject.toml index be5afb6..5e39d17 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "claude-agent-sdk" -version = "0.1.13" +version = "0.1.14" description = "Python SDK for Claude Code" readme = "README.md" requires-python = ">=3.10" diff --git a/src/claude_agent_sdk/_version.py b/src/claude_agent_sdk/_version.py index 782d1c6..b02a634 100644 --- a/src/claude_agent_sdk/_version.py +++ b/src/claude_agent_sdk/_version.py @@ -1,3 +1,3 @@ """Version information for claude-agent-sdk.""" -__version__ = "0.1.13" +__version__ = "0.1.14" From 4acfcc2d399f71647a4186c2e3948d624cc4e3be Mon Sep 17 00:00:00 2001 From: sarahdeaton Date: Tue, 9 Dec 2025 09:33:42 -0800 Subject: [PATCH 38/55] Add license and terms section to README. (#399) Add "License and terms" section to README clarifying that use of the SDK is governed by Anthropic's Commercial Terms of Service --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2111986..bcbe969 100644 --- a/README.md +++ b/README.md @@ -351,6 +351,6 @@ The package is published to PyPI via the GitHub Actions workflow in `.github/wor 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. -## License +## License and terms -MIT +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. From 53482d8955565197261a393859fd4813dd62cb2b Mon Sep 17 00:00:00 2001 From: Noah Zweben Date: Tue, 9 Dec 2025 10:16:03 -0800 Subject: [PATCH 39/55] feat: add file checkpointing and rewind_files support (#395) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary - Add `enable_file_checkpointing` option to `ClaudeAgentOptions` - Add `rewind_files(user_message_id)` method to `ClaudeSDKClient` and `Query` - Add `SDKControlRewindFilesRequest` type for the control protocol - Set `CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING` env var when enabled This adds Python SDK support for the file rewind feature from claude-cli-internal PR #11265. ## Test plan - [x] Verified imports work correctly - [x] Verified linting passes (`ruff check`) - [x] Verified existing tests still pass (106 passed, pre-existing failures unrelated to this change) 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Co-authored-by: Ashwin Bhat --- src/claude_agent_sdk/_internal/query.py | 15 +++++++++++ .../_internal/transport/subprocess_cli.py | 4 +++ src/claude_agent_sdk/client.py | 27 +++++++++++++++++++ src/claude_agent_sdk/types.py | 10 +++++++ 4 files changed, 56 insertions(+) diff --git a/src/claude_agent_sdk/_internal/query.py b/src/claude_agent_sdk/_internal/query.py index 8f0ac19..c30fc15 100644 --- a/src/claude_agent_sdk/_internal/query.py +++ b/src/claude_agent_sdk/_internal/query.py @@ -539,6 +539,21 @@ class Query: } ) + async def rewind_files(self, user_message_id: str) -> None: + """Rewind tracked files to their state at a specific user message. + + Requires file checkpointing to be enabled via the `enable_file_checkpointing` option. + + Args: + user_message_id: UUID of the user message to rewind to + """ + await self._send_control_request( + { + "subtype": "rewind_files", + "user_message_id": user_message_id, + } + ) + async def stream_input(self, stream: AsyncIterable[dict[str, Any]]) -> None: """Stream input messages to transport. diff --git a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py index c7c7420..a4882db 100644 --- a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py +++ b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py @@ -384,6 +384,10 @@ class SubprocessCLITransport(Transport): "CLAUDE_AGENT_SDK_VERSION": __version__, } + # Enable file checkpointing if requested + if self._options.enable_file_checkpointing: + process_env["CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING"] = "true" + if self._cwd: process_env["PWD"] = self._cwd diff --git a/src/claude_agent_sdk/client.py b/src/claude_agent_sdk/client.py index 742d7d6..2f74260 100644 --- a/src/claude_agent_sdk/client.py +++ b/src/claude_agent_sdk/client.py @@ -261,6 +261,33 @@ class ClaudeSDKClient: raise CLIConnectionError("Not connected. Call connect() first.") await self._query.set_model(model) + async def rewind_files(self, user_message_id: str) -> None: + """Rewind tracked files to their state at a specific user message. + + Requires file checkpointing to be enabled via the `enable_file_checkpointing` option + when creating the ClaudeSDKClient. + + Args: + user_message_id: UUID of the user message to rewind to. This should be + the `uuid` field from a `UserMessage` received during the conversation. + + Example: + ```python + options = ClaudeAgentOptions(enable_file_checkpointing=True) + async with ClaudeSDKClient(options) as client: + await client.query("Make some changes to my files") + async for msg in client.receive_response(): + if isinstance(msg, UserMessage): + checkpoint_id = msg.uuid # Save this for later + + # Later, rewind to that point + await client.rewind_files(checkpoint_id) + ``` + """ + if not self._query: + raise CLIConnectionError("Not connected. Call connect() first.") + await self._query.rewind_files(user_message_id) + async def get_server_info(self) -> dict[str, Any] | None: """Get server initialization info including available commands and output styles. diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py index fa6ca35..6d71322 100644 --- a/src/claude_agent_sdk/types.py +++ b/src/claude_agent_sdk/types.py @@ -673,6 +673,10 @@ class ClaudeAgentOptions: # Output format for structured outputs (matches Messages API structure) # Example: {"type": "json_schema", "schema": {"type": "object", "properties": {...}}} output_format: dict[str, Any] | None = None + # Enable file checkpointing to track file changes during the session. + # When enabled, files can be rewound to their state at any user message + # using `ClaudeSDKClient.rewind_files()`. + enable_file_checkpointing: bool = False # SDK Control Protocol @@ -713,6 +717,11 @@ class SDKControlMcpMessageRequest(TypedDict): message: Any +class SDKControlRewindFilesRequest(TypedDict): + subtype: Literal["rewind_files"] + user_message_id: str + + class SDKControlRequest(TypedDict): type: Literal["control_request"] request_id: str @@ -723,6 +732,7 @@ class SDKControlRequest(TypedDict): | SDKControlSetPermissionModeRequest | SDKHookCallbackRequest | SDKControlMcpMessageRequest + | SDKControlRewindFilesRequest ) From 5b912962e200fbd37b8c872b443c57abfb05085d Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 11 Dec 2025 10:53:45 -0800 Subject: [PATCH 40/55] chore: release v0.1.15 (#408) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR updates the version to 0.1.15 after publishing to PyPI. ## Changes - Updated version in `pyproject.toml` to 0.1.15 - Updated version in `src/claude_agent_sdk/_version.py` to 0.1.15 - Updated `CHANGELOG.md` with release notes ## Release Information - Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.15/ - Bundled CLI version: 2.0.62 - Install with: `pip install claude-agent-sdk==0.1.15` 🤖 Generated by GitHub Actions --------- Co-authored-by: github-actions[bot] Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com> Co-authored-by: Claude --- CHANGELOG.md | 10 ++++++++++ pyproject.toml | 2 +- src/claude_agent_sdk/_version.py | 2 +- 3 files changed, 12 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 32775ae..f492776 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,15 @@ # Changelog +## 0.1.15 + +### New Features + +- **File checkpointing and rewind**: Added `enable_file_checkpointing` option to `ClaudeAgentOptions` and `rewind_files(user_message_id)` method to `ClaudeSDKClient` and `Query`. This enables reverting file changes made during a session back to a specific checkpoint, useful for exploring different approaches or recovering from unwanted modifications (#395) + +### Documentation + +- Added license and terms section to README (#399) + ## 0.1.14 ### Internal/Other Changes diff --git a/pyproject.toml b/pyproject.toml index 5e39d17..10b0bad 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "claude-agent-sdk" -version = "0.1.14" +version = "0.1.15" description = "Python SDK for Claude Code" readme = "README.md" requires-python = ">=3.10" diff --git a/src/claude_agent_sdk/_version.py b/src/claude_agent_sdk/_version.py index b02a634..d9b37ab 100644 --- a/src/claude_agent_sdk/_version.py +++ b/src/claude_agent_sdk/_version.py @@ -1,3 +1,3 @@ """Version information for claude-agent-sdk.""" -__version__ = "0.1.14" +__version__ = "0.1.15" From 3cbb9e56be1f5b947d640f0b05710d7d032781be Mon Sep 17 00:00:00 2001 From: lif <1835304752@qq.com> Date: Fri, 12 Dec 2025 02:55:01 +0800 Subject: [PATCH 41/55] fix: parse error field in AssistantMessage to enable rate limit detection (#405) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary Fixes #401 Enables applications to detect API errors (especially `rate_limit` errors) by properly parsing the `error` field in `AssistantMessage`. ## Problem The SDK defines `AssistantMessage.error` (including `"rate_limit"`), but the message parser never extracted this field from the CLI response. This made it impossible for applications to: - Detect when rate limits are hit - Implement retry logic - Handle other API errors gracefully ## Solution Added error field extraction in the message parser: ```python return AssistantMessage( content=content_blocks, model=data["message"]["model"], parent_tool_use_id=data.get("parent_tool_use_id"), error=data["message"].get("error"), # ← Now extracts error field ) ``` ## Changes **Modified: `src/claude_agent_sdk/_internal/message_parser.py`** The parser now extracts the `error` field from API responses and populates it in the `AssistantMessage` object. ## Usage Example Applications can now detect and handle rate limits: ```python async for message in client.receive_response(): if isinstance(message, AssistantMessage): if message.error == "rate_limit": print("Rate limit hit! Implementing backoff...") await asyncio.sleep(60) # Retry logic here elif message.error: print(f"API error: {message.error}") ``` ## Testing - ✅ Passed ruff linting and formatting - ✅ Passed mypy type checking - ✅ All existing tests pass ## Type of Change - [x] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) ## Impact This fix enables production applications to: - Implement proper error handling for API errors - Build robust retry logic for rate limits - Provide better user feedback when errors occur - Avoid silent failures when the API returns errors --- 🤖 Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude Co-Authored-By: Happy Co-authored-by: Claude Co-authored-by: Happy --- src/claude_agent_sdk/_internal/message_parser.py | 1 + 1 file changed, 1 insertion(+) diff --git a/src/claude_agent_sdk/_internal/message_parser.py b/src/claude_agent_sdk/_internal/message_parser.py index 694c52c..312e4c0 100644 --- a/src/claude_agent_sdk/_internal/message_parser.py +++ b/src/claude_agent_sdk/_internal/message_parser.py @@ -120,6 +120,7 @@ def parse_message(data: dict[str, Any]) -> Message: content=content_blocks, model=data["message"]["model"], parent_tool_use_id=data.get("parent_tool_use_id"), + error=data["message"].get("error"), ) except KeyError as e: raise MessageParseError( From d2b3477a4e527d4e3934bda91bcd93392e432d0b Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Fri, 12 Dec 2025 23:32:48 +0000 Subject: [PATCH 42/55] chore: bump bundled CLI version to 2.0.68 --- src/claude_agent_sdk/_cli_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py index 4f74ef2..06930ab 100644 --- a/src/claude_agent_sdk/_cli_version.py +++ b/src/claude_agent_sdk/_cli_version.py @@ -1,3 +1,3 @@ """Bundled Claude Code CLI version.""" -__cli_version__ = "2.0.62" +__cli_version__ = "2.0.68" From a1c338726f25f887cfed2e45eea7bd5049ea9cbf Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 12 Dec 2025 16:26:36 -0800 Subject: [PATCH 43/55] chore: release v0.1.16 (#412) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR updates the version to 0.1.16 after publishing to PyPI. ## Changes - Updated version in `pyproject.toml` to 0.1.16 - Updated version in `src/claude_agent_sdk/_version.py` to 0.1.16 - Updated `CHANGELOG.md` with release notes ## Release Information - Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.16/ - Bundled CLI version: 2.0.68 - Install with: `pip install claude-agent-sdk==0.1.16` 🤖 Generated by GitHub Actions --------- Co-authored-by: github-actions[bot] Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com> Co-authored-by: Claude --- CHANGELOG.md | 10 ++++++++++ pyproject.toml | 2 +- src/claude_agent_sdk/_version.py | 2 +- 3 files changed, 12 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f492776..e252c83 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,15 @@ # Changelog +## 0.1.16 + +### Bug Fixes + +- **Rate limit detection**: Fixed parsing of the `error` field in `AssistantMessage`, enabling applications to detect and handle API errors like rate limits. Previously, the `error` field was defined but never populated from CLI responses (#405) + +### Internal/Other Changes + +- Updated bundled Claude CLI to version 2.0.68 + ## 0.1.15 ### New Features diff --git a/pyproject.toml b/pyproject.toml index 10b0bad..84f6172 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "claude-agent-sdk" -version = "0.1.15" +version = "0.1.16" description = "Python SDK for Claude Code" readme = "README.md" requires-python = ">=3.10" diff --git a/src/claude_agent_sdk/_version.py b/src/claude_agent_sdk/_version.py index d9b37ab..4fd71fa 100644 --- a/src/claude_agent_sdk/_version.py +++ b/src/claude_agent_sdk/_version.py @@ -1,3 +1,3 @@ """Version information for claude-agent-sdk.""" -__version__ = "0.1.15" +__version__ = "0.1.16" From f834ba9e1586ea2e31353fafcb41f78b7b9eab51 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Sat, 13 Dec 2025 01:00:44 +0000 Subject: [PATCH 44/55] chore: bump bundled CLI version to 2.0.69 --- src/claude_agent_sdk/_cli_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py index 06930ab..079e323 100644 --- a/src/claude_agent_sdk/_cli_version.py +++ b/src/claude_agent_sdk/_cli_version.py @@ -1,3 +1,3 @@ """Bundled Claude Code CLI version.""" -__cli_version__ = "2.0.68" +__cli_version__ = "2.0.69" From 0ae5c3285c0f9b58c3430d609ed839701f9b8874 Mon Sep 17 00:00:00 2001 From: Noah Zweben Date: Mon, 15 Dec 2025 09:03:58 -0800 Subject: [PATCH 45/55] Add UUID to UserMessage response type to improve devX for rewind (#418) --- src/claude_agent_sdk/_internal/message_parser.py | 3 +++ src/claude_agent_sdk/client.py | 13 +++++++++---- src/claude_agent_sdk/types.py | 1 + tests/test_message_parser.py | 15 +++++++++++++++ 4 files changed, 28 insertions(+), 4 deletions(-) diff --git a/src/claude_agent_sdk/_internal/message_parser.py b/src/claude_agent_sdk/_internal/message_parser.py index 312e4c0..4bfe814 100644 --- a/src/claude_agent_sdk/_internal/message_parser.py +++ b/src/claude_agent_sdk/_internal/message_parser.py @@ -48,6 +48,7 @@ def parse_message(data: dict[str, Any]) -> Message: case "user": try: parent_tool_use_id = data.get("parent_tool_use_id") + uuid = data.get("uuid") if isinstance(data["message"]["content"], list): user_content_blocks: list[ContentBlock] = [] for block in data["message"]["content"]: @@ -74,10 +75,12 @@ def parse_message(data: dict[str, Any]) -> Message: ) return UserMessage( content=user_content_blocks, + uuid=uuid, parent_tool_use_id=parent_tool_use_id, ) return UserMessage( content=data["message"]["content"], + uuid=uuid, parent_tool_use_id=parent_tool_use_id, ) except KeyError as e: diff --git a/src/claude_agent_sdk/client.py b/src/claude_agent_sdk/client.py index 2f74260..18ab818 100644 --- a/src/claude_agent_sdk/client.py +++ b/src/claude_agent_sdk/client.py @@ -264,8 +264,10 @@ class ClaudeSDKClient: async def rewind_files(self, user_message_id: str) -> None: """Rewind tracked files to their state at a specific user message. - Requires file checkpointing to be enabled via the `enable_file_checkpointing` option - when creating the ClaudeSDKClient. + Requires: + - `enable_file_checkpointing=True` to track file changes + - `extra_args={"replay-user-messages": None}` to receive UserMessage + objects with `uuid` in the response stream Args: user_message_id: UUID of the user message to rewind to. This should be @@ -273,11 +275,14 @@ class ClaudeSDKClient: Example: ```python - options = ClaudeAgentOptions(enable_file_checkpointing=True) + options = ClaudeAgentOptions( + enable_file_checkpointing=True, + extra_args={"replay-user-messages": None}, + ) async with ClaudeSDKClient(options) as client: await client.query("Make some changes to my files") async for msg in client.receive_response(): - if isinstance(msg, UserMessage): + if isinstance(msg, UserMessage) and msg.uuid: checkpoint_id = msg.uuid # Save this for later # Later, rewind to that point diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py index 6d71322..9c09345 100644 --- a/src/claude_agent_sdk/types.py +++ b/src/claude_agent_sdk/types.py @@ -562,6 +562,7 @@ class UserMessage: """User message.""" content: str | list[ContentBlock] + uuid: str | None = None parent_tool_use_id: str | None = None diff --git a/tests/test_message_parser.py b/tests/test_message_parser.py index 60bcc53..cd18952 100644 --- a/tests/test_message_parser.py +++ b/tests/test_message_parser.py @@ -31,6 +31,21 @@ class TestMessageParser: assert isinstance(message.content[0], TextBlock) assert message.content[0].text == "Hello" + def test_parse_user_message_with_uuid(self): + """Test parsing a user message with uuid field (issue #414). + + The uuid field is needed for file checkpointing with rewind_files(). + """ + data = { + "type": "user", + "uuid": "msg-abc123-def456", + "message": {"content": [{"type": "text", "text": "Hello"}]}, + } + message = parse_message(data) + assert isinstance(message, UserMessage) + assert message.uuid == "msg-abc123-def456" + assert len(message.content) == 1 + def test_parse_user_message_with_tool_use(self): """Test parsing a user message with tool_use block.""" data = { From 5752f38834373998800d58f10f745716d76b6102 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Mon, 15 Dec 2025 23:52:59 +0000 Subject: [PATCH 46/55] chore: bump bundled CLI version to 2.0.70 --- src/claude_agent_sdk/_cli_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py index 079e323..6309e4c 100644 --- a/src/claude_agent_sdk/_cli_version.py +++ b/src/claude_agent_sdk/_cli_version.py @@ -1,3 +1,3 @@ """Bundled Claude Code CLI version.""" -__cli_version__ = "2.0.69" +__cli_version__ = "2.0.70" From eba5675328703d47aa6210d6341a2fff9b06c43b Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 15 Dec 2025 16:41:49 -0800 Subject: [PATCH 47/55] chore: release v0.1.17 (#419) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR updates the version to 0.1.17 after publishing to PyPI. ## Changes - Updated version in `pyproject.toml` to 0.1.17 - Updated version in `src/claude_agent_sdk/_version.py` to 0.1.17 - Updated `CHANGELOG.md` with release notes ## Release Information - Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.17/ - Bundled CLI version: 2.0.70 - Install with: `pip install claude-agent-sdk==0.1.17` 🤖 Generated by GitHub Actions --------- Co-authored-by: github-actions[bot] Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com> Co-authored-by: Claude --- CHANGELOG.md | 10 ++++++++++ pyproject.toml | 2 +- src/claude_agent_sdk/_version.py | 2 +- 3 files changed, 12 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e252c83..0b0ad22 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,15 @@ # Changelog +## 0.1.17 + +### New Features + +- **UserMessage UUID field**: Added `uuid` field to `UserMessage` response type, making it easier to use the `rewind_files()` method by providing direct access to message identifiers needed for file checkpointing (#418) + +### Internal/Other Changes + +- Updated bundled Claude CLI to version 2.0.70 + ## 0.1.16 ### Bug Fixes diff --git a/pyproject.toml b/pyproject.toml index 84f6172..0f3c76c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "claude-agent-sdk" -version = "0.1.16" +version = "0.1.17" description = "Python SDK for Claude Code" readme = "README.md" requires-python = ">=3.10" diff --git a/src/claude_agent_sdk/_version.py b/src/claude_agent_sdk/_version.py index 4fd71fa..e60bfef 100644 --- a/src/claude_agent_sdk/_version.py +++ b/src/claude_agent_sdk/_version.py @@ -1,3 +1,3 @@ """Version information for claude-agent-sdk.""" -__version__ = "0.1.16" +__version__ = "0.1.17" From 904c2ec33cc3339b480f47408b63771f57e521a3 Mon Sep 17 00:00:00 2001 From: Ashwin Bhat Date: Mon, 15 Dec 2025 16:53:23 -0800 Subject: [PATCH 48/55] chore: use CHANGELOG.md content for GitHub release notes (#420) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace auto-generated release notes with content extracted from CHANGELOG.md for the specific version being released. This provides more structured and consistent release notes with proper sections like Bug Fixes, New Features, etc. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude --- .github/workflows/create-release-tag.yml | 46 +++++++++++++++--------- 1 file changed, 30 insertions(+), 16 deletions(-) diff --git a/.github/workflows/create-release-tag.yml b/.github/workflows/create-release-tag.yml index 8d6b8e1..47f6c82 100644 --- a/.github/workflows/create-release-tag.yml +++ b/.github/workflows/create-release-tag.yml @@ -24,12 +24,6 @@ jobs: VERSION="${BRANCH_NAME#release/v}" echo "version=$VERSION" >> $GITHUB_OUTPUT - - name: Get previous release tag - id: previous_tag - run: | - PREVIOUS_TAG=$(git describe --tags --abbrev=0 HEAD~1 2>/dev/null || echo "") - echo "previous_tag=$PREVIOUS_TAG" >> $GITHUB_OUTPUT - - name: Create and push tag run: | git config --local user.email "github-actions[bot]@users.noreply.github.com" @@ -46,14 +40,34 @@ jobs: env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | - # Create release with auto-generated notes - gh release create "v${{ steps.extract_version.outputs.version }}" \ - --title "Release v${{ steps.extract_version.outputs.version }}" \ - --generate-notes \ - --notes-start-tag "${{ steps.previous_tag.outputs.previous_tag }}" \ - --notes "Published to PyPI: https://pypi.org/project/claude-agent-sdk/${{ steps.extract_version.outputs.version }}/ + VERSION="${{ steps.extract_version.outputs.version }}" - ### Installation - \`\`\`bash - pip install claude-agent-sdk==${{ steps.extract_version.outputs.version }} - \`\`\`" + # Extract changelog section for this version to a temp file + awk -v ver="$VERSION" ' + /^## / { + if (found) exit + if ($2 == ver) found=1 + next + } + found { print } + ' CHANGELOG.md > release_notes.md + + # Append install instructions + cat >> release_notes.md << 'EOF' + +--- + +**PyPI:** https://pypi.org/project/claude-agent-sdk/VERSION/ + +```bash +pip install claude-agent-sdk==VERSION +``` +EOF + + # Replace VERSION placeholder + sed -i "s/VERSION/$VERSION/g" release_notes.md + + # Create release with notes from file + gh release create "v$VERSION" \ + --title "v$VERSION" \ + --notes-file release_notes.md From a0ce44a3fabbc714df7a559a2855694569fe9585 Mon Sep 17 00:00:00 2001 From: Ashwin Bhat Date: Tue, 16 Dec 2025 10:53:13 -0800 Subject: [PATCH 49/55] Add Docker-based test infrastructure for e2e tests (#424) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary - Add `Dockerfile.test`: Python 3.12 image with Claude Code CLI installed - Add `scripts/test-docker.sh`: Local script to run tests in Docker - Add `test-e2e-docker` job to CI workflow that runs the full e2e suite in a container - Add `.dockerignore` to speed up Docker builds ## Context This helps catch Docker-specific issues like #406 where filesystem-based agents loaded via `setting_sources=["project"]` may silently fail in Docker environments. ## Local Usage ```bash # Run unit tests in Docker (no API key needed) ./scripts/test-docker.sh unit # Run e2e tests in Docker ANTHROPIC_API_KEY=sk-... ./scripts/test-docker.sh e2e # Run all tests ANTHROPIC_API_KEY=sk-... ./scripts/test-docker.sh all ``` ## Test plan - [x] Unit tests pass in Docker locally (129 passed) - [ ] CI job runs successfully 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude --- .claude/agents/test-agent.md | 9 +++ .dockerignore | 49 ++++++++++++ .github/workflows/test.yml | 18 +++++ Dockerfile.test | 29 +++++++ e2e-tests/test_agents_and_settings.py | 111 +++++++++++++++++++++----- examples/filesystem_agents.py | 107 +++++++++++++++++++++++++ scripts/test-docker.sh | 77 ++++++++++++++++++ 7 files changed, 381 insertions(+), 19 deletions(-) create mode 100644 .claude/agents/test-agent.md create mode 100644 .dockerignore create mode 100644 Dockerfile.test create mode 100644 examples/filesystem_agents.py create mode 100755 scripts/test-docker.sh diff --git a/.claude/agents/test-agent.md b/.claude/agents/test-agent.md new file mode 100644 index 0000000..6515827 --- /dev/null +++ b/.claude/agents/test-agent.md @@ -0,0 +1,9 @@ +--- +name: test-agent +description: A simple test agent for SDK testing +tools: Read +--- + +# Test Agent + +You are a simple test agent. When asked a question, provide a brief, helpful answer. diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..d013f1b --- /dev/null +++ b/.dockerignore @@ -0,0 +1,49 @@ +# Git +.git +.gitignore + +# Python +__pycache__ +*.py[cod] +*$py.class +*.so +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +*.egg-info/ +.installed.cfg +*.egg + +# Virtual environments +.env +.venv +env/ +venv/ +ENV/ + +# IDE +.idea/ +.vscode/ +*.swp +*.swo + +# Testing/Coverage +.coverage +.pytest_cache/ +htmlcov/ +.tox/ +.nox/ + +# Misc +*.log +.DS_Store diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index d78d425..d581a8f 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -81,6 +81,24 @@ jobs: run: | python -m pytest e2e-tests/ -v -m e2e + test-e2e-docker: + runs-on: ubuntu-latest + needs: test # Run after unit tests pass + # Run e2e tests in Docker to catch container-specific issues like #406 + + steps: + - uses: actions/checkout@v4 + + - name: Build Docker test image + run: docker build -f Dockerfile.test -t claude-sdk-test . + + - name: Run e2e tests in Docker + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + run: | + docker run --rm -e ANTHROPIC_API_KEY \ + claude-sdk-test python -m pytest e2e-tests/ -v -m e2e + test-examples: runs-on: ubuntu-latest needs: test-e2e # Run after e2e tests diff --git a/Dockerfile.test b/Dockerfile.test new file mode 100644 index 0000000..22adf2e --- /dev/null +++ b/Dockerfile.test @@ -0,0 +1,29 @@ +# Dockerfile for running SDK tests in a containerized environment +# This helps catch Docker-specific issues like #406 + +FROM python:3.12-slim + +# Install dependencies for Claude CLI and git (needed for some tests) +RUN apt-get update && apt-get install -y \ + curl \ + git \ + && rm -rf /var/lib/apt/lists/* + +# Install Claude Code CLI +RUN curl -fsSL https://claude.ai/install.sh | bash +ENV PATH="/root/.local/bin:$PATH" + +# Set up working directory +WORKDIR /app + +# Copy the SDK source +COPY . . + +# Install SDK with dev dependencies +RUN pip install -e ".[dev]" + +# Verify CLI installation +RUN claude -v + +# Default: run unit tests +CMD ["python", "-m", "pytest", "tests/", "-v"] diff --git a/e2e-tests/test_agents_and_settings.py b/e2e-tests/test_agents_and_settings.py index 6e04066..3f6fc80 100644 --- a/e2e-tests/test_agents_and_settings.py +++ b/e2e-tests/test_agents_and_settings.py @@ -38,15 +38,88 @@ async def test_agent_definition(): async for message in client.receive_response(): if isinstance(message, SystemMessage) and message.subtype == "init": agents = message.data.get("agents", []) - assert isinstance( - agents, list - ), f"agents should be a list of strings, got: {type(agents)}" - assert ( - "test-agent" in agents - ), f"test-agent should be available, got: {agents}" + assert isinstance(agents, list), ( + f"agents should be a list of strings, got: {type(agents)}" + ) + assert "test-agent" in agents, ( + f"test-agent should be available, got: {agents}" + ) break +@pytest.mark.e2e +@pytest.mark.asyncio +async def test_filesystem_agent_loading(): + """Test that filesystem-based agents load via setting_sources and produce full response. + + This is the core test for issue #406. It verifies that when using + setting_sources=["project"] with a .claude/agents/ directory containing + agent definitions, the SDK: + 1. Loads the agents (they appear in init message) + 2. Produces a full response with AssistantMessage + 3. Completes with a ResultMessage + + The bug in #406 causes the iterator to complete after only the + init SystemMessage, never yielding AssistantMessage or ResultMessage. + """ + with tempfile.TemporaryDirectory() as tmpdir: + # Create a temporary project with a filesystem agent + project_dir = Path(tmpdir) + agents_dir = project_dir / ".claude" / "agents" + agents_dir.mkdir(parents=True) + + # Create a test agent file + agent_file = agents_dir / "fs-test-agent.md" + agent_file.write_text( + """--- +name: fs-test-agent +description: A filesystem test agent for SDK testing +tools: Read +--- + +# Filesystem Test Agent + +You are a simple test agent. When asked a question, provide a brief, helpful answer. +""" + ) + + options = ClaudeAgentOptions( + setting_sources=["project"], + cwd=project_dir, + max_turns=1, + ) + + messages = [] + async with ClaudeSDKClient(options=options) as client: + await client.query("Say hello in exactly 3 words") + async for msg in client.receive_response(): + messages.append(msg) + + # Must have at least init, assistant, result + message_types = [type(m).__name__ for m in messages] + + assert "SystemMessage" in message_types, "Missing SystemMessage (init)" + assert "AssistantMessage" in message_types, ( + f"Missing AssistantMessage - got only: {message_types}. " + "This may indicate issue #406 (silent failure with filesystem agents)." + ) + assert "ResultMessage" in message_types, "Missing ResultMessage" + + # Find the init message and check for the filesystem agent + for msg in messages: + if isinstance(msg, SystemMessage) and msg.subtype == "init": + agents = msg.data.get("agents", []) + # Agents are returned as strings (just names) + assert "fs-test-agent" in agents, ( + f"fs-test-agent not loaded from filesystem. Found: {agents}" + ) + break + + # On Windows, wait for file handles to be released before cleanup + if sys.platform == "win32": + await asyncio.sleep(0.5) + + @pytest.mark.e2e @pytest.mark.asyncio async def test_setting_sources_default(): @@ -74,12 +147,12 @@ async def test_setting_sources_default(): async for message in client.receive_response(): if isinstance(message, SystemMessage) and message.subtype == "init": output_style = message.data.get("output_style") - assert ( - output_style != "local-test-style" - ), f"outputStyle should NOT be from local settings (default is no settings), got: {output_style}" - assert ( - output_style == "default" - ), f"outputStyle should be 'default', got: {output_style}" + assert output_style != "local-test-style", ( + f"outputStyle should NOT be from local settings (default is no settings), got: {output_style}" + ) + assert output_style == "default", ( + f"outputStyle should be 'default', got: {output_style}" + ) break # On Windows, wait for file handles to be released before cleanup @@ -121,9 +194,9 @@ This is a test command. async for message in client.receive_response(): if isinstance(message, SystemMessage) and message.subtype == "init": commands = message.data.get("slash_commands", []) - assert ( - "testcmd" not in commands - ), f"testcmd should NOT be available with user-only sources, got: {commands}" + assert "testcmd" not in commands, ( + f"testcmd should NOT be available with user-only sources, got: {commands}" + ) break # On Windows, wait for file handles to be released before cleanup @@ -159,11 +232,11 @@ async def test_setting_sources_project_included(): async for message in client.receive_response(): if isinstance(message, SystemMessage) and message.subtype == "init": output_style = message.data.get("output_style") - assert ( - output_style == "local-test-style" - ), f"outputStyle should be from local settings, got: {output_style}" + assert output_style == "local-test-style", ( + f"outputStyle should be from local settings, got: {output_style}" + ) break # On Windows, wait for file handles to be released before cleanup if sys.platform == "win32": - await asyncio.sleep(0.5) \ No newline at end of file + await asyncio.sleep(0.5) diff --git a/examples/filesystem_agents.py b/examples/filesystem_agents.py new file mode 100644 index 0000000..e5f6904 --- /dev/null +++ b/examples/filesystem_agents.py @@ -0,0 +1,107 @@ +#!/usr/bin/env python3 +"""Example of loading filesystem-based agents via setting_sources. + +This example demonstrates how to load agents defined in .claude/agents/ files +using the setting_sources option. This is different from inline AgentDefinition +objects - these agents are loaded from markdown files on disk. + +This example tests the scenario from issue #406 where filesystem-based agents +loaded via setting_sources=["project"] may silently fail in certain environments. + +Usage: +./examples/filesystem_agents.py +""" + +import asyncio +from pathlib import Path + +from claude_agent_sdk import ( + AssistantMessage, + ClaudeAgentOptions, + ClaudeSDKClient, + ResultMessage, + SystemMessage, + TextBlock, +) + + +def extract_agents(msg: SystemMessage) -> list[str]: + """Extract agent names from system message init data.""" + if msg.subtype == "init": + agents = msg.data.get("agents", []) + # Agents can be either strings or dicts with a 'name' field + result = [] + for a in agents: + if isinstance(a, str): + result.append(a) + elif isinstance(a, dict): + result.append(a.get("name", "")) + return result + return [] + + +async def main(): + """Test loading filesystem-based agents.""" + print("=== Filesystem Agents Example ===") + print("Testing: setting_sources=['project'] with .claude/agents/test-agent.md") + print() + + # Use the SDK repo directory which has .claude/agents/test-agent.md + sdk_dir = Path(__file__).parent.parent + + options = ClaudeAgentOptions( + setting_sources=["project"], + cwd=sdk_dir, + ) + + message_types: list[str] = [] + agents_found: list[str] = [] + + async with ClaudeSDKClient(options=options) as client: + await client.query("Say hello in exactly 3 words") + + async for msg in client.receive_response(): + message_types.append(type(msg).__name__) + + if isinstance(msg, SystemMessage) and msg.subtype == "init": + agents_found = extract_agents(msg) + print(f"Init message received. Agents loaded: {agents_found}") + + elif isinstance(msg, AssistantMessage): + for block in msg.content: + if isinstance(block, TextBlock): + print(f"Assistant: {block.text}") + + elif isinstance(msg, ResultMessage): + print( + f"Result: subtype={msg.subtype}, cost=${msg.total_cost_usd or 0:.4f}" + ) + + print() + print("=== Summary ===") + print(f"Message types received: {message_types}") + print(f"Total messages: {len(message_types)}") + + # Validate the results + has_init = "SystemMessage" in message_types + has_assistant = "AssistantMessage" in message_types + has_result = "ResultMessage" in message_types + has_test_agent = "test-agent" in agents_found + + print() + if has_init and has_assistant and has_result: + print("SUCCESS: Received full response (init, assistant, result)") + else: + print("FAILURE: Did not receive full response") + print(f" - Init: {has_init}") + print(f" - Assistant: {has_assistant}") + print(f" - Result: {has_result}") + + if has_test_agent: + print("SUCCESS: test-agent was loaded from filesystem") + else: + print("WARNING: test-agent was NOT loaded (may not exist in .claude/agents/)") + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/scripts/test-docker.sh b/scripts/test-docker.sh new file mode 100755 index 0000000..2cf9889 --- /dev/null +++ b/scripts/test-docker.sh @@ -0,0 +1,77 @@ +#!/bin/bash +# Run SDK tests in a Docker container +# This helps catch Docker-specific issues like #406 +# +# Usage: +# ./scripts/test-docker.sh [unit|e2e|all] +# +# Examples: +# ./scripts/test-docker.sh unit # Run unit tests only +# ANTHROPIC_API_KEY=sk-... ./scripts/test-docker.sh e2e # Run e2e tests +# ANTHROPIC_API_KEY=sk-... ./scripts/test-docker.sh all # Run all tests + +set -e + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PROJECT_DIR="$(dirname "$SCRIPT_DIR")" + +cd "$PROJECT_DIR" + +usage() { + echo "Usage: $0 [unit|e2e|all]" + echo "" + echo "Commands:" + echo " unit - Run unit tests only (no API key needed)" + echo " e2e - Run e2e tests (requires ANTHROPIC_API_KEY)" + echo " all - Run both unit and e2e tests" + echo "" + echo "Examples:" + echo " $0 unit" + echo " ANTHROPIC_API_KEY=sk-... $0 e2e" + exit 1 +} + +echo "Building Docker test image..." +docker build -f Dockerfile.test -t claude-sdk-test . + +case "${1:-unit}" in + unit) + echo "" + echo "Running unit tests in Docker..." + docker run --rm claude-sdk-test \ + python -m pytest tests/ -v + ;; + e2e) + if [ -z "$ANTHROPIC_API_KEY" ]; then + echo "Error: ANTHROPIC_API_KEY environment variable is required for e2e tests" + echo "" + echo "Usage: ANTHROPIC_API_KEY=sk-... $0 e2e" + exit 1 + fi + echo "" + echo "Running e2e tests in Docker..." + docker run --rm -e ANTHROPIC_API_KEY \ + claude-sdk-test python -m pytest e2e-tests/ -v -m e2e + ;; + all) + echo "" + echo "Running unit tests in Docker..." + docker run --rm claude-sdk-test \ + python -m pytest tests/ -v + + echo "" + if [ -n "$ANTHROPIC_API_KEY" ]; then + echo "Running e2e tests in Docker..." + docker run --rm -e ANTHROPIC_API_KEY \ + claude-sdk-test python -m pytest e2e-tests/ -v -m e2e + else + echo "Skipping e2e tests (ANTHROPIC_API_KEY not set)" + fi + ;; + *) + usage + ;; +esac + +echo "" +echo "Done!" From 27575ae2ca7460c6a0f9224350b1f2941704b89d Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Tue, 16 Dec 2025 22:09:36 +0000 Subject: [PATCH 50/55] chore: bump bundled CLI version to 2.0.71 --- src/claude_agent_sdk/_cli_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py index 6309e4c..794eb56 100644 --- a/src/claude_agent_sdk/_cli_version.py +++ b/src/claude_agent_sdk/_cli_version.py @@ -1,3 +1,3 @@ """Bundled Claude Code CLI version.""" -__cli_version__ = "2.0.70" +__cli_version__ = "2.0.71" From 91e65b1927f4d3ab586e6a6eb8ce2d3fc78a152d Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Wed, 17 Dec 2025 21:59:10 +0000 Subject: [PATCH 51/55] chore: bump bundled CLI version to 2.0.72 --- src/claude_agent_sdk/_cli_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py index 794eb56..bcc7288 100644 --- a/src/claude_agent_sdk/_cli_version.py +++ b/src/claude_agent_sdk/_cli_version.py @@ -1,3 +1,3 @@ """Bundled Claude Code CLI version.""" -__cli_version__ = "2.0.71" +__cli_version__ = "2.0.72" From a3df9441286782f2c0fd476aaa99e1233c677ad2 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 17 Dec 2025 17:18:44 -0800 Subject: [PATCH 52/55] chore: release v0.1.18 (#428) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR updates the version to 0.1.18 after publishing to PyPI. ## Changes - Updated version in `pyproject.toml` to 0.1.18 - Updated version in `src/claude_agent_sdk/_version.py` to 0.1.18 - Updated `CHANGELOG.md` with release notes ## Release Information - Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.18/ - Bundled CLI version: 2.0.72 - Install with: `pip install claude-agent-sdk==0.1.18` 🤖 Generated by GitHub Actions --------- Co-authored-by: github-actions[bot] Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com> Co-authored-by: Claude --- CHANGELOG.md | 7 +++++++ pyproject.toml | 2 +- src/claude_agent_sdk/_version.py | 2 +- 3 files changed, 9 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0b0ad22..bfade18 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## 0.1.18 + +### Internal/Other Changes + +- **Docker-based test infrastructure**: Added Docker support for running e2e tests in containerized environments, helping catch Docker-specific issues (#424) +- Updated bundled Claude CLI to version 2.0.72 + ## 0.1.17 ### New Features diff --git a/pyproject.toml b/pyproject.toml index 0f3c76c..9058f3e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "claude-agent-sdk" -version = "0.1.17" +version = "0.1.18" description = "Python SDK for Claude Code" readme = "README.md" requires-python = ">=3.10" diff --git a/src/claude_agent_sdk/_version.py b/src/claude_agent_sdk/_version.py index e60bfef..de9a16c 100644 --- a/src/claude_agent_sdk/_version.py +++ b/src/claude_agent_sdk/_version.py @@ -1,3 +1,3 @@ """Version information for claude-agent-sdk.""" -__version__ = "0.1.17" +__version__ = "0.1.18" From 04347495b8ff309fb384fbf73749cacc1121b619 Mon Sep 17 00:00:00 2001 From: Ashwin Bhat Date: Wed, 17 Dec 2025 17:39:12 -0800 Subject: [PATCH 53/55] fix: resolve YAML syntax error in create-release-tag workflow (#429) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace heredoc with echo statements to fix YAML parsing issue. The unindented heredoc content was breaking out of the literal block scalar, causing `---` to be interpreted as a YAML document separator. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude --- .github/workflows/create-release-tag.yml | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/.github/workflows/create-release-tag.yml b/.github/workflows/create-release-tag.yml index 47f6c82..c50abab 100644 --- a/.github/workflows/create-release-tag.yml +++ b/.github/workflows/create-release-tag.yml @@ -53,16 +53,16 @@ jobs: ' CHANGELOG.md > release_notes.md # Append install instructions - cat >> release_notes.md << 'EOF' - ---- - -**PyPI:** https://pypi.org/project/claude-agent-sdk/VERSION/ - -```bash -pip install claude-agent-sdk==VERSION -``` -EOF + { + echo "" + echo "---" + echo "" + echo "**PyPI:** https://pypi.org/project/claude-agent-sdk/VERSION/" + echo "" + echo '```bash' + echo "pip install claude-agent-sdk==VERSION" + echo '```' + } >> release_notes.md # Replace VERSION placeholder sed -i "s/VERSION/$VERSION/g" release_notes.md From 57e8b6ecd54e4851e3111da4874bfcecec17c6a3 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Fri, 19 Dec 2025 00:16:21 +0000 Subject: [PATCH 54/55] chore: bump bundled CLI version to 2.0.73 --- src/claude_agent_sdk/_cli_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py index bcc7288..c855c1b 100644 --- a/src/claude_agent_sdk/_cli_version.py +++ b/src/claude_agent_sdk/_cli_version.py @@ -1,3 +1,3 @@ """Bundled Claude Code CLI version.""" -__cli_version__ = "2.0.72" +__cli_version__ = "2.0.73" From 3eb12c5a37f09f8fba65271cfbd6233ae100e0c7 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Fri, 19 Dec 2025 22:12:38 +0000 Subject: [PATCH 55/55] chore: bump bundled CLI version to 2.0.74 --- src/claude_agent_sdk/_cli_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py index c855c1b..8e7a72d 100644 --- a/src/claude_agent_sdk/_cli_version.py +++ b/src/claude_agent_sdk/_cli_version.py @@ -1,3 +1,3 @@ """Bundled Claude Code CLI version.""" -__cli_version__ = "2.0.73" +__cli_version__ = "2.0.74"