Migrating to 0.80.0

​

The SDK listener now binds localhost only, and checks browser origins

​

Spring Boot support moved into the SDK

​

Removed: session/set_model and the WebSocket-only agent transport

// Before (removed)
AcpAgent.async(new WebSocketAcpAgentTransport(port, mapper))...build();

// After
new StreamableHttpAcpAgentTransport(port, mapper,
    AcpAgentFactory.async(t -> AcpAgent.async(t)...build()));

​

Removed: @SessionState and @AcpExceptionHandler

​

Annotation model: capabilities derived from handlers, and new return/parameter support

• @SetSessionMode or @SetSessionConfigOption without a @NewSession method is now a build error. Those two set state a session needs to exist first; an agent offering either must also offer a way to create the session with the options they set.
• Every agent needs a @Prompt method (or a prompt handler, on the plain builder). Building one without it now fails with IllegalStateException, rather than silently answering “Method not found” for every prompt at runtime.
• A handler-implied capability can no longer be withdrawn by an @Initialize method. Capabilities merge by OR: a handler’s presence always means “advertised,” even if the @Initialize response returned doesn’t mention it. If you relied on @Initialize to selectively suppress a capability a handler would otherwise imply, remove the handler instead (or gate it so it isn’t registered).
• Misuse of the annotation model now fails at registration, not at the first call. Two handler methods for one annotation, two handler annotations on one method, a parameter no resolver can supply, @SessionId/@ConfigId/@ConfigValue on a method that doesn’t have a session or config option to supply it from, and a request handler declared void or returning the wrong type: all of these now throw when the agent is built, each naming the class, method, and fix, instead of behaving unpredictably (or not at all) once traffic arrives.
• MonoHandler is renamed AsyncValueHandler, and now also handles CompletionStage and any single-value Reactive Streams Publisher, not only Mono. Code referencing the class by name (a custom ReturnValueHandler composed alongside it, say) needs the new name. A Publisher that emits more than one value now fails the call, where it previously wasn’t a supported return type at all.
• PromptContext and SyncPromptContext gain abstract methods: isCancelled() on both, onCancel(Runnable) on SyncPromptContext, whenCancelled() on PromptContext. A custom implementation of either interface, typically a test double, must implement the new methods.
• AcpAgentSupport.Builder.buildFactory() now throws if transport(...) was also set (a listener supplies its own transport per connection, so the two are mutually exclusive), and both build() and buildFactory() throw IllegalStateException if no agent bean was given at all. Previously these cases either weren’t checked or failed less clearly downstream.

​

Client initialize(InitializeRequest) is removed

• AcpClient.async(...) / AcpClient.sync(...): .clientCapabilities(ClientCapabilities) (as before) and the new .clientInfo(Implementation).
• initialize() sends protocol version 1 with the builder’s capabilities and client info.
• initialize(int protocolVersion, Map<String, Object> meta) (new) sends a chosen protocol version and _meta with the same builder values; for _meta and version-negotiation tests, not for capabilities.

// Before (removed)
AcpSyncClient client = AcpClient.sync(transport).build();
client.initialize(new InitializeRequest(1, myCapabilities));

// After
AcpSyncClient client = AcpClient.sync(transport)
    .clientCapabilities(myCapabilities)
    .build();
client.initialize();

​

Session-update short constructors drop the discriminator

​

Error codes now follow the ACP v1 schema

​

Elicitation is stable

• The elicitation capability’s modes are typed, and the no-argument ElicitationCapabilities() constructor is removed. form and url were Object; they are now ElicitationFormCapabilities and ElicitationUrlCapabilities. Migration: new ElicitationCapabilities() becomes ElicitationCapabilities.formOnly(); urlOnly() and formAndUrl() advertise the other modes.
• ElicitationAction is an open value, not an enum (see the next section): compare with equals, not ==; replace a switch with if/else or a switch over action().value().
• StringPropertySchema and MultiSelectPropertySchema have only their canonical constructors, which end with _meta. Migration: pass null as the last argument, or use StringPropertySchema.text(...) and singleSelect(...).

​

Open value types replace six enums

​

Constructor signatures changed

