tweek 0.4.1__py3-none-any.whl → 0.4.3__py3-none-any.whl

tweek/cli_install.py

@@ -36,6 +36,112 @@ from tweek.cli_helpers import (
 )
 
 
+# ---------------------------------------------------------------------------
+# Installed scope tracking
+# ---------------------------------------------------------------------------
+
+_INSTALLED_SCOPES_FILE = Path("~/.tweek/installed_scopes.json").expanduser()
+
+
+def _record_installed_scope(target: Path) -> None:
+    """Record that hooks were installed at *target* (.claude/ directory).
+
+    Stored in ~/.tweek/installed_scopes.json so ``tweek uninstall --all``
+    can find and clean project-level hooks regardless of the user's cwd.
+    """
+    target_str = str(target.resolve())
+
+    existing: list = []
+    if _INSTALLED_SCOPES_FILE.exists():
+        try:
+            existing = json.loads(_INSTALLED_SCOPES_FILE.read_text()) or []
+        except (json.JSONDecodeError, IOError):
+            existing = []
+
+    if target_str not in existing:
+        existing.append(target_str)
+
+    _INSTALLED_SCOPES_FILE.parent.mkdir(parents=True, exist_ok=True)
+    _INSTALLED_SCOPES_FILE.write_text(json.dumps(existing, indent=2))
+
+
+def _get_installed_scopes() -> list:
+    """Return all recorded .claude/ directories where hooks were installed."""
+    if not _INSTALLED_SCOPES_FILE.exists():
+        return []
+    try:
+        return json.loads(_INSTALLED_SCOPES_FILE.read_text()) or []
+    except (json.JSONDecodeError, IOError):
+        return []
+
+
+# ---------------------------------------------------------------------------
+# Hook wrapper deployment
+# ---------------------------------------------------------------------------
+
+_TWEEK_HOOKS_DIR = Path("~/.tweek/hooks").expanduser()
+
+
+def _deploy_hook_wrappers() -> Path:
+    """Deploy self-healing hook wrappers to ~/.tweek/hooks/.
+
+    These wrappers are standalone Python scripts that delegate to the real
+    hook implementations in the tweek package. If the tweek package has been
+    removed (e.g. via ``pip uninstall``), the wrappers silently remove
+    themselves from settings.json and allow the tool call.
+
+    Returns:
+        Path to the hooks directory (~/.tweek/hooks/).
+    """
+    _TWEEK_HOOKS_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Source wrappers live alongside the real hooks in the package
+    wrapper_src_dir = Path(__file__).resolve().parent / "hooks"
+
+    for wrapper_name in ("wrapper_pre_tool_use.py", "wrapper_post_tool_use.py"):
+        src = wrapper_src_dir / wrapper_name
+        # Deploy as the canonical name (without "wrapper_" prefix)
+        dest_name = wrapper_name.replace("wrapper_", "")
+        dest = _TWEEK_HOOKS_DIR / dest_name
+
+        if not src.exists():
+            raise FileNotFoundError(
+                f"Hook wrapper template not found: {src}\n"
+                f"Re-install tweek to restore missing files."
+            )
+
+        shutil.copy2(src, dest)
+
+    return _TWEEK_HOOKS_DIR
+
+
+def _deploy_uninstall_script() -> Path:
+    """Deploy the standalone uninstall.sh to ~/.tweek/.
+
+    This shell script can clean up all Tweek state (hooks, skills, config,
+    .tweek.yaml files, MCP integrations, and the pip package) even when
+    the tweek Python package has already been removed.
+
+    Returns:
+        Path to the deployed uninstall.sh.
+    """
+    tweek_dir = Path("~/.tweek").expanduser()
+    tweek_dir.mkdir(parents=True, exist_ok=True)
+
+    src = Path(__file__).resolve().parent / "scripts" / "uninstall.sh"
+    dest = tweek_dir / "uninstall.sh"
+
+    if src.exists():
+        shutil.copy2(src, dest)
+        # Ensure executable
+        dest.chmod(dest.stat().st_mode | 0o111)
+    else:
+        # If source not found, skip gracefully
+        pass
+
+    return dest
+
+
 # ---------------------------------------------------------------------------
 # Utility functions for .env scanning
 # ---------------------------------------------------------------------------
