agent-base-kit 0.1.0 → 0.3.0

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