Add skipConversationRestore for before_branch hooks (#286)

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 };
+  }
 });
 ```
 

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 };
 	}

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;
 }
 
 // ============================================================================