feat: create agent-teams-guard hook plugin for team safety

[JacobPEvans]

Parent

Part of #14 (epic: migrate workaround orchestration patterns to native Claude Agent Teams)

Summary

Create a new agent-teams-guard hook plugin that provides safety guardrails for Agent Teams, preventing common issues like orphaned sessions, runaway token costs, and file conflicts between teammates.

Problem

Agent Teams have known limitations that can cause issues:

• Orphaned tmux sessions that persist after team cleanup
• Teammates editing the same files causing overwrites
• Task status lagging, blocking dependent tasks
• No token budget enforcement per teammate
• Lead sometimes starts implementing instead of delegating
• No session resumption for in-process teammates

Without guardrails, these issues silently degrade the team's effectiveness.

Proposed Solution

Plugin Structure

agent-teams-guard/
├── .claude-plugin/plugin.json
├── hooks/
│   └── hooks.json
├── scripts/
│   ├── team-file-conflict-guard.py    # PreToolUse: Write/Edit
│   └── team-session-guard.py          # SessionStart
└── README.md

Guards

1. File Conflict Guard (PreToolUse: Write|Edit)

• Checks if another teammate is currently editing the same file
• Uses file locking or git status to detect conflicts
• Blocks the edit with: "BLOCKED: teammate 'security-reviewer' is currently editing this file"
• Prevents the most common Agent Teams failure mode

2. Session Cleanup Guard (SessionStart)

• On session start, checks for orphaned team resources:
  • ~/.claude/teams/*/config.json with no active processes
  • Orphaned tmux sessions matching team patterns
• Warns user about stale team resources
• Offers cleanup commands

Alternative: Token Budget Guard (Future)

• Track cumulative tokens per teammate via team config
• Warn when teammate approaches budget
• This requires API access to token counts - may not be feasible in v1

Acceptance Criteria

• File conflict detection works between teammates
• Orphaned session detection on startup
• Clear error messages with remediation steps
• No false positives on non-team sessions
• Plugin validates with cclint
• Graceful no-op when teams are not enabled

Dependencies

• Depends on: agent-teams-orchestrator plugin (feat: create agent-teams-orchestrator plugin with team lifecycle management #15) for team config format knowledge

Design Notes

The file conflict guard is the highest value component. Agent Teams' most common failure mode is two teammates editing the same file. This guard prevents that at the hook level before the edit happens.

[JacobPEvans]

Parent epic: #14 | Depends on: #15

[claude]

This issue has had no activity for 30+ days. Is this still relevant?