• NewSessionResponse, LoadSessionResponse, ResumeSessionResponse take configOptions before _meta. new NewSessionResponse(id, modes, null) and new LoadSessionResponse(modes, null) still compile (the null is now the config options), but a call that passed a _meta map in that position no longer compiles. Migration: pass (id, modes, configOptions, meta) or (modes, configOptions, meta).
• ToolCall, ToolCallUpdate, ToolCallUpdateNotification take name after title. Migration: insert the tool’s name, or null, after the title argument.
• AuthMethod is an interface; construct AuthMethodAgent. The schema makes AuthMethod a union. Migration: new AuthMethod(id, name, description) becomes new AcpSchema.AuthMethodAgent(id, name, description); id(), name(), and description() stay on the interface.
• ClientCapabilities takes session and auth after terminal, in schema order. Migration: new ClientCapabilities(fs, terminal, elicitation, meta) becomes new ClientCapabilities(fs, terminal, session, auth, elicitation, meta) (both may be null).
• AgentCapabilities takes auth after promptCapabilities. Migration: new AgentCapabilities(loadSession, session, mcp, prompt, providers, meta) becomes new AgentCapabilities(loadSession, session, mcp, prompt, auth, providers, meta) (auth may be null).
• Union records write their own discriminator and reject a wrong one. A canonical constructor now turns null into the record’s own wire name and throws IllegalArgumentException for any other value (new AgentMessageChunk("agentMessage", ...) used to be silently corrected). Migration: pass the variant’s wire name (e.g. "agent_message_chunk") or null, or use the convenience constructors, which already do this. An exhaustive switch over a union’s known records needs a branch for its new Unknown* record (below).
• _meta was added to 48 records; old-signature constructors are kept except where noted above.

​

Session config options: flat or grouped

​

Forward compatibility: unknown variants no longer fail the message

​

session/cancel no longer ends the prompt turn

​

$/cancel_request, both directions

​

Lifecycle renames, sync exceptions and timeouts

​

Lifecycle names line up, and both sync facades close gracefully

• AcpSyncAgent.await() is renamed awaitTermination(), matching AcpAsyncAgent and the transports. Migration: rename the call.
• AcpSyncAgent and AcpAgentSupport implement AutoCloseable, and close() now means what it means on AcpSyncClient: close gracefully, waiting at most 10 seconds, then close at once if that failed or took longer (AcpSyncAgent.close() used to close at once; AcpAgentSupport.close() used to wait up to the 5-minute block timeout and never force). For the old immediate close, call agent.async().close(). New AcpSyncClient.async() returns the AcpAsyncClient it blocks on. Migration: use try-with-resources on the sync agent and the annotated agent, the same pattern already shown for AcpSyncClient.
• StdioAcpClientTransport.awaitForExit() is renamed awaitProcessExit(), so it doesn’t sit beside awaitTermination() (which completes when the transport ends, not the process). Interrupted, it now throws CancellationException (interrupt flag kept) instead of a plain RuntimeException (interrupt flag cleared). Migration: rename the call; catch CancellationException instead.

​

The sync API’s exceptions change shape

​

A client’s prompt is no longer bounded by the request timeout

​

sendSessionUpdate drops the session ID

​

Builders reject a null handler and a duplicate registration

​

handlerExecutor replaces the static handler pools; two public constants are gone

​

askPermission/askChoice now announce a tool call

​

One error type and stricter client builders

​

A caller catches one type, AcpError, for every failed request

​

A client initializes first, and calls only what the agent advertised

​

A client’s advertised capabilities must have their handlers

​

Client builders reject a null, duplicate, or misdirected handler too

​

SessionConfigSelect.Builder.build() checks the option’s value

​

Two new conveniences

• One default request timeout, 60 seconds, everywhere. The client builders (AcpClient.sync/async) and AcpAgentSupport.Builder defaulted to 30 seconds while the agent builders defaulted to 60; all four now default to 60. 60 seconds because an agent’s own requests (a permission prompt, an elicitation) wait on a person, and a client’s session/new may wait for the agent to start its MCP servers. AcpAgentSupport.Builder.requestTimeout now accepts null, meaning the SDK default. The Spring Boot (spring.acp.client.request-timeout) and Micronaut (acp.client.request-timeout) properties default to 60s too; Quarkus’s quarkus.acp.client.request-timeout, left unset, already followed the SDK default either way. Migration: none needed; to keep the old 30-second client bound, set requestTimeout(Duration.ofSeconds(30)) (or the property to 30s).
• defaultSessionUpdateHandler(..) on AcpClient.AsyncSpec/SyncSpec: a handler that runs only while no sessionUpdateHandler has been added, so a framework can supply a default (logging each update at DEBUG, say) that the application’s own handler replaces outright rather than running beside. The Spring Boot, Micronaut, and Quarkus client beans now register their DEBUG logging this way. sessionUpdateHandler itself stays additive, as before. (Named defaultSessionUpdateConsumer and sessionUpdateConsumer before the rename below.)
• Shortcuts for the messages real code writes most: new NewSessionRequest(cwd) (no MCP servers), new NewSessionResponse(sessionId) (no modes or config options), and PromptRequest.text(sessionId, text) (a prompt of one text block). Each equals, and writes the same JSON as, the long form; prefer them in new code wherever the full form adds nothing.

