test: cover AgentStop E2E in every SDK

Add Node, Python, Rust, and Java replay tests for natural-stop callback delivery and block-driven continuation using the shared hooks_extended snapshot.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Copilot

java/src/test/java/com/github/copilot/HooksTest.java

@@ -18,6 +18,8 @@
 import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Test;
 
+import com.github.copilot.rpc.AgentStopHookInput;
+import com.github.copilot.rpc.AgentStopHookOutput;
 import com.github.copilot.rpc.MessageOptions;
 import com.github.copilot.rpc.PermissionHandler;
 import com.github.copilot.rpc.PostToolUseHookInput;
@@ -225,4 +227,44 @@ void testDenyToolExecutionWhenPreToolUseReturnsDeny() throws Exception {
             assertEquals(originalContent, Files.readString(testFile), "Denied preToolUse hook should block file edits");
         }
     }
+
+    /**
+     * Verifies that agent-stop can block a natural stop and enqueue another turn.
+     *
+     * @see Snapshot: hooks_extended/should_invoke_agentstop_hook_and_apply_block_response
+     */
+    @Test
+    void testInvokeAgentStopHookAndApplyBlockResponse() throws Exception {
+        ctx.configureForTest("hooks_extended", "should_invoke_agentstop_hook_and_apply_block_response");
+
+        var inputs = new ArrayList<AgentStopHookInput>();
+        final String[] sessionIdHolder = new String[1];
+        var config = new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+                .setHooks(new SessionHooks().setOnAgentStop((input, invocation) -> {
+                    assertEquals(sessionIdHolder[0], invocation.getSessionId());
+                    inputs.add(input);
+                    if (inputs.size() == 1) {
+                        return CompletableFuture.completedFuture(new AgentStopHookOutput().setDecision("block")
+                                .setReason("Reply with exactly: AGENT_STOP_CONTINUED"));
+                    }
+                    return CompletableFuture.completedFuture(null);
+                }));
+
+        try (CopilotClient client = ctx.createClient()) {
+            CopilotSession session = client.createSession(config).get();
+            sessionIdHolder[0] = session.getSessionId();
+
+            var response = session
+                    .sendAndWait(new MessageOptions().setPrompt("Reply with exactly: AGENT_STOP_INITIAL"))
+                    .get(60, TimeUnit.SECONDS);
+
+            assertEquals(2, inputs.size());
+            assertNotEquals(Boolean.TRUE, inputs.get(0).getStopHookActive());
+            assertEquals(Boolean.TRUE, inputs.get(1).getStopHookActive());
+            assertEquals("end_turn", inputs.get(0).getStopReason());
+            assertFalse(inputs.get(0).getTranscriptPath().isBlank());
+            assertNotNull(response);
+            assertTrue(response.getData().content().contains("AGENT_STOP_CONTINUED"));
+        }
+    }
 }

nodejs/test/e2e/hooks_extended.e2e.test.ts

