@mcp-index/sdk 0.18.1 → 0.19.1

package/CHANGELOG.md

@@ -3,7 +3,26 @@
 All notable changes to the TypeScript SDK. Versioning is semver (0.x: minor =
 additive feature, patch = fix). Backward-compatible additions only in 0.2.0.
 
-## [Unreleased]
+## [0.19.1] - 2026-10-21
+
+### Security
+
+- A title or annotation hint change that comes with a new optional parameter is now held for review instead of accepted. Before, the gate auto-accepted the parameter and re-pinned the tool, taking the new `title`, `annotations.title`, readOnlyHint, destructiveHint, idempotentHint or openWorldHint with it unreviewed. Guard and strict now hold it the way they hold a description change; monitor still lets the call run and reports it, and no longer re-pins. Lock mode is unchanged. Same as mcpindex-gate.
+- A title or annotation hint change is now held for review wherever it used to go through. A readOnlyHint, destructiveHint, idempotentHint or openWorldHint change on a tool whose definition hash still matches is held in either direction: a tool newly claiming to be read-only or non-destructive is the case a host would run unattended. So is a hint change that comes with a first outputSchema, and a behavioural validation that clears no longer re-pins over a title or hint change. Guard and strict hold these the way they hold a description change; monitor lets the call run and reports it. A title change on a hash-matched tool was already held. Lock mode is unchanged.
+
+### Added
+
+- `classifyLabelChanges` and `LABEL_ONLY_KINDS`, with two new `ChangeKind` members, `title-changed` (tool `title` or `annotations.title` added, removed or changed) and `annotation-hint-changed` (any move of readOnlyHint, destructiveHint, idempotentHint or openWorldHint that `annotation-flip-to-destructive` does not already cover). Labels for a reviewer only: `classifyChange` is unchanged and the kinds never enter a gate verdict. Same output as the Python `classify_label_changes`.
+
+## [0.19.0] - 2026-10-20
+
+### Added
+
+- Lock mode, in three new subpaths. It follows mcp.lock draft 1, revision 1d, which is not stable: files carry `lockVersion: "1-draft"` and a later reader will refuse them. It is opt-in, and the root `@mcp-index/sdk` import does not load any of it.
+- `@mcp-index/sdk/lock`: reads and writes a lock in `.mcp/lock/` and `.mcp/contracts/`, checks each `tools/list` against it, and refuses calls to tools that are not approved with error -32011. `lockClient` and `LockedTransport` put it in front of the official MCP client. `FileLockStore` approves and revokes, verifies a signed manifest when a signer is configured, and refuses a `sequencePath` or `trustedRootPath` inside the lock's repository. Listing and refusal events go to a sink you pass.
+- `@mcp-index/sdk/lock/pg`: `PgLockStore`, a Postgres store with append-only hash-chained records, row-level security, `app-scoped` and `role-bound` tenancy, two roles, and an optional signed head that needs a sequence store.
+- `@mcp-index/sdk/ai`: `lockTransport` for `createMCPClient` from the Vercel AI SDK.
+- Optional peer dependencies: `@ai-sdk/mcp` for `/ai`, `pg` for `/lock/pg`, `sigstore` for signed locks. The package still has no runtime dependencies.
 
 ## 0.18.1 - 2026-10-13
 

package/README.md

@@ -174,6 +174,184 @@ When enabled, each tool you pin and each contract drift sends **one one-way sign
 opt-in richer tier (it behaves identically today). The full notice is exported as
 `DRIFT_TELEMETRY_NOTICE`. Unset the variable any time to stop.
 
