agent-base-kit 0.1.1 → 0.3.0

package/README.md

@@ -14,7 +14,7 @@
 [![node](https://img.shields.io/node/v/agent-base-kit)](./package.json)
 [![license: MIT](https://img.shields.io/npm/l/agent-base-kit)](./LICENSE)
 
-[Why](#why) · [What you get](#what-you-get) · [Usage](#usage) · [What install writes](#what-install-writes) · [Fail-closed](#the-fail-closed-contract) · [Kinds](#kinds-and-matchers) · [API](#api)
+[Why](#why) · [What you get](#what-you-get) · [Usage](#usage) · [What install writes](#what-install-writes) · [Fail-closed](#the-fail-closed-contract) · [Kinds](#kinds-and-matchers) · [Other events](#stop-and-userpromptsubmit) · [API](#api)
 
 </div>
 
@@ -26,7 +26,8 @@ agent-base-kit is that plumbing, shared by every hook you build. You write the c
 
 ## What you get
 
-- **One function to write.** `check(call)` gets a typed call (`shell`, `write`, `edit` or `patch`) and returns `{ block, reason }`, sync or async.
+- **One function to write.** `check(call)` gets a typed call (`shell`, `write`, `edit`, `patch`, or a named tool such as an MCP server's) and returns `{ block, reason }`, sync or async.
+- **Stop and UserPromptSubmit too.** Check the reply before the turn ends or the prompt before the model sees it, failing open where a broken hook would trap the session.
 - **Both agents.** Claude Code and Codex, with matchers derived from the kinds you list.
 - **Fail-closed by default.** Unreadable payloads, throws, bad verdicts, hangs and a hook that cannot start all block.
 - **One command to install.** Your bin gets `install` and `uninstall` for `claude` or `codex`, at user or project scope.
@@ -78,12 +79,18 @@ A user install (the default scope) does four things:
 4. **Writes the hook:**
 
 ```sh
-n='/path/to/the/installing/node'; [ -x "$n" ] || n=node; "$n" '/home/you/.<name>/current/cli.mjs' hook || exit 2
+n='/path/to/the/installing/node'; [ -x "$n" ] || n=node; "$n" '/home/you/.<name>/current/cli.mjs' hook --event PreToolUse --agent claude || exit 2
 ```
 
-`--project` writes `npx --no-install <packageName> hook || exit 2` instead, which is safe to commit. Uninstall removes the entry and leaves the copy, since another agent may still run it.
+`--project` writes `npx --no-install <packageName> hook --event PreToolUse --agent claude || exit 2` instead, which is safe to commit. Each of the plugin's [other events](#stop-and-userpromptsubmit) gets an entry of its own with the same command, naming its own event, minus `|| exit 2`. Uninstall removes every entry and leaves the copy, since another agent may still run it.
 
-Install replaces any entry it wrote before and keeps every other one. It refuses, and changes nothing, when the settings file is not JSON or not an object with a `hooks` object and a `PreToolUse` list, or when `~/.<name>/current` exists and is not a link.
+`--event` tells the hook which event it runs for without reading the payload, so a Stop or UserPromptSubmit payload that arrives cut short or empty still passes instead of being blocked as unreadable. `--agent` tells it which agent to answer, so a prompt block sent to Codex carries only the fields Codex accepts. A command written before the flags existed still works: the hook then takes the event from the payload's `hook_event_name`, and treats a UserPromptSubmit payload carrying `turn_id` (which Codex's input schema requires and Claude Code does not send) as Codex's. Install recognizes those older commands as its own and replaces them; Codex asks to trust the hook once more, since its command changed.
+
+Install replaces any entry it wrote before, at any event, and keeps every other one; an entry an earlier version wrote for an event this one no longer has is removed. It refuses, and changes nothing, when the settings file is not JSON, not an object with a `hooks` object, or has a `PreToolUse`, `Stop` or `UserPromptSubmit` that is not a list, or when `~/.<name>/current` exists and is not a link.
+
+`onInstall` runs once the config is written, for what else the hook needs, such as a skill copied into the agent's directory; `onUninstall` runs after uninstall. Each gets the agent, scope, home, working directory, bin and config file, and may return `{ notes, warnings }`, which the command line prints after the config file, to stdout and stderr. A step that throws puts the config and `~/.<name>/current` back as they were and fails the command, so the hooks already installed keep their build.
+
+A hook that wrote other commands before it moved to agent-base-kit lists them in `ownCommands`, so install replaces and uninstall removes those entries too.
 
 ## The fail-closed contract
 
@@ -94,8 +101,10 @@ The hook exits 0 only when your check passes the call:
 | `check` returns `{ block: false }` | 0 |
 | `check` returns `{ block: true, reason }` (the reason goes to stderr as is) | 2 |
 | `check` throws, rejects, never settles, or returns anything else | 2 |
-| The payload is not JSON, names no tool, or has a field of the wrong shape | 2 |
-| The tool is not one of your kinds | 0, and `check` is not called |
+| The payload is not JSON, names no tool, has a field of the wrong shape, or names an event other than PreToolUse, Stop or UserPromptSubmit | 2 |
+| The command says `--event PreToolUse` and the payload names another event | 2 |
+| The command has an argument `hook` does not take | 2, or 0 when its first valid `--event` names Stop or UserPromptSubmit or, with none, the payload does |
+| The tool is not one of your kinds or `tools` | 0, and `check` is not called |
 | The hook cannot start: Node.js is missing, the build was deleted, a dependency was not bundled | 2, from `\|\| exit 2` |
 | The hook runs on a Node.js older than 22 | 2, with a message naming the fix |
 | The hook times out | Claude Code blocks it (`onFailure: "block"`, Claude Code 2.1.295 or later). Codex lets the call run. |
@@ -110,29 +119,81 @@ Keep `check` well inside `timeout`, which defaults to 10 seconds.
 | --- | --- | --- | --- |
 | `shell` | `{ kind: 'shell', command }` | `Bash` | `Bash` |
 | `write` | `{ kind: 'write', path, content }` | `Write`, `NotebookEdit` | `apply_patch` |
-| `edit` | `{ kind: 'edit', path, before, after }` (a MultiEdit's edits joined by newlines) | `Edit`, `MultiEdit` | `apply_patch` |
+| `edit` | `{ kind: 'edit', path, before, after }` (a MultiEdit's edits one call each) | `Edit`, `MultiEdit` | `apply_patch` |
 | `patch` | `{ kind: 'patch', patch }` (the whole patch text) | none | `apply_patch` |
+| `tool` | `{ kind: 'tool', name, input }` (the tool's input object) | the names in `tools` | the names in `tools` |
+
+`tools` names tools beyond the agents' own, such as `mcp__github__create_pull_request`, and `kinds` lists `tool` exactly when it does. A name holds only letters, digits, `_` and `-`, and may not be a tool a kind already covers (`Bash`, `Write`, `Edit`, `MultiEdit`, `NotebookEdit`, `apply_patch`). A listed tool's input that is not an object blocks the call; an absent one reaches the check as `{}`.
 
 Codex sends every file change as one `apply_patch`, so `install codex` refuses a plugin with `write` or `edit` but no `patch`. A plugin with no tool in an agent, such as `['patch']` for Claude Code, is refused too.
 
+## Stop and UserPromptSubmit
+
+`events` adds checks on two more events, installed beside PreToolUse:
+
+```ts
+function verdict(text: string): HookVerdict {
+  return /\bsk-[\w-]{20,}/.test(text)
+    ? { block: true, reason: 'no-pasted-keys: reference the key through an environment variable instead.' }
+    : { block: false }
+}
+
+defineHook({
+  name: 'no-pasted-keys',
+  kinds: ['shell'],
+  check: call => verdict(call.command),
+  events: {
+    Stop: { check: ({ reply }) => verdict(reply) },
+    UserPromptSubmit: { check: ({ prompt }) => verdict(prompt), hidePrompt: true },
+  },
+})
+```
+
+A block goes to stdout as `{"decision":"block","reason":…}`. At Stop the agent keeps going with the reason as its next instruction; at UserPromptSubmit it drops the prompt and shows the reason, and `hidePrompt` keeps Claude Code from printing the prompt back under it (Codex has no such field, and a reply carrying it would let the prompt through, so it is not sent there). Both fail open, since an exit 2 at Stop would keep the agent going forever and one at UserPromptSubmit would drop every prompt:
+
+| What happens | Exit |
+| --- | --- |
+| `check` returns `{ block: true, reason }` | 0, with the decision on stdout |
+| `check` returns `{ block: false }` | 0, silently |
+| `check` throws, rejects, never settles, returns anything else, or the field has the wrong shape | 0, with the cause on stderr |
+| With `--event`: the payload is not JSON, is empty or cut short, or names another event | 0, with the cause on stderr |
+| A Stop payload with `stop_hook_active`, the reply to the hook's own block | 0, and `check` is not called |
+| The hook cannot start, or runs on a Node.js older than 22 | anything but 2: the event passes |
+
+Each event takes its own `statusMessage` and `timeout`, defaulting to the hook's. Without `--event`, a payload that is not JSON is blocked with exit 2 whatever event it was meant for, which is why install writes the flag. A payload with no `hook_event_name` is read as PreToolUse; one naming any other event (`PostToolUse`, `pre_tool_use`, an empty string) is blocked with exit 2, since the tool call it may carry would otherwise run unchecked.
+
 ## API
 
 ```ts
 function defineHook<const K extends ToolKind>(definition: HookDefinition<K>): HookPlugin
 function runCli(plugin: HookPlugin, entryUrl: string, options?: { bin?: string }): Promise<void>
 function createCli(plugin: HookPlugin, options?: { bin?: string }): (argv: readonly string[], io: CliIO) => Promise<number>
-function runHook(plugin: HookPlugin, stdin: string, options?: { cwd?: string, stderr?: (text: string) => void }): Promise<number>
+function runHook(plugin: HookPlugin, stdin: string, options?: { cwd?: string, stderr?: (text: string) => void, stdout?: (text: string) => void, event?: HookEvent, agent?: Agent }): Promise<number>
 function readStdin(stream?: AsyncIterable<unknown>): Promise<string>
-function install(options: InstallOptions): { file: string, command?: string }
-function uninstall(options: UninstallOptions): { file: string }
+function install(options: InstallOptions): InstallResult // { file, command, commands, notes, warnings }
+function uninstall(options: UninstallOptions): InstallResult
 function configFile(agent: Agent, scope: Scope, place: { home: string, cwd: string }): string
 function matcherFor(agent: Agent, kinds: readonly ToolKind[]): string
 function claudePluginFiles(options: ClaudePluginOptions): Record<string, string>
 function writeClaudePlugin(dir: string, options: ClaudePluginOptions): string[]
 ```
 
+`defineHook` takes `name`, `kinds` and `check`, and optionally:
+
+| Field | Default | What it does |
+| --- | --- | --- |
+| `packageName` | `name` | The npm package a project install runs through `npx --no-install`. |
+| `statusMessage` | `Running <name>` | What the agent shows while the hook runs. |
+| `timeout` | `10` | Seconds the agent waits for the hook. |
+| `ownCommands` | `[]` | Patterns for commands an earlier version of your hook wrote, which install replaces and uninstall removes, at any event. A pattern must match the whole command, not a part of it; the `g`, `m` and `y` flags are refused. |
+| `tools` | `[]` | Tools beyond the agents' own, checked as `tool` calls. |
+| `events` | `{}` | `Stop` and `UserPromptSubmit` checks, each with an optional `statusMessage` and `timeout`, and `hidePrompt` for UserPromptSubmit. |
+| `onInstall`, `onUninstall` | none | Steps run after the config is written; see [What install writes](#what-install-writes). They do not run for a Claude Code plugin. |
+
 `runCli` is the only function that reads the home directory, the working directory and the Node.js path from the process; the others take them as arguments, which keeps tests away from your real `~`. `writeClaudePlugin` writes the files to ship the same hook as a Claude Code plugin instead; use either the plugin or `install claude`, not both.
 
+The commands install and `writeClaudePlugin` write pass `--event` and `--agent`, which `createCli` hands to `runHook`. A bin that wires its own hook command passes them as `runHook`'s `event` and `agent` options, so a cut-short payload at Stop or UserPromptSubmit passes there too.
+
 ## Contributing
 
 ```sh

package/dist/index.d.mts

@@ -1,13 +1,17 @@
 /**
  * What a hook declares it checks. Each kind selects the agents' tools that
  * make that change, and is the `kind` of the {@link ToolCall} the check gets.
+ * `tool` selects the tools the definition names in `tools`, such as an MCP
+ * server's.
  */
-type ToolKind = 'shell' | 'write' | 'edit' | 'patch';
+type ToolKind = 'shell' | 'write' | 'edit' | 'patch' | 'tool';
 /**
  * An agent's tool call, reduced to what a check needs. `shell` is Bash in
- * either agent; `write` is Claude Code's Write or NotebookEdit; `edit` is Edit
- * or MultiEdit, whose edits arrive joined by newlines; `patch` is Codex's
- * apply_patch, the whole patch text, which can add, change and delete files.
+ * either agent; `write` is Claude Code's Write or NotebookEdit; `edit` is Edit,
+ * or one edit of a MultiEdit, which the check gets edit by edit; `patch` is
+ * Codex's apply_patch, the whole patch text, which can add, change and delete
+ * files; `tool` is one of the tools named in `tools`, with its input as the
+ * agent sent it, an object.
  */
 type ToolCall = {
   kind: 'shell';
@@ -24,6 +28,10 @@ type ToolCall = {
 } | {
   kind: 'patch';
   patch: string;
+} | {
+  kind: 'tool';
+  name: string;
+  input: Readonly<Record<string, unknown>>;
 };
 /** What a check declared with kinds `K` receives: only the matching shapes of {@link ToolCall}. */
 type ToolCallOf<K extends ToolKind> = Extract<ToolCall, {
@@ -45,6 +53,65 @@ interface HookContext {
   /** The agent's working directory, from the payload, else the hook's own. */
   cwd: string;
 }
+/**
+ * The agent events a hook takes part in. Every hook has PreToolUse, which
+ * fails closed; Stop and UserPromptSubmit are optional and fail open, since a
+ * hook that cannot run must not trap the session in a loop or swallow every
+ * prompt.
+ */
+type HookEvent = 'PreToolUse' | 'Stop' | 'UserPromptSubmit';
+/** What a Stop check gets: the reply the agent is about to end its turn on. */
+interface StopInput {
+  reply: string;
+}
+/** What a UserPromptSubmit check gets: the prompt the user sent. */
+interface PromptInput {
+  prompt: string;
+}
+/**
+ * A check on one event other than PreToolUse. A block makes the agent take
+ * the reason instead: at Stop it keeps going with the reason as its next
+ * instruction, at UserPromptSubmit it drops the prompt and shows the reason.
+ * A check that throws or returns anything but a verdict lets the event pass.
+ */
+interface EventDefinition<I> {
+  check: (input: I, context: HookContext) => HookVerdict | Promise<HookVerdict>;
+  /** What the agent shows while the check runs. Defaults to the hook's `statusMessage`. */
+  statusMessage?: string;
+  /** Seconds the agent waits. Defaults to the hook's `timeout`; past it, the event passes. */
+  timeout?: number;
+}
+interface PromptDefinition extends EventDefinition<PromptInput> {
+  /**
+   * Keeps Claude Code from printing the blocked prompt back under the reason,
+   * for a check that blocks a prompt because of what it holds, such as a
+   * secret.
+   */
+  hidePrompt?: boolean;
+}
+/** The events a hook adds on top of PreToolUse. */
+interface EventDefinitions {
+  Stop?: EventDefinition<StopInput>;
+  UserPromptSubmit?: PromptDefinition;
+}
+/** Where {@link HookDefinition.onInstall} and `onUninstall` run. */
+interface InstallPlace {
+  agent: Agent;
+  scope: Scope;
+  home: string;
+  cwd: string;
+  /** The built bin install runs from, to find files shipped beside it. */
+  script: string;
+  /** The agent config just written. */
+  file: string;
+}
+/** Lines an install step adds to what the command line prints. */
+interface InstallNotes {
+  /** Printed to stdout after the config file. */
+  notes?: readonly string[];
+  /** Printed to stderr. */
+  warnings?: readonly string[];
+}
 /** What a plugin author writes; {@link defineHook} checks it and fills in the defaults. */
 interface HookDefinition<K extends ToolKind> {
   /**
@@ -73,6 +140,38 @@ interface HookDefinition<K extends ToolKind> {
    * the call run, and Claude Code blocks it.
    */
   timeout?: number;
+  /**
+   * Commands an earlier version of the hook wrote in a form install no longer
+   * recognizes, such as a path that does not sit in a directory named after
+   * the hook. A command any pattern matches is taken as this hook's own:
+   * install replaces it and uninstall removes it. A pattern must match the
+   * whole command, not a part of it, and may not carry the `g`, `m` or `y`
+   * flag.
+   */
+  ownCommands?: readonly RegExp[];
+  /**
+   * Tools no kind covers, by exact name, such as
+   * `mcp__github__create_pull_request`. They reach the check as `tool` calls,
+   * so `kinds` must list `tool` exactly when this names any.
+   */
+  tools?: readonly string[];
+  /** Checks on events other than PreToolUse, installed beside it. */
+  events?: EventDefinitions;
+  /**
+   * Runs after install writes the config, to set up what else the hook needs,
+   * such as files in the agent's directory. Throwing puts the config and the
+   * `current` link back as they were and fails the install. Not run for a
+   * Claude Code plugin, which Claude Code installs itself.
+   */
+  onInstall?: (place: InstallPlace) => InstallNotes | void;
+  /** Runs after uninstall, even when the config held no entry; throwing puts the config back. */
+  onUninstall?: (place: InstallPlace) => InstallNotes | void;
+}
+/** An event hook with its defaults filled in. */
+interface EventHook<I> {
+  readonly check: (input: I, context: HookContext) => HookVerdict | Promise<HookVerdict>;
+  readonly statusMessage: string;
+  readonly timeout: number;
 }
 /** A checked hook definition, as {@link defineHook} returns it. */
 interface HookPlugin {
@@ -81,6 +180,16 @@ interface HookPlugin {
   readonly kinds: readonly ToolKind[];
   readonly statusMessage: string;
   readonly timeout: number;
+  readonly ownCommands: readonly RegExp[];
+  readonly tools: readonly string[];
+  readonly events: Readonly<{
+    Stop?: EventHook<StopInput>;
+    UserPromptSubmit?: EventHook<PromptInput> & {
+      readonly hidePrompt: boolean;
+    };
+  }>;
+  readonly onInstall?: (place: InstallPlace) => InstallNotes | void;
+  readonly onUninstall?: (place: InstallPlace) => InstallNotes | void;
   /** Called only with a call whose kind is in `kinds`. */
   readonly check: (call: ToolCall, context: HookContext) => HookVerdict | Promise<HookVerdict>;
 }
@@ -130,10 +239,12 @@ interface ClaudePluginOptions {
  * 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.
  */
@@ -170,13 +281,19 @@ interface CliOptions {
 type CliMain = (argv: readonly string[], io: CliIO) => Promise<number>;
 /**
  * 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.
  */
 export declare function createCli(plugin: HookPlugin, options?: CliOptions): CliMain;
 /**
@@ -191,9 +308,10 @@ export declare function readStdin(stream?: AsyncIterable<unknown>): Promise<stri
  * `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.
  */
 export declare function runCli(plugin: HookPlugin, entryUrl: string, options?: CliOptions): Promise<void>;
 /**
@@ -208,16 +326,45 @@ interface RunHookOptions {
   cwd?: string;
   /** Receives the block reason or the error, newline-terminated. */
   stderr?: (text: string) => void;
+  /** Receives the decision a Stop or UserPromptSubmit check blocks with, as a JSON line. */
+  stdout?: (text: string) => void;
+  /**
+   * The event the agent runs the hook for, as the installed command names it
+   * with `--event`. Given, it decides how a fault exits without reading the
+   * payload, so a Stop or UserPromptSubmit payload that is cut short or not
+   * JSON passes, and a payload naming another event is a fault. Absent, the
+   * event comes from the payload's `hook_event_name`.
+   */
+  event?: HookEvent;
+  /**
+   * The agent that runs the hook, as the installed command names it with
+   * `--agent`. Absent, a UserPromptSubmit payload carrying `turn_id`, which
+   * only Codex sends, reads as Codex.
+   */
+  agent?: Agent;
 }
 /**
- * Runs one PreToolUse call through the plugin and returns the exit code the
- * agent reads: 2 blocks the call, 0 lets it run.
+ * 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.
+ *
+ * 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.
  *
- * 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.
+ * 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.
  */
 export declare function runHook(plugin: HookPlugin, stdin: string, options?: RunHookOptions): Promise<number>;
 /** Where {@link uninstall} looks: everything is passed in, so nothing reaches past what the caller names. */
@@ -237,10 +384,17 @@ interface InstallOptions extends UninstallOptions {
   /** The Node.js a user-scope hook keeps running on, as `process.execPath` gives it. */
   execPath: string;
 }
-/** The config file written and, for an install, the command in it. */
+/** The config file written and, for an install, the commands in it. */
 interface InstallResult {
   file: string;
+  /** The PreToolUse command. */
   command?: string;
+  /** The command written for each event. */
+  commands?: Partial<Record<HookEvent, string>>;
+  /** What the plugin's `onInstall` or `onUninstall` returned, for stdout. */
+  notes: string[];
+  /** And for stderr. */
+  warnings: string[];
 }
 /** The agent config a scope writes: `~/.claude/settings.json`, `<cwd>/.codex/hooks.json` and so on. */
 export declare function configFile(agent: Agent, scope: Scope, place: {
@@ -248,26 +402,31 @@ export declare function configFile(agent: Agent, scope: Scope, place: {
   cwd: string;
 }): string;
 /**
- * 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.
  */
 export declare function install(options: InstallOptions): InstallResult;
 /**
- * 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.
  */
 export declare function uninstall(options: UninstallOptions): InstallResult;
-export type { Agent, ClaudePluginOptions, ClaudePluginPerson, CliIO, CliMain, CliOptions, HookContext, HookDefinition, HookPlugin, HookVerdict, InstallOptions, InstallResult, RunHookOptions, Scope, ToolCall, ToolCallOf, ToolKind, UninstallOptions };
+export type { Agent, ClaudePluginOptions, ClaudePluginPerson, CliIO, CliMain, CliOptions, EventDefinition, EventDefinitions, EventHook, HookContext, HookDefinition, HookEvent, HookPlugin, HookVerdict, InstallNotes, InstallOptions, InstallPlace, InstallResult, PromptDefinition, PromptInput, RunHookOptions, Scope, StopInput, ToolCall, ToolCallOf, ToolKind, UninstallOptions };

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-base-kit",
   "type": "module",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "packageManager": "pnpm@10.23.0",
   "description": "The base kit for Claude Code and Codex hooks: typed tool calls, a fail-closed runner, install and uninstall with a stable copy of the build, and Claude Code plugin files. Zero dependencies.",
   "author": "devmaxxx",