@ultimat3/mcp 22.10.0 → 22.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mcp",
-  "version": "22.10.0",
+  "version": "22.11.0",
   "description": "MCP server, dev tools, and the action-to-tool projection \u2014 one authz system, two surfaces",
   "license": "MIT",
   "type": "module",
@@ -31,13 +31,13 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "22.10.0",
-    "@ultimat3/core": "22.10.0",
-    "@ultimat3/entity": "22.10.0",
-    "@ultimat3/http": "22.10.0",
-    "@ultimat3/jobs": "22.10.0",
-    "@ultimat3/policy": "22.10.0",
-    "@ultimat3/query": "22.10.0",
-    "@ultimat3/schema": "22.10.0"
+    "@ultimat3/action": "22.11.0",
+    "@ultimat3/core": "22.11.0",
+    "@ultimat3/entity": "22.11.0",
+    "@ultimat3/http": "22.11.0",
+    "@ultimat3/jobs": "22.11.0",
+    "@ultimat3/policy": "22.11.0",
+    "@ultimat3/query": "22.11.0",
+    "@ultimat3/schema": "22.11.0"
   }
 }

package/src/app-tool.ts

@@ -10,7 +10,7 @@
 // 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, InputInvalidError } from '@ultimat3/action';
+import { actorOf, guard, guardBeforeInput, InputInvalidError } from '@ultimat3/action';
 import type { Ctx } from '@ultimat3/core';
 import { useContext } from '@ultimat3/core';
 import type { KnownPermission } from '@ultimat3/policy';
@@ -103,14 +103,22 @@ export function appToolPrimitive(name: string, def: AnyAppToolDefinition): Proje
     },
     inputJsonSchema: toWireSchema(def.input),
     mutates: def.destructive ?? true,
