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/cli/args.ts

@@ -26,6 +26,7 @@ export interface Args {
 	models?: string[];
 	tools?: ToolName[];
 	hooks?: string[];
+	customTools?: string[];
 	print?: boolean;
 	export?: string;
 	noSkills?: boolean;
@@ -109,6 +110,9 @@ export function parseArgs(args: string[]): Args {
 		} else if (arg === "--hook" && i + 1 < args.length) {
 			result.hooks = result.hooks ?? [];
 			result.hooks.push(args[++i]);
+		} else if (arg === "--tool" && i + 1 < args.length) {
+			result.customTools = result.customTools ?? [];
+			result.customTools.push(args[++i]);
 		} else if (arg === "--no-skills") {
 			result.noSkills = true;
 		} else if (arg === "--list-models") {
@@ -151,6 +155,7 @@ ${chalk.bold("Options:")}
                                  Available: read, bash, edit, write, grep, find, ls
   --thinking <level>             Set thinking level: off, minimal, low, medium, high, xhigh
   --hook <path>                  Load a hook file (can be used multiple times)
+  --tool <path>                  Load a custom tool file (can be used multiple times)
   --no-skills                    Disable skills discovery and loading
   --export <file>                Export session file to HTML and exit
   --list-models [search]         List available models (with optional fuzzy search)

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;
 	}

packages/coding-agent/src/index.ts

@@ -22,6 +22,19 @@ export {
 	getLastAssistantUsage,
 	shouldCompact,
 } from "./core/compaction.js";
+// Custom tools
+export type {
+	CustomAgentTool,
+	CustomToolFactory,
+	CustomToolsLoadResult,
+	ExecResult,
+	LoadedCustomTool,
+	RenderResultOptions,
+	SessionEvent as ToolSessionEvent,
+	ToolAPI,
+	ToolUIContext,
+} from "./core/custom-tools/index.js";
+export { discoverAndLoadCustomTools, loadCustomTools } from "./core/custom-tools/index.js";
 // Hook system types
 export type {
 	AgentEndEvent,
@@ -33,8 +46,7 @@ export type {
 	HookEventContext,
 	HookFactory,
 	HookUIContext,
-	SessionStartEvent,
-	SessionSwitchEvent,
+	SessionEvent,
 	ToolCallEvent,
 	ToolCallEventResult,
 	ToolResultEvent,

packages/coding-agent/src/main.ts

@@ -10,6 +10,7 @@ import { listModels } from "./cli/list-models.js";
 import { selectSession } from "./cli/session-picker.js";
 import { getModelsPath, VERSION } from "./config.js";
 import { AgentSession } from "./core/agent-session.js";
+import { discoverAndLoadCustomTools, type LoadedCustomTool } from "./core/custom-tools/index.js";
 import { exportFromFile } from "./core/export-html.js";
 import { discoverAndLoadHooks, HookRunner, wrapToolsWithHooks } from "./core/hooks/index.js";
 import { messageTransformer } from "./core/messages.js";
@@ -53,11 +54,13 @@ async function runInteractiveMode(
 	modelFallbackMessage: string | null,
 	versionCheckPromise: Promise<string | null>,
 	initialMessages: string[],
+	customTools: LoadedCustomTool[],
+	setToolUIContext: (uiContext: import("./core/hooks/types.js").HookUIContext, hasUI: boolean) => void,
 	initialMessage?: string,
 	initialAttachments?: Attachment[],
 	fdPath: string | null = null,
 ): Promise<void> {
-	const mode = new InteractiveMode(session, version, changelogMarkdown, fdPath);
+	const mode = new InteractiveMode(session, version, changelogMarkdown, customTools, setToolUIContext, fdPath);
 
 	// Initialize TUI (subscribes to agent events internally)
 	await mode.init();
@@ -317,6 +320,30 @@ export async function main(args: string[]) {
 		selectedTools = wrapToolsWithHooks(selectedTools, hookRunner);
 	}
 
+	// Discover and load custom tools from:
+	// 1. ~/.pi/agent/tools/*.ts (global)
+	// 2. cwd/.pi/tools/*.ts (project-local)
+	// 3. Explicit paths in settings.json
+	// 4. CLI --tool flags
+	const configuredToolPaths = [...settingsManager.getCustomToolPaths(), ...(parsed.customTools ?? [])];
+	const builtInToolNames = Object.keys(allTools);
+	const {
+		tools: loadedCustomTools,
+		errors: toolErrors,
+		setUIContext: setToolUIContext,
+	} = await discoverAndLoadCustomTools(configuredToolPaths, cwd, builtInToolNames);
+
+	// Report custom tool loading errors
+	for (const { path, error } of toolErrors) {
+		console.error(chalk.red(`Failed to load custom tool "${path}": ${error}`));
+	}
+
+	// Add custom tools to selected tools
+	if (loadedCustomTools.length > 0) {
+		const customToolInstances = loadedCustomTools.map((lt) => lt.tool);
+		selectedTools = [...selectedTools, ...customToolInstances] as typeof selectedTools;
+	}
+
 	// Create agent
 	const agent = new Agent({
 		initialState: {
@@ -373,6 +400,7 @@ export async function main(args: string[]) {
 		scopedModels,
 		fileCommands,
 		hookRunner,
+		customTools: loadedCustomTools,
 	});
 
 	// Route to appropriate mode
@@ -406,6 +434,8 @@ export async function main(args: string[]) {
 			modelFallbackMessage,
 			versionCheckPromise,
 			parsed.messages,
+			loadedCustomTools,
+			setToolUIContext,
 			initialMessage,
 			initialAttachments,
 			fdPath,

packages/coding-agent/src/modes/interactive/components/tool-execution.ts

@@ -1,5 +1,6 @@
 import * as os from "node:os";
 import {
+	Box,
 	Container,
 	getCapabilities,
 	getImageDimensions,
@@ -9,6 +10,7 @@ import {
 	Text,
 } from "@mariozechner/pi-tui";
 import stripAnsi from "strip-ansi";
+import type { CustomAgentTool } from "../../../core/custom-tools/types.js";
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize } from "../../../core/tools/truncate.js";
 import { theme } from "../theme/theme.js";
 
@@ -38,27 +40,37 @@ export interface ToolExecutionOptions {
  * Component that renders a tool call with its result (updateable)
  */
 export class ToolExecutionComponent extends Container {
-	private contentText: Text;
+	private contentBox: Box;
+	private contentText: Text; // For built-in tools
 	private imageComponents: Image[] = [];
 	private toolName: string;
 	private args: any;
 	private expanded = false;
 	private showImages: boolean;
 	private isPartial = true;
+	private customTool?: CustomAgentTool;
 	private result?: {
 		content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>;
 		isError: boolean;
 		details?: any;
 	};
 
-	constructor(toolName: string, args: any, options: ToolExecutionOptions = {}) {
+	constructor(toolName: string, args: any, options: ToolExecutionOptions = {}, customTool?: CustomAgentTool) {
 		super();
 		this.toolName = toolName;
 		this.args = args;
 		this.showImages = options.showImages ?? true;
+		this.customTool = customTool;
+
 		this.addChild(new Spacer(1));
-		this.contentText = new Text("", 1, 1, (text: string) => theme.bg("toolPendingBg", text));
-		this.addChild(this.contentText);
+
+		// Box wraps content with padding and background
+		this.contentBox = new Box(1, 1, (text: string) => theme.bg("toolPendingBg", text));
+		this.addChild(this.contentBox);
+
+		// Text component for built-in tool rendering
+		this.contentText = new Text("", 0, 0);
+
 		this.updateDisplay();
 	}
 
@@ -91,15 +103,66 @@ export class ToolExecutionComponent extends Container {
 	}
 
 	private updateDisplay(): void {
+		// Set background based on state
 		const bgFn = this.isPartial
 			? (text: string) => theme.bg("toolPendingBg", text)
 			: this.result?.isError
 				? (text: string) => theme.bg("toolErrorBg", text)
 				: (text: string) => theme.bg("toolSuccessBg", text);
 
-		this.contentText.setCustomBgFn(bgFn);
-		this.contentText.setText(this.formatToolExecution());
+		this.contentBox.setBgFn(bgFn);
+		this.contentBox.clear();
 
+		// Check for custom tool rendering
+		if (this.customTool) {
+			// Render call component
+			if (this.customTool.renderCall) {
+				try {
+					const callComponent = this.customTool.renderCall(this.args, theme);
+					if (callComponent) {
+						this.contentBox.addChild(callComponent);
+					}
+				} catch {
+					// Fall back to default on error
+					this.contentBox.addChild(new Text(theme.fg("toolTitle", theme.bold(this.toolName)), 0, 0));
+				}
+			} else {
+				// No custom renderCall, show tool name
+				this.contentBox.addChild(new Text(theme.fg("toolTitle", theme.bold(this.toolName)), 0, 0));
+			}
+
+			// Render result component if we have a result
+			if (this.result && this.customTool.renderResult) {
+				try {
+					const resultComponent = this.customTool.renderResult(
+						{ content: this.result.content as any, details: this.result.details },
+						{ expanded: this.expanded, isPartial: this.isPartial },
+						theme,
+					);
+					if (resultComponent) {
+						this.contentBox.addChild(resultComponent);
+					}
+				} catch {
+					// Fall back to showing raw output on error
+					const output = this.getTextOutput();
+					if (output) {
+						this.contentBox.addChild(new Text(theme.fg("toolOutput", output), 0, 0));
+					}
+				}
+			} else if (this.result) {
+				// Has result but no custom renderResult
+				const output = this.getTextOutput();
+				if (output) {
+					this.contentBox.addChild(new Text(theme.fg("toolOutput", output), 0, 0));
+				}
+			}
+		} else {
+			// Built-in tool: use existing formatToolExecution
+			this.contentText.setText(this.formatToolExecution());
+			this.contentBox.addChild(this.contentText);
+		}
+
+		// Handle images (same for both custom and built-in)
 		for (const img of this.imageComponents) {
 			this.removeChild(img);
 		}
@@ -110,7 +173,6 @@ export class ToolExecutionComponent extends Container {
 			const caps = getCapabilities();
 
 			for (const img of imageBlocks) {
-				// Show inline image only if terminal supports it AND user setting allows it
 				if (caps.images && this.showImages && img.data && img.mimeType) {
 					this.addChild(new Spacer(1));
 					const imageComponent = new Image(
@@ -142,7 +204,6 @@ export class ToolExecutionComponent extends Container {
 			.join("\n");
 
 		const caps = getCapabilities();
-		// Show text fallback if terminal doesn't support images OR if user disabled inline images
 		if (imageBlocks.length > 0 && (!caps.images || !this.showImages)) {
 			const imageIndicators = imageBlocks
 				.map((img: any) => {
@@ -159,7 +220,6 @@ export class ToolExecutionComponent extends Container {
 	private formatToolExecution(): string {
 		let text = "";
 
-		// Format based on tool type
 		if (this.toolName === "bash") {
 			const command = this.args?.command || "";
 			text = theme.fg("toolTitle", theme.bold(`$ ${command || theme.fg("toolOutput", "...")}`));
@@ -180,7 +240,6 @@ export class ToolExecutionComponent extends Container {
 						displayLines.map((line: string) => theme.fg("toolOutput", line)).join("\n");
 				}
 
-				// Show truncation warning at the bottom (outside collapsed area)
 				const truncation = this.result.details?.truncation;
 				const fullOutputPath = this.result.details?.fullOutputPath;
 				if (truncation?.truncated || fullOutputPath) {
@@ -205,7 +264,6 @@ export class ToolExecutionComponent extends Container {
 			const offset = this.args?.offset;
 			const limit = this.args?.limit;
 
-			// Build path display with offset/limit suffix (in warning color if offset/limit used)
 			let pathDisplay = path ? theme.fg("accent", path) : theme.fg("toolOutput", "...");
 			if (offset !== undefined || limit !== undefined) {
 				const startLine = offset ?? 1;
@@ -228,7 +286,6 @@ export class ToolExecutionComponent extends Container {
 					text += theme.fg("toolOutput", `\n... (${remaining} more lines)`);
 				}
 
-				// Show truncation warning at the bottom (outside collapsed area)
 				const truncation = this.result.details?.truncation;
 				if (truncation?.truncated) {
 					if (truncation.firstLineExceedsLimit) {
@@ -269,7 +326,6 @@ export class ToolExecutionComponent extends Container {
 				text += ` (${totalLines} lines)`;
 			}
 
-			// Show first 10 lines of content if available
 			if (fileContent) {
 				const maxLines = this.expanded ? lines.length : 10;
 				const displayLines = lines.slice(0, maxLines);
@@ -288,14 +344,12 @@ export class ToolExecutionComponent extends Container {
 				(path ? theme.fg("accent", path) : theme.fg("toolOutput", "..."));
 
 			if (this.result) {
-				// Show error message if it's an error
 				if (this.result.isError) {
 					const errorText = this.getTextOutput();
 					if (errorText) {
 						text += "\n\n" + theme.fg("error", errorText);
 					}
 				} else if (this.result.details?.diff) {
-					// Show diff if available
 					const diffLines = this.result.details.diff.split("\n");
 					const coloredLines = diffLines.map((line: string) => {
 						if (line.startsWith("+")) {
@@ -332,7 +386,6 @@ export class ToolExecutionComponent extends Container {
 					}
 				}
 
-				// Show truncation warning at the bottom (outside collapsed area)
 				const entryLimit = this.result.details?.entryLimitReached;
 				const truncation = this.result.details?.truncation;
 				if (entryLimit || truncation?.truncated) {
@@ -374,7 +427,6 @@ export class ToolExecutionComponent extends Container {
 					}
 				}
 
-				// Show truncation warning at the bottom (outside collapsed area)
 				const resultLimit = this.result.details?.resultLimitReached;
 				const truncation = this.result.details?.truncation;
 				if (resultLimit || truncation?.truncated) {
@@ -420,7 +472,6 @@ export class ToolExecutionComponent extends Container {
 					}
 				}
 
-				// Show truncation warning at the bottom (outside collapsed area)
 				const matchLimit = this.result.details?.matchLimitReached;
 				const truncation = this.result.details?.truncation;
 				const linesTruncated = this.result.details?.linesTruncated;
@@ -439,7 +490,7 @@ export class ToolExecutionComponent extends Container {
 				}
 			}
 		} else {
-			// Generic tool
+			// Generic tool (shouldn't reach here for custom tools)
 			text = theme.fg("toolTitle", theme.bold(this.toolName));
 
 			const content = JSON.stringify(this.args, null, 2);

packages/coding-agent/src/modes/interactive/interactive-mode.ts

@@ -26,6 +26,7 @@ import {
 import { exec } from "child_process";
 import { APP_NAME, getDebugLogPath, getOAuthPath } from "../../config.js";
 import type { AgentSession, AgentSessionEvent } from "../../core/agent-session.js";
+import type { LoadedCustomTool, SessionEvent as ToolSessionEvent } from "../../core/custom-tools/index.js";
 import type { HookUIContext } from "../../core/hooks/index.js";
 import { isBashExecutionMessage } from "../../core/messages.js";
 import { invalidateOAuthCache } from "../../core/model-config.js";
@@ -113,6 +114,9 @@ export class InteractiveMode {
 	private hookSelector: HookSelectorComponent | null = null;
 	private hookInput: HookInputComponent | null = null;
 
+	// Custom tools for custom rendering
+	private customTools: Map<string, LoadedCustomTool>;
+
 	// Convenience accessors
 	private get agent() {
 		return this.session.agent;
@@ -128,11 +132,14 @@ export class InteractiveMode {
 		session: AgentSession,
 		version: string,
 		changelogMarkdown: string | null = null,
+		customTools: LoadedCustomTool[] = [],
+		private setToolUIContext: (uiContext: HookUIContext, hasUI: boolean) => void = () => {},
 		fdPath: string | null = null,
 	) {
 		this.session = session;
 		this.version = version;
 		this.changelogMarkdown = changelogMarkdown;
+		this.customTools = new Map(customTools.map((ct) => [ct.tool.name, ct]));
 		this.ui = new TUI(new ProcessTerminal());
 		this.chatContainer = new Container();
 		this.pendingMessagesContainer = new Container();
@@ -263,7 +270,7 @@ export class InteractiveMode {
 		this.isInitialized = true;
 
 		// Initialize hooks with TUI-based UI context
-		await this.initHooks();
+		await this.initHooksAndCustomTools();
 
 		// Subscribe to agent events
 		this.subscribeToAgent();
@@ -288,7 +295,7 @@ export class InteractiveMode {
 	/**
 	 * Initialize the hook system with TUI-based UI context.
 	 */
-	private async initHooks(): Promise<void> {
+	private async initHooksAndCustomTools(): Promise<void> {
 		// Show loaded project context files
 		const contextFiles = loadProjectContextFiles();
 		if (contextFiles.length > 0) {
@@ -305,13 +312,37 @@ export class InteractiveMode {
 			this.chatContainer.addChild(new Spacer(1));
 		}
 
+		// Show loaded custom tools
+		if (this.customTools.size > 0) {
+			const toolList = Array.from(this.customTools.values())
+				.map((ct) => theme.fg("dim", `  ${ct.tool.name} (${ct.path})`))
+				.join("\n");
+			this.chatContainer.addChild(new Text(theme.fg("muted", "Loaded custom tools:\n") + toolList, 0, 0));
+			this.chatContainer.addChild(new Spacer(1));
+		}
+
+		// Load session entries if any
+		const entries = this.session.sessionManager.loadEntries();
+
+		// Set TUI-based UI context for custom tools
+		const uiContext = this.createHookUIContext();
+		this.setToolUIContext(uiContext, true);
+
+		// Notify custom tools of session start
+		await this.emitToolSessionEvent({
+			entries,
+			sessionFile: this.session.sessionFile,
+			previousSessionFile: null,
+			reason: "start",
+		});
+
 		const hookRunner = this.session.hookRunner;
 		if (!hookRunner) {
 			return; // No hooks loaded
 		}
 
-		// Set TUI-based UI context on the hook runner
-		hookRunner.setUIContext(this.createHookUIContext(), true);
+		// Set UI context on hook runner
+		hookRunner.setUIContext(uiContext, true);
 		hookRunner.setSessionFile(this.session.sessionFile);
 
 		// Subscribe to hook errors
@@ -332,8 +363,38 @@ export class InteractiveMode {
 			this.chatContainer.addChild(new Spacer(1));
 		}
 
-		// Emit session_start event
-		await hookRunner.emit({ type: "session_start" });
+		// Emit session event
+		await hookRunner.emit({
+			type: "session",
+			entries,
+			sessionFile: this.session.sessionFile,
+			previousSessionFile: null,
+			reason: "start",
+		});
+	}
+
+	/**
+	 * Emit session event to all custom tools.
+	 */
+	private async emitToolSessionEvent(event: ToolSessionEvent): Promise<void> {
+		for (const { tool } of this.customTools.values()) {
+			if (tool.onSession) {
+				try {
+					await tool.onSession(event);
+				} catch (err) {
+					this.showToolError(tool.name, err instanceof Error ? err.message : String(err));
+				}
+			}
+		}
+	}
+
+	/**
+	 * Show a tool error in the chat.
+	 */
+	private showToolError(toolName: string, error: string): void {
+		const errorText = new Text(theme.fg("error", `Tool "${toolName}" error: ${error}`), 1, 0);
+		this.chatContainer.addChild(errorText);
+		this.ui.requestRender();
 	}
 
 	/**
@@ -708,9 +769,14 @@ export class InteractiveMode {
 						if (content.type === "toolCall") {
 							if (!this.pendingTools.has(content.id)) {
 								this.chatContainer.addChild(new Text("", 0, 0));
-								const component = new ToolExecutionComponent(content.name, content.arguments, {
-									showImages: this.settingsManager.getShowImages(),
-								});
+								const component = new ToolExecutionComponent(
+									content.name,
+									content.arguments,
+									{
+										showImages: this.settingsManager.getShowImages(),
+									},
+									this.customTools.get(content.name)?.tool,
+								);
 								this.chatContainer.addChild(component);
 								this.pendingTools.set(content.id, component);
 							} else {
@@ -750,9 +816,14 @@ export class InteractiveMode {
 
 			case "tool_execution_start": {
 				if (!this.pendingTools.has(event.toolCallId)) {
-					const component = new ToolExecutionComponent(event.toolName, event.args, {
-						showImages: this.settingsManager.getShowImages(),
-					});
+					const component = new ToolExecutionComponent(
+						event.toolName,
+						event.args,
+						{
+							showImages: this.settingsManager.getShowImages(),
+						},
+						this.customTools.get(event.toolName)?.tool,
+					);
 					this.chatContainer.addChild(component);
 					this.pendingTools.set(event.toolCallId, component);
 					this.ui.requestRender();
@@ -984,9 +1055,14 @@ export class InteractiveMode {
 
 				for (const content of assistantMsg.content) {
 					if (content.type === "toolCall") {
-						const component = new ToolExecutionComponent(content.name, content.arguments, {
-							showImages: this.settingsManager.getShowImages(),
-						});
+						const component = new ToolExecutionComponent(
+							content.name,
+							content.arguments,
+							{
+								showImages: this.settingsManager.getShowImages(),
+							},
+							this.customTools.get(content.name)?.tool,
+						);
 						this.chatContainer.addChild(component);
 
 						if (assistantMsg.stopReason === "aborted" || assistantMsg.stopReason === "error") {
@@ -1307,6 +1383,7 @@ export class InteractiveMode {
 						this.ui.requestRender();
 						return;
 					}
+
 					this.chatContainer.clear();
 					this.isFirstUserMessage = true;
 					this.renderInitialMessages(this.session.state);
@@ -1353,7 +1430,7 @@ export class InteractiveMode {
 		this.streamingComponent = null;
 		this.pendingTools.clear();
 
-		// Switch session via AgentSession
+		// Switch session via AgentSession (emits hook and tool session events)
 		await this.session.switchSession(sessionPath);
 
 		// Clear and re-render the chat
@@ -1560,7 +1637,7 @@ export class InteractiveMode {
 		}
 		this.statusContainer.clear();
 
-		// Reset via session
+		// Reset via session (emits hook and tool session events)
 		await this.session.reset();
 
 		// Clear UI state

packages/coding-agent/src/modes/print-mode.ts

@@ -27,6 +27,9 @@ export async function runPrintMode(
 	initialMessage?: string,
 	initialAttachments?: Attachment[],
 ): Promise<void> {
+	// Load entries once for session start events
+	const entries = session.sessionManager.loadEntries();
+
 	// Hook runner already has no-op UI context by default (set in main.ts)
 	// Set up hooks for print mode (no UI)
 	const hookRunner = session.hookRunner;
@@ -40,8 +43,30 @@ export async function runPrintMode(
 		hookRunner.setSendHandler(() => {
 			console.error("Warning: pi.send() is not supported in print mode");
 		});
-		// Emit session_start event
-		await hookRunner.emit({ type: "session_start" });
+		// Emit session event
+		await hookRunner.emit({
+			type: "session",
+			entries,
+			sessionFile: session.sessionFile,
+			previousSessionFile: null,
+			reason: "start",
+		});
+	}
+
+	// Emit session start event to custom tools (no UI in print mode)
+	for (const { tool } of session.customTools) {
+		if (tool.onSession) {
+			try {
+				await tool.onSession({
+					entries,
+					sessionFile: session.sessionFile,
+					previousSessionFile: null,
+					reason: "start",
+				});
+			} catch (_err) {
+				// Silently ignore tool errors
+			}
+		}
 	}
 
 	// Always subscribe to enable session persistence via _handleAgentEvent

packages/coding-agent/src/modes/rpc/rpc-mode.ts

@@ -120,6 +120,9 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 		},
 	});
 
+	// Load entries once for session start events
+	const entries = session.sessionManager.loadEntries();
+
 	// Set up hooks with RPC-based UI context
 	const hookRunner = session.hookRunner;
 	if (hookRunner) {
@@ -139,8 +142,31 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 				});
 			}
 		});
-		// Emit session_start event
-		await hookRunner.emit({ type: "session_start" });
+		// Emit session event
+		await hookRunner.emit({
+			type: "session",
+			entries,
+			sessionFile: session.sessionFile,
+			previousSessionFile: null,
+			reason: "start",
+		});
+	}
+
+	// Emit session start event to custom tools
+	// Note: Tools get no-op UI context in RPC mode (host handles UI via protocol)
+	for (const { tool } of session.customTools) {
+		if (tool.onSession) {
+			try {
+				await tool.onSession({
+					entries,
+					sessionFile: session.sessionFile,
+					previousSessionFile: null,
+					reason: "start",
+				});
+			} catch (_err) {
+				// Silently ignore tool errors
+			}
+		}
 	}
 
 	// Output all agent events as JSON