claude-team-mcp 0.3.2__py3-none-any.whl → 0.5.0__py3-none-any.whl

claude_team_mcp/cli_backends/__init__.py

@@ -0,0 +1,44 @@
+"""
+CLI Backends Module.
+
+Provides abstraction layer for different agent CLI tools (Claude Code, Codex, etc.)
+This allows claude-team to orchestrate multiple agent types through a unified interface.
+"""
+
+from .base import AgentCLI
+from .claude import ClaudeCLI, claude_cli
+from .codex import CodexCLI, codex_cli
+
+__all__ = [
+    "AgentCLI",
+    "ClaudeCLI",
+    "claude_cli",
+    "CodexCLI",
+    "codex_cli",
+    "get_cli_backend",
+]
+
+
+def get_cli_backend(agent_type: str = "claude") -> AgentCLI:
+    """
+    Get a CLI backend instance by agent type.
+
+    Args:
+        agent_type: The agent type ("claude" or "codex")
+
+    Returns:
+        An AgentCLI implementation instance
+
+    Raises:
+        ValueError: If the agent type is not supported
+    """
+    backends = {
+        "claude": claude_cli,
+        "codex": codex_cli,
+    }
+
+    if agent_type not in backends:
+        valid = ", ".join(sorted(backends.keys()))
+        raise ValueError(f"Unknown agent type: {agent_type}. Valid types: {valid}")
+
+    return backends[agent_type]

claude_team_mcp/cli_backends/base.py

@@ -0,0 +1,132 @@
+"""
+Base protocol for CLI agent backends.
+
+Defines the interface that all CLI backends (Claude, Codex, etc.) must implement.
+This abstraction allows claude-team to orchestrate different agent CLIs.
+"""
+
+from abc import abstractmethod
+from typing import Literal, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class AgentCLI(Protocol):
+    """
+    Protocol defining the interface for agent CLI backends.
+
+    Each implementation encapsulates the CLI-specific details:
+    - Command and arguments
+    - Ready detection patterns
+    - Idle/completion detection method
+    - Settings/hook injection support
+    """
+
+    @property
+    @abstractmethod
+    def engine_id(self) -> str:
+        """
+        Unique identifier for this CLI engine (e.g., "claude", "codex").
+
+        Used for configuration, logging, and distinguishing between backends.
+        """
+        ...
+
+    @abstractmethod
+    def command(self) -> str:
+        """
+        Return the CLI executable name or path.
+
+        Examples: "claude", "codex", "/usr/local/bin/custom-agent"
+        """
+        ...
+
+    @abstractmethod
+    def build_args(
+        self,
+        *,
+        dangerously_skip_permissions: bool = False,
+        settings_file: str | None = None,
+    ) -> list[str]:
+        """
+        Build the argument list for the CLI command.
+
+        Args:
+            dangerously_skip_permissions: If True, add flag to skip permission prompts
+            settings_file: Optional path to settings file for hook injection
+
+        Returns:
+            List of command-line arguments (not including the command itself)
+        """
+        ...
+
+    @abstractmethod
+    def ready_patterns(self) -> list[str]:
+        """
+        Return patterns that indicate the CLI is ready for input.
+
+        These patterns are searched for in terminal output to detect when
+        the agent has started and is ready to receive prompts.
+
+        Returns:
+            List of strings to search for in terminal output
+        """
+        ...
+
+    @abstractmethod
+    def idle_detection_method(self) -> Literal["stop_hook", "jsonl_stream", "none"]:
+        """
+        Return the method used to detect when the agent finishes responding.
+
+        - "stop_hook": Uses a Stop hook that fires when the agent completes
+        - "jsonl_stream": Monitors JSONL output for completion markers
+        - "none": No idle detection available (must use timeouts)
+
+        Returns:
+            The detection method identifier
+        """
+        ...
+
+    @abstractmethod
+    def supports_settings_file(self) -> bool:
+        """
+        Return whether this CLI supports --settings flag for hook injection.
+
+        If False, build_args() should ignore the settings_file parameter.
+        """
+        ...
+
+    def build_full_command(
+        self,
+        *,
+        dangerously_skip_permissions: bool = False,
+        settings_file: str | None = None,
+        env_vars: dict[str, str] | None = None,
+    ) -> str:
+        """
+        Build the complete command string including env vars.
+
+        This is a convenience method that combines command(), build_args(),
+        and optional environment variables into a single shell command string.
+
+        Args:
+            dangerously_skip_permissions: Skip permission prompts
+            settings_file: Settings file for hook injection
+            env_vars: Environment variables to prepend
+
+        Returns:
+            Complete command string ready for shell execution
+        """
+        cmd = self.command()
+        args = self.build_args(
+            dangerously_skip_permissions=dangerously_skip_permissions,
+            settings_file=settings_file if self.supports_settings_file() else None,
+        )
+
+        if args:
+            cmd = f"{cmd} {' '.join(args)}"
+
+        if env_vars:
+            env_exports = " ".join(f"{k}={v}" for k, v in env_vars.items())
+            cmd = f"{env_exports} {cmd}"
+
+        return cmd

