@jaguilar87/gaia 5.0.0-rc1

package/hooks/subagent_stop.py

@@ -0,0 +1,295 @@
+#!/usr/bin/env python3
+"""
+Subagent stop hook for Claude Code Agent System.
+
+Thin gate: parse stdin -> delegate to adapter -> format response -> exit.
+
+Architecture:
+- Uses adapter layer to parse and process the full SubagentStop lifecycle
+- All business logic lives in ClaudeCodeAdapter.adapt_subagent_stop()
+- This file is stdin/stdout glue only
+
+Business logic modules (called by the adapter):
+- modules.agents.contract_validator        : Contract validation + evidence parsing
+- modules.agents.transcript_reader         : Transcript I/O
+- modules.agents.task_info_builder         : Hook payload -> task_info mapping
+- modules.audit.workflow_recorder          : Workflow metrics capture
+- modules.audit.workflow_auditor           : Anomaly detection + Gaia signaling
+- modules.memory.episode_writer            : Episodic memory storage + session events
+- modules.context.context_writer           : Progressive context enrichment
+- modules.security.approval_cleanup        : Approval file consumption
+- modules.agents.response_contract         : Response contract validation
+"""
+
+import json
+import logging
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+# Adapter layer
+from adapters.claude_code import ClaudeCodeAdapter
+from modules.core.hook_entry import run_hook
+
+# Configure structured logging with file handler
+try:
+    from modules.core.paths import get_logs_dir
+    _log_dir = get_logs_dir()
+except ImportError:
+    _log_dir = Path.cwd() / ".claude" / "logs"
+    _log_dir.mkdir(parents=True, exist_ok=True)
+
+_log_file = _log_dir / f"hooks-{datetime.now().strftime('%Y-%m-%d')}.log"
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s [subagent_stop] %(name)s - %(levelname)s - %(message)s',
+    handlers=[
+        logging.FileHandler(_log_file),
+    ]
+)
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# Backward-compatible aliases (tests and e2e import these names)
+# ============================================================================
+
+from modules.agents.contract_validator import (
+    extract_commands_from_evidence,
+    extract_exit_code_from_output,
+    parse_contract,
+    requires_consolidation_report,
+    validate as validate_contract,
+)
+from modules.agents.response_contract import (
+    save_validation_result,
+    validate_response_contract,
+    resolve_agent_id,
+)
+from modules.agents.task_info_builder import build_task_info_from_hook_data
+from modules.agents.transcript_reader import read_transcript
+from modules.audit.workflow_auditor import audit as audit_workflow, signal_gaia_analysis
+from modules.audit.workflow_recorder import record as record_workflow
+from modules.context.context_writer import process_context_updates
+from modules.memory.episode_writer import write as write_episode
+from modules.security.approval_cleanup import cleanup as cleanup_approval
+from modules.session.session_manager import get_or_create_session_id
+
+_extract_commands_from_evidence = extract_commands_from_evidence
+_extract_exit_code_from_output = extract_exit_code_from_output
+_read_transcript = read_transcript
+_process_context_updates = process_context_updates
+
+
+def _build_task_info_from_hook_data(
+    hook_data: Dict[str, Any],
+    agent_output: str = "",
+) -> Dict[str, Any]:
+    """Backward-compatible wrapper for build_task_info_from_hook_data."""
+    return build_task_info_from_hook_data(hook_data, agent_output)
+
+
+# ============================================================================
+# Backward-compatible main processing chain (used by tests directly)
+# ============================================================================
+
+def subagent_stop_hook(task_info, agent_output):
+    """
+    Main subagent stop hook - validates contracts, captures metrics, detects anomalies, stores episodes.
+
+    This is the backward-compatible entry point. The adapter calls the same
+    modules internally.
+
+    Args:
+        task_info: Task information including ID, description, agent, etc.
+        agent_output: Complete output from agent execution
+
+    Returns:
+        Success confirmation with metrics info, or contract_rejected dict on validation failure.
+    """
+    try:
+        from datetime import datetime as _dt
+        session_id = get_or_create_session_id()
+        agent_type = task_info.get("agent", "unknown")
+
+        parsed_contract = parse_contract(agent_output)
+
+        contract_result = validate_contract(agent_output, task_info)
+        if not contract_result.is_valid:
+            logger.warning(
+                "Contract validation failed for %s: %s",
+                agent_type, contract_result.error_message,
+            )
+
+        cleanup_approval(agent_type)
+
+        # Consume all confirmed grants -- subagent session is over
+        try:
+            from modules.security.approval_grants import consume_session_grants
+            consume_session_grants(session_id)
+        except Exception:
+            pass
+
+        commands_executed = extract_commands_from_evidence(agent_output)
+        context_update_result = process_context_updates(agent_output, task_info)
+
+        session_context = {
+            "timestamp": _dt.now().isoformat(),
+            "session_id": session_id,
+            "task_id": task_info.get("task_id", "unknown"),
+            "agent_id": task_info.get("agent_id", "unknown"),
+            "agent": agent_type,
+        }
+        workflow_metrics = record_workflow(
+            task_info,
+            agent_output,
+            session_context,
+            commands_executed=commands_executed,
+            context_update_result=context_update_result,
+        )
+
+        response_contract = validate_response_contract(
+            agent_output,
+            task_agent_id=resolve_agent_id(task_info),
+            consolidation_required=requires_consolidation_report(task_info),
+            parsed_contract=parsed_contract,
+        )
+        save_validation_result(task_info, response_contract)
+
+        anomalies = audit_workflow(
+            workflow_metrics,
+            agent_output,
+            task_info,
+            rejected_sections=(context_update_result or {}).get("rejected", []),
+        )
+        if not response_contract.valid:
+            missing = ", ".join(response_contract.missing) or "none"
+            invalid = ", ".join(response_contract.invalid) or "none"
+            anomalies.append({
+                "type": "response_contract_violation",
+                "severity": "critical",
+                "message": (
+                    f"Agent response contract invalid for {task_info.get('agent', 'unknown')}: "
+                    f"missing=[{missing}] invalid=[{invalid}]"
+                ),
+            })
+
+        if anomalies:
+            logger.warning(f"{len(anomalies)} anomalies detected in workflow")
+            signal_gaia_analysis(anomalies, workflow_metrics)
+
+        workflow_metrics["anomalies_detected"] = len(anomalies)
+        workflow_metrics["anomaly_types"] = [a.get("type", "") for a in anomalies]
+
+        episode_id = write_episode(
+            workflow_metrics,
+            anomalies=anomalies if anomalies else None,
+            commands_executed=commands_executed,
+        )
+
+        contract_attempts = 0
+        if not response_contract.valid:
+            try:
+                repair_data = response_contract.to_dict()
+                contract_attempts = int(repair_data.get("repair_attempts", 0))
+            except Exception:
+                contract_attempts = 0
+
+        return {
+            "success": True,
+            "session_id": session_id,
+            "status": "metrics_captured",
+            "metrics_captured": True,
+            "anomalies_detected": len(anomalies) if anomalies else 0,
+            "episode_id": episode_id,
+            "context_updated": context_update_result.get("updated", False) if context_update_result else False,
+            "response_contract": response_contract.to_dict(),
+            "contract_validated": contract_result.is_valid,
+            "contract_attempts": contract_attempts,
+        }
+
+    except Exception as e:
+        logger.error(f"Error in subagent_stop_hook: {e}", exc_info=True)
+        return {
+            "success": False,
+            "error": str(e),
+            "status": "partial_update"
+        }
+
+
+# ============================================================================
+# Thin gate handler (stdin mode)
+# ============================================================================
+
+def _handle_subagent_stop(event) -> None:
+    """Process a SubagentStop event.
+
+    Delegates all business logic to the adapter.
+
+    Args:
+        event: Parsed HookEvent from the adapter layer.
+    """
+    adapter = ClaudeCodeAdapter()
+    response = adapter.adapt_subagent_stop(event)
+
+    if response.exit_code == 2:
+        error_msg = response.output.get("contract_rejection_reason", response.output.get("error", "unknown")) if isinstance(response.output, dict) else str(response.output)
+        print(
+            f"HOOK ERROR: Contract rejected: {error_msg}",
+            file=sys.stderr,
+        )
+
+    print(json.dumps(response.output))
+    sys.exit(response.exit_code)
+
+
+# ============================================================================
+# CLI interface
+# ============================================================================
+
+def main():
+    """CLI interface for testing metrics capture."""
+    if len(sys.argv) < 2:
+        print("Usage: python subagent_stop.py --test")
+        sys.exit(1)
+
+    if sys.argv[1] == "--test":
+        test_task_info = {
+            "task_id": "T006",
+            "description": "Terraform plan for infrastructure",
+            "agent": "terraform-architect",
+            "tier": "T1",
+            "tags": ["#terraform", "#infrastructure"],
+        }
+        test_output = (
+            "# Terraform Architect Execution Log\n\n"
+            "## Task: T006 - Terraform plan for infrastructure\n\n"
+            "### Results:\n"
+            "- Configuration validated successfully\n"
+            "- Plan generated with 12 resources\n"
+            "- Duration: 45000 ms\n"
+        )
+        result = subagent_stop_hook(test_task_info, test_output)
+        if result["success"]:
+            print("Test completed successfully!")
+            print(f"Session ID: {result['session_id']}")
+            print(f"Anomalies: {result['anomalies_detected']}")
+            print(f"Episode ID: {result.get('episode_id', 'none')}")
+        else:
+            print(f"Test failed: {result.get('error', 'Unknown error')}")
+    else:
+        print("Unknown command. Use --test to run test.")
+
+
+# ============================================================================
+# STDIN HANDLER (Claude Code integration)
+# ============================================================================
+
+if __name__ == "__main__":
+    if len(sys.argv) > 1:
+        main()
+    else:
+        run_hook(_handle_subagent_stop, hook_name="subagent_stop")

