[FEATURE] Self-checkpoint-and-reset tool for long multi-phase tasks

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When Claude Code executes long, multi-phase plans (e.g., 7 phases of a feature implementation), context degrades as the session progresses. By the later phases, the context window is filled with stale tool outputs, code diffs, and conversation history from earlier phases that are no longer relevant. This leaves fewer tokens available for the actual work in later phases, reducing quality and increasing the chance of errors or hallucinations.

Today, the only mitigations are:

User manually runs /clear or /compact between phases -- breaks the autonomous workflow and requires the user to babysit the session
External orchestration (e.g., a shell loop that re-invokes Claude per phase) -- works but requires custom scripting outside of Claude Code
Subagents via the Task tool -- each gets fresh context, but subagents have limited turn budgets and can't access all tools (e.g., no Edit/Write for some agent types)
None of these allow Claude to autonomously execute a full multi-phase plan with fresh context per phase within a single session.

Proposed Solution

A Checkpoint or ResetContext tool available to the agent that:

Writes state to a designated file (plan progress, current phase, key decisions, files modified)
Clears the conversation context
Automatically resumes by reading the state file and CLAUDE.md, continuing from the next phase
This would enable a workflow like:

Phase 1 → execute → update plan file → checkpoint/reset →
Phase 2 → execute → update plan file → checkpoint/reset →
...
Phase 7 → execute → mark complete
Each phase gets a full context window. The plan file (e.g., @fix_plan.md) serves as persistent memory across resets.

Why This Matters

Multi-phase plans are common in real-world development (new features, large refactors, multi-file bug fixes)
Context quality directly impacts code quality in later phases
Users currently must choose between autonomous execution (degraded context) or manual intervention (defeats the purpose of agentic coding)
The agent already knows when it transitions between phases -- it just lacks the ability to act on that knowledge by reclaiming context

Alternative Solutions

/clear - Requires user intervention, breaks autonomy
/compact - Lossy summarization, user-initiated only
External loop (Ralph) - Requires shell scripting outside Claude Code if on windows
Task subagents - Limited turns, restricted tool access, not a full session

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

A user asks Claude Code to implement a new feature: adding a parental consent system to a web application. The plan breaks down into 7 phases:

Phase 1: Database models and migrations
Phase 2: Backend API endpoints
Phase 3: Email notification service
Phase 4: Frontend consent form components
Phase 5: Frontend parent dashboard integration
Phase 6: End-to-end integration and wiring
Phase 7: Testing, error handling, and polish
What happens today (without checkpoint/reset):

By phase 3, context is nearly half full with stale tool outputs -- hundreds of lines of Edit results, Bash outputs, and file reads from phases 1-2 that are no longer relevant.

By phase 5, Claude starts losing track of the plan structure, skips tasks, or produces lower-quality code. The context window is 75% consumed by history that has no bearing on the current phase.

By phase 7 -- testing and polish, the phase that requires understanding the entire system -- auto-compaction has silently dropped early decisions and the user's original requirements. Claude is working with roughly 5% of available context, effectively blind to the big picture.

The user has two bad options:

Babysit the session -- manually type /clear between each phase, re-explain what's happening, and point Claude back to the plan file. This defeats the purpose of autonomous execution and requires the user to stay present for the entire multi-hour workflow.

Accept degraded output -- let Claude push through with shrinking context and spend time afterward finding and fixing the mistakes from later phases. The phases that need the most care (integration, testing) get the least.

What happens with checkpoint/reset:

Between phases, Claude updates the plan file (marks Phase N complete, notes decisions or blockers), calls the Checkpoint tool, and the context resets. CLAUDE.md reloads, Claude reads the updated plan file, and picks up at Phase N+1 with a full context window.

Every phase executes with the same quality. Phase 7 gets the same context budget as Phase 1. The plan file serves as persistent memory across resets. The user walks away and comes back to a completed feature.

Why this matters most for later phases: Phases 5-7 involve the most complex work -- integration across the full stack, wiring frontend to backend, and testing edge cases. These are exactly the phases that suffer most from context exhaustion, and exactly the phases where full context matters most. Today, they get the least.

Additional Context

_No response_