@allansantos-dev/smart-tool 0.9.14 → 0.9.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,40 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.9.16 - beta
4
+
5
+ - New setup screen. It opens on an **Overview** that checks everything Smart Tool needs on this machine (model
6
+ gateway, each agent's connection and hook, block patterns waiting, the service, web search, the setup audit) and
7
+ lists what needs you first, each with a button that takes you to the fix. A side menu replaces the long scroll:
8
+ Connect (Agents, Models, Web search), Behavior (Agent rules, Redirects) and Maintenance (Setup audit, Startup),
9
+ with a count of open items next to each. Every section says what it is for; choices apply as soon as they are
10
+ picked, and typed values keep a save button next to them. Light and dark follow the system; under 860 px the menu
11
+ becomes a row of tabs.
12
+ - An outdated hook says so. The setup screen compares each agent's Smart Tool hook entry with the one this version
13
+ writes and lists what the old one misses (tools not covered, an old address or timeout). **Update hook** shows the
14
+ exact entry first and, after you confirm, rewrites only Smart Tool's entry (other hooks stay, the file is backed up).
15
+ The tray notice also names an outdated hook.
16
+ - Agent rules (redirect behavior, documentation and duplicate checks on edit, block pattern proposals) moved off the
17
+ Agents section into their own, with the recommended choice marked.
18
+
19
+ ## 0.9.15 - beta
20
+
21
+ - The hook redirects the folder searches that slipped past it in a shell: wrapped (`bash -c`, `sh -lc`,
22
+ `powershell -Command`, `cmd /c`, `timeout 60`, `env X=1`, `time`, `nice`, a `( ... )` subshell), looped
23
+ (`for f in src/*.py; do grep x "$f"`), fed by a listing (`find -exec grep|cat`, `find | xargs -0 grep`,
24
+ `grep x $(find src -name '*.py')`, `find | while read f`, `Get-ChildItem -Recurse | Select-String` or
25
+ `| % { Get-Content $_ }`), `git --no-pager grep`, `cat` over more than 20 files, and inline python/node scripts
26
+ (`-c`, `-e`, heredoc) that walk a project folder, read the files and match their text. A listing capped by `head`,
27
+ `find -name` of one exact file and scripts that write files still run. Replayed over 3 days of real transcripts
28
+ (14,580 Grep and shell calls), 37 more calls are redirected, all folder searches; none of the previous redirects
29
+ changed.
30
+ - Claude Code's PowerShell tool goes through the same rule as Bash; it was not in the hook matcher. Reinstall the
31
+ hook from the setup screen (it shows as outdated): the matcher now has `PowerShell` and `smart_search`.
32
+ - Setup screen, Agents: the redirects of the last 7 days by tool and reason, and what the same session did next
33
+ (called `smart_search`, ran an allowed native call, was blocked again, or nothing within 15 minutes). The hook log
34
+ now records the session, and `smart_search` calls pass through the hook only to be counted. Next to it, the
35
+ measured context per call: a native call of the kinds redirected ~510 tokens, a `smart_search` round trip ~2,160
36
+ tokens; a redirect saves context only when one search replaces several native ones, which is not measured yet.
37
+
3
38
  ## 0.9.14 - beta
4
39
 
5
40
  - The setup audit runs on its own: the daemon audits every registered project two minutes after it starts and then
package/README.md CHANGED
@@ -15,7 +15,7 @@ registered as the `playwright` server where this machine lets a browser be drive
15
15
  An optional hook routes the agent's native Grep/Glob/Read/Bash/WebSearch/WebFetch calls to these tools when they
16
16
  are cheaper, or just tells the agent what Smart Tool would do.
17
17
 
18
- **Status:** 0.9.14 beta. Windows only. What changed in each version: [CHANGELOG.md](CHANGELOG.md).
18
+ **Status:** 0.9.16 beta. Windows only. What changed in each version: [CHANGELOG.md](CHANGELOG.md).
19
19
 
20
20
  ## How it works
21
21
 
@@ -89,7 +89,10 @@ State lives in `~/.smart-tool`: `config.json`, your model adapters in `adapters/
89
89
 
90
90
  ## Set up
91
91
 
92
- Open the setup screen from the tray icon ("Open settings") or at `http://127.0.0.1:8765/setup`.
92
+ Open the setup screen from the tray icon ("Open settings") or at `http://127.0.0.1:8765/setup`. It opens on
93
+ **Overview**: everything Smart Tool needs, checked on this machine, with what needs you first and a button that takes
94
+ you to the fix. The side menu groups the rest under Connect (Agents, Models, Web search), Behavior (Agent rules,
95
+ Redirects) and Maintenance (Setup audit, Startup).
93
96
 
94
97
  1. **Model gateway**: pick an adapter and fill its fields. The built-in **OpenAI-compatible** adapter takes a base
95
98
  URL ending where the API starts, like the OpenAI SDK `base_url` (`https://api.openai.com/v1`,
@@ -98,7 +101,8 @@ Open the setup screen from the tray icon ("Open settings") or at `http://127.0.0
98
101
  reasoning: web search tier order and result checks), the index classification model (also reviews block patterns) and the research model. Any id the gateway
99
102
  accepts works; the catalog is shown as suggestions.
100
103
  3. **Agents**: register the MCP server in Claude Code or Codex (runs their official `mcp add` command), install the
101
- hook and choose its behavior.
104
+ hook and choose its behavior under **Agent rules**. A hook written by an older Smart Tool shows as outdated, with
105
+ what an update changes; updating previews the entry and rewrites only Smart Tool's, after a backup.
102
106
 
103
107
  **Browser control** comes with the registration, and with every update for clients where smart-tool is registered:
104
108
  the official Playwright MCP (pinned in `web_adapters/node`) is registered as the `playwright` server, driving the
@@ -116,8 +120,12 @@ Open the setup screen from the tray icon ("Open settings") or at `http://127.0.0
116
120
  The hook behaviors:
117
121
  - **Redirect** (default): the native tool is denied with the reason and the Smart Tool tool to use. The decision
118
122
  is a fixed rule, under a millisecond and the same every time: a content search over a project folder (`grep -r`,
119
- `rg`, `git grep`, the Grep tool on a folder) or over more than 20 listed files goes to `smart_search`; reading or
120
- searching known files, listings, Glob and commands that change files run. With **Block patterns proposed by a
123
+ `rg`, `git grep`, the Grep tool on a folder) or over more than 20 listed files goes to `smart_search`, in Bash and
124
+ PowerShell alike and also when it is wrapped (`bash -c`, `powershell -Command`, `timeout`, a subshell), looped
125
+ (`for f in src/*.py`), fed by a listing (`find -exec grep`, `xargs`, `Get-ChildItem | Select-String`) or written
126
+ as an inline python/node script that walks a folder and matches text; reading or searching known files,
127
+ listings, Glob and commands that change files run. The setup screen counts the redirects and what each session
128
+ did next. With **Block patterns proposed by a
121
129
  model** on (default), the scope model reviews, in the background, bulk reads the rule could not measure and
122
130
  proposes regex patterns, each checked against the logged calls; a pattern blocks only after you accept it.
123
131
  - **Advise only**: the native tool runs; the agent receives the same advice next to the result and decides.
package/client_hooks.py CHANGED
@@ -16,7 +16,7 @@ HOME = os.path.expanduser("~")
16
16
  PREVIEW_TTL_S = 600
17
17
  CLIENTS = {
18
18
  "claude": {"label": "Claude Code", "names": {"claude-code"}, "files": [os.path.join(endpoint_sync.claude_dir(), "settings.json")],
19
- "docs": "https://code.claude.com/docs/en/hooks", "event": "PreToolUse", "matcher": "Grep|Glob|Read|Bash|WebSearch|WebFetch|Edit|MultiEdit|Write", "http": True},
19
+ "docs": "https://code.claude.com/docs/en/hooks", "event": "PreToolUse", "matcher": "Grep|Glob|Read|Bash|PowerShell|WebSearch|WebFetch|Edit|MultiEdit|Write|mcp__smart-tool__smart_search", "http": True},
20
20
  "codex": {"label": "Codex", "prefix": "codex", "files": [os.path.join(HOME, ".codex", "hooks.json"), os.path.join(HOME, ".codex", "config.toml")],
21
21
  "docs": "https://learn.chatgpt.com/docs/hooks", "event": "PreToolUse", "matcher": "Bash|apply_patch",
22
22
  "after_install": "Codex only runs new hooks after the user approves the definition in /hooks."},
@@ -55,8 +55,13 @@ def _without_ours(groups):
55
55
  return kept
56
56
 
57
57
 
58
- def installed(client):
59
- """Our hook is present with the current matcher; an entry with an older matcher counts as missing."""
58
+ def _target(handler):
59
+ return handler.get("url") or handler.get("command") or ""
60
+
61
+
62
+ def inspect(client):
63
+ """Our hook in the client's config: `current`, `missing`, or `outdated` (an older entry of ours) with `changes`,
64
+ plain sentences saying what an update rewrites (tools the old matcher leaves out, an old address or timeout)."""
60
65
  spec = CLIENTS[client]
61
66
  for path in spec["files"]:
62
67
  try:
@@ -67,30 +72,56 @@ def installed(client):
67
72
  if MARKER not in text and HTTP_PATH not in text:
68
73
  continue
69
74
  if not path.endswith(".json"):
70
- return True
75
+ return {"state": "current", "changes": []}
71
76
  data = json.loads(text)
72
77
  hooks = data.get("hooks") if isinstance(data, dict) else None
73
78
  groups = hooks.get(spec["event"]) if isinstance(hooks, dict) else None
79
+ ours = [group for group in groups if _ours(group)] if isinstance(groups, list) else []
80
+ if not ours:
81
+ return {"state": "outdated", "changes": [f"Smart Tool's entry is not under {spec['event']}."]}
74
82
  expected = _handler(client)
75
- return isinstance(groups, list) and any(
76
- group.get("matcher") == spec["matcher"] and expected in group["hooks"] for group in groups if _ours(group))
77
- return False
83
+ if any(group.get("matcher") == spec["matcher"] and expected in group["hooks"] for group in ours):
84
+ return {"state": "current", "changes": []}
85
+ group = ours[0]
86
+ changes = []
87
+ covered = str(group.get("matcher") or "").split("|")
88
+ left_out = [tool for tool in spec["matcher"].split("|") if tool not in covered]
89
+ if left_out:
90
+ changes.append("It does not cover " + ", ".join(left_out) + ".")
91
+ found = next(hook for hook in group["hooks"] if _our_hook(hook))
92
+ if _target(found) != _target(expected):
93
+ changes.append(f"It calls {_target(found)} instead of {_target(expected)}.")
94
+ elif found != expected:
95
+ changes.append("Its timeout or type is older than the current one.")
96
+ if not changes:
97
+ changes.append("Its tool list is ordered or written differently from the current one.")
98
+ return {"state": "outdated", "changes": changes}
99
+ return {"state": "missing", "changes": []}
100
+
101
+
102
+ def installed(client):
103
+ """Our hook is present and current; an older entry of ours counts as not installed."""
104
+ return inspect(client)["state"] == "current"
78
105
 
79
106
 
80
107
  def status(client_info):
108
+ """Hook state for an MCP client's clientInfo: `installed` (bool, None when unreadable or unknown client), `state`
109
+ (current/outdated/missing), `changes` an update would make, `error`, the config `files` and `docs`."""
81
110
  client = identify(client_info)
82
111
  if client is None:
83
112
  return {"client": None, "name": (client_info or {}).get("name"), "installed": None, "error": None}
84
113
  spec = CLIENTS[client]
85
114
  try:
86
- state, error = installed(client), None
115
+ found, error = inspect(client), None
87
116
  except (OSError, ValueError) as exc:
88
- state, error = None, f"{type(exc).__name__}: {exc}"[:200]
89
- return {"client": client, "name": client_info.get("name"), "installed": state, "error": error,
90
- "files": spec["files"], "docs": spec["docs"]}
117
+ found, error = {"state": None, "changes": []}, f"{type(exc).__name__}: {exc}"[:200]
118
+ return {"client": client, "name": client_info.get("name"),
119
+ "installed": None if found["state"] is None else found["state"] == "current", "state": found["state"],
120
+ "changes": found["changes"], "error": error, "files": spec["files"], "docs": spec["docs"]}
91
121
 
92
122
 
93
123
  def notice(state):
124
+ """Sentence for the agent when the hook is not current (from `status`), or None when nothing needs saying."""
94
125
  if state["client"] is None:
95
126
  return (f"Unrecognized MCP client ({state['name'] or 'no clientInfo'}): Smart Tool does not check the hook "
96
127
  "that redirects Grep/Read to smart_search and WebSearch/WebFetch to web_search/web_fetch in this client.")
@@ -101,7 +132,10 @@ def notice(state):
101
132
  return None
102
133
  action = spec.get("blocked") or ("If the user asks, use project_manage action=install_hook_preview, show the "
103
134
  "change and confirm with action=install_hook (makes a backup).")
104
- return (f"Smart Tool hook missing or outdated in {spec['label']} ({spec['files'][0]}): Grep/Read/Bash are not "
135
+ if state.get("state") == "outdated":
136
+ return (f"Smart Tool hook outdated in {spec['label']} ({spec['files'][0]}): {' '.join(state['changes'])} "
137
+ f"{action} Docs: {spec['docs']}")
138
+ return (f"Smart Tool hook missing in {spec['label']} ({spec['files'][0]}): Grep/Read/Bash are not "
105
139
  f"redirected to smart_search, nor WebSearch/WebFetch to web_search/web_fetch. {action} Docs: {spec['docs']}")
106
140
 
107
141
 
package/hook_decision.py CHANGED
@@ -27,6 +27,7 @@ EDIT_TOOLS = ("Edit", "MultiEdit", "Write", "apply_patch")
27
27
  MAX_DOC_FINDINGS = 5
28
28
  MAX_DUPLICATE_FINDINGS = 3
29
29
  SMART_TOOL_SERVER = "smart-tool"
30
+ SMART_SEARCH_TOOL = f"mcp__{SMART_TOOL_SERVER}__smart_search"
30
31
  REASON_MAX_CHARS = 200
31
32
 
32
33
 
@@ -260,6 +261,12 @@ def decide(payload, client, web_route):
260
261
  if doc_mode == "off" and duplicate_mode == "off":
261
262
  return {}
262
263
  return _edit_review(payload, doc_mode, duplicate_mode)
264
+ if isinstance(payload, dict) and str(payload.get("tool_name")).startswith(f"mcp__{SMART_TOOL_SERVER}__"):
265
+ if payload["tool_name"] == SMART_SEARCH_TOOL:
266
+ router.CLIENT.set(client)
267
+ router.SESSION.set(payload.get("session_id"))
268
+ router._log_decision(SMART_SEARCH_TOOL, {}, "allow", "Smart Tool search, logged to measure followed redirects")
269
+ return {}
263
270
  mode = config.hook_mode(cfg)
264
271
  if mode == "off" or not isinstance(payload, dict):
265
272
  return {}
@@ -288,6 +295,7 @@ def _route(payload, client, web_route, cfg):
288
295
  decision = web_route(tool_name, url)
289
296
  return deny(web_message(client, tool_name, url, clean_reason(decision.get("reason")))) if decision.get("redirect") else {}
290
297
  router.CLIENT.set(client)
298
+ router.SESSION.set(payload.get("session_id"))
291
299
  try:
292
300
  decision, reason, target = router.decide(tool_name, tool_input, cwd=cwd)
293
301
  except Exception as exc:
@@ -2,6 +2,7 @@ import collections
2
2
  import json
3
3
  import os
4
4
  import paths
5
+ import re
5
6
  import threading
6
7
  import time
7
8
 
@@ -11,6 +12,12 @@ import router
11
12
  PATH = os.path.join(paths.DATA_DIR, "integration-metrics.jsonl")
12
13
  MAX_BYTES = 20 * 1024 * 1024
13
14
  _LOCK = threading.Lock()
15
+ FOLLOW_WINDOW_S = 900
16
+ # Measured on 2026-10-12 with docs/spikes/bash_bypass_replay.py over 3 days of Claude Code transcripts (14,580 Grep and
17
+ # shell calls), at ~4 characters per token: the 310 calls the rule redirects put 2,031 characters on average in the
18
+ # context when they ran; a smart_search round trip (pending reply 716 + result 7,924) puts 8,640.
19
+ NATIVE_REDIRECTED_TOKENS = 510
20
+ SMART_SEARCH_TOKENS = 2160
14
21
 
15
22
 
16
23
  def record(event, **fields):
@@ -78,5 +85,48 @@ def summary(days=7):
78
85
  return {"days": days, "events_by_client": {k: dict(v) for k, v in by_client.items()},
79
86
  "rejects_by_kind": dict(rejects), "single_language_reasons": dict(reasons.most_common(20)),
80
87
  "hook_decisions_by_client": {k: dict(v) for k, v in decisions.items()},
88
+ "redirects": redirects(days),
81
89
  "web_search_cache": web_cache,
82
90
  "files": {"integration": PATH, "router": router.METRICS_PATH}}
91
+
92
+
93
+ def _next_in_session(rows, index):
94
+ """The session's next logged call within FOLLOW_WINDOW_S of rows[index], or None."""
95
+ start = rows[index]["ts"]
96
+ return next((row for row in rows[index + 1:] if row["ts"] - start <= FOLLOW_WINDOW_S), None)
97
+
98
+
99
+ def redirects(days=7):
100
+ """Redirects of native searches in the last days and what the same session did next: called smart_search
101
+ (followed), ran an allowed native call such as reading a file it found (native), was blocked again, or made no other
102
+ call within FOLLOW_WINDOW_S. Redirects logged without a session (before 0.9.15, or a client that sends none) count
103
+ as unknown. tokens_per_call holds the measured context of each side, so the panel never claims a saving it did
104
+ not measure."""
105
+ rows = sorted(_read(router.METRICS_PATH, time.time() - days * 86400), key=lambda row: row["ts"])
106
+ sessions = collections.defaultdict(list)
107
+ for row in rows:
108
+ if row.get("session"):
109
+ sessions[row["session"]].append(row)
110
+ by_tool, by_reason, outcomes = collections.Counter(), collections.Counter(), collections.Counter()
111
+ for row in rows:
112
+ if row.get("decision") != "redirect":
113
+ continue
114
+ by_tool[row.get("tool_name") or "?"] += 1
115
+ by_reason[re.sub(r"\d+", "N", str(row.get("reason") or "?"))[:80]] += 1
116
+ own = sessions.get(row.get("session"))
117
+ if not own:
118
+ outcomes["unknown"] += 1
119
+ continue
120
+ after = _next_in_session(own, own.index(row))
121
+ if after is None:
122
+ outcomes["no_other_call"] += 1
123
+ elif str(after.get("tool_name", "")).startswith("mcp__smart-tool__"):
124
+ outcomes["followed"] += 1
125
+ elif after.get("decision") == "redirect":
126
+ outcomes["blocked_again"] += 1
127
+ else:
128
+ outcomes["native"] += 1
129
+ return {"days": days, "total": sum(by_tool.values()), "by_tool": dict(by_tool),
130
+ "by_reason": dict(by_reason.most_common(8)), "outcomes": dict(outcomes),
131
+ "tokens_per_call": {"native_redirected": NATIVE_REDIRECTED_TOKENS, "smart_search": SMART_SEARCH_TOKENS,
132
+ "measured": "2026-10-12, 3 days of Claude Code transcripts"}}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@allansantos-dev/smart-tool",
3
- "version": "0.9.14",
3
+ "version": "0.9.16",
4
4
  "description": "Local MCP server that gives coding agents (Claude Code, Codex) cheaper, sharper tools than their built-in search. Windows.",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Allan Santos",