Declare and check a supported Jackson floor

acp-json-jackson2 needs Jackson 2.18.1 or later and acp-json-jackson3
Jackson 3.0.0 or later: the oldest releases the SDK's tests pass with.
Each supplier and mapper constructor checks jackson-core and
jackson-databind and fails with a message naming the found and required
versions, instead of a NoSuchMethodError on the first message.

Author: Mark Pollack

CHANGELOG.md

@@ -305,6 +305,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **A supported Jackson floor, checked at startup: Jackson 2.18.1 or later for
+  `acp-json-jackson2`, Jackson 3.0.0 or later for `acp-json-jackson3`.** Frameworks manage their
+  own Jackson version, and the SDK stated none: an older Jackson (Vert.x 4.5's jackson-core 2.16.1
+  under jackson-databind 2.22.3, for example) failed much later with a `NoSuchMethodError` while
+  reading a message. Each mapper supplier (`JacksonAcpJsonMapperSupplier`,
+  `Jackson3AcpJsonMapperSupplier`) and mapper constructor now checks the jackson-core and
+  jackson-databind on the classpath and fails with an `IllegalStateException` naming the version
+  found and the version required. The floors are the oldest releases the SDK's tests pass with
+  (2.18.0 drops unknown values of the open enumerations, and 2.17 the unknown fields the SDK keeps
+  for forward compatibility). Quarkus 3.40 (Jackson 2.21.7) and Spring Boot 4.1 (Jackson 3.1.7) are
+  within them. Migration: none for a
+  consistent Jackson at or above the floor; otherwise align the Jackson artifacts on one version,
+  for example by importing the `jackson-bom`.
+
 - **Breaking: `StdioAcpClientTransport.awaitForExit()` is renamed `awaitProcessExit()`**, so it does
   not sit beside `awaitTermination()` (which completes when the transport ends, not the process).
   Interrupted, it now throws `CancellationException` and keeps the thread's interrupt flag; it used

README.md

@@ -86,6 +86,15 @@ Jackson 2 (-200), and an application's own supplier (default 0) wins over both.
 the system property `acp.json.mapper.supplier` to the supplier's class name, for example
 `com.agentclientprotocol.sdk.json.JacksonAcpJsonMapperSupplier`.
 