​

acp-integration: a shared layer under all three framework integrations, and what moves because of it

​

AcpClientCustomizer and the transport-type enum move

​

Spring Boot: several property changes

• spring.acp.agent.request-timeout and spring.acp.client.request-timeout have no default of their own (an earlier candidate’s 60s row in each properties table was the SDK’s default showing through, not Spring’s own): unset, both keep following the SDK’s one default request timeout, so a future SDK default change would reach these properties automatically.
• Several client transports configured with no explicit transport.type now fail at startup, naming them: "Several ACP client transports are configured [...]; choose one with spring.acp.client.transport.type." The stdio/websocket/http precedence order it used to pick silently is gone.
• The listener-only agent properties move: spring.acp.agent.transport.http.port becomes spring.acp.agent.transport.http.listener.port, and ...http.max-concurrent-streams-per-connection becomes ...http.listener.max-concurrent-streams-per-connection. They meant nothing in a servlet web application (which serves the endpoint on its own server and server.port) even before this move; now they’re grouped under a prefix that makes that explicit.
• spring.acp.agent.transport.type=websocket is accepted, meaning the same as http: the endpoint takes WebSocket upgrades on its path either way.
• New properties: spring.acp.client.capabilities.elicitation-form, .elicitation-url and .boolean-config-options (the last needs no handler, unlike the others); spring.acp.agent.cancel-grace-period and spring.acp.agent.max-prompt-duration; and spring.acp.agent.handler-executor, see below.
• ArgumentResolver and ReturnValueHandler beans are now added to the agent, the same as AcpInterceptor beans already were: register one as a plain @Bean and it’s picked up automatically, in bean order, with no further wiring.
• The agent’s handler methods can run on a Spring executor. spring.acp.agent.handler-executor names an Executor bean (a plain TaskExecutor is adapted), or none for the SDK’s own pool. Unset, they run on the context’s applicationTaskExecutor only when spring.threads.virtual.enabled=true (a virtual thread per handler); without virtual threads that executor is a pool of 8 threads by default, which would cap the prompts served at once, so the SDK’s own pool stays the default instead. See Spring Boot: Where handlers run.
• Closing the client waits at most its request timeout plus 10 seconds, then closes it at once, bounded rather than left to whatever Spring’s own shutdown ordering happened to do.
• Everything else in this release’s breaking changes still applies: Spring applications compile against the SDK’s current API, same as any other consumer.

​

Micronaut: handler methods run on virtual threads on JDK 21+

​

Quarkus: the same transport strictness, and handlers on the ManagedExecutor

​

Errors, interceptors and build-time checks

​

Errors: a security fix, a new exception, and a hierarchy change

• A handler’s unexpected exception no longer sends its message to the peer. Any exception other than AcpProtocolException escaping a handler used to answer -32603 with that exception’s own message, which can carry paths, SQL, or credentials; it’s now answered -32603 with the generic message "Internal error" on both sides, and the real exception is logged at WARN with its stack trace on the side that handled it. An AcpError that escapes a handler is the one exception besides AcpProtocolException with its own, unchanged treatment: it’s passed on as the answer, not flattened to -32603, since it’s already the peer’s own failure moving one hop further. Migration: a handler whose exception message the peer needs throws AcpProtocolException with that message explicitly.
• AcpError now extends AcpException. A multi-catch catch (AcpException | AcpError e) no longer compiles; catch AcpException alone, and if AcpError needs its own clause, put it before the AcpException one. Migration: fix the multi-catch, and check the order of any adjacent AcpError/AcpException catch blocks.
• A lost connection fails a request with AcpConnectionException, on both sides, replacing a plain RuntimeException (a request pending when the transport ended) and an IllegalStateException (sent after that, or after close()). Migration: replace catch (RuntimeException e) or catch (IllegalStateException e) used to mean “the connection is gone” with catch (AcpConnectionException e).
• AcpCapabilityException.toProtocolException() is removed. It answered -32600, a code the SDK made up for the case; the one refusal ACP actually specifies (an elicitation mode the client never declared) already answers -32602 directly, without this method. Migration: a handler converting its own capability check to an error throws new AcpProtocolException(AcpErrorCodes.INVALID_PARAMS, e.getMessage(), e.getCapability()).

