@jaguilar87/gaia-ops 4.4.0 → 4.7.2

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

@@ -0,0 +1,179 @@
+"""
+Hook state management - Share state between pre and post hooks.
+
+Uses a temporary file to pass information from pre_tool_use to post_tool_use,
+since they run in separate processes.
+"""
+
+import os
+import json
+import logging
+import time
+from pathlib import Path
+from datetime import datetime
+from typing import Dict, Any, Optional
+from dataclasses import dataclass, asdict, field
+
+from .paths import find_claude_dir
+
+logger = logging.getLogger(__name__)
+
+# State file location
+STATE_FILE_NAME = ".hooks_state.json"
+
+
+def get_session_id() -> str:
+    """Return the current Claude session ID, defaulting to 'default'."""
+    return os.environ.get("CLAUDE_SESSION_ID", "default")
+
+
+@dataclass
+class HookState:
+    """
+    State passed from pre-hook to post-hook.
+
+    Attributes:
+        tool_name: Name of the tool being executed
+        command: Command being executed (for Bash)
+        tier: Security tier assigned by pre-hook
+        start_time: ISO timestamp when pre-hook ran
+        session_id: Current session identifier
+        pre_hook_result: Result from pre-hook validation
+        metadata: Additional context data
+    """
+    tool_name: str = ""
+    command: str = ""
+    tier: str = "unknown"
+    start_time: str = ""
+    start_time_epoch: float = 0.0
+    session_id: str = ""
+    pre_hook_result: str = "allowed"
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "HookState":
+        """Create from dictionary."""
+        return cls(
+            tool_name=data.get("tool_name", ""),
+            command=data.get("command", ""),
+            tier=data.get("tier", "unknown"),
+            start_time=data.get("start_time", ""),
+            start_time_epoch=float(data.get("start_time_epoch", 0.0)),
+            session_id=data.get("session_id", ""),
+            pre_hook_result=data.get("pre_hook_result", "allowed"),
+            metadata=data.get("metadata", {}),
+        )
+
+
+def _get_state_file_path() -> Path:
+    """Get path to state file."""
+    claude_dir = find_claude_dir()
+    return claude_dir / STATE_FILE_NAME
+
+
+def save_hook_state(state: HookState) -> bool:
+    """
+    Save hook state for post-hook to read.
+
+    Args:
+        state: HookState to save
+
+    Returns:
+        True if saved successfully
+    """
+    try:
+        state_file = _get_state_file_path()
+        state_file.parent.mkdir(parents=True, exist_ok=True)
+
+        with open(state_file, "w") as f:
+            json.dump(state.to_dict(), f)
+
+        logger.debug(f"Saved hook state: {state.tool_name} / {state.tier}")
+        return True
+
+    except Exception as e:
+        logger.warning(f"Could not save hook state: {e}")
+        return False
+
+
+def get_hook_state() -> Optional[HookState]:
+    """
+    Get hook state saved by pre-hook.
+
+    Returns:
+        HookState if found, None otherwise
+    """
+    try:
+        state_file = _get_state_file_path()
+
+        if not state_file.exists():
+            logger.debug("No hook state file found")
+            return None
+
+        with open(state_file, "r") as f:
+            data = json.load(f)
+
+        return HookState.from_dict(data)
+
+    except Exception as e:
+        logger.warning(f"Could not read hook state: {e}")
+        return None
+
+
+def clear_hook_state() -> bool:
+    """
+    Clear hook state after post-hook has processed it.
+
+    Returns:
+        True if cleared successfully
+    """
+    try:
+        state_file = _get_state_file_path()
+
+        if state_file.exists():
+            state_file.unlink()
+            logger.debug("Cleared hook state")
+
+        return True
+
+    except Exception as e:
+        logger.warning(f"Could not clear hook state: {e}")
+        return False
+
+
+def create_pre_hook_state(
+    tool_name: str,
+    command: str = "",
+    tier: str = "unknown",
+    **metadata
+) -> HookState:
+    """
+    Create a new hook state for pre-hook.
+
+    Convenience function that sets common fields automatically.
+
+    Args:
+        tool_name: Name of the tool
+        command: Command being executed
+        tier: Security tier
+        **metadata: Additional metadata
+
+    Returns:
+        New HookState instance
+    """
+    session_id = get_session_id()
+
+    return HookState(
+        tool_name=tool_name,
+        command=command,
+        tier=tier,
+        start_time=datetime.now().isoformat(),
+        start_time_epoch=time.time(),
+        session_id=session_id,
+        pre_hook_result="allowed",
+        metadata=metadata,
+    )

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

