Manage Claude Sessions, Resume, Fork, and Persistence

Claude Agent SDK sessions preserve conversation and agent state across exchanges. Use a continuous client for interactive work, capture session IDs from streamed lifecycle/results, resume an existing session for continuity, and fork when exploring an alternative without mutating the original history. Session identity never replaces application authorization or durable business state.

What will you be able to do?

You will capture and resume a session, know when to fork, and list the state that must travel across hosts.

Which API shape should you choose?

Python offers query() for one-off or explicitly resumed exchanges and ClaudeSDKClient for continuous conversations with richer lifecycle control. TypeScript supports continuing through the query interface. Choose the smallest lifecycle that fits the product.

How do you capture and resume?

The durable pattern is:

python

import asyncio

from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query


async def run_once(prompt: str, resume: str | None = None) -> str:
    session_id: str | None = None
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],
        max_turns=4,
        resume=resume,
    )
    async for message in query(prompt=prompt, options=options):
        if isinstance(message, ResultMessage):
            session_id = message.session_id
            if message.subtype != "success":
                raise RuntimeError(f"Claude run stopped: {message.subtype}")
    if session_id is None:
        raise RuntimeError("Claude run ended without a session ID")
    return session_id


async def main() -> None:
    session_id = await run_once("Read README.md and remember its main claim.")
    await run_once("What was the main claim?", resume=session_id)


if __name__ == "__main__":
    asyncio.run(main())

Consult the current reference for message fields and external-storage support before production use.

When should you fork?

Resume continues the same line of work. Fork creates a new branch from an existing session, useful for comparing plans or providers without corrupting the source branch. Store parent/child relationships so evaluation and auditing can distinguish experiments.

What must persist across hosts?

The provider session plus local state it references: working files/checkpoints, project configuration, permissions, prompt/skill files, MCP configuration, tool attempt records, budgets, and application identity. The hosting chapter explains that parts of Claude’s runtime state live on local disk; a session ID alone may not recreate the environment.

How do you prove persistence works?

Resume from a new process, then from a new container with restored storage. Confirm tenant/user authorization before handing the session ID to the SDK. Fork and verify the parent remains unchanged.

Failure injection: Resume a valid session in the wrong working directory. The harness should detect the environment mismatch before execution.

What mistakes should you avoid?

Treating session ID possession as authorization.
Assuming session ID alone captures files and runtime configuration.
Resuming with broader tools than the original policy permits.
Losing budget consumption on resume.
Using fork when the user expects one canonical continuation.

Check your understanding

When is ClaudeSDKClient preferable to one-off query() calls?
What does fork preserve and change?
Which local state may be needed with a session ID?

Expert extension

Design a session registry with tenant binding, environment fingerprint, parent session, retention, tool profile, and last checkpoint. Add mismatch and cross-tenant tests.

Official references