@jaguilar87/gaia 5.0.0-rc.2

package/hooks/modules/security/tiers.py

@@ -0,0 +1,196 @@
+"""
+Security tier definitions and classification.
+
+Provides tier metadata for commands after bash_validator has already
+enforced security decisions. The bash_validator is the primary gate;
+this module's classify_command_tier() is used for logging and state
+tracking.
+
+Tiers:
+- T0: Read-only operations (safe by elimination)
+- T1: Validation operations (validate, lint, fmt, check) -- local only
+- T2: Simulation operations (plan, diff, dry-run) -- may contact remote APIs
+- T3: State-modifying operations (mutative_verbs.py detection,
+  nonce-based approval via approval_grants.py)
+"""
+from __future__ import annotations
+
+import re
+import logging
+from enum import Enum
+from functools import lru_cache
+
+logger = logging.getLogger(__name__)
+
+
+class SecurityTier(str, Enum):
+    """Security tier classification for commands."""
+
+    T0_READ_ONLY = "T0"      # describe, get, show, list operations
+    T1_VALIDATION = "T1"     # validate, lint, fmt, check (local only)
+    T2_DRY_RUN = "T2"        # plan, diff, dry-run, template (simulation)
+    T3_BLOCKED = "T3"        # apply, reconcile, deploy operations (require approval)
+
+    def __str__(self) -> str:
+        return self.value
+
+    @property
+    def requires_approval(self) -> bool:
+        """Check if this tier requires user approval."""
+        return self == SecurityTier.T3_BLOCKED
+
+    @property
+    def description(self) -> str:
+        """Human-readable description of the tier."""
+        descriptions = {
+            SecurityTier.T0_READ_ONLY: "Read-only operation",
+            SecurityTier.T1_VALIDATION: "Validation operation",
+            SecurityTier.T2_DRY_RUN: "Dry-run operation",
+            SecurityTier.T3_BLOCKED: "State-modifying operation (requires approval)",
+        }
+        return descriptions.get(self, "Unknown tier")
+
+
+# T1: Local validation (no remote API calls)
+T1_PATTERNS = [
+    r"\bvalidate\b",
+    r"\blint\b",
+    r"\bcheck\b",
+    r"\bfmt\b",
+]
+
+# T2: Simulation (may contact remote APIs, but no state changes)
+T2_PATTERNS = [
+    r"\bplan\b",
+    r"\btemplate\b",
+    r"\bdiff\b",
+]
+
+# Ultra-common commands that should fast-path to T0
+# These are commands that appear in >80% of sessions
+# NOTE: Only include commands that are ALWAYS read-only regardless of flags.
+# "git branch" was removed because it has mutative variants (-D, -m, -M, etc.).
+ULTRA_COMMON_T0_COMMANDS = frozenset({
+    "ls", "pwd", "cat", "echo", "git status", "git diff",
+    "git log", "kubectl get",
+})
+
+
+@lru_cache(maxsize=512)
+def _classify_command_tier_cached(
+    command: str,
+    has_blocked_patterns: bool = False,
+) -> SecurityTier:
+    """
+    Classify command into security tier with LRU cache.
+
+    This is the internal cached implementation. Use classify_command_tier() instead.
+    """
+    if not command or not command.strip():
+        return SecurityTier.T3_BLOCKED
+
+    command = command.strip()
+
+    # Fast-path: Ultra-common T0 commands
+    words = command.split()
+    if len(words) >= 2:
+        prefix2 = f"{words[0]} {words[1]}"
+        if prefix2 in ULTRA_COMMON_T0_COMMANDS:
+            return SecurityTier.T0_READ_ONLY
+    if len(words) >= 1:
+        if words[0] in ULTRA_COMMON_T0_COMMANDS:
+            return SecurityTier.T0_READ_ONLY
+
+    # Blocked patterns already checked externally
+    if has_blocked_patterns:
+        return SecurityTier.T3_BLOCKED
+
+    # Check for dry-run operations (T2)
+    if "--dry-run" in command or "--plan-only" in command:
+        return SecurityTier.T2_DRY_RUN
+
+    # Check for simulation operations (T2: plan, diff, template)
+    for pattern in T2_PATTERNS:
+        if re.search(pattern, command, re.IGNORECASE):
+            return SecurityTier.T2_DRY_RUN
+
+    # Check for local validation operations (T1: validate, lint, fmt, check)
+    for pattern in T1_PATTERNS:
+        if re.search(pattern, command, re.IGNORECASE):
+            return SecurityTier.T1_VALIDATION
+
+    # Use the mutative verb detector for T3 classification
+    from .mutative_verbs import (
+        detect_mutative_command,
+        CATEGORY_MUTATIVE,
+        CATEGORY_READ_ONLY,
+        CATEGORY_SIMULATION,
+    )
+    result = detect_mutative_command(command)
+    if result.is_mutative:
+        return SecurityTier.T3_BLOCKED
+    if result.category == CATEGORY_SIMULATION:
+        return SecurityTier.T2_DRY_RUN
+    if result.category == CATEGORY_READ_ONLY:
+        return SecurityTier.T0_READ_ONLY
+
+    # Not blocked, not mutative -> safe by elimination (T0)
+    return SecurityTier.T0_READ_ONLY
+
+
+def classify_command_tier(
+    command: str,
+    *,
+    pre_computed_tier: "SecurityTier | None" = None,
+) -> SecurityTier:
+    """
+    Classify command into security tier.
+
+    NOTE: This function is used for tier metadata AFTER the bash_validator has
+    already enforced security decisions. The bash_validator's own validation
+    order (blocked -> safe -> dangerous verbs -> GitOps -> tier) is the primary
+    security gate.
+
+    If *pre_computed_tier* is provided (e.g. from a ``BashValidationResult``
+    that already determined the tier during validation), it is returned
+    immediately without re-computing.
+
+    Classification order (when no pre-computed tier):
+    1. Ultra-common T0 fast-path (ls, git status, etc.)
+    2. Blocked patterns (T3) -- checked against pre-compiled patterns
+    3. Dry-run/simulation (T2) -- --dry-run, plan, diff, template
+    4. Local validation (T1) -- validate, lint, fmt, check
+    5. Mutative verb detector (T3) -- MUTATIVE verbs
+    6. Default T0 for everything else (safe by elimination)
+
+    Args:
+        command: Shell command to classify
+        pre_computed_tier: Optional tier already determined by an upstream
+            validator.  When provided the function returns it directly.
+
+    Returns:
+        SecurityTier classification
+    """
+    # Fast path: caller already knows the tier (e.g. BashValidationResult).
+    if pre_computed_tier is not None:
+        return pre_computed_tier
+
+    if not command or not command.strip():
+        return SecurityTier.T3_BLOCKED
+
+    command = command.strip()
+
+    # Import here to avoid circular imports
+    from .blocked_commands import get_blocked_patterns
+    blocked_patterns = get_blocked_patterns()
+
+    # Check for blocked operations first (T3)
+    # This must be done before caching since blocked_patterns come from module state
+    has_blocked = False
+    for pattern in blocked_patterns:
+        if pattern.search(command):
+            has_blocked = True
+            break
+
+    # Use cached classification
+    return _classify_command_tier_cached(command, has_blocked)

