@@ -15,6 +15,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Prompt handlers see their prompt's cancellation.** `SyncPromptContext.isCancelled()` and
+  `onCancel(Runnable)`, and `PromptContext.isCancelled()` and `whenCancelled()` (a `Mono<Void>`
+  that completes on cancel), signal a cancel by `session/cancel` for the prompt's session or by
+  `$/cancel_request` for its request, and also when the agent cancels the handler itself (the
+  cancel grace period or `maxPromptDuration` passed, or the connection closed). An annotated
+  `@Prompt` method reads it from the context it takes, with no `@Cancel` handler or shared state;
+  a builder prompt handler likewise. After `session/cancel` the handler still answers `cancelled`
+  within the cancel grace period; after `$/cancel_request` the agent has already answered, so the
+  handler just stops. New `PromptResponse.cancelled()`.
+  **Breaking** for code implementing `PromptContext` or `SyncPromptContext` itself (test doubles):
+  implement the new methods.
+
 - **`$/cancel_request` (ACP v1, Cancellation), both directions.** Client and agent sessions alike:
   - **Cancelling a request you sent:** dispose (cancel) the subscription to its `Mono` before the
     response arrives, directly or through `timeout(...)`, `take...`, or the SDK's own request
 
@@ -261,6 +261,39 @@ PromptResponse handle(PromptRequest req, SyncPromptContext ctx) {
 }
 ```
 
+### Cancellation
+
+A prompt method learns that its prompt was cancelled from its context, whether by `session/cancel`
+for its session or by `$/cancel_request` for its request; no `@Cancel` handler or shared state is
+needed:
+
+```java
+@Prompt
+PromptResponse handle(PromptRequest req, SyncPromptContext ctx) {
+    for (Step step : plan(req)) {
+        if (ctx.isCancelled()) {
+            ctx.sendMessage("Stopped.");
+            return PromptResponse.cancelled();
+        }
+        step.run(ctx);
+    }
+    return PromptResponse.endTurn();
+}
+
+@Prompt
+Mono<PromptResponse> handle(PromptRequest req, PromptContext ctx) {
+    return work(req, ctx)
+        .takeUntilOther(ctx.whenCancelled())
+        .defaultIfEmpty(PromptResponse.cancelled());
+}
+```
+
+`SyncPromptContext.onCancel(Runnable)` runs an action once on cancel, for work that cannot poll
+(a subprocess, an HTTP call). After `session/cancel` the method must answer `cancelled` within the
+cancel grace period (`cancelGracePeriod`, default 60 s); once it passes the agent answers
+`cancelled` itself and interrupts the method's thread. After `$/cancel_request` the agent has already
+answered (`-32800`, or `cancelled` if the session was cancelled too), so the method just stops.
+
 ## Interceptors
 
 Interceptors allow cross-cutting concerns like logging, metrics, or error handling:
 
@@ -0,0 +1,187 @@
+/*
+ * Copyright 2026 the original author or authors.
+ */
+
+package com.agentclientprotocol.sdk.agent.support;
+
+import java.time.Duration;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+
+import com.agentclientprotocol.sdk.agent.PromptContext;
+import com.agentclientprotocol.sdk.agent.SyncPromptContext;
+import com.agentclientprotocol.sdk.annotation.AcpAgent;
+import com.agentclientprotocol.sdk.annotation.Cancel;
+import com.agentclientprotocol.sdk.annotation.NewSession;
+import com.agentclientprotocol.sdk.annotation.Prompt;
+import com.agentclientprotocol.sdk.client.AcpAsyncClient;
+import com.agentclientprotocol.sdk.client.AcpClient;
+import com.agentclientprotocol.sdk.spec.AcpSchema;
+import com.agentclientprotocol.sdk.spec.AcpSchema.PromptRequest;
+import com.agentclientprotocol.sdk.spec.AcpSchema.PromptResponse;
+import com.agentclientprotocol.sdk.test.InMemoryTransportPair;
+import org.junit.jupiter.api.Test;
+import reactor.core.Disposable;
+import reactor.core.publisher.Mono;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * An annotated {@code @Prompt} method learns of its prompt's cancellation from its context,
+ * with no {@code @Cancel} handler or shared state: {@code SyncPromptContext.isCancelled()} or
+ * {@code PromptContext.whenCancelled()}. The grace period is long, so a prompt answered
+ * promptly with the handler's {@code _meta} was answered by the handler.
+ */
+class AnnotatedPromptCancellationTest {
+
+	private static final Duration TIMEOUT = Duration.ofSeconds(5);
+
+	private static final String SESSION = "annotated-cancel";
+
+	private static final Map<String, Object> HANDLERS_OWN = Map.of("answeredBy", "handler");
+
+	@AcpAgent
+	static class PollingAgent {
+
+		final CountDownLatch running = new CountDownLatch(1);
+
+		final CountDownLatch sawCancel = new CountDownLatch(1);
+
+		final CountDownLatch cancelHandlerRan = new CountDownLatch(1);
+
+		@NewSession
+		AcpSchema.NewSessionResponse newSession() {
+			return new AcpSchema.NewSessionResponse(SESSION, null, null);
+		}
+
+		@Prompt
+		PromptResponse prompt(PromptRequest request, SyncPromptContext context) {
+			running.countDown();
+			while (!context.isCancelled()) {
+				Thread.interrupted(); // a cancelled request interrupts the thread: keep polling
+				pause();
+			}
+			sawCancel.countDown();
+			return new PromptResponse(AcpSchema.StopReason.CANCELLED, HANDLERS_OWN);
+		}
+
+		@Cancel
+		void cancel() {
+			cancelHandlerRan.countDown();
+		}
+
+	}
+
+	@AcpAgent
+	static class ReactiveAgent {
+
+		@NewSession
+		AcpSchema.NewSessionResponse newSession() {
+			return new AcpSchema.NewSessionResponse(SESSION, null, null);
+		}
+
+		@Prompt
+		Mono<PromptResponse> prompt(PromptContext context) {
+			return Mono.<PromptResponse>never()
+				.takeUntilOther(context.whenCancelled())
+				.switchIfEmpty(Mono.fromSupplier(
+						() -> new PromptResponse(AcpSchema.StopReason.CANCELLED, HANDLERS_OWN)));
+		}
+
+	}
+
+	@Test
+	void aPollingPromptAnswersCancelledPromptlyOnSessionCancel() throws Exception {
+		PollingAgent bean = new PollingAgent();
+		run(bean, client -> {
+			Mono<PromptResponse> response = client.prompt(prompt()).cache();
+			response.subscribe(r -> {
+			}, e -> {
+			});
+			await(bean.running);
+			long start = System.nanoTime();
+			client.cancel(new AcpSchema.CancelNotification(SESSION)).block(TIMEOUT);
+
+			PromptResponse answer = response.block(TIMEOUT);
+			assertThat(answer.stopReason()).isEqualTo(AcpSchema.StopReason.CANCELLED);
+			assertThat(answer.meta()).as("the handler's own answer").isEqualTo(HANDLERS_OWN);
+			assertThat(Duration.ofNanos(System.nanoTime() - start)).isLessThan(Duration.ofSeconds(3));
+			await(bean.cancelHandlerRan);
+		});
+	}
+
+	@Test
+	void aPollingPromptSeesACancelRequestForItsRequest() throws Exception {
+		PollingAgent bean = new PollingAgent();
+		run(bean, client -> {
+			Disposable prompt = client.prompt(prompt()).subscribe(r -> {
+			}, e -> {
+			});
+			await(bean.running);
+
+			prompt.dispose(); // $/cancel_request
+
+			await(bean.sawCancel);
+		});
+	}
+
+	@Test
+	void aReactivePromptCompletesOnWhenCancelled() throws Exception {
+		run(new ReactiveAgent(), client -> {
+			Mono<PromptResponse> response = client.prompt(prompt()).cache();
+			response.subscribe(r -> {
+			}, e -> {
+			});
+			pause();
+			client.cancel(new AcpSchema.CancelNotification(SESSION)).block(TIMEOUT);
+
+			assertThat(response.block(TIMEOUT).meta()).isEqualTo(HANDLERS_OWN);
+		});
+	}
+
+	interface ClientScenario {
+
+		void run(AcpAsyncClient client) throws Exception;
+
+	}
+
+	private static void run(Object bean, ClientScenario scenario) throws Exception {
+		InMemoryTransportPair pair = InMemoryTransportPair.create();
+		AcpAgentSupport agent = AcpAgentSupport.create(bean)
+			.transport(pair.agentTransport())
+			.requestTimeout(TIMEOUT)
+			.cancelGracePeriod(Duration.ofSeconds(30))
+			.build();
+		agent.start();
+		AcpAsyncClient client = AcpClient.async(pair.clientTransport()).requestTimeout(TIMEOUT).build();
+		try {
+			client.initialize().block(TIMEOUT);
+			client.newSession(new AcpSchema.NewSessionRequest("/w", List.of())).block(TIMEOUT);
+			scenario.run(client);
+		}
+		finally {
+			client.closeGracefully().block(TIMEOUT);
+			agent.close();
+		}
+	}
+
+	private static PromptRequest prompt() {
+		return new PromptRequest(SESSION, List.of(new AcpSchema.TextContent("work")));
+	}
+
+	private static void await(CountDownLatch latch) throws InterruptedException {
+		assertThat(latch.await(5, TimeUnit.SECONDS)).isTrue();
+	}
+
+	private static void pause() {
+		try {
+			Thread.sleep(20);
+		}
+		catch (InterruptedException ex) {
+			Thread.currentThread().interrupt();
+		}
+	}
+
+}
@@ -14,9 +14,11 @@
  * Marks the {@link AcpAgent} method that receives {@code session/cancel}: the client asks the
  * agent to stop the session's running prompt turn, and the method tells the {@link Prompt} method
  * to stop. {@code session/cancel} is a notification, so the method returns {@code void} and
- * nothing is sent back. Without a {@code @Cancel} method the SDK still records the cancel and runs
- * the grace period described below, but the prompt method is not told until the grace period
- * ends.
+ * nothing is sent back. The prompt method does not need it to learn of the cancel: its context
+ * says so ({@code SyncPromptContext.isCancelled()} or {@code onCancel(Runnable)},
+ * {@code PromptContext.whenCancelled()}), for {@code session/cancel} and for a
+ * {@code $/cancel_request} naming the prompt. Declare a {@code @Cancel} method for work outside
+ * the prompt method, such as stopping a job the prompt started elsewhere.
  *
  * <p>The cancel does not end the turn. The prompt method should stop, send any last updates, and
  * return stop reason {@code cancelled}; until it returns, a new prompt on the session is answered
@@ -26,41 +28,37 @@
  * is SDK policy; ACP sets no time limit.
  *
  * <p>This method runs on a handler thread while the prompt method is still running on another, so
- * the two share a thread-safe flag, keyed by session id, as in the example. An exception it throws
- * is logged and dropped. {@code $/cancel_request}, which cancels a single request, never reaches
+ * state the two share is thread-safe and keyed by session id, as in the example. An exception it
+ * throws is logged and dropped. {@code $/cancel_request}, which cancels a single request, never reaches
  * this method: the SDK handles it.
  *
  * <p>The method can take a {@code CancelNotification}, a {@link SessionId @SessionId}
  * {@code String} and the connection parameters (see {@link AcpAgent}).
  *
- * <p>Example usage:
+ * <p>Example usage, stopping a build the prompt started on a build server:
  * <pre>{@code
- * private final Map<String, AtomicBoolean> stopFlags = new ConcurrentHashMap<>();
+ * private final Map<String, String> runningBuilds = new ConcurrentHashMap<>();
  *
- * @Prompt
- * public PromptResponse prompt(@SessionId String sessionId, SyncPromptContext context) {
- *     AtomicBoolean stop = new AtomicBoolean();
- *     stopFlags.put(sessionId, stop);
- *     try {
- *         for (int step = 1; step <= 3; step++) {
- *             if (stop.get()) {
- *                 return new PromptResponse(StopReason.CANCELLED);
- *             }
- *             context.sendMessage("Step " + step + " done. ");
- *         }
- *         return PromptResponse.endTurn();
- *     }
- *     finally {
- *         stopFlags.remove(sessionId);
+ * @Cancel
+ * public void cancel(@SessionId String sessionId) {
+ *     String buildId = runningBuilds.remove(sessionId);
+ *     if (buildId != null) {
+ *         buildServer.abort(buildId);
  *     }
  * }
+ * }</pre>
  *
- * @Cancel
- * public void cancel(@SessionId String sessionId) {
- *     AtomicBoolean stop = stopFlags.get(sessionId);
- *     if (stop != null) {
- *         stop.set(true);
+ * <p>A prompt method that only needs to stop its own loop checks its context instead:
+ * <pre>{@code
+ * @Prompt
+ * public PromptResponse prompt(SyncPromptContext context) {
+ *     for (int step = 1; step <= 3; step++) {
+ *         if (context.isCancelled()) {
+ *             return PromptResponse.cancelled();
+ *         }
+ *         context.sendMessage("Step " + step + " done. ");
  *     }
+ *     return PromptResponse.endTurn();
  * }
  * }</pre>
  *
 
@@ -46,12 +46,18 @@
  *
  * <p>A session has one prompt turn at a time. Until this method returns, a second prompt on the
  * same session is answered with {@code -32600} (Invalid request); prompts on other sessions run at
- * the same time, on other threads. When the client cancels the turn, this method keeps running:
- * the {@link Cancel} method is called, and this method should stop and return stop reason
- * {@code cancelled}. If it has not returned when the cancel grace period ends, the SDK answers
- * {@code cancelled} for it and interrupts its thread. {@code AcpAgentSupport.Builder} sets the
- * grace period and can also limit how long any turn runs ({@code maxPromptDuration}, off by
- * default).
+ * the same time, on other threads.
+ *
+ * <p><b>Cancellation.</b> The context tells the method that its turn was cancelled, by
+ * {@code session/cancel} for its session or by {@code $/cancel_request} for its request: a sync
+ * method polls {@code SyncPromptContext.isCancelled()} (or registers {@code onCancel(Runnable)}),
+ * a method returning {@code Mono} composes {@code PromptContext.whenCancelled()}. After
+ * {@code session/cancel} the method keeps running until it returns: it should stop, send any last
+ * updates, and return {@code PromptResponse.cancelled()}. If it has not returned when the cancel
+ * grace period ends, the SDK answers {@code cancelled} for it and interrupts its thread. After
+ * {@code $/cancel_request} the SDK has already answered, so the method just stops.
+ * {@code AcpAgentSupport.Builder} sets the grace period and can also limit how long any turn runs
+ * ({@code maxPromptDuration}, off by default).
  *
  * <p>Example usage:
  * <pre>{@code