+## Lock mode (`@mcp-index/sdk/lock`)
+
+Lock mode checks every `tools/list` against an mcp.lock kept in your repository
+(`.mcp/lock/` and `.mcp/contracts/`, format: mcp.lock draft 1, revision 1e). The model sees
+only tools whose definition digest matches an approval, and a call to anything else is
+refused with JSON-RPC error -32011 before it reaches the server. Lock mode is opt-in and
+draft 1 is not stable. Nothing here runs unless you construct it, and the root
+`@mcp-index/sdk` import does not load it.
+
+Connect the official MCP client through `lockClient`:
+
+```ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { FileLockStore, lockClient } from "@mcp-index/sdk/lock";
+import type { Identity } from "@mcp-index/sdk/lock";
+
+const identity: Identity = { kind: "stdio", package: "npm:@example/docs-server" };
+const store = new FileLockStore({ root: process.cwd() }); // the directory that holds .mcp/
+const client = new Client({ name: "my-host", version: "1.0.0" });
+const transport = new StdioClientTransport({ command: "npx", args: ["-y", "@example/docs-server"] });
+const locked = await lockClient(client, transport, { store, identity, posture: "guard" });
+
+const { tools } = await client.listTools(); // approved tools only
+console.log(tools.map((t) => t.name), locked.decision?.withheld);
+```
+
+`posture` is `monitor` (show everything, report what does not match), `guard` (withhold it)
+or `strict` (same as guard in draft 1). Lock mode never approves a tool on first sight and
+never re-pins. The lock changes only through `store.approve` and `store.revoke`, or a
+reviewed edit to the lock files:
+
+```ts
+import { readFileSync } from "node:fs";
+
+// The Tool object exactly as the server sent it, saved for review. Not an SDK-parsed copy:
+// the SDK drops members it does not know, and the digest covers every member.
+const tool: unknown = JSON.parse(readFileSync("review/search.json", "utf8"));
+await store.approve({ identity, tool, subject: "github:you", via: "api", ref: "pr-42" });
+```
+
+The identity names the server, in one of three forms:
+
+```ts
+const remote: Identity = { kind: "remote", url: "https://mcp.example.com/v1/mcp" };
+const pkg: Identity = { kind: "stdio", package: "npm:@example/docs-server" }; // npm, pypi or oci
+const cmd: Identity = { kind: "stdio", command: "uvx", args: ["git+https://github.com/example/server"] };
+```
+
+`remoteIdentity`, `packageIdentity` and `commandIdentity` build them in normalized form.
+`commandIdentity` throws when an argument looks like a credential.
+
+A signed lock verifies `.mcp/lock/MANIFEST.json.sigstore` against a signer from your host
+configuration. It needs the optional `sigstore` peer, a trust root file, and a sequence file
+where the host keeps the highest manifest sequence it accepted, so an older signed manifest
+is refused after a newer one:
+
+```ts
+const signed = new FileLockStore({
+  root: "/srv/app",
+  signer: {
+    issuer: "https://token.actions.githubusercontent.com",
+    san: "https://github.com/acme/app/.github/workflows/lock.yml@refs/heads/main",
+  },
+  trustedRootPath: "/etc/mcplock/trusted_root.json",
+  sequencePath: "/var/lib/mcplock/sequence",
+});
+```
+
+Both paths must lie outside the repository that holds the lock, or the constructor throws
+`HostConfigError`. The repository is the nearest directory at or above `root` with a `.git`
+directory or a linked worktree's `.git` file; a submodule's `.git` file sends the search on to
+the superproject. The check compares directories by device and inode, so a case-folded
+spelling on macOS and a symlink followed by `..` are judged where they land, and a `..` in the
+part of a path that does not exist yet is refused. When no `.git` entry exists at or above
+`root`, only `root` itself is protected: a path beside it in the same untracked directory is
+accepted, so keep host files somewhere the lock's writers cannot reach. A signer without a sequence store makes every load
+`lock-signature-invalid`.
+
+## Postgres lock store (`@mcp-index/sdk/lock/pg`)
+
+`PgLockStore` keeps approvals in Postgres instead of files: append-only, hash-chained
+records per tenant, with row-level security on both tables. `pg` is an optional peer.
+
+The schema owner runs the migrations once. They are exported as SQL text:
+
+```ts
+import { writeFileSync } from "node:fs";
+import { MIGRATION_SQL, ROLE_BOUND_SQL, ROLE_SQL } from "@mcp-index/sdk/lock/pg";
+
+writeFileSync("mcplock-schema.sql", MIGRATION_SQL + ROLE_SQL);
+writeFileSync("mcplock-role-bound.sql", ROLE_BOUND_SQL); // only for role-bound tenancy
+// psql -v ON_ERROR_STOP=1 -f mcplock-schema.sql
+```
+
+`ROLE_SQL` creates two roles without login. `mcplock_runtime` may only read, and is what hosts
+in lock mode connect as. `mcplock_approver` may also append records and move the head, and
+belongs to the approval path only. Neither may update or delete a record. Grant each to its
+own login, and never connect as a superuser, since a superuser bypasses row-level security:
+
+```sql
+GRANT mcplock_runtime TO host_login;
+GRANT mcplock_approver TO approver_login;
+```
+
+Two tenancy modes:
+
+- `app-scoped` (the default, `MIGRATION_SQL` alone). The store sets the tenant from the
+  principal at the start of each transaction. This stops a query bug from reaching another
+  tenant. It does not stop someone holding a shared login, who can set any tenant.
+- `role-bound` (`ROLE_BOUND_SQL` after the other two). Each tenant gets its own logins, and
+  the administrator maps each login to its tenant in `mcplock.tenant_logins`. The policies
+  read the tenant from the login, so a login reaches only its own tenant. Use this before
+  sharing one database between tenants that do not trust each other.
+
+```ts
+import { PgLockStore, createPgPool } from "@mcp-index/sdk/lock/pg";
+
+const pool = await createPgPool(process.env.MCPLOCK_PG_URL ?? "postgres://host_login@127.0.0.1/app");
+const store = new PgLockStore({
+  pool,
+  principal: { tenantId: "acme", subject: "svc:docs-host" }, // from your own auth, never a header
+  tenancy: "app-scoped",
+});
+const snapshot = await store.loadSnapshot();
+console.log(snapshot.snapshotId);
+```
+
+With `headVerifier` set, each load checks a signature over the head row, and the store must
+also get a `sequenceStore`, for example `fileSequenceStore("/var/lib/mcplock/pg-sequence")`
+from `@mcp-index/sdk/lock`, or every load is `lock-signature-invalid`. Without a head
+signature, whoever can write the tables can rewrite the chain. Errors never carry the
+connection string unredacted.
+
+## Lock mode for the Vercel AI SDK (`@mcp-index/sdk/ai`)
+
+Wrap the transport you hand to `createMCPClient` from `@ai-sdk/mcp` (an optional peer). The
+wrapper reads the raw `tools/list` exchange, checks every tool against your mcp.lock, and the
+client only ever sees approved tools, through `tools()` or `listTools()` alike:
+
+```ts
+import { createMCPClient } from "@ai-sdk/mcp";
+import { Experimental_StdioMCPTransport } from "@ai-sdk/mcp/mcp-stdio";
+import { lockTransport } from "@mcp-index/sdk/ai";
+import { FileLockStore } from "@mcp-index/sdk/lock";
+import type { Identity } from "@mcp-index/sdk/lock";
+
+const identity: Identity = { kind: "stdio", package: "npm:@example/docs-server" };
+const store = new FileLockStore({ root: process.cwd() });
+const inner = new Experimental_StdioMCPTransport({ command: "npx", args: ["-y", "@example/docs-server"] });
+const transport = lockTransport(inner, { store, identity, posture: "guard" });
+const client = await createMCPClient({ transport });
+const tools = await client.tools(); // approved tools only
+console.log(Object.keys(tools));
+```
+
+A call to a withheld or unlisted tool never reaches the server. `callTool()` and the tool's
+`execute()` reject with an `MCPClientError` whose `code` is -32011 and `data.reason` says why;
+inside `generateText` that shows up as a `tool-error` part.
+
+Limits:
+
+- A digest says whether the contract changed. It says nothing about what the server does
+  when a tool runs.
+- The AI SDK client does not refetch on `notifications/tools/list_changed`. After an approval
+  or a server change, call `tools()` again; until then the previous allow-list holds. While a
+  listing is being collected, every call is refused with `no-listing`.
+- A tool's top-level `_meta` is not part of its digest. It reaches the client only when it
+  matches the `metaDigest` recorded at approval; otherwise, under guard, the tool is shown
+  without it and the decision reports `meta-changed` or `meta-unapproved`.
+- `@mcp-index/sdk/ai` imports only types from `@ai-sdk/mcp`, so loading it needs nothing at
+  runtime. The `@ai-sdk/mcp` peer itself needs Node >= 22; that is the only part with that
+  requirement, and the rest of the package runs on Node 20.
+- The AI SDK's own transports reject any message carrying a `__proto__` key before the wrapper
+  sees it, so such a listing never arrives and nothing is callable. The official SDK transports
+  pass it through and the lock withholds the tool. Instructions given to the client as
+  `initialInitializeResult` never cross the transport and are not checked.
+
 ## Related packages
 
 Three ways to bring mcpindex into an agent, for different surfaces:

package/dist/src/ai.d.ts

@@ -0,0 +1,96 @@
+/**
+ * `@mcp-index/sdk/ai`: lock mode for the Vercel AI SDK MCP client
+ * (`createMCPClient` from `@ai-sdk/mcp`).
+ *
+ * The AI SDK client parses `tools/list` with its own zod schema and builds
+ * tools from what is left, so a digest over `client.listTools()` would not be
+ * a digest over what the server sent. lockTransport wraps the transport the
+ * client is given and works on JSON-RPC messages before the client sees them.
+ * The message work is LockedTransport from `../lock/rawList.ts`: every page of
+ * a listing is collected under private ids and digested raw, withheld tools
+ * are dropped, and the client gets one result with no cursor. `client.tools()`
+ * and `client.listTools()` + `toolsFromDefinitions()` both only ever see
+ * approved tools (under guard).
+ *
+ * Every `tools/call` is checked against the allow-list from the latest
+ * complete listing. A refused call is never sent; the client gets a JSON-RPC
+ * -32011 error with data.reason. In @ai-sdk/mcp 2.0.74 that rejects
+ * `callTool()` and the tool's `execute()` with an MCPClientError carrying
+ * code -32011 and data { reason, tool }; it is not retried (the client never
+ * retries an error with a JSON-RPC code). Inside generateText the throw
+ * becomes a `tool-error` part, so the model sees the refusal as a tool error.
+ *
+ * Limits, all from the AI SDK client as of 2.0.74:
+ *   - The client treats any server notification as "Unsupported message
+ *     type" and reports it to onUncaughtError, so it never refetches on
+ *     `notifications/tools/list_changed`. The wrapper still marks a listing
+ *     as due (`listingDue`) and keeps the old allow-list until a new complete
+ *     listing. The app has to call `tools()` again to see newly approved
+ *     tools, and to drop ones the server removed.
+ *   - The wrapper reports `supportsProtocolVersionDiscovery = false`, so the
+ *     client uses the `initialize` handshake. Server instructions then arrive
+ *     in the initialize result, where they are digested and, under guard,
+ *     stripped when they differ from the lock. Instructions passed to the
+ *     client as `initialInitializeResult` never cross the transport and are
+ *     not checked.
+ *   - The AI SDK's own stdio, SSE and HTTP transports parse with a secure
+ *     JSON parser that throws on a `__proto__` key. Such a message never
+ *     reaches the wrapper, so there is no listing and no tool is callable;
+ *     the official SDK transports keep the key and the lock withholds the tool.
+ *   - `@ai-sdk/mcp` needs Node >= 22. This module itself only imports types
+ *     from it.
+ *
+ * The check covers the tool contract the model reads, and nothing about what
+ * the server does when a tool runs.
+ */
+import type { JSONRPCMessage, MCPTransport, MCPTransportCloseOptions, MCPTransportSendOptions } from "@ai-sdk/mcp";
+import type { CallGate, Decision } from "./lock/check.js";
+import type { LockEventSink } from "./lock/events.js";
+import type { Identity, Posture } from "./lock/lock.js";
+import type { LockStore } from "./lock/store.js";
+/** Host settings that are not about which lock or which server. */
+export interface AiLockHostConfig {
+    /** The host name written into events. Default "mcpindex-sdk". */
+    readonly host?: string;
+    /** Age after which a call reloads the snapshot. Default 60 s. */
+    readonly maxStalenessMs?: number;
+    readonly now?: () => number;
+}
+export interface AiLockOptions {
+    readonly store: LockStore;
+    /** This server's identity (section 3), from host configuration. */
+    readonly identity: Identity;
+    /** monitor, guard, or strict (behaves as guard in draft 1). */
+    readonly posture: Posture;
+    readonly sink?: LockEventSink;
+    readonly hostConfig?: AiLockHostConfig;
+}
+export declare class AiLockTransport implements MCPTransport {
+    #private;
+    /** Forces the initialize handshake, where instructions are checked. */
+    readonly supportsProtocolVersionDiscovery = false;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: (message: JSONRPCMessage) => void;
+    constructor(inner: MCPTransport, options: AiLockOptions);
+    get supportsMcpToolParameterHeaders(): boolean | undefined;
+    get protocolVersion(): string | undefined;
+    set protocolVersion(version: string | undefined);
+    setProtocolVersion(version: string): void;
+    /** The per-connection allow-list. */
+    get gate(): CallGate;
+    /** The decision for the latest complete listing, or null before one. */
+    get decision(): Decision | null;
+    /** True after list_changed until the next complete listing (call tools() again). */
+    get listingDue(): boolean;
+    start(): Promise<void>;
+    send(message: JSONRPCMessage, options?: MCPTransportSendOptions): Promise<void>;
+    close(options?: MCPTransportCloseOptions): Promise<void>;
+}
+/**
+ * Wrap `inner` in lock mode for `createMCPClient({ transport })`.
+ * Lock mode has no auto-accept, first-use pin or re-pin; the lock changes
+ * only through LockStore.approve and revoke.
+ */
+export declare function lockTransport(inner: MCPTransport, options: AiLockOptions): AiLockTransport;
+//# sourceMappingURL=ai.d.ts.map

