Add shell notification types and handlers across all SDKs

Add support for shell.output and shell.exit JSON-RPC notifications
that stream output from shell commands started via session.shell.exec.

Each SDK gets:
- ShellOutputNotification and ShellExitNotification types
- Session-level onShellOutput/onShellExit subscription methods
- Client-level processId-to-session routing with auto-cleanup on exit
- Process tracking via _trackShellProcess/_untrackShellProcess

The RPC method wrappers (session.rpc.shell.exec and session.rpc.shell.stop)
will be auto-generated once the @github/copilot package is updated with
the new api.schema.json.

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

Author: 2 people

dotnet/src/Client.cs

@@ -78,6 +78,7 @@ public sealed partial class CopilotClient : IDisposable, IAsyncDisposable
     private readonly List<Action<SessionLifecycleEvent>> _lifecycleHandlers = [];
     private readonly Dictionary<string, List<Action<SessionLifecycleEvent>>> _typedLifecycleHandlers = [];
     private readonly object _lifecycleHandlersLock = new();
+    private readonly ConcurrentDictionary<string, CopilotSession> _shellProcessMap = new();
     private ServerRpc? _rpc;
 
     /// <summary>
@@ -428,6 +429,9 @@ public async Task<CopilotSession> CreateSessionAsync(SessionConfig config, Cance
             session.On(config.OnEvent);
         }
         _sessions[sessionId] = session;
+        session.SetShellProcessCallbacks(
+            (processId, s) => _shellProcessMap[processId] = s,
+            processId => _shellProcessMap.TryRemove(processId, out _));
 
         try
         {
@@ -532,6 +536,9 @@ public async Task<CopilotSession> ResumeSessionAsync(string sessionId, ResumeSes
             session.On(config.OnEvent);
         }
         _sessions[sessionId] = session;
+        session.SetShellProcessCallbacks(
+            (processId, s) => _shellProcessMap[processId] = s,
+            processId => _shellProcessMap.TryRemove(processId, out _));
 
         try
         {
@@ -1202,6 +1209,8 @@ private async Task<Connection> ConnectToServerAsync(Process? cliProcess, string?
         rpc.AddLocalRpcMethod("permission.request", handler.OnPermissionRequestV2);
         rpc.AddLocalRpcMethod("userInput.request", handler.OnUserInputRequest);
         rpc.AddLocalRpcMethod("hooks.invoke", handler.OnHooksInvoke);
+        rpc.AddLocalRpcMethod("shell.output", handler.OnShellOutput);
+        rpc.AddLocalRpcMethod("shell.exit", handler.OnShellExit);
         rpc.StartListening();
 
         // Transition state to Disconnected if the JSON-RPC connection drops
@@ -1421,6 +1430,34 @@ public async Task<PermissionRequestResponseV2> OnPermissionRequestV2(string sess
                 });
             }
         }
+
+        public void OnShellOutput(string processId, string stream, string data)
+        {
+            if (client._shellProcessMap.TryGetValue(processId, out var session))
+            {
+                session.DispatchShellOutput(new ShellOutputNotification
+                {
+                    ProcessId = processId,
+                    Stream = stream,
+                    Data = data,
+                });
+            }
+        }
+
+        public void OnShellExit(string processId, int exitCode)
+        {
+            if (client._shellProcessMap.TryGetValue(processId, out var session))
+            {
+                session.DispatchShellExit(new ShellExitNotification
+                {
+                    ProcessId = processId,
+                    ExitCode = exitCode,
+                });
+                // Clean up the mapping after exit
+                client._shellProcessMap.TryRemove(processId, out _);
+                session.UntrackShellProcess(processId);
+            }
+        }
     }
 
     private class Connection(

dotnet/src/Session.cs

@@ -67,6 +67,12 @@ public sealed partial class CopilotSession : IAsyncDisposable
     private readonly SemaphoreSlim _hooksLock = new(1, 1);
     private SessionRpc? _sessionRpc;
     private int _isDisposed;
+    private event Action<ShellOutputNotification>? ShellOutputHandlers;
+    private event Action<ShellExitNotification>? ShellExitHandlers;
+    private readonly HashSet<string> _trackedProcessIds = [];
+    private readonly object _trackedProcessIdsLock = new();
+    private Action<string, CopilotSession>? _registerShellProcess;
+    private Action<string>? _unregisterShellProcess;
 
     /// <summary>
     /// Channel that serializes event dispatch. <see cref="DispatchEvent"/> enqueues;
@@ -278,6 +284,52 @@ public IDisposable On(SessionEventHandler handler)
         return new ActionDisposable(() => ImmutableInterlocked.Update(ref _eventHandlers, array => array.Remove(handler)));
     }
 