@@ -0,0 +1,24 @@
+"""
+Stdin availability check for hook entrypoints.
+
+Provides a single ``has_stdin_data()`` helper that determines whether the
+current process has data available on stdin. This replaces the duplicate
+implementations that previously lived in ``adapters.utils``.
+"""
+
+import logging
+import select
+import sys
+
+logger = logging.getLogger(__name__)
+
+
+def has_stdin_data() -> bool:
+    """Check if there is data available on stdin."""
+    if sys.stdin.isatty():
+        return False
+    try:
+        readable, _, _ = select.select([sys.stdin], [], [], 0)
+        return bool(readable)
+    except Exception:
+        return not sys.stdin.isatty()

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

@@ -0,0 +1 @@
+"""Event context system for cross-session operational event logging."""

package/dist/gaia-security/hooks/modules/events/event_writer.py

@@ -0,0 +1,210 @@
+"""Event writer and reader for the GAIA Event Context system.
+
+Provides:
+    - EventWriter: append-only JSONL writer with file locking
+    - read_events(): read events from last N hours with optional filtering
+    - cleanup_old_events(): remove events older than N days
+    - Event type constants
+"""
+
+import fcntl
+import json
+import logging
+import os
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from ..core.paths import get_events_dir
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Event type constants
+# ---------------------------------------------------------------------------
+
+AGENT_DISPATCH = "agent.dispatch"
+AGENT_COMPLETE = "agent.complete"
+COMMAND_EXECUTED = "command.executed"
+SESSION_END = "session.end"
+TRIGGER_SCHEDULED = "trigger.scheduled"
+HEARTBEAT = "heartbeat"
+USER_NOTE = "user.note"
+
+
+class EventWriter:
+    """Append-only JSONL event writer with file locking.
+
+    All writes are wrapped in try/except -- events are non-critical and
+    must never block the hook pipeline.
+    """
+
+    def __init__(self, events_dir: Optional[Path] = None):
+        self.events_dir = events_dir or get_events_dir()
+        self.events_file = self.events_dir / "events.jsonl"
+        self.lock_file = self.events_dir / "events.jsonl.lock"
+
+    def write_event(
+        self,
+        event_type: str,
+        source: str,
+        agent: str,
+        result: str,
+        severity: str = "info",
+        meta: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Append a single event to the JSONL log.
+
+        Thread-safe via exclusive file lock.  Fails silently on any error
+        to avoid disrupting the hook pipeline.
+
+        Args:
+            event_type: Dotted event category (e.g. "agent.dispatch").
+            source: Who wrote the event (e.g. "hook").
+            agent: Agent involved, or empty string for non-agent events.
+            result: Outcome summary string.
+            severity: info | warning | error.
+            meta: Optional type-specific structured data.
+        """
+        try:
+            self.events_dir.mkdir(parents=True, exist_ok=True)
+
+            record: Dict[str, Any] = {
+                "ts": datetime.now(timezone.utc).isoformat(),
+                "type": event_type,
+                "source": source,
+                "agent": agent,
+                "result": result,
+                "severity": severity,
+            }
+            if meta:
+                record["meta"] = meta
+
+            with open(self.lock_file, "w") as lf:
+                fcntl.flock(lf.fileno(), fcntl.LOCK_EX)
+                try:
+                    with open(self.events_file, "a") as f:
+                        f.write(json.dumps(record, separators=(",", ":")) + "\n")
+                finally:
+                    fcntl.flock(lf.fileno(), fcntl.LOCK_UN)
+
+        except Exception as exc:
+            logger.debug("Event write failed (non-fatal): %s", exc)
+
+
+def read_events(
+    hours: int = 24,
+    event_type: Optional[str] = None,
+    limit: int = 50,
+    events_dir: Optional[Path] = None,
+) -> List[Dict[str, Any]]:
+    """Read recent events from the JSONL log.
+
+    Args:
+        hours: How far back to look (default 24h).
+        event_type: Optional filter by event type (exact match).
+        limit: Maximum number of events to return.
+        events_dir: Override events directory (for testing).
+
+    Returns:
+        List of event dicts, most recent last, capped at *limit*.
+    """
+    try:
+        edir = events_dir or get_events_dir()
+        events_file = edir / "events.jsonl"
+        if not events_file.exists():
+            return []
+
+        cutoff = datetime.now(timezone.utc) - timedelta(hours=hours)
+        results: List[Dict[str, Any]] = []
+
+        with open(events_file, "r") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    evt = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+
+                # Time filter
+                try:
+                    ts = datetime.fromisoformat(evt.get("ts", ""))
+                    if ts < cutoff:
+                        continue
+                except (ValueError, TypeError):
+                    continue
+
+                # Type filter
+                if event_type and evt.get("type") != event_type:
+                    continue
+
+                results.append(evt)
+
+        # Return the most recent events, capped at limit
+        return results[-limit:]
+
+    except Exception as exc:
+        logger.debug("Event read failed (non-fatal): %s", exc)
+        return []
+
+
+def cleanup_old_events(
+    days: int = 7,
+    events_dir: Optional[Path] = None,
+) -> int:
+    """Remove events older than *days* from the JSONL log.
+
+    Uses file locking to avoid conflicts with concurrent writers.
+    Retains lines that cannot be parsed (conservative).
+
+    Args:
+        days: Retention window in days (default 7).
+        events_dir: Override events directory (for testing).
+
+    Returns:
+        Number of events removed.
+    """
+    try:
+        edir = events_dir or get_events_dir()
+        events_file = edir / "events.jsonl"
+        lock_file = edir / "events.jsonl.lock"
+
+        if not events_file.exists():
+            return 0
+
+        retention_days = int(os.environ.get("GAIA_EVENT_RETENTION_DAYS", str(days)))
+        cutoff = datetime.now(timezone.utc) - timedelta(days=retention_days)
+        kept: List[str] = []
+        removed = 0
+
+        with open(lock_file, "w") as lf:
+            fcntl.flock(lf.fileno(), fcntl.LOCK_EX)
+            try:
+                with open(events_file, "r") as f:
+                    for line in f:
+                        line = line.strip()
+                        if not line:
+                            continue
+                        try:
+                            evt = json.loads(line)
+                            ts = datetime.fromisoformat(evt["ts"])
+                            if ts < cutoff:
+                                removed += 1
+                                continue
+                        except (json.JSONDecodeError, KeyError, ValueError):
+                            pass  # Keep unparseable lines
+                        kept.append(line)
+
+                with open(events_file, "w") as f:
+                    for line in kept:
+                        f.write(line + "\n")
+            finally:
+                fcntl.flock(lf.fileno(), fcntl.LOCK_UN)
+
+        return removed
+
+    except Exception as exc:
+        logger.debug("Event cleanup failed (non-fatal): %s", exc)
+        return 0

package/dist/gaia-security/hooks/modules/identity/identity_provider.py

@@ -0,0 +1,21 @@
+"""Dynamic identity provider based on installed plugins."""
+
+import logging
+from ..core.plugin_mode import get_plugin_mode
+
+logger = logging.getLogger(__name__)
+
+
+def build_identity() -> str:
+    """Build the identity context based on installed plugin mode."""
+    mode = get_plugin_mode()
+
+    if mode == "ops":
+        from .ops_identity import build_ops_identity
+        identity = build_ops_identity()
+    else:
+        from .security_identity import build_security_identity
+        identity = build_security_identity()
+
+    logger.info("Identity built for mode: %s (%d chars)", mode, len(identity))
+    return identity

package/dist/gaia-security/hooks/modules/identity/ops_identity.py

@@ -0,0 +1,34 @@
+"""Ops orchestrator identity for gaia-ops plugin."""
+
+
+def build_ops_identity() -> str:
+    return """# Identity: Gaia Ops Orchestrator
+
+You are a dispatcher. Users bring requests; you route to the right
+specialist agent. You never investigate or execute yourself.
+
+## Your tools
+- **Agent** — dispatch to specialist agents
+- **SendMessage** — resume a previously spawned agent
+- **AskUserQuestion** — get clarification or approval
+- **Skill** — load on-demand procedures (agent-response, orchestrator-approval)
+
+## Routing
+
+Each user message includes a routing recommendation. Follow it:
+- confidence >= 0.5 — dispatch the recommended agent(s) using the dispatch_mode
+- confidence < 0.5 — ask the user to clarify
+- no recommendation — respond directly (general question)
+
+Your prompt to the agent = user's objective + info agent cannot derive.
+Resume an active agent with SendMessage instead of creating a new one.
+
+## Response Handling
+
+When an agent returns a json:contract, load agent-response skill.
+When an agent returns REVIEW with approval_id, load orchestrator-approval skill.
+
+## Failures
+- Hook blocks a command — relay message verbatim, no alternatives
+- Routing unclear — ask the user
+- Agents contradict — present both sides, user decides"""

package/dist/gaia-security/hooks/modules/identity/security_identity.py

@@ -0,0 +1,10 @@
+"""Security-only identity for gaia-security plugin."""
+
+
+def build_security_identity() -> str:
+    """Build identity context for security-only mode."""
+    return (
+        "You work directly with the user. "
+        "If a command is blocked by a security hook, do not attempt alternatives "
+        "to achieve the same result. Explain what was blocked and ask the user how to proceed."
+    )

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

@@ -0,0 +1,8 @@
+"""
+Memory module - Episodic memory capture for workflow episodes.
+
+Provides:
+- episode_writer: Workflow episode storage + session events (replaces episode_capture + session_state)
+"""
+
+__all__ = []