fix(python): sync hardened Cursor hooks

AGENTS.md

@@ -33,6 +33,7 @@ This repository publishes the open-source server, console, integration catalog,
 - Model Cursor as one CLI-and-IDE hook contract. Preserve user, project, and enterprise sources in documented priority order; forward `tool_name`, `tool_input`, and `conversation_id`; use exit code `2` for denial; record `failClosed` as the per-script failure-mode control.
 - Write Node Cursor hooks only to `~/.cursor/hooks.json`; keep project and enterprise sources read-only. Register `preToolUse`, `postToolUse`, and `postToolUseFailure`, preserve the complete native payload, emit valid native JSON responses, retain PowerShell exit codes, and commit guard, runtime metadata, private key, audit runtime, and user hooks in one rollback-capable transaction.
 - Write Go Cursor hooks only to `~/.cursor/hooks.json`; keep project and enterprise sources read-only. Preserve user hooks, migrate the prior versionless Elydora contract, audit successful and failed tool calls, emit valid native JSON responses, retain PowerShell exit codes, and commit guard, runtime metadata, private key, audit runtime, and user hooks in one rollback-capable transaction.
+- Write Python Cursor hooks only to `~/.cursor/hooks.json`; keep project and enterprise sources read-only. Preserve user hooks, migrate the prior versionless Elydora contract, use exact native command ownership, retain PowerShell exit code `2`, and set security-critical handlers to `failClosed` with a bounded timeout.
 - Preserve Factory Droid's scope-root `hooks.json` precedence, legacy nested hook source, and per-event `settings.json` fallback. Scope-root and legacy files store event keys at the document root; settings stores the same map under `hooks`. Edit only effective user sources; keep project and organization sources read-only. Preserve JSONC comments through syntax-tree edits, use SDK-native absolute runtime commands, commit generated runtime artifacts and hook sources as one recoverable transaction, and require `/hooks` review after external changes.
 - Qwen Code `0.20.0` resolves user settings through explicit `QWEN_HOME`, then user-level `.qwen/.env`, then `~/.env`, with `~/.qwen/settings.json` as the default. Keep workspace settings read-only. Preserve JSON comments, reject trailing commas and duplicate keys before writes, express timeouts in milliseconds, propagate native exit code `2` through PowerShell, and require `/hooks` review.
 - Commit Qwen Code runtime config, private key, audit runtime, and user settings in one rollback-capable transaction. Status requires enabled `PreToolUse` and `PostToolUse` hooks with matching managed runtime files.

sdks/python/README.md

@@ -80,6 +80,8 @@ Credential options may be omitted in an interactive terminal; the CLI then reads
 
 Codex performs a one-time trust review for user hooks. Run `/hooks` in Codex after installation and trust the Elydora `PreToolUse` and `PostToolUse` definitions.
 
+Cursor installation writes native global `preToolUse` and `postToolUse` handlers to `~/.cursor/hooks.json`. Elydora preserves unrelated user hooks, leaves project and enterprise sources unchanged, and configures a 10-second fail-closed command boundary with exact freeze exit-code propagation.
+
 Cline installation writes `PreToolUse.mjs` and `PostToolUse.mjs` to `$CLINE_DIR/hooks` (default `~/.cline/hooks`). Elydora leaves the Documents and workspace hook roots unchanged. The wrappers preserve Cline's official payload and translate a frozen guard into JSON stdout cancellation control.
 
 Kimi installation writes the strict hook contract to each detected runtime: Kimi Code's `$KIMI_CODE_HOME/config.toml` (default `~/.kimi-code/config.toml`) and the migrating Python CLI's `~/.kimi/config.toml`. A fresh installation targets current Kimi Code, avoiding cross-runtime migration markers. Both runtimes load the hooks globally; run `/hooks` to inspect them.

sdks/python/elydora/cli.py

@@ -204,21 +204,7 @@ def cmd_install(args: argparse.Namespace) -> None:
 
     print(f"Verified key pair (public key: {pub[:16]}...)")
 
-    # Create per-agent directory under ~/.elydora/{agent_id}/
-    ensure_private_directory(_runtime_root())
-    ensure_private_directory(agent_dir)
-
-    # Generate and write the guard script
     guard_script_path = os.path.join(agent_dir, "guard.py")
-    guard_script = generate_guard_script(agent_name, args.agent_id)
-    write_text_atomic(
-        guard_script_path,
-        guard_script,
-        0o700,
-        "Elydora guard runtime",
-    )
-    print(f"  Guard script: {guard_script_path}")
-
     config: InstallConfig = {
         "org_id": args.org_id,
         "agent_id": args.agent_id,
@@ -230,8 +216,24 @@ def cmd_install(args: argparse.Namespace) -> None:
     }
     if secrets.token:
         config["token"] = secrets.token
+    plugin.preflight_install(config)
+
+    # Create per-agent directory under ~/.elydora/{agent_id}/
+    ensure_private_directory(_runtime_root())
+    ensure_private_directory(agent_dir)
+
+    # Generate and write the guard script for adapters that use the shared runtime.
+    if not plugin.manages_guard_runtime:
+        guard_script = generate_guard_script(agent_name, args.agent_id)
+        write_text_atomic(
+            guard_script_path,
+            guard_script,
+            0o700,
+            "Elydora guard runtime",
+        )
 
     plugin.install(config)
+    print(f"  Guard script: {guard_script_path}")
 
 
 def cmd_uninstall(args: argparse.Namespace) -> None:

sdks/python/elydora/plugins/base.py

@@ -32,6 +32,11 @@ class PluginStatus(TypedDict):
 class AgentPlugin(ABC):
     """Base class for all agent plugins."""
 
+    manages_guard_runtime = False
+
+    def preflight_install(self, config: InstallConfig) -> None:
+        """Validate provider sources before the CLI creates runtime files."""
+
     @abstractmethod
     def install(self, config: InstallConfig) -> None:
         """Install the Elydora hook for this agent."""

sdks/python/elydora/plugins/cursor.py

@@ -1,181 +1,183 @@
-"""Cursor plugin — writes/merges postToolUse hook into ~/.cursor/hooks.json."""
+"""Cursor native user-hook integration."""
 
 from __future__ import annotations
 
 import json
 import os
-import sys
+from typing import List, Optional
 
-from ._file_io import write_json_atomic, write_text_atomic
+from elydora._runtime_paths import resolve_agent_directory
+
+from ._transaction import FileChange
 from .base import AgentPlugin, InstallConfig, PluginStatus
