bastani-inc · lavaman131 · Jun 9, 2026 · Jun 8, 2026 · Jun 8, 2026 · Jun 8, 2026
diff --git a/bun.lock b/bun.lock
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
@@ -2,16 +2,33 @@
 
 ## [Unreleased]
 
+## [0.8.28-alpha.1] - 2026-06-08
+
+### Changed
+
+- Changed Atomic compaction to be verbatim-only across manual `/compact`, automatic threshold/overflow compaction, SDK/RPC compaction, and extension-triggered compaction. All compaction now records validated `context_compaction` deletion targets and rebuilds active context with retained transcript content verbatim and unchanged. Retained file paths, exact commands, error strings, and line numbers are never paraphrased or rewritten.
+- Changed compaction extension hooks (`session_before_compact`, `session_compact`) to receive verbatim context-compaction preparations/results and allow cancellation or locally validated deletion requests instead of custom generated summaries. The before-compact hook now yields `ContextCompactionPreparation` and accepts `{ cancel: true }` or `{ deletionRequest }` returns; the after-compact hook now receives `ContextCompactionResult` and `contextCompactionEntry`.
+
 ### Fixed
 
 - Fixed `AgentSession.prompt` surfacing the confusing `No API key found for undefined` error when a model never resolved to a real provider (for example an unknown/unresolved model id reaching the prompt path as a bare string). The prompt path now fails fast with a clear `Unknown model: "<id>" did not resolve to an available provider` message, and `No API key found` guidance no longer renders a literal `undefined` provider.
 