package/hooks/modules/session/__init__.py

@@ -0,0 +1,10 @@
+"""Session management module.
+
+Provides:
+- session_manager: Session ID generation and management
+- session_event_injector: Filter and inject session events into agent prompts
+
+Note: session_state.py has been absorbed into modules.memory.episode_writer.
+"""
+
+__all__ = []

package/hooks/modules/session/pending_scanner.py

@@ -0,0 +1,174 @@
+"""Scan for deferred pending approvals and format a human-readable summary."""
+
+import json
+import logging
+import os
+import time
+from pathlib import Path
+from typing import List, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+
+def scan_pending_approvals(
+    approvals_dir: Path,
+    session_id: Optional[str] = None,
+    current_session_id: Optional[str] = None,
+    exclude_live_sessions: bool = False,
+) -> List[Dict]:
+    """Scan approvals directory for pending files.
+
+    Returns list of dicts with: nonce (short), command, verb, category,
+    age_human (e.g. "14 hours ago"), context (if enriched), timestamp,
+    cross_session (bool), pending_session_id.
+
+    If session_id provided, filter to that session. Otherwise return all.
+    current_session_id is used to annotate items from prior sessions
+    (cross_session=True when pending.session_id != current_session_id).
+
+    If exclude_live_sessions is True, pendings whose owning session_id
+    is currently registered as alive (per session_registry.get_live_sessions)
+    are filtered out. This is used by the [ACTIONABLE] injection path and
+    the `gaia approvals list --orphans-only` CLI flag to avoid showing
+    cross-session pendings that a parallel live session may still resolve.
+    On registry errors the function logs a warning and returns all pendings
+    unfiltered (conservative: better to show extras than lose real pendings).
+    """
+    results = []
+
+    if not approvals_dir.exists():
+        return results
+
+    for f in approvals_dir.glob("pending-*.json"):
+        if "index" in f.name:
+            continue
+        try:
+            data = json.loads(f.read_text())
+            # Clean up expired pendings (ttl > 0 and expired)
+            ttl = data.get("ttl_minutes", 0)
+            if ttl > 0:
+                elapsed = (time.time() - data.get("timestamp", 0)) / 60
+                if elapsed > ttl:
+                    try:
+                        os.unlink(str(f))
+                    except OSError:
+                        pass
+                    continue
+            # Clean up rejected pendings
+            if data.get("status") == "rejected":
+                try:
+                    os.unlink(str(f))
+                except OSError:
+                    pass
+                continue
+            # Filter by session if requested
+            if session_id and data.get("session_id") != session_id:
+                continue
+            # Format age
+            age_seconds = time.time() - data.get("timestamp", 0)
+            age_human = _format_age(age_seconds)
+
+            # Detect cross-session pending approvals
+            pending_sid = data.get("session_id", "unknown")
+            cross_session = bool(
+                current_session_id and pending_sid != current_session_id
+            )
+
+            results.append({
+                "nonce_short": data["nonce"][:8],
+                "nonce_full": data["nonce"],
+                "command": data.get("command", data.get("file_path", "unknown")),
+                "verb": data.get("danger_verb", "unknown"),
+                "category": data.get("danger_category", "UNKNOWN"),
+                "age_human": age_human,
+                "timestamp": data.get("timestamp", 0),
+                "context": data.get("context", {}),
+                "scope_type": data.get("scope_type", "semantic_signature"),
+                "cross_session": cross_session,
+                "pending_session_id": pending_sid,
+            })
+        except Exception:
+            continue
+
+    # Optionally exclude pendings whose owning session is currently alive.
+    # Lazy import keeps the registry dependency out of modules that call
+    # scan_pending_approvals() without the flag.
+    if exclude_live_sessions:
+        try:
+            from modules.session.session_registry import get_live_sessions
+            live = get_live_sessions()
+            results = [r for r in results if r["pending_session_id"] not in live]
+        except Exception as exc:  # noqa: BLE001 — deliberate broad catch
+            logger.warning(
+                "scan_pending_approvals: get_live_sessions() failed (%s) "
+                "— returning all pendings unfiltered",
+                exc,
+            )
+
+    # Sort by timestamp (oldest first)
+    results.sort(key=lambda x: x["timestamp"])
+    return results
+
+
+def format_pending_summary(pendings: List[Dict]) -> str:
+    """Format pending approvals as a readable summary for injection."""
+    if not pendings:
+        return ""
+
+    lines = [f"## {len(pendings)} aprobaciones pendientes\n"]
+    for i, p in enumerate(pendings, 1):
+        ctx = p["context"]
+        source = ctx.get("source", "unknown")
+        desc = ctx.get("description", p["command"])
+        risk = ctx.get("risk", "unknown")
+
+        cross_tag = " [session anterior]" if p.get("cross_session") else ""
+        lines.append(f"**#{i} [P-{p['nonce_short']}]** `{p['command'][:60]}`{cross_tag}")
+        lines.append(f"  Hace: {p['age_human']} | Source: {source} | Risk: {risk}")
+        if desc != p["command"]:
+            lines.append(f"  {desc}")
+        lines.append("")
+
+    lines.append('Di "ver P-XXXX" para detalles o "aprobar P-XXXX" para ejecutar.')
+    return "\n".join(lines)
+
+
+def format_pending_detail(pending: Dict) -> str:
+    """Format a single pending approval with full details."""
+    ctx = pending["context"]
+    lines = [
+        f"## Detalle P-{pending['nonce_short']}",
+        "",
+        f"**OPERACION:** {pending['verb']} ({pending['category']})",
+        f"**COMANDO:** `{pending['command']}`",
+    ]
+    if ctx.get("description"):
+        lines.append(f"**CONTEXTO:** {ctx['description']}")
+    if ctx.get("source"):
+        lines.append(f"**SOURCE:** {ctx['source']}")
+    if ctx.get("branch"):
+        lines.append(f"**BRANCH:** {ctx['branch']}")
+    if ctx.get("files_changed"):
+        lines.append(f"**ARCHIVOS:** {', '.join(ctx['files_changed'])}")
+    if ctx.get("risk"):
+        lines.append(f"**RIESGO:** {ctx['risk']}")
+    if ctx.get("rollback"):
+        lines.append(f"**ROLLBACK:** {ctx['rollback']}")
+    lines.append(f"**EDAD:** {pending['age_human']}")
+    lines.append("")
+    lines.append(f'"aprobar P-{pending["nonce_short"]}" o "rechazar P-{pending["nonce_short"]}"')
+    return "\n".join(lines)
+
+
+def _format_age(seconds: float) -> str:
+    """Format seconds into human-readable age."""
+    if seconds < 60:
+        return f"{int(seconds)}s"
+    elif seconds < 3600:
+        return f"{int(seconds/60)} min"
+    elif seconds < 86400:
+        hours = int(seconds / 3600)
+        return f"{hours} hora{'s' if hours > 1 else ''}"
+    else:
+        days = int(seconds / 86400)
+        return f"{days} dia{'s' if days > 1 else ''}"

