lmcoding-local 3.1.0__py3-none-any.whl

lmcoding.py

@@ -0,0 +1,2565 @@
+#!/usr/bin/env python3
+"""
+LMCoding Pro: agente de programación local para LM Studio.
+
+Ejemplos:
+    python lmcoding.py
+    python lmcoding.py -C C:\\proyectos\\mi-app
+    python lmcoding.py exec "corrige las pruebas que fallan" -C .
+    python lmcoding.py resume --last
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import dataclasses
+import datetime as dt
+import difflib
+import fnmatch
+import importlib.util
+import hashlib
+import json
+import os
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Callable, Iterable, Literal
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - Python 3.10
+    import tomli as tomllib  # type: ignore
+
+from openai import OpenAI
+from prompt_toolkit import PromptSession
+from prompt_toolkit.completion import Completer, Completion
+from prompt_toolkit.formatted_text import HTML
+from prompt_toolkit.history import FileHistory
+from prompt_toolkit.key_binding import KeyBindings
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.prompt import Confirm, Prompt
+from rich.table import Table
+from rich.text import Text
+
+
+APP_NAME = "LMCoding"
+COMMAND_BRAND = "llmCodex"
+APP_VERSION = "3.1.0"
+DEFAULT_BASE_URL = "http://localhost:1234/v1"
+DEFAULT_MAX_STEPS = 32
+DEFAULT_CONTEXT_CHARS = 120_000
+MAX_TOOL_OUTPUT = 30_000
+MAX_FILE_READ_LINES = 1_500
+MAX_LISTED_FILES = 1_000
+MAX_SEARCH_MATCHES = 500
+
+PermissionMode = Literal["read-only", "workspace-write", "full-access"]
+ApprovalPolicy = Literal["untrusted", "on-request", "never"]
+VerificationMode = Literal["off", "quick", "full"]
+
+console = Console()
+
+HOME_DIR = Path(os.getenv("LMCODING_HOME", Path.home() / ".lmcoding")).expanduser()
+SESSIONS_DIR = HOME_DIR / "sessions"
+HISTORY_FILE = HOME_DIR / "history"
+GLOBAL_CONFIG_FILE = HOME_DIR / "config.toml"
+
+DEFAULT_IGNORES = {
+    ".git",
+    ".idea",
+    ".vscode",
+    ".lmcoding",
+    "__pycache__",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+    "node_modules",
+    ".venv",
+    "venv",
+    "dist",
+    "build",
+    "target",
+    ".next",
+    ".nuxt",
+    "coverage",
+}
+
+PROJECT_HINT_FILES = [
+    "AGENTS.md",
+    "CLAUDE.md",
+    "README.md",
+    "README.rst",
+    "README.txt",
+    "pyproject.toml",
+    "package.json",
+    "Cargo.toml",
+    "go.mod",
+    "pom.xml",
+    "build.gradle",
+    "build.gradle.kts",
+    "requirements.txt",
+]
+
+SAFE_COMMAND_PREFIXES = (
+    "git status",
+    "git diff",
+    "git log",
+    "git show",
+    "git branch",
+    "git rev-parse",
+    "git ls-files",
+    "pwd",
+    "ls",
+    "dir",
+    "tree",
+    "rg",
+    "grep",
+    "find",
+    "where",
+    "which",
+    "python --version",
+    "python -V",
+    "node --version",
+    "npm --version",
+    "java -version",
+    "gradle --version",
+    "cargo --version",
+)
+
+NETWORK_COMMAND_PATTERNS = (
+    r"\bcurl\b",
+    r"\bwget\b",
+    r"\binvoke-webrequest\b",
+    r"\bgit\s+(clone|pull|fetch|push)\b",
+    r"\b(pip|pip3|python\s+-m\s+pip)\s+install\b",
+    r"\b(npm|pnpm|yarn|bun)\s+(install|add|update|upgrade)\b",
+    r"\b(cargo|go)\s+(install|get)\b",
+    r"\bapt(-get)?\b",
+    r"\bbrew\s+install\b",
+    r"\bchoco\s+install\b",
+    r"\bwinget\s+install\b",
+)
+
+DANGEROUS_COMMAND_PATTERNS = (
+    r"(^|[;&|]\s*)rm\s+-rf\b",
+    r"(^|[;&|]\s*)del\s+(/s|/q|/f)",
+    r"(^|[;&|]\s*)rmdir\s+(/s|/q)",
+    r"\bformat\s+[a-z]:",
+    r"\bmkfs\b",
+    r"\bdd\s+if=",
+    r"\bshutdown\b",
+    r"\breboot\b",
+    r"\breg\s+delete\b",
+    r"\bgit\s+reset\s+--hard\b",
+    r"\bgit\s+clean\s+-[a-z]*f",
+    r"\bgit\s+push\s+.*--force\b",
+    r"\b(drop|truncate)\s+(database|table)\b",
+    r"\bchmod\s+-R\s+777\b",
+    r"\b(chown|takeown)\b",
+    r"\b(powershell|pwsh)\b.*-enc(odedcommand)?\b",
+    r"\bcurl\b.*\|\s*(sh|bash|powershell|pwsh)\b",
+)
+
+SYSTEM_PROMPT = """Eres LMCoding Ultra, un agente de programación local avanzado y autocorrectivo.
+Tu trabajo es completar tareas de ingeniería de software de principio a fin dentro del proyecto.
+
+Principios obligatorios:
+1. Inspecciona el proyecto antes de modificarlo. Lee AGENTS.md y reglas locales si existen.
+2. Usa herramientas para comprobar hechos. No inventes archivos, salidas, pruebas ni resultados.
+3. Prefiere cambios pequeños y precisos. Para editar, usa apply_patch cuando sea posible.
+4. Conserva el estilo, arquitectura y convenciones existentes del repositorio.
+5. Después de cualquier modificación, verifica con diagnose_project, pruebas, lint o build apropiado.
+6. Si una verificación falla, analiza la causa raíz, corrige y vuelve a verificar; no ocultes el fallo.
+7. No destruyas trabajo del usuario. No reviertas cambios ajenos ni uses comandos destructivos sin necesidad.
+8. Mantén un plan breve para tareas complejas y actualízalo mientras avanzas.
+9. Si una acción está bloqueada por permisos, explica la razón o solicita aprobación mediante la herramienta.
+10. No repitas indefinidamente la misma herramienta o el mismo cambio; cambia de estrategia.
+11. Al terminar, informa: resultado, archivos cambiados, verificaciones ejecutadas y riesgos pendientes.
+12. No reveles razonamiento privado paso a paso. Comunica decisiones, hallazgos y resultados útiles.
+13. Responde en el idioma del usuario.
+"""
+
+AUTO_REPAIR_PROMPT = """VERIFICACIÓN AUTOMÁTICA FALLIDA.
+No des por terminada la tarea. Examina la salida real incluida abajo, identifica la causa raíz,
+inspecciona los archivos relevantes, aplica una corrección mínima y vuelve a verificar.
+No elimines pruebas ni desactives validaciones para hacerlas pasar. Si el fallo parece anterior
+a tus cambios, demuéstralo con evidencia y evita empeorar el proyecto.
+"""
+
+PLAN_MODE_PROMPT = """
+MODO PLAN ACTIVO:
+- Solo inspecciona y analiza.
+- No modifiques archivos, no elimines rutas y no ejecutes comandos que alteren el proyecto.
+- Entrega un plan concreto con archivos, pasos, pruebas y riesgos.
+"""
+
+REVIEW_PROMPT = """Revisa el árbol de trabajo actual como revisor de código senior.
+Busca errores funcionales, regresiones, riesgos de seguridad, problemas de compatibilidad,
+falta de pruebas y cambios accidentales. Prioriza hallazgos por severidad y cita archivo y línea.
+Si no encuentras problemas, dilo claramente y menciona riesgos de prueba restantes.
+"""
+
+
+def ensure_home() -> None:
+    HOME_DIR.mkdir(parents=True, exist_ok=True)
+    SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def now_iso() -> str:
+    return dt.datetime.now(dt.timezone.utc).isoformat()
+
+
+def truncate(text: str, limit: int = MAX_TOOL_OUTPUT) -> str:
+    if len(text) <= limit:
+        return text
+    omitted = len(text) - limit
+    return text[:limit] + f"\n\n...[salida recortada: {omitted} caracteres]"
+
+
+def sha256_text(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8", errors="replace")).hexdigest()
+
+
+def deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    result = dict(base)
+    for key, value in override.items():
+        if isinstance(value, dict) and isinstance(result.get(key), dict):
+            result[key] = deep_merge(result[key], value)
+        else:
+            result[key] = value
+    return result
+
+
+def load_toml(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        with path.open("rb") as handle:
+            data = tomllib.load(handle)
+        return data if isinstance(data, dict) else {}
+    except Exception as exc:
+        console.print(f"[yellow]No se pudo leer {path}: {exc}[/yellow]")
+        return {}
+
+
+@dataclasses.dataclass
+class AppConfig:
+    base_url: str = DEFAULT_BASE_URL
+    api_key: str = "lm-studio"
+    model: str | None = None
+    permission_mode: PermissionMode = "workspace-write"
+    approval_policy: ApprovalPolicy = "on-request"
+    max_steps: int = DEFAULT_MAX_STEPS
+    max_context_chars: int = DEFAULT_CONTEXT_CHARS
+    temperature: float = 0.15
+    command_timeout: int = 180
+    auto_compact: bool = True
+    save_sessions: bool = True
+    show_tool_output: bool = True
+    self_heal: bool = True
+    verification_mode: VerificationMode = "quick"
+    max_fix_attempts: int = 3
+    rollback_on_failure: bool = True
+    api_retries: int = 4
+    retry_backoff: float = 1.0
+    max_repeat_tool_calls: int = 3
+    extra_writable_roots: list[str] = dataclasses.field(default_factory=list)
+    trusted_commands: list[str] = dataclasses.field(default_factory=list)
+    denied_commands: list[str] = dataclasses.field(default_factory=list)
+
+    @classmethod
+    def from_layers(
+        cls,
+        workspace: Path,
+        cli_values: dict[str, Any] | None = None,
+    ) -> "AppConfig":
+        defaults = dataclasses.asdict(cls())
+        global_data = load_toml(GLOBAL_CONFIG_FILE)
+        project_data = load_toml(workspace / ".lmcoding" / "config.toml")
+        merged = deep_merge(defaults, global_data)
+        merged = deep_merge(merged, project_data)
+        if cli_values:
+            merged = deep_merge(merged, {k: v for k, v in cli_values.items() if v is not None})
+
+        valid_fields = {field.name for field in dataclasses.fields(cls)}
+        filtered = {key: value for key, value in merged.items() if key in valid_fields}
+        config = cls(**filtered)
+        config.max_steps = max(1, min(int(config.max_steps), 128))
+        config.max_context_chars = max(20_000, int(config.max_context_chars))
+        config.command_timeout = max(1, min(int(config.command_timeout), 3_600))
+        config.max_fix_attempts = max(0, min(int(config.max_fix_attempts), 10))
+        config.api_retries = max(1, min(int(config.api_retries), 10))
+        config.retry_backoff = max(0.1, min(float(config.retry_backoff), 10.0))
+        config.max_repeat_tool_calls = max(1, min(int(config.max_repeat_tool_calls), 10))
+        if config.verification_mode not in {"off", "quick", "full"}:
+            config.verification_mode = "quick"
+        if config.permission_mode not in {"read-only", "workspace-write", "full-access"}:
+            config.permission_mode = "workspace-write"
+        if config.approval_policy not in {"untrusted", "on-request", "never"}:
+            config.approval_policy = "on-request"
+        return config
+
+
+@dataclasses.dataclass
+class PlanItem:
+    step: str
+    status: Literal["pending", "in_progress", "completed"] = "pending"
+
+
+@dataclasses.dataclass
+class SessionState:
+    id: str
+    name: str
+    workspace: str
+    model: str | None
+    created_at: str
+    updated_at: str
+    messages: list[dict[str, Any]]
+    plan: list[PlanItem] = dataclasses.field(default_factory=list)
+    plan_mode: bool = False
+    total_prompt_tokens: int = 0
+    total_completion_tokens: int = 0
+    last_checkpoint: str | None = None
+    last_verification: str | None = None
+    repair_cycles: int = 0
+
+    @classmethod
+    def create(cls, workspace: Path, model: str | None = None) -> "SessionState":
+        session_id = str(uuid.uuid4())
+        return cls(
+            id=session_id,
+            name=f"session-{session_id[:8]}",
+            workspace=str(workspace),
+            model=model,
+            created_at=now_iso(),
+            updated_at=now_iso(),
+            messages=[],
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        data = dataclasses.asdict(self)
+        return data
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "SessionState":
+        plan = [PlanItem(**item) for item in data.get("plan", [])]
+        return cls(
+            id=data["id"],
+            name=data.get("name", f"session-{data['id'][:8]}"),
+            workspace=data["workspace"],
+            model=data.get("model"),
+            created_at=data.get("created_at", now_iso()),
+            updated_at=data.get("updated_at", now_iso()),
+            messages=data.get("messages", []),
+            plan=plan,
+            plan_mode=bool(data.get("plan_mode", False)),
+            total_prompt_tokens=int(data.get("total_prompt_tokens", 0)),
+            total_completion_tokens=int(data.get("total_completion_tokens", 0)),
+            last_checkpoint=data.get("last_checkpoint"),
+            last_verification=data.get("last_verification"),
+            repair_cycles=int(data.get("repair_cycles", 0)),
+        )
+
+
+class SessionStore:
+    def __init__(self) -> None:
+        ensure_home()
+
+    def path_for(self, session_id: str) -> Path:
+        return SESSIONS_DIR / f"{session_id}.json"
+
+    def save(self, state: SessionState) -> None:
+        state.updated_at = now_iso()
+        path = self.path_for(state.id)
+        temp = path.with_suffix(".tmp")
+        temp.write_text(json.dumps(state.to_dict(), ensure_ascii=False, indent=2), encoding="utf-8")
+        temp.replace(path)
+
+    def load(self, session_id: str) -> SessionState:
+        exact = self.path_for(session_id)
+        if exact.exists():
+            return SessionState.from_dict(json.loads(exact.read_text(encoding="utf-8")))
+
+        matches = list(SESSIONS_DIR.glob(f"{session_id}*.json"))
+        if len(matches) == 1:
+            return SessionState.from_dict(json.loads(matches[0].read_text(encoding="utf-8")))
+        if not matches:
+            for item in self.list_states():
+                if item.name == session_id:
+                    return item
+            raise FileNotFoundError(f"Sesión no encontrada: {session_id}")
+        raise ValueError(f"ID de sesión ambiguo: {session_id}")
+
+    def list_states(self, workspace: Path | None = None) -> list[SessionState]:
+        states: list[SessionState] = []
+        for path in SESSIONS_DIR.glob("*.json"):
+            try:
+                state = SessionState.from_dict(json.loads(path.read_text(encoding="utf-8")))
+            except Exception:
+                continue
+            if workspace is None or Path(state.workspace).resolve() == workspace.resolve():
+                states.append(state)
+        states.sort(key=lambda item: item.updated_at, reverse=True)
+        return states
+
+    def latest(self, workspace: Path | None = None) -> SessionState:
+        states = self.list_states(workspace)
+        if not states:
+            raise FileNotFoundError("No hay sesiones guardadas")
+        return states[0]
+
+    def delete(self, session_id: str) -> None:
+        state = self.load(session_id)
+        self.path_for(state.id).unlink(missing_ok=True)
+
+
+class ApprovalManager:
+    def __init__(self, config: AppConfig) -> None:
+        self.config = config
+
+    def classify_command(self, command: str) -> tuple[str, list[str]]:
+        normalized = " ".join(command.strip().split())
+        reasons: list[str] = []
+
+        for pattern in self.config.denied_commands:
+            if re.search(pattern, normalized, flags=re.IGNORECASE):
+                return "deny", [f"coincide con regla denegada: {pattern}"]
+
+        if any(re.search(pattern, normalized, flags=re.IGNORECASE) for pattern in DANGEROUS_COMMAND_PATTERNS):
+            reasons.append("comando potencialmente destructivo")
+            return "dangerous", reasons
+
+        if any(re.search(pattern, normalized, flags=re.IGNORECASE) for pattern in NETWORK_COMMAND_PATTERNS):
+            reasons.append("puede usar la red o instalar dependencias")
+            return "network", reasons
+
+        prefixes = tuple(SAFE_COMMAND_PREFIXES) + tuple(self.config.trusted_commands)
+        if normalized.lower().startswith(tuple(prefix.lower() for prefix in prefixes)):
+            return "trusted", ["comando de inspección reconocido"]
+
+        if ".." in normalized or re.search(r"(^|\s)(/|[A-Za-z]:\\)", normalized):
+            reasons.append("puede acceder fuera del directorio de trabajo")
+            return "outside", reasons
+
+        return "untrusted", ["comando no clasificado como seguro"]
+
+    def approve_command(self, command: str) -> tuple[bool, str]:
+        classification, reasons = self.classify_command(command)
+        if classification == "deny":
+            return False, "; ".join(reasons)
+
+        mode = self.config.permission_mode
+        policy = self.config.approval_policy
+
+        if mode == "read-only":
+            if classification == "trusted":
+                return True, "permitido en lectura"
+            return self._prompt(command, classification, reasons)
+
+        if mode == "full-access" and policy == "never":
+            return True, "full-access"
+
+        if policy == "never":
+            return True, "sin confirmaciones"
+
+        if classification == "trusted":
+            return True, "comando confiable"
+
+        if policy == "untrusted":
+            return self._prompt(command, classification, reasons)
+
+        if classification in {"dangerous", "network", "outside"}:
+            return self._prompt(command, classification, reasons)
+
+        return True, "dentro del workspace"
+
+    def approve_mutation(self, description: str, outside_workspace: bool = False) -> bool:
+        if self.config.permission_mode == "full-access" and self.config.approval_policy == "never":
+            return True
+        if self.config.permission_mode == "read-only":
+            return Confirm.ask(
+                f"[yellow]Modo read-only. ¿Permitir una vez?[/yellow]\n{description}",
+                default=False,
+            )
+        if outside_workspace:
+            if self.config.permission_mode != "full-access":
+                return False
+            if self.config.approval_policy != "never":
+                return Confirm.ask(f"[red]Acción fuera del workspace[/red]\n{description}", default=False)
+        return True
+
+    @staticmethod
+    def _prompt(command: str, classification: str, reasons: list[str]) -> tuple[bool, str]:
+        details = ", ".join(reasons)
+        approved = Confirm.ask(
+            f"[yellow]Autorizar comando ({classification})?[/yellow]\n"
+            f"[bold]{command}[/bold]\n[dim]{details}[/dim]",
+            default=False,
+        )
+        return approved, "aprobado por usuario" if approved else "rechazado por usuario"
+
+
+class Workspace:
+    def __init__(self, root: Path, config: AppConfig) -> None:
+        self.root = root.expanduser().resolve()
+        self.root.mkdir(parents=True, exist_ok=True)
+        self.config = config
+        self.approvals = ApprovalManager(config)
+        workspace_key = hashlib.sha256(str(self.root).encode("utf-8")).hexdigest()[:20]
+        self.metadata_dir = HOME_DIR / "workspaces" / workspace_key
+        self.checkpoints_dir = self.metadata_dir / "checkpoints"
+        self.checkpoints_dir.mkdir(parents=True, exist_ok=True)
+        self.extra_writable_roots = [Path(item).expanduser().resolve() for item in config.extra_writable_roots]
+
+    def resolve(self, user_path: str | None = None, *, for_write: bool = False) -> Path:
+        raw = user_path or "."
+        candidate = Path(raw).expanduser()
+        if not candidate.is_absolute():
+            candidate = self.root / candidate
+        candidate = candidate.resolve()
+
+        inside_root = self._is_within(candidate, self.root)
+        inside_extra = any(self._is_within(candidate, extra) for extra in self.extra_writable_roots)
+        if inside_root:
+            return candidate
+        if for_write and inside_extra:
+            return candidate
+        if self.config.permission_mode == "full-access":
+            return candidate
+        raise ValueError(f"Ruta fuera del workspace no permitida: {user_path}")
+
+    @staticmethod
+    def _is_within(candidate: Path, root: Path) -> bool:
+        try:
+            candidate.relative_to(root)
+            return True
+        except ValueError:
+            return False
+
+    def relative(self, path: Path) -> str:
+        try:
+            return str(path.relative_to(self.root)) or "."
+        except ValueError:
+            return str(path)
+
+    def is_outside(self, path: Path) -> bool:
+        return not self._is_within(path, self.root)
+
+    def checkpoint(self, paths: Iterable[Path], description: str) -> str:
+        checkpoint_id = f"{int(time.time())}-{uuid.uuid4().hex[:8]}"
+        target_dir = self.checkpoints_dir / checkpoint_id
+        files_dir = target_dir / "files"
+        files_dir.mkdir(parents=True, exist_ok=True)
+        manifest: dict[str, Any] = {
+            "id": checkpoint_id,
+            "created_at": now_iso(),
+            "description": description,
+            "entries": [],
+        }
+
+        for path in paths:
+            path = path.resolve()
+            rel = self.relative(path)
+            entry: dict[str, Any] = {"path": rel, "absolute": str(path), "existed": path.exists()}
+            if path.exists():
+                backup_name = hashlib.sha256(str(path).encode()).hexdigest()[:16]
+                backup_path = files_dir / backup_name
+                if path.is_dir():
+                    shutil.copytree(path, backup_path)
+                    entry["kind"] = "dir"
+                else:
+                    shutil.copy2(path, backup_path)
+                    entry["kind"] = "file"
+                entry["backup"] = str(backup_path.relative_to(target_dir))
+            manifest["entries"].append(entry)
+
+        (target_dir / "manifest.json").write_text(
+            json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8"
+        )
+        return checkpoint_id
+
+    def undo(self, checkpoint_id: str | None = None) -> str:
+        if checkpoint_id is None:
+            candidates = sorted(
+                [item for item in self.checkpoints_dir.iterdir() if item.is_dir()],
+                key=lambda item: item.name,
+                reverse=True,
+            )
+            if not candidates:
+                return "ERROR: no hay checkpoints para deshacer"
+            checkpoint_dir = candidates[0]
+        else:
+            checkpoint_dir = self.checkpoints_dir / checkpoint_id
+        manifest_path = checkpoint_dir / "manifest.json"
+        if not manifest_path.exists():
+            return f"ERROR: checkpoint no encontrado: {checkpoint_id}"
+
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        restored: list[str] = []
+        for entry in reversed(manifest.get("entries", [])):
+            target = Path(entry["absolute"])
+            if target.exists():
+                if target.is_dir():
+                    shutil.rmtree(target)
+                else:
+                    target.unlink()
+            if entry.get("existed"):
+                backup = checkpoint_dir / entry["backup"]
+                target.parent.mkdir(parents=True, exist_ok=True)
+                if entry.get("kind") == "dir":
+                    shutil.copytree(backup, target)
+                else:
+                    shutil.copy2(backup, target)
+            restored.append(entry["path"])
+        checkpoint_name = manifest["id"]
+        shutil.rmtree(checkpoint_dir, ignore_errors=True)
+        return f"Checkpoint restaurado: {checkpoint_name}\nRutas: " + ", ".join(restored)
+
+    def git_root(self) -> Path | None:
+        try:
+            result = subprocess.run(
+                ["git", "rev-parse", "--show-toplevel"],
+                cwd=self.root,
+                text=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.DEVNULL,
+                timeout=5,
+            )
+        except (OSError, subprocess.SubprocessError):
+            return None
+        if result.returncode != 0:
+            return None
+        return Path(result.stdout.strip()).resolve()
+
+    def git_branch(self) -> str:
+        try:
+            result = subprocess.run(
+                ["git", "branch", "--show-current"],
+                cwd=self.root,
+                text=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.DEVNULL,
+                timeout=3,
+            )
+            return result.stdout.strip() or "detached"
+        except Exception:
+            return "no-git"
+
+
+class PatchError(RuntimeError):
+    pass
+
+
+class PatchEngine:
+    """Aplica el formato *** Begin Patch usado por agentes de código."""
+
+    def __init__(self, workspace: Workspace) -> None:
+        self.workspace = workspace
+
+    def apply(self, patch: str) -> tuple[list[str], str]:
+        lines = patch.splitlines()
+        if not lines or lines[0].strip() != "*** Begin Patch":
+            raise PatchError("el parche debe comenzar con '*** Begin Patch'")
+        if lines[-1].strip() != "*** End Patch":
+            raise PatchError("el parche debe terminar con '*** End Patch'")
+
+        index = 1
+        operations: list[tuple[str, str, list[str]]] = []
+        while index < len(lines) - 1:
+            header = lines[index]
+            match = re.match(r"\*\*\* (Add|Update|Delete) File: (.+)$", header)
+            if not match:
+                if not header.strip():
+                    index += 1
+                    continue
+                raise PatchError(f"encabezado de operación inválido: {header}")
+            operation = match.group(1).lower()
+            path = match.group(2).strip()
+            index += 1
+            body: list[str] = []
+            while index < len(lines) - 1 and not lines[index].startswith("*** "):
+                body.append(lines[index])
+                index += 1
+            operations.append((operation, path, body))
+
+        targets = [self.workspace.resolve(path, for_write=True) for _, path, _ in operations]
+        checkpoint = self.workspace.checkpoint(targets, "apply_patch")
+        changed: list[str] = []
+
+        try:
+            for operation, path, body in operations:
+                target = self.workspace.resolve(path, for_write=True)
+                if operation == "add":
+                    if target.exists():
+                        raise PatchError(f"el archivo ya existe: {path}")
+                    content_lines = [line[1:] if line.startswith("+") else line for line in body]
+                    target.parent.mkdir(parents=True, exist_ok=True)
+                    target.write_text("\n".join(content_lines) + ("\n" if body else ""), encoding="utf-8")
+                elif operation == "delete":
+                    if not target.exists():
+                        raise PatchError(f"no existe: {path}")
+                    if target.is_dir():
+                        shutil.rmtree(target)
+                    else:
+                        target.unlink()
+                else:
+                    self._update_file(target, path, body)
+                changed.append(path)
+        except Exception:
+            self.workspace.undo(checkpoint)
+            raise
+
+        return changed, checkpoint
+
+    def _update_file(self, target: Path, path: str, body: list[str]) -> None:
+        if not target.exists() or not target.is_file():
+            raise PatchError(f"archivo no encontrado: {path}")
+        original = target.read_text(encoding="utf-8")
+        original_lines = original.splitlines()
+        had_final_newline = original.endswith("\n")
+
+        hunks: list[list[str]] = []
+        current: list[str] = []
+        for line in body:
+            if line.startswith("@@"):
+                if current:
+                    hunks.append(current)
+                    current = []
+            else:
+                current.append(line)
+        if current:
+            hunks.append(current)
+        if not hunks:
+            raise PatchError(f"sin bloques de cambio para {path}")
+
+        working = original_lines[:]
+        search_start = 0
+        for hunk in hunks:
+            old: list[str] = []
+            new: list[str] = []
+            for line in hunk:
+                if line.startswith("-"):
+                    old.append(line[1:])
+                elif line.startswith("+"):
+                    new.append(line[1:])
+                elif line.startswith(" "):
+                    value = line[1:]
+                    old.append(value)
+                    new.append(value)
+                elif line == "\":
+                    continue
+                else:
+                    old.append(line)
+                    new.append(line)
+
+            position = self._find_sequence(working, old, search_start)
+            if position is None:
+                position = self._find_sequence(working, old, 0)
+            if position is None:
+                preview = "\n".join(old[:8])
+                raise PatchError(f"no se encontró el contexto en {path}:\n{preview}")
+            working[position : position + len(old)] = new
+            search_start = position + len(new)
+
+        new_content = "\n".join(working)
+        if had_final_newline:
+            new_content += "\n"
+        target.write_text(new_content, encoding="utf-8")
+
+    @staticmethod
+    def _find_sequence(haystack: list[str], needle: list[str], start: int) -> int | None:
+        if not needle:
+            return start
+        limit = len(haystack) - len(needle) + 1
+        for index in range(max(0, start), max(0, limit)):
+            if haystack[index : index + len(needle)] == needle:
+                return index
+        return None
+
+
+@dataclasses.dataclass
+class CommandResult:
+    command: str
+    cwd: str
+    returncode: int
+    duration: float
+    output: str
+    timed_out: bool = False
+    blocked: bool = False
+    policy: str = ""
+
+    @property
+    def success(self) -> bool:
+        return self.returncode == 0 and not self.timed_out and not self.blocked
+
+    def to_text(self) -> str:
+        state = "OK" if self.success else "FALLO"
+        extras: list[str] = []
+        if self.timed_out:
+            extras.append("timeout")
+        if self.blocked:
+            extras.append("bloqueado")
+        suffix = f" ({', '.join(extras)})" if extras else ""
+        return (
+            f"[{state}{suffix}] {self.command}\n"
+            f"Política: {self.policy or '-'}\n"
+            f"Código de salida: {self.returncode}\n"
+            f"Duración: {self.duration:.2f}s\n"
+            f"CWD: {self.cwd}\nSalida:\n{self.output or '(sin salida)'}"
+        )
+
+
+@dataclasses.dataclass(frozen=True)
+class DiagnosticCommand:
+    name: str
+    command: str
+    timeout: int = 180
+    cwd: str = "."
+
+
+@dataclasses.dataclass
+class DiagnosticReport:
+    mode: VerificationMode
+    detected: list[str]
+    results: list[CommandResult]
+    skipped_reason: str | None = None
+
+    @property
+    def success(self) -> bool:
+        return bool(self.results) and all(item.success for item in self.results)
+
+    @property
+    def blocked(self) -> bool:
+        return any(item.blocked for item in self.results)
+
+    @property
+    def failed(self) -> list[CommandResult]:
+        return [item for item in self.results if not item.success]
+
+    def to_text(self, limit: int = 24_000) -> str:
+        if not self.results:
+            return f"VERIFICACIÓN OMITIDA: {self.skipped_reason or 'no se detectaron comprobaciones'}"
+        heading = (
+            f"VERIFICACIÓN {'CORRECTA' if self.success else 'FALLIDA'} · "
+            f"modo={self.mode} · tipos={', '.join(self.detected) or 'genérico'}"
+        )
+        body = "\n\n".join(item.to_text() for item in self.results)
+        return truncate(heading + "\n\n" + body, limit)
+
+
+class ProjectDoctor:
+    """Detecta el tipo de proyecto y propone verificaciones locales sin instalar nada."""
+
+    def __init__(self, workspace: Workspace, config: AppConfig) -> None:
+        self.workspace = workspace
+        self.config = config
+
+    def detect_commands(self, mode: VerificationMode = "quick") -> tuple[list[str], list[DiagnosticCommand]]:
+        if mode == "off":
+            return [], []
+        root = self.workspace.root
+        detected: list[str] = []
+        commands: list[DiagnosticCommand] = []
+
+        def add(kind: str, name: str, command: str, timeout: int = 180, cwd: str = ".") -> None:
+            if kind not in detected:
+                detected.append(kind)
+            if command and all(existing.command != command for existing in commands):
+                commands.append(DiagnosticCommand(name=name, command=command, timeout=timeout, cwd=cwd))
+
+        def has_source(suffix: str, limit: int = 3000) -> bool:
+            seen = 0
+            for current_root, dirs, files in os.walk(root):
+                dirs[:] = [d for d in dirs if d not in DEFAULT_IGNORES]
+                for filename in files:
+                    seen += 1
+                    if filename.endswith(suffix):
+                        return True
+                    if seen >= limit:
+                        return False
+            return False
+
+        python_cmd = f'"{sys.executable}"' if os.name == "nt" else shlex.quote(sys.executable)
+        is_python = any((root / name).exists() for name in ("pyproject.toml", "setup.py", "requirements.txt")) or has_source(".py")
+        if is_python:
+            add("python", "compilación de sintaxis", f"{python_cmd} -m compileall -q .", 180)
+            ruff_configured = any((root / name).exists() for name in ("ruff.toml", ".ruff.toml"))
+            if not ruff_configured and (root / "pyproject.toml").exists():
+                try:
+                    ruff_configured = "[tool.ruff" in (root / "pyproject.toml").read_text(encoding="utf-8")
+                except Exception:
+                    ruff_configured = False
+            if ruff_configured and shutil.which("ruff"):
+                add("python", "ruff", "ruff check .", 180)
+            has_tests = any((root / name).exists() for name in ("tests", "test", "pytest.ini", "tox.ini"))
+            pytest_available = importlib.util.find_spec("pytest") is not None or shutil.which("pytest") is not None
+            if mode == "full" and has_tests and pytest_available:
+                add("python", "pytest", f"{python_cmd} -m pytest -q", 600)
+
+        package_json = root / "package.json"
+        if package_json.exists():
+            scripts: dict[str, Any] = {}
+            try:
+                data = json.loads(package_json.read_text(encoding="utf-8"))
+                scripts = data.get("scripts", {}) if isinstance(data, dict) else {}
+            except Exception:
+                scripts = {}
+            manager = "npm"
+            if (root / "pnpm-lock.yaml").exists() and shutil.which("pnpm"):
+                manager = "pnpm"
+            elif (root / "yarn.lock").exists() and shutil.which("yarn"):
+                manager = "yarn"
+            elif (root / "bun.lockb").exists() and shutil.which("bun"):
+                manager = "bun"
+            run = f"{manager} run"
+            if "lint" in scripts:
+                add("javascript", "lint", f"{run} lint", 300)
+            local_tsc = root / "node_modules" / ".bin" / ("tsc.cmd" if os.name == "nt" else "tsc")
+            if (root / "tsconfig.json").exists() and local_tsc.exists():
+                tsc = f'"{local_tsc}"' if os.name == "nt" else shlex.quote(str(local_tsc))
+                add("typescript", "typecheck", f"{tsc} --noEmit", 300)
+            if mode == "full":
+                if "test" in scripts:
+                    add("javascript", "tests", f"{run} test", 600)
+                if "build" in scripts:
+                    add("javascript", "build", f"{run} build", 600)
+            elif "check" in scripts:
+                add("javascript", "check", f"{run} check", 300)
+
+        if (root / "Cargo.toml").exists() and shutil.which("cargo"):
+            add("rust", "cargo check", "cargo check", 600)
+            if mode == "full":
+                add("rust", "cargo test", "cargo test", 900)
+
+        if (root / "go.mod").exists() and shutil.which("go"):
+            add("go", "go test", "go test ./...", 600)
+
+        gradlew = root / ("gradlew.bat" if os.name == "nt" else "gradlew")
+        if gradlew.exists():
+            wrapper = "gradlew.bat" if os.name == "nt" else "./gradlew"
+            add("gradle", "gradle check", f"{wrapper} check", 900)
+            if mode == "full":
+                add("gradle", "gradle test", f"{wrapper} test", 900)
+        elif any((root / name).exists() for name in ("build.gradle", "build.gradle.kts")) and shutil.which("gradle"):
+            add("gradle", "gradle check", "gradle check", 900)
+
+        mvnw = root / ("mvnw.cmd" if os.name == "nt" else "mvnw")
+        if mvnw.exists():
+            wrapper = "mvnw.cmd" if os.name == "nt" else "./mvnw"
+            goal = "test" if mode == "full" else "-DskipTests compile"
+            add("maven", "maven", f"{wrapper} {goal}", 900)
+        elif (root / "pom.xml").exists() and shutil.which("mvn"):
+            goal = "test" if mode == "full" else "-DskipTests compile"
+            add("maven", "maven", f"mvn {goal}", 900)
+
+        if any(root.glob("*.sln")) or any(root.glob("*.csproj")):
+            if shutil.which("dotnet"):
+                add("dotnet", "dotnet build", "dotnet build --nologo", 900)
+                if mode == "full":
+                    add("dotnet", "dotnet test", "dotnet test --nologo --no-build", 900)
+
+        if (root / "composer.json").exists() and shutil.which("php"):
+            add("php", "php syntax", "php -l index.php" if (root / "index.php").exists() else "php --version", 120)
+
+        return detected, commands
+
+
+class ToolBox:
+    def __init__(self, workspace: Workspace, state: SessionState, config: AppConfig) -> None:
+        self.workspace = workspace
+        self.state = state
+        self.config = config
+        self.patch_engine = PatchEngine(workspace)
+        self.doctor = ProjectDoctor(workspace, config)
+        self.mutation_checkpoints: list[str] = []
+        self.changed_paths: list[str] = []
+        self.last_diagnostic_report: DiagnosticReport | None = None
+        self.functions: dict[str, Callable[..., str]] = {
+            "list_files": self.list_files,
+            "read_file": self.read_file,
+            "read_files": self.read_files,
+            "search_text": self.search_text,
+            "find_files": self.find_files,
+            "apply_patch": self.apply_patch,
+            "write_file": self.write_file,
+            "delete_path": self.delete_path,
+            "run_command": self.run_command,
+            "git_status": self.git_status,
+            "git_diff": self.git_diff,
+            "update_plan": self.update_plan,
+            "project_context": self.project_context,
+            "diagnose_project": self.diagnose_project,
+        }
+
+    @property
+    def schemas(self) -> list[dict[str, Any]]:
+        schemas = [
+            self._schema(
+                "list_files",
+                "Lista el árbol de archivos y carpetas del proyecto.",
+                {
+                    "path": {"type": "string", "default": "."},
+                    "max_depth": {"type": "integer", "default": 4},
+                },
+            ),
+            self._schema(
+                "read_file",
+                "Lee un archivo de texto con números de línea.",
+                {
+                    "path": {"type": "string"},
+                    "start_line": {"type": "integer", "default": 1},
+                    "end_line": {"type": "integer", "default": 500},
+                },
+                ["path"],
+            ),
+            self._schema(
+                "read_files",
+                "Lee varios archivos de texto en una sola llamada.",
+                {"paths": {"type": "array", "items": {"type": "string"}, "maxItems": 20}},
+                ["paths"],
+            ),
+            self._schema(
+                "search_text",
+                "Busca una expresión regular o texto en los archivos del proyecto.",
+                {
+                    "query": {"type": "string"},
+                    "path": {"type": "string", "default": "."},
+                    "case_sensitive": {"type": "boolean", "default": False},
+                    "regex": {"type": "boolean", "default": False},
+                    "glob": {"type": "string", "description": "Filtro opcional, por ejemplo *.py"},
+                },
+                ["query"],
+            ),
+            self._schema(
+                "find_files",
+                "Encuentra archivos por patrón glob, por ejemplo **/*.py.",
+                {
+                    "pattern": {"type": "string"},
+                    "path": {"type": "string", "default": "."},
+                },
+                ["pattern"],
+            ),
+            self._schema(
+                "apply_patch",
+                "Aplica cambios atómicos con formato *** Begin Patch / Add|Update|Delete File / *** End Patch.",
+                {"patch": {"type": "string"}},
+                ["patch"],
+            ),
+            self._schema(
+                "write_file",
+                "Crea o reemplaza por completo un archivo. Prefiere apply_patch para archivos existentes.",
+                {"path": {"type": "string"}, "content": {"type": "string"}},
+                ["path", "content"],
+            ),
+            self._schema(
+                "delete_path",
+                "Elimina un archivo o carpeta después de aplicar la política de permisos.",
+                {"path": {"type": "string"}},
+                ["path"],
+            ),
+            self._schema(
+                "run_command",
+                "Ejecuta un comando de terminal. Indica cwd relativo y timeout cuando sea necesario.",
+                {
+                    "command": {"type": "string"},
+                    "cwd": {"type": "string", "default": "."},
+                    "timeout": {"type": "integer", "default": self.config.command_timeout},
+                },
+                ["command"],
+            ),
+            self._schema("git_status", "Muestra el estado Git corto del proyecto.", {}, []),
+            self._schema(
+                "git_diff",
+                "Muestra el diff Git. Puede incluir cambios staged.",
+                {
+                    "staged": {"type": "boolean", "default": False},
+                    "path": {"type": "string", "description": "Ruta opcional"},
+                },
+            ),
+            self._schema(
+                "update_plan",
+                "Crea o actualiza el plan de trabajo visible al usuario.",
+                {
+                    "items": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "step": {"type": "string"},
+                                "status": {
+                                    "type": "string",
+                                    "enum": ["pending", "in_progress", "completed"],
+                                },
+                            },
+                            "required": ["step", "status"],
+                        },
+                    }
+                },
+                ["items"],
+            ),
+            self._schema(
+                "project_context",
+                "Obtiene reglas, manifiestos y resumen Git del proyecto.",
+                {},
+                [],
+            ),
+            self._schema(
+                "diagnose_project",
+                "Detecta el tipo de proyecto y ejecuta verificaciones locales. Usa quick durante el trabajo y full antes de finalizar una corrección importante.",
+                {"mode": {"type": "string", "enum": ["quick", "full"], "default": "quick"}},
+                [],
+            ),
+        ]
+        return schemas
+
+    @staticmethod
+    def _schema(
+        name: str,
+        description: str,
+        properties: dict[str, Any],
+        required: list[str] | None = None,
+    ) -> dict[str, Any]:
+        parameters: dict[str, Any] = {"type": "object", "properties": properties}
+        if required:
+            parameters["required"] = required
+        return {
+            "type": "function",
+            "function": {"name": name, "description": description, "parameters": parameters},
+        }
+
+    def execute(self, name: str, arguments: dict[str, Any]) -> str:
+        function = self.functions.get(name)
+        if function is None:
+            return f"ERROR: herramienta desconocida: {name}"
+        if self.state.plan_mode and name in {"apply_patch", "write_file", "delete_path"}:
+            return "BLOQUEADO: el modo plan no permite modificar archivos"
+        try:
+            return truncate(str(function(**arguments)))
+        except TypeError as exc:
+            return f"ERROR de argumentos en {name}: {exc}"
+        except Exception as exc:
+            return f"ERROR en {name}: {type(exc).__name__}: {exc}"
+
+    def _iter_files(self, base: Path) -> Iterable[Path]:
+        if base.is_file():
+            yield base
+            return
+        for current_root, dirs, files in os.walk(base):
+            dirs[:] = sorted(d for d in dirs if d not in DEFAULT_IGNORES)
+            for filename in sorted(files):
+                yield Path(current_root) / filename
+
+    def list_files(self, path: str = ".", max_depth: int = 4) -> str:
+        base = self.workspace.resolve(path)
+        max_depth = max(1, min(int(max_depth), 12))
+        if not base.exists():
+            return f"ERROR: no existe {path}"
+        if base.is_file():
+            return self.workspace.relative(base)
+
+        rows: list[str] = []
+        base_depth = len(base.parts)
+        for current_root, dirs, files in os.walk(base):
+            current = Path(current_root)
+            depth = len(current.parts) - base_depth
+            dirs[:] = sorted(d for d in dirs if d not in DEFAULT_IGNORES and depth < max_depth)
+            if current != base:
+                rows.append(f"{'  ' * depth}{current.name}/")
+            file_indent = "  " * (depth + (1 if current != base else 0))
+            for filename in sorted(files):
+                rows.append(f"{file_indent}{filename}")
+                if len(rows) >= MAX_LISTED_FILES:
+                    rows.append("...[límite de archivos alcanzado]")
+                    return "\n".join(rows)
+        return "\n".join(rows) if rows else "(carpeta vacía)"
+
+    def read_file(self, path: str, start_line: int = 1, end_line: int = 500) -> str:
+        target = self.workspace.resolve(path)
+        if not target.exists():
+            return f"ERROR: no existe {path}"
+        if not target.is_file():
+            return f"ERROR: {path} no es un archivo"
+        if target.stat().st_size > 5_000_000:
+            return f"ERROR: archivo demasiado grande ({target.stat().st_size} bytes)"
+
+        start = max(1, int(start_line))
+        end = min(max(start, int(end_line)), start + MAX_FILE_READ_LINES - 1)
+        try:
+            text = target.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            return f"ERROR: {path} parece binario o no usa UTF-8"
+        lines = text.splitlines()
+        selected = lines[start - 1 : end]
+        numbered = [f"{number:>5} | {line}" for number, line in enumerate(selected, start=start)]
+        return (
+            f"Archivo: {self.workspace.relative(target)} "
+            f"(líneas {start}-{min(end, len(lines))} de {len(lines)}, sha256={sha256_text(text)[:12]})\n"
+            + "\n".join(numbered)
+        )
+
+    def read_files(self, paths: list[str]) -> str:
+        if len(paths) > 20:
+            return "ERROR: máximo 20 archivos por llamada"
+        outputs = [self.read_file(path, 1, 500) for path in paths]
+        return "\n\n" + ("\n\n" + "=" * 80 + "\n\n").join(outputs)
+
+    def search_text(
+        self,
+        query: str,
+        path: str = ".",
+        case_sensitive: bool = False,
+        regex: bool = False,
+        glob: str | None = None,
+    ) -> str:
+        base = self.workspace.resolve(path)
+        if not base.exists():
+            return f"ERROR: no existe {path}"
+        flags = 0 if case_sensitive else re.IGNORECASE
+        try:
+            pattern = re.compile(query if regex else re.escape(query), flags)
+        except re.error as exc:
+            return f"ERROR: expresión regular inválida: {exc}"
+
+        matches: list[str] = []
+        for candidate in self._iter_files(base):
+            if glob and not fnmatch.fnmatch(candidate.name, glob) and not fnmatch.fnmatch(self.workspace.relative(candidate), glob):
+                continue
+            try:
+                if candidate.stat().st_size > 2_000_000:
+                    continue
+                text = candidate.read_text(encoding="utf-8")
+            except (UnicodeDecodeError, OSError):
+                continue
+            for line_number, line in enumerate(text.splitlines(), start=1):
+                if pattern.search(line):
+                    matches.append(f"{self.workspace.relative(candidate)}:{line_number}: {line.rstrip()}")
+                    if len(matches) >= MAX_SEARCH_MATCHES:
+                        matches.append("...[límite de coincidencias alcanzado]")
+                        return "\n".join(matches)
+        return "\n".join(matches) if matches else "(sin coincidencias)"
+
+    def find_files(self, pattern: str, path: str = ".") -> str:
+        base = self.workspace.resolve(path)
+        if not base.exists():
+            return f"ERROR: no existe {path}"
+        matches = [
+            self.workspace.relative(candidate)
+            for candidate in self._iter_files(base)
+            if fnmatch.fnmatch(self.workspace.relative(candidate), pattern)
+            or fnmatch.fnmatch(candidate.name, pattern)
+        ]
+        return "\n".join(matches[:MAX_LISTED_FILES]) if matches else "(sin archivos)"
+
+    def _mutation_allowed(self, target: Path, description: str) -> bool:
+        return self.workspace.approvals.approve_mutation(description, self.workspace.is_outside(target))
+
+    def apply_patch(self, patch: str) -> str:
+        paths = re.findall(r"^\*\*\* (?:Add|Update|Delete) File: (.+)$", patch, flags=re.MULTILINE)
+        if not paths:
+            return "ERROR: el parche no contiene operaciones"
+        for path in paths:
+            target = self.workspace.resolve(path, for_write=True)
+            if not self._mutation_allowed(target, f"Aplicar parche sobre {path}"):
+                return "OPERACIÓN RECHAZADA POR PERMISOS"
+        changed, checkpoint = self.patch_engine.apply(patch)
+        self.state.last_checkpoint = checkpoint
+        self.mutation_checkpoints.append(checkpoint)
+        self.changed_paths.extend(path for path in changed if path not in self.changed_paths)
+        return f"Parche aplicado. Checkpoint: {checkpoint}\nArchivos: " + ", ".join(changed)
+
+    def write_file(self, path: str, content: str) -> str:
+        target = self.workspace.resolve(path, for_write=True)
+        if not self._mutation_allowed(target, f"Escribir {path}"):
+            return "OPERACIÓN RECHAZADA POR PERMISOS"
+        if target.exists() and target.is_dir():
+            return f"ERROR: {path} es una carpeta"
+        if target.exists():
+            try:
+                old = target.read_text(encoding="utf-8")
+            except UnicodeDecodeError:
+                return f"ERROR: {path} parece binario; write_file no lo reemplazará"
+        else:
+            old = ""
+        checkpoint = self.workspace.checkpoint([target], f"write_file {path}")
+        try:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(content, encoding="utf-8", newline="")
+        except Exception:
+            self.workspace.undo(checkpoint)
+            raise
+        self.state.last_checkpoint = checkpoint
+        self.mutation_checkpoints.append(checkpoint)
+        if path not in self.changed_paths:
+            self.changed_paths.append(path)
+        diff = "\n".join(
+            difflib.unified_diff(
+                old.splitlines(), content.splitlines(), fromfile=f"a/{path}", tofile=f"b/{path}", lineterm=""
+            )
+        )
+        return f"Escrito: {path}. Checkpoint: {checkpoint}\n{truncate(diff, 8_000)}"
+
+    def delete_path(self, path: str) -> str:
+        target = self.workspace.resolve(path, for_write=True)
+        if target == self.workspace.root:
+            return "ERROR: no se puede eliminar la raíz del workspace"
+        if not target.exists():
+            return f"ERROR: no existe {path}"
+        if not self._mutation_allowed(target, f"Eliminar {path}"):
+            return "OPERACIÓN RECHAZADA POR PERMISOS"
+        checkpoint = self.workspace.checkpoint([target], f"delete_path {path}")
+        if target.is_dir():
+            shutil.rmtree(target)
+        else:
+            target.unlink()
+        self.state.last_checkpoint = checkpoint
+        self.mutation_checkpoints.append(checkpoint)
+        if path not in self.changed_paths:
+            self.changed_paths.append(path)
+        return f"Eliminado: {path}. Checkpoint: {checkpoint}"
+
+    def _run_command_raw(
+        self, command: str, cwd: str = ".", timeout: int | None = None, *, internal_diagnostic: bool = False
+    ) -> CommandResult:
+        if self.state.plan_mode:
+            classification, _ = self.workspace.approvals.classify_command(command)
+            if classification != "trusted":
+                return CommandResult(
+                    command=command,
+                    cwd=str(self.workspace.root),
+                    returncode=126,
+                    duration=0.0,
+                    output="BLOQUEADO: modo plan solo permite comandos de inspección reconocidos",
+                    blocked=True,
+                    policy="modo plan",
+                )
+
+        try:
+            working_dir = self.workspace.resolve(cwd)
+        except Exception as exc:
+            return CommandResult(command, cwd, 126, 0.0, f"ERROR: cwd inválido: {exc}", blocked=True, policy="ruta")
+        if not working_dir.exists() or not working_dir.is_dir():
+            return CommandResult(command, str(working_dir), 126, 0.0, "ERROR: cwd inválido", blocked=True, policy="ruta")
+
+        if internal_diagnostic:
+            classification, reasons = self.workspace.approvals.classify_command(command)
+            if self.config.permission_mode == "read-only":
+                approved, reason = False, "diagnóstico bloqueado por modo read-only"
+            elif classification in {"dangerous", "network", "deny"}:
+                approved, reason = False, "; ".join(reasons)
+            else:
+                approved, reason = True, "verificador interno del workspace"
+        else:
+            approved, reason = self.workspace.approvals.approve_command(command)
+        if not approved:
+            return CommandResult(
+                command=command,
+                cwd=str(working_dir),
+                returncode=126,
+                duration=0.0,
+                output=f"OPERACIÓN RECHAZADA: {reason}",
+                blocked=True,
+                policy=reason,
+            )
+
+        timeout_value = max(1, min(int(timeout or self.config.command_timeout), 3_600))
+        started = time.perf_counter()
+        env = os.environ.copy()
+        env["LMCODING_WORKSPACE"] = str(self.workspace.root)
+        env["LMCODING_PERMISSION_MODE"] = self.config.permission_mode
+        env.setdefault("CI", "1")
+        try:
+            completed = subprocess.run(
+                command,
+                cwd=working_dir,
+                shell=True,
+                text=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                timeout=timeout_value,
+                errors="replace",
+                env=env,
+            )
+            return CommandResult(
+                command=command,
+                cwd=str(working_dir),
+                returncode=int(completed.returncode),
+                duration=time.perf_counter() - started,
+                output=completed.stdout or "(sin salida)",
+                policy=reason,
+            )
+        except subprocess.TimeoutExpired as exc:
+            partial = exc.stdout or ""
+            if isinstance(partial, bytes):
+                partial = partial.decode(errors="replace")
+            return CommandResult(
+                command=command,
+                cwd=str(working_dir),
+                returncode=124,
+                duration=time.perf_counter() - started,
+                output=f"El comando excedió {timeout_value}s. Salida parcial:\n{partial}",
+                timed_out=True,
+                policy=reason,
+            )
+        except Exception as exc:
+            return CommandResult(
+                command=command,
+                cwd=str(working_dir),
+                returncode=127,
+                duration=time.perf_counter() - started,
+                output=f"{type(exc).__name__}: {exc}",
+                policy=reason,
+            )
+
+    def run_command(self, command: str, cwd: str = ".", timeout: int | None = None) -> str:
+        return self._run_command_raw(command, cwd, timeout).to_text()
+
+    def run_diagnostics_report(self, mode: VerificationMode = "quick") -> DiagnosticReport:
+        detected, commands = self.doctor.detect_commands(mode)
+        if not commands:
+            report = DiagnosticReport(mode=mode, detected=detected, results=[], skipped_reason="no se detectaron validadores locales")
+            self.last_diagnostic_report = report
+            self.state.last_verification = report.to_text()
+            return report
+        results: list[CommandResult] = []
+        for item in commands:
+            result = self._run_command_raw(item.command, item.cwd, item.timeout, internal_diagnostic=True)
+            results.append(result)
+            if result.blocked:
+                break
+            if not result.success and mode == "quick":
+                break
+        report = DiagnosticReport(mode=mode, detected=detected, results=results)
+        self.last_diagnostic_report = report
+        self.state.last_verification = report.to_text()
+        return report
+
+    def diagnose_project(self, mode: str = "quick") -> str:
+        selected: VerificationMode = "full" if mode == "full" else "quick"
+        return self.run_diagnostics_report(selected).to_text()
+
+    def rollback_mutations(self, start_index: int) -> str:
+        checkpoints = self.mutation_checkpoints[start_index:]
+        if not checkpoints:
+            return "No había cambios del agente para revertir."
+        messages: list[str] = []
+        for checkpoint in reversed(checkpoints):
+            result = self.workspace.undo(checkpoint)
+            messages.append(result)
+        del self.mutation_checkpoints[start_index:]
+        self.state.last_checkpoint = self.mutation_checkpoints[-1] if self.mutation_checkpoints else None
+        return "\n".join(messages)
+
+    def git_status(self) -> str:
+        if self.workspace.git_root() is None:
+            return "(no es un repositorio Git)"
+        return self.run_command("git status --short --branch", timeout=30)
+
+    def git_diff(self, staged: bool = False, path: str | None = None) -> str:
+        if self.workspace.git_root() is None:
+            return "(no es un repositorio Git)"
+        command = "git diff --no-ext-diff --unified=3"
+        if staged:
+            command += " --cached"
+        if path:
+            safe_path = shlex.quote(path) if os.name != "nt" else f'"{path}"'
+            command += f" -- {safe_path}"
+        return self.run_command(command, timeout=30)
+
+    def update_plan(self, items: list[dict[str, str]]) -> str:
+        if len(items) > 20:
+            return "ERROR: máximo 20 pasos"
+        plan: list[PlanItem] = []
+        in_progress = 0
+        for item in items:
+            status = item.get("status", "pending")
+            if status not in {"pending", "in_progress", "completed"}:
+                return f"ERROR: estado inválido: {status}"
+            if status == "in_progress":
+                in_progress += 1
+            plan.append(PlanItem(step=str(item.get("step", "")).strip(), status=status))
+        if in_progress > 1:
+            return "ERROR: solo un paso puede estar in_progress"
+        self.state.plan = plan
+        self._render_plan()
+        return "Plan actualizado"
+
+    def _render_plan(self) -> None:
+        if not self.state.plan:
+            return
+        table = Table(title="Plan", show_header=False)
+        table.add_column("Estado", width=3)
+        table.add_column("Paso")
+        symbols = {"pending": "○", "in_progress": "◉", "completed": "✓"}
+        for item in self.state.plan:
+            table.add_row(symbols[item.status], item.step)
+        console.print(table)
+
+    def project_context(self) -> str:
+        chunks: list[str] = [f"Workspace: {self.workspace.root}"]
+        chunks.append(f"Git branch: {self.workspace.git_branch()}")
+        status = self.git_status()
+        chunks.append(f"Git status:\n{truncate(status, 3_000)}")
+        for filename in PROJECT_HINT_FILES:
+            candidate = self.workspace.root / filename
+            if candidate.is_file():
+                try:
+                    text = candidate.read_text(encoding="utf-8")
+                except Exception:
+                    continue
+                chunks.append(f"\n## {filename}\n{truncate(text, 8_000)}")
+        return "\n".join(chunks)
+
+
+class SlashCompleter(Completer):
+    COMMANDS = {
+        "/help": "mostrar comandos",
+        "/status": "estado de sesión",
+        "/permissions": "cambiar permisos",
+        "/model": "cambiar modelo",
+        "/models": "listar modelos",
+        "/plan": "activar o desactivar modo plan",
+        "/review": "revisar cambios Git",
+        "/doctor": "diagnóstico completo del proyecto",
+        "/verify": "verificación rápida o completa",
+        "/autofix": "activar o desactivar autocorrección",
+        "/diff": "mostrar diff",
+        "/undo": "restaurar último checkpoint",
+        "/compact": "compactar contexto",
+        "/new": "nueva conversación",
+        "/save": "guardar sesión",
+        "/rename": "renombrar sesión",
+        "/sessions": "listar sesiones",
+        "/resume": "reanudar sesión",
+        "/clear": "limpiar pantalla",
+        "/exit": "salir",
+    }
+
+    def get_completions(self, document: Any, complete_event: Any) -> Iterable[Completion]:
+        text = document.text_before_cursor
+        if not text.startswith("/") or " " in text:
+            return
+        for command, description in self.COMMANDS.items():
+            if command.startswith(text):
+                yield Completion(command, start_position=-len(text), display_meta=description)
+
+
+class LMCodingAgent:
+    def __init__(
+        self,
+        workspace: Workspace,
+        config: AppConfig,
+        state: SessionState | None = None,
+    ) -> None:
+        self.workspace = workspace
+        self.config = config
+        self.client = OpenAI(base_url=config.base_url.rstrip("/"), api_key=config.api_key)
+        self.store = SessionStore()
+        self.state = state or SessionState.create(workspace.root, config.model)
+        self.model = self.state.model or config.model
+        self.toolbox = ToolBox(workspace, self.state, config)
+        self.available_models: list[str] = []
+        self._ensure_system_message()
+
+    def _ensure_system_message(self) -> None:
+        prompt = SYSTEM_PROMPT + f"\nWorkspace: {self.workspace.root}\n"
+        prompt += (
+            f"Permisos actuales: mode={self.config.permission_mode}, "
+            f"approval={self.config.approval_policy}.\n"
+        )
+        if self.state.plan_mode:
+            prompt += PLAN_MODE_PROMPT
+        if self.state.messages and self.state.messages[0].get("role") == "system":
+            self.state.messages[0]["content"] = prompt
+        else:
+            self.state.messages.insert(0, {"role": "system", "content": prompt})
+
+    def connect(self) -> str:
+        try:
+            models = list(self.client.models.list().data)
+        except Exception as exc:
+            raise RuntimeError(
+                "No se pudo conectar con LM Studio. Inicia el servidor local en Developer."
+            ) from exc
+        self.available_models = [item.id for item in models]
+        if not self.model:
+            if not self.available_models:
+                raise RuntimeError("LM Studio no expone ningún modelo. Carga uno primero.")
+            self.model = self.available_models[0]
+        self.state.model = self.model
+        self._save()
+        return self.model
+
+    def _save(self) -> None:
+        if self.config.save_sessions:
+            self.store.save(self.state)
+
+    def set_model(self, model: str) -> None:
+        self.model = model.strip()
+        self.state.model = self.model
+        self._save()
+
+    def set_permissions(self, mode: PermissionMode, approval: ApprovalPolicy | None = None) -> None:
+        self.config.permission_mode = mode
+        if approval:
+            self.config.approval_policy = approval
+        elif mode == "read-only":
+            self.config.approval_policy = "untrusted"
+        elif mode == "workspace-write":
+            self.config.approval_policy = "on-request"
+        else:
+            self.config.approval_policy = "never"
+        self._ensure_system_message()
+
+    def set_plan_mode(self, enabled: bool) -> None:
+        self.state.plan_mode = enabled
+        self._ensure_system_message()
+        self._save()
+
+    def new_conversation(self) -> None:
+        self.state = SessionState.create(self.workspace.root, self.model)
+        self.toolbox = ToolBox(self.workspace, self.state, self.config)
+        self._ensure_system_message()
+        self._save()
+
+    def resume(self, state: SessionState) -> None:
+        self.state = state
+        self.model = state.model or self.model
+        self.toolbox = ToolBox(self.workspace, self.state, self.config)
+        self._ensure_system_message()
+
+    def estimate_context_chars(self) -> int:
+        return sum(len(json.dumps(message, ensure_ascii=False)) for message in self.state.messages)
+
+    def compact(self, force: bool = True) -> bool:
+        size = self.estimate_context_chars()
+        if not force and size < self.config.max_context_chars:
+            return False
+        if len(self.state.messages) < 8:
+            return False
+
+        old_messages = self.state.messages[1:-6]
+        if not old_messages:
+            return False
+        transcript = truncate(json.dumps(old_messages, ensure_ascii=False), 60_000)
+        summary_request = [
+            {
+                "role": "system",
+                "content": (
+                    "Resume una sesión de programación para conservar contexto operativo. "
+                    "Incluye objetivo, decisiones, archivos leídos/modificados, comandos, resultados, "
+                    "errores, restricciones y trabajo pendiente. No inventes nada."
+                ),
+            },
+            {"role": "user", "content": transcript},
+        ]
+        try:
+            response = self.client.chat.completions.create(
+                model=self.model,
+                messages=summary_request,
+                temperature=0.0,
+            )
+            summary = response.choices[0].message.content or "Resumen no disponible."
+        except Exception:
+            summary = truncate(transcript, 20_000)
+        self.state.messages = [
+            self.state.messages[0],
+            {"role": "system", "content": "Resumen de conversación anterior:\n" + summary},
+            *self.state.messages[-6:],
+        ]
+        self._save()
+        return True
+
+    def expand_file_mentions(self, text: str) -> str:
+        mentions = re.findall(r"(?<!\w)@([^\s]+)", text)
+        if not mentions:
+            return text
+        attachments: list[str] = []
+        for raw in mentions[:10]:
+            clean = raw.strip('"\'')
+            try:
+                path = self.workspace.resolve(clean)
+            except ValueError:
+                continue
+            if not path.is_file() or path.stat().st_size > 200_000:
+                continue
+            try:
+                content = path.read_text(encoding="utf-8")
+            except Exception:
+                continue
+            attachments.append(f"\n<file path=\"{self.workspace.relative(path)}\">\n{content}\n</file>")
+        if attachments:
+            return text + "\n\nArchivos adjuntos por @mención:\n" + "\n".join(attachments)
+        return text
+
+    def _chat_completion(self, **kwargs: Any) -> Any:
+        last_error: Exception | None = None
+        for attempt in range(1, self.config.api_retries + 1):
+            try:
+                response = self.client.chat.completions.create(**kwargs)
+                if not getattr(response, "choices", None):
+                    raise RuntimeError("LM Studio devolvió una respuesta sin choices")
+                return response
+            except Exception as exc:
+                last_error = exc
+                if attempt >= self.config.api_retries:
+                    break
+                delay = self.config.retry_backoff * (2 ** (attempt - 1))
+                console.print(
+                    f"[yellow]LM Studio falló ({type(exc).__name__}). "
+                    f"Reintento {attempt}/{self.config.api_retries}...[/yellow]"
+                )
+                time.sleep(delay)
+        raise RuntimeError(f"LM Studio no respondió después de {self.config.api_retries} intentos: {last_error}")
+
+    @staticmethod
+    def _parse_tool_arguments(raw: str | None) -> tuple[dict[str, Any], str | None]:
+        value = (raw or "{}").strip()
+        candidates = [value]
+        if value.startswith("```"):
+            stripped = re.sub(r"^```(?:json)?\s*|\s*```$", "", value, flags=re.IGNORECASE | re.DOTALL)
+            candidates.append(stripped)
+        first = value.find("{")
+        last = value.rfind("}")
+        if first >= 0 and last > first:
+            candidates.append(value[first : last + 1])
+        for candidate in candidates:
+            try:
+                parsed = json.loads(candidate)
+                if isinstance(parsed, dict):
+                    return parsed, None
+            except Exception:
+                pass
+            try:
+                parsed = ast.literal_eval(candidate)
+                if isinstance(parsed, dict):
+                    return parsed, None
+            except Exception:
+                pass
+        return {}, f"ERROR: argumentos JSON inválidos: {truncate(value, 1_000)}"
+
+    def verify_now(self, mode: VerificationMode | None = None, *, quiet: bool = False) -> DiagnosticReport:
+        selected = mode or self.config.verification_mode
+        if selected == "off":
+            report = DiagnosticReport(mode="off", detected=[], results=[], skipped_reason="verificación desactivada")
+        else:
+            report = self.toolbox.run_diagnostics_report(selected)
+        self.state.last_verification = report.to_text()
+        self._save()
+        if not quiet:
+            style = "green" if report.success else ("yellow" if not report.results or report.blocked else "red")
+            console.print(Panel(Text(report.to_text()), title="doctor", border_style=style))
+        return report
+
+    def doctor_report(self, mode: VerificationMode = "full") -> str:
+        checks: list[str] = []
+        checks.append(f"Python: {sys.version.split()[0]} ({sys.executable})")
+        checks.append(f"LM Studio URL: {self.config.base_url}")
+        checks.append(f"Modelo: {self.model or 'no seleccionado'}")
+        checks.append(f"Workspace: {self.workspace.root}")
+        checks.append(f"Git: {self.workspace.git_branch()}")
+        checks.append(f"Permisos: {self.config.permission_mode} / {self.config.approval_policy}")
+        report = self.verify_now(mode, quiet=True)
+        return "DIAGNÓSTICO DE LMCODING\n" + "\n".join(f"- {item}" for item in checks) + "\n\n" + report.to_text()
+
+    def ask(self, user_text: str, *, quiet: bool = False) -> str:
+        if not self.model:
+            raise RuntimeError("No hay modelo seleccionado")
+        if self.config.auto_compact:
+            self.compact(force=False)
+
+        expanded = self.expand_file_mentions(user_text)
+        self.state.messages.append({"role": "user", "content": expanded})
+        self._save()
+
+        task_checkpoint_start = len(self.toolbox.mutation_checkpoints)
+        repair_round = 0
+        repeat_counts: dict[str, int] = {}
+        last_tool_results: dict[str, str] = {}
+        final_content = ""
+
+        for step in range(1, self.config.max_steps + 1):
+            if not quiet:
+                status = console.status(
+                    f"[bold cyan]LMCoding trabajando · paso {step}/{self.config.max_steps}[/bold cyan]",
+                    spinner="dots",
+                )
+                status.start()
+            else:
+                status = None
+            try:
+                response = self._chat_completion(
+                    model=self.model,
+                    messages=self.state.messages,
+                    tools=self.toolbox.schemas,
+                    tool_choice="auto",
+                    temperature=self.config.temperature,
+                )
+            finally:
+                if status:
+                    status.stop()
+
+            usage = getattr(response, "usage", None)
+            if usage:
+                self.state.total_prompt_tokens += int(getattr(usage, "prompt_tokens", 0) or 0)
+                self.state.total_completion_tokens += int(getattr(usage, "completion_tokens", 0) or 0)
+
+            message = response.choices[0].message
+            tool_calls = message.tool_calls or []
+            assistant_message: dict[str, Any] = {
+                "role": "assistant",
+                "content": message.content or "",
+            }
+            if tool_calls:
+                assistant_message["tool_calls"] = [
+                    {
+                        "id": call.id,
+                        "type": "function",
+                        "function": {
+                            "name": call.function.name,
+                            "arguments": call.function.arguments,
+                        },
+                    }
+                    for call in tool_calls
+                ]
+            self.state.messages.append(assistant_message)
+            self._save()
+
+            if not tool_calls:
+                final_content = message.content or "(sin respuesta)"
+                has_new_mutations = len(self.toolbox.mutation_checkpoints) > task_checkpoint_start
+                should_verify = (
+                    self.config.self_heal
+                    and not self.state.plan_mode
+                    and self.config.verification_mode != "off"
+                    and has_new_mutations
+                )
+                if should_verify:
+                    report = self.verify_now(self.config.verification_mode, quiet=True)
+                    if report.success or not report.results:
+                        verification_note = "\n\n✅ " + report.to_text(limit=4_000)
+                        final_content += verification_note
+                    elif report.blocked:
+                        final_content += "\n\n⚠️ La verificación automática fue bloqueada por la política de permisos.\n" + report.to_text(limit=4_000)
+                    elif repair_round < self.config.max_fix_attempts:
+                        repair_round += 1
+                        self.state.repair_cycles += 1
+                        if not quiet:
+                            console.print(
+                                Panel(
+                                    Text(report.to_text(limit=8_000)),
+                                    title=f"[red]Autocorrección {repair_round}/{self.config.max_fix_attempts}[/red]",
+                                    border_style="red",
+                                )
+                            )
+                        self.state.messages.append(
+                            {
+                                "role": "user",
+                                "content": AUTO_REPAIR_PROMPT + "\n\n" + report.to_text(limit=16_000),
+                            }
+                        )
+                        self._save()
+                        continue
+                    else:
+                        failure_text = report.to_text(limit=8_000)
+                        if self.config.rollback_on_failure:
+                            rollback = self.toolbox.rollback_mutations(task_checkpoint_start)
+                            final_content += (
+                                "\n\n❌ No fue posible dejar el proyecto verificado después de "
+                                f"{repair_round} ciclos. Los cambios de esta tarea fueron revertidos.\n\n"
+                                + failure_text
+                                + "\n\nREVERSIÓN:\n"
+                                + rollback
+                            )
+                        else:
+                            final_content += (
+                                "\n\n❌ Persisten errores de verificación. Los cambios se conservaron porque rollback_on_failure=false.\n\n"
+                                + failure_text
+                            )
+
+                if not quiet:
+                    console.print(
+                        Panel(Markdown(final_content), title="[bold cyan]LMCoding[/bold cyan]", border_style="bright_magenta")
+                    )
+                self._save()
+                return final_content
+
+            loop_detected = False
+            for call in tool_calls:
+                tool_name = call.function.name
+                arguments, parse_error = self._parse_tool_arguments(call.function.arguments)
+                signature = tool_name + ":" + json.dumps(arguments, ensure_ascii=False, sort_keys=True)
+                repeat_counts[signature] = repeat_counts.get(signature, 0) + 1
+
+                if not quiet:
+                    self._print_tool_call(tool_name, arguments)
+
+                if repeat_counts[signature] > self.config.max_repeat_tool_calls:
+                    tool_result = (
+                        "BLOQUEADO: se detectó un bucle de herramienta. La misma llamada ya se repitió "
+                        f"{repeat_counts[signature] - 1} veces. Inspecciona nueva evidencia y cambia de estrategia."
+                    )
+                    loop_detected = True
+                else:
+                    tool_result = parse_error or self.toolbox.execute(tool_name, arguments)
+                    previous = last_tool_results.get(signature)
+                    if previous == tool_result and repeat_counts[signature] >= self.config.max_repeat_tool_calls:
+                        loop_detected = True
+                    last_tool_results[signature] = tool_result
+
+                if not quiet and self.config.show_tool_output:
+                    console.print(
+                        Panel(
+                            Text(truncate(tool_result, 6_000)),
+                            title="[dim]resultado[/dim]",
+                            border_style="dim",
+                        )
+                    )
+                self.state.messages.append(
+                    {"role": "tool", "tool_call_id": call.id, "content": tool_result}
+                )
+                self._save()
+
+            if loop_detected:
+                self.state.messages.append(
+                    {
+                        "role": "user",
+                        "content": (
+                            "Se detectó repetición improductiva. No repitas la misma llamada. "
+                            "Relee el error, inspecciona otros archivos o utiliza una estrategia distinta."
+                        ),
+                    }
+                )
+                self._save()
+
+        final_content = "Se alcanzó el máximo de pasos antes de completar y verificar la tarea."
+        if self.config.rollback_on_failure and len(self.toolbox.mutation_checkpoints) > task_checkpoint_start:
+            rollback = self.toolbox.rollback_mutations(task_checkpoint_start)
+            final_content += " Los cambios incompletos de esta tarea fueron revertidos.\n" + rollback
+        if not quiet:
+            console.print(f"[yellow]{final_content}[/yellow]")
+        return final_content
+
+    @staticmethod
+    def _print_tool_call(name: str, arguments: dict[str, Any]) -> None:
+        summary = json.dumps(arguments, ensure_ascii=False, indent=2)
+        console.print(
+            Panel(Text(truncate(summary, 4_000)), title=f"[magenta]› {name}[/magenta]", border_style="magenta")
+        )
+
+    def review(self) -> str:
+        diff = self.toolbox.git_diff()
+        prompt = REVIEW_PROMPT + "\n\nDiff actual:\n" + truncate(diff, 50_000)
+        return self.ask(prompt)
+
+    def status_table(self) -> Table:
+        table = Table(title=f"Estado de {COMMAND_BRAND}", show_header=False)
+        table.add_column("Campo", style="bright_magenta")
+        table.add_column("Valor")
+        table.add_row("Versión", APP_VERSION)
+        table.add_row("Modelo", self.model or "-")
+        table.add_row("Workspace", str(self.workspace.root))
+        table.add_row("Git", self.workspace.git_branch())
+        table.add_row("Permisos", f"{self.config.permission_mode} / {self.config.approval_policy}")
+        table.add_row("Modo plan", "sí" if self.state.plan_mode else "no")
+        table.add_row(
+            "Autocorrección",
+            f"{'sí' if self.config.self_heal else 'no'} / {self.config.verification_mode} / intentos {self.config.max_fix_attempts}",
+        )
+        table.add_row("Sesión", f"{self.state.name} ({self.state.id[:8]})")
+        table.add_row("Contexto estimado", f"{self.estimate_context_chars():,} caracteres")
+        table.add_row(
+            "Tokens reportados",
+            f"entrada {self.state.total_prompt_tokens:,} / salida {self.state.total_completion_tokens:,}",
+        )
+        table.add_row("Último checkpoint", self.state.last_checkpoint or "-")
+        table.add_row("Última verificación", truncate(self.state.last_verification or "-", 140))
+        table.add_row("Ciclos de reparación", str(self.state.repair_cycles))
+        return table
+
+
+class InteractiveApp:
+    def __init__(self, agent: LMCodingAgent) -> None:
+        self.agent = agent
+        ensure_home()
+        bindings = KeyBindings()
+
+        @bindings.add("escape", "enter")
+        def submit_multiline(event: Any) -> None:
+            event.current_buffer.validate_and_handle()
+
+        self.prompt = PromptSession(
+            history=FileHistory(str(HISTORY_FILE)),
+            completer=SlashCompleter(),
+            complete_while_typing=True,
+            multiline=True,
+            key_bindings=bindings,
+            bottom_toolbar=self._toolbar,
+        )
+
+    def _toolbar(self) -> HTML:
+        branch = self.agent.workspace.git_branch()
+        mode = self.agent.config.permission_mode
+        plan = " PLAN" if self.agent.state.plan_mode else ""
+        heal = f" HEAL:{self.agent.config.verification_mode}" if self.agent.config.self_heal else " HEAL:off"
+        return HTML(
+            f" <b>{COMMAND_BRAND}</b> {APP_VERSION} | {self.agent.model} | {branch} | {mode}{plan}{heal} "
+            "| Esc+Enter enviar · Enter nueva línea "
+        )
+
+    def run(self) -> int:
+        self.print_banner()
+        while True:
+            try:
+                text = self.prompt.prompt(HTML("<ansimagenta><b>›</b></ansimagenta> ")).strip()
+            except (EOFError, KeyboardInterrupt):
+                console.print("\n[dim]Sesión guardada. Cerrando LMCoding.[/dim]")
+                return 0
+            if not text:
+                continue
+            if text.startswith("/"):
+                if self.handle_command(text):
+                    return 0
+                continue
+            if text.startswith("!"):
+                result = self.agent.toolbox.run_command(text[1:].strip())
+                console.print(Panel(Text(result), title="shell", border_style="yellow"))
+                continue
+            try:
+                self.agent.ask(text)
+            except KeyboardInterrupt:
+                console.print("\n[yellow]Tarea cancelada.[/yellow]")
+            except Exception as exc:
+                console.print(Panel(f"{type(exc).__name__}: {exc}", title="[red]Error[/red]", border_style="red"))
+
+    def print_banner(self) -> None:
+        text = Text()
+        text.append(COMMAND_BRAND, style="bold bright_magenta")
+        text.append(f"  v{APP_VERSION}\n", style="dim")
+        text.append("  · motor LMCoding\n", style="dim")
+        text.append("Agente local autocorrectivo para LM Studio\n")
+        text.append(f"modelo: {self.agent.model}\n", style="green")
+        text.append(f"workspace: {self.agent.workspace.root}\n", style="yellow")
+        text.append("Escribe /help para comandos. Usa @archivo para adjuntarlo.", style="dim")
+        console.print(Panel(text, border_style="bright_magenta"))
+
+    def handle_command(self, text: str) -> bool:
+        command, _, argument = text.partition(" ")
+        command = command.lower()
+        argument = argument.strip()
+
+        if command in {"/exit", "/quit"}:
+            self.agent._save()
+            return True
+        if command == "/help":
+            self.print_help()
+        elif command == "/status":
+            console.print(self.agent.status_table())
+        elif command == "/models":
+            self.print_models()
+        elif command == "/model":
+            self.change_model(argument)
+        elif command == "/permissions":
+            self.change_permissions(argument)
+        elif command == "/plan":
+            self.toggle_plan(argument)
+        elif command == "/review":
+            self.agent.review()
+        elif command == "/doctor":
+            console.print(Panel(Text(self.agent.doctor_report("full")), title="doctor", border_style="bright_magenta"))
+        elif command == "/verify":
+            selected: VerificationMode = "full" if argument.lower() == "full" else "quick"
+            self.agent.verify_now(selected)
+        elif command == "/autofix":
+            value = argument.lower()
+            if value in {"off", "0", "false", "no"}:
+                self.agent.config.self_heal = False
+            else:
+                self.agent.config.self_heal = True
+                if value in {"quick", "full"}:
+                    self.agent.config.verification_mode = value  # type: ignore[assignment]
+            console.print(
+                f"[green]Autocorrección: {'activada' if self.agent.config.self_heal else 'desactivada'} "
+                f"({self.agent.config.verification_mode})[/green]"
+            )
+        elif command == "/diff":
+            console.print(Panel(Text(self.agent.toolbox.git_diff()), title="git diff", border_style="blue"))
+        elif command == "/undo":
+            checkpoint = argument or self.agent.state.last_checkpoint
+            result = self.agent.workspace.undo(checkpoint)
+            console.print(Panel(Text(result), title="undo", border_style="yellow"))
+        elif command == "/compact":
+            changed = self.agent.compact(force=True)
+            console.print("[green]Contexto compactado.[/green]" if changed else "[dim]No fue necesario compactar.[/dim]")
+        elif command == "/new":
+            self.agent.new_conversation()
+            console.print(f"[green]Nueva sesión: {self.agent.state.id[:8]}[/green]")
+        elif command == "/save":
+            self.agent._save()
+            console.print("[green]Sesión guardada.[/green]")
+        elif command == "/rename":
+            if not argument:
+                argument = Prompt.ask("Nombre de la sesión").strip()
+            self.agent.state.name = argument
+            self.agent._save()
+            console.print(f"[green]Sesión renombrada: {argument}[/green]")
+        elif command == "/sessions":
+            self.print_sessions()
+        elif command == "/resume":
+            self.resume_session(argument)
+        elif command == "/clear":
+            console.clear()
+            self.print_banner()
+        else:
+            console.print(f"[red]Comando desconocido: {command}[/red]")
+        return False
+
+    @staticmethod
+    def print_help() -> None:
+        table = Table(title="Comandos")
+        table.add_column("Comando", style="bright_magenta")
+        table.add_column("Función")
+        rows = [
+            ("/status", "modelo, permisos, Git, tokens y sesión"),
+            ("/permissions [read-only|workspace-write|full-access]", "cambiar autonomía"),
+            ("/model [ID]", "seleccionar modelo"),
+            ("/models", "listar modelos"),
+            ("/plan [on|off]", "modo de planificación sin cambios"),
+            ("/review", "revisión del árbol de trabajo"),
+            ("/doctor", "diagnóstico completo del entorno y proyecto"),
+            ("/verify [quick|full]", "ejecutar validadores detectados"),
+            ("/autofix [on|off|quick|full]", "controlar autocorrección"),
+            ("/diff", "mostrar git diff"),
+            ("/undo [checkpoint]", "restaurar cambios del agente"),
+            ("/compact", "resumir historial antiguo"),
+            ("/new", "crear conversación nueva"),
+            ("/sessions", "listar sesiones guardadas"),
+            ("/resume ID", "reanudar una sesión"),
+            ("/rename NOMBRE", "renombrar sesión"),
+            ("!comando", "ejecutar shell con la política actual"),
+            ("@ruta", "adjuntar un archivo al mensaje"),
+            ("/exit", "guardar y salir"),
+        ]
+        for row in rows:
+            table.add_row(*row)
+        console.print(table)
+
+    def print_models(self) -> None:
+        table = Table(title="Modelos de LM Studio")
+        table.add_column("ID")
+        table.add_column("Activo")
+        for model in self.agent.available_models:
+            table.add_row(model, "✓" if model == self.agent.model else "")
+        console.print(table)
+
+    def change_model(self, argument: str) -> None:
+        if not argument:
+            self.print_models()
+            argument = Prompt.ask("ID del modelo").strip()
+        if argument:
+            self.agent.set_model(argument)
+            console.print(f"[green]Modelo activo: {argument}[/green]")
+
+    def change_permissions(self, argument: str) -> None:
+        aliases = {"auto": "workspace-write", "readonly": "read-only", "full": "full-access"}
+        value = aliases.get(argument.lower(), argument.lower()) if argument else ""
+        if value not in {"read-only", "workspace-write", "full-access"}:
+            table = Table(title="Permisos")
+            table.add_column("Modo")
+            table.add_column("Comportamiento")
+            table.add_row("read-only", "inspecciona; pide permiso para cambiar o ejecutar")
+            table.add_row("workspace-write", "edita dentro del proyecto; pregunta por red o riesgo")
+            table.add_row("full-access", "acceso amplio y sin confirmaciones")
+            console.print(table)
+            value = Prompt.ask(
+                "Modo",
+                choices=["read-only", "workspace-write", "full-access"],
+                default=self.agent.config.permission_mode,
+            )
+        if value == "full-access":
+            confirmed = Confirm.ask(
+                "[red]Full access permite comandos y archivos fuera del proyecto sin confirmación. ¿Continuar?[/red]",
+                default=False,
+            )
+            if not confirmed:
+                console.print("[yellow]Cambio cancelado.[/yellow]")
+                return
+        self.agent.set_permissions(value)  # type: ignore[arg-type]
+        console.print(
+            f"[green]Permisos: {self.agent.config.permission_mode} / "
+            f"{self.agent.config.approval_policy}[/green]"
+        )
+
+    def toggle_plan(self, argument: str) -> None:
+        if argument.lower() in {"on", "1", "true", "si", "sí"}:
+            enabled = True
+        elif argument.lower() in {"off", "0", "false", "no"}:
+            enabled = False
+        else:
+            enabled = not self.agent.state.plan_mode
+        self.agent.set_plan_mode(enabled)
+        console.print(f"[green]Modo plan: {'activado' if enabled else 'desactivado'}[/green]")
+
+    def print_sessions(self) -> None:
+        states = self.agent.store.list_states(self.agent.workspace.root)
+        table = Table(title="Sesiones")
+        table.add_column("ID")
+        table.add_column("Nombre")
+        table.add_column("Actualizada")
+        table.add_column("Modelo")
+        for state in states[:30]:
+            table.add_row(state.id[:8], state.name, state.updated_at[:19], state.model or "-")
+        console.print(table)
+
+    def resume_session(self, argument: str) -> None:
+        if not argument:
+            self.print_sessions()
+            argument = Prompt.ask("ID o nombre").strip()
+        try:
+            state = self.agent.store.load(argument)
+        except Exception as exc:
+            console.print(f"[red]{exc}[/red]")
+            return
+        if Path(state.workspace).resolve() != self.agent.workspace.root:
+            console.print("[red]La sesión pertenece a otro workspace.[/red]")
+            return
+        self.agent.resume(state)
+        console.print(f"[green]Sesión reanudada: {state.name} ({state.id[:8]})[/green]")
+
+
+def cli_values_from_args(args: argparse.Namespace) -> dict[str, Any]:
+    return {
+        "base_url": getattr(args, "base_url", None),
+        "api_key": getattr(args, "api_key", None),
+        "model": getattr(args, "model", None),
+        "permission_mode": getattr(args, "permission_mode", None),
+        "approval_policy": getattr(args, "approval_policy", None),
+        "max_steps": getattr(args, "max_steps", None),
+        "temperature": getattr(args, "temperature", None),
+        "self_heal": getattr(args, "self_heal", None),
+        "verification_mode": getattr(args, "verification_mode", None),
+        "max_fix_attempts": getattr(args, "max_fix_attempts", None),
+        "rollback_on_failure": getattr(args, "rollback_on_failure", None),
+        "api_retries": getattr(args, "api_retries", None),
+        "save_sessions": False if getattr(args, "no_save", False) else None,
+    }
+
+
+def add_common_flags(parser: argparse.ArgumentParser, *, suppress_defaults: bool = False) -> None:
+    missing = argparse.SUPPRESS if suppress_defaults else None
+    parser.add_argument(
+        "-C", "--cd", "--workspace", dest="workspace",
+        default=argparse.SUPPRESS if suppress_defaults else ".",
+    )
+    parser.add_argument(
+        "--base-url",
+        default=argparse.SUPPRESS if suppress_defaults else os.getenv("LMSTUDIO_BASE_URL"),
+    )
+    parser.add_argument(
+        "--api-key",
+        default=argparse.SUPPRESS if suppress_defaults else os.getenv("LMSTUDIO_API_KEY"),
+    )
+    parser.add_argument(
+        "-m", "--model",
+        default=argparse.SUPPRESS if suppress_defaults else os.getenv("LMSTUDIO_MODEL"),
+    )
+    parser.add_argument(
+        "-s",
+        "--sandbox",
+        dest="permission_mode",
+        choices=["read-only", "workspace-write", "full-access"],
+        default=missing,
+    )
+    parser.add_argument(
+        "-a",
+        "--ask-for-approval",
+        dest="approval_policy",
+        choices=["untrusted", "on-request", "never"],
+        default=missing,
+    )
+    parser.add_argument("--max-steps", type=int, default=missing)
+    parser.add_argument("--temperature", type=float, default=missing)
+    parser.add_argument(
+        "--self-heal",
+        action=argparse.BooleanOptionalAction,
+        default=missing,
+        help="activar/desactivar diagnóstico, reparación y verificación automáticos",
+    )
+    parser.add_argument(
+        "--verification",
+        dest="verification_mode",
+        choices=["off", "quick", "full"],
+        default=missing,
+    )
+    parser.add_argument("--fix-attempts", dest="max_fix_attempts", type=int, default=missing)
+    parser.add_argument(
+        "--rollback-on-failure",
+        action=argparse.BooleanOptionalAction,
+        default=missing,
+        help="revertir cambios de la tarea si no superan las verificaciones",
+    )
+    parser.add_argument("--api-retries", type=int, default=missing)
+    parser.add_argument("--no-save", action="store_true", default=missing)
+    parser.add_argument(
+        "--full-auto",
+        action="store_true",
+        default=missing,
+        help="workspace-write + on-request (modo recomendado)",
+    )
+    parser.add_argument(
+        "--dangerously-bypass-approvals-and-sandbox",
+        action="store_true",
+        default=missing,
+        help="full-access + never; úsalo solo en entornos confiables",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog=(Path(sys.argv[0]).stem or "llmCodex"),
+        description="Agente de programación local avanzado para LM Studio",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {APP_VERSION}")
+    subparsers = parser.add_subparsers(dest="subcommand")
+
+    interactive = subparsers.add_parser("interactive", help="abrir interfaz interactiva")
+    add_common_flags(interactive, suppress_defaults=True)
+
+    execute = subparsers.add_parser("exec", help="ejecutar una tarea no interactiva")
+    execute.add_argument("prompt", nargs="?", help="tarea; si se omite, lee stdin")
+    execute.add_argument("--output", help="guardar respuesta final en un archivo")
+    execute.add_argument("--json", action="store_true", help="imprimir resultado JSON")
+    add_common_flags(execute, suppress_defaults=True)
+
+    resume = subparsers.add_parser("resume", help="reanudar una sesión")
+    resume.add_argument("session", nargs="?")
+    resume.add_argument("--last", action="store_true")
+    add_common_flags(resume, suppress_defaults=True)
+
+    doctor = subparsers.add_parser("doctor", help="diagnosticar entorno y proyecto")
+    doctor.add_argument("--mode", choices=["quick", "full"], default="full")
+    add_common_flags(doctor, suppress_defaults=True)
+
+    verify = subparsers.add_parser("verify", help="ejecutar verificaciones sin pedir una corrección al modelo")
+    verify.add_argument("--mode", choices=["quick", "full"], default="quick")
+    add_common_flags(verify, suppress_defaults=True)
+
+    fix = subparsers.add_parser("fix", help="detectar, corregir y verificar errores automáticamente")
+    fix.add_argument("prompt", nargs="?", default="Detecta y corrige todos los errores reproducibles del proyecto. Ejecuta diagnóstico completo y no termines hasta verificar los cambios.")
+    fix.add_argument("--output")
+    fix.add_argument("--json", action="store_true")
+    add_common_flags(fix, suppress_defaults=True)
+
+    sessions = subparsers.add_parser("sessions", help="listar sesiones guardadas")
+    sessions.add_argument("-C", "--cd", "--workspace", dest="workspace")
+
+    delete = subparsers.add_parser("delete", help="eliminar una sesión guardada")
+    delete.add_argument("session")
+    delete.add_argument("--force", action="store_true")
+
+    # Permite ejecutar sin escribir 'interactive'.
+    add_common_flags(parser)
+    return parser
+
+
+def normalize_args(args: argparse.Namespace) -> argparse.Namespace:
+    if getattr(args, "full_auto", False):
+        args.permission_mode = "workspace-write"
+        args.approval_policy = "on-request"
+    if getattr(args, "dangerously_bypass_approvals_and_sandbox", False):
+        args.permission_mode = "full-access"
+        args.approval_policy = "never"
+    return args
+
+
+def create_agent(args: argparse.Namespace, state: SessionState | None = None, *, connect: bool = True) -> LMCodingAgent:
+    workspace_path = Path(getattr(args, "workspace", ".") or ".").expanduser().resolve()
+    config = AppConfig.from_layers(workspace_path, cli_values_from_args(args))
+    workspace = Workspace(workspace_path, config)
+    agent = LMCodingAgent(workspace, config, state=state)
+    if connect:
+        agent.connect()
+    return agent
+
+
+def print_connection_error(exc: Exception, base_url: str | None = None) -> None:
+    url = base_url or DEFAULT_BASE_URL
+    console.print(
+        Panel(
+            f"{exc}\n\n"
+            "En LM Studio:\n"
+            "1. Carga un modelo con tool use.\n"
+            "2. Abre Developer.\n"
+            "3. Pulsa Start Server.\n\n"
+            f"URL esperada: {url}",
+            title="[red]No se pudo conectar[/red]",
+            border_style="red",
+        )
+    )
+
+
+
+def command_doctor(args: argparse.Namespace) -> int:
+    agent = create_agent(args, connect=False)
+    connection_note = "LM Studio: conectado"
+    try:
+        agent.connect()
+    except Exception as exc:
+        connection_note = f"LM Studio: no disponible ({type(exc).__name__}: {exc})"
+    result = connection_note + "\n\n" + agent.doctor_report(args.mode)
+    console.print(Panel(Text(result), title=f"{COMMAND_BRAND} Doctor", border_style="bright_magenta"))
+    report = agent.toolbox.last_diagnostic_report
+    return 0 if report is None or report.success or not report.results else 1
+
+
+def command_verify(args: argparse.Namespace) -> int:
+    agent = create_agent(args, connect=False)
+    report = agent.verify_now(args.mode, quiet=True)
+    print(report.to_text())
+    if report.blocked:
+        return 2
+    return 0 if report.success or not report.results else 1
+
+
+def command_fix(args: argparse.Namespace) -> int:
+    args.self_heal = True
+    args.verification_mode = "full"
+    if getattr(args, "max_fix_attempts", None) is None:
+        args.max_fix_attempts = 5
+    try:
+        agent = create_agent(args)
+        result = agent.ask(args.prompt, quiet=True)
+    except Exception as exc:
+        print_connection_error(exc, getattr(args, "base_url", None))
+        return 1
+    if args.output:
+        Path(args.output).write_text(result, encoding="utf-8")
+    if args.json:
+        print(json.dumps({
+            "session_id": agent.state.id,
+            "model": agent.model,
+            "result": result,
+            "verification": agent.state.last_verification,
+            "repair_cycles": agent.state.repair_cycles,
+        }, ensure_ascii=False))
+    else:
+        print(result)
+    report = agent.toolbox.last_diagnostic_report
+    return 0 if report is None or report.success or not report.results else 1
+
+def command_sessions(args: argparse.Namespace) -> int:
+    store = SessionStore()
+    workspace = Path(args.workspace).expanduser().resolve() if args.workspace else None
+    states = store.list_states(workspace)
+    table = Table(title="Sesiones LMCoding")
+    table.add_column("ID")
+    table.add_column("Nombre")
+    table.add_column("Workspace")
+    table.add_column("Actualizada")
+    table.add_column("Modelo")
+    for state in states:
+        table.add_row(state.id[:8], state.name, state.workspace, state.updated_at[:19], state.model or "-")
+    console.print(table)
+    return 0
+
+
+def command_delete(args: argparse.Namespace) -> int:
+    store = SessionStore()
+    try:
+        state = store.load(args.session)
+    except Exception as exc:
+        console.print(f"[red]{exc}[/red]")
+        return 1
+    if not args.force and not Confirm.ask(f"¿Eliminar la sesión '{state.name}'?", default=False):
+        return 1
+    store.delete(state.id)
+    console.print("[green]Sesión eliminada.[/green]")
+    return 0
+
+
+def command_exec(args: argparse.Namespace) -> int:
+    prompt = args.prompt
+    if not prompt:
+        prompt = sys.stdin.read().strip()
+    if not prompt:
+        console.print("[red]Falta una tarea.[/red]")
+        return 2
+    try:
+        agent = create_agent(args)
+        result = agent.ask(prompt, quiet=True)
+    except Exception as exc:
+        print_connection_error(exc, getattr(args, "base_url", None))
+        return 1
+
+    if args.output:
+        Path(args.output).write_text(result, encoding="utf-8")
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "session_id": agent.state.id,
+                    "model": agent.model,
+                    "result": result,
+                    "prompt_tokens": agent.state.total_prompt_tokens,
+                    "completion_tokens": agent.state.total_completion_tokens,
+                },
+                ensure_ascii=False,
+            )
+        )
+    else:
+        print(result)
+    return 0
+
+
+def command_resume(args: argparse.Namespace) -> int:
+    workspace = Path(args.workspace).expanduser().resolve()
+    store = SessionStore()
+    try:
+        state = store.latest(workspace) if args.last or not args.session else store.load(args.session)
+        if Path(state.workspace).resolve() != workspace:
+            console.print("[red]La sesión pertenece a otro workspace.[/red]")
+            return 1
+        agent = create_agent(args, state=state)
+    except Exception as exc:
+        print_connection_error(exc, getattr(args, "base_url", None))
+        return 1
+    return InteractiveApp(agent).run()
+
+
+def main() -> int:
+    ensure_home()
+    parser = build_parser()
+    args = normalize_args(parser.parse_args())
+
+    if args.subcommand == "doctor":
+        return command_doctor(args)
+    if args.subcommand == "verify":
+        return command_verify(args)
+    if args.subcommand == "fix":
+        return command_fix(args)
+    if args.subcommand == "sessions":
+        return command_sessions(args)
+    if args.subcommand == "delete":
+        return command_delete(args)
+    if args.subcommand == "exec":
+        return command_exec(args)
+    if args.subcommand == "resume":
+        return command_resume(args)
+
+    try:
+        agent = create_agent(args)
+    except Exception as exc:
+        print_connection_error(exc, getattr(args, "base_url", None))
+        return 1
+    return InteractiveApp(agent).run()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())