+### Removed
+
+- Removed the legacy summary-compaction runtime path, summary prompts, `CompactionEntry` active-context injection, `CompactionSummaryMessage` active message type, custom compaction instructions (`CompactOptions.customInstructions`, RPC `compact.customInstructions`, `/compact [instructions]`), `compaction.keepRecentTokens` setting, summary-compaction public exports (`CompactionResult`, `CompactionPreparation`, `appendCompaction()`, `prepareCompaction()`, `generateSummary()`, summary `compact()`), and summary-compaction docs and examples. Historical `type:"compaction"` JSONL lines on disk are inert and are not injected into active LLM context.
+
 ## [0.8.27] - 2026-06-08
 
 ### Fixed
 
 - Fixed `/compact` and auto-compaction regressions by removing the native `better-sqlite3` dependency from transcript-bound deletion tools and preserving the currently selected reasoning level for the compaction planner ([#1310](https://github.com/bastani-inc/atomic/issues/1310)).
 
+## [0.8.27-alpha.1] - 2026-06-08
+
+### Fixed
+
+- Fixed `/compact` and auto-compaction regressions by removing the native `better-sqlite3` dependency from transcript-bound deletion tools and preserving the currently selected reasoning level for the compaction planner ([#1310](https://github.com/bastani-inc/atomic/issues/1310)).
+
 ## [0.8.26] - 2026-06-08
 
 ### Added

diff --git a/packages/coding-agent/docs/compaction.md b/packages/coding-agent/docs/compaction.md
diff --git a/packages/coding-agent/docs/extensions.md b/packages/coding-agent/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` |

diff --git a/packages/coding-agent/docs/json.md b/packages/coding-agent/docs/json.md
@@ -53,10 +53,9 @@ Base messages come from `@earendil-works/pi-ai` (installed as an Atomic dependen
 - `ToolResultMessage`
 
 Extended messages from [`packages/coding-agent/src/core/messages.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/messages.ts#L29):
-- `BashExecutionMessage` (line 29)
-- `CustomMessage` (line 46)
-- `BranchSummaryMessage` (line 55)
-- `CompactionSummaryMessage` (line 62)
+- `BashExecutionMessage`
+- `CustomMessage`
+- `BranchSummaryMessage`
 
 ## Output Format
 

diff --git a/packages/coding-agent/docs/session-format.md b/packages/coding-agent/docs/session-format.md
@@ -144,15 +144,10 @@ interface BranchSummaryMessage {
   fromId: string;                // Entry we branched from
   timestamp: number;
 }
-
-interface CompactionSummaryMessage {
-  role: "compactionSummary";
-  summary: string;
-  tokensBefore: number;
-  timestamp: number;
-}
 ```
 
+Historical sessions may contain retired `compactionSummary` role messages from the old summary-compaction implementation. Atomic no longer produces them, they are not part of the active `AgentMessage` union, and they are not injected when active LLM context is rebuilt.
+
 ### AgentMessage Union
 
 ```typescript
@@ -162,8 +157,8 @@ type AgentMessage =
   | ToolResultMessage
   | BashExecutionMessage
   | CustomMessage
-  | BranchSummaryMessage
-  | CompactionSummaryMessage;
+  | BranchSummaryMessage;
+// CompactionSummaryMessage was removed; it is no longer part of the active union.
 ```
 
 ## Entry Base
@@ -223,14 +218,14 @@ Emitted when the user changes the thinking/reasoning level.
 
 ### CompactionEntry
 
-Legacy summary-compaction entry. Stores a generated summary of earlier messages for older APIs and extension hooks. Default `/compact` and auto-compaction now create `ContextCompactionEntry` records instead.
+Retired summary-compaction entry. Atomic no longer produces this entry type, does not treat it as an active compaction boundary, and does not inject its generated summary into active LLM context. Historical JSONL files may still contain these lines for audit/export compatibility.
 
 ```json
 {"type":"compaction","id":"f6g7h8i9","parentId":"e5f6g7h8","timestamp":"2024-12-03T14:10:00.000Z","summary":"User discussed X, Y, Z...","firstKeptEntryId":"c3d4e5f6","tokensBefore":50000}
 ```
 
-Optional fields:
-- `details`: Implementation-specific data (e.g., `{ readFiles: string[], modifiedFiles: string[] }` for default, or custom data for extensions)
+Optional historical fields:
+- `details`: Legacy implementation-specific data
 - `fromHook`: `true` if generated by an extension, `false`/`undefined` if Atomic-generated (legacy field name)
 
 ### ContextCompactionEntry
@@ -316,14 +311,11 @@ Entries form a tree:
 
 `buildSessionContext()` walks from the current leaf to the root, producing the message list for the LLM:
 
-1. Collects all entries on the path
+1. Collects all entries on the active branch path
 2. Extracts current model and thinking level settings
-3. If a `CompactionEntry` is on the path:
-   - Emits the summary first
-   - Then messages from `firstKeptEntryId` to compaction
-   - Then messages after compaction
-4. Applies `ContextCompactionEntry` logical deletions recorded after the latest summary compaction
-5. Converts `BranchSummaryEntry` and `CustomMessageEntry` to appropriate message formats
+3. Applies every `ContextCompactionEntry` logical deletion on that path, filtering targeted entries/content blocks from active context while leaving retained content unchanged
+4. Converts `BranchSummaryEntry` and `CustomMessageEntry` to appropriate message formats
+5. Ignores retired `CompactionEntry` lines for active LLM context; they remain archival JSONL data only
 
 ## Parsing Example
 
@@ -343,7 +335,7 @@ for (const line of lines) {
       console.log(`[${entry.id}] ${entry.message.role}: ${JSON.stringify(entry.message.content)}`);
       break;
     case "compaction":
-      console.log(`[${entry.id}] Compaction: ${entry.tokensBefore} tokens summarized`);
+      console.log(`[${entry.id}] Retired summary-compaction record: ${entry.tokensBefore} tokens summarized historically`);
       break;
     case "context_compaction":
       console.log(`[${entry.id}] Context compaction: ${entry.stats.objectsDeleted} objects deleted`);
@@ -394,7 +386,6 @@ Key methods for working with sessions programmatically.
 - `appendMessage(message)` - Add message
 - `appendThinkingLevelChange(level)` - Record thinking change
 - `appendModelChange(provider, modelId)` - Record model change
-- `appendCompaction(summary, firstKeptEntryId, tokensBefore, details?, fromHook?)` - Add summary compaction
 - `appendContextCompaction(deletedTargets, protectedEntryIds, stats, backupPath?)` - Add logical deletion compaction
 - `appendCustomEntry(customType, data?)` - Extension state (not in context)
 - `appendSessionInfo(name)` - Set session display name

diff --git a/packages/coding-agent/docs/sessions.md b/packages/coding-agent/docs/sessions.md
@@ -128,10 +128,12 @@ When prompted, choose one of:
 2. summarize with the default prompt
 3. summarize with custom focus instructions
 
+Branch summaries are separate from `/compact`: branch navigation can generate summary prose (optionally with focus instructions), while Verbatim Compaction records validated deletion targets and does not accept summary instructions.
+
 See [Compaction](/compaction) for Verbatim Compaction, branch summarization internals, and extension hooks.
 
 ## Session Format
 
-Session files are JSONL and contain message entries, model changes, thinking-level changes, labels, summary compactions, context compactions, branch summaries, and extension entries.
+Session files are JSONL and contain message entries, model changes, thinking-level changes, labels, context compactions, branch summaries, extension entries, and retired legacy `type:"compaction"` records from older sessions.
 
 For parsers, extensions, SDK usage, and the full SessionManager API, see [Session Format](/session-format).
diff --git a/packages/coding-agent/docs/settings.md b/packages/coding-agent/docs/settings.md
@@ -92,14 +92,12 @@ Set `ATOMIC_SKIP_VERSION_CHECK=1` to disable the Atomic version update check. Us
 |---------|------|---------|-------------|
 | `compaction.enabled` | boolean | `true` | Enable automatic Verbatim Compaction |
 | `compaction.reserveTokens` | number | `16384` | Tokens reserved for LLM response |
-| `compaction.keepRecentTokens` | number | `20000` | Legacy summary-compaction retained-token budget; default Verbatim Compaction protects recent entries structurally |
 
 ```json
 {
   "compaction": {
     "enabled": true,
-    "reserveTokens": 16384,
-    "keepRecentTokens": 20000
+    "reserveTokens": 16384
   }
 }
 ```
@@ -285,8 +283,7 @@ See [Atomic packages](/packages) for package management details.
   "theme": "dark",
   "compaction": {
     "enabled": true,
-    "reserveTokens": 16384,
-    "keepRecentTokens": 20000
+    "reserveTokens": 16384
   },
   "retry": {
     "enabled": true,