Better tools for long-term work: detecting remaining context + new_session tool for AI

[taoeffect]

Description

(NOTE: I just noticed after creating a PR that I was supposed to create a discussion thread first. My apologies, I already created a feature request issue first: #2331)

Problem / Motivation

When working with massive code bases on very large tasks, the context window will easily be filled up.

The current solution for handling this is not ideal: Crush will automatically interrupt the work via an auto-compaction algorithm and start a new session. This works OK but is not ideal because the auto-compaction instructions in internal/agent/templates/summary.md are fixed and cannot be modified or adjusted by either the user or the LLM, severely limiting the use-cases for managing long-running sessions.

There are many use-cases that could benefit from a new design:

• When working through agentic workflows like the tasks skill, where the AI methodically works through a massive list of TODOs.
• When wanting to start a fresh session based on the context of the current one, but with a custom summary
• When wanting to customize the conditions that trigger a new session / compaction

Solution / Design

Introduce a compaction method toggle (auto vs llm) and two complementary mechanisms that give the AI agent direct control over context management.

1. Context status injection

When compaction is set to llm, a <context_status> system message is appended to every turn:

<context_status>{"used_pct":72,"remaining_tokens":56000,"context_window":200000}</context_status>

This gives the AI real-time visibility into context consumption so it can plan ahead — wrapping up current work, writing progress to disk, or proactively starting a new session before context runs out.

Users can also give custom instructions to the LLM on when to begin a new session and how exactly to summarize the new session.

Note

This context message is not injected when the compaction method is set to auto (the default).

2. new_session tool

A new agent tool that lets the AI create a fresh session and carry forward a structured summary as the first message. The tool accepts a summary parameter describing what's been accomplished and what remains. When invoked, the current session ends and a new one begins automatically with the summary as its initial prompt.

The new_session tool is only registered when compaction is set to llm mode. In auto mode, the tool is hidden so as to not cause any conflict with the existing auto-compaction tooling. This also saves a tiny amount of tokens.

4. Compaction method selector

A new command palette dialog ("Select Compaction Method") lets users toggle between auto and llm modes at any time. The selection persists to the data config and takes effect immediately.

---

A PR will be submitted along with this issue and this issue will be edited to link to it.