@allansantos-dev/smart-tool 0.9.5 → 0.9.6

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.9.6 - beta
+
+Reported by the claude-code-boss session validating 0.9.5.
+
+- `project_manage action=duplicates` reads the files the index does not reflect yet (working tree, files changed on
+  disk, commits after the last indexing) and says how many it read: it kept reporting a function removed in a commit
+  made after the last indexing, with no sign that the index was behind.
+- In `graph` impact results, a test or caller that is an anonymous callback registered with `test('title', fn)`,
+  `it()` or `describe()` shows its title (`test "embedder (Q47): ..."`) instead of `callback`.
+- `graph` with `symbol` accepts a partial path before `::` (`brain-embedder.js::loadConfig`), matching the files whose
+  path ends with it; it needed the full path from the project root.
+
+Automatic updates.
+
+- When the tray starts (at logon, before agent sessions use the daemon) and npm has a newer version, it runs the
+  install command in a visible console that closes on success and stays open on failure. Each version is installed
+  automatically once: a failed update restores the previous version and restarts the tray, which then only offers it.
+- The tray menu has "Update to X" (or "Check for updates", which says when the installed version is the latest) and an
+  "Update automatically" switch (`auto_update`, on by default). Later daily checks only notify.
+
+Agents that ignored the hook's redirect: only 44 of 368 blocked calls (12%) were followed by a `smart_search` within
+30 s; the rest rewrote the search in Bash, node or python.
+
+- The block message names the exact tool and arguments (`mcp__smart-tool__smart_search` with the project root filled
+  in, `web_fetch` with the URL), says it is a routing rule and not a failure, that redoing the search through Bash,
+  python, node or PowerShell bypasses it, and, in Claude Code, how to load the tool with ToolSearch.
+- The MCP server sends instructions on what to do when a call is blocked, and `smart_search`, `web_fetch`,
+  `web_search` and their `_result` tools load upfront (`anthropic/alwaysLoad`): Claude Code defers MCP tools, so a
+  blocked agent often did not have the replacement in its tool list. In real `claude -p` sessions, an agent asked to
+  read a page went straight to `web_fetch`, and one asked to run a broad `grep -rn` switched to `smart_search` after
+  the block.
+- `cd dir; grep -n x file.py` was measured as a search over the whole tree (the `;` stuck to the directory name hid
+  the file): 45 of the 92 logged Bash redirects with `cd dir;` were reads of one file. A command with a recursive
+  search after a file read (`sed -n 1,9p a.py; grep -rn x src`) is still measured by the directory it searches.
+- A subagent whose tool list has no Smart Tool tool (claude-code-guide, statusline-setup, or an agent in
+  `.claude/agents` with a `tools` list without it) is not redirected: it had nothing to switch to and gave up.
+- Bash commands that change files, the repository or dependencies (`git checkout`, `rm`, `sed -i`, `writeFileSync`,
+  `npm run`, ...) are never redirected and skip the router model: 12 of 283 Bash redirects were such commands.
+
 ## 0.9.5 - beta
 
 Reported by the claude-code-boss session on its first day using 0.9.4.

package/README.md