​

Interceptors

• AcpInterceptor.onError can answer with an error of its own, and now reaches only the interceptors whose preInvoke actually ran. An AcpProtocolException thrown from onError becomes the response, with the original failure attached as suppressed; any other exception there is a fault in the interceptor and is answered -32603. Migration: an onError that threw expecting to be ignored should log and return null instead.
• Breaking: afterCompletion takes the exception the call failed with, as a second parameter: afterCompletion(AcpInvocationContext context, Throwable ex), ex null on success. An override without @Override keeps compiling against the old one-argument signature but is silently never called again; add @Override to catch this at compile time, and add the parameter.
• The default session/new answer now passes through the interceptors too. An annotated agent with no @NewSession method used to answer session/new without going through preInvoke/ postInvoke/onError/afterCompletion, unlike every other derived answer. Migration: an interceptor that should ignore session/new checks context.getAcpMethod().

​

Rejected at build or setter, instead of failing later or silently

• An @ExtNotification method that doesn’t return void fails the build, naming the method: a notification gets no answer, so a returned value was silently dropped before.
• AcpAgentSupport.Builder.cancelGracePeriod(..) and maxPromptDuration(..) reject a negative value at once, instead of storing it and failing later at build() (or, with buildFactory(), failing every connection).
• AcpAgentSupport.Builder.interceptor(null) fails at once with IllegalArgumentException, as argumentResolver(null) and returnValueHandler(null) already did.

​

additionalDirectories needs the capability, both ways

​

Two more fixes worth knowing about

• A prompt’s updates no longer follow its answer. Once a prompt has been answered, by its handler or by the SDK itself (the cancel grace period or maxPromptDuration passed), sendUpdate (and the helpers built on it, such as sendMessage) now drops anything sent afterward and logs it at DEBUG, without its content, instead of sending an update after the answer, which ACP forbids. sendSessionUpdate outside a prompt context is unaffected.
• SessionCapabilities writes only objects, and reads only objects as advertised. Boolean.TRUE used to write "list": true, which the schema forbids (a session capability is an object or absent); it now writes {}. Reading used to count any non-null value, including false, as advertised; only a JSON object does now. Migration: none for code using the builder or the supportsX() accessors; code that read the raw JSON by hand should expect {}, not true.
• A builder agent advertises providers for any provider handler, not only providers/list: an annotated agent already did; a plain builder agent with only a providers/set or /disable handler used to advertise nothing, so the client refused those calls.

​

Micronaut: the three capability properties it was missing now exist

​

Cancellation no longer needs an explicit answer

• A prompt answers cancelled once session/cancel was received, whatever the handler returns or throws. Before, a handler that returned another stop reason within the grace period (or just let PromptResponse.endTurn() fall through) had that answer sent instead, and a handler that failed after a cancel was answered -32603, not cancelled. The agent session now sends cancelled regardless, keeping the handler’s _meta when it did return a response; before a cancel, failures are still answered as before (only a cancellation, or an AcpProtocolException the handler threw itself, gets special treatment there). Migration: none needed to keep working; a try/catch written solely to turn a post-cancel failure into cancelled, or an explicit check-and-return of StopReason.CANCELLED for the same reason, is now redundant rather than required. See Cancellation for the full behavior.
• Builder agents answer session/new without a registered handler. build() used to answer -32601 without a newSessionHandler, so no client could open a session; it now answers with AcpSchema.NewSessionResponse.withGeneratedId() (a random UUID, no modes or config options), the same default an annotated agent without @NewSession already had. build() still requires a prompt handler; that remains the one ACP method with no default. Migration: none needed; a newSessionHandler registered explicitly still replaces the default.
• The agent checks the client’s terminal capability for every terminal method, not only create. terminal/output, terminal/wait_for_exit, terminal/kill and terminal/release used to be sent regardless of whether the client advertised terminal, for example with a terminal ID from a different connection. All five now fail locally with AcpCapabilityException and send nothing, from the agent and from a prompt context’s execute(...). Migration: none for a client that already advertises terminal consistently; code that relied on these four methods reaching the wire without the capability advertised needs to register the capability instead.

