@mamdouh-aboammar/agentic-workflow 1.2.0

package/core/hooks/adapters/__init__.py

@@ -0,0 +1,25 @@
+"""
+Universal Agentic Hooks Framework (UAHF) — Adapters
+===================================================
+Adapters for normalizing hooks across Claude, Cursor, Antigravity, Gemini CLI, Codex, Shell, Homebrew, MCP, and CLI.
+"""
+
+from .claude_adapter import ClaudeHookAdapter
+from .gemini_adapter import GeminiHookAdapter
+from .cursor_adapter import CursorHookAdapter
+from .codex_adapter import CodexHookAdapter
+from .shell_adapter import ShellHookAdapter
+from .homebrew_adapter import HomebrewHookAdapter
+from .mcp_proxy import McpHookProxy
+from .cli_agent_adapter import CliAgentAdapter
+
+__all__ = [
+    "ClaudeHookAdapter",
+    "GeminiHookAdapter",
+    "CursorHookAdapter",
+    "CodexHookAdapter",
+    "ShellHookAdapter",
+    "HomebrewHookAdapter",
+    "McpHookProxy",
+    "CliAgentAdapter",
+]

package/core/hooks/adapters/claude_adapter.py

@@ -0,0 +1,83 @@
+"""
+Claude Code Hook Adapter
+========================
+Consumes native Claude Code PreToolUse, PostToolUse, and Session lifecycle hooks.
+Interprets stdin JSON, normalizes to HookEvent, and controls Claude via exit codes (0 vs 2).
+"""
+
+import json
+import sys
+from typing import Any, Dict, Optional
+
+from ..types import (
+    HookEvent,
+    HookResult,
+    HookSource,
+    HookType,
+    HookVerdict,
+)
+from ..policy_engine import UniversalPolicyEngine
+
+
+class ClaudeHookAdapter:
+    """Consumes and mediates Claude Code lifecycle hooks."""
+
+    def __init__(self, policy_engine: Optional[UniversalPolicyEngine] = None):
+        self.engine = policy_engine or UniversalPolicyEngine()
+
+    def parse_payload(self, raw_input: str, hook_type: HookType = HookType.PRE_TOOL) -> Optional[HookEvent]:
+        try:
+            data = json.loads(raw_input) if isinstance(raw_input, str) else raw_input
+        except Exception:
+            return None
+
+        if not isinstance(data, dict):
+            return None
+
+        tool_name = data.get("tool_name") or data.get("name")
+        tool_input = data.get("tool_input") or data.get("input") or {}
+        tool_response = data.get("tool_response") or data.get("output")
+
+        command = None
+        file_path = None
+
+        if isinstance(tool_input, dict):
+            command = tool_input.get("command")
+            file_path = tool_input.get("file_path") or tool_input.get("path") or tool_input.get("target")
+
+        return HookEvent(
+            source=HookSource.CLAUDE,
+            hook_type=hook_type,
+            tool_name=tool_name,
+            command=command,
+            file_path=file_path,
+            args=tool_input if isinstance(tool_input, dict) else {"raw": tool_input},
+            output=tool_response,
+            metadata={"raw_claude_payload": data},
+        )
+
+    def handle(self, raw_input: str, hook_type: HookType = HookType.PRE_TOOL) -> HookResult:
+        event = self.parse_payload(raw_input, hook_type)
+        if not event:
+            return HookResult(event_id="claude_empty", verdict=HookVerdict.ALLOW, exit_code=0)
+
+        result = self.engine.evaluate(event)
+        return result
+
+    def run_cli(self, hook_type_str: str = "pre_tool"):
+        """CLI runner for direct pipe execution in .claude/settings.json."""
+        raw = sys.stdin.read()
+        if not raw.strip():
+            sys.exit(0)
+
+        htype = HookType.POST_TOOL if "post" in hook_type_str.lower() else HookType.PRE_TOOL
+        result = self.handle(raw, htype)
+
+        if result.verdict == HookVerdict.BLOCK:
+            print(f"🛑 [UAHF Claude Hook] {result.message}", file=sys.stderr)
+            sys.exit(result.exit_code or 2)
+        elif result.verdict == HookVerdict.WARN:
+            print(f"⚠️ [UAHF Claude Hook] {result.message}", file=sys.stderr)
+            sys.exit(0)
+
+        sys.exit(0)

