Add PromptContext for prompt handlers and fix sync API parity

- Add PromptContext interface providing all agent capabilities to prompt handlers
- Add SyncPromptContext for blocking prompt handlers
- Add DefaultPromptContext and DefaultSyncPromptContext implementations
- Update handler signatures to use PromptContext instead of SessionUpdateSender
- Remove deprecated SessionUpdateSender and SyncSessionUpdateSender interfaces
- Add getClientCapabilities() to AcpSyncAgent
- Add getAgentCapabilities() to AcpSyncClient
- Add unit tests for sync capability accessor methods

This follows the MCP SDK's Exchange pattern where handlers receive
a context object with all necessary capabilities.

Author: Mark Pollack

acp-core/src/main/java/com/agentclientprotocol/sdk/agent/AcpAgent.java

@@ -170,33 +170,38 @@ interface LoadSessionHandler {
 	}
 
 	/**
-	 * Interface for sending session updates during prompt processing.
-	 */
-	interface SessionUpdateSender {
-
-		/**
-		 * Sends a session update notification to the client.
-		 * @param sessionId The session ID
-		 * @param update The session update to send
-		 * @return A Mono that completes when the notification is sent
-		 */
-		Mono<Void> sendUpdate(String sessionId, AcpSchema.SessionUpdate update);
-
-	}
-
-	/**
-	 * Functional interface for handling prompt requests with streaming updates.
+	 * Functional interface for handling prompt requests with full agent context.
+	 *
+	 * <p>
+	 * The handler receives a {@link PromptContext} that provides access to all agent
+	 * capabilities including file operations, permission requests, terminal operations,
+	 * and session updates.
+	 *
+	 * <p>Example usage:
+	 * <pre>{@code
+	 * AcpAgent.async(transport)
+	 *     .promptHandler((request, context) -> {
+	 *         // Read a file
+	 *         var file = context.readTextFile(new ReadTextFileRequest(...)).block();
+	 *
+	 *         // Send progress update
+	 *         context.sendUpdate(sessionId, new AgentThoughtChunk(...));
+	 *
+	 *         return Mono.just(new PromptResponse(StopReason.END_TURN));
+	 *     })
+	 *     .build();
+	 * }</pre>
 	 */
 	@FunctionalInterface
 	interface PromptHandler {
 
 		/**
-		 * Handles a prompt request, optionally sending session updates during processing.
+		 * Handles a prompt request with full access to agent capabilities.
 		 * @param request The prompt request
-		 * @param updater Interface for sending session updates
+		 * @param context Context providing all agent capabilities (file ops, permissions, updates, etc.)
 		 * @return A Mono containing the prompt response
 		 */
-		Mono<AcpSchema.PromptResponse> handle(AcpSchema.PromptRequest request, SessionUpdateSender updater);
+		Mono<AcpSchema.PromptResponse> handle(AcpSchema.PromptRequest request, PromptContext context);
 
 	}
 
@@ -279,34 +284,38 @@ interface SyncLoadSessionHandler {
 	}
 
 	/**
-	 * Synchronous interface for sending session updates during prompt processing.
-	 * Blocks until the update is sent, returns void.
-	 */
-	interface SyncSessionUpdateSender {
-
-		/**
-		 * Sends a session update notification to the client. Blocks until sent.
-		 * @param sessionId The session ID
-		 * @param update The session update to send
-		 */
-		void sendUpdate(String sessionId, AcpSchema.SessionUpdate update);
-
-	}
-
-	/**
-	 * Synchronous functional interface for handling prompt requests with streaming updates.
-	 * Returns a plain value instead of Mono for use with sync agents.
+	 * Synchronous functional interface for handling prompt requests with full agent context.
+	 *
+	 * <p>
+	 * The handler receives a {@link SyncPromptContext} that provides blocking access to all
+	 * agent capabilities including file operations, permission requests, terminal operations,
+	 * and session updates.
+	 *
+	 * <p>Example usage:
+	 * <pre>{@code
+	 * AcpAgent.sync(transport)
+	 *     .promptHandler((request, context) -> {
+	 *         // Read a file (blocks)
+	 *         var file = context.readTextFile(new ReadTextFileRequest(...));
+	 *
+	 *         // Send progress update (blocks)
+	 *         context.sendUpdate(sessionId, new AgentThoughtChunk(...));
+	 *
+	 *         return new PromptResponse(StopReason.END_TURN);
+	 *     })
+	 *     .build();
+	 * }</pre>
 	 */
 	@FunctionalInterface
 	interface SyncPromptHandler {
 
 		/**
-		 * Handles a prompt request, optionally sending session updates during processing.
+		 * Handles a prompt request with full access to agent capabilities.
 		 * @param request The prompt request
-		 * @param updater Interface for sending session updates (blocking)
+		 * @param context Context providing blocking access to all agent capabilities
 		 * @return The prompt response
 		 */
-		AcpSchema.PromptResponse handle(AcpSchema.PromptRequest request, SyncSessionUpdateSender updater);
+		AcpSchema.PromptResponse handle(AcpSchema.PromptRequest request, SyncPromptContext context);
 
 	}
 
