From 2953a9d8d4670289f44d62a8ed1b67e38a31dae9 Mon Sep 17 00:00:00 2001
From: Nico Bailon <nico.bailon@gmail.com>
Date: Mon, 22 Dec 2025 18:26:08 -0800
Subject: [PATCH] Add skipConversationRestore for before_branch hooks (#286)

---
 packages/coding-agent/docs/hooks.md             | 7 ++++++-
 packages/coding-agent/src/core/agent-session.ts | 7 ++++++-
 packages/coding-agent/src/core/hooks/types.ts   | 2 ++
 3 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/packages/coding-agent/docs/hooks.md b/packages/coding-agent/docs/hooks.md
index 89936ced..50383971 100644
--- a/packages/coding-agent/docs/hooks.md
+++ b/packages/coding-agent/docs/hooks.md
@@ -154,7 +154,12 @@ pi.on("session", async (event, ctx) => {
   if (event.reason === "before_clear") {
     return { cancel: true };
   }
-  // No return needed if not cancelling
+
+  // For before_branch only: create branch but skip conversation restore
+  // (useful for checkpoint hooks that restore files separately)
+  if (event.reason === "before_branch") {
+    return { skipConversationRestore: true };
+  }
 });
 ```
 
diff --git a/packages/coding-agent/src/core/agent-session.ts b/packages/coding-agent/src/core/agent-session.ts
index 54c574da..3fa1617e 100644
--- a/packages/coding-agent/src/core/agent-session.ts
+++ b/packages/coding-agent/src/core/agent-session.ts
@@ -1249,6 +1249,8 @@ export class AgentSession {
 
 		const selectedText = this._extractUserMessageText(selectedEntry.message.content);
 
+		let skipConversationRestore = false;
+
 		// Emit before_branch event (can be cancelled)
 		if (this._hookRunner?.hasHandlers("session")) {
 			const result = (await this._hookRunner.emit({
@@ -1263,6 +1265,7 @@ export class AgentSession {
 			if (result?.cancel) {
 				return { selectedText, cancelled: true };
 			}
+			skipConversationRestore = result?.skipConversationRestore ?? false;
 		}
 
 		// Create branched session (returns null in --no-session mode)
@@ -1293,7 +1296,9 @@ export class AgentSession {
 		// Emit session event to custom tools (with reason "branch")
 		await this._emitToolSessionEvent("branch", previousSessionFile);
 
-		this.agent.replaceMessages(loaded.messages);
+		if (!skipConversationRestore) {
+			this.agent.replaceMessages(loaded.messages);
+		}
 
 		return { selectedText, cancelled: false };
 	}
diff --git a/packages/coding-agent/src/core/hooks/types.ts b/packages/coding-agent/src/core/hooks/types.ts
index 02563048..a9451139 100644
--- a/packages/coding-agent/src/core/hooks/types.ts
+++ b/packages/coding-agent/src/core/hooks/types.ts
@@ -323,6 +323,8 @@ export interface ToolResultEventResult {
 export interface SessionEventResult {
 	/** If true, cancel the pending action (switch, clear, or branch) */
 	cancel?: boolean;
+	/** If true (for before_branch only), skip restoring conversation to branch point while still creating the branched session file */
+	skipConversationRestore?: boolean;
 }
 
 // ============================================================================