Surface agent delegation lineage in list_agents and messages

[selfcontained]

Implements idea agent-lineage-provenance.

The problem

agents.parent_agent_id has always recorded who launched whom, but nothing read it back out. list_agents returned a flat list and an incoming message carried only a sender name — so an orchestrator could not tell a message from its own direct child apart from one from a grandchild two levels down. In the multi-repo build session that motivated this, a planner's research subagents messaged the orchestrator directly and it only found out afterwards, when the planner mentioned it.

Before / after, from the same live endpoint

list_agents as the orchestrator of orchestrator → planner → researcher:

Before — planner and researcher are indistinguishable peers:

[{"id":"agt_plan01","name":"planner","status":"running","latestEvent":null},
 {"id":"agt_res001","name":"researcher","status":"running","latestEvent":null}]

After:

agt_plan01   planner      relation=child       parent=orchestrator (agt_orch01)
agt_res001   researcher   relation=descendant  parent=planner (agt_plan01)
agt_solo01   stranger     relation=unrelated   parent=-

The delivered prompt for a skip-level message (researcher → orchestrator), captured from the recipient's tmux pane:

Before:

--- DISPATCH MESSAGE ---
{"from":"researcher","senderId":"agt_res001","message":"…","replyTarget":"agt_res001"}
--- END MESSAGE ---

After:

--- DISPATCH MESSAGE ---
{"from":"researcher","senderId":"agt_res001","senderRelation":"descendant",
 "delegationChain":["researcher (agt_res001)","planner (agt_plan01)","orchestrator (agt_orch01)"],
 "message":"…","replyTarget":"agt_res001"}
--- END MESSAGE ---
Provenance: researcher is not your direct child — delegation chain: researcher (agt_res001) -> planner (agt_plan01) -> orchestrator (agt_orch01, you).

A direct child's message gains "senderRelation":"child" and no provenance line — its chain is just [child, you], which tells the recipient nothing it did not already know.

Design notes

• Routing is unchanged. The idea floated rerouting a grandchild's message to its direct parent; Brad picked surfacing-only. A skip-level message still goes exactly where it was addressed, and the sender's tool result is untouched.
• The visibility boundary is unchanged. addressableAgents still scopes by repo root with a direct parent/child bypass. This PR only annotates what was already returned.
• Lineage resolves against every agent, not the caller's addressable subset. An intermediate the caller cannot address (different repo, archived) is still named via parentName, rather than two levels silently collapsing into one. Chain walking stops at the first unresolvable ancestor, terminates on a cycle, and is capped at 20 hops.

Files

• apps/server/src/agents/lineage.ts (new) — ancestorChain, relationTo, delegationChain, formatDelegationChain
• apps/server/src/server/mcp-handlers.ts — wires both into handleListAgentsForAgent and handleSendMessage
• apps/server/src/shared/mcp/messaging-tools.ts, shared/mcp/server.ts — AgentListing type + tool descriptions
• plugins/dispatch/skills/subagents/SKILL.md — four lines telling agents the list is not flat

Verification

• New apps/server/test/agent-lineage.test.ts (25 cases: missing ancestors, cycles, depth cap, every relation pair) plus 6 new handler tests.
• Full suite: 2775 + 912 + 60 passing.
• Exercised end-to-end against a live dev stack over the real agent-scoped MCP route — tools/list confirms registration, list_agents and dispatch_send_message called as three seeded agents in a real tree, delivered prompt read back off the recipient's tmux pane. Before-state captured by stashing the source and restarting the same API.

🤖 Generated with Claude Code