package/core/hooks/adapters/cli_agent_adapter.py

@@ -0,0 +1,82 @@
+"""
+CLI Agent Wrapper & Interceptor Adapter
+=======================================
+Supervises external CLI agents (OpenAI Codex, Moonshot Kimi, Aider, etc.).
+Intercepts agent execution, enforces pre-flight governance, and injects protective hooks.
+"""
+
+import os
+import shutil
+import subprocess
+import sys
+from typing import List, Optional
+
+from ..types import (
+    HookEvent,
+    HookResult,
+    HookSource,
+    HookType,
+    HookVerdict,
+)
+from ..policy_engine import UniversalPolicyEngine
+
+
+class CliAgentAdapter:
+    """Wraps and mediates execution of autonomous CLI agents."""
+
+    def __init__(self, policy_engine: Optional[UniversalPolicyEngine] = None):
+        self.engine = policy_engine or UniversalPolicyEngine()
+
+    def identify_agent_source(self, binary_name: str) -> HookSource:
+        name = os.path.basename(binary_name).lower()
+        if "codex" in name:
+            return HookSource.CODEX
+        elif "kimi" in name:
+            return HookSource.KIMI
+        elif "cursor" in name:
+            return HookSource.CURSOR
+        elif "antigravity" in name:
+            return HookSource.ANTIGRAVITY
+        elif "claude" in name:
+            return HookSource.CLAUDE
+        return HookSource.CLI
+
+    def run_supervised(self, command_args: List[str]) -> int:
+        if not command_args:
+            print("❌ No command provided to CLI Agent supervisor.", file=sys.stderr)
+            return 1
+
+        binary = command_args[0]
+        source = self.identify_agent_source(binary)
+
+        # Pre-execution policy check on the agent invocation itself
+        full_command = " ".join(command_args)
+        event = HookEvent(
+            source=source,
+            hook_type=HookType.SESSION_START,
+            command=full_command,
+            tool_name=binary,
+            args={"raw_args": command_args[1:]},
+            agent_id=f"agent_{source.value}",
+        )
+
+        result = self.engine.evaluate(event)
+        if result.verdict == HookVerdict.BLOCK:
+            print(f"\033[1;31m🛑 [CLI Agent Guard] INVOCATION BLOCKED:\033[0m\n  {result.message}", file=sys.stderr)
+            return 2
+
+        # Inject environment hook overrides so subshells spawned by the agent hit our hooks
+        env = os.environ.copy()
+        repo_root = os.path.abspath(os.path.join(os.path.dirname(__file__), "../../.."))
+        hook_bin = os.path.join(repo_root, "bin")
+
+        current_path = env.get("PATH", "")
+        if hook_bin not in current_path:
+            env["PATH"] = f"{hook_bin}:{current_path}"
+
+        env["AGENTIC_HOOKS_ACTIVE"] = "1"
+        env["AGENTIC_AGENT_NAME"] = source.value
+
+        # Execute target agent
+        proc = subprocess.run(command_args, env=env)
+        return proc.returncode

package/core/hooks/adapters/codex_adapter.py

@@ -0,0 +1,78 @@
+"""
+OpenAI Codex & ChatGPT Plugin Hook Driver Adapter
+=================================================
+Consumes execution events from OpenAI Codex and ChatGPT plugin environments.
+Normalizes events to HookEvent(source=HookSource.CODEX) and applies sandbox security
+and governance policies.
+"""
+
+import json
+from typing import Any, Dict, Optional
+
+from ..types import (
+    HookEvent,
+    HookResult,
+    HookSource,
+    HookType,
+    HookVerdict,
+)
+from ..policy_engine import UniversalPolicyEngine
+
+
+class CodexHookAdapter:
+    """Consumes and mediates OpenAI Codex & ChatGPT plugin lifecycle events."""
+
+    def __init__(self, policy_engine: Optional[UniversalPolicyEngine] = None):
+        self.engine = policy_engine or UniversalPolicyEngine()
+
+    def parse_payload(self, raw_input: Any, hook_type: HookType = HookType.PRE_TOOL) -> Optional[HookEvent]:
+        """Parses a Codex / ChatGPT tool call payload into a normalized HookEvent."""
+        try:
+            data = json.loads(raw_input) if isinstance(raw_input, str) else raw_input
+        except Exception:
+            return None
+
+        if not isinstance(data, dict):
+            return None
+
+        tool_name = data.get("name") or data.get("tool_name") or data.get("function")
+        tool_args = data.get("arguments") or data.get("args") or data.get("input") or {}
+        output = data.get("output") or data.get("response")
+
+        if isinstance(tool_args, str):
+            try:
+                tool_args = json.loads(tool_args)
+            except Exception:
+                tool_args = {"raw": tool_args}
+
+        command = None
+        file_path = None
+
+        if isinstance(tool_args, dict):
+            command = tool_args.get("command") or tool_args.get("cmd") or tool_args.get("code")
+            file_path = tool_args.get("path") or tool_args.get("file_path") or tool_args.get("filename")
+
+        return HookEvent(
+            source=HookSource.CODEX,
+            hook_type=hook_type,
+            tool_name=tool_name or ("exec" if command else "plugin_call"),
+            command=command,
+            file_path=file_path,
+            args=tool_args if isinstance(tool_args, dict) else {"raw": tool_args},
+            output=output,
+            metadata={"raw_codex_payload": data},
+        )
+
+    def handle(self, raw_input: Any, hook_type: HookType = HookType.PRE_TOOL) -> HookResult:
+        """Evaluates Codex event against universal policies."""
+        event = self.parse_payload(raw_input, hook_type)
+        if not event:
+            return HookResult(event_id="codex_empty", verdict=HookVerdict.ALLOW, exit_code=0)
+
+        return self.engine.evaluate(event)
+
+    def evaluate_tool(self, name: str, arguments: Dict[str, Any], is_pre: bool = True, output: Optional[Any] = None) -> HookResult:
+        """Convenience method for programmatic Codex tool call evaluation."""
+        hook_type = HookType.PRE_TOOL if is_pre else HookType.POST_TOOL
+        payload = {"name": name, "arguments": arguments, "output": output}
+        return self.handle(payload, hook_type)

package/core/hooks/adapters/cursor_adapter.py

@@ -0,0 +1,73 @@
+"""
+Cursor IDE & Windsurf Hook Driver Adapter
+=========================================
+Consumes tool execution and terminal command events from Cursor IDE rules (.cursor/rules)
+and Windsurf cascades. Normalizes events to HookEvent(source=HookSource.CURSOR) and applies
+governance policies.
+"""
+
+import json
+from typing import Any, Dict, Optional
+
+from ..types import (
+    HookEvent,
+    HookResult,
+    HookSource,
+    HookType,
+    HookVerdict,
+)
+from ..policy_engine import UniversalPolicyEngine
+
+
+class CursorHookAdapter:
+    """Consumes and mediates Cursor IDE & Windsurf lifecycle events."""
+
+    def __init__(self, policy_engine: Optional[UniversalPolicyEngine] = None):
+        self.engine = policy_engine or UniversalPolicyEngine()
+
+    def parse_payload(self, raw_input: Any, hook_type: HookType = HookType.PRE_TOOL) -> Optional[HookEvent]:
+        """Parses Cursor / Windsurf command or tool invocation payload."""
+        try:
+            data = json.loads(raw_input) if isinstance(raw_input, str) else raw_input
+        except Exception:
+            return None
+
+        if not isinstance(data, dict):
+            return None
+
+        tool_name = data.get("tool") or data.get("tool_name") or data.get("action")
+        command = data.get("command") or data.get("cmd")
+        file_path = data.get("file_path") or data.get("path") or data.get("target_file")
+        tool_args = data.get("args") or data.get("parameters") or {}
+        output = data.get("output") or data.get("result")
+
+        if isinstance(tool_args, dict):
+            if not command:
+                command = tool_args.get("command") or tool_args.get("cmd")
+            if not file_path:
+                file_path = tool_args.get("file_path") or tool_args.get("path") or tool_args.get("target_file")
+
+        return HookEvent(
+            source=HookSource.CURSOR,
+            hook_type=hook_type,
+            tool_name=tool_name or ("terminal" if command else "file_op"),
+            command=command,
+            file_path=file_path,
+            args=tool_args if isinstance(tool_args, dict) else {"raw": tool_args},
+            output=output,
+            metadata={"raw_cursor_payload": data},
+        )
+
+    def handle(self, raw_input: Any, hook_type: HookType = HookType.PRE_TOOL) -> HookResult:
+        """Evaluates Cursor event against universal policies."""
+        event = self.parse_payload(raw_input, hook_type)
+        if not event:
+            return HookResult(event_id="cursor_empty", verdict=HookVerdict.ALLOW, exit_code=0)
+
+        return self.engine.evaluate(event)
+
+    def evaluate_command(self, command_line: str, is_pre: bool = True, output: Optional[str] = None) -> HookResult:
+        """Convenience method for evaluating Cursor terminal commands."""
+        hook_type = HookType.PRE_COMMAND if is_pre else HookType.POST_COMMAND
+        payload = {"command": command_line, "output": output}
+        return self.handle(payload, hook_type)

package/core/hooks/adapters/gemini_adapter.py

@@ -0,0 +1,93 @@
+"""
+Google Antigravity & Gemini CLI Hook Driver Adapter
+===================================================
+Consumes tool execution events from Google Antigravity and Gemini CLI environments.
+Normalizes tool calls (run_command, write_to_file, replace_file_content, view_file, invoke_subagent)
+into canonical HookEvent instances and applies UAHF policy engine gates.
+"""
+
+import json
+import os
+import re
+import sys
+from typing import Any, Dict, Optional
+
+from ..types import (
+    HookEvent,
+    HookResult,
+    HookSource,
+    HookType,
+    HookVerdict,
+)
+from ..policy_engine import UniversalPolicyEngine
+
+
+class GeminiHookAdapter:
+    """Consumes and mediates Gemini CLI & Google Antigravity lifecycle tool events."""
+
+    def __init__(self, policy_engine: Optional[UniversalPolicyEngine] = None):
+        self.engine = policy_engine or UniversalPolicyEngine()
+
+    def parse_payload(self, raw_input: Any, hook_type: HookType = HookType.PRE_TOOL) -> Optional[HookEvent]:
+        """Parses a Gemini CLI / Antigravity tool call payload into a normalized HookEvent."""
+        try:
+            data = json.loads(raw_input) if isinstance(raw_input, str) else raw_input
+        except Exception:
+            return None
+
+        if not isinstance(data, dict):
+            return None
+
+        tool_name = data.get("tool_name") or data.get("name") or data.get("tool")
+        tool_args = data.get("args") or data.get("arguments") or data.get("parameters") or {}
+        tool_response = data.get("response") or data.get("output") or data.get("result")
+
+        command = None
+        file_path = None
+
+        if isinstance(tool_args, dict):
+            # Antigravity run_command convention
+            command = tool_args.get("CommandLine") or tool_args.get("command") or tool_args.get("cmd")
+            # Antigravity file tools (view_file, write_to_file, replace_file_content)
+            file_path = (
+                tool_args.get("AbsolutePath")
+                or tool_args.get("TargetFile")
+                or tool_args.get("file_path")
+                or tool_args.get("path")
+            )
+
+        return HookEvent(
+            source=HookSource.ANTIGRAVITY,
+            hook_type=hook_type,
+            tool_name=tool_name,
+            command=command,
+            file_path=file_path,
+            args=tool_args if isinstance(tool_args, dict) else {"raw": tool_args},
+            output=tool_response,
+            metadata={"raw_gemini_payload": data},
+        )
+
+    def handle(self, raw_input: Any, hook_type: HookType = HookType.PRE_TOOL) -> HookResult:
+        """Evaluates payload against universal policies."""
+        event = self.parse_payload(raw_input, hook_type)
+        if not event:
+            return HookResult(event_id="gemini_empty", verdict=HookVerdict.ALLOW, exit_code=0)
+
+        result = self.engine.evaluate(event)
+        return result
+
+    def evaluate_tool_call(
+        self,
+        tool_name: str,
+        arguments: Dict[str, Any],
+        is_pre: bool = True,
+        output: Optional[Any] = None
+    ) -> HookResult:
+        """Programmatic evaluation entry point for Python-driven Gemini / Antigravity agents."""
+        hook_type = HookType.PRE_TOOL if is_pre else HookType.POST_TOOL
+        payload = {
+            "tool_name": tool_name,
+            "args": arguments,
+            "output": output
+        }
+        return self.handle(payload, hook_type)

package/core/hooks/adapters/homebrew_adapter.py

@@ -0,0 +1,69 @@
+"""
+Homebrew Package Manager Hook Adapter
+=====================================
+Dedicated gatekeeper for Homebrew command interception and package hygiene.
+Enforces prohibitions against heavy or banned packages (e.g. Colima) and unsafe flags.
+"""
+
+import shutil
+import subprocess
+import sys
+from typing import List, Optional
+
+from ..types import (
+    HookEvent,
+    HookResult,
+    HookSource,
+    HookType,
+    HookVerdict,
+)
+from ..policy_engine import UniversalPolicyEngine
+
+
+class HomebrewHookAdapter:
+    """Intercepts and verifies brew operations before execution."""
+
+    def __init__(self, policy_engine: Optional[UniversalPolicyEngine] = None):
+        self.engine = policy_engine or UniversalPolicyEngine()
+
+    def evaluate_brew_args(self, args: List[str]) -> HookResult:
+        full_command = f"brew {' '.join(args)}".strip()
+        package_target = None
+        for i, arg in enumerate(args):
+            if arg in ["install", "reinstall", "cask"] and i + 1 < len(args):
+                package_target = args[i + 1]
+                break
+
+        event = HookEvent(
+            source=HookSource.HOMEBREW,
+            hook_type=HookType.PRE_COMMAND,
+            command=full_command,
+            tool_name="homebrew",
+            args={"raw_args": args, "package": package_target},
+        )
+        return self.engine.evaluate(event)
+
+    def run_shim(self, brew_args: List[str]) -> int:
+        result = self.evaluate_brew_args(brew_args)
+        if result.verdict == HookVerdict.BLOCK:
+            print(f"\033[1;31m🛑 [Homebrew Hook Guard] OPERATION BLOCKED:\033[0m\n  {result.message}", file=sys.stderr)
+            return 2
+        elif result.verdict == HookVerdict.WARN:
+            print(f"\033[1;33m⚠️ [Homebrew Hook Guard] ADVISORY:\033[0m {result.message}", file=sys.stderr)
+
+        # Locate real brew binary
+        real_brew = None
+        for candidate in ["/opt/homebrew/bin/brew", "/usr/local/bin/brew"]:
+            if shutil.which(candidate):
+                real_brew = candidate
+                break
+        if not real_brew:
+            real_brew = shutil.which("brew")
+
+        if not real_brew:
+            print("❌ [Homebrew Hook Guard] Homebrew executable not found on system PATH.", file=sys.stderr)
+            return 127
+
+        # Pass through to real brew
+        res = subprocess.run([real_brew] + brew_args)
+        return res.returncode

package/core/hooks/adapters/mcp_proxy.py

