@jaguilar87/gaia-ops 4.4.0 → 4.7.2

package/dist/gaia-security/hooks/modules/core/__init__.py

@@ -0,0 +1,40 @@
+"""
+Core module - Shared utilities for all hook modules.
+
+Provides:
+- paths: Unified path resolution (find_claude_dir)
+- plugin_mode: Plugin mode detection (security vs ops)
+- state: Pre/post hook state sharing
+- stdin: Stdin availability check (has_stdin_data)
+"""
+
+from .paths import find_claude_dir, get_plugin_data_dir, get_logs_dir, get_metrics_dir, get_memory_dir
+from .plugin_mode import get_plugin_mode, is_ops_mode, is_security_mode, has_plugin, clear_mode_cache
+from .state import HookState, get_hook_state, save_hook_state, clear_hook_state, get_session_id
+from .stdin import has_stdin_data
+from .hook_entry import run_hook
+
+__all__ = [
+    # Paths
+    "find_claude_dir",
+    "get_plugin_data_dir",
+    "get_logs_dir",
+    "get_metrics_dir",
+    "get_memory_dir",
+    # Plugin mode
+    "get_plugin_mode",
+    "is_ops_mode",
+    "is_security_mode",
+    "has_plugin",
+    "clear_mode_cache",
+    # State
+    "HookState",
+    "get_hook_state",
+    "save_hook_state",
+    "clear_hook_state",
+    "get_session_id",
+    # Stdin
+    "has_stdin_data",
+    # Hook entry
+    "run_hook",
+]

package/dist/gaia-security/hooks/modules/core/hook_entry.py

@@ -0,0 +1,78 @@
+"""
+Common hook entrypoint boilerplate.
+
+Provides ``run_hook()`` which encapsulates the repeated pattern found in
+every hook entrypoint:
+
+1. Check ``has_stdin_data()``
+2. Read stdin
+3. Parse via the adapter
+4. Call a caller-provided handler with the parsed ``HookEvent``
+5. Catch and log exceptions, exiting appropriately
+
+Usage in a hook entrypoint::
+
+    from modules.core.hook_entry import run_hook
+
+    def _handle(event: HookEvent) -> None:
+        ...  # business logic, call sys.exit() / print as needed
+
+    if __name__ == "__main__":
+        run_hook(_handle, hook_name="stop_hook")
+"""
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from typing import Callable
+
+from .stdin import has_stdin_data
+
+logger = logging.getLogger(__name__)
+
+
+def run_hook(
+    handler: Callable,
+    *,
+    hook_name: str = "hook",
+    usage_message: str | None = None,
+) -> None:
+    """Read stdin, parse via ClaudeCodeAdapter, and delegate to *handler*.
+
+    Args:
+        handler: Callable that receives an ``adapters.types.HookEvent``.
+            The handler is responsible for printing output and calling
+            ``sys.exit()`` with the appropriate code.
+        hook_name: Human-readable name used in log messages and the default
+            usage string.
+        usage_message: Custom usage text shown when stdin is absent. If
+            *None*, a sensible default is generated from *hook_name*.
+    """
+    if not has_stdin_data():
+        msg = usage_message or (
+            f"Usage: echo '{{...}}' | python {hook_name}.py  (stdin mode)"
+        )
+        print(msg)
+        sys.exit(1)
+
+    try:
+        # Deferred adapter import avoids circular dependencies at module level;
+        # the adapter package is a sibling of modules/.
+        from adapters.claude_code import ClaudeCodeAdapter
+
+        adapter = ClaudeCodeAdapter()
+        stdin_data = sys.stdin.read()
+        event = adapter.parse_event(stdin_data)
+        handler(event)
+    except ValueError as e:
+        logger.error("Adapter parse failed in %s: %s", hook_name, e)
+        sys.exit(1)
+    except json.JSONDecodeError as e:
+        logger.error("Invalid JSON from stdin in %s: %s", hook_name, e)
+        sys.exit(1)
+    except SystemExit:
+        raise  # Let explicit sys.exit() calls propagate
+    except Exception as e:
+        logger.error("Error processing %s hook: %s", hook_name, e)
+        sys.exit(1)

package/dist/gaia-security/hooks/modules/core/paths.py

@@ -0,0 +1,160 @@
+"""
+Unified path resolution for gaia-ops hooks.
+
+Single source of truth for finding .claude directory and its subdirectories.
+
+Path resolution follows two base directories:
+- PLUGIN_ROOT (.claude/): Code, config, agents, skills, context providers
+- PLUGIN_DATA (CLAUDE_PLUGIN_DATA or .claude/ fallback): Logs, sessions,
+  approval grants, workflow episodic memory — data that survives plugin updates
+"""
+
+import os
+import logging
+from pathlib import Path
+from functools import lru_cache
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+@lru_cache(maxsize=1)
+def find_claude_dir() -> Path:
+    """
+    Find the .claude directory by searching upward from current location.
+
+    Search order:
+    1. If currently in .claude, return it
+    2. Check current directory for .claude/
+    3. Search parent directories upward
+    4. Fall back to current/.claude (without creating it)
+
+    Returns:
+        Path to the .claude directory
+
+    Note:
+        Result is cached for performance. Clear with find_claude_dir.cache_clear()
+    """
+    current = Path.cwd()
+
+    # If we're already in a .claude directory, return it
+    if current.name == ".claude":
+        return current
+
+    # Look for .claude in current directory
+    claude_dir = current / ".claude"
+    if claude_dir.exists():
+        return claude_dir
+
+    # Search upward through parent directories
+    for parent in current.parents:
+        claude_dir = parent / ".claude"
+        if claude_dir.exists():
+            return claude_dir
+
+    # Fallback - use current directory's .claude (but don't create it yet)
+    logger.warning(f"No .claude directory found, using {current}/.claude")
+    return current / ".claude"
+
+
+@lru_cache(maxsize=1)
+def get_plugin_data_dir() -> Path:
+    """
+    Get the base directory for persistent plugin data.
+
+    Resolution order:
+    1. CLAUDE_PLUGIN_DATA env var (set by Claude Code >= 2.1.78)
+    2. Fallback to find_claude_dir() for backward compatibility
+
+    Data stored here survives plugin updates. Code and config remain
+    under PLUGIN_ROOT (find_claude_dir()).
+
+    Returns:
+        Path to the plugin data directory (created if needed)
+
+    Note:
+        Result is cached for performance. Clear with clear_path_cache()
+    """
+    plugin_data = os.environ.get("CLAUDE_PLUGIN_DATA")
+    if plugin_data:
+        data_dir = Path(plugin_data)
+        data_dir.mkdir(parents=True, exist_ok=True)
+        return data_dir
+    # Fallback: data co-located with code in .claude/
+    return find_claude_dir()
+
+
+def get_logs_dir() -> Path:
+    """
+    Get the logs directory, creating it if necessary.
+
+    Returns:
+        Path to .claude/logs/
+    """
+    logs_dir = get_plugin_data_dir() / "logs"
+    logs_dir.mkdir(parents=True, exist_ok=True)
+    return logs_dir
+
+
+def get_metrics_dir() -> Path:
+    """
+    Get the metrics directory, creating it if necessary.
+
+    Returns:
+        Path to .claude/metrics/
+    """
+    metrics_dir = get_plugin_data_dir() / "metrics"
+    metrics_dir.mkdir(parents=True, exist_ok=True)
+    return metrics_dir
+
+
+def get_memory_dir(subdir: Optional[str] = None) -> Path:
+    """
+    Get the memory directory, creating it if necessary.
+
+    Args:
+        subdir: Optional subdirectory (e.g., "workflow-episodic")
+
+    Returns:
+        Path to .claude/memory/ or .claude/memory/{subdir}/
+    """
+    memory_dir = get_plugin_data_dir() / "memory"
+    if subdir:
+        memory_dir = memory_dir / subdir
+    memory_dir.mkdir(parents=True, exist_ok=True)
+    return memory_dir
+
+
+def get_events_dir() -> Path:
+    """
+    Get the events directory, creating it if necessary.
+
+    Returns:
+        Path to .claude/events/
+    """
+    events_dir = get_plugin_data_dir() / "events"
+    events_dir.mkdir(parents=True, exist_ok=True)
+    return events_dir
+
+
+def get_session_dir() -> Path:
+    """
+    Get the active session directory, creating it if necessary.
+
+    Returns:
+        Path to .claude/session/active/
+    """
+    session_dir = get_plugin_data_dir() / "session" / "active"
+    session_dir.mkdir(parents=True, exist_ok=True)
+    return session_dir
+
+
+def clear_path_cache():
+    """Clear all cached path results (useful for testing)."""
+    find_claude_dir.cache_clear()
+    get_plugin_data_dir.cache_clear()
+    try:
+        from .plugin_mode import clear_mode_cache
+        clear_mode_cache()
+    except ImportError:
+        pass

package/dist/gaia-security/hooks/modules/core/plugin_mode.py

