perf MCP has no visibility into subagent telemetry (child Sink/ToolCallRecorder off by design); add role-tagged child metrics #47

Summary

The perf MCP server (--perf-mcp) has no visibility into subagent (child-engine) activity. A run dominated by delegated work — Subagent, team members, Parallel branches, forks — is a blind spot in the metrics plane: the tool_* / turn_* histograms and the tool_calls_total counter only ever reflect the main session. When you're debugging a slow/heavy run that's actually spending its time inside subagents, the perf MCP shows almost nothing useful.

This is intentional today (and tested), but the design comment that made it intentional explicitly defers the proper fix. Filing to track that follow-up.

Where this is decided

internal/app/build.go (the child-engine deps builder) sets, for every child engine:

deps.Sink = nil
deps.ToolCallRecorder = nil

with the rationale (verbatim from the comment):

Telemetry stays OFF for child engines ... a sub-agent's turns/tool-calls were invisible to the operator-facing TTFT/turn-duration histograms. Restoring nil keeps byte-identity with the pre-feature child shape — without it every def-pinned / team-member / Half-B session child would double-count against the shared Sink. Distinct sub-agent telemetry tagging is a SEPARATE decision; nil is the conservative choice here.

So the off-by-design is to avoid double-counting child turns/tools against the main session's metrics — a real constraint, not an accident.

Observed impact (live)

While debugging a real mecatui session (Opus, panel review) where a single foreground Subagent was grinding ~10 tool calls, the perf MCP reported:

• tool_calls_total: 8 while the TUI subagent card showed 10 tools — the child's tools simply aren't metered.
• active_runs: 1 for the parent, but no attribution of where the time/tokens were going.
• No way, from metrics alone, to tell whether a subagent was slow, churning allocations, leaking goroutines, or wedged.

Note what is still visible (so this is scoped to the metrics plane only):

• The TUI sees subagent activity via the subagent.* / team.* / parallel.* delegation observability events (a different channel).
• Diagnostics (port.Diagnostics) are intentionally LIVE for children, correlated by agent role.
• Only the metrics sink + per-tool audit (ToolCallRecorder) are off — which is exactly the plane the perf MCP reads.

Proposed direction (the deferred "separate decision")

Don't just flip the child Sink on — that reintroduces the double-count the comment warns about. Instead add role-tagged child telemetry:

• Give the tool/turn histograms and counters an agent / role label (main vs the child role), mirroring how diagnostics already tag children with Deps.Role.
• Aggregate child observations under their label so subagent time, tokens, tool durations, and queue time are attributable without being conflated with the main session.
• Surface per-role breakdowns through the perf MCP (e.g. an optional role dimension on query_metric / the metrics summary, and a child rollup in list_slow_turns).

This makes the perf MCP genuinely useful for delegation-heavy runs (Subagent fan-out, teams, Parallel), which is increasingly the common shape.

Acceptance sketch

• Subagent/team-member/Parallel-branch tool and turn observations appear in the metrics plane, tagged by role, with no double-counting against the main session (the existing byte-identity / no-double-count tests stay green or are consciously updated).
• The perf MCP can attribute latency/usage to child roles.

Found while debugging a live session via the perf MCP on 2026-06-11. Companion to the diagnostics design (docs/design/DIAGNOSTICS.md).