@ultimat3/mcp 24.0.0 → 25.1.0

package/CLAUDE.md

@@ -22,13 +22,15 @@ import. The CLI wires it.
 | `dev-server.ts` | the 13 dev tools; depends only on an injected `DevHost` |
 | `dev-host.ts` | wires `describe*` from entity/action/query/jobs into a `DevHost` |
 | `transport-http.ts` | `POST /mcp` route descriptor, bearer → agent actor, and the per-caller rate limit it enforces itself |
+| `audit-hook.ts` | `onAudit`; `resolveToken`'s 2nd arg is http's `RequestFacts` (`seen.address` only, never `x-forwarded-for`), re-exported as `McpRequestFacts` |
+| `confirmations.ts` · `confirmation-*.ts` | `mcpConfirmations`: a factory over `action` (view/decide) · the gate on `handle` · stores · DDL · codes |
 | `oauth-metadata.ts` | RFC 9728 protected-resource metadata + the 401 `resource_metadata` challenge (`defineAppMcp({ oauth })`); the authorization server is the app's |
 | `transport-stdio.ts` | NDJSON on stdin/stdout for `x mcp serve` |
 | `app-tools.ts` | `defineAppMcp` — a generated app's own MCP surface, one call |
 | `app-tool.ts` | the authored `tools: { name: {...} }` record → `ProjectablePrimitive` |
 | `projectable.ts` | a real `action`/`query` → `ProjectablePrimitive`; the ONE adapter both the sweep and the written-out list use |
 | `exposed.ts` | `include: 'exposed'` — the action/query registries → primitives |
-| `scopes.ts` | the `scopes:` map — outcome 2's declaration surface; boot-time refusal of an unknown or doubly-claimed tool |
+| `scopes.ts` | the `scopes:` map — outcome 2's declaration surface and its three boot refusals |
 | `readonly-sql.ts` · `readonly-sql-calls.ts` | layer 3 of `db.query` — the single-read parse — and `db.migrate`'s branch check · the banned call families |
 | `query-limits.ts` | layer 4 of `db.query` — the row, byte and timeout ceilings, and what truncation reports |
 | `meta-surface.ts` | `surface: 'meta'` catalog: `list_resources` / `describe_resource`, `groups:` boot checks; dispatch stays in `server.ts` |
@@ -83,8 +85,7 @@ import. The CLI wires it.
   `Object.prototype` supplies a value for `constructor`, `toString`, `hasOwnProperty` and
   `__proto__` on every plain object — so the index read answered "declared" for four names no
   schema declares, and `validate-args.ts` accepted them past an `additionalProperties: false` that
-  forbids them and then dropped them. Third instance of the class in the framework, after
-  `@ultimat3/i18n`'s catalog lookup and `@ultimat3/schema`'s `coerce`. Its twin: a validated key
+  forbids them and then dropped them. Its twin: a validated key
   lands on the result through `Object.defineProperty`, because `out[key] = v` for `__proto__` runs
   the setter on `Object.prototype` and re-prototypes the record instead of adding a key.
 - **The RESOURCE surface owes the same three outcomes as the tool surface.** `resources/list` and
@@ -109,11 +110,11 @@ import. The CLI wires it.
   only drift from the action's own parse. `tools/list` published it and `validate-args.ts` ignored
   it, so a tool declaring `t.uuid` accepted `"not-a-uuid"` with `ok: true`. `pattern` is the
   opposite case and is kept: the rule travels with the schema. The narrowing is `@ultimat3/schema`'s
-  `toWireSchema` (tier 0, so `@ultimat3/action`'s `.tool()` publishes the same document) and the
+  `toWireSchema` (tier 0, so OpenAPI-adjacent readers reach the same document) and the
   type is its `WireJsonSchema`, which `wire.ts` names `JsonSchema`; `validate-args-subset.test.ts`
   asserts every published keyword is one this server enforces, at any depth.
 - **A hand-written app tool parses its own input**, in the slot `invoke` puts it: parse, then
-  `guard()`, then `handle`. A projected action re-parses inside `invoke`; `app-tool.ts` had no second
+  `guardAction()`, then `handle`. A projected action re-parses inside `invoke`; `app-tool.ts` had no second
   parse, so `handle` was handed whatever the wire subset let through — typed `InferOutput<TInput>`,
   past the policy. One code either way, `X_INPUT_INVALID`, built from `@ultimat3/action`'s own
   `InputInvalidError`.
@@ -141,15 +142,15 @@ import. The CLI wires it.
   and `tools/list` are silent by design (answered pre-filtered). `resource-security.test.ts` reads
   both streams: core's logger puts `error` on stderr.
 - **A tool that renders its OWN `isError` result may NAME the code it refused with**
-  (`McpToolResult.code`), and `outcomeForResult` sends it through the same `outcomeForCode` a
-  THROWN error goes through. Audit-only: `server.ts` never puts it on the wire, because the code is
-  already inside the rendered body. Without it every self-rendered refusal was `policy-denied` at
-  `warn` — so `@ultimat3/admin`'s `X_ADMIN_INVALID` (a client mistyping an argument the published
-  JSON Schema could not have refused: admin publishes a `type` per field and nothing else) sat in
-  the bucket this package's enumeration alert watches. `X_ADMIN_INVALID` is `ARGUMENT_CODES`;
-  `X_INPUT_INVALID` deliberately stays `failed`, because a projected action publishes its WHOLE
-  schema and input this server already validated failing inside it means the two have drifted.
-  A result naming no code keeps the conservative `policy-denied`.
+  (`McpToolResult.code`, audit-only, never on the wire); `outcomeForResult` sends it through the
+  `outcomeForCode` a thrown error takes. Unnamed keeps the conservative `policy-denied`. Why:
+  `X_ADMIN_INVALID` (`ARGUMENT_CODES`) sat in the enumeration alert's bucket. `X_INPUT_INVALID`
+  stays `failed` — a projected action's whole schema was already validated, so it means drift.
+  `X_MCP_CONFIRMATION_PENDING`/`_EXPIRED` are `unconfirmed` (`info`); `_REJECTED` is a denial.
+- **`onAudit` is a second DESTINATION, never a second path** (`audit-hook.ts`, `As of 2026-10`):
+  the line is written, then the decision handed on, unawaited; a throwing hook changes no answer
+  (`mcp.audit-hook.failed`). Core's `AuditSink` = what a primitive DID; `onAudit` = what the gate
+  decided, refused tokens included (`mcp.auth.<reason>`). The route reads `server.audit`.
 - **A `--` comment ends at the first CR *or* LF — Postgres' own boundary set** (`readonly-sql.ts`,
   `endOfLineComment`). A scanner stopping at LF alone read `select 1;--\rupdate …` as one read.
 - `security.test.ts` and `app-security.test.ts` are the executable contract for all of the
