Squad.Agents.AI 0.3.0: first-class subagent observability (OnSubagentTrace + OTel ActivitySource)

[tamirdresher]

Summary

Adds a first-class subagent observability surface to Squad.Agents.AI so consumers can see the coordinator's task-tool dispatch (when the coordinator spawns specialist sub-agents and synthesises their replies) without writing their own polymorphic dispatch over the raw GitHub.Copilot.SessionEvent hierarchy.

The previous 0.2.x required exactly the boilerplate the aspire-squad-resource demo had to ship: switch on every event subtype, unwrap subagent context, manage Activity lifetime. 0.3.0 makes that the SDK's job.

Bumps Squad.Agents.AI to 0.3.0.

New public surface

// 1) Typed callback. No GitHub.Copilot.SDK types leak through the signature.
options.OnSubagentTrace = trace =>
{
    if (trace.Kind == SquadAgentTraceEventKind.SubagentStarted)
        Console.WriteLine($"[spawn] {trace.SubagentName} sdkId={trace.SdkAgentId}");
    else if (trace.Kind == SquadAgentTraceEventKind.AssistantMessage && trace.SdkAgentId is not null)
        Console.WriteLine($"[{trace.SdkAgentId}] {trace.Content}"); // subagent's reply
};

// 2) Wire OpenTelemetry — one span per subagent dispatch shows up in your dashboard.
builder.Services.AddOpenTelemetry()
    .WithTracing(t => t.AddSource(SquadAgentDiagnostics.ActivitySourceName));

New type	Purpose
SquadAgentOptions.OnSubagentTrace	The single subscription point. Setting it implicitly turns on SessionConfig.IncludeSubAgentStreamingEvents so subagent replies flow up to the parent session.
SquadAgentTraceEvent record	Typed envelope: Kind, RawEventType, Timestamp, SdkAgentId, SubagentName, SubagentDisplayName, ToolCallId, Content, Success, RawEvent. The raw SDK event is preserved on RawEvent for advanced consumers but everything else is plain primitives.
SquadAgentTraceEventKind enum	Categorises the SessionEvent into well-known cases: SubagentSelected/Started/Completed/Failed, AssistantMessage, ToolStart/Complete, SessionIdle.
SquadAgentDiagnostics.ActivitySourceName ("Microsoft.Agents.AI.Squad")	Static constant for hosts to pass to .AddSource(...) on their OpenTelemetry tracer. One Activity per subagent dispatch is opened on SubagentStartedEvent, tagged with squad.subagent.name, squad.subagent.display_name, squad.subagent.sdk_agent_id, squad.subagent.reply_preview, and closed on the matching completion event.

Internal

• SquadSubagentTraceMapper (internal, InternalsVisibleTo=Squad.Agents.AI.Tests) — wires SessionEvent -> SquadAgentTraceEvent and the Activity lifecycle. Held by SquadAgent and disposed in DisposeAsync to drain subagent activities that never received a matching completed event (e.g. session ended mid-dispatch).
• Consumer callback exceptions are caught and swallowed inside the mapper so a misbehaving subscriber cannot tear down the SDK event loop.

Verification

54/54 tests passing on net8.0/net9.0/net10.0 (+8 new tests covering the observability surface: typed envelope mapping, Activity lifetime, tag propagation, mid-session disposal, callback exception isolation, unknown-event filtering).

End-to-end against the tamresearch1 Star Trek squad, asking the coordinator to dispatch two parallel subagents via the task tool. Captured trace shows both the typed callback AND the OTel spans firing on real subagent dispatch:

[OTEL start] squad.subagent Picard
[TRACE]  SUBAGENT STARTED   name='Picard' sdkId=toolu_vrtx_01XMaAa...
[OTEL start] squad.subagent Data
[TRACE]  SUBAGENT STARTED   name='Data'   sdkId=toolu_vrtx_01W52YU...
[TRACE]  MSG from=toolu_vrtx_01XMaAa...
  text=Clear boundaries between agent context and shared state — so agents can be
       composed, swapped, and reasoned about independently without hidden coupling.
