bantamkit-mcp 0.35.3 → 0.35.4

package/README.md

@@ -6,9 +6,13 @@ command, connect it to **Claude Code**, **Claude Desktop**, **Cursor** or **GitH
 Code**, and every later launch starts **offline**. No Python, `pip`, `uv`, `pipx` or venv.
 
 It serves the same fourteen tools, `bantamkit_status` prompt and two resource templates as the
-Python server on **PyPI** (`pip install "bantamkit[mcp]"`), and reads and writes the same memory
-store. The two are compared frame by frame: 8,130 conformance cases on 2026-09-15, with every
-intentional difference written down as a ruling.
+Python server — [`bantamkit` on PyPI](https://pypi.org/project/bantamkit/) — and reads and
+writes the same memory store. The two are compared frame by frame: 8,130 conformance cases on
+2026-09-15, with every intentional difference written down as a ruling.
+
+**This page is the npm package's.** Every command on it runs `bantamkit-mcp` from npm. The
+Python package is named where the two differ, but its own install, update and CLI commands live
+on [its page](https://pypi.org/project/bantamkit/); run them here and you get nothing.
 
 ## Contents
 
@@ -31,6 +35,7 @@ intentional difference written down as a ruling.
 | [Memory stores are layered by default](#memory-stores-are-layered-by-default) | Why not to add `--store` by reflex |
 | [The asset pack](#the-asset-pack) | What ships in `assets/` and how it is found |
 | [Where the Python and Node servers differ](#where-the-python-and-node-servers-differ) | One store; concurrent writes, one hand-edit to avoid |
+| [Module API](#module-api) | The one entry point, all 139 exports it reaches, and the one break in `clockIn` |
 | [Development](#development) | Build, test, conformance |
 | [Measurements and history](#measurements-and-history) | Where the measured numbers behind this page live |
 
@@ -107,7 +112,6 @@ Each host below has the same steps: **1** command, **2** file, **3** entry, **4*
 | Route | `command` | `args` |
 |---|---|---|
 | npm, install once | `/absolute/path/to/node` | `["/Users/you/.bantamkit/mcp/node_modules/bantamkit-mcp/dist/cli.js"]` |
-| Python venv | `/absolute/path/to/env/bin/bantamkit-mcp` | `[]` |
 | npx every launch | `npx` | `["-y", "bantamkit-mcp"]` |
 
 A JSON file cannot expand `~`, so spell both paths out. To check a recorded command, run it in
@@ -226,9 +230,12 @@ It is the only network access here — not at startup, not on `bantamkit_status`
 | `npx -y bantamkit-mcp --install <host>` from 0.34.0: a kept install at `~/.bantamkit/mcp` | `npx -y bantamkit-mcp@latest --update` patches it in place, or `npm i --prefix ~/.bantamkit/mcp bantamkit-mcp@latest`. The recorded paths do not change. Before 0.34.0, `--update` from an npx cache refuses instead |
 | `npm i -g bantamkit-mcp` | `npm i -g bantamkit-mcp@latest` |
 | `npm i --prefix <dir> bantamkit-mcp` | `npm i --prefix <dir> bantamkit-mcp@latest` |
-| PyPI (`pip install "bantamkit[mcp]"`) | `pip install -U "bantamkit[mcp]"` · pipx: `pipx upgrade bantamkit` · uv: `uv tool upgrade bantamkit` |
 | a checkout, via `tools/bantamkit-mcp-node` | `git pull && npm ci --prefix runtime-ts && npm run build --prefix runtime-ts` — no registry, and `runtime-ts/dist/` is build output, so a pull alone changes nothing |
 
+No row above is the Python package. If what you have is **`bantamkit` from PyPI** instead, it
+updates by its own route, written on [its PyPI page](https://pypi.org/project/bantamkit/); the
+two sets of commands are not interchangeable.
+
 **Then restart the server in your host** — a running server keeps serving the code it loaded at
 startup. In Claude Code: `/mcp` → reconnect. In Claude Desktop: a full restart of the app.
 
@@ -405,6 +412,100 @@ are deliberate and each is ruled in the
   the whole store with `malformed fact file …`. Quote it: `description: '2026'`. Every fact the
   tools *write* is quoted correctly (`src/memory/factfile.ts:257`).
 
+## Module API
+
+The package is a server first, but it is importable too: `exports` maps exactly one entry
+point — `.` — to `dist/index.js` and `dist/index.d.ts`, so `import { clockIn } from
+'bantamkit-mcp'` is a supported call, and the names and arities behind that entry point are
+part of what is published.
+
+Everything in this section was measured against the **tarball**, not the source tree: `npm
+pack`, extracted into a throwaway package's `node_modules`, and imported by `node`. A name in
+`src/` that no entry point reaches is not API; the table below is what an importer gets.
+
+**One entry point, and nothing beside it.** There are no subpaths, so every deep import is
+refused by Node's resolver:
+
+| specifier | result |
+| --- | --- |
+| `bantamkit-mcp` | 139 value exports, 26 type-only exports |
+| `bantamkit-mcp/dist/cli.js` | `ERR_PACKAGE_PATH_NOT_EXPORTED` |
+| `bantamkit-mcp/dist/shiftwork.js` | `ERR_PACKAGE_PATH_NOT_EXPORTED` |
+| `bantamkit-mcp/package.json` | `ERR_PACKAGE_PATH_NOT_EXPORTED` |
+| `bantamkit-mcp/assets/tools/memory_save.json` | `ERR_PACKAGE_PATH_NOT_EXPORTED` |
+
+**So what you can import is the library half, not the server.** The MCP server and its
+transport, both CLIs, the host-install and self-update code, the hook adapter, the document
+reader, the repo map, the skill audit, the token ledger, the pricing table and the work planner
+all ship inside `dist/` and none of them is reachable through an import — they are reached by
+running `bantamkit-mcp` and `bantamkit-memory`. Importing the package starts no server and
+opens no transport. The vendored `assets/` is not importable either, but it is *readable*:
+`assetsRoot()` resolves to the `assets/` directory inside the installed package, which is how
+`loadTool('memory_save')` answers from a consumer that never unpacked anything itself.
+
+**What the one entry point exports**, grouped by the module each name comes from:
+
+| module | what it is | exported names |
+| --- | --- | --- |
+| `errors.js` | The base error every other one extends | `BantamError` |
+| `contract.js` | The JSON-answer contract: load it, pull JSON out of a model reply, compose the retry feedback | `ContractParseError`, `extractJson`, `loadContract`, `parseContractDocument`, `parseErrorMessage`, `REQUIRED_KEYS`, `schemaError`, `schemaRetryFeedback`, `validationErrorMessage` |
+| `pyjson.js` | CPython `json` semantics over a `PyValue` tree — float repr and decode errors included | `dumpJson`, `fromJs`, `parseJson`, `PY_NONE`, `pyFloatRepr`, `PyJSONDecodeError`, `PyValueError`, `rawDecode`, `reprValue`, `toJs`<br>*types:* `DumpOptions`, `PyValue` |
+| `pyjsonschema.js` | The JSON Schema validator, with CPython `jsonschema`'s error ordering and best-match | `absolutePath`, `bestMatch`, `iterErrors`, `pyEqual`, `PyJsonSchemaUnsupported`, `validate`<br>*types:* `PyValidationError` |
+| `assets.js` | The vendored asset pack: schemas, skills and tool definitions | `AssetNotFound`, `assetsRoot`, `loadSchema`, `loadSkill`, `loadTool`, `loadToolAsset`<br>*types:* `Tool` |
+| `memory/factfile.js` | One fact file: frontmatter, parse, format | `decodeFactBytes`, `FactParseError`, `formatFact`, `parseFactText`, `parseFrontmatter`, `pySplit`, `pyStrip`, `todayLocal`<br>*types:* `Fact`, `FactMeta`, `FactValue` |
+| `memory/pyyaml.js` | The YAML subset PyYAML's safe loader and dumper accept | `constructPlain`, `PyScalar`, `resolveImplicitTag`, `safeDumpMapping`, `YamlConstructError`, `YamlEmitError`<br>*types:* `PyOrder`, `YamlScalar`, `YamlValue` |
+| `memory/layers.js` | Which stores a recall reads, and where the project store is | `countFacts`, `discoverProjectStore`, `loadGrants`, `MEMORY_DIR_ENV`, `PROJECT_STORE`, `resolveProjectStore`<br>*types:* `StoreBinding` |
+| `memory/component.js` | `Memory`, the save/recall/compact/dream component the server calls | `layerLabel`, `Memory`, `normalizeName`, `profileStore`<br>*types:* `CompactOutcome`, `DreamOutcome`, `MemoryOptions`, `RecallOutcome`, `SaveOutcome` |
+| `memory/dream.js` | The consolidation pass: similarity, merge, supersede | `absolutise`, `blockKey`, `claimSlot`, `collapse`, `dream`, `formatFixed3`, `mergeBodies`, `mergeDescriptions`, `mergeLinks`, `PROFILE_LAYER`, `PROJECT_LAYER`, `pyIntDigits`, `sortedNames`, `splitBlocks`, `SUPERSEDED_HEADING`<br>*types:* `DateHit`, `DreamMerge`, `DreamResult`, `SimilarPair`, `Superseded` |
+| `eventlog.js` | The JSONL event log | `CAP_BYTES`, `DEFAULT_RELATIVE_PATH`, `defaultPath`, `encodeRecord`, `EVENT_LOG_ENV`, `EventLog`, `formatTimestamp`, `resolvePath`, `SCHEMA_VERSION`<br>*types:* `DetailValue` |
+| `memory/store.js` | `MemoryStore`: the on-disk store, its budgets and its dedupe | `BANTAMKIT_GITIGNORE_TEXT`, `DEFAULT_INDEX_BUDGET`, `DUPLICATE_JACCARD`, `ensureBantamkitGitignore`, `jaccard`, `MemoryBudgetExceeded`, `MemoryStore`, `MemoryValidationError`, `pyCompareLt`, `pyEqualValue`, `pyHashKey`, `pyText`, `RECALL_MIN_SCORE_RATIO`, `sortScored`, `tokens`, `VALID_TYPES`<br>*types:* `MemoryStoreOptions`, `SaveResult`, `StoreInternals` |
+| `memory/pyfs.js` | CPython `pathlib` and `os.path` semantics over `node:fs`, error numbering included | `asPyOSError`, `cmpCodepoint`, `matchesMd`, `normcase`, `pyAppendText`, `pyCwd`, `pyDecodeUtf8`, `pyExists`, `pyExpanduser`, `pyHome`, `pyIsAbsolute`, `pyIsDir`, `pyIsFile`, `pyJoin`, `pyLexists`, `pyMkdirParents`, `pyMtimeDate`, `pyName`, `PyOSError`, `pyParent`, `pyParents`, `pyReadText`, `pyReplace`, `pyRepr`, `pyResolve`, `PyRuntimeError`, `pyScandirNames`, `pyStatIsDir`, `pySuffix`, `PyUnicodeDecodeError`, `pyUnlink`, `pyWithSuffix`, `pyWriteText`, `sortedPathNames`, `sortedPathParts`, `STRERROR_NAMES` |
+| `shiftwork.js` | The shift-work checkpoint tools | `clockIn`, `clockOut`, `HISTORY_RING_SIZE`, `SCHEMA_NAME`, `status`, `TERMINAL_UNIT_STATUS`, `timestamp`<br>*types:* `ClockOptions` |
+| **14 modules** | | **139 values, 26 types** |
+
+Two things that table is easy to misread. The `py*` names are not a Python bridge — they are
+this port's re-implementations of CPython semantics (`pyfs.js` alone is 36 of the 139), and
+they are exported because the conformance harness and the operator tooling call them, not
+because an application should. And `Function.length` is not the signature: `clockIn.length` is
+`1` because two of its three parameters have defaults.
+
+**One export changed shape.** `clockIn` took a unit id as its **second positional parameter**,
+ahead of the options object:
+
+```ts
+clockIn(checkpoint: string, unitId: string | null = null, options: ClockOptions = {}): PyValue
+```
+
+A caller who wrote `clockIn(path, { now })` must now write `clockIn(path, null, { now })`, and
+`clockIn(path, 'U3')` briefs a named ready unit. TypeScript rejects the old shape at the type;
+plain JavaScript does not — the object lands in the id slot, the call asks for a unit named
+`[object Object]`, and `now` is dropped, which is a wrong answer rather than an error.
+`clockOut` is unchanged. The reasoning and the measurement behind it are in
+[docs/porting.md → The published export surface](https://github.com/Ink01101011/bantamkit/blob/main/docs/porting.md#the-published-export-surface-and-the-one-break-in-it);
+`docs/` is not in the npm tarball (`files: ["dist", "assets"]`), which is why the migration line
+is repeated here.
+
+**Rerun the whole table.** From a clone, in `runtime-ts/`:
+
+```sh
+npm pack --pack-destination /tmp/bk
+mkdir -p /tmp/bk/consumer/node_modules/bantamkit-mcp
+tar -xzf /tmp/bk/bantamkit-mcp-*.tgz -C /tmp/bk/consumer/node_modules/bantamkit-mcp --strip-components=1
+printf '{"name":"c","private":true,"type":"module"}' > /tmp/bk/consumer/package.json
+cd /tmp/bk/consumer && node -e "import('bantamkit-mcp').then((m) => console.log(Object.keys(m).length))"
+```
+
+It prints `139`, with no `npm install` and nothing fetched: `dist/index.js` pulls in none of the
+server code, so the one runtime dependency is never reached. The 26 type-only exports are in the
+same tarball — from `/tmp/bk/consumer`:
+
+```sh
+node -e "const t=require('fs').readFileSync('node_modules/bantamkit-mcp/dist/index.d.ts','utf8');console.log([...t.matchAll(/export type \{([^}]*)\}/g)].flatMap((m) => m[1].split(',')).map((x) => x.trim()).filter(Boolean).length)"
+```
+
+Both numbers move whenever `src/index.ts` does, which is why they are quoted with the command
+that prints them rather than kept in prose.
+
 ## Development
 
 ```sh

package/assets/tools/shiftwork_clock_in.json

@@ -1,6 +1,6 @@
 {
   "name": "shiftwork_clock_in",
-  "description": "Shift-work clock-in: schema-validate the checkpoint file and return the brief for the unit at plan.cursor — {unit, role, invariants, handoff, do_not, files} — to hand to the spawned agent verbatim. Structured refusals, never exceptions: result=escalate when handoff.open_questions is non-empty, result=success when every unit is done or dropped, result=error when the checkpoint fails validation. Clock-in also WRITES: on result=brief, and only then, it appends one line {event: brief, ts, unit, role} to <checkpoint>.log.jsonl — best-effort: a log it cannot write costs the brief nothing (the brief still returns, no error, only the record is lost). clock_out reads those lines back to write `briefed` on every accounting line, so the ledger is no longer one line per clock-out; a brief line carries `event` and no `status`. See docs/shiftwork.md.",
+  "description": "Shift-work clock-in: schema-validate the checkpoint file and return the brief for the unit at plan.cursor — {unit, role, invariants, handoff, do_not, files} — to hand to the spawned agent verbatim. The unit briefed is the one at plan.cursor, or, when unit_id is given, that unit — which must appear in shiftwork_plan's `ready`, the batch the dependency graph says may run now. A unit_id that is not ready, including one naming no unit, is refused with {\"result\": \"error\", \"reason\": \"unit <id> is not ready; ready is <a, b>\"}, and the refusals of the batch view itself (cycle, unknown dependency, unreadable checkpoint) pass through verbatim. Clock-in still never moves plan.cursor; clock_out does. Structured refusals, never exceptions: result=escalate when handoff.open_questions is non-empty, result=success when every unit is done or dropped, result=error when the checkpoint fails validation. Clock-in also WRITES: on result=brief, and only then, it appends one line {event: brief, ts, unit, role} to <checkpoint>.log.jsonl — best-effort: a log it cannot write costs the brief nothing (the brief still returns, no error, only the record is lost). clock_out reads those lines back to write `briefed` on every accounting line, so the ledger is no longer one line per clock-out; a brief line carries `event` and no `status`. See docs/shiftwork.md.",
   "surfaces": [
     "mcp"
   ],
@@ -9,6 +9,18 @@
       "checkpoint": {
         "title": "Checkpoint",
         "type": "string"
+      },
+      "unit_id": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Unit Id"
       }
     },
     "required": [

package/assets/tools/shiftwork_clock_out.json

@@ -1,6 +1,6 @@
 {
   "name": "shiftwork_clock_out",
-  "description": "Shift-work clock-out: record a finished unit — set its status, advance plan.cursor, merge handoff_patch, push history_entry onto the 5-entry ring — validating the whole mutated document against the checkpoint schema BEFORE an atomic write (a failure writes nothing and returns result=error). `unit_id` must be `plan.cursor`, the one unit clock_in briefs; any other id is refused (`unit X is not the cursor unit Y`). `handoff_patch` and `history_entry` are both required arguments: `handoff_patch` is shallow-merged into `handoff` and takes only its four keys (pass `{}` to leave it unchanged); `history_entry` needs `unit` and `outcome`; `status` is one of the five unit statuses — a value outside these shapes is refused by the schema check, nothing written. Every success appends one accounting line (unit, role, status, ts, briefed, plus your accounting fields, e.g. tokens/duration_ms/model) to <checkpoint>.log.jsonl, beside the brief lines clock_in writes (a brief line carries `event` and no `status`). `accounting` is optional: null, the default, logs a line with no cost figures at all; a non-null line must fit the accounting shape below. `briefed` is written by the runtime, never taken from you — a self-reported value is overwritten by the measured one: true when a brief was issued for this unit since its LAST clock-out (not ever), so a unit re-run inline after a blocked clock-out reads false. A brief is not a precondition: a unit that was never clocked in still clocks out, with briefed=false. If the checkpoint's job.roles names this unit's role, accounting.model must be one of that role's model identifiers, spelled exactly — a model that is not on the list, or none reported at all, is refused before anything is written; a role job.roles omits, and a checkpoint carrying no job.roles, are unconstrained.",
+  "description": "Shift-work clock-out: record a finished unit — set its status, advance plan.cursor, merge handoff_patch, push history_entry onto the 5-entry ring — validating the whole mutated document against the checkpoint schema BEFORE an atomic write (a failure writes nothing and returns result=error). `unit_id` must be `plan.cursor` — which needs no brief, clocking out with briefed=false — OR a unit briefed since its own last clock-out; any other id keeps its refusal (`unit X is not the cursor unit Y`). plan.cursor then advances to the head of the ready batch recomputed on the mutated document, falling back to plan.units order over the remaining non-terminal units when the graph cannot batch (cycle or unknown dependency), and to unit_id when none remain. `handoff_patch` and `history_entry` are both required arguments: `handoff_patch` is shallow-merged into `handoff` and takes only its four keys (pass `{}` to leave it unchanged); `history_entry` needs `unit` and `outcome`; `status` is one of the five unit statuses — a value outside these shapes is refused by the schema check, nothing written. Every success appends one accounting line (unit, role, status, ts, briefed, plus your accounting fields, e.g. tokens/duration_ms/model) to <checkpoint>.log.jsonl, beside the brief lines clock_in writes (a brief line carries `event` and no `status`). `accounting` is optional: null, the default, logs a line with no cost figures at all; a non-null line must fit the accounting shape below. `briefed` is written by the runtime, never taken from you: true when a brief was issued for this unit since its LAST clock-out (not ever), so a unit re-run after a blocked clock-out reads false. If job.roles names this unit's role, accounting.model must be one of that role's model identifiers, spelled exactly, or nothing is written — see the `model` property below.",
   "surfaces": [
     "mcp"
   ],
@@ -13,7 +13,7 @@
       "unit_id": {
         "title": "Unit Id",
         "type": "string",
-        "description": "The unit being clocked out. Must equal plan.cursor — the single-pointer contract: clock_in briefs only the cursor unit and clock_out accepts only it."
+        "description": "The unit being clocked out. Must be plan.cursor, or a unit briefed since its own last clock-out: clock_in briefs the cursor unit by default and, when its unit_id names one, any unit shiftwork_plan reports in `ready` — and that brief is what lets clock_out accept a unit the cursor is not on."
       },
       "status": {
         "title": "Status",

package/assets/tools/shiftwork_plan.json

@@ -1,6 +1,6 @@
 {
   "name": "shiftwork_plan",
-  "description": "Shift-work plan: read-only batch view of a checkpoint — which units its `depends_on` graph permits to run in parallel. Answers `{\"result\": \"plan\", \"batches\", \"ready\", \"sequence\", \"width\", \"cursor\"}`: `ready` is `batches[0]`, the units whose dependencies are all satisfied, and `width` is the largest batch length, the widest fan-out. Only `cursor` can be clocked: shiftwork_clock_in briefs it and shiftwork_clock_out refuses every other id, so a `ready` member beyond the cursor is what the graph permits, not a unit the clock accepts yet. Units with status `done` or `dropped` are satisfied — dropped from the graph, and edges pointing at them treated as already resolved; `todo`, `in_progress` and `blocked` stay in it. Every unit has priority 0, because the checkpoint schema has no priority field, so order inside a batch is `plan.units` order. Same refusal sentences as `work_plan` for a duplicate id, an unknown dependency or a cycle, and the same refusals `shiftwork_status` gives for a checkpoint it cannot read. It reports what the dependency graph permits; it does not move the cursor, which is echoed unchanged so the single-pointer contract and the batch view can be read side by side. An orchestrator stays responsible for what it actually dispatches: `depends_on` encodes logical order, not file contention. Never mutates.",
+  "description": "Shift-work plan: read-only batch view of a checkpoint — which units its `depends_on` graph permits to run in parallel. Answers `{\"result\": \"plan\", \"batches\", \"ready\", \"sequence\", \"width\", \"cursor\"}`: `ready` is `batches[0]`, the units whose dependencies are all satisfied, and `width` is the largest batch length, the widest fan-out. A `ready` member beyond the cursor is clockable, but only in that order: shiftwork_clock_in briefs any unit in `ready` when `unit_id` names it, and shiftwork_clock_out then accepts that unit because it was briefed — an id that is neither the cursor nor briefed since its own last clock-out is still refused. Units with status `done` or `dropped` are satisfied — dropped from the graph, and edges pointing at them treated as already resolved; `todo`, `in_progress` and `blocked` stay in it. Every unit has priority 0, because the checkpoint schema has no priority field, so order inside a batch is `plan.units` order. Same refusal sentences as `work_plan` for a duplicate id, an unknown dependency or a cycle, and the same refusals `shiftwork_status` gives for a checkpoint it cannot read. It reports what the dependency graph permits; it does not move the cursor, which is echoed unchanged so the single-pointer contract and the batch view can be read side by side. An orchestrator stays responsible for what it actually dispatches: `depends_on` encodes logical order, not file contention. Never mutates.",
   "surfaces": [
     "mcp"
   ],

package/dist/cli.d.ts

@@ -6,11 +6,15 @@ export interface Options {
     store: string | null;
     start: string | null;
     assetsRoot: boolean;
+    hook: boolean;
     mcpReport: boolean;
     statusline: boolean;
     update: boolean;
     install: Host | null;
     force: boolean;
+    installHooks: boolean;
+    removeHooks: boolean;
+    yes: boolean;
 }
 /** `_parse_args`, arm for arm, including the mutually exclusive group and `-h`. */
 export declare function parseArgs(argv: readonly string[]): Options;

package/dist/cli.js

@@ -68,11 +68,12 @@
  * reaches for is answered on the wire instead, by `build_identity`. `runtime-ts/README.md`
  * and `docs/install.md` carry the same correction in their own words.
  */
-import { readFileSync } from 'node:fs';
+import { readFileSync, readSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { assetsRoot } from './assets.js';
 import { BantamError } from './errors.js';
+import { logHookFailure, runHook } from './hookadapter.js';
 import { buildReport, resolveEventLogPath } from './mcpreport.js';
 import { Memory } from './memory/component.js';
 import { DEFAULT_INDEX_BUDGET } from './memory/store.js';
@@ -81,7 +82,7 @@ import { buildServer } from './mcp/server.js';
 import { RawStdioTransport } from './mcp/transport.js';
 import { ArgumentTypeError, ArgvError, formatHelp, formatUsageBlock, HelpRequested, helpWidth, parseArgs as parseWithSpec, pyIntStrict, } from './pyargparse.js';
 import { pyJoin, PyOSError, pyRepr, pyStatIsDir } from './memory/pyfs.js';
-import { HOSTS, InstallError, installSelf } from './hostinstall.js';
+import { HOSTS, HookConsentUnavailable, HookDeclined, installHooks, InstallError, installSelf, removeHooks, } from './hostinstall.js';
 import { runUpdate } from './selfupdate.js';
 import { statusLine } from './statusline.js';
 /** `SystemExit("...")`: the message on stderr, exit 1. */
@@ -137,6 +138,38 @@ const PARSER = {
             typeName: 'int',
             defaultValue: DEFAULT_INDEX_BUDGET,
         },
+        // THE HOOK ADAPTER, AND IT IS A FLAG FOR THE REASON `--mcp-report` GIVES BELOW, ONLY
+        // HARDER. `package.json` declares exactly one bin, so anything hung off a second entry
+        // point is unreachable in the pure-npx install that is the shipped product -- and the
+        // hook adapter was, literally: it lived in `tools/hooks/bantamkit-hook.mjs`, and MEASURED
+        // at 0.35.3 with `npm pack --dry-run` the tarball is 174 files under
+        // `files: ["dist","assets"]` with not one of them matching `hook`. An operator who
+        // installed bantamkit the only way it is published had no adapter on disk to register.
+        //
+        // POSITION IS WIRE-VISIBLE AND IT IS MEASURED, the same as every flag below it. At the
+        // 80-column fallback argparse breaks the usage after `[--index-budget BYTES]`, and that
+        // first line is pinned in `test_mcpserver.py`, in `test/cli-surface.test.mjs` and as a
+        // THROWING precondition in `tools/conformance/suites/cli.mjs`. Registered HERE -- the
+        // first flag AFTER `--index-budget` -- it grows the SECOND usage line only, from 61
+        // columns to 70 against a fold at 78. Registering it any earlier would move the pinned
+        // line and turn a differential suite into a re-baselining one.
+        //
+        // BARE, WITH NO METAVAR, AND THE EVENT COMES FROM STDIN. The host sends one JSON object
+        // carrying `hook_event_name`, which is what the adapter has always dispatched on; a
+        // second spelling of the event on the command line would be a second thing to keep in
+        // step with the host, and the registration in `~/.claude/settings.json` would have to
+        // carry seven different commands instead of one.
+        //
+        // THE CONTRACT IS DELIBERATELY NARROW, WHICH IS WHAT MAKES IT GATEABLE: one JSON object
+        // in on stdin, at most one JSON object out on stdout, exit 0 ALWAYS. A conformance case
+        // can feed both runtimes the same payload and compare the emitted object byte for byte.
+        {
+            optionStrings: ['--hook'],
+            dest: 'hook',
+            kind: 'storeTrue',
+            help: 'run as a Claude Code hook: one JSON event on stdin, then exit',
+            defaultValue: false,
+        },
         // WHY THIS IS A FLAG ON THIS PROCESS AND NOT A NEW ENTRY POINT, and why it sits HERE.
         // The lifecycle argument against printing from this process -- stdout is the JSON-RPC
         // channel -- is true of a RUNNING server and not of a flag that prints and returns before
@@ -226,6 +259,52 @@ const PARSER = {
             help: 'with --install, replace an existing bantamkit entry',
             defaultValue: false,
         },
+        // THE HOOK REGISTRATION, AND IT IS THREE FLAGS, NOT A MODIFIER ON `--install`.
+        //
+        // S1 RULING Q3.1: hooks are NEVER written as a side effect of `--install <host>`. Somebody
+        // asking to register an MCP server has not asked to register seven hooks that run on every
+        // tool call. RULING Q3.2 makes it its own opt-in, with a paired `--remove-hooks`, and gives
+        // the reason a modifier was refused: `--force`'s help above says "with --install", and
+        // overloading `--install` with a second, differently-consented write would make that
+        // sentence false.
+        //
+        // `--yes` IS THE THIRD STATE OF THE GATE, WHICH IS WHY IT IS A FLAG AND NOT AN ENV VAR.
+        // RULING Q3.3 makes the no-terminal-and-no-`--yes` case a REFUSAL at exit 2, so `--yes` is
+        // the only path a CI or scripted install has, and the ruling requires it to appear in `-h`
+        // so nobody has to guess it. It carries `--force`'s "with --install…" phrasing for the
+        // same reason `--force` does: a flag that is inert on its own says so in its own help.
+        //
+        // POSITION IS WIRE-VISIBLE, the same as every flag above. These three land AFTER `--force`
+        // and before the `--store`/`--start` group, which leaves the FIRST line of the 80-column
+        // usage — the line pinned by `test/cli-surface.test.mjs` and by the `cli` conformance
+        // suite — byte-identical, and moves the wrap boundary on the later lines only. The group
+        // indices below move with them.
+        {
+            optionStrings: ['--install-hooks'],
+            dest: 'install_hooks',
+            kind: 'storeTrue',
+            help: "add bantamkit's hook entries to ~/.claude/settings.json, then exit",
+            defaultValue: false,
+        },
+        {
+            optionStrings: ['--remove-hooks'],
+            dest: 'remove_hooks',
+            kind: 'storeTrue',
+            help: "take bantamkit's hook entries back out of ~/.claude/settings.json, then exit",
+            defaultValue: false,
+        },
+        {
+            optionStrings: ['--yes'],
+            dest: 'yes',
+            kind: 'storeTrue',
+            // NAMES BOTH FLAGS since the user's ruling of 2026-09-20 put the same gate on
+            // `--remove-hooks`. RULING Q3.3 requires the non-interactive consent path to be in `-h`
+            // so nobody has to guess it; a `--yes` that silently also worked with `--remove-hooks`
+            // would leave the only way to script a removal undocumented, which is the defect
+            // `--assets-root` shipped once already.
+            help: 'with --install-hooks or --remove-hooks, say yes in advance instead of being asked',
+            defaultValue: false,
+        },
         {
             optionStrings: ['--store'],
             dest: 'store',
@@ -242,10 +321,11 @@ const PARSER = {
         },
     ],
     // `--store`/`--start` moved from 6/7 to 8/9 when `--install` and `--force` were added
-    // ahead of them, and from 8/9 to 9/10 when `--update` was. These are POSITIONS, not names,
-    // so adding an action above the group and leaving this line alone would silently make two
-    // unrelated flags mutually exclusive.
-    groups: [[9, 10]],
+    // ahead of them, from 8/9 to 9/10 when `--update` was, from 9/10 to 10/11 when `--hook`
+    // was, and from 10/11 to 13/14 when `--install-hooks`, `--remove-hooks` and `--yes` were.
+    // These are POSITIONS, not names, so adding an action above the group and leaving this
+    // line alone would silently make two unrelated flags mutually exclusive.
+    groups: [[13, 14]],
 };
 /** `_parse_args`, arm for arm, including the mutually exclusive group and `-h`. */
 export function parseArgs(argv) {
@@ -256,11 +336,15 @@ export function parseArgs(argv) {
         store: values['store'],
         start: values['start'],
         assetsRoot: values['assets_root'],
+        hook: values['hook'],
         mcpReport: values['mcp_report'],
         statusline: values['statusline'],
         update: values['update'],
         install: values['install'],
         force: values['force'],
+        installHooks: values['install_hooks'],
+        removeHooks: values['remove_hooks'],
+        yes: values['yes'],
     };
 }
 /**
@@ -320,6 +404,86 @@ function typedBareAtATerminal(argv) {
         return false;
     return Boolean(stream.isTTY);
 }
+/**
+ * Is there a terminal to ask a question at? The SAME signal `typedBareAtATerminal` uses.
+ *
+ * `process.stdin.isTTY` is `true` on a terminal and **`undefined`** — not `false` — on a pipe,
+ * a file or `/dev/null`, so this is a truthiness test for the reason spelled out above: a
+ * `=== false` test would make every non-terminal invocation look like a terminal, and on THIS
+ * path that inverts a consent gate. Neither the getter throwing nor a null `process.stdin` is
+ * a terminal, and neither may take the process down: what is at stake is a refusal.
+ */
+function haveATerminal() {
+    let stream;
+    try {
+        stream = process.stdin;
+    }
+    catch {
+        return false;
+    }
+    if (stream === null || stream === undefined)
+        return false;
+    return Boolean(stream.isTTY);
+}
+/**
+ * RULING Q3.4's question, on stderr, answered on stdin. Only ever called at a terminal.
+ *
+ * THE QUESTION IS A PARAMETER AND THE READER IS NOT. `--install-hooks` asks "Write these hook
+ * entries?" and `--remove-hooks` asks "Remove these hook entries?"; everything after the
+ * question mark — the `[y/N]` default, the one-byte read, the EAGAIN retry, and the rule that
+ * only `y`/`Y` is a yes — is one implementation on purpose, because two flags rewriting one
+ * file must not answer differently to the same keystroke.
+ *
+ * ONE LINE, READ SYNCHRONOUSLY, ONE BYTE AT A TIME. `readFileSync(0)` would block until EOF —
+ * at a terminal that is Ctrl-D, not Enter — so the answer is read to the first newline and no
+ * further, which leaves anything the person typed after it for whoever asks next.
+ *
+ * ANYTHING OTHER THAN `y` OR `Y` MEANS NO, including empty and including EOF. That is the
+ * ruling, and it is why the default in the prompt is spelled `[y/N]`: the safe answer is the
+ * one you get by pressing Enter, by piping nothing, or by closing the terminal.
+ *
+ * EAGAIN IS NOT AN ANSWER, AND THE FIRST VERSION OF THIS FUNCTION THOUGHT IT WAS. Node leaves
+ * a terminal's fd 0 in NON-BLOCKING mode, so a synchronous read of one the person has not
+ * typed into yet throws `EAGAIN` instead of waiting. Measured on a real pty on 2026-09-20:
+ * `isTTY=true`, and the very first `readSync(0, …)` threw
+ * `EAGAIN: resource temporarily unavailable, read` before anything had been typed. Treating
+ * that as EOF answered "no" to a question nobody had been given a chance to answer — the
+ * refusal was safe, but the feature was unreachable at the only place it is meant to work,
+ * and NO UNIT TEST COULD SEE IT because every one of them injects the answer through the
+ * `ask` seam. A pty found it; a suite could not.
+ *
+ * `Atomics.wait` IS THE ONLY SYNCHRONOUS SLEEP THERE IS, and one is needed: without it the
+ * retry is a busy spin on a terminal waiting for a human.
+ */
+function askAtTheTerminal(question) {
+    process.stderr.write(`${question} [y/N] `);
+    const byte = Buffer.alloc(1);
+    const idle = new Int32Array(new SharedArrayBuffer(4));
+    let answer = '';
+    for (;;) {
+        let read;
+        try {
+            read = readSync(0, byte, 0, 1, null);
+        }
+        catch (e) {
+            if (e.code === 'EAGAIN') {
+                Atomics.wait(idle, 0, 0, 20); // nothing typed yet; wait for the person, not for the cpu
+                continue;
+            }
+            break; // a closed fd, a stream the platform cannot read this way — not a yes
+        }
+        if (read === 0)
+            break; // EOF: Ctrl-D, or a terminal that went away
+        const ch = byte.toString('utf8');
+        if (ch === '\n')
+            break;
+        if (ch !== '\r')
+            answer += ch;
+    }
+    process.stderr.write('\n');
+    const said = answer.trim();
+    return said === 'y' || said === 'Y';
+}
 /** `_build_memory`, including the two refusals argparse cannot express. */
 function buildMemory(options) {
     if (options.k < 1)
@@ -429,6 +593,28 @@ async function main(argv) {
         process.stdout.write(`${root}\n${packFileCount(root)} files\n`);
         return 0;
     }
+    if (options.hook) {
+        // DISPATCH ORDER IS REGISTRATION ORDER, which is the rule the four flags below already
+        // follow and the reason `--mcp-report --install cursor` prints a report and writes
+        // nothing. `--hook` is registered directly after `--index-budget`, so it is checked
+        // directly after `--assets-root`.
+        //
+        // EXIT 0 ALWAYS, AND THAT IS THE CONTRACT, not a convenience. A hook that exits non-zero
+        // or lets a stack reach stderr is rendered by the host as an error on the user's screen,
+        // so every failure is logged into `~/.bantamkit/hooks/hook-log.jsonl` and swallowed. This
+        // is the one arm in this file whose refusal path is a log line rather than a message.
+        //
+        // It returns before `buildMemory` for the same reason every flag around it does: the
+        // adapter binds whatever store the winning MCP registration pins, from the cwd the HOST
+        // sent in the payload — not from whatever directory the hook process was spawned in.
+        try {
+            await runHook();
+        }
+        catch (e) {
+            logHookFailure(e);
+        }
+        return 0;
+    }
     if (options.mcpReport) {
         // Same discipline as `--assets-root`, and the same place in `main`: BEFORE
         // `buildMemory`, which touches the filesystem, and before the transport exists at all.
@@ -485,10 +671,91 @@ async function main(argv) {
         }
         return 0;
     }
+    // REGISTRATION ORDER AGAIN, which is what makes `--mcp-report --install-hooks` print a
+    // report and write nothing, exactly as `--mcp-report --install cursor` already does.
+    //
+    // THREE EXITS, AND THE TWO THAT WRITE NOTHING ARE NOT THE SAME EXIT (S1 RULING Q3.3/Q3.4):
+    //
+    //   0  written, or already installed and matching
+    //   1  the person was asked at a terminal and did not say yes — `no hooks were written`
+    //   2  there was no terminal to ask at and no `--yes`
+    //
+    // Neither refusal carries the `error:` prefix `InstallError` gets. Nothing went wrong: the
+    // program asked, or found it could not ask, and then did nothing — which is the feature.
+    //
+    // THE PLAN AND THE QUESTION GO TO STDERR, the report to stdout. One stream is the operator's
+    // answer and the other is the conversation that led to it, and a caller piping stdout into
+    // something should get the report and not the prompt.
+    if (options.installHooks) {
+        try {
+            process.stdout.write(`${installHooks({
+                version: version(),
+                yes: options.yes,
+                ask: haveATerminal() ? () => askAtTheTerminal('Write these hook entries?') : null,
+                tell: (text) => process.stderr.write(text),
+            })}\n`);
+        }
+        catch (e) {
+            if (e instanceof HookConsentUnavailable) {
+                process.stderr.write(`${e.message}\n`);
+                return 2;
+            }
+            if (e instanceof HookDeclined) {
+                process.stderr.write(`${e.message}\n`);
+                return 1;
+            }
+            if (!(e instanceof InstallError))
+                throw e;
+            process.stderr.write(`error: ${e.message}\n`);
+            return 1;
+        }
+        return 0;
+    }
+    if (options.removeHooks) {
+        // THE SAME THREE EXITS, AND THEY ARE THE SAME THREE NUMBERS. RULING Q3.7 used to exempt
+        // this flag from the gate; the user overturned that on 2026-09-20 after `--remove-hooks`
+        // rewrote the operator's real `~/.claude/settings.json` with no terminal and no `--yes`.
+        //
+        //   0  removed, or there was nothing of ours to remove
+        //   1  the person was asked at a terminal and did not say yes — `no hooks were removed`
+        //   2  there was no terminal to ask at and no `--yes`
+        //
+        // The arms below are `--install-hooks`' arms, in the same order, for the same reasons.
+        try {
+            process.stdout.write(`${removeHooks({
+                yes: options.yes,
+                ask: haveATerminal() ? () => askAtTheTerminal('Remove these hook entries?') : null,
+                tell: (text) => process.stderr.write(text),
+            })}\n`);
+        }
+        catch (e) {
+            if (e instanceof HookConsentUnavailable) {
+                process.stderr.write(`${e.message}\n`);
+                return 2;
+            }
+            if (e instanceof HookDeclined) {
+                process.stderr.write(`${e.message}\n`);
+                return 1;
+            }
+            if (!(e instanceof InstallError))
+                throw e;
+            process.stderr.write(`error: ${e.message}\n`);
+            return 1;
+        }
+        return 0;
+    }
     // `--force` alone is a typo with a plausible reading — somebody meant to install and
     // dropped the flag that says where. Refusing names the missing half.
     if (options.force)
         throw new Refusal('--force is only meaningful with --install');
+    // The same reading, and the same refusal, for the consent flag: `--yes` on its own is
+    // somebody who meant to install or remove hooks and dropped the flag that says which. It is
+    // checked AFTER `--force` because that is registration order, and both are checked after
+    // every flag that acts, so `--install-hooks --yes` never reaches either of them. The
+    // sentence names BOTH flags since the ruling of 2026-09-20: naming only one would send an
+    // operator who mistyped `--remove-hooks` looking for a flag they already had.
+    if (options.yes)
+        throw new Refusal('--yes is only meaningful with --install-hooks or --remove-hooks');
     // A PERSON TYPED IT. `typedBareAtATerminal` carries the whole argument; what belongs here is
     // only that this sits BEFORE `buildMemory`, which is what creates a store. Somebody who typed
     // a command to see what it does has not asked for a `.bantamkit/memory` directory in whatever

package/dist/hookadapter.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The host's hook payload. Every field is optional because the host sends a DIFFERENT shape
+ * per event and this module is handed whatever arrives — including, on a malformed line,
+ * nothing at all. Narrowing happens in the arm that needs the field, never here.
+ */
+export interface HookInput {
+    hook_event_name?: string;
+    session_id?: string;
+    transcript_path?: string;
+    cwd?: string;
+    source?: string;
+    prompt?: string;
+    tool_name?: string;
+    tool_input?: Record<string, unknown>;
+    tool_use_id?: string;
+    trigger?: string;
+    stop_hook_active?: boolean;
+}
+/**
+ * `bantamkit-mcp --hook`: ONE JSON object in, AT MOST ONE JSON object out, and the caller
+ * exits 0 whatever happens.
+ *
+ * NOTHING HERE THROWS PAST THE CALLER. `cli.ts` wraps this in the same `catch → log → 0` the
+ * standalone script's last line was, because a hook that exits non-zero or writes a stack to
+ * stderr is rendered by the host as an error on the user's screen.
+ */
+export declare function runHook(): Promise<void>;
+/** The `catch` half of the contract, so `cli.ts` states it in one line. */
+export declare function logHookFailure(e: unknown): void;