@jaguilar87/gaia 5.0.0-rc.2

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

@@ -0,0 +1,122 @@
+"""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"DELEGATION REQUIRED: '{tool_name}' is not available.\n"
+            f"Dispatch a specialist agent for this task.\n"
+            f"The routing recommendation in your last message indicates which agent to use."
+        ),
+    )

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,120 @@
+"""
+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
+- shell_unwrapper: Detect and strip wrapper shells for inner command classification
+- flag_classifiers: Flag-dependent classifiers for 15 command families
+- composition_rules: Cross-stage pipe composition rules (exfiltration, RCE, obfuscation)
+- network_hosts: Network host classification for curl/wget/httpie targets
+"""
+
+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,
+)
+from .shell_unwrapper import ShellUnwrapper
+from .flag_classifiers import classify_by_flags, FlagClassifierResult
+from .composition_rules import (
+    check_composition,
+    build_composition_stages,
+    CompositionResult,
+    CompositionStage,
+    CompositionDecision,
+    StageType,
+)
+from .network_hosts import classify_host, extract_url_from_tokens, HostClassification
+
+__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",
+    # Shell unwrapper
+    "ShellUnwrapper",
+    # Flag classifiers
+    "classify_by_flags",
+    "FlagClassifierResult",
+    # Composition rules
+    "check_composition",
+    "build_composition_stages",
+    "CompositionResult",
+    "CompositionStage",
+    "CompositionDecision",
+    "StageType",
+    # Network hosts
+    "classify_host",
+    "extract_url_from_tokens",
+    "HostClassification",
+]

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",
+)