higpertext-cli 0.8.0__py3-none-any.whl

higpertext/hooks/hook_tasks/_rules/context_engine_rule.py

@@ -0,0 +1,79 @@
+"""Regla UserPromptSubmit — inyecta ContextPack ensamblado en cada prompt del usuario.
+
+Integra el context_engine con el sistema de hooks para que el modelo reciba
+símbolos relevantes, memorias y esqueletos de archivos en cada turno.
+"""
+
+from __future__ import annotations
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+RuleSeverity = Literal["continue", "context", "block"]
+
+_DEFAULT_TOKEN_BUDGET = 4_000
+
+# Importación al nivel de módulo — permite patch en tests y falla limpio si no existe.
+try:
+    from higpertext.kernel.application.context_engine import ContextAssembler
+    from higpertext.kernel.domain.context_engine import TaskIntent
+
+    _ENGINE_AVAILABLE = True
+except ImportError:
+    _ENGINE_AVAILABLE = False
+
+
+@dataclass
+class RuleResult:
+    severity: RuleSeverity
+    message: str = ""
+
+
+def inject_context_pack(root: Path, prompt: str) -> RuleResult | None:
+    """Ensambla un ContextPack a partir del prompt y lo retorna como contexto.
+
+    Returns:
+        RuleResult con el pack en markdown, o None si no hay contenido relevante
+        o si el context_engine no está disponible.
+    """
+    if not _ENGINE_AVAILABLE:
+        return None
+
+    budget = _resolve_budget()
+    intent = TaskIntent.from_goal(goal=prompt, task_type="general", token_budget=budget)
+
+    try:
+        assembler = ContextAssembler(project_root=root)
+        pack = assembler.assemble(intent)
+    except Exception:
+        return None
+
+    if not pack.relevant_symbols and not pack.applicable_memories:
+        return None
+
+    return RuleResult(severity="context", message=_format_pack(pack))
+
+
+def _resolve_budget() -> int:
+    """Retorna el budget de tokens desde variable de entorno o usa el default."""
+    try:
+        return int(os.environ.get("HIGPERTEXT_CONTEXT_BUDGET", _DEFAULT_TOKEN_BUDGET))
+    except ValueError:
+        return _DEFAULT_TOKEN_BUDGET
+
+
+def _format_pack(pack: object) -> str:
+    """Envuelve el markdown del ContextPack en un banner higpertext."""
+    lines = [
+        "╔─ HIGPERTEXT  ·  Context Engine — Contexto ensamblado ──────",
+        # type: ignore[attr-defined]
+        f"│  Tokens estimados : {pack.estimated_tokens:,} / {pack.intent.token_budget:,}",
+        f"│  Símbolos         : {len(pack.relevant_symbols)}",  # type: ignore[attr-defined]
+        f"│  Memorias         : {len(pack.applicable_memories)}",  # type: ignore[attr-defined]
+        f"│  Esqueletos       : {len(pack.skeletons)}",  # type: ignore[attr-defined]
+        "╠────────────────────────────────────────────────────────────",
+        pack.to_markdown(),  # type: ignore[attr-defined]
+        "╚───────────────────────────────────────────────────────────",
+    ]
+    return "\n".join(lines)

higpertext/hooks/hook_tasks/_rules/context_rules.py

@@ -0,0 +1,199 @@
+"""Reglas de gestión de contexto para PreCompact y PostToolUse.
+
+check_context_pressure — preserva estado higpertext crítico antes de compresión.
+check_large_output     — avisa al modelo cuando un tool output es demasiado grande.
+check_window_pressure  — mide uso acumulado de la ventana de contexto por turno.
+"""
+
+from __future__ import annotations
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+RuleSeverity = Literal["continue", "context", "block"]
+
+
+def _large_output_threshold() -> int:
+    """Umbral de chars para output masivo. Configurable vía HIGPERTEXT_LARGE_OUTPUT_CHARS."""
+    try:
+        return int(os.environ.get("HIGPERTEXT_LARGE_OUTPUT_CHARS", "5000"))
+    except ValueError:
+        return 5_000
+
+
+# Mantiene compatibilidad con imports existentes (tests, otros módulos)
+LARGE_OUTPUT_CHARS = _large_output_threshold()
+
+
+@dataclass
+class RuleResult:
+    severity: RuleSeverity
+    message: str = ""
+
+
+# ── Regla 1: Preservar estado higpertext antes de compresión (PreCompress) ─────────
+
+
+def check_context_pressure(root: Path) -> RuleResult:
+    """Emite resumen compacto de sesión para preservarlo tras la compresión."""
+    session = _read_json(root / WORKSPACE_DIR_NAME / "state" / "session.json")
+    env = _read_json(root / WORKSPACE_DIR_NAME / "config" / "environment.json")
+
+    sid = session.get("session_id", "—")
+    profile = env.get("active_profile", "—")
+    asst = env.get("assistant", "claude")
+    active = session.get("status") == "active"
+
+    if not active:
+        return RuleResult(severity="continue")
+
+    skills = _list_dir_names(root / _SKILL_DIRS.get(asst, ".claude/skills"))
+    subagents = _list_dir_names(root / _AGENT_DIRS.get(asst, ".claude/subagents"), "*.md")
+
+    lines = [
+        "╔─ HIGPERTEXT  ·  Contexto preservado (pre-compresión) ──────",
+        f"│  Sesión  : {sid}",
+        f"│  Perfil  : {profile}",
+        f"│  Skills  : {', '.join(skills) or '—'}",
+        f"│  Agentes : {', '.join(subagents) or '—'}",
+        "│  → Continúa usando `htx task <cap>` para",
+        "│    invocar capacidades higpertext.",
+        "╚───────────────────────────────────────────────────────",
+    ]
+    return RuleResult(severity="context", message="\n".join(lines))
+
+
+# ── Regla 2: Aviso de output masivo (PostToolUse) ─────────────────────────────
+
+
+def check_large_output(payload: dict) -> RuleResult | None:
+    """Avisa si la respuesta de un tool supera el umbral de chars."""
+    threshold = _large_output_threshold()
+    tool_response = payload.get("tool_response", {})
+    output_str = json.dumps(tool_response, ensure_ascii=False)
+    if len(output_str) <= threshold:
+        return None
+    tool = payload.get("tool_name", "unknown")
+    n_lines = output_str.count("\n") + 1
+    suggestion = _large_output_suggestion(tool)
+    return RuleResult(
+        severity="context",
+        message="\n".join(
+            [
+                "╔─ HIGPERTEXT  ·  Output masivo detectado ───────────────────",
+                f"│  Tool    : {tool}",
+                f"│  Tamaño  : {len(output_str):,} chars"
+                f" · ~{n_lines:,} líneas (límite {threshold:,})",
+                "│  ⚠  No re-emitas este blob en tu respuesta.",
+                "│     Referencia el archivo por path:line. Si necesitas",
+                "│     releer, usa offset/limit en vez de leer todo.",
+                f"│  → {suggestion}",
+                "╚───────────────────────────────────────────────────────",
+            ]
+        ),
+    )
+
+
+def _large_output_suggestion(tool: str) -> str:
+    """Devuelve acción concreta según herramienta que generó output masivo."""
+    normalized = tool.lower()
+    if normalized == "read":
+        return "Usa: htx task common.smart-read --path <archivo> --mode auto"
+    if normalized == "bash":
+        return "Si fue cat/head/less, usa: htx task common.code-skeletonizer --path <archivo>"
+    if "grep" in normalized or normalized == "common.grep-search":
+        return "Reduce con --max_results, --max_per_file y --line_limit"
+    return "Reduce la salida con filtros, rangos o capacidades smart-read/grep-search"
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+from higpertext.kernel.app_config import SKILL_DIRS as _SKILL_DIRS, AGENT_DIRS as _AGENT_DIRS
+
+
+def _read_json(path: Path) -> dict:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _list_dir_names(path: Path, glob: str = "*") -> list[str]:
+    if not path.exists():
+        return []
+    if glob == "*.md":
+        return sorted(f.stem for f in path.glob(glob))
+    return sorted(d.name for d in path.iterdir() if d.is_dir())
+
+
+# ── Regla 3: Presión de ventana de contexto (PostToolUse) ────────────────────
+
+
+def _window_config() -> tuple[int, float, float]:
+    """Retorna (window_limit, warn_pct, critical_pct) desde env vars o defaults."""
+    try:
+        limit = int(os.environ.get("HIGPERTEXT_WINDOW_LIMIT", "200000"))
+    except ValueError:
+        limit = 200_000
+    try:
+        warn = float(os.environ.get("HIGPERTEXT_WARN_PCT", "0.70"))
+    except ValueError:
+        warn = 0.70
+    try:
+        critical = float(os.environ.get("HIGPERTEXT_CRITICAL_PCT", "0.90"))
+    except ValueError:
+        critical = 0.90
+    return limit, warn, critical
+
+
+def check_window_pressure(payload: dict, root: Path) -> RuleResult | None:
+    """Acumula tokens del tool output y alerta si la ventana supera los umbrales.
+
+    Returns:
+        None si está bajo el umbral de warning.
+        RuleResult(context) con banner WARNING entre warn y critical.
+        RuleResult(context) con banner CRITICAL si supera el umbral crítico.
+    """
+    try:
+        from higpertext.kernel.domain.context_engine import (
+            load_window_state,
+            save_window_state,
+        )
+    except ImportError:
+        return None
+
+    limit, warn_pct, critical_pct = _window_config()
+    output_str = json.dumps(payload.get("tool_response", {}), ensure_ascii=False)
+    new_tokens = int(len(output_str) / 3.5)
+
+    state = load_window_state(root)
+    state.add(new_tokens)
+    save_window_state(root, state)
+
+    usage = state.usage_pct(limit)
+    if usage < warn_pct:
+        return None
+
+    level = "🔴 CRITICAL" if usage >= critical_pct else "🟡 WARNING"
+    action = (
+        "Ejecuta /compact para comprimir el historial antes de continuar."
+        if usage >= critical_pct
+        else "Considera ejecutar /compact pronto."
+    )
+    return RuleResult(
+        severity="context",
+        message="\n".join(
+            [
+                f"╔─ HIGPERTEXT  ·  Ventana de Contexto  ·  {level} ─────────────",
+                f"│  Uso estimado : {
+                state.accumulated_tokens:,} / {
+                limit:,} tokens  ({
+                usage * 100:.1f}%)",
+                f"│  Turno actual : {state.turn}",
+                f"│  ⚠  {action}",
+                "╚──────────────────────────────────────────────────────────────",
+            ]
+        ),
+    )

higpertext/hooks/hook_tasks/_rules/governance_adapter.py

@@ -0,0 +1,72 @@
+"""Adaptador de gobernanza — lee contratos de dominio y expone valores para hooks."""
+
+from __future__ import annotations
+import sys
+from pathlib import Path
+
+DEFAULT_HARD_BLOCKS = [
+    (r"\bsudo\b", "sudo no está permitido en este entorno por política de seguridad"),
+    (
+        r"\bgit\s+push\b",
+        "git push es una acción exclusiva del usuario"
+        " — el agente no puede publicar cambios al remoto",
+    ),
+]
+DEFAULT_FUNC_LIMIT = 30
+DEFAULT_CLASS_LIMIT = 200
+DEFAULT_UNCOMMITTED_LIMIT = 5
+
+
+def _load_domain(root: Path, name: str) -> dict:
+    """Carga un archivo de contrato de dominio via ContractLoader."""
+    core_path = str(root / "src")
+    if core_path not in sys.path:
+        sys.path.insert(0, core_path)
+    try:
+        from higpertext.kernel.infrastructure import ContractLoader
+
+        return getattr(ContractLoader(root), f"load_{name}")()
+    except Exception:
+        return {}
+
+
+def get_bash_blocks(root: Path) -> list[tuple[str, str]]:
+    """Bloqueos hard de bash: security_guardrails + branching_strategy."""
+    blocks: list[tuple[str, str]] = []
+    for source in ("security_guardrails", "branching_strategy"):
+        data = _load_domain(root, source)
+        for entry in data.get("blocked_patterns", []) + data.get("rules", []):
+            pattern = entry.get("pattern")
+            reason = entry.get("reason", "Comando bloqueado por política de gobernanza")
+            if pattern:
+                blocks.append((pattern, reason))
+    return blocks or DEFAULT_HARD_BLOCKS
+
+
+def get_deployment_blocks(root: Path) -> list[tuple[str, str, str]]:
+    """Retorna (pattern, reason, severity) desde deployment_gates.json."""
+    data = _load_domain(root, "deployment_gates")
+    result = []
+    for entry in data.get("blocked_patterns", []):
+        pattern = entry.get("pattern")
+        reason = entry.get("reason", "Acción de deployment bloqueada por gobernanza")
+        severity = entry.get("severity", "warn")
+        if pattern:
+            result.append((pattern, reason, severity))
+    return result
+
+
+def get_code_limits(root: Path) -> tuple[int, int]:
+    """Retorna (max_function_lines, max_class_lines) desde quality_gates.json."""
+    data = _load_domain(root, "quality_gates")
+    limits = data.get("code_quality_limits", {})
+    return (
+        limits.get("max_function_lines", DEFAULT_FUNC_LIMIT),
+        limits.get("max_class_lines", DEFAULT_CLASS_LIMIT),
+    )
+
+
+def get_session_limits(root: Path) -> int:
+    """Retorna max_uncommitted_files desde quality_gates.json."""
+    data = _load_domain(root, "quality_gates")
+    return data.get("gitflow_limits", {}).get("max_uncommitted_files", DEFAULT_UNCOMMITTED_LIMIT)

higpertext/hooks/hook_tasks/_rules/profile_rules.json

@@ -0,0 +1,25 @@
+{
+  "rules": [
+    {
+      "pattern": "\\bgit\\s+commit\\b",
+      "severity": "block",
+      "capability": "git.committer",
+      "reason": "Los commits directos omiten el flujo de gobernanza: conventional commits, stage selectivo, validación de cobertura y registro de telemetría. Usa la capacidad git.committer que aplica todas estas reglas automáticamente.",
+      "example": "htx task git.committer --message \"feat(scope): description\""
+    },
+    {
+      "pattern": "\\bpip\\s+install\\b|\\bpip3\\s+install\\b",
+      "severity": "block",
+      "capability": "",
+      "reason": "Las instalaciones de paquetes deben hacerse en el entorno controlado .venv. Usa '.venv/bin/pip install <paquete>' o gestiona dependencias desde pyproject.toml.",
+      "example": ".venv/bin/pip install <paquete>"
+    },
+    {
+      "pattern": "\\bpython\\s+(?!htx\\.py)\\S+\\.py\\b|\\bpython3\\s+(?!htx\\.py)\\S+\\.py\\b",
+      "severity": "context",
+      "capability": "common.higpertext-tester",
+      "reason": "Ejecutar scripts Python directamente evita el runtime del motor. Usa 'htx task' para lanzar capacidades o 'htx workflow run' para pipelines.",
+      "example": "htx task common.higpertext-tester --test <módulo>"
+    }
+  ]
+}

higpertext/hooks/hook_tasks/_rules/quality_rules.py

@@ -0,0 +1,86 @@
+"""Reglas de evaluación para escritura de código (PreToolUse:Write|Edit).
+
+Cada función retorna una RuleResult o None si no aplica.
+"""
+
+from __future__ import annotations
+from .governance_adapter import get_code_limits
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+RuleSeverity = Literal["continue", "context", "block"]
+
+
+_PYTHON_FILE = re.compile(r"\.py$")
+
+
+@dataclass
+class RuleResult:
+    severity: RuleSeverity
+    message: str = ""
+
+
+def is_python_file(file_path: str) -> bool:
+    return bool(_PYTHON_FILE.search(file_path))
+
+
+# ── Regla 1: Longitud de funciones y clases ───────────────────────────────────
+
+
+def check_code_length(file_path: str, root: Path) -> RuleResult | None:
+    func_limit, class_limit = get_code_limits(root)
+    violations = _scan_file(file_path, func_limit, class_limit)
+    if not violations:
+        return None
+    msg = "[HIGPERTEXT QUALITY GATE] Violaciones detectadas:\n" + "\n".join(violations)
+    return RuleResult(severity="context", message=msg)
+
+
+def _check_func_limit(in_func: bool, current_line: int, func_start: int, func_limit: int, func_name: str, violations: list[str]) -> None:
+    if in_func and (current_line - func_start) > func_limit:
+        violations.append(
+            f"  función '{func_name}' excede {func_limit} líneas (línea {func_start})"
+        )
+
+
+def _check_class_limit(in_class: bool, current_line: int, class_start: int, class_limit: int, class_name: str, violations: list[str]) -> None:
+    if in_class and (current_line - class_start) > class_limit:
+        violations.append(
+            f"  clase '{class_name}' excede {class_limit} líneas (línea {class_start})"
+        )
+
+
+def _scan_file(filepath: str, func_limit: int, class_limit: int) -> list[str]:
+    violations: list[str] = []
+    try:
+        lines = Path(filepath).read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return violations
+
+    in_func = False
+    in_class = False
+    func_start = 0
+    class_start = 0
+    func_name = ""
+    class_name = ""
+
+    total = len(lines)
+    for i, line in enumerate(lines, 1):
+        m_func = re.match(r"\s*def\s+(\w+)", line)
+        m_class = re.match(r"\s*class\s+(\w+)", line)
+
+        if m_func:
+            _check_func_limit(in_func, i, func_start, func_limit, func_name, violations)
+            in_func, func_start, func_name = True, i, m_func.group(1)
+
+        elif m_class:
+            _check_class_limit(in_class, i, class_start, class_limit, class_name, violations)
+            in_class, class_start, class_name = True, i, m_class.group(1)
+
+    # Chequeo final: última función/clase del archivo
+    _check_func_limit(in_func, total + 1, func_start, func_limit, func_name, violations)
+    _check_class_limit(in_class, total + 1, class_start, class_limit, class_name, violations)
+
+    return violations

higpertext/hooks/hook_tasks/_rules/security_rules.py

@@ -0,0 +1,214 @@
+"""Reglas de seguridad comunes para hooks de asistentes higpertext."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+RuleSeverity = Literal["continue", "context", "warn", "ask", "block"]
+
+
+@dataclass
+class RuleResult:
+    severity: RuleSeverity
+    message: str = ""
+    replacement_output: str = ""
+
+
+_SENSITIVE_PATH_PATTERNS = [
+    r"(^|/)\.env(\..*)?$",
+    r"(^|/)\.npmrc$",
+    r"(^|/)\.pypirc$",
+    r"(^|/)\.netrc$",
+    r"(^|/)id_(rsa|dsa|ecdsa|ed25519)$",
+    r"\.(pem|key|p12|pfx|crt)$",
+    r"(^|/)(secrets?|credentials?)(/|\.|$)",
+    r"(^|/)\.aws/credentials$",
+    r"(^|/)\.azure(/|$)",
+    r"(^|/)\.kube/config$",
+]
+
+
+def evaluate_command_guard(command: str, root: Path) -> RuleResult | None:
+    """Evalúa comandos peligrosos definidos por gobernanza."""
+    if not command:
+        return None
+    for pattern, reason, severity in _command_rules(root):
+        if re.search(pattern, command, re.IGNORECASE):
+            normalized = _normalize_severity(severity)
+            return RuleResult(
+                severity=normalized,
+                message=_format_command_message(command, reason, normalized),
+            )
+    return None
+
+
+def evaluate_path_guard(tool_name: str, tool_input: dict[str, Any]) -> RuleResult | None:
+    """Bloquea acceso a rutas sensibles desde Read/Write/Edit."""
+    path = _extract_path(tool_input)
+    if not path or not _is_sensitive_path(path):
+        return None
+    return RuleResult(
+        severity="block",
+        message="\n".join(
+            [
+                "╔─ HIGPERTEXT  ·  Security Guard ───────────────────────────",
+                f"│  ✗  {tool_name} sobre ruta sensible bloqueado.",
+                f"│  Ruta: {path}",
+                "│  Usa una capacidad segura o pide aprobación humana explícita.",
+                "╚────────────────────────────────────────────────────────────",
+            ]
+        ),
+    )
+
+
+def mask_tool_output(tool_response: Any, root: Path) -> RuleResult | None:
+    """Enmascara secretos presentes en outputs de herramientas."""
+    output = _stringify_response(tool_response)
+    if not output:
+        return None
+    masked = output
+    for pattern, replacement in _masking_patterns(root):
+        masked = re.sub(pattern, replacement, masked, flags=re.IGNORECASE | re.DOTALL)
+    if masked == output:
+        return None
+    return RuleResult(
+        severity="context",
+        message="[HIGPERTEXT SECURITY] Se enmascararon secretos detectados en el output.",
+        replacement_output=masked,
+    )
+
+
+def _command_rules(root: Path) -> list[tuple[str, str, str]]:
+    data = _load_security_guardrails(root)
+    entries = [
+        (
+            item.get("pattern", ""),
+            item.get("reason", "Comando restringido por seguridad"),
+            item.get("severity", "block"),
+        )
+        for item in data.get("blocked_patterns", [])
+        if item.get("pattern")
+    ]
+    entries.extend(
+        (
+            item.get("pattern", ""),
+            item.get("reason", "Acción requiere aprobación humana explícita"),
+            "ask",
+        )
+        for item in data.get("approval_patterns", [])
+        if item.get("pattern")
+    )
+    entries.extend(
+        (
+            item.get("pattern", ""),
+            item.get("reason", "Acción potencialmente riesgosa"),
+            item.get("severity", "warn"),
+        )
+        for item in data.get("warning_patterns", [])
+        if item.get("pattern")
+    )
+    forbidden = data.get("guardrails", {}).get("forbidden_commands", [])
+    entries.extend(
+        (
+            re.escape(command),
+            f"'{command}' está prohibido por política de seguridad",
+            "block",
+        )
+        for command in forbidden
+        if command
+    )
+    return entries
+
+
+def _normalize_severity(value: str) -> RuleSeverity:
+    lowered = str(value).lower().strip()
+    if lowered in {"warn", "warning", "context"}:
+        return "warn"
+    if lowered in {"ask", "approval", "human_approval"}:
+        return "ask"
+    return "block"
+
+
+def _format_command_message(command: str, reason: str, severity: RuleSeverity) -> str:
+    if severity == "warn":
+        marker = "⚠"
+        action = "Advertencia: la acción continuará, pero queda registrada."
+    elif severity == "ask":
+        marker = "?"
+        action = "Requiere aprobación humana explícita antes de ejecutar."
+    else:
+        marker = "✗"
+        action = "Comando bloqueado por política de seguridad."
+    return "\n".join(
+        [
+            "╔─ HIGPERTEXT  ·  Security Guard ───────────────────────────",
+            f"│  {marker}  {reason}",
+            f"│  Severidad: {severity}",
+            f"│  Acción   : {action}",
+            f"│  Comando  : {command}",
+            "╚────────────────────────────────────────────────────────────",
+        ]
+    )
+
+
+def _masking_patterns(root: Path) -> list[tuple[str, str]]:
+    data = _load_security_guardrails(root)
+    configured = data.get("data_masking", {}).get("patterns", [])
+    patterns = [
+        (item.get("regex", ""), item.get("mask", "[MASKED]"))
+        for item in configured
+        if item.get("regex")
+    ]
+    patterns.extend(
+        [
+            (
+                r"(?i)(token|password|secret|api[_-]?key)\s*[:=]\s*['\"]?[^\s'\"]{8,}",
+                r"\1=********[MASKED]",
+            ),
+            (r"(?i)bearer\s+[a-z0-9._\-]{20,}", "Bearer ********[MASKED]"),
+        ]
+    )
+    return patterns
+
+
+def _load_security_guardrails(root: Path) -> dict[str, Any]:
+    path = root / "src" / "config" / "governance" / "security_guardrails.json"
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _extract_path(tool_input: dict[str, Any]) -> str:
+    return str(
+        tool_input.get("filePath")
+        or tool_input.get("filepath")
+        or tool_input.get("path")
+        or tool_input.get("file_path")
+        or tool_input.get("file")
+        or ""
+    )
+
+
+def _is_sensitive_path(path: str) -> bool:
+    normalized = path.replace("\\", "/")
+    return any(
+        re.search(pattern, normalized, re.IGNORECASE) for pattern in _SENSITIVE_PATH_PATTERNS
+    )
+
+
+def _stringify_response(tool_response: Any) -> str:
+    if isinstance(tool_response, str):
+        return tool_response
+    if isinstance(tool_response, dict):
+        for key in ("output", "content", "text", "stdout"):
+            if key in tool_response and isinstance(tool_response[key], str):
+                return tool_response[key]
+    try:
+        return json.dumps(tool_response, ensure_ascii=False)
+    except TypeError:
+        return str(tool_response)