@@ -557,7 +566,7 @@ public SyncAgentBuilder loadSessionHandler(SyncLoadSessionHandler handler) {
 
 		/**
 		 * Sets the synchronous handler for prompt requests.
-		 * @param handler The sync prompt handler (returns plain value, uses SyncSessionUpdateSender)
+		 * @param handler The sync prompt handler (returns plain value, receives SyncPromptContext)
 		 * @return This builder for chaining
 		 */
 		public SyncAgentBuilder promptHandler(SyncPromptHandler handler) {
@@ -644,11 +653,10 @@ private static PromptHandler fromSync(SyncPromptHandler syncHandler) {
 			if (syncHandler == null) {
 				return null;
 			}
-			return (request, asyncUpdater) -> Mono.fromCallable(() -> {
-				// Create a blocking wrapper around the async SessionUpdateSender
-				SyncSessionUpdateSender syncUpdater = (sessionId, update) -> asyncUpdater.sendUpdate(sessionId, update)
-					.block();
-				return syncHandler.handle(request, syncUpdater);
+			return (request, asyncContext) -> Mono.fromCallable(() -> {
+				// Create a blocking wrapper around the async PromptContext
+				SyncPromptContext syncContext = new DefaultSyncPromptContext(asyncContext);
+				return syncHandler.handle(request, syncContext);
 			}).subscribeOn(SYNC_HANDLER_SCHEDULER);
 		}
 

acp-core/src/main/java/com/agentclientprotocol/sdk/agent/AcpSyncAgent.java

@@ -170,6 +170,20 @@ public AcpSchema.KillTerminalCommandResponse killTerminal(AcpSchema.KillTerminal
 		return asyncAgent.killTerminal(request).block(blockTimeout);
 	}
 
+	/**
+	 * Returns the capabilities negotiated with the client during initialization.
+	 *
+	 * <p>
+	 * This method returns null if initialization has not been completed yet.
+	 * Use this to check what features the client supports before calling
+	 * methods like {@link #readTextFile} or {@link #createTerminal}.
+	 * </p>
+	 * @return the negotiated client capabilities, or null if not initialized
+	 */
+	public com.agentclientprotocol.sdk.capabilities.NegotiatedCapabilities getClientCapabilities() {
+		return asyncAgent.getClientCapabilities();
+	}
+
 	/**
 	 * Returns the underlying async agent.
 	 * @return The async agent

acp-core/src/main/java/com/agentclientprotocol/sdk/agent/DefaultAcpAsyncAgent.java

@@ -130,13 +130,15 @@ public Mono<Void> start() {
 				});
 			}
 
-			// Prompt handler - uses the session update sender
+			// Prompt handler - provides full PromptContext with all agent capabilities
 			if (promptHandler != null) {
 				requestHandlers.put(AcpSchema.METHOD_SESSION_PROMPT, params -> {
 					AcpSchema.PromptRequest request = transport.unmarshalFrom(params,
 							new TypeRef<AcpSchema.PromptRequest>() {
 							});
-					return promptHandler.handle(request, (sessionId, update) -> sendSessionUpdate(sessionId, update))
+					// Create PromptContext that wraps this agent, giving handler access to all capabilities
+					PromptContext context = new DefaultPromptContext(this);
+					return promptHandler.handle(request, context)
 						.cast(Object.class);
 				});
 			}

acp-core/src/main/java/com/agentclientprotocol/sdk/agent/DefaultPromptContext.java

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ */
+
+package com.agentclientprotocol.sdk.agent;
+
+import com.agentclientprotocol.sdk.capabilities.NegotiatedCapabilities;
+import com.agentclientprotocol.sdk.spec.AcpSchema;
+import reactor.core.publisher.Mono;
+
+/**
+ * Default implementation of {@link PromptContext} that delegates to an {@link AcpAsyncAgent}.
+ *
+ * <p>
+ * This class is created internally by {@link DefaultAcpAsyncAgent} and passed to prompt handlers.
+ * It provides a clean interface for handlers to access all agent capabilities without needing
+ * a direct reference to the agent instance.
+ *
+ * @author Mark Pollack
+ * @since 0.9.1
+ */
+class DefaultPromptContext implements PromptContext {
+
+	private final AcpAsyncAgent agent;
+
+	/**
+	 * Creates a new prompt context wrapping the given agent.
+	 * @param agent The agent to delegate to
+	 */
+	DefaultPromptContext(AcpAsyncAgent agent) {
+		this.agent = agent;
+	}
+
+	@Override
+	public Mono<Void> sendUpdate(String sessionId, AcpSchema.SessionUpdate update) {
+		return agent.sendSessionUpdate(sessionId, update);
+	}
+
+	@Override
+	public Mono<AcpSchema.ReadTextFileResponse> readTextFile(AcpSchema.ReadTextFileRequest request) {
+		return agent.readTextFile(request);
+	}
+
+	@Override
+	public Mono<AcpSchema.WriteTextFileResponse> writeTextFile(AcpSchema.WriteTextFileRequest request) {
+		return agent.writeTextFile(request);
+	}
+
+	@Override
+	public Mono<AcpSchema.RequestPermissionResponse> requestPermission(AcpSchema.RequestPermissionRequest request) {
+		return agent.requestPermission(request);
+	}
+
+	@Override
+	public Mono<AcpSchema.CreateTerminalResponse> createTerminal(AcpSchema.CreateTerminalRequest request) {
+		return agent.createTerminal(request);
+	}
+
+	@Override
+	public Mono<AcpSchema.TerminalOutputResponse> getTerminalOutput(AcpSchema.TerminalOutputRequest request) {
+		return agent.getTerminalOutput(request);
+	}
+
+	@Override
+	public Mono<AcpSchema.ReleaseTerminalResponse> releaseTerminal(AcpSchema.ReleaseTerminalRequest request) {
+		return agent.releaseTerminal(request);
+	}
+
+	@Override
+	public Mono<AcpSchema.WaitForTerminalExitResponse> waitForTerminalExit(
+			AcpSchema.WaitForTerminalExitRequest request) {
+		return agent.waitForTerminalExit(request);
+	}
+
+	@Override
+	public Mono<AcpSchema.KillTerminalCommandResponse> killTerminal(AcpSchema.KillTerminalCommandRequest request) {
+		return agent.killTerminal(request);
+	}
+
+	@Override
+	public NegotiatedCapabilities getClientCapabilities() {
+		return agent.getClientCapabilities();
+	}
+
+}

acp-core/src/main/java/com/agentclientprotocol/sdk/agent/DefaultSyncPromptContext.java

@@ -0,0 +1,82 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ */
+
+package com.agentclientprotocol.sdk.agent;
+
+import com.agentclientprotocol.sdk.capabilities.NegotiatedCapabilities;
+import com.agentclientprotocol.sdk.spec.AcpSchema;
+
+/**
+ * Default implementation of {@link SyncPromptContext} that wraps an async {@link PromptContext}
+ * and provides blocking methods.
+ *
+ * <p>
+ * This class is created internally by the sync-to-async handler converter in {@link AcpAgent.SyncAgentBuilder}.
+ *
+ * @author Mark Pollack
+ * @since 0.9.1
+ */
+class DefaultSyncPromptContext implements SyncPromptContext {
+
+	private final PromptContext asyncContext;
+
+	/**
+	 * Creates a new sync context wrapping the given async context.
+	 * @param asyncContext The async context to wrap
+	 */
+	DefaultSyncPromptContext(PromptContext asyncContext) {
+		this.asyncContext = asyncContext;
+	}
+
+	@Override
+	public void sendUpdate(String sessionId, AcpSchema.SessionUpdate update) {
+		asyncContext.sendUpdate(sessionId, update).block();
+	}
+
+	@Override
+	public AcpSchema.ReadTextFileResponse readTextFile(AcpSchema.ReadTextFileRequest request) {
+		return asyncContext.readTextFile(request).block();
+	}
+
+	@Override
+	public AcpSchema.WriteTextFileResponse writeTextFile(AcpSchema.WriteTextFileRequest request) {
+		return asyncContext.writeTextFile(request).block();
+	}
+
+	@Override
+	public AcpSchema.RequestPermissionResponse requestPermission(AcpSchema.RequestPermissionRequest request) {
+		return asyncContext.requestPermission(request).block();
+	}
+
+	@Override
+	public AcpSchema.CreateTerminalResponse createTerminal(AcpSchema.CreateTerminalRequest request) {
+		return asyncContext.createTerminal(request).block();
+	}
+
+	@Override
+	public AcpSchema.TerminalOutputResponse getTerminalOutput(AcpSchema.TerminalOutputRequest request) {
+		return asyncContext.getTerminalOutput(request).block();
+	}
+
+	@Override
+	public AcpSchema.ReleaseTerminalResponse releaseTerminal(AcpSchema.ReleaseTerminalRequest request) {
+		return asyncContext.releaseTerminal(request).block();
+	}
+
+	@Override
+	public AcpSchema.WaitForTerminalExitResponse waitForTerminalExit(AcpSchema.WaitForTerminalExitRequest request) {
+		return asyncContext.waitForTerminalExit(request).block();
+	}
+
+	@Override
+	public AcpSchema.KillTerminalCommandResponse killTerminal(AcpSchema.KillTerminalCommandRequest request) {
+		return asyncContext.killTerminal(request).block();
+	}
+
+	@Override
+	public NegotiatedCapabilities getClientCapabilities() {
+		return asyncContext.getClientCapabilities();
+	}
+
+}