agent-base-kit 0.0.0-stage → 0.1.1

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,147 @@
-# 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
+
+**The base kit for Claude Code and Codex hooks.**
+
+[![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-base-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/devmaxxx/agent-base-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)
+
+[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)
+
+</div>
+
+## Why
+
+A [PreToolUse hook](https://code.claude.com/docs/en/hooks) is the last point where you can stop an agent's tool call. Every hook needs the same plumbing before its own check: read the agent's payload, write the agent's config without breaking anyone else's entries, keep running across Node.js upgrades, and block when the check cannot run, since the agents treat every exit except 2 as "go on".
+
+agent-base-kit is that plumbing, shared by every hook you build. You write the check; reuse the rest for a secret scanner, a policy guard, or any other hook.
+
+## 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.
+- **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.
+- **Other hooks left alone.** Install and uninstall touch only their own entry, and refuse a config they cannot extend safely.
+- **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 or a rebuild does not switch it off.
+- **Claude Code plugin files.** One call writes the manifest, `hooks.json` and a marketplace.
+- **Zero dependencies**, ESM only, typed.
+
+## Usage
+
+```sh
+pnpm add -D agent-base-kit
+```
+
+Write the check and hand it to `runCli` in your bin:
+
+```ts
+#!/usr/bin/env node
+import { defineHook, runCli } from 'agent-base-kit'
+
+const plugin = defineHook({
+  name: 'no-force-push',
+  kinds: ['shell'],
+  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 },
+})
+
+void runCli(plugin, import.meta.url)
+```
+
+Bundle the bin into `.mjs` files with agent-base-kit inlined, for example with tsdown, since the stable copy has no `node_modules`. Your users then run:
+
+```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
+```
+
+Requires Node.js 22 or later and a POSIX shell.
+
+## What install writes
+
+A user install (the default scope) does four things:
+
+1. **Copies the build.** The `.mjs` files beside your bin go to `~/.<name>/<build-id>/`, where the id is a hash of their content. The same build reuses its directory, a new build gets a new one, and the copy is staged and renamed in, so a hook never loads a half-written one.
+2. **Runs the copy once.** Before any config points at it, the copy runs on a tool no kind covers. If it cannot start, `install` refuses and changes nothing.
+3. **Swaps `~/.<name>/current`.** One rename moves the link to the new build, so the hook command stays the same across versions and Codex keeps trusting it.
+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
+```
+
+`--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.
+
+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.
+
+## The fail-closed contract
+
+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, 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 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. |
+
+Keep `check` well inside `timeout`, which defaults to 10 seconds.
+
+## Kinds and matchers
+
+`kinds` decides which calls reach your check, and 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` |
+
+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.
+
+## 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 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[]
+```
+
+`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.
+
+## Contributing
+
+```sh
+git clone https://github.com/devmaxxx/agent-base-kit.git
+cd agent-base-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.1",
+  "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",
+  "license": "MIT",
+  "homepage": "https://github.com/devmaxxx/agent-base-kit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/devmaxxx/agent-base-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/devmaxxx/agent-base-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"
+  }
+}