hanuscode 1.0.0__py3-none-any.whl

hanus/tools.py

@@ -0,0 +1,1849 @@
+# tools.py
+"""
+Todas las herramientas del agente con su lógica de ejecución.
+Incluye: bash, archivo (leer/escribir/editar/crear/append), glob, grep,
+git, web_fetch, web_search, notebook_edit, structured_output y más.
+"""
+from __future__ import annotations
+import json
+import os
+import re
+import shlex
+import subprocess
+import urllib.request
+import urllib.parse
+from pathlib import Path
+from typing import Dict, Any, List, Optional, Tuple
+
+
+# ─── Resultado unificado ──────────────────────────────────────────────────────
+
+class ToolResult:
+    def __init__(self, output: str = "", error: str = "", success: bool = True):
+        self.output  = output
+        self.error   = error
+        self.success = success
+
+    def to_str(self) -> str:
+        parts = []
+        if self.output.strip():
+            parts.append(self.output.strip())
+        if self.error.strip():
+            parts.append(f"[stderr]\n{self.error.strip()}")
+        return "\n".join(parts) if parts else ("OK" if self.success else "Sin salida")
+
+    @classmethod
+    def ok(cls, msg: str)  -> "ToolResult": return cls(output=msg, success=True)
+    @classmethod
+    def err(cls, msg: str) -> "ToolResult": return cls(error=msg,  success=False)
+
+
+# ─── Executor ─────────────────────────────────────────────────────────────────
+
+class ToolExecutor:
+    MAX_OUTPUT   = 20_000
+    SHELL_TO     = 60
+    PYTHON_TO    = 120
+
+    def __init__(self, root_dir: Path, permission_manager, task_manager=None):
+        self.root  = root_dir
+        self.perms = permission_manager
+        self.tasks = task_manager  # TaskManager instance (optional)
+        self.memory = None  # MemoryManager instance (optional, set later)
+        self.subagents = None  # SubagentManager instance (optional, set later)
+        self.plan_mode = None  # PlanMode instance (optional, set later)
+
+    def execute(self, tool_name: str, args: Dict[str, Any]) -> ToolResult:
+        """Valida permisos y ejecuta la herramienta."""
+        desc     = self._describe(tool_name, args)
+        decision = self.perms.check(tool_name, desc, args)
+        if not decision.approved:
+            return ToolResult.err(f"⛔ Permiso denegado: {decision.reason}")
+
+        handler = getattr(self, f"_tool_{tool_name}", None)
+        if handler is None:
+            return ToolResult.err(f"Herramienta desconocida: '{tool_name}'")
+
+        try:
+            result = handler(args)
+            if result.output and len(result.output) > self.MAX_OUTPUT:
+                result.output = result.output[:self.MAX_OUTPUT] + "\n…(truncado)"
+            return result
+        except Exception as e:
+            return ToolResult.err(f"[{tool_name}] Error: {type(e).__name__}: {e}")
+
+    # ══════════════════════════════════════════════════════════════════════════
+    # HERRAMIENTAS DE LECTURA
+    # ══════════════════════════════════════════════════════════════════════════
+
+    def _tool_read_file(self, args: Dict) -> ToolResult:
+        raw_path = args.get("path", "")
+        path = self._safe(raw_path, must_exist=True)
+        if not path:
+            # Dar sugerencia de rutas similares
+            hint = self._suggest_path(raw_path)
+            msg = f"Archivo no encontrado: '{raw_path}'"
+            if hint:
+                msg += f"\n¿Quisiste decir: {hint}?"
+            return ToolResult.err(msg)
+        if not path.exists():
+            hint = self._suggest_path(raw_path)
+            msg = f"Archivo no existe: {path}"
+            if hint:
+                msg += f"\n¿Quisiste decir: {hint}?"
+            return ToolResult.err(msg)
+        try:
+            content = path.read_text(encoding="utf-8", errors="replace")
+            s = args.get("start_line")
+            e = args.get("end_line")
+            if s is not None or e is not None:
+                lines = content.splitlines()
+                si = int(s or 1) - 1
+                ei = int(e) if e else len(lines)
+                content = "\n".join(lines[si:ei])
+            # Incluir la ruta real en la respuesta para que el modelo la conozca
+            rel = str(path.relative_to(self.root)) if self.root in path.parents else str(path)
+            if rel != raw_path:
+                header = f"[Leyendo: {rel}]\n"
+                return ToolResult.ok(header + content)
+            return ToolResult.ok(content)
+        except Exception as ex:
+            return ToolResult.err(str(ex))
+
+    def _tool_glob_search(self, args: Dict) -> ToolResult:
+        pattern = args.get("pattern", "*")
+        base    = self._safe(args.get("dir", ".")) or self.root
+        IGNORE  = {".git", "__pycache__", "node_modules", "venv", ".venv", "dist", "build"}
+        results = []
+        for p in base.rglob(pattern):
+            if p.is_file() and not any(ig in p.parts for ig in IGNORE):
+                try:
+                    results.append(str(p.relative_to(self.root)))
+                except ValueError:
+                    pass
+        return ToolResult.ok("\n".join(results[:200]) if results else "Sin resultados")
+
+    def _tool_grep_search(self, args: Dict) -> ToolResult:
+        raw_pattern = args.get("pattern", "")
+        base        = self._safe(args.get("dir", ".")) or self.root
+        use_regex   = args.get("regex", False)
+        ctx_lines   = int(args.get("context", 0))
+
+        if not raw_pattern:
+            return ToolResult.err("pattern requerido")
+
+        # Si el patrón contiene | o el usuario pidió regex → siempre usar re.search
+        # Esto permite grep_search pattern="foo|bar|baz" y funciona como OR
+        has_pipe = "|" in raw_pattern
+        if has_pipe or use_regex:
+            try:
+                compiled = re.compile(raw_pattern, re.IGNORECASE)
+                def match_fn(line: str) -> bool:
+                    return bool(compiled.search(line))
+            except re.error as e:
+                return ToolResult.err(f"Patrón regex inválido '{raw_pattern}': {e}")
+        else:
+            # Búsqueda literal case-insensitive
+            needle = raw_pattern.lower()
+            def match_fn(line: str) -> bool:
+                return needle in line.lower()
+
+        IGNORE = {".git", "__pycache__", "node_modules", "venv", ".venv", "dist", "build"}
+        EXTS   = {".py", ".js", ".ts", ".jsx", ".tsx", ".md", ".txt", ".yaml", ".yml",
+                  ".toml", ".json", ".html", ".css", ".go", ".rs", ".java", ".rb",
+                  ".php", ".c", ".cpp", ".h", ".cs", ".sh", ".env", ".cfg", ".ini"}
+        found = []
+        for p in sorted(base.rglob("*")):
+            if not p.is_file() or any(ig in p.parts for ig in IGNORE):
+                continue
+            if p.suffix not in EXTS:
+                continue
+            try:
+                text  = p.read_text(encoding="utf-8", errors="replace")
+                lines = text.splitlines()
+                for i, line in enumerate(lines, 1):
+                    if match_fn(line):
+                        rel = str(p.relative_to(self.root))
+                        found.append(f"{rel}:{i}: {line.rstrip()}")
+                        if ctx_lines > 0:
+                            start = max(0, i - ctx_lines - 1)
+                            end   = min(len(lines), i + ctx_lines)
+                            for j in range(start, end):
+                                if j + 1 != i:
+                                    found.append(f"  {j+1}: {lines[j].rstrip()}")
+                        if len(found) >= 400:
+                            break
+            except Exception:
+                continue
+            if len(found) >= 400:
+                break
+
+        if not found:
+            return ToolResult.ok(f"Sin resultados para '{raw_pattern}'")
+        header = f"{len(found)} resultado(s) para '{raw_pattern}'"
+        if len(found) == 400:
+            header += " (truncado a 400)"
+        return ToolResult.ok(f"{header}:\n" + "\n".join(found))
+
+    def _tool_list_files(self, args: Dict) -> ToolResult:
+        base   = self._safe(args.get("dir", ".")) or self.root
+        IGNORE = {".git", "__pycache__", "node_modules", "venv", ".venv"}
+        files  = []
+        for p in sorted(base.rglob("*")):
+            if p.is_file() and not any(ig in p.parts for ig in IGNORE):
+                try:
+                    files.append(str(p.relative_to(self.root)))
+                except ValueError:
+                    pass
+        return ToolResult.ok("\n".join(files[:300]))
+
+    # ══════════════════════════════════════════════════════════════════════════
+    # HERRAMIENTAS DE ESCRITURA
+    # ══════════════════════════════════════════════════════════════════════════
+
+    def _tool_write_file(self, args: Dict) -> ToolResult:
+        return self._write(args, "w")
+
+    def _tool_create_file(self, args: Dict) -> ToolResult:
+        path = self._safe(args.get("path", ""))
+        if not path:
+            return ToolResult.err("path requerido y dentro del proyecto")
+        if path.exists() and not args.get("overwrite", False):
+            return ToolResult.err(f"El archivo ya existe: {path.relative_to(self.root)}. Usa write_file para sobrescribir.")
+        return self._write(args, "w")
+
+    def _tool_append_to_file(self, args: Dict) -> ToolResult:
+        return self._write(args, "a")
+
+    def _tool_file_edit(self, args: Dict) -> ToolResult:
+        """Búsqueda y reemplazo en archivo (texto exacto o regex)."""
+        path = self._safe(args.get("path", ""))
+        if not path or not path.exists():
+            return ToolResult.err(f"Archivo no existe: {args.get('path', '?')}")
+        search    = args.get("search", "")
+        replace   = args.get("replace", "")
+        use_regex = args.get("regex", False)
+        if not search:
+            return ToolResult.err("Parámetro 'search' requerido")
+        content = path.read_text(encoding="utf-8", errors="replace")
+        if use_regex:
+            new_content, n = re.subn(search, replace, content)
+        else:
+            n = content.count(search)
+            new_content = content.replace(search, replace)
+        if n == 0:
+            return ToolResult.err(f"Patrón no encontrado: {search!r}")
+        path.write_text(new_content, encoding="utf-8")
+        return ToolResult.ok(f"✓ {n} reemplazo(s) en {path.relative_to(self.root)}")
+
+    def _tool_edit_file(self, args: Dict) -> ToolResult:
+        """
+        Edición con verificación de string exacto (estilo Claude Code).
+        Más seguro que file_edit - requiere que old_str sea único en el archivo.
+        """
+        path = self._safe(args.get("path", ""))
+        if not path:
+            return ToolResult.err("path requerido y dentro del proyecto")
+        if not path.exists():
+            return ToolResult.err(f"Archivo no existe: {path.relative_to(self.root)}")
+
+        old_str = args.get("old_str", "")
+        new_str = args.get("new_str", "")
+
+        if not old_str:
+            return ToolResult.err("old_str es requerido y no puede estar vacío")
+
+        content = path.read_text(encoding="utf-8", errors="replace")
+
+        # Verificar que old_str existe exactamente
+        if old_str not in content:
+            similar = self._find_similar(content, old_str)
+            if similar:
+                return ToolResult.err(
+                    f"old_str no encontrado en el archivo.\n"
+                    f"Texto similar encontrado:\n---\n{similar}\n---\n"
+                    f"Tu old_str (primeros 500 chars):\n---\n{old_str[:500]}\n---"
+                )
+            return ToolResult.err(
+                f"old_str no encontrado en el archivo.\n"
+                f"Buscado ({len(old_str)} caracteres):\n---\n{old_str[:500]}{'...' if len(old_str) > 500 else ''}\n---"
+            )
+
+        # Verificar que old_str es único
+        count = content.count(old_str)
+        if count > 1:
+            lines = content.splitlines()
+            locations = []
+            for i, line in enumerate(lines, 1):
+                if old_str in line:
+                    locations.append(f"  Línea {i}: {line[:60]}{'...' if len(line) > 60 else ''}")
+                    if len(locations) >= 5:
+                        locations.append(f"  ... y {count - 5} más")
+                        break
+            return ToolResult.err(
+                f"old_str encontrado {count} veces en el archivo. Debe ser único.\n"
+                f"Ubicaciones:\n" + "\n".join(locations)
+            )
+
+        # Realizar la edición
+        new_content = content.replace(old_str, new_str, 1)
+        path.write_text(new_content, encoding="utf-8")
+
+        rel_path = path.relative_to(self.root)
+        return ToolResult.ok(
+            f"✓ Editado {rel_path}\n"
+            f"  Reemplazados {len(old_str)} chars por {len(new_str)} chars"
+        )
+
+    def _find_similar(self, content: str, target: str, threshold: float = 0.7) -> str:
+        """Encuentra texto similar en el contenido para sugerencias."""
+        import difflib
+
+        # Dividir en líneas para comparación
+        lines = content.splitlines()
+        target_first_line = target.split("\n")[0][:100]
+
+        # Buscar líneas similares
+        matches = difflib.get_close_matches(target_first_line, lines, n=3, cutoff=threshold)
+        if matches:
+            results = []
+            for match in matches[:2]:
+                idx = lines.index(match)
+                start = max(0, idx - 2)
+                end = min(len(lines), idx + 3)
+                context = "\n".join(f"  {i+1}: {lines[i]}" for i in range(start, end))
+                results.append(context)
+            return "\n---\n".join(results)
+
+        return ""
+
+    def _write(self, args: Dict, mode: str) -> ToolResult:
+        path = self._safe(args.get("path", ""))
+        if not path:
+            return ToolResult.err("path requerido y dentro del proyecto")
+        content = args.get("content", "")
+        path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            with open(path, mode, encoding="utf-8") as f:
+                if mode == "a" and path.stat().st_size > 0:
+                    f.write("\n")
+                f.write(content)
+            size = path.stat().st_size
+            lines = content.count('\n') + 1 if content else 0
+            rel  = path.relative_to(self.root)
+            # Mensaje de confirmación claro y enfático
+            return ToolResult.ok(
+                f"✓ FILE WRITTEN: {rel}\n"
+                f"  Size: {size:,} bytes | Lines: {lines}\n"
+                f"  DO NOT rewrite this file. Move to next task."
+            )
+        except Exception as ex:
+            return ToolResult.err(str(ex))
+
+    # ══════════════════════════════════════════════════════════════════════════
+    # HERRAMIENTAS DE EJECUCIÓN (bash / python)
+    # ══════════════════════════════════════════════════════════════════════════
+
+    def _tool_exec_cmd(self, args: Dict) -> ToolResult:
+        cmd = args.get("cmd") or args.get("command", "")
+        if not cmd:
+            return ToolResult.err("Parámetro 'cmd' requerido")
+        try:
+            # Usar shell=True para soportar operadores como &&, ||, |, >
+            # Esto permite comandos como "cd dir && make && ./test"
+            proc = subprocess.run(
+                cmd,
+                shell=True,
+                cwd=self.root,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                timeout=self.SHELL_TO,
+                env={**os.environ, "PYTHONIOENCODING": "utf-8"},
+            )
+            out = f"[Exit: {proc.returncode}]\n{proc.stdout}"
+            return ToolResult(output=out, error=proc.stderr, success=proc.returncode == 0)
+        except subprocess.TimeoutExpired:
+            return ToolResult.err(f"Timeout tras {self.SHELL_TO}s")
+        except Exception as ex:
+            return ToolResult.err(str(ex))
+
+    def _tool_exec_file(self, args: Dict) -> ToolResult:
+        path = self._safe(args.get("path", ""))
+        if not path or not path.exists():
+            return ToolResult.err(f"Archivo no existe: {args.get('path', '?')}")
+        if path.suffix != ".py":
+            return ToolResult.err("Solo archivos .py")
+        try:
+            proc = subprocess.run(
+                ["python", "-u", str(path)],
+                cwd=self.root,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                timeout=self.PYTHON_TO,
+            )
+            out = f"[Exit: {proc.returncode}]\n{proc.stdout}"
+            return ToolResult(output=out, error=proc.stderr, success=proc.returncode == 0)
+        except subprocess.TimeoutExpired:
+            return ToolResult.err(f"Timeout tras {self.PYTHON_TO}s")
+        except Exception as ex:
+            return ToolResult.err(str(ex))
+
+    # ══════════════════════════════════════════════════════════════════════════
+    # HERRAMIENTAS GIT
+    # ══════════════════════════════════════════════════════════════════════════
+
+    def _tool_git_status(self, args: Dict) -> ToolResult:
+        return self._git("status --short --branch")
+
+    def _tool_git_diff(self, args: Dict) -> ToolResult:
+        extra = args.get("args", "")
+        return self._git(f"diff {extra}".strip())
+
+    def _tool_git_log(self, args: Dict) -> ToolResult:
+        n = int(args.get("n", 10))
+        return self._git(f"log --oneline -{n}")
+
+    def _tool_git_push(self, args: Dict) -> ToolResult:
+        branch = args.get("branch", "")
+        remote = args.get("remote", "origin")
+        return self._git(f"push {remote} {branch}".strip())
+
+    def _tool_git_reset(self, args: Dict) -> ToolResult:
+        mode = args.get("mode", "--soft")
+        ref  = args.get("ref", "HEAD~1")
+        return self._git(f"reset {mode} {ref}")
+
+    def _tool_git_commit(self, args: Dict) -> ToolResult:
+        msg = args.get("message", "chore: auto-commit by Hanus")
+        return self._git(f'commit -am "{msg}"')
+
+    def _tool_git_branch(self, args: Dict) -> ToolResult:
+        name = args.get("name", "")
+        return self._git(f"checkout -b {name}" if name else "branch -a")
+
+    def _git(self, subcmd: str) -> ToolResult:
+        try:
+            proc = subprocess.run(
+                ["git"] + shlex.split(subcmd),
+                cwd=self.root, capture_output=True, text=True, timeout=30,
+            )
+            return ToolResult(
+                output=proc.stdout,
+                error=proc.stderr,
+                success=proc.returncode == 0,
+            )
+        except Exception as ex:
+            return ToolResult.err(str(ex))
+
+    # ══════════════════════════════════════════════════════════════════════════
+    # HERRAMIENTAS WEB
+    # ══════════════════════════════════════════════════════════════════════════
+
+    def _tool_web_fetch(self, args: Dict) -> ToolResult:
+        url = args.get("url", "")
+        if not url:
+            return ToolResult.err("url requerido")
+        blocked = ["localhost", "127.0.0.1", "192.168.", "10.0.", "172.16.", "0.0.0.0"]
+        if any(b in url for b in blocked):
+            return ToolResult.err("URLs internas/locales no permitidas")
+        try:
+            req = urllib.request.Request(
+                url,
+                headers={"User-Agent": "Hanus-Agent/2.0", "Accept": "text/html,*/*"},
+            )
+            with urllib.request.urlopen(req, timeout=15) as r:
+                raw = r.read(500_000)
+                content = raw.decode("utf-8", errors="replace")
+                # Limpiar HTML básico si es HTML
+                ct = r.headers.get("Content-Type", "")
+                if "html" in ct:
+                    content = re.sub(r"<[^>]+>", " ", content)
+                    content = re.sub(r"\s{3,}", "\n", content)
+                return ToolResult.ok(content[:15_000])
+        except Exception as ex:
+            return ToolResult.err(str(ex))
+
+    def _tool_web_search(self, args: Dict) -> ToolResult:
+        """Búsqueda web básica vía DuckDuckGo (sin API key)."""
+        query = args.get("query", "")
+        if not query:
+            return ToolResult.err("query requerido")
+        n = int(args.get("results", 5))
+        try:
+            q_enc = urllib.parse.quote_plus(query)
+            url   = f"https://html.duckduckgo.com/html/?q={q_enc}"
+            req   = urllib.request.Request(url, headers={"User-Agent": "Mozilla/5.0"})
+            with urllib.request.urlopen(req, timeout=10) as r:
+                html = r.read(300_000).decode("utf-8", errors="replace")
+            # Extraer resultados
+            results = re.findall(
+                r'<a[^>]+class="result__a"[^>]*href="([^"]+)"[^>]*>([^<]+)</a>',
+                html
+            )
+            if not results:
+                # Fallback: extraer URLs
+                urls = re.findall(r'href="(https?://[^"]+)"', html)
+                results = [(u, u) for u in urls[:n]]
+            lines = [f"{i+1}. {title.strip()} — {url}" for i, (url, title) in enumerate(results[:n])]
+            return ToolResult.ok(f"Resultados para '{query}':\n" + "\n".join(lines))
+        except Exception as ex:
+            return ToolResult.err(f"Error buscando '{query}': {ex}")
+
+    # ══════════════════════════════════════════════════════════════════════════
+    # HERRAMIENTA: SALIDA ESTRUCTURADA (JSON validado)
+    # ══════════════════════════════════════════════════════════════════════════
+
+    def _tool_structured_output(self, args: Dict) -> ToolResult:
+        """Valida un objeto JSON contra un schema JSON."""
+        try:
+            import jsonschema
+        except ImportError:
+            # Sin jsonschema: solo validar que sea JSON válido
+            try:
+                obj = json.loads(args.get("data", "{}"))
+                return ToolResult.ok(json.dumps(obj, indent=2, ensure_ascii=False))
+            except Exception as ex:
+                return ToolResult.err(f"JSON inválido: {ex}")
+
+        try:
+            data   = json.loads(args.get("data", "{}"))
+            schema = json.loads(args.get("schema", "{}"))
+            jsonschema.validate(data, schema)
+            return ToolResult.ok(json.dumps(data, indent=2, ensure_ascii=False))
+        except jsonschema.ValidationError as ex:
+            return ToolResult.err(f"Validación fallida: {ex.message}")
+        except Exception as ex:
+            return ToolResult.err(str(ex))
+
+    # ══════════════════════════════════════════════════════════════════════════
+    # HERRAMIENTA: JUPYTER NOTEBOOK EDIT
+    # ══════════════════════════════════════════════════════════════════════════
+
+    def _tool_notebook_edit(self, args: Dict) -> ToolResult:
+        path      = self._safe(args.get("path", ""))
+        cell_idx  = args.get("cell_index")
+        new_src   = args.get("source", "")
+        cell_type = args.get("cell_type", "code")
+
+        if not path or not path.exists():
+            return ToolResult.err(f"Notebook no existe: {args.get('path', '?')}")
+        if path.suffix != ".ipynb":
+            return ToolResult.err("Solo archivos .ipynb")
+        try:
+            nb = json.loads(path.read_text(encoding="utf-8"))
+            cells = nb.get("cells", [])
+            if cell_idx is None:
+                # Añadir nueva celda al final
+                cells.append({
+                    "cell_type": cell_type,
+                    "metadata": {},
+                    "source": new_src.splitlines(keepends=True),
+                    "outputs": [],
+                    "execution_count": None,
+                })
+                action = "añadida"
+            else:
+                idx = int(cell_idx)
+                if idx < 0 or idx >= len(cells):
+                    return ToolResult.err(f"Índice {idx} fuera de rango (0..{len(cells)-1})")
+                cells[idx]["source"] = new_src.splitlines(keepends=True)
+                action = f"editada (celda {idx})"
+            nb["cells"] = cells
+            path.write_text(json.dumps(nb, indent=1, ensure_ascii=False), encoding="utf-8")
+            return ToolResult.ok(f"✓ Celda {action} en {path.relative_to(self.root)}")
+        except Exception as ex:
+            return ToolResult.err(str(ex))
+
+    # ══════════════════════════════════════════════════════════════════════════
+    # HELPERS
+    # ══════════════════════════════════════════════════════════════════════════
+
+    def _suggest_path(self, path_str: str) -> str:
+        """Sugiere rutas similares cuando un archivo no se encuentra."""
+        if not path_str:
+            return ""
+        IGNORE = {".git", "__pycache__", "node_modules", "venv", ".venv", "dist", "build"}
+        filename = Path(path_str).name
+        if not filename or "." not in filename:
+            return ""
+        candidates = []
+        try:
+            for f in self.root.rglob(filename):
+                if f.is_file() and not any(ig in f.parts for ig in IGNORE):
+                    try:
+                        candidates.append(str(f.relative_to(self.root)))
+                    except ValueError:
+                        pass
+        except Exception:
+            pass
+        if not candidates:
+            return ""
+        if len(candidates) == 1:
+            return candidates[0]
+        return " o ".join(candidates[:3])
+
+    def _safe(self, path_str: str, must_exist: bool = False) -> Optional[Path]:
+        """
+        Resuelve una ruta de forma robusta. Intenta en orden:
+        1. Ruta relativa bajo root tal cual
+        2. Limpiar prefijos comunes (./,  /, leading dirs no existentes)
+        3. Buscar por sufijo de ruta (a/b/c.py → busca **/**/b/c.py)
+        4. Fuzzy por nombre de archivo solo
+        5. Para escritura: devuelve la ruta resuelta aunque no exista
+        """
+        if not path_str:
+            return None
+
+        IGNORE = {".git", "__pycache__", "node_modules", "venv", ".venv", "dist", "build"}
+
+        # Normalizar: quitar \\ de Windows, leading ./
+        path_str = path_str.replace("\\", "/").strip()
+        if path_str.startswith("./"):
+            path_str = path_str[2:]
+
+        # ── Intento 1: ruta relativa directa bajo root ────────────────────────
+        try:
+            p = (self.root / path_str).resolve()
+            if p == self.root or self.root in p.parents:
+                if p.exists():
+                    return p
+                if not must_exist:
+                    return p  # para escritura de archivos nuevos
+        except Exception:
+            pass
+
+        # ── Intento 2: ruta absoluta dentro de root ───────────────────────────
+        try:
+            p2 = Path(path_str).resolve()
+            if (p2 == self.root or self.root in p2.parents) and p2.exists():
+                return p2
+        except Exception:
+            pass
+
+        # ── Intento 3: sufijo de ruta (maneja prefijos incorrectos) ──────────
+        # Ejemplo: 'hanus/ui.py' → busca **/*.../ui.py con hanus/ui.py como sufijo
+        # Esto resuelve cuando el modelo usa un prefix incorrecto como nombre de paquete
+        try:
+            target_parts = Path(path_str).parts  # ('hanus', 'ui.py') o ('src', 'api', 'routes.py')
+            if len(target_parts) >= 2:
+                filename = target_parts[-1]
+                # Buscar todos los archivos con ese nombre
+                candidates = []
+                for f in self.root.rglob(filename):
+                    if f.is_file() and not any(ig in f.parts for ig in IGNORE):
+                        candidates.append(f)
+
+                if len(candidates) == 1:
+                    return candidates[0]
+
+                if len(candidates) > 1:
+                    # Scoring: cuántas partes del path dado coinciden desde el final
+                    best = None
+                    best_score = -1
+                    for c in candidates:
+                        try:
+                            rel_parts = c.relative_to(self.root).parts
+                        except ValueError:
+                            continue
+                        score = 0
+                        for i, part in enumerate(reversed(target_parts)):
+                            idx = -(i + 1)
+                            if abs(idx) <= len(rel_parts) and rel_parts[idx] == part:
+                                score += 1
+                            else:
+                                break
+                        if score > best_score:
+                            best_score = score
+                            best = c
+                    if best and best_score > 0:
+                        return best
+        except Exception:
+            pass
+
+        # ── Intento 4: solo por nombre de archivo (fuzzy) ─────────────────────
+        try:
+            filename = Path(path_str).name
+            if filename and "." in filename:
+                candidates = [
+                    f for f in self.root.rglob(filename)
+                    if f.is_file() and not any(ig in f.parts for ig in IGNORE)
+                ]
+                if len(candidates) == 1:
+                    return candidates[0]
+                if len(candidates) > 1:
+                    # Preferir el que tiene menor profundidad
+                    candidates.sort(key=lambda f: len(f.relative_to(self.root).parts))
+                    return candidates[0]
+        except Exception:
+            pass
+
+        # ── Fallback para escritura: path bajo root aunque no exista ─────────
+        if not must_exist:
+            try:
+                p = (self.root / path_str).resolve()
+                if p == self.root or self.root in p.parents:
+                    return p
+            except Exception:
+                pass
+
+        return None
+
+        return None
+
+    # ══════════════════════════════════════════════════════════════════════════
+    # HERRAMIENTAS DE TAREAS
+    # ══════════════════════════════════════════════════════════════════════════
+
+    def _tool_task_create(self, args: Dict) -> ToolResult:
+        """Create a new tracking task."""
+        if not self.tasks:
+            return ToolResult.err("Task system not initialized")
+
+        subject = args.get("subject", "")
+        if not subject:
+            return ToolResult.err("subject required")
+
+        description = args.get("description", subject)
+        active_form = args.get("activeForm", "")
+        metadata = args.get("metadata", {})
+
+        task = self.tasks.create(
+            subject=subject,
+            description=description,
+            activeForm=active_form,
+            metadata=metadata,
+        )
+
+        return ToolResult.ok(
+            f"✓ Task created:\n"
+            f"  ID: {task.id}\n"
+            f"  Subject: {task.subject}\n"
+            f"  Status: {task.status.value}"
+        )
+
+    def _tool_task_update(self, args: Dict) -> ToolResult:
+        """Update an existing task."""
+        if not self.tasks:
+            return ToolResult.err("Task system not initialized")
+
+        task_id = args.get("taskId", "")
+        if not task_id:
+            return ToolResult.err("taskId required")
+
+        task = self.tasks.get(task_id)
+        if not task:
+            return ToolResult.err(f"Task {task_id} not found")
+
+        update_kwargs = {}
+
+        if "status" in args and args["status"]:
+            update_kwargs["status"] = args["status"]
+
+        # Only update subject if provided and non-empty
+        if "subject" in args and args.get("subject"):
+            update_kwargs["subject"] = args["subject"]
+
+        if "description" in args and args.get("description"):
+            update_kwargs["description"] = args["description"]
+
+        if "addBlockedBy" in args and args.get("addBlockedBy"):
+            update_kwargs["blocked_by"] = list(set(task.blocked_by + args["addBlockedBy"]))
+
+        if "addBlocks" in args and args.get("addBlocks"):
+            update_kwargs["blocks"] = list(set(task.blocks + args["addBlocks"]))
+
+        task = self.tasks.update(task_id, **update_kwargs)
+
+        return ToolResult.ok(
+            f"✓ Task {task_id} updated:\n"
+            f"  Status: {task.status.value}\n"
+            f"  Subject: {task.subject}"
+        )
+
+    def _tool_task_list(self, args: Dict) -> ToolResult:
+        """List all tasks."""
+        if not self.tasks:
+            return ToolResult.err("Task system not initialized")
+
+        return ToolResult.ok(self.tasks.format_status())
+
+    def _tool_task_get(self, args: Dict) -> ToolResult:
+        """Get task details."""
+        if not self.tasks:
+            return ToolResult.err("Task system not initialized")
+
+        task_id = args.get("taskId", "")
+        if not task_id:
+            return ToolResult.err("taskId required")
+
+        task = self.tasks.get(task_id)
+        if not task:
+            return ToolResult.err(f"Task {task_id} not found")
+
+        lines = [
+            f"Task {task.id}:",
+            f"  Subject: {task.subject}",
+            f"  Status: {task.status.value}",
+            f"  Description: {task.description[:200]}{'...' if len(task.description) > 200 else ''}",
+        ]
+
+        if task.blocked_by:
+            lines.append(f"  Blocked by: {', '.join(task.blocked_by)}")
+
+        if task.blocks:
+            lines.append(f"  Blocks: {', '.join(task.blocks)}")
+
+        if task.owner:
+            lines.append(f"  Owner: {task.owner}")
+
+        if task.metadata:
+            lines.append(f"  Metadata: {task.metadata}")
+
+        return ToolResult.ok("\n".join(lines))
+
+    # ══════════════════════════════════════════════════════════════════════════
+    # HERRAMIENTAS DE MEMORIA
+    # ══════════════════════════════════════════════════════════════════════════
+
+    def _tool_memory_save(self, args: Dict) -> ToolResult:
+        """Guarda información en la memoria persistente."""
+        if not self.memory:
+            return ToolResult.err("Sistema de memoria no inicializado")
+
+        from hanus.memory.types import MemoryType
+
+        name = args.get("name", "")
+        mem_type = args.get("type", "project")
+        content = args.get("content", "")
+        description = args.get("description", "")
+
+        if not name:
+            return ToolResult.err("name requerido")
+        if not content:
+            return ToolResult.err(
+                "content requerido.\n\n"
+                "Formato correcto:\n"
+                "<memory_save name=\"nombre\" type=\"project\">\n"
+                "El contenido que quieres guardar va aquí.\n"
+                "</memory_save>\n\n"
+                "O usa el plugin cortex para datos estructurados:\n"
+                "<run_plugin name=\"cortex\" args=\"remember entity_name type key=value\"/>"
+            )
+
+        try:
+            mem_type_enum = MemoryType(mem_type.lower())
+        except ValueError:
+            return ToolResult.err(f"Tipo inválido: {mem_type}. Usar: user, feedback, project, reference")
+
+        entry = self.memory.save_memory(
+            name=name,
+            memory_type=mem_type_enum,
+            content=content,
+            description=description,
+        )
+
+        return ToolResult.ok(
+            f"✓ Memoria guardada:\n"
+            f"  Nombre: {entry.name}\n"
+            f"  Tipo: {entry.memory_type.value}\n"
+            f"  Descripción: {entry.description[:50]}{'...' if len(entry.description) > 50 else ''}"
+        )
+
+    def _tool_memory_search(self, args: Dict) -> ToolResult:
+        """Busca en la memoria persistente."""
+        if not self.memory:
+            return ToolResult.err("Sistema de memoria no inicializado")
+
+        query = args.get("query", "")
+        mem_type = args.get("type")
+
+        if not query:
+            return ToolResult.err("query requerido")
+
+        from hanus.memory.types import MemoryType
+
+        mem_type_enum = None
+        if mem_type:
+            try:
+                mem_type_enum = MemoryType(mem_type.lower())
+            except ValueError:
+                pass
+
+        results = self.memory.search(query)
+
+        if mem_type_enum:
+            results = [r for r in results if r.memory_type == mem_type_enum]
+
+        if not results:
+            return ToolResult.ok(f"No se encontraron memorias para: {query}")
+
+        lines = [f"Memorias encontradas ({len(results)}):\n"]
+        for mem in results[:5]:
+            lines.append(f"**{mem.name}** ({mem.memory_type.value})")
+            if mem.description:
+                lines.append(f"  {mem.description}")
+            lines.append(f"  {mem.content[:100]}{'...' if len(mem.content) > 100 else ''}\n")
+
+        return ToolResult.ok("\n".join(lines))
+
+    def _tool_memory_list(self, args: Dict) -> ToolResult:
+        """Lista memorias por tipo o todas."""
+        if not self.memory:
+            return ToolResult.err("Sistema de memoria no inicializado")
+
+        mem_type = args.get("type")
+
+        from hanus.memory.types import MemoryType
+
+        mem_type_enum = None
+        if mem_type:
+            try:
+                mem_type_enum = MemoryType(mem_type.lower())
+            except ValueError:
+                return ToolResult.err(f"Tipo inválido: {mem_type}")
+
+        if mem_type_enum:
+            memories = self.memory.list_by_type(mem_type_enum)
+            lines = [f"Memorias tipo '{mem_type}':\n"]
+        else:
+            memories = self.memory.list_all()
+            lines = ["Todas las memorias:\n"]
+
+        if not memories:
+            return ToolResult.ok("Sin memorias guardadas.")
+
+        for mem in memories:
+            lines.append(f"- **{mem.name}** ({mem.memory_type.value})")
+            if mem.description:
+                lines.append(f"  {mem.description}")
+
+        return ToolResult.ok("\n".join(lines))
+
+    # ══════════════════════════════════════════════════════════════════════════
+    # HERRAMIENTA DE SUBAGENTES
+    # ══════════════════════════════════════════════════════════════════════════
+
+    def _tool_subagent(self, args: Dict) -> ToolResult:
+        """
+        Ejecuta un subagente especializado.
+
+        Tipos disponibles:
+        - explore: Solo lectura, exploración de código
+        - plan: Planificación y diseño
+        - general: Propósito general con todas las herramientas
+        - review: Revisión de código
+        - test: Escritura y ejecución de tests
+        """
+        if not self.subagents:
+            return ToolResult.err("Sistema de subagentes no inicializado")
+
+        from hanus.subagent.types import SubagentType, SubagentConfig
+
+        agent_type_str = args.get("type", "general")
+        task = args.get("task", "")
+        context = args.get("context", "")
+
+        if not task:
+            return ToolResult.err("task es requerido")
+
+        # Validar tipo
+        try:
+            agent_type = SubagentType(agent_type_str.lower())
+        except ValueError:
+            return ToolResult.err(
+                f"Tipo de subagente inválido: {agent_type_str}. "
+                f"Usa: explore, plan, general, review, test"
+            )
+
+        # Crear configuración
+        config = SubagentConfig(
+            agent_type=agent_type,
+            task_description=task,
+            context=context,
+        )
+
+        # Mostrar inicio en UI
+        import hanus.logger as log
+        log.info(f"▶ 🤖 SUBAGENT [{agent_type.value}] {task[:60]}...")
+
+        # Ejecutar subagente
+        result = self.subagents.execute(config)
+
+        if result.success:
+            log.info(f"✓ 🤖 SUBAGENT [{agent_type.value}] completado")
+            return ToolResult.ok(
+                f"✓ Subagente [{agent_type.value}] completado:\n"
+                f"  Tokens: {result.tokens_used:,}\n"
+                f"  Costo: ${result.cost_usd:.4f}\n\n"
+                f"Resultado:\n{result.output}"
+            )
+        else:
+            log.error(f"✗ 🤖 SUBAGENT [{agent_type.value}] falló: {result.error}")
+            return ToolResult.err(
+                f"✗ Subagente [{agent_type.value}] falló:\n"
+                f"  Error: {result.error}"
+            )
+
+    # ══════════════════════════════════════════════════════════════════════════
+    # HERRAMIENTAS DE PLAN MODE
+    # ══════════════════════════════════════════════════════════════════════════
+
+    def _tool_plan_create(self, args: Dict) -> ToolResult:
+        """Crea un nuevo plan de implementación."""
+        if not self.plan_mode:
+            return ToolResult.err("Sistema de planificación no inicializado")
+
+        title = args.get("title", "").strip() or "Plan sin título"
+        description = args.get("description", "").strip()
+
+        plan = self.plan_mode.create_plan(title, description)
+        return ToolResult.ok(
+            f"Plan creado: {plan.id}\n"
+            f"Título: {plan.title}\n"
+            f"Descripción: {plan.description[:100]}...\n\n"
+            f"Añade pasos con: plan_add_step description=\"Paso 1\"\n"
+            f"(El plan {plan.id} está activo, no necesitas especificar plan_id)"
+        )
+
+    def _tool_plan_add_step(self, args: Dict) -> ToolResult:
+        """Añade un paso a un plan."""
+        if not self.plan_mode:
+            return ToolResult.err("Sistema de planificación no inicializado")
+
+        plan_id = args.get("plan_id", "").strip() or None  # None para usar el activo
+        description = args.get("description", "").strip()
+
+        if not description:
+            return ToolResult.err("description es requerido")
+
+        # Verificar que hay un plan activo
+        active_plan = self.plan_mode.get_active_plan()
+        if not plan_id and not active_plan:
+            return ToolResult.err(
+                "No hay un plan activo. Primero crea un plan con plan_create.\n"
+                "Ejemplo: plan_create title=\"Mi plan\" description=\"Descripción\""
+            )
+
+        step = self.plan_mode.add_step(plan_id, description)
+        if not step:
+            return ToolResult.err(
+                f"Plan no encontrado. "
+                f"{'Crea un plan primero con plan_create' if not plan_id else f'El plan {plan_id} no existe'}"
+            )
+
+        plan = self.plan_mode.get_plan(plan_id) if plan_id else active_plan
+        completed, total = plan.progress() if plan else (0, 1)
+
+        return ToolResult.ok(
+            f"✓ Paso {step.id} añadido: {step.description}\n"
+            f"  Progreso: {completed}/{total} pasos"
+        )
+
+    def _tool_plan_update_step(self, args: Dict) -> ToolResult:
+        """Actualiza el estado de un paso del plan."""
+        if not self.plan_mode:
+            return ToolResult.err("Sistema de planificación no inicializado")
+
+        plan_id = args.get("plan_id")
+        step_id = args.get("step_id")
+        status = args.get("status")
+        notes = args.get("notes", "")
+
+        if not step_id:
+            return ToolResult.err("step_id es requerido")
+
+        try:
+            step_id = int(step_id)
+        except ValueError:
+            return ToolResult.err("step_id debe ser un número")
+
+        from hanus.plan.models import StepStatus
+
+        status_enum = None
+        if status:
+            try:
+                status_enum = StepStatus(status.lower())
+            except ValueError:
+                return ToolResult.err(
+                    f"Estado inválido: {status}. "
+                    f"Usa: pending, in_progress, completed, skipped, failed"
+                )
+
+        if not self.plan_mode.update_step(plan_id, step_id, status_enum, notes):
+            return ToolResult.err("Paso o plan no encontrado")
+
+        plan = self.plan_mode.get_plan(plan_id) if plan_id else self.plan_mode.get_active_plan()
+        step = plan.get_step(step_id) if plan else None
+
+        return ToolResult.ok(
+            f"✓ Paso {step_id} actualizado\n"
+            f"  Estado: {step.status.value if step else status}\n"
+            f"  {'Notas: ' + notes if notes else ''}"
+        )
+
+    def _tool_plan_list(self, args: Dict) -> ToolResult:
+        """Lista todos los planes."""
+        if not self.plan_mode:
+            return ToolResult.err("Sistema de planificación no inicializado")
+
+        from hanus.plan.models import PlanStatus
+
+        status_filter = args.get("status")
+        status_enum = None
+        if status_filter:
+            try:
+                status_enum = PlanStatus(status_filter.lower())
+            except ValueError:
+                pass
+
+        plans = self.plan_mode.list_plans(status_enum)
+
+        if not plans:
+            return ToolResult.ok("Sin planes. Crea uno con plan_create")
+
+        lines = ["Planes:\n"]
+        for p in plans:
+            completed, total = p.progress()
+            icon = {
+                PlanStatus.DRAFT: "📝",
+                PlanStatus.APPROVED: "✅",
+                PlanStatus.EXECUTING: "🔄",
+                PlanStatus.COMPLETED: "✔️",
+                PlanStatus.FAILED: "❌",
+            }.get(p.status, "📋")
+            lines.append(f"  {icon} [{p.id}] {p.title}")
+            lines.append(f"      {completed}/{total} pasos | {p.status.value}")
+
+        return ToolResult.ok("\n".join(lines))
+
+    def _tool_plan_get(self, args: Dict) -> ToolResult:
+        """Obtiene detalles de un plan."""
+        if not self.plan_mode:
+            return ToolResult.err("Sistema de planificación no inicializado")
+
+        plan_id = args.get("plan_id")
+        plan = self.plan_mode.get_plan(plan_id) if plan_id else self.plan_mode.get_active_plan()
+
+        if not plan:
+            return ToolResult.err("Plan no encontrado")
+
+        return ToolResult.ok(plan.to_markdown())
+
+    def _tool_plan_approve(self, args: Dict) -> ToolResult:
+        """Aprueba un plan para ejecución."""
+        if not self.plan_mode:
+            return ToolResult.err("Sistema de planificación no inicializado")
+
+        plan_id = args.get("plan_id")
+
+        if not self.plan_mode.approve(plan_id):
+            return ToolResult.err("No se pudo aprobar el plan")
+
+        plan = self.plan_mode.get_plan(plan_id) if plan_id else self.plan_mode.get_active_plan()
+        return ToolResult.ok(
+            f"✓ Plan aprobado\n"
+            f"{plan.to_markdown() if plan else ''}"
+        )
+
+    def _tool_plan_reject(self, args: Dict) -> ToolResult:
+        """Rechaza y elimina un plan."""
+        if not self.plan_mode:
+            return ToolResult.err("Sistema de planificación no inicializado")
+
+        plan_id = args.get("plan_id")
+
+        if not self.plan_mode.reject(plan_id):
+            return ToolResult.err("No se pudo rechazar el plan")
+
+        return ToolResult.ok("✓ Plan rechazado y eliminado")
+
+    def _tool_binsmasher(self, args: Dict) -> ToolResult:
+        """Ejecuta BinSmasher para análisis y explotación de binarios."""
+        import shutil
+
+        binary = args.get("binary", "")
+        action = args.get("action", "analyze")
+        host = args.get("host")
+        port = args.get("port")
+        timeout = int(args.get("timeout", 120))
+
+        # Verificar instalación
+        bs_path = shutil.which("binsmasher")
+        if not bs_path:
+            # Buscar como módulo Python
+            try:
+                import importlib.util
+                spec = importlib.util.find_spec("binsmasher")
+                if spec:
+                    bs_path = "python -m binsmasher"
+            except ImportError:
+                pass
+
+        if not bs_path:
+            return ToolResult.err(
+                "BinSmasher no está instalado.\n\n"
+                "Instalación:\n"
+                "```bash\n"
+                "sudo apt-get install -y python3-pip gdb radare2 socat binutils file patchelf\n"
+                "pip install pwntools rich ropper\n"
+                "git clone https://github.com/VABISMO/binsmasher ~/tools/binsmasher\n"
+                "cd ~/tools/binsmasher && pip install -e .\n"
+                "```\n"
+                "O con Docker:\n"
+                "```bash\n"
+                "docker run --rm -it --cap-add=SYS_PTRACE -v $(pwd):/work vabismo/binsmasher:latest analyze ./binary\n"
+                "```"
+            )
+
+        # Verificar que el binario existe
+        if not binary:
+            return ToolResult.err("Parámetro 'binary' requerido")
+
+        bin_path = self._safe(binary)
+        if not bin_path or not bin_path.exists():
+            return ToolResult.err(f"Binario no encontrado: {binary}")
+
+        # Construir comando
+        if bs_path == "python -m binsmasher":
+            cmd = ["python", "-m", "binsmasher", "binary", "-b", str(bin_path)]
+        else:
+            cmd = [bs_path, "binary", "-b", str(bin_path)]
+
+        # Añadir argumentos según acción
+        if action == "detect":
+            cmd.append("--detect-vuln")
+        elif action == "exploit":
+            cmd.append("--template")
+            if host:
+                cmd.extend(["--host", host])
+            if port:
+                cmd.extend(["--port", port])
+            if host and port:
+                cmd.append("--test-exploit")
+        elif action == "template":
+            cmd.append("--template")
+        elif action == "multistage":
+            cmd.append("--multistage")
+        elif action == "heap":
+            cmd.append("--heap-advanced")
+
+        try:
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                cwd=str(self.root_dir),
+            )
+            output = result.stdout
+            if result.stderr:
+                output += f"\n[stderr]\n{result.stderr}"
+            if not output.strip():
+                output = "Comando ejecutado (sin output)"
+            return ToolResult.ok(output)
+        except subprocess.TimeoutExpired:
+            return ToolResult.err(f"Timeout ({timeout}s). El análisis tardó demasiado.")
+        except Exception as e:
+            return ToolResult.err(f"Error ejecutando binsmasher: {e}")
+
+    def _tool_ask_user(self, args: Dict) -> ToolResult:
+        """
+        Herramienta para que el modelo pregunte al usuario con opciones.
+        El usuario responde interactivamente en la terminal.
+        """
+        # Esta herramienta requiere un callback de UI para funcionar
+        # El callback se establece desde agent_runner.py
+        if not hasattr(self, 'ask_user_callback') or not self.ask_user_callback:
+            return ToolResult.err(
+                "ask_user requiere modo interactivo. "
+                "Esta herramienta no está disponible en modo no interactivo."
+            )
+
+        question = args.get("question", "")
+        header = args.get("header", "")
+        options = args.get("options", [])
+        multi_select = args.get("multiSelect", False)
+
+        if not question:
+            return ToolResult.err("Parámetro 'question' requerido")
+
+        if not options:
+            return ToolResult.err("Parámetro 'options' requerido (lista de opciones)")
+
+        # Validar opciones
+        if not isinstance(options, list) or len(options) < 2:
+            return ToolResult.err("Se requieren al menos 2 opciones")
+
+        # Validar estructura de cada opción
+        for opt in options:
+            if not isinstance(opt, dict):
+                return ToolResult.err("Cada opción debe ser un objeto con 'label' y 'description'")
+            if "label" not in opt:
+                return ToolResult.err("Cada opción debe tener 'label'")
+
+        try:
+            result = self.ask_user_callback(question, header, options, multi_select)
+            # Resultado incluye:
+            # - selected: lista de opciones seleccionadas (labels)
+            # - custom_input: texto personalizado si el usuario eligió "Other"
+            # - cancelled: si el usuario canceló
+            if result.get("cancelled"):
+                return ToolResult.ok("[CANCELLED] El usuario canceló la pregunta.")
+
+            selected = result.get("selected", [])
+            custom_input = result.get("custom_input", "")
+
+            response_parts = []
+            if selected:
+                response_parts.append(f"Opciones seleccionadas: {', '.join(selected)}")
+            if custom_input:
+                response_parts.append(f"Entrada personalizada: {custom_input}")
+
+            return ToolResult.ok("\n".join(response_parts) if response_parts else "Sin respuesta")
+
+        except Exception as e:
+            return ToolResult.err(f"Error en ask_user: {e}")
+
+    def _describe(self, tool: str, args: Dict) -> str:
+        if tool == "exec_cmd":
+            return f"Ejecutar: {args.get('cmd', '?')}"
+        if tool in ("write_file", "create_file"):
+            size = len(str(args.get("content", "")))
+            return f"Escribir {args.get('path', '?')} ({size:,} chars)"
+        if tool == "file_edit":
+            return f"Editar {args.get('path', '?')}: {str(args.get('search',''))[:40]!r}"
+        if tool == "git_push":
+            return "git push al remoto"
+        if tool == "git_reset":
+            return f"git reset {args.get('ref', 'HEAD~1')}"
+        return f"{tool}: {str(args)[:80]}"
+
+
+# ─── Definiciones de herramientas para el modelo ─────────────────────────────
+
+TOOL_DEFINITIONS = [
+    {
+        "name": "read_file",
+        "description": "Lee el contenido de un archivo del proyecto.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path":       {"type": "string", "description": "Ruta relativa al proyecto"},
+                "start_line": {"type": "integer", "description": "Línea de inicio (1-indexed, opcional)"},
+                "end_line":   {"type": "integer", "description": "Línea de fin (opcional)"},
+            },
+            "required": ["path"],
+        },
+    },
+    {
+        "name": "write_file",
+        "description": "Crea o sobrescribe un archivo con el contenido dado.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path":    {"type": "string"},
+                "content": {"type": "string"},
+            },
+            "required": ["path", "content"],
+        },
+    },
+    {
+        "name": "create_file",
+        "description": "Crea un archivo nuevo. Falla si ya existe (usa write_file para sobrescribir).",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path":      {"type": "string"},
+                "content":   {"type": "string"},
+                "overwrite": {"type": "boolean", "default": False},
+            },
+            "required": ["path", "content"],
+        },
+    },
+    {
+        "name": "append_to_file",
+        "description": "Añade contenido al final de un archivo existente.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path":    {"type": "string"},
+                "content": {"type": "string"},
+            },
+            "required": ["path", "content"],
+        },
+    },
+    {
+        "name": "file_edit",
+        "description": "Busca y reemplaza texto en un archivo. Más seguro que sobrescribir.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path":    {"type": "string"},
+                "search":  {"type": "string", "description": "Texto o regex a buscar"},
+                "replace": {"type": "string", "description": "Texto de reemplazo"},
+                "regex":   {"type": "boolean", "default": False},
+            },
+            "required": ["path", "search", "replace"],
+        },
+    },
+    {
+        "name": "edit_file",
+        "description": "Edita un archivo con verificación de string exacto. Más seguro que file_edit. "
+                       "old_str DEBE existir exactamente una vez en el archivo.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path":     {"type": "string", "description": "Ruta del archivo a editar"},
+                "old_str":  {"type": "string", "description": "Texto exacto a buscar (debe ser único en el archivo)"},
+                "new_str":  {"type": "string", "description": "Texto de reemplazo"},
+            },
+            "required": ["path", "old_str", "new_str"],
+        },
+    },
+    {
+        "name": "exec_cmd",
+        "description": "Ejecuta un comando de shell en el directorio del proyecto.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "cmd":    {"type": "string", "description": "Comando completo a ejecutar"},
+                "reason": {"type": "string", "description": "Por qué necesitas ejecutar esto"},
+            },
+            "required": ["cmd"],
+        },
+    },
+    {
+        "name": "exec_file",
+        "description": "Ejecuta un archivo Python del proyecto.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path":   {"type": "string"},
+                "reason": {"type": "string"},
+            },
+            "required": ["path"],
+        },
+    },
+    {
+        "name": "glob_search",
+        "description": "Busca archivos por patrón glob (ej: '**/*.py', 'test_*.py').",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "pattern": {"type": "string", "description": "Patrón glob"},
+                "dir":     {"type": "string", "default": "."},
+            },
+            "required": ["pattern"],
+        },
+    },
+    {
+        "name": "grep_search",
+        "description": "Busca texto o regex en el contenido de archivos del proyecto.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "pattern": {"type": "string"},
+                "dir":     {"type": "string", "default": "."},
+                "regex":   {"type": "boolean", "default": False},
+                "context": {"type": "integer", "default": 0, "description": "Líneas de contexto"},
+            },
+            "required": ["pattern"],
+        },
+    },
+    {
+        "name": "list_files",
+        "description": "Lista todos los archivos del proyecto o subdirectorio.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "dir": {"type": "string", "default": "."},
+            },
+        },
+    },
+    {
+        "name": "git_status",
+        "description": "Estado actual del repositorio git (rama, cambios staged/unstaged).",
+        "input_schema": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "git_diff",
+        "description": "Muestra diferencias en el repositorio git.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "args": {"type": "string", "description": "Argumentos extra (ej: HEAD~1, -- src/)"},
+            },
+        },
+    },
+    {
+        "name": "git_log",
+        "description": "Muestra el historial de commits.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "n": {"type": "integer", "default": 10, "description": "Número de commits a mostrar"},
+            },
+        },
+    },
+    {
+        "name": "git_commit",
+        "description": "Hace commit de todos los cambios con un mensaje.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "message": {"type": "string", "description": "Mensaje del commit"},
+            },
+            "required": ["message"],
+        },
+    },
+    {
+        "name": "git_push",
+        "description": "Hace push al repositorio remoto.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "branch": {"type": "string", "description": "Rama a pushear (opcional)"},
+                "remote": {"type": "string", "default": "origin"},
+            },
+        },
+    },
+    {
+        "name": "git_reset",
+        "description": "Revierte commits (git reset). Úsalo con precaución.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "ref":  {"type": "string", "default": "HEAD~1"},
+                "mode": {"type": "string", "default": "--soft", "enum": ["--soft", "--mixed", "--hard"]},
+            },
+        },
+    },
+    {
+        "name": "git_branch",
+        "description": "Crea o lista ramas git.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string", "description": "Nombre de nueva rama (vacío = listar)"},
+            },
+        },
+    },
+    {
+        "name": "web_fetch",
+        "description": "Obtiene el contenido de una URL pública.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "url": {"type": "string"},
+            },
+            "required": ["url"],
+        },
+    },
+    {
+        "name": "web_search",
+        "description": "Busca en internet vía DuckDuckGo (sin API key).",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "query":   {"type": "string"},
+                "results": {"type": "integer", "default": 5},
+            },
+            "required": ["query"],
+        },
+    },
+    {
+        "name": "structured_output",
+        "description": "Valida y formatea datos JSON contra un schema.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "data":   {"type": "string", "description": "Objeto JSON como string"},
+                "schema": {"type": "string", "description": "JSON Schema como string (opcional)"},
+            },
+            "required": ["data"],
+        },
+    },
+    {
+        "name": "notebook_edit",
+        "description": "Edita o añade celdas en un Jupyter Notebook (.ipynb).",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path":       {"type": "string"},
+                "cell_index": {"type": "integer", "description": "Índice de celda a editar (null = añadir nueva)"},
+                "source":     {"type": "string", "description": "Contenido de la celda"},
+                "cell_type":  {"type": "string", "default": "code", "enum": ["code", "markdown"]},
+            },
+            "required": ["path", "source"],
+        },
+    },
+    {
+        "name": "task_create",
+        "description": "Crea una nueva tarea para seguimiento del trabajo.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "subject":     {"type": "string", "description": "Título breve de la tarea"},
+                "description": {"type": "string", "description": "Descripción completa"},
+                "activeForm":  {"type": "string", "description": "Forma presente continuo (ej: 'Implementando login')"},
+                "metadata":    {"type": "object", "description": "Datos adicionales"},
+            },
+            "required": ["subject"],
+        },
+    },
+    {
+        "name": "task_update",
+        "description": "Actualiza una tarea existente.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "taskId":       {"type": "string", "description": "ID de la tarea"},
+                "status":       {"type": "string", "enum": ["pending", "in_progress", "completed", "failed"]},
+                "subject":      {"type": "string"},
+                "description":  {"type": "string"},
+                "addBlockedBy": {"type": "array", "items": {"type": "string"}, "description": "IDs de tareas que bloquean esta"},
+                "addBlocks":    {"type": "array", "items": {"type": "string"}, "description": "IDs de tareas que esta bloquea"},
+            },
+            "required": ["taskId"],
+        },
+    },
+    {
+        "name": "task_list",
+        "description": "Lista todas las tareas.",
+        "input_schema": {
+            "type": "object",
+            "properties": {},
+        },
+    },
+    {
+        "name": "task_get",
+        "description": "Obtiene detalles completos de una tarea.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "taskId": {"type": "string", "description": "ID de la tarea"},
+            },
+            "required": ["taskId"],
+        },
+    },
+    {
+        "name": "memory_save",
+        "description": "Guarda información en la memoria persistente del agente.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "name":        {"type": "string", "description": "Nombre identificador de la memoria"},
+                "type":        {"type": "string", "enum": ["user", "feedback", "project", "reference"]},
+                "content":     {"type": "string", "description": "Contenido a guardar"},
+                "description": {"type": "string", "description": "Descripción corta (opcional)"},
+            },
+            "required": ["name", "type", "content"],
+        },
+    },
+    {
+        "name": "memory_search",
+        "description": "Busca en la memoria persistente del agente.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "description": "Texto a buscar"},
+                "type":  {"type": "string", "enum": ["user", "feedback", "project", "reference"]},
+            },
+            "required": ["query"],
+        },
+    },
+    {
+        "name": "memory_list",
+        "description": "Lista memorias por tipo o todas.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "type": {"type": "string", "enum": ["user", "feedback", "project", "reference"]},
+            },
+        },
+    },
+    {
+        "name": "subagent",
+        "description": "Ejecuta un subagente especializado para tareas complejas. "
+                       "Útil para exploración de código, revisión, planificación, etc.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "type": {
+                    "type": "string",
+                    "enum": ["explore", "plan", "general", "review", "test"],
+                    "description": "Tipo de subagente"
+                },
+                "task": {
+                    "type": "string",
+                    "description": "Descripción clara de la tarea a realizar"
+                },
+                "context": {
+                    "type": "string",
+                    "description": "Contexto adicional (archivos relevantes, requisitos, etc.)"
+                },
+            },
+            "required": ["type", "task"],
+        },
+    },
+    {
+        "name": "plan_create",
+        "description": "Crea un nuevo plan de implementación para organizar el trabajo.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "title":       {"type": "string", "description": "Título del plan"},
+                "description": {"type": "string", "description": "Descripción del objetivo"},
+            },
+            "required": ["title"],
+        },
+    },
+    {
+        "name": "plan_add_step",
+        "description": "Añade un paso a un plan existente.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "plan_id":     {"type": "string", "description": "ID del plan (usa el activo si omitido)"},
+                "description": {"type": "string", "description": "Descripción del paso"},
+            },
+            "required": ["description"],
+        },
+    },
+    {
+        "name": "plan_update_step",
+        "description": "Actualiza el estado de un paso del plan.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "plan_id": {"type": "string", "description": "ID del plan"},
+                "step_id": {"type": "integer", "description": "Número del paso"},
+                "status":  {"type": "string", "enum": ["pending", "in_progress", "completed", "skipped", "failed"]},
+                "notes":   {"type": "string", "description": "Notas adicionales"},
+            },
+            "required": ["step_id"],
+        },
+    },
+    {
+        "name": "plan_list",
+        "description": "Lista todos los planes.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "status": {"type": "string", "description": "Filtrar por estado"},
+            },
+        },
+    },
+    {
+        "name": "plan_get",
+        "description": "Obtiene detalles completos de un plan.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "plan_id": {"type": "string", "description": "ID del plan"},
+            },
+        },
+    },
+    {
+        "name": "plan_approve",
+        "description": "Aprueba un plan para comenzar la ejecución.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "plan_id": {"type": "string", "description": "ID del plan"},
+            },
+        },
+    },
+    {
+        "name": "plan_reject",
+        "description": "Rechaza y elimina un plan.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "plan_id": {"type": "string", "description": "ID del plan"},
+            },
+        },
+    },
+    {
+        "name": "binsmasher",
+        "description": "Análisis y explotación de binarios ELF/PE usando BinSmasher. "
+                       "Para CTFs, pentesting autorizado y research de seguridad. "
+                       "Detecta vulnerabilidades, genera exploits, encuentra gadgets ROP.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "binary": {
+                    "type": "string",
+                    "description": "Ruta al binario a analizar/explotar"
+                },
+                "action": {
+                    "type": "string",
+                    "enum": ["analyze", "detect", "exploit", "template", "multistage", "heap"],
+                    "default": "analyze",
+                    "description": "Tipo de acción: analyze (completo), detect (solo vuln), exploit (generar exploit), template (solo template)"
+                },
+                "host": {
+                    "type": "string",
+                    "description": "Host remoto para explotación (CTF)"
+                },
+                "port": {
+                    "type": "string",
+                    "description": "Puerto del servidor remoto"
+                },
+                "timeout": {
+                    "type": "integer",
+                    "default": 120,
+                    "description": "Timeout en segundos"
+                },
+            },
+            "required": ["binary"],
+        },
+    },
+    {
+        "name": "ask_user",
+        "description": "Pregunta al usuario con opciones seleccionables. Úsalo cuando necesites "
+                       "clarificar requisitos, elegir entre múltiples enfoques, o obtener "
+                       "preferencias del usuario. El usuario verá las opciones y podrá "
+                       "seleccionar una o varias, o proporcionar entrada personalizada.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "question": {
+                    "type": "string",
+                    "description": "La pregunta completa para el usuario. Debe ser clara y específica."
+                },
+                "header": {
+                    "type": "string",
+                    "description": "Etiqueta corta para mostrar junto a la pregunta (ej: 'Auth method', 'Approach'). Max 12 caracteres."
+                },
+                "options": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "label": {
+                                "type": "string",
+                                "description": "Texto de la opción (1-5 palabras, conciso)"
+                            },
+                            "description": {
+                                "type": "string",
+                                "description": "Explicación de qué significa esta opción"
+                            }
+                        },
+                        "required": ["label", "description"]
+                    },
+                    "minItems": 2,
+                    "maxItems": 4,
+                    "description": "Opciones disponibles. Debe tener entre 2 y 4 opciones."
+                },
+                "multiSelect": {
+                    "type": "boolean",
+                    "description": "true = permitir seleccionar múltiples opciones, false = selección única"
+                }
+            },
+            "required": ["question", "options"]
+        },
+    },
+]