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/examples/hooks/dirty-repo-guard.ts

@@ -5,47 +5,55 @@
  * Useful to ensure work is committed before switching context.
  */
 
-import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+import type { HookAPI, HookEventContext } from "@mariozechner/pi-coding-agent/hooks";
+
+async function checkDirtyRepo(
+	pi: HookAPI,
+	ctx: HookEventContext,
+	action: string,
+): Promise<{ cancel: boolean } | undefined> {
+	// Check for uncommitted changes
+	const { stdout, code } = await pi.exec("git", ["status", "--porcelain"]);
+
+	if (code !== 0) {
+		// Not a git repo, allow the action
+		return;
+	}
+
+	const hasChanges = stdout.trim().length > 0;
+	if (!hasChanges) {
+		return;
+	}
+
+	if (!ctx.hasUI) {
+		// In non-interactive mode, block by default
+		return { cancel: true };
+	}
+
+	// Count changed files
+	const changedFiles = stdout.trim().split("\n").filter(Boolean).length;
+
+	const choice = await ctx.ui.select(`You have ${changedFiles} uncommitted file(s). ${action} anyway?`, [
+		"Yes, proceed anyway",
+		"No, let me commit first",
+	]);
+
+	if (choice !== "Yes, proceed anyway") {
+		ctx.ui.notify("Commit your changes first", "warning");
+		return { cancel: true };
+	}
+}
 
 export default function (pi: HookAPI) {
-	pi.on("session", async (event, ctx) => {
-		// Only guard destructive actions
-		if (event.reason !== "before_new" && event.reason !== "before_switch" && event.reason !== "before_branch") {
-			return;
-		}
+	pi.on("session_before_new", async (_event, ctx) => {
+		return checkDirtyRepo(pi, ctx, "new session");
+	});
 
-		// Check for uncommitted changes
-		const { stdout, code } = await pi.exec("git", ["status", "--porcelain"]);
+	pi.on("session_before_switch", async (_event, ctx) => {
+		return checkDirtyRepo(pi, ctx, "switch session");
+	});
 
-		if (code !== 0) {
-			// Not a git repo, allow the action
-			return;
-		}
-
-		const hasChanges = stdout.trim().length > 0;
-		if (!hasChanges) {
-			return;
-		}
-
-		if (!ctx.hasUI) {
-			// In non-interactive mode, block by default
-			return { cancel: true };
-		}
-
-		// Count changed files
-		const changedFiles = stdout.trim().split("\n").filter(Boolean).length;
-
-		const action =
-			event.reason === "before_new" ? "new session" : event.reason === "before_switch" ? "switch session" : "branch";
-
-		const choice = await ctx.ui.select(`You have ${changedFiles} uncommitted file(s). ${action} anyway?`, [
-			"Yes, proceed anyway",
-			"No, let me commit first",
-		]);
-
-		if (choice !== "Yes, proceed anyway") {
-			ctx.ui.notify("Commit your changes first", "warning");
-			return { cancel: true };
-		}
+	pi.on("session_before_branch", async (_event, ctx) => {
+		return checkDirtyRepo(pi, ctx, "branch");
 	});
 }