@@ -125,11 +231,77 @@ def parse_env_keys(env_path: Path) -> List[str]:
 # ---------------------------------------------------------------------------
 
 
+def _ensure_local_model_deps() -> bool:
+    """Install onnxruntime, tokenizers, numpy if missing.
+
+    Tries pip first, then uv pip (for uv-managed venvs that lack pip).
+
+    Returns True if deps are available after this call.
+    """
+    try:
+        import onnxruntime  # noqa: F401
+        import tokenizers  # noqa: F401
+        import numpy  # noqa: F401
+        return True
+    except ImportError:
+        pass
+
+    import subprocess
+    import shutil
+
+    deps = ["onnxruntime>=1.16.0", "tokenizers>=0.15.0", "numpy>=1.24.0"]
+    console.print("\n[bold cyan]Installing classifier dependencies[/bold cyan]")
+    console.print("  [white]onnxruntime, tokenizers, numpy[/white]")
+    console.print()
+
+    # Method 1: Try pip (works for pip/pipx installs)
+    try:
+        result = subprocess.run(
+            [sys.executable, "-m", "pip", "install", *deps],
+            capture_output=True,
+            text=True,
+            timeout=300,
+        )
+        if result.returncode == 0:
+            console.print("[green]\u2713[/green] Classifier dependencies installed")
+            return True
+    except Exception:
+        pass
+
+    # Method 2: Try uv pip (works for uv tool installs where pip is absent)
+    uv_cmd = shutil.which("uv")
+    if uv_cmd:
+        console.print("  [white]pip not available in this environment, trying uv...[/white]")
+        try:
+            result = subprocess.run(
+                [uv_cmd, "pip", "install", "--python", sys.executable, *deps],
+                capture_output=True,
+                text=True,
+                timeout=300,
+            )
+            if result.returncode == 0:
+                console.print("[green]\u2713[/green] Classifier dependencies installed (via uv)")
+                return True
+            else:
+                console.print(f"[yellow]\u26a0[/yellow] uv pip install failed: {result.stderr.strip()[:200]}")
+        except Exception as e:
+            console.print(f"[yellow]\u26a0[/yellow] uv pip install failed: {e}")
+
+    console.print("[yellow]\u26a0[/yellow] Could not install classifier dependencies automatically")
+    console.print("  [white]Install manually:[/white]")
+    if uv_cmd:
+        console.print(f"    uv pip install --python {sys.executable} tweek[local-models]")
+    else:
+        console.print("    pip install tweek[local-models]")
+    return False
+
+
 def _download_local_model(quick: bool) -> bool:
-    """Download the local classifier model if dependencies are available.
+    """Download the local classifier model, installing deps if needed.
 
     Called during ``tweek install`` to ensure the on-device prompt-injection
-    classifier is ready to use immediately after installation.
+    classifier is ready to use immediately after installation. Dependencies
+    are installed automatically if missing.
 
     Args:
         quick: If True, skip informational output and just download.
@@ -139,7 +311,6 @@ def _download_local_model(quick: bool) -> bool:
         successfully), False otherwise.
     """
     try:
-        from tweek.security.local_model import LOCAL_MODEL_AVAILABLE
         from tweek.security.model_registry import (
             ModelDownloadError,
             download_model,
@@ -152,37 +323,55 @@ def _download_local_model(quick: bool) -> bool:
             console.print("\n[white]Local model module not available — skipping model download[/white]")
         return False
 
+    console.print("\n[bold cyan]Local Classifier Setup[/bold cyan]")
+    console.print("  [white]The on-device classifier detects prompt injection without any API key.[/white]")
+    console.print()
+
+    # Step A: Ensure deps are installed
+    console.print("  [bold]1/2 Dependencies[/bold]")
+    deps_available = _ensure_local_model_deps()
+    if not deps_available:
+        return False
+
+    # Re-import after potential install
+    try:
+        from tweek.security.local_model import LOCAL_MODEL_AVAILABLE
+    except ImportError:
+        return False
+
     if not LOCAL_MODEL_AVAILABLE:
         if not quick:
-            console.print("\n[white]Local model dependencies not installed (optional)[/white]")
-            console.print("  [white]Install with: pip install tweek[local-models][/white]")
+            console.print("  [yellow]\u26a0[/yellow] Dependencies installed but not functional — restart may be needed")
         return False
 
+    # Step B: Download model
+    console.print()
+    console.print("  [bold]2/2 Model Download[/bold]")
+
     default_name = get_default_model_name()
 
     if is_model_installed(default_name):
-        console.print(f"\n[green]\u2713[/green] Local classifier model already installed ({default_name})")
+        console.print(f"  [green]\u2713[/green] Already installed ({default_name})")
         return True
 
     definition = get_model_definition(default_name)
     if definition is None:
         return False
 
-    if not quick:
-        console.print(f"\n[bold]Downloading local classifier model[/bold]")
-        console.print(f"  Model:   {definition.display_name}")
-        console.print(f"  Size:    ~{definition.size_mb:.0f} MB")
-        console.print(f"  License: {definition.license}")
-        console.print(f"  [white]This enables on-device prompt injection detection (no API key needed)[/white]")
-        console.print()
+    console.print(f"  Model:   {definition.display_name}")
+    console.print(f"  Size:    ~{definition.size_mb:.0f} MB")
+    console.print(f"  License: {definition.license}")
+    console.print()
 
-    from rich.progress import Progress, BarColumn, DownloadColumn, TransferSpeedColumn
+    from rich.progress import Progress, BarColumn, DownloadColumn, TransferSpeedColumn, TimeRemainingColumn
 
     progress = Progress(
         "[progress.description]{task.description}",
         BarColumn(),
+        "[progress.percentage]{task.percentage:>3.0f}%",
         DownloadColumn(),
         TransferSpeedColumn(),
+        TimeRemainingColumn(),
         console=console,
     )
 
@@ -199,16 +388,16 @@ def _download_local_model(quick: bool) -> bool:
         with progress:
             download_model(default_name, progress_callback=progress_callback)
 
-        console.print(f"[green]\u2713[/green] Local classifier model downloaded ({default_name})")
+        console.print(f"  [green]\u2713[/green] Classifier model ready ({default_name})")
         return True
 
     except ModelDownloadError as e:
-        console.print(f"\n[yellow]\u26a0[/yellow] Could not download local model: {e}")
-        console.print("  [white]You can download it later with: tweek model download[/white]")
+        console.print(f"\n  [yellow]\u26a0[/yellow] Could not download model: {e}")
+        console.print("    [white]Download later with: tweek model download[/white]")
         return False
     except Exception as e:
-        console.print(f"\n[yellow]\u26a0[/yellow] Model download failed: {e}")
-        console.print("  [white]You can download it later with: tweek model download[/white]")
+        console.print(f"\n  [yellow]\u26a0[/yellow] Model download failed: {e}")
+        console.print("    [white]Download later with: tweek model download[/white]")
         return False
 
 
@@ -253,6 +442,12 @@ def _install_claude_code_hooks(install_global: bool, dev_test: bool, backup: boo
         "proxy": False,
     }
 
+    # ═══════════════════════════════════════════════════════════════
+    # PHASE 1: Environment Detection
+    # ═══════════════════════════════════════════════════════════════
+    console.print("[bold cyan]Phase 1/4: Environment Detection[/bold cyan]")
+    console.print()
+
     # ─────────────────────────────────────────────────────────────
     # Step 1: Detect Claude Code CLI
     # ─────────────────────────────────────────────────────────────
@@ -416,11 +611,39 @@ def _install_claude_code_hooks(install_global: bool, dev_test: bool, backup: boo
         except Exception as e:
             console.print(f"[white]Warning: Could not check for proxy conflicts: {e}[/white]")
 
+    # ═══════════════════════════════════════════════════════════════
+    # PHASE 2: Hook & Skill Installation
+    # ═══════════════════════════════════════════════════════════════
+    console.print()
+    console.print("[bold cyan]Phase 2/4: Hook & Skill Installation[/bold cyan]")
+    console.print()
+
     # ─────────────────────────────────────────────────────────────
     # Step 5: Install hooks into settings.json
     # ─────────────────────────────────────────────────────────────
-    hook_script = Path(__file__).resolve().parent / "hooks" / "pre_tool_use.py"
-    post_hook_script = Path(__file__).resolve().parent / "hooks" / "post_tool_use.py"
+
+    # Create Tweek data directory first (needed for hook deployment)
+    tweek_dir = Path("~/.tweek").expanduser()
+    tweek_dir.mkdir(parents=True, exist_ok=True)
+
+    # Deploy self-healing hook wrappers to ~/.tweek/hooks/
+    # These survive `pip uninstall tweek` and auto-clean settings.json
+    # if the tweek package is no longer available.
+    try:
+        hooks_dir = _deploy_hook_wrappers()
+        console.print(f"[green]\u2713[/green] Self-healing hooks deployed to: {hooks_dir}")
+    except FileNotFoundError as e:
+        console.print(f"[red]\u2717[/red] {e}")
+        return
+
+    # Deploy standalone uninstall script
+    uninstall_path = _deploy_uninstall_script()
+    if uninstall_path.exists():
+        console.print(f"[green]\u2713[/green] Standalone uninstall: {uninstall_path}")
+
+    # Hook paths now point to the deployed wrappers, not the package
+    hook_script = hooks_dir / "pre_tool_use.py"
+    post_hook_script = hooks_dir / "post_tool_use.py"
 
     # Backup existing hooks if requested
     if backup and target.exists():
@@ -460,7 +683,7 @@ def _install_claude_code_hooks(install_global: bool, dev_test: bool, backup: boo
             "hooks": [
                 {
                     "type": "command",
-                    "command": f"{python_exe} {hook_script.resolve()}"
+                    "command": f"{python_exe} {hook_script}"
                 }
             ]
         }
@@ -474,7 +697,7 @@ def _install_claude_code_hooks(install_global: bool, dev_test: bool, backup: boo
             "hooks": [
                 {
                     "type": "command",
-                    "command": f"{python_exe} {post_hook_script.resolve()}"
+                    "command": f"{python_exe} {post_hook_script}"
                 }
             ]
         }
@@ -486,9 +709,9 @@ def _install_claude_code_hooks(install_global: bool, dev_test: bool, backup: boo
     console.print(f"\n[green]\u2713[/green] PreToolUse hooks installed to: {target}")
     console.print(f"[green]\u2713[/green] PostToolUse content screening installed to: {target}")
 
-    # Create Tweek data directory
-    tweek_dir = Path("~/.tweek").expanduser()
-    tweek_dir.mkdir(parents=True, exist_ok=True)
+    # Track this installation scope so `tweek uninstall --all` can find it
+    _record_installed_scope(target)
+
     console.print(f"[green]\u2713[/green] Tweek data directory: {tweek_dir}")
 
     # Create .tweek.yaml in the install directory (per-directory hook control)
@@ -558,6 +781,12 @@ def _install_claude_code_hooks(install_global: bool, dev_test: bool, backup: boo
         console.print(f"[white]Tweek skill source not found \u2014 skill not installed[/white]")
         console.print(f"  [white]Skill can be installed manually from the tweek repository[/white]")
 
+    # ═══════════════════════════════════════════════════════════════
+    # PHASE 3: Classifier & Security
+    # ═══════════════════════════════════════════════════════════════
+    console.print()
+    console.print("[bold cyan]Phase 3/4: Classifier & Security Configuration[/bold cyan]")
+
     # ─────────────────────────────────────────────────────────────
     # Step 7: Download local classifier model
     # ─────────────────────────────────────────────────────────────
@@ -642,11 +871,21 @@ def _install_claude_code_hooks(install_global: bool, dev_test: bool, backup: boo
         # Full interactive configuration
         console.print("\n[bold]Security Configuration[/bold]")
         console.print("Choose how to configure security settings:\n")
-        console.print("  [cyan]1.[/cyan] Paranoid  - Maximum security, prompt on everything")
-        console.print("  [cyan]2.[/cyan] Balanced  - Smart defaults with provenance tracking [green](recommended)[/green]")
-        console.print("  [cyan]3.[/cyan] Cautious  - Prompt on risky operations")
-        console.print("  [cyan]4.[/cyan] Trusted   - Minimal prompts")
-        console.print("  [cyan]5.[/cyan] Custom    - Configure individually")
+        console.print("  [cyan]1.[/cyan] Paranoid")
+        console.print("     [white]Block everything suspicious. Manual approval required.[/white]")
+        console.print("     [dim]Best for: production systems, sensitive codebases[/dim]")
+        console.print("  [cyan]2.[/cyan] Balanced [green](recommended)[/green]")
+        console.print("     [white]Smart defaults with provenance tracking. Clean sessions[/white]")
+        console.print("     [white]get fewer prompts; tainted sessions get extra scrutiny.[/white]")
+        console.print("     [dim]Best for: most development workflows[/dim]")
+        console.print("  [cyan]3.[/cyan] Cautious")
+        console.print("     [white]Block high-risk actions, warn on medium-risk.[/white]")
+        console.print("     [dim]Best for: teams with mixed trust levels[/dim]")
+        console.print("  [cyan]4.[/cyan] Trusted")
+        console.print("     [white]Monitor only, never block. Logging still active.[/white]")
+        console.print("     [dim]Best for: air-gapped systems, solo trusted projects[/dim]")
+        console.print("  [cyan]5.[/cyan] Custom")
+        console.print("     [white]Configure tool and skill tiers individually.[/white]")
         console.print()
 
         choice = click.prompt("Select", type=click.IntRange(1, 5), default=2)
@@ -831,50 +1070,62 @@ def _install_claude_code_hooks(install_global: bool, dev_test: bool, backup: boo
         except Exception as e:
             console.print(f"\n[yellow]Warning: Could not save proxy config: {e}[/yellow]")
 
+    # ═══════════════════════════════════════════════════════════════
+    # PHASE 4: Verification & Summary
+    # ═══════════════════════════════════════════════════════════════
+    console.print()
+    console.print("[bold cyan]Phase 4/4: Verification & Summary[/bold cyan]")
+    console.print()
+
     # ─────────────────────────────────────────────────────────────
     # Step 13: Post-install verification and summary
     # ─────────────────────────────────────────────────────────────
     _print_install_summary(install_summary, target, tweek_dir, proxy_override_enabled)
 
     # ─────────────────────────────────────────────────────────────
-    # Step 14: Scan for other AI tools and offer protection
+    # Step 14: Detect all AI tools and offer protection
     # ─────────────────────────────────────────────────────────────
     if not quick:
-        _offer_mcp_protection()
+        unprotected = _detect_and_show_tools()
+        if unprotected:
+            _offer_tool_protection(unprotected)
 
 
 
-def _offer_mcp_protection() -> None:
-    """Scan for installed MCP-capable AI tools and offer to protect them.
-
-    Detects Claude Desktop, Gemini CLI, and ChatGPT Desktop. For each tool
-    that is installed but not yet protected, prompts the user to add Tweek
-    as an MCP server.
-    """
-    from tweek.cli_protect import _protect_mcp_client
-
-    # MCP client tool IDs to scan for (exclude claude-code and openclaw —
-    # those are handled by their own install paths)
-    mcp_tool_ids = {"claude-desktop", "chatgpt", "gemini"}
-
+def _detect_and_show_tools() -> list:
+    """Detect all AI tools and display status. Returns unprotected tools."""
     try:
         all_tools = _detect_all_tools()
     except Exception:
-        return
+        return []
+
+    console.print("\n[bold]Detected AI Tools[/bold]")
+    for tool_id, label, installed, protected, detail in all_tools:
+        if installed and protected:
+            console.print(f"  [green]\u2713[/green] {label:<20} [green]protected[/green]")
+        elif installed:
+            console.print(f"  [yellow]\u25cb[/yellow] {label:<20} [yellow]not configured[/yellow]")
+        else:
+            console.print(f"  [dim]\u2717 {label:<20} not found[/dim]")
+    console.print()
 
-    unprotected = [
-        (tool_id, label)
-        for tool_id, label, installed, protected, _detail in all_tools
-        if tool_id in mcp_tool_ids and installed and not protected
-    ]
+    return [t for t in all_tools if t[2] and not t[3]]
 
-    if not unprotected:
-        return
 
-    console.print("\n[bold]Other AI tools detected[/bold]")
-    console.print("Tweek can also protect these tools via MCP server integration:\n")
+def _offer_tool_protection(unprotected_tools: list) -> None:
+    """Offer to protect each unprotected MCP-based AI tool."""
+    from tweek.cli_protect import _protect_mcp_client
+
+    mcp_tool_ids = {"claude-desktop", "chatgpt", "gemini"}
+    mcp_unprotected = [
+        (tid, lbl) for tid, lbl, *_ in unprotected_tools if tid in mcp_tool_ids
+    ]
+    if not mcp_unprotected:
+        return
 
-    for tool_id, label in unprotected:
+    console.print("[bold]Configure MCP protection for other tools?[/bold]")
+    console.print("Tweek can protect these via MCP server integration:\n")
+    for tool_id, label in mcp_unprotected:
         if click.confirm(f"  Protect {label}?", default=True):
             try:
                 _protect_mcp_client(tool_id)
@@ -882,10 +1133,16 @@ def _offer_mcp_protection() -> None:
                 console.print(f"  [yellow]Could not configure {label}: {e}[/yellow]")
         else:
             console.print(f"  [dim]Skipped {label}[/dim]")
-
     console.print()
 
 
+def _offer_mcp_protection() -> None:
+    """Legacy wrapper: detect + offer protection for MCP tools."""
+    unprotected = _detect_and_show_tools()
+    if unprotected:
+        _offer_tool_protection(unprotected)
+
+
 def _create_tweek_yaml(install_global: bool) -> None:
     """Create .tweek.yaml in the project directory with hooks enabled.
 
@@ -1160,12 +1417,17 @@ def _warn_no_llm_provider(quick: bool) -> None:
 
 
 def _detect_llm_provider():
-    """Detect which LLM provider is available based on environment.
+    """Detect which LLM provider is available based on environment and SDK.
 
-    Priority: Local ONNX model > Anthropic > OpenAI > Google.
+    Priority: Local ONNX model > Google > OpenAI > xAI > Anthropic.
     Returns dict with 'name' and 'model', or None if none available.
+
+    Both the API key AND the SDK must be available for cloud providers.
+    This aligns with the doctor's detection logic to avoid contradictions
+    where install says a provider is configured but doctor says it isn't.
     """
     import os
+    from importlib import import_module
 
     # Check local ONNX model first (no API key needed)
     try:
@@ -1179,18 +1441,24 @@ def _detect_llm_provider():
     except ImportError:
         pass
 
-    # Cloud providers — Google first (free tier), then others (pay-per-token)
+    # Cloud providers — check both API key AND SDK importability
+    # sdk_module is the Python package that must be importable
     checks = [
-        ("GOOGLE_API_KEY", "Google", "gemini-2.0-flash"),
-        ("GEMINI_API_KEY", "Google", "gemini-2.0-flash"),
-        ("OPENAI_API_KEY", "OpenAI", "gpt-4o-mini"),
-        ("XAI_API_KEY", "xAI (Grok)", "grok-2"),
-        ("ANTHROPIC_API_KEY", "Anthropic", "claude-3-5-haiku-latest"),
+        ("GOOGLE_API_KEY", "Google", "gemini-2.0-flash", "google.generativeai"),
+        ("GEMINI_API_KEY", "Google", "gemini-2.0-flash", "google.generativeai"),
+        ("OPENAI_API_KEY", "OpenAI", "gpt-4o-mini", "openai"),
+        ("XAI_API_KEY", "xAI (Grok)", "grok-2", "openai"),
+        ("ANTHROPIC_API_KEY", "Anthropic", "claude-3-5-haiku-latest", "anthropic"),
     ]
 
-    for env_var, name, model in checks:
+    for env_var, name, model, sdk_module in checks:
         if os.environ.get(env_var):
-            return {"name": name, "model": model, "env_var": env_var}
+            try:
+                import_module(sdk_module)
+                return {"name": name, "model": model, "env_var": env_var}
+            except ImportError:
+                # Key exists but SDK not installed — skip this provider
+                continue
 
     return None
 
@@ -1291,6 +1559,10 @@ def _validate_llm_provider(llm_config: dict) -> None:
                     console.print(f"  [yellow]\u26a0[/yellow] Could not store in vault: {e}")
                     console.print(f"  [white]Set {key_name} in your shell profile instead.[/white]")
 
+    # Validate the key actually works with a lightweight API call
+    if found_key:
+        _validate_api_key(provider, llm_config)
+
     if not found_key:
         console.print(f"  [white]LLM review will be disabled until a key is available.[/white]")
 
@@ -1314,6 +1586,42 @@ def _validate_llm_provider(llm_config: dict) -> None:
                 console.print(f"  [white]No API keys found \u2014 LLM review will be disabled[/white]")
 
 
+def _validate_api_key(provider: str, llm_config: dict) -> None:
+    """Make a lightweight API call to verify the key works.
+
+    This catches invalid/expired keys during install rather than at runtime.
+    On failure, warns but does not block — the key might work later.
+    """
+    console.print("  [white]Validating API key...[/white]", end="")
+    try:
+        if provider == "google":
+            import google.generativeai as genai
+            key = os.environ.get("GOOGLE_API_KEY") or os.environ.get("GEMINI_API_KEY", "")
+            genai.configure(api_key=key)
+            list(genai.list_models())
+            console.print(f"\r  [green]\u2713[/green] API key validated                 ")
+        elif provider == "openai":
+            import openai
+            client = openai.OpenAI(timeout=5.0)
+            client.models.list()
+            console.print(f"\r  [green]\u2713[/green] API key validated                 ")
+        elif provider == "anthropic":
+            import anthropic
+            client = anthropic.Anthropic(timeout=5.0)
+            client.messages.create(
+                model="claude-3-5-haiku-latest",
+                max_tokens=1,
+                messages=[{"role": "user", "content": "hi"}],
+            )
+            console.print(f"\r  [green]\u2713[/green] API key validated                 ")
+        else:
+            console.print(f"\r  [white]\u25cb[/white] Validation skipped (unknown provider)")
+    except Exception as e:
+        err_msg = str(e)[:100]
+        console.print(f"\r  [yellow]\u26a0[/yellow] Could not validate key: {err_msg}")
+        console.print("  [white]Tweek will retry at runtime. Key may still work.[/white]")
+
+
 def _print_install_summary(
     summary: dict,
     target: Path,
@@ -1542,10 +1850,18 @@ def install(scope, preset, quick, backup, skip_env_scan, interactive, ai_default
     # Step 2: Security preset
     console.print("[bold cyan]Step 2/5: Security Preset[/bold cyan]")
     if preset is None:
-        console.print("  [cyan]1.[/cyan] paranoid  \u2014 Block everything suspicious, prompt on risky")
-        console.print("  [cyan]2.[/cyan] balanced  \u2014 Smart defaults with provenance tracking [white](recommended)[/white]")
-        console.print("  [cyan]3.[/cyan] cautious  \u2014 Block dangerous, prompt on risky")
-        console.print("  [cyan]4.[/cyan] trusted   \u2014 Allow most operations, block only dangerous")
+        console.print("  [cyan]1.[/cyan] paranoid")
+        console.print("     [white]Block everything suspicious. Manual approval required.[/white]")
+        console.print("     [dim]Best for: production systems, sensitive codebases[/dim]")
+        console.print("  [cyan]2.[/cyan] balanced [white](recommended)[/white]")
+        console.print("     [white]Smart defaults with provenance tracking.[/white]")
+        console.print("     [dim]Best for: most development workflows[/dim]")
+        console.print("  [cyan]3.[/cyan] cautious")
+        console.print("     [white]Block high-risk, warn on medium-risk.[/white]")
+        console.print("     [dim]Best for: teams with mixed trust levels[/dim]")
+        console.print("  [cyan]4.[/cyan] trusted")
+        console.print("     [white]Monitor only, never block. Logging still active.[/white]")
+        console.print("     [dim]Best for: air-gapped systems, solo projects[/dim]")
         console.print()
 
         preset_choice = click.prompt(
@@ -1607,7 +1923,12 @@ def install(scope, preset, quick, backup, skip_env_scan, interactive, ai_default
 
 
 def _quickstart_install_hooks(scope: str) -> None:
-    """Install hooks for quickstart wizard (simplified version)."""
+    """Install hooks for quickstart wizard (simplified version).
+
+    Uses the same self-healing wrapper deployment as the main install flow.
+    Hook wrappers are deployed to ~/.tweek/hooks/ and referenced from
+    settings.json — they survive ``pip uninstall tweek``.
+    """
     import json
 
     if scope == "global":
@@ -1615,8 +1936,15 @@ def _quickstart_install_hooks(scope: str) -> None:
     else:
         target_dir = Path.cwd() / ".claude"
 
-    hooks_dir = target_dir / "hooks"
-    hooks_dir.mkdir(parents=True, exist_ok=True)
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    # Deploy self-healing hook wrappers to ~/.tweek/hooks/
+    hooks_dir = _deploy_hook_wrappers()
+    _deploy_uninstall_script()
+
+    python_exe = sys.executable
+    pre_hook_path = hooks_dir / "pre_tool_use.py"
+    post_hook_path = hooks_dir / "post_tool_use.py"
 
     settings_path = target_dir / "settings.json"
     settings = {}
@@ -1630,37 +1958,43 @@ def _quickstart_install_hooks(scope: str) -> None:
     if "hooks" not in settings:
         settings["hooks"] = {}
 
-    pre_hook_entry = {
-        "type": "command",
-        "command": "tweek hook pre-tool-use $TOOL_NAME",
-    }
-    post_hook_entry = {
-        "type": "command",
-        "command": "tweek hook post-tool-use $TOOL_NAME",
-    }
-
-    hook_entries = {
-        "PreToolUse": pre_hook_entry,
-        "PostToolUse": post_hook_entry,
-    }
-
+    # Remove any existing tweek hooks (clean install)
     for hook_type in ["PreToolUse", "PostToolUse"]:
-        if hook_type not in settings["hooks"]:
-            settings["hooks"][hook_type] = []
-
-        # Check if tweek hooks already present
-        already_installed = False
-        for hook_config in settings["hooks"][hook_type]:
-            for h in hook_config.get("hooks", []):
-                if "tweek" in h.get("command", "").lower():
-                    already_installed = True
-                    break
-
-        if not already_installed:
-            settings["hooks"][hook_type].append({
-                "matcher": "",
-                "hooks": [hook_entries[hook_type]],
-            })
+        if hook_type in settings["hooks"]:
+            settings["hooks"][hook_type] = [
+                hc for hc in settings["hooks"][hook_type]
+                if not any(
+                    "tweek" in h.get("command", "").lower()
+                    for h in hc.get("hooks", [])
+                )
+            ]
+
+    # Install hooks pointing to deployed wrappers
+    settings["hooks"]["PreToolUse"] = settings["hooks"].get("PreToolUse", []) + [
+        {
+            "matcher": "Bash|Write|Edit|Read|WebFetch|NotebookEdit|WebSearch",
+            "hooks": [
+                {
+                    "type": "command",
+                    "command": f"{python_exe} {pre_hook_path}",
+                }
+            ],
+        }
+    ]
+    settings["hooks"]["PostToolUse"] = settings["hooks"].get("PostToolUse", []) + [
+        {
+            "matcher": "Read|WebFetch|Bash|Grep|WebSearch",
+            "hooks": [
+                {
+                    "type": "command",
+                    "command": f"{python_exe} {post_hook_path}",
+                }
+            ],
+        }
+    ]
 
     with open(settings_path, "w") as f:
         json.dump(settings, f, indent=2)
+
+    # Track this installation scope
+    _record_installed_scope(target_dir)