@allansantos-dev/smart-tool 0.9.5 → 0.9.7

package/hook_decision.py

@@ -42,6 +42,109 @@ 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(target, cwd):
+    """project_root for smart_search: the registered project holding the folder the redirected search reads, else that
+    folder; the session folder when the rule names none."""
+    target = os.path.abspath(target or cwd or ".")
+    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, target, reason, cwd):
+    """Deny text for a broad raw search: the exact tool and arguments to call (project_root from the folder the search
+    reads), and that rewriting the same search in Bash, python, node or PowerShell is the bypass the rule stops."""
+    root = _search_root(target, 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 +252,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 +265,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
 
 
@@ -168,21 +275,21 @@ def _route(payload, client, web_route, cfg):
     tool_name = payload.get("tool_name", "")
     tool_input = payload.get("tool_input") if isinstance(payload.get("tool_input"), dict) else {}
     cwd = payload.get("cwd")
-    router_model = cfg.get("router_model")
-    if not router_model:
-        return {}
     if tool_name in WEB_TOOLS:
+        if not cfg.get("router_model"):
+            return {}
         try:
             present = smart_tool_in_session(cwd)
         except (OSError, ValueError):
             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)
+        decision, reason, target = router.decide(tool_name, tool_input, cwd=cwd)
     except Exception as exc:
         try:
             router.log_unavailable(tool_name, tool_input, exc)
@@ -190,5 +297,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, target, reason, cwd))
     return {}

package/index_scope.py

@@ -138,6 +138,32 @@ def load_scope(root):
     return None
 
 
+def sibling_scope(root):
+    """Scope of the most recently saved other Git view of the same project, or None. A new branch or a worktree starts
+    without a scope; asking the scope and profile models again cost ~28 s of a 52 s first search (measured 2026-10-09
+    on a branch at the same commit). The caller still checks it with needs_rescan before using it."""
+    if not index_views.describe(root).get("git"):
+        return None
+    own = scope_path(root)
+    prefix = project_identity.project_id(root) + ".v-"
+    try:
+        names = [n for n in os.listdir(SCOPE_DIR) if n.startswith(prefix) and n.endswith(".scope.json")]
+    except OSError:
+        return None
+    paths = sorted((os.path.join(SCOPE_DIR, n) for n in names), key=os.path.getmtime, reverse=True)
+    for path in paths:
+        if os.path.normcase(path) == os.path.normcase(own):
+            continue
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+        except (OSError, ValueError, UnicodeError):
+            continue
+        if valid_scope(data):
+            return data
+    return None
+
+
 def save_scope(root, scope):
     if not valid_scope(scope):
         raise ValueError("Scope must contain lists of paths in include/exclude.")

package/indexer.py

@@ -230,12 +230,28 @@ def migrate_legacy(root):
             if not old and index_views.describe(root).get('git'):
                 old = next((os.path.join(INDEX_DIR, key + '.sqlite3') for key in
                             [project_identity.project_id(root), *project_identity.legacy_ids(root)]
-                            if os.path.isfile(os.path.join(INDEX_DIR, key + '.sqlite3'))), None)
+                            if os.path.isfile(os.path.join(INDEX_DIR, key + '.sqlite3'))), None) or \
+                    _sibling_view_db(root, target)
             if old:
                 _backup(old, target)
     return target
 
 
+def _sibling_view_db(root, target):
+    """Most recently written index of another Git view of the same project, or None. A new branch or worktree starts
+    from its copy: the full content check a view change forces then reprocesses only the files that differ, instead
+    of chunking every file again (17 s of a 52 s first search on a branch at the same commit, measured 2026-10-09)."""
+    prefix = project_identity.project_id(root) + ".v-"
+    try:
+        names = os.listdir(INDEX_DIR)
+    except OSError:
+        return None
+    candidates = [os.path.join(INDEX_DIR, n) for n in names
+                  if n.startswith(prefix) and n.endswith(".sqlite3") and ".building-" not in n]
+    candidates = [p for p in candidates if os.path.normcase(p) != os.path.normcase(target)]
+    return max(candidates, key=os.path.getmtime, default=None)
+
+
 def _open_path(path):
     conn = sqlite3.connect(path, timeout=10)
     # `chunks.text` é conteúdo de arquivo em texto puro: sem isto, um DELETE só desliga a