+    /// <summary>
+    /// Subscribes to shell output notifications for this session.
+    /// </summary>
+    /// <param name="handler">A callback that receives shell output notifications.</param>
+    /// <returns>An <see cref="IDisposable"/> that unsubscribes the handler when disposed.</returns>
+    /// <remarks>
+    /// Shell output notifications are streamed in chunks when commands started
+    /// via <c>session.Rpc.Shell.ExecAsync()</c> produce stdout or stderr output.
+    /// </remarks>
+    /// <example>
+    /// <code>
+    /// using var sub = session.OnShellOutput(n =>
+    /// {
+    ///     Console.WriteLine($"[{n.ProcessId}:{n.Stream}] {n.Data}");
+    /// });
+    /// </code>
+    /// </example>
+    public IDisposable OnShellOutput(Action<ShellOutputNotification> handler)
+    {
+        ShellOutputHandlers += handler;
+        return new ActionDisposable(() => ShellOutputHandlers -= handler);
+    }
+
+    /// <summary>
+    /// Subscribes to shell exit notifications for this session.
+    /// </summary>
+    /// <param name="handler">A callback that receives shell exit notifications.</param>
+    /// <returns>An <see cref="IDisposable"/> that unsubscribes the handler when disposed.</returns>
+    /// <remarks>
+    /// Shell exit notifications are sent when commands started via
+    /// <c>session.Rpc.Shell.ExecAsync()</c> complete (after all output has been streamed).
+    /// </remarks>
+    /// <example>
+    /// <code>
+    /// using var sub = session.OnShellExit(n =>
+    /// {
+    ///     Console.WriteLine($"Process {n.ProcessId} exited with code {n.ExitCode}");
+    /// });
+    /// </code>
+    /// </example>
+    public IDisposable OnShellExit(Action<ShellExitNotification> handler)
+    {
+        ShellExitHandlers += handler;
+        return new ActionDisposable(() => ShellExitHandlers -= handler);
+    }
+
     /// <summary>
     /// Enqueues an event for serial dispatch to all registered handlers.
     /// </summary>
@@ -323,6 +375,57 @@ private async Task ProcessEventsAsync()
         }
     }
 
+    /// <summary>
+    /// Dispatches a shell output notification to all registered handlers.
+    /// </summary>
+    internal void DispatchShellOutput(ShellOutputNotification notification)
+    {
+        ShellOutputHandlers?.Invoke(notification);
+    }
+
+    /// <summary>
+    /// Dispatches a shell exit notification to all registered handlers.
+    /// </summary>
+    internal void DispatchShellExit(ShellExitNotification notification)
+    {
+        ShellExitHandlers?.Invoke(notification);
+    }
+
+    /// <summary>
+    /// Track a shell process ID so notifications are routed to this session.
+    /// </summary>
+    internal void TrackShellProcess(string processId)
+    {
+        lock (_trackedProcessIdsLock)
+        {
+            _trackedProcessIds.Add(processId);
+        }
+        _registerShellProcess?.Invoke(processId, this);
+    }
+
+    /// <summary>
+    /// Stop tracking a shell process ID.
+    /// </summary>
+    internal void UntrackShellProcess(string processId)
+    {
+        lock (_trackedProcessIdsLock)
+        {
+            _trackedProcessIds.Remove(processId);
+        }
+        _unregisterShellProcess?.Invoke(processId);
+    }
+
+    /// <summary>
+    /// Set the registration callbacks for shell process tracking.
+    /// </summary>
+    internal void SetShellProcessCallbacks(
+        Action<string, CopilotSession> register,
+        Action<string> unregister)
+    {
+        _registerShellProcess = register;
+        _unregisterShellProcess = unregister;
+    }
+
     /// <summary>
     /// Registers custom tool handlers for this session.
     /// </summary>
