From 60933b91ebebcae14bf48b6c762964aa545dec81 Mon Sep 17 00:00:00 2001
From: Tamir Dresher <tamirdresher@users.noreply.github.com>
Date: Thu, 11 Jun 2026 09:27:50 +0300
Subject: [PATCH] Squad.Agents.AI 0.3.0: first-class subagent observability
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a typed OnSubagentTrace callback + OpenTelemetry ActivitySource so consumers
can see subagent dispatch (the coordinator's 'task' tool spawning specialist
sub-agents and their replies) without writing their own polymorphic dispatch over
the raw GitHub.Copilot SessionEvent hierarchy.

The previous 0.2.x surface required consumers to write the same boilerplate the
aspire-squad-resource demo had to (CopilotSessionTraceMapper.cs): switch on every
event subtype, unwrap subagent context, manage Activity lifetime. 0.3.0 makes that
the SDK's job.

New public surface:

* SquadAgentOptions.OnSubagentTrace (Action<SquadAgentTraceEvent>)
  Set this to subscribe to subagent lifecycle (Selected / Started / Completed /
  Failed), assistant messages from coordinator AND subagents, tool start/complete,
  and SessionIdle. Setting OnSubagentTrace implicitly turns on
  SessionConfig.IncludeSubAgentStreamingEvents so subagent replies actually flow
  up to the parent session (otherwise they stay inside the subagent session and
  never reach the callback).

* SquadAgentTraceEvent record — typed envelope (Kind, RawEventType, Timestamp,
  SdkAgentId, SubagentName, SubagentDisplayName, ToolCallId, Content, Success,
  RawEvent). Carries the original SessionEvent on RawEvent for advanced consumers
  but exposes everything else through neutral primitive types so the callback
  signature has no transitive dependency on GitHub.Copilot.SDK.

* SquadAgentTraceEventKind enum — categorises the SessionEvent into the well-known
  cases that downstream observability surfaces want.

* SquadAgentDiagnostics.ActivitySourceName ('Microsoft.Agents.AI.Squad') +
  SquadAgentDiagnostics.ActivitySource — one Activity per subagent dispatch is
  opened on SubagentStartedEvent and disposed on the matching
  SubagentCompletedEvent / SubagentFailedEvent, tagged with squad.subagent.name,
  squad.subagent.display_name, squad.subagent.sdk_agent_id, and
  squad.subagent.reply_preview (a short truncated copy of the subagent's
  assistant message). Hosts that .AddSource(SquadAgentDiagnostics.ActivitySourceName)
  on their OpenTelemetry tracer get these spans in their backend — the Aspire
  dashboard renders them in the trace view automatically.

Internal:

* SquadSubagentTraceMapper — wires SessionEvent -> SquadAgentTraceEvent and the
  Activity lifecycle. Held by SquadAgent and disposed during DisposeAsync to
  drain any subagent activities that never received a matching Completed event
  (e.g. session ended mid-dispatch).

* InternalsVisibleTo=Squad.Agents.AI.Tests so the mapper can be unit tested
  directly without spinning a real CLI session.

Tests: 54/54 passing across net8, net9, net10 (+8 new tests for the
observability surface including Activity lifetime, tag propagation, mid-session
disposal, and consumer-callback exception isolation).

Verified end-to-end against the tamresearch1 Star Trek squad: the OnSubagentTrace
callback observed two parallel subagent dispatches (Picard, Data), captured each
of their replies attributed to the right SdkAgentId, and the matching
'squad.subagent Picard' / 'squad.subagent Data' OTel spans opened and closed
cleanly with the reply tagged on each span.

Version bumped 0.2.0 -> 0.3.0 to signal the new public surface.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 src/Squad.Agents.AI/Squad.Agents.AI.csproj    |   3 +-
 src/Squad.Agents.AI/SquadAgent.cs             |  23 +-
 src/Squad.Agents.AI/SquadAgentDiagnostics.cs  | 124 +++++++++
 src/Squad.Agents.AI/SquadAgentOptions.cs      |  44 ++++
 .../SquadSubagentTraceMapper.cs               | 136 ++++++++++
 .../SquadSubagentTraceTests.cs                | 241 ++++++++++++++++++
 6 files changed, 568 insertions(+), 3 deletions(-)
 create mode 100644 src/Squad.Agents.AI/SquadAgentDiagnostics.cs
 create mode 100644 src/Squad.Agents.AI/SquadSubagentTraceMapper.cs
 create mode 100644 test/Squad.Agents.AI.Tests/SquadSubagentTraceTests.cs

