effect 4.1.0 → 4.1.1

package/src/ai/McpSchema.ts

@@ -1382,6 +1382,125 @@ export class ResourceUpdatedNotification extends Rpc.make("notifications/resourc
   }
 }) {}
 
+// =============================================================================
+// Skills
+// =============================================================================
+
+/**
+ * Schema for a file of an Agent Skill served under the MCP Skills extension
+ * (SEP-2640), with the digest and size of its content.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 4.1.1
+ */
+export class SkillResource extends Schema.Class<SkillResource>(
+  "@effect/ai/McpSchema/SkillResource"
+)({
+  /**
+   * The resource URI of the file.
+   */
+  uri: Schema.String,
+  /**
+   * The SHA-256 digest of the file's bytes, as `sha256:` followed by 64
+   * lowercase hexadecimal digits.
+   */
+  digest: Schema.String.check(Schema.isPattern(/^sha256:[0-9a-f]{64}$/)),
+  /**
+   * The length of the file's bytes.
+   */
+  size: Schema.Natural
+}) {}
+
+/**
+ * Schema for the YAML frontmatter of an Agent Skill's `SKILL.md`, as the
+ * Agent Skills specification defines it (https://agentskills.io/specification).
+ *
+ * **Details**
+ *
+ * Fields the specification does not define are kept unchanged. `McpServer`
+ * checks a skill's frontmatter against this schema before serving it. The
+ * frontmatter of a {@link Skill} received from a server is only checked for
+ * the `name` and `description` that the Skills extension requires; decode it
+ * with this schema for the other fields.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 4.1.1
+ */
+export const SkillFrontmatter = Schema.StructWithRest(
+  Schema.Struct({
+    /**
+     * 1 to 64 lowercase letters, digits and hyphens, with no leading, trailing
+     * or consecutive hyphen. It names the directory holding `SKILL.md`.
+     */
+    name: Schema.String.check(Schema.isMaxLength(64), Schema.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)),
+    /**
+     * What the skill does and when to use it, in 1 to 1024 characters.
+     */
+    description: Schema.String.check(Schema.isNonEmpty(), Schema.isMaxLength(1024)),
+    /**
+     * The skill's license, or the name of a bundled license file.
+     */
+    license: Schema.optionalKey(Schema.String),
+    /**
+     * Environment requirements, in 1 to 500 characters.
+     */
+    compatibility: Schema.optionalKey(Schema.String.check(Schema.isNonEmpty(), Schema.isMaxLength(500))),
+    /**
+     * Additional properties not defined by the specification.
+     */
+    metadata: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+    /**
+     * Space-separated tools the skill asks to run without approval. Hosts must
+     * ignore it for a skill served over MCP unless the user approved the grant.
+     */
+    "allowed-tools": Schema.optionalKey(Schema.String)
+  }),
+  [UnknownObject]
+)
+
+/**
+ * The YAML frontmatter of an Agent Skill's `SKILL.md`.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.1.1
+ */
+export type SkillFrontmatter = typeof SkillFrontmatter.Type
+
+/**
+ * Schema for an Agent Skill served under the MCP Skills extension (SEP-2640),
+ * as `skills/list` and `skills/get` describe it.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 4.1.1
+ */
+export class Skill extends Schema.Class<Skill>(
+  "@effect/ai/McpSchema/Skill"
+)({
+  /**
+   * The resource URI of the skill's `SKILL.md`.
+   */
+  uri: Schema.String,
+  /**
+   * The YAML frontmatter of the skill's `SKILL.md`, as a JSON object, with
+   * every field the author wrote. See {@link SkillFrontmatter} for the fields
+   * the Agent Skills specification defines.
+   */
+  frontmatter: Schema.StructWithRest(
+    Schema.Struct({ name: Schema.String, description: Schema.String }),
+    [UnknownObject]
+  ),
+  /**
+   * Every file of the skill, `SKILL.md` included, or `"dynamic"` when the
+   * server generates the skill's content and publishes no digests.
+   */
+  resources: Schema.Union([Schema.Array(SkillResource), Schema.Literal("dynamic")]),
+  _meta: optional(UnknownObject)
+}) {}
+
 // =============================================================================
 // Prompts
 // =============================================================================

package/src/ai/McpServer.ts

