@jaguilar87/gaia 5.0.0-rc.2

package/dist/gaia-security/hooks/user_prompt_submit.py

@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+"""UserPromptSubmit hook — injects routing recommendations, first-run welcome, and agentic-loop resume context."""
+
+import sys
+import json
+import logging
+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
+from modules.core.plugin_setup import run_first_time_setup
+from modules.core.plugin_mode import get_plugin_mode
+
+# 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 [user_prompt_submit] %(name)s - %(levelname)s - %(message)s',
+    handlers=[logging.FileHandler(_log_file)],
+)
+logger = logging.getLogger(__name__)
+
+
+def _extract_user_prompt(raw_input: str) -> str:
+    """Extract user prompt text from stdin event.
+
+    The UserPromptSubmit event is JSON with the user's message.
+    Try known field names; return empty string if extraction fails.
+    """
+    try:
+        event = json.loads(raw_input)
+        # Try known field names from Claude Code hook events
+        for field in ("user_message", "prompt", "message", "content"):
+            if field in event and isinstance(event[field], str):
+                return event[field]
+        # Check nested hookEventInput
+        hook_input = event.get("hookEventInput", {})
+        if isinstance(hook_input, dict):
+            for field in ("user_message", "prompt", "message", "content"):
+                if field in hook_input and isinstance(hook_input[field], str):
+                    return hook_input[field]
+    except (json.JSONDecodeError, TypeError, AttributeError):
+        pass
+    return ""
+
+
+def _build_routing_recommendation(prompt_text: str) -> str:
+    """Run surface classification and format as a routing recommendation block.
+
+    Returns empty string if classification fails or produces no active surfaces.
+    This is advisory — never raises exceptions.
+    """
+    try:
+        # Import surface_router from tools/context
+        tools_dir = Path(__file__).resolve().parent.parent / "tools" / "context"
+        if str(tools_dir) not in sys.path:
+            sys.path.insert(0, str(tools_dir))
+
+        from surface_router import classify_surfaces
+
+        routing = classify_surfaces(prompt_text)
+
+        active_surfaces = routing.get("active_surfaces", [])
+        if not active_surfaces:
+            logger.info("Surface routing: no active surfaces for prompt")
+            return ""
+
+        agents = routing.get("recommended_agents", [])
+        dispatch_mode = routing.get("dispatch_mode", "single_surface")
+        confidence = routing.get("confidence", 0.0)
+        matched_signals = routing.get("matched_signals", {})
+
+        # Flatten matched signals into a single list for display
+        all_signals = []
+        for surface_signals in matched_signals.values():
+            all_signals.extend(surface_signals)
+
+        lines = [
+            "\n\n## Surface Routing Recommendation",
+            f"- Recommended agents: {agents}",
+            f"- Dispatch mode: {dispatch_mode}",
+            f"- Confidence: {confidence}",
+            f"- Matched signals: {json.dumps(all_signals)}",
+        ]
+
+        logger.info(
+            "Surface routing: agents=%s mode=%s confidence=%.2f signals=%s",
+            agents, dispatch_mode, confidence, all_signals,
+        )
+        return "\n".join(lines)
+
+    except Exception as e:
+        logger.warning("Surface routing failed (advisory, skipping): %s", e)
+        return ""
+
+
+def _build_welcome(mode: str) -> str:
+    """Build first-run welcome message for the user.
+
+    This message is injected as additionalContext so Claude receives it,
+    not the user directly.  The framing explains WHY the user needs to
+    know — Claude should naturally relay it because it is actionable
+    and the user cannot use the plugin fully without restarting.
+    """
+    plugin_name = f"GAIA {'Ops' if mode == 'ops' else 'Security'}"
+
+    return (
+        f"{plugin_name} was just installed for the first time in this project. "
+        f"The plugin detected the installation and configured security permissions, "
+        f"but these permissions only take effect after restarting Claude Code. "
+        f"Until the user closes this session and reopens Claude Code, "
+        f"{plugin_name} cannot protect their commands — destructive operations "
+        f"will not be blocked and mutative operations will not require approval. "
+        f"The user needs to know this because they just installed {plugin_name} "
+        f"expecting it to work, but it will not be active until they restart. "
+        f"Tell the user that {plugin_name} is installed, that they need to close "
+        f"and reopen Claude Code to activate it, and that until they do, "
+        f"security protections are not active."
+    )
+
+
+def _build_pending_context() -> str:
+    """Scan for pending approvals and format as actionable context.
+
+    Returns an [ACTIONABLE]-framed summary if pending approvals exist,
+    or empty string if none found.  Includes cross-session fallback:
+    scans current session first, then all sessions if empty.
+
+    Fully fail-safe — never raises exceptions.
+    """
+    try:
+        from modules.session.pending_scanner import scan_pending_approvals, format_pending_summary
+        from modules.core.paths import get_plugin_data_dir
+        from modules.core.state import get_session_id
+
+        approvals_dir = get_plugin_data_dir() / "cache" / "approvals"
+        session_id = get_session_id()
+
+        # Current session first
+        pendings = scan_pending_approvals(
+            approvals_dir, session_id=session_id, current_session_id=session_id
+        )
+
+        # Cross-session fallback: scan all sessions if current has none.
+        # exclude_live_sessions=True prevents pendings from parallel live
+        # sessions from appearing as "[session anterior]" injections.
+        if not pendings:
+            pendings = scan_pending_approvals(
+                approvals_dir,
+                current_session_id=session_id,
+                exclude_live_sessions=True,
+            )
+
+        if not pendings:
+            return ""
+
+        summary = format_pending_summary(pendings)
+        logger.info("Pending context: %d approvals found", len(pendings))
+        return (
+            "[ACTIONABLE] Pending approvals require your attention before "
+            "routing this request.\n\n" + summary
+        )
+    except Exception as e:
+        logger.debug("Pending context scan skipped (non-fatal): %s", e)
+        return ""
+
+
+if __name__ == "__main__":
+    if not has_stdin_data():
+        sys.exit(0)
+
+    try:
+        raw_input = sys.stdin.read()
+
+        # Check first-run BEFORE setup (SessionStart does setup with
+        # mark_done=False so the marker doesn't exist yet on first run).
+        from modules.core.plugin_setup import is_first_run, mark_initialized
+        first_run = is_first_run()
+
+        # Ensure registry + permissions exist (idempotent, no mark).
+        setup_msg = run_first_time_setup(mark_done=False)
+        mode = get_plugin_mode()
+
+        # Build additionalContext: welcome + agentic-loop + routing.
+        # Identity now lives in agents/gaia-orchestrator.md (agent definition).
+        context_parts = []
+
+        # First-time welcome: the marker does not exist yet because
+        # neither SessionStart nor this call marked it.
+        if first_run:
+            welcome = _build_welcome(mode)
+            context_parts.append(welcome)
+            mark_initialized()  # Mark AFTER building the welcome
+            logger.info("First-run welcome prepended for %s mode", mode)
+
+        # Detect active agentic-loop and inject resume context (ops mode only).
+        # Lightweight: checks file existence + small JSON read, fully fail-safe.
+        if mode == "ops":
+            try:
+                from modules.context.agentic_loop_detector import build_resume_context
+                loop_context = build_resume_context()
+                if loop_context:
+                    context_parts.append(loop_context)
+                    logger.info("Agentic loop resume context injected")
+            except Exception as e:
+                logger.debug("Agentic loop detection skipped (non-fatal): %s", e)
+
+        # Inject pending approval context (ops mode only, before routing).
+        if mode == "ops":
+            pending_block = _build_pending_context()
+            if pending_block:
+                context_parts.append(pending_block)
+                logger.info("Pending approval context injected")
+
+        # Append deterministic surface routing recommendation (ops mode only)
+        if mode == "ops":
+            prompt_text = _extract_user_prompt(raw_input)
+
+            # NOTE: Approval activation moved to ElicitationResult hook.
+            # AskUserQuestion responses trigger ElicitationResult, not
+            # UserPromptSubmit, so approval detection lives there now.
+
+            if prompt_text:
+                routing_block = _build_routing_recommendation(prompt_text)
+                if routing_block:
+                    context_parts.append(routing_block)
+            else:
+                logger.info("Could not extract user prompt from stdin, skipping routing")
+
+        additional_context = "\n\n".join(context_parts)
+        logger.info("Context injected: %s mode (%d chars)", mode, len(additional_context))
+
+        print(json.dumps({
+            "hookSpecificOutput": {
+                "hookEventName": "UserPromptSubmit",
+                "additionalContext": additional_context,
+            }
+        }))
+        sys.exit(0)
+
+    except Exception as e:
+        logger.error("Error in user_prompt_submit: %s", e, exc_info=True)
+        sys.exit(0)

