@bastani/atomic 0.8.29 → 0.8.30-alpha.1

package/docs/compaction.md

@@ -25,7 +25,7 @@ Atomic has one context compaction behavior and one separate branch-summarization
 
 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.
+`/compact` has no user-facing arguments. It uses the effective `compaction` settings (`compression_ratio`, `preserve_recent`, and optional `query`), 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
 
@@ -45,7 +45,7 @@ Atomic uses Verbatim Compaction as its sole compaction strategy. The following c
 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.
+- **Local validation**: Disallowed deletion targets return explicit non-terminating tool errors; grep/regex deletion ignores rejected matches and continues with accepted matches.
 - **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.
 
@@ -62,6 +62,28 @@ Atomic records those targets in an append-only `context_compaction` entry. When
 
 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.
 
+### Compaction Parameters
+
+Atomic uses three effective parameters for each context-compaction run. They are available to extension hooks as `event.parameters`, copied into `event.preparation.parameters`, and returned on `event.result.parameters` after a successful compaction.
+
+| Parameter | Type | Default | Meaning |
+|-----------|------|---------|---------|
+| `compression_ratio` | `float` | `0.5` | Fraction of compactable context to keep. `0.3` is aggressive (keep 30%, delete 70%); `0.7` is light (keep 70%, delete 30%). |
+| `preserve_recent` | `int` | `2` | Number of most recent context-eligible messages kept uncompressed / undeletable. |
+| `query` | `string` | auto-detected | Focus query for relevance-based pruning. If provided in settings or `ctx.compact()`, Atomic uses that value; otherwise it derives the query from the latest context-eligible user message. |
+
+Settings use the same snake_case names under `compaction`, for example:
+
+```json
+{
+  "compaction": {
+    "compression_ratio": 0.5,
+    "preserve_recent": 2,
+    "query": "preserve details relevant to the current refactor"
+  }
+}
+```
+
 ### When It Triggers
 
 Auto-compaction triggers when:
@@ -76,72 +98,461 @@ You can also trigger compaction manually with `/compact`. Custom summary instruc
 
 ### How It Works
 
