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/compaction-hooks-example.test.ts

@@ -3,18 +3,16 @@
  */
 
 import { describe, expect, it } from "vitest";
-import type { HookAPI } from "../src/core/hooks/index.js";
+import type { HookAPI, SessionBeforeCompactEvent, SessionCompactEvent } from "../src/core/hooks/index.js";
 
 describe("Documentation example", () => {
 	it("custom compaction example should type-check correctly", () => {
 		// This is the example from hooks.md - verify it compiles
 		const exampleHook = (pi: HookAPI) => {
-			pi.on("session", async (event, ctx) => {
-				if (event.reason !== "before_compact") return;
-
-				// After narrowing, these should all be accessible
-				// sessionManager and modelRegistry come from ctx, not event
+			pi.on("session_before_compact", async (event: SessionBeforeCompactEvent, ctx) => {
+				// All these should be accessible on the event
 				const { preparation, previousCompactions, model } = event;
+				// sessionManager and modelRegistry come from ctx, not event
 				const { sessionManager, modelRegistry } = ctx;
 				const { messagesToSummarize, messagesToKeep, tokensBefore, firstKeptEntryId, cutPoint } = preparation;
 
@@ -51,12 +49,10 @@ describe("Documentation example", () => {
 		expect(typeof exampleHook).toBe("function");
 	});
 
-	it("compact event should have correct fields after narrowing", () => {
+	it("compact event should have correct fields", () => {
 		const checkCompactEvent = (pi: HookAPI) => {
-			pi.on("session", async (event, _ctx) => {
-				if (event.reason !== "compact") return;
-
-				// After narrowing, these should all be accessible
+			pi.on("session_compact", async (event: SessionCompactEvent) => {
+				// These should all be accessible
 				const entry = event.compactionEntry;
 				const fromHook = event.fromHook;