@@ -157,10 +158,9 @@ import. The CLI wires it.
   actually declares (`defineAppMcp` projecting real actions and queries). Extend them, never
   weaken them. A gate can only refuse what a declaration can reach, so a new gate needs a test
   in BOTH: the registry half passes while the declaration surface silently drops the field.
-- **`isExposed` and `exposureOf` both delegate to `isMcpExposed` in `@ultimat3/core`.** That is the
-  framework's one answer to "did this opt in?", shared with `action`, `query`, `ai` and `manifest`
-  — five packages that cannot import each other, which is how three spellings of the check shipped
-  and why the pin lives in `@ultimat3/cli`. Never spell `=== true` inline here again.
+- **Exposure is core's `isMcpExposed`** (private `exposed` and `exposureOf`; no exported
+  wrapper since 25.0.0) — the one answer shared with `action`, `query`, `ai`, `manifest`; the pin
+  lives in `@ultimat3/cli`. Never spell `=== true` inline here again.
 - Exposure is declared at the primitive, never in `defineAppMcp`. A primitive NAMED in
   `actions:`/`queries:` without `mcp: { expose: true }` is `X_MCP_TOOL_UNDECLARED` at boot —
   a written-out list is a request, so filtering it would ship a catalog missing a tool its
@@ -178,23 +178,24 @@ import. The CLI wires it.
   query. Writing a primitive out NAMES a tool; it never re-shapes or re-runs one. An action
   with no export name is `X_ACTION_UNREGISTERED` rather than a tool called `''`, which no
   `tools/call` and no `scopes:` entry could ever address.
-- **This package NAMES a tool, it never derives one.** `primitive.mcp?.name ?? primitive.name` in
-  `from-action.ts` is the whole rule, fed the verbatim export name by `projectable.ts`. Every
-  publisher (`action.tool()`, `query.tool()`, `x-ultimate.mcpTool`, `ActionDescriptor.mcp.tool`)
-  owes the same string; `cross-surface.test.ts` drives a `tools/call` with the name OpenAPI
-  published.
+- **This package NAMES a tool, never derives one**: `primitive.name`, verbatim from
+  `projectable.ts`; core's `McpExposureDeclaration` is the one block, no `name` (`type-pins.ts`). `x-ultimate.mcpTool` and
+  `ActionDescriptor.mcp.tool` owe the same string (`cross-surface.test.ts`).
+- **`toolFrom` is THE tool projection** (O-tool, 25.0.0), over a real action/query or a
+  `ProjectablePrimitive`; `toolListEntry(toolFrom(x))` deep-equals the `tools/list` entry.
+  action/query `.tool()` and the `toolFromQuery` alias are deleted.
 - Every boot-time refusal in `defineAppMcp` is an `UltimateError` with a code, never a bare
   throw: `X_MCP_TOOL_UNDECLARED`, `X_MCP_TOOL_UNSAFE`, `X_MCP_TOOL_DUPLICATE`,
-  `X_MCP_SCOPE_UNKNOWN`, `X_MCP_SCOPE_CONFLICT`. The caller reading them is usually an agent
+  `X_MCP_SCOPE_UNKNOWN`, `X_MCP_SCOPE_CONFLICT`, `X_MCP_SCOPE_UNCOVERED`. The caller reading them is usually an agent
   that needs `{ code, cause, fix }`.
-- `scopes:` is refused at boot two ways, both because the alternative ships a tool silently
-  ungated: a name no projected tool answers to is `X_MCP_SCOPE_UNKNOWN` (a typo, a rename, a
-  primitive never listed); one tool claimed by two scopes is `X_MCP_SCOPE_CONFLICT` — a tool
-  carries exactly one, and object key order is not a security model.
-- The **projection** invents no `scope` — `toolFromAction` cannot know what a token means.
+- `scopes:` is refused at boot three ways, each shipping a silently ungated tool otherwise: a name
+  nothing projects (`X_MCP_SCOPE_UNKNOWN`); one tool under two scopes (`X_MCP_SCOPE_CONFLICT` —
+  key order is not a security model); a tool under none (`X_MCP_SCOPE_UNCOVERED`, `As of 2026-10`:
+  it answered every token while `bearerMount` served it to nobody — `scope-surfaces.test.ts`).
+- The **projection** invents no `scope` — `toolFrom` cannot know what a token means.
   `defineAppMcp`'s `scopes:` may attach one afterward, as a capability of the CONNECTION; that
   is not a second authz path, because the scope gate decides before the policy runs and never
-  reads the input. A hand-written app tool is the same: its `policy` reaches `guard()` from
+  reads the input. A hand-written app tool is the same: its `policy` reaches `guardAction()` from
   `@ultimat3/action`, which is the one authz path that reads the input — never a second check
   written for MCP.
 - **A URI is taken once.** `ResourceRegistry.register` throws `X_MCP_RESOURCE_DUPLICATE` on a
@@ -221,22 +222,14 @@ import. The CLI wires it.
 - `db.query` / `db.migrate` refuse structurally, in `readonly-sql.ts`, before the host runs
   (`X_MCP_QUERY_REJECTED` / `X_MCP_NOT_BRANCH_DB` — one code each, because they want different
   next commands).
