@allansantos-dev/smart-tool 0.9.29 → 0.9.32

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## 0.9.32 - beta
+
+- Users who updated are told about the new recommended models. `model_upgrade` compares the saved `router_model`,
+  `scope_model`, `research_model` and `scout_model` with the recommended ones against the gateway's catalog and the
+  Windows tray shows a toast with "Apply now" and "Don't show again". Applying keeps the previous models so they can be
+  restored from the setup page (card "New recommended models"); a role you changed after the offer is never overwritten;
+  closing the toast reminds again after 24 h; declining silences it for this version. Embedding and rerank models are
+  never offered (changing them invalidates every index). Buttons are protocol links run by `notice_action.py`
+  (`pythonw`, no window, HKCU only, no admin), each carrying a nonce of the offer.
+- Model failures are logged and shown. `model_health` records every model call by hour, model and role (and, on
+  failure, tool, route and error text without the request content). A tool answer that hit a failing model now carries
+  a line with the model, the role, the error and the link to `/setup#models`; the Models page shows the last 24 h
+  (failures/calls) and the 20 latest failures; the tray raises one toast per model per day (5+ calls and 50%+ failures
+  in 24 h) with "Switch model" and "Mute 7 days". Endpoint: `GET /setup/models/health`.
+- Tests: `tests/test_model_upgrade.py`, `tests/test_model_health.py`; research note
+  `docs/research/2026-10-24-aviso-de-modelos-novos-e-falhas-de-modelo.md`.
+
+## 0.9.31 - beta
+
+- `scout_model` is filled by default. The setup screen (and the daemon, when it checks the models) now fills an empty
+  `scout_model` with Claude Haiku 5.5 when the configured gateway has it; a choice you made is never replaced, and a
+  gateway without that model leaves the field empty to choose (the scout then returns the literal lines, as before).
+- The other recommended models were re-measured by the same criterion (correctness first, price second; 3 rounds per
+  model; docs/research/2026-10-24-modelos-do-scout-e-dos-outros-papeis.md) and changed for new fills: `router_model`
+  Claude Haiku 5.5 (was GPT-4o-mini: it invented an answer to every request whose answer was not on the page),
+  `scope_model` GPT-5.4 nano (same accuracy as GPT-5-mini at 29% of the price), `research_model` GPT-5.4 nano (was
+  GPT-OSS 20B, which failed tool calls). Models already set are kept.
+  - Scout with an index (16 questions x 3 rounds x 15 models): Haiku 5.5 21/36 files found (the index's ceiling, equal
+    to no model), 12/12 on the questions with no answer, 0 failures; without an index, 20/36 against 12/36 for the
+    keyword scan and at most 17/36 for the other models.
+  - 8-question sessions with Sonnet: US$ 0.121 per session with Haiku 5.5 against 0.177 without a model, 73/80 against
+    75/80, and the agent never left the tool to read files itself (GPT-4o-mini: 10 times).
+- The client repeats a chat call once without `temperature` when the gateway answers 400 about it (Claude on Bedrock,
+  the GPT-5 family) and remembers the model; a second refusal still fails.
+- Tests: `tests/test_model_client.py`; probes `tests/scout_model_probe.py` and `tests/role_model_probe.py`;
+  `tests/scout_probe.py --scout-model`.
+
+## 0.9.30 - beta
+
+- New MCP tool `smart_scout(project_root, question, terms?, max_files?)`: answers a question about a project's code with
+  the lines that answer it, read inside Smart Tool so the files never enter the agent's context.
+  - Candidates come from the `smart_search` pipeline: the index when it is ready, the index plus a keyword read of the
+    files changed after it, or the keyword scan of the disk while the first index is built (answered at once, outside
+    the per-folder queue). With no index, no saved scope and no model, the scan covers the whole project (dependency,
+    hidden and generated folders excluded) instead of the root files only.
+  - For each of up to `max_files` files (default 5, at most 10) it reads the current lines from disk and keeps the
+    window with most of the question's words; the agent gets `path:lines`, the functions in it and those lines verbatim.
+  - Optional `scout_model` (setup screen, "Code scout"; empty by default): a small model of the configured gateway
+    reads the windows, writes up to 5 lines of answer and picks the line ranges to show, which are sliced from what
+    was read on disk. Without an index it first chooses the terms and folders to scan (two calls; one with an index).
+    A range outside what was read is clipped or dropped; an answer that cites no lines comes with the best keyword
+    windows; a model failure returns the lines with the error in a warning. Model calls are metered under the
+    purpose `scout` (`project_manage action=usage`).
+  - The server instructions point to `smart_scout` for questions that would mean reading several files, and the tool
+    loads upfront in Claude Code.
+  - Measured in isolated sessions (clean HOME and config, no CLAUDE.md, hooks, skills or plugins; 8 questions per
+    session, Sonnet, two repositories; docs/research/2026-10-24-smart-scout-construido-e-medido.md): with an index,
+    `smart_scout` with a `scout_model` cost US$ 0.154 per session against US$ 0.250 for `smart_search` alone, 31/32
+    right against 29/32, 90 s against 70 s; without a model, US$ 0.203, 29/32, 63 s. On a fresh install (no index)
+    it answered in 43 s (no model) and 117 s (model) against 256 s.
+- Tests: `tests/test_scout.py`; probe `tests/scout_probe.py`.
+
 ## 0.9.29 - beta
 
 - Registering the MCP server in Claude Code or Codex is idempotent. `claude mcp add` refuses a name that exists

package/README.md

@@ -5,6 +5,7 @@ A local MCP server that gives coding agents (Claude Code, Codex) cheaper, sharpe
 | Tool | What it does |
 |---|---|
 | `smart_search` / `smart_search_result` | Semantic + lexical search over an indexed project, results split into code, tests and docs, with the likeliest functions per chunk |
+| `smart_scout` | Answers a question about the code with the lines that answer it: reads the candidate files inside Smart Tool and returns `path:lines` with the literal text, so the files never enter the agent's context; with a `scout_model`, a small model also writes a short answer and keeps only the lines that support it |
 | `web_search` / `web_search_result` | Web search across several sources in parallel, in the query language and in English, with a cache shared across sessions; `depth="research"` runs a multi-round research loop |
 | `web_fetch` | Reads a known URL and returns only the answer to your prompt, written by a small model; pages are cached for 24 h. Pages over 60,000 characters are not cut: the model reads the parts closest to the prompt (needs an `embedding_model`) |
 | `project_manage` | Registers and indexes projects, shows coverage, code maps, duplicated functions and index storage; `graph` with `symbol` tells what changing a function touches: callers, calls, the tests that reach it and the files that import it |
@@ -15,7 +16,7 @@ registered as the `playwright` server where this machine lets a browser be drive
 An optional hook routes the agent's native Grep/Glob/Read/Bash/WebSearch/WebFetch calls to these tools when they
 are cheaper, or just tells the agent what Smart Tool would do.
 
-**Status:** 0.9.29 beta. Windows only. What changed in each version: [CHANGELOG.md](CHANGELOG.md).
+**Status:** 0.9.32 beta. Windows only. What changed in each version: [CHANGELOG.md](CHANGELOG.md).
 
 ## How it works
 