-```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
+The diagram below is intentionally a block diagram, not a flowchart DSL. Read it left to right first, then use the lower diagrams to inspect the tool loop, validation airlock, dependency repair, and persistence path.
+
+#### Context compaction at a glance
+
+```text
+┌──────────────────────────────────────────────────────────────────────────────────────────────┐
+│ GOAL                                                                                         │
+│ Delete low-signal transcript objects while leaving every surviving object byte-for-byte       │
+│ equivalent in active model context. No summaries. No paraphrases. No replacement messages.   │
+└──────────────────────────────────────────────────────────────────────────────────────────────┘
+
+┌──────────────┐    ┌──────────────────────┐    ┌──────────────────────┐    ┌──────────────────┐
+│  1 Trigger   │───▶│  2 Prepare transcript │───▶│  3 Planner workspace  │───▶│  4 Tool loop      │
+└──────────────┘    └──────────────────────┘    └──────────────────────┘    └──────────────────┘
+       │                       │                           │                           │
+       │                       │                           │                           ▼
+       │                       │                           │              ┌──────────────────────────┐
+       │                       │                           │              │ 5 Validation airlock      │
+       │                       │                           │              └──────────────────────────┘
+       │                       │                           │                           │
+       │                       │                           │             ┌─────────────┴─────────────┐
+       │                       │                           │             ▼                           ▼
+       │                       │                           │   ┌──────────────────┐      ┌─────────────────────┐
+       │                       │                           │   │ ✗ Correction     │      │ ✓ Validated state    │
+       │                       │                           │   │ tool result      │      │ replaces tool store  │
+       │                       │                           │   └──────────────────┘      └─────────────────────┘
+       │                       │                           │             │                           │
+       │                       │                           │             └──────────────┬────────────┘
+       │                       │                           │                            ▼
+       │                       │                           │              ┌──────────────────────────┐
+       │                       │                           └─────────────▶│ 6 Planner stops or adds   │
+       │                       │                                          │ more deletion targets     │
+       │                       │                                          └──────────────────────────┘
+       │                       │                                                       │
+       │                       │                                                       ▼
+       │                       │                                          ┌──────────────────────────┐
+       └───────────────────────┴─────────────────────────────────────────▶│ 7 Persist compaction     │
+                                                                          └──────────────────────────┘
+                                                                                       │
+                                                                                       ▼
+                                                                          ┌──────────────────────────┐
+                                                                          │ 8 Rebuild active context │
+                                                                          └──────────────────────────┘
+```
+
+| Block | Main code path | Input | Output |
+|-------|----------------|-------|--------|
+| 1 Trigger | `/compact`, threshold check, overflow retry, `ctx.compact()` | Current session branch | Compaction request with reason and parameters |
+| 2 Prepare transcript | `prepareContextCompaction` | Branch `SessionEntry[]` plus prior `context_compaction` filters | `ContextCompactionPreparation` |
+| 3 Planner workspace | `runContextDeletionAssistant` | `CompactableTranscript` | Temp JSONL transcript file plus bounded manifest prompt, inheriting the session's current model thinking level |
+| 4 Tool loop | `createContextDeletionTool` tools | Planner tool calls | In-run deletion store updates or correction errors |
+| 5 Validation airlock | `validateContextDeletionRequest` | Candidate cumulative deletion request | Reconciled `deletedTargets` or thrown error |
+| 6 Planner stops or adds more | Agent loop until target is met or no progress remains | Tool results and current context | Final validated deletion state |
+| 7 Persist compaction | session manager append path | `ContextCompactionResult` | New append-only `context_compaction` entry |
+| 8 Rebuild active context | `buildSessionContext` | Branch plus all logical deletion filters | Model messages with deleted objects omitted verbatim |
+
+#### Block 1: trigger sources
+
+```text
+┌───────────────────────────────────────────────┐
+│ Trigger source                                │
+├───────────────────────────────────────────────┤
+│ /compact                                      │
+│   fixed deletion-only prompt                  │
+│                                               │
+│ Auto threshold / provider overflow            │
+│   if contextTokens > contextWindow - reserve  │
+│                                               │
+│ Extension ctx.compact()                       │
+│   optional compression parameters             │
+└───────────────────────────────────────────────┘
 ```
 
+All triggers produce the same `ContextDeletionTarget[]` shape and append the same `context_compaction` entry type.
+
+#### Block 2: transcript preparation
+
+```text
+append-only SessionEntry branch
+        │
+        │  Example branch path:
+        │
+        │    entry-0  system/header context
+        │    entry-1  user task
+        │    entry-2  assistant with toolCall(call-a)
+        │    entry-3  toolResult(call-a)
+        │    entry-4  assistant note
+        │    entry-5  context_compaction     ← old logical deletion filters
+        │    entry-6  user clarification
+        │    entry-7  recent assistant
+        │
+        ▼
+┌──────────────────────────────────────────────────────────────────────────────────────────────┐
+│ A. Accumulate prior deletion filters                                                         │
+│                                                                                                │
+│    Prior context_compaction entries are interpreted as filters:                                │
+│      deletedEntries       = Set<entryId>                                                       │
+│      deletedContentBlocks = Map<entryId, Set<blockIndex>>                                      │
+│                                                                                                │
+│    Disk is append-only. Old entries remain in JSONL. They are only hidden from active context. │
+└──────────────────────────────────────────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌──────────────────────────────────────────────────────────────────────────────────────────────┐
+│ B. Build filtered path                                                                         │
+│                                                                                                │
+│    entry deletion      → remove that SessionEntry from the compactable path                    │
+│    content_block       → keep the SessionEntry, but omit selected content blocks               │
+│    context_compaction  → do not include as a model message                                     │
+│    excludeFromContext  → omit from compactable transcript                                      │
+└──────────────────────────────────────────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌──────────────────────────────────────────────────────────────────────────────────────────────┐
+│ C. Mark entries that validation will not delete                                                 │
+│                                                                                                │
+│    protected = true when any of these are true:                                                │
+│      • entry is inside the configured preserve_recent context window                           │
+│      • role is user                                                                            │
+│      • role is custom                                                                          │
+│      • role is branchSummary, or entryType is branch_summary                                   │
+│      • assistant stopReason is error                                                           │
+│      • toolResult isError is true                                                              │
+│      • bashExecution has non-zero exitCode                                                     │
+└──────────────────────────────────────────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌──────────────────────────────────────────────────────────────────────────────────────────────┐
+│ D. Emit CompactableTranscript                                                                  │
+│                                                                                                │
+│    transcript.entries[] contains one CompactableTranscriptEntry per compactable message:        │
+│                                                                                                │
+│      entryId          stable id used in deletion targets                                        │
+│      entryType        message | custom_message | branch_summary | ...                          │
+│      role             user | assistant | toolResult | bashExecution | custom | branchSummary    │
+│      text             searchable/readable text                                                  │
+│      tokenEstimate    stats and manifest prioritization                                         │
+│      protected        validation guard bit                                                       │
+│      contentBlocks    per-block delete targets with original blockIndex                         │
+│      message          original AgentMessage for invariant checks                                │
+│      toolCallIds      ids from assistant toolCall content blocks                                │
+│      toolResultFor    call id answered by a toolResult entry                                    │
+│                                                                                                │
+│    transcript.protectedEntryIds records the protected ids for the persisted result.             │
+└──────────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+#### Block 3: planner workspace
+
+```text
+CompactableTranscript
+        │
+        ├─ writeContextCompactionTranscriptFile(transcript)
+        │
+        │    Temporary file layout:
+        │
+        │      /tmp/atomic-context-transcript-*/transcript.jsonl
+        │
+        │      line 1: { entryId, role, protected, tokenEstimate, text, contentBlocks, ... }
+        │      line 2: { entryId, role, protected, tokenEstimate, text, contentBlocks, ... }
+        │      ...
+        │
+        │    The full transcript text lives here, not in the prompt.
+        │
+        └─ buildContextCompactionPrompt(transcript, transcriptFilePath)
+
+Prompt body
+┌──────────────────────────────────────────────────────────────────────────────────────────────┐
+│ Planner guardrails                                                                            │
+│   • context_delete is id-only: kind, entryId, and optional blockIndex.                         │
+│   • context_grep_delete may use a concise content pattern, never full block bodies.            │
+│   • No-summary/no-paraphrase wording prevents legacy replacement-context behavior.             │
+│   • Atomic ignores final prose as a deletion plan; validated tool state is the result.         │
+├──────────────────────────────────────────────────────────────────────────────────────────────┤
+│ Strategy                                                                                      │
+│   • Aggressively compact/remove blocks.                                                       │
+│   • Start with context_compaction_budget to inspect window fullness and reduction target.      │
+│   • Spend a few turns exploring with search/read tools to gain high confidence of candidate   │
+│     blocks to remove.                                                                         │
+│   • Prefer high-confidence exploit actions after that: delete obvious low-value entries via    │
+│     context_grep_delete or context_delete.                                                     │
+│   • Check context_compaction_budget after deletion batches.                                   │
+│   • Treat compression_ratio as strict: default 0.5 means keep 50% / delete 50%.                │
+│   • If the target is not met, continue deleting low-value entries/content blocks.              │
+│   • Converge quickly; do not keep reading once safe deletion targets are clear.                │
+├──────────────────────────────────────────────────────────────────────────────────────────────┤
+│ Transcript file path                                                                          │
+│   The planner can search/read slices through tools instead of loading the whole JSONL file.     │
+├──────────────────────────────────────────────────────────────────────────────────────────────┤
+│ Manifest                                                                                      │
+│   • max 80 entries                                                                            │
+│   • entries selected by largest tokenEstimate                                                  │
+│   • sorted back into transcript order                                                          │
+│   • previews truncated to 240 chars                                                           │
+└──────────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+#### Block 4: transcript-bound tool loop
+
+```text
+                                      ┌────────────────────────────────────┐
+                                      │ ContextDeletionMemoryStore          │
+                                      ├────────────────────────────────────┤
+                                      │ deletionTargets: []                 │
+                                      │ callCount: 0                        │
+                                      │ lastError: undefined                │
+                                      │ immutable entry rows                │
+                                      │ immutable content-block rows        │
+                                      └────────────────────────────────────┘
+                                                      ▲
+                                                      │ serialized transaction
+                                                      │
+┌──────────────────────────────┐      ┌──────────────┴──────────────┐      ┌──────────────────────────────┐
+│ Inspection tools             │      │ Mutation tools               │      │ Planner continuation          │
+├──────────────────────────────┤      ├─────────────────────────────┤      ├──────────────────────────────┤
+│ context_search_transcript    │      │ context_delete               │      │ Every tool result has          │
+│   search entry/block text    │      │   exact targets              │      │ terminate: false.              │
+│   no mutation                │      │                              │      │                              │
+│ context_read_entry           │      │ context_grep_delete          │      │ The planner can respond with   │
+│   read bounded text slice    │      │   guarded bulk targets       │      │ more tool calls, or stop.      │
+│   no mutation                │      │                              │      │                              │
+│ context_compaction_budget    │      │ Both route through           │      │ Final assistant prose is       │
+│   window fullness + target   │      │ validateContextDeletionRequest│      │ ignored for deletion targets.  │
+└──────────────────────────────┘      └─────────────────────────────┘      └──────────────────────────────┘
+```
+
+Mutation tool transaction shape:
+
+```text
+┌─────────────────────────────────────────────────────────────────────┐
+│ context_delete / context_grep_delete                                │
+└─────────────────────────────────────────────────────────────────────┘
+        │
+        ├─ snapshot current store
+        ├─ increment callCount
+        ├─ build candidate ContextDeletionTarget[]
+        │    context_delete payload is id-only: { kind, entryId, blockIndex? }
+        │    context_grep_delete payload uses a concise pattern selector
+        ├─ validate incoming targets
+        ├─ merge with existing store.deletionTargets
+        ├─ validate merged cumulative plan
+        │
+        ├─ ✓ success
+        │     ├─ replace store.deletionTargets with reconciled targets
+        │     ├─ clear lastError
+        │     └─ return { content: success text, details: stats, terminate: false }
+        │
+        └─ ✗ failure
+              ├─ restore snapshot
+              ├─ set lastError to exact validation message
+              └─ return { content: correction text, details.error, terminate: false }
+```
+
+#### Block 5: validation airlock
+
+```text
+Candidate cumulative deletion request
+        │
+        ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ Gate 0: request shape                                                │
+│   object with deletions[], id-only keys, valid kind, known entryId     │
+└─────────────────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ Gate 1: recent-context guard                                         │
+│   preserve_recent context entries are rejected with correction text   │
+└─────────────────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ Gate 2: thinking-content guard                                       │
+│   assistant entries containing thinking/redacted_thinking cannot be   │
+│   deleted or partially block-deleted                                  │
+└─────────────────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ Gate 3: protected target guard                                       │
+│   disallowed entries/blocks are rejected with correction text         │
+└─────────────────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ Gate 4: content-block details                                        │
+│   valid integer blockIndex, block exists, not the only block          │
+└─────────────────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ Gate 5: duplicate targets                                            │
+│   duplicate entry/block targets are rejected                          │
+└─────────────────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌─────────────────────────────────────────────────────────────────────┐
+┌─────────────────────────────────────────────────────────────────────┐
+│ Gate 6: tool-call/tool-result reconciliation                         │
+│   repairs paired call/result deletion dependencies when safe          │
+│   throws explicit recent-context errors when repair crosses the       │
+│   preserve_recent boundary                                           │
+└─────────────────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ Gate 7: post-reconcile guards                                        │
+│   no recent targets, no thinking-bearing assistant targets            │
+└─────────────────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ Gate 8: structural integrity                                         │
+│   no entry/content-block overlap, no all-block deletion by blocks,    │
+│   no orphaned tool result, no dangling tool call                      │
+└─────────────────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ Gate 10: context survival                                            │
+│   at least one entry remains, and at least one task-bearing entry     │
+│   remains (user, custom, branchSummary, or branch_summary)            │
+└─────────────────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ Gate 11: stats                                                       │
+│   compute objectsBefore, objectsDeleted, tokensBefore, tokensAfter,   │
+│   percentReduction                                                   │
+└─────────────────────────────────────────────────────────────────────┘
+        │
+        ▼
+ValidatedContextDeletionResult
+```
+
+#### Block 6: dependency repair as a block diagram
+
+```text
+Normal model-visible pairing
+
+┌─────────────────────────────────────────┐        toolCallId        ┌────────────────────────────┐
+│ assistant entry                          │────────────────────────▶│ toolResult entry            │
+│ content block: { type: toolCall, id }    │                         │ toolResultFor = id          │
+└─────────────────────────────────────────┘                         └────────────────────────────┘
+
+If the assistant tool-call block is deleted:
+
+┌─────────────────────────────────────────┐                         ┌────────────────────────────┐
+│ assistant tool-call block deleted        │──────── requires ──────▶│ paired result deleted       │
+└─────────────────────────────────────────┘                         └────────────────────────────┘
+                │                                                                  │
+                └─ if paired result is not deletable                               │
+                   validation removes/rejects the unsafe call deletion             │
+
+If the tool result is deleted:
+
+┌─────────────────────────────────────────┐                         ┌────────────────────────────┐
+│ paired call deleted                      │◀────── requires ───────│ toolResult entry deleted    │
+└─────────────────────────────────────────┘                         └────────────────────────────┘
+                │                                                                  │
+                └─ if paired call is not deletable                                 │
+                   validation removes/rejects the unsafe result deletion           │
+
+Standard recent boundary case:
+
+┌──────────────────────────────┐       repair would delete       ┌──────────────────────────────┐
+│ old side of pair requested   │────────────────────────────────▶│ last-5 side of pair          │
+└──────────────────────────────┘                                  └──────────────────────────────┘
+                                      │
+                                      ▼
+                           explicit correction error
+                           "Cannot delete recent context entry ..."
+```
+
+#### Block 7: persistence and rebuild
+
+```text
+ValidatedContextDeletionResult
+        │
+        ├─ deletedTargets
+        │    [{ kind: "entry", entryId }, { kind: "content_block", entryId, blockIndex }]
+        │
+        ├─ protectedEntryIds
+        │    snapshot of ids protected during preparation
+        │
+        └─ stats
+             object and token reduction estimate
+        │
+        ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ Persist                                                             │
+│   1. write .compact.bak for persisted sessions when available        │
+│   2. append one context_compaction SessionEntry                      │
+│   3. emit session_compact event                                      │
+└─────────────────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ Future buildSessionContext                                           │
+│   1. walk branch path                                                │
+│   2. accumulate all context_compaction filters                       │
+│   3. omit deleted entries                                            │
+│   4. clone messages with deleted content blocks removed              │
+│   5. preserve surviving message objects and content blocks verbatim  │
+│   6. skip unsafe historical filters against latest thinking arrays   │
+│   7. retain paired tool results for restored tool-call blocks        │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+#### Failure paths
+
+| Failure path | State mutation | What the planner or caller sees |
+|--------------|----------------|----------------------------------|
+| `context_delete` validation error | Store rolls back to previous deletion targets | Non-terminating correction tool result with exact error |
+| `context_grep_delete` regex/pattern error | Store rolls back to previous deletion targets | Non-terminating correction tool result with exact error |
+| `context_grep_delete` protected/recent match | Matching protected target is ignored and not counted as a deletion | Non-protected matches still apply when validation succeeds |
+| Planner stops without any valid deletion | Nothing persisted | Compaction fails, including last deletion-tool error when available |
+| Provider overflow after some valid deletions | Valid in-run deletions are used | Compaction can proceed with recorded targets |
+| Provider non-overflow error | Nothing persisted | Error propagates |
+| Extension-provided deletion request invalid | Nothing persisted | Extension/caller sees validation failure |
+
+
+
 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.