package/dist/gaia-security/settings.json

@@ -0,0 +1,58 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(*)",
+      "Read",
+      "Glob",
+      "Grep",
+      "BashOutput",
+      "KillShell"
+    ],
+    "deny": [
+      "Bash(aws ec2 delete-vpc:*)",
+      "Bash(aws ec2 delete-subnet:*)",
+      "Bash(aws ec2 delete-internet-gateway:*)",
+      "Bash(aws ec2 delete-route-table:*)",
+      "Bash(aws ec2 delete-route:*)",
+      "Bash(aws rds delete-db-instance:*)",
+      "Bash(aws rds delete-db-cluster:*)",
+      "Bash(aws dynamodb delete-table:*)",
+      "Bash(aws s3 rb:*)",
+      "Bash(aws s3api delete-bucket:*)",
+      "Bash(aws elasticache delete-cache-cluster:*)",
+      "Bash(aws elasticache delete-replication-group:*)",
+      "Bash(aws eks delete-cluster:*)",
+      "Bash(gcloud projects delete:*)",
+      "Bash(gcloud container clusters delete:*)",
+      "Bash(gcloud sql instances delete:*)",
+      "Bash(gcloud sql databases delete:*)",
+      "Bash(gcloud services disable:*)",
+      "Bash(gsutil rb:*)",
+      "Bash(gsutil rm -r:*)",
+      "Bash(kubectl delete namespace:*)",
+      "Bash(kubectl delete node:*)",
+      "Bash(kubectl delete cluster:*)",
+      "Bash(kubectl delete pv:*)",
+      "Bash(kubectl delete persistentvolume:*)",
+      "Bash(kubectl delete pvc:*)",
+      "Bash(kubectl delete persistentvolumeclaim:*)",
+      "Bash(kubectl delete crd:*)",
+      "Bash(kubectl delete customresourcedefinition:*)",
+      "Bash(kubectl delete mutatingwebhookconfiguration:*)",
+      "Bash(kubectl delete validatingwebhookconfiguration:*)",
+      "Bash(kubectl drain:*)",
+      "Bash(git push --force:*)",
+      "Bash(git push -f:*)",
+      "Bash(git push origin --force:*)",
+      "Bash(git push origin -f:*)",
+      "Bash(dd:*)",
+      "Bash(fdisk:*)",
+      "Bash(mkfs:*)",
+      "Bash(mkfs.ext4:*)",
+      "Bash(mkfs.ext3:*)",
+      "Bash(mkfs.fat:*)",
+      "Bash(mkfs.ntfs:*)"
+    ],
+    "ask": []
+  }
+}

