Agent SDK reference - Python changedagent-sdk/python
Upstream edited this page at 10 Oct 2026 17:34 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 10 Oct 2026 17:37 UTC.
Upstream edited
Recorded here
Lines+45added
Lines−0removed
From line
446
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits61to this page, all time
### `fork_session()`
The whole hunk
from line 446, old and new numbered
/
from line 446
446446 print(session.summary)
447447```
448448
449### `fork_session()`
450
451Copies a session's transcript into a new session so you can take the conversation in another direction while the original stays unchanged. To branch from an earlier point in the conversation, pass `up_to_message_id`. Synchronous.
452
453```python theme={null}
454def fork_session(
455 session_id: str,
456 directory: str | None = None,
457 up_to_message_id: str | None = None,
458 title: str | None = None,
459) -> ForkSessionResult
460```
461
462#### Parameters
463
464| Parameter | Type | Default | Description |
465| :- | :- | :- | :- |
466| `session_id` | `str` | required | UUID of the session to fork |
467| `directory` | `str \| None` | `None` | Project directory path. When omitted, searches all project directories |
468| `up_to_message_id` | `str \| None` | `None` | Copy the transcript up to and including the message with this UUID, such as a `uuid` from [`get_session_messages()`](#get_session_messages). When omitted, copies the whole transcript |
469| `title` | `str \| None` | `None` | Title for the fork. When omitted, the SDK derives one from the original session, followed by `(fork)` |
470
471Returns a `ForkSessionResult` whose `session_id` is the new session's UUID. Pass it as [`resume`](#claudeagentoptions) to continue the fork. The fork doesn't include the original session's [file checkpoints](/docs/en/agent-sdk/file-checkpointing), so you can't rewind it to a checkpoint captured before the fork.
472
473`fork_session()` raises:
474
475* `ValueError`: `session_id` or `up_to_message_id` is not a valid UUID
476* `ValueError`: the session has no messages, or `up_to_message_id` matches no message in the transcript
477* `FileNotFoundError`: the session cannot be found
478
479#### Example
480
481Fork the most recent session under a new title, then resume the fork. The original session keeps its own history.
482
483```python theme={null}
484from claude_agent_sdk import fork_session, list_sessions
485
486sessions = list_sessions(directory="/path/to/project", limit=1)
487if sessions:
488 forked = fork_session(sessions[0].session_id, title="Try the OAuth approach")
489 print(forked.session_id) # pass as ClaudeAgentOptions(resume=...) to continue the fork
490```
491
449492## Classes
450493
451494### `ClaudeSDKClient`
from line 1715
16721715* `errors`: loop-level error strings such as the max-turns message. Populated only on the `error_*` subtypes.
16731716* `terminal_reason`: why the query loop ended, such as `"completed"`, `"max_turns"`, `"api_error"`, `"aborted_streaming"`, or `"aborted_tools"`. A value of `"aborted_streaming"` or `"aborted_tools"` means the turn was aborted before completing. Common causes are [`interrupt()`](#claudesdkclient) and a permission callback returning [`PermissionResultDeny`](#permissionresultdeny) with `interrupt=True`. `None` on CLI versions that predate the field, on results from local commands such as `/voice` or `/usage`, which bypass the query loop, or on synthesized error results emitted when the session fails fatally. Mirrors the TypeScript SDK's [`SDKResultMessage.terminal_reason`](/docs/en/agent-sdk/typescript#sdkresultmessage), which lists the full set of values.
16741717* `origin`: origin of the user message that triggered this turn. In [streaming input mode](/docs/en/agent-sdk/streaming-vs-single-mode), check this to tell the result of your own prompt, where `origin` is `None` or `{"kind": "human"}`, from the result of an injected turn such as a background-task notification. Requires Python Agent SDK 0.2.137 or later.
1718
1719When several background tasks finish close together, Claude Code can answer their notifications in one turn rather than one turn each. You still receive one `ResultMessage` per notification, in order, each with an `origin` whose `kind` is `"task-notification"`. All but the last have `num_turns` set to `0` and an empty `result`, and the last one carries the turn that answers them all.
16751720
16761721The `usage` dict covers the main agent loop only and excludes subagent and other nested or auxiliary model calls. In [streaming input mode](/docs/en/agent-sdk/streaming-vs-single-mode), the values are per-turn. Prefer `model_usage` for token and cost accounting. The `usage` dict contains the following keys when present:
16771722
No line in this hunk matches that.