-- **Banned function families** (each is a ban already made elsewhere in another spelling):
-  `pg_notify` (= `NOTIFY`, a write keyword); server control (`pg_cancel_backend`,
-  `pg_terminate_backend`, `pg_reload_*`, `pg_rotate_*`, `pg_switch_*`, `pg_promote`,
-  `pg_wal_replay_*`); replication (`pg_logical_*`, `pg_create_*`, `pg_drop_*`, `pg_replication_*` —
-  advancing a slot is a write no `ROLLBACK` undoes); `pg_file_*`; `txid_current` /
-  `pg_current_xact_id`; `pg_import_*`; SQL run from a string (`*_to_xml*`, `ts_stat`, `ts_rewrite`). `U&"…"` is
-  refused, never decoded; a keyword is a whole identifier (`set2` is a column). Catalog VIEWS
-  (`pg_replication_slots`) are read `from`, never called.
+- **Banned function families** — each a ban already made elsewhere in another spelling; the list
+  and why lives in README's `db.query` section, held by `readonly-sql-forbidden-calls.test.ts`.
+  `U&"…"` is refused, never decoded; a keyword is a whole identifier (`set2` is a column).
 - Banned SQL functions are matched as a **prefix of a CALLED function name** — add a family, never
-  a name (`pg_sleep_for` passed an exact `pg_sleep` ban). The unit is the call (`name(`), so a
-  column `pg_sleep_for_seconds` is fine; the call scan keeps quoted-identifier content
-  (`"pg_advisory_lock"(1)` is a call), the keyword scan blanks it. `pg_advisory_*` (a session lock
-  survives layer 2's `ROLLBACK`; `packages/testing/src/db-integration.test.ts`), `pg_sleep*` (the
-  one ban that holds on PGlite), `nextval`/`setval` (a consumed id is not rolled back).
+  a name (`pg_sleep_for` passed an exact `pg_sleep` ban); the call unit and the three named bans: README.
 - `db.query` is defended four ways: a SELECT-only role and `BEGIN READ ONLY` in `@ultimat3/db`
-  (the CLI wires them — this package must never import `db`), the parse here, and the caps here.
+  (the CLI wires them — this package never opens a `db` connection; it imports one lexer rule,
+  `endOfBlockComment`, so a nested comment ends where Postgres ends it), the parse here, the caps here.
   `limit` is a request, never a permission: `resolveQueryLimits` clamps it into a hard 1000.
 - The caps run in the **tool**, not the host. A host that forgets them answers a million rows
   into a model's context. `guards` names the layers that engaged; a layer that could not engage
@@ -258,6 +251,11 @@ import. The CLI wires it.
   SAME rejected token, which is precisely the oracle the pre-parse 401 exists to remove. The parse
   error still exists — it is what an authenticated agent gets. Failures spend a per-ADDRESS bucket
   (`seen.address`), and an exhausted address is `429` BEFORE `resolveToken` — a valid guess too.
+- **Confirmation order: visibility → scope → args → `admit` → confirmation → policy.** An approval
+  binds actor + tool + `keyedFingerprint(args)` (rotation ⇒ new row); `consume` (CAS) makes one approval run one
+  call; rejected/expired is told once, then the call asks again. Args sealed; `approve` carries
+  viewed args (digest must match); default `check`: same org. An agent never decides (in the
+  policy). Statuses < 500, or `forAudience` hides the id.
 - **`transport-stdio.ts`'s default `write` is AWAITED** — fd 1 is a pipe, and an unawaited
   `Bun.stdout.write` lost the tail of a 4 MB frame at exit. It is also the loop's only
   back-pressure; only a child-process test can see it.

package/README.md

@@ -33,6 +33,10 @@ reads only the catalog still knows what it is holding.
 | 3. Parse | one statement, a read leader, no mutating keyword at statement level, no lock — clause **or** `pg_advisory_*` call — and no call into a banned function family, matched by prefix of the called name — quoted and schema-qualified spellings included — so a new spelling is refused by default and a column sharing a prefix is not; on a form with literals and comments blanked | `readonly-sql.ts` |
 | 4. Limits | `SET LOCAL statement_timeout`, a hard 1000-row ceiling (`limit` clamps into it, never past it) and a 256 KiB byte cap | `query-limits.ts` |
 
+**Banned function families** — each is a ban already made elsewhere in another spelling: `pg_notify` (= `NOTIFY`, a write keyword); server control (`pg_cancel_backend`, `pg_terminate_backend`, `pg_reload_*`, `pg_rotate_*`, `pg_switch_*`, `pg_promote`, `pg_wal_replay_*`); replication (`pg_logical_*`, `pg_create_*`, `pg_drop_*`, `pg_replication_*` — advancing a slot is a write no `ROLLBACK` undoes); `pg_file_*`; `txid_current` / `pg_current_xact_id`; `pg_import_*`; SQL run from a string (`*_to_xml*`, `ts_stat`, `ts_rewrite`). `U&"…"` is refused, never decoded; a keyword is a whole identifier (`set2` is a column). Catalog VIEWS (`pg_replication_slots`) are read `from`, never called.
+
+Banned SQL functions are matched as a **prefix of a CALLED function name** — add a family, never a name (`pg_sleep_for` passed an exact `pg_sleep` ban). The unit is the call (`name(`), so a column `pg_sleep_for_seconds` is fine; the call scan keeps quoted-identifier content (`"pg_advisory_lock"(1)` is a call), the keyword scan blanks it. `pg_advisory_*` (a session lock survives layer 2's `ROLLBACK`; `packages/testing/src/db-integration.test.ts`), `pg_sleep*` (the one ban that holds on PGlite), `nextval`/`setval` (a consumed id is not rolled back).
+
 The answer carries `guards` — the layers that actually engaged — plus `truncatedBy` and `bytes`.
 A layer that could not engage (a managed Postgres that refuses `CREATE ROLE`) is **absent from
 the list**, never assumed. Truncation is never silent.
@@ -79,7 +83,7 @@ strand a well-behaved client.
 | A predicate audience sees the caller and nothing else | it is handed `McpCaller` — never the call arguments, so two calls with different inputs cannot answer differently. Must return the literal `true`; if it throws, the tool is hidden |
 | `tools/list` is answered per caller | filtered on every call against the caller the transport resolved — one per HTTP request, one per stdio connection — never a static catalog |
 | Gate order | visibility → scope → arguments → policy; the scope gate never waits on a policy run against attacker-supplied input |
-| Every outcome is audited | one line per `tools/call`; hidden/scope/policy at `warn`, ok and invalid-args at `info` — see `audit.ts`. A tool that renders its OWN `isError` result may name the code it refused with (`McpToolResult.code`, audit-only, never on the wire) and is then classified by the same `outcomeForCode` a thrown error is — otherwise every self-rendered refusal lands in the `policy-denied` bucket a prober's name walk is alerted from |
+| Every outcome is audited | one line per `tools/call`; hidden/scope/policy at `warn`, ok, invalid-args and unconfirmed at `info` — see `audit.ts`; the same decision reaches `onAudit` after the line. A tool that renders its OWN `isError` result may name the code it refused with (`McpToolResult.code`, audit-only, never on the wire) and is then classified by the same `outcomeForCode` a thrown error is — otherwise every self-rendered refusal lands in the `policy-denied` bucket a prober's name walk is alerted from |
 | Audit lines carry no payload | tool, outcome, actor, code. Never arguments, never rows |
 | No trusted-tool mode | there is no flag that skips policy evaluation |
 
@@ -110,7 +114,10 @@ export const mcp = defineAppMcp({
       },
     },
   },
