cycode 3.15.4.dev1__py3-none-any.whl → 3.15.4.dev2__py3-none-any.whl

cycode/__init__.py

@@ -1 +1 @@
-__version__ = '3.15.4.dev1'  # DON'T TOUCH. Placeholder. Will be filled automatically on poetry build from Git Tag
+__version__ = '3.15.4.dev2'  # DON'T TOUCH. Placeholder. Will be filled automatically on poetry build from Git Tag

cycode/cli/apps/ai_guardrails/hooks_manager.py

@@ -28,7 +28,7 @@ def _is_cycode_command(command: str) -> bool:
 
 
 def is_cycode_hook_entry(entry: dict) -> bool:
-    """Detect Cycode hook entries in both Cursor (flat) and Claude Code (nested) shapes."""
+    """True if any hook inside ``entry`` is owned by Cycode."""
     command = entry.get('command', '')
     if _is_cycode_command(command):
         return True
@@ -40,6 +40,31 @@ def is_cycode_hook_entry(entry: dict) -> bool:
     return False
 
 
+def _strip_cycode_from_entry(entry: dict) -> Optional[dict]:
+    """Remove Cycode hooks from ``entry`` and return the remainder.
+
+    Returns ``None`` when nothing useful remains (Cursor-flat Cycode entry, or
+    every nested hook was Cycode). Non-Cycode hooks co-located in the same
+    entry are preserved.
+    """
+    # Cursor format: the entry itself IS a single hook command.
+    if 'command' in entry and 'hooks' not in entry:
+        return None if _is_cycode_command(entry.get('command', '')) else entry
+
+    # Claude Code / Codex format: nested `hooks` list inside the entry.
+    nested = entry.get('hooks')
+    if isinstance(nested, list):
+        kept = [h for h in nested if not (isinstance(h, dict) and _is_cycode_command(h.get('command', '')))]
+        if not kept:
+            return None
+        if len(kept) == len(nested):
+            return entry  # nothing Cycode-shaped inside; preserve identity
+        return {**entry, 'hooks': kept}
+
+    # Entry has neither shape we recognize — leave it alone defensively.
+    return entry
+
+
 def _load_hooks_file(hooks_path: Path) -> Optional[dict]:
     if not hooks_path.exists():
         return None