diff --git a/src/Squad.Agents.AI/Squad.Agents.AI.csproj b/src/Squad.Agents.AI/Squad.Agents.AI.csproj
index 7e0343c50..7ed9a7aab 100644
--- a/src/Squad.Agents.AI/Squad.Agents.AI.csproj
+++ b/src/Squad.Agents.AI/Squad.Agents.AI.csproj
@@ -17,12 +17,13 @@
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
     <PackageReadmeFile>README.md</PackageReadmeFile>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
-    <Version>0.2.0</Version>
+    <Version>0.3.0</Version>
   </PropertyGroup>
   <ItemGroup>
     <Compile Remove="samples/**/*.cs" />
   </ItemGroup>
   <ItemGroup>
+    <InternalsVisibleTo Include="Squad.Agents.AI.Tests" />
     <PackageReference Include="Microsoft.Agents.AI.GitHub.Copilot" Version="1.10.0-rc1" />
     <!--
       Direct reference to GitHub.Copilot.SDK so its build/ targets fire during our build.
diff --git a/src/Squad.Agents.AI/SquadAgent.cs b/src/Squad.Agents.AI/SquadAgent.cs
index b457b7e92..f629d5244 100644
--- a/src/Squad.Agents.AI/SquadAgent.cs
+++ b/src/Squad.Agents.AI/SquadAgent.cs
@@ -27,6 +27,7 @@ public sealed class SquadAgent : DelegatingAIAgent, IAsyncDisposable
     private readonly ILogger? _logger;
     private readonly bool _ownsClient;
     private readonly SquadAgentOptions _options;
+    private readonly SquadSubagentTraceMapper? _traceMapper;
 
     // State-bag to thread pre-base-ctor state through chain constructors.
     // DelegatingAIAgent requires the inner AIAgent at base() call time, so we
@@ -36,7 +37,8 @@ private readonly record struct SquadAgentState(
         CopilotClient CopilotClient,
         ILogger? Logger,
         bool OwnsClient,
-        SquadAgentOptions Options);
+        SquadAgentOptions Options,
+        SquadSubagentTraceMapper? TraceMapper);
 
     /// <summary>
     /// Initializes a new <see cref="SquadAgent"/> with the Squad team root as the primary required parameter.
@@ -76,6 +78,7 @@ private SquadAgent(SquadAgentState state)
         _logger = state.Logger;
         _ownsClient = state.OwnsClient;
         _options = state.Options;
+        _traceMapper = state.TraceMapper;
         _logger?.LogInformation("SquadAgent initialized with name '{AgentName}', team root '{TeamRoot}'",
             state.Options.AgentName, state.Options.SquadFolderPath);
     }
@@ -135,6 +138,18 @@ private static SquadAgentState BuildStateInternal(SquadAgentOptions options, ILo
         {
             sessionConfig.SystemMessage = new SystemMessageConfig { Content = options.Instructions };
         }
+
+        // Wire OnSubagentTrace before ConfigureSession so consumer-supplied ConfigureSession
+        // callbacks can still override or chain behind our defaults (e.g. compose multiple OnEvent
+        // handlers, replace IncludeSubAgentStreamingEvents, etc.).
+        SquadSubagentTraceMapper? traceMapper = null;
+        if (options.OnSubagentTrace is not null)
+        {
+            traceMapper = new SquadSubagentTraceMapper(options.OnSubagentTrace);
+            sessionConfig.IncludeSubAgentStreamingEvents = true;
+            sessionConfig.OnEvent = traceMapper.OnSessionEvent;
+        }
+
         options.ConfigureSession?.Invoke(sessionConfig);
 
         var inner = client.AsAIAgent(
@@ -144,7 +159,7 @@ private static SquadAgentState BuildStateInternal(SquadAgentOptions options, ILo
             name: options.AgentName ?? "Squad",
             description: null);
 
-        return new SquadAgentState(inner, client, lf?.CreateLogger<SquadAgent>(), true, options);
+        return new SquadAgentState(inner, client, lf?.CreateLogger<SquadAgent>(), true, options, traceMapper);
     }
 
     // ── Extensibility seam ──────────────────────────────────────────────
@@ -323,6 +338,10 @@ public async ValueTask DisposeAsync()
         if (InnerAgent is IAsyncDisposable innerDisposable)
             await innerDisposable.DisposeAsync().ConfigureAwait(false);
 
+        // Drain any subagent activities that never received a matching SubagentCompletedEvent
+        // (e.g. session ended mid-dispatch). Failing to do so leaks Activity instances.
+        _traceMapper?.Dispose();
+
         _logger?.LogDebug("SquadAgent disposed");
     }
 }