-  scopes: { 'admin:seats': ['seatReport'] },   // scope name → tool NAMES, by string
+  scopes: {                              // scope name → tool NAMES; given, it must cover EVERY tool
+    'admin:seats': ['seatReport'],
+    'posts:write': ['publishPost'],      // …including each one include: 'exposed' projected
+  },
   instructions: 'Admin console. seatReport({}) answers seat questions; writes are audited.',
   resolveToken: (token) => sessions.resolveAgentToken(token),
 });
@@ -121,7 +128,7 @@ export const mcp = defineAppMcp({
 has no `routes:` key and never had one; this page said `routes: [mcp.route]` while nothing read it,
 and `POST /mcp` answered `X_ROUTE_NOT_FOUND` in every app ever scaffolded. Now: `apps/<app>/mcp.ts`
 exports `mcp` (the value `defineAppMcp` returns), and both boots — `x dev` and `runRole` — mount
-`POST config.ai.mcp.path` → `mcp.route.handle(request)` when `config.ai.mcp.expose` is `true`,
+`POST <defineAppMcp path>` (default `/mcp`) → `mcp.route.handle(request)` when `config.ai.mcp.expose` is `true`,
 which is the **default**, and say `app mcp mounted` in the boot log (`x dev` prints `mcp POST /mcp`
 in its summary). The http pipeline does not pre-judge the route (`auth: 'public'`,
 `enforcedBy: 'handler'`): `mcp.route.handle` reads `Authorization: Bearer` through `resolveToken`
@@ -131,9 +138,8 @@ to mount — no file exports `mcp`, or the export was built without `resolveToke
 and says nothing.
 
 **Several endpoints, one per population (Unreleased).** `mcp` may be a non-empty array of
-`defineAppMcp` values: endpoint #0 mounts at `config.ai.mcp.path` and owns the root well-known
-document; every other mounts at its own `defineAppMcp({ path })` and serves only its path-inserted
-metadata document. Each is its own server — catalog, instructions, groups, scopes, prompts. Two on
+`defineAppMcp` values: every endpoint mounts at its own `defineAppMcp({ path })`; endpoint #0 owns
+the root well-known document, and every other serves only its path-inserted metadata document. Each is its own server — catalog, instructions, groups, scopes, prompts. Two on
 one route throws `X_MCP_PATH_DUPLICATE` at boot. `McpPrompt.visibleTo` hides a prompt from
 `prompts/list` and `prompts/get` with the tool/resource `McpVisibility` semantics.
 
@@ -165,16 +171,22 @@ An action that was never handed to `defineApi` has no export name, and is
 
 **The tool name is the export name, verbatim** — `publishPost`, never `publish_post`. This server
 answers `tools/call` for that name and no other, so every surface that PUBLISHES a name has to
-publish the same one: `action.tool()`, `query.tool()`, `x-ultimate.mcpTool` in `openapi.json`, and
-`ActionDescriptor.mcp.tool`. The projection reads `primitive.mcp?.name ?? primitive.name`, so the
-export name is the **default** and `mcp.name` is an explicit override — unreachable from `action()`
-or `query()`, whose declarations carry no `name` field, and available only to a hand-authored
-`ProjectablePrimitive` passed to `defineAppMcp`'s `tools:`. The three action publishers snake_cased
-the name `As of 2026-08`, so an agent reading the spec called a tool the catalog never contained and
-got ToolNotFound.
+publish the same one: `x-ultimate.mcpTool` in `openapi.json` and `ActionDescriptor.mcp.tool`. The
+projection reads `primitive.name` and nothing else — a hand-built `ProjectablePrimitive` names its
+tool with its own `name`; the `mcp.name` override, which no `action()` or `query()` could set, is
+gone (`As of 25.0.0`). The action publishers snake_cased the name `As of 2026-08`, so an agent
+reading the spec called a tool the catalog never contained and got ToolNotFound.
+
+**One projection: `toolFrom`** (`As of 25.0.0`). It takes a real action or query (or a
+`ProjectablePrimitive`) and answers the tool this server serves —
+`toolListEntry(toolFrom(publishPost))` is, field for field, its `tools/list` entry. Reach for
+it where `publishPost.tool()` / `liveFeed.tool()` were: those were a second projection, built a tier
+below this one, and they disagreed with the served tool (description fallback, the `idempotencyKey`
+argument, annotations). `toolFromQuery` was this function under another name and is gone; ask
+`isMcpExposed(primitive.mcp)` from `@ultimat3/core` where `isExposed` was.
 `src/cross-surface.test.ts` is what makes a fourth spelling a failing test rather than a note.
 
-A hand-written tool's `policy` is a permission, evaluated through the same `guard()` an
+A hand-written tool's `policy` is a permission, evaluated through the same `guardAction()` an
 HTTP request goes through, so a tool cannot acquire a second authz path. A tool without one
 is `X_MCP_TOOL_UNSAFE` at boot, and an unmarked tool is metered as a write.
 
@@ -186,6 +198,13 @@ beside the action, because a scope is a capability of the CONNECTION's token —
 stays the only rule that reads the input. A name this server does not project is
 `X_MCP_SCOPE_UNKNOWN` at boot; one tool claimed by two scopes is `X_MCP_SCOPE_CONFLICT`.
 
+**Given at all, `scopes:` must cover every tool** — `X_MCP_SCOPE_UNCOVERED` at boot names each one
+no scope lists, `As of 2026-10`. The registry gates a tool only when it carries a scope, so an
+unlisted tool answered every token, while `bearerMount` over the same map serves an unlisted
+primitive to nobody; one map now exposes one set on both doors. A ready `McpTool` that arrives with
+its own `scope` is covered by it. With `include: 'exposed'`, every primitive that opts in later
+needs a line here too, or the next boot says which.
+
 ### A constant surface: `surface: 'meta'`
 
 A large or sparsely used catalog blows an agent's context one tool per primitive. `surface: 'meta'`
@@ -209,7 +228,7 @@ defineAppMcp({
 
 | Tool | Answers |
 |---|---|
-| `list_resources` | PLAIN TEXT (`As of 22.10`; JSON until then): one line per resource, and under it one line per action — `  previewPayoutBatch (action; confirms; scope payouts:write) {batchId: string, note?: string} — <description>`. The same catalog as data: `server.catalog(caller)` (`MetaResource[]`, `undefined` for a flat caller); the renderer is `renderCatalog` |
+| `list_resources` | PLAIN TEXT (`As of 22.10`; JSON until then): one line per resource, and under it one line per action — `  previewPayoutBatch (action; confirms) {batchId: string, note?: string} — <description>`. Compact by rule, never by a character cut (`As of 2026-10`, #590): a scope every action of a resource shares — or every action of one kind, `query scope payouts:read; action scope payouts:write` — is said once on the resource line, and stays on each action otherwise; only `(action)` is tagged, untagged is a read-only query (from `destructive`, never the name); `oneLineParams` names every required field, then optional ones up to 4 fields / 100 characters, then `…`, and cuts an enum after 8 literals with `\|…`. The same catalog as data: `server.catalog(caller)` (`MetaResource[]`, per-action `scope` intact, `undefined` for a flat caller); the renderer is `renderCatalog` |
 | `describe_resource` | `{ resources: string[] }` (batched) → each action's full `inputSchema` |
 | `manage_resource` | `{ resource, action, params }` → the flat tool's answer, byte for byte |
 
@@ -238,7 +257,7 @@ whitelisted key the input does not declare is `X_MCP_LIST_PARAMS_INVALID` at boo
 
 | Field | Source | Default |
 |---|---|---|
-| `initialize.instructions` | `defineAppMcp({ instructions })` / `createMcpServer({ instructions })` — a string, or `(caller) => string \| undefined` | none; a function that throws or answers blank sends none |
+| `initialize.instructions` | `defineAppMcp({ instructions })` / `mcpServer({ instructions })` — a string, or `(caller) => string \| undefined` | none; a function that throws or answers blank sends none |
 | `title` | `mcp: { title }` · hand-written `title` | none |
 | `annotations` | `deriveAnnotations(primitive)`, then `mcp: { annotations }` key by key | query `{ readOnlyHint: true }`; action `{ readOnlyHint: false, destructiveHint: true, idempotentHint: <idempotent> }`; `openWorldHint` only when declared |
 | `outputSchema` | an action's `output` with an object root; a query's `rows` as `{ rows: [<row>] }`, or as the row itself for a `single: true` read (which answers one row or `X_NOT_FOUND`, as its route does) — `toWireOutputSchema` (from `@ultimat3/schema`) / `toRowsOutputSchema`, structure only (no bounds, patterns or `additionalProperties`: a client refuses a result that misses its schema) | none |
@@ -256,7 +275,7 @@ surface over its ceiling. Put the derivation beside the number.
 **Whose fix.** `errorAudience: 'caller'` (`defineAppMcp`'s default) renders an error's
 `callerFix` — `X_FORBIDDEN`: ask the account owner for the permission; `X_MCP_SCOPE_DENIED`: ask for
 a token with the scope; `X_INPUT_INVALID`: correct the named fields — where `fix` names something
-only the app's developer can run. `'developer'` (`createMcpServer`'s default, the dev server's)
+only the app's developer can run. `'developer'` (`mcpServer`'s default, the dev server's)
 keeps `fix`. An error whose `docs` is not the framework's one Error-Codes page — an app's
 `docs://recipes/...` — renders a fourth `docs:` line. Byte-identical to
 `UltimateError.format({ audience, docs })`.
@@ -265,7 +284,7 @@ keeps `fix`. An error whose `docs` is not the framework's one Error-Codes page
 
 | Transport | Entry | Auth |
 |---|---|---|
-| HTTP | `mcpHttpRoute({ server, resolveToken })` → `POST /mcp` | `Authorization: Bearer <token>` → `Actor { kind: 'agent' }` |
+| HTTP | `mcpHttpRoute({ server, resolveToken })` → `POST /mcp` — `resolveToken(token, facts)` | `Authorization: Bearer <token>` → `Actor { kind: 'agent' }` |
 | stdio | `serveStdio({ server, caller })` | none — the peer already owns the shell |
 
 The HTTP transport exports a route *descriptor*, not a mounted handler: a host owns the lifecycle,
@@ -296,6 +315,54 @@ did not.
 | where they are counted | `mcpHttpRoute({ rateLimitStore })` · `defineAppMcp({ rateLimitStore })` | a per-**process** memory store — N replicas behind one URL each enforce the full allowance, so a fleet passes `postgresRateLimitStore({ executor })` |
 | OAuth discovery | `mcpHttpRoute({ oauth })` · `defineAppMcp({ oauth })` | absent: the 401 is `Bearer realm="ultimate-mcp"` |
 
+### What `resolveToken` is told: `McpRequestFacts`
+
+`resolveToken(token, facts)` (`As of 2026-10`) — a second argument a one-argument resolver ignores.
+Frozen, typed, never the raw `Headers`, so a token can be bound to a network or refused from a
+browser origin without the resolver parsing a header it cannot trust.
+
+| Fact | Source | Absent |
+|---|---|---|
+| `address` | `handle(request, { address })` — what the HOST resolved (`ctx.ip`: a declared proxy's `x-forwarded-for` per `trustedProxyHops`, else the socket). Never read from a header here | `null` |
+| `userAgent` | `User-Agent`, verbatim — a hint, never an identity | `null` |
+| `origin` | the `Origin` request header; `'null'` (the string) is an opaque origin, not an absent one | `null` |
+| `path` | the URL path, no query string | — |
+
+```ts
+import type { McpRequestFacts, ResolvedToken } from '@ultimat3/mcp';
+import { defineAppMcp } from '@ultimat3/mcp';
+
+declare const tokens: {
+  resolve(token: string, where: { network: string | null }): Promise<ResolvedToken | null>;
+};
+
+export const mcp = defineAppMcp({
+  include: 'exposed',
+  resolveToken: async (token: string, facts: McpRequestFacts) => {
+    if (facts.origin !== null) return null; // agents are not browsers — the same 401 as a bad token
+    return tokens.resolve(token, { network: facts.address });
+  },
+});
+```
+
+### `onAudit`: the gate's decisions, as data
+
+`mcpServer({ onAudit })` · `defineAppMcp({ onAudit })` — the route reads its server's. One
+audit PATH with a second destination: the `mcp.*` log line is written, then the same decision is
+handed on. What an action or query DID still reaches core's `setAuditSink` (`surface: 'mcp'`);
+`onAudit` carries what no `AuditRecord` can — the refusals before anything ran.
+
+| `event.kind` | When | Carries |
+|---|---|---|
+| `tool-call` | every `tools/call` outcome (`ok`, `hidden`, `scope-denied`, `policy-denied`, `invalid-args`, `unconfirmed`, `failed`) | `tool`, `outcome`, `caller`, `scope?`, `code?` |
+| `resource-read` | every `resources/read` outcome | `uri`, `outcome`, `caller`, `scope?`, `code?` |
+| `auth-refused` | a missing or rejected token, a non-agent actor, an address past its failure allowance — also logged `mcp.auth.<reason>` at `warn` | `reason`, `status` (401/403/429), `facts` |
+
+Every event has `at` from the server's `clock`. Never the token, never the arguments. The hook is
+not awaited and cannot change an answer: one that throws or rejects is logged once as
+`mcp.audit-hook.failed` at `error` (its `code` when it has one, never its message). `tools/list` and
+`resources/list` stay silent, as in the log.
+
 ### OAuth discovery (RFC 9728)
 
 `defineAppMcp({ oauth: { authorizationServers: ['https://www.example.com'] } })` (`As of 22.6.0`;
@@ -308,6 +375,50 @@ PUBLIC origin (`handle(request, { origin })`, which the boot fills from `ctx.htt
 path; `scopes_supported` to the `scopes` map's keys. Issuers must be https (http on loopback):
 `X_MCP_OAUTH_INVALID`. The authorization server is the app's own routes.
 
+## Human confirmation: `mcpConfirmations`
+
+A factory over `action`, never a ninth primitive: what it returns IS the decision action
+(`{ id, decision: 'approve' | 'reject' }`), registered like any other — route, OpenAPI, typed client,
+`audit: true` if asked — and `defineAppMcp({ confirmations })` gates the named tools with it.
+
+```ts
+import type { PgExecutor } from '@ultimat3/core';
+import { defineAppMcp, mcpConfirmations, postgresConfirmationStore } from '@ultimat3/mcp';
+
+declare const executor: PgExecutor;
+
+// apps/web/app/orders/actions/confirm-refunds.ts — register it like any action
+export const confirmRefunds = mcpConfirmations({
+  tools: ['refundOrder'],
+  store: postgresConfirmationStore({ executor }), // memoryConfirmationStore() in a test
+  permission: 'order:refund',
+  ttlMs: 600_000, // DEFAULT_MCP_CONFIRMATION_TTL_MS
+});
+
+// apps/web/app/mcp.ts
+export const mcp = defineAppMcp({ include: 'exposed', confirmations: confirmRefunds });
+```
+
+| Step | What happens |
+|---|---|
+| agent calls `refundOrder` | after visibility → scope → args → the tool's caller-only `admit`, a pending row opens — actor, org, tool, `keyedFingerprint` (HMAC-SHA-256 under the signing secret) of the validated arguments, expiry — and the call answers `X_MCP_CONFIRMATION_PENDING` naming the id. Nothing ran. Repeating it answers the same id |
+| a person views it | `confirmRefunds({ id, decision: 'view' })` answers the request exactly as the agent sent it — `{ tool, status, expiresAt, arguments }`, the arguments opened from their seal. Changes nothing |
+| a person decides | `confirmRefunds({ id, decision: 'approve', arguments })` with the `arguments` the view returned, or `decision: 'reject'`, over any surface the action projects to. An approval whose arguments' keyed digest is not the row's — none, different, or a row keyed before a secret rotation — is `X_MCP_CONFIRMATION_ARGUMENTS_MISMATCH`, so a swap between the view and the approval decides nothing. Decided once (`X_MCP_CONFIRMATION_DECIDED`), never after expiry (`X_MCP_CONFIRMATION_EXPIRED`) |
+| who may view and decide | policy `can(permission, check)`. An agent never may, whatever it holds (`X_FORBIDDEN`). The default `check` is the asking org: `row !== null && row.orgId === (actor.orgId ?? null)` — another tenant's row and an unknown id are one `X_FORBIDDEN`. Crossing tenants is an explicit `check`; with one that admits a missing row, an unknown id is `X_MCP_CONFIRMATION_UNKNOWN` |
+| agent repeats the SAME call | approved: it runs once, through the tool's own `handle` — the action's full policy still decides it. Rejected: `X_MCP_CONFIRMATION_REJECTED`, audited as a denial. Past expiry: `X_MCP_CONFIRMATION_EXPIRED`. Each outcome is delivered once; the next identical call asks again |
+
+Bound to the asking actor, the tool and the input digest: other arguments, or another agent, ride
+no one's approval. The digest is keyed because the row stores it — an unkeyed hash of `{ accountNumber }` is
+brute-forced from a database read. The open row is found by equality on it, key id included, so
+after a signing-secret rotation the same call opens a FRESH confirmation: never a mismatch error,
+never the old approval. The arguments are stored SEALED (`seal()`, AES-256-GCM under the app's one
+master key, purpose `MCP_CONFIRMATION_ARGUMENTS_PURPOSE`), never plaintext at rest — the person
+deciding must see what they approve, or a prompt-injected agent describes "$5 to order 17" and sends
+another. `sealKeys` points at the key in a test. `SQL_MCP_CONFIRMATIONS_TABLE` is the store's DDL, imported from `@ultimat3/mcp/schema` (its one path — 25.0.0 took it off the barrel); `store.purge(before)` from a
+`task` bounds the table. A gated name the server does not project — or `tools: []` — is
+`X_MCP_CONFIRMATION_TOOL_UNKNOWN` at boot. The gated tool carries `confirms: true`, which the meta
+catalog shows as `(confirms)`.
+
 ## Resources
 
 | URI | Contents |
@@ -360,6 +471,7 @@ is `X_MCP_IDEMPOTENCY_KEY_SHADOWED` at boot.
 | `X_MCP_SCOPE_DENIED` | visible, but the connection's token lacks the scope |
 | `X_MCP_SCOPE_UNKNOWN` | `defineAppMcp`'s `scopes:` names a tool this server does not project |
 | `X_MCP_SCOPE_CONFLICT` | two scopes in `defineAppMcp`'s `scopes:` claim one tool |
+| `X_MCP_SCOPE_UNCOVERED` | `defineAppMcp` was given `scopes:` and a projected tool is under none of them |
 | `X_INPUT_INVALID` | arguments failed the published `inputSchema` — an `isError` result since 22.10 |
 | `X_MCP_ARGS_INVALID` | no longer raised on the wire (22.10); `McpArgsInvalidError` stays exported |
 | `X_MCP_SURFACE_OVER_BUDGET` | `assertMcpSurfaceBudget` measured a surface over its declared ceiling |
@@ -371,6 +483,14 @@ is `X_MCP_IDEMPOTENCY_KEY_SHADOWED` at boot.
 | `X_MCP_GROUP_UNKNOWN` · `X_MCP_GROUP_CONFLICT` | `groups:` names a tool not projected · lists one tool twice |
 | `X_MCP_SURFACE_INVALID` | `surface` and `groups` disagree |
 | `X_MCP_LIST_PARAMS_INVALID` | `listParams` whitelists a key the tool's input does not declare |
+| `X_MCP_CONFIRMATION_PENDING` | a gated call waits for a person: the cause names the confirmation id |
+| `X_MCP_CONFIRMATION_EXPIRED` | the confirmation lapsed before the call came back, or before a person decided it |
+| `X_MCP_CONFIRMATION_REJECTED` | a person rejected this exact call |
+| `X_MCP_CONFIRMATION_DECIDED` | approve/reject on a confirmation already decided |
+| `X_MCP_CONFIRMATION_UNKNOWN` | no confirmation has that id |
+| `X_MCP_CONFIRMATION_TOOL_UNKNOWN` | `mcpConfirmations({ tools })` names a tool this server does not project, or none |
+| `X_MCP_CONFIRMATION_CONTESTED` | identical concurrent calls kept racing one confirmation; retry |
+| `X_MCP_CONFIRMATION_ARGUMENTS_MISMATCH` | an approval did not carry the arguments the agent sent (missing, different, or keyed before a rotation) |
 | `X_MCP_RATE_LIMITED` | the caller spent its per-minute allowance for this request's class. Its own code rather than `@ultimat3/http`'s `X_RATE_LIMITED` because the KNOB differs — `rateLimits` on the route, never `rateLimit.buckets` in `app.config.ts` |
 
 ### Error classes
@@ -384,6 +504,14 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `McpArgsInvalidError` | `X_MCP_ARGS_INVALID` | `src/errors.ts` |
 | `McpBodyTooLargeError` | `X_MCP_BODY_TOO_LARGE` | `src/errors.ts` |
 | `McpIdempotencyKeyShadowedError` | `X_MCP_IDEMPOTENCY_KEY_SHADOWED` | `src/errors.ts` |
+| `McpConfirmationArgumentsMismatchError` | `X_MCP_CONFIRMATION_ARGUMENTS_MISMATCH` | `src/confirmation-errors.ts` |
+| `McpConfirmationContestedError` | `X_MCP_CONFIRMATION_CONTESTED` | `src/confirmation-errors.ts` |
+| `McpConfirmationDecidedError` | `X_MCP_CONFIRMATION_DECIDED` | `src/confirmation-errors.ts` |
+| `McpConfirmationExpiredError` | `X_MCP_CONFIRMATION_EXPIRED` | `src/confirmation-errors.ts` |
+| `McpConfirmationPendingError` | `X_MCP_CONFIRMATION_PENDING` | `src/confirmation-errors.ts` |
+| `McpConfirmationRejectedError` | `X_MCP_CONFIRMATION_REJECTED` | `src/confirmation-errors.ts` |
+| `McpConfirmationToolUnknownError` | `X_MCP_CONFIRMATION_TOOL_UNKNOWN` | `src/confirmation-errors.ts` |
+| `McpConfirmationUnknownError` | `X_MCP_CONFIRMATION_UNKNOWN` | `src/confirmation-errors.ts` |
 | `McpGroupConflictError` | `X_MCP_GROUP_CONFLICT` | `src/meta-errors.ts` |
 | `McpGroupUnknownError` | `X_MCP_GROUP_UNKNOWN` | `src/meta-errors.ts` |
 | `McpListParamsInvalidError` | `X_MCP_LIST_PARAMS_INVALID` | `src/meta-errors.ts` |
@@ -395,6 +523,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `McpResourceDuplicateError` | `X_MCP_RESOURCE_DUPLICATE` | `src/errors.ts` |
 | `McpScopeConflictError` | `X_MCP_SCOPE_CONFLICT` | `src/errors.ts` |
 | `McpScopeDeniedError` | `X_MCP_SCOPE_DENIED` | `src/errors.ts` |
+| `McpScopeUncoveredError` | `X_MCP_SCOPE_UNCOVERED` | `src/errors.ts` |
 | `McpScopeUnknownError` | `X_MCP_SCOPE_UNKNOWN` | `src/errors.ts` |
 | `McpSurfaceOverBudgetError` | `X_MCP_SURFACE_OVER_BUDGET` | `src/errors.ts` |
 | `McpToolDuplicateError` | `X_MCP_TOOL_DUPLICATE` | `src/errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mcp",
-  "version": "24.0.0",
+  "version": "25.1.0",
   "description": "MCP server, dev tools, and the action-to-tool projection \u2014 one authz system, two surfaces",
   "license": "MIT",
   "type": "module",
@@ -14,7 +14,8 @@
     "provenance": true
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./schema": "./src/confirmation-schema.ts"
   },
   "files": [
     "src",
@@ -25,20 +26,21 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "24.0.0",
-    "@ultimat3/core": "24.0.0",
-    "@ultimat3/entity": "24.0.0",
-    "@ultimat3/http": "24.0.0",
-    "@ultimat3/jobs": "24.0.0",
-    "@ultimat3/policy": "24.0.0",
-    "@ultimat3/query": "24.0.0",
-    "@ultimat3/schema": "24.0.0"
+    "@ultimat3/action": "25.1.0",
+    "@ultimat3/core": "25.1.0",
+    "@ultimat3/db": "25.1.0",
+    "@ultimat3/entity": "25.1.0",
+    "@ultimat3/http": "25.1.0",
+    "@ultimat3/jobs": "25.1.0",
+    "@ultimat3/policy": "25.1.0",
+    "@ultimat3/query": "25.1.0",
+    "@ultimat3/schema": "25.1.0"
   }
 }

package/src/app-tool.ts

@@ -5,14 +5,14 @@
 // registry runs, so this file is the mapping to `ProjectablePrimitive`, which `toolsFrom` then
 // projects exactly as it projects an action. One projection, not two.
 //
-// The load-bearing line is `guard(...)` in `run` below: it is the SAME function `invoke` calls
+// The load-bearing line is `guardAction(...)` in `run` below: it is the SAME function `invoke` calls
 // for an HTTP request, reached through the same `@ultimat3/action` policy gate. A hand-written
 // tool therefore has no authz of its own — it borrows the action tier's, so a rule change cannot
 // apply to routes and miss tools.
 
-import { actorOf, guard, guardBeforeInput, InputInvalidError } from '@ultimat3/action';
+import { guardAction, guardActionBeforeInput, InputInvalidError } from '@ultimat3/action';
 import type { Ctx } from '@ultimat3/core';
-import { useContext } from '@ultimat3/core';
+import { actorOf, useContext } from '@ultimat3/core';
 import type { KnownPermission } from '@ultimat3/policy';
 import { can } from '@ultimat3/policy';
 import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
@@ -105,7 +105,7 @@ export function appToolPrimitive(name: string, def: AnyAppToolDefinition): Proje
     admit: (actor) =>
       asCallerContext(actor, () => {
         const ctx = useContext();
-        guardBeforeInput(policy, { actor: actorOf(ctx), ctx, action: name }, 'mcp');
+        guardActionBeforeInput(policy, { actor: actorOf(ctx), ctx, action: name }, 'mcp');
       }),
     run: ({ input, actor }) =>
       // The caller is the actor for the WHOLE call. A child context is how the framework
@@ -115,7 +115,7 @@ export function appToolPrimitive(name: string, def: AnyAppToolDefinition): Proje
         const ctx = useContext();
         // The policy's actor half first, as in `invoke`: a caller refused whatever they send is
         // told X_FORBIDDEN, never the tool's argument schema.
-        guardBeforeInput(policy, { actor: actorOf(ctx), ctx, action: name }, 'mcp');
+        guardActionBeforeInput(policy, { actor: actorOf(ctx), ctx, action: name }, 'mcp');
         // The AUTHORITATIVE parse, in the same slot `invoke` puts it: before the full policy,
         // before the handler. A projected action re-parses inside `invoke`; a hand-written tool has no
         // second parse, so `handle` was typed `InferOutput<TInput>` and handed whatever
@@ -123,7 +123,7 @@ export function appToolPrimitive(name: string, def: AnyAppToolDefinition): Proje
         // arrived as any string at all. `InputInvalidError` because a tool argument is an action
         // input by another name: one code, X_INPUT_INVALID, whichever surface the call came in on.
         const parsed = await parseInput(def.input, input, name);
-        guard(policy, { actor: actorOf(ctx), input: parsed, ctx, action: name }, 'mcp');
+        guardAction(policy, { actor: actorOf(ctx), input: parsed, ctx, action: name }, 'mcp');
         return def.handle({ input: parsed, ctx });
       }),
   };