feat: enrich delegate events with agent, sub_session_id, and metadata

[colombod]

Summary

Fixes inconsistencies in delegate lifecycle event payloads and adds an extensible metadata property bag to all delegate events.

Changes

Bug Fixes

• DEL-1: Added sub_session_id to all resume-path events to normalize the child session ID key name. Kept session_id for backward compatibility.
• DEL-2: Added missing agent field to all resume-path events (delegate:agent_completed, delegate:error). Agent name is extracted from the session ID suffix.

Enhancements

• DEL-3: Added metadata: dict | null property bag to all 10 delegate event emit sites. Contains namespace decomposition (namespace, agent_name) when the agent is a qualified string (e.g., "foundation:explorer").
• Replaced string literals with module-level constants (DELEGATE_AGENT_SPAWNED, etc.) to prevent typo errors.
• Added two static helper methods: _build_delegate_metadata(), _extract_agent_from_session_id().
• Added Lifecycle Events documentation section to tool-delegate/README.md.

Before (resume-path events)

# delegate:agent_resumed — missing agent, inconsistent key name
{"session_id": full_session_id, "parent_session_id": parent_session_id}

# delegate:agent_completed — missing agent
{"sub_session_id": full_session_id, "parent_session_id": parent_session_id, "success": True}

# delegate:error — missing agent, inconsistent key name
{"session_id": session_id, "parent_session_id": parent_session_id, "error": msg}

After (all paths normalized)

# All events now have: agent, sub_session_id, metadata
{"agent": "foundation:explorer", "sub_session_id": full_session_id, "parent_session_id": parent_session_id,
 "metadata": {"namespace": "foundation", "agent_name": "explorer"}}

Backward Compatibility

All changes are additive — no existing fields removed or renamed:

• session_id kept in resume-path events alongside new sub_session_id
• metadata is null when agent name cannot be decomposed
• Event constants are defined locally in tool-delegate, not in amplifier-core

Testing

• 2 resume-path tests pass (the 2 spawn-path test failures are pre-existing on main — they reference _spawn_new_session which does not exist)
• Lint and format checks pass

[bkrabach]

Thanks for working on this. The bug fixes (DEL-1, DEL-2) address real inconsistencies and the constants refactor is a clear improvement. A few things to adjust:

Accept: Constants refactor + DEL-1 + DEL-2

String-to-constant refactor, adding sub_session_id and agent to resume-path events — all good.

Field normalization: just pick one name, no aliases

Since there are zero known consumers of these events, there's no backward compatibility concern. Just normalize to sub_session_id everywhere — drop the session_id alias entirely. Clean is better than compatible-with-nothing.

Drop _extract_agent_from_session_id

The rsplit("_", 1) approach is fragile (breaks for agent names containing underscores). Rather than shipping it with fragility caveats, don't ship it. If you can't get the agent name reliably on the resume path, that's fine — leave it out of those events rather than guessing.

Drop _build_delegate_metadata and the namespace/agent_name decomposition

Don't decompose the raw agent string into metadata. The agent field carries the full qualified name (e.g., "foundation:explorer") and consumers should split it at their own site if needed. Any real helpers for this belong in the consuming hook, not in foundation — we follow the principle of not promoting patterns to this level until we have 2+ examples.

Do keep metadata on all event payloads — as an empty bag

We want "metadata": None on every delegate event. This is a deliberate philosophy choice — metadata is our established property bag for experimentation and extensibility across the ecosystem. Just don't populate it with the decomposed agent string. The hook under development can put what it needs in there; foundation provides the slot.

Summary of what the revised PR should look like:

• Constants refactor ✓
• sub_session_id on all events (no session_id alias) ✓
• agent on resume-path events where reliably available ✓
• metadata: None on all events (empty bag, no decomposition) ✓
• Remove _build_delegate_metadata() and _extract_agent_from_session_id() helpers

[colombod]

Thanks for the detailed review Brian. I have addressed all your points in the updated commit:

Constants refactor + DEL-1 + DEL-2 — Kept as accepted.

Field normalization: just pick one name, no aliases — Done. Dropped all session_id aliases from resume-path events. Every event now uses sub_session_id exclusively.

Drop _extract_agent_from_session_id — Done. Removed the method entirely. Resume-path events no longer include agent since we cannot get it reliably. The timeout error message also no longer attempts to name the agent.

Drop _build_delegate_metadata and the namespace/agent_name decomposition — Done. Removed the method entirely. No agent string decomposition anywhere.

Keep metadata on all events as an empty bag — Done. All 10 emit sites now have "metadata": None. The slot is there for consuming hooks to populate as needed.

README updated to reflect the revised event shapes and document that agent is only present on spawn-path events.