Change branch() to use entryId instead of entryIndex

- AgentSession.branch(entryId: string) now takes entry ID
- SessionBeforeBranchEvent.entryId replaces entryIndex
- getUserMessagesForBranching() returns entryId
- Update RPC types and client
- Update UserMessageSelectorComponent
- Update hook examples and tests
- Update docs (hooks.md, sdk.md)

packages/coding-agent/src/modes/interactive/components/user-message-selector.ts

@@ -14,7 +14,7 @@ import { theme } from "../theme/theme.js";
 import { DynamicBorder } from "./dynamic-border.js";
 
 interface UserMessageItem {
-	index: number; // Index in the full messages array
+	id: string; // Entry ID in the session
 	text: string; // The message text
 	timestamp?: string; // Optional timestamp if available
 }
@@ -25,7 +25,7 @@ interface UserMessageItem {
 class UserMessageList implements Component {
 	private messages: UserMessageItem[] = [];
 	private selectedIndex: number = 0;
-	public onSelect?: (messageIndex: number) => void;
+	public onSelect?: (entryId: string) => void;
 	public onCancel?: () => void;
 	private maxVisible: number = 10; // Max messages visible
 
@@ -101,7 +101,7 @@ class UserMessageList implements Component {
 		else if (isEnter(keyData)) {
 			const selected = this.messages[this.selectedIndex];
 			if (selected && this.onSelect) {
-				this.onSelect(selected.index);
+				this.onSelect(selected.id);
 			}
 		}
 		// Escape - cancel
@@ -125,7 +125,7 @@ class UserMessageList implements Component {
 export class UserMessageSelectorComponent extends Container {
 	private messageList: UserMessageList;
 
-	constructor(messages: UserMessageItem[], onSelect: (messageIndex: number) => void, onCancel: () => void) {
+	constructor(messages: UserMessageItem[], onSelect: (entryId: string) => void, onCancel: () => void) {
 		super();
 
 		// Add header

packages/coding-agent/src/modes/interactive/interactive-mode.ts

@@ -1570,9 +1570,9 @@ export class InteractiveMode {
 
 		this.showSelector((done) => {
 			const selector = new UserMessageSelectorComponent(
-				userMessages.map((m) => ({ index: m.entryIndex, text: m.text })),
-				async (entryIndex) => {
-					const result = await this.session.branch(entryIndex);
+				userMessages.map((m) => ({ id: m.entryId, text: m.text })),
+				async (entryId) => {
+					const result = await this.session.branch(entryId);
 					if (result.cancelled) {
 						// Hook cancelled the branch
 						done();

packages/coding-agent/src/modes/rpc/rpc-client.ts

@@ -326,17 +326,17 @@ export class RpcClient {
 	 * Branch from a specific message.
 	 * @returns Object with `text` (the message text) and `cancelled` (if hook cancelled)
 	 */
-	async branch(entryIndex: number): Promise<{ text: string; cancelled: boolean }> {
-		const response = await this.send({ type: "branch", entryIndex });
+	async branch(entryId: string): Promise<{ text: string; cancelled: boolean }> {
+		const response = await this.send({ type: "branch", entryId });
 		return this.getData(response);
 	}
 
 	/**
 	 * Get messages available for branching.
 	 */
-	async getBranchMessages(): Promise<Array<{ entryIndex: number; text: string }>> {
+	async getBranchMessages(): Promise<Array<{ entryId: string; text: string }>> {
 		const response = await this.send({ type: "get_branch_messages" });
-		return this.getData<{ messages: Array<{ entryIndex: number; text: string }> }>(response).messages;
+		return this.getData<{ messages: Array<{ entryId: string; text: string }> }>(response).messages;
 	}
 
 	/**

packages/coding-agent/src/modes/rpc/rpc-mode.ts

@@ -347,7 +347,7 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 			}
 
 			case "branch": {
-				const result = await session.branch(command.entryIndex);
+				const result = await session.branch(command.entryId);
 				return success(id, "branch", { text: result.selectedText, cancelled: result.cancelled });
 			}
 

packages/coding-agent/src/modes/rpc/rpc-types.ts

@@ -53,7 +53,7 @@ export type RpcCommand =
 	| { id?: string; type: "get_session_stats" }
 	| { id?: string; type: "export_html"; outputPath?: string }
 	| { id?: string; type: "switch_session"; sessionPath: string }
-	| { id?: string; type: "branch"; entryIndex: number }
+	| { id?: string; type: "branch"; entryId: string }
 	| { id?: string; type: "get_branch_messages" }
 	| { id?: string; type: "get_last_assistant_text" }
 
@@ -150,7 +150,7 @@ export type RpcResponse =
 			type: "response";
 			command: "get_branch_messages";
 			success: true;
-			data: { messages: Array<{ entryIndex: number; text: string }> };
+			data: { messages: Array<{ entryId: string; text: string }> };
 	  }
 	| {
 			id?: string;