diff --git a/src/Squad.Agents.AI/SquadAgentDiagnostics.cs b/src/Squad.Agents.AI/SquadAgentDiagnostics.cs
new file mode 100644
index 000000000..2f245960d
--- /dev/null
+++ b/src/Squad.Agents.AI/SquadAgentDiagnostics.cs
@@ -0,0 +1,124 @@
+using System.Diagnostics;
+
+namespace Squad.Agents.AI;
+
+/// <summary>
+/// Diagnostic constants for Squad.Agents.AI. Consumers wiring OpenTelemetry should
+/// add <see cref="ActivitySourceName"/> to their tracer provider to surface subagent
+/// dispatch spans (one span per <c>task</c>-tool invocation) in their backend.
+/// </summary>
+/// <example>
+/// <code>
+/// builder.Services.AddOpenTelemetry()
+///     .WithTracing(t => t.AddSource(SquadAgentDiagnostics.ActivitySourceName));
+/// </code>
+/// </example>
+public static class SquadAgentDiagnostics
+{
+    /// <summary>
+    /// Name of the <see cref="System.Diagnostics.ActivitySource"/> Squad.Agents.AI emits spans on.
+    /// </summary>
+    public const string ActivitySourceName = "Microsoft.Agents.AI.Squad";
+
+    /// <summary>
+    /// Singleton <see cref="System.Diagnostics.ActivitySource"/> used internally to emit subagent
+    /// dispatch spans. Consumers normally do not interact with this directly; subscribe via
+    /// <c>AddSource(SquadAgentDiagnostics.ActivitySourceName)</c> on their OpenTelemetry tracer.
+    /// </summary>
+    public static readonly ActivitySource ActivitySource = new(ActivitySourceName);
+}
+
+/// <summary>
+/// Categorises the underlying <c>GitHub.Copilot.SessionEvent</c> for consumers who want a typed view
+/// without depending directly on the SDK's polymorphic event hierarchy.
+/// </summary>
+public enum SquadAgentTraceEventKind
+{
+    /// <summary>An event that does not match any of the well-known categories below.</summary>
+    Other = 0,
+
+    /// <summary>The coordinator selected a custom agent to dispatch to (precedes <see cref="SubagentStarted"/>).</summary>
+    SubagentSelected,
+
+    /// <summary>A subagent process started (the coordinator's <c>task</c> tool spawned it).</summary>
+    SubagentStarted,
+
+    /// <summary>A subagent finished and returned its result back to the coordinator.</summary>
+    SubagentCompleted,
+
+    /// <summary>A subagent terminated abnormally.</summary>
+    SubagentFailed,
+
+    /// <summary>An assistant turn completed (from the coordinator OR a subagent — see <see cref="SquadAgentTraceEvent.SdkAgentId"/>).</summary>
+    AssistantMessage,
+
+    /// <summary>A tool started executing (the <c>task</c> tool is what spawns subagents).</summary>
+    ToolStart,
+
+    /// <summary>A tool finished executing.</summary>
+    ToolComplete,
+
+    /// <summary>The session became idle (the run is complete).</summary>
+    SessionIdle,
+}
+
+/// <summary>
+/// Typed envelope around a <c>GitHub.Copilot.SessionEvent</c> for consumers who want to surface
+/// subagent dispatch + assistant messages in a UI (e.g. an Aspire dashboard) without writing their
+/// own polymorphic dispatch over the raw SDK event hierarchy.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Squad.Agents.AI converts the raw event stream into <see cref="SquadAgentTraceEvent"/> instances
+/// inside its own <c>OnEvent</c> handler when <see cref="SquadAgentOptions.OnSubagentTrace"/> is set,
+/// then invokes the consumer's callback. Consumers therefore do not need a transitive reference to
+/// <c>GitHub.Copilot.SDK</c> to subscribe to subagent activity.
+/// </para>
+/// <para>
+/// The full underlying <c>GitHub.Copilot.SessionEvent</c> is preserved on <see cref="RawEvent"/> for
+/// advanced consumers that need access to the original payload.
+/// </para>
+/// </remarks>
+public sealed record SquadAgentTraceEvent
+{
+    /// <summary>The categorised kind of event.</summary>
+    public required SquadAgentTraceEventKind Kind { get; init; }
+
+    /// <summary>The raw <c>GitHub.Copilot.SessionEvent</c> type name, e.g. <c>SubagentStartedEvent</c>.</summary>
+    public required string RawEventType { get; init; }
+
+    /// <summary>Server-assigned timestamp on the SDK event.</summary>
+    public DateTimeOffset Timestamp { get; init; }
+
+    /// <summary>
+    /// The SDK agent identifier (e.g. <c>toolu_vrtx_01Fc3uBTKapUoDDMnPUSe2ww</c>) the event is attributed to.
+    /// Null for events emitted by the root coordinator; non-null for subagent-scoped events when
+    /// <see cref="SquadAgentOptions.IncludeSubAgentStreamingEvents"/> is on.
+    /// </summary>
+    public string? SdkAgentId { get; init; }
+
+    /// <summary>Display-friendly name of the spawning subagent (e.g. <c>Picard</c>), when known.</summary>
+    public string? SubagentName { get; init; }
+
+    /// <summary>Long-form display name of the spawning subagent, when known.</summary>
+    public string? SubagentDisplayName { get; init; }
+
+    /// <summary>SDK <c>ToolCallId</c> for <see cref="SquadAgentTraceEventKind.ToolStart"/> / <see cref="SquadAgentTraceEventKind.ToolComplete"/>.</summary>
+    public string? ToolCallId { get; init; }
+
+    /// <summary>
+    /// Assistant message content for <see cref="SquadAgentTraceEventKind.AssistantMessage"/>; null for other kinds.
+    /// Consumers may treat this as the subagent's reply when <see cref="SdkAgentId"/> is non-null.
+    /// </summary>
+    public string? Content { get; init; }
+
+    /// <summary>Tool success flag, for <see cref="SquadAgentTraceEventKind.ToolComplete"/>.</summary>
+    public bool? Success { get; init; }
+
+    /// <summary>
+    /// The original underlying <c>GitHub.Copilot.SessionEvent</c> instance. Kept as <see cref="object"/> on this
+    /// type so consumers do not need a transitive reference to the SDK. Cast to the concrete event type for advanced
+    /// scenarios.
+    /// </summary>
+    public object? RawEvent { get; init; }
+}
diff --git a/src/Squad.Agents.AI/SquadAgentOptions.cs b/src/Squad.Agents.AI/SquadAgentOptions.cs
index a308b7ae3..657251ee6 100644
--- a/src/Squad.Agents.AI/SquadAgentOptions.cs
+++ b/src/Squad.Agents.AI/SquadAgentOptions.cs
@@ -136,6 +136,50 @@ public sealed class SquadAgentOptions
     [JsonIgnore]
     public Action<SessionConfig>? ConfigureSession { get; set; }
 
