Add setEditorText/getEditorText to hook UI context, improve custom() API

- Add setEditorText() and getEditorText() to HookUIContext for prompt generator pattern
- custom() now accepts async factories for fire-and-forget work
- Add CancellableLoader component to tui package
- Add BorderedLoader component for hooks with cancel UI
- Export HookAPI, HookContext, HookFactory from main package
- Update all examples to import from packages instead of relative paths
- Update hooks.md and custom-tools.md documentation

fixes #350

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

@@ -2,97 +2,53 @@
 
 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/).
-
-### file-trigger.ts
-Watches a trigger file and injects its contents into the conversation. Useful for external systems (CI, file watchers, webhooks) to send messages to the agent.
-
-### confirm-destructive.ts
-Prompts for confirmation before destructive session actions (clear, switch, branch). Demonstrates how to cancel `before_*` session events.
-
-### dirty-repo-guard.ts
-Prevents session changes when there are uncommitted git changes. Blocks clear/switch/branch until you commit.
-
-### auto-commit-on-exit.ts
-Automatically commits changes when the agent exits (shutdown event). Uses the last assistant message to generate a commit message.
-
-### custom-compaction.ts
-Custom context compaction that summarizes the entire conversation instead of keeping recent turns. Uses the `before_compact` hook event to intercept compaction and generate a comprehensive summary using `complete()` from the AI package. Useful when you want maximum context window space at the cost of losing exact conversation history.
-
 ## Usage
 
 ```bash
-# Test directly
+# Load a hook with --hook flag
 pi --hook examples/hooks/permission-gate.ts
 
-# Or copy to hooks directory for persistent use
+# Or copy to hooks directory for auto-discovery
 cp permission-gate.ts ~/.pi/agent/hooks/
 ```
 
+## Examples
+
+| Hook | Description |
+|------|-------------|
+| `permission-gate.ts` | Prompts for confirmation before dangerous bash commands (rm -rf, sudo, etc.) |
+| `git-checkpoint.ts` | Creates git stash checkpoints at each turn for code restoration on branch |
+| `protected-paths.ts` | Blocks writes to protected paths (.env, .git/, node_modules/) |
+| `file-trigger.ts` | Watches a trigger file and injects contents into conversation |
+| `confirm-destructive.ts` | Confirms before destructive session actions (clear, switch, branch) |
+| `dirty-repo-guard.ts` | Prevents session changes with uncommitted git changes |
+| `auto-commit-on-exit.ts` | Auto-commits on exit using last assistant message for commit message |
+| `custom-compaction.ts` | Custom compaction that summarizes entire conversation |
+| `qna.ts` | Extracts questions from last response into editor via `ctx.ui.setEditorText()` |
+| `snake.ts` | Snake game with custom UI, keyboard handling, and session persistence |
+
 ## 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" | "before_switch" | "switch" | "before_clear" | "clear" |
-    //               "before_branch" | "branch" | "shutdown"
-    // event.targetTurnIndex: number (only for before_branch/branch)
-    // ctx.ui, ctx.exec, ctx.cwd, ctx.sessionFile, ctx.hasUI
-
-    // Cancel before_* actions:
-    if (event.reason === "before_clear") {
-      return { cancel: true };
-    }
-    return undefined;
-  });
-
+  // Subscribe to events
   pi.on("tool_call", async (event, ctx) => {
-    // Can block tool execution
-    if (dangerous) {
-      return { block: true, reason: "Blocked" };
+    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" };
     }
-    return undefined;
   });
 
