@jaguilar87/gaia 5.0.0-rc.2

package/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/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/hooks/elicitation_result.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""ElicitationResult hook -- activates T3 approval grants when user approves via AskUserQuestion.
+
+This hook fires after the user responds to an AskUserQuestion elicitation.
+It checks if the response indicates approval and, if so, activates all
+pending approval grants for the current session.
+
+The hook NEVER blocks (always exits 0). It is purely side-effectful:
+reading the user's answer and activating grants when appropriate.
+"""
+from __future__ import annotations
+
+import sys
+import json
+import logging
+import os
+from datetime import datetime
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from modules.core.paths import get_logs_dir
+from modules.core.stdin import has_stdin_data
+
+# Configure logging -- file only, no stderr
+_log_file = get_logs_dir() / f"hooks-{datetime.now().strftime('%Y-%m-%d')}.log"
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s [elicitation_result] %(name)s - %(levelname)s - %(message)s',
+    handlers=[logging.FileHandler(_log_file)],
+)
+logger = logging.getLogger(__name__)
+
+
+def _extract_response(event: dict) -> str | None:
+    """Extract the user's answer from the ElicitationResult event.
+
+    The exact schema is not fully documented, so we probe multiple
+    possible field names defensively.
+    """
+    # Try top-level fields first
+    for field in ("result", "answer", "response", "selected", "value",
+                  "hookEventInput", "elicitation_result"):
+        val = event.get(field)
+        if val is None:
+            continue
+        if isinstance(val, str) and val.strip():
+            return val
+        if isinstance(val, dict):
+            # Nested -- look for answer/selected inside
+            for inner in ("answer", "selected", "value", "result", "label"):
+                inner_val = val.get(inner)
+                if inner_val and isinstance(inner_val, str):
+                    return inner_val
+            # Check for answers dict (AskUserQuestion structured format)
+            answers = val.get("answers", {})
+            if answers and isinstance(answers, dict):
+                first_val = next(iter(answers.values()), None)
+                if first_val:
+                    return str(first_val)
+            # Check for options list selection
+            options = val.get("options", [])
+            if options and isinstance(options, list):
+                for opt in options:
+                    if isinstance(opt, dict) and opt.get("selected"):
+                        return str(opt.get("label", opt.get("value", "")))
+    return None
+
+
+def _is_approval(response: str) -> bool:
+    """Check if the response indicates approval."""
+    normalized = response.lower().strip()
+    approval_words = ["approve", "approved", "yes", "accept", "confirm", "allow"]
+    return any(word in normalized for word in approval_words)
+
+
+def _activate_grants(session_id: str, response: str = "") -> None:
+    """Activate approval grants for this session.
+
+    When *response* contains a ``[P-<nonce>]`` tag (nonce-labeled approval),
+    only the specific grant identified by that nonce is activated.  When no
+    nonce is present (legacy approvals that predate nonce labeling) the
+    function falls back to session-wide activation for backward compatibility.
+    """
+    from modules.security.approval_grants import (
+        activate_grants_for_session,
+        activate_pending_approval,
+        activate_cross_session_pending,
+        extract_nonce_from_label,
+        load_pending_by_nonce_prefix,
+        get_pending_approvals_for_session,
+    )
+
+    # Try nonce-targeted activation first
+    nonce_prefix = extract_nonce_from_label(response) if response else None
+    if nonce_prefix:
+        logger.info(
+            "ElicitationResult: nonce prefix found in response: %s", nonce_prefix,
+        )
+        pending_data = load_pending_by_nonce_prefix(nonce_prefix)
+        if pending_data:
+            full_nonce = pending_data.get("nonce", "")
+            pending_session = pending_data.get("session_id", "")
+            if pending_session == session_id:
+                # Same session -- standard targeted activation
+                result = activate_pending_approval(
+                    nonce=full_nonce, session_id=session_id,
+                )
+            else:
+                # Cross-session pending -- approval came from a prior session
+                result = activate_cross_session_pending(
+                    pending_data, session_id=session_id,
+                )
+            logger.info(
+                "ElicitationResult nonce-targeted activation: "
+                "nonce=%s success=%s status=%s",
+                full_nonce[:12] if full_nonce else nonce_prefix,
+                result.success,
+                result.status,
+            )
+            return
+        else:
+            logger.warning(
+                "ElicitationResult: nonce prefix %s not found in pending files, "
+                "falling back to session-wide activation",
+                nonce_prefix,
+            )
+
+    # Fallback: session-wide activation (backward compat for unlabeled approvals)
+    pending = get_pending_approvals_for_session(session_id)
+    if not pending:
+        logger.info("No pending approvals to activate for session %s", session_id)
+        return
+
+    results = activate_grants_for_session(session_id)
+    activated = sum(1 for r in results if r.success)
+    logger.info(
+        "ElicitationResult activated %d/%d pending approvals for session %s",
+        activated, len(results), session_id,
+    )
+
+
+if __name__ == "__main__":
+    if not has_stdin_data():
+        sys.exit(0)
+
+    try:
+        raw = sys.stdin.read()
+        if not raw.strip():
+            sys.exit(0)
+
+        event = json.loads(raw)
+
+        # Extract session_id from event or environment
+        session_id = event.get("session_id") or os.environ.get("CLAUDE_SESSION_ID", "")
+
+        # Extract user's response
+        response = _extract_response(event)
+
+        if not response:
+            logger.info("No extractable response in ElicitationResult event")
+            sys.exit(0)
+
+        logger.info("ElicitationResult response: %s", response[:80])
+
+        # Check if the response indicates approval
+        if _is_approval(response):
+            if session_id:
+                _activate_grants(session_id, response=response)
+            else:
+                logger.warning("Approval detected but no session_id available")
+        else:
+            logger.info("ElicitationResult response is not an approval: %s", response[:40])
+
+    except Exception as e:
+        logger.error("Error in elicitation_result hook: %s", e, exc_info=True)
+
+    # Never block -- always exit 0
+    sys.exit(0)

package/hooks/hooks.json

@@ -0,0 +1,84 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{"type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre_tool_use.py"}]
+      },
+      {
+        "matcher": "Task",
+        "hooks": [{"type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre_tool_use.py"}]
+      },
+      {
+        "matcher": "Agent",
+        "hooks": [{"type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre_tool_use.py"}]
+      },
+      {
+        "matcher": "SendMessage",
+        "hooks": [{"type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre_tool_use.py"}]
+      },
+      {
+        "matcher": "Read|Edit|Write|Glob|Grep|WebSearch|WebFetch|NotebookEdit",
+        "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"}]
+      },
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [{"type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post_tool_use.py"}]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": "*",
+        "hooks": [{"type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/subagent_stop.py"}]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [{"type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session_start.py"}]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [{"type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/stop_hook.py"}]
+      }
+    ],
+    "TaskCompleted": [
+      {
+        "hooks": [{"type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/task_completed.py"}]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": "*",
+        "hooks": [{"type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/subagent_start.py"}]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [{"type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/user_prompt_submit.py"}]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [{"type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre_compact.py"}]
+      }
+    ],
+    "PostCompact": [
+      {
+        "hooks": [{"type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post_compact.py"}]
+      }
+    ],
+    "ElicitationResult": [
+      {
+        "hooks": [{"type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/elicitation_result.py"}]
+      }
+    ]
+  }
+}

package/hooks/modules/README.md

@@ -0,0 +1,189 @@
+# Hooks Modular Architecture
+
+This directory contains the modular hook system for gaia-ops.
+
+## What is this?
+
+A refactored, maintainable architecture for Claude Code hooks. Instead of monolithic 1000+ line files, the logic is split into focused modules that can be tested, maintained, and extended independently.
+
+## Where does this fit?
+
+```
+Claude Code invokes hook
+        |
+        v
+[session_start.py] --------> [modules/context/context_freshness] -> Staleness check
+        |                     [modules/scanning/scan_trigger]     -> Auto-refresh
+        v
+[pre_tool_use.py] ---------> [modules/security/*] -> Tier classification
+        |                     [modules/tools/*]   -> Bash/Task validation
+        v
+    Tool executes
+        |
+        v
+[post_tool_use.py] --------> [modules/audit/*]    -> Logging & metrics
+                              [modules/session/*]  -> Session context updates
+                              [modules/agents/*]   -> Anomaly detection
+```
+
+## Module Structure
+
+```
+modules/
+├── __init__.py           # Package marker
+├── core/                 # Shared utilities
+│   ├── __init__.py
+│   ├── paths.py          # find_claude_dir() - single source of truth
+│   └── state.py          # Pre/post hook state sharing
+│
+├── security/             # Security classification & approval
+│   ├── __init__.py
+│   ├── tiers.py          # SecurityTier enum (T0-T3)
+│   ├── blocked_commands.py # Blocked patterns by category
+│   ├── mutative_verbs.py   # CLI-agnostic verb detector, nonce-based deny
+│   ├── approval_grants.py  # Nonce-based approval grant management
+│   ├── approval_constants.py # Approval system constants
+│   ├── approval_messages.py  # Approval denial message formatting
+│   ├── approval_scopes.py   # Approval scope definitions
+│   ├── command_semantics.py  # Command semantic analysis
+│   └── gitops_validator.py # kubectl/helm/flux validation
+│
+├── tools/                # Tool-specific validators
+│   ├── __init__.py
+│   ├── shell_parser.py   # Parse compound commands
+│   ├── bash_validator.py # Bash command validation (orchestrates pipeline)
+│   ├── task_validator.py # Task tool validation with context enforcement
+│   ├── cloud_pipe_validator.py # Cloud pipe/redirect/chain check
+│   └── hook_response.py  # Standardized hook response formatting
+│
+├── context/              # Context management
+│   ├── __init__.py
+│   ├── context_writer.py # Write context updates
+│   └── context_freshness.py     # Check staleness for SessionStart
+│
+├── scanning/             # Scan triggering
+│   ├── __init__.py
+│   └── scan_trigger.py   # Lightweight scan invocation for SessionStart
+│
+├── session/              # Session context management
+│   ├── __init__.py
+│   └── session_context_writer.py # Write critical events to session context
+│
+├── validation/           # Commit validation
+│   ├── __init__.py
+│   └── commit_validator.py # Conventional Commits enforcement
+│
+├── audit/                # Logging and metrics
+│   ├── __init__.py
+│   ├── logger.py         # AuditLogger
+│   ├── metrics.py        # MetricsCollector + FUNCTIONAL generate_summary
+│   └── event_detector.py # CriticalEventDetector
+│
+├── identity/             # Orchestrator identity injection
+│   ├── __init__.py
+│   ├── identity_provider.py # Build identity based on installed plugins
+│   ├── ops_identity.py      # Ops mode: minimal identity + on-demand skills
+│   └── security_identity.py # Security-only mode identity
+│
+└── agents/               # Subagent support
+    ├── __init__.py
+    └── response_contract.py # Agent response contract validation
+```
+
+## Key Features
+
+### Orchestrator Gate
+The orchestrator is restricted to four tools:
+- `Agent` -- dispatch work to specialist agents
+- `SendMessage` -- resume a previously spawned agent
+- `AskUserQuestion` -- get clarification or approval from the user
+- `Skill` -- load on-demand procedures
+
+This enforces the principle: "Orchestrator delegates, agents execute."
+
+### SendMessage Validation (PreToolUse matcher)
+SendMessage is validated as a PreToolUse event (not a separate hook event):
+- Agent ID format check (must match `/^a[0-9a-f]{5,}$/`)
+- Non-empty message required
+- Grant activation is handled by ElicitationResult hook (user approval via AskUserQuestion)
+
+### Context Enforcement
+Task invocations for project agents inject project-context via `context_provider.py`.
+
+### State Sharing
+Pre-hook saves state to `.claude/.hooks_state.json`, which post-hook reads to get:
+- Security tier assigned
+- Command executed
+- Timestamp for duration calculation
+
+### Functional Metrics
+`generate_summary()` now actually works - reads JSONL metrics files and aggregates:
+- Total executions
+- Success rate
+- Average duration
+- Top command types
+- Tier distribution
+
+## Usage
+
+### Entry Points
+
+```bash
+# Pre-hook (validation)
+python3 pre_tool_use.py --test
+
+# Post-hook (audit)
+python3 post_tool_use.py --test
+
+# Metrics (use the JS CLI instead)
+npx gaia-metrics
+```
+
+### Importing Modules
+
+```python
+from modules.security import SecurityTier, classify_command_tier, is_blocked_command
+from modules.security import CATEGORY_MUTATIVE, CATEGORY_READ_ONLY
+from modules.tools import BashValidator
+from modules.audit import generate_summary
+
+# Check if command is permanently blocked
+result = is_blocked_command("kubectl delete namespace production")
+print(f"Blocked: {result.blocked}, Reason: {result.reason}")
+
+# Classify command tier
+tier = classify_command_tier("kubectl get pods")
+print(f"Tier: {tier}")  # SecurityTier.T0
+
+# Validate Bash command (full pipeline: blocked -> mutative verbs -> safe by elimination)
+validator = BashValidator()
+result = validator.validate("kubectl get pods")
+print(f"Allowed: {result.allowed}, Tier: {result.tier}")
+
+# Get metrics summary
+summary = generate_summary(days=7)
+print(f"Success rate: {summary['success_rate']:.1%}")
+```
+
+## Architecture Notes
+
+The modular architecture maintains full backward compatibility with Claude Code's hook interface (stdin JSON format).
+
+All security rules (blocked patterns, mutative verbs, tiers) are hardcoded in the Python modules for performance and simplicity - no external JSON config files needed.
+
+### Validation Order (Defense-in-Depth)
+bash_validator checks commands in this order (short-circuit on first match):
+0. **Indirect execution detection** — `bash -c`, `eval`, `python -c` etc. → ask or block
+1. **Blocked commands** (blocked_commands.py) — permanently denied patterns, exit 2
+2. **Claude footer stripping** — transparent via updatedInput
+3. **Commit message validation** — conventional commits enforcement
+4. **Cloud pipe/redirect/chain check** (cloud_pipe_validator.py) — corrective deny
+5. **Mutative verbs** (mutative_verbs.py) — CLI-agnostic verb detector, native `ask` dialog
+6. **GitOps validation** (gitops_validator.py) — kubectl/helm/flux policy enforcement
+7. **Everything else** — SAFE by elimination (auto-approved)
+
+### Tier Classification
+- **T0**: Read-only (get, list, describe, show)
+- **T1**: Local validation (validate, lint, fmt, check)
+- **T2**: Simulation (plan, template, diff, --dry-run)
+- **T3**: State-modifying (apply, delete, push, commit)

package/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"