gobby 0.2.5__py3-none-any.whl

gobby/__init__.py

@@ -0,0 +1,3 @@
+"""Gobby - Local-first daemon for multi-CLI session management."""
+
+__version__ = "0.2.3"

gobby/adapters/__init__.py

@@ -0,0 +1,30 @@
+"""CLI adapters for multi-CLI session management.
+
+This module contains adapters that translate between CLI-specific hook formats
+and the unified HookEvent/HookResponse models.
+
+Each adapter is responsible for:
+1. Translating native CLI payloads to HookEvent
+2. Translating HookResponse back to CLI-expected format
+3. Managing CLI-specific session lifecycle
+
+Adapters:
+- ClaudeCodeAdapter: For Claude Code CLI hooks (HTTP-based)
+- GeminiAdapter: For Gemini CLI hooks (HTTP-based) [Phase 3]
+- CodexAdapter: For Codex CLI via app-server (JSON-RPC-based) [Phase 4]
+- CodexNotifyAdapter: For Codex CLI notify events (simple HTTP-based)
+"""
+
+from gobby.adapters.base import BaseAdapter
+from gobby.adapters.claude_code import ClaudeCodeAdapter
+from gobby.adapters.codex import CodexAdapter, CodexAppServerClient, CodexNotifyAdapter
+from gobby.adapters.gemini import GeminiAdapter
+
+__all__ = [
+    "BaseAdapter",
+    "ClaudeCodeAdapter",
+    "CodexAdapter",
+    "CodexAppServerClient",
+    "CodexNotifyAdapter",
+    "GeminiAdapter",
+]

gobby/adapters/base.py

@@ -0,0 +1,93 @@
+"""Base adapter class for CLI hook translation.
+
+This module defines the abstract base class that all CLI adapters must implement.
+Adapters are responsible for translating between CLI-specific hook formats and
+the unified HookEvent/HookResponse models.
+"""
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+from gobby.hooks.events import HookEvent, HookResponse, SessionSource
+
+if TYPE_CHECKING:
+    from gobby.hooks.hook_manager import HookManager
+
+
+class BaseAdapter(ABC):
+    """Base class for CLI adapters that translate native events to HookEvents.
+
+    Each CLI (Claude Code, Gemini, Codex) has its own adapter that:
+    1. Knows how to parse the CLI's native hook payload format
+    2. Translates payloads to unified HookEvent objects
+    3. Translates HookResponse objects back to CLI-expected format
+
+    Subclasses must implement:
+    - source: The SessionSource enum value for this CLI
+    - translate_to_hook_event(): Convert native payload to HookEvent
+    - translate_from_hook_response(): Convert HookResponse to native format
+    """
+
+    source: SessionSource
+
+    @abstractmethod
+    def translate_to_hook_event(self, native_event: dict[str, Any]) -> HookEvent | None:
+        """Convert native CLI event to unified HookEvent.
+
+        Args:
+            native_event: The raw payload from the CLI's hook dispatcher.
+                Structure varies by CLI:
+                - Claude Code: {"hook_type": "...", "input_data": {...}}
+                - Gemini: {"hook_event_name": "...", "session_id": "...", ...}
+                - Codex: JSON-RPC params from app-server events
+
+        Returns:
+            A unified HookEvent that can be processed by HookManager.
+        """
+        pass
+
+    @abstractmethod
+    def translate_from_hook_response(self, response: HookResponse) -> dict[str, Any]:
+        """Convert HookResponse to native CLI response format.
+
+        Args:
+            response: The unified HookResponse from HookManager.
+
+        Returns:
+            A dict in the format expected by the CLI's hook dispatcher:
+            - Claude Code: {"continue": bool, "stopReason": str | None, ...}
+            - Gemini: {"decision": str, "hookSpecificOutput": {...}}
+            - Codex: JSON-RPC response format
+        """
+        pass
+
+    def handle_native(
+        self, native_event: dict[str, Any], hook_manager: "HookManager"
+    ) -> dict[str, Any]:
+        """Main entry point for HTTP endpoints.
+
+        This method handles the full round-trip:
+        1. Translate native event to HookEvent
+        2. Process through HookManager
+        3. Translate response back to native format
+
+        Note: This method is synchronous for Phase 2A-2B compatibility.
+        In Phase 2C+, when HookManager.handle() is async, subclasses may
+        override with async versions.
+
+        Subclasses may override this to add CLI-specific behavior, such as
+        the strangler fig pattern used by ClaudeCodeAdapter.
+
+        Args:
+            native_event: The raw payload from the CLI.
+            hook_manager: The HookManager instance to process events.
+
+        Returns:
+            Response dict in CLI-specific format.
+        """
+        hook_event = self.translate_to_hook_event(native_event)
+        if hook_event is None:
+            # Event ignored by adapter
+            return {}
+        hook_response = hook_manager.handle(hook_event)
+        return self.translate_from_hook_response(hook_response)