-from .hook_template import generate_hook_script
+from .cursor_contract import (
+    AGENT_KEY,
+    AUDIT_SCRIPT,
+    GUARD_SCRIPT,
+    build_handler,
+    remove_managed_hooks,
+    render_document,
+    runtime_contracts,
+    runtime_root,
+    same_path,
+)
+from .cursor_io import (
+    read_document,
+    rendered_change,
+    physical_directory_exists,
+    physical_file_exists,
+    require_runtime_directory,
+    runtime_change,
+    runtime_files_exist,
+    validate_runtime_identity,
+    write_cursor_changes,
+)
+from .hook_template import generate_guard_script, generate_hook_script
 
 
-SETTINGS_PATH = os.path.join(os.path.expanduser("~"), ".cursor", "hooks.json")
-ELYDORA_DIR = os.path.join(os.path.expanduser("~"), ".elydora")
+def _runtime_config(config: InstallConfig, agent_id: str) -> dict:
+    value = {
+        "org_id": config.get("org_id", ""),
+        "agent_id": agent_id,
+        "kid": config.get("kid", ""),
+        "base_url": config.get("base_url", "https://api.elydora.com"),
+        "agent_name": AGENT_KEY,
+    }
+    token = config.get("token", "")
+    if token:
+        value["token"] = token
+    return value
+
+
+def _json_source(value: dict) -> str:
+    return json.dumps(value, indent=2) + "\n"
+
+
+def _present(changes: List[Optional[FileChange]]) -> List[FileChange]:
+    return [change for change in changes if change is not None]
+
+
+def _agent_paths(config: InstallConfig) -> tuple[str, str, str]:
+    agent_id = config.get("agent_id", "")
+    if not agent_id:
+        raise ValueError("agent_id is required")
+    agent_directory = resolve_agent_directory(runtime_root(), agent_id)
+    guard_path = os.path.join(agent_directory, GUARD_SCRIPT)
+    configured_guard = config.get("guard_script_path", "")
+    if not same_path(configured_guard, guard_path):
+        raise ValueError(
+            "Elydora guard runtime must use the managed agent directory: "
+            f"{guard_path}"
+        )
+    return agent_id, agent_directory, guard_path
 
 
 class CursorPlugin(AgentPlugin):
-    """Install/uninstall Elydora audit hook for Cursor."""
+    """Install Elydora into Cursor's native global user hooks."""
 
-    @staticmethod
-    def _hook_path_for(agent_id: str) -> str:
-        return os.path.join(ELYDORA_DIR, agent_id, "hook.py")
+    manages_guard_runtime = True
+
+    def preflight_install(self, config: InstallConfig) -> None:
+        read_document()
+        agent_id, agent_directory, guard_path = _agent_paths(config)
+        if not physical_directory_exists(agent_directory):
+            return
+        validate_runtime_identity(
+            os.path.join(agent_directory, "config.json"),
+            agent_id,
+        )
+        for file_path, label in (
+            (guard_path, "Elydora guard runtime"),
+            (os.path.join(agent_directory, AUDIT_SCRIPT), "Elydora audit runtime"),
+            (os.path.join(agent_directory, "private.key"), "Elydora private key"),
+        ):
+            physical_file_exists(file_path, label)
 
     def install(self, config: InstallConfig) -> None:
-        agent_id = config.get("agent_id", "")
-        agent_name = config.get("agent_name", "")
+        document = read_document()
+        agent_id, agent_directory, guard_path = _agent_paths(config)
+        require_runtime_directory(agent_directory)
+        audit_path = os.path.join(agent_directory, AUDIT_SCRIPT)
 
