@bastani/atomic 0.8.27-alpha.1 → 0.8.28-alpha.1

package/docs/compaction.md

@@ -1,32 +1,54 @@
 # Compaction & Branch Summarization
 
-LLMs have limited context windows. When conversations grow too long, Atomic's default compaction path uses **Verbatim Compaction**: it deletes safe older transcript objects while preserving every retained object exactly as it was recorded. This page covers default auto/manual compaction, legacy summary compaction internals, and branch summarization.
+LLMs have limited context windows. When conversations grow too long, Atomic's compaction behavior uses **Verbatim Compaction**: it deletes safe older transcript objects while preserving every retained object exactly as it was recorded. This page covers default auto/manual compaction, how it compares to the retired legacy summary compaction, and branch summarization.
 
-Atomic's default compaction design and terminology are informed by Morph's Context Compaction work: [Morph's Context Compaction](https://www.morphllm.com/context-compaction). Atomic follows the same core idea that coding agents often benefit more from deleting low-signal context than from rewriting high-signal details like file paths, line numbers, commands, and error strings into a lossy summary.
+Atomic's compaction design and terminology are informed by Morph's Context Compaction work: [Morph's Context Compaction](https://www.morphllm.com/context-compaction). Atomic follows the same core idea that coding agents often benefit more from deleting low-signal context than from rewriting high-signal details like file paths, line numbers, commands, and error strings into a lossy summary.
 
 **Source files** ([atomic](https://github.com/bastani-inc/atomic)):
 
 - [`packages/coding-agent/src/core/compaction/context-compaction.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/context-compaction.ts) - Verbatim Compaction planner, transcript tools, validation, and prompt
-- [`packages/coding-agent/src/core/compaction/compaction.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) - Legacy summary compaction logic and shared threshold helpers
 - [`packages/coding-agent/src/core/compaction/branch-summarization.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts) - Branch summarization
 - [`packages/coding-agent/src/core/compaction/utils.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/utils.ts) - Shared utilities (file tracking, serialization)
-- [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/session-manager.ts) - Entry types (`ContextCompactionEntry`, `CompactionEntry`, `BranchSummaryEntry`) and active-context rebuild logic
+- [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/session-manager.ts) - Entry types (`ContextCompactionEntry`, `BranchSummaryEntry`) and active-context rebuild logic
 - [`packages/coding-agent/src/core/extensions/types.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/extensions/types.ts) - Extension event types
 
 For TypeScript definitions in your project, inspect `node_modules/@bastani/atomic/dist/`.
 
 ## Overview
 
-Atomic has three compaction/summarization mechanisms:
+Atomic has one context compaction behavior and one separate branch-summarization mechanism:
 
 | Mechanism | Trigger | Purpose |
 |-----------|---------|---------|
-| Verbatim Compaction (default context compaction) | Context exceeds threshold, context overflow, or `/compact` | Delete safe old transcript entries/content blocks while retaining surviving content verbatim |
-| Summary compaction internals | Legacy core APIs and legacy extension hooks | Summarize old messages into replacement context |
+| Verbatim Compaction (context compaction) | Context exceeds threshold, context overflow, or `/compact` | Delete safe old transcript entries/content blocks while retaining surviving content verbatim |
 | Branch summarization | `/tree` navigation | Preserve useful context when switching branches |
 
+Summary compaction — the earlier behavior that generated replacement prose — has been removed as an active runtime path. Historical JSONL lines with `type:"compaction"` remain readable on disk but are not injected into active LLM context. See [Legacy Summary Compaction (Retired)](#legacy-summary-compaction-retired) for a comparison and historical reference.
+
 `/compact` has no user-facing arguments. It uses a fixed internal prompt, transcript-bound inspection/deletion tools, local validation, and a `context_compaction` session entry. Auto-compaction uses the same deletion-only path.
 
+## Verbatim vs. Summary Compaction
+
+Atomic uses Verbatim Compaction as its sole compaction strategy. The following comparison explains why, and documents what legacy summary compaction used to do.
+
+| Property | Verbatim Compaction | Summary Compaction (retired) |
+|----------|---------------------|------------------------------|
+| Mechanism | Deletes entries/content blocks | Rewrites earlier context into new prose |
+| Surviving content | Exact original transcript content | Generated summary text |
+| File paths / commands / errors | Kept exact or deleted | Can be paraphrased or omitted |
+| Line numbers and stack traces | Kept exact or deleted | Can be distorted in summary |
+| Auditability | Deleted targets are listed and inspectable | Omission/paraphrase is hard to audit |
+| Recoverability | Pre-compaction backup snapshot; deleted targets listed in entry | Generated summary cannot be losslessly reversed |
+| Failure mode | Needed context may be deleted (mitigated by validation and backups) | Needed context may be silently distorted |
+| Atomic end state | **Canonical behavior** | **Removed runtime behavior** |
+
+Coding agents depend on exact file paths (`src/foo.ts:42`), exact commands (`npm run build`), exact error strings, and exact line numbers. A generated summary that says "an error occurred in the auth module" instead of recording the actual stack trace loses irreplaceable information. Deletion is honest: what remains is unchanged, and what was deleted is listed in an inspectable `context_compaction` entry.
+
+Deletion can still lose needed context. Atomic mitigates this with:
+- **Local validation**: Protected entries (user tasks, recent context, unresolved errors, failed commands) cannot be deleted in standard mode.
+- **Pre-compaction backups**: A `.compact.bak` snapshot is written before each compaction for persisted sessions.
+- **Auditable targets**: The `context_compaction` entry records every deleted entry/content-block ID.
+
 ## Default Context Compaction (Verbatim Compaction)
 
 ### What "Verbatim" Means
@@ -36,7 +58,7 @@ Verbatim Compaction never asks a model to rewrite the conversation for the main
 - **Whole entries** such as an old assistant message or obsolete tool result.
 - **Individual content blocks** inside a multi-block message, such as one stale tool call block while keeping other blocks.
 
-Atomic records those targets in an append-only `context_compaction` entry. When the active branch is rebuilt, Atomic filters the targeted objects out and reuses every retained entry/content block unchanged. There is no generated summary, no paraphrasing, and no replacement message inserted by default.
+Atomic records those targets in an append-only `context_compaction` entry. When the active branch is rebuilt, Atomic filters the targeted objects out and reuses every retained entry/content block unchanged. There is no generated summary, no paraphrasing, and no replacement message inserted.
 
 The raw session JSONL remains append-only. Deleted objects stay available in the stored session file and backup snapshot; they are only omitted from future active LLM context on that branch.
 
@@ -50,11 +72,34 @@ contextTokens > contextWindow - reserveTokens
 
 By default, `reserveTokens` is 16384 tokens. Configure it in `~/.atomic/agent/settings.json` or `<project-dir>/.atomic/settings.json`; legacy `.pi` paths are also supported. This leaves room for the LLM's response.
 
-You can also trigger compaction manually with `/compact`. Custom summary instructions are no longer accepted because default compaction is deletion-only and retained transcript content stays verbatim.
+You can also trigger compaction manually with `/compact`. Custom summary instructions are not accepted because Verbatim Compaction is deletion-only and retained transcript content stays verbatim.
 
 ### How It Works
 
-1. **Collect active branch context.** Atomic walks the current session branch, applies any earlier `context_compaction` logical deletions, and respects legacy summary-compaction boundaries if they exist.
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#f8f9fa','primaryTextColor':'#2c3e50','primaryBorderColor':'#4a5568','lineColor':'#4a90e2','secondaryColor':'#ffffff','tertiaryColor':'#e9ecef'}}}%%
+flowchart TD
+    A["🗣 /compact · auto-threshold · auto-overflow"]
+    B["collect active branch context\napply prior context_compaction deletions"]
+    C["build compactable transcript\n(entry IDs · roles · token estimates · text)"]
+    D["mark protected context\n(user tasks · recent 5 entries · errors · failed commands)"]
+    E["write temporary transcript file\nsend manifest to planner"]
+    F["internal deletion planner\nfixed prompt · lowest thinking level"]
+    G["transcript-bound tools\ncontext_search · context_read · context_delete · context_grep_delete"]
+    H["validateContextDeletionRequest()\nlocal airlock: unknown · protected · orphaning · empty checks"]
+    I["write pre-compaction backup snapshot"]
+    J["appendContextCompaction()\ndeletedTargets · protectedEntryIds · stats · backupPath"]
+    K["buildSessionContext()\nfilter deleted targets · reuse survivors verbatim"]
+    L["emit session_compact event\nContextCompactionResult · contextCompactionEntry"]
+
+    A --> B --> C --> D --> E --> F
+    F <--> G
+    G --> H
+    H -->|validated| I --> J --> K --> L
+    H -->|rejected| F
+```
+
+1. **Collect active branch context.** Atomic walks the current session branch and applies any earlier `context_compaction` logical deletions.
 2. **Build a compactable transcript.** Each compactable entry includes a stable `entryId`, role, token estimate, full text, content-block indexes, tool-call IDs, and tool-result links.
 3. **Mark protected context.** Standard compaction protects user instructions, custom messages, branch/summary messages, the last five context-eligible entries, unresolved assistant/tool errors, and failed bash executions.
 4. **Write a temporary transcript file.** The compaction assistant receives a compact manifest plus the path to a JSONL transcript file. It should inspect with tools instead of loading the whole transcript into prompt context.
@@ -82,7 +127,7 @@ Tool calls are cumulative during one compaction run. The assistant can apply sev
 In standard mode, Atomic protects:
 
 - User messages and user-provided task context.
-- Custom messages, branch summaries, and existing summary-compaction messages.
+- Custom messages, branch summaries, and branch-summary context.
 - The last five context-eligible entries on the active branch.
 - Assistant messages whose stop reason is an error.
 - Tool results marked as errors.
@@ -172,111 +217,80 @@ No generated summary is inserted. Every surviving entry/content block is reused
 verbatim; deleted objects are simply omitted from the active LLM context.
 ```
 
-## Summary Compaction Internals
+## Extension Hooks for Compaction
 
-The older summarization pipeline still exists in the core compaction module and for legacy extension hook types, but `/compact` and auto-compaction no longer use it by default.
+Extensions can observe, cancel, or contribute exact deletion targets to the compaction pipeline. They cannot provide generated summaries.
 
-```text
-Before summary compaction:
+### session_before_compact
 
-  entry:  0     1     2     3      4     5     6      7      8     9
-        ┌─────┬─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┐
-        │ hdr │ usr │ ass │ tool │ usr │ ass │ tool │ tool │ ass │ tool│
-        └─────┴─────┴─────┴──────┴─────┴─────┴──────┴──────┴─────┴─────┘
-                └────────┬───────┘ └──────────────┬──────────────┘
-               messagesToSummarize            kept messages
-                                   ↑
-                          firstKeptEntryId (entry 4)
+Fired before the internal deletion planner runs. Extensions can cancel compaction or provide their own validated deletion request.
 
-After compaction (new entry appended):
+```typescript
+pi.on("session_before_compact", async (event, ctx) => {
+  const { preparation, branchEntries, reason, mode, signal } = event;
 
-  entry:  0     1     2     3      4     5     6      7      8     9     10
-        ┌─────┬─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┬─────┐
-        │ hdr │ usr │ ass │ tool │ usr │ ass │ tool │ tool │ ass │ tool│ cmp │
-        └─────┴─────┴─────┴──────┴─────┴─────┴──────┴──────┴─────┴─────┴─────┘
-               └──────────┬──────┘ └──────────────────────┬───────────────────┘
-                 not sent to LLM                    sent to LLM
-                                                         ↑
-                                              starts from firstKeptEntryId
+  // preparation.transcript.entries - entries eligible for deletion
+  // preparation.transcript.protectedEntryIds - entries that cannot be deleted in standard mode
+  // preparation.transcript.tokensBefore - context token estimate before compaction
+  // branchEntries - all entries on current branch
+  // reason - "manual" | "threshold" | "overflow"
+  // mode - "standard" | "critical_overflow"
 
-What the LLM sees:
+  // Cancel compaction:
+  return { cancel: true };
 
-  ┌────────┬─────────┬─────┬─────┬──────┬──────┬─────┬──────┐
-  │ system │ summary │ usr │ ass │ tool │ tool │ ass │ tool │
-  └────────┴─────────┴─────┴─────┴──────┴──────┴─────┴──────┘
-       ↑         ↑      └─────────────────┬────────────────┘
-    prompt   from cmp          messages from firstKeptEntryId
+  // Or provide a deletion request (Atomic validates it locally before persisting):
+  return {
+    deletionRequest: {
+      deletions: [
+        { kind: "entry", entryId: "abc123" },
+        { kind: "content_block", entryId: "def456", blockIndex: 2 },
+      ],
+    },
+  };
+});
 ```
 
-On repeated legacy summary compactions, the summarized span starts at the previous compaction's kept boundary (`firstKeptEntryId`), not at the compaction entry itself, falling back to the entry after the previous compaction if that kept entry cannot be found in the path. This preserves messages that survived the earlier compaction by including them in the next summarization pass as well. Atomic also recalculates `tokensBefore` from the rebuilt session context before writing the new `CompactionEntry`, so the token count reflects the actual pre-compaction context being replaced.
-
-### Split Turns
+If `{ cancel: true }` is returned, compaction aborts with a cancellation error. If `{ deletionRequest }` is returned, Atomic validates it through the same local airlock as model-proposed deletions — unknown IDs, protected targets, orphaning, and empty-context plans are rejected — and skips the internal planner. If nothing is returned, the internal planner runs normally.
 
-A "turn" starts with a user message and includes all assistant responses and tool calls until the next user message. The legacy summary pipeline normally cuts at turn boundaries.
+### session_compact
 
-When a single turn exceeds `keepRecentTokens`, the cut point lands mid-turn at an assistant message. This is a "split turn":
+Fired after compaction succeeds and the `context_compaction` entry is persisted.
 
-```text
-Split turn (one huge turn exceeds budget):
-
-  entry:  0     1     2      3     4      5      6     7      8
-        ┌─────┬─────┬─────┬──────┬─────┬──────┬──────┬─────┬──────┐
-        │ hdr │ usr │ ass │ tool │ ass │ tool │ tool │ ass │ tool │
-        └─────┴─────┴─────┴──────┴─────┴──────┴──────┴─────┴──────┘
-                ↑                                     ↑
-         turnStartIndex = 1                  firstKeptEntryId = 7
-                │                                     │
-                └──── turnPrefixMessages (1-6) ───────┘
-                                                      └── kept (7-8)
-
-  isSplitTurn = true
-  messagesToSummarize = []  (no complete turns before)
-  turnPrefixMessages = [usr, ass, tool, ass, tool, tool]
+```typescript
+pi.on("session_compact", async (event, ctx) => {
+  // event.result - ContextCompactionResult
+  // event.contextCompactionEntry - the saved ContextCompactionEntry
+  // event.reason - "manual" | "threshold" | "overflow"
+  // event.fromExtension - true if extension provided the deletionRequest
+
+  const { result } = event;
+  ctx.ui.notify(
+    `Compaction: deleted ${result.stats.objectsDeleted} objects, ` +
+    `${result.stats.percentReduction}% token reduction`,
+    "info",
+  );
+});
 ```
 
-For split turns, Atomic generates two summaries and merges them:
-
-1. **History summary**: Previous context (if any)
-2. **Turn prefix summary**: The early part of the split turn
-
-### Cut Point Rules
-
-Valid legacy summary-compaction cut points are:
+### ctx.compact()
 
-- User messages
-- Assistant messages
-- BashExecution messages
-- Custom messages (custom_message, branch_summary)
-
-Never cut at tool results because they must stay with their tool call.
-
-### CompactionEntry Structure
-
-Defined in [`session-manager.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/session-manager.ts):
+Trigger Verbatim Compaction without awaiting completion. See [Extensions](/extensions) for full `ctx.compact()` documentation.
 
 ```typescript
-interface CompactionEntry<T = unknown> {
-  type: "compaction";
-  id: string;
-  parentId: string | null;
-  timestamp: string;  // ISO timestamp
-  summary: string;
-  firstKeptEntryId: string;
-  tokensBefore: number;
-  fromHook?: boolean;  // true if provided by extension (legacy field name)
-  details?: T;         // implementation-specific data
-}
-
-// Legacy summary compaction uses this for details (from compaction.ts):
-interface CompactionDetails {
-  readFiles: string[];
-  modifiedFiles: string[];
-}
+ctx.compact({
+  onComplete: (result) => {
+    ctx.ui.notify(`Compacted: deleted ${result.stats.objectsDeleted} objects`, "info");
+  },
+  onError: (error) => {
+    ctx.ui.notify(`Compaction failed: ${error.message}`, "error");
+  },
+});
 ```
 
-Extensions can store any JSON-serializable data in `details`. The legacy summary compaction pipeline tracks file operations, but custom extension implementations can use their own structure.
+`ctx.compact()` does not accept custom instructions. Verbatim Compaction uses a fixed internal prompt; no custom summary text can be injected.
 
-See [`prepareCompaction()`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) and [`compact()`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) for the implementation.
+See [examples/extensions/trigger-compact.ts](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/extensions/trigger-compact.ts) for a full example.
 
 ## Branch Summarization
 
@@ -284,6 +298,8 @@ See [`prepareCompaction()`](https://github.com/bastani-inc/atomic/blob/main/pack
 
 When you use `/tree` to navigate to a different branch, Atomic offers to summarize the work you're leaving. This injects context from the left branch into the new branch.
 
+Branch summarization is a separate mechanism from context compaction. It generates a summary of the abandoned branch path and injects it into the new branch position. This is appropriate here because the alternative (losing branch context entirely on navigation) is worse than a lossy summary.
+
 ### How It Works
 
 1. **Find common ancestor**: Deepest node shared by old and new positions
@@ -292,6 +308,20 @@ When you use `/tree` to navigate to a different branch, Atomic offers to summari
 4. **Generate summary**: Call LLM with structured format
 5. **Append entry**: Save `BranchSummaryEntry` at navigation point
 
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#f8f9fa','primaryTextColor':'#2c3e50','primaryBorderColor':'#4a5568','lineColor':'#4a90e2','secondaryColor':'#ffffff','tertiaryColor':'#e9ecef'}}}%%
+flowchart TD
+    A["user navigates /tree\nold leaf → new target"]
+    B["find common ancestor"]
+    C["collect abandoned branch entries\n(old leaf → common ancestor)"]
+    D["prepare with token budget\n(newest first)"]
+    E["generate branch summary\nLLM call · structured format"]
+    F["append BranchSummaryEntry\nat common ancestor or new target"]
+    G["navigate to new target\nbranch summary context carried forward"]
+
+    A --> B --> C --> D --> E --> F --> G
+```
+
 ```text
 Tree before navigation:
 
@@ -311,12 +341,12 @@ After navigation with summary:
 
 ### Cumulative File Tracking
 
-Legacy summary compaction and branch summarization track files cumulatively. When generating a summary, Atomic extracts file operations from:
+Branch summarization tracks files cumulatively. When generating a summary, Atomic extracts file operations from:
 
 - Tool calls in the messages being summarized
-- Previous compaction or branch summary `details` (if any)
+- Previous branch summary `details` (if any)
 
-This means file tracking accumulates across multiple summary compactions or nested branch summaries, preserving the full history of read and modified files.
+This means file tracking accumulates across nested branch summaries, preserving the full history of read and modified files.
 
 ### BranchSummaryEntry Structure
 
@@ -341,13 +371,13 @@ interface BranchSummaryDetails {
 }
 ```
 
-Same as legacy summary compaction, extensions can store custom data in `details`.
+Extensions can store custom data in `details`.
 
 See [`collectEntriesForBranchSummary()`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts), [`prepareBranchEntries()`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts), and [`generateBranchSummary()`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts) for the implementation.
 
-## Legacy Summary Format
+## Branch Summary Format
 
-Legacy summary compaction and branch summarization use the same structured format:
+Branch summarization uses a structured format:
 
 ```markdown
 ## Goal
@@ -385,9 +415,9 @@ path/to/changed.ts
 </modified-files>
 ```
 
-### Message Serialization
+### Message Serialization for Branch Summaries
 
-Before legacy summarization, messages are serialized to text via [`serializeConversation()`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/utils.ts):
+Before branch summarization, messages are serialized to text via [`serializeConversation()`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/utils.ts):
 
 ```text
 [User]: What they said
@@ -399,81 +429,9 @@ Before legacy summarization, messages are serialized to text via [`serializeConv
 
 This prevents the model from treating it as a conversation to continue.
 
-Tool results are truncated to 2000 characters during serialization. Content beyond that limit is replaced with a marker indicating how many characters were truncated. This keeps summarization requests within reasonable token budgets, since tool results (especially from `read` and `bash`) are typically the largest contributors to context size.
+Tool results are truncated to 2000 characters during serialization. Content beyond that limit is replaced with a marker indicating how many characters were truncated.
 
-## Custom Summarization via Extensions
-
-Extensions can still customize the legacy summary compaction pipeline and branch summarization. Default `/compact` and auto-compaction use deletion-only Verbatim Compaction and do not call summary customization hooks. See [`extensions/types.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/extensions/types.ts) for event type definitions.
-
-### session_before_compact
-
-Fired before legacy summary compaction. Can cancel or provide custom summary. See `SessionBeforeCompactEvent` and `CompactionPreparation` in the types file.
-
-```typescript
-pi.on("session_before_compact", async (event, ctx) => {
-  const { preparation, branchEntries, customInstructions, signal } = event;
-
-  // preparation.messagesToSummarize - messages to summarize
-  // preparation.turnPrefixMessages - split turn prefix (if isSplitTurn)
-  // preparation.previousSummary - previous compaction summary
-  // preparation.fileOps - extracted file operations
-  // preparation.tokensBefore - context tokens before compaction
-  // preparation.firstKeptEntryId - where kept messages start
-  // preparation.settings - compaction settings
-
-  // branchEntries - all entries on current branch (for custom state)
-  // signal - AbortSignal (pass to LLM calls)
-
-  // Cancel:
-  return { cancel: true };
-
-  // Custom summary:
-  return {
-    compaction: {
-      summary: "Your summary...",
-      firstKeptEntryId: preparation.firstKeptEntryId,
-      tokensBefore: preparation.tokensBefore,
-      details: { /* custom data */ },
-    }
-  };
-});
-```
-
-#### Converting Messages to Text
-
-To generate a summary with your own model, convert messages to text using `serializeConversation`:
-
-```typescript
-import { convertToLlm, serializeConversation } from "@bastani/atomic";
-
-pi.on("session_before_compact", async (event, ctx) => {
-  const { preparation } = event;
-  
-  // Convert AgentMessage[] to Message[], then serialize to text
-  const conversationText = serializeConversation(
-    convertToLlm(preparation.messagesToSummarize)
-  );
-  // Returns:
-  // [User]: message text
-  // [Assistant thinking]: thinking content
-  // [Assistant]: response text
-  // [Assistant tool calls]: read(path="..."); bash(command="...")
-  // [Tool result]: output text
-
-  // Now send to your model for summarization
-  const summary = await myModel.summarize(conversationText);
-  
-  return {
-    compaction: {
-      summary,
-      firstKeptEntryId: preparation.firstKeptEntryId,
-      tokensBefore: preparation.tokensBefore,
-    }
-  };
-});
-```
-
-See [custom-compaction.ts](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/extensions/custom-compaction.ts) for a complete example using a different model.
+## Extension Hooks for Branch Summarization
 
 ### session_before_tree
 
@@ -514,8 +472,7 @@ Configure compaction in `~/.atomic/agent/settings.json` or `<project-dir>/.atomi
 {
   "compaction": {
     "enabled": true,
-    "reserveTokens": 16384,
-    "keepRecentTokens": 20000
+    "reserveTokens": 16384
   }
 }
 ```
@@ -524,6 +481,78 @@ Configure compaction in `~/.atomic/agent/settings.json` or `<project-dir>/.atomi
 |---------|---------|-------------|
 | `enabled` | `true` | Enable automatic Verbatim Compaction. |
 | `reserveTokens` | `16384` | Tokens to reserve for the next LLM response; auto-compaction starts when context usage exceeds `contextWindow - reserveTokens`. |
-| `keepRecentTokens` | `20000` | Legacy summary-compaction retained-token budget. Default Verbatim Compaction protects recent entries structurally instead of using this as a token cut point. |
 
 Disable auto-compaction with `"enabled": false`. You can still compact manually with `/compact`.
+
+## Legacy Summary Compaction (Retired)
+
+Summary compaction — an earlier behavior that generated replacement prose for older context — has been removed as an active runtime path in Atomic. This section documents it for historical reference only.
+
+### What it did
+
+The summary compaction pipeline:
+1. Selected a cut point (user message boundary) called `firstKeptEntryId`.
+2. Passed all messages before that cut point to an LLM to generate a replacement summary.
+3. Appended a `CompactionEntry` with `type:"compaction"` to the session JSONL.
+4. When rebuilding active context, injected a `compactionSummary` message at the boundary.
+
+```text
+(Historical — no longer the active behavior)
+
+Before summary compaction:
+
+  entry:  0     1     2     3      4     5     6      7      8     9
+        ┌─────┬─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┐
+        │ hdr │ usr │ ass │ tool │ usr │ ass │ tool │ tool │ ass │ tool│
+        └─────┴─────┴─────┴──────┴─────┴─────┴──────┴──────┴─────┴─────┘
+                └────────┬───────┘ └──────────────┬──────────────┘
+               messagesToSummarize            kept messages
+                                   ↑
+                          firstKeptEntryId (entry 4)
+
+After compaction (new entry appended):
+
+  entry:  0     1     2     3      4     5     6      7      8     9     10
+        ┌─────┬─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┬─────┐
+        │ hdr │ usr │ ass │ tool │ usr │ ass │ tool │ tool │ ass │ tool│ cmp │
+        └─────┴─────┴─────┴──────┴─────┴─────┴──────┴──────┴─────┴─────┴─────┘
+               └──────────┬──────┘ └──────────────────────┬───────────────────┘
+                 not sent to LLM                    sent to LLM
+                                                         ↑
+                                              starts from firstKeptEntryId
+
+What the LLM saw:
+
+  ┌────────┬─────────┬─────┬─────┬──────┬──────┬─────┬──────┐
+  │ system │ summary │ usr │ ass │ tool │ tool │ ass │ tool │
+  └────────┴─────────┴─────┴─────┴──────┴──────┴─────┴──────┘
+       ↑         ↑      └─────────────────┬────────────────┘
+    prompt   from cmp          messages from firstKeptEntryId
+```
+
+### Why it was removed
+
+The core problem: a generated summary can paraphrase or omit exact file paths (`src/auth/middleware.ts:87`), commands (`npm run build -- --watch`), error strings, and line numbers. For coding agents, this loss of precision frequently causes confusion and regressions. Verbatim Compaction is honest: what remains is unchanged, and what was deleted is recorded.
+
+See [Verbatim vs. Summary Compaction](#verbatim-vs-summary-compaction) for the full comparison.
+
+### Historical entry types
+
+`type:"compaction"` JSONL lines may exist in sessions created before the removal. They remain readable on disk and visible in session exports, but Atomic does not inject them as active LLM context. If you encounter sessions with these entries, they are safe to leave in place.
+
+`type:"compaction"` entry structure (historical):
+```typescript
+interface CompactionEntry {
+  type: "compaction";
+  id: string;
+  parentId: string | null;
+  timestamp: string;
+  summary: string;           // generated replacement prose
+  firstKeptEntryId: string;  // cut point boundary
+  tokensBefore: number;
+  fromHook?: boolean;
+  details?: unknown;
+}
+```
+
+This entry type is no longer produced by Atomic. Extension hooks that returned `{ compaction: { summary, firstKeptEntryId, tokensBefore } }` no longer have effect; update extensions to use the new `{ cancel: true }` or `{ deletionRequest }` hook returns instead.

package/docs/extensions.md

@@ -8,7 +8,7 @@ Extensions are TypeScript modules that extend Atomic's behavior. They can subscr
 
 **Key capabilities:**
 - **Custom tools** - Register tools the LLM can call via `pi.registerTool()`
-- **Event interception** - Block or modify tool calls, inject context, customize legacy summary compaction and branch summaries
+- **Event interception** - Block or modify tool calls, inject context, observe/cancel deletion-only compaction, and customize branch summaries
 - **User interaction** - Prompt users via `ctx.ui` (select, confirm, input, notify)
 - **Custom UI components** - Full TUI components with keyboard input via `ctx.ui.custom()` for complex interactions
 - **Custom commands** - Register commands like `/mycommand` via `pi.registerCommand()`
@@ -19,7 +19,7 @@ Extensions are TypeScript modules that extend Atomic's behavior. They can subscr
 - Permission gates (confirm before `rm -rf`, `sudo`, etc.)
 - Git checkpointing (stash at each turn, restore on branch)
 - Path protection (block writes to `.env`, `node_modules/`)
-- Legacy custom summary compaction (summarize older context your way)
+- Compaction policies (cancel compaction or provide exact deletion targets)
 - Conversation summaries (see `summarize.ts` example)
 - Interactive tools (questions, wizards, custom dialogs)
 - Stateful tools (todo lists, connection pools)
@@ -322,11 +322,9 @@ user sends another prompt ◄─────────────────
   └─► resources_discover { reason: "startup" }
 
 /compact or auto-compaction
-  └─► compaction_start / compaction_end (deletion-only context compaction)
-
-legacy summary compaction APIs
-  ├─► session_before_compact (can cancel or customize)
-  └─► session_compact
+  ├─► compaction_start / compaction_end (deletion-only context compaction status)
+  ├─► session_before_compact (can cancel or provide a deletion request)
+  └─► session_compact (after the context_compaction entry is persisted)
 
 /tree navigation
   ├─► session_before_tree (can cancel or customize)
@@ -416,28 +414,41 @@ Do cleanup work in `session_shutdown`, then reestablish any in-memory state in `
 
 #### session_before_compact / session_compact
 
-Fired by the legacy summary compaction pipeline. `/compact` and auto-compaction now use deletion-only context compaction by default, so extensions should not rely on these events for default compaction. See [Compaction](/compaction) for details.
+Fired by `/compact` and auto-compaction. Compaction is deletion-only: extensions can cancel the run or return exact entry/content-block deletion targets for Atomic to validate locally. Extensions cannot return generated summaries.
 
 ```typescript
 pi.on("session_before_compact", async (event, ctx) => {
-  const { preparation, branchEntries, customInstructions, signal } = event;
+  const { preparation, branchEntries, reason, mode, signal } = event;
+  const { transcript } = preparation;
+
+  // transcript.entries - compactable entries on the active branch
+  // transcript.protectedEntryIds - entries protected from standard compaction
+  // transcript.tokensBefore - token estimate before compaction
+  // branchEntries - raw session entries on the current branch
+  // reason - "manual" | "threshold" | "overflow"
+  // mode - "standard" | "critical_overflow"
+
+  if (signal.aborted) return { cancel: true };
 
-  // Cancel:
+  // Cancel compaction:
   return { cancel: true };
 
-  // Custom summary:
+  // Or provide a deletion request. Atomic validates IDs, protected targets,
+  // tool-call/tool-result pairing, and non-empty remaining context before saving.
   return {
-    compaction: {
-      summary: "...",
-      firstKeptEntryId: preparation.firstKeptEntryId,
-      tokensBefore: preparation.tokensBefore,
-    }
+    deletionRequest: {
+      deletions: [
+        { kind: "entry", entryId: "abc123", rationale: "Old successful command output" },
+        { kind: "content_block", entryId: "def456", blockIndex: 2, rationale: "Verbose obsolete log" },
+      ],
+    },
   };
 });
 
 pi.on("session_compact", async (event, ctx) => {
-  // event.compactionEntry - the saved compaction
-  // event.fromExtension - whether extension provided it
+  // event.result - ContextCompactionResult with deletedTargets/protectedEntryIds/stats
+  // event.contextCompactionEntry - the saved context_compaction entry
+  // event.fromExtension - true if session_before_compact provided deletionRequest
 });
 ```
 
@@ -963,7 +974,7 @@ ctx.compact({
 });
 ```
 
-`customInstructions` is deprecated. Passing a non-empty value to default compaction fails because Verbatim Compaction does not accept custom summary instructions.
+Verbatim Compaction uses a fixed internal prompt; no custom summary text can be injected.
 
 ### ctx.getSystemPrompt()
 
@@ -2572,7 +2583,7 @@ All examples in [examples/extensions/](https://github.com/bastani-inc/atomic/tre
 | `prompt-customizer.ts` | Add context-aware tool guidance using `systemPromptOptions` | `on("before_agent_start")`, `BuildSystemPromptOptions` |
 | `file-trigger.ts` | File watcher triggers messages | `sendMessage` |
 | **Compaction & Sessions** |||
-| `custom-compaction.ts` | Legacy custom compaction summary | `on("session_before_compact")` |
+| `custom-compaction.ts` | Custom deletion-request compaction policy | `on("session_before_compact")` |
 | `trigger-compact.ts` | Trigger compaction manually | `compact()` |
 | `git-checkpoint.ts` | Git stash on turns | `on("turn_start")`, `on("session_before_fork")`, `exec` |
 | `auto-commit-on-exit.ts` | Commit on shutdown | `on("session_shutdown")`, `exec` |