package/hooks/modules/session/session_context_writer.py

@@ -0,0 +1,100 @@
+"""
+Session context writer for PostToolUse hook.
+
+Manages the active session context file, appending critical events
+(git commits, pushes, etc.) and applying a time-based retention policy.
+
+Public API:
+    - SessionContextWriter  (class with update_context method)
+"""
+
+import fcntl
+import json
+import logging
+import os
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Dict, Any
+
+from ..core.paths import get_session_dir
+
+logger = logging.getLogger(__name__)
+
+# Default retention period for session events
+DEFAULT_RETENTION_HOURS = 24
+
+
+class SessionContextWriter:
+    """Update active session context for critical events.
+
+    Thread-safe via file locking. Applies a configurable retention
+    policy (default 24h, override via SESSION_RETENTION_HOURS env var).
+    """
+
+    def __init__(self, context_path: Path = None):
+        """Initialize with optional custom context path.
+
+        Args:
+            context_path: Override path. Defaults to session_dir/context.json.
+        """
+        self.context_path = context_path or (get_session_dir() / "context.json")
+
+    def update_context(self, event_data: Dict[str, Any]) -> None:
+        """Update active context with event data.
+
+        Appends the event to the critical_events list, applies retention
+        policy, and writes back atomically with file locking.
+
+        Args:
+            event_data: Event dict (must include at least event_type).
+        """
+        try:
+            self.context_path.parent.mkdir(parents=True, exist_ok=True)
+
+            # File lock to prevent race conditions from parallel tool calls
+            lock_path = self.context_path.with_suffix(".lock")
+            with open(lock_path, "w") as lock_file:
+                fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX)
+                try:
+                    context: Dict[str, Any] = {}
+                    if self.context_path.exists():
+                        with open(self.context_path, "r") as f:
+                            context = json.load(f)
+
+                    if "critical_events" not in context:
+                        context["critical_events"] = []
+
+                    event_data["timestamp"] = datetime.now().isoformat()
+
+                    context["critical_events"].append(event_data)
+
+                    # Keep only events within retention window
+                    retention_hours = int(
+                        os.environ.get(
+                            "SESSION_RETENTION_HOURS",
+                            str(DEFAULT_RETENTION_HOURS),
+                        )
+                    )
+                    cutoff = datetime.now() - timedelta(hours=retention_hours)
+
+                    context["critical_events"] = [
+                        event
+                        for event in context["critical_events"]
+                        if event.get("timestamp")
+                        and datetime.fromisoformat(event["timestamp"]) > cutoff
+                    ]
+
+                    context["last_modified"] = datetime.now().isoformat()
+
+                    with open(self.context_path, "w") as f:
+                        json.dump(context, f, indent=2)
+                finally:
+                    fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)
+
+            logger.info(
+                "Updated context with event: %s",
+                event_data.get("event_type", "unknown"),
+            )
+
+        except Exception as e:
+            logger.error("Error updating active context: %s", e)

