refactor: replace polling with direct inbox reads and teammate checks (#16)

* feat(introspection): add peek_teammate tool for non-blocking tmux status checks

* feat(opencode): add experimental lead notify via push to OpenCode session

Behind CLAUDE_TEAMS_EXPERIMENTAL_LEAD_NOTIFY env var, discover the lead
agent's OpenCode session by matching cwd against active sessions at
initialization. When enabled, push messages addressed to team-lead
directly into their session and skip long-poll blocking in poll_inbox
(which stalls the single-threaded OpenCode agent).

* refactor(introspection): replace peek_teammate with check_teammate

Evolve peek_teammate into check_teammate with richer semantics:
- Read and mark-as-read unread messages FROM the checked teammate
  (via new read_inbox_filtered helper with sender-scoped marking)
- Report their_unread_count (messages they haven't consumed)
- Output is opt-in (include_output flag, off by default)
- Dynamic tool description based on push notification availability
- Optional deferred reminder via notify_after_minutes (OpenCode push)
- Remove CLAUDE_TEAMS_EXPERIMENTAL_LEAD_NOTIFY env gate; push
  activation is now automatic when OpenCode session is discovered

* refactor(introspection): add dynamic descriptions for poll_inbox and read_inbox

* refactor: remove poll_inbox tool in favor of read_inbox and check_teammate

Author: cs50victor

README.md

@@ -23,7 +23,7 @@ Claude Code (`.mcp.json`):
   "mcpServers": {
     "claude-teams": {
       "command": "uvx",
-      "args": ["--from", "git+https://github.com/cs50victor/claude-code-teams-mcp@v0.1.0", "claude-teams"]
+      "args": ["--from", "git+https://github.com/cs50victor/claude-code-teams-mcp@v0.1.1", "claude-teams"]
     }
   }
 }
@@ -36,7 +36,7 @@ OpenCode (`~/.config/opencode/opencode.json`):
   "mcp": {
     "claude-teams": {
       "type": "local",
-      "command": ["uvx", "--from", "git+https://github.com/cs50victor/claude-code-teams-mcp@v0.1.0", "claude-teams"],
+      "command": ["uvx", "--from", "git+https://github.com/cs50victor/claude-code-teams-mcp@v0.1.1", "claude-teams"],
       "enabled": true
     }
   }
@@ -65,7 +65,7 @@ Without `CLAUDE_TEAMS_BACKENDS`, the server auto-detects the connecting client a
   "mcpServers": {
     "claude-teams": {
       "command": "uvx",
-      "args": ["--from", "git+https://github.com/cs50victor/claude-code-teams-mcp@v0.1.0", "claude-teams"],
+      "args": ["--from", "git+https://github.com/cs50victor/claude-code-teams-mcp@v0.1.1", "claude-teams"],
       "env": {
         "CLAUDE_TEAMS_BACKENDS": "claude,opencode",
         "OPENCODE_SERVER_URL": "http://localhost:4096"
@@ -84,7 +84,6 @@ Without `CLAUDE_TEAMS_BACKENDS`, the server auto-detects the connecting client a
 | `spawn_teammate` | Spawn a teammate in tmux |
 | `send_message` | Send DMs, broadcasts (lead only), shutdown/plan responses |
 | `read_inbox` | Read messages from an agent's inbox |
-| `poll_inbox` | Long-poll inbox for new messages (up to 30s) |
 | `read_config` | Read team config and member list |
 | `task_create` | Create a task (auto-incrementing ID) |
 | `task_update` | Update task status, owner, dependencies, or metadata |

src/claude_teams/messaging.py

@@ -78,6 +78,71 @@ def read_inbox(
         return list(all_msgs)
 
 
+def read_inbox_filtered(
+    team_name: str,
+    agent_name: str,
+    sender_filter: str,
+    unread_only: bool = True,
+    mark_as_read: bool = True,
+    limit: int | None = None,
+    base_dir: Path | None = None,
+) -> list[InboxMessage]:
+    """Read inbox messages filtered by sender.
+
+    When mark_as_read=True, only messages matching the sender_filter
+    (and unread_only criteria) are marked as read. Other messages in
+    the inbox are left untouched.
+
+    Args:
+        team_name: Team name.
+        agent_name: Whose inbox to read (e.g. "team-lead").
+        sender_filter: Only return messages where from_ == sender_filter.
+        unread_only: If True, skip already-read messages.
+        mark_as_read: If True, mark returned messages as read on disk.
+        limit: Max messages to return (newest N if set). Returns chronological order.
+        base_dir: Override base directory for testing.
+    """
+    path = inbox_path(team_name, agent_name, base_dir)
+    if not path.exists():
+        return []
+
+    if mark_as_read:
+        lock_path = path.parent / ".lock"
+        with file_lock(lock_path):
+            raw_list = json.loads(path.read_text())
+            all_msgs = [InboxMessage.model_validate(entry) for entry in raw_list]
+
+            selected_indices = []
+            for i, m in enumerate(all_msgs):
+                if m.from_ != sender_filter:
+                    continue
+                if unread_only and m.read:
+                    continue
+                selected_indices.append(i)
+
+            if limit is not None and len(selected_indices) > limit:
+                selected_indices = selected_indices[-limit:]
+
+            result = [all_msgs[i] for i in selected_indices]
+            if result:
+                for i in selected_indices:
+                    all_msgs[i].read = True
+                serialized = [m.model_dump(by_alias=True, exclude_none=True) for m in all_msgs]
+                path.write_text(json.dumps(serialized))
+
+            return result
+    else:
+        raw_list = json.loads(path.read_text())
+        all_msgs = [InboxMessage.model_validate(entry) for entry in raw_list]
+
+        filtered = [m for m in all_msgs if m.from_ == sender_filter]
+        if unread_only:
+            filtered = [m for m in filtered if not m.read]
+        if limit is not None and len(filtered) > limit:
+            filtered = filtered[-limit:]
+        return filtered
+
+
 def append_message(
     team_name: str,
     agent_name: str,

src/claude_teams/opencode_client.py

@@ -163,3 +163,37 @@ def get_session_status(server_url: str, session_id: str) -> str:
     except json.JSONDecodeError:
         raise OpenCodeAPIError("Opencode returned invalid JSON from /session/status")
     return data.get(session_id, "unknown")
+
+
+def list_active_sessions(server_url: str) -> dict:
+    """Return mapping of session_id -> status from GET /session/status.
+
+    Only returns currently active/busy sessions, not historical ones.
+    """
+    raw = _request("GET", f"{server_url}/session/status")
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        raise OpenCodeAPIError("Opencode returned invalid JSON from /session/status")
+    if not isinstance(data, dict):
+        return {}
+    return data
+
+
+def get_session(server_url: str, session_id: str) -> dict:
+    """Return full session metadata from GET /session/{id}.
+
+    Includes id, slug, directory, title, projectID, etc.
+    """
+    raw = _request("GET", f"{server_url}/session/{session_id}")
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        raise OpenCodeAPIError(
+            f"Opencode returned invalid JSON from /session/{session_id}"
+        )
+    if not isinstance(data, dict):
+        raise OpenCodeAPIError(
+            f"Opencode returned non-object from /session/{session_id}"
+        )
+    return data