@@ -108,50 +133,83 @@ def install_hooks(
 
     for event, entries in rendered['hooks'].items():
         existing['hooks'].setdefault(event, [])
-
-        # Remove any existing Cycode entries for this event
-        existing['hooks'][event] = [e for e in existing['hooks'][event] if not is_cycode_hook_entry(e)]
-
-        # Add new Cycode entries
+        existing['hooks'][event] = [
+            stripped for e in existing['hooks'][event] if (stripped := _strip_cycode_from_entry(e)) is not None
+        ]
         for entry in entries:
             existing['hooks'][event].append(entry)
 
-    if _save_hooks_file(hooks_path, existing):
-        return True, f'AI guardrails hooks installed: {hooks_path}'
-    return False, f'Failed to install hooks to {hooks_path}'
+    if not _save_hooks_file(hooks_path, existing):
+        return False, f'Failed to install hooks to {hooks_path}'
 
+    message = f'AI guardrails hooks installed: {hooks_path}'
 
-def uninstall_hooks(ide: IDE, scope: str = 'user', repo_path: Optional[Path] = None) -> tuple[bool, str]:
-    """Remove Cycode AI guardrails hooks for ``ide``."""
-    hooks_path = ide.settings_path(scope, repo_path)
+    # IDE-specific extras (e.g. Codex enables a TOML feature flag).
+    extra_ok, extra_message = ide.post_install(scope, repo_path)
+    if not extra_ok:
+        return False, extra_message
+    if extra_message:
+        message = f'{message}\n  {extra_message}'
 
-    existing = _load_hooks_file(hooks_path)
-    if existing is None:
-        return True, f'No hooks file found at {hooks_path}'
+    return True, message
 
+
+def _strip_cycode_entries(existing: dict) -> bool:
+    """Mutate ``existing`` to drop Cycode hooks (surgically). Return True if anything changed."""
     modified = False
     for event in list(existing.get('hooks', {}).keys()):
-        original_count = len(existing['hooks'][event])
-        existing['hooks'][event] = [e for e in existing['hooks'][event] if not is_cycode_hook_entry(e)]
-        if len(existing['hooks'][event]) != original_count:
-            modified = True
-        if not existing['hooks'][event]:
+        before = existing['hooks'][event]
+        after: list = []
+        for e in before:
+            stripped = _strip_cycode_from_entry(e)
+            if stripped is None:
+                modified = True
+                continue
+            if stripped is not e:
+                modified = True
+            after.append(stripped)
+        if not after:
             del existing['hooks'][event]
+        else:
+            existing['hooks'][event] = after
+    return modified
 
+
+def _persist_uninstall(hooks_path: Path, existing: dict, modified: bool) -> tuple[bool, str]:
+    """Apply the uninstall result to disk and return ``(success, message)``."""
     if not modified:
         return True, 'No Cycode hooks found to remove'
-
     if not existing.get('hooks'):
         try:
             hooks_path.unlink()
-            return True, f'Removed hooks file: {hooks_path}'
         except Exception as e:
             logger.debug('Failed to delete hooks file', exc_info=e)
             return False, f'Failed to remove hooks file: {hooks_path}'
+        return True, f'Removed hooks file: {hooks_path}'
+    if not _save_hooks_file(hooks_path, existing):
+        return False, f'Failed to update hooks file: {hooks_path}'
+    return True, f'Cycode hooks removed from: {hooks_path}'
+
+
+def uninstall_hooks(ide: IDE, scope: str = 'user', repo_path: Optional[Path] = None) -> tuple[bool, str]:
+    """Remove Cycode AI guardrails hooks for ``ide``."""
+    hooks_path = ide.settings_path(scope, repo_path)
+
+    existing = _load_hooks_file(hooks_path)
+    if existing is None:
+        return True, f'No hooks file found at {hooks_path}'
 
-    if _save_hooks_file(hooks_path, existing):
-        return True, f'Cycode hooks removed from: {hooks_path}'
-    return False, f'Failed to update hooks file: {hooks_path}'
+    modified = _strip_cycode_entries(existing)
+    file_ok, message = _persist_uninstall(hooks_path, existing, modified)
+    if not file_ok:
+        return False, message
+
+    extra_ok, extra_message = ide.post_uninstall(scope, repo_path)
+    if not extra_ok:
+        return False, extra_message
+    if extra_message:
+        message = f'{message}\n  {extra_message}'
+    return True, message
 
 
 def get_hooks_status(ide: IDE, scope: str = 'user', repo_path: Optional[Path] = None) -> dict:

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

@@ -9,11 +9,12 @@ import typer
 
 from cycode.cli.apps.ai_guardrails.ides.base import IDE
 from cycode.cli.apps.ai_guardrails.ides.claude_code import ClaudeCode
+from cycode.cli.apps.ai_guardrails.ides.codex import Codex
 from cycode.cli.apps.ai_guardrails.ides.cursor import Cursor
 
 # Single source of truth: name → singleton instance.
 # `--ide` choices and install/uninstall/status iteration both derive from this.
-IDES: dict[str, IDE] = {ide.name: ide for ide in (Cursor(), ClaudeCode())}
+IDES: dict[str, IDE] = {ide.name: ide for ide in (Cursor(), ClaudeCode(), Codex())}
 
 # Default IDE used when `--ide` is omitted. Kept here so the value is colocated
 # with the registry; no module outside `ides/` needs to know which IDE wins.

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

@@ -0,0 +1,73 @@
+"""Shared plugin-resolution helpers for IDE integrations.
+
+Both Claude Code and Codex use the same ``<plugin>@<marketplace>`` key convention
+and emit the same telemetry shape — only the marketplace layout and manifest
+location differ. ``walk_enabled_plugins`` is the IDE-agnostic loop; each IDE
+supplies the two callables that vary (``locate_dir`` + ``read_plugin``).
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+from cycode.logger import get_logger
+
+logger = get_logger('AI Guardrails Plugins')
+
+
+def load_plugin_json(path: Path) -> Optional[dict]:
+    """Load a JSON file inside a plugin directory; None if missing or invalid."""
+    if not path.exists():
+        return None
+    try:
+        return json.loads(path.read_text(encoding='utf-8'))
+    except Exception as e:
+        logger.debug('Failed to load plugin file, %s', {'path': str(path)}, exc_info=e)
+        return None
+
+
+def walk_enabled_plugins(
+    plugin_entries: dict[str, Any],
+    is_enabled: Callable[[Any], bool],
+    locate_dir: Callable[[str, str], Optional[Path]],
+    read_plugin: Callable[[Path], tuple[dict, dict]],
+) -> tuple[dict, dict]:
+    """Iterate enabled plugins; merge their MCP servers and metadata.
+
+    Args:
+        plugin_entries: ``{<plugin>@<marketplace>: settings}`` map from the IDE config.
+        is_enabled: returns True if ``settings`` indicates the plugin is on
+            (e.g. ``bool(settings)`` for Claude, ``settings.get('enabled')`` for Codex).
+        locate_dir: given ``(plugin_name, marketplace)``, returns the plugin's
+            filesystem path or None if it can't be resolved.
+        read_plugin: given the plugin path, returns ``(entry_fields, servers)``:
+            ``entry_fields`` are extra metadata to attach to the inventory entry
+            (name/version/description/...), ``servers`` are MCP servers contributed.
+
+    Returns ``(merged_mcp_servers, enriched_plugins)``. Plugin keys without
+    ``@`` (or that fail to resolve to a directory) still appear in the
+    inventory with just ``{'enabled': True}`` so we don't silently drop them.
+    """
+    merged_mcp: dict = {}
+    enriched: dict = {}
+
+    for plugin_key, settings in plugin_entries.items():
+        if not is_enabled(settings):
+            continue
+
+        entry: dict = {'enabled': True}
+        enriched[plugin_key] = entry
+
+        if '@' not in plugin_key:
+            continue
+        plugin_name, marketplace = plugin_key.split('@', 1)
+
+        plugin_dir = locate_dir(plugin_name, marketplace)
+        if plugin_dir is None:
+            continue
+
+        plugin_fields, servers = read_plugin(plugin_dir)
+        entry.update(plugin_fields)
+        merged_mcp.update(servers)
+
+    return merged_mcp, enriched

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

@@ -108,6 +108,26 @@ class IDE(ABC):
         ``hooks_manager`` can treat them uniformly.
         """
 
+    def post_install(self, scope: str, repo_path: Optional[Path] = None) -> tuple[bool, str]:
+        """Run IDE-specific actions after the hooks file is written.
+
+        Default: no-op success. Override to perform extra setup that doesn't
+        belong in the hooks file itself — e.g. Codex enables a
+        ``[features] codex_hooks = true`` flag in its TOML config.
+
+        Returns ``(success, message)``. If ``success`` is False, the overall
+        install is considered failed.
+        """
+        return True, ''
+
+    def post_uninstall(self, scope: str, repo_path: Optional[Path] = None) -> tuple[bool, str]:
+        """Run IDE-specific cleanup after the hooks file is removed.
+
+        Default: no-op success. Override to undo whatever ``post_install``
+        wrote outside the hooks file.
+        """
+        return True, ''
+
     # --- runtime scan ---
 
     @abstractmethod

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

@@ -7,6 +7,7 @@ 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._plugin_utils import load_plugin_json, walk_enabled_plugins
 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
@@ -127,7 +128,7 @@ 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)})
+        logger.debug('Claude config file not found, %s', {'path': str(path)})
         return None
     try:
         return json.loads(path.read_text(encoding='utf-8'))