@@ -0,0 +1,149 @@
+"""Plugin mode detection for gaia hooks.
+
+Determines whether the installation is security-only or ops (full orchestrator).
+Security mode: T3 operations use native Claude Code approval dialog (permissionDecision: ask).
+Ops mode: T3 operations block with nonce for orchestrator agent approval flow.
+
+Detection order:
+1. plugin-registry.json in plugin data directory
+2. NPM package name detection (gaia-ops vs gaia-security)
+3. GAIA_PLUGIN_MODE env var fallback
+4. Default: "security" (most restrictive)
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+from functools import lru_cache
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+VALID_MODES = ("security", "ops")
+DEFAULT_MODE = "security"
+
+# Map NPM package names to plugin modes
+_NPM_PACKAGE_MODE = {
+    "gaia-ops": "ops",
+    "gaia-security": "security",
+}
+
+
+def _detect_mode_from_npm_package() -> str | None:
+    """Detect plugin mode from the NPM package name.
+
+    When installed via npm, this module lives at a path like:
+      .../node_modules/@jaguilar87/gaia-ops/hooks/modules/core/plugin_mode.py
+
+    The package directory name (gaia-ops or gaia-security) determines the mode.
+    Also checks .claude/ symlinks as a secondary signal for npm installs.
+
+    Returns the mode string or None if not detectable.
+    """
+    # Primary: check our own file path for node_modules package name
+    module_path = Path(__file__).resolve()
+    parts = module_path.parts
+    for i, part in enumerate(parts):
+        if part == "node_modules" and i + 2 < len(parts):
+            # Could be @scope/package-name or just package-name
+            pkg_name = parts[i + 1]
+            if pkg_name.startswith("@") and i + 2 < len(parts):
+                pkg_name = parts[i + 2]
+            mode = _NPM_PACKAGE_MODE.get(pkg_name)
+            if mode:
+                logger.debug("Detected mode '%s' from npm package path: %s", mode, pkg_name)
+                return mode
+
+    # Secondary: check if .claude/agents symlink points to a gaia package
+    try:
+        from .paths import find_claude_dir
+        claude_dir = find_claude_dir()
+        agents_link = claude_dir / "agents"
+        if agents_link.is_symlink():
+            target = str(agents_link.resolve())
+            for pkg_name, mode in _NPM_PACKAGE_MODE.items():
+                if pkg_name in target:
+                    logger.debug("Detected mode '%s' from .claude/agents symlink target", mode)
+                    return mode
+    except Exception:
+        pass
+
+    return None
+
+
+@lru_cache(maxsize=1)
+def get_plugin_mode() -> str:
+    """Get the current plugin mode.
+
+    Returns "security" or "ops".
+    """
+    # 1. Check plugin registry
+    try:
+        from .paths import get_plugin_data_dir
+        registry_path = get_plugin_data_dir() / "plugin-registry.json"
+        if registry_path.exists():
+            registry = json.loads(registry_path.read_text())
+            installed = [p.get("name", "") for p in registry.get("installed", [])]
+            if "gaia-ops" in installed:
+                return "ops"
+            if "gaia-security" in installed:
+                return "security"
+    except Exception as e:
+        logger.debug("Registry check failed (non-fatal): %s", e)
+
+    # 2. CLAUDE_PLUGIN_ROOT + plugin.json (--plugin-dir mode)
+    plugin_root = os.environ.get("CLAUDE_PLUGIN_ROOT", "")
+    if plugin_root:
+        try:
+            pjson = Path(plugin_root) / ".claude-plugin" / "plugin.json"
+            if pjson.exists():
+                pdata = json.loads(pjson.read_text())
+                pname = pdata.get("name", "")
+                mode = _NPM_PACKAGE_MODE.get(pname)
+                if mode:
+                    logger.debug("Detected mode '%s' from plugin.json name: %s", mode, pname)
+                    return mode
+        except Exception as e:
+            logger.debug("Plugin.json check failed (non-fatal): %s", e)
+
+    # 3. NPM package name detection
+    npm_mode = _detect_mode_from_npm_package()
+    if npm_mode:
+        return npm_mode
+
+    # 4. Env var fallback
+    mode = os.environ.get("GAIA_PLUGIN_MODE", "").lower()
+    if mode in VALID_MODES:
+        return mode
+
+    # 5. Default: security (most restrictive)
+    return DEFAULT_MODE
+
+
+def has_plugin(name: str) -> bool:
+    """Check if a specific plugin is installed."""
+    try:
+        from .paths import get_plugin_data_dir
+        registry_path = get_plugin_data_dir() / "plugin-registry.json"
+        if registry_path.exists():
+            registry = json.loads(registry_path.read_text())
+            return any(p.get("name") == name for p in registry.get("installed", []))
+    except Exception:
+        pass
+    return False
+
+
+def is_ops_mode() -> bool:
+    """Convenience: check if running in ops mode."""
+    return get_plugin_mode() == "ops"
+
+
+def is_security_mode() -> bool:
+    """Convenience: check if running in security-only mode."""
+    return get_plugin_mode() == "security"
+
+
+def clear_mode_cache():
+    """Clear cached mode (for testing)."""
+    get_plugin_mode.cache_clear()