-  pi.on("tool_result", async (event, ctx) => {
-    // Can modify result
-    return { result: "modified result" };
+  // Register custom commands
+  pi.registerCommand("hello", {
+    description: "Say hello",
+    handler: async (args, ctx) => {
+      ctx.ui.notify("Hello!", "info");
+    },
   });
 }
 ```
-
-**Available events:**
-- `session` - lifecycle events with before/after variants (can cancel before_* actions)
-- `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/auto-commit-on-exit.ts

@@ -5,7 +5,7 @@
  * Uses the last assistant message to generate a commit message.
  */
 
-import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+import type { HookAPI } from "@mariozechner/pi-coding-agent";
 
 export default function (pi: HookAPI) {
 	pi.on("session_shutdown", async (_event, ctx) => {

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

@@ -5,8 +5,7 @@
  * Demonstrates how to cancel session events using the before_* events.
  */
 
-import type { SessionMessageEntry } from "@mariozechner/pi-coding-agent";
-import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+import type { HookAPI, SessionMessageEntry } from "@mariozechner/pi-coding-agent";
 
 export default function (pi: HookAPI) {
 	pi.on("session_before_new", async (_event, ctx) => {

packages/coding-agent/examples/hooks/custom-compaction.ts

@@ -14,8 +14,8 @@
  */
 
 import { complete, getModel } from "@mariozechner/pi-ai";
+import type { HookAPI } from "@mariozechner/pi-coding-agent";
 import { convertToLlm, serializeConversation } from "@mariozechner/pi-coding-agent";
-import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
 
 export default function (pi: HookAPI) {
 	pi.on("session_before_compact", async (event, ctx) => {

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

@@ -5,7 +5,7 @@
  * Useful to ensure work is committed before switching context.
  */
 
-import type { HookAPI, HookContext } from "@mariozechner/pi-coding-agent/hooks";
+import type { HookAPI, HookContext } from "@mariozechner/pi-coding-agent";
 
 async function checkDirtyRepo(pi: HookAPI, ctx: HookContext, action: string): Promise<{ cancel: boolean } | undefined> {
 	// Check for uncommitted changes

packages/coding-agent/examples/hooks/file-trigger.ts

@@ -9,7 +9,7 @@
  */
 
 import * as fs from "node:fs";
-import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+import type { HookAPI } from "@mariozechner/pi-coding-agent";
 
 export default function (pi: HookAPI) {
 	pi.on("session_start", async (_event, ctx) => {

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

@@ -5,7 +5,7 @@
  * When branching, offers to restore code to that point in history.
  */
 
-import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+import type { HookAPI } from "@mariozechner/pi-coding-agent";
 
 export default function (pi: HookAPI) {
 	const checkpoints = new Map<string, string>();

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

@@ -5,7 +5,7 @@
  * Patterns checked: rm -rf, sudo, chmod/chown 777
  */
 
-import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+import type { HookAPI } from "@mariozechner/pi-coding-agent";
 
 export default function (pi: HookAPI) {
 	const dangerousPatterns = [/\brm\s+(-rf?|--recursive)/i, /\bsudo\b/i, /\b(chmod|chown)\b.*777/i];

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

@@ -5,7 +5,7 @@
  * Useful for preventing accidental modifications to sensitive files.
  */
 
-import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+import type { HookAPI } from "@mariozechner/pi-coding-agent";
 
 export default function (pi: HookAPI) {
 	const protectedPaths = [".env", ".git/", "node_modules/"];

packages/coding-agent/examples/hooks/qna.ts

@@ -0,0 +1,119 @@
+/**
+ * Q&A extraction hook - extracts questions from assistant responses
+ *
+ * Demonstrates the "prompt generator" pattern:
+ * 1. /qna command gets the last assistant message
+ * 2. Shows a spinner while extracting (hides editor)
+ * 3. Loads the result into the editor for user to fill in answers
+ */
+
+import { complete, type UserMessage } from "@mariozechner/pi-ai";
+import type { HookAPI } from "@mariozechner/pi-coding-agent";
+import { BorderedLoader } from "@mariozechner/pi-coding-agent";
+
+const SYSTEM_PROMPT = `You are a question extractor. Given text from a conversation, extract any questions that need answering and format them for the user to fill in.
+
+Output format:
+- List each question on its own line, prefixed with "Q: "
+- After each question, add a blank line for the answer prefixed with "A: "
+- If no questions are found, output "No questions found in the last message."
+
+Example output:
+Q: What is your preferred database?
+A: 
+
+Q: Should we use TypeScript or JavaScript?
+A: 
+
+Keep questions in the order they appeared. Be concise.`;
+
+export default function (pi: HookAPI) {
+	pi.registerCommand("qna", {
+		description: "Extract questions from last assistant message into editor",
+		handler: async (_args, ctx) => {
+			if (!ctx.hasUI) {
+				ctx.ui.notify("qna requires interactive mode", "error");
+				return;
+			}
+
+			if (!ctx.model) {
+				ctx.ui.notify("No model selected", "error");
+				return;
+			}
+
+			// Find the last assistant message on the current branch
+			const branch = ctx.sessionManager.getBranch();
+			let lastAssistantText: string | undefined;
+
+			for (let i = branch.length - 1; i >= 0; i--) {
+				const entry = branch[i];
+				if (entry.type === "message") {
+					const msg = entry.message;
+					if ("role" in msg && msg.role === "assistant") {
+						if (msg.stopReason !== "stop") {
+							ctx.ui.notify(`Last assistant message incomplete (${msg.stopReason})`, "error");
+							return;
+						}
+						const textParts = msg.content
+							.filter((c): c is { type: "text"; text: string } => c.type === "text")
+							.map((c) => c.text);
+						if (textParts.length > 0) {
+							lastAssistantText = textParts.join("\n");
+							break;
+						}
+					}
+				}
+			}
+
+			if (!lastAssistantText) {
+				ctx.ui.notify("No assistant messages found", "error");
+				return;
+			}
+
+			// Run extraction with loader UI
+			const result = await ctx.ui.custom<string | null>((tui, theme, done) => {
+				const loader = new BorderedLoader(tui, theme, `Extracting questions using ${ctx.model!.id}...`);
+				loader.onAbort = () => done(null);
+
+				// Do the work
+				const doExtract = async () => {
+					const apiKey = await ctx.modelRegistry.getApiKey(ctx.model!);
+					const userMessage: UserMessage = {
+						role: "user",
+						content: [{ type: "text", text: lastAssistantText! }],
+						timestamp: Date.now(),
+					};
+
+					const response = await complete(
+						ctx.model!,
+						{ systemPrompt: SYSTEM_PROMPT, messages: [userMessage] },
+						{ apiKey, signal: loader.signal },
+					);
+
+					if (response.stopReason === "aborted") {
+						return null;
+					}
+
+					return response.content
+						.filter((c): c is { type: "text"; text: string } => c.type === "text")
+						.map((c) => c.text)
+						.join("\n");
+				};
+
+				doExtract()
+					.then(done)
+					.catch(() => done(null));
+
+				return loader;
+			});
+
+			if (result === null) {
+				ctx.ui.notify("Cancelled", "info");
+				return;
+			}
+
+			ctx.ui.setEditorText(result);
+			ctx.ui.notify("Questions loaded. Edit and submit when ready.", "info");
+		},
+	});
+}

packages/coding-agent/examples/hooks/snake.ts

@@ -2,8 +2,8 @@
  * Snake game hook - play snake with /snake command
  */
 
+import type { HookAPI } from "@mariozechner/pi-coding-agent";
 import { isArrowDown, isArrowLeft, isArrowRight, isArrowUp, isEscape, visibleWidth } from "@mariozechner/pi-tui";
-import type { HookAPI } from "../../src/core/hooks/types.js";
 
 const GAME_WIDTH = 40;
 const GAME_HEIGHT = 15;
@@ -56,7 +56,7 @@ class SnakeComponent {
 	private interval: ReturnType<typeof setInterval> | null = null;
 	private onClose: () => void;
 	private onSave: (state: GameState | null) => void;
-	private requestRender: () => void;
+	private tui: { requestRender: () => void };
 	private cachedLines: string[] = [];
 	private cachedWidth = 0;
 	private version = 0;
@@ -64,11 +64,12 @@ class SnakeComponent {
 	private paused: boolean;
 
 	constructor(
+		tui: { requestRender: () => void },
 		onClose: () => void,
 		onSave: (state: GameState | null) => void,
-		requestRender: () => void,
 		savedState?: GameState,
 	) {
+		this.tui = tui;
 		if (savedState && !savedState.gameOver) {
 			// Resume from saved state, start paused
 			this.state = savedState;
@@ -84,7 +85,6 @@ class SnakeComponent {
 		}
 		this.onClose = onClose;
 		this.onSave = onSave;
-		this.requestRender = requestRender;
 	}
 
 	private startGame(): void {
@@ -92,7 +92,7 @@ class SnakeComponent {
 			if (!this.state.gameOver) {
 				this.tick();
 				this.version++;
-				this.requestRender();
+				this.tui.requestRender();
 			}
 		}, TICK_MS);
 	}
@@ -196,7 +196,7 @@ class SnakeComponent {
 			this.state.highScore = highScore;
 			this.onSave(null); // Clear saved state on restart
 			this.version++;
-			this.requestRender();
+			this.tui.requestRender();
 		}
 	}
 
@@ -327,19 +327,17 @@ export default function (pi: HookAPI) {
 				}
 			}
 
-			let ui: { close: () => void; requestRender: () => void } | null = null;
-
-			const component = new SnakeComponent(
-				() => ui?.close(),
-				(state) => {
-					// Save or clear state
-					pi.appendEntry(SNAKE_SAVE_TYPE, state);
-				},
-				() => ui?.requestRender(),
-				savedState,
-			);
-
-			ui = ctx.ui.custom(component);
+			await ctx.ui.custom((tui, _theme, done) => {
+				return new SnakeComponent(
+					tui,
+					() => done(undefined),
+					(state) => {
+						// Save or clear state
+						pi.appendEntry(SNAKE_SAVE_TYPE, state);
+					},
+					savedState,
+				);
+			});
 		},
 	});
 }

packages/coding-agent/examples/sdk/01-minimal.ts

@@ -5,7 +5,7 @@
  * from cwd and ~/.pi/agent. Model chosen from settings or first available.
  */
 
-import { createAgentSession } from "../../src/index.js";
+import { createAgentSession } from "@mariozechner/pi-coding-agent";
 
 const { session } = await createAgentSession();
 

packages/coding-agent/examples/sdk/02-custom-model.ts

@@ -5,7 +5,7 @@
  */
 
 import { getModel } from "@mariozechner/pi-ai";
-import { createAgentSession, discoverAuthStorage, discoverModels } from "../../src/index.js";
+import { createAgentSession, discoverAuthStorage, discoverModels } from "@mariozechner/pi-coding-agent";
 
 // Set up auth storage and model registry
 const authStorage = discoverAuthStorage();

packages/coding-agent/examples/sdk/03-custom-prompt.ts

@@ -4,7 +4,7 @@
  * Shows how to replace or modify the default system prompt.
  */
 
-import { createAgentSession, SessionManager } from "../../src/index.js";
+import { createAgentSession, SessionManager } from "@mariozechner/pi-coding-agent";
 
 // Option 1: Replace prompt entirely
 const { session: session1 } = await createAgentSession({

packages/coding-agent/examples/sdk/04-skills.ts

@@ -5,7 +5,7 @@
  * Discover, filter, merge, or replace them.
  */
 
-import { createAgentSession, discoverSkills, SessionManager, type Skill } from "../../src/index.js";
+import { createAgentSession, discoverSkills, SessionManager, type Skill } from "@mariozechner/pi-coding-agent";
 
 // Discover all skills from cwd/.pi/skills, ~/.pi/agent/skills, etc.
 const allSkills = discoverSkills();

packages/coding-agent/examples/sdk/05-tools.ts

@@ -8,7 +8,6 @@
  * tools resolve paths relative to your cwd, not process.cwd().
  */
 
-import { Type } from "@sinclair/typebox";
 import {
 	bashTool, // read, bash, edit, write - uses process.cwd()
 	type CustomTool,
@@ -21,7 +20,8 @@ import {
 	readOnlyTools, // read, grep, find, ls - uses process.cwd()
 	readTool,
 	SessionManager,
-} from "../../src/index.js";
+} from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
 
 // Read-only mode (no edit/write) - uses process.cwd()
 await createAgentSession({

packages/coding-agent/examples/sdk/06-hooks.ts

@@ -4,7 +4,7 @@
  * Hooks intercept agent events for logging, blocking, or modification.
  */
 
-import { createAgentSession, type HookFactory, SessionManager } from "../../src/index.js";
+import { createAgentSession, type HookFactory, SessionManager } from "@mariozechner/pi-coding-agent";
 
 // Logging hook
 const loggingHook: HookFactory = (api) => {

packages/coding-agent/examples/sdk/07-context-files.ts

@@ -4,7 +4,7 @@
  * Context files provide project-specific instructions loaded into the system prompt.
  */
 
-import { createAgentSession, discoverContextFiles, SessionManager } from "../../src/index.js";
+import { createAgentSession, discoverContextFiles, SessionManager } from "@mariozechner/pi-coding-agent";
 
 // Discover AGENTS.md files walking up from cwd
 const discovered = discoverContextFiles();

packages/coding-agent/examples/sdk/08-slash-commands.ts

@@ -4,7 +4,12 @@
  * File-based commands that inject content when invoked with /commandname.
  */
 
-import { createAgentSession, discoverSlashCommands, type FileSlashCommand, SessionManager } from "../../src/index.js";
+import {
+	createAgentSession,
+	discoverSlashCommands,
+	type FileSlashCommand,
+	SessionManager,
+} from "@mariozechner/pi-coding-agent";
 
 // Discover commands from cwd/.pi/commands/ and ~/.pi/agent/commands/
 const discovered = discoverSlashCommands();

packages/coding-agent/examples/sdk/09-api-keys-and-oauth.ts

@@ -11,7 +11,7 @@ import {
 	discoverModels,
 	ModelRegistry,
 	SessionManager,
-} from "../../src/index.js";
+} from "@mariozechner/pi-coding-agent";
 
 // Default: discoverAuthStorage() uses ~/.pi/agent/auth.json
 // discoverModels() loads built-in + custom models from ~/.pi/agent/models.json

packages/coding-agent/examples/sdk/10-settings.ts

@@ -4,7 +4,7 @@
  * Override settings using SettingsManager.
  */
 
-import { createAgentSession, loadSettings, SessionManager, SettingsManager } from "../../src/index.js";
+import { createAgentSession, loadSettings, SessionManager, SettingsManager } from "@mariozechner/pi-coding-agent";
 
 // Load current settings (merged global + project)
 const settings = loadSettings();

packages/coding-agent/examples/sdk/11-sessions.ts

@@ -4,7 +4,7 @@
  * Control session persistence: in-memory, new file, continue, or open specific.
  */
 
-import { createAgentSession, SessionManager } from "../../src/index.js";
+import { createAgentSession, SessionManager } from "@mariozechner/pi-coding-agent";
 
 // In-memory (no persistence)
 const { session: inMemory } = await createAgentSession({

packages/coding-agent/examples/sdk/12-full-control.ts

@@ -9,7 +9,6 @@
  */
 
 import { getModel } from "@mariozechner/pi-ai";
-import { Type } from "@sinclair/typebox";
 import {
 	AuthStorage,
 	type CustomTool,
@@ -20,7 +19,8 @@ import {
 	ModelRegistry,
 	SessionManager,
 	SettingsManager,
-} from "../../src/index.js";
+} from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
 
 // Custom auth storage location
 const authStorage = new AuthStorage("/tmp/my-agent/auth.json");