package/package.json

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

@@ -0,0 +1,232 @@
+"""Deterministic redirect rule of the PreToolUse hook for native code searches (Grep, Glob, Bash).
+
+A content search over a directory of a project (grep -r, rg, git grep, the Grep tool on a folder) or over more than
+LISTED_MAX files goes to smart_search; reading listed files, listings, Glob and commands that change files run. Only
+the part of a Bash command that searches is measured, with its own paths: `cd` is carried, `$VAR` set in the command or
+in the environment, `~` and globs are expanded, and a path still holding an unresolved variable is left alone.
+
+Measured on 2026-10-09 against 2,789 real decisions of the LLM router it replaced (session cwd recovered from the
+transcripts): the model redirected 315, this rule 463 (134 shared); in a sample of 40 redirected by the rule alone, 40
+were content searches over a folder or many files; in a sample of 40 redirected by the model alone, ~36 were wrong
+(one file, `node -e` over one file, `git show`, listings, commands changing files). Median 0.2 ms against 1.5 s.
+"""
+import glob
+import os
+import re
+import shlex
+import time
+
+import index_scope
+import project_store
+
+LISTED_MAX = 20
+SCAN_MAX_FILES = 4000
+SCAN_MAX_SECONDS = 0.25
+# Trees the native tools walk into: their presence is part of the cost, they are counted.
+HEAVY_DIRS = frozenset({"node_modules", ".venv", "venv", "vendor", "target", "dist", "build", "out", ".next", ".nuxt",
+                        ".gradle", "Pods"})
+SEARCHERS = frozenset({"grep", "egrep", "fgrep", "rg", "ripgrep", "ack", "ag", "findstr", "select-string", "sls"})
+ALWAYS_RECURSIVE = frozenset({"rg", "ripgrep", "ack", "ag"})
+LISTERS = frozenset({"find", "fd", "ls", "dir", "tree", "get-childitem", "gci"})
+CD_VERBS = frozenset({"cd", "pushd", "set-location", "sl"})
+PATTERN_FLAGS = frozenset({"-e", "--regexp", "-f", "--file"})
+VALUE_FLAGS = frozenset({"-A", "-B", "-C", "-m", "--max-count", "--include", "--exclude", "--exclude-dir", "-g",
+                         "--glob", "-t", "--type", "-T", "--type-not", "--max-depth", "-d", "--context",
+                         "--after-context", "--before-context"})
+RECURSIVE_FLAGS = frozenset({"-r", "-R", "--recursive", "-Recurse", "/s", "/S"})
+_ASSIGN = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*)=(.*)$")
+_VARIABLE = re.compile(r"\$\{(\w+)\}|\$(\w+)")
+
+
+def resolve_path(raw, base):
+    """Path normalized for the disk: relative to base, and the MSYS `/c/...` form agents write in a POSIX shell on
+    Windows turned into `C:/...`."""
+    if not raw:
+        return None
+    path = raw.strip().replace("\\", "/")
+    msys = re.fullmatch(r"/([A-Za-z])(/.*)?", path)
+    if msys:
+        path = f"{msys.group(1).upper()}:{msys.group(2) or '/'}"
+    if not os.path.isabs(path) and base:
+        path = os.path.join(base, path)
+    return os.path.normpath(path)
+
+
+def count_files(path):
+    """(files, truncated) under a directory, skipping dot-directories, bounded by count and time."""
+    files, deadline = 0, time.monotonic() + SCAN_MAX_SECONDS
+    for _dirpath, dirnames, filenames in os.walk(path):
+        dirnames[:] = [d for d in dirnames if not d.startswith(".") and d != "__pycache__"]
+        files += len(filenames)
+        if files > SCAN_MAX_FILES or time.monotonic() > deadline:
+            return files, True
+    return files, False
+
+
+def _in_project(target, cwd):
+    """A registered project holds target, or target is inside the session's directory."""
+    key = os.path.normcase(os.path.abspath(target)) + os.sep
+    if any(key.startswith(os.path.normcase(os.path.abspath(p["root"])).rstrip(os.sep) + os.sep)
+           for p in project_store.all_projects()):
+        return True
+    return bool(cwd) and index_scope._within_root(cwd, target)
+
+
+def _has_files(target):
+    """Any file under the folder: the size limit measured made no difference (0 files: 463 redirects, 50: 400), and a
+    missed redirect costs more context than a needless one."""
+    files, truncated = count_files(target)
+    return truncated or files > 0
+
+
+def segments(command):
+    """(text, after_single_pipe) of each part of a shell command split on ; && || | and newlines outside quotes."""
+    parts, current, quote, i, after_pipe = [], [], None, 0, False
+    while i < len(command):
+        ch = command[i]
+        if quote:
+            current.append(ch)
+            quote = None if ch == quote else quote
+        elif ch in "'\"":
+            quote = ch
+            current.append(ch)
+        elif command.startswith(("&&", "||"), i):
+            parts.append(("".join(current), after_pipe))
+            current, after_pipe = [], False
+            i += 2
+            continue
+        elif ch in ";\n|":
+            parts.append(("".join(current), after_pipe))
+            current, after_pipe = [], ch == "|"
+        else:
+            current.append(ch)
+        i += 1
+    parts.append(("".join(current), after_pipe))
+    return [(text.strip(), pipe) for text, pipe in parts if text.strip()]
+
+
+def _expand(token, variables):
+    def substitute(match):
+        name = match.group(1) or match.group(2)
+        return variables.get(name, os.environ.get(name, match.group(0)))
+    return os.path.expanduser(_VARIABLE.sub(substitute, token))
+
+
+def _paths(raw, base):
+    """Existing paths of a token (globs expanded), or None when it still holds an unresolved variable."""
+    if "$" in raw or "`" in raw:
+        return None
+    path = resolve_path(raw, base)
+    if any(ch in raw for ch in "*?["):
+        return [os.path.normpath(p) for p in glob.glob(path)]
+    return [path] if path and os.path.exists(path) else []
+
+
+def _search_args(verb, tokens):
+    """Path arguments of a grep-like command (the pattern and flag values dropped) and whether it is recursive."""
+    recursive = verb in ALWAYS_RECURSIVE or any(
+        t in RECURSIVE_FLAGS or (re.fullmatch(r"-[a-zA-Z]+", t) and ("r" in t or "R" in t)) for t in tokens)
+    args, skip, pattern_given = [], False, False
+    for token in tokens:
+        if skip:
+            skip = False
+        elif token in PATTERN_FLAGS:
+            skip, pattern_given = True, True
+        elif token in VALUE_FLAGS:
+            skip = True
+        elif not token.startswith("-") and not (verb == "findstr" and token.startswith("/")):
+            args.append(token)
+    return (args if pattern_given else args[1:]), recursive
+
+
+def _bash(command, cwd):
+    base, variables, verdict = cwd, {}, ("allow", "No content search over a folder.")
+    for text, after_pipe in segments(command):
+        try:
+            tokens = shlex.split(text, posix=True)
+        except ValueError:
+            tokens = text.split()
+        while tokens and _ASSIGN.match(tokens[0]):
+            name, value = _ASSIGN.match(tokens[0]).groups()
+            variables[name] = _expand(value, variables)
+            tokens = tokens[1:]
+        if not tokens:
+            continue
+        verb = tokens[0].lower()
+        if verb in CD_VERBS and len(tokens) > 1:
+            base = resolve_path(_expand(tokens[1], variables), base) or base
+            continue
+        xargs = verb == "xargs" and len(tokens) > 1 and tokens[1].lower() in SEARCHERS
+        if after_pipe and not xargs:
+            continue
+        if xargs:
+            if base and os.path.isdir(base) and _in_project(base, cwd) and _has_files(base):
+                return "redirect", base, "content search over the files of a listing"
+            continue
+        if verb == "git":
+            rest, repo = tokens[1:], base
+            while len(rest) > 1 and rest[0] == "-C":
+                repo = resolve_path(_expand(rest[1], variables), repo) or repo
+                rest = rest[2:]
+            if rest and rest[0] == "grep":
+                specs = rest[rest.index("--") + 1:] if "--" in rest else []
+                found = [_paths(_expand(raw, variables), repo) for raw in specs]
+                only_files = specs and all(f and all(os.path.isfile(p) for p in f) for f in found)
+                listed = sum(len(f) for f in found if f) if only_files else 0
+                if (not only_files or listed > LISTED_MAX) and repo and os.path.isdir(repo) and \
+                        _in_project(repo, cwd) and _has_files(repo):
+                    return "redirect", repo, "git grep over the repository"
+            continue
+        if verb in LISTERS:
+            recursive = verb in ("find", "fd", "tree") or "-recurse" in (t.lower() for t in tokens) or any(
+                re.fullmatch(r"-[a-zA-Z]*R[a-zA-Z]*", t) for t in tokens[1:])
+            first = next((t for t in tokens[1:] if not t.startswith("-")), ".")
+            for target in (_paths(_expand(first, variables), base) or []) if recursive else []:
+                if os.path.isdir(target) and _in_project(target, cwd) and count_files(target)[1]:
+                    return "redirect", target, "recursive listing of a very large tree"
+            continue
+        if verb not in SEARCHERS:
+            continue
+        args, recursive = _search_args(verb, tokens[1:])
+        if not args:
+            if recursive and base and os.path.isdir(base) and _in_project(base, cwd) and _has_files(base):
+                return "redirect", base, "recursive content search of the working folder"
+            continue
+        listed = 0
+        for raw in args:
+            found = _paths(_expand(raw, variables), base)
+            if found is None:
+                verdict = ("allow", "The searched path uses a variable the hook cannot resolve.")
+                continue
+            for target in found:
+                if os.path.isdir(target):
+                    if recursive and _in_project(target, cwd) and _has_files(target):
+                        return "redirect", target, "recursive content search over a folder"
+                else:
+                    listed += 1
+        if listed > LISTED_MAX:
+            return "redirect", base, f"content search over {listed} files"
+        if listed:
+            verdict = ("allow", "Search inside listed files.")
+    return verdict[0], None, verdict[1]
+
+
+def decide(tool_name, tool_input, cwd):
+    """(decision, target, reason) for a Grep, Glob or Bash call: decision is redirect or allow, target the folder that
+    would be searched (None when allowed)."""
+    if tool_name == "Glob":
+        return "allow", None, "Glob lists file names; smart_search does not replace a listing."
+    if tool_name == "Grep":
+        target = resolve_path(tool_input.get("path") or cwd, cwd)
+        if not target or not os.path.exists(target):
+            return "allow", None, "The path does not exist: the native tool's error is the useful answer."
+        if os.path.isfile(target):
+            return "allow", None, "Search inside one file."
+        if not _in_project(target, cwd):
+            return "allow", None, "The folder is outside every project: no index covers it."
+        if not _has_files(target):
+            return "allow", None, "The folder has no files."
+        return "redirect", target, "content search over a folder"
+    if tool_name == "Bash":
+        return _bash(tool_input.get("command") or "", cwd)
+    return "allow", None, "Tool not redirected."