@@ -29,7 +29,9 @@ are cheaper, or just tells the agent what Smart Tool would do.
 npx @allansantos-dev/smart-tool@latest install
 ```
 
-Run the same command to update; `~/.smart-tool` is kept. It downloads [uv](https://docs.astral.sh/uv/) (checksum
+Updates install themselves: when the tray starts (at logon) and npm has a newer version, it runs this same command in
+a visible console, once per version; the tray menu has "Update to X" (or "Check for updates") on demand and an
+"Update automatically" switch. 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
 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

package/code_impact.py

@@ -2,6 +2,7 @@
 which tests reach it through static calls and which files import its module, each with the first line of its
 docstring. Answers the question an agent asks before an edit without a chain of searches and file reads."""
 import os
+import re
 from collections import defaultdict
 
 import code_graph
@@ -17,7 +18,7 @@ NOTE = ("Static analysis of the indexed snapshot plus the files changed in the w
 def _matches(symbols, name):
     path, _sep, wanted = name.strip().rpartition("::")
     path = path.replace("\\", "/").removeprefix("./")
-    pool = [s for s in symbols if s["path"] == path] if path else symbols
+    pool = [s for s in symbols if s["path"] == path or s["path"].endswith("/" + path)] if path else symbols
     exact = [s for s in pool if s["id"] == wanted or s["name"] == wanted]
     return exact or [s for s in pool if s["name"].split(".")[-1] == wanted]
 
@@ -49,6 +50,31 @@ def summaries(root, symbols, wanted_ids):
             if s["id"] in wanted_ids and (s["path"], s["start_line"]) in docs}
 
 
+_TEST_TITLE = re.compile(r"""\b(test|it|describe|suite)(?:\.\w+)?\s*\(\s*(['"`])(.+?)\2""")
+
+
+def _name_test_callbacks(root, by_id, sites):
+    """Anonymous callbacks registered with test('title', fn), it(), describe() are named after their title, so a test
+    reads 'test "loads the config"' instead of 'callback'."""
+    lines_of = {}
+    for site in sites:
+        symbol = by_id.get(site.get("id")) or {}
+        if symbol.get("name", "").split(".")[-1] not in ("callback", "anonymous"):
+            continue
+        path = symbol["path"]
+        if path not in lines_of:
+            try:
+                with open(os.path.join(root, path), encoding="utf-8") as stream:
+                    lines_of[path] = stream.read().splitlines()
+            except (OSError, UnicodeDecodeError):
+                lines_of[path] = []
+        start = symbol["start_line"]
+        text = " ".join(lines_of[path][max(start - 2, 0):start])
+        match = _TEST_TITLE.search(text)
+        if match:
+            site["function"] = f'{match.group(1)} "{match.group(3)[:80]}"'
+
+
 def impact(root, symbol, view_id=None, depth=3, limit=30):
     if not isinstance(symbol, str) or not symbol.strip():
         raise ValueError("Pass symbol: a function, method (Class.method) or class name.")
@@ -92,6 +118,7 @@ def impact(root, symbol, view_id=None, depth=3, limit=30):
     importers = sorted({d["source"] for d in data["dependencies"] if d.get("target") in files and d["source"] not in files})
     ordered_tests = sorted(tests.values(), key=lambda t: (t["hops"], t["path"], t["line"]))
     shown = direct[:limit] + outgoing[:limit] + ordered_tests[:limit]
+    _name_test_callbacks(root, by_id, shown)
     docs = summaries(root, data["symbols"], targets | {site["id"] for site in shown})
     for site in shown:
         doc = docs.get(site.pop("id"))

package/config.py

@@ -33,6 +33,7 @@ DEFAULT_CONFIG = {
     "hook_mode": "redirect",
     "doc_mode": "remind",
     "duplicate_mode": "warn",
+    "auto_update": True,
     "contact": "",
     "model_adapter": "",
     "model_adapter_options": {},
@@ -66,6 +67,14 @@ def duplicate_mode(cfg=None):
     return value
 
 
+def auto_update(cfg=None):
+    """Whether the tray installs a newer release by itself when it starts (once per version)."""
+    value = (cfg if cfg is not None else load_config()).get("auto_update", DEFAULT_CONFIG["auto_update"])
+    if not isinstance(value, bool):
+        raise ValueError(f"Invalid auto_update ({value!r}) in {CONFIG_PATH}: use true or false.")
+    return value
+
+
 def hook_mode(cfg=None):
     value = (cfg if cfg is not None else load_config()).get("hook_mode") or DEFAULT_CONFIG["hook_mode"]
     if value not in HOOK_MODES:

package/duplicates.py

@@ -199,13 +199,16 @@ def _entry(path, name, start, end, file_lines, ext):
             "hash": hashlib.sha1(normalized.encode("utf-8")).hexdigest(), **_features(body, ext, short)}
 
 
-def _working_tree_functions(root, changes, profile):
-    """Production functions of the files changed in the working tree, read from disk, so a copy of a function written
-    earlier in the same session is caught before the index catches up."""
+def _working_tree_functions(root, changes, profile, include_tests=False):
+    """Functions of the files the index does not reflect yet, read from disk (production code, plus tests when
+    include_tests), with the same identity as indexed ones, so a copy written earlier in the session is caught and
+    a function removed since the last indexing is not reported."""
     found = []
+    kinds = ("code", "test") if include_tests else ("code",)
     for rel, status in changes.items():
         ext = rel.rsplit(".", 1)[-1].lower() if "." in rel else ""
-        if status == "deleted" or ext not in _LANG or index_profile.kind(rel, profile) != "code":
+        kind = index_profile.kind(rel, profile)
+        if status == "deleted" or ext not in _LANG or kind not in kinds:
             continue
         try:
             with open(os.path.join(root, rel), encoding="utf-8") as stream:
@@ -215,12 +218,18 @@ def _working_tree_functions(root, changes, profile):
         if _GENERATED.search(source[:4000]):
             continue
         lines = source.splitlines()
-        for function in doc_check.functions(rel, source):
-            if function["end"] - function["start"] + 1 < MIN_LINES:
+        functions = doc_check.functions(rel, source)
+        occurrences = {}
+        for function in functions:
+            if function["end"] - function["start"] + 1 < MIN_LINES or any(
+                    other is not function and other["start"] <= function["start"] and function["end"] <= other["end"]
+                    and (other["start"], other["end"]) != (function["start"], function["end"]) for other in functions):
                 continue
             entry = _entry(rel, function["name"], function["start"], function["end"], lines, ext)
             if entry:
-                found.append({**entry, "kind": "code"})
+                occurrence = occurrences[entry["hash"]] = occurrences.get(entry["hash"], 0) + 1
+                found.append({**entry, "kind": kind, "fp": hashlib.sha1(
+                    f"{rel}\0{entry['hash']}\0{occurrence}".encode("utf-8")).hexdigest()})
     return found
 
 
@@ -359,6 +368,13 @@ def find(root, embed, configured_model, min_similarity=DEFAULT_MIN_SIMILARITY, i
     started = time.monotonic()
     dismissed = dismissed or {}
     functions, notes, view = _functions(root, include_tests)
+    if view.get("current"):
+        pending = code_graph.pending_changes(root, view["path"])
+        if pending:
+            profile = index_profile.current((index_scope.load_scope(root) or {}).get("profile"))
+            functions = [f for f in functions if f["path"] not in pending] + _working_tree_functions(
+                root, pending, profile, include_tests)
+            notes.append(f"{len(pending)} file(s) changed since the last indexing were read from disk.")
     groups = {}
     for f in functions:
         groups.setdefault(f["hash"], []).append(f)

package/hook_decision.py

@@ -42,6 +42,114 @@ def deny(reason):
                                    "permissionDecisionReason": reason}}
 
 
+# Claude Code built-in subagents whose tool list has no MCP tool (claude-code-guide: Glob, Grep, Read, WebFetch,
+# WebSearch; statusline-setup: Read, Edit).
+BUILTIN_AGENTS_WITHOUT_MCP = frozenset({"claude-code-guide", "statusline-setup"})
+
+
+def _frontmatter(path):
+    """`name` and `tools` of an agent definition (.md with YAML frontmatter); tools is None when the field is absent
+    (the agent inherits every tool), else the list of tool names (inline `[a, b]`, `a, b` or a `- a` block)."""
+    with open(path, encoding="utf-8") as stream:
+        lines = stream.read().splitlines()
+    if not lines or lines[0].strip() != "---":
+        return None, None
+    name, tools, block = None, None, False
+    for line in lines[1:]:
+        if line.strip() == "---":
+            break
+        if block and line.lstrip().startswith("- "):
+            tools.append(line.strip()[2:].strip().strip("'\""))
+            continue
+        block = False
+        key, _sep, value = line.partition(":")
+        value = value.strip()
+        if key == "name":
+            name = value.strip("'\"")
+        elif key == "tools":
+            if value:
+                tools = [item.strip().strip("'\"") for item in value.strip("[]").split(",") if item.strip()]
+            else:
+                tools, block = [], True
+    return name, tools
+
+
+def agent_has_smart_tool(agent_type, cwd):
+    """Whether the subagent running the call can call the Smart Tool MCP tools: denying a native tool to an agent that
+    has no replacement only makes it give up. Agents defined in .claude/agents (user or project) are read; unknown
+    agents keep the redirect."""
+    if not agent_type:
+        return True
+    if agent_type in BUILTIN_AGENTS_WITHOUT_MCP:
+        return False
+    for folder in (os.path.join(cwd or "", ".claude", "agents"), os.path.join(endpoint_sync.claude_dir(), "agents")):
+        try:
+            names = sorted(os.listdir(folder))
+        except OSError:
+            continue
+        for entry in names:
+            if not entry.endswith(".md"):
+                continue
+            try:
+                name, tools = _frontmatter(os.path.join(folder, entry))
+            except (OSError, UnicodeDecodeError):
+                continue
+            if (name or entry.split(".")[0]) != agent_type:
+                continue
+            return tools is None or any(tool == "*" or tool.startswith(f"mcp__{SMART_TOOL_SERVER}") for tool in tools)
+    return True
+
+
+def _search_root(tool_input, cwd):
+    """project_root for smart_search: the registered project holding what the call searches (its path field, or the
+    first existing path of the command, after any `cd`), else that directory; the session directory when the call
+    names no path."""
+    raw = router._target_path(tool_input, cwd)
+    paths = [router._resolve_path(raw, cwd)] if raw else router._command_paths(tool_input.get("command"), cwd)
+    target = os.path.abspath(next((p for p in paths if p), None) or cwd or ".")
+    if os.path.isfile(target):
+        target = os.path.dirname(target)
+    key = os.path.normcase(target) + os.sep
+    roots = [p["root"] for p in project_store.all_projects()
+             if key.startswith(os.path.normcase(os.path.abspath(p["root"])).rstrip(os.sep) + os.sep)]
+    return max(roots, key=len) if roots else target
+
+
+def _tool_name(client, tool):
+    return f"mcp__{SMART_TOOL_SERVER}__{tool}" if client == "claude" else f"the {tool} tool of the {SMART_TOOL_SERVER} MCP server"
+
+
+def _load_hint(client, tool):
+    """Claude Code defers MCP tools behind tool search: a blocked agent may not have the schema loaded yet."""
+    if client != "claude":
+        return ""
+    return f' If it is not in your tool list yet, load it first with ToolSearch, query "select:mcp__{SMART_TOOL_SERVER}__{tool}".'
+
+
+def redirect_message(client, tool_name, tool_input, reason, cwd):
+    """Deny text for a broad raw search: the exact tool and arguments to call, and that rewriting the same search in
+    Bash, python, node or PowerShell is the bypass the rule exists to stop."""
+    root = _search_root(tool_input, cwd).replace("\\", "/")
+    return (f"Blocked by Smart Tool, a routing rule set by the user, not a failure ({tool_name}: {clean_reason(reason)}). "
+            f'Run this search with {_tool_name(client, "smart_search")}: project_root="{root}", query_identifiers = what '
+            f"you are looking for in identifier terms (plus query_comments when the project has two languages)."
+            f'{_load_hint(client, "smart_search")} Do not repeat the same search through Bash, python, node or '
+            f"PowerShell: that bypasses the rule. Reading one known file, or searching inside one known file, is never "
+            f"blocked.")
+
+
+def web_message(client, tool_name, url, why):
+    """Deny text for native WebFetch/WebSearch: the Smart Tool call to make instead, with the URL filled in."""
+    if tool_name == "WebFetch":
+        call = f'{_tool_name(client, "web_fetch")} with url="{url}" and prompt = what you need from the page'
+        tool, fetchers = "web_fetch", "curl, wget, python or PowerShell"
+    else:
+        call = f"{_tool_name(client, 'web_search')} with query (and query_en in English)"
+        tool, fetchers = "web_search", "curl, a browser script or another search tool"
+    return (f"Blocked by Smart Tool, a routing rule set by the user, not a failure. Call {call}: {why}"
+            f"{_load_hint(client, tool)} Do not fetch it through {fetchers}: that bypasses the rule.")
+
+
 def smart_tool_in_session(cwd):
     """Claude Code loads MCP servers from ~/.claude.json (user and per project) and the project's .mcp.json."""
     with open(endpoint_sync.claude_json(), encoding="utf-8") as stream:
@@ -149,7 +257,8 @@ def _edit_review(payload, doc_mode, duplicate_mode):
 
 def decide(payload, client, web_route):
     """Hook output for one PreToolUse payload: edits follow doc_mode (require | remind | off) and duplicate_mode
-    (warn | off), the other tools follow hook_mode (redirect | advise | off)."""
+    (warn | off), the other tools follow hook_mode (redirect | advise | off). A subagent whose tool list has no
+    Smart Tool MCP tool is never redirected: it has nothing to switch to."""
     cfg = config.load_config()
     if isinstance(payload, dict) and payload.get("tool_name") in EDIT_TOOLS:
         doc_mode, duplicate_mode = config.doc_mode(cfg), config.duplicate_mode(cfg)
@@ -161,6 +270,9 @@ def decide(payload, client, web_route):
         return {}
     output = _route(payload, client, web_route, cfg)
     reason = (output.get("hookSpecificOutput") or {}).get("permissionDecisionReason")
+    if reason and not agent_has_smart_tool(payload.get("agent_type") if payload.get("agent_id") else None,
+                                           payload.get("cwd")):
+        return {}
     return advise(reason) if mode == "advise" and reason else output
 
 
@@ -178,8 +290,9 @@ def _route(payload, client, web_route, cfg):
             present = False
         if not present:
             return {}
-        decision = web_route(tool_name, str(tool_input.get("url") or ""))
-        return deny(clean_reason(decision.get("reason"))) if decision.get("redirect") else {}
+        url = str(tool_input.get("url") or "")
+        decision = web_route(tool_name, url)
+        return deny(web_message(client, tool_name, url, clean_reason(decision.get("reason")))) if decision.get("redirect") else {}
     router.CLIENT.set(client)
     try:
         decision, reason = router.decide(tool_name, tool_input, router_model, cwd=cwd)
@@ -190,5 +303,5 @@ def _route(payload, client, web_route, cfg):
             pass
         return {"systemMessage": f"Smart Tool unavailable, routing skipped: {type(exc).__name__}"}
     if decision == "redirect":
-        return deny(f"Use smart_search instead of raw {tool_name}: {clean_reason(reason)}")
+        return deny(redirect_message(client, tool_name, tool_input, reason, cwd))
     return {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allansantos-dev/smart-tool",
-  "version": "0.9.5",
+  "version": "0.9.6",
   "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/router.py

@@ -74,6 +74,7 @@ _HEAVY_DIR_NAMES = frozenset({
 # dos de cima superestimaria o custo e enviesaria a decisão pra `redirect`.
 _IGNORED_BY_DEFAULT_DIRS = frozenset({".git", "__pycache__", ".mypy_cache", ".pytest_cache"})
 _PATH_FIELDS = ("path", "file_path", "notebook_path")
+_RECURSIVE_RE = re.compile(r"\b(?:grep|egrep|fgrep)\s+(?:-\w+\s+)*-\w*[rR]|\b(?:rg|find|fd|tree)\s|\bls\s+-\w*R|-Recurse\b")
 
 
 def _resolve_path(raw, cwd):
@@ -107,6 +108,9 @@ def _command_paths(command, cwd):
     previous, base = "", cwd
     for token in re.findall(r'"([^"]+)"|\'([^\']+)\'|(\S+)', command or ""):
         raw = next((t for t in token if t), "")
+        if token[2]:
+            # `cd dir; grep x file`: the separator sticks to the unquoted word before it.
+            raw = raw.rstrip(";")
         after_cd, previous = previous.lower() in ("cd", "pushd", "set-location", "sl"), raw
         if after_cd:
             # The directory of a `cd` is where the command runs (base for what follows), not what it searches.
@@ -167,6 +171,9 @@ def _target_facts(tool_name, tool_input, cwd):
     raw = _target_path(tool_input, cwd)
     if raw is None and tool_name == "Bash":
         candidates = _command_paths(tool_input.get("command"), cwd)
+        if candidates and _RECURSIVE_RE.search(tool_input.get("command") or ""):
+            # `sed -n 1,9p a.py; grep -rn x src`: the recursive part is the cost, not the file read before it.
+            candidates = [c for c in candidates if os.path.isdir(c)] or candidates
         if candidates:
             raw = candidates[0]
     scope_note = None
@@ -308,6 +315,22 @@ _READ_PRODUCER_RE = re.compile(
     re.IGNORECASE,
 )
 _READ_TOOLS = frozenset({"Read", "NotebookRead"})
+# Commands that change files, the repository or dependencies are never redirected (smart_search cannot do the change).
+# Verbs are matched outside quoted strings, so a grep pattern like "pip install" is not one; file writes inside an
+# inline script (node -e, python -c) are matched anywhere.
+_QUOTED_RE = re.compile(r"""'[^']*'|"(?:\\.|[^"\\])*\"""")
+_MUTATING_VERB_RE = re.compile(
+    r"(?:^|[;&|(]|\s)(?:rm|mv|cp|mkdir|rmdir|touch|chmod|tee)\s"
+    r"|\bgit\s+(?:-C\s+\S+\s+)?(?:checkout|commit|add|push|pull|reset|stash|restore|rm|mv|merge|rebase|apply|tag|clean|"
+    r"clone|switch|cherry-pick)\b|\bsed\s+-i"
+    r"|\b(?:npm|pnpm|yarn|pip|uv)\s+(?:install|i|add|run|publish|ci|test)\b"
+)
+_FILE_WRITE_RE = re.compile(r"writeFileSync|writeFile\(|write_text\(|Set-Content|Out-File")
+
+
+def _mutates(command):
+    """Whether a shell command changes files, the repository or dependencies."""
+    return bool(_FILE_WRITE_RE.search(command) or _MUTATING_VERB_RE.search(_QUOTED_RE.sub("''", command)))
 
 BREAKER_PATH = os.path.join(os.path.dirname(METRICS_PATH), "router-breaker.json")
 BREAKER_FAILURES = 3