@@ -150,7 +151,7 @@ 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)})
+        logger.debug('Claude settings file not found, %s', {'path': str(path)})
         return None
     try:
         return json.loads(path.read_text(encoding='utf-8'))
@@ -171,69 +172,47 @@ def _resolve_marketplace_path(marketplace: dict) -> Optional[Path]:
     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.
+def _read_claude_plugin(plugin_dir: Path) -> tuple[dict, dict]:
+    """Read one Claude Code plugin's manifest + MCP servers.
 
-    Returns None if the file is missing, unreadable, or has invalid JSON.
+    Claude hardcodes the MCP file at ``<plugin_dir>/.mcp.json`` and always
+    wraps it as ``{"mcpServers": {...}}``.
     """
-    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
+    manifest = load_plugin_json(plugin_dir / '.claude-plugin' / 'plugin.json') or {}
+    entry: dict = {}
+    for field in ('name', 'version', 'description'):
+        if field in manifest:
+            entry[field] = manifest[field]
 
+    mcp_config = load_plugin_json(plugin_dir / '.mcp.json') or {}
+    servers: dict = mcp_config.get('mcpServers') or {}
+    if servers:
+        entry['mcp_server_names'] = list(servers.keys())
+    return entry, servers
 
-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)
+def resolve_plugins(settings: dict) -> tuple[dict, dict]:
+    """Walk Claude Code's ``enabledPlugins`` via the shared plugin walker.
 
-    Returns ``(merged_mcp_servers, enriched_plugins)``.
+    Each enabled plugin's marketplace is resolved through
+    ``extraKnownMarketplaces`` to a directory; the rest of the work
+    (manifest + ``.mcp.json``) is the shared ``_read_claude_plugin``.
     """
     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)
+    def _locate(_plugin_name: str, marketplace_name: str) -> Optional[Path]:
         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 None
+        return _resolve_marketplace_path(marketplace)
 
-    return merged_mcp, enriched
+    return walk_enabled_plugins(
+        plugin_entries=enabled,
+        is_enabled=bool,
+        locate_dir=_locate,
+        read_plugin=_read_claude_plugin,
+    )
 
 
 # --- IDE integration ----------------------------------------------------------
@@ -260,6 +239,7 @@ class ClaudeCode(IDE):
             'hooks': {
                 'SessionStart': [
                     {
+                        'matcher': 'startup|clear',
                         'hooks': [{'type': 'command', 'command': _SESSION_START_COMMAND}],
                     }
                 ],

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

@@ -0,0 +1,310 @@
+"""Codex CLI IDE integration for AI guardrails."""
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import ClassVar, Optional
+
+import tomli_w
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover - py<3.11 fallback
+    import tomli as tomllib
+
+from cycode.cli.apps.ai_guardrails.consts import CYCODE_SCAN_PROMPT_COMMAND, CYCODE_SESSION_START_COMMAND
+from cycode.cli.apps.ai_guardrails.ides._plugin_utils import load_plugin_json, walk_enabled_plugins
+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.cli.utils.jwt_utils import decode_jwt_unverified
+from cycode.logger import get_logger
+
+logger = get_logger('AI Guardrails Codex')
+
+_CONFIG_DIR_NAME = '.codex'
+_HOOKS_FILE_NAME = 'hooks.json'
+_CONFIG_TOML_NAME = 'config.toml'
+_AUTH_JSON_NAME = 'auth.json'
+_CODEX_HOME_ENV_VAR = 'CODEX_HOME'
+
+_HOOK_EVENTS = ('UserPromptSubmit', 'PreToolUse:mcp')
+_CODEX_EVENT_NAMES = frozenset(e.split(':', 1)[0] for e in _HOOK_EVENTS)
+
+_SCAN_COMMAND = f'{CYCODE_SCAN_PROMPT_COMMAND} --ide codex'
+_SESSION_START_COMMAND = f'{CYCODE_SESSION_START_COMMAND} --ide codex'
+
+
+def _codex_home() -> Path:
+    """Resolve Codex's user-scope home directory.
+
+    Honors ``$CODEX_HOME`` per Codex's documented override; falls back to
+    ``~/.codex``.
+    """
+    override = os.environ.get(_CODEX_HOME_ENV_VAR)
+    if override:
+        return Path(override)
+    return Path.home() / _CONFIG_DIR_NAME
+
+
+def _codex_config_toml_path(scope: str, repo_path: Optional[Path] = None) -> Path:
+    """Return the Codex ``config.toml`` path for the given scope."""
+    if scope == 'repo' and repo_path:
+        return repo_path / _CONFIG_DIR_NAME / _CONFIG_TOML_NAME
+    return _codex_home() / _CONFIG_TOML_NAME
+
+
+def _load_codex_config(config_path: Optional[Path] = None) -> Optional[dict]:
+    """Load and parse Codex's ``config.toml``. Returns None on missing/invalid."""
+    path = config_path or (_codex_home() / _CONFIG_TOML_NAME)
+    if not path.exists():
+        logger.debug('Codex config file not found, %s', {'path': str(path)})
+        return None
+    try:
+        with path.open('rb') as f:
+            return tomllib.load(f)
+    except Exception as e:
+        logger.debug('Failed to load Codex config file, %s', {'path': str(path)}, exc_info=e)
+        return None
+
+
+def _email_from_auth(auth_path: Optional[Path] = None) -> Optional[str]:
+    """Best-effort extraction of the signed-in Codex user's email.
+
+    Reads ``~/.codex/auth.json`` and decodes the JWT in ``tokens.id_token``
+    to pull the ``email`` claim. Returns None if auth.json is missing
+    (``OPENAI_API_KEY``-only setups, OS keychain credentials) or unreadable.
+    """
+    path = auth_path or (_codex_home() / _AUTH_JSON_NAME)
+    if not path.exists():
+        logger.debug('Codex auth file not found, %s', {'path': str(path)})
+        return None
+    try:
+        auth = json.loads(path.read_text(encoding='utf-8'))
+    except (OSError, json.JSONDecodeError) as e:
+        logger.debug('Failed to load Codex auth file, %s', {'path': str(path)}, exc_info=e)
+        return None
+
+    token = (auth.get('tokens') or {}).get('id_token')
+    if not token:
+        return None
+    claims = decode_jwt_unverified(token)
+    if not claims:
+        return None
+    return claims.get('email')
+
+
+def _resolve_codex_plugin_dir(plugin_name: str, marketplace: str) -> Optional[Path]:
+    """Find ``~/.codex/plugins/cache/<marketplace>/<plugin>/<hash>/``.
+
+    The trailing segment is a content hash. If multiple are cached, pick the
+    most recently modified.
+    """
+    base = _codex_home() / 'plugins' / 'cache' / marketplace / plugin_name
+    if not base.is_dir():
+        return None
+    candidates = [d for d in base.iterdir() if d.is_dir()]
+    if not candidates:
+        return None
+    return max(candidates, key=lambda d: d.stat().st_mtime)
+
+
+def _read_codex_plugin(plugin_dir: Path) -> tuple[dict, dict]:
+    """Read one Codex plugin's manifest + MCP servers.
+
+    Codex's manifest references the MCP file via a path string in the
+    ``mcpServers`` field (default ``./.mcp.json``); the target file is either
+    a bare ``{name: cfg}`` map or wrapped in ``{"mcpServers": {...}}``.
+    """
+    manifest = load_plugin_json(plugin_dir / '.codex-plugin' / 'plugin.json')
+    entry: dict = {}
+    if not manifest:
+        return entry, {}
+
+    for field in ('name', 'version', 'description'):
+        if field in manifest:
+            entry[field] = manifest[field]
+
+    mcp_ref = manifest.get('mcpServers')
+    if not mcp_ref:
+        return entry, {}
+    mcp_doc = load_plugin_json(plugin_dir / mcp_ref) or {}
+    servers = mcp_doc.get('mcpServers', mcp_doc)
+    if not isinstance(servers, dict):
+        servers = {}
+    if servers:
+        entry['mcp_server_names'] = list(servers.keys())
+    return entry, servers
+
+
+def _resolve_codex_plugins(config: dict) -> tuple[dict, dict]:
+    """Walk enabled ``[plugins."<plugin>@<marketplace>"]`` entries."""
+    return walk_enabled_plugins(
+        plugin_entries=config.get('plugins') or {},
+        is_enabled=lambda s: isinstance(s, dict) and bool(s.get('enabled')),
+        locate_dir=_resolve_codex_plugin_dir,
+        read_plugin=_read_codex_plugin,
+    )
+
+
+def _enable_codex_hooks_feature(scope: str, repo_path: Optional[Path] = None) -> tuple[bool, str]:
+    """Set ``[features] hooks = true`` in Codex's ``config.toml``.
+
+    Codex's hook scripts are gated behind this feature flag. We preserve any
+    existing keys and create the file (+ parent dir) when missing.
+    """
+    config_path = _codex_config_toml_path(scope, repo_path)
+
+    config: dict = {}
+    if config_path.exists():
+        try:
+            with config_path.open('rb') as f:
+                config = tomllib.load(f)
+        except Exception as e:
+            logger.error('Failed to parse Codex config.toml, %s', {'path': str(config_path)}, exc_info=e)
+            return False, f'Failed to parse existing Codex config at {config_path}'
+
+    features = config.get('features')
+    if not isinstance(features, dict):
+        features = {}
+    features['hooks'] = True
+    config['features'] = features
+
+    try:
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        with config_path.open('wb') as f:
+            tomli_w.dump(config, f)
+        return True, f'Enabled hooks feature in {config_path}'
+    except Exception as e:
+        logger.error('Failed to write Codex config.toml, %s', {'path': str(config_path)}, exc_info=e)
+        return False, f'Failed to write Codex config at {config_path}'
+
+
+class Codex(IDE):
+    name: ClassVar[str] = 'codex'
+    display_name: ClassVar[str] = 'Codex'
+    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 / _CONFIG_DIR_NAME / _HOOKS_FILE_NAME
+        return _codex_home() / _HOOKS_FILE_NAME
+
+    def render_hooks_config(self, async_mode: bool = False) -> dict:
+        # Codex's TOML `async: true` flag is unimplemented; shell-background via
+        # `&` is the working mechanism. SessionStart stays sync so the
+        # conversation context is registered before any scan hook fires.
+        bg = ' &' if async_mode else ''
+        scan_cmd = f'{_SCAN_COMMAND}{bg}'
+        return {
+            'hooks': {
+                'SessionStart': [
+                    {
+                        'matcher': 'startup|clear',
+                        'hooks': [{'type': 'command', 'command': _SESSION_START_COMMAND}],
+                    }
+                ],
+                'UserPromptSubmit': [
+                    {
+                        'hooks': [{'type': 'command', 'command': scan_cmd}],
+                    }
+                ],
+                'PreToolUse': [
+                    {
+                        'matcher': 'mcp__.*',
+                        'hooks': [{'type': 'command', 'command': scan_cmd}],
+                    },
+                ],
+            },
+        }
+
+    def post_install(self, scope: str, repo_path: Optional[Path] = None) -> tuple[bool, str]:
+        return _enable_codex_hooks_feature(scope, repo_path)
+
+    def matches_payload(self, raw_payload: dict) -> bool:
+        return raw_payload.get('hook_event_name', '') in _CODEX_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' and tool_name.startswith('mcp__'):
+            canonical_event = AiHookEventType.MCP_EXECUTION
+        else:
+            canonical_event = hook_event_name
+
+        mcp_server_name = None
+        mcp_tool_name = None
+        mcp_arguments = 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]
+            mcp_arguments = tool_input
+
+        return AIHookPayload(
+            event_name=canonical_event,
+            conversation_id=raw_payload.get('session_id'),
+            generation_id=raw_payload.get('turn_id'),
+            ide_user_email=_email_from_auth(),
+            model=raw_payload.get('model'),
+            ide_provider=self.name,
+            prompt=raw_payload.get('prompt', ''),
+            mcp_server_name=mcp_server_name,
+            mcp_tool_name=mcp_tool_name,
+            mcp_arguments=mcp_arguments,
+        )
+
+    def build_hook_response(self, decision: HookDecision) -> dict:
+        # Codex accepts the same hook response shapes as Claude Code:
+        #  - PROMPT: empty for allow, {"decision": "block", "reason": ...} for deny
+        #  - PreToolUse: hookSpecificOutput.permissionDecision
+        if decision.event_type == AiHookEventType.PROMPT:
+            if decision.action == DecisionAction.ALLOW:
+                return {}
+            return {'decision': 'block', 'reason': decision.user_message or ''}
+
+        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:
+        return AIHookPayload(
+            conversation_id=raw_payload.get('session_id'),
+            ide_user_email=_email_from_auth(),
+            model=raw_payload.get('model'),
+            ide_provider=self.name,
+            ide_version=raw_payload.get('codex_version'),
+            source=raw_payload.get('source'),
+        )
+
+    def get_user_email(self) -> Optional[str]:
+        return _email_from_auth()
+
+    def get_session_context(self) -> tuple[dict, dict]:
+        config = _load_codex_config()
+        if not config:
+            return {}, {}
+        # Codex stores MCP servers under `[mcp_servers.<name>]`. Plugin-contributed
+        # servers (via `[plugins."<plugin>@<marketplace>"]`) merge on top.
+        mcp_servers: dict = dict(config.get('mcp_servers') or {})
+        plugin_mcp, enriched_plugins = _resolve_codex_plugins(config)
+        mcp_servers.update(plugin_mcp)
+        return mcp_servers, enriched_plugins

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

