@jaguilar87/gaia-ops 4.4.0 → 4.7.2

package/dist/gaia-security/hooks/adapters/types.py

@@ -0,0 +1,194 @@
+"""
+Adapter Normalized Types for Gaia-Ops Hooks.
+
+CLI-agnostic frozen dataclasses and enums consumed by business logic modules.
+The adapter layer translates between these types and CLI-specific JSON protocols.
+
+No dependencies on any existing gaia-ops module -- this is standalone.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+class HookEventType(enum.Enum):
+    """All Claude Code hook events as an enumeration."""
+
+    # P0 - Currently implemented
+    PRE_TOOL_USE = "PreToolUse"
+    POST_TOOL_USE = "PostToolUse"
+    SUBAGENT_STOP = "SubagentStop"
+
+    # P1
+    SESSION_START = "SessionStart"
+    USER_PROMPT_SUBMIT = "UserPromptSubmit"
+
+    # P2
+    PERMISSION_REQUEST = "PermissionRequest"
+    STOP = "Stop"
+    TASK_COMPLETED = "TaskCompleted"
+    SUBAGENT_START = "SubagentStart"
+
+    # P3
+    PRE_COMPACT = "PreCompact"
+    POST_COMPACT = "PostCompact"
+    CONFIG_CHANGE = "ConfigChange"
+    SESSION_END = "SessionEnd"
+    INSTRUCTIONS_LOADED = "InstructionsLoaded"
+    POST_TOOL_USE_FAILURE = "PostToolUseFailure"
+
+    # P4
+    NOTIFICATION = "Notification"
+
+    # P5 - Additional events
+    TEAMMATE_IDLE = "TeammateIdle"
+    WORKTREE_CREATE = "WorktreeCreate"
+    WORKTREE_REMOVE = "WorktreeRemove"
+    PROMPT_SUBMIT = "PromptSubmit"  # Deprecated alias for USER_PROMPT_SUBMIT
+
+
+class PermissionDecision(enum.Enum):
+    """Hook permission decision values."""
+
+    ALLOW = "allow"
+    DENY = "deny"
+    ASK = "ask"
+
+
+class DistributionChannel(enum.Enum):
+    """How gaia-ops was installed and is being invoked."""
+
+    NPM = "npm"
+    PLUGIN = "plugin"
+
+
+@dataclass(frozen=True)
+class HookEvent:
+    """Normalized hook event, CLI-agnostic.
+
+    Produced by the adapter's parse_event() method.
+    """
+
+    event_type: HookEventType
+    session_id: str
+    payload: Dict[str, Any]
+    channel: DistributionChannel
+    plugin_root: Optional[Path] = None
+
+
+@dataclass(frozen=True)
+class ValidationRequest:
+    """Pre-tool-use validation request extracted from a HookEvent."""
+
+    tool_name: str
+    command: str
+    tool_input: Dict[str, Any]
+    session_id: str
+
+
+@dataclass(frozen=True)
+class ValidationResult:
+    """CLI-agnostic validation result from business logic.
+
+    Business logic produces this; the adapter formats it for the CLI.
+    """
+
+    allowed: bool = True
+    reason: str = ""
+    tier: str = "T0"
+    modified_input: Optional[Dict[str, Any]] = None
+    suggestions: List[str] = field(default_factory=list)
+    nonce: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class ToolResult:
+    """Post-tool-use result data extracted from a HookEvent."""
+
+    tool_name: str
+    command: str
+    output: str
+    exit_code: int
+    session_id: str
+
+
+@dataclass(frozen=True)
+class AgentCompletion:
+    """Subagent completion data extracted from a HookEvent."""
+
+    agent_type: str
+    agent_id: str
+    transcript_path: str
+    last_message: str
+    session_id: str
+
+
+@dataclass(frozen=True)
+class CompletionResult:
+    """Result of processing an agent completion event."""
+
+    contract_valid: bool = True
+    episode_id: Optional[str] = None
+    context_updated: bool = False
+    anomalies: List[Dict[str, Any]] = field(default_factory=list)
+    repair_needed: bool = False
+
+
+@dataclass(frozen=True)
+class ContextResult:
+    """Result of context injection processing."""
+
+    context_injected: bool = False
+    additional_context: Optional[str] = None
+    sections_provided: List[str] = field(default_factory=list)
+    # Reserved for future adapter use
+    prompt_text: str = ""
+
+
+@dataclass(frozen=True)
+class BootstrapResult:
+    """Result of project bootstrap/scanning."""
+
+    project_scanned: bool = False
+    context_path: Optional[Path] = None
+    tools_detected: List[str] = field(default_factory=list)
+    # P1 fields: SessionStart adapter populates these
+    should_scan: bool = False
+    should_refresh: bool = False
+    session_type: str = "startup"
+
+
+@dataclass(frozen=True)
+class QualityResult:
+    """Result of a Stop event -- whether evidence quality meets threshold."""
+
+    quality_sufficient: bool = True
+    score: float = 1.0
+    missing_elements: List[str] = field(default_factory=list)
+    recommendation: str = "continue"
+
+
+@dataclass(frozen=True)
+class VerificationResult:
+    """Result of a TaskCompleted event -- whether completion criteria are met."""
+
+    criteria_met: bool = True
+    verified_items: List[str] = field(default_factory=list)
+    failed_items: List[str] = field(default_factory=list)
+    block_completion: bool = False
+
+
+@dataclass(frozen=True)
+class HookResponse:
+    """CLI-specific hook response. Constructed by adapter, not business logic."""
+
+    output: Dict[str, Any]
+    exit_code: int = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize to a dictionary suitable for JSON output."""
+        return {"output": self.output, "exit_code": self.exit_code}

