higpertext-cli 0.8.0__py3-none-any.whl

higpertext/kernel/application/hook_renderer.py

@@ -0,0 +1,720 @@
+"""HookRenderer — genera config nativa de hooks por asistente."""
+
+from __future__ import annotations
+import json
+import platform
+import shutil
+import sys
+from pathlib import Path
+
+from higpertext.kernel.application.hook_registry import HookRegistry
+from higpertext.kernel.domain.hook_models import HookDefinition
+from higpertext.kernel.pkg_resources import installed_src_root
+from higpertext.kernel.htx_resolver import _load_config, get_htx_cmd
+from higpertext.kernel.config_paths import PROJECT_ROOT as ENGINE_ROOT
+from higpertext.kernel.infrastructure.logger import get_logger
+from higpertext.kernel.app_config import (
+    SETTINGS_FILE as SETTINGS_JSON,
+    ASSISTANT_HOOKS_DIRS,
+    ASSISTANT_ALIASES,
+)
+
+_log = get_logger()
+
+
+class HookRenderer:
+    """Convierte HookDefinitions en configuración nativa de cada asistente.
+
+    Al renderizar, copia los scripts de hook desde el repo de higpertext a la
+    carpeta de configuración del asistente en el proyecto destino
+    (p.ej. .claude/hooks/, .gemini/hooks/). Esto permite que los hooks
+    se ejecuten con CWD = raíz del proyecto destino, donde htx.py existe.
+    """
+
+    _HOOKS_DIR: dict[str, str] = ASSISTANT_HOOKS_DIRS
+    _ALIAS: dict[str, str] = ASSISTANT_ALIASES
+
+    def __init__(self, project_root: Path) -> None:
+        self.project_root = project_root
+        self.registry = HookRegistry(project_root)
+
+    def _shell_matchers(self) -> set[str]:
+        """Matchers de shell válidos para el OS actual."""
+        matchers = {"Bash"}
+        if platform.system() == "Windows":
+            matchers.add("PowerShell")
+        return matchers
+
+    def _get_venv_dir(self) -> Path:
+        """Retorna la ruta del directorio bin/Scripts de la venv configurada o por defecto."""
+        is_windows = platform.system() == "Windows"
+        default_dir = ".venv/Scripts" if is_windows else ".venv/bin"
+        try:
+            cfg = _load_config()
+            venv_key = "venv_bin_windows" if is_windows else "venv_bin"
+            cfg_venv = cfg.get(venv_key)
+            if cfg_venv:
+                return Path(cfg_venv).parent
+        except Exception as exc:
+            _log.warning(f"[hooks] Config de venv no disponible, usando default: {exc}")
+        return Path(default_dir)
+
+    def _htx_cmd(self) -> str:
+        """Retorna el ejecutable htx en formato POSIX, priorizando la venv."""
+        try:
+            cmds = get_htx_cmd(self.project_root)
+            if cmds:
+                return " ".join(cmds)
+        except Exception as exc:
+            _log.warning(f"[hooks] Resolución htx falló, usando fallback: {exc}")
+
+        is_windows = platform.system() == "Windows"
+        exe_name = "htx.exe" if is_windows else "htx"
+        venv_htx = self.project_root / self._get_venv_dir() / exe_name
+        if venv_htx.exists():
+            return venv_htx.as_posix()
+
+        system_htx = shutil.which("htx")
+        if system_htx:
+            return system_htx
+        return self._python_cmd()
+
+    def _python_cmd(self) -> str:
+        """Retorna el ejecutable Python en formato POSIX (Claude hooks corren en Bash)."""
+        is_windows = platform.system() == "Windows"
+        python_name = "python.exe" if is_windows else "python"
+        venv_python = self.project_root / self._get_venv_dir() / python_name
+        if venv_python.exists():
+            return venv_python.as_posix()
+        path = Path(sys.executable)
+        return path.as_posix()
+
+    def _script_path(self, script: str) -> str:
+        """Convierte la ruta del script a ruta absoluta POSIX (Claude hooks corren en Bash)."""
+        p = Path(script)
+        if not p.is_absolute():
+            p = self.project_root / p
+        return p.as_posix()
+
+    def render(self, assistant: str, profile: str) -> None:
+        hooks = self.registry.get_hooks_for(assistant, profile)
+        canonical = self._ALIAS.get(assistant, assistant)
+        deployed = self._deploy_scripts(canonical, hooks)
+        method = getattr(self, f"_render_{canonical}", None)
+        if method:
+            method(deployed)
+            _log.ok(
+                f"[*] Hooks nativos generados para '{assistant}' "
+                f"(perfil: {profile}, activos: {len(hooks)})"
+            )
+
+    def _resolve_engine_path(self, rel_path: str) -> Path:
+        """Resuelve una ruta relativa a src/ probando dev tree y luego paquete instalado."""
+        dev_path = ENGINE_ROOT / rel_path
+        if dev_path.exists():
+            return dev_path
+        src_root = installed_src_root()
+        if src_root is not None:
+            rel_parts = Path(rel_path).parts
+            if rel_parts and rel_parts[0] == "src":
+                pkg_path = src_root.joinpath(*rel_parts[1:])
+                if pkg_path.exists():
+                    return pkg_path
+        return dev_path
+
+    def _deploy_scripts(self, canonical: str, hooks: list[HookDefinition]) -> list[HookDefinition]:
+        """Copia scripts al directorio de hooks del asistente en project_root.
+
+        Devuelve nuevas HookDefinitions con script apuntando a la ruta
+        relativa destino (usable desde el CWD del proyecto destino).
+        También copia hook_utils.py como dependencia compartida.
+        """
+        hooks_subdir = self._HOOKS_DIR.get(canonical, f".{canonical}/hooks")
+        dest_dir = self.project_root / hooks_subdir
+        dest_dir.mkdir(parents=True, exist_ok=True)
+
+        self._deploy_hook_utils(dest_dir)
+
+        deployed: list[HookDefinition] = []
+        for h in hooks:
+            src = self._resolve_engine_path(h.script)
+            if not src.exists():
+                _log.warning(f"[!] Script no encontrado, se omite copia: {src}")
+                continue
+            dest_file = dest_dir / src.name
+            self._safe_copy(src, dest_file, f"script {src.name}")
+            deployed.append(
+                HookDefinition(
+                    id=h.id,
+                    event=h.event,
+                    script=str(Path(hooks_subdir) / src.name),
+                    description=h.description,
+                    matcher=h.matcher,
+                    timeout=h.timeout,
+                    enabled=h.enabled,
+                    assistants=h.assistants,
+                    profiles=h.profiles,
+                    capability_id=h.capability_id,
+                )
+            )
+        return deployed
+
+    def _deploy_hook_utils(self, dest_dir: Path) -> None:
+        """Copia dependencias compartidas al directorio destino."""
+        hook_tasks = self._resolve_engine_path(
+            str(Path("src") / "higpertext" / "hooks" / "hook_tasks")
+        )
+        self._copy_util_files(hook_tasks, dest_dir)
+        self._copy_rule_files(hook_tasks, dest_dir)
+
+    def _copy_util_files(self, hook_tasks: Path, dest_dir: Path) -> None:
+        for dep in ("hook_utils.py", "hook_io.py"):
+            src = hook_tasks / dep
+            if src.exists():
+                dest_file = dest_dir / dep
+                self._safe_copy(src, dest_file, f"dependencia {dep}")
+
+    def _copy_rule_files(self, hook_tasks: Path, dest_dir: Path) -> None:
+        rules_src = hook_tasks / "_rules"
+        if rules_src.exists():
+            rules_dest = dest_dir / "_rules"
+            rules_dest.mkdir(parents=True, exist_ok=True)
+            for f in rules_src.iterdir():
+                if f.is_file():
+                    dest_file = rules_dest / f.name
+                    self._safe_copy(f, dest_file, f"regla {f.name}")
+
+    def _safe_copy(self, src: Path, dest: Path, label: str) -> None:
+        try:
+            if src.resolve() != dest.resolve():
+                shutil.copy2(src, dest)
+        except Exception as e:
+            _log.warning(f"[!] Error al copiar {label}: {e}")
+
+    # --- Claude: .claude/settings.json ---
+
+    def _render_claude(self, hooks: list[HookDefinition]) -> None:
+        settings_path = self.project_root / ".claude" / SETTINGS_JSON
+        settings_path.parent.mkdir(parents=True, exist_ok=True)
+
+        existing = self._load_existing_settings(settings_path)
+
+        all_shell = {"Bash", "PowerShell"}
+        active_shell = self._shell_matchers()
+
+        hook_map: dict[str, list[dict]] = {}
+        for h in hooks:
+            matcher = h.matcher or ""
+            if matcher in all_shell and matcher not in active_shell:
+                continue
+            entry = {
+                "type": "command",
+                "command": f"{self._python_cmd()} {self._script_path(h.script)}",
+                "timeout": h.timeout,
+                "statusMessage": h.description[:60] if h.description else "",
+            }
+            group = hook_map.setdefault(h.event, [])
+            existing_group = next((g for g in group if g.get("matcher") == matcher), None)
+            if existing_group:
+                existing_group["hooks"].append(entry)
+            else:
+                group.append({"matcher": matcher, "hooks": [entry]})
+
+        # SonarQube S7500 compliant: use dict() constructor instead of dict comprehension
+        existing["hooks"] = dict(hook_map)
+        settings_path.write_text(
+            json.dumps(existing, indent=4, ensure_ascii=False), encoding="utf-8"
+        )
+
+    # --- Gemini: .gemini/settings.json ---
+
+    def _render_gemini(self, hooks: list[HookDefinition]) -> None:
+        settings_path = self.project_root / ".gemini" / SETTINGS_JSON
+        self._render_gemini_family(hooks, settings_path)
+
+    def _render_gemini_family(self, hooks: list[HookDefinition], settings_path: Path) -> None:
+        settings_path.parent.mkdir(parents=True, exist_ok=True)
+        existing = self._load_existing_settings(settings_path)
+
+        all_shell = {"Bash", "PowerShell"}
+        active_shell = self._shell_matchers()
+        hook_map: dict[str, list[dict]] = {}
+
+        for h in hooks:
+            if h.matcher in all_shell and h.matcher not in active_shell:
+                continue
+            self._process_gemini_hook(h, hook_map)
+
+        existing["hooks"] = hook_map
+        settings_path.write_text(
+            json.dumps(existing, indent=2, ensure_ascii=False), encoding="utf-8"
+        )
+
+    def _load_existing_settings(self, settings_path: Path) -> dict:
+        if settings_path.exists():
+            try:
+                return json.loads(settings_path.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                pass
+        return {}
+
+    def _process_gemini_hook(self, h: HookDefinition, hook_map: dict[str, list[dict]]) -> None:
+        # Generic event mapping -> Gemini CLI
+        event_mapping = {
+            "PreToolUse": "BeforeTool",
+            "PostToolUse": "AfterTool",
+            "Stop": "SessionEnd",
+            "Notification": "Notification",
+            "UserPromptSubmit": "BeforeAgent",
+            "SessionStart": "SessionStart",
+            "BeforeModel": "BeforeModel",
+            "AfterModel": "AfterModel",
+            "AfterAgent": "AfterAgent",
+            "BeforeToolSelection": "BeforeToolSelection",
+            "PreCompact": "PreCompact",
+        }
+        gemini_event = event_mapping.get(h.event, h.event)
+
+        # SonarQube python:S3358 compliant: Extract nested conditional expression
+        hook_name = "higpertext-hook"
+        if h.id:
+            hook_name = h.id
+        elif h.description:
+            hook_name = h.description[:40]
+
+        entry = {
+            "name": hook_name,
+            "type": "command",
+            "command": f"{self._python_cmd()} {self._script_path(h.script)}",
+            "timeout": h.timeout * 1000,
+        }
+
+        matcher = h.matcher
+        if matcher in ("Bash", "PowerShell"):
+            matcher = "run_shell_command"
+        elif not matcher:
+            matcher = ".*"
+
+        group = hook_map.setdefault(gemini_event, [])
+        existing_group = next((g for g in group if g.get("matcher") == matcher), None)
+        if existing_group:
+            existing_group["hooks"].append(entry)
+        else:
+            group.append({"matcher": matcher, "hooks": [entry]})
+
+    # --- Antigravity AI: .agents/hooks + opencode.json plugin ---
+
+    def _render_antigravity(self, hooks: list[HookDefinition]) -> None:
+        settings_path = self.project_root / ".agents" / SETTINGS_JSON
+        self._render_gemini_family(hooks, settings_path)
+
+    # --- OpenCode (opencode.ai): .opencode/hooks + plugin JS nativo ---
+
+    def _render_opencode(self, hooks: list[HookDefinition]) -> None:
+        config_path = self.project_root / "opencode.json"
+        existing: dict = {}
+        if config_path.exists():
+            try:
+                existing = json.loads(config_path.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                pass
+
+        plugin_path = self._render_opencode_plugin(hooks)
+        plugins = existing.get("plugin", [])
+        if not isinstance(plugins, list):
+            plugins = []
+        if plugin_path not in plugins:
+            plugins.append(plugin_path)
+        existing["plugin"] = plugins
+        existing.pop("hooks", None)
+        config_path.write_text(json.dumps(existing, indent=2, ensure_ascii=False), encoding="utf-8")
+
+    def _render_opencode_plugin(self, hooks: list[HookDefinition]) -> str:
+        plugin_dir = self.project_root / ".opencode" / "plugin"
+        plugin_dir.mkdir(parents=True, exist_ok=True)
+        self._ensure_opencode_plugin_package(plugin_dir.parent)
+        plugin_path = plugin_dir / "higpertext-hooks.js"
+        all_shell = {"Bash", "PowerShell"}
+        active_shell = self._shell_matchers()
+        entries = [
+            {
+                "id": h.id,
+                "event": h.event,
+                "matcher": h.matcher,
+                "script": self._script_path(h.script),
+                "timeout": h.timeout,
+            }
+            for h in hooks
+            if h.matcher not in all_shell or h.matcher in active_shell
+        ]
+        plugin_path.write_text(self._opencode_plugin_source(entries), encoding="utf-8")
+        return "./.opencode/plugin/higpertext-hooks.js"
+
+    def _ensure_opencode_plugin_package(self, opencode_dir: Path) -> None:
+        package_path = opencode_dir / "package.json"
+        data: dict = {}
+        if package_path.exists():
+            try:
+                data = json.loads(package_path.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                data = {}
+        data["type"] = "module"
+        package_path.write_text(
+            json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+        )
+
+    def _opencode_plugin_source(self, hooks: list[dict]) -> str:
+        hooks_json = json.dumps(hooks, ensure_ascii=False, indent=2)
+        python_cmd = json.dumps(self._python_cmd())
+        python_path = json.dumps(self._resolve_engine_path("src").as_posix())
+        htx_path = json.dumps((self.project_root / "htx.py").as_posix())
+        return f"""import {{ spawnSync }} from "node:child_process";
+import {{ tool }} from "@opencode-ai/plugin";
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+const hooks = {hooks_json};
+const pythonCmd = {python_cmd};
+const pythonPath = {python_path};
+const htxPath = {htx_path};
+
+function canonicalToolName(input) {{
+  const raw = input?.tool || input?.toolID || input?.toolName || input?.name || "";
+  const map = {{ bash: "Bash", edit: "Edit", write: "Write", read: "Read" }};
+  return map[String(raw).toLowerCase()] || String(raw);
+}}
+
+function matches(hook, toolName) {{
+  if (!hook.matcher) return true;
+  return new RegExp(`^(${{hook.matcher}})$`, "i").test(toolName);
+}}
+
+function hooksForEvent(eventName) {{
+  return hooks.filter((h) => h.event === eventName);
+}}
+
+function runHook(hook, payload) {{
+  const result = spawnSync(pythonCmd, [hook.script], {{
+    input: JSON.stringify(payload),
+    encoding: "utf8",
+    timeout: hook.timeout * 1000,
+    cwd: process.cwd(),
+    env: {{
+      ...process.env,
+      PYTHONPATH: [pythonPath, process.env.PYTHONPATH].filter(Boolean).join(":"),
+    }},
+  }});
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(result.stderr || `Hook ${{hook.id}} failed`);
+  if (!result.stdout) return {{ parsed: undefined, context: "", visibleContext: "" }};
+  const parsed = JSON.parse(result.stdout);
+  const context = parsed.hookSpecificOutput?.additionalContext || parsed.stopReason;
+  const visibleContext = context ? formatContextForOpencode(hook, context) : "";
+
+  if (parsed.continue === false) throw new Error(context || `Hook ${{hook.id}} blocked execution`);
+
+  return {{ parsed, context, visibleContext }};
+}}
+
+function addContextToBashCommand(output, context) {{
+  if (context) {{
+    const args = output?.args || {{}};
+    const command = args.command || args.CommandLine;
+    if (!command) return;
+
+    const banner = `printf '%s\\n' ${{shellQuote(`[HIGPERTEXT]\\n${{context}}`)}}`;
+    if (args.command) args.command = `${{banner}}\\n${{command}}`;
+    else args.CommandLine = `${{banner}}\\n${{command}}`;
+  }}
+}}
+
+function addContextToToolOutput(output, context) {{
+  if (!context || !output) return;
+  const banner = `\\n\\n[HIGPERTEXT]\\n${{context}}`;
+  output.output = `${{output.output || ""}}${{banner}}`;
+}}
+
+function addContextToCompaction(output, context) {{
+  if (!context || !output) return;
+  output.context = output.context || [];
+  output.context.push(`[HIGPERTEXT]\\n${{context}}`);
+}}
+
+function shellQuote(value) {{
+  return `'${{String(value).replace(/'/g, `'"'"'`)}}'`;
+}}
+
+function formatContextForOpencode(hook, context) {{
+  if (process.env.HIGPERTEXT_OPENCODE_VERBOSE === "1") return context;
+  if (hook.id !== "hook_session_prompt") return context;
+
+  // Keep command-specific warnings expanded; they contain required actions.
+  if (/ACCI[ÓO]N REQUERIDA|REQUERIDO|Checkpoint|Reiniciada/i.test(context)) {{
+    return context;
+  }}
+
+  const lines = String(context).split(/\\r?\\n/).map((line) => line.trim()).filter(Boolean);
+
+  if (lines.some((line) => line.includes("Sesión activa"))) {{
+    const sessionLine = lines.find((line) => line.includes("perfil:")) || "";
+    const sessionMatch = sessionLine.match(/│\\s*([^·]+?)\\s*·\\s*perfil:\\s*(.+)$/);
+    const sessionId = sessionMatch?.[1]?.trim() || "sesión activa";
+    const profile = sessionMatch?.[2]?.trim() || "perfil activo";
+    const skills = countListItems(extractValue(lines, "Skills"));
+    const subagents = countListItems(extractValue(lines, "Subagentes"));
+    const contextEngine = summarizeContextEngine(lines);
+
+    return [
+      `HIGPERTEXT · ${{profile}} · skills:${{skills}} · subagents:${{subagents}} · ${{sessionId}}`,
+      contextEngine,
+    ].filter(Boolean).join("\\n");
+  }}
+
+  if (lines.some((line) => line.includes("Sin sesión activa"))) {{
+    const profile = extractValue(lines, "Perfil") || "perfil no detectado";
+    return `HIGPERTEXT · sin sesión activa · ${{profile}} · usa session-start`;
+  }}
+
+  return context;
+}}
+
+function extractValue(lines, label) {{
+  const line = lines.find((entry) => new RegExp(`^│\\\\s*${{label}}\\\\s*:`, "i").test(entry));
+  return line?.replace(new RegExp(`^│\\\\s*${{label}}\\\\s*:\\\\s*`, "i"), "").trim() || "";
+}}
+
+function countListItems(value) {{
+  if (!value || value === "—") return 0;
+  return value.split(",").map((item) => item.trim()).filter(Boolean).length;
+}}
+
+function summarizeContextEngine(lines) {{
+  if (!lines.some((line) => line.includes("Context Engine"))) return "";
+  const tokens = extractValue(lines, "Tokens estimados");
+  const symbols = extractValue(lines, "Símbolos");
+  const memories = extractValue(lines, "Memorias");
+  return `HIGPERTEXT · context engine · tokens:${{tokens || "—"}}`
+    + ` · símbolos:${{symbols || 0}} · memorias:${{memories || 0}}`;
+}}
+
+function payloadFor(event, input, output) {{
+  const toolName = canonicalToolName(input);
+  const toolInput =
+    event === "PreToolUse"
+      ? input?.args || input?.parameters || input?.tool?.args || {{}}
+      : output?.args || input?.args || input?.parameters || {{}};
+  const toolResponse =
+    event === "PostToolUse"
+      ? output?.result || output?.output || input?.result || {{}}
+      : {{}};
+  return {{ event, tool_name: toolName, tool_input: toolInput, tool_response: toolResponse }};
+}}
+
+function runHigpertextTask(args, context) {{
+  const params = args.parameters || {{}};
+  const cliArgs = [htxPath, "task"];
+  if (args.no_cache) cliArgs.push("--no-cache");
+  cliArgs.push(args.name);
+
+  for (const [key, value] of Object.entries(params)) {{
+    if (value === undefined || value === null || value === false) continue;
+    const flag = `--${{key.replace(/_/g, "-")}}`;
+    if (value === true) cliArgs.push(flag);
+    else cliArgs.push(flag, String(value));
+  }}
+
+  const result = spawnSync(pythonCmd, cliArgs, {{
+    encoding: "utf8",
+    timeout: (args.timeout_seconds || 120) * 1000,
+    cwd: context?.directory || process.cwd(),
+    env: {{
+      ...process.env,
+      PYTHONPATH: [pythonPath, process.env.PYTHONPATH].filter(Boolean).join(":"),
+    }},
+  }});
+
+  const output = [
+    result.stdout || "",
+    result.stderr ? `\\n[stderr]\\n${{result.stderr}}` : "",
+  ].join("").trim();
+
+  if (result.error) throw result.error;
+
+  return {{
+    title: `higpertext task ${{args.name}}`,
+    output: output || `[higpertext] exit code ${{result.status}}`,
+    metadata: {{
+      capability: args.name,
+      returncode: result.status,
+      command: [pythonCmd, ...cliArgs].join(" "),
+    }},
+  }};
+}}
+
+function runHigpertextWorkflow(args, context) {{
+  const params = args.parameters || {{}};
+  const cliArgs = [htxPath, "workflow", "run", args.name];
+  if (args.no_cache) cliArgs.push("--no-cache");
+
+  for (const [key, value] of Object.entries(params)) {{
+    if (value === undefined || value === null || value === false) continue;
+    const flag = `--${{key.replace(/_/g, "-")}}`;
+    if (value === true) cliArgs.push(flag);
+    else cliArgs.push(flag, String(value));
+  }}
+
+  const result = spawnSync(pythonCmd, cliArgs, {{
+    encoding: "utf8",
+    timeout: (args.timeout_seconds || 120) * 1000,
+    cwd: context?.directory || process.cwd(),
+    env: {{
+      ...process.env,
+      PYTHONPATH: [pythonPath, process.env.PYTHONPATH].filter(Boolean).join(":"),
+    }},
+  }});
+
+  const output = [
+    result.stdout || "",
+    result.stderr ? `\\n[stderr]\\n${{result.stderr}}` : "",
+  ].join("").trim();
+
+  if (result.error) throw result.error;
+
+  return {{
+    title: `higpertext workflow ${{args.name}}`,
+    output: output || `[higpertext] exit code ${{result.status}}`,
+    metadata: {{
+      workflow: args.name,
+      returncode: result.status,
+      command: [pythonCmd, ...cliArgs].join(" "),
+    }},
+  }};
+}}
+
+function opencodeEventType(input) {{
+  return input?.event?.type || input?.type || "";
+}}
+
+export default async () => {{
+  return {{
+    tool: {{
+      higpertext_task: tool({{
+        description: "Ejecuta una capability de higpertext: python htx.py task <name> con parámetros opcionales.",
+        args: {{
+          name: tool.schema.string().describe(
+            "ID de capability, por ejemplo common.graph-query o common.session-start"),
+          parameters: tool.schema.record(tool.schema.string(), tool.schema.any())
+            .optional().describe("Parámetros de la capability como objeto {{ parametro: valor }}"),
+          no_cache: tool.schema.boolean().optional().describe("Ejecutar con --no-cache"),
+          timeout_seconds: tool.schema.number().optional()
+            .describe("Timeout de ejecución en segundos; default 120"),
+        }},
+        execute: async (args, context) => runHigpertextTask(args, context),
+      }}),
+      higpertext_workflow: tool({{
+        description: "Ejecuta un workflow de higpertext: python htx.py workflow run <name>.",
+        args: {{
+          name: tool.schema.string().describe("ID de workflow: spec, plan, build o review"),
+          parameters: tool.schema.record(tool.schema.string(), tool.schema.any())
+            .optional().describe("Parámetros del workflow como objeto {{ parametro: valor }}"),
+          no_cache: tool.schema.boolean().optional().describe("Ejecutar con --no-cache"),
+          timeout_seconds: tool.schema.number().optional()
+            .describe("Timeout de ejecución en segundos; default 120"),
+        }},
+        execute: async (args, context) => runHigpertextWorkflow(args, context),
+      }}),
+    }},
+    "tool.execute.before": async (input, output) => {{
+      const toolName = canonicalToolName(input);
+      for (const hook of hooksForEvent("PreToolUse").filter((h) => matches(h, toolName))) {{
+        const result = runHook(hook, payloadFor("PreToolUse", input, output));
+        if (toolName === "Bash") addContextToBashCommand(output, result?.visibleContext);
+      }}
+    }},
+    "tool.execute.after": async (input, output) => {{
+      const toolName = canonicalToolName(input);
+      if (!["Bash", "Edit", "Write", "Read"].includes(toolName)) return;
+      for (const hook of hooksForEvent("PostToolUse").filter((h) => matches(h, toolName))) {{
+        const result = runHook(hook, payloadFor("PostToolUse", input, output));
+        if (result?.parsed?.hookSpecificOutput?.replacementOutput) {{
+          output.output = result.parsed.hookSpecificOutput.replacementOutput;
+        }} else {{
+          addContextToToolOutput(output, result?.visibleContext);
+        }}
+      }}
+    }},
+    "chat.message": async (input, output) => {{
+      const text = output?.message?.text || input?.message?.text || input?.text || "";
+      for (const hook of hooksForEvent("UserPromptSubmit")) {{
+        const result = runHook(hook, {{ event: "UserPromptSubmit", prompt: text }});
+        if (result?.visibleContext && output?.message) {{
+          output.message.text = `${{output.message.text || text}}\\n\\n${{result.visibleContext}}`;
+        }}
+      }}
+    }},
+    "experimental.session.compacting": async (input, output) => {{
+      for (const hook of hooksForEvent("PreCompact")) {{
+        const result = runHook(hook, {{ event: "PreCompact", sessionID: input?.sessionID }});
+        addContextToCompaction(output, result?.visibleContext);
+      }}
+    }},
+    event: async (input) => {{
+      if (opencodeEventType(input) !== "session.idle") return;
+      for (const hook of hooksForEvent("Stop")) {{
+        runHook(hook, {{
+          event: "Stop",
+          opencode_event: opencodeEventType(input),
+          sessionID: input?.event?.properties?.sessionID,
+        }});
+      }}
+    }},
+  }};
+}};
+"""
+
+    # --- Copilot: .github/hooks/higpertext-hooks.json ---
+
+    def _render_copilot(self, hooks: list[HookDefinition]) -> None:
+        hooks_dir = self.project_root / ".github" / "hooks"
+        hooks_dir.mkdir(parents=True, exist_ok=True)
+        config_path = hooks_dir / "higpertext-hooks.json"
+
+        # Mapeo de eventos genéricos → Copilot CLI
+        event_mapping = {
+            "PreToolUse": "preToolUse",
+            "PostToolUse": "postToolUse",
+            "Stop": "sessionEnd",
+            "SessionStart": "sessionStart",
+            "UserPromptSubmit": "userPromptSubmitted",
+        }
+
+        copilot_hooks: dict[str, list[dict]] = {
+            "sessionStart": [],
+            "sessionEnd": [],
+            "userPromptSubmitted": [],
+            "preToolUse": [],
+            "postToolUse": [],
+            "errorOccurred": [],
+        }
+
+        for h in hooks:
+            copilot_event = event_mapping.get(h.event)
+            if not copilot_event:
+                continue
+
+            entry = {
+                "type": "command",
+                "bash": f"{self._python_cmd()} {self._script_path(h.script)}",
+                "powershell": f"{self._python_cmd()} {self._script_path(h.script)}",
+                "timeoutSec": h.timeout,
+            }
+            copilot_hooks[copilot_event].append(entry)
+
+        # Limpiar listas vacías para mantener el JSON limpio
+        active_hooks = {k: v for k, v in copilot_hooks.items() if v}
+
+        output = {"version": 1, "hooks": active_hooks}
+
+        config_path.write_text(json.dumps(output, indent=2, ensure_ascii=False), encoding="utf-8")
+        _log.ok(f"[*] Hooks nativos de Copilot CLI generados en: {config_path}")