gobby/adapters/claude_code.py

@@ -0,0 +1,276 @@
+"""Claude Code adapter for hook translation.
+
+This adapter translates between Claude Code's native hook format and the unified
+HookEvent/HookResponse models. It implements the strangler fig pattern for safe
+migration from the existing HookManager.execute() method.
+
+Claude Code Hook Types (12 total):
+- session-start, session-end: Session lifecycle
+- user-prompt-submit: Before user prompt validation
+- pre-tool-use, post-tool-use, post-tool-use-failure: Tool lifecycle
+- pre-compact: Context compaction
+- stop: Agent stops
+- subagent-start, subagent-stop: Subagent lifecycle
+- permission-request: Permission requests (future)
+- notification: System notifications
+"""
+
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+from gobby.adapters.base import BaseAdapter
+from gobby.hooks.events import HookEvent, HookEventType, HookResponse, SessionSource
+
+if TYPE_CHECKING:
+    from gobby.hooks.hook_manager import HookManager
+
+
+class ClaudeCodeAdapter(BaseAdapter):
+    """Adapter for Claude Code CLI hook translation.
+
+    This adapter:
+    1. Translates Claude Code's kebab-case hook payloads to unified HookEvent
+    2. Translates HookResponse back to Claude Code's expected format
+    3. Calls HookManager.handle() with unified HookEvent model
+
+    Phase 2C Migration Complete:
+    - Now using HookManager.handle(HookEvent) for all hooks
+    - Legacy execute() path available via set_legacy_mode(True) for rollback
+    """
+
+    source = SessionSource.CLAUDE
+
+    # Event type mapping: Claude Code hook names -> unified HookEventType
+    # Claude Code uses kebab-case hook names in the payload's "hook_type" field
+    EVENT_MAP: dict[str, HookEventType] = {
+        "session-start": HookEventType.SESSION_START,
+        "session-end": HookEventType.SESSION_END,
+        "user-prompt-submit": HookEventType.BEFORE_AGENT,
+        "stop": HookEventType.STOP,
+        "pre-tool-use": HookEventType.BEFORE_TOOL,
+        "post-tool-use": HookEventType.AFTER_TOOL,
+        "post-tool-use-failure": HookEventType.AFTER_TOOL,  # Same as AFTER_TOOL with error flag
+        "pre-compact": HookEventType.PRE_COMPACT,
+        "subagent-start": HookEventType.SUBAGENT_START,
+        "subagent-stop": HookEventType.SUBAGENT_STOP,
+        "permission-request": HookEventType.PERMISSION_REQUEST,
+        "notification": HookEventType.NOTIFICATION,
+    }
+
+    def __init__(self, hook_manager: "HookManager | None" = None):
+        """Initialize the Claude Code adapter.
+
+        Args:
+            hook_manager: Reference to HookManager for strangler fig delegation.
+                         If None, the adapter can only translate (not handle events).
+        """
+        self._hook_manager = hook_manager
+        # Phase 2C: Use new handle() path with unified HookEvent model
+        # Note: systemMessage handoff notification bug exists in both paths (see plan-multi-cli.md)
+        self._use_legacy = False
+
+    def translate_to_hook_event(self, native_event: dict[str, Any]) -> HookEvent:
+        """Convert Claude Code native event to unified HookEvent.
+
+        Claude Code payloads have the structure:
+        {
+            "hook_type": "session-start",  # kebab-case hook name
+            "input_data": {
+                "session_id": "abc123",    # Claude calls this session_id but it's external_id
+                "machine_id": "...",
+                "cwd": "/path/to/project",
+                "transcript_path": "...",
+                # ... other hook-specific fields
+            }
+        }
+
+        Args:
+            native_event: Raw payload from Claude Code's hook_dispatcher.py
+
+        Returns:
+            Unified HookEvent with normalized fields.
+        """
+        hook_type = native_event.get("hook_type", "")
+        input_data = native_event.get("input_data", {})
+
+        # Map Claude hook type to unified event type
+        # Fall back to NOTIFICATION for unknown types (fail-open)
+        event_type = self.EVENT_MAP.get(hook_type, HookEventType.NOTIFICATION)
+
+        # Extract session_id (Claude calls it session_id but it's the external_id)
+        session_id = input_data.get("session_id", "")
+
+        # Check for failure flag in post-tool-use-failure
+        is_failure = hook_type == "post-tool-use-failure"
+        metadata = {"is_failure": is_failure} if is_failure else {}
+
+        return HookEvent(
+            event_type=event_type,
+            session_id=session_id,
+            source=self.source,
+            timestamp=datetime.now(UTC),
+            machine_id=input_data.get("machine_id"),
+            cwd=input_data.get("cwd"),
+            data=input_data,
+            metadata=metadata,
+        )
+
+    # Map Claude Code hook types to hookEventName for hookSpecificOutput
+    HOOK_EVENT_NAME_MAP: dict[str, str] = {
+        "session-start": "SessionStart",
+        "session-end": "SessionEnd",
+        "user-prompt-submit": "UserPromptSubmit",
+        "stop": "Stop",
+        "pre-tool-use": "PreToolUse",
+        "post-tool-use": "PostToolUse",
+        "post-tool-use-failure": "PostToolUse",
+        "pre-compact": "PreCompact",
+        "subagent-start": "SubagentStart",
+        "subagent-stop": "SubagentStop",
+        "permission-request": "PermissionRequest",
+        "notification": "Notification",
+    }
+
+    def translate_from_hook_response(
+        self, response: HookResponse, hook_type: str | None = None
+    ) -> dict[str, Any]:
+        """Convert HookResponse to Claude Code's expected format.
+
+        Claude Code expects responses in this format:
+        {
+            "continue": True/False,        # Whether to continue execution
+            "stopReason": "...",           # Reason if stopped (optional)
+            "decision": "approve"/"block", # Tool decision
+            "hookSpecificOutput": {        # Hook-specific data
+                "hookEventName": "SessionStart",  # Required!
+                "additionalContext": "..."  # Context to inject into Claude
+            }
+        }
+
+        Args:
+            response: Unified HookResponse from HookManager.
+            hook_type: Original Claude Code hook type (e.g., "session-start")
+                      Used to set hookEventName in hookSpecificOutput.
+
+        Returns:
+            Dict in Claude Code's expected format.
+        """
+        # Map decision to continue flag
+        # Both "deny" and "block" should stop execution
+        should_continue = response.decision not in ("deny", "block")
+
+        result: dict[str, Any] = {
+            "continue": should_continue,
+        }
+
+        # Add stop reason if denied or blocked
+        if response.decision in ("deny", "block") and response.reason:
+            result["stopReason"] = response.reason
+
+        # Add system_message to systemMessage (for system-level messages)
+        # Note: response.context goes to additionalContext below (visible to model)
+        if response.system_message:
+            result["systemMessage"] = response.system_message
+
+        # Add tool decision for pre-tool-use hooks
+        # Claude Code schema: decision uses "approve"/"block"
+        # permissionDecision uses "allow"/"deny"/"ask"
+        if response.decision in ("deny", "block"):
+            result["decision"] = "block"
+        else:
+            result["decision"] = "approve"
+
+        # Add hookSpecificOutput with additionalContext for model context injection
+        # This includes both workflow inject_context AND session identifiers
+        hook_event_name = self.HOOK_EVENT_NAME_MAP.get(hook_type or "", "Unknown")
+        additional_context_parts: list[str] = []
+
+        # Add workflow-injected context (from inject_context action)
+        # This is the primary way to inject context visible to the model
+        if response.context:
+            additional_context_parts.append(response.context)
+
+        # Add session identifiers from metadata
+        if response.metadata:
+            session_id = response.metadata.get("session_id")
+            if session_id:
+                # Build context with all available identifiers
+                context_lines = [f"session_id: {session_id}"]
+                if response.metadata.get("parent_session_id"):
+                    context_lines.append(
+                        f"parent_session_id: {response.metadata['parent_session_id']}"
+                    )
+                if response.metadata.get("machine_id"):
+                    context_lines.append(f"machine_id: {response.metadata['machine_id']}")
+                if response.metadata.get("project_id"):
+                    context_lines.append(f"project_id: {response.metadata['project_id']}")
+                # Add terminal context (non-null values only)
+                if response.metadata.get("terminal_term_program"):
+                    context_lines.append(f"terminal: {response.metadata['terminal_term_program']}")
+                if response.metadata.get("terminal_tty"):
+                    context_lines.append(f"tty: {response.metadata['terminal_tty']}")
+                if response.metadata.get("terminal_parent_pid"):
+                    context_lines.append(f"parent_pid: {response.metadata['terminal_parent_pid']}")
+                # Add terminal-specific session IDs (only one will be present)
+                for key in [
+                    "terminal_iterm_session_id",
+                    "terminal_term_session_id",
+                    "terminal_kitty_window_id",
+                    "terminal_tmux_pane",
+                    "terminal_vscode_terminal_id",
+                    "terminal_alacritty_socket",
+                ]:
+                    if response.metadata.get(key):
+                        # Use friendlier names in output
+                        friendly_name = key.replace("terminal_", "").replace("_", " ")
+                        context_lines.append(f"{friendly_name}: {response.metadata[key]}")
+                additional_context_parts.append("\n".join(context_lines))
+
+        # Build hookSpecificOutput if we have any context to inject
+        if additional_context_parts:
+            result["hookSpecificOutput"] = {
+                "hookEventName": hook_event_name,
+                "additionalContext": "\n\n".join(additional_context_parts),
+            }
+
+        return result
+
+    def handle_native(
+        self, native_event: dict[str, Any], hook_manager: "HookManager"
+    ) -> dict[str, Any]:
+        """Main entry point for HTTP endpoint.
+
+        Strangler fig pattern:
+        - Phase 2A-2B: Delegates to existing execute() — validates translation only
+        - Phase 2C+: Calls new handle() with HookEvent
+
+        Note: This method is synchronous for Phase 2A-2B compatibility with
+        the existing execute() method. In Phase 2C+, it will become async
+        when handle() is implemented as async.
+
+        Args:
+            native_event: Raw payload from Claude Code's hook_dispatcher.py
+            hook_manager: HookManager instance for processing.
+
+        Returns:
+            Response dict in Claude Code's expected format.
+        """
+        # Always translate (validates our mapping is correct)
+        hook_event = self.translate_to_hook_event(native_event)
+
+        # Phase 2C+: Use new HookEvent-based handler
+        # Legacy execute() path removed as HookManager.execute is deprecated/removed.
+        hook_type = native_event.get("hook_type", "")
+        hook_response = hook_manager.handle(hook_event)
+        return self.translate_from_hook_response(hook_response, hook_type=hook_type)
+
+    def set_legacy_mode(self, use_legacy: bool) -> None:
+        """Toggle between legacy and new code paths.
+
+        This method is used during the strangler fig migration to switch
+        between delegating to execute() and calling handle() directly.
+
+        Args:
+            use_legacy: If True, use legacy execute() path. If False, use new handle() path.
+        """
+        self._use_legacy = use_legacy