@@ -324,7 +347,9 @@ def _mechanical_decision(tool_name, tool_input):
     `offset`/`limit` explícitos, onde só as linhas pedidas servem). Remedido em 2026-10-08
     sobre 2488 Bash que foram ao modelo (mediana 1,5 s, 7,8% redirecionados): ignorar os
     filtros depois de `|` (salvo quando o produtor lê código ou páginas) decide 439 deles
-    sem modelo (13,3 min em 58 h) e perde 1 dos 155 redirecionamentos."""
+    sem modelo (13,3 min em 58 h) e perde 1 dos 155 redirecionamentos. Remedido em 2026-10-09 sobre 3294 Bash decididos
+    pelo modelo: comandos que alteram arquivos, o repositório ou dependências foram 12 dos 283 redirecionamentos (todos
+    errados: o agente contornava o bloqueio) e 566 liberações."""
     if tool_name in _READ_TOOLS:
         return "allow", "Reading a specific file is never replaced by semantic search."
     if tool_name == "Bash":
@@ -333,6 +358,8 @@ def _mechanical_decision(tool_name, tool_input):
             return "allow", "Bash without a readable command."
         if not _SEARCH_VERB_RE.search(command) and not _READ_PRODUCER_RE.search(command):
             return "allow", "The command neither searches nor reads source code."