+    /// <summary>
+    /// Gets or sets a callback that receives <see cref="SquadAgentTraceEvent"/> instances for every
+    /// notable session event from the underlying Copilot SDK — including subagent dispatch lifecycle
+    /// (<c>task</c>-tool spawn / completion), tool calls, and assistant messages from both the root
+    /// coordinator AND each spawned subagent.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Setting this callback has three side effects:
+    /// </para>
+    /// <list type="number">
+    /// <item><see cref="GitHub.Copilot.SessionConfigBase.IncludeSubAgentStreamingEvents"/> is forced to
+    /// <see langword="true"/> so subagent assistant messages flow up to the parent session (otherwise
+    /// the subagent's reply stays inside its own session and never reaches the callback).</item>
+    /// <item>An <see cref="System.Diagnostics.ActivitySource"/> named
+    /// <see cref="SquadAgentDiagnostics.ActivitySourceName"/> emits one <see cref="System.Diagnostics.Activity"/>
+    /// per subagent dispatch, tagged with <c>squad.subagent.name</c> and a preview of the subagent's
+    /// reply. Hosts that <c>.AddSource(SquadAgentDiagnostics.ActivitySourceName)</c> on their
+    /// OpenTelemetry tracer get these spans in their backend (e.g. the Aspire dashboard).</item>
+    /// <item><see cref="ConfigureSession"/> may still override <see cref="GitHub.Copilot.SessionConfigBase.OnEvent"/>
+    /// or <see cref="GitHub.Copilot.SessionConfigBase.IncludeSubAgentStreamingEvents"/>; consumers
+    /// that need a stacked event handler should call <c>OnSubagentTrace</c> from inside their
+    /// <see cref="ConfigureSession"/> callback to compose the two.</item>
+    /// </list>
+    /// <para>
+    /// Consumer callback exceptions are caught and swallowed so a misbehaving subscriber cannot tear
+    /// down the SDK event loop. Add your own try/catch + logging inside the callback if you need to
+    /// surface those errors.
+    /// </para>
+    /// </remarks>
+    /// <example>
+    /// <code>
+    /// options.OnSubagentTrace = trace =>
+    /// {
+    ///     if (trace.Kind == SquadAgentTraceEventKind.SubagentStarted)
+    ///         Console.WriteLine($"[spawn] {trace.SubagentName} (id={trace.SdkAgentId})");
+    ///     else if (trace.Kind == SquadAgentTraceEventKind.AssistantMessage && trace.SdkAgentId is not null)
+    ///         Console.WriteLine($"[{trace.SdkAgentId}] {trace.Content}");
+    /// };
+    /// </code>
+    /// </example>
+    [JsonIgnore]
+    public Action<SquadAgentTraceEvent>? OnSubagentTrace { get; set; }
+
     private static readonly string[] TokenPatterns = { "TOKEN", "KEY", "SECRET", "HMAC", "PASSWORD", "CREDENTIAL" };
 
     private static bool IsTokenKey(string key)