[OTEL stop ] squad.subagent Picard  status=Ok
  reply=Clear boundaries between agent context and shared state...
[TRACE]  SUBAGENT COMPLETED name='Picard'
[TRACE]  MSG from=toolu_vrtx_01W52YU...
  text=Reliable, observable control flow — you need to be able to see exactly what
       the agent did, why, and reproduce it...
[OTEL stop ] squad.subagent Data  status=Ok
[TRACE]  SUBAGENT COMPLETED name='Data'

Release plan

Merging to dev triggers squad-agents-ai-release.yml. Dev branch produces 0.3.0-preview.{run_number}.

[github-actions]

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit 60933b9

PR Scope: 🔧 Infrastructure

⚠️ 2 item(s) to address before review

Status	Check	Details
✅	Single commit	1 commit — clean history
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	No source files changed — changeset not required
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
✅	Copilot threads resolved	No Copilot review threads
❌	CI passing	6 check(s) still running

Files Changed (6 files, +568 −3)

File	+/−
src/Squad.Agents.AI/Squad.Agents.AI.csproj	+2 −1
src/Squad.Agents.AI/SquadAgent.cs	+21 −2
src/Squad.Agents.AI/SquadAgentDiagnostics.cs	+124 −0
src/Squad.Agents.AI/SquadAgentOptions.cs	+44 −0
src/Squad.Agents.AI/SquadSubagentTraceMapper.cs	+136 −0
test/Squad.Agents.AI.Tests/SquadSubagentTraceTests.cs	+241 −0

Total: +568 −3

---

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

[github-actions]

🟡 Impact Analysis — PR #1265

Risk tier: 🟡 MEDIUM

📊 Summary

Metric	Count
Files changed	6
Files added	3
Files modified	3
Files deleted	0
Modules touched	2

🎯 Risk Factors

• 6 files changed (6-20 → MEDIUM)
• 2 modules touched (2-4 → MEDIUM)

📦 Modules Affected

root (5 files)

• src/Squad.Agents.AI/Squad.Agents.AI.csproj
• src/Squad.Agents.AI/SquadAgent.cs
• src/Squad.Agents.AI/SquadAgentDiagnostics.cs
• src/Squad.Agents.AI/SquadAgentOptions.cs
• src/Squad.Agents.AI/SquadSubagentTraceMapper.cs

tests (1 file)

• test/Squad.Agents.AI.Tests/SquadSubagentTraceTests.cs

---

This report is generated automatically for every PR. See #733 for details.

[Copilot]

Pull request overview

This PR evolves the Squad.Agents.AI .NET package to expose first-class subagent observability by mapping Copilot SDK SessionEvents into a typed SquadAgentTraceEvent callback surface and emitting OpenTelemetry spans via a dedicated ActivitySource, while also updating routing/config wiring for newer Copilot SDK APIs.

Changes:

• Introduces SquadAgentOptions.OnSubagentTrace, SquadAgentTraceEvent(Kind/Content/etc.), and SquadAgentDiagnostics.ActivitySourceName for typed tracing + OTel integration.
• Adds an internal SquadSubagentTraceMapper to translate SessionEvent → typed envelope and manage one Activity per subagent dispatch.
• Updates SDK integration details (WorkingDirectory/Connection-based routing) and refreshes tests + package version (0.3.0).

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/Squad.Agents.AI/SquadAgent.cs	Wires .squad config discovery, adds subagent trace mapper hookup, and updates Copilot client routing/connection logic for SDK 1.0.0-style APIs.
src/Squad.Agents.AI/SquadAgentOptions.cs	Switches to GitHub.Copilot types and adds the OnSubagentTrace public surface + docs.
src/Squad.Agents.AI/SquadAgentDiagnostics.cs	Adds diagnostics constants (ActivitySourceName), event kind enum, and the typed trace envelope record.
src/Squad.Agents.AI/SquadSubagentTraceMapper.cs	Implements event mapping + OTel Activity lifecycle per subagent dispatch.
src/Squad.Agents.AI/Squad.Agents.AI.csproj	Bumps package version to 0.3.0, adds InternalsVisibleTo, and updates package references.
test/Squad.Agents.AI.Tests/SquadSubagentTraceTests.cs	New hermetic tests for typed mapping + Activity lifecycle.
test/Squad.Agents.AI.Tests/SquadBYOKTests.cs	Updates BYOK routing-gate assertions to the new Connection model.
test/Squad.Agents.AI.Tests/SquadAgentSessionConfigTests.cs	Minor update removing an SDK namespace dependency and simplifying typing.
test/Squad.Agents.AI.Tests/SquadAgentRoutingTests.cs	Updates routing assertions to reflect WorkingDirectory/Connection args helpers.
src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/Program.cs	Improves error visibility and tightens CLI-missing detection; adds trailing whitespace that should be removed.
.gitignore	Ignores VS IDE artifacts.