@@ -27,6 +28,7 @@ program that runs on your machine and offers the agent better tools for the same
 ```
 Claude Code / Codex ──MCP──▶ Smart Tool daemon (127.0.0.1, one per machine)
                                ├─ smart_search ──▶ local index of your project (SQLite)
+                               ├─ smart_scout ───▶ the files behind a search, read on disk (small model optional)
                                ├─ web_search ───▶ several search engines at once, shared cache
                                ├─ web_fetch ────▶ the page, read by a small model
                                └─ project_manage
@@ -41,6 +43,13 @@ rerank model, reorders the best candidates. The agent gets back a few chunks spl
 the functions most likely to matter, instead of every line that contains a word. The index follows the project:
 only files whose content changed are processed again, and each Git branch keeps its own view.
 
+**Reading code to answer a question.** `smart_scout` takes a question in plain language. It finds the candidates the
+same way as `smart_search` (or by keyword on disk while there is no index yet), reads the current lines of each one
+and keeps, per file, the window with most of the question's words. The agent receives `path:lines` and those lines
+verbatim. With a `scout_model` (the setup screen fills it with Claude Haiku 5.5 when the gateway has it), a small model reads those windows, writes a few lines of answer
+and picks which lines to show; without an index it first picks the words and folders to scan (two calls; one with an
+index). What the model writes never replaces the literal lines, and when it fails the lines come back with the error.
+
 **Searching the web.** `web_search` asks several free search sources in parallel (DuckDuckGo, Wikipedia, Yahoo,
 Exa, Google and others), in the language of the question and in English, and merges what comes back. Search APIs with a
 free quota (Tavily, Firecrawl) and a real browser are tried only when those results are not enough. Answers are cached and shared by every agent
@@ -83,7 +92,7 @@ updating, updated, update failed), and agent sessions get the same line on their
 start when the SessionStart report is on, shown to you too) with the link to the changes. The tray menu has "Update to
 X" (or "Check for updates") on demand and an "Update automatically" switch; `SMART_TOOL_AUTO_UPDATE=off` also turns
 automatic updates off, and the newer-version notice then carries the command to run. Running the command by hand also updates; `~/.smart-tool` is kept. It downloads [uv](https://docs.astral.sh/uv/) (checksum
-verified) and a private Python 3.12 into `~/.smart-tool/runtime`, with nothing added to `PATH` or the registry, then
+verified) and a private Python 3.12 into `~/.smart-tool/runtime`, with nothing added to `PATH` and, in the registry, only two per-user (HKCU) keys that make the notification buttons work, then
 copies Smart Tool to `%LOCALAPPDATA%\Programs\SmartTool` with its own virtual environment,
 installs the web runtime, registers a per-user Scheduled Task that starts the tray at logon and starts the daemon on
 `http://127.0.0.1:8765` (another free port is used, and announced, if 8765 is taken).
@@ -242,13 +251,16 @@ fails to load is listed in the setup screen with its error and does not affect t
   everything local.
 - Web queries go to the search sources listed in `NOTICE`. Their free tiers are rate limited per IP address; respect
   each service's terms of use.