claude_team_mcp/cli_backends/claude.py

@@ -0,0 +1,110 @@
+"""
+Claude Code CLI backend.
+
+Implements the AgentCLI protocol for Claude Code CLI.
+This preserves the existing behavior from iterm_utils.py.
+"""
+
+import os
+from typing import Literal
+
+from .base import AgentCLI
+
+
+class ClaudeCLI(AgentCLI):
+    """
+    Claude Code CLI implementation.
+
+    Supports:
+    - --dangerously-skip-permissions flag
+    - --settings flag for Stop hook injection
+    - Ready detection via TUI patterns (robot banner, '>' prompt, 'tokens' status)
+    - Idle detection via Stop hook markers in JSONL
+    """
+
+    @property
+    def engine_id(self) -> str:
+        """Return 'claude' as the engine identifier."""
+        return "claude"
+
+    def command(self) -> str:
+        """
+        Return the Claude CLI command.
+
+        Respects CLAUDE_TEAM_COMMAND environment variable for overrides
+        (e.g., "happy" wrapper).
+        """
+        return os.environ.get("CLAUDE_TEAM_COMMAND", "claude")
+
+    def build_args(
+        self,
+        *,
+        dangerously_skip_permissions: bool = False,
+        settings_file: str | None = None,
+    ) -> list[str]:
+        """
+        Build Claude CLI arguments.
+
+        Args:
+            dangerously_skip_permissions: Add --dangerously-skip-permissions
+            settings_file: Path to settings JSON for Stop hook injection
+
+        Returns:
+            List of CLI arguments
+        """
+        args: list[str] = []
+
+        if dangerously_skip_permissions:
+            args.append("--dangerously-skip-permissions")
+
+        # Only add --settings for the default 'claude' command.
+        # Custom commands like 'happy' have their own session tracking mechanisms.
+        # See HAPPY_INTEGRATION_RESEARCH.md for full analysis.
+        if settings_file and self._is_default_command():
+            args.append("--settings")
+            args.append(settings_file)
+
+        return args
+
+    def ready_patterns(self) -> list[str]:
+        """
+        Return patterns indicating Claude TUI is ready.
+
+        These patterns appear in Claude's startup:
+        - '>' prompt indicates input ready
+        - 'tokens' in status bar
+        - Parts of the robot ASCII art banner
+        """
+        return [
+            ">",  # Input prompt
+            "tokens",  # Status bar
+            "Claude Code v",  # Version line in banner
+            "▐▛███▜▌",  # Top of robot head
+            "▝▜█████▛▘",  # Middle of robot
+        ]
+
+    def idle_detection_method(self) -> Literal["stop_hook", "jsonl_stream", "none"]:
+        """
+        Claude uses Stop hook for idle detection.
+
+        A Stop hook writes a marker to the JSONL when Claude finishes responding.
+        """
+        return "stop_hook"
+
+    def supports_settings_file(self) -> bool:
+        """
+        Claude supports --settings for hook injection.
+
+        Only returns True for the default 'claude' command.
+        Custom wrappers may have their own settings mechanisms.
+        """
+        return self._is_default_command()
+
+    def _is_default_command(self) -> bool:
+        """Check if using the default 'claude' command (not a custom wrapper)."""
+        cmd = os.environ.get("CLAUDE_TEAM_COMMAND", "claude")
+        return cmd == "claude"
+
+
+# Singleton instance for convenience
+claude_cli = ClaudeCLI()

claude_team_mcp/cli_backends/codex.py