+3. **Mark validation guards.** Atomic marks user instructions, custom messages, branch/summary messages, the configured `preserve_recent` context-eligible entries, unresolved assistant/tool errors, and failed bash executions as not directly deletable. If a planner targets one, the deletion tool returns an explicit correction error.
 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.
-5. **Run the deletion planner.** The selected model runs with Atomic's fixed Verbatim Compaction prompt and the lowest supported thinking level for that model. It can search/read transcript slices and then call deletion tools.
+5. **Run the deletion planner.** The user's currently selected model runs Atomic's fixed Verbatim Compaction prompt using the session's current model thinking level. It can search/read transcript slices and then call deletion tools. The prompt substitutes the effective compaction parameters: `compression_ratio` (fraction to keep, default `0.5`), `preserve_recent` (default `2`), and `query` (explicit or auto-detected). The target reduction is `1 - compression_ratio` and is treated as a strict completion requirement.
 6. **Validate fail-closed.** Atomic validates every cumulative deletion plan locally. Unknown IDs, protected targets, duplicate/overlapping targets, empty-context plans, missing task-bearing context, and tool-call/tool-result orphaning are rejected.
-7. **Save and rebuild.** Atomic writes a backup snapshot for persisted sessions, appends a `context_compaction` entry with validated targets and stats, then rebuilds the active LLM context from the filtered branch.
+7. **Continue until target.** Atomic exits the internal planner loop when validated deletion stats meet the configured reduction target. If the model tries to finish early, Atomic injects a follow-up nudge with the current validated reduction and tells the planner to continue removing message entries/content blocks.
+8. **Save and rebuild.** Atomic writes a backup snapshot for persisted sessions, appends a `context_compaction` entry with validated targets and stats, then rebuilds the active LLM context from the filtered branch.
 
 ### Transcript-Bound Tools
 
