Custom tools with session lifecycle, examples for hooks and tools

- Custom tools: TypeScript modules that extend pi with new tools
  - Custom TUI rendering via renderCall/renderResult
  - User interaction via pi.ui (select, confirm, input, notify)
  - Session lifecycle via onSession callback for state reconstruction
  - Examples: todo.ts, question.ts, hello.ts

- Hook examples: permission-gate, git-checkpoint, protected-paths

- Session lifecycle centralized in AgentSession
  - Works across all modes (interactive, print, RPC)
  - Unified session event for hooks (replaces session_start/session_switch)

- Box component added to pi-tui

- Examples bundled in npm and binary releases

Fixes #190

packages/coding-agent/examples/hooks/README.md

@@ -0,0 +1,76 @@
+# Hooks Examples
+
+Example hooks for pi-coding-agent.
+
+## Examples
+
+### permission-gate.ts
+Prompts for confirmation before running dangerous bash commands (rm -rf, sudo, chmod 777, etc.).
+
+### git-checkpoint.ts
+Creates git stash checkpoints at each turn, allowing code restoration when branching.
+
+### protected-paths.ts
+Blocks writes to protected paths (.env, .git/, node_modules/).
+
+## Usage
+
+```bash
+# Test directly
+pi --hook examples/hooks/permission-gate.ts
+
+# Or copy to hooks directory for persistent use
+cp permission-gate.ts ~/.pi/agent/hooks/
+```
+
+## Writing Hooks
+
+See [docs/hooks.md](../../docs/hooks.md) for full documentation.
+
+### Key Points
+
+**Hook structure:**
+```typescript
+import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+
+export default function (pi: HookAPI) {
+  pi.on("session", async (event, ctx) => {
+    // event.reason: "start" | "switch" | "clear"
+    // ctx.ui, ctx.exec, ctx.cwd, ctx.sessionFile, ctx.hasUI
+  });
+
+  pi.on("tool_call", async (event, ctx) => {
+    // Can block tool execution
+    if (dangerous) {
+      return { block: true, reason: "Blocked" };
+    }
+    return undefined;
+  });
+
+  pi.on("tool_result", async (event, ctx) => {
+    // Can modify result
+    return { result: "modified result" };
+  });
+}
+```
+
+**Available events:**
+- `session` - startup, session switch, clear
+- `branch` - before branching (can skip conversation restore)
+- `agent_start` / `agent_end` - per user prompt
+- `turn_start` / `turn_end` - per LLM turn
+- `tool_call` - before tool execution (can block)
+- `tool_result` - after tool execution (can modify)
+
+**UI methods:**
+```typescript
+const choice = await ctx.ui.select("Title", ["Option A", "Option B"]);
+const confirmed = await ctx.ui.confirm("Title", "Are you sure?");
+const input = await ctx.ui.input("Title", "placeholder");
+ctx.ui.notify("Message", "info"); // or "warning", "error"
+```
+
+**Sending messages:**
+```typescript
+pi.send("Message to inject into conversation");
+```

packages/coding-agent/examples/hooks/git-checkpoint.ts

@@ -0,0 +1,48 @@
+/**
+ * Git Checkpoint Hook
+ *
+ * Creates git stash checkpoints at each turn so /branch can restore code state.
+ * When branching, offers to restore code to that point in history.
+ */
+
+import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+
+export default function (pi: HookAPI) {
+	const checkpoints = new Map<number, string>();
+
+	pi.on("turn_start", async (event, ctx) => {
+		// Create a git stash entry before LLM makes changes
+		const { stdout } = await ctx.exec("git", ["stash", "create"]);
+		const ref = stdout.trim();
+		if (ref) {
+			checkpoints.set(event.turnIndex, ref);
+		}
+	});
+
+	pi.on("branch", async (event, ctx) => {
+		const ref = checkpoints.get(event.targetTurnIndex);
+		if (!ref) return undefined;
+
+		if (!ctx.hasUI) {
+			// In non-interactive mode, don't restore automatically
+			return undefined;
+		}
+
+		const choice = await ctx.ui.select("Restore code state?", [
+			"Yes, restore code to that point",
+			"No, keep current code",
+		]);
+
+		if (choice?.startsWith("Yes")) {
+			await ctx.exec("git", ["stash", "apply", ref]);
+			ctx.ui.notify("Code restored to checkpoint", "info");
+		}
+
+		return undefined;
+	});
+
+	pi.on("agent_end", async () => {
+		// Clear checkpoints after agent completes
+		checkpoints.clear();
+	});
+}

packages/coding-agent/examples/hooks/permission-gate.ts

@@ -0,0 +1,38 @@
+/**
+ * Permission Gate Hook
+ *
+ * Prompts for confirmation before running potentially dangerous bash commands.
+ * Patterns checked: rm -rf, sudo, chmod/chown 777
+ */
+
+import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+
+export default function (pi: HookAPI) {
+	const dangerousPatterns = [
+		/\brm\s+(-rf?|--recursive)/i,
+		/\bsudo\b/i,
+		/\b(chmod|chown)\b.*777/i,
+	];
+
+	pi.on("tool_call", async (event, ctx) => {
+		if (event.toolName !== "bash") return undefined;
+
+		const command = event.input.command as string;
+		const isDangerous = dangerousPatterns.some((p) => p.test(command));
+
+		if (isDangerous) {
+			if (!ctx.hasUI) {
+				// In non-interactive mode, block by default
+				return { block: true, reason: "Dangerous command blocked (no UI for confirmation)" };
+			}
+
+			const choice = await ctx.ui.select(`⚠️ Dangerous command:\n\n  ${command}\n\nAllow?`, ["Yes", "No"]);
+
+			if (choice !== "Yes") {
+				return { block: true, reason: "Blocked by user" };
+			}
+		}
+
+		return undefined;
+	});
+}

packages/coding-agent/examples/hooks/protected-paths.ts

@@ -0,0 +1,30 @@
+/**
+ * Protected Paths Hook
+ *
+ * Blocks write and edit operations to protected paths.
+ * Useful for preventing accidental modifications to sensitive files.
+ */
+
+import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+
+export default function (pi: HookAPI) {
+	const protectedPaths = [".env", ".git/", "node_modules/"];
+
+	pi.on("tool_call", async (event, ctx) => {
+		if (event.toolName !== "write" && event.toolName !== "edit") {
+			return undefined;
+		}
+
+		const path = event.input.path as string;
+		const isProtected = protectedPaths.some((p) => path.includes(p));
+
+		if (isProtected) {
+			if (ctx.hasUI) {
+				ctx.ui.notify(`Blocked write to protected path: ${path}`, "warning");
+			}
+			return { block: true, reason: `Path "${path}" is protected` };
+		}
+
+		return undefined;
+	});
+}