fix(python): sync transactional Codex hooks

sdks/python/elydora/plugins/_managed_files.py

@@ -0,0 +1,104 @@
+"""Physical file and directory primitives for managed hook state."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+import stat
+from typing import Optional
+
+
+MAX_SECRET_BYTES = 64 * 1024
+MAX_CONFIG_BYTES = 512 * 1024
+MAX_SOURCE_BYTES = 2 * 1024 * 1024
+
+
+@dataclass(frozen=True)
+class FileSnapshot:
+    contents: str
+    device: int
+    inode: int
+    mode: int
+
+
+def _inspect_regular_file(file_path: str, label: str) -> Optional[os.stat_result]:
+    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}")
+    return metadata
+
+
+def read_physical_file(
+    file_path: str,
+    label: str,
+    maximum_bytes: int = MAX_SOURCE_BYTES,
+) -> Optional[FileSnapshot]:
+    before = _inspect_regular_file(file_path, label)
+    if before is None:
+        return None
+    if before.st_size > maximum_bytes:
+        raise ValueError(f"{label} exceeds {maximum_bytes} bytes: {file_path}")
+
+    flags = os.O_RDONLY | getattr(os, "O_BINARY", 0) | getattr(os, "O_CLOEXEC", 0)
+    flags |= getattr(os, "O_NOFOLLOW", 0)
+    descriptor = -1
+    try:
+        descriptor = os.open(file_path, flags)
+        after = os.fstat(descriptor)
+        if not stat.S_ISREG(after.st_mode):
+            raise OSError(f"{label} path is not a physical file: {file_path}")
+        if (before.st_dev, before.st_ino) != (after.st_dev, after.st_ino):
+            raise OSError(f"{label} changed while opening: {file_path}")
+        if after.st_size > maximum_bytes:
+            raise ValueError(f"{label} exceeds {maximum_bytes} bytes: {file_path}")
+        with os.fdopen(descriptor, "rb") as file:
+            descriptor = -1
+            raw = file.read(maximum_bytes + 1)
+    except OSError as error:
+        raise OSError(f"Read {label} at {file_path}: {error}") from error
+    finally:
+        if descriptor >= 0:
+            os.close(descriptor)
+
+    if len(raw) > maximum_bytes:
+        raise ValueError(f"{label} exceeds {maximum_bytes} bytes: {file_path}")
+    try:
+        contents = raw.decode("utf-8")
+    except UnicodeDecodeError as error:
+        raise ValueError(f"{label} at {file_path} must contain UTF-8 text") from error
+    return FileSnapshot(
+        contents=contents,
+        device=after.st_dev,
+        inode=after.st_ino,
+        mode=stat.S_IMODE(after.st_mode),
+    )
+
+
+def physical_file_exists(file_path: str, label: str) -> bool:
+    return _inspect_regular_file(file_path, label) is not None
+
+
+def physical_directory_exists(directory: str, label: str) -> bool:
+    try:
+        metadata = os.lstat(directory)
+    except FileNotFoundError:
+        return False
+    except OSError as error:
+        raise OSError(f"Inspect {label} at {directory}: {error}") from error
+    if not stat.S_ISDIR(metadata.st_mode) or stat.S_ISLNK(metadata.st_mode):
+        raise OSError(f"{label} is not a physical directory: {directory}")
+    return True
+
+
+def ensure_physical_directory(directory: str, label: str) -> None:
+    try:
+        os.makedirs(directory, mode=0o700, exist_ok=True)
+    except OSError as error:
+        raise OSError(f"Prepare {label} at {directory}: {error}") from error
+    if not physical_directory_exists(directory, label):
+        raise OSError(f"{label} is missing: {directory}")

sdks/python/elydora/plugins/_strict_json.py

@@ -0,0 +1,32 @@
+"""Strict JSON parsing with duplicate-key rejection."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Tuple
+
+
+JsonObject = Dict[str, Any]
+
+
+class _DuplicateKey(ValueError):
+    pass
+
+
+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, 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

sdks/python/elydora/plugins/_transaction.py

@@ -4,11 +4,17 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 import os
-import stat
 import tempfile
 from typing import List, Optional, Sequence
 from uuid import uuid4
 
+from ._managed_files import (
+    MAX_SOURCE_BYTES,
+    ensure_physical_directory,
+    physical_file_exists,
+    read_physical_file,
+)
+
 
 @dataclass(frozen=True)
 class FileChange:
@@ -18,6 +24,9 @@ class FileChange:
     next_source: Optional[str]
     mode: int
     original_mode: Optional[int]
+    original_device: Optional[int]
+    original_inode: Optional[int]
+    maximum_bytes: int
 
 
 @dataclass
@@ -28,23 +37,13 @@ class _StagedChange:
     committed: bool = False
 
 
-def read_optional(file_path: str, label: str) -> Optional[str]:
-    try:
-        with open(file_path, "r", encoding="utf-8", newline="") as file:
-            return file.read()
-    except FileNotFoundError:
-        return None
-    except OSError as error:
-        raise OSError(f"Read {label} at {file_path}: {error}") from error
-
-
-def _existing_mode(file_path: str) -> Optional[int]:
-    try:
-        return stat.S_IMODE(os.stat(file_path).st_mode)
-    except FileNotFoundError:
-        return None
-    except OSError as error:
-        raise OSError(f"Read file mode at {file_path}: {error}") from error
+def read_optional(
+    file_path: str,
+    label: str,
+    maximum_bytes: int = MAX_SOURCE_BYTES,
+) -> Optional[str]:
+    snapshot = read_physical_file(file_path, label, maximum_bytes)
+    return None if snapshot is None else snapshot.contents
 
 
 def source_change(
@@ -53,16 +52,24 @@ def source_change(
     original: Optional[str],
     next_source: Optional[str],
     mode: int,
+    maximum_bytes: int = MAX_SOURCE_BYTES,
 ) -> Optional[FileChange]:
     if original == next_source:
         return None
+    snapshot = read_physical_file(file_path, label, maximum_bytes)
+    current = None if snapshot is None else snapshot.contents
+    if current != original:
+        raise OSError(f"{label} changed before staging: {file_path}")
     return FileChange(
         file_path,
         label,
         original,
         next_source,
         mode,
-        _existing_mode(file_path),
+        None if snapshot is None else snapshot.mode,
+        None if snapshot is None else snapshot.device,
+        None if snapshot is None else snapshot.inode,
+        maximum_bytes,
     )
 
 
@@ -71,13 +78,16 @@ def file_change(
     label: str,
     next_source: Optional[str],
     mode: int,
+    maximum_bytes: int = MAX_SOURCE_BYTES,
 ) -> Optional[FileChange]:
+    snapshot = read_physical_file(file_path, label, maximum_bytes)
     return source_change(
         file_path,
         label,
-        read_optional(file_path, label),
+        None if snapshot is None else snapshot.contents,
         next_source,
         mode,
+        maximum_bytes,
     )
 
 
@@ -137,20 +147,24 @@ def _write_staged(
 
 
 def _assert_unchanged(change: FileChange) -> None:
-    current = read_optional(change.file_path, change.label)
-    if current != change.original:
+    snapshot = read_physical_file(
+        change.file_path,
+        change.label,
+        change.maximum_bytes,
+    )
+    current = None if snapshot is None else snapshot.contents
+    identity_changed = snapshot is not None and (
+        snapshot.device != change.original_device
+        or snapshot.inode != change.original_inode
+    )
+    if current != change.original or identity_changed:
         raise OSError(f"{change.label} changed during installation: {change.file_path}")
 
 
 def _stage(change: FileChange) -> _StagedChange:
     _assert_unchanged(change)
     directory = os.path.dirname(change.file_path)
-    try:
-        os.makedirs(directory, mode=0o700, exist_ok=True)
-    except OSError as error:
-        raise OSError(
-            f"Create directory for {change.label} at {directory}: {error}"
-        ) from error
+    ensure_physical_directory(directory, f"{change.label} directory")
     basename = os.path.basename(change.file_path)
     temporary_path = None
     rollback_path = None
@@ -258,12 +272,7 @@ def write_changes(changes: Sequence[FileChange], label: str) -> None:
 
 
 def regular_file_exists(file_path: str, label: str) -> bool:
-    try:
-        return stat.S_ISREG(os.stat(file_path).st_mode)
-    except FileNotFoundError:
-        return False
-    except OSError as error:
-        raise OSError(f"Read {label} at {file_path}: {error}") from error
+    return physical_file_exists(file_path, label)
 
 
 def require_runtime(file_path: str, label: str) -> None:

sdks/python/elydora/plugins/codex.py

@@ -1,415 +1,236 @@
-"""OpenAI Codex lifecycle-hook integration."""
+"""OpenAI Codex native user-hook integration."""
 
 from __future__ import annotations
 
+import base64
 import json
 import os
-import shlex
-import stat
-# subprocess provides argument quoting only; this module starts no process.
-import subprocess  # nosec B404
-import sys
-import tempfile
-from typing import Any, Dict, List, Optional
+import urllib.parse
+from typing import List, Optional
 
+from elydora._runtime_paths import resolve_agent_directory
+from elydora.utils import base64url_encode
+
+from ._managed_files import MAX_CONFIG_BYTES, MAX_SECRET_BYTES
+from ._transaction import FileChange
 from .base import AgentPlugin, InstallConfig, PluginStatus
-from .hook_template import generate_hook_script
+from .codex_contract import (
+    AGENT_KEY,
+    AUDIT_SCRIPT,
+    AUDIT_STATUS,
+    GUARD_SCRIPT,
+    GUARD_STATUS,
+    build_handler,
+    remove_managed_hooks,
+    render_document,
+    runtime_contracts,
+    runtime_root,
+    same_path,
+)
+from .codex_io import (
+    read_document,
+    rendered_change,
+    runtime_change,
+    runtime_files_exist,
+    validate_hooks_directory,
+    validate_runtime_tree,
+    write_codex_changes,
+)
+from .hook_template import generate_guard_script, generate_hook_script
 
 
-AGENT_KEY = "codex"
-OWNED_DESCRIPTION = "Elydora audit and freeze enforcement"
-GUARD_STATUS = "Checking Elydora agent state"
-AUDIT_STATUS = "Recording Elydora tool use"
-GUARD_SCRIPT = "guard.py"
-AUDIT_SCRIPT = "hook.py"
-ELYDORA_DIR = os.path.join(os.path.expanduser("~"), ".elydora")
-CONFIG_PATH = os.path.join(os.path.expanduser("~"), ".codex", "hooks.json")
-
-JsonObject = Dict[str, Any]
-
-
-def _read_json(path: str, label: str) -> Optional[JsonObject]:
-    try:
-        with open(path, "r", encoding="utf-8") as file:
-            raw = file.read()
-    except FileNotFoundError:
-        return None
-    except OSError as error:
-        raise OSError(f"Read {label} at {path}: {error}") from error
-
-    try:
-        value = json.loads(raw)
-    except json.JSONDecodeError as error:
-        raise ValueError(f"Failed to parse {label} at {path}: {error}") from error
-    if not isinstance(value, dict):
-        raise ValueError(f"{label} at {path} must contain a JSON object")
+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 _cleanup_failed_write(path: str, label: str, cause: Exception) -> None:
-    try:
-        os.remove(path)
-    except FileNotFoundError:
-        return
-    except OSError as cleanup_error:
-        raise OSError(
-            f"Write {label} failed: {cause}; cleanup of {path} failed: {cleanup_error}"
-        ) from cause
+def _json_source(value: dict) -> str:
+    return json.dumps(value, indent=2) + "\n"
 
 
-def _write_text_atomic(path: str, content: str, mode: int, label: str) -> None:
-    directory = os.path.dirname(path)
-    try:
-        os.makedirs(directory, mode=0o700, exist_ok=True)
-    except OSError as error:
-        raise OSError(f"Create directory for {label} at {directory}: {error}") from error
-
-    descriptor = -1
-    temporary_path = ""
-    try:
-        descriptor, temporary_path = tempfile.mkstemp(
-            prefix=f".{os.path.basename(path)}.",
-            suffix=".tmp",
-            dir=directory,
-            text=True,
-        )
-        with os.fdopen(descriptor, "w", encoding="utf-8", newline="\n") as file:
-            descriptor = -1
-            file.write(content)
-            file.flush()
-            os.fsync(file.fileno())
-        os.chmod(temporary_path, mode)
-        os.replace(temporary_path, path)
-    except Exception as error:
-        if descriptor >= 0:
-            try:
-                os.close(descriptor)
-            except OSError as close_error:
-                _cleanup_failed_write(temporary_path, label, close_error)
-                raise OSError(
-                    f"Write {label} at {path} failed: {error}; "
-                    f"close failed: {close_error}"
-                ) from error
-        _cleanup_failed_write(temporary_path, label, error)
-        raise OSError(f"Write {label} at {path}: {error}") from error
+def _present(changes: List[Optional[FileChange]]) -> List[FileChange]:
+    return [change for change in changes if change is not None]
 
 
-def _write_json_atomic(path: str, value: JsonObject, mode: int, label: str) -> None:
-    encoded = json.dumps(value, indent=2) + "\n"
-    _write_text_atomic(path, encoded, mode, label)
-
-
-def _remove_file(path: str, label: str) -> None:
-    try:
-        os.remove(path)
-    except FileNotFoundError:
-        return
-    except OSError as error:
-        raise OSError(f"Remove {label} at {path}: {error}") from error
-
-
-def _regular_file_exists(path: str, label: str) -> bool:
-    try:
-        metadata = os.stat(path)
-    except FileNotFoundError:
-        return False
-    except OSError as error:
-        raise OSError(f"Read {label} at {path}: {error}") from error
-    return stat.S_ISREG(metadata.st_mode)
-
-
-def _require_runtime(path: str, label: str) -> None:
-    if not path:
-        raise ValueError(f"{label} path is required")
-    if not _regular_file_exists(path, label):
-        raise FileNotFoundError(f"{label} is missing: {path}")
-
-
-def _build_handler(script_path: str, status_message: str) -> JsonObject:
-    return {
-        "type": "command",
-        "command": f"{shlex.quote(sys.executable)} {shlex.quote(script_path)}",
-        "commandWindows": subprocess.list2cmdline([sys.executable, script_path]),
-        "timeout": 10,
-        "statusMessage": status_message,
-    }
-
-
-def _hooks_object(settings: JsonObject) -> JsonObject:
-    if "hooks" not in settings:
-        return {}
-    hooks = settings["hooks"]
-    if not isinstance(hooks, dict):
-        raise ValueError('Codex hooks config field "hooks" must be an object')
-    return dict(hooks)
-
-
-def _event_groups(hooks: JsonObject, event: str) -> List[JsonObject]:
-    if event not in hooks:
-        return []
-    groups = hooks[event]
-    if not isinstance(groups, list) or not all(
-        isinstance(group, dict) for group in groups
-    ):
-        raise ValueError(
-            f'Codex hooks config field "hooks.{event}" must be an array of objects'
-        )
-    return groups
-
-
-def _is_managed_command(command: Any, script_name: str, agent_id: str = "") -> bool:
-    if not isinstance(command, str):
-        return False
-    normalized = os.path.normcase(command)
-    if ".elydora" not in normalized or script_name.lower() not in normalized.lower():
-        return False
+def _agent_paths(config: InstallConfig) -> tuple[str, str, str, str]:
+    agent_id = config.get("agent_id", "")
     if not agent_id:
-        return True
-    expected_path = os.path.normcase(
-        os.path.join(ELYDORA_DIR, agent_id, script_name)
-    )
-    return expected_path in normalized
+        raise ValueError("agent_id is required")
+    agent_directory = resolve_agent_directory(runtime_root(), agent_id)
+    guard_path = os.path.join(agent_directory, GUARD_SCRIPT)
+    audit_path = os.path.join(agent_directory, AUDIT_SCRIPT)
+    configured_guard = config.get("guard_script_path", "")
+    if not same_path(configured_guard, guard_path):
+        raise ValueError(
+            f"Elydora guard runtime must use the managed agent directory: {guard_path}"
+        )
+    return agent_id, agent_directory, guard_path, audit_path
 
 
-def _is_elydora_handler(handler: JsonObject, agent_id: str = "") -> bool:
-    status_message = handler.get("statusMessage")
-    if status_message == GUARD_STATUS:
-        script_name = GUARD_SCRIPT
-    elif status_message == AUDIT_STATUS:
-        script_name = AUDIT_SCRIPT
-    else:
-        return False
-    return any(
-        _is_managed_command(handler.get(key), script_name, agent_id)
-        for key in ("command", "commandWindows")
-    )
-
-
-def _without_elydora(
-    groups: List[JsonObject],
-    agent_id: str = "",
-) -> List[JsonObject]:
-    filtered_groups: List[JsonObject] = []
-    for group in groups:
-        handlers = group.get("hooks")
-        if not isinstance(handlers, list) or not all(
-            isinstance(handler, dict) for handler in handlers
-        ):
-            raise ValueError("Codex hook matcher group must contain a hooks array")
-        filtered = [
-            handler
-            for handler in handlers
-            if not _is_elydora_handler(handler, agent_id)
-        ]
-        if filtered:
-            filtered_groups.append({**group, "hooks": filtered})
-    return filtered_groups
-
-
-def _find_handler(
-    groups: List[JsonObject],
-    status_message: str,
-) -> Optional[JsonObject]:
-    for group in groups:
-        handlers = group.get("hooks")
-        if not isinstance(handlers, list) or not all(
-            isinstance(handler, dict) for handler in handlers
-        ):
-            raise ValueError("Codex hook matcher group must contain a hooks array")
-        for handler in handlers:
-            if (
-                handler.get("statusMessage") == status_message
-                and _is_elydora_handler(handler)
-            ):
-                return handler
-    return None
-
-
-def _command_references(handler: JsonObject, script_path: str) -> bool:
-    return any(
-        isinstance(handler.get(key), str) and script_path in handler[key]
-        for key in ("command", "commandWindows")
-    )
-
-
-def _is_owned_settings(settings: JsonObject, hooks: JsonObject) -> bool:
-    settings_keys = {"description", "hooks"}
-    hook_keys = {"PreToolUse", "PostToolUse"}
-    return (
-        all(key in settings_keys for key in settings)
-        and settings.get("description") == OWNED_DESCRIPTION
-        and all(key in hook_keys for key in hooks)
-        and all(isinstance(value, list) and not value for value in hooks.values())
-    )
-
-
-def _runtime_scripts_exist(guard: JsonObject, audit: JsonObject) -> bool:
+def _validate_private_key(value: str) -> None:
     try:
-        with os.scandir(ELYDORA_DIR) as iterator:
-            entries = sorted(iterator, key=lambda entry: entry.name)
-    except FileNotFoundError:
-        return False
-    except OSError as error:
-        raise OSError(
-            f"Read Elydora runtime directory at {ELYDORA_DIR}: {error}"
+        padded = value + "=" * ((4 - len(value) % 4) % 4)
+        seed = base64.b64decode(
+            padded.replace("-", "+").replace("_", "/"),
+            validate=True,
+        )
+    except (ValueError, UnicodeEncodeError) as error:
+        raise ValueError(
+            "private_key must be a canonical 32-byte base64url value"
         ) from error
+    if len(seed) != 32 or base64url_encode(seed) != value:
+        raise ValueError("private_key must be a canonical 32-byte base64url value")
 
-    for entry in entries:
-        try:
-            is_directory = entry.is_dir(follow_symlinks=False)
-        except OSError as error:
-            raise OSError(
-                f"Read Elydora runtime entry at {entry.path}: {error}"
-            ) from error
-        if not is_directory:
-            continue
 
-        guard_path = os.path.join(entry.path, GUARD_SCRIPT)
-        hook_path = os.path.join(entry.path, AUDIT_SCRIPT)
-        if not (
-            _command_references(guard, guard_path)
-            and _command_references(audit, hook_path)
-        ):
-            continue
+def _validate_install_config(config: InstallConfig) -> None:
+    for field in ("org_id", "agent_id", "kid", "private_key", "base_url"):
+        value = config.get(field)
+        if not isinstance(value, str) or not value:
+            raise ValueError(f"{field} is required")
+    if config.get("agent_name") != AGENT_KEY:
+        raise ValueError(f"Codex installation requires agent_name {AGENT_KEY}")
+    _validate_private_key(config["private_key"])
 
-        config_path = os.path.join(entry.path, "config.json")
-        config = _read_json(config_path, "Elydora runtime config")
-        if config is None:
-            continue
-        agent_name = config.get("agent_name")
-        if not isinstance(agent_name, str):
-            raise ValueError(
-                f'Elydora runtime config at {config_path} field "agent_name" '
-                "must be a string"
-            )
-        if agent_name != AGENT_KEY:
-            continue
-        return _regular_file_exists(
-            guard_path, "Elydora guard runtime"
-        ) and _regular_file_exists(hook_path, "Elydora audit runtime")
-    return False
+    base_url = config["base_url"]
+    try:
+        parsed = urllib.parse.urlsplit(base_url)
+        hostname = parsed.hostname
+        parsed.port
+        has_credentials = parsed.username is not None or parsed.password is not None
+    except ValueError as error:
+        raise ValueError("base_url must be an absolute HTTP or HTTPS URL") from error
+    invalid_character = "\\" in base_url or any(
+        character.isspace() or ord(character) < 32 for character in base_url
+    )
+    valid_origin = (
+        parsed.scheme in ("http", "https")
+        and bool(parsed.netloc)
+        and hostname is not None
+        and not invalid_character
+    )
+    if not valid_origin:
+        raise ValueError("base_url must be an absolute HTTP or HTTPS URL")
+    if has_credentials or parsed.query or parsed.fragment:
+        raise ValueError(
+            "base_url must exclude credentials, query parameters, and fragments"
+        )
+
+    if "token" in config:
+        token = config["token"]
+        if not isinstance(token, str) or not token:
+            raise ValueError("token must be a non-empty string when provided")
+    _agent_paths(config)
 
 
 class CodexPlugin(AgentPlugin):
-    """Install Elydora into Codex user lifecycle hooks."""
+    """Install Elydora into Codex's native global user hooks."""
+
+    manages_guard_runtime = True
+
+    def preflight_install(self, config: InstallConfig) -> None:
+        _validate_install_config(config)
+        document = read_document()
+        validate_hooks_directory(document.file_path)
+        agent_id, agent_directory, _, _ = _agent_paths(config)
+        validate_runtime_tree(runtime_root(), agent_directory, agent_id)
 
     def install(self, config: InstallConfig) -> None:
-        agent_id = config.get("agent_id", "")
-        if not agent_id:
-            raise ValueError("agent_id is required")
+        self.preflight_install(config)
+        document = read_document()
+        agent_id, agent_directory, guard_path, audit_path = _agent_paths(config)
 
-        existing_settings = _read_json(CONFIG_PATH, "Codex hooks config")
-        settings = (
-            existing_settings
-            if existing_settings is not None
-            else {"description": OWNED_DESCRIPTION}
-        )
-        hooks = _hooks_object(settings)
-        pre_tool_use = _without_elydora(_event_groups(hooks, "PreToolUse"))
-        post_tool_use = _without_elydora(_event_groups(hooks, "PostToolUse"))
-
-        guard_path = config.get("guard_script_path", "")
-        _require_runtime(guard_path, "Elydora guard runtime")
-        agent_dir = os.path.join(ELYDORA_DIR, agent_id)
-        hook_path = os.path.join(agent_dir, AUDIT_SCRIPT)
+        hooks = remove_managed_hooks(document.hooks)
         hooks["PreToolUse"] = [
-            *pre_tool_use,
+            *hooks.get("PreToolUse", []),
             {
                 "matcher": "*",
-                "hooks": [_build_handler(guard_path, GUARD_STATUS)],
+                "hooks": [build_handler(guard_path, GUARD_STATUS)],
             },
         ]
         hooks["PostToolUse"] = [
-            *post_tool_use,
+            *hooks.get("PostToolUse", []),
             {
                 "matcher": "*",
-                "hooks": [_build_handler(hook_path, AUDIT_STATUS)],
+                "hooks": [build_handler(audit_path, AUDIT_STATUS)],
             },
         ]
 
-        runtime_config: JsonObject = {
-            "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": config.get("agent_name", AGENT_KEY) or AGENT_KEY,
-        }
-        hook_script = generate_hook_script(
+        guard_script = generate_guard_script(AGENT_KEY, agent_id)
+        audit_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"),
+            native_payload=True,
+            agent_name=AGENT_KEY,
         )
-        _write_json_atomic(
-            os.path.join(agent_dir, "config.json"),
-            runtime_config,
-            0o600,
-            "Elydora runtime config",
+        changes = _present(
+            [
+                runtime_change(
+                    guard_path,
+                    "Elydora guard runtime",
+                    guard_script,
+                    0o700,
+                ),
+                runtime_change(
+                    os.path.join(agent_directory, "config.json"),
+                    "Elydora runtime config",
+                    _json_source(_runtime_config(config, agent_id)),
+                    0o600,
+                    MAX_CONFIG_BYTES,
+                ),
+                runtime_change(
+                    os.path.join(agent_directory, "private.key"),
+                    "Elydora private key",
+                    config.get("private_key", ""),
+                    0o600,
+                    MAX_SECRET_BYTES,
+                ),
+                runtime_change(
+                    audit_path,
+                    "Elydora audit runtime",
+                    audit_script,
+                    0o700,
+                ),
+                rendered_change(render_document(document, hooks)),
+            ]
         )
-        _write_text_atomic(
-            os.path.join(agent_dir, "private.key"),
-            config.get("private_key", ""),
-            0o600,
-            "Elydora private key",
-        )
-        _write_text_atomic(
-            hook_path,
-            hook_script,
-            0o700,
-            "Elydora audit runtime",
-        )
-        _write_json_atomic(
-            CONFIG_PATH,
-            {**settings, "hooks": hooks},
-            0o600,
-            "Codex hooks config",
-        )
-        print("Codex: run /hooks to review and trust the Elydora hooks.")
+        write_codex_changes(changes, "Install Codex hooks")
+        print(f"  Codex hooks: {document.file_path}")
+        print("  Codex trust: run /hooks and approve both Elydora command hooks.")
 
     def uninstall(self, agent_id: str = "") -> None:
-        settings = _read_json(CONFIG_PATH, "Codex hooks config")
-        if settings is None:
+        document = read_document()
+        hooks = remove_managed_hooks(document.hooks, agent_id)
+        change = rendered_change(render_document(document, hooks))
+        if change is None:
             return
-        hooks = _hooks_object(settings)
-        hooks["PreToolUse"] = _without_elydora(
-            _event_groups(hooks, "PreToolUse"),
-            agent_id,
-        )
-        hooks["PostToolUse"] = _without_elydora(
-            _event_groups(hooks, "PostToolUse"),
-            agent_id,
-        )
-        if _is_owned_settings(settings, hooks):
-            _remove_file(CONFIG_PATH, "Codex hooks config")
-        else:
-            _write_json_atomic(
-                CONFIG_PATH,
-                {**settings, "hooks": hooks},
-                0o600,
-                "Codex hooks config",
-            )
+        validate_hooks_directory(document.file_path)
+        write_codex_changes([change], "Uninstall Codex hooks")
 
     def status(self) -> PluginStatus:
-        settings = _read_json(CONFIG_PATH, "Codex hooks config")
-        guard: Optional[JsonObject] = None
-        audit: Optional[JsonObject] = None
-        if settings is not None:
-            hooks = _hooks_object(settings)
-            guard = _find_handler(_event_groups(hooks, "PreToolUse"), GUARD_STATUS)
-            audit = _find_handler(_event_groups(hooks, "PostToolUse"), AUDIT_STATUS)
-
-        if guard is None or audit is None:
+        document = read_document()
+        contracts = runtime_contracts(document.hooks)
+        if not contracts:
             return PluginStatus(
                 installed=False,
                 agent=AGENT_KEY,
                 details="Not installed",
             )
-        installed = _runtime_scripts_exist(guard, audit)
+        installed = runtime_files_exist(contracts)
         details = (
-            f"Config: {CONFIG_PATH}"
+            f"Config: {document.file_path}"
             if installed
-            else f"Configured at {CONFIG_PATH}; runtime scripts missing"
+            else f"Configured at {document.file_path}; runtime files missing"
         )
         return PluginStatus(
             installed=installed,

sdks/python/elydora/plugins/codex_contract.py

@@ -0,0 +1,448 @@
+"""Codex user-hook contract, exact ownership, and rendering."""
+
+from __future__ import annotations
+
+import base64
+from dataclasses import dataclass
+import json
+import ntpath
+import os
+import re
+import shlex
+import subprocess  # nosec B404 - used only for legacy argument rendering
+import sys
+from typing import Any, Dict, List, Optional, Tuple
+
+from ._strict_json import JsonObject, parse_json_object
+
+
+AGENT_KEY = "codex"
+CONFIG_FILE = "hooks.json"
+GUARD_SCRIPT = "guard.py"
+AUDIT_SCRIPT = "hook.py"
+HOOK_TIMEOUT_SECONDS = 10
+OWNED_DESCRIPTION = "Elydora audit and freeze enforcement"
+GUARD_STATUS = "Checking Elydora agent state"
+AUDIT_STATUS = "Recording Elydora tool use"
+
+CodexHooks = Dict[str, List[JsonObject]]
+
+
+@dataclass(frozen=True)
+class CodexDocument:
+    exists: bool
+    file_path: str
+    root: JsonObject
+    hooks: CodexHooks
+    raw: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class RenderedDocument:
+    document: CodexDocument
+    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
+
+
+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 _windows_powershell_path() -> str:
+    configured = os.environ.get("SystemRoot") if os.name == "nt" else None
+    system_root = (
+        configured
+        if configured
+        and ntpath.isabs(configured)
+        and re.search(r'["%\r\n]', configured) is None
+        else r"C:\Windows"
+    )
+    return ntpath.join(
+        system_root,
+        "System32",
+        "WindowsPowerShell",
+        "v1.0",
+        "powershell.exe",
+    )
+
+
+def _windows_command(script_path: str) -> str:
+    source = (
+        f"& {_quote_powershell(sys.executable)} "
+        f"{_quote_powershell(script_path)}; exit $LASTEXITCODE"
+    )
+    encoded = base64.b64encode(source.encode("utf-16le")).decode("ascii")
+    return (
+        f'"{_windows_powershell_path()}" -NoLogo -NoProfile '
+        f"-NonInteractive -EncodedCommand {encoded}"
+    )
+
+
+def build_handler(script_path: str, status_message: str) -> JsonObject:
+    return {
+        "type": "command",
+        "command": f"{_quote_posix(sys.executable)} {_quote_posix(script_path)}",
+        "commandWindows": _windows_command(script_path),
+        "timeout": HOOK_TIMEOUT_SECONDS,
+        "statusMessage": status_message,
+    }
+
+
+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: Any) -> Optional[Tuple[str, str]]:
+    if not isinstance(command, str):
+        return None
+    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_source(source: str) -> Optional[Tuple[str, str]]:
+    if not source.startswith("& "):
+        return None
+    executable = _read_powershell_argument(source, 2)
+    if (
+        executable is None
+        or source[executable.next_index : executable.next_index + 1] != " "
+    ):
+        return None
+    script = _read_powershell_argument(source, executable.next_index + 1)
+    if script is None or source[script.next_index :] != "; exit $LASTEXITCODE":
+        return None
+    return executable.value, script.value
+
+
+def _parse_windows_command(command: Any) -> Optional[Tuple[str, str]]:
+    if not isinstance(command, str):
+        return None
+    match = re.fullmatch(
+        r'"([^"\r\n]+)" -NoLogo -NoProfile -NonInteractive '
+        r"-EncodedCommand ([A-Za-z0-9+/]+={0,2})",
+        command,
+    )
+    if (
+        match is None
+        or not ntpath.isabs(match.group(1))
+        or ntpath.basename(match.group(1)).lower() != "powershell.exe"
+    ):
+        return None
+    try:
+        raw = base64.b64decode(match.group(2), validate=True)
+        if base64.b64encode(raw).decode("ascii") != match.group(2):
+            return None
+        source = raw.decode("utf-16le")
+    except (UnicodeDecodeError, ValueError):
+        return None
+    return _parse_powershell_source(source)
+
+
+def _parse_legacy_commands(handler: JsonObject) -> Optional[Tuple[str, str]]:
+    command = handler.get("command")
+    command_windows = handler.get("commandWindows")
+    if not isinstance(command, str) or not isinstance(command_windows, str):
+        return None
+    try:
+        arguments = shlex.split(command, posix=True)
+    except ValueError:
+        return None
+    if len(arguments) != 2:
+        return None
+    expected_posix = f"{shlex.quote(arguments[0])} {shlex.quote(arguments[1])}"
+    if command != expected_posix or command_windows != subprocess.list2cmdline(
+        arguments
+    ):
+        return None
+    return arguments[0], arguments[1]
+
+
+def _is_python_executable(file_path: str) -> bool:
+    return (
+        re.fullmatch(
+            r"python(?:[0-9]+(?:\.[0-9]+)*)?(?:\.exe)?",
+            os.path.basename(file_path),
+            re.I,
+        )
+        is not None
+    )
+
+
+def _managed_script_path(
+    handler: JsonObject,
+    status_message: str,
+) -> Optional[str]:
+    if (
+        set(handler)
+        != {"type", "command", "commandWindows", "timeout", "statusMessage"}
+        or handler.get("type") != "command"
+        or type(handler.get("timeout")) is not int
+        or handler.get("timeout") != HOOK_TIMEOUT_SECONDS
+        or handler.get("statusMessage") != status_message
+    ):
+        return None
+    posix = _parse_posix_command(handler.get("command"))
+    windows = _parse_windows_command(handler.get("commandWindows"))
+    if posix is None or windows is None:
+        legacy = _parse_legacy_commands(handler)
+        posix = legacy
+        windows = legacy
+    if (
+        posix is None
+        or windows is None
+        or not os.path.isabs(posix[0])
+        or not os.path.isabs(posix[1])
+        or not _is_python_executable(posix[0])
+        or not _is_python_executable(windows[0])
+        or not same_path(posix[0], windows[0])
+        or not same_path(posix[1], windows[1])
+    ):
+        return None
+    return posix[1]
+
+
+def _managed_agent_id(
+    handler: JsonObject,
+    script_name: str,
+    status_message: str,
+) -> Optional[str]:
+    script_path = _managed_script_path(handler, status_message)
+    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 _read_hooks(value: Any, label: str) -> CodexHooks:
+    if value is None or not isinstance(value, dict):
+        raise ValueError(f'{label} field "hooks" must be an object')
+    hooks: CodexHooks = {}
+    for event, groups in value.items():
+        if not isinstance(groups, list):
+            raise ValueError(f'{label} field "hooks.{event}" must be an array')
+        parsed_groups = []
+        for index, group in enumerate(groups):
+            if not isinstance(group, dict):
+                raise ValueError(
+                    f"{label} matcher group hooks.{event}[{index}] must be an object"
+                )
+            handlers = group.get("hooks")
+            if not isinstance(handlers, list) or not all(
+                isinstance(handler, dict) for handler in handlers
+            ):
+                raise ValueError(
+                    f"{label} matcher group hooks.{event}[{index}] must contain a hooks array"
+                )
+            parsed_groups.append(group)
+        hooks[event] = parsed_groups
+    return hooks
+
+
+def parse_document(file_path: str, raw: str) -> CodexDocument:
+    label = f"Codex user hooks at {file_path}"
+    root = parse_json_object(raw, label)
+    hooks = _read_hooks(root.get("hooks", {}), label)
+    return CodexDocument(True, file_path, root, hooks, raw)
+
+
+def create_document(file_path: str) -> CodexDocument:
+    return CodexDocument(False, file_path, {"description": OWNED_DESCRIPTION}, {})
+
+
+def _exact_matcher_group(group: JsonObject) -> bool:
+    return set(group) == {"matcher", "hooks"} and group.get("matcher") == "*"
+
+
+def _remove_from_groups(
+    groups: List[JsonObject],
+    script_name: str,
+    status_message: str,
+    agent_id: str,
+) -> List[JsonObject]:
+    result = []
+    for group in groups:
+        handlers = []
+        for handler in group["hooks"]:
+            managed_id = _managed_agent_id(handler, script_name, status_message)
+            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 or not _exact_matcher_group(group):
+            result.append({**group, "hooks": handlers})
+    return result
+
+
+def remove_managed_hooks(hooks: CodexHooks, agent_id: str = "") -> CodexHooks:
+    result = {event: list(groups) for event, groups in hooks.items()}
+    for event, script_name, status_message in (
+        ("PreToolUse", GUARD_SCRIPT, GUARD_STATUS),
+        ("PostToolUse", AUDIT_SCRIPT, AUDIT_STATUS),
+    ):
+        groups = _remove_from_groups(
+            result.get(event, []),
+            script_name,
+            status_message,
+            agent_id,
+        )
+        if groups:
+            result[event] = groups
+        else:
+            result.pop(event, None)
+    return result
+
+
+def _entirely_managed(document: CodexDocument) -> bool:
+    if (
+        not document.exists
+        or document.root.get("description") != OWNED_DESCRIPTION
+        or not set(document.root).issubset({"description", "hooks"})
+        or not document.hooks
+    ):
+        return False
+    count = 0
+    for event, groups in document.hooks.items():
+        contract = {
+            "PreToolUse": (GUARD_SCRIPT, GUARD_STATUS),
+            "PostToolUse": (AUDIT_SCRIPT, AUDIT_STATUS),
+        }.get(event)
+        if contract is None or not groups:
+            return False
+        for group in groups:
+            handlers = group["hooks"]
+            if (
+                not _exact_matcher_group(group)
+                or not handlers
+                or any(
+                    _managed_agent_id(handler, contract[0], contract[1]) is None
+                    for handler in handlers
+                )
+            ):
+                return False
+            count += len(handlers)
+    return count > 0
+
+
+def render_document(document: CodexDocument, hooks: CodexHooks) -> RenderedDocument:
+    if not document.exists and not hooks:
+        return RenderedDocument(document, False)
+    if hooks == document.hooks:
+        return RenderedDocument(document, False)
+    if not hooks and _entirely_managed(document):
+        return RenderedDocument(document, True)
+    root = dict(document.root)
+    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(
+    groups: List[JsonObject],
+    script_name: str,
+    status_message: str,
+) -> Dict[str, str]:
+    result = {}
+    for group in groups:
+        if not _exact_matcher_group(group):
+            continue
+        for handler in group["hooks"]:
+            agent_id = _managed_agent_id(handler, script_name, status_message)
+            if agent_id:
+                result[os.path.normcase(agent_id)] = agent_id
+    return result
+
+
+def runtime_contracts(hooks: CodexHooks) -> List[RuntimeContract]:
+    guards = _managed_ids(hooks.get("PreToolUse", []), GUARD_SCRIPT, GUARD_STATUS)
+    audits = _managed_ids(hooks.get("PostToolUse", []), AUDIT_SCRIPT, AUDIT_STATUS)
+    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/codex_io.py

@@ -0,0 +1,193 @@
+"""Codex hook source and managed runtime I/O."""
+
+from __future__ import annotations
+
+import os
+import stat
+from typing import Any, List, Optional
+
+from ._managed_files import (
+    MAX_CONFIG_BYTES,
+    MAX_SOURCE_BYTES,
+    physical_directory_exists,
+    physical_file_exists,
+    read_physical_file,
+)
+from ._strict_json import JsonObject, parse_json_object
+from ._transaction import FileChange, source_change, write_changes
+from .codex_contract import (
+    AGENT_KEY,
+    CONFIG_FILE,
+    CodexDocument,
+    RenderedDocument,
+    RuntimeContract,
+    create_document,
+    parse_document,
+)
+
+
+def _same_agent_id(value: Any, expected: str) -> bool:
+    return isinstance(value, str) and os.path.normcase(value) == os.path.normcase(
+        expected
+    )
+
+
+def codex_home_path() -> str:
+    configured = os.environ.get("CODEX_HOME")
+    if configured is None or configured == "":
+        return os.path.join(os.path.expanduser("~"), ".codex")
+    try:
+        metadata = os.stat(configured)
+    except OSError as error:
+        raise OSError(f"Resolve CODEX_HOME at {configured}: {error}") from error
+    if not stat.S_ISDIR(metadata.st_mode):
+        raise OSError(f"CODEX_HOME is not a directory: {configured}")
+    try:
+        canonical = os.path.realpath(configured, strict=True)
+    except OSError as error:
+        raise OSError(f"Canonicalize CODEX_HOME at {configured}: {error}") from error
+    if not physical_directory_exists(canonical, "CODEX_HOME"):
+        raise OSError(f"CODEX_HOME is missing: {canonical}")
+    return canonical
+
+
+def config_path() -> str:
+    return os.path.join(codex_home_path(), CONFIG_FILE)
+
+
+def read_document() -> CodexDocument:
+    file_path = config_path()
+    snapshot = read_physical_file(file_path, "Codex user hooks", MAX_SOURCE_BYTES)
+    if snapshot is None:
+        return create_document(file_path)
+    return parse_document(file_path, snapshot.contents)
+
+
+def validate_hooks_directory(file_path: str) -> None:
+    directory = os.path.dirname(file_path)
+    physical_directory_exists(directory, "Codex hooks directory")
+
+
+def rendered_change(rendered: RenderedDocument) -> Optional[FileChange]:
+    if not rendered.changed:
+        return None
+    return source_change(
+        rendered.document.file_path,
+        "Codex user hooks",
+        rendered.document.raw,
+        rendered.next_source,
+        0o600,
+        MAX_SOURCE_BYTES,
+    )
+
+
+def runtime_change(
+    file_path: str,
+    label: str,
+    next_source: str,
+    mode: int,
+    maximum_bytes: int = MAX_SOURCE_BYTES,
+) -> Optional[FileChange]:
+    snapshot = read_physical_file(file_path, label, maximum_bytes)
+    return source_change(
+        file_path,
+        label,
+        None if snapshot is None else snapshot.contents,
+        next_source,
+        mode,
+        maximum_bytes,
+    )
+
+
+def _read_runtime_config(file_path: str) -> Optional[JsonObject]:
+    snapshot = read_physical_file(
+        file_path,
+        "Elydora runtime config",
+        MAX_CONFIG_BYTES,
+    )
+    if snapshot is None:
+        return None
+    return parse_json_object(
+        snapshot.contents,
+        f"Elydora runtime config at {file_path}",
+    )
+
+
+def validate_runtime_identity(agent_directory: str, agent_id: str) -> bool:
+    config_path_value = os.path.join(agent_directory, "config.json")
+    config = _read_runtime_config(config_path_value)
+    artifacts = [
+        ("private.key", "Elydora private key"),
+        ("guard.py", "Elydora guard runtime"),
+        ("hook.py", "Elydora audit runtime"),
+        ("chain-state.json", "Elydora chain state"),
+        ("status-cache.json", "Elydora status cache"),
+        ("error.log", "Elydora error log"),
+    ]
+    artifact_states = [
+        physical_file_exists(os.path.join(agent_directory, name), label)
+        for name, label in artifacts
+    ]
+    artifact_exists = any(artifact_states)
+    if config is None:
+        if artifact_exists:
+            raise ValueError(
+                "Elydora runtime identity cannot be verified without config.json: "
+                f"{agent_directory}"
+            )
+        return False
+    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 Codex agent {agent_id}: "
+            f"{config_path_value}"
+        )
+    return True
+
+
+def validate_runtime_tree(
+    runtime_root: str, agent_directory: str, agent_id: str
+) -> None:
+    if not physical_directory_exists(runtime_root, "Elydora runtime directory"):
+        return
+    if not physical_directory_exists(
+        agent_directory,
+        "Elydora agent runtime directory",
+    ):
+        return
+    validate_runtime_identity(agent_directory, agent_id)
+
+
+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,
+            "Elydora agent runtime directory",
+        ):
+            continue
+        config = _read_runtime_config(os.path.join(agent_directory, "config.json"))
+        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 all(
+            (
+                physical_file_exists(contract.guard_path, "Elydora guard runtime"),
+                physical_file_exists(contract.audit_path, "Elydora audit runtime"),
+                physical_file_exists(
+                    os.path.join(agent_directory, "private.key"),
+                    "Elydora private key",
+                ),
+            )
+        ):
+            return True
+    return False
+
+
+def write_codex_changes(changes: List[FileChange], label: str) -> None:
+    write_changes(changes, label)

sdks/python/elydora/plugins/cursor_contract.py

@@ -9,13 +9,14 @@ import re
 import sys
 from typing import Any, Dict, List, Optional, Tuple
 
+from ._strict_json import JsonObject, parse_json_object
+
 
 AGENT_KEY = "cursor"
 GUARD_SCRIPT = "guard.py"
 AUDIT_SCRIPT = "hook.py"
 HOOK_TIMEOUT_SECONDS = 10
 
-JsonObject = Dict[str, Any]
 CursorHooks = Dict[str, List[JsonObject]]
 
 
@@ -48,10 +49,6 @@ class _ParsedArgument:
     next_index: int
 
 
-class _DuplicateKey(ValueError):
-    pass
-
-
 def runtime_root() -> str:
     return os.path.join(os.path.expanduser("~"), ".elydora")
 
@@ -109,7 +106,10 @@ def _read_posix_argument(command: str, start: int) -> Optional[_ParsedArgument]:
 
 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] != " ":
+    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):
@@ -142,10 +142,13 @@ 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] != " ":
+    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":
+    if script is None or command[script.next_index :] != "; exit $LASTEXITCODE":
         return None
     return executable.value, script.value
 