diff --git a/src/Squad.Agents.AI/SquadSubagentTraceMapper.cs b/src/Squad.Agents.AI/SquadSubagentTraceMapper.cs
new file mode 100644
index 000000000..38ea5780e
--- /dev/null
+++ b/src/Squad.Agents.AI/SquadSubagentTraceMapper.cs
@@ -0,0 +1,136 @@
+using System.Diagnostics;
+using GitHub.Copilot;
+
+namespace Squad.Agents.AI;
+
+/// <summary>
+/// Converts the GitHub.Copilot SDK's polymorphic <see cref="SessionEvent"/> stream into the typed
+/// <see cref="SquadAgentTraceEvent"/> envelope and emits matching OpenTelemetry spans on
+/// <see cref="SquadAgentDiagnostics.ActivitySource"/>.
+/// </summary>
+/// <remarks>
+/// One <c>Activity</c> per subagent dispatch is opened on <see cref="SubagentStartedEvent"/> and
+/// disposed on the matching <see cref="SubagentCompletedEvent"/> / <see cref="SubagentFailedEvent"/>.
+/// Inactive subagent <c>Activity</c> instances are tracked by their <c>SdkAgentId</c> so concurrent
+/// dispatches each get their own span. The activity is kept alive in a <see cref="System.Collections.Concurrent.ConcurrentDictionary{TKey, TValue}"/>
+/// for the duration of the subagent run; if the session ends without a matching completion event
+/// (e.g. an unhandled exception in the SDK), <see cref="DisposeAll"/> drains the dictionary so spans
+/// still terminate cleanly.
+/// </remarks>
+internal sealed class SquadSubagentTraceMapper : IDisposable
+{
+    private readonly Action<SquadAgentTraceEvent>? _onTrace;
+    private readonly System.Collections.Concurrent.ConcurrentDictionary<string, Activity> _liveSubagentActivities = new(StringComparer.Ordinal);
+
+    public SquadSubagentTraceMapper(Action<SquadAgentTraceEvent>? onTrace)
+    {
+        _onTrace = onTrace;
+    }
+
+    /// <summary>Hook to set on <see cref="SessionConfigBase.OnEvent"/>.</summary>
+    public void OnSessionEvent(SessionEvent sessionEvent)
+    {
+        if (sessionEvent is null) return;
+
+        SquadAgentTraceEvent? envelope = sessionEvent switch
+        {
+            SubagentSelectedEvent s => Build(s, SquadAgentTraceEventKind.SubagentSelected, subagentName: s.Data?.AgentName),
+            SubagentStartedEvent s => Build(s, SquadAgentTraceEventKind.SubagentStarted, subagentName: s.Data?.AgentName, subagentDisplayName: s.Data?.AgentDisplayName),
+            SubagentCompletedEvent s => Build(s, SquadAgentTraceEventKind.SubagentCompleted, subagentName: s.Data?.AgentName),
+            SubagentFailedEvent s => Build(s, SquadAgentTraceEventKind.SubagentFailed, subagentName: s.Data?.AgentName, success: false),
+            AssistantMessageEvent a => Build(a, SquadAgentTraceEventKind.AssistantMessage, content: a.Data?.Content),
+            ToolExecutionStartEvent t => Build(t, SquadAgentTraceEventKind.ToolStart, toolCallId: t.Data?.ToolCallId),
+            ToolExecutionCompleteEvent t => Build(t, SquadAgentTraceEventKind.ToolComplete, toolCallId: t.Data?.ToolCallId, success: t.Data?.Success),
+            SessionIdleEvent _ => Build(sessionEvent, SquadAgentTraceEventKind.SessionIdle),
+            _ => null,
+        };
+
+        if (envelope is null) return;
+
+        // OpenTelemetry: open/close an Activity per subagent run.
+        if (envelope.Kind == SquadAgentTraceEventKind.SubagentStarted &&
+            !string.IsNullOrEmpty(envelope.SdkAgentId))
+        {
+            var activity = SquadAgentDiagnostics.ActivitySource.StartActivity(
+                $"squad.subagent {envelope.SubagentName ?? envelope.SdkAgentId}",
+                ActivityKind.Internal);
+            if (activity is not null)
+            {
+                activity.SetTag("squad.subagent.name", envelope.SubagentName);
+                activity.SetTag("squad.subagent.display_name", envelope.SubagentDisplayName);
+                activity.SetTag("squad.subagent.sdk_agent_id", envelope.SdkAgentId);
+                _liveSubagentActivities[envelope.SdkAgentId!] = activity;
+            }
+        }
+        else if (envelope.Kind == SquadAgentTraceEventKind.AssistantMessage &&
+                 !string.IsNullOrEmpty(envelope.SdkAgentId) &&
+                 _liveSubagentActivities.TryGetValue(envelope.SdkAgentId!, out var liveActivity))
+        {
+            // The subagent's assistant message is the substantive output of that dispatch. Tag the span
+            // with a short preview so backends can group spans by subagent and show the reply at a glance.
+            // We bound the preview to a sane length even though backends are free to truncate further.
+            if (!string.IsNullOrEmpty(envelope.Content))
+            {
+                var preview = envelope.Content!.Length > 512
+                    ? envelope.Content.Substring(0, 512) + "..."
+                    : envelope.Content;
+                liveActivity.SetTag("squad.subagent.reply_preview", preview);
+            }
+        }
+        else if (envelope.Kind is SquadAgentTraceEventKind.SubagentCompleted or SquadAgentTraceEventKind.SubagentFailed &&
+                 !string.IsNullOrEmpty(envelope.SdkAgentId) &&
+                 _liveSubagentActivities.TryRemove(envelope.SdkAgentId!, out var completedActivity))
+        {
+            completedActivity.SetStatus(
+                envelope.Kind == SquadAgentTraceEventKind.SubagentFailed
+                    ? ActivityStatusCode.Error
+                    : ActivityStatusCode.Ok);
+            completedActivity.Dispose();
+        }
+
+        // Deliver the typed event to the consumer last so any consumer-side side effects (logging,
+        // UI updates) see the OTel span as already open/closed.
+        try
+        {
+            _onTrace?.Invoke(envelope);
+        }
+        catch
+        {
+            // Consumer callback exceptions must never tear down the SDK event loop.
+        }
+    }
+
+    private static SquadAgentTraceEvent Build(
+        SessionEvent sessionEvent,
+        SquadAgentTraceEventKind kind,
+        string? subagentName = null,
+        string? subagentDisplayName = null,
+        string? toolCallId = null,
+        string? content = null,
+        bool? success = null)
+    {
+        return new SquadAgentTraceEvent
+        {
+            Kind = kind,
+            RawEventType = sessionEvent.GetType().Name,
+            Timestamp = sessionEvent.Timestamp,
+            SdkAgentId = sessionEvent.AgentId,
+            SubagentName = subagentName,
+            SubagentDisplayName = subagentDisplayName,
+            ToolCallId = toolCallId,
+            Content = content,
+            Success = success,
+            RawEvent = sessionEvent,
+        };
+    }
+
+    public void Dispose()
+    {
+        foreach (var (_, activity) in _liveSubagentActivities)
+        {
+            try { activity.SetStatus(ActivityStatusCode.Error, "Session ended without matching SubagentCompletedEvent"); activity.Dispose(); }
+            catch { }
+        }
+        _liveSubagentActivities.Clear();
+    }
+}
diff --git a/test/Squad.Agents.AI.Tests/SquadSubagentTraceTests.cs b/test/Squad.Agents.AI.Tests/SquadSubagentTraceTests.cs
new file mode 100644
index 000000000..9174aafc6
--- /dev/null
+++ b/test/Squad.Agents.AI.Tests/SquadSubagentTraceTests.cs
@@ -0,0 +1,241 @@
+using System.Diagnostics;
+using GitHub.Copilot;
+using Xunit;
+
+namespace Squad.Agents.AI.Tests;
+
+/// <summary>
+/// Tests for the typed subagent observability surface added in 0.3.0.
+/// Mapper is exercised directly via InternalsVisibleTo so tests stay hermetic
+/// (no live CLI session); a real end-to-end smoke test runs through the sample.
+/// </summary>
+public class SquadSubagentTraceTests
+{
+    private static SubagentStartedData MakeStartedData(string name, string? displayName = null) => new()
+    {
+        AgentName = name,
+        AgentDisplayName = displayName ?? name,
+        AgentDescription = $"{name} test agent",
+        ToolCallId = $"toolu_{name.ToLowerInvariant()}",
+    };
+
+    private static SubagentCompletedData MakeCompletedData(string name) => new()
+    {
+        AgentName = name,
+        AgentDisplayName = name,
+        ToolCallId = $"toolu_{name.ToLowerInvariant()}",
+    };
+
+    private static SubagentFailedData MakeFailedData(string name) => new()
+    {
+        AgentName = name,
+        AgentDisplayName = name,
+        ToolCallId = $"toolu_{name.ToLowerInvariant()}",
+        Error = "test failure",
+    };
+
+    private static AssistantMessageData MakeAssistantData(string content) => new()
+    {
+        Content = content,
+        MessageId = Guid.NewGuid().ToString("n"),
+    };
+
+    [Fact]
+    public void Mapper_MapsSubagentStartedEvent_ToTypedEnvelope()
+    {
+        SquadAgentTraceEvent? captured = null;
+        var mapper = new SquadSubagentTraceMapper(evt => captured = evt);
+
+        var raw = new SubagentStartedEvent
+        {
+            AgentId = "toolu_subagent_1",
+            Timestamp = DateTimeOffset.UtcNow,
+            Data = MakeStartedData("Picard", "Captain Picard"),
+        };
+        mapper.OnSessionEvent(raw);
+
+        Assert.NotNull(captured);
+        Assert.Equal(SquadAgentTraceEventKind.SubagentStarted, captured!.Kind);
+        Assert.Equal("Picard", captured.SubagentName);
+        Assert.Equal("Captain Picard", captured.SubagentDisplayName);
+        Assert.Equal("toolu_subagent_1", captured.SdkAgentId);
+        Assert.Equal("SubagentStartedEvent", captured.RawEventType);
+        Assert.Same(raw, captured.RawEvent);
+    }
+
+    [Fact]
+    public void Mapper_MapsAssistantMessageEvent_ToTypedEnvelopeWithContent()
+    {
+        SquadAgentTraceEvent? captured = null;
+        var mapper = new SquadSubagentTraceMapper(evt => captured = evt);
+
+        var raw = new AssistantMessageEvent
+        {
+            AgentId = "toolu_subagent_2",
+            Timestamp = DateTimeOffset.UtcNow,
+            Data = MakeAssistantData("Hello from the subagent."),
+        };
+        mapper.OnSessionEvent(raw);
+
+        Assert.NotNull(captured);
+        Assert.Equal(SquadAgentTraceEventKind.AssistantMessage, captured!.Kind);
+        Assert.Equal("Hello from the subagent.", captured.Content);
+        Assert.Equal("toolu_subagent_2", captured.SdkAgentId);
+    }
+
+    [Fact]
+    public void Mapper_DoesNotEmitTypedEnvelopeForUnknownEvents()
+    {
+        var deliveries = new List<SquadAgentTraceEvent>();
+        var mapper = new SquadSubagentTraceMapper(deliveries.Add);
+
+        // A bare SessionEvent doesn't match any of the well-known categories the mapper switches on;
+        // it must be silently dropped, not surfaced as a generic envelope.
+        mapper.OnSessionEvent(new SessionEvent
+        {
+            AgentId = "x",
+            Timestamp = DateTimeOffset.UtcNow,
+        });
+
+        Assert.Empty(deliveries);
+    }
+
+    [Fact]
+    public void Mapper_ConsumerCallbackException_DoesNotPropagate()
+    {
+        var mapper = new SquadSubagentTraceMapper(_ => throw new InvalidOperationException("boom"));
+
+        var ex = Record.Exception(() => mapper.OnSessionEvent(new SubagentStartedEvent
+        {
+            AgentId = "x",
+            Timestamp = DateTimeOffset.UtcNow,
+            Data = MakeStartedData("Picard"),
+        }));
+        Assert.Null(ex);
+    }
+
+    [Fact]
+    public void Mapper_EmitsActivityForSubagentStartedAndDisposesOnCompleted()
+    {
+        var startedActivities = new List<Activity>();
+        var stoppedActivities = new List<Activity>();
+        using var listener = new ActivityListener
+        {
+            ShouldListenTo = source => source.Name == SquadAgentDiagnostics.ActivitySourceName,
+            Sample = (ref ActivityCreationOptions<ActivityContext> _) => ActivitySamplingResult.AllData,
+            ActivityStarted = a => startedActivities.Add(a),
+            ActivityStopped = a => stoppedActivities.Add(a),
+        };
+        ActivitySource.AddActivityListener(listener);
+
+        using var mapper = new SquadSubagentTraceMapper(onTrace: null);
+
+        mapper.OnSessionEvent(new SubagentStartedEvent
+        {
+            AgentId = "toolu_otel_1",
+            Timestamp = DateTimeOffset.UtcNow,
+            Data = MakeStartedData("Picard", "Captain Picard"),
+        });
+        mapper.OnSessionEvent(new SubagentCompletedEvent
+        {
+            AgentId = "toolu_otel_1",
+            Timestamp = DateTimeOffset.UtcNow,
+            Data = MakeCompletedData("Picard"),
+        });
+
+        Assert.Single(startedActivities);
+        Assert.Single(stoppedActivities);
+        Assert.Equal("squad.subagent Picard", startedActivities[0].DisplayName);
+        Assert.Equal("Picard", startedActivities[0].GetTagItem("squad.subagent.name"));
+        Assert.Equal("Captain Picard", startedActivities[0].GetTagItem("squad.subagent.display_name"));
+        Assert.Equal("toolu_otel_1", startedActivities[0].GetTagItem("squad.subagent.sdk_agent_id"));
+        Assert.Equal(ActivityStatusCode.Ok, stoppedActivities[0].Status);
+    }
+
+    [Fact]
+    public void Mapper_MarksActivityErrorOnSubagentFailedEvent()
+    {
+        Activity? stopped = null;
+        using var listener = new ActivityListener
+        {
+            ShouldListenTo = source => source.Name == SquadAgentDiagnostics.ActivitySourceName,
+            Sample = (ref ActivityCreationOptions<ActivityContext> _) => ActivitySamplingResult.AllData,
+            ActivityStopped = a => stopped = a,
+        };
+        ActivitySource.AddActivityListener(listener);
+
+        using var mapper = new SquadSubagentTraceMapper(onTrace: null);
+        mapper.OnSessionEvent(new SubagentStartedEvent
+        {
+            AgentId = "toolu_fail_1",
+            Timestamp = DateTimeOffset.UtcNow,
+            Data = MakeStartedData("Worf"),
+        });
+        mapper.OnSessionEvent(new SubagentFailedEvent
+        {
+            AgentId = "toolu_fail_1",
+            Timestamp = DateTimeOffset.UtcNow,
+            Data = MakeFailedData("Worf"),
+        });
+
+        Assert.NotNull(stopped);
+        Assert.Equal(ActivityStatusCode.Error, stopped!.Status);
+    }
+
+    [Fact]
+    public void Mapper_AssistantMessageOnLiveSubagent_TagsActivityWithReplyPreview()
+    {
+        Activity? activity = null;
+        using var listener = new ActivityListener
+        {
+            ShouldListenTo = source => source.Name == SquadAgentDiagnostics.ActivitySourceName,
+            Sample = (ref ActivityCreationOptions<ActivityContext> _) => ActivitySamplingResult.AllData,
+            ActivityStarted = a => activity = a,
+        };
+        ActivitySource.AddActivityListener(listener);
+
+        using var mapper = new SquadSubagentTraceMapper(onTrace: null);
+        mapper.OnSessionEvent(new SubagentStartedEvent
+        {
+            AgentId = "toolu_msg_1",
+            Timestamp = DateTimeOffset.UtcNow,
+            Data = MakeStartedData("Data"),
+        });
+        mapper.OnSessionEvent(new AssistantMessageEvent
+        {
+            AgentId = "toolu_msg_1",
+            Timestamp = DateTimeOffset.UtcNow,
+            Data = MakeAssistantData("Captain, the answer is 42."),
+        });
+
+        Assert.NotNull(activity);
+        Assert.Equal("Captain, the answer is 42.", activity!.GetTagItem("squad.subagent.reply_preview"));
+    }
+
+    [Fact]
+    public void Mapper_DisposesAllLiveActivities_WhenSessionEndsMidDispatch()
+    {
+        var stoppedCount = 0;
+        Activity? lastStopped = null;
+        using var listener = new ActivityListener
+        {
+            ShouldListenTo = source => source.Name == SquadAgentDiagnostics.ActivitySourceName,
+            Sample = (ref ActivityCreationOptions<ActivityContext> _) => ActivitySamplingResult.AllData,
+            ActivityStopped = a => { stoppedCount++; lastStopped = a; },
+        };
+        ActivitySource.AddActivityListener(listener);
+
+        var mapper = new SquadSubagentTraceMapper(onTrace: null);
+        mapper.OnSessionEvent(new SubagentStartedEvent
+        {
+            AgentId = "toolu_leak_1",
+            Timestamp = DateTimeOffset.UtcNow,
+            Data = MakeStartedData("Seven"),
+        });
+        // never send completion — simulate abrupt session shutdown
+        mapper.Dispose();
+
+        Assert.Equal(1, stoppedCount);
+        Assert.Equal(ActivityStatusCode.Error, lastStopped!.Status);
+    }
+}