agent-base-kit 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 devmaxxx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,260 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="docs/assets/logo.svg" width="96" height="96" alt="">
+
+# agent-base-kit
+
+**Turn any check into a fail-closed PreToolUse hook for Claude Code and Codex. One function in, a verdict out. Zero dependencies.**
+
+[![npm version](https://img.shields.io/npm/v/agent-base-kit?color=cb3837)](https://www.npmjs.com/package/agent-base-kit)
+[![npm downloads](https://img.shields.io/npm/dm/agent-base-kit)](https://www.npmjs.com/package/agent-base-kit)
+[![CI](https://github.com/devmaxxx/agent-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/devmaxxx/agent-kit/actions/workflows/ci.yml)
+[![types](https://img.shields.io/npm/types/agent-base-kit)](https://www.npmjs.com/package/agent-base-kit)
+[![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](./package.json)
+[![node](https://img.shields.io/node/v/agent-base-kit)](./package.json)
+[![license: MIT](https://img.shields.io/npm/l/agent-base-kit)](./LICENSE)
+
+[Install](#install) · [Quick start](#quick-start) · [Kinds](#kinds-and-matchers) · [Fail-closed](#the-fail-closed-contract) · [Install layout](#what-install-writes) · [Claude Code plugin](#shipping-as-a-claude-code-plugin) · [API](#api)
+
+</div>
+
+<details>
+<summary><b>Table of contents</b></summary>
+
+- [Why](#why)
+- [Features](#features)
+- [Install](#install)
+- [Quick start](#quick-start)
+  - [Why a devDependency](#why-a-devdependency)
+- [Kinds and matchers](#kinds-and-matchers)
+- [The fail-closed contract](#the-fail-closed-contract)
+- [What install writes](#what-install-writes)
+- [Shipping as a Claude Code plugin](#shipping-as-a-claude-code-plugin)
+- [API](#api)
+- [Design notes](#design-notes)
+- [Contributing](#contributing)
+- [License](#license)
+
+</details>
+
+## Why
+
+A [PreToolUse hook](https://code.claude.com/docs/en/hooks) is the last point where you can stop an agent's tool call before it runs. Writing one well is mostly not about the check. The agents treat every exit except 2 as "go on", so a hook that crashes, cannot parse its input, or loses its Node.js after an upgrade lets every call through without a word.
+
+agent-base-kit is that plumbing, for any guard you build. You write the check; it makes sure the check actually runs, and blocks when it cannot.
+
+## Features
+
+- **One function.** `check(call)` gets a typed call (`shell`, `write`, `edit` or `patch`) and returns `{ block, reason }`. Sync or async.
+- **Fails closed.** Unreadable payloads, throws, bad verdicts, hangs and a hook that cannot start all block.
+- **Both agents.** Claude Code and Codex, user or project scope, with matchers derived from the kinds you list.
+- **Survives upgrades.** A user install runs its own copy of your build on the Node.js that installed it, so an nvm or Homebrew upgrade does not silently switch it off.
+- **Plays well with other hooks.** Install and uninstall touch only their own entry and refuse a config they cannot extend safely.
+- **Claude Code plugin files.** One call writes the manifest, `hooks.json` and a marketplace.
+- **Zero dependencies**, ESM only, typed.
+
+## Install
+
+```sh
+pnpm add -D agent-base-kit
+# or: npm i -D agent-base-kit · yarn add -D agent-base-kit · bun add -d agent-base-kit
+```
+
+Requires Node.js 22 or later and a POSIX shell. It goes in `devDependencies`; [here is why](#why-a-devdependency).
+
+## Quick start
+
+A toy check that stops force pushes, as a plugin in three files:
+
+```ts
+// src/plugin.ts
+import { defineHook } from 'agent-base-kit'
+
+export const plugin = defineHook({
+  name: 'no-force-push',
+  kinds: ['shell'],
+  statusMessage: 'Checking for force pushes',
+  check: call => /\bgit\s+push\b.*\s(?:-f|--force)(?:\s|$)/.test(call.command)
+    ? { block: true, reason: 'Blocked by no-force-push: push without --force, or use --force-with-lease.' }
+    : { block: false },
+})
+```
+
+```ts
+#!/usr/bin/env node
+// src/cli.ts
+import { runCli } from 'agent-base-kit'
+import { plugin } from './plugin'
+
+void runCli(plugin, import.meta.url)
+```
+
+```jsonc
+// package.json (the parts that matter)
+{
+  "name": "no-force-push",
+  "type": "module",
+  "bin": { "no-force-push": "./dist/cli.mjs" },
+  "files": ["dist"],
+  "engines": { "node": ">=22" },
+  "devDependencies": {
+    "agent-base-kit": "^0.1.0",
+    "tsdown": "^0.23.1"
+  }
+}
+```
+
+Build `src/cli.ts` with tsdown. That gives you this CLI:
+
+```sh
+npx no-force-push install claude            # ~/.claude/settings.json
+npx no-force-push install codex --project   # ./.codex/hooks.json
+npx no-force-push uninstall claude
+npx no-force-push hook                      # what the agent runs, with the tool call on stdin
+```
+
+### Why a devDependency
+
+A user-scope install copies the `.mjs` files next to your bin into `~/.<name>/<build-id>/` and runs them from there. A runtime dependency would be imported from `node_modules`, and the copy has none. List agent-base-kit under `devDependencies` instead, and tsdown bundles it into your build. It also inlines its types into your `.d.mts`, so `export type { ToolCall } from 'agent-base-kit'` works for your users. If the copy cannot start anyway, `install` refuses and says why. It runs the copy once before writing any config.
+
+## Kinds and matchers
+
+`kinds` decides which calls reach your check. Each agent's matcher is derived from it.
+
+| Kind | The call your check gets | Claude Code tools | Codex tools |
+| --- | --- | --- | --- |
+| `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` |
+| `patch` | `{ kind: 'patch', patch }` (the whole patch text) | none | `apply_patch` |
+
+`check` is typed to the kinds you list. It is never called with any other kind, even if a hand-written matcher sends one.
+
+Codex sends every file change as one `apply_patch`. A plugin whose kinds include `write` or `edit` but not `patch` would match those calls and then never see them. So `install codex` refuses that plugin until you add `patch` and handle the patch text. A plugin with no tool in an agent, such as `['patch']` for Claude Code, is refused the same way.
+
+## The fail-closed contract
+
+The agents treat exit 2 as "block" and every other exit as "go on". So the hook exits 0 only when your check passes the call:
+
+| What happens | Exit |
+| --- | --- |
+| `check` returns `{ block: false }` | 0 |
+| `check` returns `{ block: true, reason }` (the reason goes to stderr as is) | 2 |
+| `check` throws or rejects | 2 |
+| `check` returns anything else: `undefined`, `{ block: true }` without a reason, a string | 2 |
+| `check` returns a promise that never settles | 2 |
+| The payload is not JSON, not an object, names no tool, or has a field of the wrong shape (a `command` sent as an array, `edits` as an object) | 2 |
+| The tool is not one of your kinds | 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"`). Codex lets the call run. |
+
+`check` may be async. Keep it well inside `timeout`, which defaults to 10 seconds. Past the timeout Codex runs the call unchecked.
+
+## What install writes
+
+The user scope is the default. Install copies the build to `~/.<name>/<build-id>/` and swaps the `~/.<name>/current` link onto it with a rename. Then it writes:
+
+```sh
+n='/path/to/the/installing/node'; [ -x "$n" ] || n=node; "$n" '/home/you/.<name>/current/cli.mjs' hook || exit 2
+```
+
+- The hook keeps running on the Node.js that installed it, so a project that pins an older Node does not change it.
+- If that Node.js is removed, the hook falls back to the `node` on PATH.
+- The copy outlives the package. An nvm upgrade or an `npx` cache clean does not remove it.
+- The command stays the same across versions installed by the same Node.js, so Codex keeps trusting it.
+
+`--project` writes `npx --no-install <packageName> hook || exit 2`, which is safe to commit.
+
+Install replaces any entry it wrote before, including the older forms listed below, and keeps every other entry as it is. It refuses, and changes nothing, when:
+
+- the settings file is not JSON, or not an object with a `hooks` object and a `PreToolUse` list (a `null` there counts as absent);
+- `~/.<name>/current` exists and is not a link;
+- the bin is not a built `.mjs` file;
+- the copied build does not start.
+
+Uninstall leaves the copy in place, since another agent may still run it.
+
+In Claude Code the entry also sets `"onFailure": "block"`. That needs Claude Code 2.1.295 or later. Codex has no such field.
+
+## Shipping as a Claude Code plugin
+
+A Claude Code plugin needs no install step and no copy, because Claude Code keeps its own copy of the plugin. Generate the plugin files from your build, for example in tsdown's `onSuccess`:
+
+```ts
+// tsdown.config.ts
+import { writeClaudePlugin } from 'agent-base-kit'
+import { defineConfig } from 'tsdown'
+import pkg from './package.json' with { type: 'json' }
+import { plugin } from './src/plugin'
+
+export default defineConfig({
+  entry: ['src/cli.ts'],
+  onSuccess() {
+    writeClaudePlugin(import.meta.dirname, {
+      plugin,
+      entry: 'dist/cli.mjs',
+      version: pkg.version,
+      description: 'Stops force pushes',
+      author: { name: 'you' },
+      license: 'MIT',
+      marketplace: { name: 'no-force-push', owner: { name: 'you' } },
+    })
+  },
+})
+```
+
+This writes three files:
+
+- `.claude-plugin/plugin.json` holds the manifest.
+- `hooks/hooks.json` holds the hook: `node "${CLAUDE_PLUGIN_ROOT}/dist/cli.mjs" hook || exit 2`, with the matcher from `kinds`, your `timeout` and `statusMessage`, and `"onFailure": "block"`.
+- `.claude-plugin/marketplace.json` is written only with `marketplace`. It is a one-plugin marketplace whose source is your npm package.
+
+The build is not committed to git, and Claude Code copies a plugin as it is, without building it. So the marketplace fetches the plugin from npm, where `dist` is published. Add `.claude-plugin` and `hooks` to `files` in package.json, publish, and commit `.claude-plugin/marketplace.json` to the repository. Users then run:
+
+```text
+/plugin marketplace add you/no-force-push
+/plugin install no-force-push@no-force-push
+```
+
+Use either the plugin or `install claude`, not both, or the check runs twice.
+
+## API
+
+```ts
+function defineHook<const K extends ToolKind>(definition: HookDefinition<K>): HookPlugin
+function runHook(plugin: HookPlugin, stdin: string, options?: { cwd?: string, stderr?: (text: string) => void }): Promise<number>
+function createCli(plugin: HookPlugin, options?: { bin?: string }): (argv: readonly string[], io: CliIO) => Promise<number>
+function runCli(plugin: HookPlugin, entryUrl: string, options?: { bin?: string }): Promise<void>
+function readStdin(stream?: AsyncIterable<unknown>): Promise<string>
+function install(options: InstallOptions): { file: string, command?: string }
+function uninstall(options: UninstallOptions): { file: string }
+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[]
+```
+
+`install`, `uninstall` and `createCli` take the home directory, the working directory, the bin path and the Node.js path as arguments, and never read them from the process. `runCli` is the one function that does, which keeps tests away from your real `~`.
+
+## Design notes
+
+- **Async checks.** A sync-only API would have to break later to allow I/O. A promise costs nothing now.
+- **The reason is printed as is.** Your plugin owns its message, so start it with the plugin's name. Errors get a `Blocked by <name>, it could not check the call: …` prefix.
+- **Which entries count as its own.** The `npx` form must match exactly. The pinned form matches any file under `~/.<name>/current/`, so a bin renamed between releases still replaces its old entry. The bare `node '<path>' hook` form from before the copy existed needs a directory named exactly after the plugin. So a hook that only mentions the plugin, or another plugin whose path merely contains this one's name, is never removed.
+- **POSIX shells only.** Hook commands rely on `|| exit 2` and single-quoted paths, so Windows is not supported yet.
+
+## Contributing
+
+Issues and pull requests are welcome.
+
+```sh
+git clone https://github.com/devmaxxx/agent-kit.git
+cd agent-kit
+pnpm install
+pnpm lint && pnpm typecheck && pnpm test
+```
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,273 @@
+/**
+ * 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.
+ */
+type ToolKind = 'shell' | 'write' | 'edit' | 'patch';
+/**
+ * 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.
+ */
+type ToolCall = {
+  kind: 'shell';
+  command: string;
+} | {
+  kind: 'write';
+  path: string;
+  content: string;
+} | {
+  kind: 'edit';
+  path: string;
+  before: string;
+  after: string;
+} | {
+  kind: 'patch';
+  patch: string;
+};
+/** What a check declared with kinds `K` receives: only the matching shapes of {@link ToolCall}. */
+type ToolCallOf<K extends ToolKind> = Extract<ToolCall, {
+  kind: K;
+}>;
+/**
+ * What a check decides. A block's `reason` is printed to stderr as it is, and
+ * the agent shows it to the model, so it should name the hook and say what to
+ * do instead.
+ */
+type HookVerdict = {
+  block: false;
+} | {
+  block: true;
+  reason: string;
+};
+/** Where the call runs. */
+interface HookContext {
+  /** The agent's working directory, from the payload, else the hook's own. */
+  cwd: string;
+}
+/** What a plugin author writes; {@link defineHook} checks it and fills in the defaults. */
+interface HookDefinition<K extends ToolKind> {
+  /**
+   * Kebab-case. It names the stable copy (`~/.<name>/`), the Claude Code
+   * plugin, and the commands install recognizes as its own.
+   */
+  name: string;
+  /**
+   * The calls to check. The agents' matchers are derived from it, and the
+   * check is only ever handed a call of one of these kinds. Codex sends every
+   * file change as one apply_patch, so a hook that takes `write` or `edit`
+   * must take `patch` too before it can be installed for Codex.
+   */
+  kinds: readonly K[];
+  /**
+   * Decides one call. Throwing, rejecting or returning anything but a verdict
+   * blocks the call.
+   */
+  check: (call: ToolCallOf<K>, context: HookContext) => HookVerdict | Promise<HookVerdict>;
+  /** The npm package whose bin runs the hook; a project install runs it through npx. Defaults to `name`. */
+  packageName?: string;
+  /** What the agent shows while the hook runs. Defaults to `Running <name>`. */
+  statusMessage?: string;
+  /**
+   * Seconds the agent waits for the hook. Defaults to 10. Past it Codex lets
+   * the call run, and Claude Code blocks it.
+   */
+  timeout?: number;
+}
+/** A checked hook definition, as {@link defineHook} returns it. */
+interface HookPlugin {
+  readonly name: string;
+  readonly packageName: string;
+  readonly kinds: readonly ToolKind[];
+  readonly statusMessage: string;
+  readonly timeout: number;
+  /** Called only with a call whose kind is in `kinds`. */
+  readonly check: (call: ToolCall, context: HookContext) => HookVerdict | Promise<HookVerdict>;
+}
+/** `claude` installs into `.claude/settings.json`, `codex` into `.codex/hooks.json`. */
+type Agent = 'claude' | 'codex';
+/** `user` writes the agent's config in the home directory, `project` the one in the working directory. */
+type Scope = 'user' | 'project';
+/**
+ * The PreToolUse matcher that routes the given kinds of call to the hook in
+ * one agent, such as `Bash|Write|Edit|MultiEdit|NotebookEdit` for every kind
+ * in Claude Code; empty when the agent has no tool of those kinds.
+ */
+export declare function matcherFor(agent: Agent, kinds: readonly ToolKind[]): string;
+/** A person or organisation, as the plugin and marketplace manifests take it. */
+interface ClaudePluginPerson {
+  name: string;
+  email?: string;
+  url?: string;
+}
+/** The plugin package's metadata; the hook itself comes from `plugin`. */
+interface ClaudePluginOptions {
+  plugin: HookPlugin;
+  /** The built bin, relative to the package root: `dist/cli.mjs`. */
+  entry: string;
+  /** The package version. Without it, Claude Code lists a plugin installed from npm as version `unknown`. */
+  version?: string;
+  description?: string;
+  author?: ClaudePluginPerson;
+  /** Must be a URL; Claude Code does not load a plugin whose homepage is not one. */
+  homepage?: string;
+  repository?: string;
+  license?: string;
+  keywords?: readonly string[];
+  /**
+   * Also writes `.claude-plugin/marketplace.json`: a marketplace of this one
+   * plugin, fetched from npm as `packageName`, at `version` (a version or
+   * range) or the latest one.
+   */
+  marketplace?: {
+    name: string;
+    owner: ClaudePluginPerson;
+    version?: string;
+  };
+}
+/**
+ * The files that make a plugin package a Claude Code plugin, by path relative
+ * 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
+ * no tool Claude Code has, or a field would make Claude Code refuse the
+ * plugin.
+ */
+export declare function claudePluginFiles(options: ClaudePluginOptions): Record<string, string>;
+/**
+ * Writes {@link claudePluginFiles} under `dir`, the plugin package's root, and
+ * returns the paths written. Run it from the package's build, and publish the
+ * written files with the build.
+ */
+export declare function writeClaudePlugin(dir: string, options: ClaudePluginOptions): string[];
+/** What the command line needs from its process, passed in so tests can supply it. */
+interface CliIO {
+  /** The tool call, read only by `hook`. */
+  stdin: () => string;
+  /** The built bin the installed hook runs. */
+  script: string;
+  /** The running Node.js version, as `process.version` gives it. */
+  node: string;
+  /** The running Node.js executable, which a user-scope hook keeps running on. */
+  execPath: string;
+  /** Holds the user-scope config and the stable copy of the build. */
+  home: string;
+  /** Holds the project-scope config, and is the hook's working directory when the payload names none. */
+  cwd: string;
+  stdout: (text: string) => void;
+  stderr: (text: string) => void;
+}
+/** How the command names itself. */
+interface CliOptions {
+  /** The command name in usage and error text, for a bin not named after the plugin. Defaults to the plugin's name. */
+  bin?: string;
+}
+/** Runs one command line and resolves to its exit code. */
+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`.
+ *
+ * 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.
+ */
+export declare function createCli(plugin: HookPlugin, options?: CliOptions): CliMain;
+/**
+ * Reads a stream to its end as UTF-8, `process.stdin` by default. A
+ * synchronous read of fd 0 fails with EAGAIN on a non-blocking pipe once the
+ * payload outgrows its buffer, so the hook reads this way. A read that fails
+ * resolves to `''`, which {@link runHook} blocks.
+ */
+export declare function readStdin(stream?: AsyncIterable<unknown>): Promise<string>;
+/**
+ * The whole bin: runs {@link createCli} on `process.argv`, reads stdin only for
+ * `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.
+ */
+export declare function runCli(plugin: HookPlugin, entryUrl: string, options?: CliOptions): Promise<void>;
+/**
+ * Checks a hook definition and returns the plugin every other function takes.
+ * Throws a `TypeError` naming the field when the definition is malformed, so a
+ * broken plugin fails when it is built, not when the hook runs.
+ */
+export declare function defineHook<const K extends ToolKind>(definition: HookDefinition<K>): HookPlugin;
+/** Where {@link runHook} falls back to and writes to; both default to the process. */
+interface RunHookOptions {
+  /** The working directory a payload without `cwd` gets. */
+  cwd?: string;
+  /** Receives the block reason or the error, newline-terminated. */
+  stderr?: (text: string) => void;
+}
+/**
+ * Runs one PreToolUse call through the plugin and returns the exit code the
+ * agent reads: 2 blocks the call, 0 lets it run.
+ *
+ * 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.
+ */
+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. */
+interface UninstallOptions {
+  plugin: HookPlugin;
+  agent: Agent;
+  scope: Scope;
+  /** The built bin the hook runs; its file name also picks out entries written before the stable copy existed. */
+  script: string;
+  /** Holds the user-scope config and the stable copy of the build. */
+  home: string;
+  /** Holds the project-scope config. */
+  cwd: string;
+}
+/** What {@link install} needs on top of {@link UninstallOptions}. */
+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. */
+interface InstallResult {
+  file: string;
+  command?: 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: {
+  home: string;
+  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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+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.
+ */
+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 };

package/dist/index.mjs

@@ -0,0 +1,567 @@
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, 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";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+// src/agents.ts
+const AGENTS = {
+	claude: {
+		label: "Claude Code",
+		dir: ".claude",
+		file: "settings.json"
+	},
+	codex: {
+		label: "Codex",
+		dir: ".codex",
+		file: "hooks.json"
+	}
+};
+const TOOLS = {
+	claude: {
+		Bash: "shell",
+		Write: "write",
+		Edit: "edit",
+		MultiEdit: "edit",
+		NotebookEdit: "write"
+	},
+	codex: {
+		Bash: "shell",
+		apply_patch: "patch"
+	}
+};
+const SELECTED_BY = {
+	shell: ["shell"],
+	write: ["write"],
+	edit: ["edit"],
+	patch: [
+		"write",
+		"edit",
+		"patch"
+	]
+};
+const KIND_OF_TOOL = new Map(Object.values(TOOLS).flatMap((tools) => Object.entries(tools)));
+function selected(agent, kinds) {
+	return Object.entries(TOOLS[agent]).filter(([, kind]) => SELECTED_BY[kind].some((by) => kinds.includes(by)));
+}
+/**
+* The PreToolUse matcher that routes the given kinds of call to the hook in
+* one agent, such as `Bash|Write|Edit|MultiEdit|NotebookEdit` for every kind
+* in Claude Code; empty when the agent has no tool of those kinds.
+*/
+function matcherFor(agent, kinds) {
+	return selected(agent, kinds).map(([tool]) => tool).join("|");
+}
+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`);
+	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("|");
+}
+// 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$/;
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+function entryOf(entry) {
+	const relative = entry.replace(/^\.\//, "");
+	if (!ENTRY.test(relative)) throw new TypeError(`entry ${JSON.stringify(entry)} is not a .mjs path inside the package`);
+	return relative;
+}
+/**
+* The files that make a plugin package a Claude Code plugin, by path relative
+* 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
+* no tool Claude Code has, or a field would make Claude Code refuse the
+* plugin.
+*/
+function claudePluginFiles(options) {
+	const { plugin, version, description, author, homepage, repository, license, keywords, marketplace } = options;
+	const matcher = requireMatcher("claude", plugin);
+	const entry = entryOf(options.entry);
+	if (RESERVED.test(plugin.name)) throw new TypeError(`Claude Code reserves plugin names like ${plugin.name} for Anthropic's own; name it for what it does`);
+	if (homepage !== void 0 && !URL.canParse(homepage)) throw new TypeError(`homepage ${JSON.stringify(homepage)} is not a URL`);
+	const files = {
+		".claude-plugin/plugin.json": json({
+			name: plugin.name,
+			version,
+			description,
+			author,
+			homepage,
+			repository,
+			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"
+			}]
+		}] } })
+	};
+	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`);
+		files[".claude-plugin/marketplace.json"] = json({
+			name: marketplace.name,
+			owner: marketplace.owner,
+			description,
+			plugins: [{
+				name: plugin.name,
+				source: {
+					source: "npm",
+					package: plugin.packageName,
+					version: marketplace.version
+				},
+				description
+			}]
+		});
+	}
+	return files;
+}
+/**
+* Writes {@link claudePluginFiles} under `dir`, the plugin package's root, and
+* returns the paths written. Run it from the package's build, and publish the
+* written files with the build.
+*/
+function writeClaudePlugin(dir, options) {
+	return Object.entries(claudePluginFiles(options)).map(([path, text]) => {
+		const file = join(dir, path);
+		mkdirSync(dirname(file), { recursive: true });
+		writeFileSync(file, text);
+		return file;
+	});
+}
+// src/hook.ts
+const isObject$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function stringField(input, key) {
+	const value = input[key];
+	if (value === void 0 || value === null) return "";
+	if (typeof value !== "string") throw new TypeError(`${key} is not a string`);
+	return value;
+}
+function record(value, key) {
+	if (value === void 0 || value === null) return {};
+	if (!isObject$1(value)) throw new TypeError(`${key} is not an object`);
+	return value;
+}
+function editList(input) {
+	const edits = input.edits ?? [];
+	if (!Array.isArray(edits)) throw new TypeError("edits is not a list");
+	return edits.map((edit) => record(edit, "edit"));
+}
+function toToolCall(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",
+			command: text("command")
+		};
+		case "Write": return {
+			kind: "write",
+			path: text("file_path"),
+			content: text("content")
+		};
+		case "NotebookEdit": return {
+			kind: "write",
+			path: text("notebook_path"),
+			content: text("new_source")
+		};
+		case "Edit": return {
+			kind: "edit",
+			path: text("file_path"),
+			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")
+		};
+		default: throw new TypeError(`${tool} is not a tool the hook reads`);
+	}
+}
+function verdictOf(value) {
+	if (isObject$1(value) && value.block === false) return { block: false };
+	if (isObject$1(value) && value.block === true && typeof value.reason === "string" && value.reason.trim() !== "") return {
+		block: true,
+		reason: value.reason
+	};
+	throw new TypeError("check returned neither { block: false } nor { block: true, reason }");
+}
+/**
+* Runs one PreToolUse call through the plugin and returns the exit code the
+* agent reads: 2 blocks the call, 0 lets it run.
+*
+* 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.
+*/
+async function runHook(plugin, stdin, options = {}) {
+	const stderr = options.stderr ?? ((text) => void process.stderr.write(text));
+	let verdict;
+	try {
+		const payload = JSON.parse(stdin);
+		if (!isObject$1(payload)) throw new TypeError("payload is not an object");
+		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);
+		if (kind === void 0 || !plugin.kinds.includes(kind)) return 0;
+		const call = toToolCall(tool, record(payload.tool_input, "tool_input"));
+		const cwd = stringField(payload, "cwd") || (options.cwd ?? process.cwd());
+		verdict = verdictOf(await plugin.check(call, { cwd }));
+	} catch (error) {
+		stderr(`Blocked by ${plugin.name}, it could not check the call: ${error instanceof Error ? error.message : String(error)}\n`);
+		return 2;
+	}
+	if (!verdict.block) return 0;
+	stderr(verdict.reason.endsWith("\n") ? verdict.reason : `${verdict.reason}\n`);
+	return 2;
+}
+// src/install.ts
+/** 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];
+	return join(scope === "project" ? place.cwd : place.home, dir, file);
+}
+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`;
+}
+const QUOTED = String.raw`(?:[^']|'\\'')*`;
+function ownHook(plugin, entry) {
+	const name = escape(plugin.name);
+	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 builtFiles = (dir) => readdirSync(dir).filter((name) => name.endsWith(".mjs")).sort();
+function buildId(dir) {
+	const hash = createHash("sha256");
+	for (const name of builtFiles(dir)) hash.update(name).update("\0").update(readFileSync(join(dir, name)));
+	return hash.digest("hex").slice(0, 12);
+}
+function copyBuild(plugin, script, root) {
+	if (!script.endsWith(".mjs") || !existsSync(script)) throw new Error(`${script} is not a built ${plugin.name} entry; run install from the published package or a build`);
+	const source = dirname(script);
+	const id = buildId(source);
+	const target = join(root, id);
+	if (!existsSync(target) || buildId(target) !== id) {
+		mkdirSync(root, { recursive: true });
+		const staging = mkdtempSync(`${target}-`);
+		try {
+			for (const name of builtFiles(source)) copyFileSync(join(source, name), join(staging, name));
+			if (existsSync(target) && buildId(target) !== id) renameSync(target, `${staging}-stale`);
+			if (!existsSync(target)) renameSync(staging, target);
+		} catch (error) {
+			if (!existsSync(target) || buildId(target) !== id) throw error;
+		} finally {
+			rmSync(staging, {
+				recursive: true,
+				force: true
+			});
+			rmSync(`${staging}-stale`, {
+				recursive: true,
+				force: true
+			});
+		}
+	}
+	return id;
+}
+function probe(file, node) {
+	const ran = spawnSync(node, [file, "hook"], {
+		input: "{\"tool_name\":\"Read\"}",
+		encoding: "utf8",
+		timeout: 1e4
+	});
+	if (ran.status === 0) return;
+	const why = ran.error?.message ?? ran.stderr.trim().split("\n").find((line) => /error/i.test(line)) ?? `exit ${ran.status ?? ran.signal}`;
+	throw new Error(`the copy of the build at ${file} does not run on its own (${why}); the bin's directory must hold the whole build as .mjs files, with its dependencies bundled in`);
+}
+function linkCurrent(root, id) {
+	const current = join(root, "current");
+	if (existsSync(current) && !lstatSync(current).isSymbolicLink()) throw new Error(`${current} is not the link install writes; move it away and install again`);
+	const link = `${current}.${process.pid}`;
+	try {
+		rmSync(link, { force: true });
+		symlinkSync(id, link);
+		renameSync(link, current);
+	} finally {
+		rmSync(link, { force: true });
+	}
+	return current;
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function readSettings(file) {
+	if (!existsSync(file)) return {};
+	let settings;
+	try {
+		settings = JSON.parse(readFileSync(file, "utf8"));
+	} catch (error) {
+		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`);
+	return settings;
+}
+function writeConfig(file, text) {
+	const real = existsSync(file) ? realpathSync(file) : file;
+	mkdirSync(dirname(real), { recursive: true });
+	const temp = `${real}.${process.pid}.tmp`;
+	try {
+		writeFileSync(temp, text);
+		if (existsSync(real)) chmodSync(temp, statSync(real).mode & 4095);
+		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;
+		return {
+			...item,
+			hooks: rest
+		};
+	}).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`);
+}
+/**
+* Adds the plugin's PreToolUse hook to one agent's config, replacing any entry
+* it wrote before 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.
+*
+* 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.
+*/
+function install(options) {
+	const { plugin, agent, scope, script } = options;
+	const matcher = requireMatcher(agent, plugin);
+	const file = configFile(agent, scope, options);
+	const settings = readSettings(file);
+	let target = script;
+	if (scope === "user") {
+		const root = join(options.home, `.${plugin.name}`);
+		const id = copyBuild(plugin, script, root);
+		probe(join(root, id, basename(script)), options.execPath);
+		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" } : {}
+		}]
+	});
+	return {
+		file,
+		command
+	};
+}
+/**
+* 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.
+*/
+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 };
+}
+// src/cli.ts
+const isAgent = (word) => word === "claude" || word === "codex";
+function usage(bin) {
+	const rows = [
+		["install <claude|codex> [--project]", "add the PreToolUse hook"],
+		["uninstall <claude|codex> [--project]", "remove it"],
+		["hook", "run as the hook (reads the tool call 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`.
+*
+* 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.
+*/
+function createCli(plugin, options = {}) {
+	const bin = options.bin ?? plugin.name;
+	return async (argv, io) => {
+		const [command, agent, ...flags] = argv;
+		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 === "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 = {
+				plugin,
+				agent,
+				scope: project ? "project" : "user",
+				script: io.script,
+				home: io.home,
+				cwd: io.cwd
+			};
+			let file;
+			try {
+				file = command === "install" ? install({
+					...place,
+					execPath: io.execPath
+				}).file : uninstall(place).file;
+			} 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`);
+			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));
+		return 1;
+	};
+}
+/**
+* Reads a stream to its end as UTF-8, `process.stdin` by default. A
+* synchronous read of fd 0 fails with EAGAIN on a non-blocking pipe once the
+* payload outgrows its buffer, so the hook reads this way. A read that fails
+* resolves to `''`, which {@link runHook} blocks.
+*/
+async function readStdin(stream = process.stdin) {
+	const chunks = [];
+	try {
+		for await (const chunk of stream) chunks.push(Buffer.from(chunk));
+	} catch {
+		return "";
+	}
+	return Buffer.concat(chunks).toString("utf8");
+}
+/**
+* The whole bin: runs {@link createCli} on `process.argv`, reads stdin only for
+* `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.
+*/
+async function runCli(plugin, entryUrl, options = {}) {
+	const argv = process.argv.slice(2);
+	const hook = argv[0] === "hook";
+	let done = false;
+	if (hook) {
+		process.exitCode = 2;
+		process.once("beforeExit", () => {
+			if (!done) process.stderr.write(`Blocked by ${plugin.name}, its check never finished\n`);
+		});
+	}
+	try {
+		const input = hook ? await readStdin() : "";
+		process.exitCode = await createCli(plugin, options)(argv, {
+			stdin: () => input,
+			script: fileURLToPath(entryUrl),
+			node: process.version,
+			execPath: process.execPath,
+			home: homedir(),
+			cwd: process.cwd(),
+			stdout: (text) => void process.stdout.write(text),
+			stderr: (text) => void process.stderr.write(text)
+		});
+		done = true;
+	} catch (error) {
+		done = true;
+		process.stderr.write(`${options.bin ?? plugin.name}: ${error instanceof Error ? error.message : String(error)}\n`);
+		process.exitCode = hook ? 2 : 1;
+	}
+}
+// src/define.ts
+const KINDS = [
+	"shell",
+	"write",
+	"edit",
+	"patch"
+];
+const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const PACKAGE = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+/**
+* Checks a hook definition and returns the plugin every other function takes.
+* Throws a `TypeError` naming the field when the definition is malformed, so a
+* 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;
+	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`);
+	return Object.freeze({
+		name,
+		packageName,
+		kinds: Object.freeze([...new Set(kinds)]),
+		statusMessage,
+		timeout,
+		check
+	});
+}
+export { claudePluginFiles, configFile, createCli, defineHook, install, matcherFor, readStdin, runCli, runHook, uninstall, writeClaudePlugin };

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "agent-base-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "type": "module",
+  "version": "0.1.0",
+  "packageManager": "pnpm@10.23.0",
+  "description": "Turn any check into a fail-closed PreToolUse hook for Claude Code and Codex: tool-call parsing, install and uninstall, a stable copy of the build, and Claude Code plugin files. Zero dependencies.",
+  "author": "devmaxxx",
+  "license": "MIT",
+  "homepage": "https://github.com/devmaxxx/agent-kit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/devmaxxx/agent-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/devmaxxx/agent-kit/issues"
+  },
+  "keywords": [
+    "ai-agent",
+    "claude-code",
+    "claude-code-plugin",
+    "codex",
+    "hook",
+    "pretooluse",
+    "guard",
+    "policy",
+    "security"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "lint": "eslint .",
+    "typecheck": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm run build"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^9.5.1",
+    "@types/node": "^26.6.5",
+    "eslint": "^10.13.0",
+    "publint": "^0.3.25",
+    "tsdown": "^0.23.1",
+    "typescript": "^6.0.3",
+    "unrun": "^0.3.1",
+    "vitest": "^5.0.5"
+  }
+}