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/src/core/agent-session.ts

@@ -19,6 +19,7 @@ import { isContextOverflow } from "@mariozechner/pi-ai";
 import { getModelsPath } from "../config.js";
 import { type BashResult, executeBash as executeBashCommand } from "./bash-executor.js";
 import { calculateContextTokens, compact, shouldCompact } from "./compaction.js";
+import type { LoadedCustomTool, SessionEvent as ToolSessionEvent } from "./custom-tools/index.js";
 import { exportSessionToHtml } from "./export-html.js";
 import type { BranchEventResult, HookRunner, TurnEndEvent, TurnStartEvent } from "./hooks/index.js";
 import type { BashExecutionMessage } from "./messages.js";
@@ -52,6 +53,8 @@ export interface AgentSessionConfig {
 	fileCommands?: FileSlashCommand[];
 	/** Hook runner (created in main.ts with wrapped tools) */
 	hookRunner?: HookRunner | null;
+	/** Custom tools for session lifecycle events */
+	customTools?: LoadedCustomTool[];
 }
 
 /** Options for AgentSession.prompt() */
@@ -132,6 +135,9 @@ export class AgentSession {
 	private _hookRunner: HookRunner | null = null;
 	private _turnIndex = 0;
 
+	// Custom tools for session lifecycle
+	private _customTools: LoadedCustomTool[] = [];
+
 	constructor(config: AgentSessionConfig) {
 		this.agent = config.agent;
 		this.sessionManager = config.sessionManager;
@@ -139,6 +145,7 @@ export class AgentSession {
 		this._scopedModels = config.scopedModels ?? [];
 		this._fileCommands = config.fileCommands ?? [];
 		this._hookRunner = config.hookRunner ?? null;
+		this._customTools = config.customTools ?? [];
 	}
 
 	// =========================================================================
@@ -465,12 +472,29 @@ export class AgentSession {
 	 * Listeners are preserved and will continue receiving events.
 	 */
 	async reset(): Promise<void> {
+		const previousSessionFile = this.sessionFile;
+
 		this._disconnectFromAgent();
 		await this.abort();
 		this.agent.reset();
 		this.sessionManager.reset();
 		this._queuedMessages = [];
 		this._reconnectToAgent();
+
+		// Emit session event with reason "clear" to hooks
+		if (this._hookRunner) {
+			this._hookRunner.setSessionFile(this.sessionFile);
+			await this._hookRunner.emit({
+				type: "session",
+				entries: [],
+				sessionFile: this.sessionFile,
+				previousSessionFile,
+				reason: "clear",
+			});
+		}
+
+		// Emit session event to custom tools
+		await this._emitToolSessionEvent("clear", previousSessionFile);
 	}
 
 	// =========================================================================
@@ -1086,19 +1110,25 @@ export class AgentSession {
 		// Set new session
 		this.sessionManager.setSessionFile(sessionPath);
 
-		// Emit session_switch event
+		// Reload messages
+		const entries = this.sessionManager.loadEntries();
+		const loaded = loadSessionFromEntries(entries);
+
+		// Emit session event to hooks
 		if (this._hookRunner) {
 			this._hookRunner.setSessionFile(sessionPath);
 			await this._hookRunner.emit({
-				type: "session_switch",
-				newSessionFile: sessionPath,
+				type: "session",
+				entries,
+				sessionFile: sessionPath,
 				previousSessionFile,
 				reason: "switch",
 			});
 		}
 
-		// Reload messages
-		const loaded = loadSessionFromEntries(this.sessionManager.loadEntries());
+		// Emit session event to custom tools
+		await this._emitToolSessionEvent("switch", previousSessionFile);
+
 		this.agent.replaceMessages(loaded.messages);
 
 		// Restore model if saved
@@ -1163,19 +1193,25 @@ export class AgentSession {
 			this.sessionManager.setSessionFile(newSessionFile);
 		}
 
-		// Emit session_switch event (in --no-session mode, both files are null)
+		// Reload messages from entries (works for both file and in-memory mode)
+		const newEntries = this.sessionManager.loadEntries();
+		const loaded = loadSessionFromEntries(newEntries);
+
+		// Emit session event to hooks (in --no-session mode, both files are null)
 		if (this._hookRunner) {
 			this._hookRunner.setSessionFile(newSessionFile);
 			await this._hookRunner.emit({
-				type: "session_switch",
-				newSessionFile,
+				type: "session",
+				entries: newEntries,
+				sessionFile: newSessionFile,
 				previousSessionFile,
-				reason: "branch",
+				reason: "switch",
 			});
 		}
 
-		// Reload messages from entries (works for both file and in-memory mode)
-		const loaded = loadSessionFromEntries(this.sessionManager.loadEntries());
+		// Emit session event to custom tools (with reason "branch")
+		await this._emitToolSessionEvent("branch", previousSessionFile);
+
 		this.agent.replaceMessages(loaded.messages);
 
 		return { selectedText, skipped: false };
@@ -1313,4 +1349,36 @@ export class AgentSession {
 	get hookRunner(): HookRunner | null {
 		return this._hookRunner;
 	}
+
+	/**
+	 * Get custom tools (for setting UI context in modes).
+	 */
+	get customTools(): LoadedCustomTool[] {
+		return this._customTools;
+	}
+
+	/**
+	 * Emit session event to all custom tools.
+	 * Called on session switch, branch, and clear.
+	 */
+	private async _emitToolSessionEvent(
+		reason: ToolSessionEvent["reason"],
+		previousSessionFile: string | null,
+	): Promise<void> {
+		const event: ToolSessionEvent = {
+			entries: this.sessionManager.loadEntries(),
+			sessionFile: this.sessionFile,
+			previousSessionFile,
+			reason,
+		};
+		for (const { tool } of this._customTools) {
+			if (tool.onSession) {
+				try {
+					await tool.onSession(event);
+				} catch (_err) {
+					// Silently ignore tool errors during session events
+				}
+			}
+		}
+	}
 }

packages/coding-agent/src/core/custom-tools/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Custom tools module.
+ */
+
+export { discoverAndLoadCustomTools, loadCustomTools } from "./loader.js";
+export type {
+	CustomAgentTool,
+	CustomToolFactory,
+	CustomToolsLoadResult,
+	ExecResult,
+	LoadedCustomTool,
+	RenderResultOptions,
+	SessionEvent,
+	ToolAPI,
+	ToolUIContext,
+} from "./types.js";

packages/coding-agent/src/core/custom-tools/loader.ts

@@ -0,0 +1,258 @@
+/**
+ * Custom tool loader - loads TypeScript tool modules using jiti.
+ */
+
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { createJiti } from "jiti";
+import { getAgentDir } from "../../config.js";
+import type { HookUIContext } from "../hooks/types.js";
+import type { CustomToolFactory, CustomToolsLoadResult, ExecResult, LoadedCustomTool, ToolAPI } from "./types.js";
+
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+
+function normalizeUnicodeSpaces(str: string): string {
+	return str.replace(UNICODE_SPACES, " ");
+}
+
+function expandPath(p: string): string {
+	const normalized = normalizeUnicodeSpaces(p);
+	if (normalized.startsWith("~/")) {
+		return path.join(os.homedir(), normalized.slice(2));
+	}
+	if (normalized.startsWith("~")) {
+		return path.join(os.homedir(), normalized.slice(1));
+	}
+	return normalized;
+}
+
+/**
+ * Resolve tool path.
+ * - Absolute paths used as-is
+ * - Paths starting with ~ expanded to home directory
+ * - Relative paths resolved from cwd
+ */
+function resolveToolPath(toolPath: string, cwd: string): string {
+	const expanded = expandPath(toolPath);
+
+	if (path.isAbsolute(expanded)) {
+		return expanded;
+	}
+
+	// Relative paths resolved from cwd
+	return path.resolve(cwd, expanded);
+}
+
+/**
+ * Execute a command and return stdout/stderr/code.
+ */
+async function execCommand(command: string, args: string[], cwd: string): Promise<ExecResult> {
+	return new Promise((resolve) => {
+		const proc = spawn(command, args, {
+			cwd,
+			shell: false,
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+
+		let stdout = "";
+		let stderr = "";
+
+		proc.stdout.on("data", (data) => {
+			stdout += data.toString();
+		});
+
+		proc.stderr.on("data", (data) => {
+			stderr += data.toString();
+		});
+
+		proc.on("close", (code) => {
+			resolve({
+				stdout,
+				stderr,
+				code: code ?? 0,
+			});
+		});
+
+		proc.on("error", (err) => {
+			resolve({
+				stdout,
+				stderr: stderr || err.message,
+				code: 1,
+			});
+		});
+	});
+}
+
+/**
+ * Create a no-op UI context for headless modes.
+ */
+function createNoOpUIContext(): HookUIContext {
+	return {
+		select: async () => null,
+		confirm: async () => false,
+		input: async () => null,
+		notify: () => {},
+	};
+}
+
+/**
+ * Load a single tool module using jiti.
+ */
+async function loadTool(
+	toolPath: string,
+	cwd: string,
+	sharedApi: ToolAPI,
+): Promise<{ tools: LoadedCustomTool[] | null; error: string | null }> {
+	const resolvedPath = resolveToolPath(toolPath, cwd);
+
+	try {
+		// Create jiti instance for TypeScript/ESM loading
+		const jiti = createJiti(import.meta.url);
+
+		// Import the module
+		const module = await jiti.import(resolvedPath, { default: true });
+		const factory = module as CustomToolFactory;
+
+		if (typeof factory !== "function") {
+			return { tools: null, error: "Tool must export a default function" };
+		}
+
+		// Call factory with shared API
+		const result = await factory(sharedApi);
+
+		// Handle single tool or array of tools
+		const toolsArray = Array.isArray(result) ? result : [result];
+
+		const loadedTools: LoadedCustomTool[] = toolsArray.map((tool) => ({
+			path: toolPath,
+			resolvedPath,
+			tool,
+		}));
+
+		return { tools: loadedTools, error: null };
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		return { tools: null, error: `Failed to load tool: ${message}` };
+	}
+}
+
+/**
+ * Load all tools from configuration.
+ * @param paths - Array of tool file paths
+ * @param cwd - Current working directory for resolving relative paths
+ * @param builtInToolNames - Names of built-in tools to check for conflicts
+ */
+export async function loadCustomTools(
+	paths: string[],
+	cwd: string,
+	builtInToolNames: string[],
+): Promise<CustomToolsLoadResult> {
+	const tools: LoadedCustomTool[] = [];
+	const errors: Array<{ path: string; error: string }> = [];
+	const seenNames = new Set<string>(builtInToolNames);
+
+	// Shared API object - all tools get the same instance
+	const sharedApi: ToolAPI = {
+		cwd,
+		exec: (command: string, args: string[]) => execCommand(command, args, cwd),
+		ui: createNoOpUIContext(),
+		hasUI: false,
+	};
+
+	for (const toolPath of paths) {
+		const { tools: loadedTools, error } = await loadTool(toolPath, cwd, sharedApi);
+
+		if (error) {
+			errors.push({ path: toolPath, error });
+			continue;
+		}
+
+		if (loadedTools) {
+			for (const loadedTool of loadedTools) {
+				// Check for name conflicts
+				if (seenNames.has(loadedTool.tool.name)) {
+					errors.push({
+						path: toolPath,
+						error: `Tool name "${loadedTool.tool.name}" conflicts with existing tool`,
+					});
+					continue;
+				}
+
+				seenNames.add(loadedTool.tool.name);
+				tools.push(loadedTool);
+			}
+		}
+	}
+
+	return {
+		tools,
+		errors,
+		setUIContext(uiContext, hasUI) {
+			sharedApi.ui = uiContext;
+			sharedApi.hasUI = hasUI;
+		},
+	};
+}
+
+/**
+ * Discover tool files from a directory.
+ * Returns all .ts files in the directory (non-recursive).
+ */
+function discoverToolsInDir(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 tools from standard locations:
+ * 1. ~/.pi/agent/tools/*.ts (global)
+ * 2. cwd/.pi/tools/*.ts (project-local)
+ *
+ * Plus any explicitly configured paths from settings or CLI.
+ *
+ * @param configuredPaths - Explicit paths from settings.json and CLI --tool flags
+ * @param cwd - Current working directory
+ * @param builtInToolNames - Names of built-in tools to check for conflicts
+ */
+export async function discoverAndLoadCustomTools(
+	configuredPaths: string[],
+	cwd: string,
+	builtInToolNames: string[],
+): Promise<CustomToolsLoadResult> {
+	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 tools: ~/.pi/agent/tools/
+	const globalToolsDir = path.join(getAgentDir(), "tools");
+	addPaths(discoverToolsInDir(globalToolsDir));
+
+	// 2. Project-local tools: cwd/.pi/tools/
+	const localToolsDir = path.join(cwd, ".pi", "tools");
+	addPaths(discoverToolsInDir(localToolsDir));
+
+	// 3. Explicitly configured paths (can override/add)
+	addPaths(configuredPaths.map((p) => resolveToolPath(p, cwd)));
+
+	return loadCustomTools(allPaths, cwd, builtInToolNames);
+}

packages/coding-agent/src/core/custom-tools/types.ts

@@ -0,0 +1,90 @@
+/**
+ * Custom tool types.
+ *
+ * Custom tools are TypeScript modules that define additional tools for the agent.
+ * They can provide custom rendering for tool calls and results in the TUI.
+ */
+
+import type { AgentTool, AgentToolResult } from "@mariozechner/pi-ai";
+import type { Component } from "@mariozechner/pi-tui";
+import type { Static, TSchema } from "@sinclair/typebox";
+import type { Theme } from "../../modes/interactive/theme/theme.js";
+import type { HookUIContext } from "../hooks/types.js";
+import type { SessionEntry } from "../session-manager.js";
+
+/** Alias for clarity */
+export type ToolUIContext = HookUIContext;
+
+export interface ExecResult {
+	stdout: string;
+	stderr: string;
+	code: number;
+}
+
+/** API passed to custom tool factory (stable across session changes) */
+export interface ToolAPI {
+	/** Current working directory */
+	cwd: string;
+	/** Execute a command */
+	exec(command: string, args: string[]): Promise<ExecResult>;
+	/** UI methods for user interaction (select, confirm, input, notify) */
+	ui: ToolUIContext;
+	/** Whether UI is available (false in print/RPC mode) */
+	hasUI: boolean;
+}
+
+/** Session event passed to onSession callback */
+export interface SessionEvent {
+	/** All session entries (including pre-compaction history) */
+	entries: SessionEntry[];
+	/** Current session file path, or null in --no-session mode */
+	sessionFile: string | null;
+	/** Previous session file path, or null for "start" and "clear" */
+	previousSessionFile: string | null;
+	/** Reason for the session event */
+	reason: "start" | "switch" | "branch" | "clear";
+}
+
+/** Rendering options passed to renderResult */
+export interface RenderResultOptions {
+	/** Whether the result view is expanded */
+	expanded: boolean;
+	/** Whether this is a partial/streaming result */
+	isPartial: boolean;
+}
+
+/** Custom tool with optional lifecycle and rendering methods */
+export interface CustomAgentTool<TParams extends TSchema = TSchema, TDetails = any>
+	extends AgentTool<TParams, TDetails> {
+	/** Called on session start/switch/branch/clear - use to reconstruct state from entries */
+	onSession?: (event: SessionEvent) => void | Promise<void>;
+	/** Custom rendering for tool call display - return a Component */
+	renderCall?: (args: Static<TParams>, theme: Theme) => Component;
+	/** Custom rendering for tool result display - return a Component */
+	renderResult?: (result: AgentToolResult<TDetails>, options: RenderResultOptions, theme: Theme) => Component;
+	/** Called when session ends - cleanup resources */
+	dispose?: () => Promise<void> | void;
+}
+
+/** Factory function that creates a custom tool or array of tools */
+export type CustomToolFactory = (
+	pi: ToolAPI,
+) => CustomAgentTool<any> | CustomAgentTool[] | Promise<CustomAgentTool | CustomAgentTool[]>;
+
+/** Loaded custom tool with metadata */
+export interface LoadedCustomTool {
+	/** Original path (as specified) */
+	path: string;
+	/** Resolved absolute path */
+	resolvedPath: string;
+	/** The tool instance */
+	tool: CustomAgentTool;
+}
+
+/** Result from loading custom tools */
+export interface CustomToolsLoadResult {
+	tools: LoadedCustomTool[];
+	errors: Array<{ path: string; error: string }>;
+	/** Update the UI context for all loaded tools. Call when mode initializes. */
+	setUIContext(uiContext: ToolUIContext, hasUI: boolean): void;
+}

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

@@ -13,8 +13,7 @@ export type {
 	HookEventContext,
 	HookFactory,
 	HookUIContext,
-	SessionStartEvent,
-	SessionSwitchEvent,
+	SessionEvent,
 	ToolCallEvent,
 	ToolCallEventResult,
 	ToolResultEvent,

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

@@ -73,25 +73,20 @@ export interface HookEventContext {
 // ============================================================================
 
 /**
- * Event data for session_start event.
- * Fired once when the coding agent starts up.
+ * Event data for session event.
+ * Fired on startup and when session changes (switch or clear).
+ * Note: branch has its own event that fires BEFORE the branch happens.
  */
-export interface SessionStartEvent {
-	type: "session_start";
-}
-
-/**
- * Event data for session_switch event.
- * Fired when the session changes (branch or session switch).
- */
-export interface SessionSwitchEvent {
-	type: "session_switch";
-	/** New session file path, or null in --no-session mode */
-	newSessionFile: string | null;
-	/** Previous session file path, or null in --no-session mode */
+export interface SessionEvent {
+	type: "session";
+	/** All session entries (including pre-compaction history) */
+	entries: SessionEntry[];
+	/** Current session file path, or null in --no-session mode */
+	sessionFile: string | null;
+	/** Previous session file path, or null for "start" and "clear" */
 	previousSessionFile: string | null;
-	/** Reason for the switch */
-	reason: "branch" | "switch";
+	/** Reason for the session event */
+	reason: "start" | "switch" | "clear";
 }
 
 /**
@@ -176,8 +171,7 @@ export interface BranchEvent {
  * Union of all hook event types.
  */
 export type HookEvent =
-	| SessionStartEvent
-	| SessionSwitchEvent
+	| SessionEvent
 	| AgentStartEvent
 	| AgentEndEvent
 	| TurnStartEvent
@@ -235,8 +229,7 @@ export type HookHandler<E, R = void> = (event: E, ctx: HookEventContext) => Prom
  * Hooks use pi.on() to subscribe to events and pi.send() to inject messages.
  */
 export interface HookAPI {
-	on(event: "session_start", handler: HookHandler<SessionStartEvent>): void;
-	on(event: "session_switch", handler: HookHandler<SessionSwitchEvent>): void;
+	on(event: "session", handler: HookHandler<SessionEvent>): void;
 	on(event: "agent_start", handler: HookHandler<AgentStartEvent>): void;
 	on(event: "agent_end", handler: HookHandler<AgentEndEvent>): void;
 	on(event: "turn_start", handler: HookHandler<TurnStartEvent>): void;

packages/coding-agent/src/core/index.ts

@@ -13,6 +13,18 @@ export {
 	type SessionStats,
 } from "./agent-session.js";
 export { type BashExecutorOptions, type BashResult, executeBash } from "./bash-executor.js";
+export {
+	type CustomAgentTool,
+	type CustomToolFactory,
+	type CustomToolsLoadResult,
+	discoverAndLoadCustomTools,
+	type ExecResult,
+	type LoadedCustomTool,
+	loadCustomTools,
+	type RenderResultOptions,
+	type ToolAPI,
+	type ToolUIContext,
+} from "./custom-tools/index.js";
 export {
 	type HookAPI,
 	type HookError,

packages/coding-agent/src/core/settings-manager.ts

@@ -36,6 +36,7 @@ export interface Settings {
 	collapseChangelog?: boolean; // Show condensed changelog after update (use /changelog for full)
 	hooks?: string[]; // Array of hook file paths
 	hookTimeout?: number; // Timeout for hook execution in ms (default: 30000)
+	customTools?: string[]; // Array of custom tool file paths
 	skills?: SkillsSettings;
 	terminal?: TerminalSettings;
 }
@@ -231,6 +232,15 @@ export class SettingsManager {
 		this.save();
 	}
 
+	getCustomToolPaths(): string[] {
+		return this.settings.customTools ?? [];
+	}
+
+	setCustomToolPaths(paths: string[]): void {
+		this.settings.customTools = paths;
+		this.save();
+	}
+
 	getSkillsEnabled(): boolean {
 		return this.settings.skills?.enabled ?? true;
 	}