package/git-hooks/commit-msg

@@ -0,0 +1,41 @@
+#!/bin/sh
+#
+# commit-msg hook: strip Claude Code attribution footers from commit messages.
+#
+# This hook runs at the git level, catching ALL commits regardless of whether
+# they originate from Claude Code's Bash tool, a subagent, or the user's terminal.
+#
+# Patterns match those in hooks/modules/tools/bash_validator.py _strip_claude_footers()
+# to maintain a single source of truth for what constitutes a forbidden footer.
+#
+# Installation:
+#   cp git-hooks/commit-msg .git/hooks/commit-msg
+#   chmod +x .git/hooks/commit-msg
+#
+# Or via gaia-init (automatic).
+
+COMMIT_MSG_FILE="$1"
+
+if [ ! -f "${COMMIT_MSG_FILE}" ]; then
+    exit 0
+fi
+
+# Create a temp file for the cleaned message
+TEMP_FILE=$(mktemp)
+trap 'rm -f "${TEMP_FILE}"' EXIT
+
+# Read the commit message and strip forbidden footer lines:
+#   - Co-Authored-By: containing "Claude" (any case)
+#   - "Generated with Claude Code" or "[Claude Code]" (any case)
+#   - Emoji-prefixed "Generated with" lines
+sed -E \
+    -e '/^[[:space:]]*[Cc][Oo]-[Aa][Uu][Tt][Hh][Oo][Rr][Ee][Dd]-[Bb][Yy]:.*[Cc][Ll][Aa][Uu][Dd][Ee]/d' \
+    -e '/^[[:space:]]*[Gg][Ee][Nn][Ee][Rr][Aa][Tt][Ee][Dd] [Ww][Ii][Tt][Hh].*[Cc][Ll][Aa][Uu][Dd][Ee] [Cc][Oo][Dd][Ee]/d' \
+    -e '/^[[:space:]]*..?[[:space:]]*[Gg][Ee][Nn][Ee][Rr][Aa][Tt][Ee][Dd] [Ww][Ii][Tt][Hh]/d' \
+    "${COMMIT_MSG_FILE}" > "${TEMP_FILE}"
+
+# Remove trailing blank lines (collapse to single trailing newline)
+# This prevents empty trailers after stripping
+sed -e :a -e '/^\n*$/{$d;N;ba' -e '}' "${TEMP_FILE}" > "${COMMIT_MSG_FILE}"
+
+exit 0

