Add hooks system with pi.send() for external message injection

- Hook discovery from ~/.pi/agent/hooks/, .pi/hooks/, --hook flag
- Events: session_start, session_switch, agent_start/end, turn_start/end, tool_call, tool_result, branch
- tool_call can block execution, tool_result can modify results
- pi.send(text, attachments?) to inject messages from external sources
- UI primitives: ctx.ui.select/confirm/input/notify
- Context: ctx.exec(), ctx.cwd, ctx.sessionFile, ctx.hasUI
- Docs shipped with npm package and binary builds
- System prompt references docs folder

packages/coding-agent/src/core/hooks/loader.ts

@@ -2,9 +2,12 @@
  * Hook loader - loads TypeScript hook modules using jiti.
  */
 
+import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import type { Attachment } from "@mariozechner/pi-agent-core";
 import { createJiti } from "jiti";
+import { getAgentDir } from "../../config.js";
 import type { HookAPI, HookFactory } from "./types.js";
 
 /**
@@ -12,6 +15,11 @@ import type { HookAPI, HookFactory } from "./types.js";
  */
 type HandlerFn = (...args: unknown[]) => Promise<unknown>;
 
+/**
+ * Send handler type for pi.send().
+ */
+export type SendHandler = (text: string, attachments?: Attachment[]) => void;
+
 /**
  * Registered handlers for a loaded hook.
  */
@@ -22,6 +30,8 @@ export interface LoadedHook {
 	resolvedPath: string;
 	/** Map of event type to handler functions */
 	handlers: Map<string, HandlerFn[]>;
+	/** Set the send handler for this hook's pi.send() */
+	setSendHandler: (handler: SendHandler) => void;
 }
 
 /**
@@ -66,15 +76,33 @@ function resolveHookPath(hookPath: string, cwd: string): string {
 
 /**
  * Create a HookAPI instance that collects handlers.
+ * Returns the API and a function to set the send handler later.
  */
-function createHookAPI(handlers: Map<string, HandlerFn[]>): HookAPI {
-	return {
+function createHookAPI(handlers: Map<string, HandlerFn[]>): {
+	api: HookAPI;
+	setSendHandler: (handler: SendHandler) => void;
+} {
+	let sendHandler: SendHandler = () => {
+		// Default no-op until mode sets the handler
+	};
+
+	const api: HookAPI = {
 		on(event: string, handler: HandlerFn): void {
 			const list = handlers.get(event) ?? [];
 			list.push(handler);
 			handlers.set(event, list);
 		},
+		send(text: string, attachments?: Attachment[]): void {
+			sendHandler(text, attachments);
+		},
 	} as HookAPI;
+
+	return {
+		api,
+		setSendHandler: (handler: SendHandler) => {
+			sendHandler = handler;
+		},
+	};
 }
 
 /**
@@ -97,13 +125,13 @@ async function loadHook(hookPath: string, cwd: string): Promise<{ hook: LoadedHo
 
 		// Create handlers map and API
 		const handlers = new Map<string, HandlerFn[]>();
-		const api = createHookAPI(handlers);
+		const { api, setSendHandler } = createHookAPI(handlers);
 
 		// Call factory to register handlers
 		factory(api);
 
 		return {
-			hook: { path: hookPath, resolvedPath, handlers },
+			hook: { path: hookPath, resolvedPath, handlers, setSendHandler },
 			error: null,
 		};
 	} catch (err) {
@@ -136,3 +164,59 @@ export async function loadHooks(paths: string[], cwd: string): Promise<LoadHooks
 
 	return { hooks, errors };
 }
+
+/**
+ * Discover hook files from a directory.
+ * Returns all .ts files in the directory (non-recursive).
+ */
+function discoverHooksInDir(dir: string): string[] {
+	if (!fs.existsSync(dir)) {
+		return [];
+	}
+
+	try {
+		const entries = fs.readdirSync(dir, { withFileTypes: true });
+		return entries.filter((e) => e.isFile() && e.name.endsWith(".ts")).map((e) => path.join(dir, e.name));
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Discover and load hooks from standard locations:
+ * 1. ~/.pi/agent/hooks/*.ts (global)
+ * 2. cwd/.pi/hooks/*.ts (project-local)
+ *
+ * Plus any explicitly configured paths from settings.
+ *
+ * @param configuredPaths - Explicit paths from settings.json
+ * @param cwd - Current working directory
+ */
+export async function discoverAndLoadHooks(configuredPaths: string[], cwd: string): Promise<LoadHooksResult> {
+	const allPaths: string[] = [];
+	const seen = new Set<string>();
+
+	// Helper to add paths without duplicates
+	const addPaths = (paths: string[]) => {
+		for (const p of paths) {
+			const resolved = path.resolve(p);
+			if (!seen.has(resolved)) {
+				seen.add(resolved);
+				allPaths.push(p);
+			}
+		}
+	};
+
+	// 1. Global hooks: ~/.pi/agent/hooks/
+	const globalHooksDir = path.join(getAgentDir(), "hooks");
+	addPaths(discoverHooksInDir(globalHooksDir));
+
+	// 2. Project-local hooks: cwd/.pi/hooks/
+	const localHooksDir = path.join(cwd, ".pi", "hooks");
+	addPaths(discoverHooksInDir(localHooksDir));
+
+	// 3. Explicitly configured paths (can override/add)
+	addPaths(configuredPaths.map((p) => resolveHookPath(p, cwd)));
+
+	return loadHooks(allPaths, cwd);
+}