[FEATURE] Threshold-triggered auto-clear with handover doc + auto-resume (alternative to auto-compact)

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

Auto-compact summarises in place and is lossy — decisions, file paths, and rationale get dropped, and there's no reliable way to get ahead of it (see #10691, #14160, #28728, #34925, #52390). Proposed alternative — draft a structured handover document, then start fresh with the handover as the first prompt — beats auto-compact's fidelity but is entirely manual or hook-cobbled today (see #54254, closed as not planned, and third-party projects like claude-skill-handover). There's no native way to (a) trigger this before hard-clearing rather than compacting, (b) trigger it early enough to actually finish writing under context pressure, or (c) surface the resulting handover file(s) in the UI afterwards.

Proposed Solution

Add a setting that swaps auto-compact for auto-clear, with an early-warning interrupt:

1. autoClear.thresholdPercent (e.g. 30) — when context used reaches this threshold, Claude Code runs /clear instead of /compact.
2. At 90% of that threshold (e.g. 27% if the setting is 30), the harness interrupts the current turn and injects: "Please stop where you are and write a handover document to <generated_filename>.md", giving Claude room to finish the doc before the hard clear fires.
3. When the auto-clear fires, the first prompt of the new session is auto-populated with "Read and resume from <path>" — using the same mechanism SessionStart already supports for seeding an initialUserMessage on source: compact.
4. The interrupt and the resulting handover file are logged in scrollback with a clickable link to open the file, with one entry per occurrence if it's happened more than once in a session.

Alternative Solutions

PreCompact hook + a handoff skill (e.g. claude-skill-handover, claude-code-context-handoff) does most of this manually today, but fires at the compact threshold with no early-warning buffer, and doesn't inject an auto-resume prompt or scrollback link without extra scripting. #54254 (/handover) covers the doc-drafting and auto-resume seeding but is user-triggered only and was closed as not planned. Disabling autoCompact and managing /clear by hand works but requires presence and manual handling.

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

1. Long refactor session, autoClear.thresholdPercent set to 30.
2. Context hits 27% remaining (90% of threshold) mid-task — harness interrupts: "stop and write a handover to .claude/handovers/2026-08-27-1610-auth-refactor.md".
3. Claude finishes the doc, confirms.
4. Context hits 30% remaining — /clear fires automatically.
5. New session's first message is auto-populated: "Read and resume from .claude/handovers/2026-08-27-1610-auth-refactor.md".
6. Scrollback shows a note with a clickable link to the handover file, so I can review it later even after the session's moved on.

Note, the main thread that would benefit from this is the orchestrator thread running the subagents across a long complex task.

Additional Context

Related: #10691, #14160, #28728, #34925, #52390, #24856 (auto-compact threshold pain), #54254 and #49146 (handover/session-continuity proposals, both closed/stale), #15923 (PreCompact hook, already implemented). Community prior art: claude-skill-handover, claude-code-context-handoff — both chain PreCompact + SessionStart(initialUserMessage) to approximate this manually.