Move exec to HookAPI, sessionManager/modelRegistry to HookEventContext

Breaking changes:
- HookEventContext now has sessionManager and modelRegistry (moved from SessionEventBase)
- HookAPI now has exec() method (moved from HookEventContext/HookCommandContext)
- HookRunner constructor takes sessionManager and modelRegistry as required params
- Session events no longer include sessionManager/modelRegistry fields

Hook code migration:
- event.sessionManager -> ctx.sessionManager
- event.modelRegistry -> ctx.modelRegistry
- ctx.exec() -> pi.exec()

Updated:
- src/core/hooks/types.ts - type changes
- src/core/hooks/runner.ts - constructor, createContext
- src/core/hooks/loader.ts - add exec to HookAPI
- src/core/sdk.ts - pass sessionManager/modelRegistry to HookRunner
- src/core/agent-session.ts - remove sessionManager/modelRegistry from events
- src/modes/* - remove setSessionFile calls, update events
- examples/hooks/* - update to new API

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

@@ -27,15 +27,13 @@ import {
 } from "./compaction.js";
 import type { LoadedCustomTool, SessionEvent as ToolSessionEvent } from "./custom-tools/index.js";
 import { exportSessionToHtml } from "./export-html.js";
-import {
-	type ExecOptions,
-	execCommand,
-	type HookCommandContext,
-	type HookMessage,
-	type HookRunner,
-	type SessionEventResult,
-	type TurnEndEvent,
-	type TurnStartEvent,
+import type {
+	HookCommandContext,
+	HookMessage,
+	HookRunner,
+	SessionEventResult,
+	TurnEndEvent,
+	TurnStartEvent,
 } from "./hooks/index.js";
 import { type BashExecutionMessage, type HookAppMessage, isHookAppMessage } from "./messages.js";
 import type { ModelRegistry } from "./model-registry.js";
@@ -519,7 +517,6 @@ export class AgentSession {
 			cwd,
 			sessionManager: this.sessionManager,
 			modelRegistry: this._modelRegistry,
-			exec: (cmd: string, cmdArgs: string[], options?: ExecOptions) => execCommand(cmd, cmdArgs, cwd, options),
 		};
 
 		try {
@@ -640,8 +637,6 @@ export class AgentSession {
 		if (this._hookRunner?.hasHandlers("session")) {
 			const result = (await this._hookRunner.emit({
 				type: "session",
-				sessionManager: this.sessionManager,
-				modelRegistry: this._modelRegistry,
 				reason: "before_new",
 			})) as SessionEventResult | undefined;
 
@@ -659,11 +654,8 @@ export class AgentSession {
 
 		// Emit session event with reason "new" to hooks
 		if (this._hookRunner) {
-			this._hookRunner.setSessionFile(this.sessionFile);
 			await this._hookRunner.emit({
 				type: "session",
-				sessionManager: this.sessionManager,
-				modelRegistry: this._modelRegistry,
 				reason: "new",
 			});
 		}
@@ -888,8 +880,6 @@ export class AgentSession {
 
 				const result = (await this._hookRunner.emit({
 					type: "session",
-					sessionManager: this.sessionManager,
-					modelRegistry: this._modelRegistry,
 					reason: "before_compact",
 					preparation,
 					previousCompactions,
@@ -952,8 +942,6 @@ export class AgentSession {
 			if (this._hookRunner && savedCompactionEntry) {
 				await this._hookRunner.emit({
 					type: "session",
-					sessionManager: this.sessionManager,
-					modelRegistry: this._modelRegistry,
 					reason: "compact",
 					compactionEntry: savedCompactionEntry,
 					fromHook,
@@ -1060,8 +1048,6 @@ export class AgentSession {
 
 				const hookResult = (await this._hookRunner.emit({
 					type: "session",
-					sessionManager: this.sessionManager,
-					modelRegistry: this._modelRegistry,
 					reason: "before_compact",
 					preparation,
 					previousCompactions,
@@ -1125,8 +1111,6 @@ export class AgentSession {
 			if (this._hookRunner && savedCompactionEntry) {
 				await this._hookRunner.emit({
 					type: "session",
-					sessionManager: this.sessionManager,
-					modelRegistry: this._modelRegistry,
 					reason: "compact",
 					compactionEntry: savedCompactionEntry,
 					fromHook,
@@ -1431,8 +1415,6 @@ export class AgentSession {
 		if (this._hookRunner?.hasHandlers("session")) {
 			const result = (await this._hookRunner.emit({
 				type: "session",
-				sessionManager: this.sessionManager,
-				modelRegistry: this._modelRegistry,
 				reason: "before_switch",
 				targetSessionFile: sessionPath,
 			})) as SessionEventResult | undefined;
@@ -1454,11 +1436,8 @@ export class AgentSession {
 
 		// Emit session event to hooks
 		if (this._hookRunner) {
-			this._hookRunner.setSessionFile(sessionPath);
 			await this._hookRunner.emit({
 				type: "session",
-				sessionManager: this.sessionManager,
-				modelRegistry: this._modelRegistry,
 				reason: "switch",
 				previousSessionFile,
 			});
@@ -1515,8 +1494,6 @@ export class AgentSession {
 		if (this._hookRunner?.hasHandlers("session")) {
 			const result = (await this._hookRunner.emit({
 				type: "session",
-				sessionManager: this.sessionManager,
-				modelRegistry: this._modelRegistry,
 				reason: "before_branch",
 				targetTurnIndex: entryIndex,
 			})) as SessionEventResult | undefined;
@@ -1544,11 +1521,8 @@ export class AgentSession {
 
 		// Emit branch event to hooks (after branch completes)
 		if (this._hookRunner) {
-			this._hookRunner.setSessionFile(newSessionFile);
 			await this._hookRunner.emit({
 				type: "session",
-				sessionManager: this.sessionManager,
-				modelRegistry: this._modelRegistry,
 				reason: "branch",
 				targetTurnIndex: entryIndex,
 			});

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

@@ -9,7 +9,15 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createJiti } from "jiti";
 import { getAgentDir } from "../../config.js";
-import type { CustomMessageRenderer, HookAPI, HookFactory, HookMessage, RegisteredCommand } from "./types.js";
+import { execCommand } from "./runner.js";
+import type {
+	CustomMessageRenderer,
+	ExecOptions,
+	HookAPI,
+	HookFactory,
+	HookMessage,
+	RegisteredCommand,
+} from "./types.js";
 
 // Create require function to resolve module paths at runtime
 const require = createRequire(import.meta.url);
@@ -123,7 +131,10 @@ function resolveHookPath(hookPath: string, cwd: string): string {
  * Create a HookAPI instance that collects handlers, renderers, and commands.
  * Returns the API, maps, and a function to set the send message handler later.
  */
