Session Management — Resume, Restart, and When to Choose Each

The Resume vs Restart Decision

The key question: Are the prior tool results still accurate?

If tool results are stale, Claude will reason about a world that no longer exists. This produces incorrect outputs that are hard to detect — they look plausible but reference old state.

# Decision framework
def should_resume_session(session_id: str, environment_changes: list) -> bool:
    """
    Returns True if resuming makes sense, False if fresh session is better.
    """
    if not environment_changes:
        return True  # Nothing changed — resume is safe

    # Check if changes affect what we were investigating
    stale_tools = check_which_tool_results_are_stale(session_id, environment_changes)

    if len(stale_tools) == 0:
        return True  # Changes don't affect prior tool results — resume

    if len(stale_tools) < 3:
        # Few stale results — resume but mention changes
        return True  # Inform session about changes

    # Many stale results — fresh session with summary is cleaner
    return False

The Resume Path

When resuming, always inform the session about what changed:

# Resume with context about changes
claude --resume "codebase-analysis-2024-01-15" \
  --context "Since the last session: 15 files were modified in the authentication module. 
             The token validation logic in auth/jwt.py was completely rewritten. 
             Please re-analyze the affected areas and update your findings."

Or in the API, inject an update message:

# Load existing session
messages = load_session("codebase-analysis-2024-01-15")

# Add update about environment changes
messages.append({
    "role": "user",
    "content": """Important update since last session:
    15 files were modified in the authentication module since our last analysis.
    Specifically: auth/jwt.py was completely rewritten (token validation logic changed).
    
    Please re-analyze the authentication module to update our security findings.
    Your prior analysis of the payment module remains valid."""
})

# Continue the session
result = run_agent_loop(messages, tools)

The Fresh Session + Summary Path

When starting fresh, inject a summary that gives Claude the context it needs without reproducing stale tool results:

def create_session_summary(previous_session: dict) -> str:
    """
    Creates a concise summary for injection into a fresh session.
    NOT a reproduction of the conversation — a structured briefing.
    """
    return f"""
# Session Continuity Brief

## What We Were Doing
{previous_session['goal']}

## Key Findings (Still Valid)
{format_findings(previous_session['confirmed_findings'])}

## Decisions Made
{format_decisions(previous_session['decisions'])}

## Outstanding Questions
{format_questions(previous_session['open_questions'])}

## What Has Changed Since Last Session
{previous_session['environment_changes']}

## What Needs Re-investigation
{previous_session['stale_areas']}

Continue the investigation from this point, focusing on the outstanding questions 
and re-investigating the stale areas given the changes.
"""

# Fresh session with summary
messages = [
    {"role": "user", "content": create_session_summary(previous_session)}
]
result = run_agent_loop(messages, tools)

Key Takeaways

1. Resume when prior tool results are still accurate — environment hasn’t changed
2. Fresh + summary when environment changed — don’t reason about stale state
3. Always inform resumed sessions about changes — “since last session, X changed”
4. Session summaries are structured briefings, not conversation reproductions
5. Use session names with —resume, not IDs