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);
+    }
+}