@@ -43,7 +43,7 @@ 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)})
+        logger.debug('Cursor MCP config file not found, %s', {'path': str(path)})
         return None
     try:
         return json.loads(path.read_text(encoding='utf-8'))

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

@@ -10,6 +10,7 @@ touching any handler in this module.
 
 import json
 import os
+from dataclasses import dataclass
 from multiprocessing.pool import ThreadPool
 from multiprocessing.pool import TimeoutError as PoolTimeoutError
 from typing import Callable, Optional
@@ -178,23 +179,44 @@ def handle_before_read_file(ctx: typer.Context, payload: AIHookPayload, policy:
         )
 
 
-def handle_before_mcp_execution(ctx: typer.Context, payload: AIHookPayload, policy: dict) -> HookDecision:
-    """Scan MCP tool arguments for secrets before execution."""
+@dataclass(frozen=True)
+class _ArgScanFeature:
+    """Configuration for a "scan some text and decide" event.
+
+    MCP execution and command exec share identical scan-and-decide logic;
+    only the policy key, event type, and user-facing messages differ.
+    """
+
+    policy_key: str  # 'mcp' or 'command_exec'
+    scan_key: str  # 'scan_arguments' or 'scan_command'
+    event_type: AiHookEventType
+    block_reason: BlockReason
+    deny_message: Callable[[str], str]
+    deny_agent_message: str
+    ask_message: Callable[[str], str]
+    ask_agent_message: str
+
+
+def _handle_arg_scan(
+    ctx: typer.Context,
+    payload: AIHookPayload,
+    policy: dict,
+    feature: _ArgScanFeature,
+    scan_text: str,
+) -> HookDecision:
+    """Shared scan + decision flow for MCP_EXECUTION and COMMAND_EXEC events."""
     ai_client = ctx.obj['ai_security_client']
 
