Consolidate session events: remove session_before_new/session_new, add reason field to switch events

- Remove session_before_new and session_new hook events
- Add reason: 'new' | 'resume' to session_before_switch and session_switch events
- Remove 'new' reason from custom tool onSession (use 'switch' for both /new and /resume)
- Rename reset() to newSession(options?) in AgentSession
- Add NewSessionOptions with optional parentSession for lineage tracking
- Rename branchedFrom to parentSession in SessionHeader
- Rename RPC reset command to new_session with optional parentSession
- Update example hooks to use new event structure
- Update documentation and changelog

Based on discussion in #293

packages/coding-agent/examples/hooks/confirm-destructive.ts

@@ -5,24 +5,26 @@
  * Demonstrates how to cancel session events using the before_* events.
  */
 
-import type { HookAPI, SessionMessageEntry } from "@mariozechner/pi-coding-agent";
+import type { HookAPI, SessionBeforeSwitchEvent, SessionMessageEntry } from "@mariozechner/pi-coding-agent";
 
 export default function (pi: HookAPI) {
-	pi.on("session_before_new", async (_event, ctx) => {
+	pi.on("session_before_switch", async (event: SessionBeforeSwitchEvent, ctx) => {
 		if (!ctx.hasUI) return;
 
-		const confirmed = await ctx.ui.confirm("Clear session?", "This will delete all messages in the current session.");
+		if (event.reason === "new") {
+			const confirmed = await ctx.ui.confirm(
+				"Clear session?",
+				"This will delete all messages in the current session.",
+			);
 
-		if (!confirmed) {
-			ctx.ui.notify("Clear cancelled", "info");
-			return { cancel: true };
+			if (!confirmed) {
+				ctx.ui.notify("Clear cancelled", "info");
+				return { cancel: true };
+			}
+			return;
 		}
-	});
 
-	pi.on("session_before_switch", async (_event, ctx) => {
-		if (!ctx.hasUI) return;
-
-		// Check if there are unsaved changes (messages since last assistant response)
+		// reason === "resume" - check if there are unsaved changes (messages since last assistant response)
 		const entries = ctx.sessionManager.getEntries();
 		const hasUnsavedWork = entries.some(
 			(e): e is SessionMessageEntry => e.type === "message" && e.message.role === "user",

packages/coding-agent/examples/hooks/dirty-repo-guard.ts

@@ -41,12 +41,9 @@ async function checkDirtyRepo(pi: HookAPI, ctx: HookContext, action: string): Pr
 }
 
 export default function (pi: HookAPI) {
-	pi.on("session_before_new", async (_event, ctx) => {
-		return checkDirtyRepo(pi, ctx, "new session");
-	});
-
-	pi.on("session_before_switch", async (_event, ctx) => {
-		return checkDirtyRepo(pi, ctx, "switch session");
+	pi.on("session_before_switch", async (event, ctx) => {
+		const action = event.reason === "new" ? "new session" : "switch session";
+		return checkDirtyRepo(pi, ctx, action);
 	});
 
 	pi.on("session_before_branch", async (_event, ctx) => {

packages/coding-agent/examples/hooks/status-line.ts

@@ -30,9 +30,11 @@ export default function (pi: HookAPI) {
 		ctx.ui.setStatus("status-demo", check + text);
 	});
 
-	pi.on("session_new", async (_event, ctx) => {
-		turnCount = 0;
-		const theme = ctx.ui.theme;
-		ctx.ui.setStatus("status-demo", theme.fg("dim", "Ready"));
+	pi.on("session_switch", async (event, ctx) => {
+		if (event.reason === "new") {
+			turnCount = 0;
+			const theme = ctx.ui.theme;
+			ctx.ui.setStatus("status-demo", theme.fg("dim", "Ready"));
+		}
 	});
 }