@jaguilar87/gaia 5.0.0-rc.2

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

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

package/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/hooks/modules/evidence/__init__.py

@@ -0,0 +1,34 @@
+"""
+Evidence Runner module.
+
+Executes evidence.shape blocks declared in brief frontmatter
+and persists results under .claude/project-context/briefs/{feature}/evidence/.
+
+Sub-modules:
+- assertions: Declarative DSL for evaluating assert specs against data.
+- loader: Parses brief frontmatter into Evidence dataclass list.
+- runner: Dispatches command and artifact evidence types.
+- index_writer: Generates INDEX.md summary from run results.
+"""
+
+from .assertions import evaluate
+from .index_writer import write_index
+from .loader import (
+    Evidence,
+    InvalidBriefFrontmatter,
+    UnknownEvidenceType,
+    load_acs,
+)
+from .runner import EvidenceResult, run_artifact, run_command
+
+__all__ = [
+    "evaluate",
+    "Evidence",
+    "InvalidBriefFrontmatter",
+    "UnknownEvidenceType",
+    "load_acs",
+    "EvidenceResult",
+    "run_artifact",
+    "run_command",
+    "write_index",
+]

package/hooks/modules/evidence/assertions.py

@@ -0,0 +1,137 @@
+"""
+Declarative assertion DSL for evidence runner.
+
+Contract:
+    evaluate(assert_spec: dict, data: Any) -> bool
+
+Ops (10 total):
+    contains, equals, gte, lte, eq, ne,
+    has_field, length_gte, length_eq, matches
+
+Path resolution:
+    - Dotted segments traverse dict keys ("a.b.c").
+    - Root "" (empty path) targets `data` itself.
+    - Missing segment -> evaluate returns False (KeyError swallowed).
+
+Unknown ops raise ValueError -- fail fast rather than silently return False.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_ALLOWED_OPS = frozenset({
+    "contains",
+    "equals",
+    "eq",
+    "ne",
+    "gte",
+    "lte",
+    "has_field",
+    "length_gte",
+    "length_eq",
+    "matches",
+})
+
+
+class _Missing:
+    """Sentinel used by _resolve_path to distinguish 'absent' from 'None'."""
+
+    _instance: "_Missing | None" = None
+
+    def __new__(cls) -> "_Missing":
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+
+_MISSING = _Missing()
+
+
+def _resolve_path(data: Any, path: str) -> Any:
+    """Return the value at `path` or _MISSING if any segment is absent.
+
+    Empty path -> data itself.
+    """
+    if path == "" or path is None:
+        return data
+
+    current: Any = data
+    for segment in path.split("."):
+        if isinstance(current, dict) and segment in current:
+            current = current[segment]
+        else:
+            return _MISSING
+    return current
+
+
+def evaluate(assert_spec: dict, data: Any) -> bool:
+    """Evaluate a single assert spec against `data` and return a boolean.
+
+    assert_spec shape:
+        { op: <str>, path: <dotted str>, value: <literal> }
+        - value is optional for has_field.
+    """
+    op = assert_spec.get("op")
+    if op not in _ALLOWED_OPS:
+        raise ValueError(f"Unknown assert op: {op!r}")
+
+    path = assert_spec.get("path", "")
+    value = assert_spec.get("value")
+
+    resolved = _resolve_path(data, path)
+
+    # has_field: resolves entirely on presence/absence.
+    if op == "has_field":
+        return resolved is not _MISSING
+
+    # Every other op requires a resolved value.
+    if resolved is _MISSING:
+        return False
+
+    if op == "contains":
+        try:
+            return value in resolved
+        except TypeError:
+            return False
+
+    if op in ("equals", "eq"):
+        return resolved == value
+
+    if op == "ne":
+        return resolved != value
+
+    if op == "gte":
+        try:
+            return resolved >= value
+        except TypeError:
+            return False
+
+    if op == "lte":
+        try:
+            return resolved <= value
+        except TypeError:
+            return False
+
+    if op == "length_gte":
+        try:
+            return len(resolved) >= value
+        except TypeError:
+            return False
+
+    if op == "length_eq":
+        try:
+            return len(resolved) == value
+        except TypeError:
+            return False
+
+    if op == "matches":
+        if not isinstance(resolved, str) or not isinstance(value, str):
+            return False
+        try:
+            return re.search(value, resolved) is not None
+        except re.error:
+            return False
+
+    # Defensive; _ALLOWED_OPS was checked up front.
+    raise ValueError(f"Unhandled op: {op!r}")

package/hooks/modules/evidence/index_writer.py

@@ -0,0 +1,57 @@
+"""
+INDEX.md writer for evidence runs.
+
+Contract:
+    write_index(evidence_dir: Path, results: list[tuple[str, EvidenceResult]]) -> Path
+
+Produces `evidence_dir/INDEX.md` with:
+    - One table row per AC: id, type, passed, artifact, error.
+    - Deterministic output (same input -> same bytes).
+    - Re-execution replaces the file; it does not append.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable, Tuple
+
+from .runner import EvidenceResult
+
+
+_HEADER = "# Evidence Index\n\n"
+_TABLE_HEADER = (
+    "| AC | Status | Error |\n"
+    "|----|--------|-------|\n"
+)
+
+
+def _format_status(passed: bool) -> str:
+    return "pass" if passed else "fail"
+
+
+def _format_row(ac_id: str, result: EvidenceResult) -> str:
+    status = _format_status(result.passed)
+    error = result.error or ""
+    # Escape pipes in error messages so the table stays well-formed.
+    error = error.replace("|", "\\|")
+    return f"| {ac_id} | {status} | {error} |\n"
+
+
+def write_index(
+    evidence_dir: Path,
+    results: Iterable[Tuple[str, EvidenceResult]],
+) -> Path:
+    """Render INDEX.md under `evidence_dir` from `results`.
+
+    Idempotent: identical `results` produce identical bytes.
+    Replaces any existing INDEX.md (does not append).
+    """
+    evidence_dir = Path(evidence_dir)
+    evidence_dir.mkdir(parents=True, exist_ok=True)
+
+    rows = [_format_row(ac_id, result) for ac_id, result in results]
+
+    content = _HEADER + _TABLE_HEADER + "".join(rows)
+
+    index_path = evidence_dir / "INDEX.md"
+    index_path.write_text(content, encoding="utf-8")
+    return index_path