package/hooks/modules/session/session_event_injector.py

@@ -0,0 +1,160 @@
+"""Session event injection for agent context.
+
+Subsystem 4 of the pre_tool_use Task/Agent path.
+
+Filters events by agent domain and injects them into agent prompts.
+Includes the hardcoded agent-to-event mapping.
+"""
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Agent-to-event-type mapping: which events each agent should see
+AGENT_EVENT_FILTERS = {
+    "terraform-architect": ["git_commit", "infrastructure_change"],
+    "gitops-operator": ["git_commit", "git_push", "infrastructure_change"],
+    "developer": ["git_commit", "file_modifications"],
+    "cloud-troubleshooter": "*",  # All events (needs full history for diagnosis)
+    "gaia-system": "*",  # All events (workflow analysis)
+    "gaia-operator": ["git_commit", "file_modifications", "infrastructure_change"],
+    "gaia-planner": ["git_commit", "file_modifications"],
+}
+
+
+def filter_events_for_agent(events: list, agent: str) -> list:
+    """
+    Filter events relevant to agent domain.
+
+    Args:
+        events: List of critical events from session
+        agent: Agent type (e.g., "gitops-operator")
+
+    Returns:
+        Filtered list of events relevant to agent
+    """
+    agent_filter = AGENT_EVENT_FILTERS.get(agent, [])
+
+    # Return all events for wildcard agents
+    if agent_filter == "*":
+        return events[-10:]  # Last 10 events
+
+    # Filter by event type and return max 10
+    filtered = [
+        e for e in events[-20:]  # Search last 20
+        if e.get("event_type") in agent_filter
+    ]
+
+    return filtered[:10]  # Return max 10
+
+
+def format_events_summary(events: list) -> str:
+    """
+    Format events as readable summary for agent context.
+
+    Args:
+        events: List of filtered events
+
+    Returns:
+        Formatted markdown string
+    """
+    if not events:
+        return "No recent events"
+
+    lines = []
+
+    for event in events:
+        etype = event.get("event_type", "")
+        ts = event.get("timestamp", "")[:16]  # YYYY-MM-DDTHH:MM
+
+        if etype == "git_commit":
+            msg = event.get("commit_message", "")
+            hash_val = event.get("commit_hash", "")[:7]
+            if hash_val and msg:
+                lines.append(f"- [{ts}] Commit {hash_val}: {msg}")
+
+        elif etype == "git_push":
+            branch = event.get("branch", "")
+            if branch:
+                lines.append(f"- [{ts}] Pushed to {branch}")
+
+        elif etype == "file_modifications":
+            count = event.get("modification_count", 0)
+            if count:
+                lines.append(f"- [{ts}] Modified {count} files")
+
+        elif etype == "infrastructure_change":
+            cmd = event.get("command", "")
+            if cmd:
+                lines.append(f"- [{ts}] Infrastructure: {cmd}")
+
+    return "\n".join(lines) if lines else "No recent events"
+
+
+def build_session_events(
+    parameters: dict,
+    project_agents: list,
+) -> str | None:
+    """
+    Build session events string for agent context without mutating parameters.
+
+    Filters events by agent domain to avoid noise.
+    Returns the events string suitable for additionalContext injection,
+    or None if no events to inject.
+
+    Args:
+        parameters: Task tool parameters (read-only).
+        project_agents: List of valid project agent names.
+
+    Returns:
+        Session events string, or None if nothing to inject.
+    """
+    subagent_type = parameters.get("subagent_type", "")
+
+    # Only inject for project agents
+    if subagent_type not in project_agents:
+        logger.debug(f"Skipping session events for non-project agent: {subagent_type}")
+        return None
+
+    # Get session events
+    from ..core.paths import get_session_dir
+    context_path = get_session_dir() / "context.json"
+    if not context_path.exists():
+        logger.debug("No session context file found")
+        return None
+
+    try:
+        with open(context_path, 'r') as f:
+            context = json.load(f)
+
+        events = context.get("critical_events", [])
+        if not events:
+            logger.debug("No critical events in session")
+            return None
+
+        # Filter by agent domain
+        filtered = filter_events_for_agent(events, subagent_type)
+
+        if not filtered:
+            logger.debug(f"No relevant events for {subagent_type}")
+            return None
+
+        # Format events summary
+        events_summary = format_events_summary(filtered)
+
+        events_string = (
+            "# Recent Session Events (Auto-Injected, Last 24h)\n"
+            f"{events_summary}"
+        )
+        logger.info(f"Session events built for {subagent_type} ({len(filtered)} events)")
+
+        return events_string
+
+    except Exception as e:
+        logger.warning(f"Failed to build session events: {e}")
+        return None
+
+

package/hooks/modules/session/session_manager.py

@@ -0,0 +1,31 @@
+"""
+Session ID generation and retrieval.
+
+Provides:
+    - get_or_create_session_id(): Get existing session ID or create new one
+"""
+
+import hashlib
+import logging
+import os
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+
+def get_or_create_session_id() -> str:
+    """Get existing session ID or create new one.
+
+    Checks the CLAUDE_SESSION_ID env var first.  If absent, generates a
+    new session ID from the current time and PID, stores it in the env var,
+    and returns it.
+    """
+    session_id = os.environ.get("CLAUDE_SESSION_ID")
+    if not session_id:
+        timestamp = datetime.now().strftime("%H%M%S")
+        hash_input = f"{timestamp}-{os.getpid()}"
+        session_hash = hashlib.sha256(hash_input.encode()).hexdigest()[:8]
+        session_id = f"session-{timestamp}-{session_hash}"
+        os.environ["CLAUDE_SESSION_ID"] = session_id
+        logger.debug(f"Generated new session_id: {session_id}")
+    return session_id