name	stable-agent-identity
description	Use stable agent identity fields for metadata joins and reserve instance ids for runtime bookkeeping.
domain	extension-architecture
confidence	high
source	observed

Context

This applies when an event-driven extension has to merge runtime agent events with roster or config metadata. The runtime payload often carries both a stable identity and a per-run instance id; mixing them creates brittle joins.

Patterns

Join metadata on stable identity fields such as agentName, agentDisplayName, or roster-derived ids.
If the team uses casting, load the latest casting snapshot's slot aliases into the lookup map so stable runtime names like tester or backend-dev resolve to cast identities without touching runtime instance ids.
Treat empty strings as missing before running fallback chains; blank values are common enough that ?? alone is not safe.
Treat low-confidence placeholders such as General Purpose Agent as missing when richer roster or casting metadata is available.
If the parent spawn tool (task, runSubagent, agent) carries a better cast hint in tool.execution_start.arguments, cache that {name, description} by toolCallId, bind it to the concrete runtime agentId on subagent.started, and feed it into Squad lookup before trusting generic runtime labels.
If Copilot emits subagent.selected before subagent.started, treat that selection payload as a short-lived identity hint only. Bind it to the concrete runtime agentId once subagent.started arrives, then reuse the bound hint for later updates or reconnect sync.
Use instance ids only for per-run state maps, event correlation, and last-resort labels.
If the product contract says every Copilot-present sub-agent should stay visible, keep one visible card per runtime agentId and use stable identity only to enrich name/role/description metadata.
If the product contract is “one visible card per cast identity,” add a separate stable-identity ownership seam above runtime instance ids so a reactivated old instance cannot render a second Tony/Howard/etc. card beside the current one.
If stable-identity cards usually collapse to one owner, let truly concurrent live instances coexist instead of hiding active work just because the cast name matches.
When stable-identity collapse does happen, merge the richest shared identity metadata (display name, role, description, task summary) into the surviving owner before hiding siblings so the card keeps its human name.
If duplicate-collapse is part of the contract, invoke the existing collapse helper on every seam that can (re)introduce a visible card — first render, reconnect rehydrate, and webview addSubagent — or the helper is just dead code.
If stableIdentityKey is absent, derive a fallback only from labels that already passed the low-confidence filters; never promote a runtime agentId into a stable identity key.
Keep mutable UI state (active tool label, live model, completion status) in a per-agent runtime map keyed by instance id, then enrich outgoing payloads from that single state seam.
If root-level Squad visuals are gated by coordinator/session state, keep a separate metadata context for sub-agent identity lookup so cast names do not disappear when the root gate turns Squad chrome off.
If hidden chrome still needs sub-agent enrichment, preserve the loaded agentsByKey/team metadata on the hidden context and let metadata lookup key off lookup presence rather than active.
If stable identity fields arrive blank, log that drift so the upstream contract problem is visible.

Examples

.github/extensions/copilot-avatar/lib/squad-context.mjs builds a roster lookup keyed by stable agent aliases.
.github/extensions/copilot-avatar/lib/squad-context.mjs enriches that lookup with .squad/casting/registry.json assignment snapshots so tester can resolve to Howard the Duck.
.github/extensions/copilot-avatar/main.mjs tracks live avatar state by event.agentId, which is appropriate for runtime instance ownership.
.github/extensions/copilot-avatar/main.mjs reuses that per-agent runtime state to push consistent displayName, model, and activityLabel data through started/completed/failed/tool events.
.github/extensions/copilot-avatar/main.mjs can gate root Squad chrome through getVisibleSquadContext() while still resolving sub-agent metadata from resolvedSquadContext via a dedicated helper.
.github/extensions/copilot-avatar/main.mjs can return an active: false visible context that still carries agentsByKey, teamName, and coordinatorName, so root chrome stays hidden while Copilot-owned cards still resolve cast names.
.github/extensions/copilot-avatar/main.mjs can derive a stableIdentityKey from Squad metadata / stable runtime labels, then collapse visible duplicates before calling addSubagent.
.github/extensions/copilot-avatar/main.mjs can preserve cached metadata during syncKnownSubagents() and rerun duplicate collapse there, so reconnects do not revive a generic third card.
.github/extensions/copilot-avatar/main.mjs can also keep every live Copilot-owned runtime agentId visible while still resolving each card's display name and role from Squad roster or casting metadata.
.github/extensions/copilot-avatar/content/main.js can derive a fallback identity key from resolveAvatarDisplayName() and call collapseAvatarIdentityDuplicates() inside window.addSubagent, so the page-side surface matches the extension's duplicate policy.
.github/extensions/copilot-avatar/main.mjs can cache a recent subagent.selected payload for Scribe, then attach that metadata to the first low-confidence subagent.started instance so the rendered card shows Scribe without letting selection events mint cards.
.github/extensions/copilot-avatar/main.mjs can cache task spawn metadata like name: "howard-the-duck" or description: "Howard the Duck: Run validation" from tool.execution_start, then let resolveSubagentDisplayData() prefer that hint over a later General Purpose Agent payload.
.github/extensions/copilot-avatar/main.mjs can keep two Peter Parker runtime instances visible when both still have live tool activity, but fold a stale/no-tool duplicate back into one owner once only one instance is actually working.
.github/extensions/copilot-avatar/main.mjs can merge a stale sibling's richer displayName / role / description into the surviving runtime owner so fresh-but-blank events do not wipe the visible card label.
In Squad UI flows, a placeholder SDK label like General Purpose Agent should not outrank roster names such as Howard the Duck.
Copilot SDK session-events.d.ts documents agentId as a sub-agent instance identifier and agentName / agentDisplayName as identity-bearing fields.

Anti-Patterns

Using runtime agentId to join against roster metadata.
Letting subagent.selected create or suppress cards instead of treating it as metadata-only enrichment for a later subagent.started.
Ignoring the parent spawn tool’s name / description arguments and assuming subagent.started will always carry the final cast identity.
Reusing a root-visibility gate as the only source of sub-agent roster metadata.
Letting stable-identity collapse override an explicit product rule that visibility should mirror Copilot runtime presence.
Driving visible-card ownership straight from runtime agentId when multiple live instances can resolve to the same cast identity.
Collapsing same-identity cards even when both runtime instances still have active live work.
Hiding a stale duplicate without first salvaging the best human-facing metadata into the remaining owner.
Defining stable-identity collapse helpers but never invoking them on reconnect or initial webview add.
Using separate ad hoc fallback chains per event type.
Storing model or badge state on tool-call maps after the agent id is known.
Letting "" short-circuit naming fallback and force the UI onto internal ids.
Letting generic placeholder labels outrank cast names or roster display names.