@allansantos-dev/smart-tool 0.9.4 → 0.9.6

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # 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.
+
+- `affected_tests` answered "no tests" for a module covered by a 1.4 MB test file (1,427 cases): the file was over the
+  index size limit and the working-tree reading skipped files over 1 MB, so it fell out of the import graph silently.
+  Files up to 5 MB are now analyzed for the graph, and any tracked test file still outside it is selected ("may cover
+  the change") instead of disappearing.
+- Tests that run a script by path (`spawnSync('node', [path.join(SCRIPTS, 'hook.js')])`, `subprocess.run(["python",
+  "tools/x.py"])`) now depend on that script: a file name in a string literal of a test, resolved against the test's
+  folder, the folders above it and the project root, links them.
+- A test is left out of the list only when it has no test cases (`conftest.py`, fixtures, helpers). The former rule
+  ("imported by another test") dropped real Java tests that share test types: on gson it caught 19 of 28 injected
+  faults; now 28 of 28. JUnit 3 suites (`@RunWith(AllTests.class)`, `static Test suite()`) count as tests.
+- Test files named in `package.json` scripts (`"test": "node scripts/test-units.js"`) get a `node <file>` command.
+- An anonymous callback among the touched functions is named after the function that contains it.
+- `project_manage register` and `status` return the project with its last jobs summarized and without the scope's
+  folder structure and profile groups (`scope_summary` keeps include/exclude): they returned the full result of every
+  past search (108-128 thousand characters on one project, now 3.3 thousand). The projects screen keeps the full
+  payload.
+- A project is no longer marked `degraded` because the per-chunk function analysis was still being prepared: that note
+  is shown with the search results but is not a degradation.
+
 ## 0.9.4 - beta
 
 Found by using 0.9.3 on its own repository right after installing it.

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/affected_tests.py

@@ -1,12 +1,13 @@
 """Tests to run for the current changes: git diff against a base (default HEAD, so staged, unstaged and untracked
 files), then every test file that imports a changed file directly or through other files, plus changed tests, ordered
 so the most likely failures come first (tests calling a touched function, test file named after the function or the
-module, import distance). Test support files (conftest.py, helpers other tests import) carry the selection but are
-not listed to run. Selection by file imports, not by calls: in fault-injection measurements on Python,
+module, import distance). Test support files (conftest.py, fixtures and helpers without test cases) carry the
+selection but are not listed to run. Selection by file imports, not by calls: in fault-injection measurements on Python,
 JavaScript, TypeScript and Java projects static calls alone found 2 to 37% of the failing test files."""
 import ast
 import json
 import os
+import posixpath
 import re
 import subprocess
 from collections import defaultdict, deque
@@ -30,6 +31,8 @@ NOTE = ("Selection from the indexed import graph: tests that load code through s
         "suite before committing; run_all is true when a changed file can change every test (config, lockfile, "
         "unanalyzed code). Changed files and files committed after the last indexing are read from disk, so new "
         "files and imports count before reindexing; pytest fixtures link a test to the conftest.py that defines them.")
+TEST_SOURCES = (".py", ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".mts", ".cts", ".java")
+_PATH_LITERAL = re.compile(r"""['"`]((?:\.{0,2}/)?[\w.-]+(?:/[\w.-]+)*\.(?:py|js|mjs|cjs|ts|mts|cts|java))['"`]""")
 _HUNK = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@", re.M)
 
 
@@ -122,6 +125,10 @@ def _commands(root, tests):
             runner = next((cmd for key, cmd in (("vitest", "npx vitest run"), ("jest", "npx jest"),
                                                 ("mocha", "npx mocha"), ("node --test", "node --test"))
                            if key in tools), None)
+            local = os.path.relpath(path, folder or ".").replace(os.sep, "/")
+            scripts = " ".join(str(v) for v in (package.get("scripts") or {}).values())
+            if runner is None and re.search(rf"\bnode\s+(\./)?{re.escape(local)}\b", scripts):
+                runner = "node-script"
             groups[(folder or "", runner)].append(path)
         elif lower.endswith(".java"):
             folder, name = _nearest(root, path, ("pom.xml", "build.gradle", "build.gradle.kts"))
@@ -138,6 +145,9 @@ def _commands(root, tests):
         if runner == "maven":
             names = ",".join(sorted({os.path.basename(f).rsplit(".", 1)[0] for f in files}))
             line = f"mvn test -Dtest={names} -Dsurefire.failIfNoSpecifiedTests=false"
+        elif runner == "node-script":
+            commands.extend({"cwd": folder or ".", "command": f"node {f}"} for f in sorted(local))
+            continue
         elif runner == "unittest-package":
             line = "python -m unittest " + " ".join(sorted(f[:-3].replace("/", ".") for f in files))
         elif runner == "unittest-folder":
@@ -194,6 +204,75 @@ def _fixture_users(root, test_files):
     return users
 
 
+def _path_literal_users(root, test_files, known):
+    """Code files a test names in a string literal ('graph-guard.js', "scripts/run.py"), resolved against the test's
+    folder, the folders above it and the project root: tests that run scripts as subprocesses or load them by path
+    (spawnSync('node', [path.join(SCRIPTS, 'hook.js')])) depend on them without importing them."""
+    users = defaultdict(set)
+    for test in test_files:
+        if not test.lower().endswith(TEST_SOURCES):
+            continue
+        source = _read(os.path.join(root, test))
+        folders, folder = [], os.path.dirname(test)
+        while True:
+            folders.append(folder)
+            if not folder:
+                break
+            folder = os.path.dirname(folder)
+        for literal in set(_PATH_LITERAL.findall(source)):
+            for base in folders:
+                candidate = posixpath.normpath(posixpath.join(base, literal.removeprefix("./")))
+                if candidate in known and candidate != test:
+                    users[candidate].add(test)
+                    break
+    return users
+
+
+_TEST_CASES = {
+    ".py": re.compile(r"^\s*(async\s+)?def\s+test\w*\s*\(|^\s*class\s+Test\w*|unittest\.TestCase", re.M),
+    ".java": re.compile(r"@(Test|ParameterizedTest|RepeatedTest|TestFactory|TestTemplate|RunWith|Suite)\b|"
+                        r"\bstatic\s+\w*Test\s+suite\s*\(|\bextends\s+TestCase\b|\bvoid\s+test\w*\s*\("),
+    "script": re.compile(r"\b(it|test|describe|suite)(\.\w+)?\s*\(|\bDeno\.test\b|\bnode:test\b|\bassert\b"),
+}
+
+
+def _support(root, path):
+    """Test-kind file without test cases (conftest.py, fixtures, helpers): it carries the selection but is not run.
+    A test referenced by another test (shared Java test types) is still a test."""
+    if os.path.basename(path) == "conftest.py":
+        return True
+    ext = os.path.splitext(path)[1].lower()
+    pattern = _TEST_CASES.get(ext) or (_TEST_CASES["script"] if ext in TEST_SOURCES else None)
+    source = _read(os.path.join(root, path))
+    return bool(pattern and source and not pattern.search(source))
+
+
+def _tracked_tests_outside_graph(root, parsed, profile):
+    """Code test files git tracks that the graph could not analyze (over the size limits, unreadable): their imports
+    are unknown, so they are selected instead of silently missing (a 1.4 MB test file covering 1,427 cases did)."""
+    listed = subprocess.run(["git", "ls-files", "-z"], cwd=root, capture_output=True, timeout=30)
+    if listed.returncode:
+        return []
+    tests = []
+    for rel in listed.stdout.decode("utf-8", "replace").split("\0"):
+        if rel and rel not in parsed and rel.lower().endswith(TEST_SOURCES) and os.path.basename(rel) != "conftest.py" \
+                and index_profile.kind(rel, profile) == "test" and os.path.isfile(os.path.join(root, rel)):
+            tests.append(rel)
+    return tests
+
+
+def _label(symbol, by_id):
+    """path::name of a touched function; an anonymous callback is named after the function that contains it."""
+    short = symbol["name"].split("(")[0].split(".")[-1]
+    if short in ("callback", "anonymous"):
+        parent = by_id.get(symbol.get("parent"))
+        while parent and parent["name"].split("(")[0].split(".")[-1] in ("callback", "anonymous"):
+            parent = by_id.get(parent.get("parent"))
+        if parent:
+            return f"{symbol['path']}::{parent['name']} (callback at line {symbol['start_line']})"
+    return f"{symbol['path']}::{symbol['name']}"
+
+
 def affected(root, base="HEAD", limit=30, view_id=None):
     """Test files to run for the changes since base, most likely failures first, with the command to run them."""
     if not isinstance(base, str) or not re.fullmatch(r"[\w./@^~{}-]{1,200}", base) or base.startswith("-"):
@@ -217,6 +296,8 @@ def affected(root, base="HEAD", limit=30, view_id=None):
         callers[call["target"]].add(call["source"])
     for conftest, users in _fixture_users(root, test_files).items():
         importers[conftest] |= users
+    for target, users in _path_literal_users(root, test_files, {f["path"] for f in data.get("files") or []}).items():
+        importers[target] |= users
     by_id = {s["id"]: s for s in data.get("symbols") or []}
     run_all, not_analyzed, changed_code, changed_tests, conftests = [], [], [], [], []
     for path, change in sorted(changes.items()):
@@ -260,9 +341,11 @@ def affected(root, base="HEAD", limit=30, view_id=None):
                 selected.setdefault(test, f"{conftest} changed")
     for test in set(import_depth) | set(call_hops):
         selected.setdefault(test, None)
-    support = {p for p in test_files if os.path.basename(p) == "conftest.py"
-               or any(source in test_files for source in importers.get(p, ()))}
-    selected = {test: reason for test, reason in selected.items() if test not in support}
+    selected = {test: reason for test, reason in selected.items() if not _support(root, test)}
+    if changed_code or conftests:
+        for test in _tracked_tests_outside_graph(root, parsed, profile):
+            selected.setdefault(test, "test file outside the import graph (too large or not analyzed): may cover "
+                                      "the change")
 
     def why(test):
         if selected[test]:
@@ -283,7 +366,7 @@ def affected(root, base="HEAD", limit=30, view_id=None):
         "base": base,
         "changed": {"code": changed_code[:limit], "tests": changed_tests[:limit],
                     "other": sorted(p for p in changes if p not in changed_code and p not in changed_tests)[:limit]},
-        "touched_functions": [f"{s['path']}::{s['name']}" for s in touched][:limit],
+        "touched_functions": [_label(s, by_id) for s in touched][:limit],
         "tests": [{"path": t, "why": why(t)} for t in ordered[:limit]],
         "counts": {"changed_files": len(changes), "tests": len(ordered), "test_files": len(test_files)},
         "run_all": bool(run_all),

package/code_graph.py

@@ -23,7 +23,7 @@ import document_text
 
 VERSION = 2
 SOURCE_EXTENSIONS = ('.py','.java','.js','.jsx','.ts','.tsx','.mjs','.cjs','.mts','.cts','.json','.html','.htm','.css','.scss','.sass','.less','.md','.markdown')
-MAX_OVERLAY_BYTES = 1024 * 1024
+MAX_OVERLAY_BYTES = 5 * 1024 * 1024
 MAX_FILES = 3000
 MAX_TEXT = 24 * 1024 * 1024
 MAX_SYMBOLS = 8000

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.4",
+  "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')."
@@ -968,8 +987,10 @@ def _perform_smart_search_isolated(arguments, job_id):
                                      else ({}, None))
     except Exception as exc:
         symbol_index, symbol_note = None, f"Function analysis failed: {_project_error(exc)}"
