agent-base-kit 0.1.0 → 0.3.0

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { Buffer } from "node:buffer";
 import { homedir } from "node:os";
@@ -40,7 +40,8 @@ const SELECTED_BY = {
 		"write",
 		"edit",
 		"patch"
-	]
+	],
+	tool: []
 };
 const KIND_OF_TOOL = new Map(Object.values(TOOLS).flatMap((tools) => Object.entries(tools)));
 function selected(agent, kinds) {
@@ -56,15 +57,36 @@ function matcherFor(agent, kinds) {
 }
 function requireMatcher(agent, plugin) {
 	const tools = selected(agent, plugin.kinds);
-	if (tools.length === 0) throw new Error(`${plugin.name} checks ${plugin.kinds.join(", ")} calls, which ${AGENTS[agent].label} does not make`);
+	if (tools.length === 0 && plugin.tools.length === 0) throw new Error(`${plugin.name} checks ${plugin.kinds.join(", ")} calls, which ${AGENTS[agent].label} does not make`);
 	const unseen = tools.filter(([, kind]) => !plugin.kinds.includes(kind)).map(([tool]) => tool);
 	if (unseen.length > 0) throw new Error(`${AGENTS[agent].label} sends file changes as ${unseen.join(", ")}, which ${plugin.name} does not take; add 'patch' to its kinds`);
-	return tools.map(([tool]) => tool).join("|");
+	return [...tools.map(([tool]) => tool), ...plugin.tools].join("|");
 }
+const hookFlags = (event, agent) => `--event ${event} --agent ${agent}`;
 // src/claude-plugin.ts
 const MARKETPLACE_NAME = /^[a-z0-9][\w.-]*$/i;
 const RESERVED = /^(?:claude|anthropics?)(?:-|$)|^cc-plugin-|(?:claude|anthropic)s?-?official|official-?(?:claude|anthropic)/;
 const ENTRY = /^[\w-][\w.-]*(?:\/[\w-][\w.-]*)*\.mjs$/;
+function pluginHooks(plugin, matcher, entry) {
+	const command = (event) => `node "\${CLAUDE_PLUGIN_ROOT}/${entry}" hook ${hookFlags(event, "claude")}`;
+	const hooks = { PreToolUse: [{
+		matcher,
+		hooks: [{
+			type: "command",
+			command: `${command("PreToolUse")} || exit 2`,
+			timeout: plugin.timeout,
+			statusMessage: plugin.statusMessage,
+			onFailure: "block"
+		}]
+	}] };
+	for (const [event, hook] of Object.entries(plugin.events)) hooks[event] = [{ hooks: [{
+		type: "command",
+		command: command(event),
+		timeout: hook.timeout,
+		statusMessage: hook.statusMessage
+	}] }];
+	return hooks;
+}
 const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
 function entryOf(entry) {
 	const relative = entry.replace(/^\.\//, "");
@@ -76,10 +98,12 @@ function entryOf(entry) {
 * to the package root: `.claude-plugin/plugin.json`, `hooks/hooks.json`, and
 * with `marketplace`, `.claude-plugin/marketplace.json`.
 *
-* The hook runs `node "${CLAUDE_PLUGIN_ROOT}/<entry>" hook || exit 2` with
-* `onFailure: "block"`, so a plugin that cannot start or times out blocks the
-* call. Claude Code copies the plugin and installs nothing into it, so the
-* entry's directory must hold the whole build. Throws when the plugin checks
+* The PreToolUse hook runs `node "${CLAUDE_PLUGIN_ROOT}/<entry>" hook --event
+* PreToolUse --agent claude || exit 2` with `onFailure: "block"`, so a plugin that cannot start or times out blocks
+* the call; each of the plugin's other events runs the same command, naming
+* its own event, without either, so it passes instead. Claude Code copies the plugin and installs
+* nothing into it, and the plugin's `onInstall` does not run, so the entry's
+* directory must hold the whole build. Throws when the plugin checks
 * no tool Claude Code has, or a field would make Claude Code refuse the
 * plugin.
 */
@@ -100,16 +124,7 @@ function claudePluginFiles(options) {
 			license,
 			keywords
 		}),
-		"hooks/hooks.json": json({ hooks: { PreToolUse: [{
-			matcher,
-			hooks: [{
-				type: "command",
-				command: `node "\${CLAUDE_PLUGIN_ROOT}/${entry}" hook || exit 2`,
-				timeout: plugin.timeout,
-				statusMessage: plugin.statusMessage,
-				onFailure: "block"
-			}]
-		}] } })
+		"hooks/hooks.json": json({ hooks: pluginHooks(plugin, matcher, entry) })
 	};
 	if (marketplace) {
 		if (!MARKETPLACE_NAME.test(marketplace.name)) throw new TypeError(`marketplace name ${JSON.stringify(marketplace.name)} may hold only letters, digits, '.', '_' and '-', and must start with a letter or digit`);
@@ -144,6 +159,9 @@ function writeClaudePlugin(dir, options) {
 	});
 }
 // src/hook.ts
+const OPEN_EVENTS = ["Stop", "UserPromptSubmit"];
+const EVENTS$2 = ["PreToolUse", ...OPEN_EVENTS];
+const isOpen = (event) => OPEN_EVENTS.includes(event);
 const isObject$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 function stringField(input, key) {
 	const value = input[key];
@@ -161,9 +179,30 @@ function editList(input) {
 	if (!Array.isArray(edits)) throw new TypeError("edits is not a list");
 	return edits.map((edit) => record(edit, "edit"));
 }
-function toToolCall(tool, input) {
+function toToolCalls(plugin, tool, input) {
+	if (tool !== "MultiEdit") return [toToolCall(plugin, tool, input)];
+	const path = stringField(input, "file_path");
+	const edits = editList(input);
+	if (edits.length === 0) return [{
+		kind: "edit",
+		path,
+		before: "",
+		after: ""
+	}];
+	return edits.map((edit) => ({
+		kind: "edit",
+		path,
+		before: stringField(edit, "old_string"),
+		after: stringField(edit, "new_string")
+	}));
+}
+function toToolCall(plugin, tool, input) {
+	if (plugin.tools.includes(tool)) return {
+		kind: "tool",
+		name: tool,
+		input
+	};
 	const text = (key, from = input) => stringField(from, key);
-	const joined = (key) => editList(input).map((edit) => text(key, edit)).join("\n");
 	switch (tool) {
 		case "Bash": return {
 			kind: "shell",
@@ -185,12 +224,6 @@ function toToolCall(tool, input) {
 			before: text("old_string"),
 			after: text("new_string")
 		};
-		case "MultiEdit": return {
-			kind: "edit",
-			path: text("file_path"),
-			before: joined("old_string"),
-			after: joined("new_string")
-		};
 		case "apply_patch": return {
 			kind: "patch",
 			patch: text("command") || text("input") || text("patch")
@@ -206,31 +239,105 @@ function verdictOf(value) {
 	};
 	throw new TypeError("check returned neither { block: false } nor { block: true, reason }");
 }
+const messageOf = (error) => error instanceof Error ? error.message : String(error);
+/**
+* The event a hook payload is for when it names one the hook lets pass on a
+* fault, else `undefined`. Read before the Node.js check and the hang guard,
+* which must not block these either.
+*/
+function openEventOf(stdin) {
+	try {
+		const event = JSON.parse(stdin)?.hook_event_name;
+		return OPEN_EVENTS.find((open) => open === event);
+	} catch {
+		return;
+	}
+}
 /**
-* Runs one PreToolUse call through the plugin and returns the exit code the
-* agent reads: 2 blocks the call, 0 lets it run.
+* Whether a fault lets the event pass: the named event when the command names
+* one, else the event the payload names.
+*/
+function passesOnFault(event, stdin) {
+	return event === void 0 ? openEventOf(stdin) !== void 0 : isOpen(event);
+}
+function payloadOf(stdin) {
+	const payload = JSON.parse(stdin);
+	if (!isObject$1(payload)) throw new TypeError("payload is not an object");
+	return payload;
+}
+async function runOpenEvent(plugin, event, read, options) {
+	if (!plugin.events[event]) return 0;
+	const stderr = options.stderr ?? ((text) => void process.stderr.write(text));
+	const stdout = options.stdout ?? ((text) => void process.stdout.write(text));
+	try {
+		const payload = read();
+		if (payload.hook_event_name !== void 0 && payload.hook_event_name !== event) throw new TypeError(`hook_event_name ${JSON.stringify(payload.hook_event_name)} is not ${event}`);
+		if (options.agent !== void 0 && options.agent !== "claude" && options.agent !== "codex") throw new TypeError(`agent ${JSON.stringify(options.agent)} is neither claude nor codex`);
+		if (event === "Stop" && payload.stop_hook_active === true) return 0;
+		const cwd = stringField(payload, "cwd") || (options.cwd ?? process.cwd());
+		const verdict = event === "Stop" ? verdictOf(await plugin.events.Stop.check({ reply: stringField(payload, "last_assistant_message") }, { cwd })) : verdictOf(await plugin.events.UserPromptSubmit.check({ prompt: stringField(payload, "prompt") }, { cwd }));
+		if (!verdict.block) return 0;
+		const codex = options.agent === void 0 ? payload.turn_id !== void 0 : options.agent === "codex";
+		const hidden = event === "UserPromptSubmit" && plugin.events.UserPromptSubmit.hidePrompt && !codex;
+		stdout(`${JSON.stringify({
+			decision: "block",
+			reason: verdict.reason,
+			...hidden ? { hookSpecificOutput: {
+				hookEventName: "UserPromptSubmit",
+				suppressOriginalPrompt: true
+			} } : {}
+		})}\n`);
+	} catch (error) {
+		stderr(`${plugin.name} could not check the ${event === "Stop" ? "reply" : "prompt"}, so it let it pass: ${messageOf(error)}\n`);
+	}
+	return 0;
+}
+/**
+* Runs one hook payload through the plugin and returns the exit code the
+* agent reads.
+*
+* A PreToolUse call returns 2 to block it and 0 to let it run, and fails
+* closed: a payload that is not JSON or names no tool, a field of the wrong
+* shape, a check that throws or rejects, and a result that is not a verdict
+* all return 2 with the error on stderr, because any other exit lets the call
+* run unchecked. A tool the plugin did not ask for returns 0 without calling
+* the check. A MultiEdit calls the check once per edit and blocks on the first
+* edit it blocks. A payload with no `hook_event_name` is read as PreToolUse;
+* one naming any event other than PreToolUse, Stop or UserPromptSubmit, or
+* a `hook_event_name` that is not a string, returns 2.
 *
-* It fails closed. A payload that is not JSON or names no tool, a field of the
-* wrong shape, a check that throws or rejects, and a result that is not a
-* verdict all return 2 with the error on stderr, because any other exit lets
-* the call run unchecked. A tool the plugin did not ask for returns 0 without
-* calling the check.
+* Stop and UserPromptSubmit always return 0. A block goes to stdout as
+* `{"decision":"block","reason":…}`, and a fault to stderr, letting the event
+* pass. A Stop with `stop_hook_active` set passes unchecked, and so does an
+* event the plugin has no check for.
+*
+* With `options.event`, the event is the one named, not the payload's: a
+* Stop or UserPromptSubmit returns 0 on any fault, a payload that is not JSON
+* included, and a payload naming another event is a fault for that event.
 */
 async function runHook(plugin, stdin, options = {}) {
 	const stderr = options.stderr ?? ((text) => void process.stderr.write(text));
+	if (isOpen(options.event)) return runOpenEvent(plugin, options.event, () => payloadOf(stdin), options);
 	let verdict;
 	try {
-		const payload = JSON.parse(stdin);
-		if (!isObject$1(payload)) throw new TypeError("payload is not an object");
+		if (options.event !== void 0 && !EVENTS$2.includes(options.event)) throw new TypeError(`event ${JSON.stringify(options.event)} is not an event the hook runs`);
+		const payload = payloadOf(stdin);
+		const event = payload.hook_event_name;
+		if (options.event === void 0 && isOpen(event)) return runOpenEvent(plugin, event, () => payload, options);
+		if (event !== void 0 && event !== "PreToolUse") throw new TypeError(`hook_event_name ${JSON.stringify(event)} is not ${options.event ?? "an event the hook runs"}`);
 		const tool = payload.tool_name;
 		if (typeof tool !== "string" || tool === "") throw new TypeError("tool_name is not a tool name");
-		const kind = KIND_OF_TOOL.get(tool);
+		const kind = plugin.tools.includes(tool) ? "tool" : KIND_OF_TOOL.get(tool);
 		if (kind === void 0 || !plugin.kinds.includes(kind)) return 0;
-		const call = toToolCall(tool, record(payload.tool_input, "tool_input"));
+		const calls = toToolCalls(plugin, tool, record(payload.tool_input, "tool_input"));
 		const cwd = stringField(payload, "cwd") || (options.cwd ?? process.cwd());
-		verdict = verdictOf(await plugin.check(call, { cwd }));
+		verdict = { block: false };
+		for (const call of calls) {
+			verdict = verdictOf(await plugin.check(call, { cwd }));
+			if (verdict.block) break;
+		}
 	} catch (error) {
-		stderr(`Blocked by ${plugin.name}, it could not check the call: ${error instanceof Error ? error.message : String(error)}\n`);
+		stderr(`Blocked by ${plugin.name}, it could not check the call: ${messageOf(error)}\n`);
 		return 2;
 	}
 	if (!verdict.block) return 0;
@@ -238,6 +345,11 @@ async function runHook(plugin, stdin, options = {}) {
 	return 2;
 }
 // src/install.ts
+const EVENTS$1 = [
+	"PreToolUse",
+	"Stop",
+	"UserPromptSubmit"
+];
 /** The agent config a scope writes: `~/.claude/settings.json`, `<cwd>/.codex/hooks.json` and so on. */
 function configFile(agent, scope, place) {
 	const { dir, file } = AGENTS[agent];
@@ -246,8 +358,31 @@ function configFile(agent, scope, place) {
 const quote = (word) => `'${word.replaceAll("'", `'\\''`)}'`;
 const escape = (text) => text.replace(/[$()*+.?[\\\]^{|}]/g, "\\$&");
 function hookCommand(plugin, scope, script, node) {
-	if (scope === "project") return `npx --no-install ${plugin.packageName} hook || exit 2`;
-	return `n=${quote(node)}; [ -x "$n" ] || n=node; "$n" ${quote(script)} hook || exit 2`;
+	if (scope === "project") return `npx --no-install ${plugin.packageName} hook`;
+	return `n=${quote(node)}; [ -x "$n" ] || n=node; "$n" ${quote(script)} hook`;
+}
+function entriesFor(plugin, agent, command) {
+	const entry = (event, status, timeout) => {
+		const run = `${command} ${hookFlags(event, agent)}`;
+		return {
+			type: "command",
+			command: event === "PreToolUse" ? `${run} || exit 2` : run,
+			timeout,
+			statusMessage: status
+		};
+	};
+	const { Stop, UserPromptSubmit } = plugin.events;
+	return {
+		PreToolUse: {
+			matcher: requireMatcher(agent, plugin),
+			hooks: [{
+				...entry("PreToolUse", plugin.statusMessage, plugin.timeout),
+				...agent === "claude" ? { onFailure: "block" } : {}
+			}]
+		},
+		...Stop ? { Stop: { hooks: [entry("Stop", Stop.statusMessage, Stop.timeout)] } } : {},
+		...UserPromptSubmit ? { UserPromptSubmit: { hooks: [entry("UserPromptSubmit", UserPromptSubmit.statusMessage, UserPromptSubmit.timeout)] } } : {}
+	};
 }
 const QUOTED = String.raw`(?:[^']|'\\'')*`;
 function ownHook(plugin, entry) {
@@ -255,7 +390,10 @@ function ownHook(plugin, entry) {
 	const pinned = String.raw`n='${QUOTED}'; \[ -x "\$n" \] \|\| n=node; "\$n" '${QUOTED}/\.${name}/current/[^/']+' hook`;
 	const bare = `node '${QUOTED}/${name}/(?:${QUOTED}/)?${escape(entry)}' hook`;
 	const project = `npx --no-install ${escape(plugin.packageName)} hook`;
-	return new RegExp(`^(?:${pinned}|${bare}|${project})(?: \\|\\| exit 2)?$`);
+	const flags = String.raw`(?: --event (?:PreToolUse|Stop|UserPromptSubmit))?(?: --agent (?:claude|codex))?`;
+	const own = new RegExp(`^(?:${pinned}|${bare}|${project})${flags}(?: \\|\\| exit 2)?$`);
+	const earlier = plugin.ownCommands.map((pattern) => new RegExp(`^(?:${pattern.source})$`, pattern.flags));
+	return (command) => own.test(command) || earlier.some((pattern) => pattern.test(command));
 }
 const builtFiles = (dir) => readdirSync(dir).filter((name) => name.endsWith(".mjs")).sort();
 function buildId(dir) {
@@ -313,6 +451,22 @@ function linkCurrent(root, id) {
 	}
 	return current;
 }
+function restoreCurrent(root, id) {
+	const current = join(root, "current");
+	const target = () => {
+		try {
+			return readlinkSync(current);
+		} catch {
+			return null;
+		}
+	};
+	const previous = target();
+	return () => {
+		if (target() !== id) return;
+		if (previous === null) rmSync(current, { force: true });
+		else linkCurrent(root, previous);
+	};
+}
 const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 function readSettings(file) {
 	if (!existsSync(file)) return {};
@@ -323,135 +477,237 @@ function readSettings(file) {
 		throw new Error(`${file} is not valid JSON (${error.message}); it was left unchanged`);
 	}
 	const hooks = isObject(settings) ? settings.hooks : void 0;
-	const preToolUse = isObject(hooks) ? hooks.PreToolUse : void 0;
 	const wrongHooks = hooks !== void 0 && hooks !== null && !isObject(hooks);
-	const wrongPreToolUse = preToolUse !== void 0 && preToolUse !== null && !Array.isArray(preToolUse);
-	if (!isObject(settings) || wrongHooks || wrongPreToolUse) throw new Error(`${file} does not hold a settings object with a hooks object and a PreToolUse list; it was left unchanged`);
+	const wrongList = EVENTS$1.find((event) => {
+		const list = isObject(hooks) ? hooks[event] : void 0;
+		return list !== void 0 && list !== null && !Array.isArray(list);
+	});
+	if (!isObject(settings) || wrongHooks) throw new Error(`${file} does not hold a settings object with a hooks object; it was left unchanged`);
+	if (wrongList) throw new Error(`${file} has a ${wrongList} that is not a list; it was left unchanged`);
 	return settings;
 }
 function writeConfig(file, text) {
 	const real = existsSync(file) ? realpathSync(file) : file;
 	mkdirSync(dirname(real), { recursive: true });
 	const temp = `${real}.${process.pid}.tmp`;
+	const mode = existsSync(real) ? statSync(real).mode & 4095 : void 0;
 	try {
-		writeFileSync(temp, text);
-		if (existsSync(real)) chmodSync(temp, statSync(real).mode & 4095);
+		rmSync(temp, { force: true });
+		writeFileSync(temp, text, {
+			mode: mode ?? 438,
+			flag: "wx"
+		});
+		if (mode !== void 0) chmodSync(temp, mode);
 		renameSync(temp, real);
 	} finally {
 		rmSync(temp, { force: true });
 	}
 }
-function configure(file, settings, own, entry) {
-	const hooks = settings.hooks ?? {};
-	const before = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
-	let removed = 0;
-	const kept = before.map((item) => {
-		if (!Array.isArray(item?.hooks)) return item;
-		const rest = item.hooks.filter((hook) => !(typeof hook?.command === "string" && own.test(hook.command)));
-		removed += item.hooks.length - rest.length;
+function configure(file, settings, own, entries) {
+	const hooks = { ...settings.hooks };
+	let changed = false;
+	for (const event of EVENTS$1) {
+		const kept = (Array.isArray(hooks[event]) ? hooks[event] : []).map((item) => {
+			if (!Array.isArray(item?.hooks)) return item;
+			const rest = item.hooks.filter((hook) => !(typeof hook?.command === "string" && own(hook.command)));
+			changed ||= rest.length < item.hooks.length;
+			return {
+				...item,
+				hooks: rest
+			};
+		}).filter((item) => !Array.isArray(item?.hooks) || item.hooks.length > 0);
+		const entry = entries[event];
+		if (entry) {
+			kept.push(entry);
+			changed = true;
+		}
+		if (kept.length > 0) hooks[event] = kept;
+		else if (Array.isArray(hooks[event])) delete hooks[event];
+	}
+	if (!changed) return;
+	settings.hooks = hooks;
+	writeConfig(file, `${JSON.stringify(settings, null, 2)}\n`);
+}
+function linesOf(value, field) {
+	if (value === void 0) return [];
+	if (!Array.isArray(value) || value.some((line) => typeof line !== "string")) throw new TypeError(`${field} is not a list of strings`);
+	return [...value];
+}
+function withExtra(file, place, write, extra) {
+	const before = existsSync(file) ? readFileSync(file, "utf8") : null;
+	write();
+	if (!extra) return {
+		notes: [],
+		warnings: []
+	};
+	try {
+		const result = extra({
+			...place,
+			file
+		});
+		if (result !== void 0 && !isObject(result)) throw new TypeError("an install step returned neither nothing nor { notes, warnings }");
 		return {
-			...item,
-			hooks: rest
+			notes: linesOf(result?.notes, "notes"),
+			warnings: linesOf(result?.warnings, "warnings")
 		};
-	}).filter((item) => !Array.isArray(item?.hooks) || item.hooks.length > 0);
-	if (!entry && removed === 0) return;
-	if (entry) kept.push(entry);
-	settings.hooks = {
-		...hooks,
-		PreToolUse: kept
-	};
-	if (kept.length === 0) delete settings.hooks.PreToolUse;
-	writeConfig(file, `${JSON.stringify(settings, null, 2)}\n`);
+	} catch (error) {
+		if (before === null) rmSync(file, { force: true });
+		else if (readFileSync(file, "utf8") !== before) writeConfig(file, before);
+		throw error;
+	}
 }
 /**
-* Adds the plugin's PreToolUse hook to one agent's config, replacing any entry
-* it wrote before and keeping every other one.
+* Adds the plugin's hooks to one agent's config, PreToolUse and each event in
+* its `events`, replacing any entry it wrote before, for any event, and
+* keeping every other one.
 *
 * The user scope copies the bin's directory to `~/.<name>/<build-id>/`, checks
 * the copy runs, points `~/.<name>/current` at it and runs it from there on
 * `execPath`. The project scope runs `npx --no-install <packageName> hook`.
-* Either command ends in `|| exit 2`, so a hook that cannot start blocks the
-* call. The Claude Code entry also sets `onFailure: "block"` for a hook that
-* times out.
+* Each command names its event and agent, `hook --event <event> --agent
+* <agent>`, and the PreToolUse one ends in `|| exit 2`, so a hook that cannot start
+* blocks the call, and the Claude Code entry sets `onFailure: "block"` for one
+* that times out. The other events' commands do not, so they pass instead.
+* Then the plugin's `onInstall` runs.
 *
-* Throws, and leaves the config as it was, when the config is not a settings
-* object it can extend, when the plugin's kinds leave tools the agent routes
-* to it unchecked, or when the build cannot be copied or does not run.
+* Throws, and leaves the config and `current` as they were, when the config
+* is not a settings object it can extend, when the plugin's kinds leave tools
+* the agent routes to it unchecked, when the build cannot be copied or does
+* not run, or when `onInstall` throws.
 */
 function install(options) {
 	const { plugin, agent, scope, script } = options;
-	const matcher = requireMatcher(agent, plugin);
+	requireMatcher(agent, plugin);
 	const file = configFile(agent, scope, options);
 	const settings = readSettings(file);
 	let target = script;
+	let restore = () => {};
 	if (scope === "user") {
 		const root = join(options.home, `.${plugin.name}`);
 		const id = copyBuild(plugin, script, root);
 		probe(join(root, id, basename(script)), options.execPath);
+		restore = restoreCurrent(root, id);
 		target = join(linkCurrent(root, id), basename(script));
 	}
-	const command = hookCommand(plugin, scope, target, options.execPath);
-	configure(file, settings, ownHook(plugin, basename(script)), {
-		matcher,
-		hooks: [{
-			type: "command",
-			command,
-			timeout: plugin.timeout,
-			statusMessage: plugin.statusMessage,
-			...agent === "claude" ? { onFailure: "block" } : {}
-		}]
-	});
+	const entries = entriesFor(plugin, agent, hookCommand(plugin, scope, target, options.execPath));
+	const place = {
+		agent,
+		scope,
+		home: options.home,
+		cwd: options.cwd,
+		script
+	};
+	let lines;
+	try {
+		lines = withExtra(file, place, () => configure(file, settings, ownHook(plugin, basename(script)), entries), plugin.onInstall);
+	} catch (error) {
+		try {
+			restore();
+		} catch {}
+		throw error;
+	}
+	const commands = Object.fromEntries(Object.entries(entries).map(([event, entry]) => [event, entry.hooks[0].command]));
 	return {
 		file,
-		command
+		command: commands.PreToolUse,
+		commands,
+		...lines
 	};
 }
 /**
-* Removes the plugin's hook from one agent's config, whichever form an earlier
-* install wrote, and keeps every other entry. The stable copy stays: another
-* agent may still run it. Throws, and leaves the file as it was, when it is not
-* a settings object.
+* Removes the plugin's hooks from one agent's config, for every event and
+* whichever form an earlier install wrote, keeps every other entry, and runs
+* the plugin's `onUninstall`. The stable copy stays: another agent may still
+* run it. Throws, and leaves the file as it was, when it is not a settings
+* object or `onUninstall` throws.
 */
 function uninstall(options) {
-	const file = configFile(options.agent, options.scope, options);
-	if (!existsSync(file)) return { file };
-	configure(file, readSettings(file), ownHook(options.plugin, basename(options.script)), null);
-	return { file };
+	const { plugin, agent, scope, script } = options;
+	const file = configFile(agent, scope, options);
+	return {
+		file,
+		...withExtra(file, {
+			agent,
+			scope,
+			home: options.home,
+			cwd: options.cwd,
+			script
+		}, () => {
+			if (existsSync(file)) configure(file, readSettings(file), ownHook(plugin, basename(script)), {});
+		}, plugin.onUninstall)
+	};
 }
 // src/cli.ts
 const isAgent = (word) => word === "claude" || word === "codex";
-function usage(bin) {
+const isEvent = (word) => word === "PreToolUse" || word === "Stop" || word === "UserPromptSubmit";
+function hookArgs(args) {
+	const parsed = {};
+	for (let i = 0; i < args.length; i += 2) {
+		const [flag, value] = [args[i], args[i + 1]];
+		if (flag === "--event" && isEvent(value) && parsed.event === void 0) parsed.event = value;
+		else if (flag === "--agent" && isAgent(value) && parsed.agent === void 0) parsed.agent = value;
+		else {
+			const named = args.find((word, at) => args[at - 1] === "--event" && isEvent(word));
+			return {
+				...parsed,
+				event: parsed.event ?? (isEvent(named) ? named : void 0),
+				error: `${[flag, value].filter((word) => word !== void 0).join(" ")} is not an argument hook takes`
+			};
+		}
+	}
+	return parsed;
+}
+function usage(plugin, bin) {
+	const events = ["PreToolUse", ...Object.keys(plugin.events)];
 	const rows = [
-		["install <claude|codex> [--project]", "add the PreToolUse hook"],
+		["install <claude|codex> [--project]", `add the ${events.join(" and ")} hook${events.length > 1 ? "s" : ""}`],
 		["uninstall <claude|codex> [--project]", "remove it"],
-		["hook", "run as the hook (reads the tool call on stdin)"]
+		["hook [--event <event>] [--agent <claude|codex>]", "run as the hook (reads the agent's payload on stdin)"]
 	];
 	const width = Math.max(...rows.map(([command]) => command.length)) + 1;
 	return `Usage:\n${rows.map(([command, what]) => `  ${bin} ${command.padEnd(width)}${what}`).join("\n")}\n`;
 }
 /**
 * Builds the plugin's command line: `install` and `uninstall <claude|codex>
-* [--project]`, and `hook`, which reads the tool call from `io.stdin`.
+* [--project]`, and `hook [--event <event>] [--agent <claude|codex>]`, which
+* reads the payload from `io.stdin` and hands the flags to {@link runHook}.
 *
-* Exit codes: `hook` returns what {@link runHook} returns, 0 or 2. `install`
-* and `uninstall` return 0, or 1 with the reason on stderr. Anything else,
-* including an unknown flag or an extra argument, prints the usage and
-* returns 1. On a Node.js older than 22, `hook` returns 2
-* and `install` 1, each with a message naming the fix; `uninstall` still runs.
+* Exit codes: `hook` returns what {@link runHook} returns, 0 or 2; an
+* argument it does not take is a fault, 0 at Stop or UserPromptSubmit and 2
+* otherwise. `install`
+* and `uninstall` return 0, or 1 with the reason on stderr; the notes the
+* plugin's `onInstall` or `onUninstall` returns follow the config file on
+* stdout, its warnings go to stderr. Anything else, including an unknown flag
+* or an extra argument, prints the usage and returns 1. On a Node.js older
+* than 22, `hook` returns 2 for PreToolUse and 0 for Stop and
+* UserPromptSubmit, and `install` 1, each with a message naming the fix;
+* `uninstall` still runs.
 */
 function createCli(plugin, options = {}) {
 	const bin = options.bin ?? plugin.name;
 	return async (argv, io) => {
 		const [command, agent, ...flags] = argv;
+		const args = command === "hook" ? hookArgs(argv.slice(1)) : {};
 		const major = Number(/^v(\d+)\./.exec(io.node)?.[1] ?? 0);
 		if ((command === "hook" || command === "install") && major < 22) {
 			io.stderr(`${bin} needs Node.js 22 or later, and this one is ${io.node}. Run \`npx ${plugin.packageName} install claude\` (or codex) again with Node.js 22 or later, or put one first on PATH and restart the agent.\n`);
-			return command === "hook" ? 2 : 1;
+			if (command === "install") return 1;
+			return passesOnFault(args.event, io.stdin()) ? 0 : 2;
+		}
+		if (command === "hook") {
+			if (args.error) {
+				const open = passesOnFault(args.event, io.stdin());
+				io.stderr(open ? `${plugin.name} let it pass: ${args.error}\n` : `Blocked by ${plugin.name}: ${args.error}\n`);
+				return open ? 0 : 2;
+			}
+			return runHook(plugin, io.stdin(), {
+				cwd: io.cwd,
+				stderr: io.stderr,
+				stdout: io.stdout,
+				event: args.event,
+				agent: args.agent
+			});
 		}
-		if (command === "hook") return runHook(plugin, io.stdin(), {
-			cwd: io.cwd,
-			stderr: io.stderr
-		});
 		const project = flags.length === 1 && flags[0] === "--project";
 		if ((command === "install" || command === "uninstall") && isAgent(agent) && (flags.length === 0 || project)) {
 			const place = {
@@ -462,21 +718,23 @@ function createCli(plugin, options = {}) {
 				home: io.home,
 				cwd: io.cwd
 			};
-			let file;
+			let result;
 			try {
-				file = command === "install" ? install({
+				result = command === "install" ? install({
 					...place,
 					execPath: io.execPath
-				}).file : uninstall(place).file;
+				}) : uninstall(place);
 			} catch (error) {
 				io.stderr(`${bin}: ${error instanceof Error ? error.message : String(error)}\n`);
 				return 1;
 			}
-			io.stdout(`${command === "install" ? "Installed in" : "Removed from"} ${file}\n`);
+			io.stdout(`${command === "install" ? "Installed in" : "Removed from"} ${result.file}\n`);
+			for (const note of result.notes) io.stdout(`${note}\n`);
+			for (const warning of result.warnings) io.stderr(`${bin}: ${warning}\n`);
 			if (command === "install" && agent === "codex") io.stdout("Codex runs a new hook only after you trust it: open /hooks in Codex once.\n");
 			return 0;
 		}
-		io.stderr(usage(bin));
+		io.stderr(usage(plugin, bin));
 		return 1;
 	};
 }
@@ -500,22 +758,29 @@ async function readStdin(stream = process.stdin) {
 * `hook`, and sets `process.exitCode`. Call it without `await`, passing the
 * bin's own `import.meta.url`, which is what install copies and runs.
 *
-* For `hook` the exit code is 2 until a verdict is in. Node.js exits 0 once
-* nothing is left to run, so a check whose promise never settles would
-* otherwise let the call run.
+* For a PreToolUse `hook` the exit code is 2 until a verdict is in. Node.js
+* exits 0 once nothing is left to run, so a check whose promise never settles
+* would otherwise let the call run. A Stop or UserPromptSubmit check that
+* never settles exits 0, as any other fault there does.
 */
 async function runCli(plugin, entryUrl, options = {}) {
 	const argv = process.argv.slice(2);
 	const hook = argv[0] === "hook";
+	const { event } = hook ? hookArgs(argv.slice(1)) : {};
 	let done = false;
+	let open = false;
 	if (hook) {
 		process.exitCode = 2;
 		process.once("beforeExit", () => {
-			if (!done) process.stderr.write(`Blocked by ${plugin.name}, its check never finished\n`);
+			if (!done) process.stderr.write(open ? `${plugin.name} let it pass, its check never finished\n` : `Blocked by ${plugin.name}, its check never finished\n`);
 		});
 	}
 	try {
 		const input = hook ? await readStdin() : "";
+		if (hook && passesOnFault(event, input)) {
+			open = true;
+			process.exitCode = 0;
+		}
 		process.exitCode = await createCli(plugin, options)(argv, {
 			stdin: () => input,
 			script: fileURLToPath(entryUrl),
@@ -530,7 +795,7 @@ async function runCli(plugin, entryUrl, options = {}) {
 	} catch (error) {
 		done = true;
 		process.stderr.write(`${options.bin ?? plugin.name}: ${error instanceof Error ? error.message : String(error)}\n`);
-		process.exitCode = hook ? 2 : 1;
+		process.exitCode = hook ? open ? 0 : 2 : 1;
 	}
 }
 // src/define.ts
@@ -538,8 +803,11 @@ const KINDS = [
 	"shell",
 	"write",
 	"edit",
-	"patch"
+	"patch",
+	"tool"
 ];
+const TOOL_NAME = /^[\w-]+$/;
+const EVENTS = ["Stop", "UserPromptSubmit"];
 const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const PACKAGE = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
 /**
@@ -548,20 +816,65 @@ const PACKAGE = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
 * broken plugin fails when it is built, not when the hook runs.
 */
 function defineHook(definition) {
-	const { name, kinds, check, packageName = name, statusMessage = `Running ${name}`, timeout = 10 } = definition;
+	const { name, kinds, check, packageName = name, statusMessage = `Running ${name}`, timeout = 10, ownCommands = [], tools = [], events = {}, onInstall, onUninstall } = definition;
 	if (typeof name !== "string" || !NAME.test(name)) throw new TypeError(`name ${JSON.stringify(name)} is not kebab-case (lowercase letters and digits, joined by single hyphens)`);
 	if (typeof packageName !== "string" || !PACKAGE.test(packageName)) throw new TypeError(`packageName ${JSON.stringify(packageName)} is not an npm package name`);
 	if (!Array.isArray(kinds) || kinds.length === 0 || kinds.some((kind) => !KINDS.includes(kind))) throw new TypeError(`kinds must list one or more of ${KINDS.join(", ")}`);
 	if (typeof check !== "function") throw new TypeError("check is not a function");
-	if (typeof statusMessage !== "string" || statusMessage === "") throw new TypeError("statusMessage is not a non-empty string");
-	if (!Number.isInteger(timeout) || timeout < 1) throw new TypeError(`timeout ${JSON.stringify(timeout)} is not a whole number of seconds`);
+	checkStatus(statusMessage, "statusMessage");
+	checkTimeout(timeout, "timeout");
+	const patterns = Array.isArray(ownCommands) ? [...ownCommands] : null;
+	if (patterns === null || patterns.some((pattern) => !(pattern instanceof RegExp) || pattern.global || pattern.multiline || pattern.sticky)) throw new TypeError("ownCommands must list regular expressions without the g, m or y flag");
+	const names = Array.isArray(tools) ? [...tools] : null;
+	if (names === null || names.some((tool) => typeof tool !== "string" || !TOOL_NAME.test(tool))) throw new TypeError("tools must list tool names of letters, digits, _ and -");
+	const builtIn = names.find((tool) => KIND_OF_TOOL.has(tool));
+	if (builtIn !== void 0) throw new TypeError(`${builtIn} is one of the agents' own tools; list its kind instead`);
+	if (kinds.includes("tool") !== names.length > 0) throw new TypeError("kinds lists tool exactly when tools names one or more tools");
+	for (const [key, hook] of [["onInstall", onInstall], ["onUninstall", onUninstall]]) if (hook !== void 0 && typeof hook !== "function") throw new TypeError(`${key} is not a function`);
 	return Object.freeze({
 		name,
 		packageName,
 		kinds: Object.freeze([...new Set(kinds)]),
 		statusMessage,
 		timeout,
+		ownCommands: Object.freeze(patterns),
+		tools: Object.freeze([...new Set(names)]),
+		events: eventHooks(events, statusMessage, timeout),
+		onInstall,
+		onUninstall,
 		check
 	});
 }
+function checkStatus(value, field) {
+	if (typeof value !== "string" || value === "") throw new TypeError(`${field} is not a non-empty string`);
+}
+function checkTimeout(value, field) {
+	if (!Number.isInteger(value) || value < 1) throw new TypeError(`${field} ${JSON.stringify(value)} is not a whole number of seconds`);
+}
+function eventHook(event, definition, statusMessage, timeout) {
+	if (typeof definition !== "object" || definition === null || typeof definition.check !== "function") throw new TypeError(`events.${event}.check is not a function`);
+	const hook = {
+		check: definition.check,
+		statusMessage: definition.statusMessage ?? statusMessage,
+		timeout: definition.timeout ?? timeout
+	};
+	checkStatus(hook.statusMessage, `events.${event}.statusMessage`);
+	checkTimeout(hook.timeout, `events.${event}.timeout`);
+	return hook;
+}
+function eventHooks(events, statusMessage, timeout) {
+	if (typeof events !== "object" || events === null || Array.isArray(events)) throw new TypeError("events is not an object");
+	const unknown = Object.keys(events).find((event) => !EVENTS.includes(event));
+	if (unknown !== void 0) throw new TypeError(`events.${unknown} is not one of ${EVENTS.join(", ")}`);
+	const { Stop, UserPromptSubmit } = events;
+	const hidePrompt = UserPromptSubmit?.hidePrompt ?? false;
+	if (typeof hidePrompt !== "boolean") throw new TypeError("events.UserPromptSubmit.hidePrompt is not a boolean");
+	return Object.freeze({
+		...Stop ? { Stop: Object.freeze(eventHook("Stop", Stop, statusMessage, timeout)) } : {},
+		...UserPromptSubmit ? { UserPromptSubmit: Object.freeze({
+			...eventHook("UserPromptSubmit", UserPromptSubmit, statusMessage, timeout),
+			hidePrompt
+		}) } : {}
+	});
+}
 export { claudePluginFiles, configFile, createCli, defineHook, install, matcherFor, readStdin, runCli, runHook, uninstall, writeClaudePlugin };