package/dist/src/ai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../src/ai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,aAAa,CAAC;AAIrB,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAGxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC;CACxC;AAuCD,qBAAa,eAAgB,YAAW,YAAY;;IAClD,uEAAuE;IACvE,QAAQ,CAAC,gCAAgC,SAAS;IAClD,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAC;gBAKlC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,aAAa;IAUvD,IAAI,+BAA+B,IAAI,OAAO,GAAG,SAAS,CAEzD;IAED,IAAI,eAAe,IAAI,MAAM,GAAG,SAAS,CAExC;IAED,IAAI,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAE9C;IAED,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIzC,qCAAqC;IACrC,IAAI,IAAI,IAAI,QAAQ,CAEnB;IAED,wEAAwE;IACxE,IAAI,QAAQ,IAAI,QAAQ,GAAG,IAAI,CAE9B;IAED,oFAAoF;IACpF,IAAI,UAAU,IAAI,OAAO,CAExB;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/E,KAAK,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC;CAI/D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,aAAa,GAAG,eAAe,CAE1F"}

package/dist/src/ai.js

@@ -0,0 +1,151 @@
+/**
+ * `@mcp-index/sdk/ai`: lock mode for the Vercel AI SDK MCP client
+ * (`createMCPClient` from `@ai-sdk/mcp`).
+ *
+ * The AI SDK client parses `tools/list` with its own zod schema and builds
+ * tools from what is left, so a digest over `client.listTools()` would not be
+ * a digest over what the server sent. lockTransport wraps the transport the
+ * client is given and works on JSON-RPC messages before the client sees them.
+ * The message work is LockedTransport from `../lock/rawList.ts`: every page of
+ * a listing is collected under private ids and digested raw, withheld tools
+ * are dropped, and the client gets one result with no cursor. `client.tools()`
+ * and `client.listTools()` + `toolsFromDefinitions()` both only ever see
+ * approved tools (under guard).
+ *
+ * Every `tools/call` is checked against the allow-list from the latest
+ * complete listing. A refused call is never sent; the client gets a JSON-RPC
+ * -32011 error with data.reason. In @ai-sdk/mcp 2.0.74 that rejects
+ * `callTool()` and the tool's `execute()` with an MCPClientError carrying
+ * code -32011 and data { reason, tool }; it is not retried (the client never
+ * retries an error with a JSON-RPC code). Inside generateText the throw
+ * becomes a `tool-error` part, so the model sees the refusal as a tool error.
+ *
+ * Limits, all from the AI SDK client as of 2.0.74:
+ *   - The client treats any server notification as "Unsupported message
+ *     type" and reports it to onUncaughtError, so it never refetches on
+ *     `notifications/tools/list_changed`. The wrapper still marks a listing
+ *     as due (`listingDue`) and keeps the old allow-list until a new complete
+ *     listing. The app has to call `tools()` again to see newly approved
+ *     tools, and to drop ones the server removed.
+ *   - The wrapper reports `supportsProtocolVersionDiscovery = false`, so the
+ *     client uses the `initialize` handshake. Server instructions then arrive
+ *     in the initialize result, where they are digested and, under guard,
+ *     stripped when they differ from the lock. Instructions passed to the
+ *     client as `initialInitializeResult` never cross the transport and are
+ *     not checked.
+ *   - The AI SDK's own stdio, SSE and HTTP transports parse with a secure
+ *     JSON parser that throws on a `__proto__` key. Such a message never
+ *     reaches the wrapper, so there is no listing and no tool is callable;
+ *     the official SDK transports keep the key and the lock withholds the tool.
+ *   - `@ai-sdk/mcp` needs Node >= 22. This module itself only imports types
+ *     from it.
+ *
+ * The check covers the tool contract the model reads, and nothing about what
+ * the server does when a tool runs.
+ */
+import { LockedTransport } from "./lock/rawList.js";
+/**
+ * Adapts an AI SDK MCPTransport (or an official SDK transport, which has the
+ * same shape) to the Transport that LockedTransport drives.
+ */
+class InnerAdapter {
+    inner;
+    onclose;
+    onerror;
+    onmessage;
+    closeOptions;
+    constructor(inner) {
+        this.inner = inner;
+    }
+    async start() {
+        this.inner.onmessage = (message) => this.onmessage?.(message);
+        this.inner.onerror = (error) => this.onerror?.(error instanceof Error ? error : new Error(String(error)));
+        this.inner.onclose = () => this.onclose?.();
+        await this.inner.start();
+    }
+    async send(message, options) {
+        const m = message;
+        if (options === undefined)
+            await this.inner.send(m);
+        else
+            await this.inner.send(m, options);
+    }
+    async close() {
+        const options = this.closeOptions;
+        if (options === undefined)
+            await this.inner.close();
+        else
+            await this.inner.close(options);
+    }
+    setProtocolVersion(version) {
+        if (typeof this.inner.setProtocolVersion === "function")
+            this.inner.setProtocolVersion(version);
+        else
+            this.inner.protocolVersion = version;
+    }
+}
+export class AiLockTransport {
+    /** Forces the initialize handshake, where instructions are checked. */
+    supportsProtocolVersionDiscovery = false;
+    onclose;
+    onerror;
+    onmessage;
+    #adapter;
+    #locked;
+    constructor(inner, options) {
+        const { hostConfig, ...rest } = options;
+        // hostConfig goes first so it cannot replace store, identity or posture.
+        // Any key the core refuses (autoAccept, tofu, repin, ...) at either level
+        // reaches the LockedTransport constructor and throws there.
+        const lockOptions = { ...(hostConfig ?? {}), ...rest };
+        this.#adapter = new InnerAdapter(inner);
+        this.#locked = new LockedTransport(this.#adapter, lockOptions);
+    }
+    get supportsMcpToolParameterHeaders() {
+        return this.#adapter.inner.supportsMcpToolParameterHeaders;
+    }
+    get protocolVersion() {
+        return this.#adapter.inner.protocolVersion;
+    }
+    set protocolVersion(version) {
+        if (version !== undefined)
+            this.#adapter.setProtocolVersion(version);
+    }
+    setProtocolVersion(version) {
+        this.#adapter.setProtocolVersion(version);
+    }
+    /** The per-connection allow-list. */
+    get gate() {
+        return this.#locked.gate;
+    }
+    /** The decision for the latest complete listing, or null before one. */
+    get decision() {
+        return this.#locked.decision;
+    }
+    /** True after list_changed until the next complete listing (call tools() again). */
+    get listingDue() {
+        return this.#locked.listingDue;
+    }
+    async start() {
+        this.#locked.onmessage = (message) => this.onmessage?.(message);
+        this.#locked.onerror = (error) => this.onerror?.(error);
+        this.#locked.onclose = () => this.onclose?.();
+        await this.#locked.start();
+    }
+    async send(message, options) {
+        await this.#locked.send(message, options);
+    }
+    async close(options) {
+        this.#adapter.closeOptions = options;
+        await this.#locked.close();
+    }
+}
+/**
+ * Wrap `inner` in lock mode for `createMCPClient({ transport })`.
+ * Lock mode has no auto-accept, first-use pin or re-pin; the lock changes
+ * only through LockStore.approve and revoke.
+ */
+export function lockTransport(inner, options) {
+    return new AiLockTransport(inner, options);
+}
+//# sourceMappingURL=ai.js.map

