topchester-ai 0.18.0 → 0.20.0

package/dist/cli.mjs

@@ -2212,7 +2212,7 @@ function killChild(pid, detached, signal) {
 const inspectCommandTool = defineTool({
 	name: "inspect_command",
 	description: "Run a narrowly validated read-only command for repository orientation.",
-	prompt: "inspect_command: run a safe read-only discovery command inside the workspace for quick orientation; prefer read_file, list_files, grep, and find_file for exact file tasks, and do not use it for builds, tests, installs, network, shell scripts, or edits. To use it, reply with only JSON: {\"tool\":\"inspect_command\",\"args\":{\"command\":\"pwd && rg --files docs/plans | head -20\",\"workdir\":\".\",\"timeout_ms\":10000}}",
+	prompt: "inspect_command: run a safe read-only discovery command inside the workspace for quick repo orientation; prefer read_file, list_files, grep, and find_file for exact file tasks, and do not use it for builds, tests, installs, network, shell scripts, edits, or user-requested specific commands such as node --version, which node, or pnpm --version. To use it, reply with only JSON: {\"tool\":\"inspect_command\",\"args\":{\"command\":\"pwd && rg --files docs/plans | head -20\",\"workdir\":\".\",\"timeout_ms\":10000}}",
 	argsSchema: inspectCommandArgsSchema,
 	execute: (context, args) => inspectWorkspaceCommand(context.workspaceRoot, args, { pathEnv: context.pathEnv })
 });
@@ -3259,8 +3259,8 @@ const runCommandArgsSchema = z.object({
 });
 const runCommandTool = defineTool({
 	name: "run_command",
-	description: "Run a strictly policy-approved project command inside the workspace.",
-	prompt: "run_command: run a project command only when strict policy allows it; prefer run_validator for tests, lint, typecheck, build, check, format-check, and smoke. To use it, reply with only JSON: {\"tool\":\"run_command\",\"args\":{\"command\":\"node scripts/check-fixtures.mjs\",\"workdir\":\".\",\"timeout_ms\":30000}}",
+	description: "Run a policy-gated command inside the workspace.",
+	prompt: "run_command: run a user-requested command when no more specific tool fits; it is the general policy-gated command runner, and runtime policy decides whether the command is allowed, rejected, or needs approval. Prefer run_validator for tests, lint, typecheck, build, check, format-check, and smoke. To use it, reply with only JSON: {\"tool\":\"run_command\",\"args\":{\"command\":\"node --version\",\"workdir\":\".\",\"timeout_ms\":30000}}",
 	argsSchema: runCommandArgsSchema,
 	requiresExclusiveWorkspace: true,
 	execute: async (context, args) => runWorkspaceCommand(context.workspaceRoot, args, context.config?.tools?.commands, context.runCommandApprovals?.allowExactCommands, context.pathEnv, context.abortSignal)
@@ -4452,6 +4452,45 @@ const commandPolicySchema = z.object({
 	allowExact: z.array(commandPatternSchema).optional().default([]),
 	deny: z.array(commandPatternSchema).optional().default([])
 }).strict();
+const hookEventNames = [
+	"SessionStart",
+	"UserPromptSubmit",
+	"PreToolUse",
+	"PostToolUse",
+	"PermissionRequest",
+	"PreCompact",
+	"Stop"
+];
+const hookEventAliasMap = {
+	TaskStart: "SessionStart",
+	TaskAcknowledge: "UserPromptSubmit",
+	UserActionRequired: "PermissionRequest",
+	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(),
+	PermissionRequest: z.array(hookHandlerSchema).optional(),
+	PreCompact: z.array(hookHandlerSchema).optional(),
+	Stop: z.array(hookHandlerSchema).optional()
+}).strict();
+const rawHooksConfigSchema = canonicalHooksConfigSchema.extend({
+	TaskStart: z.array(hookHandlerSchema).optional(),
+	TaskAcknowledge: z.array(hookHandlerSchema).optional(),
+	UserActionRequired: z.array(hookHandlerSchema).optional(),
+	TaskComplete: z.array(hookHandlerSchema).optional()
+}).strict();
 const topchesterConfigSchema = z.object({
 	models: z.object({
 		defaultPurpose: modelPurposeSchema.optional(),
@@ -4460,12 +4499,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 +4685,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 +4727,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 +4805,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 +8689,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",
@@ -8946,14 +9225,24 @@ function getChatSystemPrompt(options = {}) {
 		...canUseTool("list_files") && canUseTool("grep") && canUseTool("find_file") && canUseTool("read_file") ? ["- Use list_files, grep, find_file, and read_file for exact file listing, search, lookup, and reading tasks."] : [],
 		...canUseTool("git_status") && canUseTool("git_diff") && canUseTool("git_log") ? ["- Use git_status, git_diff, and git_log for Git state, diffs, and history. Prefer these over inspect_command for Git workflow inspection."] : [],
 		...canUseTool("git_add") && canUseTool("git_commit") ? ["- Use git_add and git_commit only when the user explicitly asks to stage or commit. Never stage unrelated files, never stage '.', and never commit unless staged paths exactly match the user's request."] : [],
-		...canUseTool("inspect_command") ? ["- Use inspect_command only for quick read-only repo orientation when a short familiar command chain is clearer than several dedicated tool calls.", "- inspect_command is not a shell. Unsafe commands, shell expansion, scripts, installs, builds, tests, network access, and file mutation are not available through it."] : [],
+		...canUseTool("inspect_command") ? [
+			"- Use inspect_command only for quick read-only repo orientation when the user did not ask to run a specific command and a short familiar command chain is clearer than several dedicated tool calls.",
+			"- inspect_command is not a shell. Unsafe commands, shell expansion, scripts, installs, builds, tests, network access, and file mutation are not available through it.",
+			canUseTool("run_command") ? "- Do not use inspect_command when the user asks to run a specific command such as node --version, which node, or pnpm --version; use run_command or run_validator instead." : ""
+		].filter(Boolean) : [],
 		...canUseTool("run_validator") ? [
 			"- After code edits, use run_validator when there is a relevant test, lint, typecheck, build, check, format-check, or smoke command that can prove the change.",
 			"- Failed run_validator exits are evidence. Read stdout and stderr, fix the issue when it is in scope, and rerun the narrowest useful validator.",
 			canUseTool("run_command") ? "- If run_validator is rejected because the command is not a strict validator shape but the user still needs command output, retry with run_command when project policy allows it." : "",
 			"- Do not use inspect_command for tests, builds, lint, typecheck, format checks, or smoke checks. Use run_validator for verification."
 		].filter(Boolean) : [],
-		...canUseTool("run_command") ? ["- Use run_command only for commands allowed by project command policy. Prefer dedicated read, edit, Git, and validator tools when they fit.", "- Do not use run_command for installs, deploys, network commands, destructive commands, interactive commands, file reads, file writes, Git inspection, or validation when run_validator can do it."] : [],
+		...canUseTool("run_command") ? [
+			"- When the user explicitly asks to run a command or asks for command output, use run_command unless a more specific tool is clearly the right fit.",
+			"- run_command is the general policy-gated command runner. Do not avoid it because a command might be disallowed; call run_command and let command policy return the allowed, rejected, or approval result.",
+			"- Prefer dedicated tools for file reads, file writes, edits, Git inspection, and searches.",
+			"- Use run_command only for commands allowed by project command policy. Prefer dedicated read, edit, Git, and validator tools when they fit.",
+			"- Do not use run_command for installs, deploys, network commands, destructive commands, interactive commands, file reads, file writes, Git inspection, or validation when run_validator can do it."
+		] : [],
 		...canUseTool("edit_file") && canUseTool("read_file") ? ["- Use read_file before editing a file so your edit is based on current file content and hash metadata."] : [],
 		...canUseTool("read_file") && (canUseTool("edit_file") || canUseTool("write_file")) ? ["- When passing expected_current_hash to edit_file or write_file, use the current pre-edit/pre-write hash from the latest read_file result for that exact file. Never invent it and never use a predicted after-edit or after-write hash."] : [],
 		...canUseTool("edit_file") ? ["- Use edit_file for targeted edits to existing files. Make multiple disjoint edits for the same file in one call when possible."] : [],
@@ -9578,6 +9867,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 +9900,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 +9926,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 +10050,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 +10069,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 +10103,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 +10164,86 @@ 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, toolCall.id, options, session, abortSignal);
+				for (const event of approval.events) yield event;
+				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,16 +10258,80 @@ var TopchesterAgentRuntime = class TopchesterAgentRuntime {
 		}
 		return events;
 	}
-	async resolveRunCommandApproval(call, options) {
+	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, toolCallId, options, session, abortSignal) {
 		const approvedCommands = [...this.approvedRunCommands];
 		if (call.tool !== "run_command") return {
 			cancelled: false,
-			approvedCommands
+			approvedCommands,
+			events: []
 		};
 		const parsed = runCommandArgsSchema.safeParse(call.args);
 		if (!parsed.success) return {
 			cancelled: false,
-			approvedCommands
+			approvedCommands,
+			events: []
 		};
 		const decision = await validateRunCommandPolicy(parsed.data, {
 			workspaceRoot: this.context.workspaceRoot,
@@ -9858,13 +10340,31 @@ var TopchesterAgentRuntime = class TopchesterAgentRuntime {
 		});
 		if (decision.allowed) return {
 			cancelled: false,
-			approvedCommands
+			approvedCommands,
+			events: []
 		};
 		if (!isRunCommandApprovalEligible(decision.reason) || !options.requestRunCommandApproval) return {
 			cancelled: false,
-			approvedCommands
+			approvedCommands,
+			events: []
 		};
 		const command = decision.commands[0] ?? parsed.data.command.trim();
+		const actionRequiredHook = await this.runHookEvent("PermissionRequest", this.createToolHookPayload("PermissionRequest", call, toolCallId, session, {
+			notification_type: "permission_prompt",
+			permission_mode: "",
+			command,
+			workdir: parsed.data.workdir,
+			reason: decision.reason
+		}), {
+			toolName: call.tool,
+			abortSignal
+		});
+		const events = this.hookResultToEvents(actionRequiredHook);
+		if (actionRequiredHook.blocked || actionRequiredHook.stopped) return {
+			cancelled: true,
+			reason: (actionRequiredHook.blocked ?? actionRequiredHook.stopped).message,
+			events
+		};
 		const approval = await options.requestRunCommandApproval({
 			command,
 			workdir: parsed.data.workdir,
@@ -9872,18 +10372,21 @@ var TopchesterAgentRuntime = class TopchesterAgentRuntime {
 		});
 		if (approval === "cancel") return {
 			cancelled: true,
-			reason: `run_command cancelled by user for '${command}'.`
+			reason: `run_command cancelled by user for '${command}'.`,
+			events
 		};
 		if (approval === "allow_session" || approval === "allow_repo") {
 			this.approvedRunCommands.add(command);
 			return {
 				cancelled: false,
-				approvedCommands: [...this.approvedRunCommands]
+				approvedCommands: [...this.approvedRunCommands],
+				events
 			};
 		}
 		return {
 			cancelled: false,
-			approvedCommands: [...approvedCommands, command]
+			approvedCommands: [...approvedCommands, command],
+			events
 		};
 	}
 	/**
@@ -10368,6 +10871,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 +11341,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 +11447,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 +11697,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 +11756,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 ?? {};