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

cycode/cli/apps/ai_guardrails/install_command.py

@@ -5,14 +5,10 @@ from typing import Annotated, Optional
 
 import typer
 
-from cycode.cli.apps.ai_guardrails.command_utils import (
-    console,
-    resolve_repo_path,
-    validate_and_parse_ide,
-    validate_scope,
-)
-from cycode.cli.apps.ai_guardrails.consts import IDE_CONFIGS, AIIDEType, InstallMode, PolicyMode
+from cycode.cli.apps.ai_guardrails.command_utils import console, resolve_repo_path, validate_scope
+from cycode.cli.apps.ai_guardrails.consts import InstallMode, PolicyMode
 from cycode.cli.apps.ai_guardrails.hooks_manager import create_policy_file, install_hooks
+from cycode.cli.apps.ai_guardrails.ides import DEFAULT_IDE_NAME, IDES, resolve_ides
 
 
 def install_command(
@@ -29,9 +25,9 @@ def install_command(
         str,
         typer.Option(
             '--ide',
-            help='IDE to install hooks for (e.g., "cursor", "claude-code", or "all" for all IDEs). Defaults to cursor.',
+            help=f'IDE to install hooks for ({", ".join(IDES)}, or "all" for every supported IDE).',
         ),
-    ] = AIIDEType.CURSOR.value,
+    ] = DEFAULT_IDE_NAME,
     repo_path: Annotated[
         Optional[Path],
         typer.Option(
@@ -55,35 +51,30 @@ def install_command(
 ) -> None:
     """Install AI guardrails hooks for supported IDEs.
 
-    This command configures the specified IDE to use Cycode for scanning prompts, file reads,
-    and MCP tool calls for secrets before they are sent to AI models.
+    Configures the specified IDE to use Cycode for scanning prompts, file reads,
+    and MCP tool calls for secrets before they reach the AI model.
 
     Examples:
         cycode ai-guardrails install                    # Install in report mode (default)
         cycode ai-guardrails install --mode block       # Install in block mode
         cycode ai-guardrails install --scope repo       # Install for current repo only
-        cycode ai-guardrails install --ide cursor       # Install for Cursor IDE
-        cycode ai-guardrails install --ide all          # Install for all supported IDEs
-        cycode ai-guardrails install --scope repo --repo-path /path/to/repo
+        cycode ai-guardrails install --ide claude-code  # Install for a specific IDE
+        cycode ai-guardrails install --ide all          # Install for every supported IDE
     """
-    # Validate inputs
     validate_scope(scope)
     repo_path = resolve_repo_path(scope, repo_path)
-    ide_type = validate_and_parse_ide(ide)
+    ides_to_install = resolve_ides(ide)
 
-    ides_to_install: list[AIIDEType] = list(AIIDEType) if ide_type is None else [ide_type]
+    report_mode = mode == InstallMode.REPORT
 
     results: list[tuple[str, bool, str]] = []
     for current_ide in ides_to_install:
-        ide_name = IDE_CONFIGS[current_ide].name
-        report_mode = mode == InstallMode.REPORT
-        success, message = install_hooks(scope, repo_path, ide=current_ide, report_mode=report_mode)
-        results.append((ide_name, success, message))
+        success, message = install_hooks(current_ide, scope, repo_path, report_mode=report_mode)
+        results.append((current_ide.display_name, success, message))
 
-    # Report results for each IDE
     any_success = False
     all_success = True
-    for _ide_name, success, message in results:
+    for _name, success, message in results:
         if success:
             console.print(f'[green]✓[/] {message}')
             any_success = True

cycode/cli/apps/ai_guardrails/scan/handlers.py

@@ -1,8 +1,11 @@
-"""
-Hook handlers for AI IDE events.
+"""Hook handlers for AI IDE events.
+
+Each handler receives a unified payload and policy, applies the scan + policy
+logic, and returns a canonical ``HookDecision``. ``scan_command`` translates
+that decision into the IDE-specific JSON response via ``IDE.build_hook_response``.
 
-Each handler receives a unified payload from an IDE, applies policy rules,
-and returns a response that either allows or blocks the action.
+Handlers are agent-agnostic by design — adding a new IDE doesn't require
+touching any handler in this module.
 """
 
 import json
@@ -14,9 +17,9 @@ from typing import Callable, Optional
 import typer
 
 from cycode.cli.apps.ai_guardrails.consts import PolicyMode
+from cycode.cli.apps.ai_guardrails.ides.base import HookDecision
 from cycode.cli.apps.ai_guardrails.scan.payload import AIHookPayload
 from cycode.cli.apps.ai_guardrails.scan.policy import get_policy_value
-from cycode.cli.apps.ai_guardrails.scan.response_builders import get_response_builder
 from cycode.cli.apps.ai_guardrails.scan.types import AiHookEventType, AIHookOutcome, BlockReason
 from cycode.cli.apps.ai_guardrails.scan.utils import is_denied_path, truncate_utf8
 from cycode.cli.apps.scan.code_scanner import _get_scan_documents_thread_func
@@ -30,21 +33,17 @@ from cycode.logger import get_logger
 logger = get_logger('AI Guardrails')
 
 
-def handle_before_submit_prompt(ctx: typer.Context, payload: AIHookPayload, policy: dict) -> dict:
-    """
-    Handle beforeSubmitPrompt hook.
+HandlerFn = Callable[[typer.Context, AIHookPayload, dict], HookDecision]
 
-    Scans prompt text for secrets before it's sent to the AI model.
-    Returns {"continue": False} to block, {"continue": True} to allow.
-    """
+
+def handle_before_submit_prompt(ctx: typer.Context, payload: AIHookPayload, policy: dict) -> HookDecision:
+    """Scan prompt text for secrets before it's sent to the AI model."""
     ai_client = ctx.obj['ai_security_client']
-    ide = payload.ide_provider
-    response_builder = get_response_builder(ide)
 
     prompt_config = get_policy_value(policy, 'prompt', default={})
     if not get_policy_value(prompt_config, 'enabled', default=True):
         ai_client.create_event(payload, AiHookEventType.PROMPT, AIHookOutcome.ALLOWED)
-        return response_builder.allow_prompt()
+        return HookDecision.allow(AiHookEventType.PROMPT)
 
     mode = get_policy_value(policy, 'mode', default=PolicyMode.BLOCK)
     prompt = payload.prompt or ''
@@ -66,9 +65,9 @@ def handle_before_submit_prompt(ctx: typer.Context, payload: AIHookPayload, poli
             if action == PolicyMode.BLOCK and mode == PolicyMode.BLOCK:
                 outcome = AIHookOutcome.BLOCKED
                 user_message = f'{violation_summary}. Remove secrets before sending.'
-                return response_builder.deny_prompt(user_message)
+                return HookDecision.deny(AiHookEventType.PROMPT, user_message)
             outcome = AIHookOutcome.WARNED
-        return response_builder.allow_prompt()
+        return HookDecision.allow(AiHookEventType.PROMPT)
     except Exception as e:
         outcome = (
             AIHookOutcome.ALLOWED if get_policy_value(policy, 'fail_open', default=True) else AIHookOutcome.BLOCKED
@@ -87,21 +86,14 @@ def handle_before_submit_prompt(ctx: typer.Context, payload: AIHookPayload, poli
         )
 
 
-def handle_before_read_file(ctx: typer.Context, payload: AIHookPayload, policy: dict) -> dict:
-    """
-    Handle beforeReadFile hook.
-
-    Blocks sensitive files (via deny_globs) and scans file content for secrets.
-    Returns {"permission": "deny"} to block, {"permission": "allow"} to allow.
-    """
+def handle_before_read_file(ctx: typer.Context, payload: AIHookPayload, policy: dict) -> HookDecision:
+    """Block sensitive paths and scan file content for secrets."""
     ai_client = ctx.obj['ai_security_client']
-    ide = payload.ide_provider
-    response_builder = get_response_builder(ide)
 
     file_read_config = get_policy_value(policy, 'file_read', default={})
     if not get_policy_value(file_read_config, 'enabled', default=True):
         ai_client.create_event(payload, AiHookEventType.FILE_READ, AIHookOutcome.ALLOWED)
-        return response_builder.allow_permission()
+        return HookDecision.allow(AiHookEventType.FILE_READ)
 
     mode = get_policy_value(policy, 'mode', default=PolicyMode.BLOCK)
     file_path = payload.file_path or ''
@@ -113,20 +105,19 @@ def handle_before_read_file(ctx: typer.Context, payload: AIHookPayload, policy:
     error_message = None
 
     try:
-        # Check path-based denylist first
         is_sensitive_path = is_denied_path(file_path, policy)
         if is_sensitive_path:
             block_reason = BlockReason.SENSITIVE_PATH
             if mode == PolicyMode.BLOCK and action == PolicyMode.BLOCK:
                 outcome = AIHookOutcome.BLOCKED
                 user_message = f'Cycode blocked sending {file_path} to the AI (sensitive path policy).'
-                return response_builder.deny_permission(
+                return HookDecision.deny(
+                    AiHookEventType.FILE_READ,
                     user_message,
                     'This file path is classified as sensitive; do not read/send it to the model.',
                 )
-            # Warn mode - if content scan is enabled, emit a separate event for the
+            # Warn mode: if content scan is enabled, emit a separate event for the
             # sensitive path so the finally block can independently track the scan result.
-            # If content scan is disabled, a single event (from finally) is enough.
             outcome = AIHookOutcome.WARNED
             if get_policy_value(file_read_config, 'scan_content', default=True):
                 ai_client.create_event(
@@ -136,11 +127,9 @@ def handle_before_read_file(ctx: typer.Context, payload: AIHookPayload, policy:
                     block_reason=BlockReason.SENSITIVE_PATH,
                     file_path=payload.file_path,
                 )
-                # Reset for the content scan result tracked by the finally block
                 block_reason = None
                 outcome = AIHookOutcome.ALLOWED
 
-        # Scan file content if enabled
         if get_policy_value(file_read_config, 'scan_content', default=True):
             violation_summary, scan_id = _scan_path_for_secrets(ctx, file_path, policy)
             if violation_summary:
@@ -148,27 +137,28 @@ def handle_before_read_file(ctx: typer.Context, payload: AIHookPayload, policy:
                 if mode == PolicyMode.BLOCK and action == PolicyMode.BLOCK:
                     outcome = AIHookOutcome.BLOCKED
                     user_message = f'Cycode blocked reading {file_path}. {violation_summary}'
-                    return response_builder.deny_permission(
+                    return HookDecision.deny(
+                        AiHookEventType.FILE_READ,
                         user_message,
                         'Secrets detected; do not send this file to the model.',
                     )
-                # Warn mode - ask user for permission
                 outcome = AIHookOutcome.WARNED
                 user_message = f'Cycode detected secrets in {file_path}. {violation_summary}'
-                return response_builder.ask_permission(
+                return HookDecision.ask(
+                    AiHookEventType.FILE_READ,
                     user_message,
                     'Possible secrets detected; proceed with caution.',
                 )
 
-        # If path was sensitive but content scan found no secrets (or scan disabled), still warn
         if is_sensitive_path:
             user_message = f'Cycode flagged {file_path} as sensitive. Allow reading?'
-            return response_builder.ask_permission(
+            return HookDecision.ask(
+                AiHookEventType.FILE_READ,
                 user_message,
                 'This file path is classified as sensitive; proceed with caution.',
             )
 
-        return response_builder.allow_permission()
+        return HookDecision.allow(AiHookEventType.FILE_READ)
     except Exception as e:
         outcome = (
             AIHookOutcome.ALLOWED if get_policy_value(policy, 'fail_open', default=True) else AIHookOutcome.BLOCKED
@@ -188,22 +178,14 @@ def handle_before_read_file(ctx: typer.Context, payload: AIHookPayload, policy:
         )
 
 
-def handle_before_mcp_execution(ctx: typer.Context, payload: AIHookPayload, policy: dict) -> dict:
-    """
-    Handle beforeMCPExecution hook.
-
-    Scans tool arguments for secrets before MCP tool execution.
-    Returns {"permission": "deny"} to block, {"permission": "ask"} to warn,
-    {"permission": "allow"} to allow.
-    """
+def handle_before_mcp_execution(ctx: typer.Context, payload: AIHookPayload, policy: dict) -> HookDecision:
+    """Scan MCP tool arguments for secrets before execution."""
     ai_client = ctx.obj['ai_security_client']
-    ide = payload.ide_provider
-    response_builder = get_response_builder(ide)
 
     mcp_config = get_policy_value(policy, 'mcp', default={})
     if not get_policy_value(mcp_config, 'enabled', default=True):
         ai_client.create_event(payload, AiHookEventType.MCP_EXECUTION, AIHookOutcome.ALLOWED)
-        return response_builder.allow_permission()
+        return HookDecision.allow(AiHookEventType.MCP_EXECUTION)
 
     mode = get_policy_value(policy, 'mode', default=PolicyMode.BLOCK)
     tool = payload.mcp_tool_name or 'unknown'
@@ -227,17 +209,19 @@ def handle_before_mcp_execution(ctx: typer.Context, payload: AIHookPayload, poli
                 if mode == PolicyMode.BLOCK and action == PolicyMode.BLOCK:
                     outcome = AIHookOutcome.BLOCKED
                     user_message = f'Cycode blocked MCP tool call "{tool}". {violation_summary}'
-                    return response_builder.deny_permission(
+                    return HookDecision.deny(
+                        AiHookEventType.MCP_EXECUTION,
                         user_message,
                         'Do not pass secrets to tools. Use secret references (name/id) instead.',
                     )
                 outcome = AIHookOutcome.WARNED
-                return response_builder.ask_permission(
+                return HookDecision.ask(
+                    AiHookEventType.MCP_EXECUTION,
                     f'{violation_summary} in MCP tool call "{tool}". Allow execution?',
                     'Possible secrets detected in tool arguments; proceed with caution.',
                 )
 
-        return response_builder.allow_permission()
+        return HookDecision.allow(AiHookEventType.MCP_EXECUTION)
     except Exception as e:
         outcome = (
             AIHookOutcome.ALLOWED if get_policy_value(policy, 'fail_open', default=True) else AIHookOutcome.BLOCKED
@@ -256,16 +240,9 @@ def handle_before_mcp_execution(ctx: typer.Context, payload: AIHookPayload, poli
         )
 
 
-def get_handler_for_event(event_type: str) -> Optional[Callable[[typer.Context, AIHookPayload, dict], dict]]:
-    """Get the appropriate handler function for a canonical event type.
-
-    Args:
-        event_type: Canonical event type string (from AiHookEventType enum)
-
-    Returns:
-        Handler function or None if event type is not recognized
-    """
-    handlers = {
+def get_handler_for_event(event_type: str) -> Optional[HandlerFn]:
+    """Look up the handler for a canonical event type."""
+    handlers: dict[str, HandlerFn] = {
         AiHookEventType.PROMPT.value: handle_before_submit_prompt,
         AiHookEventType.FILE_READ.value: handle_before_read_file,
         AiHookEventType.MCP_EXECUTION.value: handle_before_mcp_execution,
@@ -275,32 +252,24 @@ def get_handler_for_event(event_type: str) -> Optional[Callable[[typer.Context,
 
 def _setup_scan_context(ctx: typer.Context) -> typer.Context:
     """Set up minimal context for scan_documents without progress bars or printing."""
-
-    # Set up minimal required context
     ctx.obj['progress_bar'] = DummyProgressBar([ScanProgressBarSection])
-    ctx.obj['sync'] = True  # Synchronous scan
-    ctx.obj['scan_type'] = ScanTypeOption.SECRET  # AI guardrails always scans for secrets
-    ctx.obj['severity_threshold'] = SeverityOption.INFO  # Report all severities
-
-    # Set command name for scan logic
+    ctx.obj['sync'] = True
+    ctx.obj['scan_type'] = ScanTypeOption.SECRET
+    ctx.obj['severity_threshold'] = SeverityOption.INFO
     ctx.info_name = 'ai_guardrails'
-
     return ctx
 
 
 def _perform_scan(
     ctx: typer.Context, documents: list[Document], scan_parameters: dict, timeout_seconds: float
 ) -> tuple[Optional[str], Optional[str]]:
-    """
-    Perform a scan on documents and extract results.
+    """Run a scan on documents, returning (violation_summary, scan_id).
 
-    Returns tuple of (violation_summary, scan_id) if secrets found, (None, scan_id) if clean.
-    Raises exception if scan fails or times out (triggers fail_open policy).
+    Raises on scan failure / timeout so the fail-open policy can take over.
     """
     if not documents:
         return None, None
 
-    # Get the thread function for scanning
     scan_batch_thread_func = _get_scan_documents_thread_func(
         ctx, is_git_diff=False, is_commit_range=False, scan_parameters=scan_parameters
     )
@@ -324,7 +293,6 @@ def _perform_scan(
 
     scan_id = local_scan_result.scan_id
 
-    # Check if there are any detections
     if local_scan_result.detections_count > 0:
         violation_summary = build_violation_summary([local_scan_result])
         return violation_summary, scan_id
@@ -333,12 +301,7 @@ def _perform_scan(
 
 
 def _scan_text_for_secrets(ctx: typer.Context, text: str, timeout_ms: int) -> tuple[Optional[str], Optional[str]]:
-    """
-    Scan text content for secrets using Cycode CLI.
-
-    Returns tuple of (violation_summary, scan_id) if secrets found, (None, scan_id) if clean.
-    Raises exception on error or timeout.
-    """
+    """Scan text content for secrets using Cycode CLI."""
     if not text:
         return None, None
 
@@ -349,12 +312,7 @@ def _scan_text_for_secrets(ctx: typer.Context, text: str, timeout_ms: int) -> tu
 
 
 def _scan_path_for_secrets(ctx: typer.Context, file_path: str, policy: dict) -> tuple[Optional[str], Optional[str]]:
-    """
-    Scan a file path for secrets.
-
-    Returns tuple of (violation_summary, scan_id) if secrets found, (None, scan_id) if clean.
-    Raises exception on error or timeout.
-    """
+    """Scan a file path for secrets."""
     if not file_path or not os.path.isfile(file_path):
         return None, None
 
@@ -363,7 +321,6 @@ def _scan_path_for_secrets(ctx: typer.Context, file_path: str, policy: dict) ->
     with open(file_path, encoding='utf-8', errors='replace') as f:
         content = f.read(max_bytes)
 
-    # Get timeout from policy
     timeout_ms = get_policy_value(policy, 'secrets', 'timeout_ms', default=30000)
     timeout_seconds = timeout_ms / 1000.0
 

cycode/cli/apps/ai_guardrails/scan/payload.py

@@ -1,275 +1,34 @@
-"""Unified payload object for AI hook events from different tools."""
+"""Canonical AI hook payload shared across IDE integrations.
+
+The dataclass is populated by `IDE.parse_hook_payload` (see
+`cycode/cli/apps/ai_guardrails/ides/`). Per-IDE parsing logic lives on the
+respective IDE class.
+"""
 
-import json
-from collections.abc import Iterator
 from dataclasses import dataclass
-from pathlib import Path
 from typing import Optional
 
-from cycode.cli.apps.ai_guardrails.consts import AIIDEType
-from cycode.cli.apps.ai_guardrails.scan.claude_config import get_user_email, load_claude_config
-from cycode.cli.apps.ai_guardrails.scan.types import (
-    CLAUDE_CODE_EVENT_MAPPING,
-    CLAUDE_CODE_EVENT_NAMES,
-    CURSOR_EVENT_MAPPING,
-    CURSOR_EVENT_NAMES,
-    AiHookEventType,
-)
-
-
-def _reverse_readline(path: Path, buf_size: int = 8192) -> Iterator[str]:
-    """Read a file line by line from the end without loading entire file into memory.
-
-    Yields lines in reverse order (last line first).
-    """
-    with path.open('rb') as f:
-        f.seek(0, 2)  # Seek to end
-        file_size = f.tell()
-        if file_size == 0:
-            return
-
-        remaining = file_size
-        buffer = b''
-
-        while remaining > 0:
-            # Read a chunk from the end
-            read_size = min(buf_size, remaining)
-            remaining -= read_size
-            f.seek(remaining)
-            chunk = f.read(read_size)
-            buffer = chunk + buffer
-
-            # Yield complete lines from buffer
-            while b'\n' in buffer:
-                # Find the last newline
-                newline_pos = buffer.rfind(b'\n')
-                if newline_pos == len(buffer) - 1:
-                    # Trailing newline, look for previous one
-                    newline_pos = buffer.rfind(b'\n', 0, newline_pos)
-                    if newline_pos == -1:
-                        break
-                # Yield the line after this newline
-                line = buffer[newline_pos + 1 :]
-                buffer = buffer[: newline_pos + 1]
-                if line.strip():
-                    yield line.decode('utf-8', errors='replace')
-
-        # Yield any remaining content as the first line of the file
-        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, and latest generation ID from Claude Code transcript file.
-
-    The transcript is a JSONL file where each line is a JSON object.
-    We look for 'version' (IDE version), 'model', and 'uuid' (generation ID) fields.
-    The generation_id is the UUID of the latest 'user' type message.
-
-    Scans from end to start since latest entries are at the end.
-    Uses reverse reading to avoid loading entire file into memory.
-
-    Returns:
-        Tuple of (ide_version, model, generation_id), any may be 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
-
 
 @dataclass
 class AIHookPayload:
-    """Unified payload object that normalizes field names from different AI tools."""
+    """Unified payload that normalizes field names across IDEs."""
 
     # Event identification
-    event_name: Optional[str] = None  # Canonical event type (e.g., 'prompt', 'file_read', 'mcp_execution')
+    event_name: Optional[str] = None  # Canonical event type from AiHookEventType
     conversation_id: Optional[str] = None
     generation_id: Optional[str] = None
 
     # User and IDE information
     ide_user_email: Optional[str] = None
     model: Optional[str] = None
-    ide_provider: str = None  # AIIDEType value (e.g., 'cursor', 'claude-code')
+    ide_provider: Optional[str] = None  # Matches IDE.name (e.g. 'cursor', 'claude-code')
     ide_version: Optional[str] = None
 
     source: Optional[str] = None
 
     # Event-specific data
-    prompt: Optional[str] = None  # For prompt events
-    file_path: Optional[str] = None  # For file_read events
-    mcp_server_name: Optional[str] = None  # For mcp_execution events
-    mcp_tool_name: Optional[str] = None  # For mcp_execution events
-    mcp_arguments: Optional[dict] = None  # For mcp_execution events
-
-    @classmethod
-    def from_cursor_payload(cls, payload: dict) -> 'AIHookPayload':
-        """Create AIHookPayload from Cursor IDE payload.
-
-        Maps Cursor-specific event names to canonical event types.
-        """
-        cursor_event_name = payload.get('hook_event_name', '')
-        # Map Cursor event name to canonical type, fallback to original if not found
-        canonical_event = CURSOR_EVENT_MAPPING.get(cursor_event_name, cursor_event_name)
-
-        return cls(
-            event_name=canonical_event,
-            conversation_id=payload.get('conversation_id'),
-            generation_id=payload.get('generation_id'),
-            ide_user_email=payload.get('user_email'),
-            model=payload.get('model'),
-            ide_provider=AIIDEType.CURSOR.value,
-            ide_version=payload.get('cursor_version'),
-            prompt=payload.get('prompt', ''),
-            file_path=payload.get('file_path') or payload.get('path'),
-            mcp_server_name=payload.get('command'),  # MCP server name
-            mcp_tool_name=payload.get('tool_name') or payload.get('tool'),
-            mcp_arguments=payload.get('arguments') or payload.get('tool_input') or payload.get('input'),
-        )
-
-    @classmethod
-    def from_claude_code_payload(cls, payload: dict) -> 'AIHookPayload':
-        """Create AIHookPayload from Claude Code IDE payload.
-
-        Claude Code has a different structure:
-        - hook_event_name: 'UserPromptSubmit' or 'PreToolUse'
-        - For PreToolUse: tool_name determines if it's file read ('Read') or MCP ('mcp__*')
-        - tool_input contains tool arguments (e.g., file_path for Read tool)
-        - transcript_path points to JSONL file with version and model info
-        """
-        hook_event_name = payload.get('hook_event_name', '')
-        tool_name = payload.get('tool_name', '')
-        tool_input = payload.get('tool_input')
-
-        if hook_event_name == 'UserPromptSubmit':
-            canonical_event = AiHookEventType.PROMPT
-        elif hook_event_name == 'PreToolUse':
-            canonical_event = AiHookEventType.FILE_READ if tool_name == 'Read' else AiHookEventType.MCP_EXECUTION
-        else:
-            # Unknown event, use the raw event name
-            canonical_event = CLAUDE_CODE_EVENT_MAPPING.get(hook_event_name, hook_event_name)
-
-        # Extract file_path from tool_input for 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
-
-        # Extract MCP server and tool name from 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]
-
-        # Extract IDE version, model, and generation ID from transcript file
-        ide_version, model, generation_id = extract_from_claude_transcript(payload.get('transcript_path'))
-
-        # Extract user email from ~/.claude.json
-        claude_config = load_claude_config()
-        ide_user_email = get_user_email(claude_config) if claude_config else None
-
-        return cls(
-            event_name=canonical_event,
-            conversation_id=payload.get('session_id'),
-            generation_id=generation_id,
-            ide_user_email=ide_user_email,
-            model=model,
-            ide_provider=AIIDEType.CLAUDE_CODE.value,
-            ide_version=ide_version,
-            prompt=payload.get('prompt', ''),
-            file_path=file_path,
-            mcp_server_name=mcp_server_name,
-            mcp_tool_name=mcp_tool_name,
-            mcp_arguments=mcp_arguments,
-        )
-
-    @staticmethod
-    def is_payload_for_ide(payload: dict, ide: str) -> bool:
-        """Check if the payload's event name matches the expected IDE.
-
-        This prevents double-processing when Cursor reads Claude Code hooks
-        or vice versa. If the payload's hook_event_name doesn't match the
-        expected IDE's event names, we should skip processing.
-
-        Args:
-            payload: The raw payload from the IDE
-            ide: The IDE name or AIIDEType enum value
-
-        Returns:
-            True if the payload matches the IDE, False otherwise.
-        """
-        hook_event_name = payload.get('hook_event_name', '')
-
-        if ide == AIIDEType.CLAUDE_CODE:
-            return hook_event_name in CLAUDE_CODE_EVENT_NAMES
-        if ide == AIIDEType.CURSOR:
-            return hook_event_name in CURSOR_EVENT_NAMES
-
-        # Unknown IDE, allow processing
-        return True
-
-    @classmethod
-    def from_payload(cls, payload: dict, tool: str = AIIDEType.CURSOR.value) -> 'AIHookPayload':
-        """Create AIHookPayload from any tool's payload.
-
-        Args:
-            payload: The raw payload from the IDE
-            tool: The IDE/tool name or AIIDEType enum value
-
-        Returns:
-            AIHookPayload instance
-
-        Raises:
-            ValueError: If the tool is not supported
-        """
-        if tool == AIIDEType.CURSOR:
-            return cls.from_cursor_payload(payload)
-        if tool == AIIDEType.CLAUDE_CODE:
-            return cls.from_claude_code_payload(payload)
-        raise ValueError(f'Unsupported IDE/tool: {tool}')
+    prompt: Optional[str] = None  # PROMPT events
+    file_path: Optional[str] = None  # FILE_READ events
+    mcp_server_name: Optional[str] = None  # MCP_EXECUTION events
+    mcp_tool_name: Optional[str] = None
+    mcp_arguments: Optional[dict] = None