@jaguilar87/gaia-ops 4.4.0 → 4.7.2

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

@@ -0,0 +1,227 @@
+"""
+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, speckit)
+    """
+    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"
+        ]
+
+        speckit = [
+            {
+                "command": e.get("command", ""),
+                "timestamp": e.get("timestamp", "")
+            }
+            for e in critical_events
+            if e.get("event_type") == "speckit_milestone"
+        ]
+
+        result = {}
+        if commits:
+            result["git_commits"] = commits
+        if pushes:
+            result["git_pushes"] = pushes
+        if file_mods:
+            result["file_modifications"] = file_mods
+        if speckit:
+            result["speckit_milestones"] = speckit
+
+        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-security/hooks/modules/orchestrator/__init__.py

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

package/dist/gaia-security/hooks/modules/orchestrator/delegate_mode.py

@@ -0,0 +1,128 @@
+"""Orchestrator delegate mode enforcement.
+
+When GAIA is installed, delegate mode is always active. The orchestrator
+(main session) is restricted to dispatch-only tools. Direct investigation
+tools (Bash, Read, Edit, etc.) are blocked so the orchestrator must
+delegate to specialist agents.
+
+Detection: Claude Code includes ``agent_id`` and ``agent_type`` in the
+PreToolUse payload ONLY when the hook fires inside a subagent. Their absence
+means the call originates from the main session (orchestrator).
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+# Tools the orchestrator is allowed to use in delegate mode.
+# Everything NOT in this set is blocked for the main session.
+ORCHESTRATOR_ALLOWED_TOOLS = frozenset({
+    # Dispatch and communication
+    "agent",
+    "task",
+    "sendmessage",
+
+    # On-demand skills / procedures
+    "skill",
+
+    # Agent teams task management
+    "taskcreate",
+    "taskupdate",
+    "tasklist",
+    "taskget",
+
+    # Tool discovery
+    "toolsearch",
+
+    # Web research (read-only, T0)
+    "websearch",
+    "webfetch",
+
+    # User interaction (built-in, may not always trigger hooks)
+    "askuserquestion",
+})
+
+
+@dataclass(frozen=True)
+class DelegateModeResult:
+    """Result of delegate mode check."""
+
+    blocked: bool
+    reason: Optional[str] = None
+
+
+def is_orchestrator_context(hook_payload: Dict[str, Any]) -> bool:
+    """Determine if the hook is firing in the main session (orchestrator).
+
+    Claude Code includes ``agent_id`` in the PreToolUse payload only when
+    the tool call originates from a subagent. Its absence means the call
+    is from the main session.
+
+    Args:
+        hook_payload: The full stdin JSON dict from Claude Code.
+
+    Returns:
+        True if this is the orchestrator (main session), False if subagent.
+    """
+    agent_id = hook_payload.get("agent_id")
+    # agent_id is absent or empty string for the main session
+    return not agent_id
+
+
+def check_delegate_mode(
+    tool_name: str, hook_payload: Dict[str, Any]
+) -> DelegateModeResult:
+    """Check whether a tool call should be blocked by delegate mode.
+
+    This is the single entry point. Call it early in the PreToolUse flow.
+
+    Args:
+        tool_name: The tool being invoked (e.g., "Bash", "Read", "Edit").
+        hook_payload: The full stdin JSON dict from Claude Code.
+
+    Returns:
+        DelegateModeResult with blocked=True and a reason if the call
+        should be denied, or blocked=False if it should proceed.
+    """
+    is_orchestrator = is_orchestrator_context(hook_payload)
+    if not is_orchestrator:
+        # Subagents have full tool access -- delegate mode does not apply
+        agent_id = hook_payload.get("agent_id", "<none>")
+        logger.debug(
+            "delegate_mode check: SKIP (subagent %s) tool=%s",
+            agent_id,
+            tool_name,
+        )
+        return DelegateModeResult(blocked=False)
+
+    normalized = tool_name.lower().strip()
+    if normalized in ORCHESTRATOR_ALLOWED_TOOLS:
+        logger.debug(
+            "delegate_mode check: ALLOW (orchestrator allowed tool) tool=%s",
+            tool_name,
+        )
+        return DelegateModeResult(blocked=False)
+
+    logger.warning(
+        "DELEGATE_MODE blocked tool '%s' for orchestrator (main session)",
+        tool_name,
+    )
+
+    return DelegateModeResult(
+        blocked=True,
+        reason=(
+            f"[DELEGATE MODE] Tool '{tool_name}' is not available to the orchestrator.\n\n"
+            f"As the orchestrator, you must delegate work to specialist agents.\n"
+            f"Use the Agent tool to dispatch to the appropriate agent, or use\n"
+            f"SendMessage to resume an existing agent.\n\n"
+            f"Allowed orchestrator tools: Agent, SendMessage, Skill, TaskCreate, "
+            f"TaskUpdate, TaskList, TaskGet, ToolSearch, WebSearch, WebFetch, "
+            f"AskUserQuestion.\n\n"
+            f"Do NOT attempt to use {tool_name} directly. Identify the right\n"
+            f"specialist agent and delegate the work."
+        ),
+    )

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

@@ -0,0 +1,8 @@
+"""
+Scanning Module
+
+Provides tools for triggering project scans:
+- scan_trigger: Lightweight scan invocation for session-start auto-refresh
+"""
+
+__all__ = []

package/dist/gaia-security/hooks/modules/scanning/scan_trigger.py

@@ -0,0 +1,84 @@
+"""
+Lightweight scan trigger for SessionStart hook.
+
+Runs a subset of project scanners (e.g., tools + environment) to refresh
+project-context.json without significant startup delay (<3s target).
+
+Uses the scan engine directly (in-process) — no dependency on bin/gaia-scan.py.
+Works in both npm and plugin mode since tools/scan/ is always available.
+
+Public API:
+    - trigger_lightweight_scan(project_root: Path, scanners: list) -> bool
+"""
+
+import logging
+import sys
+import time
+from pathlib import Path
+from typing import List
+
+logger = logging.getLogger(__name__)
+
+
+def trigger_lightweight_scan(
+    project_root: Path,
+    scanners: List[str] = None,
+) -> bool:
+    """Run a lightweight scan using the scan engine directly.
+
+    Args:
+        project_root: Working directory for the scan.
+        scanners: List of scanner names to run. Defaults to
+            ["tools", "environment"].
+
+    Returns:
+        True on success, False on failure. Designed to complete in <3s.
+    """
+    if scanners is None:
+        scanners = ["tools", "environment"]
+
+    # Ensure tools.scan is importable by adding plugin root to sys.path
+    hooks_dir = Path(__file__).resolve().parents[2]  # hooks/
+    plugin_root = hooks_dir.parent
+    if str(plugin_root) not in sys.path:
+        sys.path.insert(0, str(plugin_root))
+
+    try:
+        from tools.scan.config import ScanConfig
+        from tools.scan.orchestrator import ScanOrchestrator
+        from tools.scan.registry import ScannerRegistry
+    except ImportError as e:
+        logger.warning("Cannot import scan engine: %s", e)
+        return False
+
+    try:
+        start = time.monotonic()
+
+        config = ScanConfig(
+            scanners=scanners,
+            project_root=project_root,
+        )
+        registry = ScannerRegistry()
+        orchestrator = ScanOrchestrator(registry=registry, config=config)
+        output = orchestrator.run(project_root=project_root)
+        elapsed = time.monotonic() - start
+
+        if output.errors:
+            logger.warning(
+                "Lightweight scan completed with errors in %.1fs: %s",
+                elapsed,
+                output.errors[:3],
+            )
+            return False
+
+        logger.info(
+            "Lightweight scan completed in %.1fs (scanners: %s, sections: %d)",
+            elapsed,
+            ", ".join(scanners),
+            output.sections_updated,
+        )
+        return True
+
+    except Exception as e:
+        logger.warning("Failed to run lightweight scan: %s", e)
+        return False

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

@@ -0,0 +1,89 @@
+"""
+Security module - Security tiers, blocked patterns, mutative verb detection.
+
+Provides:
+- tiers: SecurityTier enum and classification
+- blocked_commands: Permanently blocked pattern matching
+- mutative_verbs: Mutative verb detection (user approval workflow)
+- gitops_validator: kubectl/helm/flux validation
+- approval_constants: Approval token patterns (legacy APPROVE: and ElicitationResult)
+- approval_grants: Time-limited T3 command passthrough after user approval
+"""
+
+from .tiers import SecurityTier, classify_command_tier
+from .command_semantics import analyze_command, CommandSemantics
+from .blocked_commands import (
+    is_blocked_command,
+    get_blocked_patterns,
+    BlockedCommandResult,
+)
+from .gitops_validator import validate_gitops_workflow, GitOpsValidationResult
+from .mutative_verbs import (
+    CLI_FAMILY_LOOKUP,
+    CATEGORY_MUTATIVE,
+    CATEGORY_SIMULATION,
+    CATEGORY_READ_ONLY,
+    CATEGORY_UNKNOWN,
+)
+from .approval_constants import NONCE_APPROVAL_PATTERN, NONCE_APPROVAL_PREFIX
+from .approval_messages import (
+    CANONICAL_APPROVAL_TOKEN,
+    CANONICAL_APPROVAL_TOKEN_FORMAT,
+    CANONICAL_APPROVAL_TOKEN_GUIDANCE,
+    CANONICAL_APPROVAL_FORMAT_GUIDANCE,
+    LATEST_BLOCKED_COMMAND_PHRASE,
+)
+from .approval_scopes import (
+    ApprovalSignature,
+    SCOPE_EXACT_COMMAND,
+    SCOPE_SEMANTIC_SIGNATURE,
+    build_approval_signature,
+    matches_approval_signature,
+)
+from .approval_grants import (
+    check_approval_grant,
+    cleanup_expired_grants,
+    get_latest_pending_approval,
+    last_check_found_expired,
+    ApprovalGrant,
+)
+
+__all__ = [
+    # Tiers
+    "SecurityTier",
+    "classify_command_tier",
+    "analyze_command",
+    "CommandSemantics",
+    # Blocked commands
+    "is_blocked_command",
+    "get_blocked_patterns",
+    "BlockedCommandResult",
+    # GitOps
+    "validate_gitops_workflow",
+    "GitOpsValidationResult",
+    # Mutative verbs
+    "CLI_FAMILY_LOOKUP",
+    "CATEGORY_MUTATIVE",
+    "CATEGORY_SIMULATION",
+    "CATEGORY_READ_ONLY",
+    "CATEGORY_UNKNOWN",
+    # Approval
+    "NONCE_APPROVAL_PREFIX",
+    "NONCE_APPROVAL_PATTERN",
+    "CANONICAL_APPROVAL_TOKEN",
+    "CANONICAL_APPROVAL_TOKEN_FORMAT",
+    "CANONICAL_APPROVAL_TOKEN_GUIDANCE",
+    "CANONICAL_APPROVAL_FORMAT_GUIDANCE",
+    "LATEST_BLOCKED_COMMAND_PHRASE",
+    "ApprovalSignature",
+    "SCOPE_EXACT_COMMAND",
+    "SCOPE_SEMANTIC_SIGNATURE",
+    "build_approval_signature",
+    "matches_approval_signature",
+    # Approval Grants
+    "check_approval_grant",
+    "cleanup_expired_grants",
+    "get_latest_pending_approval",
+    "last_check_found_expired",
+    "ApprovalGrant",
+]

package/dist/gaia-security/hooks/modules/security/approval_cleanup.py

@@ -0,0 +1,87 @@
+"""
+Approval file cleanup for the subagent stop hook.
+
+Cleans up pending approval files after an agent completes, using the current
+per-nonce file layout under .claude/cache/approvals/pending-{nonce}.json.
+
+Provides:
+    - cleanup(): Delete pending approval files that match agent session
+    - consume_approval_file(): Backward-compatible alias for cleanup()
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import Optional
+
+from ..core.paths import find_claude_dir
+from ..core.state import get_session_id
+
+logger = logging.getLogger(__name__)
+
+
+def _get_approvals_dir() -> Path:
+    """Return the approvals cache directory."""
+    return find_claude_dir() / "cache" / "approvals"
+
+
+def cleanup(agent_type: str, session_id: Optional[str] = None) -> bool:
+    """
+    Delete pending-{nonce}.json files for the current session after agent completion.
+
+    Scans .claude/cache/approvals/ for pending files scoped to the current
+    session and removes them, preventing stale pending approvals from
+    accumulating after the agent run finishes.
+
+    Args:
+        agent_type: The agent type that just completed (for logging).
+        session_id: Session ID to scope cleanup (defaults to CLAUDE_SESSION_ID).
+
+    Returns:
+        True if any pending approval files were consumed, False otherwise.
+    """
+    if session_id is None:
+        session_id = get_session_id()
+
+    approvals_dir = _get_approvals_dir()
+    if not approvals_dir.exists():
+        return False
+
+    consumed = False
+    try:
+        for pending_file in approvals_dir.glob("pending-*.json"):
+            # Skip the per-session index files
+            if pending_file.name.startswith("pending-index-"):
+                continue
+            try:
+                data = json.loads(pending_file.read_text())
+                if data.get("session_id") != session_id:
+                    continue
+
+                pending_file.unlink(missing_ok=True)
+                logger.info(
+                    "Consumed pending approval for agent '%s' "
+                    "(nonce: %s, command: %s)",
+                    agent_type,
+                    data.get("nonce", "unknown"),
+                    data.get("command", "unknown"),
+                )
+                consumed = True
+
+            except (json.JSONDecodeError, TypeError):
+                # Corrupt file -- remove it
+                pending_file.unlink(missing_ok=True)
+                consumed = True
+            except Exception as e:
+                logger.debug(
+                    "Failed to process pending file %s (non-fatal): %s",
+                    pending_file.name, e,
+                )
+    except Exception as e:
+        logger.debug("Failed to scan approvals dir (non-fatal): %s", e)
+
+    return consumed
+
+
+# Backward-compatible alias
+consume_approval_file = cleanup

package/dist/gaia-security/hooks/modules/security/approval_constants.py

@@ -0,0 +1,23 @@
+"""Approval token patterns and deprecated approval phrases for T3 operation resumes.
+
+The APPROVE: prefix is a legacy path (SendMessage-based nonce relay). The primary
+approval flow now uses ElicitationResult (AskUserQuestion -> user clicks Approve).
+"""
+
+import re
+
+NONCE_APPROVAL_PREFIX = "APPROVE:"
+NONCE_APPROVAL_PATTERN = re.compile(r"\bAPPROVE:([a-f0-9]{32})\b")
+
+# Deprecated approval phrases that agents should not use.
+# Moved here from pre_tool_use.py so all approval-related constants live together.
+DEPRECATED_APPROVAL_PHRASES = (
+    "user approved:",
+    "user approval received",
+    "approved by user",
+    "approval confirmed",
+    "approved. execute",
+    "approved, execute",
+    "proceed with execution",
+    "confirmed. proceed",
+)