-function createHookAPI(handlers: Map<string, HandlerFn[]>): {
+function createHookAPI(
+	handlers: Map<string, HandlerFn[]>,
+	cwd: string,
+): {
 	api: HookAPI;
 	customMessageRenderers: Map<string, CustomMessageRenderer>;
 	commands: Map<string, RegisteredCommand>;
@@ -139,7 +150,9 @@ function createHookAPI(handlers: Map<string, HandlerFn[]>): {
 	const customMessageRenderers = new Map<string, CustomMessageRenderer>();
 	const commands = new Map<string, RegisteredCommand>();
 
-	const api: HookAPI = {
+	// Cast to HookAPI - the implementation is more general (string event names)
+	// but the interface has specific overloads for type safety in hooks
+	const api = {
 		on(event: string, handler: HandlerFn): void {
 			const list = handlers.get(event) ?? [];
 			list.push(handler);
@@ -151,12 +164,15 @@ function createHookAPI(handlers: Map<string, HandlerFn[]>): {
 		appendEntry<T = unknown>(customType: string, data?: T): void {
 			appendEntryHandler(customType, data);
 		},
-		registerCustomMessageRenderer(customType: string, renderer: CustomMessageRenderer): void {
-			customMessageRenderers.set(customType, renderer);
+		registerCustomMessageRenderer<T = unknown>(customType: string, renderer: CustomMessageRenderer<T>): void {
+			customMessageRenderers.set(customType, renderer as CustomMessageRenderer);
 		},
 		registerCommand(name: string, options: { description?: string; handler: RegisteredCommand["handler"] }): void {
 			commands.set(name, { name, ...options });
 		},
+		exec(command: string, args: string[], options?: ExecOptions) {
+			return execCommand(command, args, options?.cwd ?? cwd, options);
+		},
 	} as HookAPI;
 
 	return {
@@ -196,8 +212,10 @@ async function loadHook(hookPath: string, cwd: string): Promise<{ hook: LoadedHo
 
 		// Create handlers map and API
 		const handlers = new Map<string, HandlerFn[]>();
-		const { api, customMessageRenderers, commands, setSendMessageHandler, setAppendEntryHandler } =
-			createHookAPI(handlers);
+		const { api, customMessageRenderers, commands, setSendMessageHandler, setAppendEntryHandler } = createHookAPI(
+			handlers,
+			cwd,
+		);
 
 		// Call factory to register handlers
 		factory(api);

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

@@ -3,6 +3,8 @@
  */
 
 import { spawn } from "node:child_process";
+import type { ModelRegistry } from "../model-registry.js";
+import type { SessionManager } from "../session-manager.js";
 import type { AppendEntryHandler, LoadedHook, SendMessageHandler } from "./loader.js";
 import type {
 	CustomMessageRenderer,
@@ -133,16 +135,24 @@ export class HookRunner {
 	private uiContext: HookUIContext;
 	private hasUI: boolean;
 	private cwd: string;
-	private sessionFile: string | null;
+	private sessionManager: SessionManager;
+	private modelRegistry: ModelRegistry;
 	private timeout: number;
 	private errorListeners: Set<HookErrorListener> = new Set();
 
-	constructor(hooks: LoadedHook[], cwd: string, timeout: number = DEFAULT_TIMEOUT) {
+	constructor(
+		hooks: LoadedHook[],
+		cwd: string,
+		sessionManager: SessionManager,
+		modelRegistry: ModelRegistry,
+		timeout: number = DEFAULT_TIMEOUT,
+	) {
 		this.hooks = hooks;
 		this.uiContext = noOpUIContext;
 		this.hasUI = false;
 		this.cwd = cwd;
-		this.sessionFile = null;
+		this.sessionManager = sessionManager;
+		this.modelRegistry = modelRegistry;
 		this.timeout = timeout;
 	}
 
@@ -176,13 +186,6 @@ export class HookRunner {
 		return this.hooks.map((h) => h.path);
 	}
 
-	/**
-	 * Set the session file path.
-	 */
-	setSessionFile(sessionFile: string | null): void {
-		this.sessionFile = sessionFile;
-	}
-
 	/**
 	 * Set the send message handler for all hooks' pi.sendMessage().
 	 * Call this when the mode initializes.
@@ -283,12 +286,11 @@ export class HookRunner {
 	 */
 	private createContext(): HookEventContext {
 		return {
-			exec: (command: string, args: string[], options?: ExecOptions) =>
-				execCommand(command, args, this.cwd, options),
 			ui: this.uiContext,
 			hasUI: this.hasUI,
 			cwd: this.cwd,
-			sessionFile: this.sessionFile,
+			sessionManager: this.sessionManager,
+			modelRegistry: this.modelRegistry,
 		};
 	}
 

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

@@ -41,6 +41,8 @@ export interface ExecOptions {
 	signal?: AbortSignal;
 	/** Timeout in milliseconds */
 	timeout?: number;
+	/** Working directory */
+	cwd?: string;
 }
 
 /**
@@ -78,16 +80,16 @@ export interface HookUIContext {
  * Context passed to hook event handlers.
  */
 export interface HookEventContext {
-	/** Execute a command and return stdout/stderr/code */
-	exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
 	/** UI methods for user interaction */
 	ui: HookUIContext;
 	/** Whether UI is available (false in print mode) */
 	hasUI: boolean;
 	/** Current working directory */
 	cwd: string;
-	/** Path to session file, or null if --no-session */
-	sessionFile: string | null;
+	/** Session manager instance - use for entries, session file, etc. */
+	sessionManager: SessionManager;
+	/** Model registry - use for API key resolution and model retrieval */
+	modelRegistry: ModelRegistry;
 }
 
 // ============================================================================
@@ -99,10 +101,6 @@ export interface HookEventContext {
  */
 interface SessionEventBase {
 	type: "session";
-	/** Session manager instance - use for entries, session file, etc. */
-	sessionManager: SessionManager;
-	/** Model registry - use for API key resolution */
-	modelRegistry: ModelRegistry;
 }
 
 /**
@@ -402,8 +400,6 @@ export interface HookCommandContext {
 	args: string;
 	/** UI methods for user interaction */
 	ui: HookUIContext;
-	/** Execute a command and return stdout/stderr/code */
-	exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
 	/** Whether UI is available (false in print mode) */
 	hasUI: boolean;
 	/** Current working directory */
@@ -491,9 +487,15 @@ export interface HookAPI {
 
 	/**
 	 * Register a custom slash command.
-	 * Handler receives CommandContext and can return a string to send as prompt.
+	 * Handler receives HookCommandContext.
 	 */
 	registerCommand(name: string, options: { description?: string; handler: RegisteredCommand["handler"] }): void;
+
+	/**
+	 * Execute a shell command and return stdout/stderr/code.
+	 * Supports timeout and abort signal.
+	 */
+	exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
 }
 
 /**

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

@@ -534,7 +534,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	if (options.hooks !== undefined) {
 		if (options.hooks.length > 0) {
 			const loadedHooks = createLoadedHooksFromDefinitions(options.hooks);
-			hookRunner = new HookRunner(loadedHooks, cwd, settingsManager.getHookTimeout());
+			hookRunner = new HookRunner(loadedHooks, cwd, sessionManager, modelRegistry, settingsManager.getHookTimeout());
 		}
 	} else {
 		// Discover hooks, merging with additional paths
@@ -545,7 +545,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			console.error(`Failed to load hook "${path}": ${error}`);
 		}
 		if (hooks.length > 0) {
-			hookRunner = new HookRunner(hooks, cwd, settingsManager.getHookTimeout());
+			hookRunner = new HookRunner(hooks, cwd, sessionManager, modelRegistry, settingsManager.getHookTimeout());
 		}
 	}