+**Supported Jackson versions.** `acp-json-jackson2` needs Jackson **2.18.1 or later** and
+`acp-json-jackson3` needs Jackson **3.0.0 or later**, for jackson-core and jackson-databind alike;
+the SDK is built and released against the versions in its POM (Jackson 2.22.3 and 3.1.7).
+Frameworks manage their own Jackson version: Quarkus 3.40 (Jackson 2.21.7) and Spring Boot 4.1
+(Jackson 3.1.7) are within these floors. Creating a mapper checks the versions on the classpath and
+fails at once with an `IllegalStateException` that names the version found and the one required,
+instead of a `NoSuchMethodError` on the first message. Keep the Jackson artifacts on one version,
+for example by importing `com.fasterxml.jackson:jackson-bom` (or `tools.jackson:jackson-bom`).
+
 For annotation-based agent development:
 ```xml
 <dependency>

acp-json-jackson2/src/main/java/com/agentclientprotocol/sdk/json/JacksonAcpJsonMapper.java

@@ -26,7 +26,8 @@
  * Jackson 2 implementation of {@link AcpJsonMapper}, shipped in {@code acp-json-jackson2}.
  * Wraps a Jackson {@link ObjectMapper} but keeps the SDK decoupled from Jackson at the API
  * level. It keeps the package it had when it lived in {@code acp-core}, so code that
- * constructs it compiles unchanged.
+ * constructs it compiles unchanged. It needs Jackson 2.18.1 or later (jackson-core and
+ * jackson-databind), which it checks when it is created.
  *
  * @author Mark Pollack
  */
@@ -93,8 +94,11 @@ public boolean handleUnknownProperty(DeserializationContext ctxt, JsonParser p,
 	 * Constructs a new JacksonAcpJsonMapper with the given ObjectMapper.
 	 * @param objectMapper the ObjectMapper to use. Must not be null.
 	 * @throws IllegalArgumentException if the provided ObjectMapper is null.
+	 * @throws IllegalStateException if the Jackson 2 on the classpath is older than the supported
+	 * floor (see the type comment)
 	 */
 	public JacksonAcpJsonMapper(ObjectMapper objectMapper) {
+		JacksonVersions.requireSupported();
 		if (objectMapper == null) {
 			throw new IllegalArgumentException("ObjectMapper must not be null");
 		}

acp-json-jackson2/src/main/java/com/agentclientprotocol/sdk/json/JacksonAcpJsonMapperSupplier.java

@@ -23,6 +23,8 @@ public int priority() {
 
 	@Override
 	public AcpJsonMapper get() {
+		// Before building the ObjectMapper: an unsupported Jackson may fail inside it.
+		JacksonVersions.requireSupported();
 		return new JacksonAcpJsonMapper(JacksonAcpJsonMapper.defaultObjectMapper());
 	}
 

acp-json-jackson2/src/main/java/com/agentclientprotocol/sdk/json/JacksonVersions.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2026-2026 the original author or authors.
+ */
+
+package com.agentclientprotocol.sdk.json;
+
+import com.fasterxml.jackson.core.Version;
+
+/**
+ * The Jackson 2 versions acp-json-jackson2 supports: {@value #FLOOR} or later, for jackson-core
+ * and jackson-databind alike. Frameworks manage their own Jackson version, and an older
+ * jackson-core under a newer jackson-databind fails much later with a {@code NoSuchMethodError}
+ * while reading a message; checking when the mapper is created names the problem instead.
+ */
+final class JacksonVersions {
+
+	/**
+	 * The oldest Jackson 2 release the SDK's tests pass with. 2.18.0 loses unknown values of the
+	 * SDK's open enumerations (stop reasons, plan entry statuses), and 2.17 the unknown fields the
+	 * SDK keeps for forward compatibility.
+	 */
+	static final String FLOOR = "2.18.1";
+
+	private static final Version FLOOR_VERSION = new Version(2, 18, 1, null, "com.fasterxml.jackson.core",
+			"jackson-core");
+
+	private JacksonVersions() {
+	}
+
+	/**
+	 * Fails unless the jackson-core and jackson-databind on the classpath are {@value #FLOOR} or
+	 * later.
+	 * @throws IllegalStateException naming the version found and the version required
+	 */
+	static void requireSupported() {
+		require("jackson-core", com.fasterxml.jackson.core.json.PackageVersion.VERSION);
+		require("jackson-databind", com.fasterxml.jackson.databind.cfg.PackageVersion.VERSION);
+	}
+
+	/**
+	 * Fails unless {@code found} is {@value #FLOOR} or later.
+	 * @param artifact the Jackson artifact the version belongs to
+	 * @param found the version on the classpath
+	 * @throws IllegalStateException naming the version found and the version required
+	 */
+	static void require(String artifact, Version found) {
+		if (found.getMajorVersion() != FLOOR_VERSION.getMajorVersion()
+				|| compare(found, FLOOR_VERSION) < 0) {
+			throw new IllegalStateException("acp-json-jackson2 needs Jackson " + FLOOR + " or later, but " + artifact
+					+ " " + found.toString() + " is on the classpath (jackson-core "
+					+ com.fasterxml.jackson.core.json.PackageVersion.VERSION.toString() + ", jackson-databind "
+					+ com.fasterxml.jackson.databind.cfg.PackageVersion.VERSION.toString()
+					+ "). Align the Jackson 2 artifacts on one version, " + FLOOR
+					+ " or later, for example by importing com.fasterxml.jackson:jackson-bom.");
+		}
+	}
+
+	/** Compares major, minor and patch level only, ignoring the artifact and any snapshot. */
+	private static int compare(Version a, Version b) {
+		int major = Integer.compare(a.getMajorVersion(), b.getMajorVersion());
+		if (major != 0) {
+			return major;
+		}
+		int minor = Integer.compare(a.getMinorVersion(), b.getMinorVersion());
+		return (minor != 0) ? minor : Integer.compare(a.getPatchLevel(), b.getPatchLevel());
+	}
+
+}

acp-json-jackson2/src/test/java/com/agentclientprotocol/sdk/json/JacksonVersionsTest.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2026-2026 the original author or authors.
+ */
+
+package com.agentclientprotocol.sdk.json;
+
+import com.fasterxml.jackson.core.Version;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThatCode;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+/**
+ * acp-json-jackson2 states its Jackson floor and checks it when a mapper is created: an older
+ * jackson-core (a framework's BOM pinning 2.16.1 under databind 2.22.3, say) fails at once with
+ * a message naming both versions, instead of a {@code NoSuchMethodError} on the first message.
+ */
+class JacksonVersionsTest {
+
+	@Test
+	void aJacksonOlderThanTheFloorIsRefusedNamingFoundAndRequired() {
+		assertThatThrownBy(() -> JacksonVersions.require("jackson-core",
+				new Version(2, 16, 1, null, "com.fasterxml.jackson.core", "jackson-core")))
+			.isInstanceOf(IllegalStateException.class)
+			.hasMessageContaining("jackson-core 2.16.1")
+			.hasMessageContaining("needs Jackson " + JacksonVersions.FLOOR + " or later");
+	}
+
+	@Test
+	void theFloorAndTheJacksonOfQuarkusAreAccepted() {
+		assertThatCode(() -> JacksonVersions.require("jackson-databind",
+				new Version(2, 18, 1, null, "com.fasterxml.jackson.core", "jackson-databind")))
+			.doesNotThrowAnyException();
+		assertThatThrownBy(() -> JacksonVersions.require("jackson-databind",
+				new Version(2, 18, 0, null, "com.fasterxml.jackson.core", "jackson-databind")))
+			.isInstanceOf(IllegalStateException.class);
+		// Quarkus 3.40 manages Jackson 2.21.7.
+		assertThatCode(() -> JacksonVersions.require("jackson-databind",
+				new Version(2, 21, 7, null, "com.fasterxml.jackson.core", "jackson-databind")))
+			.doesNotThrowAnyException();
+	}
+
+	@Test
+	void theJacksonOnTheClasspathIsSupportedAndTheSupplierChecksIt() {
+		assertThatCode(JacksonVersions::requireSupported).doesNotThrowAnyException();
+		assertThatCode(() -> new JacksonAcpJsonMapperSupplier().get()).doesNotThrowAnyException();
+	}
+
+}

acp-json-jackson3/src/main/java/com/agentclientprotocol/sdk/json/jackson3/Jackson3AcpJsonMapper.java

@@ -28,7 +28,8 @@
 /**
  * Jackson 3 ({@code tools.jackson}) implementation of {@link AcpJsonMapper}, shipped in
  * {@code acp-json-jackson3}. Wraps a Jackson {@link JsonMapper} but keeps the SDK
- * decoupled from Jackson at the API level.
+ * decoupled from Jackson at the API level. It needs Jackson 3.0.0 or later (jackson-core and
+ * jackson-databind), which it checks when it is created.
  *
  * <p>
  * The schema records carry Jackson 2 annotations ({@code com.fasterxml.jackson.annotation}),
@@ -131,8 +132,11 @@ public boolean handleUnknownProperty(DeserializationContext ctxt, JsonParser p,
 	 * Constructs a new Jackson3AcpJsonMapper with the given JsonMapper, used as is.
 	 * @param jsonMapper the JsonMapper to use. Must not be null.
 	 * @throws IllegalArgumentException if the provided JsonMapper is null.
+	 * @throws IllegalStateException if the Jackson 3 on the classpath is older than the supported
+	 * floor (see the type comment)
 	 */
 	public Jackson3AcpJsonMapper(JsonMapper jsonMapper) {
+		Jackson3Versions.requireSupported();
 		if (jsonMapper == null) {
 			throw new IllegalArgumentException("JsonMapper must not be null");
 		}

acp-json-jackson3/src/main/java/com/agentclientprotocol/sdk/json/jackson3/Jackson3AcpJsonMapperSupplier.java

@@ -28,6 +28,8 @@ public int priority() {
 
 	@Override
 	public AcpJsonMapper get() {
+		// Before building the JsonMapper: an unsupported Jackson may fail inside it.
+		Jackson3Versions.requireSupported();
 		return new Jackson3AcpJsonMapper(Jackson3AcpJsonMapper.defaultJsonMapper());
 	}
 

acp-json-jackson3/src/main/java/com/agentclientprotocol/sdk/json/jackson3/Jackson3Versions.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2026-2026 the original author or authors.
+ */
+
+package com.agentclientprotocol.sdk.json.jackson3;
+
+import tools.jackson.core.Version;
+
+/**
+ * The Jackson 3 versions acp-json-jackson3 supports: {@value #FLOOR} or later, for jackson-core
+ * and jackson-databind alike. Checked when the mapper is created, so a framework that manages an
+ * older Jackson fails at once with a message naming the versions, not later while reading a
+ * message.
+ */
+final class Jackson3Versions {
+
+	/** The oldest Jackson 3 release the SDK's tests pass with: the first release of Jackson 3. */
+	static final String FLOOR = "3.0.0";
+
+	private static final int FLOOR_MAJOR = 3;
+
+	private static final int FLOOR_MINOR = 0;
+
+	private Jackson3Versions() {
+	}
+
+	/**
+	 * Fails unless the jackson-core and jackson-databind on the classpath are {@value #FLOOR} or
+	 * later.
+	 * @throws IllegalStateException naming the version found and the version required
+	 */
+	static void requireSupported() {
+		require("jackson-core", tools.jackson.core.json.PackageVersion.VERSION);
+		require("jackson-databind", tools.jackson.databind.cfg.PackageVersion.VERSION);
+	}
+
+	/**
+	 * Fails unless {@code found} is {@value #FLOOR} or later.
+	 * @param artifact the Jackson artifact the version belongs to
+	 * @param found the version on the classpath
+	 * @throws IllegalStateException naming the version found and the version required
+	 */
+	static void require(String artifact, Version found) {
+		if (found.getMajorVersion() != FLOOR_MAJOR || found.getMinorVersion() < FLOOR_MINOR) {
+			throw new IllegalStateException("acp-json-jackson3 needs Jackson " + FLOOR + " or later, but " + artifact
+					+ " " + found.toString() + " is on the classpath (jackson-core "
+					+ tools.jackson.core.json.PackageVersion.VERSION.toString() + ", jackson-databind "
+					+ tools.jackson.databind.cfg.PackageVersion.VERSION.toString()
+					+ "). Align the Jackson 3 artifacts on one version, " + FLOOR
+					+ " or later, for example by importing tools.jackson:jackson-bom.");
+		}
+	}
+
+}

acp-json-jackson3/src/test/java/com/agentclientprotocol/sdk/json/jackson3/Jackson3VersionsTest.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2026-2026 the original author or authors.
+ */
+
+package com.agentclientprotocol.sdk.json.jackson3;
+
+import tools.jackson.core.Version;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThatCode;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+/**
+ * acp-json-jackson3 states its Jackson 3 floor and checks it when a mapper is created: a Jackson
+ * outside it fails at once with a message naming the versions found and required.
+ */
+class Jackson3VersionsTest {
+
+	@Test
+	void aJacksonOutsideTheFloorIsRefusedNamingFoundAndRequired() {
+		assertThatThrownBy(() -> Jackson3Versions.require("jackson-core",
+				new Version(2, 22, 3, null, "tools.jackson.core", "jackson-core")))
+			.isInstanceOf(IllegalStateException.class)
+			.hasMessageContaining("jackson-core 2.22.3")
+			.hasMessageContaining("needs Jackson " + Jackson3Versions.FLOOR + " or later");
+	}
+
+	@Test
+	void theFloorAndTheJacksonOfSpringBootAreAccepted() {
+		String[] floor = Jackson3Versions.FLOOR.split("\\.");
+		assertThatCode(() -> Jackson3Versions.require("jackson-databind", new Version(3, Integer.parseInt(floor[1]),
+				0, null, "tools.jackson.core", "jackson-databind")))
+			.doesNotThrowAnyException();
+		// Spring Boot 4.1 manages Jackson 3.1.7.
+		assertThatCode(() -> Jackson3Versions.require("jackson-databind",
+				new Version(3, 1, 7, null, "tools.jackson.core", "jackson-databind")))
+			.doesNotThrowAnyException();
+	}
+
+	@Test
+	void theJacksonOnTheClasspathIsSupportedAndTheSupplierChecksIt() {
+		assertThatCode(Jackson3Versions::requireSupported).doesNotThrowAnyException();
+		assertThatCode(() -> new Jackson3AcpJsonMapperSupplier().get()).doesNotThrowAnyException();
+	}
+
+}