-The compaction assistant can only compact by using these internal tools:
+The compaction assistant can only compact by using these internal tools. Exact deletion is intentionally id-only: the planner identifies entries or content blocks, then calls `context_delete` with `kind`, `entryId`, and optional `blockIndex`. Content-based deletion goes through `context_grep_delete`, where the planner sends a concise literal or regex pattern and Atomic resolves the matching ids locally. Neither mutation path accepts full block text, replacement bodies, summaries, or rationale fields as deletion payload content.
 
 | Tool | Purpose |
 |------|---------|
 | `context_search_transcript` | Search entry or content-block text and return small snippets. |
 | `context_read_entry` | Read a bounded slice of one entry or content block. |
+| `context_compaction_budget` | Report context-window fullness, selected-deletion progress, `compression_ratio`, and remaining work to reach the strict reduction target. |
 | `context_delete` | Record exact entry/content-block deletion targets. |
 | `context_grep_delete` | Bulk-delete matching entries or content blocks with guardrails. |
 
-`context_grep_delete` supports literal or regex matching, skips protected/already-deleted context, has match-count caps, can require `expectedMatchCount`, and routes matches through the same validation pipeline as exact deletions.
-
-Tool calls are cumulative during one compaction run. The assistant can apply several small deletion batches, inspect the updated state, and stop when enough safe context has been removed. Atomic uses the validated tool state as the compaction result; deletion JSON written in ordinary assistant text is not used for the final action.
-
-### Protection and Validation Rules
-
-In standard mode, Atomic protects:
-
-- User messages and user-provided task context.
-- 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.
-- Failed bash executions.
+The planner is prompted to call `context_compaction_budget` before deleting and after deletion batches. The tool reports the current transcript token estimate as a percentage of the selected model's context window, the configured `compression_ratio`, the projected percentage after selected deletions, current reduction percentage, and how many more estimated tokens must be removed to reach the strict target. With the default `compression_ratio: 0.5`, the strict target is a 50% token reduction.
 