-- Logs and metrics are written to `~/.smart-tool/data` and never leave the machine.
+- Logs and metrics are written to `~/.smart-tool/data` and never leave the machine. That includes the model failure log
+  (model, role, tool and the error text, up to 300 characters, which can carry the gateway's error body; never the request).
 
 ## Uninstall
 
 Turn off "Start automatically" in the setup screen, quit from the tray, remove the hook entries from
 `~/.claude/settings.json` / `~/.codex/hooks.json` (the setup screen shows them), run `claude mcp remove smart-tool -s
-user` / `codex mcp remove smart-tool`, then delete `%LOCALAPPDATA%\Programs\SmartTool` and `~/.smart-tool`.
+user` / `codex mcp remove smart-tool`, then delete `%LOCALAPPDATA%\Programs\SmartTool` and `~/.smart-tool`. Turning off "Start automatically" also removes the
+two per-user registry keys of the notification buttons (`HKCU\Software\Classes\smart-tool-action` and
+`HKCU\Software\Classes\AppUserModelId\SmartTool.Notifications`); they come back the next time a notification is shown.
 
 ## License
 

package/autostart.py

@@ -11,6 +11,8 @@ import subprocess
 import sys
 import tempfile
 
+import toast_notice
+
 TASK_NAME = os.environ.get("SMART_TOOL_TASK_NAME", "SmartTool-Tray")
 
 
@@ -188,6 +190,8 @@ def remove():
         pass
     if _remove_startup_shortcut():
         removed.append("startup_folder")
+    if sys.platform == "win32" and toast_notice.unregister():
+        removed.append("toast_registry")
     return {"ok": True, "removed": removed}
 
 

package/config.py

@@ -23,6 +23,7 @@ _LOCK = threading.RLock()
 DEFAULT_CONFIG = {
     "router_model": "",
     "scope_model": "",
+    "scout_model": "",
     "embedding_model": "",
     "rerank_model": "",
     "research_model": "",

package/model_client.py

@@ -1,11 +1,17 @@
 """Smart Tool model client: talks to the configured model gateway through its adapter."""
 import contextvars
+import io
+import threading
 import time
+import urllib.error
 import usage_meter
 
 import gateway
+import model_health
 
 OFFLINE = contextvars.ContextVar("model_offline", default=None)
+_NO_TEMPERATURE = set()
+_no_temperature_lock = threading.Lock()
 
 
 def get_token():
@@ -29,10 +35,29 @@ def fetch(path, token, method="GET", body=None, timeout=15):
         raise
     finally:
         usage_meter.record(path,body,result,headers,failure,time.monotonic()-started)
+        model_health.record(path,body,failure)
 
 
 def _fetch(path, _token, method="GET", body=None, timeout=15):
-    # Callers name routes as /v1/...; the adapter knows where its API starts.
+    """Routes are named /v1/...; the adapter knows where its API starts. Some models (a Claude on Bedrock, the GPT-5
+    family) reject `temperature` with HTTP 400; the request is repeated once without it and the model is remembered, so
+    any model of the gateway works with the same call. A second refusal propagates."""
     if not path.startswith("/v1/"):
         raise ValueError("Only /v1/ routes are accepted by this client.")
-    return gateway.request(path[len("/v1/"):], body=body, timeout=timeout)
+    route = path[len("/v1/"):]
+    model = body.get("model") if isinstance(body, dict) else None
+    if isinstance(body, dict) and "temperature" in body and model in _NO_TEMPERATURE:
+        body = {key: value for key, value in body.items() if key != "temperature"}
+    try:
+        return gateway.request(route, body=body, timeout=timeout)
+    except urllib.error.HTTPError as exc:
+        if exc.code != 400 or not isinstance(body, dict) or "temperature" not in body:
+            raise
+        detail = exc.read()
+        if b"temperature" not in detail.lower():
+            exc.read = io.BytesIO(detail).read
+            raise
+    with _no_temperature_lock:
+        _NO_TEMPERATURE.add(model)
+    return gateway.request(route, body={key: value for key, value in body.items() if key != "temperature"},
+                           timeout=timeout)

package/model_defaults.py

@@ -6,12 +6,16 @@ import config
 import model_catalog
 
 
-# Matched as the last path/dot segment of the catalog id, so "gpt-4o-mini" also finds "openai/gpt-4o-mini" (OpenRouter)
-# and "openai.gpt-4o-mini" (LiteLLM aliases). Router: small, no reasoning (it runs before tool calls).
+# Matched as the last path/dot segment of the catalog id, so "claude-haiku-5-5" also finds "vertex_ai.anthropic.claude-haiku-5-5"
+# (LiteLLM aliases) and "anthropic/claude-haiku-5-5" (OpenRouter). Chosen by measurement, 3 rounds per model, correctness
+# first and price second (docs/research/2026-10-24-modelos-do-scout-e-dos-outros-papeis.md): the router answers pages
+# and the scout reads code excerpts, where Claude Haiku 5.5 answered every request and led the no-index path; scope and
+# research pick the GPT-5.4 nano, as accurate there at about half the price and without the long reasoning of the mini.
 RECOMMENDED_MODELS = {
-    "router_model": ("chat", "gpt-4o-mini"),
-    "scope_model": ("chat", "gpt-5-mini"),
-    "research_model": ("chat", "gpt-oss-20b"),
+    "router_model": ("chat", "claude-haiku-5-5"),
+    "scope_model": ("chat", "gpt-5.4-nano"),
+    "scout_model": ("chat", "claude-haiku-5-5"),
+    "research_model": ("chat", "gpt-5.4-nano"),
     "embedding_model": ("embedding", "text-embedding-3-small"),
     "rerank_model": ("rerank", "rerank-3-5"),
 }

package/model_health.py

@@ -0,0 +1,164 @@
+"""Failure log and failure rate of the gateway models, per model and role (router, scope, scout, research, embedding,
+rerank). Never stores request content: the model, the role, the tool that was running, the HTTP path, a short error
+text and the time.
+
+Three consumers read it: the tool answer (a warning line when a call of that very tool failed), the setup screen
+(rate table and recent failures) and the tray (one toast per model per day when the rate passes the limit).
+"""
+import contextlib
+import contextvars
+import io
+import os
+import sqlite3
+import time
+
+import config
+import project_store
+
+WINDOW_S = 24 * 3600
+ALERT_MIN_CALLS = 5
+ALERT_RATE = 0.5
+ALERT_EVERY_S = 24 * 3600
+MUTE_S = 7 * 24 * 3600
+KEEP_S = 7 * 24 * 3600
+KEEP_FAILURES = 500
+ERROR_CHARS = 300
+_ROLES = ("router_model", "scope_model", "scout_model", "research_model", "embedding_model", "rerank_model")
+_PATHS = ("/v1/chat/completions", "/v1/embeddings", "/v1/rerank")
+_TOOL = contextvars.ContextVar("model_health_tool", default=None)
+_COLLECTED = contextvars.ContextVar("model_health_collected", default=None)
+_SCHEMA = set()
+
+
+@contextlib.contextmanager
+def tool_call(name):
+    """Marks the model calls made inside the block as run by tool `name` and collects their failures; the block yields
+    the list, which `warning_text` turns into the line appended to the tool answer."""
+    failures = []
+    tool_token, list_token = _TOOL.set(name), _COLLECTED.set(failures)
+    try:
+        yield failures
+    finally:
+        _TOOL.reset(tool_token)
+        _COLLECTED.reset(list_token)
+
+
+def _db():
+    return project_store._db()
+
+
+def _tables(db):
+    if project_store.DB_PATH in _SCHEMA and os.path.isfile(project_store.DB_PATH):
+        return
+    db.execute("CREATE TABLE IF NOT EXISTS model_calls(hour INTEGER,model TEXT,role TEXT,calls INTEGER,errors INTEGER,"
+               "PRIMARY KEY(hour,model,role))")
+    db.execute("CREATE TABLE IF NOT EXISTS model_failures(at REAL,model TEXT,role TEXT,tool TEXT,path TEXT,error TEXT)")
+    db.execute("CREATE TABLE IF NOT EXISTS model_alerts(model TEXT PRIMARY KEY,last_notified REAL,muted_until REAL)")
+    _SCHEMA.add(project_store.DB_PATH)
+
+
+def role_of(model, cfg=None):
+    """Name of the config field that selects `model` ('other' when none does)."""
+    cfg = cfg if cfg is not None else config.load_config()
+    return next((field for field in _ROLES if cfg.get(field) == model), "other")
+
+
+def error_text(exc):
+    """Short text of a failed call. An HTTP error body is read once and put back so the caller can still read it."""
+    text = f"{type(exc).__name__}: {exc}"
+    fp = getattr(exc, "fp", None)
+    if fp is not None and hasattr(exc, "read"):
+        try:
+            detail = exc.read()
+            exc.read = io.BytesIO(detail).read
+            text += " | " + detail.decode("utf-8", "replace")
+        except Exception:
+            pass
+    return " ".join(text.split())[:ERROR_CHARS]
+
+
+def record(path, body, failure=None):
+    """Counts one model call and, when it failed, logs it. Never raises: the log must not change the call's result."""
+    if path not in _PATHS:
+        return
+    try:
+        model = str((body or {}).get("model", "")) if isinstance(body, dict) else ""
+        role = role_of(model)
+        now = time.time()
+        text = error_text(failure) if failure is not None else None
+        with project_store._LOCK, _db() as db:
+            _tables(db)
+            db.execute("INSERT INTO model_calls VALUES(?,?,?,1,?) ON CONFLICT(hour,model,role) DO UPDATE SET "
+                       "calls=calls+1,errors=errors+excluded.errors", (int(now // 3600), model, role, int(text is not None)))
+            if text is not None:
+                db.execute("INSERT INTO model_failures VALUES(?,?,?,?,?,?)", (now, model, role, _TOOL.get() or "", path, text))
+                db.execute("DELETE FROM model_failures WHERE at<? OR rowid NOT IN "
+                           "(SELECT rowid FROM model_failures ORDER BY at DESC LIMIT ?)", (now - KEEP_S, KEEP_FAILURES))
+                db.execute("DELETE FROM model_calls WHERE hour<?", (int((now - KEEP_S) // 3600),))
+        collected = _COLLECTED.get()
+        if text is not None and collected is not None:
+            collected.append({"model": model, "role": role, "error": text})
+    except Exception:
+        pass
+
+
+def warning_text(failures, setup_url):
+    """The line a tool answer carries when a model call inside it failed ('' when none did)."""
+    if not failures:
+        return ""
+    first = failures[0]
+    more = f" (+{len(failures) - 1} more)" if len(failures) > 1 else ""
+    return (f"\n\nSmart Tool model warning: {first['role']} `{first['model']}` failed in this call{more}: "
+            f"{first['error']}. Pick another model: {setup_url}/setup#models")
+
+
+def summary(now=None):
+    """Per model and role over the last 24 h, plus the 20 latest failures."""
+    now = now or time.time()
+    with project_store._LOCK, _db() as db:
+        _tables(db)
+        db.row_factory = sqlite3.Row
+        models = [dict(row) for row in db.execute(
+            "SELECT model,role,SUM(calls) AS calls,SUM(errors) AS errors FROM model_calls WHERE hour>=? "
+            "GROUP BY model,role ORDER BY SUM(errors) DESC,SUM(calls) DESC", (int((now - WINDOW_S) // 3600),))]
+        failures = [dict(row) for row in db.execute(
+            "SELECT at,model,role,tool,path,error FROM model_failures WHERE at>=? ORDER BY at DESC LIMIT 20", (now - WINDOW_S,))]
+        for row in models:
+            last = db.execute("SELECT error FROM model_failures WHERE model=? AND role=? ORDER BY at DESC LIMIT 1",
+                              (row["model"], row["role"])).fetchone()
+            row["last_error"] = last[0] if last else ""
+    for row in models:
+        row["rate"] = round(row["errors"] / row["calls"], 3) if row["calls"] else 0.0
+        row["failing"] = row["calls"] >= ALERT_MIN_CALLS and row["rate"] >= ALERT_RATE
+    return {"window_hours": WINDOW_S // 3600, "models": models, "failures": failures}
+
+
+def alerts_due(now=None):
+    """Models over the failure limit that are neither muted nor already announced in the last 24 h; marks them
+    announced, so a second call in the same day returns nothing."""
+    now = now or time.time()
+    due = []
+    for row in summary(now)["models"]:
+        if not row["failing"]:
+            continue
+        with project_store._LOCK, _db() as db:
+            _tables(db)
+            seen = db.execute("SELECT last_notified,muted_until FROM model_alerts WHERE model=?", (row["model"],)).fetchone()
+            if seen and (seen[1] > now or now - seen[0] < ALERT_EVERY_S):
+                continue
+            db.execute("INSERT INTO model_alerts VALUES(?,?,0) ON CONFLICT(model) DO UPDATE SET last_notified=excluded.last_notified",
+                       (row["model"], now))
+        due.append(row)
+    return due
+
+
+def mute(model, now=None):
+    """Silences the failure toast for `model` for 7 days (the failures stay in the log)."""
+    if not model:
+        raise ValueError("No model to mute.")
+    now = now or time.time()
+    with project_store._LOCK, _db() as db:
+        _tables(db)
+        db.execute("INSERT INTO model_alerts VALUES(?,?,?) ON CONFLICT(model) DO UPDATE SET muted_until=excluded.muted_until",
+                   (model, now, now + MUTE_S))
+    return f"failure alerts for {model} muted for 7 days"

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 = 1
+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.29",
+  "version": "0.9.32",
   "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",