+    admit: (actor) =>
+      asCallerContext(actor, () => {
+        const ctx = useContext();
+        guardBeforeInput(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
       // impersonates, so the policy subject and whatever `handle` reads off `ctx.actor` are
       // the same identity by construction rather than by two call sites agreeing.
       asCallerContext(actor, async () => {
         const ctx = useContext();
-        // The AUTHORITATIVE parse, in the same slot `invoke` puts it: before the policy, before
-        // the handler. A projected action re-parses inside `invoke`; a hand-written tool has no
+        // 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');
+        // 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
         // `validate-args.ts` let past the wire subset — which carries no `format`, so a `t.uuid`
         // arrived as any string at all. `InputInvalidError` because a tool argument is an action

package/src/from-action.ts

@@ -96,6 +96,11 @@ export interface ProjectablePrimitive {
   readonly outputWrap?: string;
   /** The one server-authoritative entry point. Runs policy, then the handler. */
   run(args: { input: unknown; actor: Actor }): Promise<unknown>;
+  /**
+   * The policy's actor half, alone: throws the denial `run` would raise for this actor whatever
+   * the input, returns otherwise. Becomes the tool's `admit`. Absent: no before-args gate.
+   */
+  admit?(actor: Actor): void;
 }
 
 /**
@@ -132,6 +137,9 @@ export function toolFromAction(primitive: ProjectablePrimitive): AnyMcpTool {
     destructive: mutates,
     ...(visibleTo !== undefined ? { visibleTo } : {}),
     ...(listParams !== undefined ? { listParams } : {}),
+    ...(primitive.admit === undefined
+      ? {}
+      : { admit: (caller: McpCaller) => primitive.admit?.(caller.actor) }),
     // No `scope` from here: see the header. `defineAppMcp`'s `scopes:` map may add one.
     async handle(args: ToolArgs, caller: McpCaller): Promise<McpToolResult> {
       // ONE authz system, TWO surfaces. This `run` IS `invoke`; the HTTP route reaches the

package/src/meta-call.ts

@@ -83,7 +83,9 @@ export async function metaCall(
   let resolved = host.tools.resolve(action, input, caller);
   if (resolved.kind !== 'scope-denied' && resolved.kind !== 'not-found') {
     const listed = validateArgs(schemaOf(tool), input);
-    if (!listed.ok) resolved = { kind: 'invalid-args', name: action, issues: listed.issues };
+    if (!listed.ok) {
+      resolved = { kind: 'invalid-args', name: action, issues: listed.issues, tool };
+    }
   }
   return host.dispatch(id, action, resolved, caller);
 }

package/src/projectable.ts

@@ -4,10 +4,21 @@
 // primitive out is a different way to NAME a tool, never a second way to run one.
 
 import type { AnyAction } from '@ultimat3/action';
-import { actionName, invoke, isAction } from '@ultimat3/action';
-import { isMcpExposed } from '@ultimat3/core';
+import {
+  guardBeforeInput as actionGuardBeforeInput,
+  actionName,
+  actorOf,
+  invoke,
+  isAction,
+} from '@ultimat3/action';
+import { type Actor, isMcpExposed, useContext } from '@ultimat3/core';
 import type { AnyQuery } from '@ultimat3/query';
-import { isQuery, queryName, sourceFor } from '@ultimat3/query';
+import {
+  isQuery,
+  guardBeforeInput as queryGuardBeforeInput,
+  queryName,
+  sourceFor,
+} from '@ultimat3/query';
 import { asCallerContext } from './caller-context';
 import type { McpExposure, ProjectablePrimitive } from './from-action';
 import { takeIdempotencyKeyArg, withIdempotencyKeyArg } from './idempotency-arg';
@@ -58,6 +69,12 @@ export function primitiveFromAction(target: AnyAction): ProjectablePrimitive {
     ...(output === undefined ? {} : { outputJsonSchema: output }),
     mutates: true,
     idempotent: keyed,
+    // The same gate `invoke` opens with, asked by the server before it answers `invalid-args`.
+    admit: (actor: Actor) =>
+      asCallerContext(actor, () => {
+        const ctx = useContext();
+        actionGuardBeforeInput(target.policy, { actor: actorOf(ctx), ctx, action: name }, 'mcp');
+      }),
     // The actor rides in on the options: `invoke` swaps it inside the one execution path.
     run: keyed
       ? ({ input: args, actor }) => {
@@ -74,13 +91,20 @@ export function primitiveFromQuery(target: AnyQuery): ProjectablePrimitive {
   // answers the rows as a list, so the structured copy is `{ rows }` — `structuredContent` is an
   // object by the spec.
   const output = toRowsOutputSchema(target.rows);
+  const name = queryName(target);
   return {
-    name: queryName(target),
+    name,
     ...(exposure === undefined ? {} : { mcp: exposure }),
     ...(exposure?.description === undefined ? {} : { description: exposure.description }),
     inputJsonSchema: toWireSchema(target.input),
     ...(output === undefined ? {} : { outputJsonSchema: output, outputWrap: 'rows' }),
     mutates: false,
+    // `sourceFor`'s opening gate, on the surface it runs on ('server'), asked before `invalid-args`.
+    admit: (actor: Actor) =>
+      asCallerContext(actor, () => {
+        const ctx = useContext();
+        queryGuardBeforeInput(target.policy, { actor: actorOf(ctx), ctx, query: name }, 'server');
+      }),
     run: ({ input, actor }) =>
       asCallerContext(actor, async () => {
         // `sourceFor` is the authorized front half of `runQuery` — validate, guard, build —

package/src/registry.ts

@@ -147,6 +147,14 @@ export interface McpTool<A extends ToolArgs = ToolArgs> {
    * `list_resources` so an agent plans for the hand-off; it changes nothing about the call.
    */
   readonly confirms?: boolean;
+  /**
+   * The tool's policy, decided on the CALLER alone — throws the same denial `handle` would, or
+   * returns when the caller may call it (or when only the arguments can decide). The server asks
+   * it before answering `invalid-args`, so a caller who may never call this tool gets the 403,
+   * never an issue list describing its arguments. Projected actions and queries and app tools
+   * carry one; a hand-written tool without it answers `invalid-args` as before.
+   */
+  admit?(caller: McpCaller): void;
   // Method syntax (not a property) so a tool declared with narrower args stays assignable.
   handle(args: A, caller: McpCaller): Promise<McpToolResult>;
 }
@@ -222,7 +230,13 @@ export type ToolResolution =
   | { readonly kind: 'ok'; readonly tool: AnyMcpTool; readonly args: ToolArgs }
   | { readonly kind: 'not-found'; readonly name: string }
   | { readonly kind: 'scope-denied'; readonly name: string; readonly scope: string }
-  | { readonly kind: 'invalid-args'; readonly name: string; readonly issues: readonly ArgIssue[] };
+  | {
+      readonly kind: 'invalid-args';
+      readonly name: string;
+      readonly issues: readonly ArgIssue[];
+      /** The tool the arguments were refused for — asked to `admit` the caller first. */
+      readonly tool?: AnyMcpTool;
+    };
 
 export class ToolRegistry {
   readonly #tools = new Map<string, AnyMcpTool>();
@@ -268,7 +282,8 @@ export class ToolRegistry {
    * Both gates then validation, in the only order that is safe:
    *   1. visibility → not-found     (never reveals existence)
    *   2. scope      → scope-denied  (safe: the caller was already shown the tool)
-   *   3. args       → invalid-args
+   *   3. args       → invalid-args — unless the tool's `admit` refuses the caller first, which
+   *                    the server asks before answering (the policy's actor half, `dispatch`)
    *   4. policy     → inside `tool.handle`, which is why it is not here
    * Validating before the gates would leak a schema to a caller that may not see the tool;
    * running the policy before the scope gate would decide a refusal from attacker-supplied
@@ -283,7 +298,7 @@ export class ToolRegistry {
       return { kind: 'scope-denied', name, scope: tool.scope };
     }
     const validation = validateArgs(tool.inputSchema, rawArgs ?? {});
-    if (!validation.ok) return { kind: 'invalid-args', name, issues: validation.issues };
+    if (!validation.ok) return { kind: 'invalid-args', name, issues: validation.issues, tool };
     return { kind: 'ok', tool, args: validation.value };
   }
 

package/src/server.ts

@@ -5,9 +5,9 @@
 
 import type { ErrorAudience } from '@ultimat3/core';
 import { fixFor } from '@ultimat3/core';
-import { auditResourceRead, auditToolCall, outcomeForCode, outcomeForResult } from './audit';
+import { auditResourceRead, auditToolCall, outcomeForResult } from './audit';
 import { McpProtocolError, McpScopeDeniedError, TOOL_UNKNOWN_FIX } from './errors';
-import { asFrameworkError, renderFrameworkError } from './framework-error';
+import { asFrameworkError } from './framework-error';
 import { metaCall } from './meta-call';
 import { META_UNKNOWN_FIX } from './meta-errors';
 import type { McpResourceGroups, McpSurfaceOption, MetaResource } from './meta-surface';
@@ -26,6 +26,7 @@ import type { McpPrompt, McpResource } from './resources';
 import { ResourceRegistry } from './resources';
 import type { McpInstructions, McpServerVoice } from './server-voice';
 import { instructionsFor, invalidArgsResult } from './server-voice';
+import { admitted, thrownResponse } from './tool-thrown';
 import type { JsonRpcId, JsonRpcRequest, JsonRpcResponse, ServerInfo } from './wire';
 import {
   defaultServerInfo,
@@ -339,6 +340,11 @@ export class McpServer {
         });
       }
       case 'invalid-args': {
+        // The policy's actor half outranks the argument check: a caller the tool refuses whatever
+        // they send gets the denial `handle` would give, never the issue list — which describes
+        // the arguments of a tool they may not call.
+        const refused = admitted(resolved.tool, caller);
+        if (refused !== undefined) return thrownResponse(id, name, refused, caller, audience);
         const invalid = invalidArgsResult(name, resolved.issues, audience);
         auditToolCall({ tool: name, outcome: 'invalid-args', caller, code: invalid.code });
         return resultResponse(id, invalid.result);
@@ -351,25 +357,7 @@ export class McpServer {
     try {
       result = await resolved.tool.handle(resolved.args, caller);
     } catch (error) {
-      // OUTCOME 3 arrives here: the tool ran its policy through `guard()` and the policy
-      // said no. An UltimateError is an EXPECTED outcome the model can act on, so it comes
-      // back as an `isError` result carrying code/cause/fix — the same three lines an HTTP
-      // caller gets for the same call — rather than an opaque transport failure.
-      const framework = asFrameworkError(error);
-      if (framework !== undefined) {
-        auditToolCall({
-          tool: name,
-          outcome: outcomeForCode(framework.code),
-          caller,
-          code: framework.code,
-        });
-        return resultResponse(id, {
-          content: [{ type: 'text', text: renderFrameworkError(framework, audience) }],
-          isError: true,
-        });
-      }
-      auditToolCall({ tool: name, outcome: 'failed', caller });
-      return errorResponse(id, INTERNAL_ERROR, `tool "${name}" failed unexpectedly`);
+      return thrownResponse(id, name, error, caller, audience);
     }
 
     // A tool may answer `isError` itself (admin renders its own denial). Outcome 3 unless it

package/src/tool-thrown.ts

@@ -0,0 +1,51 @@
+// What a `tools/call` answers when the tool threw — or its `admit` refused the caller before the
+// arguments were read. One renderer for both, so a policy denial reads the same whichever gate
+// raised it. Split from `server.ts` for the file ceiling; the server is its only caller.
+
+import type { ErrorAudience } from '@ultimat3/core';
+import { auditToolCall, outcomeForCode } from './audit';
+import { asFrameworkError, renderFrameworkError } from './framework-error';
+import type { AnyMcpTool, McpCaller } from './registry';
+import type { JsonRpcId, JsonRpcResponse } from './wire';
+import { errorResponse, INTERNAL_ERROR, resultResponse } from './wire';
+
+/**
+ * OUTCOME 3 arrives here: the tool ran its policy through `guard()` and the policy said no. An
+ * UltimateError is an EXPECTED outcome the model can act on, so it comes back as an `isError`
+ * result carrying code/cause/fix — the same three lines an HTTP caller gets for the same call —
+ * rather than an opaque transport failure.
+ */
+export function thrownResponse(
+  id: JsonRpcId,
+  name: string,
+  error: unknown,
+  caller: McpCaller,
+  audience: ErrorAudience,
+): JsonRpcResponse {
+  const framework = asFrameworkError(error);
+  if (framework !== undefined) {
+    auditToolCall({
+      tool: name,
+      outcome: outcomeForCode(framework.code),
+      caller,
+      code: framework.code,
+    });
+    return resultResponse(id, {
+      content: [{ type: 'text', text: renderFrameworkError(framework, audience) }],
+      isError: true,
+    });
+  }
+  auditToolCall({ tool: name, outcome: 'failed', caller });
+  return errorResponse(id, INTERNAL_ERROR, `tool "${name}" failed unexpectedly`);
+}
+
+/** What the tool's `admit` threw for this caller, or `undefined` when it let them through. */
+export function admitted(tool: AnyMcpTool | undefined, caller: McpCaller): unknown {
+  if (tool?.admit === undefined) return undefined;
+  try {
+    tool.admit(caller);
+    return undefined;
+  } catch (error) {
+    return error;
+  }
+}