Surface context compaction lifecycle

src/CodexAcpServer.ts

@@ -46,6 +46,7 @@ import {
 } from "./AcpExtensions";
 import {
     createCollabAgentToolCallUpdate,
+    createCompletedContextCompactionUpdate,
     createCommandExecutionCompleteUpdate,
     createCommandExecutionUpdate,
     createDynamicToolCallUpdate,
@@ -1039,7 +1040,7 @@ export class CodexAcpServer {
             case "exitedReviewMode":
                 return [this.createReviewModeUpdate(item, false)];
             case "contextCompaction":
-                return [this.createContextCompactionUpdate()];
+                return [createCompletedContextCompactionUpdate(item)];
             case "plan":
                 return [this.createPlanUpdate(item)];
         }
@@ -1092,16 +1093,6 @@ export class CodexAcpServer {
         };
     }
 
-    private createContextCompactionUpdate(): UpdateSessionEvent {
-        return {
-            sessionUpdate: "agent_message_chunk",
-            content: {
-                type: "text",
-                text: "Context compacted.",
-            },
-        };
-    }
-
     private createPlanUpdate(
         item: ThreadItem & { type: "plan" }
     ): UpdateSessionEvent {

src/CodexEventHandler.ts

@@ -36,6 +36,8 @@ import {
     createCollabAgentToolCallCompleteUpdate,
     createCollabAgentToolCallUpdate,
     createCommandExecutionUpdate,
+    createContextCompactionCompleteUpdate,
+    createContextCompactionStartUpdate,
     createDynamicToolCallUpdate,
     createFileChangeUpdate,
     createGuardianApprovalReviewToolCall,
@@ -337,14 +339,15 @@ export class CodexEventHandler {
             case "agentMessage":
                 this.rememberAgentMessagePhase(event.item);
                 return null;
+            case "contextCompaction":
+                return createContextCompactionStartUpdate(event.item);
             case "subAgentActivity":
             case "sleep":
             case "userMessage":
             case "hookPrompt":
             case "reasoning":
             case "enteredReviewMode":
             case "exitedReviewMode":
-            case "contextCompaction":
             case "plan":
                 return null;
         }
@@ -394,7 +397,7 @@ export class CodexEventHandler {
             case "exitedReviewMode":
                 return this.createExitedReviewModeEvent(event.item);
             case "contextCompaction":
-                return this.createContextCompactedEvent();
+                return createContextCompactionCompleteUpdate(event.item);
             //ignored types
             case "subAgentActivity":
             case "sleep":

src/CodexToolCallMapper.ts

@@ -41,8 +41,11 @@ type GuardianApprovalReviewNotification =
 type WebSearchItem = ThreadItem & { type: "webSearch" };
 type CollabAgentToolCallItem = ThreadItem & { type: "collabAgentToolCall" };
 type CommandExecutionItem = ThreadItem & { type: "commandExecution" };
+type ContextCompactionItem = ThreadItem & { type: "contextCompaction" };
 type AcpToolCallEvent = Extract<UpdateSessionEvent, { sessionUpdate: "tool_call" }>;
 
+const CONTEXT_COMPACTION_META = { contextCompaction: true };
+
 function toAcpStatus(status: CodexItemStatus): AcpToolCallStatus {
     switch (status) {
         case "inProgress":
@@ -220,6 +223,44 @@ export function createImageGenerationUpdate(
     };
 }
 
+export function createContextCompactionStartUpdate(
+    item: ContextCompactionItem,
+): UpdateSessionEvent {
+    return {
+        sessionUpdate: "tool_call",
+        toolCallId: item.id,
+        kind: "other",
+        title: "Context compacting",
+        status: "in_progress",
+        _meta: CONTEXT_COMPACTION_META,
+    };
+}
+
+export function createContextCompactionCompleteUpdate(
+    item: ContextCompactionItem,
+): UpdateSessionEvent {
+    return {
+        sessionUpdate: "tool_call_update",
+        toolCallId: item.id,
+        title: "Context compacted",
+        status: "completed",
+        _meta: CONTEXT_COMPACTION_META,
+    };
+}
+
+export function createCompletedContextCompactionUpdate(
+    item: ContextCompactionItem,
+): UpdateSessionEvent {
+    return {
+        sessionUpdate: "tool_call",
+        toolCallId: item.id,
+        kind: "other",
+        title: "Context compacted",
+        status: "completed",
+        _meta: CONTEXT_COMPACTION_META,
+    };
+}
+
 export async function createExecuteToolCallUpdate(
     item: ThreadItem & ({ type: "mcpToolCall" } | { type: "dynamicToolCall" }),
     title: string,

src/ResponseItemHistoryFallback.ts

@@ -175,6 +175,7 @@ function toolCallIdFromThreadItem(item: ThreadItem): string | null {
         case "webSearch":
         case "imageView":
         case "imageGeneration":
+        case "contextCompaction":
             return item.id;
         case "userMessage":
         case "hookPrompt":
@@ -184,7 +185,6 @@ function toolCallIdFromThreadItem(item: ThreadItem): string | null {
         case "subAgentActivity":
         case "enteredReviewMode":
         case "exitedReviewMode":
-        case "contextCompaction":
         case "sleep":
             return null;
     }

src/__tests__/CodexACPAgent/CodexAcpClient.test.ts

@@ -3243,7 +3243,7 @@ describe('ACP server test', { timeout: 40_000 }, () => {
         await expect(mockFixture.getAcpConnectionDump([])).toMatchFileSnapshot("data/thread-compacted.json");
     });
 
-    it ('should surface contextCompaction item as user-visible message', async () => {
+    it ('should surface contextCompaction item lifecycle as a tool call', async () => {
         const sessionId = "test-session-id";
         const { mockFixture } = setupPromptFixture({ sessionId });
 
@@ -3254,6 +3254,15 @@ describe('ACP server test', { timeout: 40_000 }, () => {
 
         mockFixture.clearAcpConnectionDump();
 
+        mockFixture.sendServerNotification({
+            method: "item/started",
+            params: {
+                threadId: sessionId,
+                turnId: "turn-id",
+                startedAtMs: 0,
+                item: { type: "contextCompaction", id: "context-compaction-id" },
+            },
+        });
         mockFixture.sendServerNotification({
             method: "item/completed",
             params: {
@@ -3265,11 +3274,11 @@ describe('ACP server test', { timeout: 40_000 }, () => {
         });
 
         await vi.waitFor(() => {
-            const dump = mockFixture.getAcpConnectionDump([]);
-            expect(dump.length).toBeGreaterThan(0);
+            const events = mockFixture.getAcpConnectionEvents([]);
+            expect(events).toHaveLength(2);
         });
 
-        await expect(mockFixture.getAcpConnectionDump([])).toMatchFileSnapshot("data/thread-compacted.json");
+        await expect(mockFixture.getAcpConnectionDump([])).toMatchFileSnapshot("data/context-compaction-lifecycle.json");
     });
 
     it ('should surface exitedReviewMode item as user-visible review output', async () => {

src/__tests__/CodexACPAgent/data/context-compaction-lifecycle.json

@@ -0,0 +1,35 @@
+{
+  "method": "sessionUpdate",
+  "args": [
+    {
+      "sessionId": "test-session-id",
+      "update": {
+        "sessionUpdate": "tool_call",
+        "toolCallId": "context-compaction-id",
+        "kind": "other",
+        "title": "Context compacting",
+        "status": "in_progress",
+        "_meta": {
+          "contextCompaction": true
+        }
+      }
+    }
+  ]
+}
+{
+  "method": "sessionUpdate",
+  "args": [
+    {
+      "sessionId": "test-session-id",
+      "update": {
+        "sessionUpdate": "tool_call_update",
+        "toolCallId": "context-compaction-id",
+        "title": "Context compacted",
+        "status": "completed",
+        "_meta": {
+          "contextCompaction": true
+        }
+      }
+    }
+  ]
+}

src/__tests__/CodexACPAgent/data/load-session-history.json

@@ -327,4 +327,22 @@
       }
     }
   ]
+}
+{
+  "method": "sessionUpdate",
+  "args": [
+    {
+      "sessionId": "session-1",
+      "update": {
+        "sessionUpdate": "tool_call",
+        "toolCallId": "item-context-compaction-1",
+        "kind": "other",
+        "title": "Context compacted",
+        "status": "completed",
+        "_meta": {
+          "contextCompaction": true
+        }
+      }
+    }
+  ]
 }

src/__tests__/CodexACPAgent/load-session.test.ts

@@ -161,6 +161,10 @@ describe("CodexACPAgent - loadSession", () => {
                             result: "iVBORw0KGgo=",
                             savedPath: "/test/project/generated-blue-square.png",
                         },
+                        {
+                            type: "contextCompaction",
+                            id: "item-context-compaction-1",
+                        },
                     ],
                 },
             ],