Manage Session State, Resumption & Forking

# Starting a named investigation session
claude --session-name payment-refactor-investigation \
       "Explore the payment module codebase. Map all files, \
identify the legacy payment gateway integration points, \
and document the data flow from checkout to confirmation."

# Session runs, agent explores, produces findings...
# Work ends for the day.

# ── NEXT DAY ── Resume the named session exactly where it stopped
claude --resume payment-refactor-investigation \
       "Continue from where you left off. Focus next on \
the error handling paths — I'd like to understand \
how payment failures are currently managed."

# The agent resumes with full prior conversation history:
# - The original exploration findings
# - All tool calls and their results
# - The structural map it built yesterday
# It does NOT need to re-explore what it already mapped.

from anthropic_agent_sdk import AgentSession
import asyncio

async def compare_testing_strategies(session_id: str):
    """
    After completing codebase analysis in a shared session,
    fork to explore two testing strategies independently.
    Neither branch contaminates the other.
    """
    # Shared baseline is complete: codebase analysis, architecture map, etc.
    # Neither branch should be influenced by the other's findings.

    # Create two independent branches from the same baseline
    branch_a_session = await AgentSession.fork_session(
        session_id=session_id,
        branch_name="unit-test-strategy"
    )
    branch_b_session = await AgentSession.fork_session(
        session_id=session_id,
        branch_name="integration-test-strategy"
    )

    # Run both branches in parallel — they share the baseline but
    # their subsequent actions are completely independent
    results_a, results_b = await asyncio.gather(
        branch_a_session.run(
            "Explore a unit testing strategy for this codebase. "
            "What unit tests would give the best coverage? "
            "List all mocks you'd need and estimate test count."
        ),
        branch_b_session.run(
            "Explore an integration testing strategy for this codebase. "
            "What integration tests would give the best behaviour coverage? "
            "List infrastructure requirements and estimate test count."
        )
    )

    # Synthesize findings from both branches to make recommendation
    return {
        "unit_test_findings": results_a,
        "integration_test_findings": results_b,
        "recommendation": await synthesize_recommendation(results_a, results_b)
    }

def build_structured_summary(prior_findings: dict, changes_since: list) -> str:
    """
    Build the structured summary injected into a fresh session
    when prior tool results are stale.
    """
    return f"""
## Context from Prior Investigation (verified current as of today)

### Still Valid Findings
{chr(10).join(f"- {finding}" for finding in prior_findings['still_valid'])}

### INVALIDATED — Do NOT rely on these
The following were previously analyzed but have since changed:
{chr(10).join(f"- {change['file']}: {change['nature_of_change']}" 
             for change in changes_since)}

### Current Task Focus
{prior_findings['next_objective']}

### Known Architectural Facts (human-verified, current)
{chr(10).join(f"- {fact}" for fact in prior_findings['verified_facts'])}

---
Begin your analysis from this context. Use tools to read the changed files fresh.
Do NOT assume you have prior knowledge of files listed as INVALIDATED above.
"""

# Usage: inject as system_prompt in the new session
summary = build_structured_summary(
    prior_findings={
        "still_valid": [
            "Payment module is still JWT RS256, no changes",
            "API gateway configuration unchanged",
            "Database schema: orders table unchanged"
        ],
        "next_objective": "Analyze new OAuth 2.0 auth implementation",
        "verified_facts": [
            "Team uses pytest for all unit tests",
            "Production DB is PostgreSQL 15"
        ]
    },
    changes_since=[
        {"file": "auth.py", "nature_of_change": "Refactored from JWT to OAuth 2.0"},
        {"file": "middleware/session.py", "nature_of_change": "New file added for OAuth state"}
    ]
)

# Resume the named session AND inform about what changed
# The agent will re-analyze only the changed files, not everything.
claude --resume payment-refactor-investigation \
  "Since our last session, two files have been modified:
  
  1. src/payment/processor.py — The team added retry logic for 
     network timeouts. Please re-read this file and update your 
     understanding of the payment flow accordingly.
  
  2. src/payment/config.py — New configuration keys added for 
     the retry settings. Please re-read and note the new keys.
  
  All other files you previously analyzed are unchanged.
  After re-analyzing these two files, continue your assessment 
  of the payment module's error handling."