package/hooks/task_completed.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""
+TaskCompleted hook for Claude Code Agent System.
+
+Fires when a task is marked complete. Verifies that completion criteria are
+met before allowing the task to close. For MVP: logs the event and allows
+completion (passthrough). Quality checks will be wired in a future iteration.
+
+Architecture:
+- Uses adapter layer to parse TaskCompleted event
+- Calls adapter.adapt_task_completed() for criteria verification
+- Returns verification result via adapter format_verification_response()
+"""
+
+import sys
+import json
+import logging
+from datetime import datetime
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from adapters.claude_code import ClaudeCodeAdapter
+from modules.core.hook_entry import run_hook
+from modules.core.paths import get_logs_dir
+
+# Configure logging
+_log_file = get_logs_dir() / f"hooks-{datetime.now().strftime('%Y-%m-%d')}.log"
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s [task_completed] %(name)s - %(levelname)s - %(message)s',
+    handlers=[logging.FileHandler(_log_file)],
+)
+logger = logging.getLogger(__name__)
+
+
+def _handle_task_completed(event) -> None:
+    """Process a TaskCompleted event.
+
+    Checks whether task completion criteria are met.
+    For MVP, always allows completion.
+
+    Args:
+        event: Parsed HookEvent from the adapter layer.
+    """
+    adapter = ClaudeCodeAdapter()
+
+    # Parse task completed event via adapter
+    verification_result = adapter.adapt_task_completed(event.payload)
+    task_id = event.payload.get("task_id", "unknown")
+
+    logger.info(
+        "TaskCompleted: task_id=%s, criteria_met=%s, block=%s",
+        task_id,
+        verification_result.criteria_met,
+        verification_result.block_completion,
+    )
+
+    # Format and output verification response
+    response = adapter.format_verification_response(verification_result)
+    print(json.dumps(response.output))
+    sys.exit(0)
+
+
+# ============================================================================
+# STDIN HANDLER (Claude Code integration)
+# ============================================================================
+
+if __name__ == "__main__":
+    run_hook(_handle_task_completed, hook_name="task_completed")

package/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/index.js

@@ -0,0 +1,83 @@
+/**
+ * @jaguilar87/gaia
+ *
+ * Multi-agent orchestration system for Claude Code - DevOps automation toolkit
+ *
+ * Usage:
+ *   import { getAgentPath, getToolPath, getConfigPath } from '@jaguilar87/gaia';
+ *   const agentPath = getAgentPath('gitops-operator');
+ *   const toolPath = getToolPath('context_provider.py');
+ *   const configPath = getConfigPath('git_standards.json');
+ */
+
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export const PACKAGE_ROOT = __dirname;
+
+/**
+ * Get absolute path to an agent definition
+ * @param {string} agentName - Name of the agent (e.g., 'gitops-operator')
+ * @returns {string} Absolute path to agent file
+ */
+export function getAgentPath(agentName) {
+  return join(PACKAGE_ROOT, 'agents', `${agentName}.md`);
+}
+
+/**
+ * Get absolute path to a tool
+ * @param {string} toolName - Name of the tool (e.g., 'context_provider.py')
+ * @returns {string} Absolute path to tool file
+ */
+export function getToolPath(toolName) {
+  return join(PACKAGE_ROOT, 'tools', toolName);
+}
+
+/**
+ * Get absolute path to a hook
+ * @param {string} hookName - Name of the hook (e.g., 'pre-commit')
+ * @returns {string} Absolute path to hook file
+ */
+export function getHookPath(hookName) {
+  return join(PACKAGE_ROOT, 'hooks', hookName);
+}
+
+/**
+ * Get absolute path to a command
+ * @param {string} commandName - Name of the command (e.g., 'architect.md')
+ * @returns {string} Absolute path to command file
+ */
+export function getCommandPath(commandName) {
+  return join(PACKAGE_ROOT, 'commands', commandName);
+}
+
+/**
+ * Get absolute path to a template
+ * @param {string} templateName - Name of the template (e.g., 'governance.template.md')
+ * @returns {string} Absolute path to template file
+ */
+export function getTemplatePath(templateName) {
+  return join(PACKAGE_ROOT, 'templates', templateName);
+}
+
+/**
+ * Get absolute path to config file
+ * @param {string} configName - Name of the config (e.g., 'git_standards.json')
+ * @returns {string} Absolute path to config file
+ */
+export function getConfigPath(configName) {
+  return join(PACKAGE_ROOT, 'config', configName);
+}
+
+export default {
+  PACKAGE_ROOT,
+  getAgentPath,
+  getToolPath,
+  getHookPath,
+  getCommandPath,
+  getTemplatePath,
+  getConfigPath
+};