anvil-dev-framework 0.1.6

package/global/lib/agent_registry.py

@@ -0,0 +1,995 @@
+#!/usr/bin/env python3
+"""
+agent_registry.py - Global agent state management for Anvil HUD
+
+Manages the shared agent registry at ~/.anvil/agents.json that enables
+cross-terminal visibility of all active Claude Code sessions.
+
+Usage:
+    from agent_registry import AgentRegistry
+
+    # Register an agent
+    registry = AgentRegistry()
+    registry.register(agent_id="agent-alpha", project="/path/to/project", ...)
+
+    # Update an agent
+    registry.update(agent_id="agent-alpha", context_usage=32, phase="implement")
+
+    # Deregister an agent
+    registry.deregister(agent_id="agent-alpha")
+
+    # Get all agents
+    agents = registry.get_all()
+"""
+
+import fcntl
+import json
+import os
+import signal
+import tempfile
+import time
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Generator, List, Optional, TypedDict
+
+
+def process_exists(pid: int) -> bool:
+    """Check if a process with the given PID is still running.
+
+    Uses signal 0 which doesn't actually send a signal but checks
+    if the process exists and we have permission to send signals to it.
+
+    Args:
+        pid: Process ID to check
+
+    Returns:
+        True if process exists, False otherwise
+    """
+    if pid <= 0:
+        return False
+    try:
+        os.kill(pid, 0)  # Signal 0 just checks existence
+        return True
+    except ProcessLookupError:
+        return False  # Process doesn't exist
+    except PermissionError:
+        return True  # Process exists but we can't signal it
+    except OSError:
+        return False
+
+
+# =============================================================================
+# File Locking (ANV-223)
+# =============================================================================
+
+# Global lock file path
+LOCK_FILE = Path.home() / ".anvil" / "agents.lock"
+CODENAME_MAP_FILE = Path.home() / ".anvil" / "codename_map.json"
+
+
+@contextmanager
+def registry_lock(timeout: float = 5.0) -> Generator[None, None, None]:
+    """Context manager for atomic registry operations using file locking.
+
+    Uses fcntl.flock for advisory locking. This ensures that multiple
+    agents registering simultaneously won't get the same codename.
+
+    Args:
+        timeout: Maximum seconds to wait for lock (default 5s)
+
+    Yields:
+        None when lock is acquired
+
+    Raises:
+        TimeoutError: If lock cannot be acquired within timeout
+    """
+    LOCK_FILE.parent.mkdir(parents=True, exist_ok=True)
+
+    lock_fd = os.open(str(LOCK_FILE), os.O_CREAT | os.O_RDWR)
+    try:
+        start_time = time.time()
+        while True:
+            try:
+                fcntl.flock(lock_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                break  # Lock acquired
+            except BlockingIOError:
+                if time.time() - start_time > timeout:
+                    raise TimeoutError(f"Could not acquire registry lock within {timeout}s")
+                time.sleep(0.05)  # Wait 50ms and retry
+
+        yield
+    finally:
+        fcntl.flock(lock_fd, fcntl.LOCK_UN)
+        os.close(lock_fd)
+
+
+def _load_codename_map() -> Dict[str, str]:
+    """Load the persistent codename mapping (agent_id -> codename).
+
+    This ensures agents keep the same codename across re-registrations
+    (e.g., after context compaction causes SessionStart to re-run).
+    """
+    if not CODENAME_MAP_FILE.exists():
+        return {}
+    try:
+        return json.loads(CODENAME_MAP_FILE.read_text())
+    except (json.JSONDecodeError, IOError):
+        return {}
+
+
+def _save_codename_map(mapping: Dict[str, str]) -> None:
+    """Save the persistent codename mapping."""
+    CODENAME_MAP_FILE.parent.mkdir(parents=True, exist_ok=True)
+    CODENAME_MAP_FILE.write_text(json.dumps(mapping, indent=2))
+
+
+def _cleanup_codename_map(active_agents: Dict[str, Any]) -> None:
+    """Remove stale entries from codename map.
+
+    Called during registration to clean up codenames for agents
+    that are no longer in the registry.
+    """
+    codename_map = _load_codename_map()
+    active_ids = set(active_agents.keys())
+
+    # Only keep mappings for currently active agents
+    cleaned = {aid: cn for aid, cn in codename_map.items() if aid in active_ids}
+
+    if len(cleaned) != len(codename_map):
+        _save_codename_map(cleaned)
+
+
+# =============================================================================
+# Cost Tracking Schema (ANV-90)
+# =============================================================================
+
+class TokenUsage(TypedDict, total=False):
+    """Token usage breakdown by type."""
+    input: int          # Input tokens (prompts)
+    output: int         # Output tokens (responses)
+    cache_read: int     # Cached tokens read (lower cost)
+    cache_write: int    # Cached tokens written
+
+
+class SessionCost(TypedDict, total=False):
+    """Cost information for a session."""
+    tokens: TokenUsage      # Token breakdown
+    cost_usd: float         # Total calculated cost in USD
+    last_updated: str       # ISO timestamp of last update
+
+
+class CostAttribution(TypedDict, total=False):
+    """Cost attributed to a specific issue."""
+    issue_id: str           # Linear issue ID (e.g., "ANV-45")
+    cost_usd: float         # Cost attributed to this issue
+    tokens: int             # Tokens used for this issue
+    started_at: str         # When work on issue started
+
+
+class CostData(TypedDict, total=False):
+    """Complete cost tracking data for an agent."""
+    session: SessionCost                    # Current session costs
+    attributed: Dict[str, CostAttribution]  # Cost by issue ID
+    daily_total: float                      # Accumulated daily cost
+    weekly_total: float                     # Accumulated weekly cost
+    last_issue: Optional[str]               # Last active issue for attribution
+
+
+# =============================================================================
+# Context Tracking Schema (ANV-98)
+# =============================================================================
+
+class ContextMetrics(TypedDict, total=False):
+    """Context window metrics for compaction estimation."""
+    usage_history: List[int]        # Rolling history of context usage values
+    delta_history: List[int]        # Rolling history of usage deltas per turn
+    avg_tokens_per_turn: float      # Calculated average tokens per turn
+    estimated_turns: Optional[int]  # Estimated turns until compaction
+    last_usage: int                 # Last recorded context usage
+
+
+def estimate_turns_until_compaction(
+    context_usage: int,
+    context_limit: int,
+    delta_history: List[int],
+    min_samples: int = 3,
+) -> Optional[int]:
+    """Estimate turns until context compaction.
+
+    Args:
+        context_usage: Current context token usage
+        context_limit: Maximum context window size
+        delta_history: List of recent usage deltas per turn
+        min_samples: Minimum samples needed for estimation
+
+    Returns:
+        Estimated turns until compaction, or None if insufficient data
+    """
+    if len(delta_history) < min_samples:
+        return None
+
+    # Use last 10 deltas for rolling average
+    recent_deltas = delta_history[-10:]
+    positive_deltas = [d for d in recent_deltas if d > 0]
+
+    if not positive_deltas:
+        return None
+
+    avg_per_turn = sum(positive_deltas) / len(positive_deltas)
+    if avg_per_turn <= 0:
+        return None
+
+    remaining = context_limit - context_usage
+    if remaining <= 0:
+        return 0
+
+    return int(remaining / avg_per_turn)
+
+
+# Claude API Pricing (per million tokens) - Updated Jan 2026
+CLAUDE_PRICING = {
+    "Opus": {
+        "input": 15.00,
+        "output": 75.00,
+        "cache_write": 18.75,
+        "cache_read": 1.50,
+    },
+    "Sonnet": {
+        "input": 3.00,
+        "output": 15.00,
+        "cache_write": 3.75,
+        "cache_read": 0.30,
+    },
+    "Haiku": {
+        "input": 0.80,
+        "output": 4.00,
+        "cache_write": 1.00,
+        "cache_read": 0.08,
+    },
+}
+
+
+def calculate_cost(tokens: TokenUsage, model: str = "Sonnet") -> float:
+    """Calculate cost in USD from token usage.
+
+    Args:
+        tokens: Token usage breakdown
+        model: Model name (Opus, Sonnet, Haiku)
+
+    Returns:
+        Cost in USD
+    """
+    pricing = CLAUDE_PRICING.get(model, CLAUDE_PRICING["Sonnet"])
+
+    cost = 0.0
+    cost += (tokens.get("input", 0) / 1_000_000) * pricing["input"]
+    cost += (tokens.get("output", 0) / 1_000_000) * pricing["output"]
+    cost += (tokens.get("cache_write", 0) / 1_000_000) * pricing["cache_write"]
+    cost += (tokens.get("cache_read", 0) / 1_000_000) * pricing["cache_read"]
+
+    return round(cost, 4)
+
+
+def get_next_codename(existing_agents: Dict[str, Any], agent_id: Optional[str] = None) -> str:
+    """Assign next available codename (A1, A2, A3...) with persistence (ANV-223).
+
+    Uses a two-layer approach:
+    1. Check persistent codename map - if agent has a saved codename, reuse it
+    2. If new agent, find lowest unused number and persist the mapping
+
+    This ensures agents keep stable identities across re-registrations
+    (e.g., after context compaction).
+
+    Args:
+        existing_agents: Current agents dict from registry
+        agent_id: Optional agent ID for persistent codename lookup
+
+    Returns:
+        Codename like "A1", "A2", etc.
+    """
+    # ANV-223: Check persistent mapping first
+    if agent_id:
+        codename_map = _load_codename_map()
+        if agent_id in codename_map:
+            return codename_map[agent_id]
+
+    # Collect used codenames from both active agents and persistent map
+    used_numbers: set[int] = set()
+
+    # From active agents
+    for agent in existing_agents.values():
+        codename = agent.get("codename", "")
+        if codename.startswith("A") and codename[1:].isdigit():
+            used_numbers.add(int(codename[1:]))
+
+    # From persistent map (in case an agent is mid-registration)
+    codename_map = _load_codename_map()
+    for codename in codename_map.values():
+        if codename.startswith("A") and codename[1:].isdigit():
+            used_numbers.add(int(codename[1:]))
+
+    # Find lowest available number starting from 1
+    next_num = 1
+    while next_num in used_numbers:
+        next_num += 1
+
+    new_codename = f"A{next_num}"
+
+    # ANV-223: Persist the mapping
+    if agent_id:
+        codename_map[agent_id] = new_codename
+        _save_codename_map(codename_map)
+
+    return new_codename
+
+
+def create_empty_cost_data() -> CostData:
+    """Create an empty cost data structure."""
+    return {
+        "session": {
+            "tokens": {
+                "input": 0,
+                "output": 0,
+                "cache_read": 0,
+                "cache_write": 0,
+            },
+            "cost_usd": 0.0,
+            "last_updated": datetime.now(timezone.utc).isoformat(),
+        },
+        "attributed": {},
+        "daily_total": 0.0,
+        "weekly_total": 0.0,
+        "last_issue": None,
+    }
+
+
+# =============================================================================
+# Agent Registry
+# =============================================================================
+
+
+class AgentRegistry:
+    """Manages the global agent registry for multi-agent visibility."""
+
+    VERSION = "1.0"
+    STALE_TIMEOUT_MINUTES = 1  # Reduced from 5 for accurate agent counts (ANV-221)
+
+    def __init__(self, base_dir: Optional[str] = None):
+        """Initialize the registry.
+
+        Args:
+            base_dir: Override base directory (default: ~/.anvil)
+        """
+        if base_dir:
+            self.base_dir = Path(base_dir)
+        else:
+            self.base_dir = Path.home() / ".anvil"
+
+        self.registry_file = self.base_dir / "agents.json"
+        self.state_dir = self.base_dir / "state"
+
+        # Ensure directories exist
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+        self.state_dir.mkdir(parents=True, exist_ok=True)
+
+    def _atomic_write(self, filepath: Path, data: Dict[str, Any]) -> None:
+        """Write data to file atomically (write temp, then rename)."""
+        dir_path = filepath.parent
+        dir_path.mkdir(parents=True, exist_ok=True)
+
+        with tempfile.NamedTemporaryFile(
+            mode='w',
+            dir=str(dir_path),
+            delete=False,
+            suffix='.tmp'
+        ) as tmp:
+            json.dump(data, tmp, indent=2)
+            tmp_path = tmp.name
+
+        os.rename(tmp_path, str(filepath))
+
+    def _read_registry(self) -> Dict[str, Any]:
+        """Read the registry file, creating if it doesn't exist."""
+        if not self.registry_file.exists():
+            return {
+                "version": self.VERSION,
+                "lastUpdated": datetime.now(timezone.utc).isoformat(),
+                "agents": {}
+            }
+
+        try:
+            with open(self.registry_file, 'r') as f:
+                return json.load(f)
+        except (json.JSONDecodeError, IOError):
+            # Corrupted file, return fresh
+            return {
+                "version": self.VERSION,
+                "lastUpdated": datetime.now(timezone.utc).isoformat(),
+                "agents": {}
+            }
+
+    def _write_registry(self, data: Dict[str, Any]) -> None:
+        """Write the registry file atomically."""
+        data["lastUpdated"] = datetime.now(timezone.utc).isoformat()
+        self._atomic_write(self.registry_file, data)
+
+    def _update_cost_data(
+        self,
+        agent: Dict[str, Any],
+        tokens_input: int,
+        tokens_output: int,
+        tokens_cache_read: int,
+        tokens_cache_write: int,
+        model: str,
+    ) -> None:
+        """Update agent's cost tracking data with new token usage.
+
+        Args:
+            agent: Agent data dict to update (mutated in place)
+            tokens_input: Input tokens from this request
+            tokens_output: Output tokens from this request
+            tokens_cache_read: Cache read tokens
+            tokens_cache_write: Cache write tokens
+            model: Model name for pricing lookup
+        """
+        now = datetime.now(timezone.utc).isoformat()
+
+        # Ensure cost structure exists (backward compat for old agents)
+        if "cost" not in agent:
+            agent["cost"] = create_empty_cost_data()
+
+        cost_data = agent["cost"]
+
+        # Ensure session structure exists
+        if "session" not in cost_data:
+            cost_data["session"] = {
+                "tokens": {"input": 0, "output": 0, "cache_read": 0, "cache_write": 0},
+                "cost_usd": 0.0,
+                "last_updated": now,
+            }
+
+        session = cost_data["session"]
+        tokens = session.get("tokens", {})
+
+        # Accumulate token counts
+        tokens["input"] = tokens.get("input", 0) + tokens_input
+        tokens["output"] = tokens.get("output", 0) + tokens_output
+        tokens["cache_read"] = tokens.get("cache_read", 0) + tokens_cache_read
+        tokens["cache_write"] = tokens.get("cache_write", 0) + tokens_cache_write
+        session["tokens"] = tokens
+
+        # Calculate total session cost
+        session["cost_usd"] = calculate_cost(tokens, model)
+        session["last_updated"] = now
+
+        # Update backward-compat sessionCost field
+        agent["sessionCost"] = session["cost_usd"]
+
+        # Attribute cost to current issue if set
+        current_issue = cost_data.get("last_issue") or agent.get("issue")
+        if current_issue:
+            if "attributed" not in cost_data:
+                cost_data["attributed"] = {}
+
+            if current_issue not in cost_data["attributed"]:
+                cost_data["attributed"][current_issue] = {
+                    "issue_id": current_issue,
+                    "cost_usd": 0.0,
+                    "tokens": 0,
+                    "started_at": now,
+                }
+
+            attr = cost_data["attributed"][current_issue]
+            request_tokens = tokens_input + tokens_output + tokens_cache_read + tokens_cache_write
+            request_cost = calculate_cost({
+                "input": tokens_input,
+                "output": tokens_output,
+                "cache_read": tokens_cache_read,
+                "cache_write": tokens_cache_write,
+            }, model)
+
+            attr["tokens"] = attr.get("tokens", 0) + request_tokens
+            attr["cost_usd"] = round(attr.get("cost_usd", 0) + request_cost, 4)
+
+    def _cleanup_stale(self, agents: Dict[str, Any]) -> Dict[str, Any]:
+        """Remove agents that are stale or whose process has died (ANV-221).
+
+        Uses a multi-layered approach:
+        1. PID check: If agent has a PID and that process is dead, remove it
+        2. Heartbeat check: If lastHeartbeat is older than timeout, remove it
+        3. Fallback to lastActivity if no heartbeat (backward compat)
+        """
+        now = datetime.now(timezone.utc)
+        cleaned = {}
+
+        for agent_id, agent in agents.items():
+            # ANV-221: Check if process is still alive first
+            pid = agent.get('pid')
+            if pid and not process_exists(pid):
+                # Process has died - this is a ghost agent
+                continue
+
+            # Check heartbeat/activity timeout
+            try:
+                # Prefer lastHeartbeat (ANV-221), fall back to lastActivity
+                timestamp_str = agent.get('lastHeartbeat') or agent.get('lastActivity', '')
+                if not timestamp_str:
+                    # No timestamp at all, keep the agent
+                    cleaned[agent_id] = agent
+                    continue
+
+                last_seen = datetime.fromisoformat(
+                    timestamp_str.replace('Z', '+00:00')
+                )
+                age_minutes = (now - last_seen).total_seconds() / 60
+
+                if age_minutes < self.STALE_TIMEOUT_MINUTES:
+                    cleaned[agent_id] = agent
+            except (ValueError, TypeError):
+                # Invalid timestamp, keep the agent
+                cleaned[agent_id] = agent
+
+        return cleaned
+
+    def register(
+        self,
+        agent_id: str,
+        project: str,
+        session_id: Optional[str] = None,
+        model: str = "Claude",
+        issue: Optional[str] = None,
+        phase: Optional[str] = None,
+    ) -> None:
+        """Register a new agent or update existing.
+
+        Uses file locking (ANV-223) to ensure atomic codename assignment
+        and prevent race conditions when multiple agents register simultaneously.
+
+        Args:
+            agent_id: Unique identifier for this agent
+            project: Absolute path to the project directory
+            session_id: Claude Code session ID
+            model: Model name (Opus, Sonnet, etc.)
+            issue: Active Linear issue key
+            phase: Current workflow phase
+        """
+        # ANV-223: Use file locking for atomic registration
+        with registry_lock():
+            registry = self._read_registry()
+
+            # Cleanup stale agents
+            registry["agents"] = self._cleanup_stale(registry["agents"])
+
+            # ANV-223: Clean up codename map for removed agents
+            _cleanup_codename_map(registry["agents"])
+
+            now = datetime.now(timezone.utc).isoformat()
+            project_name = Path(project).name if project else "unknown"
+
+            # ANV-223: Assign codename with persistence (pass agent_id for stable identity)
+            codename = get_next_codename(registry["agents"], agent_id)
+
+            # Initialize cost data structure
+            cost_data = create_empty_cost_data()
+            if issue:
+                cost_data["last_issue"] = issue
+
+            # Initialize context metrics for compaction estimation (ANV-98)
+            context_metrics: ContextMetrics = {
+                "usage_history": [],
+                "delta_history": [],
+                "avg_tokens_per_turn": 0.0,
+                "estimated_turns": None,
+                "last_usage": 0,
+            }
+
+            registry["agents"][agent_id] = {
+                "id": agent_id,
+                "codename": codename,  # Short identifier (A1, A2, A3...) for multi-agent visibility
+                "project": project,
+                "projectName": project_name,
+                "sessionId": session_id,
+                "issue": issue,
+                "phase": phase,
+                "model": model,
+                "contextUsage": 0,
+                "contextLimit": 200000,
+                "sessionCost": 0.0,  # Backward compat: simple total
+                "cost": cost_data,   # New: detailed cost tracking (ANV-90)
+                "context": context_metrics,  # New: compaction estimation (ANV-98)
+                "estimatedTurns": None,  # Convenience field for HUD
+                "pid": os.getpid(),  # ANV-221: Track process ID for crash detection
+                "lastHeartbeat": now,  # ANV-221: Separate heartbeat tracking
+                "lastActivity": now,
+                "startedAt": now,
+                "status": "active"
+            }
+
+            self._write_registry(registry)
+
+            # Also create detailed state file
+            self._write_detailed_state(agent_id, {
+                "version": self.VERSION,
+                "agentId": agent_id,
+                "codename": codename,
+                "session": {
+                    "id": session_id,
+                    "startedAt": now,
+                },
+                "workflow": {
+                    "phase": phase,
+                    "activeIssue": issue,
+                },
+                "metrics": {
+                    "model": model,
+                    "contextUsage": 0,
+                    "contextLimit": 200000,
+                    "sessionCost": 0.0,
+                },
+                "recentTools": [],
+                "git": {}
+            })
+
+    def update(
+        self,
+        agent_id: str,
+        context_usage: Optional[int] = None,
+        context_limit: Optional[int] = None,
+        session_cost: Optional[float] = None,
+        phase: Optional[str] = None,
+        issue: Optional[str] = None,
+        tool_name: Optional[str] = None,
+        tool_input: Optional[Dict] = None,
+        tool_duration: Optional[int] = None,
+        model: Optional[str] = None,
+        git_branch: Optional[str] = None,
+        # New cost tracking parameters (ANV-90)
+        tokens_input: Optional[int] = None,
+        tokens_output: Optional[int] = None,
+        tokens_cache_read: Optional[int] = None,
+        tokens_cache_write: Optional[int] = None,
+        # Transcript path for tool activity (ANV-126)
+        transcript_path: Optional[str] = None,
+        **kwargs
+    ) -> None:
+        """Update an existing agent's state.
+
+        Args:
+            agent_id: Agent to update
+            context_usage: Current context tokens used
+            context_limit: Maximum context window size
+            session_cost: Total session cost in USD (deprecated, use tokens_*)
+            phase: Current workflow phase
+            issue: Active Linear issue key
+            tool_name: Name of tool just used
+            tool_input: Tool input parameters
+            tool_duration: Tool execution time in ms
+            model: Model name
+            git_branch: Current git branch
+            tokens_input: Input tokens from this request
+            tokens_output: Output tokens from this request
+            tokens_cache_read: Cache read tokens from this request
+            tokens_cache_write: Cache write tokens from this request
+        """
+        registry = self._read_registry()
+
+        if agent_id not in registry["agents"]:
+            # Agent not registered, skip update
+            return
+
+        agent = registry["agents"][agent_id]
+        now = datetime.now(timezone.utc).isoformat()
+
+        # Update fields if provided
+        if context_limit is not None:
+            agent["contextLimit"] = context_limit
+        if phase is not None:
+            agent["phase"] = phase
+        if model is not None:
+            agent["model"] = model
+        if transcript_path is not None:
+            agent["transcriptPath"] = transcript_path
+
+        # Update context usage and track deltas for compaction estimation (ANV-98)
+        if context_usage is not None:
+            old_usage = agent.get("contextUsage", 0)
+            agent["contextUsage"] = context_usage
+
+            # Track context metrics
+            ctx = agent.get("context")
+            if ctx is None:
+                ctx = {
+                    "usage_history": [],
+                    "delta_history": [],
+                    "avg_tokens_per_turn": 0.0,
+                    "estimated_turns": None,
+                    "last_usage": 0,
+                }
+                agent["context"] = ctx
+
+            # Only track positive deltas (compaction resets to lower value)
+            if context_usage > old_usage:
+                delta = context_usage - old_usage
+                ctx["delta_history"].append(delta)
+                # Keep last 20 deltas
+                ctx["delta_history"] = ctx["delta_history"][-20:]
+
+            ctx["last_usage"] = context_usage
+            ctx["usage_history"].append(context_usage)
+            ctx["usage_history"] = ctx["usage_history"][-20:]
+
+            # Calculate estimation
+            limit = agent.get("contextLimit", 200000)
+            estimated = estimate_turns_until_compaction(
+                context_usage, limit, ctx["delta_history"]
+            )
+            ctx["estimated_turns"] = estimated
+            agent["estimatedTurns"] = estimated
+
+            # Calculate average
+            if ctx["delta_history"]:
+                positive = [d for d in ctx["delta_history"] if d > 0]
+                if positive:
+                    ctx["avg_tokens_per_turn"] = sum(positive) / len(positive)
+
+        # Handle issue change with cost attribution
+        if issue is not None:
+            old_issue = agent.get("issue")
+            agent["issue"] = issue
+
+            # Track issue change for cost attribution
+            cost_data = agent.get("cost")
+            if cost_data and issue != old_issue:
+                cost_data["last_issue"] = issue
+                # Initialize attribution entry for new issue if not exists
+                if issue and issue not in cost_data.get("attributed", {}):
+                    cost_data["attributed"][issue] = {
+                        "issue_id": issue,
+                        "cost_usd": 0.0,
+                        "tokens": 0,
+                        "started_at": now,
+                    }
+
+        # Update detailed cost tracking (ANV-90)
+        has_token_data = any([
+            tokens_input is not None,
+            tokens_output is not None,
+            tokens_cache_read is not None,
+            tokens_cache_write is not None,
+        ])
+
+        if has_token_data:
+            self._update_cost_data(
+                agent,
+                tokens_input=tokens_input or 0,
+                tokens_output=tokens_output or 0,
+                tokens_cache_read=tokens_cache_read or 0,
+                tokens_cache_write=tokens_cache_write or 0,
+                model=model or agent.get("model", "Sonnet"),
+            )
+        elif session_cost is not None:
+            # Backward compat: accept simple session_cost if no token data
+            agent["sessionCost"] = session_cost
+
+        # ANV-221: Update heartbeat timestamp on every update
+        agent["lastHeartbeat"] = now
+        agent["lastActivity"] = now
+
+        self._write_registry(registry)
+
+        # Update detailed state if we have tool info
+        if tool_name:
+            self._update_detailed_state(
+                agent_id,
+                tool_name=tool_name,
+                tool_input=tool_input,
+                tool_duration=tool_duration,
+                context_usage=context_usage,
+                context_limit=context_limit,
+                session_cost=session_cost,
+                phase=phase,
+                git_branch=git_branch
+            )
+
+    def deregister(self, agent_id: str) -> None:
+        """Remove an agent from the registry.
+
+        Also cleans up:
+        - Persistent codename mapping (ANV-223)
+        - Issue claims held by this agent (ANV-224)
+
+        Args:
+            agent_id: Agent to remove
+        """
+        registry = self._read_registry()
+
+        if agent_id in registry["agents"]:
+            del registry["agents"][agent_id]
+            self._write_registry(registry)
+
+        # ANV-223: Clean up codename mapping
+        codename_map = _load_codename_map()
+        if agent_id in codename_map:
+            del codename_map[agent_id]
+            _save_codename_map(codename_map)
+
+        # ANV-224: Release all issue claims held by this agent
+        try:
+            from claim_service import release_all_claims
+            release_all_claims(agent_id)
+        except ImportError:
+            pass  # claim_service not available yet
+
+        # Remove detailed state file
+        state_file = self.state_dir / f"{agent_id}.json"
+        if state_file.exists():
+            state_file.unlink()
+
+    def get_all(self) -> Dict[str, Any]:
+        """Get all registered agents.
+
+        Returns:
+            Dictionary of agent_id -> agent data
+        """
+        registry = self._read_registry()
+        return self._cleanup_stale(registry.get("agents", {}))
+
+    def get_agent(self, agent_id: str) -> Optional[Dict[str, Any]]:
+        """Get a specific agent's data.
+
+        Args:
+            agent_id: Agent to retrieve
+
+        Returns:
+            Agent data or None if not found
+        """
+        agents = self.get_all()
+        return agents.get(agent_id)
+
+    def get_detailed_state(self, agent_id: str) -> Optional[Dict[str, Any]]:
+        """Get detailed state for an agent.
+
+        Args:
+            agent_id: Agent to retrieve
+
+        Returns:
+            Detailed state data or None if not found
+        """
+        state_file = self.state_dir / f"{agent_id}.json"
+        if not state_file.exists():
+            return None
+
+        try:
+            with open(state_file, 'r') as f:
+                return json.load(f)
+        except (json.JSONDecodeError, IOError):
+            return None
+
+    def _write_detailed_state(self, agent_id: str, data: Dict[str, Any]) -> None:
+        """Write detailed state file for an agent."""
+        state_file = self.state_dir / f"{agent_id}.json"
+        self._atomic_write(state_file, data)
+
+    def _update_detailed_state(
+        self,
+        agent_id: str,
+        tool_name: Optional[str] = None,
+        tool_input: Optional[Dict] = None,
+        tool_duration: Optional[int] = None,
+        **kwargs
+    ) -> None:
+        """Update detailed state with new tool call."""
+        state = self.get_detailed_state(agent_id)
+        if not state:
+            return
+
+        now = datetime.now(timezone.utc).isoformat()
+
+        # Update metrics
+        for key in ['context_usage', 'context_limit', 'session_cost', 'phase']:
+            snake_key = key
+            camel_key = ''.join(
+                word.capitalize() if i > 0 else word
+                for i, word in enumerate(key.split('_'))
+            )
+            if kwargs.get(snake_key) is not None:
+                if 'metrics' in state:
+                    state['metrics'][camel_key] = kwargs[snake_key]
+                if key == 'phase' and 'workflow' in state:
+                    state['workflow']['phase'] = kwargs[snake_key]
+
+        # Add tool to recent tools
+        if tool_name:
+            tool_entry = {
+                "name": tool_name,
+                "timestamp": now,
+            }
+            if tool_input:
+                # Truncate large inputs
+                tool_entry["input"] = {
+                    k: (v[:100] + "..." if isinstance(v, str) and len(v) > 100 else v)
+                    for k, v in list(tool_input.items())[:3]
+                }
+            if tool_duration:
+                tool_entry["duration"] = tool_duration
+
+            recent_tools = state.get("recentTools", [])
+            recent_tools.insert(0, tool_entry)
+            state["recentTools"] = recent_tools[:10]  # Keep last 10
+
+        # Update git info
+        if kwargs.get('git_branch'):
+            state["git"] = state.get("git", {})
+            state["git"]["branch"] = kwargs['git_branch']
+
+        self._write_detailed_state(agent_id, state)
+
+    def count(self) -> int:
+        """Get count of active agents.
+
+        Returns:
+            Number of active agents
+        """
+        return len(self.get_all())
+
+
+# Convenience functions for use in hooks
+_registry = None
+
+def get_registry() -> AgentRegistry:
+    """Get singleton registry instance."""
+    global _registry
+    if _registry is None:
+        _registry = AgentRegistry()
+    return _registry
+
+def register_agent(**kwargs) -> None:
+    """Register an agent (convenience function)."""
+    get_registry().register(**kwargs)
+
+def update_agent(**kwargs) -> None:
+    """Update an agent (convenience function)."""
+    get_registry().update(**kwargs)
+
+def deregister_agent(agent_id: str) -> None:
+    """Deregister an agent (convenience function)."""
+    get_registry().deregister(agent_id)
+
+def get_agent_count() -> int:
+    """Get count of active agents (convenience function)."""
+    return get_registry().count()
+
+
+if __name__ == "__main__":
+    # Simple test
+    import sys
+
+    registry = AgentRegistry()
+
+    if len(sys.argv) > 1:
+        cmd = sys.argv[1]
+
+        if cmd == "register":
+            agent_id = sys.argv[2] if len(sys.argv) > 2 else f"test-agent-{int(time.time())}"
+            project = sys.argv[3] if len(sys.argv) > 3 else os.getcwd()
+            registry.register(agent_id=agent_id, project=project, model="Opus")
+            print(f"Registered: {agent_id}")
+
+        elif cmd == "list":
+            agents = registry.get_all()
+            if not agents:
+                print("No active agents")
+            else:
+                for agent_id, agent in agents.items():
+                    print(f"  {agent_id}: {agent['projectName']} ({agent.get('phase', 'unknown')})")
+
+        elif cmd == "deregister":
+            agent_id = sys.argv[2]
+            registry.deregister(agent_id)
+            print(f"Deregistered: {agent_id}")
+
+        elif cmd == "count":
+            print(registry.count())
+    else:
+        print("Usage: agent_registry.py [register|list|deregister|count] [args...]")