-    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 HookDecision.allow(AiHookEventType.MCP_EXECUTION)
+    feature_config = get_policy_value(policy, feature.policy_key, default={})
+    if not get_policy_value(feature_config, 'enabled', default=True):
+        ai_client.create_event(payload, feature.event_type, AIHookOutcome.ALLOWED)
+        return HookDecision.allow(feature.event_type)
 
     mode = get_policy_value(policy, 'mode', default=PolicyMode.BLOCK)
-    tool = payload.mcp_tool_name or 'unknown'
-    args = payload.mcp_arguments or {}
-    args_text = args if isinstance(args, str) else json.dumps(args)
     max_bytes = get_policy_value(policy, 'secrets', 'max_bytes', default=200000)
     timeout_ms = get_policy_value(policy, 'secrets', 'timeout_ms', default=30000)
-    clipped = truncate_utf8(args_text, max_bytes)
-    action = get_policy_value(mcp_config, 'action', default=PolicyMode.BLOCK)
+    clipped = truncate_utf8(scan_text, max_bytes)
+    action = get_policy_value(feature_config, 'action', default=PolicyMode.BLOCK)
 
     scan_id = None
     block_reason = None
@@ -202,26 +224,25 @@ def handle_before_mcp_execution(ctx: typer.Context, payload: AIHookPayload, poli
     error_message = None
 
     try:
-        if get_policy_value(mcp_config, 'scan_arguments', default=True):
+        if get_policy_value(feature_config, feature.scan_key, default=True):
             violation_summary, scan_id = _scan_text_for_secrets(ctx, clipped, timeout_ms)
             if violation_summary:
-                block_reason = BlockReason.SECRETS_IN_MCP_ARGS
+                block_reason = feature.block_reason
                 if mode == PolicyMode.BLOCK and action == PolicyMode.BLOCK:
                     outcome = AIHookOutcome.BLOCKED
-                    user_message = f'Cycode blocked MCP tool call "{tool}". {violation_summary}'
                     return HookDecision.deny(
-                        AiHookEventType.MCP_EXECUTION,
-                        user_message,
-                        'Do not pass secrets to tools. Use secret references (name/id) instead.',
+                        feature.event_type,
+                        feature.deny_message(violation_summary),
+                        feature.deny_agent_message,
                     )
                 outcome = AIHookOutcome.WARNED
                 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.',
+                    feature.event_type,
+                    feature.ask_message(violation_summary),
+                    feature.ask_agent_message,
                 )
 