+        if _mutates(command):
+            return "allow", "The command changes files, the repository or dependencies."
     return None
 
 

package/smart_tool_daemon.py

@@ -300,6 +300,20 @@ def _smart_search_job_payload(job_id):
         payload['view'] = job['view']
     return payload
 
+# Claude Code defers MCP tools behind tool search; the tools the hook redirects to (and their job polling) load
+# upfront, so a blocked agent already has the replacement in its tool list.
+ALWAYS_LOAD = {"anthropic/alwaysLoad": True}
+SERVER_INSTRUCTIONS = (
+    "Smart Tool serves an indexed semantic search over the user's projects and a cheaper web reader. The user installed "
+    "a PreToolUse hook that blocks broad raw searches (recursive grep/find/ls, wide Glob/Grep) and native "
+    "WebFetch/WebSearch. A call blocked by Smart Tool is a routing rule, not a failure: make the call the block "
+    "message names (smart_search with project_root and query_identifiers, web_fetch with url and prompt, web_search "
+    "with query). Never retry the same search or download through Bash, python, node, PowerShell, curl or wget: that "
+    "bypasses the rule the user set. Reading one known file, or searching inside one known file, is never blocked. "
+    "Before changing a function, project_manage action=graph with symbol lists its callers and tests; after editing, "
+    "project_manage action=affected_tests lists the tests to run."
+)
+
 TOOLS = [
     {
         "name": "project_manage",
@@ -339,6 +353,7 @@ TOOLS = [
     },
     {
         "name": "smart_search",
+        "_meta": ALWAYS_LOAD,
         "description": (
             "Semantic search (embed+rerank) over the project's index. Use instead of "
             "raw grep/read when the search has no clear scope (e.g. a folder with node_modules). "
@@ -372,6 +387,7 @@ TOOLS = [
     },
     {
         "name": "smart_search_result",
+        "_meta": ALWAYS_LOAD,
         "description": (
             "Checks the progress and result of a background smart_search. "
             "Pass the job_id returned by smart_search; while pending, wait retry_after_s and check again."
@@ -386,6 +402,7 @@ TOOLS = [
     },
     {
         "name": "web_search",
+        "_meta": ALWAYS_LOAD,
         "description": (
             "Web search with curated results (title/url/snippet) - use instead of "
             "the native WebSearch: several sources in parallel, the query in two languages and a cache shared across sessions. Starts with free HTTP "
@@ -433,6 +450,7 @@ TOOLS = [
     },
     {
         "name": "web_fetch",
+        "_meta": ALWAYS_LOAD,
         "description": (
             "Reads a known URL and returns only the answer to the prompt, written by the gateway's mini model - use instead of "
             "the native WebFetch. The page is cached for 24 h: another prompt on the same URL does not download it again. "
@@ -449,6 +467,7 @@ TOOLS = [
     },
     {
         "name": "web_search_result",
+        "_meta": ALWAYS_LOAD,
         "description": (
             "Checks the status/result of a deep research job "
             "(web_search with depth='deep' or depth='research')."
@@ -3243,10 +3262,9 @@ def _web_route(tool, url):
     if problem:
         return {"redirect": False, "reason": f"gateway unavailable: {problem}"}
     if tool == "WebFetch":
-        return {"redirect": True, "reason": "Use the web_fetch tool from the smart-tool MCP (url + prompt): the mini model reads "
-                "the page, the answer comes back short and the page is cached for 24 h."}
-    return {"redirect": True, "reason": "Use the web_search tool from the smart-tool MCP (query + query_en): several sources, "
-            "two languages and a cache shared across sessions."}
+        return {"redirect": True, "reason": "the mini model reads the page, the answer comes back short and the page is "
+                "cached for 24 h."}
+    return {"redirect": True, "reason": "several sources, two languages and a cache shared across sessions."}
 
 
 HOOK_MAX_BODY_BYTES = 4 * 1024 * 1024
@@ -3330,6 +3348,7 @@ def _dispatch(method, params, session_id):
             "protocolVersion": PROTOCOL_VERSION,
             "capabilities": {"tools": {}},
             "serverInfo": {"name": "smart-tool", "version": version.VERSION},
+            "instructions": SERVER_INSTRUCTIONS,
         }
     if method == "tools/list":
         return {"tools": TOOLS}

package/tray.py

@@ -20,8 +20,10 @@ import pystray
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 import autostart
+import config
 import daemon_launcher
 import update_check
+import version
 
 POLL_INTERVAL_S = 45
 UPDATE_CHECK_INTERVAL_S = 24 * 3600
@@ -110,6 +112,9 @@ def _poll_loop(icon):
 
 
 def _update_loop(icon):
+    """Checks npm at start and every 24 h. At start (logon, before agent sessions use the daemon) a newer version is
+    installed right away when auto_update is on; later checks only notify and offer it in the menu."""
+    first = True
     while True:
         try:
             latest = update_check.newer_version()
@@ -118,19 +123,56 @@ def _update_loop(icon):
         if latest and latest != _state["update"]:
             _state["update"] = latest
             icon.update_menu()
-            icon.notify(f"Smart Tool {latest} is available. Update with: {update_check.UPDATE_COMMAND}", "Smart Tool")
+            if first and config.auto_update() and update_check.should_auto_update(latest):
+                icon.notify(f"Updating Smart Tool to {latest}...", "Smart Tool")
+                update_check.run_update(latest, automatic=True)
+            else:
+                icon.notify(f"Smart Tool {latest} is available: use \"Update to {latest}\" in this menu.", "Smart Tool")
+        first = False
         time.sleep(UPDATE_CHECK_INTERVAL_S)
 
 
 def _update_label(item):
-    return f"Update to {_state['update']} (copy command)"
+    return f"Update to {_state['update']}" if _state["update"] else "Check for updates"
+
+
+_update_busy = threading.Lock()
+
+
+def _update_now(icon, item):
+    """Menu action: installs the known newer version, or checks npm first and says when there is none."""
+    if not _update_busy.acquire(blocking=False):
+        return
+
+    def run():
+        try:
+            latest = _state["update"] or update_check.newer_version()
+            if not latest:
+                icon.notify(f"Smart Tool {version.VERSION} is the latest version.", "Smart Tool")
+                return
+            _state["update"] = latest
+            icon.update_menu()
+            update_check.run_update(latest, automatic=False)
+        except Exception as exc:
+            icon.notify(f"Could not update: {exc}", "Smart Tool")
+        finally:
+            _update_busy.release()
+    threading.Thread(target=run, daemon=True).start()
+
 
+def _auto_update_checked(item):
+    try:
+        return config.auto_update()
+    except Exception:
+        return False
 
-def _copy_update_command(icon, item):
-    import subprocess
-    subprocess.run(["clip.exe"], input=update_check.UPDATE_COMMAND.encode("ascii"), check=True,
-                   creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0))
-    icon.notify(f"Copied: {update_check.UPDATE_COMMAND}. Paste it in a terminal.", "Smart Tool")
+
+def _toggle_auto_update(icon, item):
+    try:
+        config.update_config(lambda cfg: cfg.__setitem__("auto_update", not config.auto_update(cfg)))
+    except Exception as exc:
+        icon.notify(f"Could not change automatic updates: {exc}", "Smart Tool")
+    icon.update_menu()
 
 
 def _open_setup(icon, item):
@@ -227,7 +269,8 @@ def main():
             pystray.MenuItem("Index a folder…", _add_project),
             pystray.MenuItem("Open settings", _open_setup),
             pystray.MenuItem("Start with Windows", _toggle_autostart, checked=_autostart_checked),
-            pystray.MenuItem(_update_label, _copy_update_command, visible=lambda item: bool(_state["update"])),
+            pystray.MenuItem(_update_label, _update_now),
+            pystray.MenuItem("Update automatically", _toggle_auto_update, checked=_auto_update_checked),
             pystray.MenuItem("Quit", _quit),
         ),
     )

package/update_check.py

@@ -1,12 +1,19 @@
-"""Newer Smart Tool release on npm, for the tray notice. Updating is running the install command again."""
+"""Newer Smart Tool release on npm and the update itself: the tray runs the same install command a user would, in a
+visible console, at startup (once per version, when auto_update is on) or on demand from its menu."""
 import json
+import os
+import subprocess
+import time
 import urllib.request
 
+import atomic_io
+import paths
 import version
 
 PACKAGE = "@allansantos-dev/smart-tool"
 REGISTRY_URL = "https://registry.npmjs.org/@allansantos-dev%2Fsmart-tool/latest"
-UPDATE_COMMAND = f"npx {PACKAGE}@latest install"
+UPDATE_COMMAND = f"npx --yes {PACKAGE}@latest install"
+STATE_PATH = os.path.join(paths.DATA_DIR, "update-state.json")
 
 
 def _parts(value):
@@ -20,3 +27,30 @@ def newer_version(timeout=10):
     with urllib.request.urlopen(request, timeout=timeout) as response:
         latest = json.load(response)["version"]
     return latest if _parts(latest) > _parts(version.VERSION) else None
+
+
+def attempted():
+    """Version the last automatic update went for, or None."""
+    try:
+        with open(STATE_PATH, encoding="utf-8") as stream:
+            return json.load(stream).get("attempted")
+    except FileNotFoundError:
+        return None
+
+
+def should_auto_update(latest):
+    """An automatic update runs once per version: when it fails, the installer restores the previous version and
+    restarts the tray, which would otherwise try the same version again on every start."""
+    return bool(latest) and attempted() != latest
+
+
+def run_update(latest, automatic):
+    """Starts the install command in its own visible console, detached from the tray (the installer stops and restarts
+    the tray). The console closes on success and stays open with the error on failure."""
+    if automatic:
+        os.makedirs(os.path.dirname(STATE_PATH), exist_ok=True)
+        atomic_io.write_secret_text(STATE_PATH, json.dumps({"attempted": latest, "at": time.time()}))
+    flags = getattr(subprocess, "CREATE_NEW_CONSOLE", 0) | getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+    command = f'title Smart Tool update to {latest} && {UPDATE_COMMAND} || pause'
+    subprocess.Popen(["cmd.exe", "/c", command], creationflags=flags, close_fds=True,
+                     cwd=os.path.expanduser("~"))

package/version.py

@@ -1,7 +1,7 @@
 """Single source of the Smart Tool version and of the User-Agent sent to public APIs."""
 import re
 
-VERSION = "0.9.5"
+VERSION = "0.9.6"
 _CONTACT_RE = re.compile(r"^(?:[^\s@()<>;]+@[^\s@()<>;]+\.[^\s@()<>;]+|https?://[^\s()<>;]+)$")