Agent SDK reference - Python changedagent-sdk/python
Nearest release: v2.1.282, published 6 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 24 Sep 2026 22:40 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 24 Sep 2026 23:07 UTC.
Upstream edited
Recorded here
Lines+13added
Lines−13removed
From line
821
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits32to this page, all time
The whole hunk
from line 821, old and new numbered
/
from line 821
821821| `cli_path` | `str \| Path \| None` | `None` | Custom path to the Claude Code CLI executable |
822822| `settings` | `str \| None` | `None` | Path to a settings file or an inline JSON string |
823823| `add_dirs` | `list[str \| Path]` | `[]` | Additional directories Claude can access. The SDK passes each entry to Claude Code as `--add-dir`, so with the `project` setting source Claude Code also [loads the directory's skills, commands, and subagents](/docs/en/permissions#additional-directories-grant-file-access-not-configuration) |
824| `env` | `dict[str, str]` | `{}` | Environment variables merged on top of the inherited process environment. See [Environment variables](/docs/en/env-vars) for variables the underlying CLI reads, and [Handle slow or stalled API responses](#handle-slow-or-stalled-api-responses) for timeout-related variables |
824| `env` | `dict[str, str]` | `{}` | Environment variables merged on top of the inherited process environment. See [Environment variables](/docs/en/env-vars) for variables the underlying CLI reads, and [Handle slow or stalled API responses](#handle-slow-or-stalled-api-responses) for timeout-related variables. Set `CLAUDE_AGENT_SDK_CLIENT_APP` to identify your app in the User-Agent header |
825825| `extra_args` | `dict[str, str \| None]` | `{}` | Additional CLI arguments to pass directly to the CLI |
826826| `max_buffer_size` | `int \| None` | `None` | Maximum bytes when buffering CLI stdout |
827| `debug_stderr` | `Any` | `sys.stderr` | *Deprecated* - File-like object for debug output. Use `stderr` callback instead |
827| `debug_stderr` | `Any` | `sys.stderr` | *Deprecated* - The SDK ignores this value. Use the `stderr` callback for CLI stderr output |
828828| `stderr` | `Callable[[str], None] \| None` | `None` | Callback function for stderr output from CLI |
829829| `can_use_tool` | [`CanUseTool`](#canusetool) ` \| None` | `None` | Tool permission callback, invoked only when the [permission flow](/docs/en/agent-sdk/permissions#how-permissions-are-evaluated) falls through to a prompt. Not invoked for calls auto-approved by `allowed_tools`, allow rules, or `permission_mode`. An allow rule doesn't pre-approve the [actions no mode auto-approves](/docs/en/permission-modes#actions-no-mode-auto-approves). See [`CanUseTool`](#canusetool) for details |
830830| `hooks` | `dict[HookEvent, list[HookMatcher]] \| None` | `None` | Hook configurations for intercepting events |
831| `user` | `str \| None` | `None` | User identifier |
831| `user` | `str \| None` | `None` | On POSIX platforms, the OS user account the Claude Code subprocess runs as. Claude Code keeps the parent process's environment, including `HOME`, and runs in `cwd` |
832832| `include_partial_messages` | `bool` | `False` | Include partial message streaming events. When enabled, [`StreamEvent`](#streamevent) messages are yielded |
833833| `include_hook_events` | `bool` | `False` | Include hook lifecycle events in the message stream as `HookEventMessage` objects |
834834| `forward_subagent_text` | `bool` | `False` | Forward subagent text and thinking blocks in the message stream. Without this option, Claude Code emits subagent `tool_use` and `tool_result` blocks but not text or thinking. Requires Python Agent SDK 0.2.140 or later |
from line 1704
17041704 raw: dict[str, Any] = field(default_factory=dict)
17051705```
17061706
1707| Field | Type | Description |
1708| :------------------------ | :------------------------ | :---------------------------------------------------------------------------------------------------- |
1709| `status` | `RateLimitStatus` | Current status. `"allowed_warning"` means approaching the limit; `"rejected"` means the limit was hit |
1710| `resets_at` | `int \| None` | Unix timestamp when the rate limit window resets |
1711| `rate_limit_type` | `RateLimitType \| None` | Which rate limit window applies |
1712| `utilization` | `float \| None` | Fraction of the rate limit consumed (0.0 to 1.0) |
1713| `overage_status` | `RateLimitStatus \| None` | Status of pay-as-you-go overage usage, if applicable |
1714| `overage_resets_at` | `int \| None` | Unix timestamp when the overage window resets |
1715| `overage_disabled_reason` | `str \| None` | Why overage is unavailable, if status is `"rejected"` |
1716| `raw` | `dict[str, Any]` | Full raw dict from the CLI, including fields not modeled above |
1707| Field | Type | Description |
1708| :------------------------ | :------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1709| `status` | `RateLimitStatus` | Current status, one of `"allowed"`, `"allowed_warning"`, or `"rejected"`. `"allowed_warning"` means approaching the limit; `"rejected"` means the limit was hit |
1710| `resets_at` | `int \| None` | Unix timestamp when the rate limit window resets |
1711| `rate_limit_type` | `RateLimitType \| None` | Which rate limit window applies |
1712| `utilization` | `float \| None` | Fraction of the rate limit consumed (0.0 to 1.0) |
1713| `overage_status` | `RateLimitStatus \| None` | Status of pay-as-you-go overage usage, if applicable |
1714| `overage_resets_at` | `int \| None` | Unix timestamp when the overage window resets |
1715| `overage_disabled_reason` | `str \| None` | Why overage is unavailable, if status is `"rejected"` |
1716| `raw` | `dict[str, Any]` | Full raw dict from the CLI, including fields not modeled above |
17171717
17181718### `ConversationResetMessage`
17191719
No line in this hunk matches that.