Agent Teams: stable discovery manifest for external monitoring tools

Summary

Agent Teams uses ~/.claude/teams/{team-name}/config.json as its internal coordination file. External tools that monitor Claude Code sessions (VS Code extensions, dashboards, IDE integrations) want to discover and group Agent Teams sessions, but config.json has several properties that make it unreliable as a monitoring contract.

Problem

Four specific issues with using config.json for external monitoring:

1. No version field — external parsers can't gate on schema changes or fail gracefully when the format evolves
2. No teammate session IDs — config.json has agentId (name@team format) but not the UUID that maps to the teammate's JSONL file. Tmux-mode teammates get separate top-level JONLs, but the only way to associate them with a team is scanning every JSONL and reading the first record to check for teamName/agentName fields
3. Members removed on completion — instead of marking agents as completed, they're removed from the members array. An external monitor that polls config.json loses the full team roster once agents finish, making completed teams look empty
4. No lifecycle timestamps — no completedAt, exitStatus, or updatedAt fields to track when agents finished or how

Proposed changes

Any of these would significantly improve external monitorability:

• Add a version field to config.json (or emit a separate stable manifest)
• Include teammate session UUIDs in the member entries (the UUIDs exist — they're used for the JSONL filenames)
• Retain completed members with completedAt/exitStatus instead of removing them
• Add an updatedAt timestamp so monitors can skip unchanged files

Context

We build Serac, a VS Code extension that monitors Claude Code sessions. Source is at github.com/snowmeltio/serac. We currently support multi-agent team grouping via sidecar manifests (for MCP orchestrators like Cornice) and want to extend this to Agent Teams. The current config.json schema requires heuristic JSONL scanning and shadow state caching to work around the limitations above.

Environment

• Claude Code v2.1.87
• macOS (darwin arm64)
• Tested both in-process and tmux teammate modes