sernixa-cli 0.1.1__py3-none-any.whl

sernixa_cli/local_agent_targets.py

@@ -0,0 +1,1031 @@
+from __future__ import annotations
+
+import copy
+import json
+import os
+import platform
+import re
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+
+Provider = Literal["claude", "codex"]
+TargetID = Literal["claude", "claude-desktop", "codex"]
+ConfigFormat = Literal["json", "toml"]
+
+SERNIXA_TOML_BEGIN = "# BEGIN SERNIXA MANAGED CODEX HOOK"
+SERNIXA_TOML_END = "# END SERNIXA MANAGED CODEX HOOK"
+
+
+class TargetConfigError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class TargetCandidate:
+    path: Path
+    config_format: ConfigFormat
+    role: str
+    exists: bool
+
+
+@dataclass(frozen=True)
+class TargetResolution:
+    target_id: TargetID
+    display_name: str
+    provider: Provider
+    selected_path: Path
+    selected_format: ConfigFormat
+    config_scope: str
+    install_mechanism: str
+    status_detection: str
+    candidates: tuple[TargetCandidate, ...]
+    selected_reason: str
+    uncertainty: str | None = None
+
+
+@dataclass(frozen=True)
+class TargetStatus:
+    target_id: TargetID
+    target_name: str
+    provider: Provider
+    supported: bool
+    primary_write_target: Path
+    selected_format: ConfigFormat
+    config_scope: str
+    install_mode: str
+    status_detection: str
+    candidates: tuple[TargetCandidate, ...]
+    detected_sources: tuple[str, ...]
+    sernixa_installed: bool
+    sernixa_installed_in: tuple[str, ...]
+    wrapper_valid: bool
+    malformed: bool
+    parse_errors: tuple[str, ...]
+    stale_reasons: tuple[str, ...]
+    selected_reason: str
+    uncertainty: str | None
+    repair_hint_override: str | None = None
+    detected_hook_sources: tuple[str, ...] = ()
+    inline_toml_hooks_present: bool = False
+    hooks_json_present: bool = False
+    hooks_declared: bool = False
+    hooks_enabled: bool = False
+    hooks_effective: bool = False
+    activation_hint: str | None = None
+    hook_activation: dict[str, dict[str, bool]] | None = None
+
+    @property
+    def selected_path(self) -> Path:
+        return self.primary_write_target
+
+    @property
+    def installed(self) -> bool:
+        return self.sernixa_installed
+
+    @property
+    def parse_error(self) -> str | None:
+        return self.parse_errors[0] if self.parse_errors else None
+
+    @property
+    def install_command(self) -> str:
+        return f"sernixa hook install {self.target_id}"
+
+    @property
+    def run_command(self) -> str:
+        return f"sernixa hook run {self.provider}"
+
+    @property
+    def repair_hint(self) -> str | None:
+        if self.repair_hint_override:
+            return self.repair_hint_override
+        if self.parse_errors:
+            return (
+                f"Fix or move the invalid config at {self.primary_write_target}, then rerun "
+                f"{self.install_command}."
+            )
+        if self.malformed:
+            return f"Run sernixa hook repair {self.target_id} to normalize Sernixa-managed entries."
+        if not self.sernixa_installed:
+            return f"Run {self.install_command} to add the Sernixa wrapper."
+        return None
+
+    @property
+    def existing_paths(self) -> tuple[Path, ...]:
+        return tuple(candidate.path for candidate in self.candidates if candidate.exists)
+
+    @property
+    def alternate_files_found(self) -> tuple[Path, ...]:
+        return tuple(path for path in self.existing_paths if path != self.primary_write_target)
+
+    def to_dict(self) -> dict[str, Any]:
+        existing_paths = [_status_path(path) for path in self.existing_paths]
+        candidate_paths = [_status_path(candidate.path) for candidate in self.candidates]
+        primary_write_target = _status_path(self.primary_write_target)
+        return {
+            "target_id": self.target_id,
+            "target": self.target_id,
+            "target_name": self.target_name,
+            "supported": self.supported,
+            "provider": self.provider,
+            "primary_write_target": primary_write_target,
+            "selected_path": primary_write_target,
+            "path": primary_write_target,
+            "candidate_paths": candidate_paths,
+            "paths": candidate_paths,
+            "existing_paths": existing_paths,
+            "file_exists": self.primary_write_target.exists(),
+            "config_format": self.selected_format,
+            "config_scope": self.config_scope,
+            "install_mode": self.install_mode,
+            "install_mechanism": self.install_mode,
+            "status_detection": self.status_detection,
+            "detected_sources": list(self.detected_sources),
+            "detected_hook_sources": list(self.detected_hook_sources),
+            "sernixa_installed": self.sernixa_installed,
+            "sernixa_installed_in": list(self.sernixa_installed_in),
+            "installed": self.sernixa_installed,
+            "detected": self.sernixa_installed,
+            "wrapper_valid": self.wrapper_valid,
+            "malformed": self.malformed,
+            "parse_errors": list(self.parse_errors),
+            "parse_error": self.parse_errors[0] if self.parse_errors else None,
+            "stale_reasons": list(self.stale_reasons),
+            "stale_reason": self.stale_reasons[0] if self.stale_reasons else None,
+            "selected_reason": self.selected_reason,
+            "uncertainty": self.uncertainty,
+            "alternate_files_found": [
+                _status_path(path)
+                for path in self.existing_paths
+                if path != self.primary_write_target
+            ],
+            "inline_toml_hooks_present": self.inline_toml_hooks_present,
+            "hooks_json_present": self.hooks_json_present,
+            "hooks_declared": self.hooks_declared,
+            "hooks_enabled": self.hooks_enabled,
+            "hooks_effective": self.hooks_effective,
+            "activation_hint": self.activation_hint,
+            "hook_activation": self.hook_activation or {},
+            "install_command": self.install_command,
+            "run_command": self.run_command,
+            "repair_hint": self.repair_hint,
+        }
+
+
+SUPPORTED_TARGETS: tuple[TargetID, ...] = ("claude", "claude-desktop", "codex")
+
+TARGET_DISPLAY_NAMES: dict[TargetID, str] = {
+    "claude": "Claude Code",
+    "claude-desktop": "Claude Desktop",
+    "codex": "Codex",
+}
+
+TARGET_METADATA: dict[TargetID, tuple[Provider, str, str, str]] = {
+    "claude": (
+        "claude",
+        "global user config",
+        "hook block",
+        "JSON hooks.PreToolUse command wrapper",
+    ),
+    "claude-desktop": (
+        "claude",
+        "global app config",
+        "MCP server block",
+        "JSON mcpServers.sernixa-governance wrapper",
+    ),
+    "codex": (
+        "codex",
+        "global user config",
+        "hook block",
+        "Codex user hooks.json or config.toml Sernixa block",
+    ),
+}
+
+
+def normalize_target(target: str) -> TargetID:
+    normalized = target.strip().lower().replace("_", "-")
+    aliases: dict[str, TargetID] = {
+        "claude": "claude",
+        "claude-code": "claude",
+        "claude-cli": "claude",
+        "claude-desktop": "claude-desktop",
+        "codex": "codex",
+    }
+    try:
+        return aliases[normalized]
+    except KeyError as exc:
+        supported = ", ".join(SUPPORTED_TARGETS)
+        raise TargetConfigError(f"Unsupported local agent target '{target}'. Supported targets: {supported}.") from exc
+
+
+def resolve_local_agent_target(
+    target_name: str,
+    *,
+    os_name: str | None = None,
+    env: dict[str, str] | None = None,
+    home: Path | None = None,
+) -> TargetResolution:
+    target_id = normalize_target(target_name)
+    system = os_name or platform.system()
+    env_map = dict(os.environ if env is None else env)
+    home_path = _absolute_path(home or Path.home(), env_map)
+    provider, config_scope, install_mechanism, status_detection = TARGET_METADATA[target_id]
+    if target_id == "claude":
+        candidates = (
+            TargetCandidate(
+                _env_or_default(
+                    "SERNIXA_CLAUDE_CONFIG_FILE",
+                    home_path / ".claude" / "settings.json",
+                    env_map,
+                ),
+                "json",
+                "Claude Code user settings",
+                False,
+            ),
+        )
+        candidates = _with_exists(candidates)
+        selected = candidates[0]
+        return _resolution(
+            target_id,
+            provider,
+            selected,
+            candidates,
+            config_scope,
+            install_mechanism,
+            status_detection,
+            "legacy override" if env_map.get("SERNIXA_CLAUDE_CONFIG_FILE") else "Claude Code user settings default",
+        )
+    if target_id == "claude-desktop":
+        return _resolve_claude_desktop(
+            target_id,
+            provider,
+            config_scope,
+            install_mechanism,
+            status_detection,
+            system,
+            env_map,
+            home_path,
+        )
+    return _resolve_codex(
+        target_id,
+        provider,
+        config_scope,
+        install_mechanism,
+        status_detection,
+        env_map,
+        home_path,
+    )
+
+
+def hook_snippet(target_name: str) -> dict[str, Any]:
+    target_id = normalize_target(target_name)
+    provider = TARGET_METADATA[target_id][0]
+    command = ["sernixa", "hook", "run", provider]
+    if target_id == "claude-desktop":
+        return {
+            "mcpServers": {
+                "sernixa-governance": {
+                    "command": command[0],
+                    "args": command[1:],
+                    "env": {},
+                }
+            }
+        }
+    if target_id == "claude":
+        handler = {
+            "type": "command",
+            "command": command[0],
+            "args": command[1:],
+            "timeout": 10,
+            "statusMessage": "Checking Sernixa policy",
+        }
+    else:
+        handler = {
+            "type": "command",
+            "command": " ".join(command),
+            "timeout": 10,
+            "statusMessage": "Checking Sernixa policy",
+        }
+    return {"hooks": {"PreToolUse": [{"matcher": "*", "hooks": [handler]}]}}
+
+
+def install_target(target_name: str) -> tuple[TargetResolution, str, Path | None]:
+    resolution = resolve_local_agent_target(target_name)
+    path = resolution.selected_path
+    changed = False
+    if resolution.selected_format == "toml":
+        before = _read_text_or_empty(path)
+        after = _merge_codex_toml(path, before)
+        changed = before != after
+        backup_path = _backup(path) if path.exists() and changed else None
+        _write_private_text(path, after)
+    else:
+        existing = _read_json_object(path) if path.exists() else {}
+        snippet = hook_snippet(resolution.target_id)
+        if resolution.target_id == "claude-desktop":
+            merged, changed = _merge_mcp_server(existing, snippet, path)
+        else:
+            merged, changed = _merge_hooks(existing, snippet, resolution.provider)
+        backup_path = _backup(path) if path.exists() and changed else None
+        _write_private_text(path, json.dumps(merged, indent=2, sort_keys=True) + "\n")
+    return resolution, "installed" if changed else "updated", backup_path
+
+
+def target_status(target_name: str) -> TargetStatus:
+    resolution = resolve_local_agent_target(target_name)
+    if resolution.target_id == "codex":
+        return _codex_status(resolution)
+    parse_errors: list[str] = []
+    detected_sources: list[str] = []
+    installed_in: list[str] = []
+    stale_reasons: list[str] = []
+    malformed = False
+    wrapper_valid = False
+    path = resolution.selected_path
+    if path.exists():
+        detected_sources.append(resolution.target_id)
+        try:
+            parsed = _read_json_object(path)
+            if resolution.target_id == "claude-desktop":
+                _validate_claude_desktop_config_shape(parsed, path)
+                state = _mcp_server_state(parsed)
+            else:
+                state = _hook_state(parsed, resolution.provider)
+            wrapper_valid = state == "valid"
+            malformed = state == "malformed"
+            if wrapper_valid:
+                installed_in.append(resolution.target_id)
+            if malformed:
+                stale_reasons.append(
+                    "A Sernixa-managed entry exists but its wrapper command is stale or malformed."
+                )
+        except (OSError, TargetConfigError, json.JSONDecodeError) as exc:
+            parse_errors.append(str(exc))
+            malformed = True
+    return TargetStatus(
+        target_id=resolution.target_id,
+        target_name=resolution.display_name,
+        provider=resolution.provider,
+        supported=True,
+        primary_write_target=path,
+        selected_format=resolution.selected_format,
+        config_scope=resolution.config_scope,
+        install_mode=resolution.install_mechanism,
+        status_detection=resolution.status_detection,
+        candidates=resolution.candidates,
+        detected_sources=tuple(detected_sources),
+        sernixa_installed=bool(installed_in),
+        sernixa_installed_in=tuple(installed_in),
+        wrapper_valid=wrapper_valid,
+        malformed=malformed,
+        parse_errors=tuple(parse_errors),
+        stale_reasons=tuple(stale_reasons),
+        selected_reason=resolution.selected_reason,
+        uncertainty=resolution.uncertainty,
+        detected_hook_sources=tuple(detected_sources),
+    )
+
+
+def all_target_statuses() -> dict[str, dict[str, Any]]:
+    return {target: target_status(target).to_dict() for target in SUPPORTED_TARGETS}
+
+
+def repair_target(target_name: str) -> tuple[TargetResolution, str, tuple[Path, ...]]:
+    resolution = resolve_local_agent_target(target_name)
+    status = target_status(target_name)
+    backups: list[Path] = []
+    changed = False
+    if resolution.target_id == "codex":
+        primary = resolution.selected_path.resolve(strict=False)
+        for candidate in resolution.candidates:
+            if not candidate.exists:
+                continue
+            if candidate.config_format == "json":
+                parsed = _read_json_object(candidate.path)
+                if candidate.path.resolve(strict=False) == primary:
+                    merged, candidate_changed = _merge_hooks(parsed, hook_snippet("codex"), "codex")
+                else:
+                    merged, candidate_changed = _remove_sernixa_json_hooks(parsed, "codex")
+                if candidate_changed:
+                    backups.append(_backup(candidate.path))
+                    _write_private_text(candidate.path, json.dumps(merged, indent=2) + "\n")
+                    changed = True
+            else:
+                before = _read_text_or_empty(candidate.path)
+                if candidate.path.resolve(strict=False) == primary:
+                    after = _merge_codex_toml(candidate.path, before)
+                else:
+                    after = _remove_sernixa_toml_block(before)
+                if after != before:
+                    backups.append(_backup(candidate.path))
+                    _write_private_text(candidate.path, after)
+                    changed = True
+    else:
+        if status.parse_errors:
+            raise TargetConfigError("; ".join(status.parse_errors))
+        if not status.primary_write_target.exists():
+            resolution, install_status, backup = install_target(target_name)
+            return resolution, install_status, tuple(path for path in (backup,) if path)
+        parsed = _read_json_object(status.primary_write_target)
+        if resolution.target_id == "claude-desktop":
+            _validate_claude_desktop_config_shape(parsed, status.primary_write_target)
+            merged, changed = _merge_mcp_server(parsed, hook_snippet("claude-desktop"), status.primary_write_target)
+        else:
+            merged, changed = _merge_hooks(parsed, hook_snippet("claude"), "claude")
+        if changed:
+            backups.append(_backup(status.primary_write_target))
+            _write_private_text(status.primary_write_target, json.dumps(merged, indent=2) + "\n")
+    return resolution, "repaired" if changed else "already_valid", tuple(backups)
+
+
+def _codex_status(resolution: TargetResolution) -> TargetStatus:
+    parse_errors: list[str] = []
+    detected_sources: list[str] = []
+    detected_hook_sources: list[str] = []
+    installed_in: list[str] = []
+    stale_reasons: list[str] = []
+    malformed_sources: list[str] = []
+    hooks_json_present = False
+    inline_toml_hooks_present = False
+    hook_activation: dict[str, dict[str, bool]] = {
+        "hooks_json": {"declared": False, "enabled": False, "effective": False},
+        "config_toml": {"declared": False, "enabled": False, "effective": False},
+    }
+
+    for candidate in resolution.candidates:
+        if not candidate.exists:
+            continue
+        source_id = _codex_source_id(candidate)
+        detected_sources.append(source_id)
+        if source_id == "hooks_json":
+            hooks_json_present = True
+        try:
+            if candidate.config_format == "json":
+                parsed = _read_json_object(candidate.path)
+                declared = _json_hooks_declared(parsed)
+                if declared:
+                    detected_hook_sources.append(source_id)
+                hook_activation[source_id]["declared"] = declared
+                hook_activation[source_id]["enabled"] = declared
+                state = _hook_state(parsed, "codex")
+            else:
+                text = candidate.path.read_text(encoding="utf-8")
+                parsed_toml = tomllib.loads(text) if text.strip() else {}
+                inline_toml_hooks_present = isinstance(parsed_toml.get("hooks"), dict)
+                if inline_toml_hooks_present:
+                    detected_hook_sources.append(source_id)
+                hook_activation[source_id]["declared"] = inline_toml_hooks_present
+                hook_activation[source_id]["enabled"] = _toml_hooks_enabled(parsed_toml)
+                state = _toml_hook_state(text, parsed_toml)
+            if state == "valid":
+                installed_in.append(source_id)
+                hook_activation[source_id]["effective"] = hook_activation[source_id]["enabled"]
+            elif state == "malformed":
+                malformed_sources.append(source_id)
+                stale_reasons.append(
+                    f"{source_id} contains a Sernixa-managed hook with stale or malformed wrapper args."
+                )
+        except tomllib.TOMLDecodeError as exc:
+            parse_errors.append(_format_toml_error(candidate.path, exc))
+        except (OSError, TargetConfigError, json.JSONDecodeError) as exc:
+            parse_errors.append(str(exc))
+
+    duplicate_install = len(installed_in) > 1
+    malformed = bool(parse_errors or malformed_sources or duplicate_install)
+    wrapper_valid = bool(installed_in) and not malformed_sources and not parse_errors
+    repair_hint_override = None
+    activation_hint = _codex_activation_hint(hook_activation)
+    if duplicate_install:
+        repair_hint_override = (
+            "Duplicate Sernixa Codex hooks were found in multiple global config files. "
+            "Run sernixa hook repair codex to keep the primary write target and remove duplicate managed entries."
+        )
+    return TargetStatus(
+        target_id=resolution.target_id,
+        target_name=resolution.display_name,
+        provider=resolution.provider,
+        supported=True,
+        primary_write_target=resolution.selected_path,
+        selected_format=resolution.selected_format,
+        config_scope=resolution.config_scope,
+        install_mode=resolution.install_mechanism,
+        status_detection=resolution.status_detection,
+        candidates=resolution.candidates,
+        detected_sources=tuple(detected_sources),
+        sernixa_installed=bool(installed_in),
+        sernixa_installed_in=tuple(installed_in),
+        wrapper_valid=wrapper_valid,
+        malformed=malformed,
+        parse_errors=tuple(parse_errors),
+        stale_reasons=tuple(stale_reasons),
+        selected_reason=resolution.selected_reason,
+        uncertainty=resolution.uncertainty,
+        repair_hint_override=repair_hint_override,
+        detected_hook_sources=tuple(detected_hook_sources),
+        inline_toml_hooks_present=inline_toml_hooks_present,
+        hooks_json_present=hooks_json_present,
+        hooks_declared=any(item["declared"] for item in hook_activation.values()),
+        hooks_enabled=any(item["enabled"] for item in hook_activation.values()),
+        hooks_effective=any(item["effective"] for item in hook_activation.values()),
+        activation_hint=activation_hint,
+        hook_activation=hook_activation,
+    )
+
+
+def _resolve_claude_desktop(
+    target_id: TargetID,
+    provider: Provider,
+    config_scope: str,
+    install_mechanism: str,
+    status_detection: str,
+    system: str,
+    env_map: dict[str, str],
+    home_path: Path,
+) -> TargetResolution:
+    override = env_map.get("SERNIXA_CLAUDE_DESKTOP_CONFIG_FILE", "").strip()
+    if override:
+        candidates = _with_exists((TargetCandidate(_absolute_path(override, env_map), "json", "env override", False),))
+        return _resolution(
+            target_id,
+            provider,
+            candidates[0],
+            candidates,
+            config_scope,
+            install_mechanism,
+            status_detection,
+            "SERNIXA_CLAUDE_DESKTOP_CONFIG_FILE override",
+        )
+    if system == "Darwin":
+        candidates = (
+            TargetCandidate(
+                home_path / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json",
+                "json",
+                "macOS documented Claude Desktop config",
+                False,
+            ),
+        )
+        uncertainty = None
+    elif system == "Windows":
+        appdata = env_map.get("APPDATA")
+        localappdata = env_map.get("LOCALAPPDATA")
+        primary = _absolute_path(appdata, env_map) / "Claude" / "claude_desktop_config.json" if appdata else home_path / "AppData" / "Roaming" / "Claude" / "claude_desktop_config.json"
+        fallback_paths: list[Path] = []
+        if localappdata:
+            packages = _absolute_path(localappdata, env_map) / "Packages"
+            fallback_paths = sorted(
+                packages.glob("*/LocalCache/Roaming/Claude/claude_desktop_config.json")
+            )
+        candidates = (
+            TargetCandidate(primary, "json", "Windows documented Claude Desktop config", False),
+            *(
+                TargetCandidate(path, "json", "Windows packaged Claude Desktop fallback", False)
+                for path in fallback_paths
+            ),
+        )
+        uncertainty = None if appdata else "APPDATA is not set; using the conventional AppData/Roaming fallback."
+    else:
+        candidates = (
+            TargetCandidate(
+                home_path / ".config" / "Claude" / "claude_desktop_config.json",
+                "json",
+                "Linux documented Claude Desktop config",
+                False,
+            ),
+        )
+        uncertainty = None
+    candidates = _with_exists(candidates)
+    selected = candidates[0]
+    if system == "Windows" and not selected.exists:
+        selected = next((candidate for candidate in candidates[1:] if candidate.exists), selected)
+    reason = selected.role if selected.exists else f"{candidates[0].role} create target"
+    return _resolution(
+        target_id,
+        provider,
+        selected,
+        candidates,
+        config_scope,
+        install_mechanism,
+        status_detection,
+        reason,
+        uncertainty,
+    )
+
+
+def _resolve_codex(
+    target_id: TargetID,
+    provider: Provider,
+    config_scope: str,
+    install_mechanism: str,
+    status_detection: str,
+    env_map: dict[str, str],
+    home_path: Path,
+) -> TargetResolution:
+    hooks_path = _env_or_default("SERNIXA_CODEX_HOOKS_FILE", home_path / ".codex" / "hooks.json", env_map)
+    toml_path = _env_or_default("SERNIXA_CODEX_CONFIG_FILE", home_path / ".codex" / "config.toml", env_map)
+    hooks_overridden = bool(env_map.get("SERNIXA_CODEX_HOOKS_FILE", "").strip())
+    candidates = _with_exists(
+        (
+            TargetCandidate(hooks_path, "json", "Codex hooks.json", False),
+            TargetCandidate(toml_path, "toml", "Codex config.toml", False),
+        )
+    )
+    hooks_candidate, toml_candidate = candidates
+    if hooks_overridden:
+        selected = hooks_candidate
+        reason = "SERNIXA_CODEX_HOOKS_FILE override"
+    elif hooks_candidate.exists:
+        selected = hooks_candidate
+        reason = "Codex hooks.json exists and is the preferred hook target"
+    elif toml_candidate.exists:
+        selected = toml_candidate
+        reason = "Codex config.toml exists and hooks.json is absent"
+    else:
+        selected = hooks_candidate
+        reason = "Codex hooks.json preferred create target; project-scoped .codex is intentionally ignored"
+    return _resolution(
+        target_id,
+        provider,
+        selected,
+        candidates,
+        config_scope,
+        install_mechanism,
+        status_detection,
+        reason,
+    )
+
+
+def _resolution(
+    target_id: TargetID,
+    provider: Provider,
+    selected: TargetCandidate,
+    candidates: tuple[TargetCandidate, ...],
+    config_scope: str,
+    install_mechanism: str,
+    status_detection: str,
+    selected_reason: str,
+    uncertainty: str | None = None,
+) -> TargetResolution:
+    return TargetResolution(
+        target_id=target_id,
+        display_name=TARGET_DISPLAY_NAMES[target_id],
+        provider=provider,
+        selected_path=selected.path,
+        selected_format=selected.config_format,
+        config_scope=config_scope,
+        install_mechanism=install_mechanism,
+        status_detection=status_detection,
+        candidates=candidates,
+        selected_reason=selected_reason,
+        uncertainty=uncertainty,
+    )
+
+
+def _env_or_default(name: str, default: Path, env_map: dict[str, str]) -> Path:
+    override = env_map.get(name, "").strip()
+    return _absolute_path(override, env_map) if override else _absolute_path(default, env_map)
+
+
+def _absolute_path(value: str | Path, env_map: dict[str, str]) -> Path:
+    expanded = str(value)
+    for name, replacement in env_map.items():
+        expanded = expanded.replace(f"${name}", replacement)
+        expanded = expanded.replace(f"${{{name}}}", replacement)
+    expanded = os.path.expandvars(expanded)
+    for name, replacement in env_map.items():
+        expanded = expanded.replace(f"%{name}%", replacement)
+    return Path(expanded).expanduser().resolve(strict=False)
+
+
+def _status_path(path: Path) -> str:
+    return str(path.expanduser().resolve(strict=False))
+
+
+def _with_exists(candidates: tuple[TargetCandidate, ...]) -> tuple[TargetCandidate, ...]:
+    return tuple(
+        TargetCandidate(candidate.path, candidate.config_format, candidate.role, candidate.path.exists())
+        for candidate in candidates
+    )
+
+
+def _read_text_or_empty(path: Path) -> str:
+    if not path.exists():
+        return ""
+    return path.read_text(encoding="utf-8")
+
+
+def _read_json_object(path: Path) -> dict[str, Any]:
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise TargetConfigError(f"Unable to read hook config: {path}") from exc
+    if not raw.strip():
+        return {}
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise TargetConfigError(f"Invalid JSON in {path}: line {exc.lineno}, column {exc.colno}: {exc.msg}") from exc
+    if not isinstance(parsed, dict):
+        raise TargetConfigError(f"Hook config must be a JSON object: {path}")
+    return parsed
+
+
+def _validate_claude_desktop_config_shape(config: dict[str, Any], path: Path) -> None:
+    servers = config.get("mcpServers")
+    if servers is not None and not isinstance(servers, dict):
+        raise TargetConfigError(
+            f"Claude Desktop config at {path} has an unexpected mcpServers shape; "
+            "expected an object keyed by MCP server name."
+        )
+    if isinstance(servers, dict):
+        for name, server in servers.items():
+            if not isinstance(server, dict):
+                raise TargetConfigError(
+                    f"Claude Desktop config at {path} has an unexpected mcpServers.{name} shape; "
+                    "expected an object with command/args/env fields."
+                )
+
+
+def _merge_hooks(existing: dict[str, Any], snippet: dict[str, Any], provider: Provider) -> tuple[dict[str, Any], bool]:
+    merged = copy.deepcopy(existing)
+    hooks = merged.setdefault("hooks", {})
+    if not isinstance(hooks, dict):
+        raise TargetConfigError("Existing hooks field is not a JSON object.")
+    changed = False
+    for event, groups in snippet["hooks"].items():
+        existing_groups = hooks.setdefault(event, [])
+        if not isinstance(existing_groups, list):
+            raise TargetConfigError(f"Existing hooks.{event} field is not a JSON array.")
+        expected_group = groups[0]
+        has_expected = any(_group_has_expected_wrapper(group, provider) for group in existing_groups)
+        cleaned_groups: list[Any] = []
+        kept_expected = False
+        for group in existing_groups:
+            is_sernixa = _is_sernixa_group_for_provider(group, provider)
+            is_expected = _group_has_expected_wrapper(group, provider)
+            if not is_sernixa:
+                cleaned_groups.append(group)
+                continue
+            if is_expected and not kept_expected:
+                cleaned_groups.append(group)
+                kept_expected = True
+                continue
+            changed = True
+        if not has_expected:
+            cleaned_groups.append(expected_group)
+            changed = True
+        hooks[event] = cleaned_groups
+    return merged, changed
+
+
+def _remove_sernixa_json_hooks(existing: dict[str, Any], provider: Provider) -> tuple[dict[str, Any], bool]:
+    merged = copy.deepcopy(existing)
+    hooks = merged.get("hooks")
+    if not isinstance(hooks, dict):
+        return merged, False
+    changed = False
+    for event, groups in list(hooks.items()):
+        if not isinstance(groups, list):
+            continue
+        cleaned = [
+            group
+            for group in groups
+            if not _is_sernixa_group_for_provider(group, provider)
+        ]
+        if len(cleaned) != len(groups):
+            hooks[event] = cleaned
+            changed = True
+    return merged, changed
+
+
+def _merge_mcp_server(existing: dict[str, Any], snippet: dict[str, Any], path: Path) -> tuple[dict[str, Any], bool]:
+    merged = copy.deepcopy(existing)
+    _validate_claude_desktop_config_shape(merged, path)
+    servers = merged.setdefault("mcpServers", {})
+    expected = snippet["mcpServers"]["sernixa-governance"]
+    current = servers.get("sernixa-governance")
+    if current == expected:
+        return merged, False
+    servers["sernixa-governance"] = expected
+    return merged, True
+
+
+def _merge_codex_toml(path: Path, before: str) -> str:
+    if before.strip():
+        try:
+            tomllib.loads(before)
+        except tomllib.TOMLDecodeError as exc:
+            raise TargetConfigError(_format_toml_error(path, exc)) from exc
+    block = _codex_toml_block()
+    if SERNIXA_TOML_BEGIN in before or SERNIXA_TOML_END in before:
+        pattern = re.compile(
+            rf"{re.escape(SERNIXA_TOML_BEGIN)}.*?{re.escape(SERNIXA_TOML_END)}\n?",
+            re.DOTALL,
+        )
+        return pattern.sub(block, before)
+    separator = "\n" if before.endswith("\n") or not before else "\n\n"
+    return f"{before}{separator}{block}"
+
+
+def _remove_sernixa_toml_block(text: str) -> str:
+    if SERNIXA_TOML_BEGIN not in text and SERNIXA_TOML_END not in text:
+        return text
+    pattern = re.compile(
+        rf"\n?{re.escape(SERNIXA_TOML_BEGIN)}.*?{re.escape(SERNIXA_TOML_END)}\n?",
+        re.DOTALL,
+    )
+    stripped = pattern.sub("\n", text)
+    return re.sub(r"\n{3,}", "\n\n", stripped).lstrip("\n")
+
+
+def _codex_toml_block() -> str:
+    return (
+        f"{SERNIXA_TOML_BEGIN}\n"
+        "[hooks.PreToolUse.sernixa]\n"
+        'command = "sernixa"\n'
+        'args = ["hook", "run", "codex"]\n'
+        "timeout = 10\n"
+        'statusMessage = "Checking Sernixa policy"\n'
+        f"{SERNIXA_TOML_END}\n"
+    )
+
+
+def _format_toml_error(path: Path, exc: tomllib.TOMLDecodeError) -> str:
+    line = getattr(exc, "lineno", None)
+    column = getattr(exc, "colno", None)
+    message = getattr(exc, "msg", None) or str(exc)
+    if line is not None and column is not None:
+        return f"Invalid TOML in {path}: line {line}, column {column}: {message}"
+    return f"Invalid TOML in {path}: {message}"
+
+
+def _hook_state(config: dict[str, Any], provider: Provider) -> Literal["valid", "malformed", "missing"]:
+    hooks = config.get("hooks")
+    if not isinstance(hooks, dict):
+        return "missing"
+    groups = hooks.get("PreToolUse")
+    if not isinstance(groups, list):
+        return "missing"
+    saw_sernixa = False
+    for group in groups:
+        if _group_has_expected_wrapper(group, provider):
+            return "valid"
+        if _is_sernixa_group_for_provider(group, provider):
+            saw_sernixa = True
+    return "malformed" if saw_sernixa else "missing"
+
+
+def _json_hooks_declared(config: dict[str, Any]) -> bool:
+    hooks = config.get("hooks")
+    if not isinstance(hooks, dict):
+        return False
+    return bool(hooks)
+
+
+def _toml_hooks_enabled(config: dict[str, Any]) -> bool:
+    hooks = config.get("hooks")
+    if isinstance(hooks, dict) and hooks.get("enabled") is True:
+        return True
+    return config.get("hooks_enabled") is True or config.get("enable_hooks") is True
+
+
+def _codex_activation_hint(activation: dict[str, dict[str, bool]]) -> str | None:
+    declared = [source for source, item in activation.items() if item["declared"]]
+    enabled = [source for source, item in activation.items() if item["enabled"]]
+    effective = [source for source, item in activation.items() if item["effective"]]
+    if effective:
+        if len(declared) > 1:
+            return (
+                "Codex hooks are effective, but declarations exist in multiple global files; "
+                "review duplicate declarations if behavior is surprising."
+            )
+        return None
+    if declared and not enabled:
+        if declared == ["config_toml"]:
+            return (
+                "Codex hook declarations exist only in config.toml, but no hooks enablement flag "
+                "was found. Set hooks.enabled = true or install into hooks.json."
+            )
+        return "Codex hook declarations exist, but no active hook source was detected."
+    if enabled and not declared:
+        return "Codex hooks appear enabled, but no hook declarations were found."
+    return None
+
+
+def _toml_hook_state(text: str, parsed: dict[str, Any]) -> Literal["valid", "malformed", "missing"]:
+    hooks = parsed.get("hooks")
+    if not isinstance(hooks, dict):
+        return "malformed" if _toml_has_sernixa_block(text) else "missing"
+    if _toml_hooks_have_expected_wrapper(hooks):
+        return "valid"
+    return "malformed" if _toml_hooks_mention_sernixa(hooks) or _toml_has_sernixa_block(text) else "missing"
+
+
+def _mcp_server_state(config: dict[str, Any]) -> Literal["valid", "malformed", "missing"]:
+    servers = config.get("mcpServers")
+    if not isinstance(servers, dict):
+        return "missing"
+    server = servers.get("sernixa-governance")
+    if not isinstance(server, dict):
+        return "missing"
+    if server.get("command") == "sernixa" and server.get("args") == ["hook", "run", "claude"]:
+        return "valid"
+    if "sernixa" in json.dumps(server, sort_keys=True):
+        return "malformed"
+    return "missing"
+
+
+def _group_has_expected_wrapper(group: Any, provider: Provider) -> bool:
+    return _expected_command(provider) in _commands(group)
+
+
+def _is_sernixa_group_for_provider(group: Any, provider: Provider) -> bool:
+    return any("sernixa" in command and provider in command for command in _commands(group))
+
+
+def _commands(group: Any) -> set[str]:
+    if not isinstance(group, dict):
+        return set()
+    commands: set[str] = set()
+    for hook in group.get("hooks") or []:
+        if not isinstance(hook, dict):
+            continue
+        command = hook.get("command")
+        if not isinstance(command, str):
+            continue
+        args = hook.get("args")
+        if isinstance(args, list):
+            commands.add(" ".join([command, *[str(item) for item in args]]))
+        commands.add(command)
+    return commands
+
+
+def _codex_source_id(candidate: TargetCandidate) -> str:
+    return "hooks_json" if candidate.config_format == "json" else "config_toml"
+
+
+def _toml_hooks_have_expected_wrapper(hooks: dict[str, Any]) -> bool:
+    return _toml_find_sernixa_wrapper(hooks, expect_valid=True)
+
+
+def _toml_hooks_mention_sernixa(hooks: dict[str, Any]) -> bool:
+    return _toml_find_sernixa_wrapper(hooks, expect_valid=False)
+
+
+def _toml_find_sernixa_wrapper(value: Any, *, expect_valid: bool) -> bool:
+    if isinstance(value, dict):
+        command = value.get("command")
+        args = value.get("args")
+        if isinstance(command, str):
+            full = " ".join([command, *[str(item) for item in args]]) if isinstance(args, list) else command
+            if expect_valid and full == "sernixa hook run codex":
+                return True
+            if not expect_valid and "sernixa" in full and "codex" in full:
+                return True
+        return any(_toml_find_sernixa_wrapper(item, expect_valid=expect_valid) for item in value.values())
+    if isinstance(value, list):
+        return any(_toml_find_sernixa_wrapper(item, expect_valid=expect_valid) for item in value)
+    if isinstance(value, str) and not expect_valid:
+        return "sernixa" in value and "codex" in value
+    return False
+
+
+def _expected_command(provider: Provider) -> str:
+    if provider == "claude":
+        return "sernixa hook run claude"
+    return "sernixa hook run codex"
+
+
+def _toml_has_sernixa_block(text: str) -> bool:
+    return SERNIXA_TOML_BEGIN in text or "sernixa" in text and "hook" in text and "codex" in text
+
+
+def _toml_has_expected_codex_block(text: str) -> bool:
+    return (
+        SERNIXA_TOML_BEGIN in text
+        and 'command = "sernixa"' in text
+        and 'args = ["hook", "run", "codex"]' in text
+    )
+
+
+def _write_private_text(path: Path, content: str) -> None:
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    temporary = path.with_suffix(path.suffix + ".tmp")
+    temporary.write_text(content, encoding="utf-8")
+    if os.name == "posix":
+        temporary.chmod(0o600)
+    temporary.replace(path)
+    if os.name == "posix":
+        path.chmod(0o600)
+
+
+def _backup(path: Path) -> Path:
+    from datetime import datetime, timezone
+
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    backup_path = path.with_name(f"{path.name}.sernixa-backup-{stamp}")
+    backup_path.write_bytes(path.read_bytes())
+    if os.name == "posix":
+        backup_path.chmod(0o600)
+    return backup_path