(feat) Enhance Auto-Summarization with Goal-Directed Handoff

[francescoalemanno]

Feature Proposal: Enhance Auto-Summarization with Goal-Directed Handoff

PR : #2142

Problem

Crush currently manages context window pressure with auto-summarization: when remaining tokens drop below a threshold, the model produces a structured summary that replaces the conversation history. This has three known issues:

1. Blind extraction. The summary prompt is generic — it captures everything equally rather than prioritizing what matters for the next task. A 50-message debugging session might preserve debugging details you'll never revisit while dropping the architectural decision you actually need.

2. No look-back. Once summarized, the original messages are gone. If the summary missed something, it's lost. There's no way to search or revisit the pre-summary conversation.

3. Worst-case timing. Summarization triggers when context is nearly full — precisely when the model is most degraded and least likely to produce a good summary.

OpenAI's own internal Codex report confirmed that recursive summarization (summaries of summaries) distorts earlier reasoning, with accuracy declining as compaction count increases. Amp retired compaction entirely in October 2025 for these reasons.

Proposal: Handoff

Replace auto-summarization with a two-part system:

1. /handoff command with goal-directed enrichment

The user triggers handoff manually (or it's forced near capacity) with a stated goal:

/handoff now implement the API layer we designed
/handoff check the rest of the codebase for the same bug pattern

An enrichment subagent analyzes the current conversation through the lens of that goal, extracting only what's relevant. The result is placed in a fresh session as the opening context. The user can review and edit before submitting.

This is fundamentally different from summarization: instead of "compress everything," it's "extract what I need for this specific next step."

2. search_in_the_past tool with archived context

When a handoff occurs, the original messages aren't discarded — they're archived as searchable text in memory. A new search_in_the_past tool spawns a subagent equipped with mini-tools (past_context_grep, past_context_read, past_context_stats) that can navigate the full archived history.

This means: if the enrichment step missed something, the agent can still find it. Across multiple handoffs, the archive accumulates, giving the agent access to the entire session's history without bloating the active context window.

Why This Matters

• User control. Users decide when to hand off and what direction to go, rather than having the model silently compress at the worst moment.
• Quality preservation. Fresh context with curated information beats a degraded context with a lossy summary.
• Safety net. Forced handoff at ~95% capacity prevents the model from silently degrading. The archive + search means nothing is truly lost.
• Longer work sessions. Multi-hour, multi-phase projects become viable without the "start over and re-explain everything" friction.

Implementation Scope

The feature would involve:

• PastContext storage — thread-safe in-memory store for archived message text, with grep and line-range read support
• Message rendering — serialize Crush's message types into a grep-friendly text format with boundary tags
• Enrichment subagent — a SessionAgent (following the existing agentic_fetch_tool.go pattern) that receives the archived context + user goal and extracts relevant information
• search_in_the_past tool — another SessionAgent with three mini-tools for navigating the archive, registered alongside existing tools
• /handoff command — TUI integration with manual trigger + forced trigger near capacity
• 4 embedded prompt markdowns — explorer system/template, enrichment system/template

Crush already has the infrastructure this needs: SessionAgent spawning from tools (agentic fetch), embedded markdown prompts, tool registration, and the TUI command system. The heaviest lift is adapting message rendering to Crush's message types and wiring the enrichment flow through the coordinator.

Prior Art

• Amp's Handoff — replaced compaction with goal-directed handoff + thread references
• Amp's context management guide — philosophy of short, focused threads over long meandering ones
• Amp's "200k Tokens Is Plenty" — argument for clusters of small threads connected by handoffs