@@ -196,27 +199,6 @@ def _managed_agent_id(
     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')
@@ -227,9 +209,7 @@ def _read_hooks(value: Any, label: str) -> CursorHooks:
         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'
-            )
+            raise ValueError(f'{label} field "hooks.{event}" must contain objects')
         hooks[event] = list(handlers)
     return hooks
 
@@ -344,9 +324,11 @@ def runtime_contracts(hooks: CursorHooks) -> List[RuntimeContract]:
         if key not in audits or key not in failures:
             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),
-        ))
+        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/guard_template.py

@@ -65,15 +65,29 @@ def read_input():
     if not raw.strip():
         if FAIL_CLOSED:
             raise ValueError("Hook input is empty")
+        sys.stderr.write(
+            "[Elydora guard] Hook input is empty; "
+            "enforcement continued in fail-open mode.\\n"
+        )
         return
     try:
         value = json.loads(raw)
     except (json.JSONDecodeError, ValueError) as error:
         if FAIL_CLOSED:
             raise ValueError("Hook input is invalid JSON: " + str(error)) from error
+        sys.stderr.write(
+            "[Elydora guard] Hook input is invalid JSON; "
+            "enforcement continued in fail-open mode: " + str(error) + "\\n"
+        )
+        return
+    if not isinstance(value, dict):
+        if FAIL_CLOSED:
+            raise ValueError("Hook input must contain a JSON object")
+        sys.stderr.write(
+            "[Elydora guard] Hook input must contain a JSON object; "
+            "enforcement continued in fail-open mode.\\n"
+        )
         return
-    if FAIL_CLOSED and not isinstance(value, dict):
-        raise ValueError("Hook input must contain a JSON object")
 
 
 def read_config():
@@ -102,7 +116,6 @@ def read_status_cache():
             STATUS_CACHE_PATH,
             "Status cache",
             MAX_PROTECTED_CONFIG_BYTES,
-            require_private_permissions=False,
         ).decode("utf-8")
     except FileNotFoundError:
         return None
@@ -124,34 +137,39 @@ def read_status_cache():
 
 
 def write_status_cache(status):
-    token = os.urandom(8).hex()
-    temporary_path = STATUS_CACHE_PATH + "." + str(os.getpid()) + "." + token + ".tmp"
-    descriptor = -1
-    try:
-        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0)
-        descriptor = os.open(temporary_path, flags, 0o600)
-        with os.fdopen(descriptor, "w", encoding="utf-8") as file:
-            descriptor = -1
-            json.dump({{"status": status, "cached_at": time.time()}}, file)
-            file.flush()
-            os.fsync(file.fileno())
-        os.replace(temporary_path, STATUS_CACHE_PATH)
-    finally:
-        if descriptor >= 0:
-            os.close(descriptor)
-        try:
-            os.remove(temporary_path)
-        except FileNotFoundError:
-            pass
+    write_protected_json(
+        STATUS_CACHE_PATH,
+        "Status cache",
+        {{"status": status, "cached_at": time.time()}},
+    )
 
 
 def resolve_remote_status(config):
     base_url = config.get("base_url", "https://api.elydora.com")
     if not isinstance(base_url, str):
         raise ValueError("Agent config base_url must be a string")
-    parsed = urllib.parse.urlsplit(base_url)
-    if parsed.scheme not in ("http", "https"):
-        raise ValueError("Agent config base_url must use HTTP or HTTPS")
+    try:
+        parsed = urllib.parse.urlsplit(base_url)
+        hostname = parsed.hostname
+        parsed.port
+    except ValueError as error:
+        raise ValueError(
+            "Agent config base_url must be an absolute HTTP or HTTPS URL"
+        ) from error
+    invalid_character = "\\\\" in base_url or any(
+        character.isspace() or ord(character) < 32 for character in base_url
+    )
+    if (
+        parsed.scheme not in ("http", "https")
+        or not parsed.netloc
+        or hostname is None
+        or invalid_character
+    ):
+        raise ValueError("Agent config base_url must be an absolute HTTP or HTTPS URL")
+    if parsed.username is not None or parsed.password is not None or parsed.query or parsed.fragment:
+        raise ValueError(
+            "Agent config base_url must exclude credentials, query parameters, and fragments"
+        )
     token = config.get("token", "")
     if not isinstance(token, str):
         raise ValueError("Agent config token must be a string")

sdks/python/elydora/plugins/hook_template.py

@@ -39,11 +39,8 @@ import urllib.error
 import urllib.parse
 import urllib.request
 
-ORG_ID = {org_id!r}
 AGENT_ID = {agent_id!r}
 AGENT_NAME = {agent_name!r}
-KID = {kid!r}
-BASE_URL = {base_url!r}
 SUCCESS_OUTPUT = {success_output!r}
 FAIL_CLOSED = {fail_closed!r}
 NATIVE_PAYLOAD = {native_payload!r}
@@ -139,27 +136,16 @@ def generate_uuidv7():
 
 
 def log_error(error):
-    descriptor = -1
     try:
         message = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
         message += " [elydora-hook] " + repr(error) + "\\n"
-        flags = os.O_WRONLY | os.O_APPEND | os.O_CREAT
-        flags |= getattr(os, "O_BINARY", 0) | getattr(os, "O_CLOEXEC", 0)
-        flags |= getattr(os, "O_NOFOLLOW", 0)
-        descriptor = os.open(ERROR_LOG_PATH, flags, 0o600)
-        metadata = os.fstat(descriptor)
-        if not stat.S_ISREG(metadata.st_mode):
-            raise ValueError("Error log path is not a physical file: " + ERROR_LOG_PATH)
-        with os.fdopen(descriptor, "a", encoding="utf-8") as file:
-            descriptor = -1
-            file.write(message)
-        if os.name != "nt":
-            os.chmod(ERROR_LOG_PATH, 0o600)
+        append_protected_text(ERROR_LOG_PATH, "Error log", message)
     except Exception as log_failure:
-        sys.stderr.write("[Elydora audit] Failed to write error log: " + str(log_failure) + "\\n")
-    finally:
-        if descriptor >= 0:
-            os.close(descriptor)
+        sys.stderr.write(
+            "[Elydora audit] Failed to write error log: "
+            + str(log_failure)
+            + "\\n"
+        )
 
 
 def read_chain_state():
@@ -168,64 +154,30 @@ def read_chain_state():
             CHAIN_STATE_PATH,
             "Chain state",
             MAX_PROTECTED_CONFIG_BYTES,
-            require_private_permissions=False,
         ).decode("utf-8")
     except FileNotFoundError:
         return ZERO_CHAIN_HASH
     except Exception as error:
-        if FAIL_CLOSED:
-            raise RuntimeError("Failed to read chain state: " + str(error)) from error
-        log_error(error)
-        return ZERO_CHAIN_HASH
+        raise RuntimeError("Failed to read chain state: " + str(error)) from error
     try:
         state = json.loads(raw)
     except (json.JSONDecodeError, ValueError) as error:
-        if FAIL_CLOSED:
-            raise RuntimeError("Chain state is invalid JSON: " + str(error)) from error
-        log_error(error)
-        return ZERO_CHAIN_HASH
+        raise RuntimeError("Chain state is invalid JSON: " + str(error)) from error
     previous = state.get("prev_chain_hash") if isinstance(state, dict) else None
     if not isinstance(previous, str) or re.fullmatch(r"[A-Za-z0-9_-]{{43}}", previous) is None:
-        error = ValueError("Chain state contains an invalid prev_chain_hash")
-        if FAIL_CLOSED:
-            raise error
-        log_error(error)
-        return ZERO_CHAIN_HASH
+        raise ValueError("Chain state contains an invalid prev_chain_hash")
     return previous
 
 
 def write_chain_state(chain_hash):
-    token = os.urandom(8).hex()
-    temporary_path = CHAIN_STATE_PATH + "." + str(os.getpid()) + "." + token + ".tmp"
-    descriptor = -1
-    try:
-        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0)
-        descriptor = os.open(temporary_path, flags, 0o600)
-        with os.fdopen(descriptor, "w", encoding="utf-8") as file:
-            descriptor = -1
-            json.dump({{"prev_chain_hash": chain_hash}}, file)
-            file.flush()
-            os.fsync(file.fileno())
-        os.replace(temporary_path, CHAIN_STATE_PATH)
-    finally:
-        if descriptor >= 0:
-            os.close(descriptor)
-        try:
-            os.remove(temporary_path)
-        except FileNotFoundError:
-            pass
+    write_protected_json(
+        CHAIN_STATE_PATH,
+        "Chain state",
+        {{"prev_chain_hash": chain_hash}},
+    )
 
 
 def read_runtime_config():
-    if not FAIL_CLOSED:
-        return {{
-            "org_id": ORG_ID,
-            "agent_id": AGENT_ID,
-            "agent_name": AGENT_NAME,
-            "kid": KID,
-            "base_url": BASE_URL,
-            "token": "",
-        }}
     try:
         raw = read_protected_file(
             CONFIG_PATH,
@@ -237,7 +189,9 @@ def read_runtime_config():
         raise RuntimeError("Failed to read agent config: " + str(error)) from error
     if not isinstance(config, dict):
         raise ValueError("Agent config must contain a JSON object")
-    if config.get("agent_id") != AGENT_ID or config.get("agent_name") != AGENT_NAME:
+    if config.get("agent_id") != AGENT_ID:
+        raise ValueError("Agent config identity does not match the generated audit hook")
+    if AGENT_NAME and config.get("agent_name") != AGENT_NAME:
         raise ValueError("Agent config identity does not match the generated audit hook")
     for field in ("org_id", "agent_id", "kid"):
         if not isinstance(config.get(field), str) or not config[field]:
@@ -245,8 +199,28 @@ def read_runtime_config():
     base_url = config.get("base_url", "https://api.elydora.com")
     if not isinstance(base_url, str):
         raise ValueError("Agent config base_url must be a string")
-    if urllib.parse.urlsplit(base_url).scheme not in ("http", "https"):
-        raise ValueError("Agent config base_url must use HTTP or HTTPS")
+    try:
+        parsed = urllib.parse.urlsplit(base_url)
+        hostname = parsed.hostname
+        parsed.port
+    except ValueError as error:
+        raise ValueError(
+            "Agent config base_url must be an absolute HTTP or HTTPS URL"
+        ) from error
+    invalid_character = "\\\\" in base_url or any(
+        character.isspace() or ord(character) < 32 for character in base_url
+    )
+    if (
+        parsed.scheme not in ("http", "https")
+        or not parsed.netloc
+        or hostname is None
+        or invalid_character
+    ):
+        raise ValueError("Agent config base_url must be an absolute HTTP or HTTPS URL")
+    if parsed.username is not None or parsed.password is not None or parsed.query or parsed.fragment:
+        raise ValueError(
+            "Agent config base_url must exclude credentials, query parameters, and fragments"
+        )
     if not isinstance(config.get("token", ""), str):
         raise ValueError("Agent config token must be a string")
     return config

sdks/python/elydora/plugins/runtime_reader_template.py

@@ -1,35 +1,40 @@
-"""Protected runtime-file reader embedded in generated hook scripts."""
+"""Protected runtime-file primitives embedded in generated hook scripts."""
 
-PROTECTED_RUNTIME_READER = r'''
+PROTECTED_RUNTIME_READER = r"""
 MAX_PROTECTED_SECRET_BYTES = 64 * 1024
 MAX_PROTECTED_CONFIG_BYTES = 512 * 1024
+MAX_PROTECTED_LOG_BYTES = 2 * 1024 * 1024
+
+
+def validate_protected_metadata(metadata, file_path, label, max_bytes):
+    if not stat.S_ISREG(metadata.st_mode):
+        raise ValueError(label + " path is not a physical file: " + file_path)
+    if metadata.st_size > max_bytes:
+        raise ValueError(label + " exceeds the size limit: " + file_path)
+    if os.name != "nt" and metadata.st_mode & (stat.S_IRWXG | stat.S_IRWXO):
+        raise PermissionError(label + " permissions are too broad: " + file_path)
+
+
+def inspect_protected_file(file_path, label, max_bytes):
+    metadata = os.lstat(file_path)
+    if stat.S_ISLNK(metadata.st_mode):
+        raise ValueError(label + " path is not a physical file: " + file_path)
+    validate_protected_metadata(metadata, file_path, label, max_bytes)
+    return metadata
 
 
 def read_protected_file(
     file_path,
     label,
     max_bytes=MAX_PROTECTED_SECRET_BYTES,
-    require_private_permissions=True,
 ):
-    before = os.lstat(file_path)
-    if not stat.S_ISREG(before.st_mode) or stat.S_ISLNK(before.st_mode):
-        raise ValueError(label + " path is not a physical file: " + file_path)
-    if before.st_size > max_bytes:
-        raise ValueError(label + " exceeds the size limit: " + file_path)
-    if require_private_permissions and os.name != "nt" and before.st_mode & (stat.S_IRWXG | stat.S_IRWXO):
-        raise PermissionError(label + " permissions are too broad: " + file_path)
-
+    before = inspect_protected_file(file_path, label, max_bytes)
     flags = os.O_RDONLY | getattr(os, "O_BINARY", 0) | getattr(os, "O_CLOEXEC", 0)
     flags |= getattr(os, "O_NOFOLLOW", 0)
     descriptor = os.open(file_path, flags)
     try:
         after = os.fstat(descriptor)
-        if not stat.S_ISREG(after.st_mode):
-            raise ValueError(label + " path is not a physical file: " + file_path)
-        if after.st_size > max_bytes:
-            raise ValueError(label + " exceeds the size limit: " + file_path)
-        if require_private_permissions and os.name != "nt" and after.st_mode & (stat.S_IRWXG | stat.S_IRWXO):
-            raise PermissionError(label + " permissions are too broad: " + file_path)
+        validate_protected_metadata(after, file_path, label, max_bytes)
         if (before.st_dev, before.st_ino) != (after.st_dev, after.st_ino):
             raise OSError(label + " changed while opening: " + file_path)
         with os.fdopen(descriptor, "rb") as file:
@@ -41,4 +46,112 @@ def read_protected_file(
     if len(value) > max_bytes:
         raise ValueError(label + " exceeds the size limit: " + file_path)
     return value
-'''
+
+
+def open_protected_append(file_path, label, max_bytes):
+    for _attempt in range(3):
+        try:
+            before = inspect_protected_file(file_path, label, max_bytes)
+        except FileNotFoundError:
+            flags = os.O_WRONLY | os.O_APPEND | os.O_CREAT | os.O_EXCL
+            flags |= getattr(os, "O_BINARY", 0) | getattr(os, "O_CLOEXEC", 0)
+            flags |= getattr(os, "O_NOFOLLOW", 0)
+            try:
+                descriptor = os.open(file_path, flags, 0o600)
+            except FileExistsError:
+                continue
+            try:
+                validate_protected_metadata(
+                    os.fstat(descriptor),
+                    file_path,
+                    label,
+                    max_bytes,
+                )
+                return descriptor
+            except Exception:
+                os.close(descriptor)
+                raise
+
+        flags = os.O_WRONLY | os.O_APPEND
+        flags |= getattr(os, "O_BINARY", 0) | getattr(os, "O_CLOEXEC", 0)
+        flags |= getattr(os, "O_NOFOLLOW", 0)
+        descriptor = os.open(file_path, flags)
+        try:
+            after = os.fstat(descriptor)
+            validate_protected_metadata(after, file_path, label, max_bytes)
+            if (before.st_dev, before.st_ino) != (after.st_dev, after.st_ino):
+                raise OSError(label + " changed while opening: " + file_path)
+            return descriptor
+        except Exception:
+            os.close(descriptor)
+            raise
+    raise OSError(label + " changed repeatedly while opening: " + file_path)
+
+
+def append_protected_text(
+    file_path,
+    label,
+    text,
+    max_bytes=MAX_PROTECTED_LOG_BYTES,
+):
+    encoded = text.encode("utf-8")
+    descriptor = open_protected_append(file_path, label, max_bytes)
+    try:
+        metadata = os.fstat(descriptor)
+        if metadata.st_size + len(encoded) > max_bytes:
+            raise ValueError(label + " exceeds the size limit: " + file_path)
+        offset = 0
+        while offset < len(encoded):
+            written = os.write(descriptor, encoded[offset:])
+            if written <= 0:
+                raise OSError(label + " write made no progress: " + file_path)
+            offset += written
+        os.fsync(descriptor)
+        if os.name != "nt":
+            os.fchmod(descriptor, 0o600)
+    finally:
+        os.close(descriptor)
+
+
+def write_protected_json(file_path, label, value):
+    encoded = json.dumps(value, separators=(",", ":")).encode("utf-8")
+    if len(encoded) > MAX_PROTECTED_CONFIG_BYTES:
+        raise ValueError(label + " exceeds the size limit: " + file_path)
+    temporary_path = (
+        file_path
+        + "."
+        + str(os.getpid())
+        + "."
+        + os.urandom(8).hex()
+        + ".tmp"
+    )
+    descriptor = -1
+    try:
+        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+        flags |= getattr(os, "O_BINARY", 0) | getattr(os, "O_CLOEXEC", 0)
+        flags |= getattr(os, "O_NOFOLLOW", 0)
+        descriptor = os.open(temporary_path, flags, 0o600)
+        with os.fdopen(descriptor, "wb") as file:
+            descriptor = -1
+            file.write(encoded)
+            file.flush()
+            os.fsync(file.fileno())
+        if os.name != "nt":
+            os.chmod(temporary_path, 0o600)
+        try:
+            inspect_protected_file(
+                file_path,
+                label,
+                MAX_PROTECTED_CONFIG_BYTES,
+            )
+        except FileNotFoundError:
+            pass
+        os.replace(temporary_path, file_path)
+    finally:
+        if descriptor >= 0:
+            os.close(descriptor)
+        try:
+            os.remove(temporary_path)
+        except FileNotFoundError:
+            pass
+"""