+    notes = []
     if symbol_index is None and any(group != "doc" for group in groups):
-        warnings.append(symbol_note or "Per-chunk functions are being prepared; they will show on the next search.")
+        (warnings if symbol_note else notes).append(
+            symbol_note or "Per-chunk functions are being prepared; they will show on the next search.")
     elif symbol_note or (symbol_index or {}).get("note"):
         warnings.append(symbol_note or symbol_index["note"])
     query_terms = _symbol_terms(" ".join(queries[group] for group in groups if group != "doc"))
@@ -1013,7 +1034,7 @@ def _perform_smart_search_isolated(arguments, job_id):
     warning = " ".join(warnings)
     if warning:
         _update_job(job_id, warning=warning)
-    return _grouped_yaml(index_profile.public(profile), blocks, warning)
+    return _grouped_yaml(index_profile.public(profile), blocks, " ".join(warnings + notes))
 
 
 def _perform_project_index(arguments, job_id, preview=False):
@@ -1717,11 +1738,31 @@ def _project_action_locked(arguments):
     return {"project": _project_payload(project_store.get(key))}
 
 
+def _for_agent(result):
+    """register/status for an agent: the project without the full result of every past job, the folder structure of
+    the scope and the profile groups (one project returned 128 thousand characters, more than an MCP client shows);
+    scope_summary keeps include/exclude. The projects screen keeps the full payload."""
+    project = result.get("project") if isinstance(result, dict) else None
+    if isinstance(project, dict) and isinstance(project.get("jobs"), list):
+        project["jobs"] = [{key: job.get(key) for key in ("job_id", "status", "kind", "phase", "updated_at", "warning",
+                                                          "error") if job.get(key) not in (None, "")}
+                           for job in project["jobs"][:5]]
+    if isinstance(project, dict):
+        if isinstance(project.get("preview"), dict):
+            project["preview"] = {key: project["preview"].get(key)
+                                  for key in ("included_files", "eligible_files", "bytes", "skipped")}
+        project.pop("scope", None)
+    return result
+
+
 def _handle_project_manage(arguments):
     # MCP não abre janelas; o seletor nativo pertence apenas à interface local.
     if isinstance(arguments, dict) and arguments.get("action") == "pick":
         raise ValueError("Use register with project_root or pick the folder from the tray.")
-    return _to_json_sanitized(_project_action(arguments))
+    result = _project_action(arguments)
+    if isinstance(arguments, dict) and arguments.get("action") in ("register", "status"):
+        result = _for_agent(result)
+    return _to_json_sanitized(result)
 
 
 def _enqueue_monitored_project(project_id, **options):
@@ -3221,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
@@ -3308,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.4"
+VERSION = "0.9.6"
 _CONTACT_RE = re.compile(r"^(?:[^\s@()<>;]+@[^\s@()<>;]+\.[^\s@()<>;]+|https?://[^\s()<>;]+)$")