The whole hunk
from line 809, old and new numbered
/
lines
from line 809
809809| `resume` | `str \| None` | `None` | Session ID to resume |
810810| `session_id` | `str \| None` | `None` | Use a specific session ID instead of an auto-generated one. Must be a valid UUID. Can't be combined with `continue_conversation` or `resume` unless `fork_session` is also set |
811811| `max_turns` | `int \| None` | `None` | Maximum agentic turns (tool-use round trips) |
812| `max_budget_usd` | `float \| None` | `None` | Stop the query when the client-side cost estimate reaches this USD value. Compared against the same estimate as `total_cost_usd`. For accuracy caveats and reset behavior, see [Track cost and usage](/docs/en/agent-sdk/cost-tracking) |
812| `max_budget_usd` | `float \| None` | `None` | Stop the query when the client-side cost estimate reaches this USD value. Counts only the call's own spend; totals restored from a resumed session don't count. For accuracy caveats and reset behavior, see [Track cost and usage](/docs/en/agent-sdk/cost-tracking) |
813813| `disallowed_tools` | `list[str]` | `[]` | Tools to deny. A bare name such as `"Bash"` removes the tool from Claude's context. A scoped rule such as `"Bash(rm *)"` leaves the tool available and denies matching calls in every permission mode, including `bypassPermissions`, for the command [as written](/docs/en/permissions#bash-rule-limits). See [Permissions](/docs/en/agent-sdk/permissions#allow-and-deny-rules) |
814814| `enable_file_checkpointing` | `bool` | `False` | Enable file change tracking for rewinding. See [File checkpointing](/docs/en/agent-sdk/file-checkpointing) |
815815| `model` | `str \| None` | `None` | Claude model alias or full model name. See [accepted values and provider-specific IDs](/docs/en/model-config#available-models) |
from line 1625
16251625
16261626The `model_usage` dict maps model names to per-model usage. It covers every model call made through the query pipeline: the main loop, subagents, and internal calls such as compaction and Workflow agents. Helper calls outside that pipeline, such as the permission classifier and token-counting requests, are excluded from `model_usage`. Treat `model_usage` as an estimate, not a billing statement.
16271627
1628In [streaming input mode](/docs/en/agent-sdk/streaming-vs-single-mode), `model_usage` and `total_cost_usd` are cumulative across turns, so read the latest result rather than summing across results. See [Track costs in streaming input mode](/docs/en/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode) for resets and [Recover totals after a session crash](/docs/en/agent-sdk/cost-tracking#recover-totals-after-a-session-crash) for zeroed results.
1628In [streaming input mode](/docs/en/agent-sdk/streaming-vs-single-mode), `model_usage` and `total_cost_usd` are cumulative across turns, so read the latest result rather than summing across results. A call that resumes a session also counts the [totals restored from the session's earlier calls](/docs/en/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls). See [Track costs in streaming input mode](/docs/en/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode) for resets and [Recover totals after a session crash](/docs/en/agent-sdk/cost-tracking#recover-totals-after-a-session-crash) for zeroed results.
16291629
16301630Each value in `model_usage` is a `ModelUsage` TypedDict, imported via `from claude_agent_sdk.types import ModelUsage`. Its keys use camelCase because the SDK passes the value through unmodified from the underlying CLI process, matching the TypeScript [`ModelUsage`](/docs/en/agent-sdk/typescript#modelusage) type:
16311631
from line 2653
26532653 "command": str | None, # Shell script; each stdout line is an event, exit ends the watch
26542654 "ws": dict | None, # WebSocket source: {"url": str, "protocols": list[str] | None}; each text frame is an event
26552655 "description": str, # Short description shown in notifications
2656 "timeout_ms": int | None, # Kill after this deadline (default 300000, max 3600000)
2657 "persistent": bool | None, # Run for the lifetime of the session; stop with TaskStop
2656 "timeout_ms": int | None, # Deadline in milliseconds (default 300000, max 3600000; the effective deadline is at most 1800000)
26582657}
26592658```
26602659
from line 2662
26632662```python theme={null}
26642663{
26652664 "taskId": str, # ID of the background monitor task
2666 "timeoutMs": int, # Timeout deadline in milliseconds (0 when persistent)
2667 "persistent": bool | None, # True when running until TaskStop or session end
2665 "timeoutMs": int, # The watch's effective deadline in milliseconds
2666 "persistent": bool | None, # False: every watch has a deadline
26682667}
26692668```
26702669
from line 3051
30523051
30533052### TaskOutput
30543053
3055**Tool name:** `TaskOutput`. The previous name `BashOutput` is still accepted as an alias.
3054Removed in Claude Code v2.1.277. Previously retrieved output from a running or completed background task, with `BashOutput` accepted as an alias; Claude reads a background task's output file with `Read` instead.
30563055
3057<Note>`TaskOutput` is deprecated; prefer `Read` on the task's output file path. The schemas below remain valid for hooks and permission handlers that encounter the tool.</Note>
3056A `disallowed_tools` entry or a deny rule that still names either name is ignored without a warning.
30583057
3059**Input:**
3060
3061```python theme={null}
3062{
3063 "task_id": str, # The task ID to get output from
3064 "block": bool, # Whether to wait for completion (default True)
3065 "timeout": int, # Max wait time in ms (default 30000)
3066}
3067```
3068
3069**Output:**
3070
3071```python theme={null}
3072{
3073 "retrieval_status": "success" | "timeout" | "not_ready", # Whether the output was retrieved
3074 "task": dict | None, # Task details: task_id, task_type, status, description, output, plus type-specific fields such as exitCode
3075}
3076```
3077
30783058### TaskStop
30793059
30803060**Tool name:** `TaskStop`. The previous names `KillShell` and `KillBash` are still accepted as aliases.
from line 3294
33143294 enableWeakerNestedSandbox: bool
33153295```
33163296
3317| Property | Type | Default | Description |
3318| :-------------------------- | :---------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3319| `enabled` | `bool` | `False` | Enable sandbox mode for command execution |
3320| `autoAllowBashIfSandboxed` | `bool` | `True` | Auto-approve bash commands when sandbox is enabled |
3321| `excludedCommands` | `list[str]` | `[]` | Commands that always bypass sandbox restrictions (e.g., `["docker"]`). These run unsandboxed automatically without model involvement |
3322| `allowUnsandboxedCommands` | `bool` | `True` | Allow the model to request running commands outside the sandbox. When `True`, the model can set `dangerouslyDisableSandbox` in tool input, which falls back to the [permissions system](#permissions-fallback-for-unsandboxed-commands) |
3323| `network` | [`SandboxNetworkConfig`](#sandboxnetworkconfig) | `None` | Network-specific sandbox configuration |
3324| `ignoreViolations` | [`SandboxIgnoreViolations`](#sandboxignoreviolations) | `None` | Configure which sandbox violations to ignore |
3325| `enableWeakerNestedSandbox` | `bool` | `False` | Enable a weaker nested sandbox for compatibility |
3297| Property | Type | Default | Description |
3298| :-------------------------- | :---------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3299| `enabled` | `bool` | `False` | Enable sandbox mode for command execution |
3300| `autoAllowBashIfSandboxed` | `bool` | `True` | Auto-approve bash commands when sandbox is enabled |
3301| `excludedCommands` | `list[str]` | `[]` | Commands that bypass sandbox restrictions, such as `["docker *"]`. These run unsandboxed automatically without model involvement; [`sandbox.excludedCommands`](/docs/en/settings-reference#sandbox-excludedcommands) covers when an entry applies |
3302| `allowUnsandboxedCommands` | `bool` | `True` | Allow the model to request running commands outside the sandbox. When `True`, the model can set `dangerouslyDisableSandbox` in tool input, which falls back to the [permissions system](#permissions-fallback-for-unsandboxed-commands) |
3303| `network` | [`SandboxNetworkConfig`](#sandboxnetworkconfig) | `None` | Network-specific sandbox configuration |
3304| `ignoreViolations` | [`SandboxIgnoreViolations`](#sandboxignoreviolations) | `None` | Configure which sandbox violations to ignore |
3305| `enableWeakerNestedSandbox` | `bool` | `False` | Enable a weaker nested sandbox for compatibility |
33263306
33273307<Note>
33283308 The sandbox depends on platform support and, on Linux, tools like `bubblewrap` and `socat`. By default, when `enabled` is `True` but the sandbox can't start, commands run unsandboxed with a warning on stderr. This default differs from the TypeScript SDK, where `failIfUnavailable` defaults to `true`.
from line 3395
34153395
34163396### Permissions Fallback for Unsandboxed Commands
34173397
3418When `allowUnsandboxedCommands` is enabled, the model can request to run commands outside the sandbox by setting `dangerouslyDisableSandbox: True` in the tool input. These requests fall back to the existing permissions system, meaning your `can_use_tool` handler will be invoked, allowing you to implement custom authorization logic. Commands listed in `excludedCommands` instead bypass the sandbox automatically, with no model involvement; see [`SandboxSettings`](#sandboxsettings).
3398When `allowUnsandboxedCommands` is enabled, the model can request to run commands outside the sandbox by setting `dangerouslyDisableSandbox: True` in the tool input. These requests fall back to the existing permissions system, meaning your `can_use_tool` handler is invoked, allowing you to implement custom authorization logic.
3399
3400Your `excludedCommands` entries instead take a call out of the sandbox with no model involvement; [`sandbox.excludedCommands`](/docs/en/settings-reference#sandbox-excludedcommands) covers when an entry applies.
34193401
34203402The following example logs each unsandboxed request and denies it unless your own authorization logic allows it:
34213403