Feature: Fine-grained compaction controls (partial compaction, boundary-aware, compaction context)

Problem

Currently, /compact summarizes the conversation as a whole — the user has no control over what gets compacted, where the boundary falls, or how aggressively the summarization behaves. This causes two problems:

1. Loss of momentum — in-progress work gets summarized alongside completed work, losing the "working memory" that makes a session productive.
2. Semantic erosion — system-level context (plugin preferences, behavioral rules, session-start outputs) degrades across compaction cycles. Each summarization slightly paraphrases, and "always use git worktrees, never commit to main, always branch → MR → auto-merge" becomes "prefers worktrees" after a few rounds.

Related Issues

| Issue | Ask | Status |
|---|---|---|
| #34806 | Configurable forward size (how much survives) | Open |
| #1301 | /compact 50 — partial compaction by percentage | Closed |
| #26488 | --from parameter for non-interactive partial compact | Closed |

This request builds on those by adding semantic awareness (what to compact) on top of mechanical controls (how much to compact).

What Exists Today

• CLAUDE_AUTOCOMPACT_PCT_OVERRIDE — controls when auto-compact triggers (default ~83%)
• /compact [instructions] — manual compaction with optional custom prompt
• PreCompact / PostCompact hooks — inject hints before/after compaction
• DISABLE_COMPACT — disables compaction entirely

These give timing control but no control over what gets summarized vs preserved.

Proposed: Fine-Grained Compaction Controls

1. Semantic boundary detection

Don't just preserve the last N% — detect task completion boundaries:

• Completed tasks (marked completed in task system) → summarize aggressively to bullet points
• In-progress or pending tasks → preserve verbatim
• Recent tool results not yet acted on → preserve verbatim
• Design decisions still being discussed → preserve verbatim

The compactor should look for natural breakpoints (task completions, commits, PR merges) rather than using arbitrary message counts.

2. Protected context tiers (never-summarize list)

Some context must survive compaction verbatim across any number of cycles:

• Plugin behavioral context — preference registries (e.g., APE adaptive preferences), output style configs, skill settings established at session start
• System instructions — CLAUDE.md references, persistence routing rules, hook-established behavioral contracts
• Active state — in-progress task lists, uncommitted changes, pending git operations
• Session identity — monitor state with actionable items, memory file paths referenced during the session

These should be a first-class config, not just hints via PreCompact hooks:

{
  "compaction": {
    "never_summarize": [
      "plugin_context",
      "active_tasks",
      "session_start_outputs",
      "system_instructions"
    ]
  }
}

3. Configurable preserve ratio

Allow users to control how much recent conversation is kept raw:

• compaction_preserve_ratio: 0.5 — keep the most recent 50% of context verbatim, only summarize the oldest 50%
• compaction_aggressiveness: "moderate" — light summary vs dense compression for the summarized portion

4. Compaction context markers

Let the task system and hooks annotate what's safe to compact:

• Tasks marked completed → tagged as compact-safe
• Tasks marked in_progress → tagged as preserve
• User/hook annotation: "this section is done, compact-safe"
• Plan files → always preserve

5. User-configurable summarization instructions

First-class config (not just hook hints) that guides the summarizer:

{
  "compaction": {
    "preserve_ratio": 0.5,
    "custom_instructions": "Preserve all in-progress tasks verbatim. Summarize completed work into bullet points. Always preserve file paths, function names, and design decisions.",
    "never_summarize": ["plugin_context", "active_tasks"],
    "aggressiveness": "moderate"
  }
}

Use Case

In long coding sessions with plugins (APE preferences, monitor hooks, custom skills), users work on multiple tasks sequentially. Early tasks are done and can be compressed. But the current task has critical context, and plugin behavioral rules must survive every compaction cycle without degradation.

The ideal compaction: aggressive on the past, gentle on the present, hands-off on system context.

Current Workarounds

• PreCompact hook to inject preservation hints (best-effort — the LLM tries to follow them but the message slicing is still mechanical)
• Running /compact manually at task boundaries (requires user discipline)
• DISABLE_COMPACT (hits context limits)
• Third-party tools like decant operating on session JSONL files offline

None give hard constraints on what gets preserved vs summarized.

---

🤖 Generated with Claude Code