package/hooks/README.md

@@ -0,0 +1,100 @@
+# Hooks
+
+Hooks are the event-driven spine of Gaia. Every significant moment in a Claude Code session — a prompt arriving, a tool being called, an agent completing — has a corresponding hook file in this directory. The hooks are not optional middleware; they are the security gate, the context injector, the audit system, and the memory writer. Remove them, and Gaia becomes a collection of agent definitions with no enforcement.
+
+Each hook is a Python script that reads a JSON event from stdin, processes it, and writes a JSON response to stdout. Claude Code calls these scripts synchronously before or after each tool execution, which means the hook can allow, modify, or block the operation. The hook cannot do complex async work — it runs inline, in the critical path, so every module it calls must complete quickly.
+
+The hooks form a pipeline. A prompt enters at `user_prompt_submit.py`, gets routed to an agent, triggers `pre_tool_use.py` before each tool call, generates audit records in `post_tool_use.py`, and closes out in `subagent_stop.py` when the agent finishes. The event handler hooks (`session_start.py`, `stop_hook.py`, `subagent_start.py`, `task_completed.py`) fire at lifecycle transitions and carry lighter responsibilities.
+
+## Cuándo se activa
+
+```
+User sends prompt
+        |
+[user_prompt_submit.py] <- fires on UserPromptSubmit event
+        |  Builds orchestrator identity via ops_identity.py
+        |  Injects surface routing recommendation (deterministic, from surface-routing.json)
+        |  Skills loaded on-demand: agent-response
+        v
+Orchestrator dispatches agent (Task/Agent tool call)
+        |
+[pre_tool_use.py] <- fires on PreToolUse for: Bash, Task, Agent, SendMessage, Write, Edit
+        |  Bash calls: security gate (blocked_commands, mutative_verbs, cloud_pipe_validator)
+        |  Task/Agent calls: context injection from context-contracts.json
+        |  Write/Edit calls: protected path validation (_is_protected())
+        v
+    ALLOWED / BLOCKED / ask dialog (T3)
+        |
+Tool executes
+        |
+[post_tool_use.py] <- fires on PostToolUse for: Bash, AskUserQuestion
+        |  Audits result, logs to .claude/logs/
+        v
+[subagent_stop.py] <- fires on SubagentStop for all agents
+        |  Validates json:contract format
+        |  Records workflow metrics
+        |  Writes to episodic memory
+        v
+[subagent_start.py] <- fires on SubagentStart for all agents
+        |  Can inject additional context (e.g. persisted memory output)
+```
+
+## Entry point -> adapter -> module
+
+Every hook entry point is thin by design. The entry point reads stdin, calls the adapter, and writes stdout. All logic lives in the adapter and module layers.
+
+```
+hooks/pre_tool_use.py              <- Entry point: stdin/stdout glue only
+  -> adapters/claude_code.py       <- Adapter: parses event, dispatches to modules
+    -> modules/security/           <- blocked_commands, mutative_verbs, cloud_pipe_validator
+    -> modules/context/            <- context_injector, contracts_loader
+    -> modules/agents/             <- contract_validator, skill_injection
+    -> modules/validation/         <- commit_validator
+    -> modules/audit/              <- logger, metrics
+```
+
+To add a new behavior to an existing hook: write a module in `modules/<package>/`, import it in the adapter, and call it from the relevant adapter method. Modules receive parsed context as arguments and return results. They never read stdin or write stdout directly.
+
+To add a new hook entry point: create `hooks/<event_name>.py`, register it in `build/gaia-ops.manifest.json` under `hooks.entries` and `hooks.matchers`, then write the adapter method. The entry point pattern is always the same: read stdin JSON, call adapter, print response.
+
+## Qué hay aquí
+
+```
+hooks/
+├── user_prompt_submit.py  # Identity injection (UserPromptSubmit event)
+├── pre_tool_use.py        # Security gate + context injection (PreToolUse)
+├── post_tool_use.py       # Audit logging (PostToolUse)
+├── subagent_stop.py       # Contract validation + memory (SubagentStop)
+├── subagent_start.py      # Subagent start — additional context injection
+├── session_start.py       # Session start event handler
+├── stop_hook.py           # Stop event handler
+├── task_completed.py      # Task completed event handler
+├── pre_compact.py         # Pre-compaction event handler
+├── post_compact.py        # Post-compaction event handler
+├── hooks.json             # Plugin-channel hook configuration
+├── adapters/              # Adapter layer — event parsing and module dispatch
+└── modules/               # Module layer — security, context, validation, audit logic
+```
+
+## Convenciones
+
+**Security tiers enforced by pre_tool_use:**
+
+| Tier | Operation Type | Approval | Hook action |
+|------|----------------|----------|-------------|
+| T0 | Read-only (get, list) | No | Allow immediately |
+| T1 | Local validation (validate, lint) | No | Allow immediately |
+| T2 | Simulation (plan, diff) | No | Allow immediately |
+| T3 | Execution (apply, delete) | Yes — native `ask` dialog | Pause, request approval |
+| T3-blocked | Irreversible (delete-vpc, drop db) | Permanently blocked | Exit 2 (hard block) |
+
+**Protected paths** (blocked regardless of permissionMode):
+- `.claude/hooks/` — hooks cannot be modified by any agent
+- `.claude/settings.json` and `.claude/settings.local.json` — settings cannot be modified by any agent
+
+## Ver también
+
+- [`build/gaia-ops.manifest.json`](../build/gaia-ops.manifest.json) — hook registration and matchers
+- [`config/surface-routing.json`](../config/surface-routing.json) — read by `user_prompt_submit.py`
+- [`config/context-contracts.json`](../config/context-contracts.json) — read by `pre_tool_use.py` for context injection
+- [`skills/security-tiers/SKILL.md`](../skills/security-tiers/SKILL.md) — tier classification that agents use; hook enforces the same tiers