@@ -14,6 +14,7 @@
 import * as Arr from "../Array.ts"
 import * as Cause from "../Cause.ts"
 import * as Context from "../Context.ts"
+import * as Digest from "../crypto/Digest.ts"
 import * as Data from "../Data.ts"
 import * as Deferred from "../Deferred.ts"
 import * as Duration from "../Duration.ts"
@@ -53,6 +54,7 @@ import * as AiError from "./AiError.ts"
 import * as McpCore from "./internal/mcpCore.ts"
 import * as McpProtocolInternal from "./internal/mcpProtocol.ts"
 import * as McpRuntime from "./internal/mcpRuntime.ts"
+import * as McpSkills from "./internal/mcpSkills.ts"
 import * as InternalStructuredOutput from "./internal/structured-output.ts"
 import type * as McpProtocol from "./McpProtocol.ts"
 import * as McpSchema from "./McpSchema.ts"
@@ -106,6 +108,8 @@ interface QueuedServerNotification {
 
 const internalState = new WeakMap<object, {
   readonly core: McpCore.McpCore
+  // Registers a skill's own file, skipping the check that reserves it for the skill.
+  readonly addSkillFile: McpServer["Service"]["addResource"]
   readonly notifications: Queue.Dequeue<QueuedServerNotification>
   readonly notificationDelivery: { consumers: number; listChangeRevision: number; requestEndpoints: number }
   readonly globalMiddleware: Array<middleware.Fn<any, any, any>>
@@ -314,6 +318,9 @@ export type MiddlewareMethod =
   | "resources/list"
   | "resources/templates/list"
   | "prompts/list"
+  | "skills/list"
+  | "skills/get"
+  | "resources/directory/read"
 
 /**
  * Request metadata passed to MCP middleware.
@@ -322,12 +329,17 @@ export type MiddlewareMethod =
  *
  * `target` is the tool name, the requested resource URI, or the prompt name.
  * For `completion/complete` it is the prompt name, or the URI template of the
- * resource template being completed. `payload` holds the request parameters.
+ * resource template being completed. For `skills/get` it is the URI of the
+ * skill's `SKILL.md`. `payload` holds the request parameters.
  *
  * On list requests, middleware runs only when it wraps a {@link visibility},
  * once for each registration it wraps. `target` is then the tool name, the
  * resource URI, the URI template or the prompt name of that registration, and
- * `payload` is `undefined`.
+ * `payload` is `undefined`. `skills/list` and `resources/directory/read` are
+ * list requests whose `target` is the `SKILL.md` URI of each skill; a
+ * directory read checks only the skills that have the directory. A skill's
+ * files are resources, checked as `resources/list` and `resources/read` with
+ * their own URIs.
  *
  * `headers` are the HTTP request headers. They are empty on stdio, on custom
  * transports and for in-process calls. `sessionId` is the `Mcp-Session-Id`
@@ -759,7 +771,7 @@ const internalError = new InternalError({ message: "Internal error" })
 const rejectWith = (error: McpErrorBase) =>
   Effect.fail(new McpCore.RequestRejected({ code: error.code, message: error.message, data: error.data, error }))
 
-type CallMethod = "tools/call" | "resources/read" | "prompts/get" | "completion/complete"
+type CallMethod = "tools/call" | "resources/read" | "prompts/get" | "completion/complete" | "skills/get"
 
 type ListMethod = Exclude<MiddlewareMethod, CallMethod>
 
@@ -768,6 +780,7 @@ interface NotFoundErrors {
   readonly "resources/read": McpCore.ResourceNotFound
   readonly "prompts/get": McpCore.PromptNotFound
   readonly "completion/complete": InvalidParams
+  readonly "skills/get": McpCore.SkillNotFound
 }
 
 const notFound = (method: CallMethod, target: string): NotFoundErrors[CallMethod] => {
@@ -780,6 +793,8 @@ const notFound = (method: CallMethod, target: string): NotFoundErrors[CallMethod
       return new McpCore.PromptNotFound({ name: target })
     case "completion/complete":
       return new InvalidParams({ message: "Unknown completion reference or argument" })
+    case "skills/get":
+      return new McpCore.SkillNotFound({ uri: target })
   }
 }
 
@@ -1127,6 +1142,38 @@ export class McpServer extends Context.Service<McpServer, {
         ))
     })
 
+    // Checking skill ownership and both writes happen in one synchronous step,
+    // so a skill cannot claim the URI in between. Skill files skip the check.
+    const addResource = (
+      options: Parameters<McpServer["Service"]["addResource"]>[0],
+      checkOwnership: boolean
+    ): Effect.Effect<void> =>
+      Effect.suspend(() => {
+        if (checkOwnership && internalCore.skills.ownsFile(options.resource.uri)) {
+          return Effect.die(
+            new Cause.IllegalArgumentError(`Resource ${options.resource.uri} is a file of a registered skill`)
+          )
+        }
+        const existingIndex = resources.findIndex(({ resource }) => resource.uri === options.resource.uri)
+        if (existingIndex === -1) {
+          resources.push(options)
+        } else {
+          resources[existingIndex] = options
+        }
+        const { invoke, visible } = makeInvoke(options.services, globalMiddleware)
+        internalCore.resources.register({
+          descriptor: options.resource,
+          visible: visible("resources/list", options.resource.uri),
+          isVisible: isEnabled(options.annotations),
+          read: (invocation) =>
+            invoke(options.handle, invocation, {
+              method: "resources/read",
+              target: options.resource.uri,
+              payload: { uri: options.resource.uri }
+            })
+        })
+        return notifications.client["notifications/resources/list_changed"]({})
+      })
     const service = McpServer.of({
       notifications: notifications.client,
       notifyElicitationComplete: ({ clientId, elicitationId }) =>
@@ -1222,27 +1269,7 @@ export class McpServer extends Context.Service<McpServer, {
       get resourceTemplates() {
         return resourceTemplates
       },
-      addResource: Effect.fnUntraced(function*(options) {
-        const existingIndex = resources.findIndex(({ resource }) => resource.uri === options.resource.uri)
-        if (existingIndex === -1) {
-          resources.push(options)
-        } else {
-          resources[existingIndex] = options
-        }
-        const { invoke, visible } = makeInvoke(options.services, globalMiddleware)
-        yield* internalCore.resources.register({
-          descriptor: options.resource,
-          visible: visible("resources/list", options.resource.uri),
-          isVisible: isEnabled(options.annotations),
-          read: (invocation) =>
-            invoke(options.handle, invocation, {
-              method: "resources/read",
-              target: options.resource.uri,
-              payload: { uri: options.resource.uri }
-            })
-        })
-        yield* notifications.client["notifications/resources/list_changed"]({})
-      }),
+      addResource: (options) => addResource(options, true),
       addResourceTemplate: Effect.fnUntraced(
         function*({ annotations, completions, handle, routerPath, services, template }) {
           const existingIndex = resourceTemplates.findIndex(({ template: current }) =>
@@ -1400,6 +1427,7 @@ export class McpServer extends Context.Service<McpServer, {
     })
     internalState.set(service, {
       core: internalCore,
+      addSkillFile: (options) => addResource(options, false),
       notifications: notificationsQueue,
       notificationDelivery,
       globalMiddleware
@@ -1467,9 +1495,11 @@ export interface CacheHint {
  *
  * Each entry sets the freshness and `cacheScope` of one result kind:
  * `server/discover`, `tools/list`, `resources/list`,
- * `resources/templates/list` and `prompts/list`. Omitted entries, and
- * `resources/read` results, keep `{ ttlMs: 0, cacheScope: "private" }`.
- * Earlier protocol revisions have no cache hints and ignore this option.
+ * `resources/templates/list` and `prompts/list`. `skills` covers the Skills
+ * extension's `skills/list`, `skills/get` and `resources/directory/read`.
+ * Omitted entries, and `resources/read` results, keep
+ * `{ ttlMs: 0, cacheScope: "private" }`. Earlier protocol revisions have no
+ * cache hints and ignore this option.
  *
  * These are hints for clients. The server does not cache results, and
  * visibility and invocation checks still run on every request.
@@ -1491,6 +1521,7 @@ export interface CacheHints {
   readonly resources?: CacheHint | undefined
   readonly resourceTemplates?: CacheHint | undefined
   readonly prompts?: CacheHint | undefined
+  readonly skills?: CacheHint | undefined
 }
 
 // Converts each hint to the wire's nonnegative integer `ttlMs` once, when the server is built.
@@ -3058,6 +3089,32 @@ export const registerToolkit: <Tools extends Record<string, Tool.Any>>(
         ? Effect.succeed(toolErrorResult(error.message))
         : Effect.map(encodeFailure(error), (encoded) =>
           new CallToolResult({ isError: true, content: toolResultContent(encoded) }))
+    // `structuredContent` must be JSON and match the advertised `outputSchema`, which is derived from the JSON codec.
+    // The Toolkit has already encoded the result, so only the JSON conversion of its encoded form runs here.
+    const encodeStructured = Schema.encodeUnknownEffect(Schema.toCodecJson(Schema.toEncoded(tool.successSchema))) as (
+      result: unknown
+    ) => Effect.Effect<unknown, Schema.SchemaError, Tool.HandlerServices<Tools[keyof Tools]>>
+    const successResult = (result: unknown) =>
+      encodeStructured(result).pipe(
+        Effect.mapError((cause) =>
+          AiError.make({
+            module: "McpServer",
+            method: "registerToolkit",
+            reason: new AiError.ToolResultEncodingError({
+              toolName: tool.name,
+              toolResult: result,
+              description: cause.message
+            })
+          })
+        ),
+        Effect.map((structuredContent) =>
+          new CallToolResult({
+            isError: false,
+            structuredContent,
+            content: toolResultContent(structuredContent)
+          })
+        )
+      )
     const handleCause = (cause: Cause.Cause<unknown>) => {
       const failure = Cause.findFail(cause)
       if (Result.isSuccess(failure)) {
@@ -3113,21 +3170,27 @@ export const registerToolkit: <Tools extends Record<string, Tool.Any>>(
           Stream.unwrap,
           Stream.runLast,
           Effect.flatMap(Effect.fromOption),
-          Effect.flatMap((result) =>
+          Effect.flatMap((result): Effect.Effect<
+            CallToolResult,
+            unknown,
+            Tool.HandlerServices<Tools[keyof Tools]>
+          > => {
+            if (!result.isFailure) {
+              // An absent result, such as `Schema.Void`, has no structured form.
+              return result.encodedResult === undefined
+                ? Effect.succeed(new CallToolResult({ isError: false, content: [] }))
+                : successResult(result.encodedResult)
+            }
             // Declared failures return their encoded payload; anything else is classified by origin.
-            result.isFailure && result.failureOrigin !== "handler"
-              ? Effect.failCause(Cause.annotate(
+            return result.failureOrigin === "handler"
+              ? Effect.succeed(
+                new CallToolResult({ isError: true, content: toolResultContent(result.encodedResult) })
+              )
+              : Effect.failCause(Cause.annotate(
                 Cause.fail(result.result),
                 Context.make(Toolkit.FailureOrigin, result.failureOrigin ?? "result")
               ))
-              : Effect.succeed(
-                new CallToolResult({
-                  isError: result.isFailure,
-                  structuredContent: result.isFailure ? undefined : result.encodedResult,
-                  content: toolResultContent(result.encodedResult)
-                })
-              )
-          ),
+          }),
           Effect.catchCause(handleCause)
         ) as Effect.Effect<CallToolResult, InvalidParams, never>
       },
@@ -3565,6 +3628,166 @@ export const resource: {
   return (options: any) => Layer.effectDiscard(register(options))
 } as any
 
+/**
+ * A file of a skill: its text, its bytes, or either with an explicit MIME
+ * type. Without one, the MIME type is inferred from the file extension.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.1.1
+ */
+export type SkillFile = string | Uint8Array | {
+  readonly content: string | Uint8Array
+  readonly mimeType?: string | undefined
+}
+
+/**
+ * Options for {@link registerSkill} and {@link skill}.
+ *
+ * **Details**
+ *
+ * `uri` addresses the skill's `SKILL.md`, as
+ * `skill://<skill-path>/SKILL.md`. Its last path segment is the skill's name,
+ * which must equal the frontmatter's `name`. Other schemes work the same way.
+ *
+ * `files` maps paths relative to the skill root to the skill's files,
+ * `SKILL.md` included. Files are served verbatim, and the skill's listed
+ * frontmatter is parsed from `SKILL.md`. Quote frontmatter strings that a YAML
+ * 1.1 parser reads as another type, such as `yes` or `1.0`.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.1.1
+ */
+export interface SkillOptions {
+  readonly uri: string
+  readonly files: { readonly "SKILL.md": SkillFile } & Readonly<Record<string, SkillFile>>
+  readonly annotations?: Context.Context<never> | undefined
+}
+
+const skillFileEncoder = new TextEncoder()
+
+// Bytes are copied so that later changes by the caller cannot alter what is
+// served under the listed digest. `Buffer#slice` shares memory, so copy with
+// the `Uint8Array` constructor.
+const toSkillSourceFile = (path: string, file: SkillFile): McpSkills.SourceFile => {
+  const { content, mimeType } = typeof file === "string" || file instanceof Uint8Array ? { content: file } : file
+  return {
+    path,
+    content: typeof content === "string" ? skillFileEncoder.encode(content) : new Uint8Array(content),
+    mimeType
+  }
+}
+
+/**
+ * Registers an Agent Skill under the MCP Skills extension (SEP-2640).
+ *
+ * **Details**
+ *
+ * Each file is registered as a resource, and the skill is listed by
+ * `skills/list` and `skills/get` with a manifest of every file's SHA-256
+ * digest and size, computed from the bytes served. Every directory of the
+ * skill namespace is readable with `resources/directory/read`. The server
+ * declares the extension once any skill is registered.
+ *
+ * Fails when the skill breaks the extension's rules: a name that does not
+ * match the URI, a `SKILL.md` without YAML frontmatter, frontmatter that is
+ * not valid {@link McpSchema.SkillFrontmatter}, a file path that leaves the
+ * skill, or more than 512 files or 16 MiB in all. It also fails when the
+ * skill's directory contains or lies inside another skill's, or one of its
+ * files is already registered as a resource. Registering a resource at the
+ * URI of a skill's file afterwards is a defect.
+ *
+ * SHA-256 runs on `crypto.subtle`.
+ *
+ * @see {@link skill} for the layer-based skill registration wrapper
+ *
+ * @stability unstable
+ * @category handlers
+ * @since 4.1.1
+ */
+export const registerSkill: (options: SkillOptions) => Effect.Effect<void, Cause.IllegalArgumentError, McpServer> =
+  Effect.fnUntraced(function*(options: SkillOptions) {
+    const files = Object.entries(options.files).map(([path, file]) => toSkillSourceFile(path, file))
+    const skill = yield* McpSkills.makeStaticSkill({ uri: options.uri, files }).pipe(
+      Effect.provide(Digest.layerWebCrypto)
+    )
+
+    const registry = yield* McpServer
+    const { addSkillFile, core, globalMiddleware } = internalState.get(registry)!
+    const services = yield* Effect.context<never>()
+    const annotations = options.annotations ?? Context.empty()
+    const { invoke, visible } = makeInvoke(services, globalMiddleware)
+    // Claims the skill's file URIs before they are registered as resources.
+    yield* core.skills.register({
+      entry: skill.entry,
+      isVisible: isEnabled(annotations),
+      visible: visible("skills/list", options.uri),
+      visibleInDirectories: visible("resources/directory/read", options.uri),
+      get: (invocation) =>
+        invoke(Effect.succeed(skill.entry), invocation, {
+          method: "skills/get",
+          target: options.uri,
+          payload: { uri: options.uri }
+        }),
+      directory: (uri) => skill.directories.get(uri)
+    })
+    for (const { content, resource, text } of skill.files) {
+      const { uri, mimeType } = resource
+      yield* addSkillFile({
+        resource: new Resource(resource),
+        annotations,
+        services,
+        handle: Effect.succeed({
+          contents: [text === undefined ? { uri, mimeType, blob: content } : { uri, mimeType, text }]
+        })
+      })
+    }
+  })
+
+/**
+ * Creates a layer that registers an Agent Skill under the MCP Skills extension
+ * (SEP-2640).
+ *
+ * **Example** (Publishing a skill with a supporting file)
+ *
+ * ```ts
+ * import { Layer } from "effect"
+ * import { McpProtocol, McpServer } from "effect/ai"
+ *
+ * const RefundsSkill = McpServer.skill({
+ *   uri: "skill://billing/refunds/SKILL.md",
+ *   files: {
+ *     "SKILL.md": `---
+ * name: refunds
+ * description: Process refunds using the billing tools
+ * ---
+ *
+ * Read references/policy.md before issuing a refund.
+ * `,
+ *     "references/policy.md": "Refunds above CHF 500 require manager approval.\n"
+ *   }
+ * })
+ *
+ * const ServerLayer = RefundsSkill.pipe(
+ *   Layer.provide(McpServer.layerHttp({
+ *     name: "billing",
+ *     version: "1.0.0",
+ *     path: "/mcp",
+ *     protocols: [McpProtocol.v2026_07_28, McpProtocol.v2025_11_25]
+ *   }))
+ * )
+ * ```
+ *
+ * @see {@link registerSkill} for the Effect-level skill registration API
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.1.1
+ */
+export const skill = (options: SkillOptions): Layer.Layer<never, Cause.IllegalArgumentError, McpServer> =>
+  Layer.effectDiscard(registerSkill(options))
+
 /**
  * Registers an MCP prompt from an Effect program.
  *

package/src/ai/Prompt.ts

@@ -486,6 +486,16 @@ export interface FilePartEncoded extends BasePartEncoded<"file", FilePartOptions
  */
 export interface FilePartOptions extends ProviderOptions {}
 
+const TaggedURL = Schema.TaggedStruct("URL", { href: Schema.URLFromString })
+
+const urlFromTaggedURL = SchemaTransformation.transform<URL, typeof TaggedURL.Type>({
+  decode: ({ href }) => href,
+  encode: (href) => (({
+    _tag: "URL",
+    href
+  }) as const)
+})
+
 /**
  * Schema for validation and encoding of file parts.
  *
@@ -535,18 +545,13 @@ export const FilePart: Schema.Struct<{
         }) as const)
       })
     )),
-    Schema.TaggedStruct("URL", { href: Schema.URLFromString }).pipe(Schema.decodeTo(
-      Schema.URL,
-      SchemaTransformation.transform({
-        decode: ({ href }) => href,
-        encode: (href) => (({
-          _tag: "URL",
-          href
-        }) as const)
-      })
-    )),
+    TaggedURL.pipe(Schema.decodeTo(Schema.URL, urlFromTaggedURL)),
     Schema.Uint8Array,
-    Schema.URL
+    // Under the JSON and binary codecs a raw `URL` would serialize as a plain
+    // string, indistinguishable from the `Schema.String` member. Serialize it
+    // through the same `TaggedURL` instance instead, so the codecs see a
+    // single `{ _tag: "URL" }` member rather than two
+    Schema.URL.annotate({ toCodecJson: () => Schema.link<URL>()(TaggedURL, urlFromTaggedURL) })
   ])
 }).annotate({ identifier: "FilePart" })
 

package/src/ai/Tool.ts

@@ -2096,8 +2096,9 @@ export const getStrictMode = <T extends Any>(tool: T): boolean | undefined => Co
 //
 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-const suspectProtoRx = /"__proto__"\s*:/
-const suspectConstructorRx = /"constructor"\s*:/
+// Text that may decode to a forbidden key. `JSON.parse` decodes Unicode
+// escapes (e.g. `"\u005f_proto__"`), so any `\u` escape also triggers the scan.
+const suspectRx = /"__proto__"\s*:|"constructor"\s*:|\\u/
 
 function _parse(text: string) {
   // Parse normally
@@ -2108,15 +2109,8 @@ function _parse(text: string) {
     return obj
   }
 
-  if (
-    suspectProtoRx.test(text) === false &&
-    suspectConstructorRx.test(text) === false
-  ) {
-    return obj
-  }
-
   // Scan result for proto keys
-  return filter(obj)
+  return suspectRx.test(text) ? filter(obj) : obj
 }
 
 function filter(obj: any) {
@@ -2133,6 +2127,7 @@ function filter(obj: any) {
 
       if (
         Object.hasOwn(node, "constructor") &&
+        node.constructor !== null &&
         Object.hasOwn(node.constructor, "prototype")
       ) {
         throw new SyntaxError("Object contains forbidden prototype property")