Comments suppressed due to low confidence (2)

src/Squad.Agents.AI/SquadAgent.cs:250

• The code comment says the SDK default connection is only overridden when the consumer supplies a custom CLI path or extra args, but combinedCliArgs includes Squad's default --allow-all, so this condition will almost always override the SDK's default connection. Either the condition or the comment should be updated so they match.

        // Only override the SDK's default child-process connection when the consumer
        // supplied a custom CLI path or any extra CLI args. Otherwise let the SDK
        // resolve its own bundled binary (downloaded via the build/ targets).
        if (!string.IsNullOrEmpty(options.CliPath) || combinedCliArgs.Count > 0)
        {
            clientOptions.Connection = RuntimeConnection.ForStdio(options.CliPath, combinedCliArgs);
        }

src/Squad.Agents.AI/SquadAgent.cs:242

• --allow-all is injected by default when the host hasn't explicitly opted into any permission-opening flag. This bypasses the Copilot CLI's tool/path/url gates for every consumer of this library, which is a significant security change compared to only honoring explicitly provided CliArgs. Consider making this behavior opt-in (or gated behind a dedicated option) so hosted / multi-tenant scenarios don't accidentally run with full permissions.

        // ── CLI permission flags ───────────────────────────────────────────
        // The Copilot CLI enforces THREE independent permission gates:
        //   1. Tools   (--allow-all-tools)  — which tool kinds may run
        //   2. Paths   (--allow-all-paths)  — which filesystem paths may be read/written
        //   3. URLs    (--allow-all-urls)   — which URLs may be fetched
        //
        // The SDK-level `OnPermissionRequest` handler only covers the SDK protocol;
        // each CLI gate is a separate verification step. We pass `--allow-all` by
        // default so the SquadAgent can actually drive tool calls end-to-end against
        // the entire Squad workspace. Hosts that want stricter behavior can replace
        // this via SquadAgentOptions.CliArgs / the ConfigureCopilotClient delegate.
        // ───────────────────────────────────────────────────────────────────
        // Skip our `--allow-all` default if the host already opted in via any of the
        // CLI's permission-opening flags (or the omnibus `--yolo` alias). Comparison is
        // case-insensitive because `copilot --help` documents the flags in lowercase but
        // CLI argument parsers on Windows are commonly forgiving of case differences.
        var combinedCliArgs = new List<string>();
        bool hostAlreadyOpenedPermissions = options.CliArgs.Any(a =>
            string.Equals(a, "--allow-all", StringComparison.OrdinalIgnoreCase) ||
            string.Equals(a, "--allow-all-tools", StringComparison.OrdinalIgnoreCase) ||
            string.Equals(a, "--allow-all-paths", StringComparison.OrdinalIgnoreCase) ||
            string.Equals(a, "--allow-all-urls", StringComparison.OrdinalIgnoreCase) ||
            string.Equals(a, "--yolo", StringComparison.OrdinalIgnoreCase));
        if (!hostAlreadyOpenedPermissions)
        {
            combinedCliArgs.Add("--allow-all");
        }
        combinedCliArgs.AddRange(options.CliArgs);