package/dist/gaia-security/hooks/adapters/utils.py

@@ -0,0 +1,25 @@
+"""
+Shared utility functions for Gaia-Ops hooks.
+
+Centralizes common patterns that were previously copy-pasted across all hook
+entry points (has_stdin_data, dual-channel warnings, etc.).
+
+``has_stdin_data`` is now defined in ``modules.core.stdin`` and re-exported
+here for backward compatibility with existing imports.
+"""
+
+import logging
+
+from modules.core.stdin import has_stdin_data  # noqa: F401 -- re-export
+
+logger = logging.getLogger(__name__)
+
+
+def warn_if_dual_channel() -> None:
+    """Log a warning if both plugin and npm distribution channels are active."""
+    from adapters.channel import is_dual_channel_active
+
+    if is_dual_channel_active():
+        logger.warning(
+            "Both plugin and npm channels detected. Plugin channel takes precedence."
+        )

package/dist/gaia-security/hooks/hooks.json

@@ -0,0 +1,57 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre_tool_use.py"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post_tool_use.py"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/stop_hook.py"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/user_prompt_submit.py"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session_start.py"
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,15 @@
+"""
+Gaia-Ops Hooks Modular Architecture
+
+This package provides a modular, maintainable hook system for Claude Code.
+
+Modules:
+- core: Shared utilities (paths, state, config loading)
+- security: Security tiers, safe commands, blocked patterns
+- tools: Tool-specific validators (Bash, Task)
+- workflow: Phase validation and state tracking
+- audit: Logging, metrics, event detection
+- agents: Subagent metrics and anomaly detection
+"""
+
+__version__ = "2.0.0"

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

@@ -0,0 +1,29 @@
+"""Agents module."""
+
+from .response_contract import (
+    CONSOLIDATION_FIELDS,
+    EVIDENCE_FIELDS,
+    EVIDENCE_REQUIRED_PLAN_STATUSES,
+    VALID_PLAN_STATUSES,
+    VALID_OWNERSHIP_ASSESSMENTS,
+    load_last_validation,
+    parse_agent_status,
+    parse_consolidation_report,
+    parse_evidence_report,
+    save_validation_result,
+    validate_response_contract,
+)
+
+__all__ = [
+    "CONSOLIDATION_FIELDS",
+    "EVIDENCE_FIELDS",
+    "EVIDENCE_REQUIRED_PLAN_STATUSES",
+    "VALID_PLAN_STATUSES",
+    "VALID_OWNERSHIP_ASSESSMENTS",
+    "load_last_validation",
+    "parse_agent_status",
+    "parse_consolidation_report",
+    "parse_evidence_report",
+    "save_validation_result",
+    "validate_response_contract",
+]