-        # Create per-agent directory
-        agent_dir = os.path.join(ELYDORA_DIR, agent_id)
-        os.makedirs(agent_dir, exist_ok=True)
-
-        # Write config.json
-        config_data = {
-            "org_id": config.get("org_id", ""),
-            "agent_id": agent_id,
-            "kid": config.get("kid", ""),
-            "base_url": config.get("base_url", "https://api.elydora.com"),
-            "token": config.get("token", ""),
-            "agent_name": agent_name,
-        }
-        config_path = os.path.join(agent_dir, "config.json")
-        write_json_atomic(
-            config_path,
-            config_data,
-            0o600,
-            "Elydora runtime config",
-        )
-
-        # Write private key
-        private_key_path = os.path.join(agent_dir, "private.key")
-        write_text_atomic(
-            private_key_path,
-            config.get("private_key", ""),
-            0o600,
-            "Elydora private key",
-        )
-
-        script = generate_hook_script(
+        runtime_config_path = os.path.join(agent_directory, "config.json")
+        validate_runtime_identity(runtime_config_path, agent_id)
+        hooks = remove_managed_hooks(document.hooks)
+        hooks["preToolUse"] = [
+            *hooks.get("preToolUse", []),
+            build_handler(guard_path),
+        ]
+        hooks["postToolUse"] = [
+            *hooks.get("postToolUse", []),
+            build_handler(audit_path),
+        ]
+        hook_script = generate_hook_script(
             org_id=config.get("org_id", ""),
             agent_id=agent_id,
             kid=config.get("kid", ""),
             base_url=config.get("base_url", "https://api.elydora.com"),
+            success_output="{}\n",
         )
-        hook_path = self._hook_path_for(agent_id)
-        write_text_atomic(
-            hook_path,
-            script,
-            0o700,
-            "Elydora audit runtime",
+        guard_script = generate_guard_script(
+            AGENT_KEY,
+            agent_id,
+            success_output='{"permission":"allow"}\n',
         )
-
-        guard_script_path = config.get("guard_script_path", "")
-        python_exe = sys.executable
-
-        settings = _load_json(SETTINGS_PATH)
-        hooks = settings.setdefault("hooks", {})
-
-        # --- preToolUse (guard — freeze enforcement, camelCase) ---
-        pre_tool_use = hooks.setdefault("preToolUse", [])
-        pre_tool_use[:] = [h for h in pre_tool_use if not _is_elydora_hook(h)]
-        if guard_script_path:
-            pre_tool_use.append({
-                "command": f'"{python_exe}" {guard_script_path}',
-            })
-
-        # --- postToolUse (audit logging, camelCase) ---
-        post_tool_use = hooks.setdefault("postToolUse", [])
-
-        post_tool_use[:] = [h for h in post_tool_use if not _is_elydora_hook(h)]
-
-        post_tool_use.append({
-            "command": hook_path,
-        })
-
-        _save_json(SETTINGS_PATH, settings)
-        print("Elydora hook installed for Cursor.")
-        print(f"  Hook script: {hook_path}")
-        print(f"  Settings: {SETTINGS_PATH}")
+        changes = _present([
+            runtime_change(
+                guard_path,
+                "Elydora guard runtime",
+                guard_script,
+                0o700,
+            ),
+            runtime_change(
+                runtime_config_path,
+                "Elydora runtime config",
+                _json_source(_runtime_config(config, agent_id)),
+                0o600,
+            ),
+            runtime_change(
+                os.path.join(agent_directory, "private.key"),
+                "Elydora private key",
+                config.get("private_key", ""),
+                0o600,
+            ),
+            runtime_change(
+                audit_path,
+                "Elydora audit runtime",
+                hook_script,
+                0o700,
+            ),
+            rendered_change(render_document(document, hooks)),
+        ])
+        write_cursor_changes(changes, "Install Cursor hooks")
+        print(f"  Cursor hooks: {document.file_path}")
 
     def uninstall(self, agent_id: str = "") -> None:
-        if os.path.exists(SETTINGS_PATH):
-            settings = _load_json(SETTINGS_PATH)
-            hooks = settings.get("hooks", {})
-            changed = False
-
-            # Remove preToolUse entries
-            pre_tool_use = hooks.get("preToolUse", [])
-            pre_filtered = [h for h in pre_tool_use if not _is_elydora_hook(h, agent_id)]
-            if len(pre_filtered) != len(pre_tool_use):
-                hooks["preToolUse"] = pre_filtered
-                if not pre_filtered:
-                    del hooks["preToolUse"]
-                changed = True
-
-            # Remove postToolUse entries
-            post_tool_use = hooks.get("postToolUse", [])
-            post_filtered = [h for h in post_tool_use if not _is_elydora_hook(h, agent_id)]
-            if len(post_filtered) != len(post_tool_use):
-                hooks["postToolUse"] = post_filtered
-                if not post_filtered:
-                    del hooks["postToolUse"]
-                changed = True
-
-            if changed:
-                if not hooks:
-                    del settings["hooks"]
-                _save_json(SETTINGS_PATH, settings)
-
-        # Hook script removal is handled by cli.py cmd_uninstall (rmtree of agent dir)
-        print("Elydora hook uninstalled from Cursor.")
+        document = read_document()
+        hooks = remove_managed_hooks(document.hooks, agent_id)
+        change = rendered_change(render_document(document, hooks))
+        write_cursor_changes(
+            [] if change is None else [change],
+            "Uninstall Cursor hooks",
+        )
 
     def status(self) -> PluginStatus:
-        # Scan ~/.elydora/*/hook.py for any installed hook
-        import glob as _glob
-        hook_pattern = os.path.join(ELYDORA_DIR, "*", "hook.py")
-        hook_files = _glob.glob(hook_pattern)
-        hook_exists = len(hook_files) > 0
-
-        settings_configured = False
-        if os.path.exists(SETTINGS_PATH):
-            settings = _load_json(SETTINGS_PATH)
-            hooks = settings.get("hooks", {})
-            pre_tool_use = hooks.get("preToolUse", [])
-            post_tool_use = hooks.get("postToolUse", [])
-            pre_configured = any(_is_elydora_hook(h) for h in pre_tool_use)
-            post_configured = any(_is_elydora_hook(h) for h in post_tool_use)
-            settings_configured = pre_configured and post_configured
-
-        installed = hook_exists and settings_configured
-        if installed:
-            details = f"Found {len(hook_files)} agent(s): {', '.join(hook_files)}"
-        elif hook_exists:
-            details = "Hook script exists but not configured in hooks.json"
-        elif settings_configured:
-            details = "Configured in hooks.json but hook script missing"
-        else:
-            details = "Not installed"
-
-        return PluginStatus(installed=installed, agent="cursor", details=details)
-
-
-def _is_elydora_hook(hook: dict, agent_id: str = "") -> bool:
-    cmd = hook.get("command", "")
-    if "elydora" not in cmd.lower():
-        return False
-    # If agent_id is specified, only match hooks for that specific agent
-    if agent_id:
-        return agent_id in cmd
-    return True
-
-
-def _load_json(path: str) -> dict:
-    if not os.path.exists(path):
-        return {}
-    with open(path, "r", encoding="utf-8") as f:
-        return json.load(f)
-
-
-def _save_json(path: str, data: dict) -> None:
-    write_json_atomic(path, data, 0o600, "Cursor hooks config")
+        document = read_document()
+        contracts = runtime_contracts(document.hooks)
+        if not contracts:
+            return PluginStatus(
+                installed=False,
+                agent=AGENT_KEY,
+                details="Not installed",
+            )
+        installed = runtime_files_exist(contracts)
+        details = (
+            f"Config: {document.file_path}"
+            if installed
+            else f"Configured at {document.file_path}; runtime files missing"
+        )
+        return PluginStatus(
+            installed=installed,
+            agent=AGENT_KEY,
+            details=details,
+        )

sdks/python/elydora/plugins/cursor_contract.py

@@ -0,0 +1,348 @@
+"""Cursor hook contract, ownership, and rendering."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import os
+import re
+import sys
+from typing import Any, Dict, List, Optional, Tuple
+
+
+AGENT_KEY = "cursor"
+GUARD_SCRIPT = "guard.py"
+AUDIT_SCRIPT = "hook.py"
+HOOK_TIMEOUT_SECONDS = 10
+
+JsonObject = Dict[str, Any]
+CursorHooks = Dict[str, List[JsonObject]]
+
+
+@dataclass(frozen=True)
+class CursorDocument:
+    exists: bool
+    file_path: str
+    root: JsonObject
+    hooks: CursorHooks
+    raw: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class RenderedDocument:
+    document: CursorDocument
+    changed: bool
+    next_source: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class RuntimeContract:
+    agent_id: str
+    guard_path: str
+    audit_path: str
+
+
+@dataclass(frozen=True)
+class _ParsedArgument:
+    value: str
+    next_index: int
+
+
+class _DuplicateKey(ValueError):
+    pass
+
+
+def runtime_root() -> str:
+    return os.path.join(os.path.expanduser("~"), ".elydora")
+
+
+def same_path(left: str, right: str) -> bool:
+    return os.path.normcase(os.path.abspath(left)) == os.path.normcase(
+        os.path.abspath(right)
+    )
+
+
+def _same_agent_id(left: str, right: str) -> bool:
+    return os.path.normcase(left) == os.path.normcase(right)
+
+
+def _quote_posix(value: str) -> str:
+    return "'" + value.replace("'", "'\"'\"'") + "'"
+
+
+def _quote_powershell(value: str) -> str:
+    return "'" + value.replace("'", "''") + "'"
+
+
+def build_handler(script_path: str) -> JsonObject:
+    if os.name == "nt":
+        command = (
+            f"& {_quote_powershell(sys.executable)} "
+            f"{_quote_powershell(script_path)}; exit $LASTEXITCODE"
+        )
+    else:
+        command = f"{_quote_posix(sys.executable)} {_quote_posix(script_path)}"
+    return {
+        "command": command,
+        "timeout": HOOK_TIMEOUT_SECONDS,
+        "failClosed": True,
+    }
+
+
+def _read_posix_argument(command: str, start: int) -> Optional[_ParsedArgument]:
+    if start >= len(command) or command[start] != "'":
+        return None
+    apostrophe = "'\"'\"'"
+    value = ""
+    index = start + 1
+    while index < len(command):
+        if command.startswith(apostrophe, index):
+            value += "'"
+            index += len(apostrophe)
+            continue
+        if command[index] == "'":
+            return _ParsedArgument(value, index + 1)
+        value += command[index]
+        index += 1
+    return None
+
+
+def _parse_posix_command(command: str) -> Optional[Tuple[str, str]]:
+    executable = _read_posix_argument(command, 0)
+    if executable is None or command[executable.next_index:executable.next_index + 1] != " ":
+        return None
+    script = _read_posix_argument(command, executable.next_index + 1)
+    if script is None or script.next_index != len(command):
+        return None
+    return executable.value, script.value
+
+
+def _read_powershell_argument(
+    command: str,
+    start: int,
+) -> Optional[_ParsedArgument]:
+    if start >= len(command) or command[start] != "'":
+        return None
+    value = ""
+    index = start + 1
+    while index < len(command):
+        if command[index] != "'":
+            value += command[index]
+            index += 1
+            continue
+        if index + 1 < len(command) and command[index + 1] == "'":
+            value += "'"
+            index += 2
+            continue
+        return _ParsedArgument(value, index + 1)
+    return None
+
+
+def _parse_powershell_command(command: str) -> Optional[Tuple[str, str]]:
+    if not command.startswith("& "):
+        return None
+    executable = _read_powershell_argument(command, 2)
+    if executable is None or command[executable.next_index:executable.next_index + 1] != " ":
+        return None
+    script = _read_powershell_argument(command, executable.next_index + 1)
+    if script is None or command[script.next_index:] != "; exit $LASTEXITCODE":
+        return None
+    return executable.value, script.value
+
+
+def _legacy_script_path(command: str) -> Optional[str]:
+    quoted = re.fullmatch(r'"([^"\r\n]+)" ([^\r\n]+)', command)
+    if quoted and same_path(quoted.group(1), sys.executable):
+        return quoted.group(2)
+    return command if os.path.isabs(command) else None
+
+
+def _managed_script_path(handler: JsonObject) -> Optional[str]:
+    if (
+        set(handler) == {"command", "timeout", "failClosed"}
+        and isinstance(handler.get("command"), str)
+        and type(handler.get("timeout")) is int
+        and handler.get("timeout") == HOOK_TIMEOUT_SECONDS
+        and handler.get("failClosed") is True
+    ):
+        parsed = (
+            _parse_powershell_command(handler["command"])
+            if os.name == "nt"
+            else _parse_posix_command(handler["command"])
+        )
+        if (
+            parsed is not None
+            and os.path.isabs(parsed[0])
+            and os.path.isabs(parsed[1])
+            and same_path(parsed[0], sys.executable)
+        ):
+            return parsed[1]
+    if set(handler) != {"command"} or not isinstance(handler.get("command"), str):
+        return None
+    return _legacy_script_path(handler["command"])
+
+
+def _managed_agent_id(
+    handler: JsonObject,
+    script_name: str,
+) -> Optional[str]:
+    script_path = _managed_script_path(handler)
+    if script_path is None or os.path.basename(script_path) != script_name:
+        return None
+    agent_directory = os.path.dirname(script_path)
+    if not same_path(os.path.dirname(agent_directory), runtime_root()):
+        return None
+    agent_id = os.path.basename(agent_directory)
+    return agent_id if agent_id not in {"", ".", ".."} else None
+
+
+def _unique_object(pairs: List[Tuple[str, Any]]) -> JsonObject:
+    result: JsonObject = {}
+    for key, value in pairs:
+        if key in result:
+            raise _DuplicateKey(f'duplicate field "{key}"')
+        result[key] = value
+    return result
+
+
+def parse_json_object(raw: str, label: str) -> JsonObject:
+    try:
+        value = json.loads(raw, object_pairs_hook=_unique_object)
+    except _DuplicateKey as error:
+        raise ValueError(f"Failed to parse {label}: {error}") from error
+    except json.JSONDecodeError as error:
+        raise ValueError(f"Failed to parse {label}: {error}") from error
+    if not isinstance(value, dict):
+        raise ValueError(f"{label} must contain a JSON object")
+    return value
+
+
+def _read_hooks(value: Any, label: str) -> CursorHooks:
+    if value is None:
+        raise ValueError(f'{label} field "hooks" must be an object')
+    if not isinstance(value, dict):
+        raise ValueError(f'{label} field "hooks" must be an object')
+    hooks: CursorHooks = {}
+    for event, handlers in value.items():
+        if not isinstance(handlers, list):
+            raise ValueError(f'{label} field "hooks.{event}" must be an array')
+        if not all(isinstance(handler, dict) for handler in handlers):
+            raise ValueError(
+                f'{label} field "hooks.{event}" must contain objects'
+            )
+        hooks[event] = list(handlers)
+    return hooks
+
+
+def _contains_managed_hook(hooks: CursorHooks) -> bool:
+    return any(
+        _managed_agent_id(handler, script_name) is not None
+        for event, script_name in (
+            ("preToolUse", GUARD_SCRIPT),
+            ("postToolUse", AUDIT_SCRIPT),
+        )
+        for handler in hooks.get(event, [])
+    )
+
+
+def parse_document(file_path: str, raw: str) -> CursorDocument:
+    label = f"Cursor user hooks at {file_path}"
+    root = parse_json_object(raw, label)
+    hooks = _read_hooks(root.get("hooks", {}), label)
+    version = root.get("version")
+    current = type(version) is int and version == 1
+    legacy_owned = "version" not in root and _contains_managed_hook(hooks)
+    if not current and not legacy_owned:
+        raise ValueError(f"{label} must declare version 1")
+    return CursorDocument(True, file_path, root, hooks, raw)
+
+
+def create_document(file_path: str) -> CursorDocument:
+    return CursorDocument(False, file_path, {}, {})
+
+
+def remove_managed_hooks(
+    hooks: CursorHooks,
+    agent_id: str = "",
+) -> CursorHooks:
+    result = {event: list(handlers) for event, handlers in hooks.items()}
+    for event, script_name in (
+        ("preToolUse", GUARD_SCRIPT),
+        ("postToolUse", AUDIT_SCRIPT),
+    ):
+        handlers = []
+        for handler in result.get(event, []):
+            managed_id = _managed_agent_id(handler, script_name)
+            remove = managed_id is not None and (
+                not agent_id or _same_agent_id(managed_id, agent_id)
+            )
+            if not remove:
+                handlers.append(handler)
+        if handlers:
+            result[event] = handlers
+        else:
+            result.pop(event, None)
+    return result
+
+
+def _entirely_managed(document: CursorDocument) -> bool:
+    if not document.exists or not set(document.root).issubset({"version", "hooks"}):
+        return False
+    if not document.hooks:
+        return False
+    handler_count = 0
+    for event, handlers in document.hooks.items():
+        script_name = {
+            "preToolUse": GUARD_SCRIPT,
+            "postToolUse": AUDIT_SCRIPT,
+        }.get(event)
+        if script_name is None or not handlers:
+            return False
+        handler_count += len(handlers)
+        if any(_managed_agent_id(handler, script_name) is None for handler in handlers):
+            return False
+    return handler_count > 0
+
+
+def render_document(
+    document: CursorDocument,
+    hooks: CursorHooks,
+) -> RenderedDocument:
+    if not document.exists and not hooks:
+        return RenderedDocument(document, False)
+    if document.exists and hooks == document.hooks:
+        return RenderedDocument(document, False)
+    if not hooks and _entirely_managed(document):
+        return RenderedDocument(document, True)
+    root = {**document.root, "version": 1}
+    if hooks:
+        root["hooks"] = hooks
+    else:
+        root.pop("hooks", None)
+    next_source = json.dumps(root, indent=2) + "\n"
+    return RenderedDocument(document, next_source != document.raw, next_source)
+
+
+def _managed_ids(handlers: List[JsonObject], script_name: str) -> Dict[str, str]:
+    result = {}
+    for handler in handlers:
+        agent_id = _managed_agent_id(handler, script_name)
+        if agent_id:
+            result[os.path.normcase(agent_id)] = agent_id
+    return result
+
+
+def runtime_contracts(hooks: CursorHooks) -> List[RuntimeContract]:
+    guards = _managed_ids(hooks.get("preToolUse", []), GUARD_SCRIPT)
+    audits = _managed_ids(hooks.get("postToolUse", []), AUDIT_SCRIPT)
+    contracts = []
+    for key, agent_id in guards.items():
+        if key not in audits:
+            continue
+        agent_directory = os.path.join(runtime_root(), agent_id)
+        contracts.append(RuntimeContract(
+            agent_id,
+            os.path.join(agent_directory, GUARD_SCRIPT),
+            os.path.join(agent_directory, AUDIT_SCRIPT),
+        ))
+    return contracts

sdks/python/elydora/plugins/cursor_io.py

@@ -0,0 +1,192 @@
+"""Cursor hook source and runtime I/O."""
+
+from __future__ import annotations
+
+import os
+import stat
+from typing import Any, List, Optional
+
+from ._transaction import FileChange, source_change, write_changes
+from .cursor_contract import (
+    AGENT_KEY,
+    CursorDocument,
+    JsonObject,
+    RenderedDocument,
+    RuntimeContract,
+    create_document,
+    parse_document,
+    parse_json_object,
+)
+
+
+CONFIG_FILE = "hooks.json"
+
+
+def config_path() -> str:
+    return os.path.join(os.path.expanduser("~"), ".cursor", CONFIG_FILE)
+
+
+def _read_optional_physical(file_path: str, label: str) -> Optional[str]:
+    try:
+        metadata = os.lstat(file_path)
+    except FileNotFoundError:
+        return None
+    except OSError as error:
+        raise OSError(f"Inspect {label} at {file_path}: {error}") from error
+    if not stat.S_ISREG(metadata.st_mode) or stat.S_ISLNK(metadata.st_mode):
+        raise OSError(f"{label} path is not a physical file: {file_path}")
+    try:
+        with open(file_path, "r", encoding="utf-8", newline="") as file:
+            return file.read()
+    except OSError as error:
+        raise OSError(f"Read {label} at {file_path}: {error}") from error
+
+
+def read_document() -> CursorDocument:
+    file_path = config_path()
+    raw = _read_optional_physical(file_path, "Cursor user hooks")
+    return create_document(file_path) if raw is None else parse_document(file_path, raw)
+
+
+def rendered_change(rendered: RenderedDocument) -> Optional[FileChange]:
+    if not rendered.changed:
+        return None
+    return source_change(
+        rendered.document.file_path,
+        "Cursor user hooks",
+        rendered.document.raw,
+        rendered.next_source,
+        0o600,
+    )
+
+
+def runtime_change(
+    file_path: str,
+    label: str,
+    next_source: str,
+    mode: int,
+) -> Optional[FileChange]:
+    original = _read_optional_physical(file_path, label)
+    return source_change(file_path, label, original, next_source, mode)
+
+
+def physical_file_exists(file_path: str, label: str) -> bool:
+    try:
+        metadata = os.lstat(file_path)
+    except FileNotFoundError:
+        return False
+    except OSError as error:
+        raise OSError(f"Inspect {label} at {file_path}: {error}") from error
+    if not stat.S_ISREG(metadata.st_mode) or stat.S_ISLNK(metadata.st_mode):
+        raise OSError(f"{label} path is not a physical file: {file_path}")
+    return True
+
+
+def require_runtime(file_path: str, label: str) -> None:
+    if not file_path:
+        raise ValueError(f"{label} path is required")
+    if not physical_file_exists(file_path, label):
+        raise FileNotFoundError(f"{label} is missing: {file_path}")
+
+
+def physical_directory_exists(directory: str) -> bool:
+    try:
+        metadata = os.lstat(directory)
+    except FileNotFoundError:
+        return False
+    except OSError as error:
+        raise OSError(
+            f"Inspect Elydora agent runtime directory at {directory}: {error}"
+        ) from error
+    if not stat.S_ISDIR(metadata.st_mode) or stat.S_ISLNK(metadata.st_mode):
+        raise OSError(
+            f"Elydora agent runtime path is not a physical directory: {directory}"
+        )
+    return True
+
+
+def require_runtime_directory(directory: str) -> None:
+    if not physical_directory_exists(directory):
+        raise FileNotFoundError(
+            f"Elydora agent runtime directory is missing: {directory}"
+        )
+
+
+def _read_runtime_config(file_path: str) -> Optional[JsonObject]:
+    raw = _read_optional_physical(file_path, "Elydora runtime config")
+    if raw is None:
+        return None
+    return parse_json_object(raw, f"Elydora runtime config at {file_path}")
+
+
+def validate_runtime_identity(
+    file_path: str,
+    agent_id: str,
+) -> None:
+    config = _read_runtime_config(file_path)
+    if config is None:
+        return
+    if config.get("agent_name") != AGENT_KEY or not _same_agent_id(
+        config.get("agent_id"), agent_id
+    ):
+        raise ValueError(
+            f"Elydora runtime config identity does not match Cursor agent {agent_id}: "
+            f"{file_path}"
+        )
+
+
+def _same_agent_id(value: Any, expected: str) -> bool:
+    return isinstance(value, str) and os.path.normcase(value) == os.path.normcase(
+        expected
+    )
+
+
+def runtime_files_exist(contracts: List[RuntimeContract]) -> bool:
+    for contract in contracts:
+        agent_directory = os.path.dirname(contract.guard_path)
+        if not physical_directory_exists(agent_directory):
+            continue
+        config_path_value = os.path.join(agent_directory, "config.json")
+        config = _read_runtime_config(config_path_value)
+        if (
+            config is None
+            or config.get("agent_name") != AGENT_KEY
+            or not _same_agent_id(config.get("agent_id"), contract.agent_id)
+        ):
+            continue
+        if physical_file_exists(
+            contract.guard_path,
+            "Elydora guard runtime",
+        ) and physical_file_exists(
+            contract.audit_path,
+            "Elydora audit runtime",
+        ) and physical_file_exists(
+            os.path.join(agent_directory, "private.key"),
+            "Elydora private key",
+        ):
+            return True
+    return False
+
+
+def _ensure_physical_directory(directory: str, label: str) -> None:
+    try:
+        os.makedirs(directory, mode=0o700, exist_ok=True)
+        metadata = os.lstat(directory)
+    except OSError as error:
+        raise OSError(f"Prepare {label} directory at {directory}: {error}") from error
+    if not stat.S_ISDIR(metadata.st_mode) or stat.S_ISLNK(metadata.st_mode):
+        raise OSError(f"{label} directory is not a physical directory: {directory}")
+
+
+def write_cursor_changes(changes: List[FileChange], label: str) -> None:
+    effective = [change for change in changes if change.original != change.next_source]
+    if not effective:
+        return
+    directories = {
+        os.path.normcase(os.path.abspath(os.path.dirname(change.file_path))):
+        os.path.dirname(change.file_path)
+        for change in effective
+    }
+    for directory in directories.values():
+        _ensure_physical_directory(directory, label)
+    write_changes(effective, label)

sdks/python/elydora/plugins/hook_template.py

@@ -16,6 +16,7 @@ def generate_hook_script(
     agent_id: str,
     kid: str,
     base_url: str,
+    success_output: str = "",
 ) -> str:
     """Return a complete, self-contained Python hook script as a string.
 
@@ -49,6 +50,7 @@ ORG_ID = {org_id!r}
 AGENT_ID = {agent_id!r}
 KID = {kid!r}
 BASE_URL = {base_url!r}
+SUCCESS_OUTPUT = {success_output!r}
 
 ELYDORA_DIR = os.path.join(os.path.expanduser("~"), ".elydora")
 PRIVATE_KEY_PATH = os.path.join(ELYDORA_DIR, AGENT_ID, "private.key")
@@ -341,10 +343,16 @@ def main():
 
 if __name__ == "__main__":
     main()
+    if SUCCESS_OUTPUT:
+        sys.stdout.write(SUCCESS_OUTPUT)
 '''
 
 
-def generate_guard_script(agent_name: str, agent_id: str) -> str:
+def generate_guard_script(
+    agent_name: str,
+    agent_id: str,
+    success_output: str = "",
+) -> str:
     """Return a self-contained Python guard script for PreToolUse freeze enforcement.
 
     The script:
@@ -367,6 +375,7 @@ import time
 
 AGENT_NAME = {agent_name!r}
 AGENT_ID = {agent_id!r}
+SUCCESS_OUTPUT = {success_output!r}
 ELYDORA_DIR = os.path.join(os.path.expanduser("~"), ".elydora")
 CONFIG_PATH = os.path.join(ELYDORA_DIR, AGENT_ID, "config.json")
 STATUS_CACHE_PATH = os.path.join(ELYDORA_DIR, AGENT_ID, "status-cache.json")
@@ -444,4 +453,6 @@ def main():
 
 if __name__ == "__main__":
     main()
+    if SUCCESS_OUTPUT:
+        sys.stdout.write(SUCCESS_OUTPUT)
 '''

sdks/python/elydora/plugins/registry.py

@@ -33,7 +33,7 @@ SUPPORTED_AGENTS: Dict[str, Dict[str, str]] = {
     },
     "cursor": {
         "name": "Cursor",
-        "hook_event": "PostToolUse",
+        "hook_event": "PreToolUse/PostToolUse",
         "config_path": "~/.cursor/hooks.json",
     },
     "droid": {

sdks/python/tests/test_cli_security.py

@@ -249,7 +249,13 @@ def test_cli_reads_credentials_from_files_before_installing(
     installed: list[dict[str, str]] = []
 
     class Plugin:
+        manages_guard_runtime = False
+
+        def preflight_install(self, config: dict[str, str]) -> None:
+            assert Path(config["guard_script_path"]).exists() is False
+
         def install(self, config: dict[str, str]) -> None:
+            assert Path(config["guard_script_path"]).is_file()
             installed.append(config)
 
     monkeypatch.setattr(cli, "_get_plugin", lambda _name: Plugin())
@@ -281,6 +287,41 @@ def test_cli_reads_credentials_from_files_before_installing(
         assert guard_path.stat().st_mode & 0o777 == 0o700
 
 
+def test_cursor_cli_preflight_rejects_config_before_runtime_writes(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    private_key_file = tmp_path / "private.key"
+    write_secret(private_key_file, PRIVATE_KEY)
+    home_dir = tmp_path / "home"
+    config_path = home_dir / ".cursor" / "hooks.json"
+    config_path.parent.mkdir(parents=True)
+    config_path.write_text("{ malformed", encoding="utf-8")
+    monkeypatch.setenv("HOME", str(home_dir))
+    monkeypatch.setenv("USERPROFILE", str(home_dir))
+    args = cli.build_parser().parse_args(
+        [
+            "install",
+            "--agent",
+            "cursor",
+            "--org_id",
+            "org-1",
+            "--agent_id",
+            "agent-1",
+            "--private_key_file",
+            str(private_key_file),
+            "--kid",
+            "key-1",
+        ]
+    )
+
+    with pytest.raises(ValueError, match="parse Cursor user hooks"):
+        cli.cmd_install(args)
+
+    assert config_path.read_text(encoding="utf-8") == "{ malformed"
+    assert (home_dir / ".elydora").exists() is False
+
+
 def test_generated_hook_reads_private_key_from_private_file(
     monkeypatch: pytest.MonkeyPatch,
     tmp_path: Path,
@@ -353,7 +394,11 @@ def test_legacy_plugins_persist_one_owner_only_private_key(
     guard_path = runtime_root / "agent-1" / "guard.py"
     guard_path.parent.mkdir(parents=True)
     guard_path.write_text("pass\n", encoding="utf-8")
-    monkeypatch.setattr(module, "ELYDORA_DIR", str(runtime_root))
+    if module is cursor:
+        monkeypatch.setenv("HOME", str(case_root))
+        monkeypatch.setenv("USERPROFILE", str(case_root))
+    else:
+        monkeypatch.setattr(module, "ELYDORA_DIR", str(runtime_root))
 
     if hasattr(module, "SETTINGS_PATH"):
         monkeypatch.setattr(

sdks/python/tests/test_cursor_plugin.py

@@ -0,0 +1,500 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import time
+from typing import Any, Mapping
+
+import pytest
+
+from elydora.plugins import cursor
+from elydora.plugins.cursor import CursorPlugin
+from elydora.plugins.hook_template import generate_guard_script
+from elydora.plugins.registry import SUPPORTED_AGENTS
+
+
+AGENT_ID = "agent-1"
+
+
+@dataclass
+class CursorFixture:
+    home_dir: Path
+    config_path: Path
+    agent_dir: Path
+    guard_path: Path
+    hook_path: Path
+    runtime_config_path: Path
+    private_key_path: Path
+    plugin: CursorPlugin
+    config: dict[str, str]
+
+    def install(self) -> None:
+        self.plugin.install(self.config)
+
+
+def _write_json(path: Path, value: object) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    source = value if isinstance(value, str) else json.dumps(value, indent=2) + "\n"
+    path.write_text(source, encoding="utf-8")
+
+
+def _prepare_fixture(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    *,
+    existing_config: object | None = None,
+    create_guard: bool = True,
+) -> CursorFixture:
+    home_dir = tmp_path / "home with spaces and 'quote"
+    config_path = home_dir / ".cursor" / "hooks.json"
+    agent_dir = home_dir / ".elydora" / AGENT_ID
+    guard_path = agent_dir / "guard.py"
+    hook_path = agent_dir / "hook.py"
+    runtime_config_path = agent_dir / "config.json"
+    private_key_path = agent_dir / "private.key"
+    monkeypatch.setenv("HOME", str(home_dir))
+    monkeypatch.setenv("USERPROFILE", str(home_dir))
+    monkeypatch.setattr(cursor, "SETTINGS_PATH", str(config_path), raising=False)
+    monkeypatch.setattr(
+        cursor,
+        "ELYDORA_DIR",
+        str(home_dir / ".elydora"),
+        raising=False,
+    )
+    agent_dir.mkdir(parents=True)
+    if create_guard:
+        guard_path.write_text(
+            generate_guard_script("cursor", AGENT_ID),
+            encoding="utf-8",
+        )
+    if existing_config is not None:
+        _write_json(config_path, existing_config)
+    return CursorFixture(
+        home_dir=home_dir,
+        config_path=config_path,
+        agent_dir=agent_dir,
+        guard_path=guard_path,
+        hook_path=hook_path,
+        runtime_config_path=runtime_config_path,
+        private_key_path=private_key_path,
+        plugin=CursorPlugin(),
+        config={
+            "org_id": "org-1",
+            "agent_id": AGENT_ID,
+            "agent_name": "cursor",
+            "private_key": "private-key",
+            "kid": "key-1",
+            "token": "token-1",
+            "base_url": "https://api.elydora.com",
+            "guard_script_path": str(guard_path),
+        },
+    )
+
+
+def _managed_handler(settings: Mapping[str, Any], event: str, script: str) -> dict:
+    handlers = settings["hooks"][event]
+    return next(handler for handler in handlers if script in handler.get("command", ""))
+
+
+def _assert_native_handler(handler: dict) -> None:
+    assert set(handler) == {"command", "timeout", "failClosed"}
+    assert handler["timeout"] == 10
+    assert handler["failClosed"] is True
+    assert sys.executable.lower() in handler["command"].lower()
+    if os.name == "nt":
+        assert handler["command"].startswith("& '")
+        assert handler["command"].endswith("; exit $LASTEXITCODE")
+    else:
+        assert handler["command"].startswith("'")
+
+
+def _run_handler(
+    handler: Mapping[str, Any], payload: bytes,
+    environment: Mapping[str, str] | None = None,
+) -> subprocess.CompletedProcess[bytes]:
+    if os.name == "nt":
+        arguments = [
+            "powershell.exe", "-NoProfile", "-NonInteractive",
+            "-Command", handler["command"],
+        ]
+    else:
+        arguments = ["/bin/sh", "-c", handler["command"]]
+    return subprocess.run(
+        arguments,
+        input=payload,
+        capture_output=True,
+        check=False,
+        env={**os.environ, **(environment or {})},
+    )
+
+
+def _symlink_or_skip(target: Path, link: Path) -> None:
+    try:
+        link.symlink_to(target)
+    except OSError as error:
+        pytest.skip(f"Symbolic links unavailable: {error}")
+
+
+def test_cursor_registry_declares_both_native_events() -> None:
+    assert SUPPORTED_AGENTS["cursor"] == {
+        "name": "Cursor", "hook_event": "PreToolUse/PostToolUse",
+        "config_path": "~/.cursor/hooks.json",
+    }
+def test_install_preserves_user_hooks_migrates_legacy_and_is_idempotent(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    fixture = _prepare_fixture(monkeypatch, tmp_path)
+    _write_json(
+        fixture.config_path,
+        {
+            "description": "user-owned",
+            "hooks": {
+                "sessionStart": [{"command": "user-session"}],
+                "preToolUse": [
+                    {"command": "user-pre"},
+                    {"command": f'"{sys.executable}" {fixture.guard_path}'},
+                ],
+                "postToolUse": [{"command": str(fixture.hook_path)}],
+            },
+        },
+    )
+
+    fixture.install()
+    fixture.install()
+
+    settings = json.loads(fixture.config_path.read_text(encoding="utf-8"))
+    assert settings["version"] == 1
+    assert settings["description"] == "user-owned"
+    assert settings["hooks"]["sessionStart"] == [{"command": "user-session"}]
+    assert settings["hooks"]["preToolUse"][0] == {"command": "user-pre"}
+    assert len(settings["hooks"]["preToolUse"]) == 2
+    assert len(settings["hooks"]["postToolUse"]) == 1
+    _assert_native_handler(_managed_handler(settings, "preToolUse", "guard.py"))
+    _assert_native_handler(_managed_handler(settings, "postToolUse", "hook.py"))
+def test_handlers_block_frozen_agent_and_forward_official_input_byte_for_byte(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    fixture = _prepare_fixture(monkeypatch, tmp_path)
+    fixture.install()
+    settings = json.loads(fixture.config_path.read_text(encoding="utf-8"))
+    guard = _managed_handler(settings, "preToolUse", "guard.py")
+    audit = _managed_handler(settings, "postToolUse", "hook.py")
+    _write_json(
+        fixture.agent_dir / "status-cache.json",
+        {"status": "active", "cached_at": time.time()},
+    )
+    assert json.loads(_run_handler(guard, b"{}\n").stdout) == {"permission": "allow"}
+    _write_json(
+        fixture.agent_dir / "status-cache.json",
+        {"status": "frozen", "cached_at": time.time()},
+    )
+    pre_payload = (
+        json.dumps(
+            {
+                "conversation_id": "conversation-1",
+                "generation_id": "generation-1",
+                "hook_event_name": "preToolUse",
+                "tool_name": "Shell",
+                "tool_input": {"command": "Get-ChildItem"},
+                "tool_use_id": "call-1",
+                "cwd": str(tmp_path),
+            },
+            separators=(",", ":"),
+        )
+        + "\n"
+    ).encode()
+    guard_result = _run_handler(guard, pre_payload)
+    assert guard_result.returncode == 2
+    assert b"frozen by Elydora" in guard_result.stderr
+    capture_path = tmp_path / "captured-event.json"
+    fixture.hook_path.write_text(
+        "import os, pathlib, sys\n"
+        "pathlib.Path(os.environ['ELYDORA_CAPTURE']).write_bytes(sys.stdin.buffer.read())\n"
+        "print('{}')\n",
+        encoding="utf-8",
+    )
+    post_payload = (
+        json.dumps(
+            {
+                "conversation_id": "conversation-1",
+                "generation_id": "generation-1",
+                "hook_event_name": "postToolUse",
+                "tool_name": "Shell",
+                "tool_input": {"command": "Get-ChildItem"},
+                "tool_output": '{"exitCode":0,"stdout":"ok"}',
+                "tool_use_id": "call-1",
+                "cwd": str(tmp_path),
+                "duration": 42,
+            },
+            separators=(",", ":"),
+        )
+        + "\n"
+    ).encode()
+    audit_result = _run_handler(audit, post_payload, {"ELYDORA_CAPTURE": str(capture_path)})
+    assert audit_result.returncode == 0
+    assert json.loads(audit_result.stdout) == {}
+    assert capture_path.read_bytes() == post_payload
+
+
+def test_status_requires_exact_pair_identity_and_physical_runtimes(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    fixture = _prepare_fixture(monkeypatch, tmp_path)
+    fixture.install()
+    assert fixture.plugin.status()["installed"] is True
+
+    settings = json.loads(fixture.config_path.read_text(encoding="utf-8"))
+    _managed_handler(settings, "preToolUse", "guard.py")["failClosed"] = False
+    _write_json(fixture.config_path, settings)
+    assert fixture.plugin.status()["installed"] is False
+
+    fixture.install()
+    hook_source = fixture.hook_path.read_text(encoding="utf-8")
+    fixture.hook_path.unlink()
+    assert fixture.plugin.status()["installed"] is False
+    fixture.hook_path.write_text(hook_source, encoding="utf-8")
+
+    _write_json(
+        fixture.runtime_config_path,
+        {"agent_id": "another-agent", "agent_name": "cursor"},
+    )
+    assert fixture.plugin.status()["installed"] is False
+    fixture.runtime_config_path.write_text("{ malformed", encoding="utf-8")
+    with pytest.raises(ValueError, match="parse Elydora runtime config"):
+        fixture.plugin.status()
+
+
+def test_uninstall_uses_exact_ownership_and_preserves_user_entries(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    fixture = _prepare_fixture(
+        monkeypatch,
+        tmp_path,
+        existing_config={
+            "version": 1,
+            "hooks": {"sessionStart": [{"command": "keep"}]},
+        },
+    )
+    fixture.install()
+    settings = json.loads(fixture.config_path.read_text(encoding="utf-8"))
+    other_guard = deepcopy(_managed_handler(settings, "preToolUse", "guard.py"))
+    other_audit = deepcopy(_managed_handler(settings, "postToolUse", "hook.py"))
+    other_guard["command"] = other_guard["command"].replace(AGENT_ID, "agent-10")
+    other_audit["command"] = other_audit["command"].replace(AGENT_ID, "agent-10")
+    settings["hooks"]["preToolUse"].extend(
+        [
+            other_guard,
+            {
+                "command": "echo elydora agent-1 guard.py",
+                "timeout": 10,
+                "failClosed": True,
+            },
+        ]
+    )
+    settings["hooks"]["postToolUse"].append(other_audit)
+    _write_json(fixture.config_path, settings)
+
+    fixture.plugin.uninstall(AGENT_ID)
+
+    remaining = json.loads(fixture.config_path.read_text(encoding="utf-8"))
+    assert remaining["hooks"]["sessionStart"] == [{"command": "keep"}]
+    assert len(remaining["hooks"]["preToolUse"]) == 2
+    assert len(remaining["hooks"]["postToolUse"]) == 1
+    assert "agent-10" in remaining["hooks"]["preToolUse"][0]["command"]
+
+
+@pytest.mark.parametrize(
+    "existing_config",
+    [
+        "{ malformed",
+        "[]\n",
+        '{"hooks":{}}\n',
+        '{"version":2,"hooks":{}}\n',
+        '{"version":1,"hooks":null}\n',
+        '{"version":1,"hooks":{"preToolUse":null}}\n',
+        '{"version":1,"hooks":{"preToolUse":[null]}}\n',
+        '{"version":1,"version":1,"hooks":{}}\n',
+        '{"version":1,"hooks":{},}\n',
+    ],
+)
+def test_invalid_config_is_preserved_before_runtime_writes(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    existing_config: str,
+) -> None:
+    fixture = _prepare_fixture(
+        monkeypatch,
+        tmp_path,
+        existing_config=existing_config,
+    )
+    original_guard = fixture.guard_path.read_text(encoding="utf-8")
+
+    with pytest.raises(ValueError):
+        fixture.install()
+
+    assert fixture.config_path.read_text(encoding="utf-8") == existing_config
+    assert fixture.guard_path.read_text(encoding="utf-8") == original_guard
+    assert fixture.hook_path.exists() is False
+    assert fixture.runtime_config_path.exists() is False
+    assert fixture.private_key_path.exists() is False
+
+
+def test_install_creates_missing_guard_and_rejects_unmanaged_path(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    fixture = _prepare_fixture(monkeypatch, tmp_path, create_guard=False)
+    fixture.install()
+    assert fixture.guard_path.is_file()
+
+    fixture = _prepare_fixture(monkeypatch, tmp_path / "unmanaged", create_guard=False)
+    unmanaged = fixture.home_dir / "unmanaged-guard.py"
+    unmanaged.write_text("pass\n", encoding="utf-8")
+    fixture.config["guard_script_path"] = str(unmanaged)
+    with pytest.raises(ValueError, match="managed agent directory"):
+        fixture.install()
+    assert fixture.config_path.exists() is False
+
+
+@pytest.mark.parametrize("runtime_name", ["guard.py", "hook.py"])
+def test_symbolic_link_runtime_is_rejected_before_config_writes(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    runtime_name: str,
+) -> None:
+    fixture = _prepare_fixture(monkeypatch, tmp_path)
+    runtime_path = fixture.agent_dir / runtime_name
+    target = fixture.home_dir / f"{runtime_name}.target"
+    target.write_text("pass\n", encoding="utf-8")
+    if runtime_path.exists():
+        runtime_path.unlink()
+    _symlink_or_skip(target, runtime_path)
+
+    with pytest.raises(OSError, match="physical file"):
+        fixture.install()
+
+    assert fixture.config_path.exists() is False
+    assert target.read_text(encoding="utf-8") == "pass\n"
+
+
+def test_symbolic_link_config_is_rejected_and_target_is_preserved(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    fixture = _prepare_fixture(monkeypatch, tmp_path)
+    target = fixture.home_dir / "cursor-hooks.target.json"
+    original = '{"version":1,"hooks":{}}\n'
+    target.write_text(original, encoding="utf-8")
+    fixture.config_path.parent.mkdir(parents=True)
+    _symlink_or_skip(target, fixture.config_path)
+
+    with pytest.raises(OSError, match="physical file"):
+        fixture.install()
+
+    assert target.read_text(encoding="utf-8") == original
+    assert fixture.config_path.is_symlink()
+
+
+@pytest.mark.parametrize("runtime_name", ["config.json", "private.key", "guard.py", "hook.py"])
+def test_status_rejects_symbolic_link_runtime_files(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    runtime_name: str,
+) -> None:
+    fixture = _prepare_fixture(monkeypatch, tmp_path)
+    fixture.install()
+    runtime_path = fixture.agent_dir / runtime_name
+    contents = runtime_path.read_bytes()
+    target = fixture.home_dir / f"status-{runtime_name}.target"
+    target.write_bytes(contents)
+    runtime_path.unlink()
+    _symlink_or_skip(target, runtime_path)
+
+    with pytest.raises(OSError, match="physical file"):
+        fixture.plugin.status()
+
+
+def test_uninstall_removes_entirely_managed_config_and_keeps_absence(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    fixture = _prepare_fixture(monkeypatch, tmp_path)
+    fixture.install()
+    fixture.plugin.uninstall(AGENT_ID)
+    assert fixture.config_path.exists() is False
+    fixture.plugin.uninstall(AGENT_ID)
+    assert fixture.config_path.exists() is False
+    user_source = '{"version":1,"hooks":{}}\n'
+    fixture.config_path.write_text(user_source, encoding="utf-8")
+    fixture.plugin.uninstall(AGENT_ID)
+    assert fixture.config_path.read_text(encoding="utf-8") == user_source
+
+
+def test_transaction_rolls_back_runtime_files_when_config_commit_fails(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    fixture = _prepare_fixture(
+        monkeypatch,
+        tmp_path,
+        existing_config={"version": 1, "hooks": {"sessionStart": []}},
+        create_guard=False,
+    )
+    original = fixture.config_path.read_text(encoding="utf-8")
+    real_replace = os.replace
+    failed = False
+    def fail_config_once(source: str, destination: str) -> None:
+        nonlocal failed
+        if os.path.abspath(destination) == str(fixture.config_path) and not failed:
+            failed = True
+            raise OSError("injected config commit failure")
+        real_replace(source, destination)
+    monkeypatch.setattr(os, "replace", fail_config_once)
+    with pytest.raises(OSError, match="injected config commit failure"):
+        fixture.install()
+    assert fixture.config_path.read_text(encoding="utf-8") == original
+    assert fixture.guard_path.exists() is False
+    assert fixture.hook_path.exists() is False
+    assert fixture.runtime_config_path.exists() is False
+    assert fixture.private_key_path.exists() is False
+    assert not list(fixture.home_dir.rglob("*.tmp"))
+    assert not list(fixture.home_dir.rglob("*.rollback"))
+
+
+def test_atomic_config_write_detects_concurrent_source_change(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    from elydora.plugins._transaction import write_changes
+    from elydora.plugins.cursor_contract import render_document
+    from elydora.plugins.cursor_io import read_document, rendered_change
+
+    fixture = _prepare_fixture(
+        monkeypatch,
+        tmp_path,
+        existing_config={
+            "version": 1,
+            "hooks": {"sessionStart": [{"command": "original"}]},
+        },
+    )
+    document = read_document()
+    rendered = render_document(document, {})
+    change = rendered_change(rendered)
+    assert change is not None
+    concurrent = '{"version":1,"hooks":{"sessionStart":[]}}\n'
+    fixture.config_path.write_text(concurrent, encoding="utf-8")
+
+    with pytest.raises(OSError, match="changed during installation"):
+        write_changes([change], "Update Cursor hooks")
+
+    assert fixture.config_path.read_text(encoding="utf-8") == concurrent
+    assert not list(fixture.config_path.parent.glob("*.tmp"))