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/test/session-manager/build-context.test.ts

@@ -48,7 +48,7 @@ function compaction(id: string, parentId: string | null, summary: string, firstK
 	};
 }
 
-function branchSummary(id: string, parentId: string | null, fromId: string, summary: string): BranchSummaryEntry {
+function branchSummary(id: string, parentId: string | null, summary: string, fromId: string): BranchSummaryEntry {
 	return { type: "branch_summary", id, parentId, timestamp: "2025-01-01T00:00:00Z", summary, fromId };
 }
 
@@ -132,7 +132,7 @@ describe("buildSessionContext", () => {
 
 			// Should have: summary + kept (3,4) + after (6,7) = 5 messages
 			expect(ctx.messages).toHaveLength(5);
-			expect((ctx.messages[0] as any).content).toContain("Summary of first two turns");
+			expect((ctx.messages[0] as any).summary).toContain("Summary of first two turns");
 			expect((ctx.messages[1] as any).content).toBe("second");
 			expect((ctx.messages[2] as any).content[0].text).toBe("response2");
 			expect((ctx.messages[3] as any).content).toBe("third");
@@ -150,7 +150,7 @@ describe("buildSessionContext", () => {
 
 			// Summary + all messages (1,2,4)
 			expect(ctx.messages).toHaveLength(4);
-			expect((ctx.messages[0] as any).content).toContain("Empty summary");
+			expect((ctx.messages[0] as any).summary).toContain("Empty summary");
 		});
 
 		it("multiple compactions uses latest", () => {
@@ -167,7 +167,7 @@ describe("buildSessionContext", () => {
 
 			// Should use second summary, keep from 4
 			expect(ctx.messages).toHaveLength(4);
-			expect((ctx.messages[0] as any).content).toContain("Second summary");
+			expect((ctx.messages[0] as any).summary).toContain("Second summary");
 		});
 	});
 
@@ -203,7 +203,7 @@ describe("buildSessionContext", () => {
 			const ctx = buildSessionContext(entries, "5");
 
 			expect(ctx.messages).toHaveLength(4);
-			expect((ctx.messages[2] as any).content).toContain("Summary of abandoned work");
+			expect((ctx.messages[2] as any).summary).toContain("Summary of abandoned work");
 			expect((ctx.messages[3] as any).content).toBe("new direction");
 		});
 
@@ -231,7 +231,7 @@ describe("buildSessionContext", () => {
 			// Main path to 7: summary + kept(3,4) + after(6,7)
 			const ctxMain = buildSessionContext(entries, "7");
 			expect(ctxMain.messages).toHaveLength(5);
-			expect((ctxMain.messages[0] as any).content).toContain("Compacted history");
+			expect((ctxMain.messages[0] as any).summary).toContain("Compacted history");
 			expect((ctxMain.messages[1] as any).content).toBe("q2");
 			expect((ctxMain.messages[2] as any).content[0].text).toBe("r2");
 			expect((ctxMain.messages[3] as any).content).toBe("q3");
@@ -243,7 +243,7 @@ describe("buildSessionContext", () => {
 			expect((ctxBranch.messages[0] as any).content).toBe("start");
 			expect((ctxBranch.messages[1] as any).content[0].text).toBe("r1");
 			expect((ctxBranch.messages[2] as any).content).toBe("q2");
-			expect((ctxBranch.messages[3] as any).content).toContain("Tried wrong approach");
+			expect((ctxBranch.messages[3] as any).summary).toContain("Tried wrong approach");
 			expect((ctxBranch.messages[4] as any).content).toBe("better approach");
 		});
 	});

packages/coding-agent/test/session-manager/tree-traversal.test.ts

@@ -451,7 +451,7 @@ describe("createBranchedSession", () => {
 
 		// Create branched session from id2 (should only have 1 -> 2)
 		const result = session.createBranchedSession(id2);
-		expect(result).toBeNull(); // in-memory returns null
+		expect(result).toBeUndefined(); // in-memory returns null
 
 		// Session should now only have entries 1 and 2
 		const entries = session.getEntries();