test: add backgroundTasks regression tests and update sendAndWait docs

- Add timeout test: sendAndWait times out when backgroundTasks never clears
  (all 3 review models flagged this gap; test uses 300ms timeout for speed)
- Add Go backgroundTasks unit tests (TestSendAndWait_BackgroundTasks, 4 subtests)
  using io.Pipe fake jsonrpc2 client
- Add .NET SendAndWait_Resolves_After_Clean_SessionIdle test in SessionTests.cs
- Add Python async backgroundTasks tests in test_session_background_tasks.py
- Add YAML snapshot for .NET clean-idle test
- Update sendAndWait docs in all 4 SDKs: clarify that it waits for ALL background
  tasks to complete (not just first session.idle), document timeout behavior for
  stuck background agents

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

Author: PureWeen

dotnet/src/Session.cs

@@ -173,20 +173,26 @@ public async Task<string> SendAsync(MessageOptions options, CancellationToken ca
     }
 
     /// <summary>
-    /// Sends a message to the Copilot session and waits until the session becomes idle.
+    /// Sends a message to the Copilot session and waits until the session is fully idle.
     /// </summary>
     /// <param name="options">Options for the message to be sent, including the prompt and optional attachments.</param>
     /// <param name="timeout">Timeout duration (default: 60 seconds). Controls how long to wait; does not abort in-flight agent work.</param>
     /// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to cancel the operation.</param>
     /// <returns>A task that resolves with the final assistant message event, or null if none was received.</returns>
-    /// <exception cref="TimeoutException">Thrown if the timeout is reached before the session becomes idle.</exception>
+    /// <exception cref="TimeoutException">Thrown if the timeout is reached before the session becomes fully idle.</exception>
     /// <exception cref="OperationCanceledException">Thrown if the <paramref name="cancellationToken"/> is cancelled.</exception>
     /// <exception cref="InvalidOperationException">Thrown if the session has been disposed.</exception>
     /// <remarks>
     /// <para>
     /// This is a convenience method that combines <see cref="SendAsync"/> with waiting for
     /// the <c>session.idle</c> event. Use this when you want to block until the assistant
-    /// has finished processing the message.
+    /// has finished processing the message and all background tasks have completed.
+    /// </para>
+    /// <para>
+    /// <b>Background tasks:</b> When the CLI emits <c>session.idle</c> with a non-empty
+    /// <c>backgroundTasks</c> field, it signals that background agents or shells are still
+    /// running. <see cref="SendAndWaitAsync"/> will continue waiting until a <c>session.idle</c>
+    /// arrives with no active background tasks, or until the timeout fires.
     /// </para>
     /// <para>
     /// Events are still delivered to handlers registered via <see cref="On"/> while waiting.

dotnet/test/SessionTests.cs

@@ -427,6 +427,40 @@ public async Task Should_Get_Session_Metadata_By_Id()
         Assert.Null(notFound);
     }
 
+    // ─────────────────────────────────────────────────────────────────────────
+    // BackgroundTasks regression tests for PolyPilot#299.
+    //
+    // The fix ensures SendAndWaitAsync only resolves when session.idle arrives
+    // with no active backgroundTasks (agents[] and shells[] both empty/absent).
+    //
+    // Note: The "does NOT resolve with active backgroundTasks" case cannot be
+    // tested through public APIs in .NET because DispatchEvent is internal and
+    // InternalsVisibleTo is not permitted per project conventions.  The
+    // equivalent unit tests (including the failing-before-fix repro) live in
+    // nodejs/test/client.test.ts under "sendAndWait backgroundTasks", and the
+    // Go unit tests in go/session_test.go TestSendAndWait_BackgroundTasks both
+    // cover the same fix logic.
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /// <summary>
+    /// Proves that SendAndWaitAsync resolves when session.idle has no
+    /// backgroundTasks (the normal, clean-idle case after our fix).
+    /// </summary>
+    [Fact]
+    public async Task SendAndWait_Resolves_After_Clean_SessionIdle()
+    {
+        var session = await CreateSessionAsync();
+
+        // A simple prompt that completes quickly — the CLI will emit
+        // session.idle with no backgroundTasks once the turn ends.
+        var result = await session.SendAndWaitAsync(
+            new MessageOptions { Prompt = "What is 1+1?" },
+            TimeSpan.FromSeconds(30));
+
+        Assert.NotNull(result);
+        Assert.Contains("2", result!.Data.Content);
+    }
+
     [Fact]
     public async Task SendAndWait_Throws_On_Timeout()
     {

go/session.go

@@ -143,18 +143,25 @@ func (s *Session) Send(ctx context.Context, options MessageOptions) (string, err
 	return response.MessageID, nil
 }
 
-// SendAndWait sends a message to this session and waits until the session becomes idle.
+// SendAndWait sends a message to this session and waits until the session is fully idle.
 //
 // This is a convenience method that combines [Session.Send] with waiting for
 // the session.idle event. Use this when you want to block until the assistant
-// has finished processing the message.
+// has finished processing the message and all background tasks (background
+// agents and shell commands) have completed.
+//
+// Background tasks: when the CLI emits session.idle with a non-empty
+// BackgroundTasks field it signals that background agents or shells are still
+// running. SendAndWait continues waiting until a session.idle arrives with no
+// active background tasks, or until the context deadline fires.
 //
 // Events are still delivered to handlers registered via [Session.On] while waiting.
 //
 // Parameters:
 //   - options: The message options including the prompt and optional attachments.
 //   - timeout: How long to wait for completion. Defaults to 60 seconds if zero.
-//     Controls how long to wait; does not abort in-flight agent work.
+//     Controls how long to wait; does not abort in-flight agent work. If
+//     background tasks are stuck the context deadline will fire.
 //
 // Returns the final assistant message event, or nil if none was received.
 // Returns an error if the timeout is reached or the connection fails.

go/session_test.go

@@ -1,10 +1,18 @@
 package copilot
 
 import (
+	"bufio"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"strings"
 	"sync"
 	"sync/atomic"
 	"testing"
 	"time"
+
+	"github.com/github/copilot-sdk/go/internal/jsonrpc2"
 )
 
 // newTestSession creates a session with an event channel and starts the consumer goroutine.
@@ -204,3 +212,252 @@ func TestSession_On(t *testing.T) {
 		}
 	})
 }
