@jaguilar87/gaia 5.0.0-rc.2

package/dist/gaia-security/hooks/modules/tools/stage_decomposer.py

@@ -0,0 +1,315 @@
+"""
+Stage Decomposer - Shell command stage tracking with operator preservation.
+
+Wraps ShellCommandParser to add operator tracking between stages.
+ShellCommandParser.parse() discards operators; StageDecomposer preserves them
+so downstream classifiers know how stages are connected (pipe vs AND vs OR).
+
+A "stage" is one command with its arguments plus the operator that links it
+to the next stage.  The last stage has operator=None.
+
+Handles:
+- Pipes (|), semicolons (;), AND (&&), OR (||)
+- Command substitution $(...)
+- Backtick substitution `...`
+- Nested command substitution
+
+Dependencies: Python stdlib only.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+from .shell_parser import ShellCommandParser
+
+
+@dataclass
+class Stage:
+    """A single command stage in a pipeline or chain."""
+
+    # The raw command token (e.g., "grep -r foo")
+    command: str
+    # Arguments as a list parsed from the command token
+    args: List[str] = field(default_factory=list)
+    # Operator connecting THIS stage to the NEXT stage (None for the last stage)
+    operator: Optional[str] = None
+
+    def __str__(self) -> str:
+        return self.command
+
+    @property
+    def executable(self) -> str:
+        """Return the executable name (first token of the command)."""
+        tokens = self.command.strip().split()
+        return tokens[0] if tokens else ""
+
+
+@dataclass
+class DecomposedCommand:
+    """Result of decomposing a raw command string into stages."""
+
+    # Original command string (before decomposition)
+    raw: str
+    # Ordered list of stages
+    stages: List[Stage] = field(default_factory=list)
+    # Command substitutions extracted from the command ($(...) or `...`)
+    substitutions: List[str] = field(default_factory=list)
+
+    @property
+    def is_compound(self) -> bool:
+        """Return True if the command has more than one stage."""
+        return len(self.stages) > 1
+
+    @property
+    def executables(self) -> List[str]:
+        """Return the list of executables across all stages."""
+        return [s.executable for s in self.stages if s.executable]
+
+
+class StageDecomposer:
+    """
+    Decomposes a raw shell command string into ordered Stage objects.
+
+    Wraps ShellCommandParser for quote-aware splitting, then re-walks the
+    original string to recover the operators that ShellCommandParser.parse()
+    discards.
+
+    Zero external dependencies -- Python stdlib only.
+
+    Usage::
+
+        decomposer = StageDecomposer()
+        result = decomposer.decompose("ls | grep foo && wc -l")
+        # result.stages[0].command  == "ls"
+        # result.stages[0].operator == "|"
+        # result.stages[1].command  == "grep foo"
+        # result.stages[1].operator == "&&"
+        # result.stages[2].command  == "wc -l"
+        # result.stages[2].operator is None
+    """
+
+    def __init__(self) -> None:
+        self._parser = ShellCommandParser()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def decompose(self, command: str) -> DecomposedCommand:
+        """
+        Decompose a raw command string into Stage objects.
+
+        Args:
+            command: Raw shell command string.
+
+        Returns:
+            DecomposedCommand with stages and any extracted substitutions.
+        """
+        if not command or not command.strip():
+            return DecomposedCommand(raw=command or "", stages=[], substitutions=[])
+
+        command = command.strip()
+
+        # Extract command substitutions before splitting so they don't
+        # interfere with operator detection.
+        substitutions = self._extract_substitutions(command)
+
+        # Walk the command string once to collect (command_text, operator) pairs.
+        pairs = self._split_with_operators(command)
+
+        stages: List[Stage] = []
+        for cmd_text, op in pairs:
+            cmd_text = cmd_text.strip()
+            if not cmd_text:
+                continue
+            args = self._tokenize_args(cmd_text)
+            stages.append(Stage(command=cmd_text, args=args, operator=op))
+
+        return DecomposedCommand(raw=command, stages=stages, substitutions=substitutions)
+
+    # ------------------------------------------------------------------
+    # Internal: operator-aware splitting
+    # ------------------------------------------------------------------
+
+    def _split_with_operators(self, command: str) -> List[tuple]:
+        """
+        Walk *command* and return a list of (segment, operator_or_None) tuples.
+
+        The final segment always has operator=None.
+        Quotes and escape sequences are respected so operators inside quoted
+        strings or $(...) subshells are not treated as segment boundaries.
+        """
+        segments: List[tuple] = []
+        current: List[str] = []
+        i = 0
+        n = len(command)
+
+        in_single_quote = False
+        in_double_quote = False
+        paren_depth = 0       # tracks $( ... ) nesting
+        backtick_depth = 0    # tracks ` ... ` nesting
+
+        while i < n:
+            ch = command[i]
+
+            # ---- escape sequence (outside single-quotes) ----
+            if ch == "\\" and not in_single_quote and i + 1 < n:
+                current.append(ch)
+                current.append(command[i + 1])
+                i += 2
+                continue
+
+            # ---- single quote toggle ----
+            if ch == "'" and not in_double_quote:
+                in_single_quote = not in_single_quote
+                current.append(ch)
+                i += 1
+                continue
+
+            # ---- double quote toggle ----
+            if ch == '"' and not in_single_quote:
+                in_double_quote = not in_double_quote
+                current.append(ch)
+                i += 1
+                continue
+
+            # ---- inside quotes: pass through ----
+            if in_single_quote or in_double_quote:
+                current.append(ch)
+                i += 1
+                continue
+
+            # ---- $( ... ) command substitution ----
+            if ch == "$" and i + 1 < n and command[i + 1] == "(":
+                paren_depth += 1
+                current.append(ch)
+                current.append("(")
+                i += 2
+                continue
+
+            if ch == "(" and paren_depth > 0:
+                paren_depth += 1
+                current.append(ch)
+                i += 1
+                continue
+
+            if ch == ")" and paren_depth > 0:
+                paren_depth -= 1
+                current.append(ch)
+                i += 1
+                continue
+
+            # ---- backtick command substitution ----
+            if ch == "`":
+                if backtick_depth > 0:
+                    backtick_depth -= 1
+                else:
+                    backtick_depth += 1
+                current.append(ch)
+                i += 1
+                continue
+
+            # ---- if inside a substitution, pass through ----
+            if paren_depth > 0 or backtick_depth > 0:
+                current.append(ch)
+                i += 1
+                continue
+
+            # ---- two-character operators: &&, || ----
+            if i + 1 < n:
+                two = command[i : i + 2]
+                if two in ("&&", "||"):
+                    segments.append(("".join(current), two))
+                    current = []
+                    i += 2
+                    continue
+
+            # ---- single-character operators: |, ;, \n ----
+            if ch in ("|", ";", "\n"):
+                segments.append(("".join(current), ch))
+                current = []
+                i += 1
+                continue
+
+            current.append(ch)
+            i += 1
+
+        # Final segment has no following operator.
+        if current:
+            segments.append(("".join(current), None))
+
+        return segments
+
+    # ------------------------------------------------------------------
+    # Internal: argument tokenisation
+    # ------------------------------------------------------------------
+
+    def _tokenize_args(self, command_text: str) -> List[str]:
+        """
+        Split *command_text* into tokens (command + args).
+
+        Uses a simple quote-aware tokeniser -- does NOT invoke shlex so we
+        stay dependency-free and avoid locale issues.
+
+        Returns a list where element 0 is the executable and the remainder
+        are arguments.
+        """
+        tokens: List[str] = []
+        current: List[str] = []
+        i = 0
+        n = len(command_text)
+        in_single = False
+        in_double = False
+
+        while i < n:
+            ch = command_text[i]
+
+            if ch == "\\" and not in_single and i + 1 < n:
+                current.append(command_text[i + 1])
+                i += 2
+                continue
+
+            if ch == "'" and not in_double:
+                in_single = not in_single
+                i += 1
+                continue
+
+            if ch == '"' and not in_single:
+                in_double = not in_double
+                i += 1
+                continue
+
+            if not in_single and not in_double and ch in (" ", "\t"):
+                if current:
+                    tokens.append("".join(current))
+                    current = []
+                i += 1
+                continue
+
+            current.append(ch)
+            i += 1
+
+        if current:
+            tokens.append("".join(current))
+
+        return tokens
+
+    # ------------------------------------------------------------------
+    # Internal: command substitution extraction
+    # ------------------------------------------------------------------
+
+    # Match $(...) -- does not handle arbitrarily deep nesting but covers
+    # the common single-level case.
+    _SUBST_PAREN_RE = re.compile(r"\$\(([^()]*(?:\([^()]*\)[^()]*)*)\)")
+    # Match `...` (non-greedy, no nesting)
+    _SUBST_BACKTICK_RE = re.compile(r"`([^`]*)`")
+
+    def _extract_substitutions(self, command: str) -> List[str]:
+        """Return a list of inner strings from $(...) and `...` substitutions."""
+        results: List[str] = []
+        results.extend(m.group(1).strip() for m in self._SUBST_PAREN_RE.finditer(command))
+        results.extend(m.group(1).strip() for m in self._SUBST_BACKTICK_RE.finditer(command))
+        return results

package/dist/gaia-security/hooks/modules/tools/task_validator.py

@@ -0,0 +1,294 @@
+"""
+Task tool validator.
+
+Validates Task tool invocations:
+- Agent existence verification
+- Context provisioning enforcement
+- T3 operation detection for user approval workflow
+"""
+
+import logging
+import re
+from typing import Dict, Any, List, Optional, Tuple
+from dataclasses import dataclass
+
+from ..security.tiers import SecurityTier
+from ..security.mutative_verbs import (
+    detect_mutative_command,
+    MutativeResult,
+    CLI_FAMILY_LOOKUP,
+    COMMAND_ALIASES,
+)
+
+logger = logging.getLogger(__name__)
+
+# Available agents for Task invocation — both bare and plugin-namespaced forms
+_BASE_AGENTS = [
+    "terraform-architect",
+    "gitops-operator",
+    "cloud-troubleshooter",
+    "developer",
+    "gaia-operator",
+    "gaia-system",
+    "gaia-planner",
+    "Explore",
+    "Plan",
+    "claude-code-guide",
+    "general-purpose",
+]
+# Support both "cloud-troubleshooter" and "gaia-ops:cloud-troubleshooter"
+AVAILABLE_AGENTS = _BASE_AGENTS + [f"gaia-ops:{a}" for a in _BASE_AGENTS]
+
+# Native Claude Code agent types — utility subagents built into the harness,
+# not gaia domain specialists. They don't require context_provider and don't
+# appear in surface routing. They are valid dispatch targets that the
+# orchestrator can legitimately use.
+NATIVE_AGENTS = ["Explore", "Plan", "general-purpose", "claude-code-guide"]
+
+# Meta-agents that don't require context_provider.
+# gaia-system was removed: it now receives context injection (has a contract
+# in context-contracts.json) so it can see project state when working on
+# Gaia internals.
+META_AGENTS = list(NATIVE_AGENTS)
+
+# T3_KEYWORDS is test-only: used by tests and cross-layer consistency checks
+# to verify that these commands are classified as T3 by the verb detector.
+# NOT used at runtime -- detection is handled entirely by detect_mutative_command().
+T3_KEYWORDS = [
+    "git commit",
+    "git push",
+    "terraform apply",
+    "terragrunt apply",
+    "terragrunt run-all apply",
+    "kubectl apply",
+    "kubectl delete",
+    "kubectl create",
+    "kubectl rollout restart",
+    "kubectl scale",
+    "kubectl set image",
+    "git push origin main",
+    "git push origin master",
+    "helm install",
+    "helm upgrade",
+    "flux reconcile",
+    "npm publish",
+    "docker push",
+    "gcloud sql import",
+    "gcloud storage cp",
+    "gcloud storage rsync",
+]
+
+
+_EMBEDDED_COMMAND_QUOTE_CHARS = "\"'`"
+
+
+def _sanitize_candidate_fragment(fragment: str) -> str:
+    """Normalize a prose-embedded command fragment for verb detection.
+
+    Task prompts often mention commands inside backticks or quotes:
+      - Please run `terraform apply` in prod
+      - Need to execute "terraform apply" in prod
+
+    The detector only needs the command skeleton, so strip quote delimiters and
+    collapse whitespace before handing the fragment to the dangerous verb
+    classifier.
+    """
+    if not fragment:
+        return ""
+    cleaned = fragment.translate(str.maketrans({char: " " for char in _EMBEDDED_COMMAND_QUOTE_CHARS}))
+    cleaned = re.sub(r"\s+", " ", cleaned).strip()
+    return cleaned.rstrip(".,;:!?")
+
+
+def _extract_command_candidates(text: str) -> List[str]:
+    """Extract command-like lines from free-form text for verb detection.
+
+    Looks for lines that start with known CLI prefixes or contain command-like
+    patterns (e.g., "git push", "terraform apply").
+
+    Args:
+        text: Free-form text (prompt or description).
+
+    Returns:
+        List of candidate command strings to scan.
+    """
+    if not text:
+        return []
+
+    candidates: List[str] = []
+    # Derive CLI prefixes from the canonical CLI_FAMILY_LOOKUP and COMMAND_ALIASES
+    cli_prefixes = tuple(
+        f"{cli} " for cli in sorted(
+            set(CLI_FAMILY_LOOKUP.keys()) | set(COMMAND_ALIASES.keys()),
+            key=len,
+            reverse=True,
+        )
+    )
+
+    text_lower = text.lower()
+
+    # Strategy 1: Scan the full text for known CLI command patterns
+    for prefix in cli_prefixes:
+        idx = 0
+        while True:
+            pos = text_lower.find(prefix, idx)
+            if pos == -1:
+                break
+            # Only match at word boundaries (start of string or preceded by whitespace/punctuation)
+            if pos > 0 and text_lower[pos - 1].isalnum():
+                idx = pos + len(prefix)
+                continue
+            # Extract from the prefix to end of line (or next sentence boundary)
+            end = text.find("\n", pos)
+            if end == -1:
+                end = len(text)
+            fragment = text[pos:end].strip()
+            # Trim trailing punctuation/quotes that are part of prose
+            fragment = fragment.rstrip(".,;:!?\"')")
+            fragment = _sanitize_candidate_fragment(fragment)
+            if fragment:
+                candidates.append(fragment)
+            idx = pos + len(prefix)
+
+    return candidates
+
+
+def _scan_text_for_t3(text: str) -> Tuple[bool, str, Optional[MutativeResult]]:
+    """Scan free-form text for T3 (dangerous) command intent using the verb detector.
+
+    Args:
+        text: Combined prompt/description text.
+
+    Returns:
+        (is_t3, matched_command, danger_result) tuple.
+    """
+    candidates = _extract_command_candidates(text)
+
+    for candidate in candidates:
+        result = detect_mutative_command(candidate)
+        if result.is_mutative:
+            return True, candidate, result
+
+    return False, "", None
+
+__all__ = [
+    "TaskValidator",
+    "TaskValidationResult",
+    "validate_task_invocation",
+    "AVAILABLE_AGENTS",
+    "META_AGENTS",
+    "NATIVE_AGENTS",
+    "T3_KEYWORDS",
+]
+
+
+@dataclass
+class TaskValidationResult:
+    """Result of Task tool validation."""
+    allowed: bool
+    tier: SecurityTier
+    reason: str
+    agent_name: str = ""
+    has_context: bool = False
+    is_t3_operation: bool = False
+
+
+class TaskValidator:
+    """Validator for Task tool invocations."""
+
+    def __init__(self, available_agents: Optional[List[str]] = None):
+        """
+        Initialize validator.
+
+        Args:
+            available_agents: Override available agents list
+        """
+        self.available_agents = available_agents or AVAILABLE_AGENTS
+
+    def validate(self, parameters: Dict[str, Any]) -> TaskValidationResult:
+        """
+        Validate Task tool invocation.
+
+        Args:
+            parameters: Task tool parameters
+
+        Returns:
+            TaskValidationResult with validation details
+        """
+        agent_name = parameters.get("subagent_type", "unknown")
+        prompt = parameters.get("prompt", "")
+        description = parameters.get("description", "")
+
+        # additionalContext means prompt is never mutated, so T3 detection
+        # runs directly against the original user prompt.
+        user_task_for_t3_check = prompt
+
+        logger.info(f"Task tool validation for agent: {agent_name}")
+
+        # Check agent exists
+        if agent_name not in self.available_agents:
+            error_msg = f"Unknown agent: '{agent_name}'\n\n"
+            error_msg += f"Available agents:\n"
+            for agent in sorted(self.available_agents):
+                error_msg += f"  - {agent}\n"
+            error_msg += "\nRefer to the Surface Routing Recommendation for agent selection.\n"
+            error_msg += f"\nCorrect usage: Task(subagent_type=\"<agent-name>\", ...)"
+
+            return TaskValidationResult(
+                allowed=False,
+                tier=SecurityTier.T3_BLOCKED,
+                reason=error_msg,
+                agent_name=agent_name,
+            )
+
+        # Context is injected via additionalContext by the adapter, not by
+        # mutating the prompt.  The validator cannot check additionalContext
+        # (it only sees parameters), so we determine context status by agent type.
+        # Meta-agents never receive context by design.
+        has_context = agent_name not in META_AGENTS
+
+        # Check for T3 operations (use original user task to avoid false positives from context)
+        is_t3 = self._is_t3_operation(user_task_for_t3_check, description)
+
+        logger.info(
+            f"Task invocation validated: {agent_name} "
+            f"(T3={is_t3}, context={has_context})"
+        )
+
+        tier = SecurityTier.T3_BLOCKED if is_t3 else SecurityTier.T0_READ_ONLY
+        reason = (
+            f"Task invocation allowed for {agent_name}; T3 execution still requires "
+            f"nonce-based approval at Bash time"
+            if is_t3
+            else f"Task invocation allowed for {agent_name}"
+        )
+
+        return TaskValidationResult(
+            allowed=True,
+            tier=tier,
+            reason=reason,
+            agent_name=agent_name,
+            has_context=has_context,
+            is_t3_operation=is_t3,
+        )
+
+    def _is_t3_operation(self, prompt: str, description: str) -> bool:
+        """Check if this is a T3 (destructive) operation using the verb detector."""
+        combined = f"{description} {prompt}"
+        is_t3, _, _ = _scan_text_for_t3(combined)
+        return is_t3
+
+
+
+def validate_task_invocation(parameters: Dict[str, Any]) -> TaskValidationResult:
+    """
+    Validate Task tool invocation (convenience function).
+
+    Args:
+        parameters: Task tool parameters
+
+    Returns:
+        TaskValidationResult
+    """
+    validator = TaskValidator()
+    return validator.validate(parameters)

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

@@ -0,0 +1,23 @@
+"""
+Validation Module: Commit message validation for bash_validator
+
+This module provides commit message validation that is exclusively used
+by hooks/modules/tools/bash_validator.py to enforce git commit standards.
+
+Note: This is an internal module. Do not import directly in agent code.
+      Commit validation is automatically enforced via bash_validator.py.
+"""
+
+from .commit_validator import (
+    CommitMessageValidator,
+    ValidationResult,
+    validate_commit_message,
+    safe_validate_before_commit,
+)
+
+__all__ = [
+    "CommitMessageValidator",
+    "ValidationResult",
+    "validate_commit_message",
+    "safe_validate_before_commit",
+]