[BUG] Session Token Expiry Kills Active Agents Without Warning

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Claude Code Issue Report — Session Token Expiry Kills Active Agents Without Warning

Date: 2026-03-22
Claude Code Version: (check with claude --version)
Filed by: David Lewis, Lucid Dream Software

Bug Summary

Claude Code session auth token expired while 5 parallel agents were actively modifying code across 2 repositories. No warning was given before the expiry. All agents were killed mid-execution, and the user had to manually recover from a partially-applied state.

What Happened

1. User initiated a complex BB-013 implementation session spanning ~3 hours of planning work (12 work items, architectural analysis, dual-agent review cycle)
2. 5 agents were spawned in parallel (1 Opus, 4 Sonnet) to implement the planned work items across 2 repos
3. Mid-execution, the auth token expired silently
4. All 5 agents were killed — no graceful shutdown, no state persistence, no warning
5. The session's conversation context (containing ~90,000 characters of planning documents that were never saved to files) became inaccessible

Impact

• 3 of 5 agents' committed work was lost (worktrees cleaned up, commits not merged to target branch)
• 12 planning documents (~90K chars) existed only in conversation context and were lost
• ~3 hours of planning work had to be reverse-engineered from the JSONL transcript
• 1 agent's work survived only because it happened to commit to the main working tree
• 1 agent's work survived in a worktree that wasn't cleaned up

What Should Happen Instead

1. Warning before token expiry: If the system knows the token TTL, warn the user 5-10 minutes before expiry: "Your session will expire in 5 minutes. X agents are running. Consider saving your work."

1. Graceful agent shutdown: Before killing agents, attempt to:

• Commit any staged changes
• Save agent state/progress
• Merge completed worktree branches
• At minimum, log what each agent was doing

1. Plan/context persistence: Long-running sessions accumulate significant planning context in conversation. This should be periodically checkpointed so it survives session loss.

1. Token refresh: If possible, refresh the token transparently without killing the session. Most OAuth implementations support this.

1. Recovery mode: After re-login, offer to resume the session with context intact rather than starting fresh.

Reproduction Steps

1. Start a Claude Code session
2. Spawn multiple background agents with run_in_background: true
3. Wait for auth token to expire (or manually revoke to simulate)
4. Observe: all agents die silently, no warning, no state saved

Environment

• macOS Darwin 25.4.0
• Claude Code CLI
• Model: Claude Opus 4.6 (1M context)
• 5 parallel agents (1 Opus + 4 Sonnet)
• 2 repos being modified simultaneously

Files for Reference

• Transcript: /Users/davidlewis/.claude/projects/-Users-davidlewis-Development-LucidDream/e43ca3d6-32f1-409b-adc4-9c88154d6777.jsonl (2.3MB)
• This was a production session, not a test — real code for a real product with a customer installation deadline

What Should Happen?

WARN FIRST!! Give the user a chance to save active data

Error Messages/Logs

Steps to Reproduce

Be working on a complex and difficult task with multiple agents and then suddenly have it shut off to Login

Claude Model

Opus

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

Claude Code v2.1.81

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_