@allansantos-dev/smart-tool 0.9.10 → 0.9.12

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.9.12 - beta
+
+- Security: `web_fetch` rendering with Moli (0.9.9 to 0.9.11) followed redirects and page requests to private
+  addresses, so a public page could redirect it to `127.0.0.1` or the local network and the agent received what was
+  there. Moli now runs with `--block-private-networks`, the same rule as the HTTP reader and the Chromium fallback.
+- Security, browser control: pages the agent opens are untrusted input. Playwright MCP is registered with
+  `--no-webmcp` (tools a page registers are never offered to the agent); every request of its browser carries
+  `X-Smart-Tool-Agent-Browser`, and the daemon refuses any request with it, so a page cannot steer the agent into the
+  setup page and its token, redirects included; `browser_run_code_unsafe` (arbitrary JavaScript in the server
+  process, outside any client sandbox) is denied in the client (`permissions.deny` in Claude Code, `disabled_tools` in
+  Codex), and the server is not registered when that fails. Existing registrations are refreshed on update.
+- Security hardening: block pattern proposals with lookarounds or backreferences, or that take over 5 s on a long
+  command, are discarded; an accepted pattern applies only to calls whose reach the rule cannot measure (a single-file
+  search stays allowed, as documented) and the block message no longer repeats the model's text; client CLIs that are
+  `.cmd` shims never receive arguments cmd.exe would interpret; the Moli archive extraction refuses drive-relative and
+  alternate-stream names.
+- `web_fetch` reads PDFs (pypdf, page by page, up to 300 pages, in a subprocess stopped at the request's deadline; a
+  PDF with only an owner password opens, one that needs a password to open is refused with that reason). The hook sends the native WebFetch here, and a PDF
+  was a dead end: 9 times in 10 days of sessions.
+- Agents are told to use `smart_search` first to explore code, not only after a block: in 10 days, 89 searches were
+  started by the agent against about 5,600 folder searches with the built-in tools. The server instructions and the
+  `smart_search` description now say when to use it, as `web_search`/`web_fetch` already did.
+
+## 0.9.11 - beta
+
+- Documentation only, no change to the program. The README opens with "How it works": what each tool does behind the
+  scenes, in plain words, for someone who has never used it (the index and the hybrid search, the web search sources,
+  how `web_fetch` reads a page, the hook, what stays on the machine). Its status line said 0.9.0; a test now fails
+  when the README status or the top of this changelog differs from `version.py`, as one already did for the product
+  page. The product page credits Moli as the page renderer (Crawl4AI is its fallback), lists Moli among the browsers
+  the installer downloads, links to "How it works" and has a favicon.
+
 ## 0.9.10 - beta
 
 - Browser control for agents, on by default: registering smart-tool in Claude Code or Codex (and every update, for

package/NOTICE

@@ -9,6 +9,7 @@ sources into the installation folder or the user's profile; each keeps its own l
 Python packages (installation venv, from PyPI)
 - ddgs (MIT)
 - trafilatura (Apache-2.0)
+- pypdf (BSD-3-Clause): text of PDFs read by web_fetch
 - pystray (LGPL-3.0; used unmodified as a library)
 - Pillow (MIT-CMU)
 - PyYAML (MIT)

package/README.md

@@ -15,7 +15,51 @@ registered as the `playwright` server where this machine lets a browser be drive
 An optional hook routes the agent's native Grep/Glob/Read/Bash/WebSearch/WebFetch calls to these tools when they
 are cheaper, or just tells the agent what Smart Tool would do.
 
-**Status:** 0.9.0 beta. Windows only.
+**Status:** 0.9.12 beta. Windows only. What changed in each version: [CHANGELOG.md](CHANGELOG.md).
+
+## How it works
+
+A coding agent normally finds code by running `grep` over the whole project and reads the web by downloading whole
+pages. Both fill its context with text it does not need, and every token of it is paid for. Smart Tool is a small
+program that runs on your machine and offers the agent better tools for the same jobs, through
+[MCP](https://modelcontextprotocol.io), the standard way agents call outside tools.
+
+```
+Claude Code / Codex ──MCP──▶ Smart Tool daemon (127.0.0.1, one per machine)
+                               ├─ smart_search ──▶ local index of your project (SQLite)
+                               ├─ web_search ───▶ several search engines at once, shared cache
+                               ├─ web_fetch ────▶ the page, read by a small model
+                               └─ project_manage
+        your model gateway (OpenAI, OpenRouter, Ollama...) ◀── embeddings and small chat calls
+```
+
+**Searching code.** When a project is registered, a small model looks at its folder structure once and decides what
+is worth indexing (source, tests, docs; not build output or dependencies). Each file is cut into chunks of up to 200
+lines, and each chunk gets an embedding, a list of numbers that captures its meaning. A search runs two ways at
+once, by meaning (embeddings) and by exact words (SQLite full-text search), merges the two lists and, if you set a
+rerank model, reorders the best candidates. The agent gets back a few chunks split into code, tests and docs, with
+the functions most likely to matter, instead of every line that contains a word. The index follows the project:
+only files whose content changed are processed again, and each Git branch keeps its own view.
+
+**Searching the web.** `web_search` asks several free search sources in parallel (DuckDuckGo, Wikipedia, Yahoo,
+Exa, Google and others), in the language of the question and in English, and merges what comes back. Search APIs with a
+free quota (Tavily, Firecrawl) and a real browser are tried only when those results are not enough. Answers are cached and shared by every agent
+session on the machine, so the same question asked twice costs nothing the second time.
+
+**Reading a page.** `web_fetch` takes a URL and a question. It downloads the page over plain HTTP; when the page only
+shows its content with JavaScript, it opens it in a headless browser ([Moli](https://github.com/lexmount/moli)
+first, Chromium as the fallback), which never reaches this machine or your local network. PDFs are read as text, page
+by page. A small model then reads the page and returns only the answer, with the source.
+The agent receives a paragraph instead of the whole page.
+
+**Steering the agent (optional hook).** Agents keep reaching for their built-in tools out of habit. The hook sees
+each call before it runs: a content search over a project folder is stopped and the agent is told the exact Smart
+Tool call to make instead; reading a known file, or anything else, runs as usual. The same hook can remind the agent
+to document functions it edits and warn when it writes a function that already exists in the project.
+
+**What stays local.** The daemon, the indexes, the caches and the logs live on your machine. Text leaves it only to
+reach the model gateway you chose (for embeddings and the small model calls) and the web search sources. With a local
+gateway such as Ollama, nothing about your code leaves the machine.
 
 ## Requirements
 
@@ -62,7 +106,11 @@ Open the setup screen from the tray icon ("Open settings") or at `http://127.0.0
    `~/.smart-tool/data/playwright-mcp`. Before registering, Smart Tool starts that server and opens a blank page as an
    agent would; where that fails (a corporate policy that forbids remote debugging, a missing browser) nothing is
    registered, agents keep reading pages through `web_fetch`, and the setup screen shows the reason with a retry
-   button. A `playwright` server you registered yourself is never touched. Remove it with
+   button. Pages the agent opens are treated as untrusted: tools a page registers (WebMCP) are never exposed, the
+   browser cannot open Smart Tool's own pages (every request it makes carries a header the daemon refuses), and
+   `browser_run_code_unsafe`, which runs arbitrary JavaScript in the server process, is denied in the client
+   (`permissions.deny` in `~/.claude/settings.json`, `disabled_tools` in `~/.codex/config.toml`); if it cannot be
+   denied, the server is not registered. A `playwright` server you registered yourself is never touched. Remove it with
    `claude mcp remove playwright -s user` / `codex mcp remove playwright`.
 
    The hook behaviors:

package/block_patterns.py

@@ -9,6 +9,8 @@ import hashlib
 import json
 import os
 import re
+import subprocess
+import sys
 import threading
 import time
 
@@ -29,6 +31,40 @@ CALL_MAX_CHARS = 1500
 REVIEWED_REASONS = ("The searched path uses a variable the hook cannot resolve.", "No content search over a folder.")
 _BULK_READ = re.compile(r"\*|\bxargs\b|-exec\b|\bfor\s+\w+\s+in\b|os\.walk|rglob|glob\(|readdirSync|readdir\(|"
                         r"walkSync|-Recurse\b|Get-ChildItem", re.IGNORECASE)
+# A lookaround, backreference or conditional can match by exclusion ("anything but these files").
+_OPEN_ENDED = re.compile(r"\(\?<?[=!]|\(\?P=|\(\?\(|\\[1-9]")
+# Every hook call runs the accepted patterns, so one that backtracks exponentially would hang the daemon (re holds
+# the GIL and cannot be interrupted). Every regex of a proposal runs in a subprocess: first a timing over each prefix
+# of the call followed by a run of characters commands are made of, and over each separator of the call itself (1 to
+# 3 characters with punctuation, such as "; " or "\\") repeated where it first appears; over SLOW_REGEX_S of regex
+# time, or no answer in SLOW_REGEX_S + START_SLACK_S, discards it. Then the checks against the call, the samples and
+# the logged history (no answer in HISTORY_TIMEOUT_S discards it too).
+SLOW_REGEX_S = 5
+START_SLACK_S = 10
+HISTORY_TIMEOUT_S = 60
+_RUNS = tuple(unit * (200 // len(unit)) for unit in ("a", " ", "/", "_", "1", "a ", "a/", "a.", "$a/", "-a "))
+_PREFIXES = 150
+_MEASURE_SCRIPT = """
+import json, re, sys, time
+sys.path.insert(0, sys.argv[1])
+import block_patterns as b
+tool, pattern, text, metrics = json.loads(sys.stdin.read())
+regex = re.compile(pattern)
+if sys.argv[2] == "timing":
+    start = time.perf_counter()
+    step = max(1, len(text) // b._PREFIXES)
+    for end in range(0, len(text) + 1, step):
+        for run in b._RUNS:
+            regex.search(text[:end] + run + "\\x00")
+    for unit in b._units(text):
+        regex.search(text[:max(0, text.find(unit))] + unit * (200 // len(unit)) + "\\x00")
+    print(json.dumps({"seconds": time.perf_counter() - start}))
+else:
+    allowed = next((x for x in b.ALLOWED_ON_PURPOSE if regex.search(x)), None)
+    matches, total = b._history(tool, regex, metrics)
+    print(json.dumps({"matches_call": bool(regex.search(text)), "allowed": allowed, "matches": matches,
+                      "total": total}))
+"""
 # Calls the rule lets run on purpose: a pattern matching any of them would block what must run.
 ALLOWED_ON_PURPOSE = ("grep -n handler src/app.py", "grep -n \"def load\" -A20 src/app.py | head -40",
                       "sed -n 1,80p src/app.py", "cat README.md", "head -50 src/app.py", "tail -20 logs/app.log",
@@ -120,6 +156,33 @@ def matching(tool_name, tool_input):
     return next((entry for entry, regex in compiled if entry["tool"] == tool_name and regex.search(text)), None)
 
 
+def _units(text, limit=400):
+    """Distinct 1-3 character pieces of text holding a non-alphanumeric character, plus each one after a letter: the
+    separators a pattern's repetition may hinge on."""
+    seen = {}
+    for size in (1, 2, 3):
+        for start in range(len(text) - size + 1):
+            piece = text[start:start + size]
+            if not piece.isalnum():
+                seen.setdefault(piece, None)
+                seen.setdefault("a" + piece, None)
+    return list(seen)[:limit]
+
+
+def _measure(stage, timeout, tool_name, pattern, text, metrics_path):
+    """One stage of _MEASURE_SCRIPT ("timing" or "checks") in a subprocess; None when it did not answer in time."""
+    try:
+        done = subprocess.run([sys.executable, "-I", "-c", _MEASURE_SCRIPT, os.path.dirname(os.path.abspath(__file__)), stage],
+                              input=json.dumps([tool_name, pattern, text, metrics_path]), capture_output=True,
+                              text=True, encoding="utf-8", timeout=timeout,
+                              creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0))
+    except subprocess.TimeoutExpired:
+        return None
+    if done.returncode:
+        raise RuntimeError(f"pattern check failed: {done.stderr.strip()[-300:]}")
+    return json.loads(done.stdout)
+
+
 def _history(tool_name, regex, metrics_path):
     """(matches, total) of the logged calls of this tool the pattern would have blocked."""
     matches = total = 0
@@ -177,15 +240,23 @@ def propose(tool_name, tool_input, rule_reason, model, metrics_path, redact):
         problem, regex = f"invalid regex: {exc}", None
     if regex and len(pattern) > PATTERN_MAX_CHARS:
         problem = f"longer than {PATTERN_MAX_CHARS} characters"
-    elif regex and not regex.search(text):
-        problem = "does not match the call it came from"
-    elif regex and any(regex.search(sample) for sample in ALLOWED_ON_PURPOSE):
-        problem = "matches calls the rule lets run on purpose: " + next(x for x in ALLOWED_ON_PURPOSE if regex.search(x))
+    elif regex and _OPEN_ENDED.search(pattern):
+        problem = "lookaround, backreference or conditional (matches by exclusion)"
     if regex and not problem:
-        matches, total = _history(tool_name, regex, metrics_path)
-        entry.update(history_matches=matches, history_total=total)
-        if total and matches / total > BROAD_SHARE:
-            problem = f"too broad: would block {matches} of {total} logged {tool_name} calls"
+        timing = _measure("timing", SLOW_REGEX_S + START_SLACK_S, tool_name, pattern, text, metrics_path)
+        checks = (_measure("checks", HISTORY_TIMEOUT_S, tool_name, pattern, text, metrics_path)
+                  if timing and timing["seconds"] <= SLOW_REGEX_S else None)
+        if checks is None:
+            problem = f"catastrophic backtracking: over {SLOW_REGEX_S}s on a long command or the logged calls"
+        elif not checks["matches_call"]:
+            problem = "does not match the call it came from"
+        elif checks["allowed"]:
+            problem = "matches calls the rule lets run on purpose: " + checks["allowed"]
+        else:
+            matches, total = checks["matches"], checks["total"]
+            entry.update(history_matches=matches, history_total=total)
+            if total and matches / total > BROAD_SHARE:
+                problem = f"too broad: would block {matches} of {total} logged {tool_name} calls"
     with _LOCK:
         data = load()
         if any(e["id"] == entry["id"] for group in data.values() for e in group):

package/browser_control.py

@@ -6,14 +6,22 @@ isolated in-memory profile, headless. Before registering, a probe launches that
 as the agent would: machines whose policy forbids it (corporate IT blocking remote debugging, a missing browser)
 keep today's read-only behavior, and the reason is shown in the setup screen instead of an error. A server named
 `playwright` the user already registered is left untouched.
+
+Pages the agent opens are untrusted input. The server never exposes tools a page registers (WebMCP); every request
+the browser makes carries AGENT_HEADER, which the daemon refuses, so a page cannot steer the agent into Smart Tool's
+own setup page and its token (redirects included); `browser_run_code_unsafe` (arbitrary JavaScript in the server
+process, outside any client sandbox) is denied in the client: Playwright MCP itself is not a security boundary and
+its documentation points to client-level permissions.
 """
 import json
 import os
 import queue
+import re
 import subprocess
 import tempfile
 import threading
 import time
+import tomllib
 
 import atomic_io
 import endpoint_sync
@@ -24,8 +32,12 @@ SERVER = "playwright"
 CLI = install_runtime.PLAYWRIGHT_MCP_CLI
 STATUS_PATH = os.path.join(paths.DATA_DIR, "browser-control.json")
 OUTPUT_DIR = os.path.join(paths.DATA_DIR, "playwright-mcp")
+CONFIG_PATH = os.path.join(paths.DATA_DIR, "playwright-mcp.json")
+AGENT_HEADER = "X-Smart-Tool-Agent-Browser"
 OUTPUT_MAX_BYTES = 100 * 1024 * 1024
 PROBE_TIMEOUT_S = 60
+DENIED_TOOLS = ("browser_run_code_unsafe",)
+_CODEX_TABLE_RE = re.compile(rf"^\[mcp_servers\.{SERVER}\][ \t]*\r?\n", re.M)
 _CHROMIUM_PROBE = ("from playwright.sync_api import sync_playwright\n"
                    "with sync_playwright() as p: print(p.chromium.executable_path)")
 
@@ -50,8 +62,18 @@ def server_command():
         raise RuntimeError("Supported Node.js not found for Playwright MCP.")
     if not CLI.is_file():
         raise RuntimeError(f"Playwright MCP is not installed ({CLI}); reinstall Smart Tool.")
-    return [node, str(CLI), "--isolated", "--headless", "--executable-path", chromium_executable(),
-            "--output-dir", OUTPUT_DIR, "--output-max-size", str(OUTPUT_MAX_BYTES)]
+    return [node, str(CLI), "--isolated", "--headless", "--no-webmcp", "--config", write_config(),
+            "--executable-path", chromium_executable(), "--output-dir", OUTPUT_DIR,
+            "--output-max-size", str(OUTPUT_MAX_BYTES)]
+
+
+def write_config():
+    """Writes the Playwright MCP config file that adds AGENT_HEADER to every request of the browser (navigations,
+    redirects, subresources; measured: no CORS preflight is added) and returns its path."""
+    os.makedirs(os.path.dirname(CONFIG_PATH), exist_ok=True)
+    config = {"browser": {"contextOptions": {"extraHTTPHeaders": {AGENT_HEADER: "1"}}}}
+    atomic_io.write_secret_text(CONFIG_PATH, json.dumps(config, indent=1))
+    return CONFIG_PATH
 
 
 def probe(command, timeout=PROBE_TIMEOUT_S):
@@ -128,13 +150,89 @@ def registered():
     except (OSError, ValueError, AttributeError):
         pass
     try:
-        with open(os.path.join(os.path.expanduser("~"), ".codex", "config.toml"), encoding="utf-8") as stream:
+        with open(_codex_config(), encoding="utf-8") as stream:
             found["codex"] = f"[mcp_servers.{SERVER}]" in stream.read()
     except OSError:
         pass
     return found
 
 
+def _codex_config():
+    """Codex keeps config.toml in CODEX_HOME when set, else ~/.codex."""
+    return os.path.join(os.environ.get("CODEX_HOME") or os.path.join(os.path.expanduser("~"), ".codex"), "config.toml")
+
+
+def _replace_text(path, text):
+    temporary = f"{path}.smart-tool-tmp"
+    with open(temporary, "w", encoding="utf-8", newline="") as stream:
+        stream.write(text)
+    os.replace(temporary, path)
+
+
+def set_claude_deny(present):
+    """Adds (present=True) or removes the `permissions.deny` rules for DENIED_TOOLS in Claude Code's user settings,
+    keeping every other rule. Raises ValueError when settings.json does not have the documented layout."""
+    path = os.path.join(endpoint_sync.claude_dir(), "settings.json")
+    try:
+        with open(path, encoding="utf-8-sig") as stream:
+            data = json.load(stream)
+    except FileNotFoundError:
+        data = {}
+    permissions = data.get("permissions", {}) if isinstance(data, dict) else None
+    deny = permissions.get("deny", []) if isinstance(permissions, dict) else None
+    if not isinstance(deny, list):
+        raise ValueError(f"{path} has no permissions.deny list Claude Code can read; fix it to deny "
+                         f"{', '.join(DENIED_TOOLS)}.")
+    rules = [f"mcp__{SERVER}__{tool}" for tool in DENIED_TOOLS]
+    kept = [rule for rule in deny if rule not in rules]
+    new = kept + rules if present else kept
+    if new == deny:
+        return
+    permissions["deny"] = new
+    if not new:
+        del permissions["deny"]
+    data["permissions"] = permissions
+    if not permissions:
+        del data["permissions"]
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    _replace_text(path, json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+
+
+def set_codex_disabled():
+    """Adds `disabled_tools` = DENIED_TOOLS to the [mcp_servers.playwright] table `codex mcp add` wrote (the CLI has
+    no flag for it) and checks the file still parses with that value. Raises ValueError otherwise."""
+    path = _codex_config()
+    with open(path, encoding="utf-8", newline="") as stream:
+        text = stream.read()
+
+    def disabled(source):
+        return ((tomllib.loads(source).get("mcp_servers") or {}).get(SERVER) or {}).get("disabled_tools")
+    current = disabled(text)
+    if current is not None:
+        if set(DENIED_TOOLS) <= set(current):
+            return
+        raise ValueError(f"{path} already sets other disabled_tools for {SERVER}; add {', '.join(DENIED_TOOLS)}.")
+    match = _CODEX_TABLE_RE.search(text)
+    if not match:
+        raise ValueError(f"[mcp_servers.{SERVER}] not found in {path}.")
+    newline = "\r\n" if match.group(0).endswith("\r\n") else "\n"
+    new = (text[:match.end()] + "disabled_tools = [" + ", ".join(json.dumps(t) for t in DENIED_TOOLS) + "]"
+           + newline + text[match.end():])
+    if not set(DENIED_TOOLS) <= set(disabled(new) or []):
+        raise ValueError(f"disabled_tools did not take effect in {path}.")
+    _replace_text(path, new)
+
+
+def deny_unsafe_tools(client):
+    """Denies DENIED_TOOLS in the client where Smart Tool registered the server."""
+    if client == "claude":
+        set_claude_deny(True)
+    elif client == "codex":
+        set_codex_disabled()
+    else:
+        raise ValueError(f"Client without MCP registration: {client!r}")
+
+
 def register_command(client, command):
     """Official CLI command that registers a stdio server (Claude Code: user scope, every project)."""
     if client == "claude":
@@ -154,7 +252,7 @@ def remove_command(client):
 
 
 def status():
-    """Last outcome per client: {"claude": {"state": "registered"|"unavailable"|"kept", "reason", "at"}, ...}."""
+    """Last outcome per client: {"claude": {"state": "registered"|"unavailable"|"kept"|"undenied", "reason", "at"}}."""
     try:
         with open(STATUS_PATH, encoding="utf-8") as stream:
             data = json.load(stream)
@@ -180,8 +278,10 @@ def ensure(client, log=None):
     and install paths change between versions). A `playwright` server the user registered is kept. When the browser
     cannot be driven on this machine (probe failed, CLI refused) records `unavailable` with the reason, removes a
     registration of ours that would no longer work and returns: agents keep the read-only browsers of web_fetch and
-    web_search. Only an unreadable status file raises (ValueError). log (optional) also gets the reason."""
-    ours = status().get(client, {}).get("state") == "registered"
+    web_search. A registration whose DENIED_TOOLS cannot be denied in the client is removed too; when even that fails
+    the state is `undenied` (the next call retries it as ours). Only an unreadable status file raises (ValueError).
+    log (optional) also gets the reason."""
+    ours = status().get(client, {}).get("state") in ("registered", "undenied")
     if registered().get(client) and not ours:
         return _record(client, "kept", "a playwright MCP server you registered is kept")
     try:
@@ -193,10 +293,25 @@ def ensure(client, log=None):
         if ours and registered().get(client):
             endpoint_sync.run_cli(remove_command(client))
         if problem:
+            if ours and client == "claude":
+                set_claude_deny(False)
             return _record(client, "unavailable", problem[:300], log)
         endpoint_sync.run_cli(register_command(client, command))
-    except RuntimeError as exc:
-        return _record(client, "unavailable", str(exc)[:300], log)
-    if not registered().get(client):
-        return _record(client, "unavailable", "the client CLI finished, but the server did not appear in its configuration", log)
+        if not registered().get(client):
+            return _record(client, "unavailable", "the client CLI finished, but the server did not appear in its "
+                           "configuration", log)
+        try:
+            deny_unsafe_tools(client)
+        except (OSError, ValueError) as exc:
+            problem = f"{', '.join(DENIED_TOOLS)} could not be denied ({exc})"
+            try:
+                endpoint_sync.run_cli(remove_command(client))
+            except RuntimeError as removal:
+                return _record(client, "undenied", f"remove it with `{' '.join(remove_command(client))}`: {problem} "
+                               f"and removing it failed ({removal})"[:300], log)
+            return _record(client, "unavailable", f"{problem}, so the server was removed"[:300], log)
+    except (OSError, RuntimeError, ValueError) as exc:
+        # Our registration still in place after a failure (its removal failed) stays ours, flagged, never "kept".
+        state = "undenied" if ours and registered().get(client) else "unavailable"
+        return _record(client, state, str(exc)[:300], log)
     return _record(client, "registered")

package/endpoint_sync.py

@@ -102,6 +102,7 @@ def registrations():
 
 
 REGISTER_TIMEOUT_S = 60
+_CMD_METACHARS = re.compile(r'[&|<>^%!"\r\n]')
 
 
 def register_command(client, base):
@@ -129,6 +130,11 @@ def run_cli(command):
     executable = shutil.which(command[0])
     if not executable:
         raise RuntimeError(f"CLI '{command[0]}' not found in Smart Tool's PATH. Register it manually: {' '.join(command)}")
+    unsafe = [arg for arg in command[1:] if _CMD_METACHARS.search(arg)]
+    if executable.lower().endswith((".cmd", ".bat")) and unsafe:
+        # cmd.exe parses a .cmd shim's arguments again: & | < > ^ % ! would run as commands or expand as variables.
+        raise RuntimeError(f"'{command[0]}' is a cmd.exe script and this argument has characters cmd.exe would "
+                           f"interpret: {unsafe[0]}. Register it manually: {' '.join(command)}")
     flags = subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0
     try:
         proc = subprocess.Popen([executable, *command[1:]], stdout=subprocess.PIPE, stderr=subprocess.PIPE,

package/install_runtime.py

@@ -87,9 +87,11 @@ def _extract_folder(zip_path, top, destination):
             parts = Path(member.filename.replace("\\", "/")).parts
             if parts == (top,) and member.is_dir():
                 continue
-            if len(parts) < 2 or parts[0] != top or ".." in parts:
-                raise RuntimeError(f"{zip_path.name} contains an unexpected path: {member.filename}")
             target = destination.joinpath(*parts[1:])
+            # "C:x" (drive-relative) and "x:stream" (alternate data stream) components escape joinpath's confinement.
+            if (len(parts) < 2 or parts[0] != top or ".." in parts or any(":" in part for part in parts)
+                    or not target.resolve().is_relative_to(destination.resolve())):
+                raise RuntimeError(f"{zip_path.name} contains an unexpected path: {member.filename}")
             if member.is_dir():
                 target.mkdir(parents=True, exist_ok=True)
             else:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allansantos-dev/smart-tool",
-  "version": "0.9.10",
+  "version": "0.9.12",
   "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/requirements.txt

@@ -3,6 +3,7 @@ Pillow
 PyYAML
 ddgs==9.16.0
 trafilatura==2.3.0
+pypdf==6.20.0
 # Mapas JS/TS: TypeScript 5.9.3 no runtime Node (web_adapters/node/package-lock.json).
 # Mapas Java/Angular: java-parser 3.0.1 e @angular/compiler 20.3.0 no mesmo runtime Node.
 # DOCX: extração com zipfile + ElementTree (stdlib; sem Office/macros/rede).

package/router.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """Routing of the native tool calls the PreToolUse hook matches (Grep, Glob, Bash, Read). Deterministic: calls that
-neither search nor read code, or that change files, run; accepted block patterns redirect; the rest follows
-redirect_rule. Searches the rule lets run are reviewed in the background by the router model, which may propose new
+neither search nor read code, or that change files, run; the rest follows redirect_rule, and accepted block patterns
+redirect only allowed calls whose reach the rule cannot measure (block_patterns.reviewable). Searches the rule lets run are reviewed in the background by the router model, which may propose new
 block patterns (block_patterns). Every decision is logged in router-metrics.jsonl. Also holds the router-model
 helpers of the web search (tier order and result assessment)."""
 import contextvars
@@ -157,12 +157,13 @@ def decide(tool_name, tool_input, cwd=None):
         decision, reason = mechanical
         _log_decision(tool_name, tool_input, decision, reason, extra={"mechanical": True})
         return decision, reason, None
-    learned = block_patterns.matching(tool_name, safe_input)
+    decision, target, reason = redirect_rule.decide(tool_name, safe_input, cwd)
+    learned = (block_patterns.matching(tool_name, safe_input)
+               if decision == "allow" and block_patterns.reviewable(tool_name, safe_input, reason) else None)
     if learned:
-        reason = f"accepted block pattern: {learned['reason']}"
+        reason = f"accepted block pattern {learned['id']} (approved by the user in Smart Tool's setup screen)"
         _log_decision(tool_name, tool_input, "redirect", reason, extra={"pattern": learned["id"]})
         return "redirect", reason, cwd
-    decision, target, reason = redirect_rule.decide(tool_name, safe_input, cwd)
     _log_decision(tool_name, tool_input, decision, reason, extra={"rule": True})
     if decision == "allow":
         try:

package/setup_ui.py

@@ -938,6 +938,7 @@ function browserText(item) {
   const state = item.browser_control || {};
   if (state.state === "registered") return "Browser control on: Playwright MCP drives an isolated, headless Chromium";
   if (state.state === "kept") return "Browser control: your own playwright MCP server is kept";
+  if (state.state === "undenied") return "Browser control is registered without its safety rule: " + state.reason;
   if (state.state === "unavailable") return "Browser control unavailable on this machine (" + state.reason + "); pages are still read by web_fetch";
   return "Browser control is set up when the MCP is registered";
 }

package/smart_tool_daemon.py

@@ -35,6 +35,7 @@ import uuid
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import browser_control
 import capabilities
 import client_hooks
 import install_runtime
@@ -309,7 +310,10 @@ def _smart_search_job_payload(job_id):
 # 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 "
+    "Smart Tool serves an indexed semantic search over the user's projects and a cheaper web reader. Use smart_search "
+    "FIRST to explore code in the user's projects (where something is implemented, how a flow works, what already "
+    "exists to reuse) before reading files one by one; Grep/Read are for an exact string or a file you already know. "
+    "Use web_search/web_fetch for any web research. The user also installed "
     "a PreToolUse hook that blocks content searches over a project folder (grep -r, rg, git grep, Grep on a folder) "
     "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 "
@@ -360,8 +364,9 @@ 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). "
+            "Semantic search (embed+rerank) over the project's index: the first step to understand code in a "
+            "project, finding functions, flows and reusable code by meaning, ranked, with name:line. Use it before "
+            "a series of Grep/Read; use Grep only for an exact literal or inside a known file. "
             "Results come in three blocks, code, test and doc, plus the project profile with the natural "
             "languages of identifiers, comments and docs (also in project_manage list/status as search_profile). "
             "Fill query_identifiers with identifier and function-name terms in the identifiers' language and "
@@ -3195,10 +3200,13 @@ WEB_FETCH_VECTOR_ROOT = os.path.join(paths.DATA_DIR, "web-fetch")
 
 
 def _moli_markdown(url, timeout):
-    """Markdown of a JavaScript page rendered by Moli (layout and paint only when the page needs them)."""
+    """Markdown of a JavaScript page rendered by Moli (layout and paint only when the page needs them). Every request
+    Moli makes (redirects, scripts, frames, fetch) refuses private, loopback, link-local and CGNAT addresses, as the
+    HTTP reader and the Crawl4AI route guard do: a public page cannot read this machine or its network through it."""
     if not install_runtime.MOLI_EXE.is_file():
         raise RuntimeError(f"Moli is not installed ({install_runtime.MOLI_EXE}); reinstall Smart Tool.")
-    done = subprocess.run([str(install_runtime.MOLI_EXE), "fetch", "--dump", "markdown", url], capture_output=True,
+    done = subprocess.run([str(install_runtime.MOLI_EXE), "fetch", "--block-private-networks", "--dump", "markdown",
+                           url], capture_output=True,
                           timeout=timeout, creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0))
     if done.returncode:
         raise RuntimeError(f"moli exited {done.returncode}: {done.stderr.decode('utf-8', 'replace').strip()[-300:]}")
@@ -3475,6 +3483,11 @@ class MCPHandler(BaseHTTPRequestHandler):
         return origin is None or _loopback_host(origin, require_port=True)
 
     def _reject_foreign_origin(self):
+        """The agent's browser (Playwright MCP marks every request with AGENT_HEADER) never reaches the daemon: a page
+        it opens could otherwise steer the agent into /setup, whose token unlocks every setting."""
+        if self.headers.get(browser_control.AGENT_HEADER):
+            self._write_json(403, {"error": "Smart Tool's pages are not available to the agent's browser"})
+            return True
         if self._origin_allowed():
             return False
         self._write_json(403, {"error": "origin not allowed"})

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.10"
+VERSION = "0.9.12"
 _CONTACT_RE = re.compile(r"^(?:[^\s@()<>;]+@[^\s@()<>;]+\.[^\s@()<>;]+|https?://[^\s()<>;]+)$")
 
 

package/web_fetch.py

@@ -20,6 +20,8 @@ import ipaddress
 import json
 import socket
 import ssl
+import subprocess
+import sys
 import threading
 import time
 import urllib.parse
@@ -37,6 +39,8 @@ SELECT_BUDGET_CHARS = 15_000
 CHUNK_CHARS = 2_000
 PAGE_FORMAT = 2
 MAX_DOWNLOAD_BYTES = 5 * 1024 * 1024
+PDF_MAX_PAGES = 300
+PDF_TIMEOUT_S = 30
 MAX_REDIRECTS = 5
 HTTP_TIMEOUT_S = 20
 READ_CHUNK = 64 * 1024
@@ -208,6 +212,48 @@ def thin(text):
     return len(stripped) < PLACEHOLDER_SCAN_CHARS and any(p in stripped[:600].lower() for p in PLACEHOLDERS)
 
 
+PDF_SCRIPT = """
+import io, json, sys
+import pypdf
+reader = pypdf.PdfReader(io.BytesIO(sys.stdin.buffer.read()))
+if reader.is_encrypted and reader.decrypt("") == pypdf.PasswordType.NOT_DECRYPTED:
+    print(json.dumps({"encrypted": True}))
+    sys.exit()
+limit, budget = int(sys.argv[1]), int(sys.argv[2])
+pages, size = [], 0
+for page in reader.pages[:limit]:
+    pages.append((page.extract_text() or "").strip()[:budget - size])
+    size += len(pages[-1])
+    if size >= budget:
+        break
+print(json.dumps({"pages": pages, "count": len(reader.pages)}))
+"""
+
+
+def pdf_text(body, url, deadline):
+    """Text of a PDF (pypdf, pure Python), page by page up to PDF_MAX_PAGES. The native WebFetch reads PDFs and the hook
+    sends it here, so a PDF used to be a dead end (9 times in 10 days of transcripts). A hostile PDF can make pypdf
+    parse for minutes, so it runs in a subprocess killed at the request's deadline (at most PDF_TIMEOUT_S)."""
+    timeout = min(PDF_TIMEOUT_S, _left(deadline))
+    try:
+        done = subprocess.run([sys.executable, "-I", "-c", PDF_SCRIPT, str(PDF_MAX_PAGES), str(PAGE_STORE_MAX_CHARS)],
+                              input=body, capture_output=True, timeout=timeout,
+                              creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0))
+    except subprocess.TimeoutExpired:
+        raise FetchError(f"PDF not read in {timeout:.0f}s ({url}).") from None
+    if done.returncode:
+        detail = (done.stderr.decode("utf-8", "replace").strip().splitlines() or ["no output"])[-1]
+        raise FetchError(f"PDF could not be read ({url}): {detail}"[:300])
+    result = json.loads(done.stdout)
+    if result.get("encrypted"):
+        raise FetchError(f"PDF protected by a password is not read by web_fetch ({url}).")
+    pages = result["pages"]
+    text = "\n\n".join(f"[page {number}]\n{page}" for number, page in enumerate(pages, 1) if page)
+    if result["count"] > len(pages):
+        text += f"\n\n[pages {len(pages) + 1}-{result['count']} not read]"
+    return text
+
+
 def read_page(url, deadline, render):
     """Page text (Markdown) from the 24 h cache, HTTP + trafilatura, or `render(url, deadline)` when HTTP comes thin."""
     url = normalize(url)
@@ -230,6 +276,8 @@ def read_page(url, deadline, render):
                 text, rendered = markdown, True
     elif kind in TEXT_TYPES:
         text = _decode(body, charset)
+    elif kind == "application/pdf":
+        text = pdf_text(body, final_url, deadline)
     else:
         raise FetchError(f"Content type {kind} is not read by web_fetch ({final_url}).")
     if len(text.strip()) < MIN_CHARS: