topchester-ai 0.18.0 → 0.19.0

package/dist/cli.mjs

@@ -4452,6 +4452,39 @@ const commandPolicySchema = z.object({
 	allowExact: z.array(commandPatternSchema).optional().default([]),
 	deny: z.array(commandPatternSchema).optional().default([])
 }).strict();
+const hookEventNames = [
+	"SessionStart",
+	"UserPromptSubmit",
+	"PreToolUse",
+	"PostToolUse",
+	"PreCompact",
+	"Stop"
+];
+const hookEventAliasMap = {
+	TaskStart: "SessionStart",
+	TaskComplete: "Stop"
+};
+const hookTimeoutMsSchema = z.number().int().positive().max(6e5);
+const hookMatcherSchema = z.union([z.string().min(1), z.array(z.string().min(1))]).optional();
+const hookHandlerSchema = z.object({
+	type: z.literal("command").optional(),
+	command: z.string().min(1),
+	timeoutMs: hookTimeoutMsSchema.optional(),
+	matcher: hookMatcherSchema
+}).strict();
+const canonicalHooksConfigSchema = z.object({
+	enabled: z.boolean().optional(),
+	SessionStart: z.array(hookHandlerSchema).optional(),
+	UserPromptSubmit: z.array(hookHandlerSchema).optional(),
+	PreToolUse: z.array(hookHandlerSchema).optional(),
+	PostToolUse: z.array(hookHandlerSchema).optional(),
+	PreCompact: z.array(hookHandlerSchema).optional(),
+	Stop: z.array(hookHandlerSchema).optional()
+}).strict();
+const rawHooksConfigSchema = canonicalHooksConfigSchema.extend({
+	TaskStart: z.array(hookHandlerSchema).optional(),
+	TaskComplete: z.array(hookHandlerSchema).optional()
+}).strict();
 const topchesterConfigSchema = z.object({
 	models: z.object({
 		defaultPurpose: modelPurposeSchema.optional(),
@@ -4460,12 +4493,14 @@ const topchesterConfigSchema = z.object({
 		providers: providersSchema.optional()
 	}).strict().optional(),
 	ignore: z.object({ paths: z.array(ignorePathSchema).optional() }).optional(),
-	tools: z.object({ commands: commandPolicySchema.optional() }).strict().optional()
+	tools: z.object({ commands: commandPolicySchema.optional() }).strict().optional(),
+	hooks: canonicalHooksConfigSchema.optional()
 });
 const rawTopchesterConfigSchema = z.object({
 	models: rawModelsSchema.optional(),
 	ignore: z.object({ paths: z.array(ignorePathSchema).optional() }).optional(),
-	tools: z.object({ commands: commandPolicySchema.optional() }).strict().optional()
+	tools: z.object({ commands: commandPolicySchema.optional() }).strict().optional(),
+	hooks: rawHooksConfigSchema.optional()
 });
 function getGlobalTopchesterConfigDir() {
 	return join(homedir(), ".config", "topchester");
@@ -4644,6 +4679,9 @@ function parseConfigFile(path, value) {
 	return parsed.data;
 }
 function normalizeConfigInput(value) {
+	return normalizeHooksConfigInput(normalizeModelsConfigInput(value));
+}
+function normalizeModelsConfigInput(value) {
 	if (!isPlainObject(value) || !isPlainObject(value.models)) return value;
 	const models = { ...value.models };
 	const providers = isPlainObject(models.providers) ? { ...models.providers } : {};
@@ -4683,6 +4721,22 @@ function normalizeConfigInput(value) {
 		}
 	};
 }
+function normalizeHooksConfigInput(value) {
+	if (!isPlainObject(value) || !isPlainObject(value.hooks)) return value;
+	const hooks = { ...value.hooks };
+	for (const [alias, canonical] of Object.entries(hookEventAliasMap)) {
+		const aliasHandlers = hooks[alias];
+		if (aliasHandlers === void 0) continue;
+		const canonicalHandlers = hooks[canonical];
+		if (!Array.isArray(aliasHandlers) || canonicalHandlers !== void 0 && !Array.isArray(canonicalHandlers)) continue;
+		hooks[canonical] = [...canonicalHandlers ?? [], ...aliasHandlers];
+		delete hooks[alias];
+	}
+	return {
+		...value,
+		hooks
+	};
+}
 function normalizeModelRef(ref, defaultProvider) {
 	if (typeof ref === "string") return parseModelRef(ref, defaultProvider);
 	if (!isPlainObject(ref) || typeof ref.name !== "string") return;
@@ -4745,7 +4799,7 @@ function isOpenAIProvider(providerId, baseURL) {
 function deepMerge(base, override, path = []) {
 	if (Array.isArray(base) && Array.isArray(override)) {
 		const joinedPath = path.join(".");
-		return joinedPath === "ignore.paths" || joinedPath === "tools.commands.allow" || joinedPath === "tools.commands.allowExact" || joinedPath === "tools.commands.deny" ? [...base, ...override] : override;
+		return joinedPath === "ignore.paths" || joinedPath === "tools.commands.allow" || joinedPath === "tools.commands.allowExact" || joinedPath === "tools.commands.deny" || path.length === 2 && path[0] === "hooks" && hookEventNames.includes(path[1]) ? [...base, ...override] : override;
 	}
 	if (!isPlainObject(base) || !isPlainObject(override)) return override;
 	const result = { ...base };
@@ -8629,6 +8683,225 @@ function isAbortError(error) {
 	return error.name === "AbortError" || error.message.toLowerCase().includes("aborted");
 }
 //#endregion
+//#region src/agent/hooks.ts
+const DEFAULT_HOOK_TIMEOUT_MS = 5e3;
+const MAX_CAPTURED_OUTPUT_CHARS = 64e3;
+const hookResponseSchema = z.object({
+	action: z.enum([
+		"continue",
+		"block",
+		"stop"
+	]).optional(),
+	decision: z.string().optional(),
+	cancel: z.boolean().optional(),
+	context: z.union([z.string(), z.array(z.string())]).optional(),
+	message: z.string().optional(),
+	feedback: z.string().optional(),
+	reason: z.string().optional()
+}).passthrough();
+async function runTopchesterHooks(context, event, payload, options = {}) {
+	const handlers = getConfiguredHookHandlers(context, event, options.toolName);
+	const result = {
+		contexts: [],
+		messages: [],
+		handlerCount: 0
+	};
+	for (const handler of handlers) {
+		result.handlerCount += 1;
+		const handlerResult = await runCommandHandler(context, event, payload, handler, options);
+		result.contexts.push(...handlerResult.contexts);
+		result.messages.push(...handlerResult.messages);
+		if (handlerResult.blocked) {
+			result.blocked = handlerResult.blocked;
+			break;
+		}
+		if (handlerResult.stopped) {
+			result.stopped = handlerResult.stopped;
+			break;
+		}
+	}
+	return result;
+}
+function formatHookContextsForPrompt(event, contexts) {
+	const normalized = contexts.map((context) => context.trim()).filter(Boolean);
+	if (normalized.length === 0) return "";
+	return [`Hook context from ${event}:`, ...normalized].join("\n\n");
+}
+function getConfiguredHookHandlers(context, event, toolName) {
+	const hooks = context.config.hooks;
+	if (!hooks || hooks.enabled === false) return [];
+	return (hooks[event] ?? []).filter((handler) => hookMatches(handler, event, toolName));
+}
+function hookMatches(handler, event, toolName) {
+	const matcher = handler.matcher;
+	if (matcher === void 0) return true;
+	const target = toolName ?? event;
+	return (Array.isArray(matcher) ? matcher : [matcher]).some((entry) => entry === "*" || entry === target);
+}
+async function runCommandHandler(context, event, payload, handler, options) {
+	const result = await runHookProcess(handler.command ?? "", payload, {
+		cwd: context.workspaceRoot,
+		timeoutMs: handler.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS,
+		abortSignal: options.abortSignal,
+		env: buildHookEnv(event, options.toolName)
+	});
+	logHookProcessResult(context, event, handler, result);
+	if (result.timedOut || result.aborted || result.spawnError || result.exitCode !== 0) return emptyHookRunResult();
+	const stdout = result.stdout.trim();
+	if (!stdout) return emptyHookRunResult();
+	let parsed;
+	try {
+		parsed = JSON.parse(stdout);
+	} catch (error) {
+		logHookWarning(context, {
+			event: "hook_response_parse_failed",
+			hookEventName: event,
+			error: error instanceof Error ? error.message : String(error),
+			stdoutLength: result.stdout.length
+		});
+		return emptyHookRunResult();
+	}
+	const response = hookResponseSchema.safeParse(parsed);
+	if (!response.success) {
+		logHookWarning(context, {
+			event: "hook_response_invalid",
+			hookEventName: event,
+			issues: response.error.issues.map((issue) => issue.message)
+		});
+		return emptyHookRunResult();
+	}
+	return normalizeHookResponse(event, response.data);
+}
+function normalizeHookResponse(event, response) {
+	const result = emptyHookRunResult();
+	const action = normalizeHookAction(event, response);
+	const message = firstNonEmpty(response.message, response.feedback, response.reason);
+	const contexts = Array.isArray(response.context) ? response.context : response.context ? [response.context] : [];
+	result.contexts.push(...contexts.filter((context) => context.trim().length > 0));
+	if (message) result.messages.push(message);
+	if (action === "block") result.blocked = { message: message || `Hook ${event} blocked the request.` };
+	else if (action === "stop") result.stopped = { message: message || `Hook ${event} stopped the turn.` };
+	return result;
+}
+function normalizeHookAction(event, response) {
+	if (response.cancel) return event === "Stop" ? "stop" : "block";
+	if (response.action) return response.action;
+	const decision = response.decision?.trim().toLowerCase();
+	if (decision === "block" || decision === "deny" || decision === "denied") return "block";
+	if (decision === "stop" || decision === "halt") return "stop";
+	return "continue";
+}
+function buildHookEnv(event, toolName) {
+	return {
+		...process.env,
+		TOPCHESTER_HOOK_EVENT: event,
+		TOPCHESTER_HOOK_TOOL: toolName ?? ""
+	};
+}
+async function runHookProcess(command, payload, options) {
+	const startedAt = Date.now();
+	const shell = process.env.SHELL || "/bin/sh";
+	return new Promise((resolve) => {
+		let stdout = "";
+		let stderr = "";
+		let settled = false;
+		let timedOut = false;
+		let aborted = false;
+		const child = spawn(shell, ["-lc", command], {
+			cwd: options.cwd,
+			env: options.env,
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		});
+		const finish = (partial) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeout);
+			options.abortSignal?.removeEventListener("abort", abort);
+			resolve({
+				stdout,
+				stderr,
+				exitCode: null,
+				signal: null,
+				timedOut,
+				aborted,
+				durationMs: Date.now() - startedAt,
+				...partial
+			});
+		};
+		const timeout = setTimeout(() => {
+			timedOut = true;
+			child.kill("SIGTERM");
+		}, options.timeoutMs);
+		const abort = () => {
+			aborted = true;
+			child.kill("SIGTERM");
+		};
+		if (options.abortSignal?.aborted) abort();
+		else options.abortSignal?.addEventListener("abort", abort, { once: true });
+		child.stdout?.setEncoding("utf8");
+		child.stderr?.setEncoding("utf8");
+		child.stdout?.on("data", (chunk) => {
+			stdout = appendCapped(stdout, chunk);
+		});
+		child.stderr?.on("data", (chunk) => {
+			stderr = appendCapped(stderr, chunk);
+		});
+		child.on("error", (error) => {
+			finish({ spawnError: error.message });
+		});
+		child.on("close", (exitCode, signal) => {
+			finish({
+				exitCode,
+				signal
+			});
+		});
+		child.stdin?.on("error", () => {});
+		child.stdin?.end(`${JSON.stringify(payload)}\n`);
+	});
+}
+function logHookProcessResult(context, event, handler, result) {
+	context.logger.debug({
+		event: "hook_run",
+		hookEventName: event,
+		handlerType: handler.type ?? "command",
+		matcher: handler.matcher,
+		exitCode: result.exitCode,
+		signal: result.signal,
+		timedOut: result.timedOut,
+		aborted: result.aborted,
+		spawnError: result.spawnError,
+		durationMs: result.durationMs,
+		stdoutLength: result.stdout.length,
+		stderrLength: result.stderr.length
+	}, "hook run");
+}
+function logHookWarning(context, payload) {
+	const logger = context.logger;
+	if (typeof logger.warn === "function") {
+		logger.warn(payload, "hook warning");
+		return;
+	}
+	context.logger.debug(payload, "hook warning");
+}
+function emptyHookRunResult() {
+	return {
+		contexts: [],
+		messages: [],
+		handlerCount: 0
+	};
+}
+function appendCapped(current, chunk) {
+	if (current.length >= MAX_CAPTURED_OUTPUT_CHARS) return current;
+	return `${current}${chunk}`.slice(0, MAX_CAPTURED_OUTPUT_CHARS);
+}
+function firstNonEmpty(...values) {
+	return values.find((value) => value !== void 0 && value.trim().length > 0);
+}
+//#endregion
 //#region src/agent/profiles.ts
 const READ_ONLY_TOOLS = [
 	"read_file",
@@ -9578,6 +9851,7 @@ var TopchesterAgentRuntime = class TopchesterAgentRuntime {
 	options;
 	taskPlan = createTaskPlanController();
 	approvedRunCommands = /* @__PURE__ */ new Set();
+	startedHookSessionKeys = /* @__PURE__ */ new Set();
 	/**
 	* Holds the shared application context for one runtime instance.
 	* The runtime does not own those dependencies; it coordinates the
@@ -9610,6 +9884,20 @@ var TopchesterAgentRuntime = class TopchesterAgentRuntime {
 	async checkKnowledgeBase() {
 		return getKnowledgeStatusEvents(await this.getKnowledgeStatusWithNonCleanFileCount());
 	}
+	async runSessionStartHooks(session, options = {}) {
+		const sessionKey = session?.sessionId ?? `workspace:${this.context.workspaceRoot}`;
+		if (this.startedHookSessionKeys.has(sessionKey)) return [];
+		this.startedHookSessionKeys.add(sessionKey);
+		const result = await this.runHookEvent("SessionStart", this.createBaseHookPayload("SessionStart", session, {
+			isResumed: Boolean(options.isResumed),
+			taskStartAlias: "TaskStart"
+		}), { abortSignal: options.abortSignal });
+		return this.hookResultToEvents(result);
+	}
+	async runPreCompactHooks(session, options = {}) {
+		const result = await this.runHookEvent("PreCompact", this.createBaseHookPayload("PreCompact", session, { reason: options.reason ?? "Compaction is about to start." }), { abortSignal: options.abortSignal });
+		return this.hookResultToEvents(result);
+	}
 	/**
 	* Streams one user chat turn through the agent loop. It builds the model
 	* prompt with relevant KB context, calls the model, executes any requested
@@ -9622,13 +9910,26 @@ var TopchesterAgentRuntime = class TopchesterAgentRuntime {
 	* ordered events.
 	*/
 	async *submitMessageStream(conversation, message, abortSignal, options = {}) {
-		let nextPrompt = await this.buildPromptWithKnowledgeContext(buildConversationPrompt(conversation, message), message);
+		const session = options.session ?? this.options.session;
+		for (const event of await this.runSessionStartHooks(session, { abortSignal })) yield event;
+		const userPromptHook = await this.runHookEvent("UserPromptSubmit", this.createBaseHookPayload("UserPromptSubmit", session, {
+			prompt: { text: message },
+			prompt_text: message,
+			user_prompt: message
+		}), { abortSignal });
+		for (const event of this.hookResultToEvents(userPromptHook)) yield event;
+		if (userPromptHook.blocked || userPromptHook.stopped) {
+			const interruption = userPromptHook.blocked ?? userPromptHook.stopped;
+			if (userPromptHook.messages.length === 0) yield agentEvent.systemMessage(interruption.message);
+			yield agentEvent.status("ready");
+			return;
+		}
+		let nextPrompt = this.appendHookContextsToPrompt(await this.buildPromptWithKnowledgeContext(buildConversationPrompt(conversation, message), message), "UserPromptSubmit", userPromptHook.contexts);
 		let totalDurationMs = 0;
 		const tokenUsageTotals = {};
 		const profile = this.options.profile ?? PRIMARY_AGENT_PROFILE;
 		const permissions = createToolPermissionView(profile, { deniedTools: this.options.parentPermissions?.deniedTools });
 		const tools = getProfileToolDefinitions(permissions);
-		const session = options.session ?? this.options.session;
 		const subagents = new SubagentManager({
 			context: this.context,
 			parentSession: session,
@@ -9733,7 +10034,9 @@ var TopchesterAgentRuntime = class TopchesterAgentRuntime {
 					}
 					yield agentEvent.taskPlan(this.taskPlan.update({ items: [] }));
 				}
-				yield agentEvent.assistantMessage(finalText.trim() || "I got an empty response from the model.", formatAgentMessageMeta(result.modelId, totalDurationMs, tokenUsageTotals));
+				const finalMessage = finalText.trim() || "I got an empty response from the model.";
+				yield agentEvent.assistantMessage(finalMessage, formatAgentMessageMeta(result.modelId, totalDurationMs, tokenUsageTotals));
+				for (const event of await this.runStopHookEvents(session, finalMessage, "completed", abortSignal)) yield event;
 				yield agentEvent.status("ready");
 				return;
 			}
@@ -9750,10 +10053,33 @@ var TopchesterAgentRuntime = class TopchesterAgentRuntime {
 			if (modelToolCalls.length > 1 && modelToolCalls.every((call) => call.tool === "task")) {
 				const taskCalls = modelToolCalls.map((call) => call);
 				const taskResults = [];
+				const postHookContexts = [];
 				for (let index = 0; index < taskCalls.length; index += DEFAULT_TASK_CONCURRENCY) {
 					const batch = taskCalls.slice(index, index + DEFAULT_TASK_CONCURRENCY);
+					const executableBatch = [];
+					for (let batchIndex = 0; batchIndex < batch.length; batchIndex += 1) {
+						const call = batch[batchIndex];
+						const resultIndex = index + batchIndex;
+						const preHook = await this.runPreToolUseHook(call, modelToolCalls[resultIndex]?.id, session, abortSignal);
+						for (const event of this.hookResultToEvents(preHook)) yield event;
+						if (preHook.stopped) {
+							if (preHook.messages.length === 0) yield agentEvent.systemMessage(preHook.stopped.message);
+							yield agentEvent.status("ready");
+							return;
+						}
+						if (preHook.blocked) {
+							taskResults[resultIndex] = createToolErrorResult(call.tool, preHook.blocked.message);
+							continue;
+						}
+						executableBatch.push({
+							call,
+							resultIndex,
+							toolCallId: modelToolCalls[resultIndex]?.id
+						});
+					}
+					if (executableBatch.length === 0) continue;
 					const taskEventQueue = createRuntimeEventQueue();
-					const batchResultPromise = Promise.all(batch.map((call, batchIndex) => executeToolCall(this.context.workspaceRoot, call, {
+					const batchResultPromise = Promise.all(executableBatch.map((entry) => executeToolCall(this.context.workspaceRoot, entry.call, {
 						logger: this.context.logger,
 						config: this.context.config,
 						taskPlan: this.taskPlan,
@@ -9761,22 +10087,60 @@ var TopchesterAgentRuntime = class TopchesterAgentRuntime {
 						permissions,
 						subagents,
 						abortSignal,
-						toolCallId: modelToolCalls[index + batchIndex]?.id,
+						toolCallId: entry.toolCallId,
 						eventSink: (event) => taskEventQueue.push(event)
 					}))).finally(() => {
 						taskEventQueue.close();
 					});
 					for await (const event of taskEventQueue) yield event;
-					taskResults.push(...await batchResultPromise);
+					const batchResults = await batchResultPromise;
+					for (let batchIndex = 0; batchIndex < executableBatch.length; batchIndex += 1) {
+						const entry = executableBatch[batchIndex];
+						taskResults[entry.resultIndex] = batchResults[batchIndex];
+					}
+				}
+				for (let index = 0; index < taskCalls.length; index += 1) {
+					const call = taskCalls[index];
+					const toolResult = taskResults[index];
+					yield agentEvent.toolCall(call, formatToolCallMessage(call, toolResult));
+					const postHook = await this.runPostToolUseHook(call, modelToolCalls[index]?.id, toolResult, session, abortSignal);
+					for (const event of this.hookResultToEvents(postHook)) yield event;
+					postHookContexts.push(...postHook.contexts);
+					if (postHook.stopped) {
+						if (postHook.messages.length === 0) yield agentEvent.systemMessage(postHook.stopped.message);
+						yield agentEvent.status("ready");
+						return;
+					}
 				}
-				for (let index = 0; index < taskCalls.length; index += 1) yield agentEvent.toolCall(taskCalls[index], formatToolCallMessage(taskCalls[index], taskResults[index]));
 				afterTool = "task";
-				nextPrompt = `${nextPrompt}\n\n${taskResults.map((toolResult) => formatToolResultForPrompt(toolResult)).join("\n\n")}\n\n${formatContinuationInstruction(result.toolProtocol, taskResults.at(-1), isToolAllowed(permissions, "plan_todo"))}`;
+				nextPrompt = this.appendHookContextsToPrompt(`${nextPrompt}\n\n${taskResults.map((toolResult) => formatToolResultForPrompt(toolResult)).join("\n\n")}\n\n${formatContinuationInstruction(result.toolProtocol, taskResults.at(-1), isToolAllowed(permissions, "plan_todo"))}`, "PostToolUse", postHookContexts);
 				continue;
 			}
 			if (modelToolCalls.length > 1 && modelToolCalls.every((call) => isParallelSafeToolName(call.tool))) {
 				const parallelCalls = modelToolCalls.map((call) => call);
-				const parallelResults = await Promise.all(parallelCalls.map((call, index) => executeToolCall(this.context.workspaceRoot, call, {
+				const parallelResults = [];
+				const executableCalls = [];
+				const postHookContexts = [];
+				for (let index = 0; index < parallelCalls.length; index += 1) {
+					const call = parallelCalls[index];
+					const preHook = await this.runPreToolUseHook(call, modelToolCalls[index]?.id, session, abortSignal);
+					for (const event of this.hookResultToEvents(preHook)) yield event;
+					if (preHook.stopped) {
+						if (preHook.messages.length === 0) yield agentEvent.systemMessage(preHook.stopped.message);
+						yield agentEvent.status("ready");
+						return;
+					}
+					if (preHook.blocked) {
+						parallelResults[index] = createToolErrorResult(call.tool, preHook.blocked.message);
+						continue;
+					}
+					executableCalls.push({
+						call,
+						resultIndex: index,
+						toolCallId: modelToolCalls[index]?.id
+					});
+				}
+				const executedResults = await Promise.all(executableCalls.map((entry) => executeToolCall(this.context.workspaceRoot, entry.call, {
 					logger: this.context.logger,
 					config: this.context.config,
 					taskPlan: this.taskPlan,
@@ -9784,48 +10148,85 @@ var TopchesterAgentRuntime = class TopchesterAgentRuntime {
 					permissions,
 					subagents,
 					abortSignal,
-					toolCallId: modelToolCalls[index]?.id
+					toolCallId: entry.toolCallId
 				})));
-				for (let index = 0; index < parallelCalls.length; index += 1) yield agentEvent.toolCall(parallelCalls[index], formatToolCallMessage(parallelCalls[index], parallelResults[index]));
+				for (let index = 0; index < executableCalls.length; index += 1) {
+					const entry = executableCalls[index];
+					parallelResults[entry.resultIndex] = executedResults[index];
+				}
+				for (let index = 0; index < parallelCalls.length; index += 1) {
+					const call = parallelCalls[index];
+					const toolResult = parallelResults[index];
+					yield agentEvent.toolCall(call, formatToolCallMessage(call, toolResult));
+					const postHook = await this.runPostToolUseHook(call, modelToolCalls[index]?.id, toolResult, session, abortSignal);
+					for (const event of this.hookResultToEvents(postHook)) yield event;
+					postHookContexts.push(...postHook.contexts);
+					if (postHook.stopped) {
+						if (postHook.messages.length === 0) yield agentEvent.systemMessage(postHook.stopped.message);
+						yield agentEvent.status("ready");
+						return;
+					}
+				}
 				afterTool = parallelCalls.at(-1)?.tool;
-				nextPrompt = `${nextPrompt}\n\n${parallelResults.map((toolResult) => formatToolResultForPrompt(toolResult)).join("\n\n")}\n\n${formatContinuationInstruction(result.toolProtocol, parallelResults.at(-1), isToolAllowed(permissions, "plan_todo"))}`;
+				nextPrompt = this.appendHookContextsToPrompt(`${nextPrompt}\n\n${parallelResults.map((toolResult) => formatToolResultForPrompt(toolResult)).join("\n\n")}\n\n${formatContinuationInstruction(result.toolProtocol, parallelResults.at(-1), isToolAllowed(permissions, "plan_todo"))}`, "PostToolUse", postHookContexts);
 				continue;
 			}
 			const executableToolCall = toolCall;
 			const suppressiblePlanTodoAnswer = getSuppressiblePlanTodoAnswer(executableToolCall, result.text, this.taskPlan.get());
 			if (suppressiblePlanTodoAnswer !== void 0) {
-				yield agentEvent.assistantMessage(suppressiblePlanTodoAnswer || "I got an empty response from the model.", formatAgentMessageMeta(result.modelId, totalDurationMs, tokenUsageTotals));
+				const finalMessage = suppressiblePlanTodoAnswer || "I got an empty response from the model.";
+				yield agentEvent.assistantMessage(finalMessage, formatAgentMessageMeta(result.modelId, totalDurationMs, tokenUsageTotals));
+				for (const event of await this.runStopHookEvents(session, finalMessage, "completed", abortSignal)) yield event;
 				yield agentEvent.status("ready");
 				return;
 			}
-			const approval = await this.resolveRunCommandApproval(executableToolCall, options);
+			const preHook = await this.runPreToolUseHook(executableToolCall, toolCall.id, session, abortSignal);
+			for (const event of this.hookResultToEvents(preHook)) yield event;
 			let toolResult;
-			if (approval.cancelled) toolResult = createToolErrorResult(executableToolCall.tool, approval.reason);
+			if (preHook.stopped) {
+				if (preHook.messages.length === 0) yield agentEvent.systemMessage(preHook.stopped.message);
+				yield agentEvent.status("ready");
+				return;
+			}
+			if (preHook.blocked) toolResult = createToolErrorResult(executableToolCall.tool, preHook.blocked.message);
 			else {
-				const toolEventQueue = createRuntimeEventQueue();
-				const toolResultPromise = executeToolCall(this.context.workspaceRoot, executableToolCall, {
-					logger: this.context.logger,
-					config: this.context.config,
-					runCommandApprovals: { allowExactCommands: approval.approvedCommands },
-					taskPlan: this.taskPlan,
-					profile,
-					permissions,
-					subagents,
-					abortSignal,
-					toolCallId: toolCall.id,
-					eventSink: (event) => toolEventQueue.push(event)
-				}).finally(() => {
-					toolEventQueue.close();
-				});
-				for await (const event of toolEventQueue) yield event;
-				toolResult = await toolResultPromise;
+				const approval = await this.resolveRunCommandApproval(executableToolCall, options);
+				if (approval.cancelled) toolResult = createToolErrorResult(executableToolCall.tool, approval.reason);
+				else {
+					const toolEventQueue = createRuntimeEventQueue();
+					const toolResultPromise = executeToolCall(this.context.workspaceRoot, executableToolCall, {
+						logger: this.context.logger,
+						config: this.context.config,
+						runCommandApprovals: { allowExactCommands: approval.approvedCommands },
+						taskPlan: this.taskPlan,
+						profile,
+						permissions,
+						subagents,
+						abortSignal,
+						toolCallId: toolCall.id,
+						eventSink: (event) => toolEventQueue.push(event)
+					}).finally(() => {
+						toolEventQueue.close();
+					});
+					for await (const event of toolEventQueue) yield event;
+					toolResult = await toolResultPromise;
+				}
 			}
 			yield agentEvent.toolCall(executableToolCall, formatToolCallMessage(executableToolCall, toolResult));
 			if (!isToolErrorResult(toolResult) && toolResult.tool === "plan_todo") yield agentEvent.taskPlan(toolResult.plan);
+			const postHook = await this.runPostToolUseHook(executableToolCall, toolCall.id, toolResult, session, abortSignal);
+			for (const event of this.hookResultToEvents(postHook)) yield event;
+			if (postHook.stopped) {
+				if (postHook.messages.length === 0) yield agentEvent.systemMessage(postHook.stopped.message);
+				yield agentEvent.status("ready");
+				return;
+			}
 			afterTool = executableToolCall.tool;
-			nextPrompt = `${nextPrompt}\n\n${formatToolResultForPrompt(toolResult)}\n\n${formatContinuationInstruction(result.toolProtocol, toolResult, isToolAllowed(permissions, "plan_todo"))}`;
+			nextPrompt = this.appendHookContextsToPrompt(`${nextPrompt}\n\n${formatToolResultForPrompt(toolResult)}\n\n${formatContinuationInstruction(result.toolProtocol, toolResult, isToolAllowed(permissions, "plan_todo"))}`, "PostToolUse", postHook.contexts);
 		}
-		yield agentEvent.assistantMessage("I stopped because the tool loop ended unexpectedly.", formatAgentMessageMeta(lastModelId, totalDurationMs, tokenUsageTotals));
+		const finalMessage = "I stopped because the tool loop ended unexpectedly.";
+		yield agentEvent.assistantMessage(finalMessage, formatAgentMessageMeta(lastModelId, totalDurationMs, tokenUsageTotals));
+		for (const event of await this.runStopHookEvents(session, finalMessage, "failed", abortSignal)) yield event;
 		yield agentEvent.status("ready");
 	}
 	/**
@@ -9840,6 +10241,68 @@ var TopchesterAgentRuntime = class TopchesterAgentRuntime {
 		}
 		return events;
 	}
+	async runPreToolUseHook(call, toolCallId, session, abortSignal) {
+		return this.runHookEvent("PreToolUse", this.createToolHookPayload("PreToolUse", call, toolCallId, session), {
+			toolName: call.tool,
+			abortSignal
+		});
+	}
+	async runPostToolUseHook(call, toolCallId, result, session, abortSignal) {
+		return this.runHookEvent("PostToolUse", this.createToolHookPayload("PostToolUse", call, toolCallId, session, { result }), {
+			toolName: call.tool,
+			abortSignal
+		});
+	}
+	async runStopHookEvents(session, finalMessage, status, abortSignal) {
+		const result = await this.runHookEvent("Stop", this.createBaseHookPayload("Stop", session, {
+			taskCompleteAlias: "TaskComplete",
+			finalMessage,
+			status
+		}), { abortSignal });
+		return this.hookResultToEvents(result);
+	}
+	async runHookEvent(event, payload, options = {}) {
+		return runTopchesterHooks(this.context, event, payload, options);
+	}
+	createBaseHookPayload(event, session, extra = {}) {
+		return {
+			hook_event_name: event,
+			event,
+			cwd: this.context.workspaceRoot,
+			workspaceRoot: this.context.workspaceRoot,
+			source: "topchester",
+			...session ? {
+				session_id: session.sessionId,
+				sessionId: session.sessionId,
+				session: {
+					sessionId: session.sessionId,
+					rootSessionId: session.metadata.rootSessionId,
+					parentSessionId: session.metadata.parentSessionId,
+					source: session.metadata.source
+				}
+			} : {},
+			...extra
+		};
+	}
+	createToolHookPayload(event, call, toolCallId, session, extra = {}) {
+		return this.createBaseHookPayload(event, session, {
+			tool_name: call.tool,
+			tool_input: call.args,
+			tool: {
+				name: call.tool,
+				input: call.args,
+				...toolCallId ? { callId: toolCallId } : {}
+			},
+			...extra
+		});
+	}
+	hookResultToEvents(result) {
+		return result.messages.map((message) => agentEvent.systemMessage(message));
+	}
+	appendHookContextsToPrompt(prompt, event, contexts) {
+		const hookContext = formatHookContextsForPrompt(event, contexts);
+		return hookContext ? `${prompt}\n\n${hookContext}` : prompt;
+	}
 	async resolveRunCommandApproval(call, options) {
 		const approvedCommands = [...this.approvedRunCommands];
 		if (call.tool !== "run_command") return {
@@ -10368,6 +10831,7 @@ var TopchesterTuiShell = class {
 		const isResumed = this.options.session !== void 0;
 		const messages = this.options.initialMessages ?? getStartupThreadMessages(this.context);
 		if (!isResumed) await persistMessagesWithWarning(session, messages, messages);
+		await this.appendStartupRuntimeEvents(session, messages, await this.runtime.runSessionStartHooks?.(session, { isResumed }) ?? []);
 		const folderName = getFolderName(this.context.workspaceRoot);
 		const modelLabel = getModelLabel(this.context);
 		if (!process.stdin.isTTY || !process.stdout.isTTY) {
@@ -10837,10 +11301,24 @@ var TopchesterTuiShell = class {
 		this.session = session;
 		this.sessionStartedAt = Date.now();
 		await persistMessagesWithWarning(session, messages, messages);
+		await this.appendStartupRuntimeEvents(session, messages, await this.runtime.runSessionStartHooks?.(session, { isResumed: false }) ?? []);
 		app.resetForNewSession(messages);
 		tui.requestRender();
 		await this.checkAgent(app, tui);
 	}
+	async appendStartupRuntimeEvents(session, messages, events) {
+		for (const event of events) {
+			messages.push(...renderRuntimeEvent(event));
+			const payload = runtimeEventToSessionPayload(event);
+			if (!payload) continue;
+			try {
+				await session.append(payload);
+			} catch (error) {
+				messages.push(systemMessage(`Session save failed: ${formatPlainError(error)}`));
+				return;
+			}
+		}
+	}
 	async applyRuntimeEvents(app, events, renderRequester) {
 		for (const event of events) {
 			if (event.type === "status") app.setStatus(event.status);
@@ -10929,6 +11407,16 @@ async function executeRunCommand(context, options) {
 	});
 	try {
 		if (!options.resume) await persistStartupMessages(session, runContext);
+		await applyRuntimeEvents({
+			events: await runtime.runSessionStartHooks(session, {
+				isResumed: Boolean(options.resume),
+				abortSignal: abortController.signal
+			}),
+			session,
+			jsonEvents,
+			runId,
+			plain: !options.json
+		});
 		await applyRuntimeEvents({
 			events: await runtime.checkKnowledgeBase(),
 			session,
@@ -11169,15 +11657,6 @@ program.command("dev").description("start local development mode").action(() =>
 	console.log("Topchester local dev mode");
 	printStartupSummary(context);
 });
-program.command("update").alias("upgrade").description("update Topchester with the package manager that installed it").argument("[target]", "version or npm dist tag to install", "latest").action(async (target) => {
-	try {
-		const command = await runSelfUpdate({ target });
-		console.log(formatSelfUpdateSuccess(command).join("\n"));
-	} catch (error) {
-		console.error(formatStartupError(error));
-		process.exitCode = 1;
-	}
-});
 program.command("run").description("run one prompt or slash command without opening the TUI").argument("<prompt...>", "prompt text or slash command").option("--model <model>", "override the agent.primary model for this run").option("--timeout <ms>", "timeout for the run in milliseconds", parsePositiveInteger).option("--json", "write JSONL run events to stdout").option("--output-json <path>", "write JSONL run events to a file").action(async (promptParts, options) => {
 	const context = createContextFromOptions();
 	const globalOptions = program.opts();
@@ -11237,6 +11716,15 @@ kbCommand.command("status").description("show project files that are not current
 	const result = await ui.spinner("Checking KB file status...", async () => filterNonCleanKnowledgeCompileResult(await dryRunKnowledgeCompile(context.workspaceRoot, { config: context.config })));
 	console.log(formatKnowledgeCompileStatusResult(result, { formatSyncStatus: formatDryRunSyncStatus }).join("\n"));
 });
+program.command("update").alias("upgrade").description("update Topchester with the package manager that installed it").argument("[target]", "version or npm dist tag to install", "latest").action(async (target) => {
+	try {
+		const command = await runSelfUpdate({ target });
+		console.log(formatSelfUpdateSuccess(command).join("\n"));
+	} catch (error) {
+		console.error(formatStartupError(error));
+		process.exitCode = 1;
+	}
+});
 await program.parseAsync();
 function printStartupSummary(context) {
 	const assignments = context.config.models?.assignments ?? {};