package/dist/src/ai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.js","sourceRoot":"","sources":["../../src/ai.ts"],"names":[],"mappings":"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"}

package/dist/src/gate.d.ts

@@ -188,6 +188,13 @@ export declare class Gate {
     private static riskOf;
     private static markerIn;
     private markerIn;
+    /** A HOLD when `classifyLabelChanges` reports a title or annotation hint change against
+     * the pin, else null. Called on every path that would otherwise proceed with a moved title
+     * or hint or re-pin over one: the benign auto-accept, a hash match, and a behavioural
+     * clear. A title is text the model reads; a hint decides what a host lets run unattended,
+     * in either direction. The hash covers neither, and the label kinds stay out of `drift` so
+     * no kind set, hold class or telemetry row moves. Mirrors gate.py `_label_hold`. */
+    private labelHold;
     private descriptionHold;
     private driftHold;
     private behavioralInconclusive;

package/dist/src/gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/gate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/gate.ts"],"names":[],"mappings":"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"}

package/dist/src/gate.js

@@ -7,7 +7,7 @@
  * only the PUBLIC contract dict the caller observed.
  */
 import { Decision, HoldClass, hashTool, makeVerdict, utcNowIso, } from "./preflight.js";
-import { ChangeKind, UndiffableError, classifyChange, isNumericOnlyDescriptionChange, isSafetyRelevant, jsonEqual, } from "./schemaDiff.js";
+import { ChangeKind, UndiffableError, classifyChange, classifyLabelChanges, isNumericOnlyDescriptionChange, isSafetyRelevant, jsonEqual, } from "./schemaDiff.js";
 import { CONTRACT_FIELDS_VERSION, comparedFields, comparedKeys, fieldLabel, fieldsToBackfill, isComplete, } from "./contractFields.js";
 import { assess, blastRank } from "./risk.js";
 import { classifyToolDef } from "./actionClass.js";
@@ -73,6 +73,9 @@ const DANGEROUS_REASON_MARKERS = [
     "could not complete",
     "DESCRIPTION changed",
     "schema text changed",
+    // A title or annotation hint that moved beside an otherwise benign change. A title is
+    // text the model reads; a hint decides what a host lets run unattended.
+    "title or annotation hint changed",
     // title, icons, _meta, execution or a later top-level field on a hash-matched tool.
     "a tool field outside the definition hash changed",
     "outputSchema text was added",
@@ -984,7 +987,10 @@ export class Gate {
         if (added.length > 0 && schemaCarriesText(observedRec["outputSchema"])) {
             return this.driftHold(pinned.toolName, added, "contract DRIFTED: outputSchema text was added to a pinned tool (strings the host passes on and the hash does not cover); review and re-pin if expected", HoldClass.DRIFT);
         }
-        return null;
+        // A hint or title that moved on a hash-matched tool, on its own or beside an additive
+        // outputSchema. comparedFields leaves the four hints out, so this is the only place a
+        // hint-only change is seen.
+        return this.labelHold(pinned.toolName, drift, pinned.schema, observed);
     }
     validateDrift(name, pinned, observed, effects = null) {
         let drift;
@@ -1053,6 +1059,10 @@ export class Gate {
         if (schemaTextBlocks(pinned.schema, observed)) {
             return this.driftHold(name, drift, "contract DRIFTED: schema text changed (an added parameter carries text, or the input schema is not the pinned schema once added parameters are removed)", HoldClass.DRIFT);
         }
+        // A title or annotation hint that rides along with an otherwise benign change.
+        const labelHold = this.labelHold(name, drift, pinned.schema, observed);
+        if (labelHold !== null)
+            return labelHold;
         if (effects !== null) {
             effects.push({ kind: "repin", toolName: name, observed });
         }
@@ -1112,6 +1122,26 @@ export class Gate {
         return Gate.markerIn(defn);
     }
     // -------------------------------------------------------------- verdicts
+    /** A HOLD when `classifyLabelChanges` reports a title or annotation hint change against
+     * the pin, else null. Called on every path that would otherwise proceed with a moved title
+     * or hint or re-pin over one: the benign auto-accept, a hash match, and a behavioural
+     * clear. A title is text the model reads; a hint decides what a host lets run unattended,
+     * in either direction. The hash covers neither, and the label kinds stay out of `drift` so
+     * no kind set, hold class or telemetry row moves. Mirrors gate.py `_label_hold`. */
+    labelHold(name, drift, pinnedSchema, observed) {
+        let labels;
+        try {
+            labels = [...new Set(classifyLabelChanges(pinnedSchema ?? {}, observed).map((c) => c.path))].sort();
+        }
+        catch {
+            return this.driftHold(name, drift, "contract DRIFTED and the title and annotation hint comparison could not complete; fail-closed HOLD", HoldClass.DRIFT);
+        }
+        if (labels.length === 0)
+            return null;
+        return this.driftHold(name, drift, "contract DRIFTED: a title or annotation hint changed (" +
+            labels.join(", ") +
+            "); review the before/after and re-pin if expected", HoldClass.DRIFT);
+    }
     descriptionHold(name, drift, oldDesc, newDesc) {
         return makeVerdict({
             serverId: this._serverId,
@@ -1307,6 +1337,10 @@ export class Gate {
                     BehavioralOutcome.CLEARED,
                 ];
             }
+            // The sandbox is as blind to a title or hint as to a description.
+            const labelHold = this.labelHold(toolName, [...staticVerdict.drift], pinned.schema, observed);
+            if (labelHold !== null)
+                return [labelHold, BehavioralOutcome.CLEARED];
             this.repinOne(toolName, observed);
             return [
                 makeVerdict({