​

Client cancellation, agent-aware handlers, context.client() and capability builders

​

Client-side prompt cancellation: prompt(request, CancellationSignal)

​

Builder handlers receive their agent

​

The prompt context is split into its two layers: context.client()

​

One vocabulary for session updates

​

Client builders derive the advertised capabilities from the handlers

​

Capability builders that lead to each choice

​

One framework-neutral ACP endpoint, and Spring MVC serving WebSocket too

​

Quarkus serves ACP on a Vert.x route, without a servlet

​

Spring Boot serves ACP in a reactive (WebFlux) web application too

​

Smaller breaking changes

• AgentParameters.Builder.inheritEnvironment(boolean): a stdio agent’s process inherits the whole client environment by default (unchanged; now documented as the explicit default rather than an accident of the old implementation), and inheritEnvironment(false) starts it from an empty environment plus only the safe defaults and whatever addEnvVar(...) adds, for a client that shouldn’t hand every secret in its own environment to an agent subprocess.
• Mapper-less transport constructors: StreamableHttpAcpClientTransport(URI), WebSocketAcpClientTransport(URI), StreamableHttpAcpAgentTransport(int port, AcpAgentFactory), and StreamableHttpAcpServlet(AcpAgentFactory) all default to AcpJsonMapper.createDefault(), as the stdio transports already did.

​

Fixes worth knowing about, even though nothing to migrate

• A handler that threw an Error used to leave the peer waiting forever. Any Throwable escaping a request handler (sync or async, agent or client, annotation-based included) now answers -32603 (Internal error) instead, and the connection keeps serving. This matters directly for the 0.18.0-to-0.80.0 upgrade itself: a handler calling a removed 0.18.0 constructor throws NoSuchMethodError at runtime, and before this fix that hung the caller instead of failing fast.
• AcpAgentSupport.Builder can now be built more than once. Previously, build() appended custom resolvers/handlers to the builder’s own lists, so a second build() duplicated them, a custom entry added after the first build() call never ran, and agents already built silently shared (and saw later changes to) the builder’s lists. build() now snapshots a composed configuration without mutating the builder, enabling AcpAgentSupport.Builder.buildFactory() (an AcpAgentFactory that creates a fresh agent per connection from one shared, thread-safe handler bean), a new-feature page held until the architecture brief is approved, but the underlying bug fix applies now to anyone who builds an AcpAgentSupport agent more than once.
• A client’s prompt() now returns only after every earlier notification on that connection has been handled. Before, a response could complete its caller while the session-update consumer was still processing the turn’s last updates, so a caller that read what it had collected right after prompt() returned could silently miss some. Code that slept, polled, or otherwise waited for “trailing” updates after prompt() returns can drop that workaround; the guarantee is now built in. A slow consumer delays the response and still counts against the request timeout, so a consumer that sends its own request and waits for it cannot deadlock against a prompt in flight, but must not itself wait for that prompt to complete.
• The stdio client’s graceful close lets the agent exit on its own, instead of always killing it. closeGracefully() used to send SIGTERM immediately, without closing the agent’s standard input, so an SDK stdio agent’s own end-of-input handling never ran and every close ended in exit code 143. It now closes the agent’s standard input first and waits up to two seconds for the agent to exit by itself; only an agent still running after that is sent SIGTERM. Code that checked for exit code 143 as the normal/expected close outcome should check for exit 0 instead. Closing twice (for example closeGracefully() followed by try-with-resources close()) no longer stops the process or logs the stop message a second time.
• A response missing a required field now fails the request instead of silently passing nulls through. A bare {} used to read as, say, a PromptResponse with a null stopReason or a NewSessionResponse with a null sessionId; only inbound params were checked for required fields before. Results are checked the same way now, on both sides and down into nested records: the caller’s request fails with AcpError (-32603), data {"reason": "missing-required-field", "method": <method>, "field": <path>}, the path naming a nested field, such as modes.currentModeId, not just its containing object. See Errors for this and the other reasons an AcpError can mean the SDK rejected the response itself rather than the peer sending an error. Code that tolerated a peer answering less than the schema requires, intentionally or not, now sees that as a hard failure.
• An agent-to-client request reaches its handler only after the session updates sent before it. Requests used to be dispatched as they arrived, outside the ordered notification drain, so a session/request_permission could reach its handler before the client’s session-update consumers had processed the tool_call update the agent sent just before it, leaving the tool call impossible to look up. A request now takes its place in the same drain as a response: dispatched once every notification before it has been handled (handlers still run concurrently with each other and with later updates; a request already being handled when a response comes in isn’t held up behind it, to avoid deadlocking a consumer that’s waiting on its own request). See Concepts: the ordering guarantee, now extended to cover this case too.
• execute releases its terminal when the prompt is cancelled. ACP requires an agent to release every terminal it creates. execute already released it when the command ended or a step failed, but not when the prompt was cancelled (the session/cancel grace period, maxPromptDuration, or $/cancel_request) while waiting in terminal/wait_for_exit, leaving the client holding a terminal the agent would never ask about again. It now sends terminal/release exactly once on every path.
• At INFO and above, the SDK logs no message content. Three gaps closed: a malformed message that failed validation used to be quoted in full by the exception every transport logs; the WebSocket client used to log its endpoint’s full URI, query string and user information included; and a peer’s error answer used to log its message and data at WARN. All three now log only what identifies the problem (the field at fault; scheme, host, port and path; the error code and the SDK’s description of it), with the peer’s own text, where it’s logged at all, at DEBUG. See Transports: Logging and sensitive data.
• A WebSocket that never sends initialize is now closed after 30 seconds (1008). Nothing enforced this before; the only thing that eventually caught a silent connection was the (also new) idle timeout. A POST initialize the agent hasn’t answered within the same window now gets 500 too, replacing what used to be a fixed, unconfigurable 30 seconds.