@@ -0,0 +1,110 @@
+"""
+OpenAI Codex CLI backend.
+
+Implements the AgentCLI protocol for OpenAI's Codex CLI.
+This is a basic implementation - full integration will be done in later tasks.
+
+Codex CLI reference: https://github.com/openai/codex
+"""
+
+import os
+from typing import Literal
+
+from .base import AgentCLI
+
+
+class CodexCLI(AgentCLI):
+    """
+    OpenAI Codex CLI implementation.
+
+    Note: This is a basic structure. Full Codex integration (ready detection,
+    idle detection, etc.) will be implemented in later tasks (cic-f7w.3+).
+
+    Codex CLI characteristics:
+    - Uses `codex` command
+    - Has --full-auto flag for non-interactive mode
+    - No known Stop hook equivalent (may need JSONL streaming or timeouts)
+    """
+
+    @property
+    def engine_id(self) -> str:
+        """Return 'codex' as the engine identifier."""
+        return "codex"
+
+    def command(self) -> str:
+        """
+        Return the Codex CLI command.
+
+        Respects CLAUDE_TEAM_CODEX_COMMAND environment variable for overrides
+        (e.g., "happy codex" wrapper).
+        """
+        return os.environ.get("CLAUDE_TEAM_CODEX_COMMAND", "codex")
+
+    def build_args(
+        self,
+        *,
+        dangerously_skip_permissions: bool = False,
+        settings_file: str | None = None,
+    ) -> list[str]:
+        """
+        Build Codex CLI arguments for interactive mode.
+
+        Args:
+            dangerously_skip_permissions: Maps to --full-auto for Codex
+            settings_file: Ignored - Codex doesn't support settings injection
+
+        Returns:
+            List of CLI arguments for interactive mode
+        """
+        args: list[str] = []
+
+        # Codex uses --dangerously-bypass-approvals-and-sandbox for autonomous operation
+        # (--full-auto doesn't work through happy wrapper)
+        if dangerously_skip_permissions:
+            args.append("--dangerously-bypass-approvals-and-sandbox")
+
+        # Note: settings_file is ignored - Codex doesn't support this
+        # Idle detection uses session file polling instead
+
+        return args
+
+
+    def ready_patterns(self) -> list[str]:
+        """
+        Return patterns indicating Codex CLI is ready for input.
+
+        Codex in interactive mode shows status bar when ready.
+        Updated for Codex CLI v0.80.0 behavior.
+        """
+        return [
+            "context left",  # Status bar shows "100% context left"
+            "for shortcuts",  # Status bar shows "? for shortcuts"
+            "What can I help you with?",  # Legacy prompt (older versions)
+            "codex>",  # Alternative prompt pattern
+            "»",  # Codex uses this prompt symbol
+            "Waiting for messages",  # Happy codex wrapper
+            "Codex Agent Running",  # Happy codex status bar
+        ]
+
+    def idle_detection_method(self) -> Literal["stop_hook", "jsonl_stream", "none"]:
+        """
+        Codex idle detection method.
+
+        Codex writes session files to ~/.codex/sessions/YYYY/MM/DD/.
+        The idle_detection module polls these files for agent_message
+        events which indicate the agent has finished responding.
+        """
+        return "jsonl_stream"
+
+    def supports_settings_file(self) -> bool:
+        """
+        Codex doesn't support --settings for hook injection.
+
+        Alternative completion detection methods will be needed.
+        """
+        return False
+
+
+
+# Singleton instance for convenience
+codex_cli = CodexCLI()

claude_team_mcp/formatting.py

@@ -57,19 +57,22 @@ def format_badge_text(
     name: str,
     bead: Optional[str] = None,
     annotation: Optional[str] = None,
+    agent_type: Optional[str] = None,
     max_annotation_length: int = 30,
 ) -> str:
     """
     Format badge text with bead/name on first line, annotation on second.
 
     Creates a multi-line string suitable for iTerm2 badge display:
-    - Line 1: bead ID if provided, otherwise worker name
+    - Line 1: Agent type prefix (if not "claude") + bead ID (if provided) or worker name
     - Line 2: annotation (if provided), truncated if too long
 
     Args:
         name: Worker name (used if bead not provided)
         bead: Optional bead/issue ID (e.g., "cic-3dj")
         annotation: Optional task annotation
+        agent_type: Optional agent type ("claude" or "codex"). If "codex",
+            adds a prefix to the first line.
         max_annotation_length: Maximum length for annotation line (default 30)
 
     Returns:
@@ -90,10 +93,22 @@ def format_badge_text(
 
         >>> format_badge_text("Groucho", annotation="a very long annotation here", max_annotation_length=20)
         'Groucho\\na very long annot...'
+
+        >>> format_badge_text("Groucho", agent_type="codex")
+        '[Codex] Groucho'
+
+        >>> format_badge_text("Groucho", "cic-3dj", agent_type="codex")
+        '[Codex] cic-3dj'
     """
     # First line: bead if provided, otherwise name
     first_line = bead if bead else name
 
+    # Add agent type prefix for non-Claude agents
+    if agent_type and agent_type != "claude":
+        # Capitalize the agent type for display (e.g., "codex" -> "Codex")
+        type_display = agent_type.capitalize()
+        first_line = f"[{type_display}] {first_line}"
+
     # Second line: annotation if provided, with truncation
     if annotation:
         if len(annotation) > max_annotation_length: