cycode 3.15.3.dev7__py3-none-any.whl → 3.15.4.dev1__py3-none-any.whl

cycode/cli/apps/ai_guardrails/ides/base.py

@@ -0,0 +1,156 @@
+"""Base abstractions for AI guardrails IDE integrations.
+
+Each AI IDE (Cursor, Claude Code, …) is represented by a subclass of `IDE`
+that consolidates every IDE-specific concern in a single module: settings file
+paths, hooks template rendering, payload parsing, response building, and any
+IDE-specific session-context lookup.
+
+Adding a new IDE is a matter of:
+  1. Subclassing `IDE` and implementing the abstract methods.
+  2. Registering the instance in `cycode/cli/apps/ai_guardrails/ides/__init__.py`.
+
+The `HookDecision` dataclass is the canonical, IDE-agnostic return type for
+event handlers; `IDE.build_hook_response` translates it into the IDE-specific
+JSON response shape that the IDE expects on stdout.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import ClassVar, Optional
+
+from cycode.cli.apps.ai_guardrails.scan.payload import AIHookPayload
+from cycode.cli.apps.ai_guardrails.scan.types import AiHookEventType
+
+
+class DecisionAction(str, Enum):
+    """Canonical decision action returned by event handlers."""
+
+    ALLOW = 'allow'
+    DENY = 'deny'
+    ASK = 'ask'
+
+
+@dataclass(frozen=True)
+class HookDecision:
+    """Canonical, IDE-agnostic decision returned by event handlers.
+
+    Carries the event type so `IDE.build_hook_response` can pick the right
+    IDE-specific response shape (Cursor's "permission" style for tool events
+    vs. "continue" style for prompts; Claude Code's "hookSpecificOutput"
+    vs. "decision: block").
+    """
+
+    action: DecisionAction
+    event_type: AiHookEventType
+    user_message: Optional[str] = None
+    agent_message: Optional[str] = None
+
+    @classmethod
+    def allow(cls, event_type: AiHookEventType) -> 'HookDecision':
+        return cls(action=DecisionAction.ALLOW, event_type=event_type)
+
+    @classmethod
+    def deny(
+        cls, event_type: AiHookEventType, user_message: str, agent_message: Optional[str] = None
+    ) -> 'HookDecision':
+        return cls(
+            action=DecisionAction.DENY,
+            event_type=event_type,
+            user_message=user_message,
+            agent_message=agent_message,
+        )
+
+    @classmethod
+    def ask(cls, event_type: AiHookEventType, user_message: str, agent_message: Optional[str] = None) -> 'HookDecision':
+        return cls(
+            action=DecisionAction.ASK,
+            event_type=event_type,
+            user_message=user_message,
+            agent_message=agent_message,
+        )
+
+
+class IDE(ABC):
+    """Per-IDE integration. Owns every IDE-specific concern in a single module.
+
+    Subclasses declare identity via class attributes and implement the abstract
+    methods. Defaults are provided for `get_user_email` and `get_session_context`
+    so IDEs without those capabilities (e.g. no plugin system, no local
+    account file) can skip them.
+    """
+
+    # CLI value passed to --ide (e.g. 'cursor', 'claude-code').
+    name: ClassVar[str]
+    # Human-friendly name for output ('Cursor', 'Claude Code').
+    display_name: ClassVar[str]
+    # Event names for status display. Use '<event>:<matcher>' for IDEs that
+    # qualify a single hook by a sub-matcher (e.g. Claude Code's PreToolUse:Read).
+    hook_events: ClassVar[list[str]]
+
+    # --- install / status ---
+
+    @abstractmethod
+    def settings_path(self, scope: str, repo_path: Optional[Path] = None) -> Path:
+        """Return the hooks/settings file path for the given scope.
+
+        `scope` is 'user' or 'repo'. `repo_path` is required when scope == 'repo'.
+        """
+
+    @abstractmethod
+    def render_hooks_config(self, async_mode: bool = False) -> dict:
+        """Return the settings blob to merge into the IDE's settings file.
+
+        Shape is IDE-specific (Cursor uses a flat ``{event: [{command}]}`` dict;
+        Claude Code uses a nested ``{event: [{hooks: [{type, command}]}]}``
+        dict). Both share the outer ``{"hooks": ...}`` wrapper so
+        ``hooks_manager`` can treat them uniformly.
+        """
+
+    # --- runtime scan ---
+
+    @abstractmethod
+    def matches_payload(self, raw_payload: dict) -> bool:
+        """Return True if ``raw_payload`` originated from this IDE.
+
+        Prevents double-processing when an IDE forwards another IDE's hook
+        event (e.g. Cursor reading Claude Code hooks from ~/.claude/settings.json).
+        """
+
+    @abstractmethod
+    def parse_hook_payload(self, raw_payload: dict) -> AIHookPayload:
+        """Normalize a raw stdin payload into the canonical ``AIHookPayload``."""
+
+    @abstractmethod
+    def build_hook_response(self, decision: HookDecision) -> dict:
+        """Translate a canonical ``HookDecision`` into the IDE-specific JSON.
+
+        The result is what ``scan_command`` writes to stdout for the IDE to
+        act on.
+        """
+
+    # --- session lifecycle (optional; sensible defaults) ---
+
+    def build_session_payload(self, raw_payload: dict) -> AIHookPayload:
+        """Build a session-start payload from the raw stdin payload.
+
+        Default: a minimal payload tagged with this IDE's ``name``. IDEs
+        that need to enrich with transcript/version info should override.
+        """
+        return AIHookPayload(ide_provider=self.name)
+
+    def get_user_email(self) -> Optional[str]:
+        """Best-effort read of the user's email from IDE-specific config.
+
+        Default: None. Override if the IDE stores a usable account locally.
+        """
+        return None
+
+    def get_session_context(self) -> tuple[dict, dict]:
+        """Return ``(mcp_servers, enabled_plugins)`` for session-context reporting.
+
+        Default: empty dicts (no plugin system, no discoverable MCP config).
+        Override to surface MCP/plugin inventory.
+        """
+        return {}, {}

cycode/cli/apps/ai_guardrails/ides/claude_code.py

@@ -0,0 +1,389 @@
+"""Claude Code IDE integration for AI guardrails."""
+
+import json
+from collections.abc import Iterator
+from copy import deepcopy
+from pathlib import Path
+from typing import ClassVar, Optional
+
+from cycode.cli.apps.ai_guardrails.consts import CYCODE_SCAN_PROMPT_COMMAND, CYCODE_SESSION_START_COMMAND
+from cycode.cli.apps.ai_guardrails.ides.base import IDE, DecisionAction, HookDecision
+from cycode.cli.apps.ai_guardrails.scan.payload import AIHookPayload
+from cycode.cli.apps.ai_guardrails.scan.types import AiHookEventType
+from cycode.logger import get_logger
+
+logger = get_logger('AI Guardrails Claude Code')
+
+_CLAUDE_CODE_EVENT_NAMES = frozenset({'UserPromptSubmit', 'PreToolUse'})
+
+_USER_HOOKS_DIR = Path.home() / '.claude'
+_HOOKS_FILE_NAME = 'settings.json'
+_REPO_SUBDIR = '.claude'
+_HOOK_EVENTS = ['UserPromptSubmit', 'PreToolUse:Read', 'PreToolUse:mcp']
+
+_CLAUDE_CONFIG_PATH = Path.home() / '.claude.json'
+_CLAUDE_SETTINGS_PATH = Path.home() / '.claude' / 'settings.json'
+
+_SCAN_COMMAND = f'{CYCODE_SCAN_PROMPT_COMMAND} --ide claude-code'
+_SESSION_START_COMMAND = f'{CYCODE_SESSION_START_COMMAND} --ide claude-code'
+
+
+# --- transcript JSONL parsing -------------------------------------------------
+
+
+def _reverse_readline(path: Path, buf_size: int = 8192) -> Iterator[str]:
+    """Yield lines of `path` from end to start without loading the file.
+
+    The Claude Code transcript can be very large; reading from the tail keeps
+    memory bounded since we only care about the most recent entries.
+    """
+    with path.open('rb') as f:
+        f.seek(0, 2)
+        file_size = f.tell()
+        if file_size == 0:
+            return
+
+        remaining = file_size
+        buffer = b''
+
+        while remaining > 0:
+            read_size = min(buf_size, remaining)
+            remaining -= read_size
+            f.seek(remaining)
+            chunk = f.read(read_size)
+            buffer = chunk + buffer
+
+            while b'\n' in buffer:
+                newline_pos = buffer.rfind(b'\n')
+                if newline_pos == len(buffer) - 1:
+                    newline_pos = buffer.rfind(b'\n', 0, newline_pos)
+                    if newline_pos == -1:
+                        break
+                line = buffer[newline_pos + 1 :]
+                buffer = buffer[: newline_pos + 1]
+                if line.strip():
+                    yield line.decode('utf-8', errors='replace')
+
+        if buffer.strip():
+            yield buffer.decode('utf-8', errors='replace')
+
+
+def _extract_model(entry: dict) -> Optional[str]:
+    """Extract model from a transcript entry (top level or nested in message)."""
+    return entry.get('model') or (entry.get('message') or {}).get('model')
+
+
+def _extract_generation_id(entry: dict) -> Optional[str]:
+    """Extract generation ID from a user-type transcript entry."""
+    if entry.get('type') == 'user':
+        return entry.get('uuid')
+    return None
+
+
+def extract_from_claude_transcript(
+    transcript_path: str,
+) -> tuple[Optional[str], Optional[str], Optional[str]]:
+    """Extract ``(ide_version, model, generation_id)`` from a transcript.
+
+    The transcript is a JSONL file scanned from end → start so the most recent
+    entries are read first. Any field may come back ``None`` if not found.
+    """
+    if not transcript_path:
+        return None, None, None
+
+    path = Path(transcript_path)
+    if not path.exists():
+        return None, None, None
+
+    ide_version = None
+    model = None
+    generation_id = None
+
+    try:
+        for line in _reverse_readline(path):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                entry = json.loads(line)
+                ide_version = ide_version or entry.get('version')
+                model = model or _extract_model(entry)
+                generation_id = generation_id or _extract_generation_id(entry)
+
+                if ide_version and model and generation_id:
+                    break
+            except json.JSONDecodeError:
+                continue
+    except OSError:
+        pass
+
+    return ide_version, model, generation_id
+
+
+# --- ~/.claude.json + ~/.claude/settings.json parsing -------------------------
+
+
+def load_claude_config(config_path: Optional[Path] = None) -> Optional[dict]:
+    """Load and parse `~/.claude.json`. Returns None if missing/invalid."""
+    path = config_path or _CLAUDE_CONFIG_PATH
+    if not path.exists():
+        logger.debug('Claude config file not found', extra={'path': str(path)})
+        return None
+    try:
+        return json.loads(path.read_text(encoding='utf-8'))
+    except Exception as e:
+        logger.debug('Failed to load Claude config file', exc_info=e)
+        return None
+
+
+def _email_from_config(config: dict) -> Optional[str]:
+    """Read ``oauthAccount.emailAddress`` from a parsed Claude config."""
+    return config.get('oauthAccount', {}).get('emailAddress')
+
+
+def get_mcp_servers(config: dict) -> Optional[dict]:
+    """Read ``mcpServers`` from a parsed Claude config."""
+    return config.get('mcpServers')
+
+
+def load_claude_settings(settings_path: Optional[Path] = None) -> Optional[dict]:
+    """Load and parse `~/.claude/settings.json`. Returns None if missing/invalid."""
+    path = settings_path or _CLAUDE_SETTINGS_PATH
+    if not path.exists():
+        logger.debug('Claude settings file not found', extra={'path': str(path)})
+        return None
+    try:
+        return json.loads(path.read_text(encoding='utf-8'))
+    except Exception as e:
+        logger.debug('Failed to load Claude settings file', exc_info=e)
+        return None
+
+
+def _resolve_marketplace_path(marketplace: dict) -> Optional[Path]:
+    """Resolve filesystem path for a directory-type marketplace."""
+    source = marketplace.get('source', {})
+    if source.get('source') != 'directory':
+        return None
+    raw = source.get('path')
+    if not raw:
+        return None
+    path = Path(raw)
+    return path if path.is_dir() else None
+
+
+def _load_plugin_json_file(plugin_path: Path, relative_path: str) -> Optional[dict]:
+    """Load and parse a JSON file inside a plugin directory.
+
+    Returns None if the file is missing, unreadable, or has invalid JSON.
+    """
+    target = plugin_path / relative_path
+    if not target.exists():
+        return None
+    try:
+        return json.loads(target.read_text(encoding='utf-8'))
+    except Exception as e:
+        logger.debug('Failed to load plugin file', extra={'path': str(target)}, exc_info=e)
+        return None
+
+
+def resolve_plugins(settings: dict) -> tuple[dict, dict]:
+    """Resolve enabled plugins to their MCP servers and metadata.
+
+    Walks ``enabledPlugins`` from claude settings, resolves each plugin's
+    marketplace directory via ``extraKnownMarketplaces``, and reads:
+      - ``<path>/.mcp.json`` for MCP servers (merged into a flat dict)
+      - ``<path>/.claude-plugin/plugin.json`` for metadata (name, version, description)
+
+    Returns ``(merged_mcp_servers, enriched_plugins)``.
+    """
+    enabled = settings.get('enabledPlugins') or {}
+    marketplaces = settings.get('extraKnownMarketplaces') or {}
+    merged_mcp: dict = {}
+    enriched: dict = {}
+
+    for plugin_key, is_enabled in enabled.items():
+        if not is_enabled:
+            continue
+
+        entry: dict = {'enabled': True}
+        enriched[plugin_key] = entry
+
+        if '@' not in plugin_key:
+            continue
+
+        _plugin_name, marketplace_name = plugin_key.split('@', 1)
+        marketplace = marketplaces.get(marketplace_name)
+        if not marketplace:
+            continue
+
+        plugin_path = _resolve_marketplace_path(marketplace)
+        if plugin_path is None:
+            continue
+
+        metadata = _load_plugin_json_file(plugin_path, '.claude-plugin/plugin.json') or {}
+        for field in ('name', 'version', 'description'):
+            if field in metadata:
+                entry[field] = metadata[field]
+
+        mcp_config = _load_plugin_json_file(plugin_path, '.mcp.json') or {}
+        plugin_server_names = []
+        for server_name, server_cfg in (mcp_config.get('mcpServers') or {}).items():
+            merged_mcp[server_name] = server_cfg
+            plugin_server_names.append(server_name)
+        if plugin_server_names:
+            entry['mcp_server_names'] = plugin_server_names
+
+    return merged_mcp, enriched
+
+
+# --- IDE integration ----------------------------------------------------------
+
+
+class ClaudeCode(IDE):
+    name: ClassVar[str] = 'claude-code'
+    display_name: ClassVar[str] = 'Claude Code'
+    hook_events: ClassVar[list[str]] = list(_HOOK_EVENTS)
+
+    def settings_path(self, scope: str, repo_path: Optional[Path] = None) -> Path:
+        if scope == 'repo' and repo_path:
+            return repo_path / _REPO_SUBDIR / _HOOKS_FILE_NAME
+        return _USER_HOOKS_DIR / _HOOKS_FILE_NAME
+
+    def render_hooks_config(self, async_mode: bool = False) -> dict:
+        # Claude Code uses a nested hook structure with optional async/timeout.
+        hook_entry: dict = {'type': 'command', 'command': _SCAN_COMMAND}
+        if async_mode:
+            hook_entry['async'] = True
+            hook_entry['timeout'] = 20
+
+        return {
+            'hooks': {
+                'SessionStart': [
+                    {
+                        'hooks': [{'type': 'command', 'command': _SESSION_START_COMMAND}],
+                    }
+                ],
+                'UserPromptSubmit': [
+                    {
+                        'hooks': [deepcopy(hook_entry)],
+                    }
+                ],
+                'PreToolUse': [
+                    {
+                        'matcher': 'Read',
+                        'hooks': [deepcopy(hook_entry)],
+                    },
+                    {
+                        'matcher': 'mcp__.*',
+                        'hooks': [deepcopy(hook_entry)],
+                    },
+                ],
+            },
+        }
+
+    def matches_payload(self, raw_payload: dict) -> bool:
+        return raw_payload.get('hook_event_name', '') in _CLAUDE_CODE_EVENT_NAMES
+
+    def parse_hook_payload(self, raw_payload: dict) -> AIHookPayload:
+        hook_event_name = raw_payload.get('hook_event_name', '')
+        tool_name = raw_payload.get('tool_name', '')
+        tool_input = raw_payload.get('tool_input')
+
+        if hook_event_name == 'UserPromptSubmit':
+            canonical_event: AiHookEventType | str = AiHookEventType.PROMPT
+        elif hook_event_name == 'PreToolUse':
+            canonical_event = AiHookEventType.FILE_READ if tool_name == 'Read' else AiHookEventType.MCP_EXECUTION
+        else:
+            canonical_event = hook_event_name
+
+        # Extract file_path from tool_input for the Read tool.
+        file_path = None
+        if tool_name == 'Read' and isinstance(tool_input, dict):
+            file_path = tool_input.get('file_path')
+
+        # For MCP tools, the entire tool_input is the arguments.
+        mcp_arguments = tool_input if tool_name.startswith('mcp__') else None
+
+        # MCP tool name format: mcp__<server>__<tool>
+        mcp_server_name = None
+        mcp_tool_name = None
+        if tool_name.startswith('mcp__'):
+            parts = tool_name.split('__')
+            if len(parts) >= 2:
+                mcp_server_name = parts[1]
+            if len(parts) >= 3:
+                mcp_tool_name = parts[2]
+
+        ide_version, model, generation_id = extract_from_claude_transcript(raw_payload.get('transcript_path'))
+
+        config = load_claude_config()
+        ide_user_email = _email_from_config(config) if config else None
+
+        return AIHookPayload(
+            event_name=canonical_event,
+            conversation_id=raw_payload.get('session_id'),
+            generation_id=generation_id,
+            ide_user_email=ide_user_email,
+            model=model,
+            ide_provider=self.name,
+            ide_version=ide_version,
+            prompt=raw_payload.get('prompt', ''),
+            file_path=file_path,
+            mcp_server_name=mcp_server_name,
+            mcp_tool_name=mcp_tool_name,
+            mcp_arguments=mcp_arguments,
+        )
+
+    def build_hook_response(self, decision: HookDecision) -> dict:
+        if decision.event_type == AiHookEventType.PROMPT:
+            if decision.action == DecisionAction.ALLOW:
+                return {}
+            # Both DENY and (unexpected) ASK on prompts collapse to a block.
+            return {'decision': 'block', 'reason': decision.user_message or ''}
+
+        # FILE_READ / MCP_EXECUTION → hookSpecificOutput shape.
+        if decision.action == DecisionAction.ALLOW:
+            return {
+                'hookSpecificOutput': {
+                    'hookEventName': 'PreToolUse',
+                    'permissionDecision': 'allow',
+                }
+            }
+        return {
+            'hookSpecificOutput': {
+                'hookEventName': 'PreToolUse',
+                'permissionDecision': decision.action.value,  # 'deny' or 'ask'
+                'permissionDecisionReason': decision.user_message or '',
+            }
+        }
+
+    def build_session_payload(self, raw_payload: dict) -> AIHookPayload:
+        config = load_claude_config()
+        ide_user_email = _email_from_config(config) if config else None
+        ide_version, _, _ = extract_from_claude_transcript(raw_payload.get('transcript_path'))
+
+        return AIHookPayload(
+            conversation_id=raw_payload.get('session_id'),
+            ide_user_email=ide_user_email,
+            model=raw_payload.get('model'),
+            ide_provider=self.name,
+            ide_version=ide_version,
+            source=raw_payload.get('source'),
+        )
+
+    def get_user_email(self) -> Optional[str]:
+        config = load_claude_config()
+        return _email_from_config(config) if config else None
+
+    def get_session_context(self) -> tuple[dict, dict]:
+        config = load_claude_config()
+        mcp_servers: dict = dict(get_mcp_servers(config) or {}) if config else {}
+
+        settings = load_claude_settings()
+        if settings:
+            plugin_mcp, enriched_plugins = resolve_plugins(settings)
+            mcp_servers.update(plugin_mcp)
+        else:
+            enriched_plugins = {}
+
+        return mcp_servers, enriched_plugins

cycode/cli/apps/ai_guardrails/ides/cursor.py

@@ -0,0 +1,119 @@
+"""Cursor IDE integration for AI guardrails."""
+
+import json
+import platform
+from pathlib import Path
+from typing import ClassVar, Optional
+
+from cycode.cli.apps.ai_guardrails.consts import CYCODE_SCAN_PROMPT_COMMAND, CYCODE_SESSION_START_COMMAND
+from cycode.cli.apps.ai_guardrails.ides.base import IDE, DecisionAction, HookDecision
+from cycode.cli.apps.ai_guardrails.scan.payload import AIHookPayload
+from cycode.cli.apps.ai_guardrails.scan.types import AiHookEventType
+from cycode.logger import get_logger
+
+logger = get_logger('AI Guardrails Cursor')
+
+_CURSOR_EVENT_MAPPING: dict[str, AiHookEventType] = {
+    'beforeSubmitPrompt': AiHookEventType.PROMPT,
+    'beforeReadFile': AiHookEventType.FILE_READ,
+    'beforeMCPExecution': AiHookEventType.MCP_EXECUTION,
+}
+
+_HOOKS_FILE_NAME = 'hooks.json'
+_REPO_SUBDIR = '.cursor'
+_MCP_CONFIG_FILENAME = 'mcp.json'
+
+# Cursor was the original default IDE — its scan command omits --ide to stay
+# byte-identical with already-installed hooks.json files. Session-start is
+# always explicit because it was introduced after Claude Code support.
+_SCAN_COMMAND = CYCODE_SCAN_PROMPT_COMMAND
+_SESSION_START_COMMAND = f'{CYCODE_SESSION_START_COMMAND} --ide cursor'
+
+
+def _user_hooks_dir() -> Path:
+    """Per-platform Cursor user-scope settings directory."""
+    if platform.system() == 'Darwin':
+        return Path.home() / '.cursor'
+    if platform.system() == 'Windows':
+        return Path.home() / 'AppData' / 'Roaming' / 'Cursor'
+    return Path.home() / '.config' / 'Cursor'
+
+
+def _load_cursor_mcp_config(config_path: Optional[Path] = None) -> Optional[dict]:
+    """Load and parse `~/.cursor/mcp.json`. Returns None if missing/invalid."""
+    path = config_path or (Path.home() / '.cursor' / _MCP_CONFIG_FILENAME)
+    if not path.exists():
+        logger.debug('Cursor MCP config file not found', extra={'path': str(path)})
+        return None
+    try:
+        return json.loads(path.read_text(encoding='utf-8'))
+    except Exception as e:
+        logger.debug('Failed to load Cursor MCP config file', exc_info=e)
+        return None
+
+
+class Cursor(IDE):
+    name: ClassVar[str] = 'cursor'
+    display_name: ClassVar[str] = 'Cursor'
+    hook_events: ClassVar[list[str]] = list(_CURSOR_EVENT_MAPPING)
+
+    def settings_path(self, scope: str, repo_path: Optional[Path] = None) -> Path:
+        if scope == 'repo' and repo_path:
+            return repo_path / _REPO_SUBDIR / _HOOKS_FILE_NAME
+        return _user_hooks_dir() / _HOOKS_FILE_NAME
+
+    def render_hooks_config(self, async_mode: bool = False) -> dict:
+        command = f'{_SCAN_COMMAND} &' if async_mode else _SCAN_COMMAND
+        hooks = {event: [{'command': command}] for event in self.hook_events}
+        hooks['sessionStart'] = [{'command': _SESSION_START_COMMAND}]
+        return {'version': 1, 'hooks': hooks}
+
+    def matches_payload(self, raw_payload: dict) -> bool:
+        return raw_payload.get('hook_event_name', '') in _CURSOR_EVENT_MAPPING
+
+    def parse_hook_payload(self, raw_payload: dict) -> AIHookPayload:
+        cursor_event_name = raw_payload.get('hook_event_name', '')
+        canonical_event = _CURSOR_EVENT_MAPPING.get(cursor_event_name, cursor_event_name)
+        return AIHookPayload(
+            event_name=canonical_event,
+            conversation_id=raw_payload.get('conversation_id'),
+            generation_id=raw_payload.get('generation_id'),
+            ide_user_email=raw_payload.get('user_email'),
+            model=raw_payload.get('model'),
+            ide_provider=self.name,
+            ide_version=raw_payload.get('cursor_version'),
+            prompt=raw_payload.get('prompt', ''),
+            file_path=raw_payload.get('file_path') or raw_payload.get('path'),
+            mcp_server_name=raw_payload.get('command'),
+            mcp_tool_name=raw_payload.get('tool_name') or raw_payload.get('tool'),
+            mcp_arguments=(raw_payload.get('arguments') or raw_payload.get('tool_input') or raw_payload.get('input')),
+        )
+
+    def build_hook_response(self, decision: HookDecision) -> dict:
+        if decision.event_type == AiHookEventType.PROMPT:
+            if decision.action == DecisionAction.ALLOW:
+                return {'continue': True}
+            return {'continue': False, 'user_message': decision.user_message or ''}
+
+        # FILE_READ / MCP_EXECUTION → permission shape
+        if decision.action == DecisionAction.ALLOW:
+            return {'permission': 'allow'}
+        return {
+            'permission': decision.action.value,  # 'deny' or 'ask'
+            'user_message': decision.user_message or '',
+            'agent_message': decision.agent_message or '',
+        }
+
+    def build_session_payload(self, raw_payload: dict) -> AIHookPayload:
+        return AIHookPayload(
+            conversation_id=raw_payload.get('conversation_id'),
+            ide_user_email=raw_payload.get('user_email'),
+            model=raw_payload.get('model'),
+            ide_provider=self.name,
+            ide_version=raw_payload.get('cursor_version'),
+        )
+
+    def get_session_context(self) -> tuple[dict, dict]:
+        config = _load_cursor_mcp_config()
+        mcp_servers = dict((config or {}).get('mcpServers') or {}) if config else {}
+        return mcp_servers, {}