refactor(hooks): split session events into individual typed events

Major changes:
- Replace monolithic SessionEvent with reason discriminator with individual
  event types: session_start, session_before_switch, session_switch,
  session_before_new, session_new, session_before_branch, session_branch,
  session_before_compact, session_compact, session_shutdown
- Each event has dedicated result type (SessionBeforeSwitchResult, etc.)
- HookHandler type now allows bare return statements (void in return type)
- HookAPI.on() has proper overloads for each event with correct typing

Additional fixes:
- AgentSession now always subscribes to agent in constructor (was only
  subscribing when external subscribe() called, breaking internal handlers)
- Standardize on undefined over null throughout codebase
- HookUIContext methods return undefined instead of null
- SessionManager methods return undefined instead of null
- Simplify hook exports to 'export type * from types.js'
- Add detailed JSDoc for skipConversationRestore vs cancel
- Fix createBranchedSession to rebuild index in persist mode
- newSession() now returns the session file path

Updated all example hooks, tests, and emission sites to use new event types.

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

@@ -51,17 +51,17 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 	 * Create a hook UI context that uses the RPC protocol.
 	 */
 	const createHookUIContext = (): HookUIContext => ({
-		async select(title: string, options: string[]): Promise<string | null> {
+		async select(title: string, options: string[]): Promise<string | undefined> {
 			const id = crypto.randomUUID();
 			return new Promise((resolve, reject) => {
 				pendingHookRequests.set(id, {
 					resolve: (response: RpcHookUIResponse) => {
 						if ("cancelled" in response && response.cancelled) {
-							resolve(null);
+							resolve(undefined);
 						} else if ("value" in response) {
 							resolve(response.value);
 						} else {
-							resolve(null);
+							resolve(undefined);
 						}
 					},
 					reject,
@@ -89,17 +89,17 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 			});
 		},
 
-		async input(title: string, placeholder?: string): Promise<string | null> {
+		async input(title: string, placeholder?: string): Promise<string | undefined> {
 			const id = crypto.randomUUID();
 			return new Promise((resolve, reject) => {
 				pendingHookRequests.set(id, {
 					resolve: (response: RpcHookUIResponse) => {
 						if ("cancelled" in response && response.cancelled) {
-							resolve(null);
+							resolve(undefined);
 						} else if ("value" in response) {
 							resolve(response.value);
 						} else {
-							resolve(null);
+							resolve(undefined);
 						}
 					},
 					reject,
@@ -144,10 +144,9 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 		hookRunner.setAppendEntryHandler((customType, data) => {
 			session.sessionManager.appendCustomEntry(customType, data);
 		});
-		// Emit session event
+		// Emit session_start event
 		await hookRunner.emit({
-			type: "session",
-			reason: "start",
+			type: "session_start",
 		});
 	}
 
@@ -159,7 +158,7 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 				await tool.onSession({
 					entries,
 					sessionFile: session.sessionFile,
-					previousSessionFile: null,
+					previousSessionFile: undefined,
 					reason: "start",
 				});
 			} catch (_err) {