Replace all dated model references (claude-sonnet-4-20250514,
claude-3-5-sonnet-20241022) with the simplified claude-sonnet-4-5
identifier across examples, tests, and documentation.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Claude <noreply@anthropic.com>
## Summary
- Adds `set_permission_mode()` method to dynamically change permission
modes during streaming sessions
- Adds `set_model()` method to switch AI models mid-conversation
- Implements control protocol support matching the TypeScript SDK's
capabilities
## Motivation
The TypeScript SDK supports dynamic control through
`setPermissionMode()` and `setModel()` methods on the Query interface.
This PR brings the same functionality to the Python SDK, allowing users
to:
1. Start with restrictive permissions for code review, then switch to
`acceptEdits` for implementation
2. Use different models for different parts of a task (e.g., Sonnet for
complex analysis, Haiku for simple tasks)
3. Adjust permissions based on workflow needs without restarting
sessions
## Changes
- **ClaudeSDKClient**: Added `set_permission_mode(mode)` and
`set_model(model)` methods
- **Internal Query class**: Added `set_model(model)` method to send
control requests
- **E2E tests**: Added comprehensive tests verifying the functionality
works with real API calls
## Test Plan
- [x] All existing unit tests pass (102 tests)
- [x] New E2E tests added and passing:
- `test_set_permission_mode`: Verifies permission mode changes take
effect
- `test_set_model`: Confirms model switching works mid-conversation
- `test_interrupt`: Validates interrupt capability
- [x] Type checking passes (`mypy`)
- [x] Linting passes (`ruff`)
## Usage Example
```python
async with ClaudeSDKClient() as client:
# Start with default permissions for review
await client.query("Analyze this code for issues")
# Switch to auto-accept edits for implementation
await client.set_permission_mode('acceptEdits')
await client.query("Now fix the issues we found")
# Use a different model for simpler tasks
await client.set_model('claude-3-5-haiku-20241022')
await client.query("Add a simple docstring")
```
🤖 Generated with [Claude Code](https://claude.ai/code)
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Ashwin Bhat <ashwin@anthropic.com>
## Summary
- Add support for custom agent definitions via `agents` option
- Add support for controlling setting sources via `setting_sources`
option
- Add `/commit` slash command to project
- Add examples demonstrating both features
- Add e2e tests for verification
## Changes
### Core Implementation
- Add `AgentDefinition` and `SettingSource` types to `types.py`
- Add `agents` and `setting_sources` fields to `ClaudeCodeOptions`
- Update subprocess CLI transport to pass `--agents` and
`--setting-sources` flags
- **Default behavior**: When `setting_sources` is not provided, pass
empty string (no settings loaded)
- Handle empty `setting_sources` array correctly (pass empty string to
CLI)
### Examples
- `examples/agents.py`: Demonstrates custom agent definitions with
different tools and models
- `examples/setting_sources.py`: Shows how setting sources control which
settings are loaded
- Default behavior (no settings)
- User-only settings
- User + project settings
### Tests
- Add e2e tests verifying agents and setting_sources functionality
- Test default behavior (no settings loaded)
- Test filtering by setting source
- Use `output_style` checking to verify settings loaded/not loaded
- Tests use temporary directories for isolated testing
### Project Config
- Add `.claude/commands/commit.md` slash command for git commits
## Test Plan
- [x] E2E tests added for all new functionality
- [ ] CI tests pass
- [ ] Examples run successfully
🤖 Generated with [Claude Code](https://claude.ai/code)
---------
Co-authored-by: Claude <noreply@anthropic.com>
## Summary
- Adds support for streaming partial messages through the
`include_partial_messages` option
- Introduces `StreamEvent` message type to handle Anthropic API stream
events
- Enables real-time streaming of Claude's responses for building
interactive UIs
## Changes
- Added `StreamEvent` dataclass with proper structure matching
TypeScript SDK (uuid, session_id, event, parent_tool_use_id)
- Added `include_partial_messages` boolean option to `ClaudeCodeOptions`
- Updated message parser to handle `stream_event` message type
- Updated subprocess CLI transport to pass `--include-partial-messages`
flag when enabled
- Added example demonstrating partial message streaming usage
## Test plan
- [x] Verified CLI flag is passed correctly when
`include_partial_messages=True`
- [x] Confirmed `StreamEvent` structure matches TypeScript SDK
implementation
- [x] Added test for user parameter in transport
- [x] Example runs successfully with streaming events
🤖 Generated with [Claude Code](https://claude.ai/code)
---------
Co-authored-by: Claude <noreply@anthropic.com>
## Summary
This PR adds support for custom tool callbacks and comprehensive e2e
testing for MCP calculator functionality.
## Key Features Added
- **Custom tool permission callbacks** - Allow dynamic tool permission
control via `can_use_tool` callback
- **E2E test suite** - Real Claude API tests validating MCP tool
execution end-to-end
- **Fixed MCP calculator example** - Now properly uses `allowed_tools`
for permission management
## Changes
### Custom Callbacks
- Added `ToolPermissionContext` and `PermissionResult` types for tool
permission handling
- Implemented `can_use_tool` callback support in SDK client
- Added comprehensive tests in `tests/test_tool_callbacks.py`
### E2E Testing Infrastructure
- Created `e2e-tests/` directory with pytest-based test suite
- `test_mcp_calculator.py` - Tests all calculator operations with real
API calls
- `conftest.py` - Pytest config with mandatory API key validation
- GitHub Actions workflow for automated e2e testing on main branch
- Comprehensive documentation in `e2e-tests/README.md`
### Bug Fixes
- Fixed MCP calculator example to use `allowed_tools` instead of
incorrect `permission_mode`
- Resolved tool permission issues preventing MCP tools from executing
## Testing
E2E tests require `ANTHROPIC_API_KEY` environment variable and will fail
without it.
Run locally:
```bash
export ANTHROPIC_API_KEY=your-key
python -m pytest e2e-tests/ -v -m e2e
```
Run unit tests including callback tests:
```bash
python -m pytest tests/test_tool_callbacks.py -v
```
🤖 Generated with [Claude Code](https://claude.ai/code)
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kashyap Murali <kashyap@anthropic.com>