@@ -0,0 +1,133 @@
+"""
+Universal MCP (Model Context Protocol) Hook Proxy
+=================================================
+Transparent JSON-RPC proxy sitting between any MCP client (Cursor, Antigravity, Claude,
+Codex, Kimi) and downstream MCP servers.
+Intercepts 'tools/call' requests for policy gating and inspects tool responses for leaks.
+"""
+
+import json
+import logging
+import subprocess
+import sys
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+from ..types import (
+    HookEvent,
+    HookResult,
+    HookSource,
+    HookType,
+    HookVerdict,
+)
+from ..policy_engine import UniversalPolicyEngine
+
+
+class McpHookProxy:
+    """Proxies and governs Model Context Protocol tool invocations."""
+
+    def __init__(self, policy_engine: Optional[UniversalPolicyEngine] = None):
+        self.engine = policy_engine or UniversalPolicyEngine()
+
+    def inspect_request(self, message: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        """
+        Inspect an MCP client JSON-RPC request.
+        If it's a tools/call and policy triggers a BLOCK, return a synthetic JSON-RPC error.
+        Otherwise return None (allow pass-through).
+        """
+        if message.get("method") != "tools/call":
+            return None
+
+        params = message.get("params") or {}
+        tool_name = params.get("name")
+        tool_args = params.get("arguments") or {}
+
+        event = HookEvent(
+            source=HookSource.MCP,
+            hook_type=HookType.PRE_TOOL,
+            tool_name=tool_name,
+            command=tool_args.get("command") or tool_args.get("cmd"),
+            file_path=tool_args.get("path") or tool_args.get("file_path"),
+            args=tool_args,
+        )
+
+        result = self.engine.evaluate(event)
+        if result.verdict == HookVerdict.BLOCK:
+            msg_id = message.get("id")
+            return {
+                "jsonrpc": "2.0",
+                "id": msg_id,
+                "error": {
+                    "code": -32000,
+                    "message": f"MCP Tool Execution Blocked by Policy: {result.message}",
+                    "data": {"rule_id": result.rule_id, "verdict": "blocked"},
+                },
+            }
+        return None
+
+    def inspect_response(self, response: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Inspect MCP server JSON-RPC response before delivering back to the client.
+        Checks for secret leakage in tool output.
+        """
+        result_payload = response.get("result")
+        if not result_payload:
+            return response
+
+        event = HookEvent(
+            source=HookSource.MCP,
+            hook_type=HookType.POST_TOOL,
+            output=json.dumps(result_payload),
+        )
+
+        res = self.engine.evaluate(event)
+        if res.verdict == HookVerdict.WARN and "SECRET LEAK DETECTED" in res.message:
+            # Mask or annotate leak advisory
+            if isinstance(result_payload, dict) and "content" in result_payload:
+                result_payload["_security_advisory"] = res.message
+        return response
+
+    def run_proxy(self, server_command: List[str]):
+        """Run downstream MCP server as subprocess, proxying stdin/stdout."""
+        proc = subprocess.Popen(
+            server_command,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=sys.stderr,
+            text=True,
+            bufsize=1,
+        )
+
+        try:
+            for line in sys.stdin:
+                line = line.strip()
+                if not line:
+                    continue
+
+                try:
+                    msg = json.loads(line)
+                    blocked_resp = self.inspect_request(msg)
+                    if blocked_resp:
+                        print(json.dumps(blocked_resp), flush=True)
+                        continue
+                except Exception as parse_err:
+                    logger.debug("MCP JSON parse error: %s", parse_err)
+
+                # Forward to server
+                if proc.stdin:
+                    proc.stdin.write(line + "\n")
+                    proc.stdin.flush()
+
+                # Read response from server
+                if proc.stdout:
+                    resp_line = proc.stdout.readline()
+                    if resp_line:
+                        try:
+                            resp_json = json.loads(resp_line.strip())
+                            sanitized = self.inspect_response(resp_json)
+                            print(json.dumps(sanitized), flush=True)
+                        except Exception:
+                            print(resp_line.strip(), flush=True)
+        finally:
+            proc.terminate()