From 67af9d707fdffdef8c652a238a5fc74caec385b1 Mon Sep 17 00:00:00 2001
From: Mario Zechner <badlogicgames@gmail.com>
Date: Wed, 31 Dec 2025 12:36:28 +0100
Subject: [PATCH] Clarify that compaction/branch details are hook-customizable

---
 packages/coding-agent/docs/compaction.md | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)

diff --git a/packages/coding-agent/docs/compaction.md b/packages/coding-agent/docs/compaction.md
index 168ce198..65b61701 100644
--- a/packages/coding-agent/docs/compaction.md
+++ b/packages/coding-agent/docs/compaction.md
@@ -108,7 +108,7 @@ Never cut at tool results (they must stay with their tool call).
 ### CompactionEntry Structure
 
 ```typescript
-interface CompactionEntry {
+interface CompactionEntry<T = unknown> {
   type: "compaction";
   id: string;
   parentId: string;
@@ -116,16 +116,20 @@ interface CompactionEntry {
   summary: string;
   firstKeptEntryId: string;
   tokensBefore: number;
-  fromHook?: boolean;
-  details?: CompactionDetails;
+  fromHook?: boolean;  // true if hook provided the compaction
+  details?: T;         // hook-specific data
 }
 
+// Default compaction uses this for details:
 interface CompactionDetails {
   readFiles: string[];
   modifiedFiles: string[];
 }
 ```
 
+Hooks can store any JSON-serializable data in `details`. The default compaction tracks file operations, but custom compaction hooks can use their own structure.
+```
+
 ## Branch Summarization
 
 ### When It Triggers
@@ -168,23 +172,26 @@ This means nested summaries accumulate file tracking across the entire abandoned
 ### BranchSummaryEntry Structure
 
 ```typescript
-interface BranchSummaryEntry {
+interface BranchSummaryEntry<T = unknown> {
   type: "branch_summary";
   id: string;
   parentId: string;
   timestamp: number;
   summary: string;
-  fromId: string;  // Entry we navigated from
-  fromHook?: boolean;
-  details?: BranchSummaryDetails;
+  fromId: string;      // Entry we navigated from
+  fromHook?: boolean;  // true if hook provided the summary
+  details?: T;         // hook-specific data
 }
 
+// Default branch summarization uses this for details:
 interface BranchSummaryDetails {
   readFiles: string[];
   modifiedFiles: string[];
 }
 ```
 
+Same as compaction, hooks can store custom data in `details`.
+
 ## Summary Format
 
 Both compaction and branch summarization use the same structured format: