@allansantos-dev/smart-tool 0.9.31 → 0.9.33

package/model_upgrade.py

@@ -0,0 +1,140 @@
+"""Tells who updated that this version recommends other models than the ones the config holds, and applies them only on
+consent. `model_defaults.ensure_recommended_models` fills empty fields only, so a user who updated keeps the previous
+version's defaults forever; this module is the visible, reversible way out.
+
+State lives in `config.json` under `defaults_notice`, tied to DEFAULTS_VERSION: pending (announced once a day until the
+user answers), declined (silent for this version), applied (the replaced models are kept for `revert`). Raising
+DEFAULTS_VERSION when RECOMMENDED_MODELS changes starts a new notice for everyone. Embedding and rerank are never
+offered: changing them invalidates every index.
+"""
+import secrets
+import time
+
+import config
+import model_catalog
+import model_defaults
+
+DEFAULTS_VERSION = 2
+ROLES = ("router_model", "scope_model", "scout_model", "research_model")
+REMIND_EVERY_S = 24 * 3600
+
+
+def _current(cfg):
+    """The notice of this defaults version, or a blank one."""
+    notice = cfg.get("defaults_notice") or {}
+    return notice if notice.get("version") == DEFAULTS_VERSION else {"version": DEFAULTS_VERSION, "state": "none"}
+
+
+def _differences(cfg, chat):
+    """{role: {"current", "new"}} for each role the user has set to something other than the recommended model that
+    this gateway's catalog has."""
+    found = {}
+    for role in ROLES:
+        wanted = model_defaults._matching(chat, model_defaults.RECOMMENDED_MODELS[role][1])
+        if wanted and cfg.get(role) and cfg[role] != wanted:
+            found[role] = {"current": cfg[role], "new": wanted}
+    return found
+
+
+def check():
+    """Recomputes what is on offer against the gateway catalog and stores it. Raises when the catalog is unreachable
+    (the caller shows that; no answer is invented). Returns `status()`."""
+    cfg = config.load_config()
+    notice = _current(cfg)
+    if notice["state"] in ("declined", "applied"):
+        return status()
+    found = _differences(cfg, set(model_catalog.list_models("chat")))
+
+    def store(current):
+        notice = dict(_current(current))
+        if not found:
+            notice.update(state="none", changes={}, nonce="")
+        else:
+            notice.update(state="pending", changes=found, nonce=notice.get("nonce") or secrets.token_hex(8))
+        current["defaults_notice"] = notice
+
+    config.update_config(store)
+    return status()
+
+
+def status(cfg=None):
+    """What the setup screen and the tray read: state, the model changes on offer, and what `revert` would restore."""
+    notice = _current(cfg if cfg is not None else config.load_config())
+    return {"version": DEFAULTS_VERSION, "state": notice["state"], "changes": notice.get("changes") or {},
+            "previous": notice.get("previous") or {}, "nonce": notice.get("nonce", "")}
+
+
+def _change(mutate_notice, nonce):
+    """Runs `mutate_notice(cfg, notice)` under the config lock on a pending notice; `nonce` None (the setup screen,
+    which has its own token) skips the link check, a toast button must carry the nonce it was shown with."""
+    result = {}
+
+    def apply(cfg):
+        notice = dict(_current(cfg))
+        if notice["state"] != "pending":
+            raise ValueError(f"No new default models are waiting (state: {notice['state']}).")
+        if nonce is not None and not secrets.compare_digest(str(nonce), str(notice.get("nonce", ""))):
+            raise ValueError("This notification is out of date; open the settings to see the current offer.")
+        result["text"] = mutate_notice(cfg, notice)
+        cfg["defaults_notice"] = notice
+
+    config.update_config(apply)
+    return result["text"]
+
+
+def apply(nonce=None):
+    """Switches the offered roles to the recommended models and keeps the previous ones for `revert`."""
+    def mutate(cfg, notice):
+        # A role the user changed since the offer was made is theirs: it is skipped, never overwritten.
+        todo = {role: change for role, change in notice["changes"].items() if cfg.get(role) == change["current"]}
+        if not todo:
+            raise ValueError("The offered roles were changed since the notice; open the settings to see the current state.")
+        notice["previous"] = {role: change["current"] for role, change in todo.items()}
+        for role, change in todo.items():
+            cfg[role] = change["new"]
+        notice.update(state="applied", applied_at=time.time())
+        return "applied: " + ", ".join(f"{role} {change['current']} -> {change['new']}" for role, change in todo.items())
+    return _change(mutate, nonce)
+
+
+def decline(nonce=None):
+    """Stops announcing this defaults version; the user's models stay as they are."""
+    def mutate(cfg, notice):
+        notice["state"] = "declined"
+        return "declined: no more notices for this version of the defaults"
+    return _change(mutate, nonce)
+
+
+def revert():
+    """Puts back the models `apply` replaced. Raises when nothing was applied."""
+    done = {}
+
+    def put_back(cfg):
+        notice = dict(_current(cfg))
+        if notice["state"] != "applied" or not notice.get("previous"):
+            raise ValueError("Nothing to revert: the recommended models were not applied.")
+        for role, model in notice["previous"].items():
+            cfg[role] = model
+        done["text"] = "reverted: " + ", ".join(f"{role} -> {model}" for role, model in notice["previous"].items())
+        notice.update(state="declined", previous={})
+        cfg["defaults_notice"] = notice
+
+    config.update_config(put_back)
+    return done["text"]
+
+
+def due(now=None):
+    """The offer the tray should announce now (pending and not announced in the last 24 h), or None. Marks it
+    announced, so a second call in the same day returns None; closing the toast without choosing brings it back."""
+    now = now or time.time()
+    taken = {}
+
+    def mark(cfg):
+        notice = dict(_current(cfg))
+        if notice["state"] == "pending" and notice.get("changes") and now - notice.get("last_notified", 0) >= REMIND_EVERY_S:
+            notice["last_notified"] = now
+            cfg["defaults_notice"] = notice
+            taken["offer"] = {"changes": notice["changes"], "nonce": notice["nonce"]}
+
+    config.update_config(mark)
+    return taken.get("offer")

package/notice_action.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""Runs a toast button: `pythonw notice_action.py "smart-tool-action:<action>?<query>"`.
+
+Started by Windows through the protocol registered in `toast_notice.register`, with no window. Every outcome (done or
+refused) is appended to `notice-actions.log` in the data folder, because nothing else can show an error here.
+"""
+import os
+import sys
+import time
+import urllib.parse
+import webbrowser
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import model_upgrade
+import paths
+import toast_notice
+
+LOG_PATH = os.path.join(paths.DATA_DIR, "notice-actions.log")
+
+
+def run(uri):
+    """Returns a short result line. Raises ValueError for a link that is not ours or an action that does not exist."""
+    prefix = toast_notice.PROTOCOL + ":"
+    if not uri.startswith(prefix):
+        raise ValueError(f"Not a Smart Tool link: {uri[:80]!r}")
+    action, _, query = uri[len(prefix):].partition("?")
+    params = dict(urllib.parse.parse_qsl(query))
+    if action == "models-apply":
+        return model_upgrade.apply(params.get("n", ""))
+    if action == "models-decline":
+        return model_upgrade.decline(params.get("n", ""))
+    if action == "open-setup":
+        import daemon_launcher
+        webbrowser.open(daemon_launcher.ensure_daemon_running().rstrip("/") + "/setup#" + params.get("section", "models"))
+        return "setup opened"
+    if action == "mute-model":
+        import model_health
+        return model_health.mute(params.get("model", ""))
+    raise ValueError(f"Unknown action {action!r}")
+
+
+def main(argv):
+    """Runs the link in `argv[1]` and logs the outcome; returns the process exit code (0 done, 1 refused)."""
+    os.makedirs(os.path.dirname(LOG_PATH), exist_ok=True)
+    stamp = time.strftime("%Y-%m-%d %H:%M:%S")
+    try:
+        line = f"{stamp} ok {argv[1] if len(argv) > 1 else ''} -> {run(argv[1])}"
+        code = 0
+    except Exception as exc:
+        line = f"{stamp} FAIL {argv[1] if len(argv) > 1 else ''} -> {type(exc).__name__}: {exc}"
+        code = 1
+    with open(LOG_PATH, "a", encoding="utf-8") as log:
+        log.write(line + "\n")
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allansantos-dev/smart-tool",
-  "version": "0.9.31",
+  "version": "0.9.33",
   "description": "Local MCP server that gives coding agents (Claude Code, Codex) cheaper, sharper tools than their built-in search. Windows.",
   "license": "Apache-2.0",
   "author": "Allan Santos",

package/setup_audit.py

@@ -11,6 +11,7 @@ Usage: python setup_audit.py [--project DIR] [--no-probe] [--json]
 """
 import argparse
 import concurrent.futures
+import glob
 import hashlib
 import json
 import os
@@ -41,18 +42,22 @@ PROBE_MAX_AGE_S = 6 * 3600
 SKILL_DESCRIPTION_MAX = 1536
 SKILL_BUDGET_CHARS = 8000
 CODEX_PROJECT_DOC_MAX = 32 * 1024
+SMART_TOOL_SERVER = "smart-tool"
 CLAUDE_TOOLS = ("Bash", "Read", "Grep", "Glob", "LS", "Edit", "MultiEdit", "Write", "NotebookEdit", "WebFetch",
                 "WebSearch", "Task")
 CODEX_TOOLS = ("Bash", "apply_patch")
 DECIDING_EVENTS = ("PreToolUse",)
 DOCS = {"claude_hooks": "https://code.claude.com/docs/en/hooks.md", "codex_hooks": "https://learn.chatgpt.com/docs/hooks.md",
         "claude_skills": "https://code.claude.com/docs/en/skills.md",
+        "claude_subagents": "https://code.claude.com/docs/en/sub-agents",
         "codex_skills": "https://learn.chatgpt.com/docs/build-skills.md",
         "claude_memory": "https://code.claude.com/docs/en/memory.md",
         "codex_agents_md": "https://developers.openai.com/codex/guides/agents-md",
         "claude_mcp": "https://code.claude.com/docs/en/mcp.md", "mcp_lifecycle":
         "https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle"}
 _SCRIPT_RE = re.compile(r"""["']?([^\s"'|&;<>]+\.(?:js|cjs|mjs|py|ps1|sh|bat|cmd|exe))["']?""", re.IGNORECASE)
+# The quoted program text after -e / -c / -p / -Command / --eval: code, not a file the hook runs.
+_INLINE_CODE_RE = re.compile(r"""\s(?:-e|-c|-p|-Command|--eval)\s+(?:"(?:[^"\\]|\\.)*"|'[^']*')""", re.IGNORECASE)
 _SILENCED_RE = re.compile(r"\|\|\s*(?:true|exit\s+0)\b|2>\s*(?:/dev/null|nul)\b|;\s*exit\s+0\s*$", re.IGNORECASE)
 _IMPORT_RE = re.compile(r"(?<![\w`])@((?:~|\.{1,2})?/?[\w.\-/\\]+\.\w+)")
 
@@ -204,6 +209,20 @@ def _approvals(data, approval):
     approval["off"].update(data.get("disabledMcpjsonServers") or [])
 
 
+def _agents(snapshot, folder, scope):
+    """Subagent definitions (*.md with frontmatter) in folder: name, scope, path and `tools` (None when the field is
+    absent, which makes the agent inherit every tool, MCP included)."""
+    found = []
+    for path in sorted(glob.glob(os.path.join(folder, "*.md"))):
+        meta = _frontmatter(snapshot.read(path))
+        tools = meta.get("tools")
+        if isinstance(tools, str):
+            tools = [item.strip() for item in tools.split(",") if item.strip()]
+        found.append({"name": str(meta.get("name") or os.path.basename(path)[:-3]), "scope": scope, "path": path,
+                      "tools": [str(item) for item in tools] if isinstance(tools, list) else None})
+    return found
+
+
 def collect_claude(project, snapshot):
     """Claude Code's effective set for project: settings layers, enabled plugins, hooks, MCP, skills, CLAUDE.md."""
     layers = [(path, "managed") for path in _managed_settings()] + [
@@ -234,6 +253,8 @@ def collect_claude(project, snapshot):
     mcp += [e for e in shared if e["name"] not in unapproved]
     skills = _skills(snapshot, os.path.join(endpoint_sync.claude_dir(), "skills"), "user", disabled=disabled_skills)
     skills += _skills(snapshot, os.path.join(project, ".claude", "skills"), "project", disabled=disabled_skills)
+    agents = _agents(snapshot, os.path.join(endpoint_sync.claude_dir(), "agents"), "user")
+    agents += _agents(snapshot, os.path.join(project, ".claude", "agents"), "project")
     plugins = []
     installed = snapshot.json(os.path.join(endpoint_sync.claude_dir(), "plugins", "installed_plugins.json")) or {}
     for plugin_id, installs in (installed.get("plugins") or {}).items():
@@ -261,10 +282,64 @@ def collect_claude(project, snapshot):
         text = snapshot.read(path)
         if text is not None:
             instructions.append({"path": path, "kind": kind, "bytes": len(text.encode("utf-8")), "_text": text})
-    return {"settings": settings, "plugins": plugins, "hooks": hooks, "mcp": mcp, "skills": skills,
+    return {"settings": settings, "plugins": plugins, "hooks": hooks, "mcp": mcp, "skills": skills, "agents": agents,
             "instructions": instructions, "unapproved_mcp": unapproved}
 
 
+def _codex_plugin_root(market, name):
+    """Newest installed version folder of a Codex plugin (`plugins/cache/<marketplace>/<name>/<version>/`), skipping
+    the `latest` alias unless it is all there is; None when the plugin is not in the cache."""
+    base = os.path.join(codex_dir(), "plugins", "cache", market, name)
+    if not os.path.isdir(base):
+        return None
+    versions = [os.path.join(base, entry) for entry in os.listdir(base) if os.path.isdir(os.path.join(base, entry))]
+    real = [path for path in versions if os.path.basename(path) != "latest"]
+    return max(real or versions, key=os.path.getmtime) if versions else None
+
+
+def _codex_plugin_path(manifest, key, root, defaults):
+    """Path a Codex plugin manifest names for `key` (relative to the plugin root), else the first default that exists."""
+    named = manifest.get(key)
+    if isinstance(named, str):
+        return os.path.join(root, named)
+    return next((os.path.join(root, d) for d in defaults if os.path.exists(os.path.join(root, d))), None)
+
+
+def _collect_codex_plugins(config, snapshot):
+    """Skills, hooks and MCP servers of the Codex plugins enabled in config.toml (`[plugins."<name>@<marketplace>"]`
+    unless `enabled = false`), read from the plugin cache: manifest `.codex-plugin/plugin.json`, `skills/`,
+    `hooks/hooks.json`, `.mcp.json`. A plugin whose folder or manifest is missing is reported as not verified."""
+    plugins, hooks, mcp, skills = [], [], [], []
+    for plugin_id, options in (config.get("plugins") or {}).items():
+        if isinstance(options, dict) and options.get("enabled") is False:
+            continue
+        name, _, market = plugin_id.rpartition("@")
+        root = _codex_plugin_root(market, name) if name else None
+        if not root:
+            snapshot.unverified.append(f"Codex plugin {plugin_id}: not found under {os.path.join(codex_dir(), 'plugins', 'cache')}")
+            continue
+        manifest_path = next((p for p in (os.path.join(root, ".codex-plugin", "plugin.json"),
+                                          os.path.join(root, "plugin.json")) if os.path.exists(p)), None)
+        manifest = snapshot.json(manifest_path) if manifest_path else None
+        if manifest is None:
+            snapshot.unverified.append(f"Codex plugin {plugin_id}: no readable manifest (.codex-plugin/plugin.json) in {root}")
+            continue
+        plugins.append({"id": plugin_id, "path": root})
+        hook_file = _codex_plugin_path(manifest, "hooks", root, (os.path.join("hooks", "hooks.json"),))
+        hooks += _hooks_from(snapshot.json(hook_file) if hook_file else None, f"plugin:{name}", root)
+        mcp_file = _codex_plugin_path(manifest, "mcpServers", root, (".mcp.json", "mcp.json"))
+        plugin_mcp = snapshot.json(mcp_file) if mcp_file else None
+        if plugin_mcp is None and isinstance(manifest.get("mcpServers"), dict):
+            plugin_mcp = manifest["mcpServers"]
+        plugin_mcp = plugin_mcp or {}
+        mcp += _mcp_entries(plugin_mcp.get("mcpServers", plugin_mcp), f"plugin:{name}", mcp_file or manifest_path,
+                            f"plugin:{name}:", {"PLUGIN_ROOT": root})
+        skill_dir = _codex_plugin_path(manifest, "skills", root, ("skills",))
+        skills += [{**s, "name": f"{name}:{s['name']}"} for s in
+                   _skills(snapshot, skill_dir, f"plugin:{name}", recursive=True)] if skill_dir else []
+    return plugins, hooks, mcp, skills
+
+
 def collect_codex(project, snapshot):
     """Codex's effective set for project: config.toml (MCP, hooks), hooks.json, skills, AGENTS.md chain."""
     config = snapshot.toml(os.path.join(codex_dir(), "config.toml")) or {}
@@ -274,6 +349,10 @@ def collect_codex(project, snapshot):
     skills = _skills(snapshot, os.path.join(codex_dir(), "skills"), "user", recursive=True)
     skills += _skills(snapshot, _home(".agents", "skills"), "user-agents")
     skills += _skills(snapshot, os.path.join(project, ".agents", "skills"), "project")
+    plugins, plugin_hooks, plugin_mcp, plugin_skills = _collect_codex_plugins(config, snapshot)
+    hooks += plugin_hooks
+    mcp += plugin_mcp
+    skills += plugin_skills
     instructions = []
     for name in ("AGENTS.override.md", "AGENTS.md"):
         text = snapshot.read(os.path.join(codex_dir(), name))
@@ -292,8 +371,7 @@ def collect_codex(project, snapshot):
                 instructions.append({"path": os.path.join(folder, name), "kind": "project",
                                      "bytes": len(text.encode("utf-8")), "_text": text})
                 break
-    return {"hooks": hooks, "mcp": mcp, "skills": skills, "instructions": instructions,
-            "plugins_unverified": bool(config.get("plugins"))}
+    return {"plugins": plugins, "hooks": hooks, "mcp": mcp, "skills": skills, "instructions": instructions}
 
 
 def _finding(check, severity, harness, subject, detail, source, evidence=()):
@@ -336,8 +414,9 @@ def check_hook_overlap(harness, hooks, tools):
 
 
 def _expand(token, root):
-    """A hook script path with ${CLAUDE_PLUGIN_ROOT}, ~ and environment variables expanded."""
-    token = token.replace("${CLAUDE_PLUGIN_ROOT}", root or "${CLAUDE_PLUGIN_ROOT}")
+    """A hook script path with ${CLAUDE_PLUGIN_ROOT} / ${PLUGIN_ROOT}, ~ and environment variables expanded."""
+    for variable in ("CLAUDE_PLUGIN_ROOT", "PLUGIN_ROOT"):
+        token = token.replace("${%s}" % variable, root or "${%s}" % variable)
     return os.path.expandvars(os.path.expanduser(token))
 
 
@@ -348,7 +427,9 @@ def check_hook_targets(harness, hooks, mcp_names, probe):
     for hook in hooks:
         where = f"{hook['source']} {hook['event']} {hook['matcher'] or '*'}"
         if hook["type"] == "command" and hook["command"]:
-            for token in _SCRIPT_RE.findall(hook["command"]):
+            for token in _SCRIPT_RE.findall(_INLINE_CODE_RE.sub(" ", hook["command"])):
+                if not re.search(r"[\\/]", token) and shutil.which(token):
+                    continue
                 path = _expand(token, hook.get("root"))
                 if "$" in path or "%" in path:
                     continue
@@ -384,6 +465,24 @@ def _reachable(url):
         return str(exc)
 
 
+def check_agents(claude):
+    """Subagents whose `tools` list names no Smart Tool tool while the smart-tool server is registered: the redirect
+    leaves them alone (nothing to redirect to), so they search folders with Grep and Read at full cost. A subagent
+    with no `tools` field inherits every tool, MCP included; with the field, only what it lists."""
+    if not any(entry["name"] == SMART_TOOL_SERVER for entry in claude["mcp"]):
+        return []
+    blind = [a for a in claude.get("agents", []) if a["tools"] is not None
+             and not any(tool == "*" or tool.startswith(f"mcp__{SMART_TOOL_SERVER}") for tool in a["tools"])]
+    if not blind:
+        return []
+    names = ", ".join(sorted(a["name"] for a in blind)[:8]) + (" ..." if len(blind) > 8 else "")
+    return [_finding("agent_without_smart_tool", "warn", "claude", "subagents without Smart Tool",
+                     f"{len(blind)} subagent(s) list tools but none of mcp__{SMART_TOOL_SERVER}__*: {names}. Add "
+                     f"mcp__{SMART_TOOL_SERVER}__smart_search and mcp__{SMART_TOOL_SERVER}__smart_search_result to "
+                     "their `tools`, or drop the `tools` line to inherit every tool.", DOCS["claude_subagents"],
+                     [a["path"] for a in blind[:8]])]
+
+
 def check_skills(harness, skills):
     """Skill name collisions, descriptions over Claude's per-skill cut, and the total over the list budget."""
     findings, by_name = [], {}
@@ -635,6 +734,7 @@ def run(project, probe=True, save=True, probe_max_age=0, trigger="manual"):
         results = (probe_mcp(data["mcp"], project, max_age=probe_max_age) if probe
                    else [None] * len(data["mcp"]))
         findings += check_mcp(harness, data["mcp"], results)
+    findings += check_agents(claude)
     findings += check_instructions(project, claude, codex)
     unverified = list(snapshot.unverified)
     if not probe:
@@ -642,8 +742,6 @@ def run(project, probe=True, save=True, probe_max_age=0, trigger="manual"):
     for name in claude["unapproved_mcp"]:
         unverified.append(f".mcp.json server '{name}' is not approved in Claude Code, so it is neither loaded nor "
                           "started here")
-    if codex.get("plugins_unverified"):
-        unverified.append("Codex plugins (their skills and hooks) are not collected yet")
     unverified += ["skill trigger overlap and contradictions between instructions need a model (not run)",
                    "the order between two parallel rewrites is undocumented and cannot be checked"]
     key = hashlib.sha256(json.dumps(sorted(snapshot.files.items())).encode()).hexdigest()[:16]

package/setup_ui.py

@@ -18,6 +18,7 @@ import json
 import os
 import re
 import secrets
+import time
 
 import autostart
 import block_patterns
@@ -29,6 +30,8 @@ import endpoint_sync
 import gateway
 import model_catalog
 import model_defaults
+import model_health
+import model_upgrade
 import local_embedder
 import project_store
 import secret_store
@@ -155,6 +158,56 @@ def handle_models_get():
     }
 
 
+_UPGRADE_CHECK_EVERY_S = 3600
+_upgrade_checked = {"at": 0.0, "error": ""}
+
+
+def _checked_upgrade(force=False):
+    """The model offer, rechecked against the catalog at most once an hour (or when forced). A catalog that cannot be
+    read is reported in `check_error`, with the last stored offer, never as 'nothing to offer'."""
+    now = time.time()
+    if force or now - _upgrade_checked["at"] >= _UPGRADE_CHECK_EVERY_S:
+        try:
+            model_upgrade.check()
+            _upgrade_checked["error"] = ""
+        except Exception as exc:
+            _upgrade_checked["error"] = str(exc)[:300]
+        _upgrade_checked["at"] = now
+    return {**model_upgrade.status(), "check_error": _upgrade_checked["error"]}
+
+
+def handle_upgrade_get():
+    return _checked_upgrade(force=True)
+
+
+def handle_upgrade_action(body):
+    action = body.get("action") if isinstance(body, dict) else None
+    try:
+        if action == "apply":
+            text = model_upgrade.apply()
+        elif action == "decline":
+            text = model_upgrade.decline()
+        elif action == "revert":
+            text = model_upgrade.revert()
+        else:
+            raise SetupError("Invalid action: use apply, decline or revert.")
+    except (ValueError, config.ConfigCorruptedError, OSError) as exc:
+        raise SetupError(str(exc))
+    return {"ok": True, "message": text, "upgrade": model_upgrade.status()}
+
+
+def handle_health_get():
+    return model_health.summary()
+
+
+def handle_notices():
+    """What the tray should show now: the model offer (once a day until answered) and models over the failure limit
+    (once a day each). Fetching marks them announced, so each toast is shown once per reminder period."""
+    upgrade = _checked_upgrade()
+    offer = model_upgrade.due() if upgrade["state"] == "pending" else None
+    return {"upgrade": offer, "failing": model_health.alerts_due(), "check_error": upgrade["check_error"]}
+
+
 def handle_local_models_get():
     available = local_embedder.info() if local_embedder.configured() else None
     return {"mode": config.local_models_mode(), "modes": list(config.LOCAL_MODEL_MODES),
@@ -671,6 +724,24 @@ _PAGE_TEMPLATE = """<!doctype html>
         <div class="msg" id="gateway-msg" role="status"></div>
       </div>
 
+      <div class="card" id="upgrade-card" hidden>
+        <div class="card-head"><h3>New recommended models</h3><span class="pill" id="upgrade-pill" data-tone="warn">Available</span></div>
+        <p class="lede">This version recommends other models than the ones you use. Nothing changes until you apply; the models you have now are kept so you can switch back.</p>
+        <ul id="upgrade-list"></ul>
+        <div class="actions">
+          <button type="button" class="primary" id="btn-upgrade-apply">Apply recommended models</button>
+          <button type="button" id="btn-upgrade-decline">Keep mine, don't ask again</button>
+          <button type="button" id="btn-upgrade-revert" hidden>Switch back to my previous models</button>
+        </div>
+        <div class="msg" id="upgrade-msg" role="status"></div>
+      </div>
+
+      <div class="card" id="health-card">
+        <div class="card-head"><h3>Model failures (last 24 h)</h3><span class="pill" id="health-pill" data-tone="busy">Checking</span></div>
+        <p class="lede">Every failed call to a gateway model, by role and tool. A model that fails half of its calls (5 or more) also raises a Windows notification.</p>
+        <div id="health-table"></div>
+      </div>
+
       <div class="card" id="models-card">
         <div class="card-head"><h3>2. Models</h3><span class="pill" id="models-pill" data-tone="busy">Checking</span></div>
         <p class="lede">Any model id your gateway accepts. The gateway's catalog shows up as suggestions while you type.</p>
@@ -1048,6 +1119,52 @@ async function loadModels() {
     setMsg("models-msg", "error", "Could not read the gateway catalog: " + error.message);
   }
 }
+
+function esc(text) { const el = document.createElement("span"); el.textContent = text; return el.innerHTML; }
+async function loadUpgrade() {
+  try {
+    const data = await getJSON("/setup/models/upgrade");
+    const rows = Object.entries(data.changes || {}).map(([role, change]) => `<li><b>${esc(role)}</b>: ${esc(change.current)} → ${esc(change.new)}</li>`);
+    const offer = data.state === "pending" && rows.length;
+    const applied = data.state === "applied" && Object.keys(data.previous || {}).length;
+    $("upgrade-card").hidden = !(offer || applied);
+    $("upgrade-list").innerHTML = offer ? rows.join("") : Object.entries(data.previous).map(([role, model]) => `<li><b>${esc(role)}</b> was ${esc(model)}</li>`).join("");
+    setPill("upgrade-pill", offer ? "warn" : "ok", offer ? "Available" : "Applied");
+    $("btn-upgrade-apply").hidden = $("btn-upgrade-decline").hidden = !offer;
+    $("btn-upgrade-revert").hidden = !applied;
+    if (data.check_error) setMsg("upgrade-msg", "error", "Could not check the catalog: " + data.check_error);
+  } catch (error) {
+    $("upgrade-card").hidden = false;
+    setMsg("upgrade-msg", "error", "Could not read the model offer: " + error.message);
+  }
+}
+for (const [id, action] of [["btn-upgrade-apply", "apply"], ["btn-upgrade-decline", "decline"], ["btn-upgrade-revert", "revert"]]) {
+  $(id).addEventListener("click", async () => {
+    setMsg("upgrade-msg", "", "Working…");
+    try {
+      const result = await post("/setup/models/upgrade", { action });
+      await loadUpgrade();
+      await loadModels();
+      setMsg("upgrade-msg", "ok", result.message);
+    } catch (error) {
+      setMsg("upgrade-msg", "error", error.message);
+    }
+  });
+}
+async function loadHealth() {
+  try {
+    const data = await getJSON("/setup/models/health");
+    const failing = data.models.filter((row) => row.failing).length;
+    setPill("health-pill", failing ? "bad" : "ok", failing ? plural(failing, "model") + " failing" : "No problem");
+    const models = data.models.map((row) => `<tr><td>${esc(row.role)}</td><td>${esc(row.model)}</td><td>${row.errors} / ${row.calls}</td><td>${Math.round(row.rate * 100)}%</td></tr>`).join("");
+    const failures = data.failures.map((row) => `<tr><td>${esc(new Date(row.at * 1000).toLocaleString())}</td><td>${esc(row.role)}</td><td>${esc(row.model)}</td><td>${esc(row.tool || "-")}</td><td>${esc(row.error)}</td></tr>`).join("");
+    $("health-table").innerHTML = (models ? `<table><tr><th>Role</th><th>Model</th><th>Failed / calls</th><th>Rate</th></tr>${models}</table>` : "<p>No model call in the last 24 hours.</p>")
+      + (failures ? `<table><tr><th>When</th><th>Role</th><th>Model</th><th>Tool</th><th>Error</th></tr>${failures}</table>` : "");
+  } catch (error) {
+    setPill("health-pill", "bad", "Unavailable");
+    $("health-table").textContent = "Could not read the failure log: " + error.message;
+  }
+}
 $("btn-save-models").addEventListener("click", async () => {
   if (!modelsLoaded) { setMsg("models-msg", "error", "The catalog has not loaded yet; nothing was saved."); return; }
   setMsg("models-msg", "", "Saving…");
@@ -1809,7 +1926,8 @@ $("btn-audit-run").addEventListener("click", async () => {
 
 renderGateway();
 renderOverview();
-if (status.gateway.status === "ready") loadModels();
+if (status.gateway.status === "ready") { loadModels(); loadUpgrade(); }
+loadHealth();
 loadLocalModels();
 loadIntegration();
 loadAutostart();

package/smart_tool_daemon.py

@@ -55,6 +55,7 @@ import dossier
 import scout
 import embedding_cache
 import model_defaults
+import model_health
 import project_identity
 import project_store
 import project_scheduler
@@ -3984,13 +3985,19 @@ def _dispatch_tool_call(params, session_id=None):
         return _tool_result(_sanitize_text(f"Unknown tool: {name}"), is_error=True)
     token = _MCP_SESSION.set(session_id)
     try:
-        return _tool_result(handler(arguments))
-    except Exception as exc:
-        # Boundary central pra qualquer handler atual/futuro: uma exceção pode
-        # carregar texto de uma fonte não totalmente confiável (ex.: corpo/reason
-        # de erro de um proxy externo) até este ponto sem ter passado por
-        # sanitização própria do handler.
-        return _tool_result(_sanitize_text(str(exc)), is_error=True)
+        with model_health.tool_call(name) as failures:
+            try:
+                result = _tool_result(handler(arguments))
+            except Exception as exc:
+                # Boundary central pra qualquer handler atual/futuro: uma exceção pode
+                # carregar texto de uma fonte não totalmente confiável (ex.: corpo/reason
+                # de erro de um proxy externo) até este ponto sem ter passado por
+                # sanitização própria do handler.
+                result = _tool_result(_sanitize_text(str(exc)), is_error=True)
+        warning = model_health.warning_text(failures, setup_ui.setup_origin())
+        if warning:
+            result["content"][0]["text"] += _sanitize_text(warning)
+        return result
     finally:
         _MCP_SESSION.reset(token)
 
@@ -4059,6 +4066,7 @@ def _loopback_host(header_value, require_port=False):
 
 _SETUP_SAVES = {
     "/setup/models": setup_ui.handle_models_save,
+    "/setup/models/upgrade": setup_ui.handle_upgrade_action,
     "/setup/providers": setup_ui.handle_providers_save,
     "/setup/local-models": setup_ui.handle_local_models_save,
     "/setup/integration": setup_ui.handle_integration_save,
@@ -4180,6 +4188,13 @@ class MCPHandler(BaseHTTPRequestHandler):
             except Exception as exc:
                 self._write_json(500, {"error": _sanitize_text(str(exc))})
             return
+        if self.path in ("/setup/models/upgrade", "/setup/models/health"):
+            try:
+                self._write_json(200, setup_ui.handle_upgrade_get() if self.path.endswith("upgrade")
+                                 else setup_ui.handle_health_get())
+            except Exception as exc:
+                self._write_json(500, {"error": _sanitize_text(str(exc))})
+            return
         if self.path == "/projects":
             import projects_ui
             self._write_html(200, projects_ui.render_projects_page())
@@ -4263,6 +4278,12 @@ class MCPHandler(BaseHTTPRequestHandler):
         if urllib.parse.urlsplit(self.path).path == "/hooks/session-audit":
             self._write_json(200, _session_audit_hook(self))
             return
+        if self.path == "/setup/notices":
+            try:
+                self._write_json(200, setup_ui.handle_notices())
+            except Exception as exc:
+                self._write_json(500, {"error": _sanitize_text(str(exc))})
+            return
         save = _SETUP_SAVES.get(self.path)
         if save:
             self._post_setup(save)