​

What you may have to change: a quick checklist

1. Recompile. This is not a drop-in jar swap.
2. Grep for session/set_model, SetSessionModel, SessionModelState, replacing with a "model" category config option.
3. Grep for acp-websocket-jetty, WebSocketAcpAgentTransport, switching to acp-streamable-http-jetty and StreamableHttpAcpAgentTransport.
4. Grep for == comparisons against StopReason, ToolCallStatus, Role, PermissionOptionKind, PlanEntryStatus, PlanEntryPriority, or ElicitationAction constants, switching to .equals(...).
5. Grep for exhaustive switch statements over any of the above, or over a union type (SessionUpdate, ContentBlock, ToolCallContent, SessionConfigOption, PermissionOutcome), adding the new Unknown* branch, or the open-value fallback.
6. Check any code that sends a second prompt immediately after session/cancel: it now needs to wait for the cancelled prompt’s answer.
7. Check any test or display code that asserts an exact status string: it now sees the wire value (end_turn), not the enum name (END_TURN).
8. Grep for @SessionState and @AcpExceptionHandler: both are removed (they were non-functional placeholders). Move session state into the agent itself; handle exceptions in the handler or an AcpInterceptor.
9. Grep for initialize(new InitializeRequest(: move capabilities to .clientCapabilities(...) on the client builder and call initialize() instead.
10. Grep for discriminator-first short constructors of Plan, AvailableCommandsUpdate, CurrentModeUpdate, UsageUpdate, ConfigOptionUpdate, UserMessageChunk, AgentMessageChunk, and AgentThoughtChunk (e.g. new Plan("plan", ...)): drop the first argument.
11. If any code constructs StreamableHttpAcpAgentTransportOptions via its canonical constructor (not the builder), add the new shutdownTimeout component.
12. If any SyncPromptContext is implemented directly (a test double, typically), implement the new abstract async() method.
13. If you use Spring Boot support, change org.springaicommunity:acp-spring-boot-starter/ acp-spring-boot-autoconfigure to com.agentclientprotocol, update the version to 0.80.0, and fix any import of com.agentclientprotocol.autoconfigure.* to com.agentclientprotocol.sdk.spring.boot.autoconfigure.*. Property names are unchanged.
14. If any annotated agent has @SetSessionMode/@SetSessionConfigOption without @NewSession, add one; building now fails without it.
15. If any custom ReturnValueHandler composition references MonoHandler by name, update it to AsyncValueHandler.
16. If any custom PromptContext/SyncPromptContext implementation exists (typically a test double), implement the new isCancelled()/onCancel(Runnable)/whenCancelled() methods.
17. If an @Initialize method’s response was relied on to suppress a capability a handler would otherwise imply, remove or conditionally register the handler instead: capabilities now merge by OR, so a handler’s presence always advertises.
18. Grep for agent.await() (rename to agent.awaitTermination()) and awaitForExit() (rename to awaitProcessExit(), and catch CancellationException instead of RuntimeException around it).
19. Grep for context.sendUpdate(sessionId, on a PromptContext/SyncPromptContext; drop the first argument and rename to sendSessionUpdate, so it becomes context.sendSessionUpdate(update). Leave agent.sendSessionUpdate(sessionId, ...) alone, it already took the session id and is unaffected.
20. Grep for .sessionUpdateConsumer(/.defaultSessionUpdateConsumer( on AcpClient.AsyncSpec/ SyncSpec; rename to .sessionUpdateHandler(/.defaultSessionUpdateHandler(. Behavior is unchanged.
21. Grep for raw context.readTextFile(/.writeTextFile(/.requestPermission(/.createTerminal(/ .getTerminalOutput(/.releaseTerminal(/.waitForTerminalExit(/.killTerminal(/ .createElicitation(/.completeElicitation( on a PromptContext/SyncPromptContext; insert .client() before each: context.client().readTextFile(...). Leave the convenience methods (readFile, tryReadFile, writeFile, askPermission, askChoice, execute) and any call on AcpAsyncAgent/AcpSyncAgent directly alone, neither moved.
22. Grep for .contextWrite(RequestCancellation.cancelWhen( around a client.prompt(request) call: replace with the two-argument prompt(request, signal) and call signal.cancel() instead. See Cancellation.
23. If a builder handler reads the built agent from an AtomicReference (a session/load replay, or sending a ConfigOptionUpdate from setSessionConfigOptionHandler), take the agent as the handler’s second parameter instead and drop the AtomicReference.
24. If using Micronaut, grep for acp.agent.transport.http.host, .port, or .max-concurrent-streams-per-connection: all three move under ...http.listener.*.
25. If a client registers readTextFileHandler, writeTextFileHandler, all five terminal handlers, or createElicitationHandler and also sets clientCapabilities(..) purely to advertise that same shape, the explicit call can be dropped; the matching capability is now derived from the handlers automatically. Keep it if the client registers handlers on purpose without advertising them, by passing clientCapabilities(new ClientCapabilities()).
26. Where it covers the shape needed, prefer the one-flag capability builders (ClientCapabilities.builder().readTextFile().writeTextFile(), AgentCapabilities.builder().loadSession()) over the record’s canonical constructor or the builder setters that take a nested record directly; both still work.
27. Grep for catch (RuntimeException (or Exceptions.unwrap) around a blocking SDK call checking for a TimeoutException cause; replace with catch (AcpTimeoutException e).
28. Grep for AcpAgent.SYNC_HANDLER_SCHEDULER, AcpClient.SYNC_HANDLER_SCHEDULER, and AcpAgent.DEFAULT_REQUEST_TIMEOUT; the first two have no replacement constant (use handlerExecutor(...) if you need a specific executor), the third becomes Duration.ofSeconds(60).
29. If any code relied on a long-running prompt being cut off by the client’s request timeout, set .promptTimeout(...) explicitly; the default is now unbounded.
30. If any code constructs CommandResult via its canonical constructor (not the 3-argument convenience one), add the new truncated component.
31. Grep for catch (AcpProtocolException around a client or agent call (not inside a handler, where throwing it is still correct): replace with catch (AcpError e).
32. Grep for client. calls made before client.initialize(): every call but initialize itself now fails locally with IllegalStateException until it has answered.
33. If a client advertises fs.readTextFile, fs.writeTextFile, terminal, or an elicitation mode, confirm the matching handler is registered; build() now fails without it.
34. Grep for a raw requestHandler/notificationHandler registered for a method the SDK models (fs/read_text_file, a terminal/* method, session/request_permission, elicitation/create, session/update, elicitation/complete): switch to the named typed setter.
35. If a SyncSpec.notificationHandler is registered, drop the Mono from its body; it’s now a blocking Consumer<Object>.
36. If any code relied on the client’s 30-second default request timeout specifically (for example, a test asserting how long a stub takes to time out), it’s now 60 seconds; set requestTimeout(...) explicitly if the old number matters.
37. If a SessionConfigSelect.Builder is ever built with no options, or a currentValue not among them, fix the options before build(); it now throws instead of building.
38. If a test specifically checked MockAcpClient’s initialize() response for a terminal capability, update it: the mock no longer advertises terminal.
39. Grep for import com.agentclientprotocol.sdk.spring.boot.autoconfigure.client.AcpClientCustomizer (or the equivalent Micronaut/Quarkus package) and TransportType: both now come from com.agentclientprotocol.sdk.integration.
40. If using Spring Boot, grep for spring.acp.agent.transport.http.port and ...max-concurrent-streams-per-connection: both move under ...http.listener.*.
41. If using Spring Boot, set spring.acp.client.transport.type/spring.acp.agent.transport.type explicitly wherever more than one transport property is set; it now fails at startup instead of picking one silently. Quarkus and Micronaut clients need the same check.
42. If a Spring ArgumentResolver or ReturnValueHandler was registered by hand (not as a @Bean), register it as one instead; it’s now picked up automatically, the same as AcpInterceptor.
43. Grep for catch (AcpException | AcpError (or any other multi-catch listing both): drop AcpError and catch AcpException alone; check the order of any adjacent catch (AcpError e) / catch (AcpException e) blocks, AcpError first.
44. Grep for catch (RuntimeException or catch (IllegalStateException around a call, used to mean “the connection is gone”: replace with catch (AcpConnectionException e).
45. Grep for .toProtocolException() on an AcpCapabilityException: replace with new AcpProtocolException(AcpErrorCodes.INVALID_PARAMS, e.getMessage(), e.getCapability()).
46. If any AcpInterceptor.afterCompletion override exists, add the Throwable parameter and @Override; without @Override it silently stops being called.
47. If any handler relied on its own exception’s message reaching the peer (other than through AcpProtocolException), throw AcpProtocolException with that message explicitly; the message is no longer sent otherwise.
48. If a client sends additionalDirectories, check getAgentCapabilities().supportsAdditionalDirectories() first, or catch AcpCapabilityException; if an annotated agent reads them, add additionalDirectories = true to @AcpAgent.
49. If a Micronaut client worked around missing elicitation-form/elicitation-url/ boolean-config-options properties with a customizer override, the properties now exist; the workaround can be dropped.
50. If a @Prompt method (or prompt handler) has a try/catch whose only job is answering cancelled after session/cancel, it can be dropped; the agent session does this regardless of what the handler returns or throws.
51. If a builder agent relies on build() failing without a newSessionHandler, note that it now answers session/new with a generated id by default instead.
52. If any agent code calls terminal/output, wait_for_exit, kill, or release on a connection where the client might not advertise terminal, expect AcpCapabilityException now, not a sent request; these four now check the same as create already did.
53. If an application mounts StreamableHttpAcpServlet in its own servlet container (Spring MVC included), switch its dependency from acp-streamable-http-jetty to acp-http-servlet. As of 0380b28, using the former on Tomcat fails fast at startup, naming the fix, rather than starting cleanly and failing every WebSocket send with NoSuchMethodError later; on Jetty or Undertow as the servlet container, the startup check doesn’t run at all, so the failure stays silent until a WebSocket send.
54. If any StreamableHttpAcpServlet subclass overrides doGet, doPost, or doDelete, note that service now handles every request itself; wrap an AcpHttpEndpoint instead to customize behavior.
55. If a client treats WebSocket close code 1000 as meaning “the server is shutting down,” treat 1001 (going away) the same way instead.
56. If a Spring MVC application’s own client connected with transport.websocket.uri and relied on it failing against the servlet-mounted agent, note that it now succeeds: the servlet serves WebSocket too, as of this release.
57. If a Quarkus application relied on acp-quarkus to pull in quarkus-undertow transitively, add that dependency directly.
58. If a Quarkus application’s path assumed quarkus.servlet.context-path, use quarkus.http.root-path instead.
59. If a Quarkus application’s own client (or test) connected to /acp over WebSocket without authenticating and expected it to succeed on a path quarkus.http.auth.permission protects, expect 401 now instead of a successful upgrade.
60. If a Spring Boot reactive (WebFlux) application serves ACP, add com.agentclientprotocol:acp-http-webflux; without it, the startup fails naming it instead of saying WebFlux isn’t supported.
61. If any test or workaround relied on spring.acp.agent.transport.type=http failing the startup in a WebFlux application with “WebFlux is not supported,” drop it: that failure is gone, replaced by the endpoint actually serving the agent (given the new module above).
62. If a WebSocket client (or a test) saw close code 1006 instead of 1001 from a Jetty-hosted agent’s graceful shutdown (the standalone listener, or a servlet on Jetty), that was the bug: it reliably gets 1001 now.
63. If a custom host of AcpHttpEndpoint implements AcpWsOutbound, update close to return CompletionStage<Void> instead of void, completing once the close frame has gone out or the socket has closed.