+
+// newTestSessionWithFakeClient creates a Session backed by an in-process fake
+// JSON-RPC 2.0 server that immediately acknowledges any "session.send" call.
+// The returned requestReceived channel is signalled once per incoming request,
+// so tests can synchronize dispatch of follow-up events.
+// The cleanup function must be deferred by the caller.
+func newTestSessionWithFakeClient(t *testing.T) (sess *Session, requestReceived <-chan struct{}, cleanup func()) {
+	t.Helper()
+
+	stdinR, stdinW := io.Pipe()
+	stdoutR, stdoutW := io.Pipe()
+
+	client := jsonrpc2.NewClient(stdinW, stdoutR)
+	client.Start()
+
+	reqCh := make(chan struct{}, 4)
+
+	go func() {
+		reader := bufio.NewReader(stdinR)
+		buf := make([]byte, 8192)
+		for {
+			var contentLength int
+			for {
+				line, err := reader.ReadString('\n')
+				if err != nil {
+					return
+				}
+				line = strings.TrimSpace(line)
+				if line == "" {
+					break
+				}
+				fmt.Sscanf(line, "Content-Length: %d", &contentLength)
+			}
+			if contentLength == 0 {
+				continue
+			}
+			if contentLength > len(buf) {
+				buf = make([]byte, contentLength)
+			}
+			if _, err := io.ReadFull(reader, buf[:contentLength]); err != nil {
+				return
+			}
+			var req struct {
+				ID json.RawMessage `json:"id"`
+			}
+			json.Unmarshal(buf[:contentLength], &req) //nolint:errcheck
+
+			// Signal that a request was received before sending the response,
+			// so tests can dispatch events once Send() is in-flight.
+			select {
+			case reqCh <- struct{}{}:
+			default:
+			}
+
+			result := `{"messageId":"test-msg"}`
+			body := fmt.Sprintf(`{"jsonrpc":"2.0","id":%s,"result":%s}`, req.ID, result)
+			header := fmt.Sprintf("Content-Length: %d\r\n\r\n", len(body))
+			stdoutW.Write([]byte(header + body)) //nolint:errcheck
+		}
+	}()
+
+	s := &Session{
+		SessionID: "test-session",
+		handlers:  make([]sessionHandler, 0),
+		eventCh:   make(chan SessionEvent, 128),
+		client:    client,
+	}
+	go s.processEvents()
+
+	cleanupFn := func() {
+		stdoutW.Close()
+		stdinW.Close()
+		client.Stop()
+		close(s.eventCh)
+	}
+
+	return s, reqCh, cleanupFn
+}
+
+// TestSendAndWait_BackgroundTasks verifies the fix for PolyPilot#299:
+// SendAndWait must NOT resolve when session.idle carries active background tasks.
+func TestSendAndWait_BackgroundTasks(t *testing.T) {
+	t.Run("does not resolve when session.idle has active background agents", func(t *testing.T) {
+		session, requestReceived, cleanup := newTestSessionWithFakeClient(t)
+		defer cleanup()
+
+		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		defer cancel()
+
+		var resolved atomic.Bool
+		done := make(chan struct{})
+		go func() {
+			defer close(done)
+			session.SendAndWait(ctx, MessageOptions{Prompt: "test"}) //nolint:errcheck
+			resolved.Store(true)
+		}()
+
+		// Wait for the fake server to receive the session.send request.
+		select {
+		case <-requestReceived:
+		case <-time.After(2 * time.Second):
+			t.Fatal("timeout waiting for session.send request")
+		}
+
+		// Dispatch session.idle WITH active background agents — must NOT resolve.
+		session.dispatchEvent(SessionEvent{
+			Type: SessionEventTypeSessionIdle,
+			Data: Data{
+				BackgroundTasks: &BackgroundTasks{
+					Agents: []BackgroundTasksAgent{{AgentID: "bg-1", AgentType: "worker"}},
+					Shells: []Shell{},
+				},
+			},
+		})
+
+		time.Sleep(100 * time.Millisecond)
+		if resolved.Load() {
+			t.Error("BUG #299: SendAndWait resolved prematurely while background agents were active")
+		}
+
+		// Dispatch a clean idle (no background tasks) — now it SHOULD resolve.
+		session.dispatchEvent(SessionEvent{
+			Type: SessionEventTypeSessionIdle,
+			Data: Data{},
+		})
+
+		select {
+		case <-done:
+		case <-time.After(2 * time.Second):
+			t.Fatal("SendAndWait did not resolve after clean session.idle")
+		}
+		if !resolved.Load() {
+			t.Error("expected SendAndWait to resolve after clean session.idle")
+		}
+	})
+
+	t.Run("does not resolve when session.idle has active background shells", func(t *testing.T) {
+		session, requestReceived, cleanup := newTestSessionWithFakeClient(t)
+		defer cleanup()
+
+		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		defer cancel()
+
+		var resolved atomic.Bool
+		done := make(chan struct{})
+		go func() {
+			defer close(done)
+			session.SendAndWait(ctx, MessageOptions{Prompt: "test"}) //nolint:errcheck
+			resolved.Store(true)
+		}()
+
+		select {
+		case <-requestReceived:
+		case <-time.After(2 * time.Second):
+			t.Fatal("timeout waiting for session.send request")
+		}
+
+		// Dispatch session.idle WITH active background shell — must NOT resolve.
+		session.dispatchEvent(SessionEvent{
+			Type: SessionEventTypeSessionIdle,
+			Data: Data{
+				BackgroundTasks: &BackgroundTasks{
+					Agents: []BackgroundTasksAgent{},
+					Shells: []Shell{{ShellID: "sh-1"}},
+				},
+			},
+		})
+
+		time.Sleep(100 * time.Millisecond)
+		if resolved.Load() {
+			t.Error("BUG #299: SendAndWait resolved prematurely while background shells were active")
+		}
+
+		// Clean idle — should now resolve.
+		session.dispatchEvent(SessionEvent{
+			Type: SessionEventTypeSessionIdle,
+			Data: Data{BackgroundTasks: &BackgroundTasks{Agents: []BackgroundTasksAgent{}, Shells: []Shell{}}},
+		})
+
+		select {
+		case <-done:
+		case <-time.After(2 * time.Second):
+			t.Fatal("SendAndWait did not resolve after clean session.idle")
+		}
+	})
+
+	t.Run("resolves when session.idle has no backgroundTasks", func(t *testing.T) {
+		session, requestReceived, cleanup := newTestSessionWithFakeClient(t)
+		defer cleanup()
+
+		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		defer cancel()
+
+		done := make(chan struct{})
+		go func() {
+			defer close(done)
+			session.SendAndWait(ctx, MessageOptions{Prompt: "test"}) //nolint:errcheck
+		}()
+
+		select {
+		case <-requestReceived:
+		case <-time.After(2 * time.Second):
+			t.Fatal("timeout waiting for session.send request")
+		}
+
+		session.dispatchEvent(SessionEvent{
+			Type: SessionEventTypeSessionIdle,
+			Data: Data{},
+		})
+
+		select {
+		case <-done:
+		case <-time.After(2 * time.Second):
+			t.Fatal("SendAndWait did not resolve when session.idle had no backgroundTasks")
+		}
+	})
+
+	t.Run("resolves when session.idle has empty backgroundTasks arrays", func(t *testing.T) {
+		session, requestReceived, cleanup := newTestSessionWithFakeClient(t)
+		defer cleanup()
+
+		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		defer cancel()
+
+		done := make(chan struct{})
+		go func() {
+			defer close(done)
+			session.SendAndWait(ctx, MessageOptions{Prompt: "test"}) //nolint:errcheck
+		}()
+
+		select {
+		case <-requestReceived:
+		case <-time.After(2 * time.Second):
+			t.Fatal("timeout waiting for session.send request")
+		}
+
+		session.dispatchEvent(SessionEvent{
+			Type: SessionEventTypeSessionIdle,
+			Data: Data{BackgroundTasks: &BackgroundTasks{Agents: []BackgroundTasksAgent{}, Shells: []Shell{}}},
+		})
+
+		select {
+		case <-done:
+		case <-time.After(2 * time.Second):
+			t.Fatal("SendAndWait did not resolve when backgroundTasks arrays were empty")
+		}
+	})
+}
+