@@ -6,6 +6,7 @@ import { describe, expect, it } from "vitest";
 import { z } from "zod";
 import { approveAll, defineTool } from "../../src/index.js";
 import type {
+    AgentStopHookInput,
     ErrorOccurredHookInput,
     PostToolUseFailureHookInput,
     PostToolUseHookInput,
@@ -260,6 +261,38 @@ describe("Extended session hooks", async () => {
         await session.disconnect();
     });
 
+    it("should invoke agentStop hook and apply block response", async () => {
+        const inputs: AgentStopHookInput[] = [];
+        const session = await client.createSession({
+            onPermissionRequest: approveAll,
+            hooks: {
+                onAgentStop: async (input, invocation) => {
+                    expect(invocation.sessionId).toBe(session.sessionId);
+                    inputs.push(input);
+                    if (inputs.length === 1) {
+                        return {
+                            decision: "block",
+                            reason: "Reply with exactly: AGENT_STOP_CONTINUED",
+                        };
+                    }
+                },
+            },
+        });
+
+        const response = await session.sendAndWait({
+            prompt: "Reply with exactly: AGENT_STOP_INITIAL",
+        });
+
+        expect(inputs).toHaveLength(2);
+        expect(inputs[0].stopHookActive).not.toBe(true);
+        expect(inputs[1].stopHookActive).toBe(true);
+        expect(inputs[0].stopReason).toBe("end_turn");
+        expect(inputs[0].transcriptPath).toBeTruthy();
+        expect(response?.data.content ?? "").toContain("AGENT_STOP_CONTINUED");
+
+        await session.disconnect();
+    });
+
     it("should allow preToolUse to return modifiedArgs and suppressOutput", async () => {
         const inputs: PreToolUseHookInput[] = [];
         const session = await client.createSession({

python/e2e/test_hooks_extended_e2e.py

@@ -4,7 +4,7 @@
 E2E coverage for every handler exposed on ``SessionHooks``:
 ``on_pre_tool_use``, ``on_post_tool_use``, ``on_post_tool_use_failure``,
 ``on_user_prompt_submitted``, ``on_session_start``, ``on_session_end``,
-``on_error_occurred``. Output-shape behavior (modifiedPrompt /
+``on_error_occurred``, ``on_agent_stop``. Output-shape behavior (modifiedPrompt /
 additionalContext / errorHandling / modifiedArgs / modifiedResult /
 sessionSummary) is asserted alongside hook invocation.
 """
@@ -114,6 +114,36 @@ async def on_error_occurred(input_data, invocation):
         finally:
             await session.disconnect()
 
+    async def test_should_invoke_agentstop_hook_and_apply_block_response(
+        self, ctx: E2ETestContext
+    ):
+        inputs: list[dict] = []
+
+        async def on_agent_stop(input_data, invocation):
+            assert invocation["session_id"] == session.session_id
+            inputs.append(input_data)
+            if len(inputs) == 1:
+                return {
+                    "decision": "block",
+                    "reason": "Reply with exactly: AGENT_STOP_CONTINUED",
+                }
+            return None
+
+        session = await ctx.client.create_session(
+            on_permission_request=PermissionHandler.approve_all,
+            hooks={"on_agent_stop": on_agent_stop},
+        )
+        try:
+            response = await session.send_and_wait("Reply with exactly: AGENT_STOP_INITIAL")
+            assert len(inputs) == 2
+            assert inputs[0].get("stopHookActive") is not True
+            assert inputs[1].get("stopHookActive") is True
+            assert inputs[0].get("stopReason") == "end_turn"
+            assert inputs[0].get("transcriptPath")
+            assert "AGENT_STOP_CONTINUED" in (response.data.content or "")
+        finally:
+            await session.disconnect()
+
     async def test_should_allow_pretooluse_to_return_modifiedargs_and_suppressoutput(
         self, ctx: E2ETestContext
     ):

rust/tests/e2e/hooks_extended.rs

@@ -1,12 +1,13 @@
 use std::sync::Arc;
+use std::sync::atomic::{AtomicUsize, Ordering};
 
 use async_trait::async_trait;
 use github_copilot_sdk::handler::ApproveAllHandler;
 use github_copilot_sdk::hooks::{
-    ErrorOccurredInput, ErrorOccurredOutput, HookContext, PostToolUseFailureInput,
-    PostToolUseFailureOutput, PostToolUseInput, PostToolUseOutput, PreToolUseInput,
-    PreToolUseOutput, SessionEndInput, SessionEndOutput, SessionHooks, SessionStartInput,
-    SessionStartOutput, UserPromptSubmittedInput, UserPromptSubmittedOutput,
+    AgentStopInput, AgentStopOutput, ErrorOccurredInput, ErrorOccurredOutput, HookContext,
+    PostToolUseFailureInput, PostToolUseFailureOutput, PostToolUseInput, PostToolUseOutput,
+    PreToolUseInput, PreToolUseOutput, SessionEndInput, SessionEndOutput, SessionHooks,
+    SessionStartInput, SessionStartOutput, UserPromptSubmittedInput, UserPromptSubmittedOutput,
 };
 use github_copilot_sdk::tool::ToolHandler;
 use github_copilot_sdk::{Error, SessionConfig, Tool, ToolInvocation, ToolResult};
@@ -281,6 +282,49 @@ async fn should_register_erroroccurred_hook() {
     .await;
 }
 
+#[tokio::test]
+async fn should_invoke_agentstop_hook_and_apply_block_response() {
+    with_e2e_context(
+        "hooks_extended",
+        "should_invoke_agentstop_hook_and_apply_block_response",
+        |ctx| {
+            Box::pin(async move {
+                ctx.set_default_copilot_user();
+                let (tx, mut rx) = mpsc::unbounded_channel();
+                let client = ctx.start_client().await;
+                let session = client
+                    .create_session(
+                        ctx.approve_all_session_config()
+                            .with_hooks(Arc::new(AgentStopHooks {
+                                tx,
+                                call_count: AtomicUsize::new(0),
+                            })),
+                    )
+                    .await
+                    .expect("create session");
+
+                let answer = session
+                    .send_and_wait("Reply with exactly: AGENT_STOP_INITIAL")
+                    .await
+                    .expect("send")
+                    .expect("assistant message");
+                let first = recv_with_timeout(&mut rx, "first agentStop hook").await;
+                let second = recv_with_timeout(&mut rx, "second agentStop hook").await;
+
+                assert_ne!(first.stop_hook_active, Some(true));
+                assert_eq!(second.stop_hook_active, Some(true));
+                assert_eq!(first.stop_reason.as_deref(), Some("end_turn"));
+                assert!(first.transcript_path.is_some());
+                assert!(assistant_message_content(&answer).contains("AGENT_STOP_CONTINUED"));
+
+                session.disconnect().await.expect("disconnect session");
+                client.stop().await.expect("stop client");
+            })
+        },
+    )
+    .await;
+}
+
 #[tokio::test]
 async fn should_allow_pretooluse_to_return_modifiedargs_and_suppressoutput() {
     with_e2e_context(
@@ -441,6 +485,27 @@ struct RecordingHooks {
     post_tool_failure: Option<mpsc::UnboundedSender<PostToolUseFailureInput>>,
 }
 
+struct AgentStopHooks {
+    tx: mpsc::UnboundedSender<AgentStopInput>,
+    call_count: AtomicUsize,
+}
+
+#[async_trait]
+impl SessionHooks for AgentStopHooks {
+    async fn on_agent_stop(
+        &self,
+        input: AgentStopInput,
+        ctx: HookContext,
+    ) -> Option<AgentStopOutput> {
+        assert!(!ctx.session_id.as_str().is_empty());
+        let _ = self.tx.send(input);
+        (self.call_count.fetch_add(1, Ordering::SeqCst) == 0).then(|| AgentStopOutput {
+            decision: Some("block".to_string()),
+            reason: Some("Reply with exactly: AGENT_STOP_CONTINUED".to_string()),
+        })
+    }
+}
+
 impl RecordingHooks {
     fn session_start(
         tx: mpsc::UnboundedSender<SessionStartInput>,