Add CLIArgs option and fix CLI process error reporting in Go SDK

- Add CLIArgs option to ClientOptions for passing extra CLI arguments
- Capture stderr from CLI process for better error messages
- Add processDone channel to signal when CLI exits unexpectedly
- Propagate process exit errors to pending JSON-RPC requests
- Add E2E test verifying error reporting when CLI fails to start

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

Author: SteveSandersonMS

go/client.go

@@ -29,10 +29,12 @@ package copilot
 
 import (
 	"bufio"
+	"bytes"
 	"context"
 	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
 	"net"
 	"os"
 	"os/exec"
@@ -85,6 +87,8 @@ type Client struct {
 	lifecycleHandlers      []SessionLifecycleHandler
 	typedLifecycleHandlers map[SessionLifecycleEventType][]SessionLifecycleHandler
 	lifecycleHandlersMux   sync.Mutex
+	stderrBuf              bytes.Buffer // captures CLI stderr for error messages
+	processDone            chan error   // signals when CLI process exits
 
 	// RPC provides typed server-scoped RPC methods.
 	// This field is nil until the client is connected via Start().
@@ -149,6 +153,9 @@ func NewClient(options *ClientOptions) *Client {
 		if options.CLIPath != "" {
 			opts.CLIPath = options.CLIPath
 		}
+		if len(options.CLIArgs) > 0 {
+			opts.CLIArgs = append([]string{}, options.CLIArgs...)
+		}
 		if options.Cwd != "" {
 			opts.Cwd = options.Cwd
 		}
@@ -1022,7 +1029,10 @@ func (c *Client) startCLIServer(ctx context.Context) error {
 		// Default to "copilot" in PATH if no embedded CLI is available and no custom path is set
 		cliPath = "copilot"
 	}
-	args := []string{"--headless", "--no-auto-update", "--log-level", c.options.LogLevel}
+
+	// Start with user-provided CLIArgs, then add SDK-managed args
+	args := append([]string{}, c.options.CLIArgs...)
+	args = append(args, "--headless", "--no-auto-update", "--log-level", c.options.LogLevel)
 
 	// Choose transport mode
 	if c.useStdio {
@@ -1087,21 +1097,32 @@ func (c *Client) startCLIServer(ctx context.Context) error {
 			return fmt.Errorf("failed to create stderr pipe: %w", err)
 		}
 
-		// Read stderr in background
+		// Read stderr in background, capturing for error messages
 		go func() {
-			scanner := bufio.NewScanner(stderr)
-			for scanner.Scan() {
-				// Optionally log stderr
-				// fmt.Fprintf(os.Stderr, "CLI stderr: %s\n", scanner.Text())
-			}
+			io.Copy(&c.stderrBuf, stderr)
 		}()
 
 		if err := c.process.Start(); err != nil {
 			return fmt.Errorf("failed to start CLI server: %w", err)
 		}
 
+		// Monitor process exit to signal pending requests
+		c.processDone = make(chan error, 1)
+		go func() {
+			err := c.process.Wait()
+			stderrOutput := strings.TrimSpace(c.stderrBuf.String())
+			if stderrOutput != "" {
+				c.processDone <- fmt.Errorf("CLI process exited: %v\nstderr: %s", err, stderrOutput)
+			} else if err != nil {
+				c.processDone <- fmt.Errorf("CLI process exited: %v", err)
+			} else {
+				c.processDone <- fmt.Errorf("CLI process exited unexpectedly")
+			}
+		}()
+
 		// Create JSON-RPC client immediately
 		c.client = jsonrpc2.NewClient(stdin, stdout)
+		c.client.SetProcessDone(c.processDone)
 		c.RPC = rpc.NewServerRpc(c.client)
 		c.setupNotificationHandler()
 		c.client.Start()

go/internal/e2e/client_test.go

@@ -1,6 +1,7 @@
 package e2e
 
 import (
+	"strings"
 	"testing"
 	"time"
 
@@ -225,4 +226,24 @@ func TestClient(t *testing.T) {
 
 		client.Stop()
 	})
+
+	t.Run("should report error with stderr when CLI fails to start", func(t *testing.T) {
+		client := copilot.NewClient(&copilot.ClientOptions{
+			CLIPath:  cliPath,
+			CLIArgs:  []string{"--nonexistent-flag-for-testing"},
+			UseStdio: copilot.Bool(true),
+		})
+		t.Cleanup(func() { client.ForceStop() })
+
+		err := client.Start(t.Context())
+		if err == nil {
+			t.Fatal("Expected Start to fail with invalid CLI args")
+		}
+
+		errStr := err.Error()
+		// Verify we get the stderr output in the error message
+		if !strings.Contains(errStr, "stderr") || !strings.Contains(errStr, "nonexistent") {
+			t.Errorf("Expected error to contain stderr output about invalid flag, got: %v", err)
+		}
+	})
 }

go/internal/jsonrpc2/jsonrpc2.go

@@ -57,6 +57,7 @@ type Client struct {
 	running         bool
 	stopChan        chan struct{}
 	wg              sync.WaitGroup
+	processDone     <-chan error // signals when the underlying process exits
 }
 
 // NewClient creates a new JSON-RPC client
@@ -70,6 +71,11 @@ func NewClient(stdin io.WriteCloser, stdout io.ReadCloser) *Client {
 	}
 }
 
+// SetProcessDone sets a channel that signals when the underlying process exits
+func (c *Client) SetProcessDone(ch <-chan error) {
+	c.processDone = ch
+}
+
 // Start begins listening for messages in a background goroutine
 func (c *Client) Start() {
 	c.running = true
@@ -189,7 +195,23 @@ func (c *Client) Request(method string, params any) (json.RawMessage, error) {
 		return nil, fmt.Errorf("failed to send request: %w", err)
 	}
 
-	// Wait for response
+	// Wait for response, also checking for process exit
+	if c.processDone != nil {
+		select {
+		case response := <-responseChan:
+			if response.Error != nil {
+				return nil, response.Error
+			}
+			return response.Result, nil
+		case err := <-c.processDone:
+			if err != nil {
+				return nil, err
+			}
+			return nil, fmt.Errorf("process exited unexpectedly")
+		case <-c.stopChan:
+			return nil, fmt.Errorf("client stopped")
+		}
+	}
 	select {
 	case response := <-responseChan:
 		if response.Error != nil {

go/types.go

@@ -16,6 +16,8 @@ const (
 type ClientOptions struct {
 	// CLIPath is the path to the Copilot CLI executable (default: "copilot")
 	CLIPath string
+	// CLIArgs are extra arguments to pass to the CLI executable (inserted before SDK-managed args)
+	CLIArgs []string
 	// Cwd is the working directory for the CLI process (default: "" = inherit from current process)
 	Cwd string
 	// Port for TCP transport (default: 0 = random port)