From 14f0714a8cda7b7a2a2db9868cec8538bb7e79cd Mon Sep 17 00:00:00 2001
From: KuaaMU <138859253+KuaaMU@users.noreply.github.com>
Date: Wed, 8 Oct 2025 07:18:30 +0800
Subject: [PATCH 01/93] Fix Windows test failures due to path separator issues 
 (#219)

- Make test_cli_path_accepts_pathlib_path platform-aware by comparing
with str(path)
- Fix test_build_command_with_add_dirs to check directories individually
- Fix test_build_command_with_mcp_servers_as_file_path to handle Path
conversion
- Fix test_query_with_async_iterable to properly execute Python scripts
on Windows

All tests now pass on both Windows and Unix-like systems (110/110 tests
passing).

Fixes the issue #217 where pathlib.Path automatically converts path
separators based on the operating system, causing test assertions to
fail on Windows.
---
 tests/test_streaming_client.py | 19 ++++++++++++------
 tests/test_transport.py        | 35 ++++++++++++++++++++++------------
 2 files changed, 36 insertions(+), 18 deletions(-)

diff --git a/tests/test_streaming_client.py b/tests/test_streaming_client.py
index 9f636d9..2929441 100644
--- a/tests/test_streaming_client.py
+++ b/tests/test_streaming_client.py
@@ -633,21 +633,28 @@ assert '"Second"' in stdin_messages[1]
 print('{"type": "result", "subtype": "success", "duration_ms": 100, "duration_api_ms": 50, "is_error": false, "num_turns": 1, "session_id": "test", "total_cost_usd": 0.001}')
 """)
 
-            Path(test_script).chmod(0o755)
+            # Make script executable (Unix-style systems)
+            if sys.platform != "win32":
+                Path(test_script).chmod(0o755)
 
             try:
-                # Mock _find_cli to return python executing our test script
+                # Mock _find_cli to return the test script path directly
                 with patch.object(
-                    SubprocessCLITransport, "_find_cli", return_value=sys.executable
+                    SubprocessCLITransport, "_find_cli", return_value=test_script
                 ):
-                    # Mock _build_command to add our test script as first argument
+                    # Mock _build_command to properly execute Python script
                     original_build_command = SubprocessCLITransport._build_command
 
                     def mock_build_command(self):
                         # Get original command
                         cmd = original_build_command(self)
-                        # Replace the CLI path with python + script
-                        cmd[0] = test_script
+                        # On Windows, we need to use python interpreter to run the script
+                        if sys.platform == "win32":
+                            # Replace first element with python interpreter and script
+                            cmd[0:1] = [sys.executable, test_script]
+                        else:
+                            # On Unix, just use the script directly
+                            cmd[0] = test_script
                         return cmd
 
                     with patch.object(
diff --git a/tests/test_transport.py b/tests/test_transport.py
index f46a2ea..93538f4 100644
--- a/tests/test_transport.py
+++ b/tests/test_transport.py
@@ -44,13 +44,15 @@ class TestSubprocessCLITransport:
         """Test that cli_path accepts pathlib.Path objects."""
         from pathlib import Path
 
+        path = Path("/usr/bin/claude")
         transport = SubprocessCLITransport(
             prompt="Hello",
             options=ClaudeAgentOptions(),
-            cli_path=Path("/usr/bin/claude"),
+            cli_path=path,
         )
 
-        assert transport._cli_path == "/usr/bin/claude"
+        # Path object is converted to string, compare with str(path)
+        assert transport._cli_path == str(path)
 
     def test_build_command_with_system_prompt_string(self):
         """Test building CLI command with system prompt as string."""
@@ -129,19 +131,25 @@ class TestSubprocessCLITransport:
         """Test building CLI command with add_dirs option."""
         from pathlib import Path
 
+        dir1 = "/path/to/dir1"
+        dir2 = Path("/path/to/dir2")
         transport = SubprocessCLITransport(
             prompt="test",
-            options=ClaudeAgentOptions(
-                add_dirs=["/path/to/dir1", Path("/path/to/dir2")]
-            ),
+            options=ClaudeAgentOptions(add_dirs=[dir1, dir2]),
             cli_path="/usr/bin/claude",
         )
 
         cmd = transport._build_command()
-        cmd_str = " ".join(cmd)
 
-        # Check that the command string contains the expected --add-dir flags
-        assert "--add-dir /path/to/dir1 --add-dir /path/to/dir2" in cmd_str
+        # Check that both directories are in the command
+        assert "--add-dir" in cmd
+        add_dir_indices = [i for i, x in enumerate(cmd) if x == "--add-dir"]
+        assert len(add_dir_indices) == 2
+
+        # The directories should appear after --add-dir flags
+        dirs_in_cmd = [cmd[i + 1] for i in add_dir_indices]
+        assert dir1 in dirs_in_cmd
+        assert str(dir2) in dirs_in_cmd
 
     def test_session_continuation(self):
         """Test session continuation options."""
@@ -322,28 +330,31 @@ class TestSubprocessCLITransport:
         from pathlib import Path
 
         # Test with string path
+        string_path = "/path/to/mcp-config.json"
         transport = SubprocessCLITransport(
             prompt="test",
-            options=ClaudeAgentOptions(mcp_servers="/path/to/mcp-config.json"),
+            options=ClaudeAgentOptions(mcp_servers=string_path),
             cli_path="/usr/bin/claude",
         )
 
         cmd = transport._build_command()
         assert "--mcp-config" in cmd
         mcp_idx = cmd.index("--mcp-config")
-        assert cmd[mcp_idx + 1] == "/path/to/mcp-config.json"
+        assert cmd[mcp_idx + 1] == string_path
 
         # Test with Path object
+        path_obj = Path("/path/to/mcp-config.json")
         transport = SubprocessCLITransport(
             prompt="test",
-            options=ClaudeAgentOptions(mcp_servers=Path("/path/to/mcp-config.json")),
+            options=ClaudeAgentOptions(mcp_servers=path_obj),
             cli_path="/usr/bin/claude",
         )
 
         cmd = transport._build_command()
         assert "--mcp-config" in cmd
         mcp_idx = cmd.index("--mcp-config")
-        assert cmd[mcp_idx + 1] == "/path/to/mcp-config.json"
+        # Path object gets converted to string, compare with str(path_obj)
+        assert cmd[mcp_idx + 1] == str(path_obj)
 
     def test_build_command_with_mcp_servers_as_json_string(self):
         """Test building CLI command with mcp_servers as JSON string."""

From 6793e40264b076f5592b623ec9a3b5692fea8dff Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Tue, 7 Oct 2025 17:28:24 -0700
Subject: [PATCH 02/93] Add Windows support to test workflows (#222)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add cross-platform testing for Windows alongside Linux across all test
jobs (unit tests, e2e tests, and examples). Uses native Windows
installation via PowerShell script and platform-specific timeout
handling for example scripts.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude <noreply@anthropic.com>
---
 .github/workflows/test.yml            | 43 +++++++++++++++++++++++----
 e2e-tests/test_agents_and_settings.py | 16 +++++++++-
 2 files changed, 53 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 7ccffcb..14933d2 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -8,9 +8,10 @@ on:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
     strategy:
       matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
         python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
@@ -37,10 +38,11 @@ jobs:
           fail_ci_if_error: false
 
   test-e2e:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
     needs: test # Run after unit tests pass
     strategy:
       matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
         python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
@@ -51,11 +53,20 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Install Claude Code
+      - name: Install Claude Code (Linux/macOS)
+        if: runner.os == 'Linux' || runner.os == 'macOS'
         run: |
           curl -fsSL https://claude.ai/install.sh | bash
           echo "$HOME/.local/bin" >> $GITHUB_PATH
 
+      - name: Install Claude Code (Windows)
+        if: runner.os == 'Windows'
+        run: |
+          irm https://claude.ai/install.ps1 | iex
+          $claudePath = "$env:USERPROFILE\.local\bin"
+          echo "$claudePath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+        shell: pwsh
+
       - name: Verify Claude Code installation
         run: claude -v
 
@@ -85,11 +96,20 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Install Claude Code
+      - name: Install Claude Code (Linux)
+        if: runner.os == 'Linux'
         run: |
           curl -fsSL https://claude.ai/install.sh | bash
           echo "$HOME/.local/bin" >> $GITHUB_PATH
 
+      - name: Install Claude Code (Windows)
+        if: runner.os == 'Windows'
+        run: |
+          irm https://claude.ai/install.ps1 | iex
+          $claudePath = "$env:USERPROFILE\.local\bin"
+          echo "$claudePath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+        shell: pwsh
+
       - name: Verify Claude Code installation
         run: claude -v
 
@@ -98,9 +118,22 @@ jobs:
           python -m pip install --upgrade pip
           pip install -e .
 
-      - name: Run example scripts
+      - name: Run example scripts (Linux)
+        if: runner.os == 'Linux'
         env:
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
         run: |
           python examples/quick_start.py
           timeout 120 python examples/streaming_mode.py all
+
+      - name: Run example scripts (Windows)
+        if: runner.os == 'Windows'
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          python examples/quick_start.py
+          $job = Start-Job { python examples/streaming_mode.py all }
+          Wait-Job $job -Timeout 120 | Out-Null
+          Stop-Job $job
+          Receive-Job $job
+        shell: pwsh
diff --git a/e2e-tests/test_agents_and_settings.py b/e2e-tests/test_agents_and_settings.py
index 678ea81..6e04066 100644
--- a/e2e-tests/test_agents_and_settings.py
+++ b/e2e-tests/test_agents_and_settings.py
@@ -1,5 +1,7 @@
 """End-to-end tests for agents and setting sources with real Claude API calls."""
 
+import asyncio
+import sys
 import tempfile
 from pathlib import Path
 
@@ -80,6 +82,10 @@ async def test_setting_sources_default():
                     ), f"outputStyle should be 'default', got: {output_style}"
                     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
@@ -120,6 +126,10 @@ This is a test command.
                     ), f"testcmd should NOT be available with user-only sources, got: {commands}"
                     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
@@ -152,4 +162,8 @@ async def test_setting_sources_project_included():
                     assert (
                         output_style == "local-test-style"
                     ), f"outputStyle should be from local settings, got: {output_style}"
-                    break
\ No newline at end of file
+                    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

From c2b72f1cc5cc59b1ce746c7bc323871575fabcee Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Thu, 9 Oct 2025 08:27:58 -0700
Subject: [PATCH 03/93] Add CHANGELOG entry for version 0.1.1 (#229)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Document the features and improvements released in version 0.1.1,
including minimum Claude Code version check, updated PermissionResult
types, and simplified model references.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
---
 CHANGELOG.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b642093..b31ab68 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -43,6 +43,17 @@ For full migration instructions, see our [migration guide](https://docs.claude.c
 - New guides for [Custom Tools](https://docs.claude.com/en/api/agent-sdk/custom-tools), [Permissions](https://docs.claude.com/en/api/agent-sdk/permissions), [Session Management](https://docs.claude.com/en/api/agent-sdk/sessions), and more
 - Complete [Python API reference](https://docs.claude.com/en/api/agent-sdk/python)
 
+## 0.1.1
+
+### Features
+
+- **Minimum Claude Code version check**: Added version validation to ensure Claude Code 2.0.0+ is installed. The SDK will display a warning if an older version is detected, helping prevent compatibility issues
+- **Updated PermissionResult types**: Aligned permission result types with the latest control protocol for better type safety and compatibility
+
+### Improvements
+
+- **Model references**: Updated all examples and tests to use the simplified `claude-sonnet-4-5` model identifier instead of dated version strings
+
 ## 0.0.22
 
 - Introduce custom tools, implemented as in-process MCP servers.

From 71a85ac9aaac21698a720ff79ebcb3ac0736bf3c Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Thu, 9 Oct 2025 10:36:54 -0700
Subject: [PATCH 04/93] feat: automate changelog updates in release workflow
 (#231)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace GitHub API-based commits with local git workflow and integrate
claude-code-action to automatically generate changelog entries. The
workflow now:
- Creates release branch locally with version commits
- Uses Claude to review changes and update CHANGELOG.md
- Pushes complete branch with all commits together

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude <noreply@anthropic.com>
---
 .github/workflows/publish.yml | 101 +++++++++++++++++++---------------
 CHANGELOG.md                  |  27 +++++----
 2 files changed, 72 insertions(+), 56 deletions(-)

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 36ecc8b..96ffd89 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -104,66 +104,79 @@ jobs:
         echo "Package published to PyPI"
         echo "Install with: pip install claude-agent-sdk==${{ env.VERSION }}"
     
-    - name: Create version update PR
-      env:
-        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    - name: Get previous release tag
+      id: previous_tag
+      run: |
+        PREVIOUS_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+        echo "previous_tag=$PREVIOUS_TAG" >> $GITHUB_OUTPUT
+        echo "Previous release: $PREVIOUS_TAG"
+
+    - name: Create release branch and commit version changes
       run: |
         # Create a new branch for the version update
         BRANCH_NAME="release/v${{ env.VERSION }}"
         echo "BRANCH_NAME=$BRANCH_NAME" >> $GITHUB_ENV
-        
-        # Create branch via API
-        BASE_SHA=$(git rev-parse HEAD)
-        gh api \
-          --method POST \
-          /repos/$GITHUB_REPOSITORY/git/refs \
-          -f ref="refs/heads/$BRANCH_NAME" \
-          -f sha="$BASE_SHA"
-        
-        # Get current SHA values of files
-        echo "Getting SHA for pyproject.toml"
-        PYPROJECT_SHA=$(gh api /repos/$GITHUB_REPOSITORY/contents/pyproject.toml --jq '.sha')
-        echo "Getting SHA for _version.py"
-        VERSION_SHA=$(gh api /repos/$GITHUB_REPOSITORY/contents/src/claude_agent_sdk/_version.py --jq '.sha')
 
-        # Commit pyproject.toml via GitHub API (this creates signed commits)
-        message="chore: bump version to ${{ env.VERSION }}"
-        base64 -i pyproject.toml > pyproject.toml.b64
-        gh api \
-          --method PUT \
-          /repos/$GITHUB_REPOSITORY/contents/pyproject.toml \
-          -f message="$message" \
-          -F content=@pyproject.toml.b64 \
-          -f sha="$PYPROJECT_SHA" \
-          -f branch="$BRANCH_NAME"
+        # Configure git
+        git config --local user.email "github-actions[bot]@users.noreply.github.com"
+        git config --local user.name "github-actions[bot]"
+
+        # Create and switch to new branch
+        git checkout -b "$BRANCH_NAME"
+
+        # Commit version changes
+        git add pyproject.toml src/claude_agent_sdk/_version.py
+        git commit -m "chore: bump version to ${{ env.VERSION }}"
+
+    - name: Update changelog with Claude
+      continue-on-error: true
+      uses: anthropics/claude-code-action@v1
+      with:
+        prompt: |
+          You are updating the changelog for the new release v${{ env.VERSION }}.
+
+          Update CHANGELOG.md to add a new section for version ${{ env.VERSION }} at the top of the file, right after the '# Changelog' heading.
+
+          Review the recent commits and merged pull requests since the last release (${{ steps.previous_tag.outputs.previous_tag }}) to generate meaningful changelog content for v${{ env.VERSION }}. Follow the existing format in CHANGELOG.md with sections like:
+          - Breaking Changes (if any)
+          - New Features
+          - Bug Fixes
+          - Documentation
+          - Internal/Other changes
+
+          Include only the sections that are relevant based on the actual changes. Write clear, user-focused descriptions.
+
+          After updating CHANGELOG.md, commit the changes with the message "docs: update changelog for v${{ env.VERSION }}".
+        anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        claude_args: |
+          --allowedTools 'Bash(git add:*),Bash(git commit:*),Edit'
+
+    - name: Push branch and create PR
+      env:
+        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: |
+        # Push the branch with all commits
+        git push origin "${{ env.BRANCH_NAME }}"
 
-        # Commit _version.py via GitHub API
-        base64 -i src/claude_agent_sdk/_version.py > version.py.b64
-        gh api \
-          --method PUT \
-          /repos/$GITHUB_REPOSITORY/contents/src/claude_agent_sdk/_version.py \
-          -f message="$message" \
-          -F content=@version.py.b64 \
-          -f sha="$VERSION_SHA" \
-          -f branch="$BRANCH_NAME"
-        
         # Create PR using GitHub CLI
         PR_BODY="This PR updates the version to ${{ env.VERSION }} after publishing to PyPI.
-        
+
         ## Changes
         - Updated version in \`pyproject.toml\`
         - Updated version in \`src/claude_agent_sdk/_version.py\`
-        
+        - Updated \`CHANGELOG.md\` with release notes
+
         ## Release Information
         - Published to PyPI: https://pypi.org/project/claude-agent-sdk/${{ env.VERSION }}/
         - Install with: \`pip install claude-agent-sdk==${{ env.VERSION }}\`
-        
+
         🤖 Generated by GitHub Actions"
-        
+
         PR_URL=$(gh pr create \
-          --title "chore: bump version to ${{ env.VERSION }}" \
+          --title "chore: release v${{ env.VERSION }}" \
           --body "$PR_BODY" \
           --base main \
-          --head "$BRANCH_NAME")
-        
+          --head "${{ env.BRANCH_NAME }}")
+
         echo "PR created: $PR_URL"
\ No newline at end of file
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b31ab68..f5b8603 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.1.1
+
+### Features
+
+- **Minimum Claude Code version check**: Added version validation to ensure Claude Code 2.0.0+ is installed. The SDK will display a warning if an older version is detected, helping prevent compatibility issues
+- **Updated PermissionResult types**: Aligned permission result types with the latest control protocol for better type safety and compatibility
+
+### Improvements
+
+- **Model references**: Updated all examples and tests to use the simplified `claude-sonnet-4-5` model identifier instead of dated version strings
+
 ## 0.1.0
 
 Introducing the Claude Agent SDK! The Claude Code SDK has been renamed to better reflect its capabilities for building AI agents across all domains, not just coding.
@@ -7,7 +18,9 @@ Introducing the Claude Agent SDK! The Claude Code SDK has been renamed to better
 ### Breaking Changes
 
 #### Type Name Changes
+
 - **ClaudeCodeOptions renamed to ClaudeAgentOptions**: The options type has been renamed to match the new SDK branding. Update all imports and type references:
+
   ```python
   # Before
   from claude_agent_sdk import query, ClaudeCodeOptions
@@ -19,6 +32,7 @@ Introducing the Claude Agent SDK! The Claude Code SDK has been renamed to better
   ```
 
 #### System Prompt Changes
+
 - **Merged prompt options**: The `custom_system_prompt` and `append_system_prompt` fields have been merged into a single `system_prompt` field for simpler configuration
 - **No default system prompt**: The Claude Code system prompt is no longer included by default, giving you full control over agent behavior. To use the Claude Code system prompt, explicitly set:
   ```python
@@ -26,6 +40,7 @@ Introducing the Claude Agent SDK! The Claude Code SDK has been renamed to better
   ```
 
 #### Settings Isolation
+
 - **No filesystem settings by default**: Settings files (`settings.json`, `CLAUDE.md`), slash commands, and subagents are no longer loaded automatically. This ensures SDK applications have predictable behavior independent of local filesystem configurations
 - **Explicit settings control**: Use the new `setting_sources` field to specify which settings locations to load: `["user", "project", "local"]`
 
@@ -43,17 +58,6 @@ For full migration instructions, see our [migration guide](https://docs.claude.c
 - New guides for [Custom Tools](https://docs.claude.com/en/api/agent-sdk/custom-tools), [Permissions](https://docs.claude.com/en/api/agent-sdk/permissions), [Session Management](https://docs.claude.com/en/api/agent-sdk/sessions), and more
 - Complete [Python API reference](https://docs.claude.com/en/api/agent-sdk/python)
 
-## 0.1.1
-
-### Features
-
-- **Minimum Claude Code version check**: Added version validation to ensure Claude Code 2.0.0+ is installed. The SDK will display a warning if an older version is detected, helping prevent compatibility issues
-- **Updated PermissionResult types**: Aligned permission result types with the latest control protocol for better type safety and compatibility
-
-### Improvements
-
-- **Model references**: Updated all examples and tests to use the simplified `claude-sonnet-4-5` model identifier instead of dated version strings
-
 ## 0.0.22
 
 - Introduce custom tools, implemented as in-process MCP servers.
@@ -91,4 +95,3 @@ For full migration instructions, see our [migration guide](https://docs.claude.c
 - Fix multi-line buffering issue
 - Rename cost_usd to total_cost_usd in API responses
 - Fix optional cost fields handling
-

From dcd51c9ecbc998a3c47703192411a70cfd240fc1 Mon Sep 17 00:00:00 2001
From: Victor Mota <vimota@gmail.com>
Date: Thu, 9 Oct 2025 12:24:13 -0700
Subject: [PATCH 05/93] fix #227: Fix PermissionResultAllow conversion to
 control_response (#232)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

https://github.com/anthropics/claude-agent-sdk-python/issues/227

Fixes zod issues returned by cli subprocess transport - example now runs
correctly to completion:


```
============================================================
Tool Permission Callback Example
============================================================

This example demonstrates how to:
1. Allow/deny tools based on type
2. Modify tool inputs for safety
3. Log tool usage
4. Prompt for unknown tools
============================================================

📝 Sending query to Claude...

📨 Receiving response...

💬 Claude: I'll help you with these tasks. Let me execute them in sequence.

💬 Claude: Now I'll create a simple Python hello world script:

🔧 Tool Permission Request: Write
   Input: {
  "file_path": "/Users/vimota/code/claude-agent-sdk-python/hello.py",
  "content": "#!/usr/bin/env python3\n\nprint(\"Hello, World!\")\n"
}
   ⚠️  Redirecting write from /Users/vimota/code/claude-agent-sdk-python/hello.py to ./safe_output/hello.py

💬 Claude: Now let's run the script:

🔧 Tool Permission Request: Bash
   Input: {
  "command": "python hello.py",
  "description": "Run hello.py script"
}
   ✅ Allowing bash command: python hello.py

💬 Claude: Let me check where the file was created:

💬 Claude: I see the file was created in the `safe_output` directory. Let me run it from there:

🔧 Tool Permission Request: Bash
   Input: {
  "command": "python ./safe_output/hello.py",
  "description": "Run hello.py from safe_output"
}
   ✅ Allowing bash command: python ./safe_output/hello.py

💬 Claude: Perfect! All tasks completed successfully:

1. **Listed files** - The directory contains a Python SDK project with source code in `src/`, tests, examples, and configuration files.

2. **Created hello.py** - A simple Python script was created at `./safe_output/hello.py` with a basic "Hello, World!" print statement.

3. **Ran the script** - The script executed successfully and printed "Hello, World!" to the console.

Note: The file was created in the `safe_output/` subdirectory rather than the root directory.

✅ Task completed!
   Duration: 31158ms
   Cost: $0.0736
   Messages processed: 18

============================================================
Tool Usage Summary
============================================================

1. Tool: Write
   Input: {
      "file_path": "/Users/vimota/code/claude-agent-sdk-python/hello.py",
      "content": "#!/usr/bin/env python3\n\nprint(\"Hello, World!\")\n"
}
   Suggestions: [{'type': 'setMode', 'mode': 'acceptEdits', 'destination': 'session'}]

2. Tool: Bash
   Input: {
      "command": "python hello.py",
      "description": "Run hello.py script"
}
   Suggestions: [{'type': 'addRules', 'rules': [{'toolName': 'Bash', 'ruleContent': 'python:*'}], 'behavior': 'allow', 'destination': 'localSettings'}]

3. Tool: Bash
   Input: {
      "command": "python ./safe_output/hello.py",
      "description": "Run hello.py from safe_output"
}
   Suggestions: [{'type': 'addRules', 'rules': [{'toolName': 'Bash', 'ruleContent': 'python:*'}], 'behavior': 'allow', 'destination': 'localSettings'}]
```
---
 src/claude_agent_sdk/_internal/query.py | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/src/claude_agent_sdk/_internal/query.py b/src/claude_agent_sdk/_internal/query.py
index 5d21dd1..85be30c 100644
--- a/src/claude_agent_sdk/_internal/query.py
+++ b/src/claude_agent_sdk/_internal/query.py
@@ -195,6 +195,7 @@ class Query:
 
             if subtype == "can_use_tool":
                 permission_request: SDKControlPermissionRequest = request_data  # type: ignore[assignment]
+                original_input = permission_request["input"]
                 # Handle tool permission request
                 if not self.can_use_tool:
                     raise Exception("canUseTool callback is not provided")
@@ -213,9 +214,14 @@ class Query:
 
                 # Convert PermissionResult to expected dict format
                 if isinstance(response, PermissionResultAllow):
-                    response_data = {"behavior": "allow"}
-                    if response.updated_input is not None:
-                        response_data["updatedInput"] = response.updated_input
+                    response_data = {
+                        "behavior": "allow",
+                        "updatedInput": (
+                            response.updated_input
+                            if response.updated_input is not None
+                            else original_input
+                        ),
+                    }
                     if response.updated_permissions is not None:
                         response_data["updatedPermissions"] = [
                             permission.to_dict()

From 5bea2dc27dbf167a0bcdde48c5177c0df753631b Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Thu, 9 Oct 2025 17:01:14 -0700
Subject: [PATCH 06/93] chore: temporarily disable Windows CI in test-e2e
 workflow (#234)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Temporarily removes windows-latest from the test-e2e job matrix to
disable Windows end-to-end testing. Unit tests continue to run on
Windows.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
---
 .github/workflows/test.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 14933d2..9822a8f 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -42,7 +42,7 @@ jobs:
     needs: test # Run after unit tests pass
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os: [ubuntu-latest, macos-latest] # windows-latest temporarily disabled
         python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:

From e8d7e71a0a7b03dc6abafd37bf84c913ebdb4616 Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Thu, 9 Oct 2025 18:13:23 -0700
Subject: [PATCH 07/93] Add missing hook output fields to match TypeScript SDK
 (#226)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes the gap between Python and TypeScript SDK hook output types by
adding:
- `reason` field for explaining decisions
- `continue_` field for controlling execution flow
- `suppressOutput` field for hiding stdout
- `stopReason` field for stop explanations
- `decision` now supports both "approve" and "block" (not just "block")
- `AsyncHookJSONOutput` type for deferred hook execution
- Proper typing for `hookSpecificOutput` with discriminated unions

Also adds comprehensive examples and tests:
- New examples in hooks.py demonstrating all new fields
- Unit tests in test_tool_callbacks.py for new output types
- E2E tests in e2e-tests/test_hooks.py with real API calls
- CI integration in .github/workflows/test.yml

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude <noreply@anthropic.com>
---
 .github/workflows/test.yml       |  12 +++
 e2e-tests/test_hooks.py          | 149 ++++++++++++++++++++++++++++
 examples/hooks.py                | 165 +++++++++++++++++++++++++++++++
 src/claude_agent_sdk/__init__.py |   2 +
 src/claude_agent_sdk/types.py    |  74 ++++++++++++--
 tests/test_tool_callbacks.py     | 133 +++++++++++++++++++++++++
 6 files changed, 526 insertions(+), 9 deletions(-)
 create mode 100644 e2e-tests/test_hooks.py

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 9822a8f..75eafa2 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -125,6 +125,8 @@ jobs:
         run: |
           python examples/quick_start.py
           timeout 120 python examples/streaming_mode.py all
+          timeout 120 python examples/hooks.py PreToolUse
+          timeout 120 python examples/hooks.py DecisionFields
 
       - name: Run example scripts (Windows)
         if: runner.os == 'Windows'
@@ -136,4 +138,14 @@ jobs:
           Wait-Job $job -Timeout 120 | Out-Null
           Stop-Job $job
           Receive-Job $job
+
+          $job = Start-Job { python examples/hooks.py PreToolUse }
+          Wait-Job $job -Timeout 120 | Out-Null
+          Stop-Job $job
+          Receive-Job $job
+
+          $job = Start-Job { python examples/hooks.py DecisionFields }
+          Wait-Job $job -Timeout 120 | Out-Null
+          Stop-Job $job
+          Receive-Job $job
         shell: pwsh
diff --git a/e2e-tests/test_hooks.py b/e2e-tests/test_hooks.py
new file mode 100644
index 0000000..a01b65c
--- /dev/null
+++ b/e2e-tests/test_hooks.py
@@ -0,0 +1,149 @@
+"""End-to-end tests for hook callbacks with real Claude API calls."""
+
+import pytest
+
+from claude_agent_sdk import (
+    ClaudeAgentOptions,
+    ClaudeSDKClient,
+    HookContext,
+    HookJSONOutput,
+    HookMatcher,
+)
+
+
+@pytest.mark.e2e
+@pytest.mark.asyncio
+async def test_hook_with_permission_decision_and_reason():
+    """Test that hooks with permissionDecision and reason fields work end-to-end."""
+    hook_invocations = []
+
+    async def test_hook(
+        input_data: dict, tool_use_id: str | None, context: HookContext
+    ) -> HookJSONOutput:
+        """Hook that uses permissionDecision and reason fields."""
+        tool_name = input_data.get("tool_name", "")
+        print(f"Hook called for tool: {tool_name}")
+        hook_invocations.append(tool_name)
+
+        # Block Bash commands for this test
+        if tool_name == "Bash":
+            return {
+                "reason": "Bash commands are blocked in this test for safety",
+                "systemMessage": "⚠️ Command blocked by hook",
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": "Security policy: Bash blocked",
+                },
+            }
+
+        return {
+            "reason": "Tool approved by security review",
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "allow",
+                "permissionDecisionReason": "Tool passed security checks",
+            },
+        }
+
+    options = ClaudeAgentOptions(
+        allowed_tools=["Bash", "Write"],
+        hooks={
+            "PreToolUse": [
+                HookMatcher(matcher="Bash", hooks=[test_hook]),
+            ],
+        },
+    )
+
+    async with ClaudeSDKClient(options=options) as client:
+        await client.query("Run this bash command: echo 'hello'")
+
+        async for message in client.receive_response():
+            print(f"Got message: {message}")
+
+    print(f"Hook invocations: {hook_invocations}")
+    # Verify hook was called
+    assert "Bash" in hook_invocations, f"Hook should have been invoked for Bash tool, got: {hook_invocations}"
+
+
+@pytest.mark.e2e
+@pytest.mark.asyncio
+async def test_hook_with_continue_and_stop_reason():
+    """Test that hooks with continue_=False and stopReason fields work end-to-end."""
+    hook_invocations = []
+
+    async def post_tool_hook(
+        input_data: dict, tool_use_id: str | None, context: HookContext
+    ) -> HookJSONOutput:
+        """PostToolUse hook that stops execution with stopReason."""
+        tool_name = input_data.get("tool_name", "")
+        hook_invocations.append(tool_name)
+
+        # Actually test continue_=False and stopReason fields
+        return {
+            "continue_": False,
+            "stopReason": "Execution halted by test hook for validation",
+            "reason": "Testing continue and stopReason fields",
+            "systemMessage": "🛑 Test hook stopped execution",
+        }
+
+    options = ClaudeAgentOptions(
+        allowed_tools=["Bash"],
+        hooks={
+            "PostToolUse": [
+                HookMatcher(matcher="Bash", hooks=[post_tool_hook]),
+            ],
+        },
+    )
+
+    async with ClaudeSDKClient(options=options) as client:
+        await client.query("Run: echo 'test message'")
+
+        async for message in client.receive_response():
+            print(f"Got message: {message}")
+
+    print(f"Hook invocations: {hook_invocations}")
+    # Verify hook was called
+    assert "Bash" in hook_invocations, f"PostToolUse hook should have been invoked, got: {hook_invocations}"
+
+
+@pytest.mark.e2e
+@pytest.mark.asyncio
+async def test_hook_with_additional_context():
+    """Test that hooks with hookSpecificOutput work end-to-end."""
+    hook_invocations = []
+
+    async def context_hook(
+        input_data: dict, tool_use_id: str | None, context: HookContext
+    ) -> HookJSONOutput:
+        """Hook that provides additional context."""
+        hook_invocations.append("context_added")
+
+        return {
+            "systemMessage": "Additional context provided by hook",
+            "reason": "Hook providing monitoring feedback",
+            "suppressOutput": False,
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": "The command executed successfully with hook monitoring",
+            },
+        }
+
+    options = ClaudeAgentOptions(
+        allowed_tools=["Bash"],
+        hooks={
+            "PostToolUse": [
+                HookMatcher(matcher="Bash", hooks=[context_hook]),
+            ],
+        },
+    )
+
+    async with ClaudeSDKClient(options=options) as client:
+        await client.query("Run: echo 'testing hooks'")
+
+        async for message in client.receive_response():
+            print(f"Got message: {message}")
+
+    print(f"Hook invocations: {hook_invocations}")
+    # Verify hook was called
+    assert "context_added" in hook_invocations, "Hook with hookSpecificOutput should have been invoked"
diff --git a/examples/hooks.py b/examples/hooks.py
index 18bd881..e533ac7 100644
--- a/examples/hooks.py
+++ b/examples/hooks.py
@@ -81,6 +81,77 @@ async def add_custom_instructions(
     }
 
 
+async def review_tool_output(
+    input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
+) -> HookJSONOutput:
+    """Review tool output and provide additional context or warnings."""
+    tool_response = input_data.get("tool_response", "")
+
+    # If the tool produced an error, add helpful context
+    if "error" in str(tool_response).lower():
+        return {
+            "systemMessage": "⚠️ The command produced an error",
+            "reason": "Tool execution failed - consider checking the command syntax",
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": "The command encountered an error. You may want to try a different approach.",
+            }
+        }
+
+    return {}
+
+
+async def strict_approval_hook(
+    input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
+) -> HookJSONOutput:
+    """Demonstrates using permissionDecision to control tool execution."""
+    tool_name = input_data.get("tool_name")
+    tool_input = input_data.get("tool_input", {})
+
+    # Block any Write operations to specific files
+    if tool_name == "Write":
+        file_path = tool_input.get("file_path", "")
+        if "important" in file_path.lower():
+            logger.warning(f"Blocked Write to: {file_path}")
+            return {
+                "reason": "Writes to files containing 'important' in the name are not allowed for safety",
+                "systemMessage": "🚫 Write operation blocked by security policy",
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": "Security policy blocks writes to important files",
+                },
+            }
+
+    # Allow everything else explicitly
+    return {
+        "reason": "Tool use approved after security review",
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "allow",
+            "permissionDecisionReason": "Tool passed security checks",
+        },
+    }
+
+
+async def stop_on_error_hook(
+    input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
+) -> HookJSONOutput:
+    """Demonstrates using continue=False to stop execution on certain conditions."""
+    tool_response = input_data.get("tool_response", "")
+
+    # Stop execution if we see a critical error
+    if "critical" in str(tool_response).lower():
+        logger.error("Critical error detected - stopping execution")
+        return {
+            "continue_": False,
+            "stopReason": "Critical error detected in tool output - execution halted for safety",
+            "systemMessage": "🛑 Execution stopped due to critical error",
+        }
+
+    return {"continue_": True}
+
+
 async def example_pretooluse() -> None:
     """Basic example demonstrating hook protection."""
     print("=== PreToolUse Example ===")
@@ -143,11 +214,99 @@ async def example_userpromptsubmit() -> None:
     print("\n")
 
 
+async def example_posttooluse() -> None:
+    """Demonstrate PostToolUse hook with reason and systemMessage fields."""
+    print("=== PostToolUse Example ===")
+    print("This example shows how PostToolUse can provide feedback with reason and systemMessage.\n")
+
+    options = ClaudeAgentOptions(
+        allowed_tools=["Bash"],
+        hooks={
+            "PostToolUse": [
+                HookMatcher(matcher="Bash", hooks=[review_tool_output]),
+            ],
+        }
+    )
+
+    async with ClaudeSDKClient(options=options) as client:
+        print("User: Run a command that will produce an error: ls /nonexistent_directory")
+        await client.query("Run this command: ls /nonexistent_directory")
+
+        async for msg in client.receive_response():
+            display_message(msg)
+
+    print("\n")
+
+
+async def example_decision_fields() -> None:
+    """Demonstrate permissionDecision, reason, and systemMessage fields."""
+    print("=== Permission Decision Example ===")
+    print("This example shows how to use permissionDecision='allow'/'deny' with reason and systemMessage.\n")
+
+    options = ClaudeAgentOptions(
+        allowed_tools=["Write", "Bash"],
+        model="claude-sonnet-4-5-20250929",
+        hooks={
+            "PreToolUse": [
+                HookMatcher(matcher="Write", hooks=[strict_approval_hook]),
+            ],
+        }
+    )
+
+    async with ClaudeSDKClient(options=options) as client:
+        # Test 1: Try to write to a file with "important" in the name (should be blocked)
+        print("Test 1: Trying to write to important_config.txt (should be blocked)...")
+        print("User: Write 'test' to important_config.txt")
+        await client.query("Write the text 'test data' to a file called important_config.txt")
+
+        async for msg in client.receive_response():
+            display_message(msg)
+
+        print("\n" + "=" * 50 + "\n")
+
+        # Test 2: Write to a regular file (should be approved)
+        print("Test 2: Trying to write to regular_file.txt (should be approved)...")
+        print("User: Write 'test' to regular_file.txt")
+        await client.query("Write the text 'test data' to a file called regular_file.txt")
+
+        async for msg in client.receive_response():
+            display_message(msg)
+
+    print("\n")
+
+
+async def example_continue_control() -> None:
+    """Demonstrate continue and stopReason fields for execution control."""
+    print("=== Continue/Stop Control Example ===")
+    print("This example shows how to use continue_=False with stopReason to halt execution.\n")
+
+    options = ClaudeAgentOptions(
+        allowed_tools=["Bash"],
+        hooks={
+            "PostToolUse": [
+                HookMatcher(matcher="Bash", hooks=[stop_on_error_hook]),
+            ],
+        }
+    )
+
+    async with ClaudeSDKClient(options=options) as client:
+        print("User: Run a command that outputs 'CRITICAL ERROR'")
+        await client.query("Run this bash command: echo 'CRITICAL ERROR: system failure'")
+
+        async for msg in client.receive_response():
+            display_message(msg)
+
+    print("\n")
+
+
 async def main() -> None:
     """Run all examples or a specific example based on command line argument."""
     examples = {
         "PreToolUse": example_pretooluse,
         "UserPromptSubmit": example_userpromptsubmit,
+        "PostToolUse": example_posttooluse,
+        "DecisionFields": example_decision_fields,
+        "ContinueControl": example_continue_control,
     }
 
     if len(sys.argv) < 2:
@@ -157,6 +316,12 @@ async def main() -> None:
         print("  all - Run all examples")
         for name in examples:
             print(f"  {name}")
+        print("\nExample descriptions:")
+        print("  PreToolUse       - Block commands using PreToolUse hook")
+        print("  UserPromptSubmit - Add context at prompt submission")
+        print("  PostToolUse      - Review tool output with reason and systemMessage")
+        print("  DecisionFields   - Use permissionDecision='allow'/'deny' with reason")
+        print("  ContinueControl  - Control execution with continue_ and stopReason")
         sys.exit(0)
 
     example_name = sys.argv[1]
diff --git a/src/claude_agent_sdk/__init__.py b/src/claude_agent_sdk/__init__.py
index 01f5a57..45eccec 100644
--- a/src/claude_agent_sdk/__init__.py
+++ b/src/claude_agent_sdk/__init__.py
@@ -23,6 +23,7 @@ from .types import (
     ContentBlock,
     HookCallback,
     HookContext,
+    HookJSONOutput,
     HookMatcher,
     McpSdkServerConfig,
     McpServerConfig,
@@ -308,6 +309,7 @@ __all__ = [
     "PermissionUpdate",
     "HookCallback",
     "HookContext",
+    "HookJSONOutput",
     "HookMatcher",
     # Agent support
     "AgentDefinition",
diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py
index 4f9c27d..a1cb210 100644
--- a/src/claude_agent_sdk/types.py
+++ b/src/claude_agent_sdk/types.py
@@ -157,18 +157,74 @@ HookEvent = (
 )
 
 
+# Hook-specific output types
+class PreToolUseHookSpecificOutput(TypedDict):
+    """Hook-specific output for PreToolUse events."""
+
+    hookEventName: Literal["PreToolUse"]
+    permissionDecision: NotRequired[Literal["allow", "deny", "ask"]]
+    permissionDecisionReason: NotRequired[str]
+    updatedInput: NotRequired[dict[str, Any]]
+
+
+class PostToolUseHookSpecificOutput(TypedDict):
+    """Hook-specific output for PostToolUse events."""
+
+    hookEventName: Literal["PostToolUse"]
+    additionalContext: NotRequired[str]
+
+
+class UserPromptSubmitHookSpecificOutput(TypedDict):
+    """Hook-specific output for UserPromptSubmit events."""
+
+    hookEventName: Literal["UserPromptSubmit"]
+    additionalContext: NotRequired[str]
+
+
+class SessionStartHookSpecificOutput(TypedDict):
+    """Hook-specific output for SessionStart events."""
+
+    hookEventName: Literal["SessionStart"]
+    additionalContext: NotRequired[str]
+
+
+HookSpecificOutput = (
+    PreToolUseHookSpecificOutput
+    | PostToolUseHookSpecificOutput
+    | UserPromptSubmitHookSpecificOutput
+    | SessionStartHookSpecificOutput
+)
+
+
 # See https://docs.anthropic.com/en/docs/claude-code/hooks#advanced%3A-json-output
-# for documentation of the output types. Currently, "continue", "stopReason",
-# and "suppressOutput" are not supported in the Python SDK.
-class HookJSONOutput(TypedDict):
-    # Whether to block the action related to the hook.
+# for documentation of the output types.
+class AsyncHookJSONOutput(TypedDict):
+    """Async hook output that defers hook execution."""
+
+    async_: Literal[True]  # Using async_ to avoid Python keyword
+    asyncTimeout: NotRequired[int]
+
+
+class SyncHookJSONOutput(TypedDict):
+    """Synchronous hook output with control and decision fields."""
+
+    # Common control fields
+    continue_: NotRequired[bool]  # Using continue_ to avoid Python keyword
+    suppressOutput: NotRequired[bool]
+    stopReason: NotRequired[str]
+
+    # Decision fields
+    # Note: "approve" is deprecated for PreToolUse (use permissionDecision instead)
+    # For other hooks, only "block" is meaningful
     decision: NotRequired[Literal["block"]]
-    # Optionally add a system message that is not visible to Claude but saved in
-    # the chat transcript.
     systemMessage: NotRequired[str]
-    # See each hook's individual "Decision Control" section in the documentation
-    # for guidance.
-    hookSpecificOutput: NotRequired[Any]
+    reason: NotRequired[str]
+
+    # Hook-specific outputs
+    hookSpecificOutput: NotRequired[HookSpecificOutput]
+
+
+HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput
 
 
 @dataclass
diff --git a/tests/test_tool_callbacks.py b/tests/test_tool_callbacks.py
index 8e69fc5..789f420 100644
--- a/tests/test_tool_callbacks.py
+++ b/tests/test_tool_callbacks.py
@@ -1,10 +1,13 @@
 """Tests for tool permission callbacks and hook callbacks."""
 
+import json
+
 import pytest
 
 from claude_agent_sdk import (
     ClaudeAgentOptions,
     HookContext,
+    HookJSONOutput,
     HookMatcher,
     PermissionResultAllow,
     PermissionResultDeny,
@@ -257,6 +260,136 @@ class TestHookCallbacks:
         last_response = transport.written_messages[-1]
         assert '"processed": true' in last_response
 
+    @pytest.mark.asyncio
+    async def test_hook_output_fields(self):
+        """Test that all SyncHookJSONOutput fields are properly handled."""
+
+        # Test all SyncHookJSONOutput fields together
+        async def comprehensive_hook(
+            input_data: dict, tool_use_id: str | None, context: HookContext
+        ) -> HookJSONOutput:
+            return {
+                # Control fields
+                "continue_": True,
+                "suppressOutput": False,
+                "stopReason": "Test stop reason",
+                # Decision fields
+                "decision": "block",
+                "systemMessage": "Test system message",
+                "reason": "Test reason for blocking",
+                # Hook-specific output with all PreToolUse fields
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": "Security policy violation",
+                    "updatedInput": {"modified": "input"},
+                },
+            }
+
+        transport = MockTransport()
+        hooks = {
+            "PreToolUse": [
+                {"matcher": {"tool": "TestTool"}, "hooks": [comprehensive_hook]}
+            ]
+        }
+
+        query = Query(
+            transport=transport, is_streaming_mode=True, can_use_tool=None, hooks=hooks
+        )
+
+        callback_id = "test_comprehensive_hook"
+        query.hook_callbacks[callback_id] = comprehensive_hook
+
+        request = {
+            "type": "control_request",
+            "request_id": "test-comprehensive",
+            "request": {
+                "subtype": "hook_callback",
+                "callback_id": callback_id,
+                "input": {"test": "data"},
+                "tool_use_id": "tool-456",
+            },
+        }
+
+        await query._handle_control_request(request)
+
+        # Check response contains all the fields
+        assert len(transport.written_messages) > 0
+        last_response = transport.written_messages[-1]
+
+        # Parse the JSON response
+        response_data = json.loads(last_response)
+        # The hook result is nested at response.response
+        result = response_data["response"]["response"]
+
+        # Verify control fields are present
+        assert result.get("continue_") is True or result.get("continue") is True
+        assert result.get("suppressOutput") is False
+        assert result.get("stopReason") == "Test stop reason"
+
+        # Verify decision fields are present
+        assert result.get("decision") == "block"
+        assert result.get("reason") == "Test reason for blocking"
+        assert result.get("systemMessage") == "Test system message"
+
+        # Verify hook-specific output is present
+        hook_output = result.get("hookSpecificOutput", {})
+        assert hook_output.get("hookEventName") == "PreToolUse"
+        assert hook_output.get("permissionDecision") == "deny"
+        assert (
+            hook_output.get("permissionDecisionReason") == "Security policy violation"
+        )
+        assert "updatedInput" in hook_output
+
+    @pytest.mark.asyncio
+    async def test_async_hook_output(self):
+        """Test AsyncHookJSONOutput type with proper async fields."""
+
+        async def async_hook(
+            input_data: dict, tool_use_id: str | None, context: HookContext
+        ) -> HookJSONOutput:
+            # Test that async hooks properly use async_ and asyncTimeout fields
+            return {
+                "async_": True,
+                "asyncTimeout": 5000,
+            }
+
+        transport = MockTransport()
+        hooks = {"PreToolUse": [{"matcher": None, "hooks": [async_hook]}]}
+
+        query = Query(
+            transport=transport, is_streaming_mode=True, can_use_tool=None, hooks=hooks
+        )
+
+        callback_id = "test_async_hook"
+        query.hook_callbacks[callback_id] = async_hook
+
+        request = {
+            "type": "control_request",
+            "request_id": "test-async",
+            "request": {
+                "subtype": "hook_callback",
+                "callback_id": callback_id,
+                "input": {"test": "async_data"},
+                "tool_use_id": None,
+            },
+        }
+
+        await query._handle_control_request(request)
+
+        # Check response contains async fields
+        assert len(transport.written_messages) > 0
+        last_response = transport.written_messages[-1]
+
+        # Parse the JSON response
+        response_data = json.loads(last_response)
+        # The hook result is nested at response.response
+        result = response_data["response"]["response"]
+
+        # The SDK should preserve the async_ field (or convert to "async")
+        assert result.get("async_") is True or result.get("async") is True
+        assert result.get("asyncTimeout") == 5000
+
 
 class TestClaudeAgentOptionsIntegration:
     """Test that callbacks work through ClaudeAgentOptions."""

From 67e77e928aab66ddab05d22a59eff9379f2e1db5 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Thu, 9 Oct 2025 19:56:53 -0700
Subject: [PATCH 08/93] chore: release v0.1.2 (#236)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This PR updates the version to 0.1.2 after publishing to PyPI.

## Changes
- Updated version in `pyproject.toml`
- Updated version in `src/claude_agent_sdk/_version.py`
- Updated `CHANGELOG.md` with release notes

## Release Information
- Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.2/
- Install with: `pip install claude-agent-sdk==0.1.2`

🤖 Generated by GitHub Actions

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.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 f5b8603..671f369 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.2
+
+### Bug Fixes
+
+- **Hook output fields**: Added missing hook output fields to match the TypeScript SDK, including `reason`, `continue_`, `suppressOutput`, and `stopReason`. The `decision` field now properly supports both "approve" and "block" values. Added `AsyncHookJSONOutput` type for deferred hook execution and proper typing for `hookSpecificOutput` with discriminated unions
+
 ## 0.1.1
 
 ### Features
diff --git a/pyproject.toml b/pyproject.toml
index ebc3d32..6f551ea 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "claude-agent-sdk"
-version = "0.1.1"
+version = "0.1.2"
 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 748df34..dc599b8 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.1"
+__version__ = "0.1.2"

From 48b62a05a34a349030b7079d7910a5dcc991fb72 Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Fri, 10 Oct 2025 10:25:35 -0700
Subject: [PATCH 09/93] fix: convert Python-safe field names (async_,
 continue_) to CLI format (#239)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixes critical bug where hook outputs using `async_` and `continue_`
(Python-safe names avoiding keyword conflicts) were not being converted
to `async` and `continue` as expected by the CLI. This caused hook
control fields like `{"decision": "block"}` or `{"continue_": False}` to
be silently ignored.

Changes:
- Add _convert_hook_output_for_cli() to handle field name conversion
- Apply conversion in hook callback handling
- Update type documentation to clarify field name usage
- Add comprehensive test coverage for field name conversion
- Update existing tests to verify conversion occurs correctly

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
---
 src/claude_agent_sdk/_internal/query.py | 23 +++++++-
 src/claude_agent_sdk/types.py           | 46 ++++++++++++++--
 tests/test_tool_callbacks.py            | 73 +++++++++++++++++++++++--
 3 files changed, 133 insertions(+), 9 deletions(-)

diff --git a/src/claude_agent_sdk/_internal/query.py b/src/claude_agent_sdk/_internal/query.py
index 85be30c..7646010 100644
--- a/src/claude_agent_sdk/_internal/query.py
+++ b/src/claude_agent_sdk/_internal/query.py
@@ -31,6 +31,25 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
+def _convert_hook_output_for_cli(hook_output: dict[str, Any]) -> dict[str, Any]:
+    """Convert Python-safe field names to CLI-expected field names.
+
+    The Python SDK uses `async_` and `continue_` to avoid keyword conflicts,
+    but the CLI expects `async` and `continue`. This function performs the
+    necessary conversion.
+    """
+    converted = {}
+    for key, value in hook_output.items():
+        # Convert Python-safe names to JavaScript names
+        if key == "async_":
+            converted["async"] = value
+        elif key == "continue_":
+            converted["continue"] = value
+        else:
+            converted[key] = value
+    return converted
+
+
 class Query:
     """Handles bidirectional control protocol on top of Transport.
 
@@ -244,11 +263,13 @@ class Query:
                 if not callback:
                     raise Exception(f"No hook callback found for ID: {callback_id}")
 
-                response_data = await callback(
+                hook_output = await callback(
                     request_data.get("input"),
                     request_data.get("tool_use_id"),
                     {"signal": None},  # TODO: Add abort signal support
                 )
+                # Convert Python-safe field names (async_, continue_) to CLI-expected names (async, continue)
+                response_data = _convert_hook_output_for_cli(hook_output)
 
             elif subtype == "mcp_message":
                 # Handle SDK MCP request
diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py
index a1cb210..3095dfd 100644
--- a/src/claude_agent_sdk/types.py
+++ b/src/claude_agent_sdk/types.py
@@ -198,18 +198,56 @@ HookSpecificOutput = (
 
 # See https://docs.anthropic.com/en/docs/claude-code/hooks#advanced%3A-json-output
 # for documentation of the output types.
+#
+# IMPORTANT: The Python SDK uses `async_` and `continue_` (with underscores) to avoid
+# Python keyword conflicts. These fields are automatically converted to `async` and
+# `continue` when sent to the CLI. You should use the underscore versions in your
+# Python code.
 class AsyncHookJSONOutput(TypedDict):
-    """Async hook output that defers hook execution."""
+    """Async hook output that defers hook execution.
 
-    async_: Literal[True]  # Using async_ to avoid Python keyword
+    Fields:
+        async_: Set to True to defer hook execution. Note: This is converted to
+            "async" when sent to the CLI - use "async_" in your Python code.
+        asyncTimeout: Optional timeout in milliseconds for the async operation.
+    """
+
+    async_: Literal[
+        True
+    ]  # Using async_ to avoid Python keyword (converted to "async" for CLI)
     asyncTimeout: NotRequired[int]
 
 
 class SyncHookJSONOutput(TypedDict):
-    """Synchronous hook output with control and decision fields."""
+    """Synchronous hook output with control and decision fields.
+
+    This defines the structure for hook callbacks to control execution and provide
+    feedback to Claude.
+
+    Common Control Fields:
+        continue_: Whether Claude should proceed after hook execution (default: True).
+            Note: This is converted to "continue" when sent to the CLI.
+        suppressOutput: Hide stdout from transcript mode (default: False).
+        stopReason: Message shown when continue is False.
+
+    Decision Fields:
+        decision: Set to "block" to indicate blocking behavior.
+        systemMessage: Warning message displayed to the user.
+        reason: Feedback message for Claude about the decision.
+
+    Hook-Specific Output:
+        hookSpecificOutput: Event-specific controls (e.g., permissionDecision for
+            PreToolUse, additionalContext for PostToolUse).
+
+    Note: The CLI documentation shows field names without underscores ("async", "continue"),
+    but Python code should use the underscore versions ("async_", "continue_") as they
+    are automatically converted.
+    """
 
     # Common control fields
-    continue_: NotRequired[bool]  # Using continue_ to avoid Python keyword
+    continue_: NotRequired[
+        bool
+    ]  # Using continue_ to avoid Python keyword (converted to "continue" for CLI)
     suppressOutput: NotRequired[bool]
     stopReason: NotRequired[str]
 
diff --git a/tests/test_tool_callbacks.py b/tests/test_tool_callbacks.py
index 789f420..4987ede 100644
--- a/tests/test_tool_callbacks.py
+++ b/tests/test_tool_callbacks.py
@@ -322,8 +322,11 @@ class TestHookCallbacks:
         # The hook result is nested at response.response
         result = response_data["response"]["response"]
 
-        # Verify control fields are present
-        assert result.get("continue_") is True or result.get("continue") is True
+        # Verify control fields are present and converted to CLI format
+        assert result.get("continue") is True, (
+            "continue_ should be converted to continue"
+        )
+        assert "continue_" not in result, "continue_ should not appear in CLI output"
         assert result.get("suppressOutput") is False
         assert result.get("stopReason") == "Test stop reason"
 
@@ -386,10 +389,72 @@ class TestHookCallbacks:
         # The hook result is nested at response.response
         result = response_data["response"]["response"]
 
-        # The SDK should preserve the async_ field (or convert to "async")
-        assert result.get("async_") is True or result.get("async") is True
+        # The SDK should convert async_ to "async" for CLI compatibility
+        assert result.get("async") is True, "async_ should be converted to async"
+        assert "async_" not in result, "async_ should not appear in CLI output"
         assert result.get("asyncTimeout") == 5000
 
+    @pytest.mark.asyncio
+    async def test_field_name_conversion(self):
+        """Test that Python-safe field names (async_, continue_) are converted to CLI format (async, continue)."""
+
+        async def conversion_test_hook(
+            input_data: dict, tool_use_id: str | None, context: HookContext
+        ) -> HookJSONOutput:
+            # Return both async_ and continue_ to test conversion
+            return {
+                "async_": True,
+                "asyncTimeout": 10000,
+                "continue_": False,
+                "stopReason": "Testing field conversion",
+                "systemMessage": "Fields should be converted",
+            }
+
+        transport = MockTransport()
+        hooks = {"PreToolUse": [{"matcher": None, "hooks": [conversion_test_hook]}]}
+
+        query = Query(
+            transport=transport, is_streaming_mode=True, can_use_tool=None, hooks=hooks
+        )
+
+        callback_id = "test_conversion"
+        query.hook_callbacks[callback_id] = conversion_test_hook
+
+        request = {
+            "type": "control_request",
+            "request_id": "test-conversion",
+            "request": {
+                "subtype": "hook_callback",
+                "callback_id": callback_id,
+                "input": {"test": "data"},
+                "tool_use_id": None,
+            },
+        }
+
+        await query._handle_control_request(request)
+
+        # Check response has converted field names
+        assert len(transport.written_messages) > 0
+        last_response = transport.written_messages[-1]
+
+        response_data = json.loads(last_response)
+        result = response_data["response"]["response"]
+
+        # Verify async_ was converted to async
+        assert result.get("async") is True, "async_ should be converted to async"
+        assert "async_" not in result, "async_ should not appear in output"
+
+        # Verify continue_ was converted to continue
+        assert result.get("continue") is False, (
+            "continue_ should be converted to continue"
+        )
+        assert "continue_" not in result, "continue_ should not appear in output"
+
+        # Verify other fields are unchanged
+        assert result.get("asyncTimeout") == 10000
+        assert result.get("stopReason") == "Testing field conversion"
+        assert result.get("systemMessage") == "Fields should be converted"
+
 
 class TestClaudeAgentOptionsIntegration:
     """Test that callbacks work through ClaudeAgentOptions."""

From d754e5cc1db5d40af37ee9b978d333fce55e5fa6 Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Fri, 10 Oct 2025 16:22:13 -0700
Subject: [PATCH 10/93] feat: add strongly-typed hook inputs with TypedDict
 (#240)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add typed hook input structures (PreToolUseHookInput,
PostToolUseHookInput, etc.) to provide better IDE autocomplete and type
safety for hook callbacks. Also convert HookContext from dataclass to
TypedDict to match runtime behavior.

Changes:
- Add BaseHookInput, PreToolUseHookInput, PostToolUseHookInput,
UserPromptSubmitHookInput, StopHookInput, SubagentStopHookInput, and
PreCompactHookInput TypedDict classes
- Update HookCallback signature to use HookInput union type
- Convert HookContext from dataclass to TypedDict (fixes type mismatch)
- Export all new hook input types from __init__.py
- Update all examples and tests to use typed hook inputs

Benefits:
- Zero breaking changes (TypedDict is dict-compatible at runtime)
- Full type safety and IDE autocomplete for hook callbacks
- Matches TypeScript SDK structure exactly
- Self-documenting hook input fields

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
---
 e2e-tests/test_hooks.py          |  7 +--
 examples/hooks.py                | 11 ++--
 src/claude_agent_sdk/__init__.py | 17 ++++++
 src/claude_agent_sdk/types.py    | 88 ++++++++++++++++++++++++++++----
 tests/test_tool_callbacks.py     | 11 ++--
 5 files changed, 111 insertions(+), 23 deletions(-)

diff --git a/e2e-tests/test_hooks.py b/e2e-tests/test_hooks.py
index a01b65c..fda60e9 100644
--- a/e2e-tests/test_hooks.py
+++ b/e2e-tests/test_hooks.py
@@ -6,6 +6,7 @@ from claude_agent_sdk import (
     ClaudeAgentOptions,
     ClaudeSDKClient,
     HookContext,
+    HookInput,
     HookJSONOutput,
     HookMatcher,
 )
@@ -18,7 +19,7 @@ async def test_hook_with_permission_decision_and_reason():
     hook_invocations = []
 
     async def test_hook(
-        input_data: dict, tool_use_id: str | None, context: HookContext
+        input_data: HookInput, tool_use_id: str | None, context: HookContext
     ) -> HookJSONOutput:
         """Hook that uses permissionDecision and reason fields."""
         tool_name = input_data.get("tool_name", "")
@@ -73,7 +74,7 @@ async def test_hook_with_continue_and_stop_reason():
     hook_invocations = []
 
     async def post_tool_hook(
-        input_data: dict, tool_use_id: str | None, context: HookContext
+        input_data: HookInput, tool_use_id: str | None, context: HookContext
     ) -> HookJSONOutput:
         """PostToolUse hook that stops execution with stopReason."""
         tool_name = input_data.get("tool_name", "")
@@ -114,7 +115,7 @@ async def test_hook_with_additional_context():
     hook_invocations = []
 
     async def context_hook(
-        input_data: dict, tool_use_id: str | None, context: HookContext
+        input_data: HookInput, tool_use_id: str | None, context: HookContext
     ) -> HookJSONOutput:
         """Hook that provides additional context."""
         hook_invocations.append("context_added")
diff --git a/examples/hooks.py b/examples/hooks.py
index e533ac7..a8001d4 100644
--- a/examples/hooks.py
+++ b/examples/hooks.py
@@ -19,6 +19,7 @@ from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient
 from claude_agent_sdk.types import (
     AssistantMessage,
     HookContext,
+    HookInput,
     HookJSONOutput,
     HookMatcher,
     Message,
@@ -43,7 +44,7 @@ def display_message(msg: Message) -> None:
 
 ##### Hook callback functions
 async def check_bash_command(
-    input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
+    input_data: HookInput, tool_use_id: str | None, context: HookContext
 ) -> HookJSONOutput:
     """Prevent certain bash commands from being executed."""
     tool_name = input_data["tool_name"]
@@ -70,7 +71,7 @@ async def check_bash_command(
 
 
 async def add_custom_instructions(
-    input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
+    input_data: HookInput, tool_use_id: str | None, context: HookContext
 ) -> HookJSONOutput:
     """Add custom instructions when a session starts."""
     return {
@@ -82,7 +83,7 @@ async def add_custom_instructions(
 
 
 async def review_tool_output(
-    input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
+    input_data: HookInput, tool_use_id: str | None, context: HookContext
 ) -> HookJSONOutput:
     """Review tool output and provide additional context or warnings."""
     tool_response = input_data.get("tool_response", "")
@@ -102,7 +103,7 @@ async def review_tool_output(
 
 
 async def strict_approval_hook(
-    input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
+    input_data: HookInput, tool_use_id: str | None, context: HookContext
 ) -> HookJSONOutput:
     """Demonstrates using permissionDecision to control tool execution."""
     tool_name = input_data.get("tool_name")
@@ -135,7 +136,7 @@ async def strict_approval_hook(
 
 
 async def stop_on_error_hook(
-    input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
+    input_data: HookInput, tool_use_id: str | None, context: HookContext
 ) -> HookJSONOutput:
     """Demonstrates using continue=False to stop execution on certain conditions."""
     tool_response = input_data.get("tool_response", "")
diff --git a/src/claude_agent_sdk/__init__.py b/src/claude_agent_sdk/__init__.py
index 45eccec..6c44747 100644
--- a/src/claude_agent_sdk/__init__.py
+++ b/src/claude_agent_sdk/__init__.py
@@ -18,11 +18,13 @@ from .query import query
 from .types import (
     AgentDefinition,
     AssistantMessage,
+    BaseHookInput,
     CanUseTool,
     ClaudeAgentOptions,
     ContentBlock,
     HookCallback,
     HookContext,
+    HookInput,
     HookJSONOutput,
     HookMatcher,
     McpSdkServerConfig,
@@ -33,8 +35,13 @@ from .types import (
     PermissionResultAllow,
     PermissionResultDeny,
     PermissionUpdate,
+    PostToolUseHookInput,
+    PreCompactHookInput,
+    PreToolUseHookInput,
     ResultMessage,
     SettingSource,
+    StopHookInput,
+    SubagentStopHookInput,
     SystemMessage,
     TextBlock,
     ThinkingBlock,
@@ -42,6 +49,7 @@ from .types import (
     ToolResultBlock,
     ToolUseBlock,
     UserMessage,
+    UserPromptSubmitHookInput,
 )
 
 # MCP Server Support
@@ -307,8 +315,17 @@ __all__ = [
     "PermissionResultAllow",
     "PermissionResultDeny",
     "PermissionUpdate",
+    # Hook support
     "HookCallback",
     "HookContext",
+    "HookInput",
+    "BaseHookInput",
+    "PreToolUseHookInput",
+    "PostToolUseHookInput",
+    "UserPromptSubmitHookInput",
+    "StopHookInput",
+    "SubagentStopHookInput",
+    "PreCompactHookInput",
     "HookJSONOutput",
     "HookMatcher",
     # Agent support
diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py
index 3095dfd..82a57ad 100644
--- a/src/claude_agent_sdk/types.py
+++ b/src/claude_agent_sdk/types.py
@@ -157,6 +157,73 @@ HookEvent = (
 )
 
 
+# Hook input types - strongly typed for each hook event
+class BaseHookInput(TypedDict):
+    """Base hook input fields present across many hook events."""
+
+    session_id: str
+    transcript_path: str
+    cwd: str
+    permission_mode: NotRequired[str]
+
+
+class PreToolUseHookInput(BaseHookInput):
+    """Input data for PreToolUse hook events."""
+
+    hook_event_name: Literal["PreToolUse"]
+    tool_name: str
+    tool_input: dict[str, Any]
+
+
+class PostToolUseHookInput(BaseHookInput):
+    """Input data for PostToolUse hook events."""
+
+    hook_event_name: Literal["PostToolUse"]
+    tool_name: str
+    tool_input: dict[str, Any]
+    tool_response: Any
+
+
+class UserPromptSubmitHookInput(BaseHookInput):
+    """Input data for UserPromptSubmit hook events."""
+
+    hook_event_name: Literal["UserPromptSubmit"]
+    prompt: str
+
+
+class StopHookInput(BaseHookInput):
+    """Input data for Stop hook events."""
+
+    hook_event_name: Literal["Stop"]
+    stop_hook_active: bool
+
+
+class SubagentStopHookInput(BaseHookInput):
+    """Input data for SubagentStop hook events."""
+
+    hook_event_name: Literal["SubagentStop"]
+    stop_hook_active: bool
+
+
+class PreCompactHookInput(BaseHookInput):
+    """Input data for PreCompact hook events."""
+
+    hook_event_name: Literal["PreCompact"]
+    trigger: Literal["manual", "auto"]
+    custom_instructions: str | None
+
+
+# Union type for all hook inputs
+HookInput = (
+    PreToolUseHookInput
+    | PostToolUseHookInput
+    | UserPromptSubmitHookInput
+    | StopHookInput
+    | SubagentStopHookInput
+    | PreCompactHookInput
+)
+
+
 # Hook-specific output types
 class PreToolUseHookSpecificOutput(TypedDict):
     """Hook-specific output for PreToolUse events."""
@@ -265,21 +332,22 @@ class SyncHookJSONOutput(TypedDict):
 HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput
 
 
-@dataclass
-class HookContext:
-    """Context information for hook callbacks."""
+class HookContext(TypedDict):
+    """Context information for hook callbacks.
 
-    signal: Any | None = None  # Future: abort signal support
+    Fields:
+        signal: Reserved for future abort signal support. Currently always None.
+    """
+
+    signal: Any | None  # Future: abort signal support
 
 
 HookCallback = Callable[
     # HookCallback input parameters:
-    # - input
-    #   See https://docs.anthropic.com/en/docs/claude-code/hooks#hook-input for
-    #   the type of 'input', the first value.
-    # - tool_use_id
-    # - context
-    [dict[str, Any], str | None, HookContext],
+    # - input: Strongly-typed hook input with discriminated unions based on hook_event_name
+    # - tool_use_id: Optional tool use identifier
+    # - context: Hook context with abort signal support (currently placeholder)
+    [HookInput, str | None, HookContext],
     Awaitable[HookJSONOutput],
 ]
 
diff --git a/tests/test_tool_callbacks.py b/tests/test_tool_callbacks.py
index 4987ede..8ace3c8 100644
--- a/tests/test_tool_callbacks.py
+++ b/tests/test_tool_callbacks.py
@@ -7,6 +7,7 @@ import pytest
 from claude_agent_sdk import (
     ClaudeAgentOptions,
     HookContext,
+    HookInput,
     HookJSONOutput,
     HookMatcher,
     PermissionResultAllow,
@@ -216,7 +217,7 @@ class TestHookCallbacks:
         hook_calls = []
 
         async def test_hook(
-            input_data: dict, tool_use_id: str | None, context: HookContext
+            input_data: HookInput, tool_use_id: str | None, context: HookContext
         ) -> dict:
             hook_calls.append({"input": input_data, "tool_use_id": tool_use_id})
             return {"processed": True}
@@ -266,7 +267,7 @@ class TestHookCallbacks:
 
         # Test all SyncHookJSONOutput fields together
         async def comprehensive_hook(
-            input_data: dict, tool_use_id: str | None, context: HookContext
+            input_data: HookInput, tool_use_id: str | None, context: HookContext
         ) -> HookJSONOutput:
             return {
                 # Control fields
@@ -349,7 +350,7 @@ class TestHookCallbacks:
         """Test AsyncHookJSONOutput type with proper async fields."""
 
         async def async_hook(
-            input_data: dict, tool_use_id: str | None, context: HookContext
+            input_data: HookInput, tool_use_id: str | None, context: HookContext
         ) -> HookJSONOutput:
             # Test that async hooks properly use async_ and asyncTimeout fields
             return {
@@ -399,7 +400,7 @@ class TestHookCallbacks:
         """Test that Python-safe field names (async_, continue_) are converted to CLI format (async, continue)."""
 
         async def conversion_test_hook(
-            input_data: dict, tool_use_id: str | None, context: HookContext
+            input_data: HookInput, tool_use_id: str | None, context: HookContext
         ) -> HookJSONOutput:
             # Return both async_ and continue_ to test conversion
             return {
@@ -468,7 +469,7 @@ class TestClaudeAgentOptionsIntegration:
             return PermissionResultAllow()
 
         async def my_hook(
-            input_data: dict, tool_use_id: str | None, context: HookContext
+            input_data: HookInput, tool_use_id: str | None, context: HookContext
         ) -> dict:
             return {}
 

From 1f080748d4b28dabbed40e8c7497dd327f4caeca Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Fri, 10 Oct 2025 16:40:58 -0700
Subject: [PATCH 11/93] Revert "chore: temporarily disable Windows CI in
 test-e2e workflow" (#241)

Reverts anthropics/claude-agent-sdk-python#234
---
 .github/workflows/test.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 75eafa2..097d2ad 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -42,7 +42,7 @@ jobs:
     needs: test # Run after unit tests pass
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest] # windows-latest temporarily disabled
+        os: [ubuntu-latest, macos-latest, windows-latest]
         python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:

From 20c1b897344c2a8376936e68259c89818064db5d Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 10 Oct 2025 17:23:14 -0700
Subject: [PATCH 12/93] chore: release v0.1.3 (#242)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This PR updates the version to 0.1.3 after publishing to PyPI.

## Changes
- Updated version in `pyproject.toml`
- Updated version in `src/claude_agent_sdk/_version.py`
- Updated `CHANGELOG.md` with release notes

## Release Information
- Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.3/
- Install with: `pip install claude-agent-sdk==0.1.3`

🤖 Generated by GitHub Actions

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Ashwin Bhat <ashwin@anthropic.com>
---
 CHANGELOG.md                     | 14 ++++++++++++++
 pyproject.toml                   |  2 +-
 src/claude_agent_sdk/_version.py |  2 +-
 3 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 671f369..d827354 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.1.3
+
+### Features
+
+- **Strongly-typed hook inputs**: Added typed hook input structures (`PreToolUseHookInput`, `PostToolUseHookInput`, `UserPromptSubmitHookInput`, etc.) using TypedDict for better IDE autocomplete and type safety. Hook callbacks now receive fully typed input parameters
+
+### Bug Fixes
+
+- **Hook output field conversion**: Fixed bug where Python-safe field names (`async_`, `continue_`) in hook outputs were not being converted to CLI format (`async`, `continue`). This caused hook control fields to be silently ignored, preventing proper hook behavior. The SDK now automatically converts field names when communicating with the CLI
+
+### Internal/Other Changes
+
+- **CI/CD**: Re-enabled Windows testing in the end-to-end test workflow. Windows CI had been temporarily disabled but is now fully operational across all test suites
+
 ## 0.1.2
 
 ### Bug Fixes
diff --git a/pyproject.toml b/pyproject.toml
index 6f551ea..c7cb269 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "claude-agent-sdk"
-version = "0.1.2"
+version = "0.1.3"
 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 dc599b8..344acbc 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.2"
+__version__ = "0.1.3"

From aebcf9d6a43d7611a68a17b3e46a2b46220fac4b Mon Sep 17 00:00:00 2001
From: Chase Naples <cnaples79@gmail.com>
Date: Mon, 13 Oct 2025 02:19:53 -0400
Subject: [PATCH 13/93] feat: add cli_path support to ClaudeAgentOptions (#235)

## Summary
Adds support for passing custom Claude Code CLI paths through
`ClaudeAgentOptions`, allowing organizations with non-standard
installation locations to specify the CLI path explicitly.

## Motivation
As noted in #214, organizations may install Claude Code CLI (or wrapped
versions) at custom locations and prefer to provide those paths instead
of relying on the SDK's default search logic. The transport layer
already supported `cli_path`, but it was never exposed through the
public API.

## Changes
1. **types.py**: Added `cli_path: str | Path | None = None` parameter to
`ClaudeAgentOptions` dataclass
2. **_internal/client.py**: Pass `cli_path` from
`configured_options.cli_path` to `SubprocessCLITransport`
3. **client.py**: Pass `cli_path` from `options.cli_path` to
`SubprocessCLITransport`

## Implementation Details
The `SubprocessCLITransport` constructor already accepted a `cli_path`
parameter (line 40 of subprocess_cli.py), but it was never passed from
the client layers. This PR completes the wiring by:
- Adding the option to the public `ClaudeAgentOptions` interface
- Extracting and passing it through both client implementations
(`InternalClient.process_query` and `ClaudeSDKClient.connect`)

## Usage Example
```python
from claude_agent_sdk import query, ClaudeAgentOptions

# Specify custom CLI path
options = ClaudeAgentOptions(
    cli_path="/custom/path/to/claude"
)

result = await query("Hello!", options=options)
```

## Testing
- No new tests added as this is a straightforward parameter pass-through
- Existing tests should continue to work (default behavior unchanged)
- CI will validate the changes don't break existing functionality

Fixes #214

---------

Co-authored-by: Ashwin Bhat <ashwin@anthropic.com>
---
 src/claude_agent_sdk/_internal/client.py      |  3 +-
 .../_internal/transport/subprocess_cli.py     |  9 ++-
 src/claude_agent_sdk/types.py                 |  1 +
 tests/test_subprocess_buffering.py            | 40 +++++-----
 tests/test_transport.py                       | 73 ++++++++-----------
 5 files changed, 54 insertions(+), 72 deletions(-)

diff --git a/src/claude_agent_sdk/_internal/client.py b/src/claude_agent_sdk/_internal/client.py
index dbb6d19..6dbc877 100644
--- a/src/claude_agent_sdk/_internal/client.py
+++ b/src/claude_agent_sdk/_internal/client.py
@@ -71,7 +71,8 @@ class InternalClient:
             chosen_transport = transport
         else:
             chosen_transport = SubprocessCLITransport(
-                prompt=prompt, options=configured_options
+                prompt=prompt,
+                options=configured_options,
             )
 
         # Connect transport
diff --git a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
index bd9fc59..8cdff4e 100644
--- a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
+++ b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
@@ -37,12 +37,13 @@ class SubprocessCLITransport(Transport):
         self,
         prompt: str | AsyncIterable[dict[str, Any]],
         options: ClaudeAgentOptions,
-        cli_path: str | Path | None = None,
     ):
         self._prompt = prompt
         self._is_streaming = not isinstance(prompt, str)
         self._options = options
-        self._cli_path = str(cli_path) if cli_path else self._find_cli()
+        self._cli_path = (
+            str(options.cli_path) if options.cli_path is not None else self._find_cli()
+        )
         self._cwd = str(options.cwd) if options.cwd else None
         self._process: Process | None = None
         self._stdout_stream: TextReceiveStream | None = None
@@ -79,8 +80,8 @@ class SubprocessCLITransport(Transport):
             "  npm install -g @anthropic-ai/claude-code\n"
             "\nIf already installed locally, try:\n"
             '  export PATH="$HOME/node_modules/.bin:$PATH"\n'
-            "\nOr specify the path when creating transport:\n"
-            "  SubprocessCLITransport(..., cli_path='/path/to/claude')"
+            "\nOr provide the path via ClaudeAgentOptions:\n"
+            "  ClaudeAgentOptions(cli_path='/path/to/claude')"
         )
 
     def _build_command(self) -> list[str]:
diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py
index 82a57ad..be1cb99 100644
--- a/src/claude_agent_sdk/types.py
+++ b/src/claude_agent_sdk/types.py
@@ -512,6 +512,7 @@ class ClaudeAgentOptions:
     model: str | None = None
     permission_prompt_tool_name: str | None = None
     cwd: str | Path | None = None
+    cli_path: str | Path | None = None
     settings: str | None = None
     add_dirs: list[str | Path] = field(default_factory=list)
     env: dict[str, str] = field(default_factory=dict)
diff --git a/tests/test_subprocess_buffering.py b/tests/test_subprocess_buffering.py
index 9437e02..0371074 100644
--- a/tests/test_subprocess_buffering.py
+++ b/tests/test_subprocess_buffering.py
@@ -15,6 +15,15 @@ from claude_agent_sdk._internal.transport.subprocess_cli import (
 )
 from claude_agent_sdk.types import ClaudeAgentOptions
 
+DEFAULT_CLI_PATH = "/usr/bin/claude"
+
+
+def make_options(**kwargs: object) -> ClaudeAgentOptions:
+    """Construct ClaudeAgentOptions with a default CLI path for tests."""
+
+    cli_path = kwargs.pop("cli_path", DEFAULT_CLI_PATH)
+    return ClaudeAgentOptions(cli_path=cli_path, **kwargs)
+
 
 class MockTextReceiveStream:
     """Mock TextReceiveStream for testing."""
@@ -50,9 +59,7 @@ class TestSubprocessBuffering:
 
             buffered_line = json.dumps(json_obj1) + "\n" + json.dumps(json_obj2)
 
-            transport = SubprocessCLITransport(
-                prompt="test", options=ClaudeAgentOptions(), cli_path="/usr/bin/claude"
-            )
+            transport = SubprocessCLITransport(prompt="test", options=make_options())
 
             mock_process = MagicMock()
             mock_process.returncode = None
@@ -85,9 +92,7 @@ class TestSubprocessBuffering:
 
             buffered_line = json.dumps(json_obj1) + "\n" + json.dumps(json_obj2)
 
-            transport = SubprocessCLITransport(
-                prompt="test", options=ClaudeAgentOptions(), cli_path="/usr/bin/claude"
-            )
+            transport = SubprocessCLITransport(prompt="test", options=make_options())
 
             mock_process = MagicMock()
             mock_process.returncode = None
@@ -115,9 +120,7 @@ class TestSubprocessBuffering:
 
             buffered_line = json.dumps(json_obj1) + "\n\n\n" + json.dumps(json_obj2)
 
-            transport = SubprocessCLITransport(
-                prompt="test", options=ClaudeAgentOptions(), cli_path="/usr/bin/claude"
-            )
+            transport = SubprocessCLITransport(prompt="test", options=make_options())
 
             mock_process = MagicMock()
             mock_process.returncode = None
@@ -161,9 +164,7 @@ class TestSubprocessBuffering:
             part2 = complete_json[100:250]
             part3 = complete_json[250:]
 
-            transport = SubprocessCLITransport(
-                prompt="test", options=ClaudeAgentOptions(), cli_path="/usr/bin/claude"
-            )
+            transport = SubprocessCLITransport(prompt="test", options=make_options())
 
             mock_process = MagicMock()
             mock_process.returncode = None
@@ -209,9 +210,7 @@ class TestSubprocessBuffering:
                 for i in range(0, len(complete_json), chunk_size)
             ]
 
-            transport = SubprocessCLITransport(
-                prompt="test", options=ClaudeAgentOptions(), cli_path="/usr/bin/claude"
-            )
+            transport = SubprocessCLITransport(prompt="test", options=make_options())
 
             mock_process = MagicMock()
             mock_process.returncode = None
@@ -239,9 +238,7 @@ class TestSubprocessBuffering:
         async def _test() -> None:
             huge_incomplete = '{"data": "' + "x" * (_DEFAULT_MAX_BUFFER_SIZE + 1000)
 
-            transport = SubprocessCLITransport(
-                prompt="test", options=ClaudeAgentOptions(), cli_path="/usr/bin/claude"
-            )
+            transport = SubprocessCLITransport(prompt="test", options=make_options())
 
             mock_process = MagicMock()
             mock_process.returncode = None
@@ -269,8 +266,7 @@ class TestSubprocessBuffering:
 
             transport = SubprocessCLITransport(
                 prompt="test",
-                options=ClaudeAgentOptions(max_buffer_size=custom_limit),
-                cli_path="/usr/bin/claude",
+                options=make_options(max_buffer_size=custom_limit),
             )
 
             mock_process = MagicMock()
@@ -309,9 +305,7 @@ class TestSubprocessBuffering:
                 large_json[3000:] + "\n" + msg3,
             ]
 
-            transport = SubprocessCLITransport(
-                prompt="test", options=ClaudeAgentOptions(), cli_path="/usr/bin/claude"
-            )
+            transport = SubprocessCLITransport(prompt="test", options=make_options())
 
             mock_process = MagicMock()
             mock_process.returncode = None
diff --git a/tests/test_transport.py b/tests/test_transport.py
index 93538f4..f23dcbf 100644
--- a/tests/test_transport.py
+++ b/tests/test_transport.py
@@ -10,6 +10,15 @@ import pytest
 from claude_agent_sdk._internal.transport.subprocess_cli import SubprocessCLITransport
 from claude_agent_sdk.types import ClaudeAgentOptions
 
+DEFAULT_CLI_PATH = "/usr/bin/claude"
+
+
+def make_options(**kwargs: object) -> ClaudeAgentOptions:
+    """Construct options using the standard CLI path unless overridden."""
+
+    cli_path = kwargs.pop("cli_path", DEFAULT_CLI_PATH)
+    return ClaudeAgentOptions(cli_path=cli_path, **kwargs)
+
 
 class TestSubprocessCLITransport:
     """Test subprocess transport implementation."""
@@ -29,9 +38,7 @@ class TestSubprocessCLITransport:
 
     def test_build_command_basic(self):
         """Test building basic CLI command."""
-        transport = SubprocessCLITransport(
-            prompt="Hello", options=ClaudeAgentOptions(), cli_path="/usr/bin/claude"
-        )
+        transport = SubprocessCLITransport(prompt="Hello", options=make_options())
 
         cmd = transport._build_command()
         assert cmd[0] == "/usr/bin/claude"
@@ -47,8 +54,7 @@ class TestSubprocessCLITransport:
         path = Path("/usr/bin/claude")
         transport = SubprocessCLITransport(
             prompt="Hello",
-            options=ClaudeAgentOptions(),
-            cli_path=path,
+            options=ClaudeAgentOptions(cli_path=path),
         )
 
         # Path object is converted to string, compare with str(path)
@@ -58,10 +64,9 @@ class TestSubprocessCLITransport:
         """Test building CLI command with system prompt as string."""
         transport = SubprocessCLITransport(
             prompt="test",
-            options=ClaudeAgentOptions(
+            options=make_options(
                 system_prompt="Be helpful",
             ),
-            cli_path="/usr/bin/claude",
         )
 
         cmd = transport._build_command()
@@ -72,10 +77,9 @@ class TestSubprocessCLITransport:
         """Test building CLI command with system prompt preset."""
         transport = SubprocessCLITransport(
             prompt="test",
-            options=ClaudeAgentOptions(
+            options=make_options(
                 system_prompt={"type": "preset", "preset": "claude_code"},
             ),
-            cli_path="/usr/bin/claude",
         )
 
         cmd = transport._build_command()
@@ -86,14 +90,13 @@ class TestSubprocessCLITransport:
         """Test building CLI command with system prompt preset and append."""
         transport = SubprocessCLITransport(
             prompt="test",
-            options=ClaudeAgentOptions(
+            options=make_options(
                 system_prompt={
                     "type": "preset",
                     "preset": "claude_code",
                     "append": "Be concise.",
                 },
             ),
-            cli_path="/usr/bin/claude",
         )
 
         cmd = transport._build_command()
@@ -105,14 +108,13 @@ class TestSubprocessCLITransport:
         """Test building CLI command with options."""
         transport = SubprocessCLITransport(
             prompt="test",
-            options=ClaudeAgentOptions(
+            options=make_options(
                 allowed_tools=["Read", "Write"],
                 disallowed_tools=["Bash"],
                 model="claude-sonnet-4-5",
                 permission_mode="acceptEdits",
                 max_turns=5,
             ),
-            cli_path="/usr/bin/claude",
         )
 
         cmd = transport._build_command()
@@ -135,8 +137,7 @@ class TestSubprocessCLITransport:
         dir2 = Path("/path/to/dir2")
         transport = SubprocessCLITransport(
             prompt="test",
-            options=ClaudeAgentOptions(add_dirs=[dir1, dir2]),
-            cli_path="/usr/bin/claude",
+            options=make_options(add_dirs=[dir1, dir2]),
         )
 
         cmd = transport._build_command()
@@ -155,10 +156,7 @@ class TestSubprocessCLITransport:
         """Test session continuation options."""
         transport = SubprocessCLITransport(
             prompt="Continue from before",
-            options=ClaudeAgentOptions(
-                continue_conversation=True, resume="session-123"
-            ),
-            cli_path="/usr/bin/claude",
+            options=make_options(continue_conversation=True, resume="session-123"),
         )
 
         cmd = transport._build_command()
@@ -198,8 +196,7 @@ class TestSubprocessCLITransport:
 
                 transport = SubprocessCLITransport(
                     prompt="test",
-                    options=ClaudeAgentOptions(),
-                    cli_path="/usr/bin/claude",
+                    options=make_options(),
                 )
 
                 await transport.connect()
@@ -215,9 +212,7 @@ class TestSubprocessCLITransport:
         """Test reading messages from CLI output."""
         # This test is simplified to just test the transport creation
         # The full async stream handling is tested in integration tests
-        transport = SubprocessCLITransport(
-            prompt="test", options=ClaudeAgentOptions(), cli_path="/usr/bin/claude"
-        )
+        transport = SubprocessCLITransport(prompt="test", options=make_options())
 
         # The transport now just provides raw message reading via read_messages()
         # So we just verify the transport can be created and basic structure is correct
@@ -231,8 +226,7 @@ class TestSubprocessCLITransport:
         async def _test():
             transport = SubprocessCLITransport(
                 prompt="test",
-                options=ClaudeAgentOptions(cwd="/this/directory/does/not/exist"),
-                cli_path="/usr/bin/claude",
+                options=make_options(cwd="/this/directory/does/not/exist"),
             )
 
             with pytest.raises(CLIConnectionError) as exc_info:
@@ -246,8 +240,7 @@ class TestSubprocessCLITransport:
         """Test building CLI command with settings as file path."""
         transport = SubprocessCLITransport(
             prompt="test",
-            options=ClaudeAgentOptions(settings="/path/to/settings.json"),
-            cli_path="/usr/bin/claude",
+            options=make_options(settings="/path/to/settings.json"),
         )
 
         cmd = transport._build_command()
@@ -259,8 +252,7 @@ class TestSubprocessCLITransport:
         settings_json = '{"permissions": {"allow": ["Bash(ls:*)"]}}'
         transport = SubprocessCLITransport(
             prompt="test",
-            options=ClaudeAgentOptions(settings=settings_json),
-            cli_path="/usr/bin/claude",
+            options=make_options(settings=settings_json),
         )
 
         cmd = transport._build_command()
@@ -271,14 +263,13 @@ class TestSubprocessCLITransport:
         """Test building CLI command with extra_args for future flags."""
         transport = SubprocessCLITransport(
             prompt="test",
-            options=ClaudeAgentOptions(
+            options=make_options(
                 extra_args={
                     "new-flag": "value",
                     "boolean-flag": None,
                     "another-option": "test-value",
                 }
             ),
-            cli_path="/usr/bin/claude",
         )
 
         cmd = transport._build_command()
@@ -309,8 +300,7 @@ class TestSubprocessCLITransport:
 
         transport = SubprocessCLITransport(
             prompt="test",
-            options=ClaudeAgentOptions(mcp_servers=mcp_servers),
-            cli_path="/usr/bin/claude",
+            options=make_options(mcp_servers=mcp_servers),
         )
 
         cmd = transport._build_command()
@@ -333,8 +323,7 @@ class TestSubprocessCLITransport:
         string_path = "/path/to/mcp-config.json"
         transport = SubprocessCLITransport(
             prompt="test",
-            options=ClaudeAgentOptions(mcp_servers=string_path),
-            cli_path="/usr/bin/claude",
+            options=make_options(mcp_servers=string_path),
         )
 
         cmd = transport._build_command()
@@ -346,8 +335,7 @@ class TestSubprocessCLITransport:
         path_obj = Path("/path/to/mcp-config.json")
         transport = SubprocessCLITransport(
             prompt="test",
-            options=ClaudeAgentOptions(mcp_servers=path_obj),
-            cli_path="/usr/bin/claude",
+            options=make_options(mcp_servers=path_obj),
         )
 
         cmd = transport._build_command()
@@ -361,8 +349,7 @@ class TestSubprocessCLITransport:
         json_config = '{"mcpServers": {"server": {"type": "stdio", "command": "test"}}}'
         transport = SubprocessCLITransport(
             prompt="test",
-            options=ClaudeAgentOptions(mcp_servers=json_config),
-            cli_path="/usr/bin/claude",
+            options=make_options(mcp_servers=json_config),
         )
 
         cmd = transport._build_command()
@@ -379,7 +366,7 @@ class TestSubprocessCLITransport:
                 "MY_TEST_VAR": test_value,
             }
 
-            options = ClaudeAgentOptions(env=custom_env)
+            options = make_options(env=custom_env)
 
             # Mock the subprocess to capture the env argument
             with patch(
@@ -408,7 +395,6 @@ class TestSubprocessCLITransport:
                 transport = SubprocessCLITransport(
                     prompt="test",
                     options=options,
-                    cli_path="/usr/bin/claude",
                 )
 
                 await transport.connect()
@@ -440,7 +426,7 @@ class TestSubprocessCLITransport:
 
         async def _test():
             custom_user = "claude"
-            options = ClaudeAgentOptions(user=custom_user)
+            options = make_options(user=custom_user)
 
             # Mock the subprocess to capture the env argument
             with patch(
@@ -469,7 +455,6 @@ class TestSubprocessCLITransport:
                 transport = SubprocessCLITransport(
                     prompt="test",
                     options=options,
-                    cli_path="/usr/bin/claude",
                 )
 
                 await transport.connect()

From f896cd6f7f1d853c71f6f09802d1e4195917b8a2 Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Tue, 14 Oct 2025 09:26:49 -0700
Subject: [PATCH 14/93] feat: add pre-push hook for lint checks (#254)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a committable pre-push hook that runs ruff checks before pushing,
matching the CI lint workflow. Developers run ./scripts/initial-setup.sh
to install the hook locally.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
---
 README.md                | 10 ++++++++++
 scripts/initial-setup.sh | 22 ++++++++++++++++++++++
 scripts/pre-push         | 30 ++++++++++++++++++++++++++++++
 3 files changed, 62 insertions(+)
 create mode 100755 scripts/initial-setup.sh
 create mode 100755 scripts/pre-push

diff --git a/README.md b/README.md
index 80ff1e3..1fcb30d 100644
--- a/README.md
+++ b/README.md
@@ -280,6 +280,16 @@ If you're upgrading from the Claude Code SDK (versions < 0.1.0), please see the
 - Settings isolation and explicit control
 - New programmatic subagents and session forking features
 
+## Development
+
+If you're contributing to this project, run the initial setup script to install git hooks:
+
+```bash
+./scripts/initial-setup.sh
+```
+
+This installs a pre-push hook that runs lint checks before pushing, matching the CI workflow. To skip the hook temporarily, use `git push --no-verify`.
+
 ## License
 
 MIT
diff --git a/scripts/initial-setup.sh b/scripts/initial-setup.sh
new file mode 100755
index 0000000..de6ff60
--- /dev/null
+++ b/scripts/initial-setup.sh
@@ -0,0 +1,22 @@
+#!/bin/bash
+
+# Initial setup script for installing git hooks
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+echo "Setting up git hooks..."
+
+# Install pre-push hook
+echo "→ Installing pre-push hook..."
+cp "$SCRIPT_DIR/pre-push" "$REPO_ROOT/.git/hooks/pre-push"
+chmod +x "$REPO_ROOT/.git/hooks/pre-push"
+echo "✓ pre-push hook installed"
+
+echo ""
+echo "✓ Setup complete!"
+echo ""
+echo "The pre-push hook will now run lint checks before each push."
+echo "To skip the hook temporarily, use: git push --no-verify"
diff --git a/scripts/pre-push b/scripts/pre-push
new file mode 100755
index 0000000..f009b61
--- /dev/null
+++ b/scripts/pre-push
@@ -0,0 +1,30 @@
+#!/bin/bash
+
+# Pre-push hook to run lint checks (matches .github/workflows/lint.yml)
+
+echo "Running lint checks before push..."
+echo ""
+
+# Run ruff check
+echo "→ Running ruff check..."
+python -m ruff check src/ tests/
+if [ $? -ne 0 ]; then
+    echo ""
+    echo "❌ ruff check failed. Fix lint issues before pushing."
+    echo "   Run: python -m ruff check src/ tests/ --fix"
+    exit 1
+fi
+
+# Run ruff format check
+echo "→ Running ruff format check..."
+python -m ruff format --check src/ tests/
+if [ $? -ne 0 ]; then
+    echo ""
+    echo "❌ ruff format check failed. Fix formatting before pushing."
+    echo "   Run: python -m ruff format src/ tests/"
+    exit 1
+fi
+
+echo ""
+echo "✓ All lint checks passed!"
+exit 0

From f27c4ab4c789426940612f3969de0279dc59e7f2 Mon Sep 17 00:00:00 2001
From: Arash Dabiri <48921602+Riehantunut@users.noreply.github.com>
Date: Wed, 15 Oct 2025 16:22:14 +0200
Subject: [PATCH 15/93] feat: Added base64 image handling to sdk_mcp_server
 tool calling (#175)

With this change claude_code_sdk tools can now also return base64
images, in addition to text, following the MCP standard.

For example:
```
import base64

@tool("make_response", "prompt", {"foo": str})
def make_response(args):

    fake_bytes = b"someimagebytes"
    encoded_image = base64.b64encode(fake_bytes).decode("utf-8")

    return {
        "content": [
            {"type": "text", "text": "Hello world!"},
            {
                "type": "image",
                 "mimeType": "image/jpeg",
                 "data": encoded_image,
            },
        ]
    }
```

The image will now be sent to Claude Code when calling the function,
allowing it to react to it.

---------

Co-authored-by: Ashwin Bhat <ashwin@anthropic.com>
---
 src/claude_agent_sdk/__init__.py  | 12 +++++-
 tests/test_sdk_mcp_integration.py | 72 +++++++++++++++++++++++++++++++
 2 files changed, 82 insertions(+), 2 deletions(-)

diff --git a/src/claude_agent_sdk/__init__.py b/src/claude_agent_sdk/__init__.py
index 6c44747..1a5ebf5 100644
--- a/src/claude_agent_sdk/__init__.py
+++ b/src/claude_agent_sdk/__init__.py
@@ -203,7 +203,7 @@ def create_sdk_mcp_server(
         - ClaudeAgentOptions: Configuration for using servers with query()
     """
     from mcp.server import Server
-    from mcp.types import TextContent, Tool
+    from mcp.types import ImageContent, TextContent, Tool
 
     # Create MCP server instance
     server = Server(name, version=version)
@@ -273,11 +273,19 @@ def create_sdk_mcp_server(
             # Convert result to MCP format
             # The decorator expects us to return the content, not a CallToolResult
             # It will wrap our return value in CallToolResult
-            content = []
+            content: list[TextContent | ImageContent] = []
             if "content" in result:
                 for item in result["content"]:
                     if item.get("type") == "text":
                         content.append(TextContent(type="text", text=item["text"]))
+                    if item.get("type") == "image":
+                        content.append(
+                            ImageContent(
+                                type="image",
+                                data=item["data"],
+                                mimeType=item["mimeType"],
+                            )
+                        )
 
             # Return just the content list - the decorator wraps it
             return content
diff --git a/tests/test_sdk_mcp_integration.py b/tests/test_sdk_mcp_integration.py
index b76c8e1..d326007 100644
--- a/tests/test_sdk_mcp_integration.py
+++ b/tests/test_sdk_mcp_integration.py
@@ -4,9 +4,11 @@ This test file verifies that SDK MCP servers work correctly through the full sta
 matching the TypeScript SDK test/sdk.test.ts pattern.
 """
 
+import base64
 from typing import Any
 
 import pytest
+from mcp.types import CallToolRequest, CallToolRequestParams
 
 from claude_agent_sdk import (
     ClaudeAgentOptions,
@@ -191,3 +193,73 @@ async def test_server_creation():
 
     # When no tools are provided, the handlers are not registered
     assert ListToolsRequest not in instance.request_handlers
+
+
+@pytest.mark.asyncio
+async def test_image_content_support():
+    """Test that tools can return image content with base64 data."""
+
+    # Create sample base64 image data (a simple 1x1 pixel PNG)
+    png_data = base64.b64encode(
+        b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01"
+        b"\x08\x02\x00\x00\x00\x90wS\xde\x00\x00\x00\tpHYs\x00\x00\x0b\x13"
+        b"\x00\x00\x0b\x13\x01\x00\x9a\x9c\x18\x00\x00\x00\x0cIDATx\x9cc```"
+        b"\x00\x00\x00\x04\x00\x01]U!\x1c\x00\x00\x00\x00IEND\xaeB`\x82"
+    ).decode("utf-8")
+
+    # Track tool executions
+    tool_executions: list[dict[str, Any]] = []
+
+    # Create a tool that returns both text and image content
+    @tool(
+        "generate_chart", "Generates a chart and returns it as an image", {"title": str}
+    )
+    async def generate_chart(args: dict[str, Any]) -> dict[str, Any]:
+        tool_executions.append({"name": "generate_chart", "args": args})
+        return {
+            "content": [
+                {"type": "text", "text": f"Generated chart: {args['title']}"},
+                {
+                    "type": "image",
+                    "data": png_data,
+                    "mimeType": "image/png",
+                },
+            ]
+        }
+
+    server_config = create_sdk_mcp_server(
+        name="image-test-server", version="1.0.0", tools=[generate_chart]
+    )
+
+    # Get the server instance
+    server = server_config["instance"]
+
+    call_handler = server.request_handlers[CallToolRequest]
+
+    # Call the chart generation tool
+    chart_request = CallToolRequest(
+        method="tools/call",
+        params=CallToolRequestParams(
+            name="generate_chart", arguments={"title": "Sales Report"}
+        ),
+    )
+    result = await call_handler(chart_request)
+
+    # Verify the result contains both text and image content
+    assert len(result.root.content) == 2
+
+    # Check text content
+    text_content = result.root.content[0]
+    assert text_content.type == "text"
+    assert text_content.text == "Generated chart: Sales Report"
+
+    # Check image content
+    image_content = result.root.content[1]
+    assert image_content.type == "image"
+    assert image_content.data == png_data
+    assert image_content.mimeType == "image/png"
+
+    # Verify the tool was executed correctly
+    assert len(tool_executions) == 1
+    assert tool_executions[0]["name"] == "generate_chart"
+    assert tool_executions[0]["args"]["title"] == "Sales Report"

From 923d3d4620a5b8d6abb5bf4b6f00ec5d04a03a41 Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Wed, 15 Oct 2025 14:17:04 -0700
Subject: [PATCH 16/93] feat: add CLAUDE_AGENT_SDK_SKIP_VERSION_CHECK env var
 (#257)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds environment variable to allow skipping the Claude Code version
check. Users can set CLAUDE_AGENT_SDK_SKIP_VERSION_CHECK to disable the
check.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
---
 src/claude_agent_sdk/_internal/transport/subprocess_cli.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
index 8cdff4e..ea2d764 100644
--- a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
+++ b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
@@ -206,7 +206,8 @@ class SubprocessCLITransport(Transport):
         if self._process:
             return
 
-        await self._check_claude_version()
+        if not os.environ.get("CLAUDE_AGENT_SDK_SKIP_VERSION_CHECK"):
+            await self._check_claude_version()
 
         cmd = self._build_command()
         try:

From 41e220cc2cf8ebb398b577220ec210c218539938 Mon Sep 17 00:00:00 2001
From: KuaaMU <138859253+KuaaMU@users.noreply.github.com>
Date: Fri, 24 Oct 2025 01:16:47 +0800
Subject: [PATCH 17/93] fix: handle Windows command line length limit for
 --agents option (#245)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

Fixes #238 - Resolves "command line too long" error on Windows when
using multiple subagents with long prompts.

## Problem

On Windows, the command line length is limited to 8191 characters
(cmd.exe). When using multiple subagents with long prompts, the
`--agents` JSON argument can easily exceed this limit, causing the
error:
```
命令行太长。 (command line too long)
Fatal error in message reader: Command failed with exit code 1
```

## Solution

This PR implements automatic detection and handling of command line
length limits:

1. **Platform-specific limits**:
   - Windows: 8000 characters (safe margin below 8191)
   - Other platforms: 100,000 characters

2. **Automatic fallback**: When the command line would exceed the limit:
   - Write agents JSON to a temporary file
   - Use Claude CLI's `@filepath` syntax to reference the file
   - Clean up temp files when transport is closed

3. **Zero breaking changes**: The fix is transparent to users - it
automatically activates only when needed

## Changes

- Add `platform` and `tempfile` imports
- Add `_CMD_LENGTH_LIMIT` constant with platform-specific values
- Track temporary files in `self._temp_files` list
- Modify `_build_command()` to detect long command lines and use temp
files
- Clean up temp files in `close()` method

## Testing

- ✅ All existing tests pass (122 tests)
- ✅ Linting and type checking pass
- ✅ Minimal changes - only 47 lines added/modified
- ✅ Solution transparently handles the Windows command line limit

## Test plan

- [x] Test on Windows with multiple subagents and long prompts
- [x] Verify temp files are created and cleaned up properly
- [x] Verify normal operation (short command lines) is unaffected
- [x] Test cross-platform compatibility (limit only applies on Windows)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
---
 .../_internal/transport/subprocess_cli.py     | 48 ++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

diff --git a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
index ea2d764..f19403c 100644
--- a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
+++ b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
@@ -3,9 +3,11 @@
 import json
 import logging
 import os
+import platform
 import re
 import shutil
 import sys
+import tempfile
 from collections.abc import AsyncIterable, AsyncIterator
 from contextlib import suppress
 from dataclasses import asdict
@@ -29,6 +31,11 @@ logger = logging.getLogger(__name__)
 _DEFAULT_MAX_BUFFER_SIZE = 1024 * 1024  # 1MB buffer limit
 MINIMUM_CLAUDE_CODE_VERSION = "2.0.0"
 
+# Platform-specific command line length limits
+# Windows cmd.exe has a limit of 8191 characters, use 8000 for safety
+# Other platforms have much higher limits
+_CMD_LENGTH_LIMIT = 8000 if platform.system() == "Windows" else 100000
+
 
 class SubprocessCLITransport(Transport):
     """Subprocess transport using Claude Code CLI."""
@@ -57,6 +64,7 @@ class SubprocessCLITransport(Transport):
             if options.max_buffer_size is not None
             else _DEFAULT_MAX_BUFFER_SIZE
         )
+        self._temp_files: list[str] = []  # Track temporary files for cleanup
 
     def _find_cli(self) -> str:
         """Find Claude Code CLI binary."""
@@ -173,7 +181,8 @@ class SubprocessCLITransport(Transport):
                 name: {k: v for k, v in asdict(agent_def).items() if v is not None}
                 for name, agent_def in self._options.agents.items()
             }
-            cmd.extend(["--agents", json.dumps(agents_dict)])
+            agents_json = json.dumps(agents_dict)
+            cmd.extend(["--agents", agents_json])
 
         sources_value = (
             ",".join(self._options.setting_sources)
@@ -199,6 +208,37 @@ class SubprocessCLITransport(Transport):
             # String mode: use --print with the prompt
             cmd.extend(["--print", "--", str(self._prompt)])
 
+        # Check if command line is too long (Windows limitation)
+        cmd_str = " ".join(cmd)
+        if len(cmd_str) > _CMD_LENGTH_LIMIT and self._options.agents:
+            # Command is too long - use temp file for agents
+            # Find the --agents argument and replace its value with @filepath
+            try:
+                agents_idx = cmd.index("--agents")
+                agents_json_value = cmd[agents_idx + 1]
+
+                # Create a temporary file
+                # ruff: noqa: SIM115
+                temp_file = tempfile.NamedTemporaryFile(
+                    mode="w", suffix=".json", delete=False, encoding="utf-8"
+                )
+                temp_file.write(agents_json_value)
+                temp_file.close()
+
+                # Track for cleanup
+                self._temp_files.append(temp_file.name)
+
+                # Replace agents JSON with @filepath reference
+                cmd[agents_idx + 1] = f"@{temp_file.name}"
+
+                logger.info(
+                    f"Command line length ({len(cmd_str)}) exceeds limit ({_CMD_LENGTH_LIMIT}). "
+                    f"Using temp file for --agents: {temp_file.name}"
+                )
+            except (ValueError, IndexError) as e:
+                # This shouldn't happen, but log it just in case
+                logger.warning(f"Failed to optimize command line length: {e}")
+
         return cmd
 
     async def connect(self) -> None:
@@ -309,6 +349,12 @@ class SubprocessCLITransport(Transport):
         """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):
+                Path(temp_file).unlink(missing_ok=True)
+        self._temp_files.clear()
+
         if not self._process:
             return
 

From 9b8576158dfd8cb74ef1bbe65fda49570c1d8539 Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Thu, 23 Oct 2025 15:03:41 -0700
Subject: [PATCH 18/93] fix: fetch all git history including tags in publish
 workflow (#284)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The changelog generation step was failing to get the previous release
tag because the checkout action was doing a shallow clone. Adding
fetch-depth: 0 ensures all tags are available for git describe.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
---
 .github/workflows/publish.yml | 281 +++++++++++++++++-----------------
 1 file changed, 141 insertions(+), 140 deletions(-)

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 96ffd89..ad70da5 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: 'Version to publish (e.g., 0.1.0)'
+        description: "Version to publish (e.g., 0.1.0)"
         required: true
         type: string
 jobs:
@@ -12,49 +12,49 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.10', '3.11', '3.12', '3.13']
-    
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
     steps:
-    - uses: actions/checkout@v4
-    
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
-      with:
-        python-version: ${{ matrix.python-version }}
-    
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install -e ".[dev]"
-    
-    - name: Run tests
-      run: |
-        python -m pytest tests/ -v
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: |
+          python -m pytest tests/ -v
 
   lint:
     runs-on: ubuntu-latest
-    
+
     steps:
-    - uses: actions/checkout@v4
-    
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.12'
-    
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install -e ".[dev]"
-    
-    - name: Run ruff
-      run: |
-        ruff check src/ tests/
-        ruff format --check src/ tests/
-    
-    - name: Run mypy
-      run: |
-        mypy src/
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run ruff
+        run: |
+          ruff check src/ tests/
+          ruff format --check src/ tests/
+
+      - name: Run mypy
+        run: |
+          mypy src/
 
   publish:
     needs: [test, lint]
@@ -62,121 +62,122 @@ jobs:
     permissions:
       contents: write
       pull-requests: write
-    
+
     steps:
-    - uses: actions/checkout@v4
-      with:
-        token: ${{ secrets.GITHUB_TOKEN }}
-    
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.12'
-    
-    - name: Set version
-      id: version
-      run: |
-        VERSION="${{ github.event.inputs.version }}"
-        echo "VERSION=$VERSION" >> $GITHUB_ENV
-        echo "version=$VERSION" >> $GITHUB_OUTPUT
-    
-    - name: Update version
-      run: |
-        python scripts/update_version.py "${{ env.VERSION }}"
-    
-    - name: Install build dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install build twine
-    
-    - name: Build package
-      run: python -m build
-    
-    - name: Check package
-      run: twine check dist/*
-    
-    - name: Publish to PyPI
-      env:
-        TWINE_USERNAME: __token__
-        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
-      run: |
-        twine upload dist/*
-        echo "Package published to PyPI"
-        echo "Install with: pip install claude-agent-sdk==${{ env.VERSION }}"
-    
-    - name: Get previous release tag
-      id: previous_tag
-      run: |
-        PREVIOUS_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
-        echo "previous_tag=$PREVIOUS_TAG" >> $GITHUB_OUTPUT
-        echo "Previous release: $PREVIOUS_TAG"
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          fetch-depth: 0 # Fetch all history including tags (necessary for changelog generation)
 
-    - name: Create release branch and commit version changes
-      run: |
-        # Create a new branch for the version update
-        BRANCH_NAME="release/v${{ env.VERSION }}"
-        echo "BRANCH_NAME=$BRANCH_NAME" >> $GITHUB_ENV
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
 
-        # Configure git
-        git config --local user.email "github-actions[bot]@users.noreply.github.com"
-        git config --local user.name "github-actions[bot]"
+      - name: Set version
+        id: version
+        run: |
+          VERSION="${{ github.event.inputs.version }}"
+          echo "VERSION=$VERSION" >> $GITHUB_ENV
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
 
-        # Create and switch to new branch
-        git checkout -b "$BRANCH_NAME"
+      - name: Update version
+        run: |
+          python scripts/update_version.py "${{ env.VERSION }}"
 
-        # Commit version changes
-        git add pyproject.toml src/claude_agent_sdk/_version.py
-        git commit -m "chore: bump version to ${{ env.VERSION }}"
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
 
-    - name: Update changelog with Claude
-      continue-on-error: true
-      uses: anthropics/claude-code-action@v1
-      with:
-        prompt: |
-          You are updating the changelog for the new release v${{ env.VERSION }}.
+      - name: Build package
+        run: python -m build
 
-          Update CHANGELOG.md to add a new section for version ${{ env.VERSION }} at the top of the file, right after the '# Changelog' heading.
+      - name: Check package
+        run: twine check dist/*
 
-          Review the recent commits and merged pull requests since the last release (${{ steps.previous_tag.outputs.previous_tag }}) to generate meaningful changelog content for v${{ env.VERSION }}. Follow the existing format in CHANGELOG.md with sections like:
-          - Breaking Changes (if any)
-          - New Features
-          - Bug Fixes
-          - Documentation
-          - Internal/Other changes
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          twine upload dist/*
+          echo "Package published to PyPI"
+          echo "Install with: pip install claude-agent-sdk==${{ env.VERSION }}"
 
-          Include only the sections that are relevant based on the actual changes. Write clear, user-focused descriptions.
+      - name: Get previous release tag
+        id: previous_tag
+        run: |
+          PREVIOUS_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+          echo "previous_tag=$PREVIOUS_TAG" >> $GITHUB_OUTPUT
+          echo "Previous release: $PREVIOUS_TAG"
 
-          After updating CHANGELOG.md, commit the changes with the message "docs: update changelog for v${{ env.VERSION }}".
-        anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        claude_args: |
-          --allowedTools 'Bash(git add:*),Bash(git commit:*),Edit'
+      - name: Create release branch and commit version changes
+        run: |
+          # Create a new branch for the version update
+          BRANCH_NAME="release/v${{ env.VERSION }}"
+          echo "BRANCH_NAME=$BRANCH_NAME" >> $GITHUB_ENV
 
-    - name: Push branch and create PR
-      env:
-        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      run: |
-        # Push the branch with all commits
-        git push origin "${{ env.BRANCH_NAME }}"
+          # Configure git
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
 
-        # Create PR using GitHub CLI
-        PR_BODY="This PR updates the version to ${{ env.VERSION }} after publishing to PyPI.
+          # Create and switch to new branch
+          git checkout -b "$BRANCH_NAME"
 
-        ## Changes
-        - Updated version in \`pyproject.toml\`
-        - Updated version in \`src/claude_agent_sdk/_version.py\`
-        - Updated \`CHANGELOG.md\` with release notes
+          # Commit version changes
+          git add pyproject.toml src/claude_agent_sdk/_version.py
+          git commit -m "chore: bump version to ${{ env.VERSION }}"
 
-        ## Release Information
-        - Published to PyPI: https://pypi.org/project/claude-agent-sdk/${{ env.VERSION }}/
-        - Install with: \`pip install claude-agent-sdk==${{ env.VERSION }}\`
+      - name: Update changelog with Claude
+        continue-on-error: true
+        uses: anthropics/claude-code-action@v1
+        with:
+          prompt: |
+            You are updating the changelog for the new release v${{ env.VERSION }}.
 
-        🤖 Generated by GitHub Actions"
+            Update CHANGELOG.md to add a new section for version ${{ env.VERSION }} at the top of the file, right after the '# Changelog' heading.
 
-        PR_URL=$(gh pr create \
-          --title "chore: release v${{ env.VERSION }}" \
-          --body "$PR_BODY" \
-          --base main \
-          --head "${{ env.BRANCH_NAME }}")
+            Review the recent commits and merged pull requests since the last release (${{ steps.previous_tag.outputs.previous_tag }}) to generate meaningful changelog content for v${{ env.VERSION }}. Follow the existing format in CHANGELOG.md with sections like:
+            - Breaking Changes (if any)
+            - New Features
+            - Bug Fixes
+            - Documentation
+            - Internal/Other changes
 
-        echo "PR created: $PR_URL"
\ No newline at end of file
+            Include only the sections that are relevant based on the actual changes. Write clear, user-focused descriptions.
+
+            After updating CHANGELOG.md, commit the changes with the message "docs: update changelog for v${{ env.VERSION }}".
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          claude_args: |
+            --allowedTools 'Bash(git add:*),Bash(git commit:*),Edit'
+
+      - name: Push branch and create PR
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Push the branch with all commits
+          git push origin "${{ env.BRANCH_NAME }}"
+
+          # Create PR using GitHub CLI
+          PR_BODY="This PR updates the version to ${{ env.VERSION }} after publishing to PyPI.
+
+          ## Changes
+          - Updated version in \`pyproject.toml\`
+          - Updated version in \`src/claude_agent_sdk/_version.py\`
+          - Updated \`CHANGELOG.md\` with release notes
+
+          ## Release Information
+          - Published to PyPI: https://pypi.org/project/claude-agent-sdk/${{ env.VERSION }}/
+          - Install with: \`pip install claude-agent-sdk==${{ env.VERSION }}\`
+
+          🤖 Generated by GitHub Actions"
+
+          PR_URL=$(gh pr create \
+            --title "chore: release v${{ env.VERSION }}" \
+            --body "$PR_BODY" \
+            --base main \
+            --head "${{ env.BRANCH_NAME }}")
+
+          echo "PR created: $PR_URL"

From 5656aeadd6ebe46fabc07c1d6fb57cf5fddb3ccb Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Thu, 23 Oct 2025 16:10:13 -0700
Subject: [PATCH 19/93] chore: release v0.1.4 (#260)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This PR updates the version to 0.1.4 after publishing to PyPI.

## Changes
- Updated version in `pyproject.toml`
- Updated version in `src/claude_agent_sdk/_version.py`
- Updated `CHANGELOG.md` with release notes

## Release Information
- Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.4/
- Install with: `pip install claude-agent-sdk==0.1.4`

🤖 Generated by GitHub Actions

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Ashwin Bhat <ashwin@anthropic.com>
---
 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 d827354..4efd0b5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.4
+
+### Features
+
+- **Skip version check**: Added `CLAUDE_AGENT_SDK_SKIP_VERSION_CHECK` environment variable to allow users to disable the Claude Code version check. Set this environment variable to skip the minimum version validation when the SDK connects to Claude Code. (Only recommended if you already have Claude Code 2.0.0 or higher installed, otherwise some functionality may break)
+- SDK MCP server tool calls can now return image content blocks
+
 ## 0.1.3
 
 ### Features
diff --git a/pyproject.toml b/pyproject.toml
index c7cb269..f7b1e10 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "claude-agent-sdk"
-version = "0.1.3"
+version = "0.1.4"
 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 344acbc..d23e14c 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.3"
+__version__ = "0.1.4"

From c5957634ac20740809f4a978f543e3087c5703f5 Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Fri, 24 Oct 2025 15:29:01 -0700
Subject: [PATCH 20/93] feat: add plugin support to Python SDK (#285)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add SdkPluginConfig type and plugins field to ClaudeAgentOptions.
Plugins can be loaded using the local type with a path to the plugin
directory.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
---
 examples/plugin_example.py                    | 71 +++++++++++++++++++
 .../demo-plugin/.claude-plugin/plugin.json    |  8 +++
 .../plugins/demo-plugin/commands/greet.md     |  5 ++
 src/claude_agent_sdk/__init__.py              |  3 +
 .../_internal/transport/subprocess_cli.py     |  8 +++
 src/claude_agent_sdk/types.py                 | 12 ++++
 6 files changed, 107 insertions(+)
 create mode 100644 examples/plugin_example.py
 create mode 100644 examples/plugins/demo-plugin/.claude-plugin/plugin.json
 create mode 100644 examples/plugins/demo-plugin/commands/greet.md

diff --git a/examples/plugin_example.py b/examples/plugin_example.py
new file mode 100644
index 0000000..ac179f8
--- /dev/null
+++ b/examples/plugin_example.py
@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""Example demonstrating how to use plugins with Claude Code SDK.
+
+Plugins allow you to extend Claude Code with custom commands, agents, skills,
+and hooks. This example shows how to load a local plugin and verify it's
+loaded by checking the system message.
+
+The demo plugin is located in examples/plugins/demo-plugin/ and provides
+a custom /greet command.
+"""
+
+from pathlib import Path
+
+import anyio
+
+from claude_agent_sdk import (
+    ClaudeAgentOptions,
+    SystemMessage,
+    query,
+)
+
+
+async def plugin_example():
+    """Example showing plugins being loaded in the system message."""
+    print("=== Plugin Example ===\n")
+
+    # Get the path to the demo plugin
+    # In production, you can use any path to your plugin directory
+    plugin_path = Path(__file__).parent / "plugins" / "demo-plugin"
+
+    options = ClaudeAgentOptions(
+        plugins=[
+            {
+                "type": "local",
+                "path": str(plugin_path),
+            }
+        ],
+        max_turns=1,  # Limit to one turn for quick demo
+    )
+
+    print(f"Loading plugin from: {plugin_path}\n")
+
+    found_plugins = False
+    async for message in query(prompt="Hello!", options=options):
+        if isinstance(message, SystemMessage) and message.subtype == "init":
+            print("System initialized!")
+            print(f"System message data keys: {list(message.data.keys())}\n")
+
+            # Check for plugins in the system message
+            plugins_data = message.data.get("plugins", [])
+            if plugins_data:
+                print("Plugins loaded:")
+                for plugin in plugins_data:
+                    print(f"  - {plugin.get('name')} (path: {plugin.get('path')})")
+                found_plugins = True
+            else:
+                print("Note: Plugin was passed via CLI but may not appear in system message.")
+                print(f"Plugin path configured: {plugin_path}")
+                found_plugins = True
+
+    if found_plugins:
+        print("\nPlugin successfully configured!\n")
+
+
+async def main():
+    """Run all plugin examples."""
+    await plugin_example()
+
+
+if __name__ == "__main__":
+    anyio.run(main)
diff --git a/examples/plugins/demo-plugin/.claude-plugin/plugin.json b/examples/plugins/demo-plugin/.claude-plugin/plugin.json
new file mode 100644
index 0000000..a33038e
--- /dev/null
+++ b/examples/plugins/demo-plugin/.claude-plugin/plugin.json
@@ -0,0 +1,8 @@
+{
+  "name": "demo-plugin",
+  "description": "A demo plugin showing how to extend Claude Code with custom commands",
+  "version": "1.0.0",
+  "author": {
+    "name": "Claude Code Team"
+  }
+}
diff --git a/examples/plugins/demo-plugin/commands/greet.md b/examples/plugins/demo-plugin/commands/greet.md
new file mode 100644
index 0000000..5274b20
--- /dev/null
+++ b/examples/plugins/demo-plugin/commands/greet.md
@@ -0,0 +1,5 @@
+# Greet Command
+
+This is a custom greeting command from the demo plugin.
+
+When the user runs this command, greet them warmly and explain that this message came from a custom plugin loaded via the Python SDK. Tell them that plugins can be used to extend Claude Code with custom commands, agents, skills, and hooks.
diff --git a/src/claude_agent_sdk/__init__.py b/src/claude_agent_sdk/__init__.py
index 1a5ebf5..cde28be 100644
--- a/src/claude_agent_sdk/__init__.py
+++ b/src/claude_agent_sdk/__init__.py
@@ -39,6 +39,7 @@ from .types import (
     PreCompactHookInput,
     PreToolUseHookInput,
     ResultMessage,
+    SdkPluginConfig,
     SettingSource,
     StopHookInput,
     SubagentStopHookInput,
@@ -339,6 +340,8 @@ __all__ = [
     # Agent support
     "AgentDefinition",
     "SettingSource",
+    # Plugin support
+    "SdkPluginConfig",
     # 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 f19403c..1ec352f 100644
--- a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
+++ b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
@@ -191,6 +191,14 @@ class SubprocessCLITransport(Transport):
         )
         cmd.extend(["--setting-sources", sources_value])
 
+        # Add plugin directories
+        if self._options.plugins:
+            for plugin in self._options.plugins:
+                if plugin["type"] == "local":
+                    cmd.extend(["--plugin-dir", plugin["path"]])
+                else:
+                    raise ValueError(f"Unsupported plugin type: {plugin['type']}")
+
         # Add extra args for future CLI flags
         for flag, value in self._options.extra_args.items():
             if value is None:
diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py
index be1cb99..efeaf70 100644
--- a/src/claude_agent_sdk/types.py
+++ b/src/claude_agent_sdk/types.py
@@ -406,6 +406,16 @@ McpServerConfig = (
 )
 
 
+class SdkPluginConfig(TypedDict):
+    """SDK plugin configuration.
+
+    Currently only local plugins are supported via the 'local' type.
+    """
+
+    type: Literal["local"]
+    path: str
+
+
 # Content block types
 @dataclass
 class TextBlock:
@@ -542,6 +552,8 @@ class ClaudeAgentOptions:
     agents: dict[str, AgentDefinition] | None = None
     # Setting sources to load (user, project, local)
     setting_sources: list[SettingSource] | None = None
+    # Plugin configurations for custom plugins
+    plugins: list[SdkPluginConfig] = field(default_factory=list)
 
 
 # SDK Control Protocol

From 68eb68b740a89dd7846a98902884cfb478bde446 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 24 Oct 2025 16:04:33 -0700
Subject: [PATCH 21/93] chore: release v0.1.5 (#286)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This PR updates the version to 0.1.5 after publishing to PyPI.

## Changes
- Updated version in `pyproject.toml`
- Updated version in `src/claude_agent_sdk/_version.py`
- Updated `CHANGELOG.md` with release notes

## Release Information
- Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.5/
- Install with: `pip install claude-agent-sdk==0.1.5`

🤖 Generated by GitHub Actions

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.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 4efd0b5..d763c43 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.5
+
+### Features
+
+- **Plugin support**: Added the ability to load Claude Code plugins programmatically through the SDK. Plugins can be specified using the new `plugins` field in `ClaudeAgentOptions` with a `SdkPluginConfig` type that supports loading local plugins by path. This enables SDK applications to extend functionality with custom commands and capabilities defined in plugin directories
+
 ## 0.1.4
 
 ### Features
diff --git a/pyproject.toml b/pyproject.toml
index f7b1e10..c28566a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "claude-agent-sdk"
-version = "0.1.4"
+version = "0.1.5"
 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 d23e14c..f241736 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.4"
+__version__ = "0.1.5"

From fd4e33d4b9ae27471f44d761efd7213e78508e82 Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Fri, 24 Oct 2025 16:21:55 -0700
Subject: [PATCH 22/93] feat: add /generate-changelog slash command (#287)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move changelog generation prompt from publish.yml into a reusable slash
command at .claude/commands/generate-changelog.md. Update workflow to
call the command with version parameters.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
---
 .claude/commands/generate-changelog.md | 19 +++++++++++++++++++
 .github/workflows/publish.yml          | 16 +---------------
 2 files changed, 20 insertions(+), 15 deletions(-)
 create mode 100644 .claude/commands/generate-changelog.md

diff --git a/.claude/commands/generate-changelog.md b/.claude/commands/generate-changelog.md
new file mode 100644
index 0000000..3a67279
--- /dev/null
+++ b/.claude/commands/generate-changelog.md
@@ -0,0 +1,19 @@
+---
+allowed-tools: Edit, Bash(git add:*), Bash(git commit:*)
+description: Generate changelog for a new release version
+---
+
+You are updating the changelog for the new release.
+
+Update CHANGELOG.md to add a new section for the new version at the top of the file, right after the '# Changelog' heading.
+
+Review the recent commits and merged pull requests since the last release to generate meaningful changelog content for the new version. Follow the existing format in CHANGELOG.md with sections like:
+- Breaking Changes (if any)
+- New Features
+- Bug Fixes
+- Documentation
+- Internal/Other changes
+
+Include only the sections that are relevant based on the actual changes. Write clear, user-focused descriptions.
+
+After updating CHANGELOG.md, commit the changes with the message "docs: update changelog for v{new_version}".
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index ad70da5..e486645 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -133,21 +133,7 @@ jobs:
         continue-on-error: true
         uses: anthropics/claude-code-action@v1
         with:
-          prompt: |
-            You are updating the changelog for the new release v${{ env.VERSION }}.
-
-            Update CHANGELOG.md to add a new section for version ${{ env.VERSION }} at the top of the file, right after the '# Changelog' heading.
-
-            Review the recent commits and merged pull requests since the last release (${{ steps.previous_tag.outputs.previous_tag }}) to generate meaningful changelog content for v${{ env.VERSION }}. Follow the existing format in CHANGELOG.md with sections like:
-            - Breaking Changes (if any)
-            - New Features
-            - Bug Fixes
-            - Documentation
-            - Internal/Other changes
-
-            Include only the sections that are relevant based on the actual changes. Write clear, user-focused descriptions.
-
-            After updating CHANGELOG.md, commit the changes with the message "docs: update changelog for v${{ env.VERSION }}".
+          prompt: /generate-changelog new version: ${{ env.VERSION }}, old version: ${{ steps.previous_tag.outputs.previous_tag }}
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           github_token: ${{ secrets.GITHUB_TOKEN }}
           claude_args: |

From 7be296f12ed5977b9edff62f79d2884fb3b3666d Mon Sep 17 00:00:00 2001
From: blois <pete@anthropic.com>
Date: Thu, 30 Oct 2025 15:14:42 -0700
Subject: [PATCH 23/93] feat: add max_thinking_tokens option to
 ClaudeAgentOptions (#298)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add support for controlling the maximum number of tokens allocated to
extended thinking blocks via the max_thinking_tokens parameter.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
---
 .gitignore                                            |  1 +
 .../_internal/transport/subprocess_cli.py             |  5 +++++
 src/claude_agent_sdk/types.py                         |  2 ++
 tests/test_transport.py                               | 11 +++++++++++
 4 files changed, 19 insertions(+)

diff --git a/.gitignore b/.gitignore
index 7e6d2df..6be5cc4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -26,6 +26,7 @@ venv/
 ENV/
 env/
 .venv
+uv.lock
 
 # IDEs
 .vscode/
diff --git a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
index 1ec352f..ac0ac83 100644
--- a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
+++ b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
@@ -216,6 +216,11 @@ class SubprocessCLITransport(Transport):
             # String mode: use --print with the prompt
             cmd.extend(["--print", "--", str(self._prompt)])
 
+        if self._options.max_thinking_tokens is not None:
+            cmd.extend(
+                ["--max-thinking-tokens", str(self._options.max_thinking_tokens)]
+            )
+
         # Check if command line is too long (Windows limitation)
         cmd_str = " ".join(cmd)
         if len(cmd_str) > _CMD_LENGTH_LIMIT and self._options.agents:
diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py
index efeaf70..bb551d0 100644
--- a/src/claude_agent_sdk/types.py
+++ b/src/claude_agent_sdk/types.py
@@ -554,6 +554,8 @@ class ClaudeAgentOptions:
     setting_sources: list[SettingSource] | None = None
     # Plugin configurations for custom plugins
     plugins: list[SdkPluginConfig] = field(default_factory=list)
+    # Max tokens for thinking blocks
+    max_thinking_tokens: int | None = None
 
 
 # SDK Control Protocol
diff --git a/tests/test_transport.py b/tests/test_transport.py
index f23dcbf..00ccd90 100644
--- a/tests/test_transport.py
+++ b/tests/test_transport.py
@@ -129,6 +129,17 @@ class TestSubprocessCLITransport:
         assert "--max-turns" in cmd
         assert "5" in cmd
 
+    def test_build_command_with_max_thinking_tokens(self):
+        """Test building CLI command with max_thinking_tokens option."""
+        transport = SubprocessCLITransport(
+            prompt="test",
+            options=make_options(max_thinking_tokens=5000),
+        )
+
+        cmd = transport._build_command()
+        assert "--max-thinking-tokens" in cmd
+        assert "5000" in cmd
+
     def test_build_command_with_add_dirs(self):
         """Test building CLI command with add_dirs option."""
         from pathlib import Path

From ae800c5ec8d0285068b25e73b092f9ef886bc08d Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Thu, 30 Oct 2025 16:45:35 -0700
Subject: [PATCH 24/93] feat: add max_budget_usd option to Python SDK (#293)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add support for limiting API costs using the max_budget_usd option,
mirroring the TypeScript SDK functionality. When the budget is exceeded,
query execution stops and returns a result with subtype
'error_max_budget_usd'.

- Add max_budget_usd field to ClaudeAgentOptions
- Pass --max-budget-usd flag to Claude Code CLI
- Add test coverage for budget limit behavior

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
---
 examples/max_budget_usd.py                    | 95 +++++++++++++++++++
 .../_internal/transport/subprocess_cli.py     |  3 +
 src/claude_agent_sdk/types.py                 |  1 +
 tests/test_integration.py                     | 70 ++++++++++++++
 4 files changed, 169 insertions(+)
 create mode 100644 examples/max_budget_usd.py

diff --git a/examples/max_budget_usd.py b/examples/max_budget_usd.py
new file mode 100644
index 0000000..bb9777e
--- /dev/null
+++ b/examples/max_budget_usd.py
@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""Example demonstrating max_budget_usd option for cost control."""
+
+import anyio
+
+from claude_agent_sdk import (
+    AssistantMessage,
+    ClaudeAgentOptions,
+    ResultMessage,
+    TextBlock,
+    query,
+)
+
+
+async def without_budget():
+    """Example without budget limit."""
+    print("=== Without Budget Limit ===")
+
+    async for message in query(prompt="What is 2 + 2?"):
+        if 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"Total cost: ${message.total_cost_usd:.4f}")
+            print(f"Status: {message.subtype}")
+    print()
+
+
+async def with_reasonable_budget():
+    """Example with budget that won't be exceeded."""
+    print("=== With Reasonable Budget ($0.10) ===")
+
+    options = ClaudeAgentOptions(
+        max_budget_usd=0.10,  # 10 cents - plenty for a simple query
+    )
+
+    async for message in query(prompt="What is 2 + 2?", options=options):
+        if 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"Total cost: ${message.total_cost_usd:.4f}")
+            print(f"Status: {message.subtype}")
+    print()
+
+
+async def with_tight_budget():
+    """Example with very tight budget that will likely be exceeded."""
+    print("=== With Tight Budget ($0.0001) ===")
+
+    options = ClaudeAgentOptions(
+        max_budget_usd=0.0001,  # Very small budget - will be exceeded quickly
+    )
+
+    async for message in query(
+        prompt="Read the README.md file and summarize it", options=options
+    ):
+        if 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"Total cost: ${message.total_cost_usd:.4f}")
+            print(f"Status: {message.subtype}")
+
+            # Check if budget was exceeded
+            if message.subtype == "error_max_budget_usd":
+                print("⚠️  Budget limit exceeded!")
+                print(
+                    "Note: The cost may exceed the budget by up to one API call's worth"
+                )
+    print()
+
+
+async def main():
+    """Run all examples."""
+    print("This example demonstrates using max_budget_usd to control API costs.\n")
+
+    await without_budget()
+    await with_reasonable_budget()
+    await with_tight_budget()
+
+    print(
+        "\nNote: Budget checking happens after each API call completes,\n"
+        "so the final cost may slightly exceed the specified budget.\n"
+    )
+
+
+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 ac0ac83..b6745c1 100644
--- a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
+++ b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
@@ -115,6 +115,9 @@ class SubprocessCLITransport(Transport):
         if self._options.max_turns:
             cmd.extend(["--max-turns", str(self._options.max_turns)])
 
+        if self._options.max_budget_usd is not None:
+            cmd.extend(["--max-budget-usd", str(self._options.max_budget_usd)])
+
         if self._options.disallowed_tools:
             cmd.extend(["--disallowedTools", ",".join(self._options.disallowed_tools)])
 
diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py
index bb551d0..17c1a98 100644
--- a/src/claude_agent_sdk/types.py
+++ b/src/claude_agent_sdk/types.py
@@ -518,6 +518,7 @@ class ClaudeAgentOptions:
     continue_conversation: bool = False
     resume: str | None = None
     max_turns: int | None = None
+    max_budget_usd: float | None = None
     disallowed_tools: list[str] = field(default_factory=list)
     model: str | None = None
     permission_prompt_tool_name: str | None = None
diff --git a/tests/test_integration.py b/tests/test_integration.py
index 8531c9e..1f237dc 100644
--- a/tests/test_integration.py
+++ b/tests/test_integration.py
@@ -212,3 +212,73 @@ class TestIntegration:
                 assert call_kwargs["options"].continue_conversation is True
 
         anyio.run(_test)
+
+    def test_max_budget_usd_option(self):
+        """Test query with max_budget_usd option."""
+
+        async def _test():
+            with patch(
+                "claude_agent_sdk._internal.client.SubprocessCLITransport"
+            ) as mock_transport_class:
+                mock_transport = AsyncMock()
+                mock_transport_class.return_value = mock_transport
+
+                # Mock the message stream that exceeds budget
+                async def mock_receive():
+                    yield {
+                        "type": "assistant",
+                        "message": {
+                            "role": "assistant",
+                            "content": [
+                                {"type": "text", "text": "Starting to read..."}
+                            ],
+                            "model": "claude-opus-4-1-20250805",
+                        },
+                    }
+                    yield {
+                        "type": "result",
+                        "subtype": "error_max_budget_usd",
+                        "duration_ms": 500,
+                        "duration_api_ms": 400,
+                        "is_error": False,
+                        "num_turns": 1,
+                        "session_id": "test-session-budget",
+                        "total_cost_usd": 0.0002,
+                        "usage": {
+                            "input_tokens": 100,
+                            "output_tokens": 50,
+                        },
+                    }
+
+                mock_transport.read_messages = mock_receive
+                mock_transport.connect = AsyncMock()
+                mock_transport.close = AsyncMock()
+                mock_transport.end_input = AsyncMock()
+                mock_transport.write = AsyncMock()
+                mock_transport.is_ready = Mock(return_value=True)
+
+                # Run query with very small budget
+                messages = []
+                async for msg in query(
+                    prompt="Read the readme",
+                    options=ClaudeAgentOptions(max_budget_usd=0.0001),
+                ):
+                    messages.append(msg)
+
+                # Verify results
+                assert len(messages) == 2
+
+                # Check result message
+                assert isinstance(messages[1], ResultMessage)
+                assert messages[1].subtype == "error_max_budget_usd"
+                assert messages[1].is_error is False
+                assert messages[1].total_cost_usd == 0.0002
+                assert messages[1].total_cost_usd is not None
+                assert messages[1].total_cost_usd > 0
+
+                # Verify transport was created with max_budget_usd option
+                mock_transport_class.assert_called_once()
+                call_kwargs = mock_transport_class.call_args.kwargs
+                assert call_kwargs["options"].max_budget_usd == 0.0001
+
+        anyio.run(_test)

From edad138cb0dca6e9d1ca3a804299b3776a7da7a5 Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Thu, 30 Oct 2025 17:05:01 -0700
Subject: [PATCH 25/93] Limit CI examples to Python 3.13 only (#299)

Reduce CI job count by only running examples on Python 3.13 instead of
all Python versions (3.10-3.13). This reduces the combinatorial
explosion while still ensuring examples work on the latest Python
version.

Co-authored-by: Claude <noreply@anthropic.com>
---
 .github/workflows/test.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 097d2ad..d78d425 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -86,7 +86,7 @@ jobs:
     needs: test-e2e # Run after e2e tests
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.13"]
 
     steps:
       - uses: actions/checkout@v4

From 5256af2dac03cc0b73228270f045581b38daebbb Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Thu, 30 Oct 2025 17:05:10 -0700
Subject: [PATCH 26/93] Update publish.yml (#300)

---
 .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 e486645..6b6e16a 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -133,7 +133,7 @@ jobs:
         continue-on-error: true
         uses: anthropics/claude-code-action@v1
         with:
-          prompt: /generate-changelog new version: ${{ env.VERSION }}, old version: ${{ steps.previous_tag.outputs.previous_tag }}
+          prompt: "/generate-changelog new version: ${{ env.VERSION }}, old version: ${{ steps.previous_tag.outputs.previous_tag }}"
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           github_token: ${{ secrets.GITHUB_TOKEN }}
           claude_args: |

From 841f8c0614d3b97bc369fe296b5c9674376552fb Mon Sep 17 00:00:00 2001
From: yokomotod <yokomotod@gmail.com>
Date: Fri, 31 Oct 2025 14:03:42 +0900
Subject: [PATCH 27/93] fix: uses empty system prompt by default (#290)

fix #289
---
 src/claude_agent_sdk/_internal/transport/subprocess_cli.py | 2 +-
 tests/test_transport.py                                    | 2 ++
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
index b6745c1..0eb2f0f 100644
--- a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
+++ b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
@@ -97,7 +97,7 @@ class SubprocessCLITransport(Transport):
         cmd = [self._cli_path, "--output-format", "stream-json", "--verbose"]
 
         if self._options.system_prompt is None:
-            pass
+            cmd.extend(["--system-prompt", ""])
         elif isinstance(self._options.system_prompt, str):
             cmd.extend(["--system-prompt", self._options.system_prompt])
         else:
diff --git a/tests/test_transport.py b/tests/test_transport.py
index 00ccd90..dc6c980 100644
--- a/tests/test_transport.py
+++ b/tests/test_transport.py
@@ -46,6 +46,8 @@ class TestSubprocessCLITransport:
         assert "stream-json" in cmd
         assert "--print" in cmd
         assert "Hello" in cmd
+        assert "--system-prompt" in cmd
+        assert cmd[cmd.index("--system-prompt") + 1] == ""
 
     def test_cli_path_accepts_pathlib_path(self):
         """Test that cli_path accepts pathlib.Path objects."""

From c30ffbeb56778b86701abc414bc03e1ac2ba2faa Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Thu, 30 Oct 2025 22:40:51 -0700
Subject: [PATCH 28/93] chore: release v0.1.6 (#301)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This PR updates the version to 0.1.6 after publishing to PyPI.

## Changes
- Updated version in `pyproject.toml`
- Updated version in `src/claude_agent_sdk/_version.py`
- Updated `CHANGELOG.md` with release notes

## Release Information
- Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.6/
- Install with: `pip install claude-agent-sdk==0.1.6`

🤖 Generated by GitHub Actions

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Ashwin Bhat <ashwin@anthropic.com>
---
 CHANGELOG.md                     | 11 +++++++++++
 pyproject.toml                   |  2 +-
 src/claude_agent_sdk/_version.py |  2 +-
 3 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d763c43..82c8765 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.1.6
+
+### Features
+
+- **Max budget control**: Added `max_budget_usd` option to set a maximum spending limit in USD for SDK sessions. When the budget is exceeded, the session will automatically terminate, helping prevent unexpected costs (#293)
+- **Extended thinking configuration**: Added `max_thinking_tokens` option to control the maximum number of tokens allocated for Claude's internal reasoning process. This allows fine-tuning of the balance between response quality and token usage (#298)
+
+### Bug Fixes
+
+- **System prompt defaults**: Fixed issue where a default system prompt was being used when none was specified. The SDK now correctly uses an empty system prompt by default, giving users full control over agent behavior (#290)
+
 ## 0.1.5
 
 ### Features
diff --git a/pyproject.toml b/pyproject.toml
index c28566a..cc9b99d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "claude-agent-sdk"
-version = "0.1.5"
+version = "0.1.6"
 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 f241736..89470e1 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.5"
+__version__ = "0.1.6"

From 5a4cc2f41a484223e5e19bcd80e0b7caa0bf1c63 Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Fri, 31 Oct 2025 08:52:17 -0700
Subject: [PATCH 29/93] feat: add support for Claude CLI at
 ~/.claude/local/claude (#302)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add ~/.claude/local/claude to the list of locations checked when finding
the Claude CLI binary.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
---
 src/claude_agent_sdk/_internal/transport/subprocess_cli.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
index 0eb2f0f..0fc02b5 100644
--- a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
+++ b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
@@ -77,6 +77,7 @@ class SubprocessCLITransport(Transport):
             Path.home() / ".local/bin/claude",
             Path.home() / "node_modules/.bin/claude",
             Path.home() / ".yarn/bin/claude",
+            Path.home() / ".claude/local/claude",
         ]
 
         for path in locations:

From ff425b293d6a79dfe972ef8a5247b43fc94589be Mon Sep 17 00:00:00 2001
From: Suzanne Wang <suzanneswang@gmail.com>
Date: Fri, 7 Nov 2025 11:25:45 -0800
Subject: [PATCH 30/93] Add fallback model handling for parity with TypeScript
 SDK (#317)

Add support for automatic model fallback when primary model is
overloaded. The Python SDK passes the fallback_model parameter to the
Claude CLI, which handles the validation and fallback logic.

Changes:
- Add fallback_model parameter to ClaudeAgentOptions
- Pass --fallback-model to CLI subprocess
- Add test for fallback model command building

The validation that fallback_model != model happens at the CLI layer,
keeping the SDK implementation simple and focused on parameter passing.

---------

Co-authored-by: Claude <noreply@anthropic.com>
---
 .../_internal/transport/subprocess_cli.py        |  3 +++
 src/claude_agent_sdk/types.py                    |  1 +
 tests/test_transport.py                          | 16 ++++++++++++++++
 3 files changed, 20 insertions(+)

diff --git a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
index 0fc02b5..d669a41 100644
--- a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
+++ b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
@@ -125,6 +125,9 @@ class SubprocessCLITransport(Transport):
         if self._options.model:
             cmd.extend(["--model", self._options.model])
 
+        if self._options.fallback_model:
+            cmd.extend(["--fallback-model", self._options.fallback_model])
+
         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 17c1a98..e375bee 100644
--- a/src/claude_agent_sdk/types.py
+++ b/src/claude_agent_sdk/types.py
@@ -521,6 +521,7 @@ class ClaudeAgentOptions:
     max_budget_usd: float | None = None
     disallowed_tools: list[str] = field(default_factory=list)
     model: str | None = None
+    fallback_model: str | None = None
     permission_prompt_tool_name: str | None = None
     cwd: str | Path | None = None
     cli_path: str | Path | None = None
diff --git a/tests/test_transport.py b/tests/test_transport.py
index dc6c980..a5a80d0 100644
--- a/tests/test_transport.py
+++ b/tests/test_transport.py
@@ -131,6 +131,22 @@ class TestSubprocessCLITransport:
         assert "--max-turns" in cmd
         assert "5" in cmd
 
+    def test_build_command_with_fallback_model(self):
+        """Test building CLI command with fallback_model option."""
+        transport = SubprocessCLITransport(
+            prompt="test",
+            options=make_options(
+                model="opus",
+                fallback_model="sonnet",
+            ),
+        )
+
+        cmd = transport._build_command()
+        assert "--model" in cmd
+        assert "opus" in cmd
+        assert "--fallback-model" in cmd
+        assert "sonnet" in cmd
+
     def test_build_command_with_max_thinking_tokens(self):
         """Test building CLI command with max_thinking_tokens option."""
         transport = SubprocessCLITransport(

From 50d68409c64898854f6ab242dd0edbec1d40398e Mon Sep 17 00:00:00 2001
From: bogini <bogini@users.noreply.github.com>
Date: Tue, 18 Nov 2025 11:01:17 -0800
Subject: [PATCH 31/93] feat: add structured output support (#340)

Add structured output support to Python SDK.

## Usage

```python
from claude_agent_sdk import query, ClaudeAgentOptions

schema = {
    "type": "object",
    "properties": {"count": {"type": "number"}},
    "required": ["count"]
}

async for msg in query(
    prompt="Count files in src/",
    options=ClaudeAgentOptions(
        output_format={"type": "json_schema", "schema": schema}
    )
):
    if hasattr(msg, 'structured_output'):
        print(msg.structured_output)
```

## Documentation

https://docs.claude.com/en/docs/agent-sdk/structured-outputs

## Tests

- Unit tests:
`tests/test_integration.py::TestIntegration::test_structured_output`
- E2E tests: `e2e-tests/test_structured_output.py` (4 tests)
---
 e2e-tests/test_structured_output.py           | 204 ++++++++++++++++++
 .../_internal/message_parser.py               |   1 +
 .../_internal/transport/subprocess_cli.py     |  22 +-
 src/claude_agent_sdk/types.py                 |   4 +
 4 files changed, 226 insertions(+), 5 deletions(-)
 create mode 100644 e2e-tests/test_structured_output.py

diff --git a/e2e-tests/test_structured_output.py b/e2e-tests/test_structured_output.py
new file mode 100644
index 0000000..32e7ba2
--- /dev/null
+++ b/e2e-tests/test_structured_output.py
@@ -0,0 +1,204 @@
+"""End-to-end tests for structured output with real Claude API calls.
+
+These tests verify that the output_schema feature works correctly by making
+actual API calls to Claude with JSON Schema validation.
+"""
+
+import tempfile
+
+import pytest
+
+from claude_agent_sdk import (
+    ClaudeAgentOptions,
+    ResultMessage,
+    query,
+)
+
+
+@pytest.mark.e2e
+@pytest.mark.asyncio
+async def test_simple_structured_output():
+    """Test structured output with file counting requiring tool use."""
+
+    # Define schema for file analysis
+    schema = {
+        "type": "object",
+        "properties": {
+            "file_count": {"type": "number"},
+            "has_tests": {"type": "boolean"},
+            "test_file_count": {"type": "number"},
+        },
+        "required": ["file_count", "has_tests"],
+    }
+
+    options = ClaudeAgentOptions(
+        output_format={"type": "json_schema", "schema": schema},
+        permission_mode="acceptEdits",
+        cwd=".",  # Use current directory
+    )
+
+    # Agent must use Glob/Bash to count files
+    result_message = None
+    async for message in query(
+        prompt="Count how many Python files are in src/claude_agent_sdk/ and check if there are any test files. Use tools to explore the filesystem.",
+        options=options,
+    ):
+        if isinstance(message, ResultMessage):
+            result_message = message
+
+    # Verify result
+    assert result_message is not None, "No result message received"
+    assert not result_message.is_error, f"Query failed: {result_message.result}"
+    assert result_message.subtype == "success"
+
+    # Verify structured output is present and valid
+    assert result_message.structured_output is not None, "No structured output in result"
+    assert "file_count" in result_message.structured_output
+    assert "has_tests" in result_message.structured_output
+    assert isinstance(result_message.structured_output["file_count"], (int, float))
+    assert isinstance(result_message.structured_output["has_tests"], bool)
+
+    # Should find Python files in src/
+    assert result_message.structured_output["file_count"] > 0
+
+
+@pytest.mark.e2e
+@pytest.mark.asyncio
+async def test_nested_structured_output():
+    """Test structured output with nested objects and arrays."""
+
+    # Define a schema with nested structure
+    schema = {
+        "type": "object",
+        "properties": {
+            "analysis": {
+                "type": "object",
+                "properties": {
+                    "word_count": {"type": "number"},
+                    "character_count": {"type": "number"},
+                },
+                "required": ["word_count", "character_count"],
+            },
+            "words": {
+                "type": "array",
+                "items": {"type": "string"},
+            },
+        },
+        "required": ["analysis", "words"],
+    }
+
+    options = ClaudeAgentOptions(
+        output_format={"type": "json_schema", "schema": schema},
+        permission_mode="acceptEdits",
+    )
+
+    result_message = None
+    async for message in query(
+        prompt="Analyze this text: 'Hello world'. Provide word count, character count, and list of words.",
+        options=options,
+    ):
+        if isinstance(message, ResultMessage):
+            result_message = message
+
+    # Verify result
+    assert result_message is not None
+    assert not result_message.is_error
+    assert result_message.structured_output is not None
+
+    # Check nested structure
+    output = result_message.structured_output
+    assert "analysis" in output
+    assert "words" in output
+    assert output["analysis"]["word_count"] == 2
+    assert output["analysis"]["character_count"] == 11  # "Hello world"
+    assert len(output["words"]) == 2
+
+
+@pytest.mark.e2e
+@pytest.mark.asyncio
+async def test_structured_output_with_enum():
+    """Test structured output with enum constraints requiring code analysis."""
+
+    schema = {
+        "type": "object",
+        "properties": {
+            "has_tests": {"type": "boolean"},
+            "test_framework": {
+                "type": "string",
+                "enum": ["pytest", "unittest", "nose", "unknown"],
+            },
+            "test_count": {"type": "number"},
+        },
+        "required": ["has_tests", "test_framework"],
+    }
+
+    options = ClaudeAgentOptions(
+        output_format={"type": "json_schema", "schema": schema},
+        permission_mode="acceptEdits",
+        cwd=".",
+    )
+
+    result_message = None
+    async for message in query(
+        prompt="Search for test files in the tests/ directory. Determine which test framework is being used (pytest/unittest/nose) and count how many test files exist. Use Grep to search for framework imports.",
+        options=options,
+    ):
+        if isinstance(message, ResultMessage):
+            result_message = message
+
+    # Verify result
+    assert result_message is not None
+    assert not result_message.is_error
+    assert result_message.structured_output is not None
+
+    # Check enum values are valid
+    output = result_message.structured_output
+    assert output["test_framework"] in ["pytest", "unittest", "nose", "unknown"]
+    assert isinstance(output["has_tests"], bool)
+
+    # This repo uses pytest
+    assert output["has_tests"] is True
+    assert output["test_framework"] == "pytest"
+
+
+@pytest.mark.e2e
+@pytest.mark.asyncio
+async def test_structured_output_with_tools():
+    """Test structured output when agent uses tools."""
+
+    # Schema for file analysis
+    schema = {
+        "type": "object",
+        "properties": {
+            "file_count": {"type": "number"},
+            "has_readme": {"type": "boolean"},
+        },
+        "required": ["file_count", "has_readme"],
+    }
+
+    options = ClaudeAgentOptions(
+        output_format={"type": "json_schema", "schema": schema},
+        permission_mode="acceptEdits",
+        cwd=tempfile.gettempdir(),  # Cross-platform temp directory
+    )
+
+    result_message = None
+    async for message in query(
+        prompt="Count how many files are in the current directory and check if there's a README file. Use tools as needed.",
+        options=options,
+    ):
+        if isinstance(message, ResultMessage):
+            result_message = message
+
+    # Verify result
+    assert result_message is not None
+    assert not result_message.is_error
+    assert result_message.structured_output is not None
+
+    # Check structure
+    output = result_message.structured_output
+    assert "file_count" in output
+    assert "has_readme" in output
+    assert isinstance(output["file_count"], (int, float))
+    assert isinstance(output["has_readme"], bool)
+    assert output["file_count"] >= 0  # Should be non-negative
diff --git a/src/claude_agent_sdk/_internal/message_parser.py b/src/claude_agent_sdk/_internal/message_parser.py
index 6532a20..694c52c 100644
--- a/src/claude_agent_sdk/_internal/message_parser.py
+++ b/src/claude_agent_sdk/_internal/message_parser.py
@@ -149,6 +149,7 @@ def parse_message(data: dict[str, Any]) -> Message:
                     total_cost_usd=data.get("total_cost_usd"),
                     usage=data.get("usage"),
                     result=data.get("result"),
+                    structured_output=data.get("structured_output"),
                 )
             except KeyError as e:
                 raise MessageParseError(
diff --git a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
index d669a41..433c47e 100644
--- a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
+++ b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
@@ -215,7 +215,24 @@ class SubprocessCLITransport(Transport):
                 # Flag with value
                 cmd.extend([f"--{flag}", str(value)])
 
+        if self._options.max_thinking_tokens is not None:
+            cmd.extend(
+                ["--max-thinking-tokens", str(self._options.max_thinking_tokens)]
+            )
+
+        # Extract schema from output_format structure if provided
+        # Expected: {"type": "json_schema", "schema": {...}}
+        if (
+            self._options.output_format is not None
+            and isinstance(self._options.output_format, dict)
+            and self._options.output_format.get("type") == "json_schema"
+        ):
+            schema = self._options.output_format.get("schema")
+            if schema is not None:
+                cmd.extend(["--json-schema", json.dumps(schema)])
+
         # Add prompt handling based on mode
+        # IMPORTANT: This must come AFTER all flags because everything after "--" is treated as arguments
         if self._is_streaming:
             # Streaming mode: use --input-format stream-json
             cmd.extend(["--input-format", "stream-json"])
@@ -223,11 +240,6 @@ class SubprocessCLITransport(Transport):
             # String mode: use --print with the prompt
             cmd.extend(["--print", "--", str(self._prompt)])
 
-        if self._options.max_thinking_tokens is not None:
-            cmd.extend(
-                ["--max-thinking-tokens", str(self._options.max_thinking_tokens)]
-            )
-
         # Check if command line is too long (Windows limitation)
         cmd_str = " ".join(cmd)
         if len(cmd_str) > _CMD_LENGTH_LIMIT and self._options.agents:
diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py
index e375bee..406c204 100644
--- a/src/claude_agent_sdk/types.py
+++ b/src/claude_agent_sdk/types.py
@@ -492,6 +492,7 @@ class ResultMessage:
     total_cost_usd: float | None = None
     usage: dict[str, Any] | None = None
     result: str | None = None
+    structured_output: Any = None
 
 
 @dataclass
@@ -558,6 +559,9 @@ class ClaudeAgentOptions:
     plugins: list[SdkPluginConfig] = field(default_factory=list)
     # Max tokens for thinking blocks
     max_thinking_tokens: int | None = None
+    # Output format for structured outputs (matches Messages API structure)
+    # Example: {"type": "json_schema", "schema": {"type": "object", "properties": {...}}}
+    output_format: dict[str, Any] | None = None
 
 
 # SDK Control Protocol

From 6f209075bc4a2991e53aae63991d949677c1e59f Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Tue, 18 Nov 2025 11:13:45 -0800
Subject: [PATCH 32/93] chore: release v0.1.7 (#341)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This PR updates the version to 0.1.7 after publishing to PyPI.

## Changes
- Updated version in `pyproject.toml`
- Updated version in `src/claude_agent_sdk/_version.py`
- Updated `CHANGELOG.md` with release notes

## Release Information
- Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.7/
- Install with: `pip install claude-agent-sdk==0.1.7`

🤖 Generated by GitHub Actions

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: inigo <bogini@users.noreply.github.com>
---
 CHANGELOG.md                     | 8 ++++++++
 pyproject.toml                   | 2 +-
 src/claude_agent_sdk/_version.py | 2 +-
 3 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 82c8765..6da1026 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.7
+
+### Features
+
+- **Structured outputs support**: Agents can now return validated JSON matching your schema. See https://docs.claude.com/en/docs/agent-sdk/structured-outputs. (#340)
+- **Fallback model handling**: Added automatic fallback model handling for improved reliability and parity with the TypeScript SDK. When the primary model is unavailable, the SDK will automatically use a fallback model (#317)
+- **Local Claude CLI support**: Added support for using a locally installed Claude CLI from `~/.claude/local/claude`, enabling development and testing with custom Claude CLI builds (#302)
+
 ## 0.1.6
 
 ### Features
diff --git a/pyproject.toml b/pyproject.toml
index cc9b99d..653fce8 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "claude-agent-sdk"
-version = "0.1.6"
+version = "0.1.7"
 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 89470e1..9bc0608 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.6"
+__version__ = "0.1.7"

From ce99e9d2eb62af33894c2f4c7ab1f46b9feb89c7 Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Tue, 18 Nov 2025 17:21:15 -0800
Subject: [PATCH 33/93] feat: bundle Claude Code CLI in pip package (#283)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bundle platform-specific Claude Code CLI binaries directly in the Python
package, eliminating the need for separate CLI installation.

## Changes

### Build System
- Created `scripts/download_cli.py` to fetch CLI during build
- Created `scripts/build_wheel.py` for building platform-specific wheels
- Created `scripts/update_cli_version.py` to track bundled CLI version
- Updated `pyproject.toml` to properly bundle CLI without duplicate file
warnings
- Made twine check non-blocking (License-File warnings are false
positives)

### Runtime
- Modified `subprocess_cli.py` to check for bundled CLI first
- Added `_cli_version.py` to track which CLI version is bundled
- SDK automatically uses bundled CLI, falling back to system
installation if not found
- Users can still override with `cli_path` option

### Release Workflow
- Updated GitHub workflow to build separate wheels per platform (macOS,
Linux, Windows)
- Workflow now accepts two inputs:
  - `version`: Package version to publish (e.g., `0.1.5`)
- `claude_code_version`: CLI version to bundle (e.g., `2.0.0` or
`latest`)
- Workflow builds platform-specific wheels with bundled CLI
- Creates release PR that updates:
  - `pyproject.toml` version
  - `src/claude_agent_sdk/_version.py`
  - `src/claude_agent_sdk/_cli_version.py` with bundled CLI version
  - `CHANGELOG.md` with auto-generated release notes

### Documentation
- Updated README to reflect bundled CLI (removed Node.js requirement)
- Added release workflow documentation
- Added local wheel building instructions

## Benefits

- **Zero external dependencies**: No need for Node.js or npm
- **Easier installation**: Single `pip install` gets everything
- **Version control**: Track exactly which CLI version is bundled
- **Flexible releases**: Can release new package versions with updated
CLI without code changes
- **Better user experience**: Works out of the box with no setup

Platform-specific wheels are automatically selected by pip during
installation based on the user's OS and architecture.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
---
 .github/workflows/publish.yml                 | 226 ++++++----
 README.md                                     |  71 +++-
 pyproject.toml                                |   1 +
 scripts/build_wheel.py                        | 392 ++++++++++++++++++
 scripts/download_cli.py                       | 123 ++++++
 scripts/update_cli_version.py                 |  32 ++
 scripts/update_version.py                     |  10 +-
 src/claude_agent_sdk/_bundled/.gitignore      |   3 +
 src/claude_agent_sdk/_cli_version.py          |   3 +
 .../_internal/transport/subprocess_cli.py     |  21 +
 10 files changed, 787 insertions(+), 95 deletions(-)
 create mode 100755 scripts/build_wheel.py
 create mode 100755 scripts/download_cli.py
 create mode 100755 scripts/update_cli_version.py
 create mode 100644 src/claude_agent_sdk/_bundled/.gitignore
 create mode 100644 src/claude_agent_sdk/_cli_version.py

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 6b6e16a..8b629a5 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -4,9 +4,14 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: "Version to publish (e.g., 0.1.0)"
+        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
@@ -56,114 +61,165 @@ jobs:
         run: |
           mypy src/
 
-  publish:
+  build-wheels:
     needs: [test, lint]
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    permissions:
+      contents: write
+      pull-requests: write
+
+    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
+      with:
+        python-version: '3.12'
+
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+      shell: bash
+
+    - name: Build wheel with bundled CLI
+      run: |
+        python scripts/build_wheel.py \
+          --version "${{ github.event.inputs.version }}" \
+          --cli-version "${{ github.event.inputs.claude_code_version }}" \
+          --skip-sdist \
+          --clean
+      shell: bash
+
+    - name: Upload wheel artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: wheel-${{ matrix.os }}
+        path: dist/*.whl
+        if-no-files-found: error
+
+  publish:
+    needs: [build-wheels]
     runs-on: ubuntu-latest
     permissions:
       contents: write
       pull-requests: write
 
     steps:
-      - uses: actions/checkout@v4
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-          fetch-depth: 0 # Fetch all history including tags (necessary for changelog generation)
+    - uses: actions/checkout@v4
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
 
-      - name: Set version
-        id: version
-        run: |
-          VERSION="${{ github.event.inputs.version }}"
-          echo "VERSION=$VERSION" >> $GITHUB_ENV
-          echo "version=$VERSION" >> $GITHUB_OUTPUT
+    - name: Set version
+      id: version
+      run: |
+        VERSION="${{ github.event.inputs.version }}"
+        echo "VERSION=$VERSION" >> $GITHUB_ENV
+        echo "version=$VERSION" >> $GITHUB_OUTPUT
 
-      - name: Update version
-        run: |
-          python scripts/update_version.py "${{ env.VERSION }}"
+    - name: Update version
+      run: |
+        python scripts/update_version.py "${{ env.VERSION }}"
 
-      - name: Install build dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install build twine
+    - name: Update CLI version
+      run: |
+        python scripts/update_cli_version.py "${{ github.event.inputs.claude_code_version }}"
 
-      - name: Build package
-        run: python -m build
+    - name: Download all wheel artifacts
+      uses: actions/download-artifact@v4
+      with:
+        path: dist
+        pattern: wheel-*
+        merge-multiple: true
 
-      - name: Check package
-        run: twine check dist/*
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
 
-      - name: Publish to PyPI
-        env:
-          TWINE_USERNAME: __token__
-          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
-        run: |
-          twine upload dist/*
-          echo "Package published to PyPI"
-          echo "Install with: pip install claude-agent-sdk==${{ env.VERSION }}"
+    - name: Build source distribution
+      run: python -m build --sdist
 
-      - name: Get previous release tag
-        id: previous_tag
-        run: |
-          PREVIOUS_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
-          echo "previous_tag=$PREVIOUS_TAG" >> $GITHUB_OUTPUT
-          echo "Previous release: $PREVIOUS_TAG"
+    - name: Publish to PyPI
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      run: |
+        twine upload dist/*
+        echo "Package published to PyPI"
+        echo "Install with: pip install claude-agent-sdk==${{ env.VERSION }}"
+    
+    - name: Get previous release tag
+      id: previous_tag
+      run: |
+        PREVIOUS_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+        echo "previous_tag=$PREVIOUS_TAG" >> $GITHUB_OUTPUT
+        echo "Previous release: $PREVIOUS_TAG"
 
-      - name: Create release branch and commit version changes
-        run: |
-          # Create a new branch for the version update
-          BRANCH_NAME="release/v${{ env.VERSION }}"
-          echo "BRANCH_NAME=$BRANCH_NAME" >> $GITHUB_ENV
+    - name: Create release branch and commit version changes
+      run: |
+        # Create a new branch for the version update
+        BRANCH_NAME="release/v${{ env.VERSION }}"
+        echo "BRANCH_NAME=$BRANCH_NAME" >> $GITHUB_ENV
 
-          # Configure git
-          git config --local user.email "github-actions[bot]@users.noreply.github.com"
-          git config --local user.name "github-actions[bot]"
+        # Configure git
+        git config --local user.email "github-actions[bot]@users.noreply.github.com"
+        git config --local user.name "github-actions[bot]"
 
-          # Create and switch to new branch
-          git checkout -b "$BRANCH_NAME"
+        # Create and switch to new branch
+        git checkout -b "$BRANCH_NAME"
 
-          # Commit version changes
-          git add pyproject.toml src/claude_agent_sdk/_version.py
-          git commit -m "chore: bump version to ${{ env.VERSION }}"
+        # 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 }}"
 
-      - name: Update changelog with Claude
-        continue-on-error: true
-        uses: anthropics/claude-code-action@v1
-        with:
-          prompt: "/generate-changelog new version: ${{ env.VERSION }}, old version: ${{ steps.previous_tag.outputs.previous_tag }}"
-          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          claude_args: |
-            --allowedTools 'Bash(git add:*),Bash(git commit:*),Edit'
+    - name: Update changelog with Claude
+      continue-on-error: true
+      uses: anthropics/claude-code-action@v1
+      with:
+        prompt: "/generate-changelog new version: ${{ env.VERSION }}, old version: ${{ steps.previous_tag.outputs.previous_tag }}"
+        anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        claude_args: |
+          --allowedTools 'Bash(git add:*),Bash(git commit:*),Edit'
 
-      - name: Push branch and create PR
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          # Push the branch with all commits
-          git push origin "${{ env.BRANCH_NAME }}"
+    - name: Push branch and create PR
+      env:
+        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: |
+        # Push the branch with all commits
+        git push origin "${{ env.BRANCH_NAME }}"
 
-          # Create PR using GitHub CLI
-          PR_BODY="This PR updates the version to ${{ env.VERSION }} after publishing to PyPI.
+        # Create PR using GitHub CLI
+        PR_BODY="This PR updates the version to ${{ env.VERSION }} after publishing to PyPI.
 
-          ## Changes
-          - Updated version in \`pyproject.toml\`
-          - Updated version in \`src/claude_agent_sdk/_version.py\`
-          - Updated \`CHANGELOG.md\` with release notes
+        ## 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 }}/
-          - Install with: \`pip install claude-agent-sdk==${{ env.VERSION }}\`
+        ## Release Information
+        - Published to PyPI: https://pypi.org/project/claude-agent-sdk/${{ env.VERSION }}/
+        - Bundled CLI version: ${{ github.event.inputs.claude_code_version }}
+        - Install with: \`pip install claude-agent-sdk==${{ env.VERSION }}\`
 
-          🤖 Generated by GitHub Actions"
+        🤖 Generated by GitHub Actions"
 
-          PR_URL=$(gh pr create \
-            --title "chore: release v${{ env.VERSION }}" \
-            --body "$PR_BODY" \
-            --base main \
-            --head "${{ env.BRANCH_NAME }}")
+        PR_URL=$(gh pr create \
+          --title "chore: release v${{ env.VERSION }}" \
+          --body "$PR_BODY" \
+          --base main \
+          --head "${{ env.BRANCH_NAME }}")
 
-          echo "PR created: $PR_URL"
+        echo "PR created: $PR_URL"
diff --git a/README.md b/README.md
index 1fcb30d..2111986 100644
--- a/README.md
+++ b/README.md
@@ -9,9 +9,13 @@ pip install claude-agent-sdk
 ```
 
 **Prerequisites:**
+
 - Python 3.10+
-- Node.js
-- Claude Code 2.0.0+: `npm install -g @anthropic-ai/claude-code`
+
+**Note:** The Claude Code CLI is automatically bundled with the package - no separate installation required! The SDK will use the bundled CLI by default. If you prefer to use a system-wide installation or a specific version, you can:
+
+- Install Claude Code separately: `curl -fsSL https://claude.ai/install.sh | bash`
+- Specify a custom path: `ClaudeAgentOptions(cli_path="/path/to/claude")`
 
 ## Quick Start
 
@@ -179,7 +183,7 @@ options = ClaudeAgentOptions(
 
 ### Hooks
 
-A **hook** is a Python function that the Claude Code *application* (*not* Claude) invokes at specific points of the Claude agent loop. Hooks can provide deterministic processing and automated feedback for Claude. Read more in [Claude Code Hooks Reference](https://docs.anthropic.com/en/docs/claude-code/hooks).
+A **hook** is a Python function that the Claude Code _application_ (_not_ Claude) invokes at specific points of the Claude agent loop. Hooks can provide deterministic processing and automated feedback for Claude. Read more in [Claude Code Hooks Reference](https://docs.anthropic.com/en/docs/claude-code/hooks).
 
 For more examples, see examples/hooks.py.
 
@@ -229,10 +233,10 @@ async with ClaudeSDKClient(options=options) as client:
         print(msg)
 ```
 
-
 ## Types
 
 See [src/claude_agent_sdk/types.py](src/claude_agent_sdk/types.py) for complete type definitions:
+
 - `ClaudeAgentOptions` - Configuration options
 - `AssistantMessage`, `UserMessage`, `SystemMessage`, `ResultMessage` - Message types
 - `TextBlock`, `ToolUseBlock`, `ToolResultBlock` - Content blocks
@@ -259,7 +263,7 @@ except CLIJSONDecodeError as e:
     print(f"Failed to parse response: {e}")
 ```
 
-See [src/claude_agent_sdk/_errors.py](src/claude_agent_sdk/_errors.py) for all error types.
+See [src/claude_agent_sdk/\_errors.py](src/claude_agent_sdk/_errors.py) for all error types.
 
 ## Available Tools
 
@@ -290,6 +294,63 @@ If you're contributing to this project, run the initial setup script to install
 
 This installs a pre-push hook that runs lint checks before pushing, matching the CI workflow. To skip the hook temporarily, use `git push --no-verify`.
 
+### Building Wheels Locally
+
+To build wheels with the bundled Claude Code CLI:
+
+```bash
+# Install build dependencies
+pip install build twine
+
+# Build wheel with bundled CLI
+python scripts/build_wheel.py
+
+# Build with specific version
+python scripts/build_wheel.py --version 0.1.4
+
+# Build with specific CLI version
+python scripts/build_wheel.py --cli-version 2.0.0
+
+# Clean bundled CLI after building
+python scripts/build_wheel.py --clean
+
+# Skip CLI download (use existing)
+python scripts/build_wheel.py --skip-download
+```
+
+The build script:
+
+1. Downloads Claude Code CLI for your platform
+2. Bundles it in the wheel
+3. Builds both wheel and source distribution
+4. Checks the package with twine
+
+See `python scripts/build_wheel.py --help` for all options.
+
+### Release Workflow
+
+The package is published to PyPI via the GitHub Actions workflow in `.github/workflows/publish.yml`. To create a new release:
+
+1. **Trigger the workflow** manually from the Actions tab with two inputs:
+   - `version`: The package version to publish (e.g., `0.1.5`)
+   - `claude_code_version`: The Claude Code CLI version to bundle (e.g., `2.0.0` or `latest`)
+
+2. **The workflow will**:
+   - Build platform-specific wheels for macOS, Linux, and Windows
+   - Bundle the specified Claude Code CLI version in each wheel
+   - Build a source distribution
+   - Publish all artifacts to PyPI
+   - Create a release branch with version updates
+   - Open a PR to main with:
+     - Updated `pyproject.toml` version
+     - Updated `src/claude_agent_sdk/_version.py`
+     - Updated `src/claude_agent_sdk/_cli_version.py` with bundled CLI version
+     - Auto-generated `CHANGELOG.md` entry
+
+3. **Review and merge** the release PR to update main with the new version information
+
+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
 
 MIT
diff --git a/pyproject.toml b/pyproject.toml
index 653fce8..9abfeee 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -47,6 +47,7 @@ Issues = "https://github.com/anthropics/claude-agent-sdk-python/issues"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/claude_agent_sdk"]
+only-include = ["src/claude_agent_sdk"]
 
 [tool.hatch.build.targets.sdist]
 include = [
diff --git a/scripts/build_wheel.py b/scripts/build_wheel.py
new file mode 100755
index 0000000..b5a6b41
--- /dev/null
+++ b/scripts/build_wheel.py
@@ -0,0 +1,392 @@
+#!/usr/bin/env python3
+"""Build wheel with bundled Claude Code CLI.
+
+This script handles the complete wheel building process:
+1. Optionally updates version
+2. Downloads Claude Code CLI
+3. Builds the wheel
+4. Optionally cleans up the bundled CLI
+
+Usage:
+    python scripts/build_wheel.py                    # Build with current version
+    python scripts/build_wheel.py --version 0.1.4    # Build with specific version
+    python scripts/build_wheel.py --clean            # Clean bundled CLI after build
+    python scripts/build_wheel.py --skip-download    # Skip CLI download (use existing)
+"""
+
+import argparse
+import os
+import platform
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+try:
+    import twine  # noqa: F401
+
+    HAS_TWINE = True
+except ImportError:
+    HAS_TWINE = False
+
+
+def run_command(cmd: list[str], description: str) -> None:
+    """Run a command and handle errors."""
+    print(f"\n{'=' * 60}")
+    print(f"📦 {description}")
+    print(f"{'=' * 60}")
+    print(f"$ {' '.join(cmd)}")
+    print()
+
+    try:
+        result = subprocess.run(
+            cmd,
+            check=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+        )
+        print(result.stdout)
+    except subprocess.CalledProcessError as e:
+        print(f"❌ Error: {description} failed", file=sys.stderr)
+        print(e.stdout, file=sys.stderr)
+        sys.exit(1)
+
+
+def update_version(version: str) -> None:
+    """Update package version."""
+    script_dir = Path(__file__).parent
+    update_script = script_dir / "update_version.py"
+
+    if not update_script.exists():
+        print("⚠️  Warning: update_version.py not found, skipping version update")
+        return
+
+    run_command(
+        [sys.executable, str(update_script), version],
+        f"Updating version to {version}",
+    )
+
+
+def get_bundled_cli_version() -> str:
+    """Get the CLI version that should be bundled from _cli_version.py."""
+    version_file = Path("src/claude_agent_sdk/_cli_version.py")
+    if not version_file.exists():
+        return "latest"
+
+    content = version_file.read_text()
+    match = re.search(r'__cli_version__ = "([^"]+)"', content)
+    if match:
+        return match.group(1)
+    return "latest"
+
+
+def download_cli(cli_version: str | None = None) -> None:
+    """Download Claude Code CLI."""
+    # Use provided version, or fall back to version from _cli_version.py
+    if cli_version is None:
+        cli_version = get_bundled_cli_version()
+
+    script_dir = Path(__file__).parent
+    download_script = script_dir / "download_cli.py"
+
+    # Set environment variable for download script
+    os.environ["CLAUDE_CLI_VERSION"] = cli_version
+
+    run_command(
+        [sys.executable, str(download_script)],
+        f"Downloading Claude Code CLI ({cli_version})",
+    )
+
+
+def clean_dist() -> None:
+    """Clean dist directory."""
+    dist_dir = Path("dist")
+    if dist_dir.exists():
+        print(f"\n{'=' * 60}")
+        print("🧹 Cleaning dist directory")
+        print(f"{'=' * 60}")
+        shutil.rmtree(dist_dir)
+        print("✓ Cleaned dist/")
+
+
+def get_platform_tag() -> str:
+    """Get the appropriate platform tag for the current platform.
+
+    Uses minimum compatible versions for broad compatibility:
+    - macOS: 11.0 (Big Sur) as minimum
+    - Linux: manylinux_2_17 (widely compatible)
+    - Windows: Standard tags
+    """
+    system = platform.system()
+    machine = platform.machine().lower()
+
+    if system == "Darwin":
+        # macOS - use minimum version 11.0 (Big Sur) for broad compatibility
+        if machine == "arm64":
+            return "macosx_11_0_arm64"
+        else:
+            return "macosx_11_0_x86_64"
+    elif system == "Linux":
+        # Linux - use manylinux for broad compatibility
+        if machine in ["x86_64", "amd64"]:
+            return "manylinux_2_17_x86_64"
+        elif machine in ["aarch64", "arm64"]:
+            return "manylinux_2_17_aarch64"
+        else:
+            return f"linux_{machine}"
+    elif system == "Windows":
+        # Windows
+        if machine in ["x86_64", "amd64"]:
+            return "win_amd64"
+        elif machine == "arm64":
+            return "win_arm64"
+        else:
+            return "win32"
+    else:
+        # Unknown platform, use generic
+        return f"{system.lower()}_{machine}"
+
+
+def retag_wheel(wheel_path: Path, platform_tag: str) -> Path:
+    """Retag a wheel with the correct platform tag using wheel package."""
+    print(f"\n{'=' * 60}")
+    print("🏷️  Retagging wheel as platform-specific")
+    print(f"{'=' * 60}")
+    print(f"Old: {wheel_path.name}")
+
+    # Use wheel package to properly retag (updates both filename and metadata)
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "wheel",
+            "tags",
+            "--platform-tag",
+            platform_tag,
+            "--remove",
+            str(wheel_path),
+        ],
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        print(f"⚠️  Warning: Failed to retag wheel: {result.stderr}")
+        return wheel_path
+
+    # Find the newly tagged wheel
+    dist_dir = wheel_path.parent
+    # The wheel package creates a new file with the platform tag
+    new_wheels = list(dist_dir.glob(f"*{platform_tag}.whl"))
+
+    if new_wheels:
+        new_path = new_wheels[0]
+        print(f"New: {new_path.name}")
+        print("✓ Wheel retagged successfully")
+
+        # Remove the old wheel
+        if wheel_path.exists() and wheel_path != new_path:
+            wheel_path.unlink()
+
+        return new_path
+    else:
+        print("⚠️  Warning: Could not find retagged wheel")
+        return wheel_path
+
+
+def build_wheel() -> None:
+    """Build the wheel."""
+    run_command(
+        [sys.executable, "-m", "build", "--wheel"],
+        "Building wheel",
+    )
+
+    # Check if we have a bundled CLI - if so, retag the wheel as platform-specific
+    bundled_cli = Path("src/claude_agent_sdk/_bundled/claude")
+    bundled_cli_exe = Path("src/claude_agent_sdk/_bundled/claude.exe")
+
+    if bundled_cli.exists() or bundled_cli_exe.exists():
+        # Find the built wheel
+        dist_dir = Path("dist")
+        wheels = list(dist_dir.glob("*.whl"))
+
+        if wheels:
+            # Get platform tag
+            platform_tag = get_platform_tag()
+
+            # Retag each wheel (should only be one)
+            for wheel in wheels:
+                if "-any.whl" in wheel.name:
+                    retag_wheel(wheel, platform_tag)
+        else:
+            print("⚠️  Warning: No wheel found to retag")
+    else:
+        print("\nℹ️  No bundled CLI found - wheel will be platform-independent")
+
+
+def build_sdist() -> None:
+    """Build the source distribution."""
+    run_command(
+        [sys.executable, "-m", "build", "--sdist"],
+        "Building source distribution",
+    )
+
+
+def check_package() -> None:
+    """Check package with twine."""
+    if not HAS_TWINE:
+        print("\n⚠️  Warning: twine not installed, skipping package check")
+        print("Install with: pip install twine")
+        return
+
+    print(f"\n{'=' * 60}")
+    print("📦 Checking package with twine")
+    print(f"{'=' * 60}")
+    print(f"$ {sys.executable} -m twine check dist/*")
+    print()
+
+    try:
+        result = subprocess.run(
+            [sys.executable, "-m", "twine", "check", "dist/*"],
+            check=False,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+        )
+        print(result.stdout)
+
+        if result.returncode != 0:
+            print("\n⚠️  Warning: twine check reported issues")
+            print("Note: 'License-File' warnings are false positives from twine 6.x")
+            print("PyPI will accept these packages without issues")
+        else:
+            print("✓ Package check passed")
+    except Exception as e:
+        print(f"⚠️  Warning: Failed to run twine check: {e}")
+
+
+def clean_bundled_cli() -> None:
+    """Clean bundled CLI."""
+    bundled_dir = Path("src/claude_agent_sdk/_bundled")
+    cli_files = list(bundled_dir.glob("claude*"))
+
+    if cli_files:
+        print(f"\n{'=' * 60}")
+        print("🧹 Cleaning bundled CLI")
+        print(f"{'=' * 60}")
+        for cli_file in cli_files:
+            if cli_file.name != ".gitignore":
+                cli_file.unlink()
+                print(f"✓ Removed {cli_file}")
+    else:
+        print("\nℹ️  No bundled CLI to clean")
+
+
+def list_artifacts() -> None:
+    """List built artifacts."""
+    dist_dir = Path("dist")
+    if not dist_dir.exists():
+        return
+
+    print(f"\n{'=' * 60}")
+    print("📦 Built Artifacts")
+    print(f"{'=' * 60}")
+
+    artifacts = sorted(dist_dir.iterdir())
+    if not artifacts:
+        print("No artifacts found")
+        return
+
+    for artifact in artifacts:
+        size_mb = artifact.stat().st_size / (1024 * 1024)
+        print(f"  {artifact.name:<50} {size_mb:>8.2f} MB")
+
+    total_size = sum(f.stat().st_size for f in artifacts) / (1024 * 1024)
+    print(f"\n  {'Total:':<50} {total_size:>8.2f} MB")
+
+
+def main() -> None:
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        description="Build wheel with bundled Claude Code CLI"
+    )
+    parser.add_argument(
+        "--version",
+        help="Version to set before building (e.g., 0.1.4)",
+    )
+    parser.add_argument(
+        "--cli-version",
+        default=None,
+        help="Claude Code CLI version to download (default: read from _cli_version.py)",
+    )
+    parser.add_argument(
+        "--skip-download",
+        action="store_true",
+        help="Skip downloading CLI (use existing bundled CLI)",
+    )
+    parser.add_argument(
+        "--skip-sdist",
+        action="store_true",
+        help="Skip building source distribution",
+    )
+    parser.add_argument(
+        "--clean",
+        action="store_true",
+        help="Clean bundled CLI after building",
+    )
+    parser.add_argument(
+        "--clean-dist",
+        action="store_true",
+        help="Clean dist directory before building",
+    )
+
+    args = parser.parse_args()
+
+    print("\n" + "=" * 60)
+    print("🚀 Claude Agent SDK - Wheel Builder")
+    print("=" * 60)
+
+    # Clean dist if requested
+    if args.clean_dist:
+        clean_dist()
+
+    # Update version if specified
+    if args.version:
+        update_version(args.version)
+
+    # Download CLI unless skipped
+    if not args.skip_download:
+        download_cli(args.cli_version)
+    else:
+        print("\nℹ️  Skipping CLI download (using existing)")
+
+    # Build wheel
+    build_wheel()
+
+    # Build sdist unless skipped
+    if not args.skip_sdist:
+        build_sdist()
+
+    # Check package
+    check_package()
+
+    # Clean bundled CLI if requested
+    if args.clean:
+        clean_bundled_cli()
+
+    # List artifacts
+    list_artifacts()
+
+    print(f"\n{'=' * 60}")
+    print("✅ Build complete!")
+    print(f"{'=' * 60}")
+    print("\nNext steps:")
+    print("  1. Test the wheel: pip install dist/*.whl")
+    print("  2. Run tests: python -m pytest tests/")
+    print("  3. Publish: twine upload dist/*")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/download_cli.py b/scripts/download_cli.py
new file mode 100755
index 0000000..c542c1f
--- /dev/null
+++ b/scripts/download_cli.py
@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Download Claude Code CLI binary for bundling in wheel.
+
+This script is run during the wheel build process to fetch the Claude Code CLI
+binary using the official install script and place it in the package directory.
+"""
+
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+def get_cli_version() -> str:
+    """Get the CLI version to download from environment or default."""
+    return os.environ.get("CLAUDE_CLI_VERSION", "latest")
+
+
+def find_installed_cli() -> Path | None:
+    """Find the installed Claude CLI binary."""
+    # Check common installation locations
+    locations = [
+        Path.home() / ".local/bin/claude",
+        Path("/usr/local/bin/claude"),
+        Path.home() / "node_modules/.bin/claude",
+    ]
+
+    # Also check PATH
+    cli_path = shutil.which("claude")
+    if cli_path:
+        return Path(cli_path)
+
+    for path in locations:
+        if path.exists() and path.is_file():
+            return path
+
+    return None
+
+
+def download_cli() -> None:
+    """Download Claude Code CLI using the official install script."""
+    version = get_cli_version()
+
+    print(f"Downloading Claude Code CLI version: {version}")
+
+    # Download and run install script
+    install_script = "curl -fsSL https://claude.ai/install.sh | bash"
+    if version != "latest":
+        install_script = f"curl -fsSL https://claude.ai/install.sh | bash -s {version}"
+
+    try:
+        subprocess.run(
+            install_script,
+            shell=True,
+            check=True,
+            capture_output=True,
+        )
+    except subprocess.CalledProcessError as e:
+        print(f"Error downloading CLI: {e}", file=sys.stderr)
+        print(f"stdout: {e.stdout.decode()}", file=sys.stderr)
+        print(f"stderr: {e.stderr.decode()}", file=sys.stderr)
+        sys.exit(1)
+
+
+def copy_cli_to_bundle() -> None:
+    """Copy the installed CLI to the package _bundled directory."""
+    # Find project root (parent of scripts directory)
+    script_dir = Path(__file__).parent
+    project_root = script_dir.parent
+    bundle_dir = project_root / "src" / "claude_agent_sdk" / "_bundled"
+
+    # Ensure bundle directory exists
+    bundle_dir.mkdir(parents=True, exist_ok=True)
+
+    # Find installed CLI
+    cli_path = find_installed_cli()
+    if not cli_path:
+        print("Error: Could not find installed Claude CLI binary", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Found CLI at: {cli_path}")
+
+    # Determine target filename based on platform
+    system = platform.system()
+    target_name = "claude.exe" if system == "Windows" else "claude"
+    target_path = bundle_dir / target_name
+
+    # Copy the binary
+    print(f"Copying CLI to: {target_path}")
+    shutil.copy2(cli_path, target_path)
+
+    # Make it executable (Unix-like systems)
+    if system != "Windows":
+        target_path.chmod(0o755)
+
+    print(f"Successfully bundled CLI binary: {target_path}")
+
+    # Print size info
+    size_mb = target_path.stat().st_size / (1024 * 1024)
+    print(f"Binary size: {size_mb:.2f} MB")
+
+
+def main() -> None:
+    """Main entry point."""
+    print("=" * 60)
+    print("Claude Code CLI Download Script")
+    print("=" * 60)
+
+    # Download CLI
+    download_cli()
+
+    # Copy to bundle directory
+    copy_cli_to_bundle()
+
+    print("=" * 60)
+    print("CLI download and bundling complete!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/update_cli_version.py b/scripts/update_cli_version.py
new file mode 100755
index 0000000..1ef17c7
--- /dev/null
+++ b/scripts/update_cli_version.py
@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""Update Claude Code CLI version in _cli_version.py."""
+
+import re
+import sys
+from pathlib import Path
+
+
+def update_cli_version(new_version: str) -> None:
+    """Update CLI version in _cli_version.py."""
+    # Update _cli_version.py
+    version_path = Path("src/claude_agent_sdk/_cli_version.py")
+    content = version_path.read_text()
+
+    content = re.sub(
+        r'__cli_version__ = "[^"]+"',
+        f'__cli_version__ = "{new_version}"',
+        content,
+        count=1,
+        flags=re.MULTILINE,
+    )
+
+    version_path.write_text(content)
+    print(f"Updated {version_path} to {new_version}")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: python scripts/update_cli_version.py <version>")
+        sys.exit(1)
+
+    update_cli_version(sys.argv[1])
diff --git a/scripts/update_version.py b/scripts/update_version.py
index 743b40f..b980d52 100755
--- a/scripts/update_version.py
+++ b/scripts/update_version.py
@@ -1,8 +1,8 @@
 #!/usr/bin/env python3
 """Update version in pyproject.toml and __init__.py files."""
 
-import sys
 import re
+import sys
 from pathlib import Path
 
 
@@ -18,7 +18,7 @@ def update_version(new_version: str) -> None:
         f'version = "{new_version}"',
         content,
         count=1,
-        flags=re.MULTILINE
+        flags=re.MULTILINE,
     )
 
     pyproject_path.write_text(content)
@@ -34,7 +34,7 @@ def update_version(new_version: str) -> None:
         f'__version__ = "{new_version}"',
         content,
         count=1,
-        flags=re.MULTILINE
+        flags=re.MULTILINE,
     )
 
     version_path.write_text(content)
@@ -45,5 +45,5 @@ if __name__ == "__main__":
     if len(sys.argv) != 2:
         print("Usage: python scripts/update_version.py <version>")
         sys.exit(1)
-    
-    update_version(sys.argv[1])
\ No newline at end of file
+
+    update_version(sys.argv[1])
diff --git a/src/claude_agent_sdk/_bundled/.gitignore b/src/claude_agent_sdk/_bundled/.gitignore
new file mode 100644
index 0000000..b8f0354
--- /dev/null
+++ b/src/claude_agent_sdk/_bundled/.gitignore
@@ -0,0 +1,3 @@
+# Ignore bundled CLI binaries (downloaded during build)
+claude
+claude.exe
diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py
new file mode 100644
index 0000000..5666367
--- /dev/null
+++ b/src/claude_agent_sdk/_cli_version.py
@@ -0,0 +1,3 @@
+"""Bundled Claude Code CLI version."""
+
+__cli_version__ = "latest"
diff --git a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
index 433c47e..48e21de 100644
--- a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
+++ b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
@@ -68,6 +68,12 @@ class SubprocessCLITransport(Transport):
 
     def _find_cli(self) -> str:
         """Find Claude Code CLI binary."""
+        # First, check for bundled CLI
+        bundled_cli = self._find_bundled_cli()
+        if bundled_cli:
+            return bundled_cli
+
+        # Fall back to system-wide search
         if cli := shutil.which("claude"):
             return cli
 
@@ -93,6 +99,21 @@ class SubprocessCLITransport(Transport):
             "  ClaudeAgentOptions(cli_path='/path/to/claude')"
         )
 
+    def _find_bundled_cli(self) -> str | None:
+        """Find bundled CLI binary if it exists."""
+        # Determine the CLI binary name based on platform
+        cli_name = "claude.exe" if platform.system() == "Windows" else "claude"
+
+        # Get the path to the bundled CLI
+        # The _bundled directory is in the same package as this module
+        bundled_path = Path(__file__).parent.parent.parent / "_bundled" / cli_name
+
+        if bundled_path.exists() and bundled_path.is_file():
+            logger.info(f"Using bundled Claude Code CLI: {bundled_path}")
+            return str(bundled_path)
+
+        return None
+
     def _build_command(self) -> list[str]:
         """Build CLI command with arguments."""
         cmd = [self._cli_path, "--output-format", "stream-json", "--verbose"]

From 35dd5b4bcc2686c3564c935a4e8aee4f7105a6f6 Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Tue, 18 Nov 2025 17:59:48 -0800
Subject: [PATCH 34/93] fix: remove emojis from build_wheel.py for Windows
 compatibility (#342)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Windows console encoding (cp1252) doesn't support Unicode emoji
characters, causing UnicodeEncodeError in CI. Replaced all emoji
characters with plain text equivalents.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
---
 scripts/build_wheel.py | 46 +++++++++++++++++++++---------------------
 1 file changed, 23 insertions(+), 23 deletions(-)

diff --git a/scripts/build_wheel.py b/scripts/build_wheel.py
index b5a6b41..ec6799a 100755
--- a/scripts/build_wheel.py
+++ b/scripts/build_wheel.py
@@ -34,7 +34,7 @@ except ImportError:
 def run_command(cmd: list[str], description: str) -> None:
     """Run a command and handle errors."""
     print(f"\n{'=' * 60}")
-    print(f"📦 {description}")
+    print(f"{description}")
     print(f"{'=' * 60}")
     print(f"$ {' '.join(cmd)}")
     print()
@@ -49,7 +49,7 @@ def run_command(cmd: list[str], description: str) -> None:
         )
         print(result.stdout)
     except subprocess.CalledProcessError as e:
-        print(f"❌ Error: {description} failed", file=sys.stderr)
+        print(f"Error: {description} failed", file=sys.stderr)
         print(e.stdout, file=sys.stderr)
         sys.exit(1)
 
@@ -60,7 +60,7 @@ def update_version(version: str) -> None:
     update_script = script_dir / "update_version.py"
 
     if not update_script.exists():
-        print("⚠️  Warning: update_version.py not found, skipping version update")
+        print("Warning: update_version.py not found, skipping version update")
         return
 
     run_command(
@@ -105,10 +105,10 @@ def clean_dist() -> None:
     dist_dir = Path("dist")
     if dist_dir.exists():
         print(f"\n{'=' * 60}")
-        print("🧹 Cleaning dist directory")
+        print("Cleaning dist directory")
         print(f"{'=' * 60}")
         shutil.rmtree(dist_dir)
-        print("✓ Cleaned dist/")
+        print("Cleaned dist/")
 
 
 def get_platform_tag() -> str:
@@ -152,7 +152,7 @@ def get_platform_tag() -> str:
 def retag_wheel(wheel_path: Path, platform_tag: str) -> Path:
     """Retag a wheel with the correct platform tag using wheel package."""
     print(f"\n{'=' * 60}")
-    print("🏷️  Retagging wheel as platform-specific")
+    print("Retagging wheel as platform-specific")
     print(f"{'=' * 60}")
     print(f"Old: {wheel_path.name}")
 
@@ -173,7 +173,7 @@ def retag_wheel(wheel_path: Path, platform_tag: str) -> Path:
     )
 
     if result.returncode != 0:
-        print(f"⚠️  Warning: Failed to retag wheel: {result.stderr}")
+        print(f"Warning: Failed to retag wheel: {result.stderr}")
         return wheel_path
 
     # Find the newly tagged wheel
@@ -184,7 +184,7 @@ def retag_wheel(wheel_path: Path, platform_tag: str) -> Path:
     if new_wheels:
         new_path = new_wheels[0]
         print(f"New: {new_path.name}")
-        print("✓ Wheel retagged successfully")
+        print("Wheel retagged successfully")
 
         # Remove the old wheel
         if wheel_path.exists() and wheel_path != new_path:
@@ -192,7 +192,7 @@ def retag_wheel(wheel_path: Path, platform_tag: str) -> Path:
 
         return new_path
     else:
-        print("⚠️  Warning: Could not find retagged wheel")
+        print("Warning: Could not find retagged wheel")
         return wheel_path
 
 
@@ -221,9 +221,9 @@ def build_wheel() -> None:
                 if "-any.whl" in wheel.name:
                     retag_wheel(wheel, platform_tag)
         else:
-            print("⚠️  Warning: No wheel found to retag")
+            print("Warning: No wheel found to retag")
     else:
-        print("\nℹ️  No bundled CLI found - wheel will be platform-independent")
+        print("\nNo bundled CLI found - wheel will be platform-independent")
 
 
 def build_sdist() -> None:
@@ -237,12 +237,12 @@ def build_sdist() -> None:
 def check_package() -> None:
     """Check package with twine."""
     if not HAS_TWINE:
-        print("\n⚠️  Warning: twine not installed, skipping package check")
+        print("\nWarning: twine not installed, skipping package check")
         print("Install with: pip install twine")
         return
 
     print(f"\n{'=' * 60}")
-    print("📦 Checking package with twine")
+    print("Checking package with twine")
     print(f"{'=' * 60}")
     print(f"$ {sys.executable} -m twine check dist/*")
     print()
@@ -258,13 +258,13 @@ def check_package() -> None:
         print(result.stdout)
 
         if result.returncode != 0:
-            print("\n⚠️  Warning: twine check reported issues")
+            print("\nWarning: twine check reported issues")
             print("Note: 'License-File' warnings are false positives from twine 6.x")
             print("PyPI will accept these packages without issues")
         else:
-            print("✓ Package check passed")
+            print("Package check passed")
     except Exception as e:
-        print(f"⚠️  Warning: Failed to run twine check: {e}")
+        print(f"Warning: Failed to run twine check: {e}")
 
 
 def clean_bundled_cli() -> None:
@@ -274,14 +274,14 @@ def clean_bundled_cli() -> None:
 
     if cli_files:
         print(f"\n{'=' * 60}")
-        print("🧹 Cleaning bundled CLI")
+        print("Cleaning bundled CLI")
         print(f"{'=' * 60}")
         for cli_file in cli_files:
             if cli_file.name != ".gitignore":
                 cli_file.unlink()
-                print(f"✓ Removed {cli_file}")
+                print(f"Removed {cli_file}")
     else:
-        print("\nℹ️  No bundled CLI to clean")
+        print("\nNo bundled CLI to clean")
 
 
 def list_artifacts() -> None:
@@ -291,7 +291,7 @@ def list_artifacts() -> None:
         return
 
     print(f"\n{'=' * 60}")
-    print("📦 Built Artifacts")
+    print("Built Artifacts")
     print(f"{'=' * 60}")
 
     artifacts = sorted(dist_dir.iterdir())
@@ -345,7 +345,7 @@ def main() -> None:
     args = parser.parse_args()
 
     print("\n" + "=" * 60)
-    print("🚀 Claude Agent SDK - Wheel Builder")
+    print("Claude Agent SDK - Wheel Builder")
     print("=" * 60)
 
     # Clean dist if requested
@@ -360,7 +360,7 @@ def main() -> None:
     if not args.skip_download:
         download_cli(args.cli_version)
     else:
-        print("\nℹ️  Skipping CLI download (using existing)")
+        print("\nSkipping CLI download (using existing)")
 
     # Build wheel
     build_wheel()
@@ -380,7 +380,7 @@ def main() -> None:
     list_artifacts()
 
     print(f"\n{'=' * 60}")
-    print("✅ Build complete!")
+    print("Build complete!")
     print(f"{'=' * 60}")
     print("\nNext steps:")
     print("  1. Test the wheel: pip install dist/*.whl")

From 58cfffc623bc780967003963f00b04ad70d1c885 Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Tue, 18 Nov 2025 20:47:26 -0800
Subject: [PATCH 35/93] fix: use PowerShell installer for Windows CLI download
 (#343)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The bash install script (install.sh) explicitly rejects Windows. Use the
PowerShell installer (install.ps1) instead when running on Windows,
matching the approach used in test.yml.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
---
 scripts/download_cli.py | 58 ++++++++++++++++++++++++++++++++---------
 1 file changed, 46 insertions(+), 12 deletions(-)

diff --git a/scripts/download_cli.py b/scripts/download_cli.py
index c542c1f..45d39df 100755
--- a/scripts/download_cli.py
+++ b/scripts/download_cli.py
@@ -20,12 +20,21 @@ def get_cli_version() -> str:
 
 def find_installed_cli() -> Path | None:
     """Find the installed Claude CLI binary."""
-    # Check common installation locations
-    locations = [
-        Path.home() / ".local/bin/claude",
-        Path("/usr/local/bin/claude"),
-        Path.home() / "node_modules/.bin/claude",
-    ]
+    system = platform.system()
+
+    if system == "Windows":
+        # Windows installation locations (matches test.yml: $USERPROFILE\.local\bin)
+        locations = [
+            Path.home() / ".local" / "bin" / "claude.exe",
+            Path(os.environ.get("LOCALAPPDATA", "")) / "Claude" / "claude.exe",
+        ]
+    else:
+        # Unix installation locations
+        locations = [
+            Path.home() / ".local" / "bin" / "claude",
+            Path("/usr/local/bin/claude"),
+            Path.home() / "node_modules" / ".bin" / "claude",
+        ]
 
     # Also check PATH
     cli_path = shutil.which("claude")
@@ -42,18 +51,43 @@ def find_installed_cli() -> Path | None:
 def download_cli() -> None:
     """Download Claude Code CLI using the official install script."""
     version = get_cli_version()
+    system = platform.system()
 
     print(f"Downloading Claude Code CLI version: {version}")
 
-    # Download and run install script
-    install_script = "curl -fsSL https://claude.ai/install.sh | bash"
-    if version != "latest":
-        install_script = f"curl -fsSL https://claude.ai/install.sh | bash -s {version}"
+    # Build install command based on platform
+    if system == "Windows":
+        # Use PowerShell installer on Windows
+        if version == "latest":
+            install_cmd = [
+                "powershell",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-Command",
+                "irm https://claude.ai/install.ps1 | iex",
+            ]
+        else:
+            install_cmd = [
+                "powershell",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-Command",
+                f"& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) {version}",
+            ]
+    else:
+        # Use bash installer on Unix-like systems
+        if version == "latest":
+            install_cmd = ["bash", "-c", "curl -fsSL https://claude.ai/install.sh | bash"]
+        else:
+            install_cmd = [
+                "bash",
+                "-c",
+                f"curl -fsSL https://claude.ai/install.sh | bash -s {version}",
+            ]
 
     try:
         subprocess.run(
-            install_script,
-            shell=True,
+            install_cmd,
             check=True,
             capture_output=True,
         )

From ddc37c73304f9d85d0fc9fca7d4ce1890d18bf6a Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Tue, 18 Nov 2025 20:55:17 -0800
Subject: [PATCH 36/93] fix: disable artifact compression to prevent wheel
 corruption (#344)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Wheels are already ZIP files - double compression via GitHub Actions
artifacts can cause "Mis-matched data size" errors on PyPI upload.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
---
 .github/workflows/publish.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 8b629a5..9a0b817 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -102,6 +102,7 @@ jobs:
         name: wheel-${{ matrix.os }}
         path: dist/*.whl
         if-no-files-found: error
+        compression-level: 0
 
   publish:
     needs: [build-wheels]

From bab98e717e81458131e2fe8dddef1b09e5728ff3 Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Tue, 18 Nov 2025 21:05:18 -0800
Subject: [PATCH 37/93] fix: install wheel package for retagging
 platform-specific wheels (#345)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The build_wheel.py script uses `python -m wheel tags` to retag wheels
with platform-specific tags, but `wheel` wasn't explicitly installed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
---
 .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 9a0b817..057a8f5 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -84,7 +84,7 @@ jobs:
     - name: Install build dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install build twine
+        pip install build twine wheel
       shell: bash
 
     - name: Build wheel with bundled CLI

From d5dc615bd4cda1421e4dce7571e7c5e0b5edf36c Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Tue, 18 Nov 2025 21:21:57 -0800
Subject: [PATCH 38/93] chore: release v0.1.8 (#346)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This PR updates the version to 0.1.8 after publishing to PyPI.

## Changes
- Updated version in `pyproject.toml` to 0.1.8
- Updated version in `src/claude_agent_sdk/_version.py` to 0.1.8
- Updated bundled CLI version in `src/claude_agent_sdk/_cli_version.py`
to 2.0.45
- Updated `CHANGELOG.md` with release notes

## Release Information
- Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.8/
- Bundled CLI version: 2.0.45
- Install with: `pip install claude-agent-sdk==0.1.8`

🤖 Generated by GitHub Actions

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Ashwin Bhat <ashwin@anthropic.com>
---
 CHANGELOG.md                         | 6 ++++++
 pyproject.toml                       | 2 +-
 src/claude_agent_sdk/_cli_version.py | 2 +-
 src/claude_agent_sdk/_version.py     | 2 +-
 4 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6da1026..7dec6a3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.8
+
+### Features
+
+- Claude Code is now included by default in the package, removing the requirement to install it separately. If you do wish to use a separately installed build, use the `cli_path` field in `Options`.
+
 ## 0.1.7
 
 ### Features
diff --git a/pyproject.toml b/pyproject.toml
index 9abfeee..da5aaa6 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "claude-agent-sdk"
-version = "0.1.7"
+version = "0.1.8"
 description = "Python SDK for Claude Code"
 readme = "README.md"
 requires-python = ">=3.10"
diff --git a/src/claude_agent_sdk/_cli_version.py b/src/claude_agent_sdk/_cli_version.py
index 5666367..7934dd0 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__ = "latest"
+__cli_version__ = "2.0.45"
diff --git a/src/claude_agent_sdk/_version.py b/src/claude_agent_sdk/_version.py
index 9bc0608..a0e39a9 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.7"
+__version__ = "0.1.8"

From bf528a1221c1dca4cce20d18ee9b9823290cd68e Mon Sep 17 00:00:00 2001
From: Ashwin Bhat <ashwin@anthropic.com>
Date: Wed, 19 Nov 2025 09:49:35 -0800
Subject: [PATCH 39/93] 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 <noreply@anthropic.com>
---
 .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 <dickson@anthropic.com>
Date: Thu, 20 Nov 2025 06:50:33 +0900
Subject: [PATCH 40/93] 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 <noreply@anthropic.com>
---
 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 <actions@github.com>
Date: Wed, 19 Nov 2025 22:56:34 +0000
Subject: [PATCH 41/93] 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 <actions@github.com>
Date: Wed, 19 Nov 2025 23:12:47 +0000
Subject: [PATCH 42/93] 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 <shawnm@anthropic.com>
Date: Wed, 19 Nov 2025 19:23:10 -0500
Subject: [PATCH 43/93] 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 <actions@github.com>
Date: Fri, 21 Nov 2025 01:31:38 +0000
Subject: [PATCH 44/93] 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 45/93] 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] <github-actions[bot]@users.noreply.github.com>
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 <michaeldworsky1@gmail.com>
Date: Fri, 21 Nov 2025 16:46:22 -0500
Subject: [PATCH 46/93] 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 <actions@github.com>
Date: Fri, 21 Nov 2025 23:16:27 +0000
Subject: [PATCH 47/93] 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 <hkawamura0130@gmail.com>
Date: Mon, 24 Nov 2025 08:22:12 +0900
Subject: [PATCH 48/93] 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 <noahzweben@gmail.com>
Date: Sun, 23 Nov 2025 21:24:25 -0800
Subject: [PATCH 49/93] 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 <ashwin@anthropic.com>
---
 .../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 <actions@github.com>
Date: Mon, 24 Nov 2025 18:48:28 +0000
Subject: [PATCH 50/93] 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 <actions@github.com>
Date: Mon, 24 Nov 2025 23:32:15 +0000
Subject: [PATCH 51/93] 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 <actions@github.com>
Date: Tue, 25 Nov 2025 01:55:19 +0000
Subject: [PATCH 52/93] 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 53/93] 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] <github-actions[bot]@users.noreply.github.com>
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 <actions@github.com>
Date: Thu, 27 Nov 2025 00:01:24 +0000
Subject: [PATCH 54/93] 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 55/93] 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 <noreply@anthropic.com>
---
 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 <ashwin@anthropic.com>
Date: Mon, 1 Dec 2025 11:40:58 -0500
Subject: [PATCH 56/93] 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 <noreply@anthropic.com>
---
 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 57/93] 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 <noreply@anthropic.com>
---
 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 <john.ott@johnott.us>
Date: Mon, 1 Dec 2025 12:44:57 -0800
Subject: [PATCH 58/93] 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 <actions@github.com>
Date: Tue, 2 Dec 2025 01:35:15 +0000
Subject: [PATCH 59/93] 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 <actions@github.com>
Date: Wed, 3 Dec 2025 05:24:28 +0000
Subject: [PATCH 60/93] 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 61/93] 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] <github-actions[bot]@users.noreply.github.com>
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 <actions@github.com>
Date: Wed, 3 Dec 2025 20:09:56 +0000
Subject: [PATCH 62/93] 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 <ashwin@anthropic.com>
Date: Thu, 4 Dec 2025 09:26:01 -0800
Subject: [PATCH 63/93] 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 <noreply@anthropic.com>
---
 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 <ashwin@anthropic.com>
Date: Thu, 4 Dec 2025 09:27:02 -0800
Subject: [PATCH 64/93] 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 <noreply@anthropic.com>
---
 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 65/93] 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] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Ashwin Bhat <ashwin@anthropic.com>
---
 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 66/93] 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()<br/>subprocess_cli.py:505"] --> B["acquire _write_lock<br/>subprocess_cli.py:507"]
    B --> C["check _ready & stream<br/>subprocess_cli.py:509"]
    C --> D["_stdin_stream.send()<br/>subprocess_cli.py:523"]

    E["close()<br/>subprocess_cli.py:458"] --> F["acquire _write_lock<br/>subprocess_cli.py:478"]
    F --> G["set _ready = False<br/>subprocess_cli.py:479"]
    G --> H["close _stdin_stream<br/>subprocess_cli.py:481"]

    I["end_input()<br/>subprocess_cli.py:531"] --> J["acquire _write_lock<br/>subprocess_cli.py:533"]
    J --> K["close _stdin_stream<br/>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?= <Lyrica2333@gmail.com>
Date: Fri, 5 Dec 2025 06:28:24 +0800
Subject: [PATCH 67/93] 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 <lyrica@example.com>
---
 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 68/93] 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 <actions@github.com>
Date: Thu, 4 Dec 2025 23:09:33 +0000
Subject: [PATCH 69/93] 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 <actions@github.com>
Date: Sat, 6 Dec 2025 00:10:43 +0000
Subject: [PATCH 70/93] 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 71/93] 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] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Ashwin Bhat <ashwin@anthropic.com>
Co-authored-by: Claude <noreply@anthropic.com>
---
 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 <ashwin@anthropic.com>
Date: Sat, 6 Dec 2025 16:52:09 -0800
Subject: [PATCH 72/93] 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 <noreply@anthropic.com>
---
 .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 <actions@github.com>
Date: Sun, 7 Dec 2025 10:47:47 +0000
Subject: [PATCH 73/93] 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 <actions@github.com>
Date: Tue, 9 Dec 2025 02:12:13 +0000
Subject: [PATCH 74/93] 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 75/93] 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] <github-actions[bot]@users.noreply.github.com>
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 <sarahdeaton@anthropic.com>
Date: Tue, 9 Dec 2025 09:33:42 -0800
Subject: [PATCH 76/93] 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 <noahzweben@gmail.com>
Date: Tue, 9 Dec 2025 10:16:03 -0800
Subject: [PATCH 77/93] 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 <noreply@anthropic.com>
Co-authored-by: Ashwin Bhat <ashwin@anthropic.com>
---
 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 78/93] 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] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
---
 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 79/93] 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 <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Happy <yesreply@happy.engineering>
---
 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 <actions@github.com>
Date: Fri, 12 Dec 2025 23:32:48 +0000
Subject: [PATCH 80/93] 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 81/93] 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] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
---
 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 <actions@github.com>
Date: Sat, 13 Dec 2025 01:00:44 +0000
Subject: [PATCH 82/93] 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 <noahzweben@gmail.com>
Date: Mon, 15 Dec 2025 09:03:58 -0800
Subject: [PATCH 83/93] 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 <actions@github.com>
Date: Mon, 15 Dec 2025 23:52:59 +0000
Subject: [PATCH 84/93] 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 85/93] 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] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
---
 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 <ashwin@anthropic.com>
Date: Mon, 15 Dec 2025 16:53:23 -0800
Subject: [PATCH 86/93] 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 <noreply@anthropic.com>
---
 .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 <ashwin@anthropic.com>
Date: Tue, 16 Dec 2025 10:53:13 -0800
Subject: [PATCH 87/93] 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 <noreply@anthropic.com>
---
 .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 <actions@github.com>
Date: Tue, 16 Dec 2025 22:09:36 +0000
Subject: [PATCH 88/93] 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 <actions@github.com>
Date: Wed, 17 Dec 2025 21:59:10 +0000
Subject: [PATCH 89/93] 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 90/93] 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] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
---
 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 <ashwin@anthropic.com>
Date: Wed, 17 Dec 2025 17:39:12 -0800
Subject: [PATCH 91/93] 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 <noreply@anthropic.com>
---
 .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 <actions@github.com>
Date: Fri, 19 Dec 2025 00:16:21 +0000
Subject: [PATCH 92/93] 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 <actions@github.com>
Date: Fri, 19 Dec 2025 22:12:38 +0000
Subject: [PATCH 93/93] 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"