-        return HookDecision.allow(AiHookEventType.MCP_EXECUTION)
+        return HookDecision.allow(feature.event_type)
     except Exception as e:
         outcome = (
             AIHookOutcome.ALLOWED if get_policy_value(policy, 'fail_open', default=True) else AIHookOutcome.BLOCKED
@@ -232,7 +253,7 @@ def handle_before_mcp_execution(ctx: typer.Context, payload: AIHookPayload, poli
     finally:
         ai_client.create_event(
             payload,
-            AiHookEventType.MCP_EXECUTION,
+            feature.event_type,
             outcome,
             scan_id=scan_id,
             block_reason=block_reason,
@@ -240,6 +261,29 @@ def handle_before_mcp_execution(ctx: typer.Context, payload: AIHookPayload, poli
         )
 
 
+def handle_before_mcp_execution(ctx: typer.Context, payload: AIHookPayload, policy: dict) -> HookDecision:
+    """Scan MCP tool arguments for secrets before execution."""
+    tool = payload.mcp_tool_name or 'unknown'
+    args = payload.mcp_arguments or {}
+    args_text = args if isinstance(args, str) else json.dumps(args)
+    return _handle_arg_scan(
+        ctx,
+        payload,
+        policy,
+        _ArgScanFeature(
+            policy_key='mcp',
+            scan_key='scan_arguments',
+            event_type=AiHookEventType.MCP_EXECUTION,
+            block_reason=BlockReason.SECRETS_IN_MCP_ARGS,
+            deny_message=lambda v: f'Cycode blocked MCP tool call "{tool}". {v}',
+            deny_agent_message='Do not pass secrets to tools. Use secret references (name/id) instead.',
+            ask_message=lambda v: f'{v} in MCP tool call "{tool}". Allow execution?',
+            ask_agent_message='Possible secrets detected in tool arguments; proceed with caution.',
+        ),
+        scan_text=args_text,
+    )
+
+
 def get_handler_for_event(event_type: str) -> Optional[HandlerFn]:
     """Look up the handler for a canonical event type."""
     handlers: dict[str, HandlerFn] = {

cycode/cli/utils/jwt_utils.py

@@ -5,6 +5,14 @@ import jwt
 _JWT_PAYLOAD_POSSIBLE_USER_ID_FIELD_NAMES = ('userId', 'internalId', 'token-user-id')
 
 
+def decode_jwt_unverified(token: str) -> Optional[dict]:
+    """Return JWT claims without signature verification, or None if the token is unreadable."""
+    try:
+        return jwt.decode(token, options={'verify_signature': False})
+    except jwt.PyJWTError:
+        return None
+
+
 def get_user_and_tenant_ids_from_access_token(access_token: str) -> tuple[Optional[str], Optional[str]]:
     payload = jwt.decode(access_token, options={'verify_signature': False})
 

{cycode-3.15.4.dev1.dist-info → cycode-3.15.4.dev2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cycode
-Version: 3.15.4.dev1
+Version: 3.15.4.dev2
 Summary: Boost security in your dev lifecycle via SAST, SCA, Secrets & IaC scanning.
 License-Expression: MIT
 License-File: LICENCE
@@ -34,6 +34,8 @@ Requires-Dist: pyyaml (>=6.0,<7.0)
 Requires-Dist: requests (>=2.32.4,<3.0)
 Requires-Dist: rich (>=13.9.4,<14)
 Requires-Dist: tenacity (>=9.0.0,<9.1.0)
+Requires-Dist: tomli (>=2.0.0,<3.0.0) ; python_version < "3.11"
+Requires-Dist: tomli-w (>=1.0.0,<2.0.0)
 Requires-Dist: typer (>=0.15.3,<0.16.0)
 Requires-Dist: urllib3 (>=2.4.0,<3.0.0)
 Project-URL: Repository, https://github.com/cycodehq/cycode-cli

{cycode-3.15.4.dev1.dist-info → cycode-3.15.4.dev2.dist-info}/RECORD

@@ -1,4 +1,4 @@
-cycode/__init__.py,sha256=UPgVpILY2bWvXK6Bul8uIehLpBu3njNwqn83H0Jz-wo,115
+cycode/__init__.py,sha256=QDmVY8Xl94_IN6IhGe3VfDW0t23u1d5S_iQ9f1k08Ww,115
 cycode/__main__.py,sha256=Z3bD5yrA7yPvAChcADQrqCaZd0ChGI1gdiwALwbWJ6U,104
 cycode/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cycode/cli/app.py,sha256=7ReEcVkRX9IaQ2I7jAj7Sl9smbtvxiuK8-9bitMEQik,7491
@@ -7,15 +7,17 @@ cycode/cli/apps/activation_manager.py,sha256=Hz9PDJFB-ZmYi4HSG8iYC-fR8j5v25VuUU-
 cycode/cli/apps/ai_guardrails/__init__.py,sha256=NsqB1Ca83BIjJMcDSt6suec6Ed0iNnacC0gBqkuuTtI,1367
 cycode/cli/apps/ai_guardrails/command_utils.py,sha256=NVwd0-2RGRKIqhsQ-4LNDR1D0gVm_o7n-z5LxG2bqAo,800
 cycode/cli/apps/ai_guardrails/consts.py,sha256=Js2QtSNYG9Kt0eo3vepRd5TFciCeJHEC9NN18zqKvlE,620
-cycode/cli/apps/ai_guardrails/hooks_manager.py,sha256=dXrVMD_4CcN5aZNZetgtajJab0g4lVGW5ktoS7ALxzc,6864
-cycode/cli/apps/ai_guardrails/ides/__init__.py,sha256=1HgTyTmsX-JPGiYk1at7jbzlay6ASkKfA5RXo7K1_a8,1621
-cycode/cli/apps/ai_guardrails/ides/base.py,sha256=_KzOlD_tTU0HcZ-NaXc6NZ0Tn0ngLxqovQtY_Pcj5H4,5752
-cycode/cli/apps/ai_guardrails/ides/claude_code.py,sha256=YqgxV_kQ39LUlAA9fQbgQmWC7ALC1xMMaEVdsObZtEQ,14197
-cycode/cli/apps/ai_guardrails/ides/cursor.py,sha256=MnzhEgYYukTx7XVdNu-u5yO_PzOrZNteTIIEf0mymYc,5237
+cycode/cli/apps/ai_guardrails/hooks_manager.py,sha256=c8okVel9KjeXWm5QTnvTraWsTwzrUTqqKd6C80C34Y4,9003
+cycode/cli/apps/ai_guardrails/ides/__init__.py,sha256=JMXbQlq-7q1429w3nQq9Z4FZ8K0zdiUK6zCbilmD3JU,1689
+cycode/cli/apps/ai_guardrails/ides/_plugin_utils.py,sha256=_wJfdUHeCJGHQIOdoXQLuMJ4YGaOq_aLjY0ZUyzpsxU,2747
+cycode/cli/apps/ai_guardrails/ides/base.py,sha256=tFWjkuTKBn-4IZUFXHThwKctB6CWOxnG9q9Yr9fscJA,6594
+cycode/cli/apps/ai_guardrails/ides/claude_code.py,sha256=2Rpc22lKGdAmZOCIQtIOTh34g-J_AMUMCDUJocJHzag,13552
+cycode/cli/apps/ai_guardrails/ides/codex.py,sha256=Ep2rNsULM4FzZnej0YXb9KyKBRGIj7qPs-eC78MZd3k,11939
+cycode/cli/apps/ai_guardrails/ides/cursor.py,sha256=_u-DS4Pdvu_UiNh-W5i2ViHPV0IDlDvFrpRnisL3ks8,5235
 cycode/cli/apps/ai_guardrails/install_command.py,sha256=vGZSIvHHVMS9_zhV_6lEhxqtmr5H6uykSq4AS5nxQYw,4278
 cycode/cli/apps/ai_guardrails/scan/__init__.py,sha256=qJc82XiQGiAuc1sYY8Ij_A-qXpxgLPuayQq8xWlouMA,48
 cycode/cli/apps/ai_guardrails/scan/consts.py,sha256=drAslw6vW3kxmbCs2qPCUbUPR7PJouT2lsXtu5sD-lQ,1094
-cycode/cli/apps/ai_guardrails/scan/handlers.py,sha256=7hnawiQhH8rNKQ0DrSyzcy41C9YYeW7LYOJA1QUpkOM,14218
+cycode/cli/apps/ai_guardrails/scan/handlers.py,sha256=pf5PrUIVnGLEEE6QKPny9at5V6Ms5u2IEtFP72hKgqA,15523
 cycode/cli/apps/ai_guardrails/scan/payload.py,sha256=pvT3UUqNMvdK3EVzzPjy4JMlOrF-WgxZ3fHN2AtN5eA,1126
 cycode/cli/apps/ai_guardrails/scan/policy.py,sha256=39s8hnxgjny1l6XAO59wsRcAlpW-LG00GUnO0PfqvuY,2566
 cycode/cli/apps/ai_guardrails/scan/scan_command.py,sha256=-Gl7cHELF1wlwLGno6ZVukFtK6NI6Z3-dTpIOsz8ors,6079
@@ -171,7 +173,7 @@ cycode/cli/utils/enum_utils.py,sha256=h_VTCfJ-0hnhwDsEznmx56rJrCb5FQ8u6PrI6p8MP3
 cycode/cli/utils/get_api_client.py,sha256=wwHabfVCDbFjcIwOn5Raho8MEPiOAgkHlGUEfXKpl8U,3542
 cycode/cli/utils/git_proxy.py,sha256=FPHMBiyLFK9X9vKYpKySRKJH6Dc9Cb3nO241Q95dASE,2911
 cycode/cli/utils/ignore_utils.py,sha256=cODqhnOHA2kRo8rMY0YcmcKkmXNPOC9UTCmFu62RRqE,15567
-cycode/cli/utils/jwt_utils.py,sha256=TfTHCCCxKO6RvSKT2qspx4577Gax3n9YRj2UgigpGuQ,537
+cycode/cli/utils/jwt_utils.py,sha256=EGI-0CKhCGY8hIcZ9b9diq9hqtOUf8Ha8ukeVJIf974,818
 cycode/cli/utils/path_utils.py,sha256=U5te1unzhs9pnU5d9BWExgFWElHQkgKvFxKiOF-lp-w,3245
 cycode/cli/utils/progress_bar.py,sha256=bKBWHHdZsVkdDdWMJLfgLGR0cBYeB44P_DpRM8pvWqU,9528
 cycode/cli/utils/scan_batch.py,sha256=5xKGVDVqoRxdKhuZkK11x4QrNqKmU20Q83E_fy8Nndk,5188
@@ -205,8 +207,8 @@ cycode/cyclient/report_client.py,sha256=Scq30NeJPzgXv0hPLO1U05AdE9i_2iu6cIrSKpEJ
 cycode/cyclient/scan_client.py,sha256=6TK5FQkfrvV7PHqRnUzEn1PBNd2oPYVamvIixcUfe3c,16755
 cycode/cyclient/scan_config_base.py,sha256=mXsPZGYCtp85rv5GIige40yQZXuRcEKUW-VQJ0vgFzk,1201
 cycode/logger.py,sha256=EfZGRK6VC5rE_LAjIcRrHFiQCueylCDXoG6bvGkrIME,2111
-cycode-3.15.4.dev1.dist-info/METADATA,sha256=zo-M7zLCUNGxECnRB06G7NpfNmynUAdahbN-tNa_0dI,89102
-cycode-3.15.4.dev1.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-cycode-3.15.4.dev1.dist-info/entry_points.txt,sha256=iDcVJM8ByLElVgvBgtYxDjw1kT7O8Mo0LcWZIT5L3Ig,45
-cycode-3.15.4.dev1.dist-info/licenses/LICENCE,sha256=2Wx4N6mD_4xB7-E3hPkZ3MPhpJy__k_I8MaCSO-PDRo,1068
-cycode-3.15.4.dev1.dist-info/RECORD,,
+cycode-3.15.4.dev2.dist-info/METADATA,sha256=xiTfy56jgKUKJCRHNswSmoi0vEizW1tCcM1FUQazfp0,89206
+cycode-3.15.4.dev2.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+cycode-3.15.4.dev2.dist-info/entry_points.txt,sha256=iDcVJM8ByLElVgvBgtYxDjw1kT7O8Mo0LcWZIT5L3Ig,45
+cycode-3.15.4.dev2.dist-info/licenses/LICENCE,sha256=2Wx4N6mD_4xB7-E3hPkZ3MPhpJy__k_I8MaCSO-PDRo,1068
+cycode-3.15.4.dev2.dist-info/RECORD,,