-Validation also preserves tool-call/tool-result consistency. If deleting a tool call would leave a tool result behind, Atomic either deletes the paired result too or rejects the plan when that would violate protection. If deleting a tool result would leave a visible dangling tool call, Atomic either deletes the paired call too or rejects the plan.
+`context_grep_delete` supports literal or regex matching, skips already-deleted or disallowed context, enforces a per-call `maxMatches` safety cap, can require `expectedMatchCount` when the planner wants an exact-match safety check, and routes every accepted match through the same validation pipeline as exact deletions. Disallowed matches are ignored before `matches`, `expectedMatchCount`, deletion stats, and selected targets are calculated, so a broad regex can still remove safe blocks without counting rejected candidates as removed. `maxMatches` limits only one tool call; there is no cumulative deletion cap across repeated `context_delete` or `context_grep_delete` calls. Exact deletion attempts that target disallowed entries/blocks return an explicit non-terminating tool error with correction guidance. Exact deletion payloads that include unsupported fields such as transcript `text`, block `content`, summaries, or replacement data are rejected as non-id-only requests.
 
-Atomic also refuses plans that would delete all context or leave no task-bearing context. These checks are local; the model cannot bypass them.
+Tool calls are cumulative during one compaction run. The assistant can apply several small deletion batches, inspect the updated state, and stop only after the validated stats meet the strict reduction target. Atomic uses the validated tool state as the compaction result; ordinary assistant text is ignored for deletion targets.
 