package/hooks/adapters/__init__.py

@@ -0,0 +1,52 @@
+"""
+Adapter Layer for Gaia-Ops Hooks.
+
+Provides CLI-agnostic normalized types and the abstract HookAdapter interface.
+Business logic modules consume and produce these types; concrete adapters
+translate between these types and CLI-specific JSON protocols.
+
+Modules:
+- types: Frozen dataclasses and enums for all hook event/response data
+- base: Abstract HookAdapter interface
+"""
+
+from .types import (
+    HookEventType,
+    PermissionDecision,
+    DistributionChannel,
+    HookEvent,
+    ValidationRequest,
+    ValidationResult,
+    ToolResult,
+    AgentCompletion,
+    CompletionResult,
+    ContextResult,
+    BootstrapResult,
+    QualityResult,
+    VerificationResult,
+    HookResponse,
+)
+from .base import HookAdapter
+from .claude_code import ClaudeCodeAdapter
+from .utils import has_stdin_data, warn_if_dual_channel
+
+__all__ = [
+    "HookEventType",
+    "PermissionDecision",
+    "DistributionChannel",
+    "HookEvent",
+    "ValidationRequest",
+    "ValidationResult",
+    "ToolResult",
+    "AgentCompletion",
+    "CompletionResult",
+    "ContextResult",
+    "BootstrapResult",
+    "QualityResult",
+    "VerificationResult",
+    "HookResponse",
+    "HookAdapter",
+    "ClaudeCodeAdapter",
+    "has_stdin_data",
+    "warn_if_dual_channel",
+]