@jaguilar87/gaia 5.0.0-rc1

package/dist/gaia-ops/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-ops/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-ops/hooks/modules/events/__init__.py

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

package/dist/gaia-ops/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-ops/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__ = []

package/dist/gaia-ops/hooks/modules/memory/episode_writer.py

@@ -0,0 +1,216 @@
+"""
+Episodic memory capture for workflow episodes.
+
+Renamed from episode_capture.py. Absorbs get_session_events() from
+session_state.py directly into this module.
+
+Provides:
+    - write(): Store workflow as episodic memory
+    - get_session_events(): Read context.json, categorize events
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# Session events (absorbed from session_state.py)
+# ============================================================================
+
+def get_session_events() -> Dict[str, Any]:
+    """
+    Get critical events from active session context.
+
+    Returns:
+        Dict with categorized session events (commits, pushes, file_mods)
+    """
+    context_path = Path(".claude/session/active/context.json")
+
+    if not context_path.exists():
+        logger.debug("No session context found")
+        return {}
+
+    try:
+        with open(context_path, "r") as f:
+            context = json.load(f)
+
+        critical_events = context.get("critical_events", [])
+
+        if not critical_events:
+            return {}
+
+        commits = [
+            {
+                "hash": e.get("commit_hash", ""),
+                "message": e.get("commit_message", ""),
+                "timestamp": e.get("timestamp", "")
+            }
+            for e in critical_events
+            if e.get("event_type") == "git_commit" and e.get("commit_hash")
+        ]
+
+        pushes = [
+            {
+                "branch": e.get("branch", ""),
+                "timestamp": e.get("timestamp", "")
+            }
+            for e in critical_events
+            if e.get("event_type") == "git_push" and e.get("branch")
+        ]
+
+        file_mods = [
+            {
+                "count": e.get("modification_count", 0),
+                "timestamp": e.get("timestamp", "")
+            }
+            for e in critical_events
+            if e.get("event_type") == "file_modifications"
+        ]
+
+        result = {}
+        if commits:
+            result["git_commits"] = commits
+        if pushes:
+            result["git_pushes"] = pushes
+        if file_mods:
+            result["file_modifications"] = file_mods
+
+        if result:
+            logger.info(f"Found {len(critical_events)} session events")
+
+        return result
+
+    except Exception as e:
+        logger.warning(f"Failed to read session events: {e}")
+        return {}
+
+
+# ============================================================================
+# Episodic memory capture
+# ============================================================================
+
+def write(
+    metrics: Dict[str, Any],
+    anomalies: Optional[List[Dict[str, str]]] = None,
+    commands_executed: Optional[List[str]] = None,
+) -> Optional[str]:
+    """
+    Capture workflow as episodic memory.
+
+    Args:
+        metrics: Subagent metrics from workflow (includes plan_status, tier, task description)
+        anomalies: Detected anomalies from audit(), stored in episode context
+        commands_executed: List of commands extracted from EVIDENCE_REPORT
+
+    Returns:
+        Episode ID if stored, None otherwise
+    """
+    try:
+        import importlib.util
+
+        candidates = [
+            Path(__file__).parent.parent.parent.parent / "tools" / "memory" / "episodic.py",
+            Path(".claude/tools/memory/episodic.py"),
+        ]
+
+        episodic_module = None
+        for path in candidates:
+            if path.exists():
+                try:
+                    spec = importlib.util.spec_from_file_location("episodic", path)
+                    if spec and spec.loader:
+                        episodic_module = importlib.util.module_from_spec(spec)
+                        spec.loader.exec_module(episodic_module)
+                        logger.debug(f"Loaded episodic module from {path}")
+                        break
+                except Exception as e:
+                    logger.debug(f"Could not load episodic from {path}: {e}")
+                    continue
+
+        if not episodic_module:
+            logger.debug("Episodic memory module not found - skipping episode capture")
+            return None
+
+        memory = episodic_module.EpisodicMemory()
+
+        # Use the real task description captured from the transcript.
+        # metrics["prompt"] now holds the first user message (task description)
+        # rather than the generic "SubagentStop for <agent>".
+        prompt = metrics.get("prompt", "")
+        if not prompt:
+            prompt = f"Task for {metrics.get('agent', 'unknown')}"
+
+        subagent_type = metrics.get("agent", "unknown")
+        duration_seconds = metrics.get("duration_ms", 0) / 1000.0 if metrics.get("duration_ms") else None
+
+        # Determine outcome: prefer plan_status string, fall back to exit_code
+        plan_status = metrics.get("plan_status", "")
+        exit_code = metrics.get("exit_code", 0)
+        if plan_status:
+            if "COMPLETE" in plan_status:
+                outcome = "success"
+                success = True
+            elif "BLOCKED" in plan_status or "ERROR" in plan_status:
+                outcome = "failed"
+                success = False
+            else:
+                # IN_PROGRESS, REVIEW, NEEDS_INPUT -> partial
+                outcome = "partial"
+                success = None
+        elif exit_code == 0:
+            outcome = "success"
+            success = True
+        else:
+            outcome = "failed"
+            success = False
+
+        # Tags from metrics -- filter empty strings defensively
+        tags = [t for t in metrics.get("tags", []) if t]
+        if not tags and subagent_type and subagent_type != "unknown":
+            tags = [subagent_type]
+
+        # Enrich with session events and anomalies
+        session_events = get_session_events()
+        context = {"metrics": metrics}
+        if session_events:
+            context["session_events"] = session_events
+            logger.info(f"Enriched episode with session events: {list(session_events.keys())}")
+        if anomalies:
+            context["anomalies"] = anomalies
+            logger.info(f"Episode has {len(anomalies)} anomaly/anomalies")
+
+        # Include context anchor hit tracking if available
+        anchor_hits = metrics.get("context_anchor_hits")
+        if anchor_hits:
+            context["context_anchor_hits"] = anchor_hits
+            logger.info(
+                "Episode anchor hits: %d/%d (%.0f%%)",
+                anchor_hits.get("hits", 0),
+                anchor_hits.get("total_checked", 0),
+                anchor_hits.get("hit_rate", 0) * 100,
+            )
+
+        # P3 CLI compatibility fields
+        episode_id = memory.store_episode(
+            prompt=prompt,
+            clarifications={},
+            enriched_prompt=prompt,
+            context=context,
+            tags=tags,
+            outcome=outcome,
+            success=success,
+            duration_seconds=duration_seconds,
+            commands_executed=commands_executed or [],
+            workflow_metrics=metrics,
+        )
+
+        logger.info(f"Captured episode: {episode_id} (outcome: {outcome}, plan_status: {plan_status})")
+        return episode_id
+
+    except Exception as e:
+        logger.debug(f"Failed to capture episodic memory: {e}")
+        return None

package/dist/gaia-ops/hooks/modules/orchestrator/__init__.py

@@ -0,0 +1 @@
+# Orchestrator enforcement modules.