-### Standard vs. Critical Overflow Mode
+### Validation Rules
 
-Manual `/compact` and threshold auto-compaction run in **standard** mode: protected entries and protected content blocks cannot be deleted.
+Validation preserves tool-call/tool-result consistency. If deleting a tool call would leave a tool result behind, Atomic either deletes the paired result too or rejects the plan when that would violate a validation guard. If deleting a tool result would leave a visible dangling tool call, Atomic either deletes the paired call too or rejects the plan.
 
-When a provider returns a context-overflow error, Atomic runs one **critical overflow** recovery pass before retrying. Critical overflow mode first tries stale unprotected context. If that is not enough, it may delete older protected user/custom/summary context, but it still preserves the last five context-eligible entries, unresolved errors, failed commands, and enough task-bearing context for continuation. Atomic retries once after a successful overflow compaction.
+Atomic also refuses plans that would delete all context or leave no task-bearing context. These checks are local; the model cannot bypass them. Provider context-overflow recovery uses the same validation rules as manual and threshold compaction.
 
 ### ContextCompactionEntry Structure
 
@@ -227,14 +638,17 @@ Fired before the internal deletion planner runs. Extensions can cancel compactio
 
 ```typescript
 pi.on("session_before_compact", async (event, ctx) => {
-  const { preparation, branchEntries, reason, mode, signal } = event;
+  const { preparation, parameters, branchEntries, reason, signal } = event;
 
+  // parameters.compression_ratio - fraction of compactable context to keep
+  // parameters.preserve_recent - recent context-eligible messages kept uncompressed
+  // parameters.query - focus query used by the planner
+  // preparation.parameters - same effective parameters on the frozen preparation snapshot
   // preparation.transcript.entries - entries eligible for deletion
-  // preparation.transcript.protectedEntryIds - entries that cannot be deleted in standard mode
+  // preparation.transcript.protectedEntryIds - entry ids validation will reject if directly deleted
   // preparation.transcript.tokensBefore - context token estimate before compaction
   // branchEntries - all entries on current branch
   // reason - "manual" | "threshold" | "overflow"
-  // mode - "standard" | "critical_overflow"
 
   // Cancel compaction:
   return { cancel: true };
@@ -259,7 +673,8 @@ Fired after compaction succeeds and the `context_compaction` entry is persisted.
 
 ```typescript
 pi.on("session_compact", async (event, ctx) => {
-  // event.result - ContextCompactionResult
+  // event.parameters - effective compression_ratio, preserve_recent, and query
+  // event.result - ContextCompactionResult, including result.parameters
   // event.contextCompactionEntry - the saved ContextCompactionEntry
   // event.reason - "manual" | "threshold" | "overflow"
   // event.fromExtension - true if extension provided the deletionRequest
@@ -279,6 +694,9 @@ Trigger Verbatim Compaction without awaiting completion. See [Extensions](/exten
 
 ```typescript
 ctx.compact({
+  compression_ratio: 0.3,
+  preserve_recent: 2,
+  query: "keep context relevant to the active bug fix",
   onComplete: (result) => {
     ctx.ui.notify(`Compacted: deleted ${result.stats.objectsDeleted} objects`, "info");
   },
@@ -288,7 +706,7 @@ ctx.compact({
 });
 ```
 
-`ctx.compact()` does not accept custom instructions. Verbatim Compaction uses a fixed internal prompt; no custom summary text can be injected.
+`ctx.compact()` accepts the same compaction parameters as hooks/settings (`compression_ratio`, `preserve_recent`, and `query`) but does not accept arbitrary custom summary instructions. Verbatim Compaction uses a fixed internal prompt; no custom summary text can be injected.
 
 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.