@@ -805,6 +908,18 @@ await InvokeRpcAsync<object>(
         }
 
         _eventHandlers = ImmutableInterlocked.InterlockedExchange(ref _eventHandlers, ImmutableArray<SessionEventHandler>.Empty);
+        ShellOutputHandlers = null;
+        ShellExitHandlers = null;
+
+        lock (_trackedProcessIdsLock)
+        {
+            foreach (var processId in _trackedProcessIds)
+            {
+                _unregisterShellProcess?.Invoke(processId);
+            }
+            _trackedProcessIds.Clear();
+        }
+
         _toolHandlers.Clear();
 
         _permissionHandler = null;

dotnet/src/Types.cs

@@ -1943,6 +1943,54 @@ public class SessionLifecycleEvent
     public SessionLifecycleEventMetadata? Metadata { get; set; }
 }
 
+// ============================================================================
+// Shell Notification Types
+// ============================================================================
+
+/// <summary>
+/// Notification sent when a shell command produces output.
+/// Streamed in chunks (up to 64KB per notification).
+/// </summary>
+public class ShellOutputNotification
+{
+    /// <summary>
+    /// Process identifier returned by shell.exec.
+    /// </summary>
+    [JsonPropertyName("processId")]
+    public string ProcessId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Which output stream produced this chunk ("stdout" or "stderr").
+    /// </summary>
+    [JsonPropertyName("stream")]
+    public string Stream { get; set; } = string.Empty;
+
+    /// <summary>
+    /// The output data (UTF-8 string).
+    /// </summary>
+    [JsonPropertyName("data")]
+    public string Data { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// Notification sent when a shell command exits.
+/// Sent after all output has been streamed.
+/// </summary>
+public class ShellExitNotification
+{
+    /// <summary>
+    /// Process identifier returned by shell.exec.
+    /// </summary>
+    [JsonPropertyName("processId")]
+    public string ProcessId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Process exit code (0 = success).
+    /// </summary>
+    [JsonPropertyName("exitCode")]
+    public int ExitCode { get; set; }
+}
+
 /// <summary>
 /// Response from session.getForeground
 /// </summary>
@@ -2007,6 +2055,8 @@ public class SetForegroundSessionResponse
 [JsonSerializable(typeof(SessionContext))]
 [JsonSerializable(typeof(SessionLifecycleEvent))]
 [JsonSerializable(typeof(SessionLifecycleEventMetadata))]
+[JsonSerializable(typeof(ShellExitNotification))]
+[JsonSerializable(typeof(ShellOutputNotification))]
 [JsonSerializable(typeof(SessionListFilter))]
 [JsonSerializable(typeof(SessionMetadata))]
 [JsonSerializable(typeof(SetForegroundSessionResponse))]

go/client.go

@@ -91,6 +91,8 @@ type Client struct {
 	lifecycleHandlers         []SessionLifecycleHandler
 	typedLifecycleHandlers    map[SessionLifecycleEventType][]SessionLifecycleHandler
 	lifecycleHandlersMux      sync.Mutex
+	shellProcessMap           map[string]*Session
+	shellProcessMapMux        sync.Mutex
 	startStopMux              sync.RWMutex // protects process and state during start/[force]stop
 	processDone               chan struct{}
 	processErrorPtr           *error
@@ -130,6 +132,7 @@ func NewClient(options *ClientOptions) *Client {
 		options:          opts,
 		state:            StateDisconnected,
 		sessions:         make(map[string]*Session),
+		shellProcessMap:  make(map[string]*Session),
 		actualHost:       "localhost",
 		isExternalServer: false,
 		useStdio:         true,
@@ -535,6 +538,7 @@ func (c *Client) CreateSession(ctx context.Context, config *SessionConfig) (*Ses
 	// Create and register the session before issuing the RPC so that
 	// events emitted by the CLI (e.g. session.start) are not dropped.
 	session := newSession(sessionID, c.client, "")
+	session.setShellProcessCallbacks(c.registerShellProcess, c.unregisterShellProcess)
 
 	session.registerTools(config.Tools)
 	session.registerPermissionHandler(config.OnPermissionRequest)
@@ -648,6 +652,7 @@ func (c *Client) ResumeSessionWithOptions(ctx context.Context, sessionID string,
 	// Create and register the session before issuing the RPC so that
 	// events emitted by the CLI (e.g. session.start) are not dropped.
 	session := newSession(sessionID, c.client, "")
+	session.setShellProcessCallbacks(c.registerShellProcess, c.unregisterShellProcess)
 
 	session.registerTools(config.Tools)
 	session.registerPermissionHandler(config.OnPermissionRequest)
@@ -1379,6 +1384,8 @@ func (c *Client) setupNotificationHandler() {
 	c.client.SetRequestHandler("permission.request", jsonrpc2.RequestHandlerFor(c.handlePermissionRequestV2))
 	c.client.SetRequestHandler("userInput.request", jsonrpc2.RequestHandlerFor(c.handleUserInputRequest))
 	c.client.SetRequestHandler("hooks.invoke", jsonrpc2.RequestHandlerFor(c.handleHooksInvoke))
+	c.client.SetRequestHandler("shell.output", jsonrpc2.NotificationHandlerFor(c.handleShellOutput))
+	c.client.SetRequestHandler("shell.exit", jsonrpc2.NotificationHandlerFor(c.handleShellExit))
 }
 
 func (c *Client) handleSessionEvent(req sessionEventRequest) {
@@ -1395,6 +1402,43 @@ func (c *Client) handleSessionEvent(req sessionEventRequest) {
 	}
 }
 
+func (c *Client) handleShellOutput(notification ShellOutputNotification) {
+	c.shellProcessMapMux.Lock()
+	session, ok := c.shellProcessMap[notification.ProcessID]
+	c.shellProcessMapMux.Unlock()
+
+	if ok {
+		session.dispatchShellOutput(notification)
+	}
+}
+
+func (c *Client) handleShellExit(notification ShellExitNotification) {
+	c.shellProcessMapMux.Lock()
+	session, ok := c.shellProcessMap[notification.ProcessID]
+	c.shellProcessMapMux.Unlock()
+
+	if ok {
+		session.dispatchShellExit(notification)
+		// Clean up the mapping after exit
+		c.shellProcessMapMux.Lock()
+		delete(c.shellProcessMap, notification.ProcessID)
+		c.shellProcessMapMux.Unlock()
+		session.untrackShellProcess(notification.ProcessID)
+	}
+}
+
+func (c *Client) registerShellProcess(processID string, session *Session) {
+	c.shellProcessMapMux.Lock()
+	c.shellProcessMap[processID] = session
+	c.shellProcessMapMux.Unlock()
+}
+
+func (c *Client) unregisterShellProcess(processID string) {
+	c.shellProcessMapMux.Lock()
+	delete(c.shellProcessMap, processID)
+	c.shellProcessMapMux.Unlock()
+}
+
 // handleUserInputRequest handles a user input request from the CLI server.
 func (c *Client) handleUserInputRequest(req userInputRequest) (*userInputResponse, *jsonrpc2.Error) {
 	if req.SessionID == "" || req.Question == "" {