@oh-my-pi/pi-coding-agent 12.7.6 → 12.8.0

package/docs/hooks.md

@@ -1,906 +0,0 @@
-> omp can create hooks. Ask it to build one for your use case.
-
-# Hooks
-
-Hooks are TypeScript modules that extend omp's behavior by subscribing to lifecycle events. They can intercept tool calls, prompt the user, modify results, inject messages, and more.
-
-**Key capabilities:**
-
-- **User interaction** - Hooks can prompt users via `ctx.ui` (select, confirm, input, notify)
-- **Custom UI components** - Full TUI components with keyboard input via `ctx.ui.custom()`
-- **Custom slash commands** - Register commands like `/mycommand` via `pi.registerCommand()`
-- **Event interception** - Block or modify tool calls, inject context, customize compaction
-- **Session persistence** - Store hook state that survives restarts via `pi.appendEntry()`
-
-**Example use cases:**
-
-- Permission gates (confirm before `rm -rf`, `sudo`, etc.)
-- Git checkpointing (stash at each turn, restore on `/branch`)
-- Path protection (block writes to `.env`, `node_modules/`)
-- External integrations (file watchers, webhooks, CI triggers)
-- Interactive tools (games, wizards, custom dialogs)
-
-See [examples/hooks/](../examples/hooks/) for working implementations, including a [snake game](../examples/hooks/snake.ts) demonstrating custom UI.
-
-## Quick Start
-
-Create `~/.omp/agent/hooks/pre/my-hook.ts` (or project-local `.omp/hooks/pre/`):
-
-```typescript
-import type { HookAPI } from "@oh-my-pi/pi-coding-agent/hooks";
-
-export default function (pi: HookAPI) {
-	pi.on("session_start", async (_event, ctx) => {
-		ctx.ui.notify("Hook loaded!", "info");
-	});
-
-	pi.on("tool_call", async (event, ctx) => {
-		if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
-			const ok = await ctx.ui.confirm("Dangerous!", "Allow rm -rf?");
-			if (!ok) return { block: true, reason: "Blocked by user" };
-		}
-	});
-}
-```
-
-Test with `--hook` flag:
-
-```bash
-omp --hook ./my-hook.ts
-```
-
-## Hook Locations
-
-Hooks are auto-discovered from config directories under `hooks/`:
-
-Native (`.omp`, `.pi`) and Claude (`.claude`) use subdirectory structure:
-
-- User-level:
-  - Native: `~/.omp/agent/hooks/{pre,post}/*.ts` (or `~/.pi/agent`)
-  - Claude: `~/.claude/hooks/{pre,post}/*.ts`
-- Project-level: `.omp/hooks/{pre,post}/*.ts` (or `.pi`, `.claude`)
-
-Codex (`.codex`) uses flat structure with filename prefixes (`pre-*.ts`, `post-*.ts`):
-
-- User-level: `~/.codex/hooks/*.ts`
-- Project-level: `.codex/hooks/*.ts`
-
-Hooks can also be loaded from plugin manifests or explicitly via `--hook`.
-
-## Available Imports
-
-| Package                           | Purpose                                              |
-| --------------------------------- | ---------------------------------------------------- |
-| `@oh-my-pi/pi-coding-agent/hooks` | Hook types (`HookAPI`, `HookContext`, events)        |
-| `@oh-my-pi/pi-coding-agent`       | Components (`BorderedLoader`), utilities, type re-exports |
-| `@oh-my-pi/pi-ai`                 | AI utilities (`complete`, message types)             |
-| `@oh-my-pi/pi-tui`                | TUI components (`CancellableLoader`, etc.)           |
-
-Node.js built-ins (`node:fs`, `node:path`, etc.) are also available.
-
-## Writing a Hook
-
-A hook exports a default function that receives `HookAPI`:
-
-```typescript
-import type { HookAPI } from "@oh-my-pi/pi-coding-agent/hooks";
-
-export default function (pi: HookAPI) {
-	// Subscribe to events
-	pi.on("event_name", async (event, ctx) => {
-		// Handle event
-	});
-}
-```
-
-Hooks are loaded via native Bun import, so TypeScript works without compilation.
-
-## Events
-
-### Lifecycle Overview
-
-```
-omp starts
-  │
-  └─► session_start
-      │
-      ▼
-user sends prompt ─────────────────────────────────────────┐
-  │                                                        │
-  ├─► before_agent_start (can inject message)              │
-  ├─► agent_start                                          │
-  │                                                        │
-  │   ┌─── turn (repeats while LLM calls tools) ───┐       │
-  │   │                                            │       │
-  │   ├─► turn_start                               │       │
-  │   ├─► context (can modify messages)            │       │
-  │   │                                            │       │
-  │   │   LLM responds, may call tools:            │       │
-  │   │     ├─► tool_call (can block)              │       │
-  │   │     │   tool executes                      │       │
-  │   │     └─► tool_result (can modify)           │       │
-  │   │                                            │       │
-  │   └─► turn_end                                 │       │
-  │                                                        │
-  └─► agent_end                                            │
-                                                           │
-user sends another prompt ◄────────────────────────────────┘
-
-/new, /resume, or /fork
-  ├─► session_before_switch (can cancel, has reason: "new" | "resume" | "fork")
-  └─► session_switch (has reason: "new" | "resume" | "fork")
-
-/branch
-  ├─► session_before_branch (can cancel)
-  └─► session_branch
-
-/compact or auto-compaction
-  ├─► session_before_compact (can cancel or customize)
-  ├─► session.compacting (customize prompt/context)
-  └─► session_compact
-
-/tree navigation
-  ├─► session_before_tree (can cancel or customize)
-  └─► session_tree
-
-exit (Ctrl+C, Ctrl+D)
-  └─► session_shutdown
-```
-
-### Session Events
-
-#### session_start
-
-Fired on initial session load.
-
-```typescript
-pi.on("session_start", async (_event, ctx) => {
-	ctx.ui.notify(`Session: ${ctx.sessionManager.getSessionFile() ?? "ephemeral"}`, "info");
-});
-```
-
-#### session_before_switch / session_switch
-
-Fired when starting a new session (`/new`), resuming (`/resume`), or forking (`/fork`).
-
-```typescript
-pi.on("session_before_switch", async (event, ctx) => {
-	// event.reason - "new" (starting fresh), "resume" (switching to existing), or "fork" (branch switch)
-	// event.targetSessionFile - session we're switching to (only for "resume")
-
-	if (event.reason === "new") {
-		const ok = await ctx.ui.confirm("Clear?", "Delete all messages?");
-		if (!ok) return { cancel: true };
-	}
-
-	return { cancel: true }; // Cancel the switch/new
-});
-
-pi.on("session_switch", async (event, ctx) => {
-	// event.reason - "new", "resume", or "fork"
-	// event.previousSessionFile - session we came from
-});
-```
-
-#### session_before_branch / session_branch
-
-Fired when branching via `/branch`.
-
-```typescript
-pi.on("session_before_branch", async (event, ctx) => {
-	// event.entryId - ID of the entry being branched from
-
-	return { cancel: true }; // Cancel branch
-	// OR
-	return { skipConversationRestore: true }; // Branch but don't rewind messages
-});
-
-pi.on("session_branch", async (event, ctx) => {
-	// event.previousSessionFile - previous session file
-});
-```
-
-The `skipConversationRestore` option is useful for checkpoint hooks that restore code state separately.
-
-#### session_before_compact / session.compacting / session_compact
-
-Fired on compaction. See [compaction.md](compaction.md) for details.
-
-```typescript
-pi.on("session_before_compact", async (event, ctx) => {
-	const { preparation, branchEntries, customInstructions, signal } = event;
-
-	// Cancel:
-	return { cancel: true };
-
-	// Custom summary:
-	return {
-		compaction: {
-			summary: "...",
-			firstKeptEntryId: preparation.firstKeptEntryId,
-			tokensBefore: preparation.tokensBefore,
-		},
-	};
-});
-
-```
-
-#### session.compacting
-
-Fired after preparation but before the default summarizer runs. Use it to customize the prompt or add context
-when you are not returning a full compaction result from `session_before_compact`.
-
-```typescript
-pi.on("session.compacting", async (event, ctx) => {
-	// event.sessionId
-	// event.messages - messages about to be summarized
-
-	return {
-		context: ["Additional context line"],
-		prompt: "Custom compaction prompt...",
-		preserveData: { source: "my-hook" },
-	};
-});
-```
-
-```typescript
-pi.on("session_compact", async (event, ctx) => {
-	// event.compactionEntry - the saved compaction
-	// event.fromExtension - whether hook provided it
-});
-```
-
-#### session_before_tree / session_tree
-
-Fired on `/tree` navigation. Always fires regardless of user's summarization choice. See [compaction.md](compaction.md) for details.
-
-```typescript
-pi.on("session_before_tree", async (event, ctx) => {
-	const { preparation, signal } = event;
-	// preparation.targetId, oldLeafId, commonAncestorId, entriesToSummarize
-	// preparation.userWantsSummary - whether user chose to summarize
-
-	return { cancel: true };
-	// OR provide custom summary (only used if userWantsSummary is true):
-	return { summary: { summary: "...", details: {} } };
-});
-
-pi.on("session_tree", async (event, ctx) => {
-	// event.newLeafId, oldLeafId, summaryEntry, fromExtension
-});
-```
-
-#### session_shutdown
-
-Fired on exit (Ctrl+C, Ctrl+D, SIGTERM).
-
-```typescript
-pi.on("session_shutdown", async (_event, ctx) => {
-	// Cleanup, save state, etc.
-});
-```
-
-### Agent Events
-
-#### before_agent_start
-
-Fired after user submits prompt, before agent loop. Can inject a persistent message.
-
-```typescript
-pi.on("before_agent_start", async (event, ctx) => {
-	// event.prompt - user's prompt text
-	// event.images - attached images (if any)
-
-	return {
-		message: {
-			customType: "my-hook",
-			content: "Additional context for the LLM",
-			display: true, // Show in TUI
-		},
-	};
-});
-```
-
-The injected message is persisted as `CustomMessageEntry` and sent to the LLM.
-
-#### agent_start / agent_end
-
-Fired once per user prompt.
-
-```typescript
-pi.on("agent_start", async (_event, ctx) => {});
-
-pi.on("agent_end", async (event, ctx) => {
-	// event.messages - messages from this prompt
-});
-```
-
-#### turn_start / turn_end
-
-Fired for each turn (one LLM response + tool calls).
-
-```typescript
-pi.on("turn_start", async (event, ctx) => {
-	// event.turnIndex, event.timestamp
-});
-
-pi.on("turn_end", async (event, ctx) => {
-	// event.turnIndex
-	// event.message - assistant's response
-	// event.toolResults - tool results from this turn
-});
-```
-
-#### context
-
-Fired before each LLM call. Modify messages non-destructively (session unchanged).
-
-```typescript
-pi.on("context", async (event, ctx) => {
-	// event.messages - deep copy, safe to modify
-
-	// Filter or transform messages
-	const filtered = event.messages.filter((m) => !shouldPrune(m));
-	return { messages: filtered };
-});
-```
-
-### Tool Events
-
-#### tool_call
-
-Fired before tool executes. **Can block.**
-
-```typescript
-pi.on("tool_call", async (event, ctx) => {
-	// event.toolName - "bash", "read", "write", "edit", etc.
-	// event.toolCallId
-	// event.input - tool parameters
-
-	if (shouldBlock(event)) {
-		return { block: true, reason: "Not allowed" };
-	}
-});
-```
-
-Tool inputs (common built-ins):
-
-- `bash`: `{ command, timeout?, cwd?, head?, tail? }`
-- `read`: `{ path, offset?, limit?, lines? }`
-- `write`: `{ path, content }`
-- `edit` (replace mode): `{ path, old_text, new_text, all? }`
-- `edit` (patch mode): `{ path, op?, rename?, diff? }`
-- `find`: `{ pattern, hidden?, limit? }`
-- `grep`: `{ pattern, path?, glob?, type?, i?, pre?, post?, multiline?, limit?, offset? }`
-
-The edit input shape depends on the current edit variant (replace vs patch). Inspect `event.input` to
-see which schema is active.
-
-Other tools (ask, browser, task, todo_write, fetch, web_search, python, notebook, lsp, ssh, calc) use
-their own schemas; inspect the tool prompt or `src/tools/*.ts` for details.
-
-#### tool_result
-
-Fired after tool executes (including errors). **Can modify result.**
-
-Check `event.isError` to distinguish successful executions from failures.
-
-```typescript
-pi.on("tool_result", async (event, ctx) => {
-  // event.toolName, event.toolCallId, event.input
-  // event.content - array of TextContent | ImageContent
-  // event.details - tool-specific (see below)
-  // event.isError - true if the tool threw an error
-
-  if (event.isError) {
-    // Handle error case
-  }
-
-  // Modify result:
-  return { content: [...], details: {...}, isError: false };
-});
-```
-
-Use `event.toolName` to narrow tool-specific details:
-
-```typescript
-pi.on("tool_result", async (event, ctx) => {
-	if (event.toolName === "bash") {
-		// event.details is BashToolDetails | undefined
-		const artifactId = event.details?.meta?.truncation?.artifactId;
-		if (artifactId) {
-			// Full output is stored under the artifact ID
-		}
-	}
-});
-```
-
-## HookContext
-
-Every handler receives `ctx: HookContext`:
-
-### ctx.ui
-
-UI methods for user interaction. Hooks can prompt users and even render custom TUI components.
-
-**Built-in dialogs:**
-
-```typescript
-// Select from options
-const choice = await ctx.ui.select("Pick one:", ["A", "B", "C"]);
-// Returns selected string or undefined if cancelled
-
-// Confirm dialog
-const ok = await ctx.ui.confirm("Delete?", "This cannot be undone");
-// Returns true or false
-
-// Text input (single line)
-const name = await ctx.ui.input("Name:", "placeholder");
-// Returns string or undefined if cancelled
-
-// Multi-line editor (with Ctrl+G for external editor)
-const text = await ctx.ui.editor("Edit prompt:", "prefilled text");
-// Returns edited text or undefined if cancelled (Escape)
-// Ctrl+Enter to submit, Ctrl+G to open $VISUAL or $EDITOR
-
-// Notification (non-blocking)
-ctx.ui.notify("Done!", "info"); // "info" | "warning" | "error"
-
-// Set status text in footer (persistent until cleared)
-ctx.ui.setStatus("my-hook", "Processing 5/10..."); // Set status
-ctx.ui.setStatus("my-hook", undefined); // Clear status
-
-// Set the core input editor text (pre-fill prompts, generated content)
-ctx.ui.setEditorText("Generated prompt text here...");
-
-// Get current editor text
-const currentText = ctx.ui.getEditorText();
-```
-
-**Status text notes:**
-
-- Multiple hooks can set their own status using unique keys
-- Statuses are displayed on a single line in the footer, sorted alphabetically by key
-- Text is sanitized (newlines/tabs replaced with spaces) and truncated to terminal width
-- Use `ctx.ui.theme` to style status text with theme colors (see below)
-
-**Styling with theme colors:**
-
-Use `ctx.ui.theme` to apply consistent colors that respect the user's theme:
-
-```typescript
-const theme = ctx.ui.theme;
-
-// Foreground colors
-ctx.ui.setStatus("my-hook", theme.fg("success", "✓") + theme.fg("dim", " Ready"));
-ctx.ui.setStatus("my-hook", theme.fg("error", "✗") + theme.fg("dim", " Failed"));
-ctx.ui.setStatus("my-hook", theme.fg("accent", "●") + theme.fg("dim", " Working..."));
-
-// Available fg colors: accent, success, error, warning, muted, dim, text, and more
-// See docs/theme.md for the full list of theme colors
-```
-
-See [examples/hooks/status-line.ts](../examples/hooks/status-line.ts) for a complete example.
-
-**Custom components:**
-
-Show a custom TUI component with keyboard focus:
-
-```typescript
-import { BorderedLoader } from "@oh-my-pi/pi-coding-agent";
-
-const result = await ctx.ui.custom((tui, theme, done) => {
-	const loader = new BorderedLoader(tui, theme, "Working...");
-	loader.onAbort = () => done(null);
-
-	doWork(loader.signal)
-		.then(done)
-		.catch(() => done(null));
-
-	return loader;
-});
-```
-
-Your component can:
-
-- Implement `handleInput(data: string)` to receive keyboard input
-- Implement `render(width: number): string[]` to render lines
-- Implement `invalidate()` to clear cached render
-- Implement `dispose()` for cleanup when closed
-- Call `tui.requestRender()` to trigger re-render
-- Call `done(result)` when done to restore normal UI
-
-See [examples/hooks/qna.ts](../examples/hooks/qna.ts) for a loader pattern and [examples/hooks/snake.ts](../examples/hooks/snake.ts) for a game. See [tui.md](tui.md) for the full component API.
-
-### ctx.hasUI
-
-`false` in print mode (`-p`) and JSON print mode. RPC mode provides UI via the host, so `ctx.hasUI` is true.
-Always check before using `ctx.ui`:
-
-```typescript
-if (ctx.hasUI) {
-  const choice = await ctx.ui.select(...);
-} else {
-  // Default behavior
-}
-```
-
-### ctx.cwd
-
-Current working directory.
-
-### ctx.sessionManager
-
-Read-only access to session state. See `ReadonlySessionManager` in [`src/session/session-manager.ts`](../src/session/session-manager.ts).
-
-```typescript
-// Session info
-ctx.sessionManager.getCwd(); // Working directory
-ctx.sessionManager.getSessionDir(); // Session directory (~/.omp/agent/sessions)
-ctx.sessionManager.getSessionId(); // Current session ID
-ctx.sessionManager.getSessionFile(); // Session file path (undefined with --no-session)
-
-// Entries
-ctx.sessionManager.getEntries(); // All entries (excludes header)
-ctx.sessionManager.getHeader(); // Session header entry
-ctx.sessionManager.getEntry(id); // Specific entry by ID
-ctx.sessionManager.getLabel(id); // Entry label (if any)
-
-// Tree navigation
-ctx.sessionManager.getBranch(); // Current branch (root to leaf)
-ctx.sessionManager.getBranch(leafId); // Specific branch
-ctx.sessionManager.getTree(); // Full tree structure
-ctx.sessionManager.getLeafId(); // Current leaf entry ID
-ctx.sessionManager.getLeafEntry(); // Current leaf entry
-```
-
-Use `pi.sendMessage()` or `pi.appendEntry()` for writes.
-
-### ctx.modelRegistry
-
-Access to models and API keys:
-
-```typescript
-// Get API key for a model
-const apiKey = await ctx.modelRegistry.getApiKey(model);
-
-// Get available models
-const models = ctx.modelRegistry.getAvailable();
-```
-
-### ctx.model
-
-Current model, or `undefined` if none selected yet. Use for LLM calls in hooks:
-
-```typescript
-if (ctx.model) {
-	const apiKey = await ctx.modelRegistry.getApiKey(ctx.model);
-	// Use with @oh-my-pi/pi-ai complete()
-}
-```
-
-### ctx.isIdle()
-
-Returns `true` if the agent is not currently streaming:
-
-```typescript
-if (ctx.isIdle()) {
-	// Agent is not processing
-}
-```
-
-### ctx.abort()
-
-Abort the current agent operation (fire-and-forget, does not wait):
-
-```typescript
-ctx.abort();
-```
-
-### ctx.hasQueuedMessages()
-
-Check if there are messages queued (user typed while agent was streaming):
-
-```typescript
-if (ctx.hasQueuedMessages()) {
-	// Skip interactive prompt, let queued message take over
-	return;
-}
-```
-
-## HookCommandContext (Slash Commands Only)
-
-Slash command handlers receive `HookCommandContext`, which extends `HookContext` with session control methods. These methods are only safe in user-initiated commands because they can cause deadlocks if called from event handlers (which run inside the agent loop).
-
-### ctx.waitForIdle()
-
-Wait for the agent to finish streaming:
-
-```typescript
-await ctx.waitForIdle();
-// Agent is now idle
-```
-
-### ctx.newSession(options?)
-
-Create a new session, optionally with initialization:
-
-```typescript
-const result = await ctx.newSession({
-	parentSession: ctx.sessionManager.getSessionFile(), // Track lineage
-	setup: async (sm) => {
-		// Initialize the new session
-		sm.appendMessage({
-			role: "user",
-			content: [{ type: "text", text: "Context from previous session..." }],
-			timestamp: Date.now(),
-		});
-	},
-});
-
-if (result.cancelled) {
-	// A hook cancelled the new session
-}
-```
-
-### ctx.branch(entryId)
-
-Branch from a specific entry, creating a new session file:
-
-```typescript
-const result = await ctx.branch("entry-id-123");
-if (!result.cancelled) {
-	// Now in the branched session
-}
-```
-
-### ctx.navigateTree(targetId, options?)
-
-Navigate to a different point in the session tree:
-
-```typescript
-const result = await ctx.navigateTree("entry-id-456", {
-	summarize: true, // Summarize the abandoned branch
-});
-```
-
-## HookAPI Methods
-
-### pi.on(event, handler)
-
-Subscribe to events. See [Events](#events) for all event types.
-
-### pi.sendMessage(message, options?)
-
-Inject a message into the session. Creates a `CustomMessageEntry` that participates in the LLM context.
-
-```typescript
-pi.sendMessage(
-	{
-		customType: "my-hook",      // Your hook's identifier
-		content: "Message text",    // string or (TextContent | ImageContent)[]
-		display: true,              // Show in TUI
-		details: { ... },           // Optional metadata (not sent to LLM)
-	},
-	{ triggerTurn: true },        // Trigger a new LLM response if idle
-);
-```
-
-**Storage and timing:**
-
-- The message is appended to the session file immediately as a `CustomMessageEntry`
-- If the agent is currently streaming, the message is queued and appended after the current turn
-- If `options.triggerTurn` is true and the agent is idle, a new agent loop starts
-- `options.deliverAs` chooses how to enqueue the message (`"steer"` or `"followUp"`)
-
-**LLM context:**
-
-- `CustomMessageEntry` is converted to a user message when building context for the LLM
-- Only `content` is sent to the LLM; `details` is for rendering/state only
-
-**TUI display:**
-
-- If `display: true`, the message appears in the chat with purple styling (customMessageBg, customMessageText, customMessageLabel theme colors)
-- If `display: false`, the message is hidden from the TUI but still sent to the LLM
-- Use `pi.registerMessageRenderer()` to customize how your messages render (see below)
-
-### pi.appendEntry(customType, data?)
-
-Persist hook state. Creates `CustomEntry` (does NOT participate in LLM context).
-
-```typescript
-// Save state
-pi.appendEntry("my-hook-state", { count: 42 });
-
-// Restore on reload
-pi.on("session_start", async (_event, ctx) => {
-	for (const entry of ctx.sessionManager.getEntries()) {
-		if (entry.type === "custom" && entry.customType === "my-hook-state") {
-			// Reconstruct from entry.data
-		}
-	}
-});
-```
-
-### pi.registerCommand(name, options)
-
-Register a custom slash command:
-
-```typescript
-pi.registerCommand("stats", {
-	description: "Show session statistics",
-	handler: async (args, ctx) => {
-		// args = everything after /stats
-		const count = ctx.sessionManager.getEntries().length;
-		ctx.ui.notify(`${count} entries`, "info");
-	},
-});
-```
-
-For long-running commands (e.g., LLM calls), use `ctx.ui.custom()` with a loader. See [examples/hooks/qna.ts](../examples/hooks/qna.ts).
-
-To trigger the LLM after a command, call `pi.sendMessage(..., { triggerTurn: true })`.
-
-### pi.registerMessageRenderer(customType, renderer)
-
-Register a custom TUI renderer for `CustomMessageEntry` messages with your `customType`. Without a custom renderer, messages display with default purple styling showing the content as-is.
-
-```typescript
-import { Text } from "@oh-my-pi/pi-tui";
-
-pi.registerMessageRenderer("my-hook", (message, options, theme) => {
-	// message.content - the message content (string or content array)
-	// message.details - your custom metadata
-	// options.expanded - true if user pressed Ctrl+O
-
-	const prefix = theme.fg("accent", `[${message.details?.label ?? "INFO"}] `);
-	const text =
-		typeof message.content === "string"
-			? message.content
-			: message.content.map((c) => (c.type === "text" ? c.text : "[image]")).join("");
-
-	return new Text(prefix + theme.fg("text", text), 0, 0);
-});
-```
-
-**Renderer signature:**
-
-```typescript
-type HookMessageRenderer = (
-	message: HookMessage,
-	options: { expanded: boolean },
-	theme: Theme
-) => Component | undefined;
-```
-
-Return `undefined` to use default rendering. The returned component is wrapped in a styled Box by the TUI. See [tui.md](tui.md) for component details.
-
-### pi.exec(command, args, options?)
-
-Execute a shell command:
-
-```typescript
-const result = await pi.exec("git", ["status"], {
-	signal, // AbortSignal
-	timeout, // Milliseconds
-});
-
-// result.stdout, result.stderr, result.code, result.killed
-```
-
-### pi.logger / pi.typebox / pi.pi
-
-- `pi.logger` is the shared logger (avoid `console.*` to keep the TUI clean)
-- `pi.typebox` exposes `@sinclair/typebox` for schema definitions
-- `pi.pi` exposes `@oh-my-pi/pi-coding-agent` exports (components, helpers)
-
-## Examples
-
-### Permission Gate
-
-```typescript
-import type { HookAPI } from "@oh-my-pi/pi-coding-agent/hooks";
-
-export default function (pi: HookAPI) {
-	const dangerous = [/\brm\s+(-rf?|--recursive)/i, /\bsudo\b/i];
-
-	pi.on("tool_call", async (event, ctx) => {
-		if (event.toolName !== "bash") return;
-
-		const cmd = event.input.command as string;
-		if (dangerous.some((p) => p.test(cmd))) {
-			if (!ctx.hasUI) {
-				return { block: true, reason: "Dangerous (no UI)" };
-			}
-			const ok = await ctx.ui.confirm("Dangerous!", `Allow: ${cmd}?`);
-			if (!ok) return { block: true, reason: "Blocked by user" };
-		}
-	});
-}
-```
-
-### Protected Paths
-
-```typescript
-import type { HookAPI } from "@oh-my-pi/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;
-
-		const path = event.input.path as string;
-		if (protectedPaths.some((p) => path.includes(p))) {
-			ctx.ui.notify(`Blocked: ${path}`, "warning");
-			return { block: true, reason: `Protected: ${path}` };
-		}
-	});
-}
-```
-
-### Git Checkpoint
-
-```typescript
-import type { HookAPI } from "@oh-my-pi/pi-coding-agent/hooks";
-
-export default function (pi: HookAPI) {
-	const checkpoints = new Map<string, string>();
-	let currentEntryId: string | undefined;
-
-	pi.on("tool_result", async (_event, ctx) => {
-		const leaf = ctx.sessionManager.getLeafEntry();
-		if (leaf) currentEntryId = leaf.id;
-	});
-
-	pi.on("turn_start", async () => {
-		const { stdout } = await pi.exec("git", ["stash", "create"]);
-		if (stdout.trim() && currentEntryId) {
-			checkpoints.set(currentEntryId, stdout.trim());
-		}
-	});
-
-	pi.on("session_before_branch", async (event, ctx) => {
-		const ref = checkpoints.get(event.entryId);
-		if (!ref || !ctx.hasUI) return;
-
-		const ok = await ctx.ui.confirm("Restore?", "Restore code to checkpoint?");
-		if (ok) {
-			await pi.exec("git", ["stash", "apply", ref]);
-			ctx.ui.notify("Code restored", "info");
-		}
-	});
-
-	pi.on("agent_end", () => checkpoints.clear());
-}
-```
-
-### Custom Command
-
-See [examples/hooks/snake.ts](../examples/hooks/snake.ts) for a complete example with `registerCommand()`, `ui.custom()`, and session persistence.
-
-## Mode Behavior
-
-| Mode            | UI Methods                 | Notes                                      |
-| --------------- | -------------------------- | ------------------------------------------ |
-| Interactive     | Full TUI                   | Normal operation                           |
-| RPC             | UI via RPC                 | Host handles UI, `ctx.hasUI` is true       |
-| Print (`-p`)    | No-op (returns undefined/false) | Hooks run but can't prompt (`ctx.hasUI`=false) |
-
-In print mode (including JSON output), `select()` returns `undefined`, `confirm()` returns `false`, `input()` returns
-`undefined`, `getEditorText()` returns `""`, and `setEditorText()`/`setStatus()` are no-ops. Design hooks to handle this
-by checking `ctx.hasUI`.
-
-## Error Handling
-
-- Hook errors are logged, agent continues
-- `tool_call` errors block the tool (fail-safe)
-- Errors display in UI with hook path and message
-- If a hook hangs, use Ctrl+C to abort
-
-## Debugging
-
-1. Open VS Code in hooks directory
-2. Open JavaScript Debug Terminal (Ctrl+Shift+P → "JavaScript Debug Terminal")
-3. Set breakpoints
-4. Run `omp --hook ./my-hook.ts`