@allansantos-dev/smart-tool 0.9.22 → 0.9.24

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,43 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.9.24 - beta
4
+
5
+ - A redirected search now tells the agent what happened: the answer opens with a line saying the search was redirected to
6
+ `smart_search` (index, related code, dependency map), that the index of the project is still loading when the answer is
7
+ a keyword search of the disk (the next searches will have it ready), and to keep using `smart_search`. Before, the
8
+ answer carried no word of the redirect.
9
+ - The deny text of a search that cannot be redirected no longer says that reading or searching inside one known file is
10
+ never blocked: no message the agent receives offers a way around the redirect (file by file, narrower scope).
11
+ `NoWayAroundTheRedirectTest` fails if any of those texts (deny, advice, redirect notice, cold-index and stale-index
12
+ warnings) suggests one.
13
+
14
+ ## 0.9.23 - beta
15
+
16
+ - The hook no longer blocks. A content search over a project folder (the Grep tool on a folder, `grep -r`, `rg`,
17
+ `git grep`, `findstr /s`, `Select-String` over a listing, an inline python/node script that walks a folder) and
18
+ native WebFetch/WebSearch are answered by Smart Tool, and the answer comes back as the output of the call the agent
19
+ made, with no block message: before, the deny pushed agents to retry the same search through Bash and the Smart Tool
20
+ went unused. The query is the search pattern of the call (regex syntax dropped); the project is the registered one
21
+ holding the folder, else the session folder.
22
+ - Claude Code: a new PostToolUse entry (`/hooks/posttool`, 60 s) puts the answer in the tool's own output, in the
23
+ shape that tool returns. A shell search whose answer is ready within 10 s runs as a no-op (`true`, `$null` in
24
+ PowerShell), so a grep with no match no longer ends in exit 1; a later answer replaces the native output when the
25
+ command succeeds. WebFetch and WebSearch still run natively and their result is replaced (measured on Claude Code
26
+ 2.1.300: a PreToolUse cannot skip them, and a WebFetch pointed at the daemon fails because http turns into https).
27
+ WebSearch with `allowed_domains`/`blocked_domains` is left alone.
28
+ - Codex: the shell search is rewritten to `cat` a file holding the answer, approved with `allow` (Codex applies a
29
+ rewrite only with it); the daemon lets `allow` through for that command and nothing else.
30
+ - A Smart Tool call that fails or does not answer in time leaves the native call and its output as they were. A deny,
31
+ with the exact call to make, remains only for a search whose pattern cannot be read from the command, and for a
32
+ client that sends no `tool_use_id`.
33
+ - A redirected shell search waits up to 10 s for its answer in the PreToolUse (a warm `smart_search` takes 4 to
34
+ 13 s with the reranker), so the PreToolUse entry's timeout goes back from 6 s to 15 s (Codex's thin command 5 s
35
+ to 14 s); every other decision keeps its 4 s budget in the daemon.
36
+ - The setup screen counts a redirect answered this way as `served`. The hook entry of an older version shows as
37
+ outdated until you accept the update (preview and backup first).
38
+ - `smart_search` with `mode=dossier` answers a narrow keyword query over `docs/research`, the backlog, `CLAUDE.md` and
39
+ `AGENTS.md` with ids, short excerpts and a time budget, without an index.
40
+
3
41
  ## 0.9.22 - beta
4
42
 
5
43
  - The review of an Edit or Write (docstring reminder, copied-function check) is about twice as fast on a warm daemon
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.22 beta. Windows only. What changed in each version: [CHANGELOG.md](CHANGELOG.md).
18
+ **Status:** 0.9.24 beta. Windows only. What changed in each version: [CHANGELOG.md](CHANGELOG.md).
19
19
 
20
20
  ## How it works
21
21
 
@@ -122,8 +122,14 @@ Redirects) and Maintenance (Setup audit, Startup).
122
122
  `claude mcp remove playwright -s user` / `codex mcp remove playwright`.
123
123
 
124
124
  The hook behaviors:
125
- - **Redirect** (default): the native tool is denied with the reason and the Smart Tool tool to use. The decision
126
- is a fixed rule, under a millisecond and the same every time: a content search over a project folder (`grep -r`,
125
+ - **Redirect** (default): the call is not denied. Smart Tool answers it and the answer comes back as the output
126
+ of the call the agent made: `smart_search` for a search, `web_fetch` for WebFetch, `web_search` for WebSearch
127
+ (without `allowed_domains`/`blocked_domains`). In Claude Code a PostToolUse entry swaps the output (WebFetch and
128
+ WebSearch still run natively, their result is replaced); a shell search whose answer is ready within 10 s runs as a
129
+ no-op instead, so a grep with no match does not end in exit 1. In Codex the shell search is rewritten to print the
130
+ answer from a file. When the Smart Tool call fails or is late, the native call and its output stay as they are; a
131
+ deny, with the exact call to make, is left only for a search whose query cannot be read from the command. The
132
+ decision is a fixed rule, under a millisecond and the same every time: a content search over a project folder (`grep -r`,
127
133
  `rg`, `git grep`, the Grep tool on a folder) or over more than 20 listed files goes to `smart_search`, in Bash and
128
134
  PowerShell alike and also when it is wrapped (`bash -c`, `powershell -Command`, `timeout`, a subshell), looped
129
135
  (`for f in src/*.py`), fed by a listing (`find -exec grep`, `xargs`, `Get-ChildItem | Select-String`) or written
@@ -131,7 +137,7 @@ Redirects) and Maintenance (Setup audit, Startup).
131
137
  listings, Glob and commands that change files run. The setup screen counts the redirects and what each session
132
138
  did next. With **Block patterns proposed by a
133
139
  model** on (default), the scope model reviews, in the background, bulk reads the rule could not measure and
134
- proposes regex patterns, each checked against the logged calls; a pattern blocks only after you accept it.
140
+ proposes regex patterns, each checked against the logged calls; a pattern redirects only after you accept it.
135
141
  - **Advise only**: the native tool runs; the agent receives the same advice next to the result and decides.
136
142
  - **Off**: no routing.
137
143
 
package/client_hooks.py CHANGED
@@ -15,12 +15,17 @@ AUDIT_MARKER = "session_audit.py"
15
15
  AUDIT_MATCHER = "startup|resume|clear"
16
16
  AUDIT_TIMEOUT_S = 10
17
17
  HTTP_PATH = "/hooks/pretool"
18
- HTTP_TIMEOUT_S = 6
18
+ POST_PATH = "/hooks/posttool"
19
+ # A redirected shell search waits for its answer in the PreToolUse (smart_tool_daemon.HOOK_SHELL_BUDGET_S).
20
+ HTTP_TIMEOUT_S = 15
21
+ # The PostToolUse waits for the Smart Tool answer of a redirected call (web_fetch reads a whole page).
22
+ POST_TIMEOUT_S = 60
19
23
  HOME = os.path.expanduser("~")
20
24
  PREVIEW_TTL_S = 600
21
25
  CLIENTS = {
22
26
  "claude": {"label": "Claude Code", "names": {"claude-code"}, "files": [os.path.join(endpoint_sync.claude_dir(), "settings.json")],
23
- "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},
27
+ "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,
28
+ "post_matcher": "Grep|Bash|PowerShell|WebFetch|WebSearch"},
24
29
  "codex": {"label": "Codex", "prefix": "codex", "files": [os.path.join(endpoint_sync.codex_dir(), "hooks.json"), os.path.join(endpoint_sync.codex_dir(), "config.toml")],
25
30
  "docs": "https://learn.chatgpt.com/docs/hooks", "event": "PreToolUse", "matcher": "Bash|apply_patch",
26
31
  "after_install": "Codex only runs new hooks after the user approves the definition in /hooks."},
@@ -39,7 +44,18 @@ def identify(client_info):
39
44
 
40
45
 
41
46
  def _our_hook(hook):
42
- return isinstance(hook, dict) and (MARKER in str(hook.get("command", "")) or HTTP_PATH in str(hook.get("url", "")))
47
+ return isinstance(hook, dict) and (MARKER in str(hook.get("command", "")) or
48
+ any(path in str(hook.get("url", "")) for path in (HTTP_PATH, POST_PATH)))
49
+
50
+
51
+ def _entries(client):
52
+ """{event: (matcher, handler)} of our hook entries for the client: the PreToolUse, plus the PostToolUse that returns
53
+ the Smart Tool answer of a redirected call in Claude Code."""
54
+ spec = CLIENTS[client]
55
+ entries = {spec["event"]: (spec["matcher"], _handler(client))}
56
+ if spec.get("post_matcher"):
57
+ entries["PostToolUse"] = (spec["post_matcher"], _handler(client, POST_PATH, POST_TIMEOUT_S))
58
+ return entries
43
59
 
44
60
 
45
61
  def _ours(group):
@@ -79,30 +95,37 @@ def inspect(client):
79
95
  return {"state": "current", "changes": []}
80
96
  data = json.loads(text)
81
97
  hooks = data.get("hooks") if isinstance(data, dict) else None
82
- groups = hooks.get(spec["event"]) if isinstance(hooks, dict) else None
83
- ours = [group for group in groups if _ours(group)] if isinstance(groups, list) else []
84
- if not ours:
85
- return {"state": "outdated", "changes": [f"Smart Tool's entry is not under {spec['event']}."]}
86
- expected = _handler(client)
87
- if any(group.get("matcher") == spec["matcher"] and expected in group["hooks"] for group in ours):
88
- return {"state": "current", "changes": []}
89
- group = ours[0]
90
98
  changes = []
91
- covered = str(group.get("matcher") or "").split("|")
92
- left_out = [tool for tool in spec["matcher"].split("|") if tool not in covered]
93
- if left_out:
94
- changes.append("It does not cover " + ", ".join(left_out) + ".")
95
- found = next(hook for hook in group["hooks"] if _our_hook(hook))
96
- if _target(found) != _target(expected):
97
- changes.append(f"It calls {_target(found)} instead of {_target(expected)}.")
98
- elif found != expected:
99
- changes.append("Its timeout or type is older than the current one.")
100
- if not changes:
101
- changes.append("Its tool list is ordered or written differently from the current one.")
102
- return {"state": "outdated", "changes": changes}
99
+ for event, (matcher, expected) in _entries(client).items():
100
+ groups = hooks.get(event) if isinstance(hooks, dict) else None
101
+ changes += _entry_changes(event, matcher, expected, groups)
102
+ return {"state": "outdated" if changes else "current", "changes": changes}
103
103
  return {"state": "missing", "changes": []}
104
104
 
105
105
 
106
+ def _entry_changes(event, matcher, expected, groups):
107
+ """Sentences saying what an update rewrites in our entry under one event; empty when it is current."""
108
+ ours = [group for group in groups if _ours(group)] if isinstance(groups, list) else []
109
+ if not ours:
110
+ return [f"Smart Tool's entry is not under {event}."]
111
+ if any(group.get("matcher") == matcher and expected in group["hooks"] for group in ours):
112
+ return []
113
+ group = ours[0]
114
+ changes = []
115
+ covered = str(group.get("matcher") or "").split("|")
116
+ left_out = [tool for tool in matcher.split("|") if tool not in covered]
117
+ if left_out:
118
+ changes.append(f"Its {event} entry does not cover " + ", ".join(left_out) + ".")
119
+ found = next(hook for hook in group["hooks"] if _our_hook(hook))
120
+ if _target(found) != _target(expected):
121
+ changes.append(f"It calls {_target(found)} instead of {_target(expected)}.")
122
+ elif found != expected:
123
+ changes.append("Its timeout or type is older than the current one.")
124
+ if not changes:
125
+ changes.append("Its tool list is ordered or written differently from the current one.")
126
+ return changes
127
+
128
+
106
129
  def installed(client):
107
130
  """Our hook is present and current; an older entry of ours counts as not installed."""
108
131
  return inspect(client)["state"] == "current"
@@ -160,18 +183,20 @@ def _command(client):
160
183
  return f"{_shell_safe(sys.executable)} {_shell_safe(HOOK_SCRIPT)} --client {client}"
161
184
 
162
185
 
163
- def _handler(client):
186
+ def _handler(client, route=HTTP_PATH, timeout=HTTP_TIMEOUT_S):
164
187
  """Claude Code posts the payload straight to the warm daemon (`type: "http"`, no process per tool call); other
165
- clients run the thin command that forwards to the same route."""
188
+ clients run the thin command that forwards to the PreToolUse route."""
166
189
  if CLIENTS[client].get("http"):
167
190
  registry = daemon_launcher.read_registry()
168
191
  if not registry or not registry.get("url"):
169
192
  raise ValueError("Smart Tool daemon has no registered URL; start the daemon before installing the hook.")
170
- return {"type": "http", "url": f"{registry['url']}{HTTP_PATH}?client={client}", "timeout": HTTP_TIMEOUT_S}
171
- return {"type": "command", "command": _command(client), "timeout": HTTP_TIMEOUT_S}
193
+ return {"type": "http", "url": f"{registry['url']}{route}?client={client}", "timeout": timeout}
194
+ return {"type": "command", "command": _command(client), "timeout": timeout}
172
195
 
173
196
 
174
197
  def _plan(client_info):
198
+ """(client, spec, path, data, changes): the client's config with our entries already taken out, and changes
199
+ {event: (groups, entry)}, the entry to append to each event's groups."""
175
200
  client = identify(client_info)
176
201
  if client is None:
177
202
  raise ValueError(f"Unrecognized MCP client ({(client_info or {}).get('name') or 'no clientInfo'}); "
@@ -187,21 +212,26 @@ def _plan(client_info):
187
212
  data = {}
188
213
  if not isinstance(data, dict) or not isinstance(data.setdefault("hooks", {}), dict):
189
214
  raise ValueError(f"{path} does not have the expected format (object with 'hooks'); nothing was changed.")
190
- groups = data["hooks"].setdefault(spec["event"], [])
191
- if not isinstance(groups, list):
192
- raise ValueError(f"{path}: hooks.{spec['event']} is not a list; nothing was changed.")
193
- groups[:] = _without_ours(groups)
194
- entry = {"matcher": spec["matcher"], "hooks": [_handler(client)]}
195
- return client, spec, path, data, groups, entry
215
+ changes = {}
216
+ for event, (matcher, handler) in _entries(client).items():
217
+ groups = data["hooks"].setdefault(event, [])
218
+ if not isinstance(groups, list):
219
+ raise ValueError(f"{path}: hooks.{event} is not a list; nothing was changed.")
220
+ groups[:] = _without_ours(groups)
221
+ changes[event] = (groups, {"matcher": matcher, "hooks": [handler]})
222
+ return client, spec, path, data, changes
196
223
 
197
224
 
198
225
  def preview(client_info):
199
- client, spec, path, _data, _groups, entry = _plan(client_info)
226
+ """The entries install would write for client_info's client ({event: entry} in `change`, None when current) and
227
+ the token `install` needs."""
228
+ client, spec, path, _data, changes = _plan(client_info)
200
229
  if installed(client):
201
230
  return {"client": client, "installed": True, "file": path, "change": None}
202
231
  token = secrets.token_urlsafe(12)
203
232
  _PREVIEWS[token] = {"client": client, "at": time.time()}
204
- return {"client": client, "installed": False, "file": path, "event": spec["event"], "change": entry,
233
+ return {"client": client, "installed": False, "file": path,
234
+ "change": {event: entry for event, (_groups, entry) in changes.items()},
205
235
  "token": token, "expires_s": PREVIEW_TTL_S, "after_install": spec.get("after_install")}
206
236
 
207
237
 
@@ -209,12 +239,13 @@ def install(client_info, token, confirm):
209
239
  """Writes the redirect hook for client_info's client with a backup; needs the `preview` token of this session
210
240
  (10 min) and confirm=True. Returns {client, installed, changed, file, backup}."""
211
241
  planned = _PREVIEWS.pop(token or "", None)
212
- client, spec, path, data, groups, entry = _plan(client_info)
242
+ client, spec, path, data, changes = _plan(client_info)
213
243
  if confirm is not True or not planned or planned["client"] != client or time.time() - planned["at"] > PREVIEW_TTL_S:
214
244
  raise ValueError("Installing requires the install_hook_preview token from this session (valid for 10 min) and confirm=true.")
215
245
  if installed(client):
216
246
  return {"client": client, "installed": True, "changed": False, "file": path}
217
- groups.append(entry)
247
+ for groups, entry in changes.values():
248
+ groups.append(entry)
218
249
  backup = _write_checked(path, data, lambda: installed(client), "The hook")
219
250
  return {"client": client, "installed": True, "changed": True, "file": path, "backup": backup,
220
251
  "after_install": spec.get("after_install")}
package/dossier.py ADDED
@@ -0,0 +1,130 @@
1
+ """Dossier mode of smart_search: a narrow keyword query over the notes a project keeps about its own intent
2
+ (docs/research, the backlog, CLAUDE.md and AGENTS.md), answered with ids and one short excerpt per hit, inside a time
3
+ budget. It reads straight from disk, uses no index and no model, and never raises on a slow or unreadable file: it
4
+ stops at the deadline and says so in `degraded`/`reasons`."""
5
+ import json
6
+ import os
7
+ import re
8
+ import time
9
+
10
+ DEFAULT_TIMEOUT_MS = 800
11
+ MAX_TIMEOUT_MS = 5000
12
+ DEFAULT_MAX_HITS = 5
13
+ MAX_HITS = 10
14
+ SNIPPET_CHARS = 160
15
+ TITLE_CHARS = 80
16
+ MAX_FILE_BYTES = 512 * 1024
17
+ BACKLOG_FILES = ("docs/BACKLOG.md", "BACKLOG.md")
18
+ INSTRUCTION_FILES = (("CLAUDE.md", "claude_md"), (".claude/CLAUDE.md", "claude_md"), ("AGENTS.md", "agents_md"))
19
+ _TERM = re.compile(r"[\w]{2,}", re.UNICODE)
20
+ _UNIT_START = re.compile(r"#{1,6}\s|[-*]\s")
21
+
22
+
23
+ def _terms(query):
24
+ """Up to 24 distinct casefolded word terms of the query."""
25
+ return list(dict.fromkeys(term.casefold() for term in _TERM.findall(query or "")))[:24]
26
+
27
+
28
+ def _sources(root):
29
+ """`[(rel_path, kind)]` of the notes to read, newest research first so a timeout drops the oldest ones."""
30
+ found = []
31
+ base = os.path.join(root, "docs", "research")
32
+ for folder, dirs, files in os.walk(base):
33
+ dirs.sort()
34
+ found += [os.path.relpath(os.path.join(folder, name), root).replace(os.sep, "/")
35
+ for name in files if name.lower().endswith(".md")]
36
+ sources = [(rel, "research") for rel in sorted(found, reverse=True)]
37
+ sources += [(rel, "backlog") for rel in BACKLOG_FILES if os.path.isfile(os.path.join(root, rel))]
38
+ sources += [(rel, kind) for rel, kind in INSTRUCTION_FILES if os.path.isfile(os.path.join(root, rel))]
39
+ return sources
40
+
41
+
42
+ def _units(lines):
43
+ """`[(first_line_number, [lines])]`: a unit starts at a heading or a bullet at column 0 and runs to the next one."""
44
+ units, current = [], None
45
+ for number, line in enumerate(lines, 1):
46
+ if _UNIT_START.match(line) or current is None:
47
+ current = (number, [])
48
+ units.append(current)
49
+ current[1].append(line)
50
+ return units
51
+
52
+
53
+ def _clean(text):
54
+ return re.sub(r"\s+", " ", re.sub(r"[#*`>]+", "", text)).strip()
55
+
56
+
57
+ def _snippet(unit_lines, terms):
58
+ """The text around the first term found in the unit body, `SNIPPET_CHARS` long at most."""
59
+ body = _clean(" ".join(unit_lines))
60
+ low = body.casefold()
61
+ at = min((low.find(term) for term in terms if term in low), default=0)
62
+ start = max(0, at - SNIPPET_CHARS // 4)
63
+ piece = body[start:start + SNIPPET_CHARS].strip()
64
+ return ("…" if start else "") + piece + ("…" if start + SNIPPET_CHARS < len(body) else "")
65
+
66
+
67
+ def _score(unit_lines, terms):
68
+ """Distinct terms in the unit, a term in its first line (the title) counting double."""
69
+ low = " ".join(unit_lines).casefold()
70
+ title = unit_lines[0].casefold()
71
+ return sum((term in low) + (term in title) for term in terms)
72
+
73
+
74
+ def query(root, text, timeout_ms=DEFAULT_TIMEOUT_MS, max_hits=DEFAULT_MAX_HITS):
75
+ """The dossier answer for `text` over the notes of `root`: `{"mode", "degraded", "reasons", "elapsed_ms",
76
+ "scanned", "hits": [{"id", "source", "title", "snippet"}]}`, best hit first. `id` is `path:line` of the unit's
77
+ first line. `degraded` is true when the deadline cut the scan or a file could not be read; `hits` then holds what
78
+ was found until then."""
79
+ started = time.monotonic()
80
+ deadline = started + timeout_ms / 1000
81
+ terms = _terms(text)
82
+ reasons, scanned, unreadable, scored = [], 0, [], []
83
+ for rel, kind in _sources(root):
84
+ if time.monotonic() > deadline:
85
+ reasons.append(f"timeout after {timeout_ms} ms")
86
+ break
87
+ scanned += 1
88
+ path = os.path.join(root, rel)
89
+ try:
90
+ if os.path.getsize(path) > MAX_FILE_BYTES:
91
+ unreadable.append(f"{rel}: over {MAX_FILE_BYTES} bytes")
92
+ continue
93
+ with open(path, encoding="utf-8", errors="replace") as handle:
94
+ lines = handle.read().splitlines()
95
+ except OSError as exc:
96
+ unreadable.append(f"{rel}: {type(exc).__name__}")
97
+ continue
98
+ for number, unit in _units(lines):
99
+ score = _score(unit, terms)
100
+ if score:
101
+ scored.append((score, rel, kind, number, unit))
102
+ if unreadable:
103
+ reasons.append("not read: " + "; ".join(unreadable[:5]))
104
+ scored.sort(key=lambda item: -item[0])
105
+ hits = [{"id": f"{rel}:{number}", "source": kind, "title": _clean(unit[0])[:TITLE_CHARS],
106
+ "snippet": _snippet(unit, terms)} for _score_value, rel, kind, number, unit in scored[:max_hits]]
107
+ return {"mode": "dossier", "degraded": bool(reasons), "reasons": reasons,
108
+ "elapsed_ms": round((time.monotonic() - started) * 1000), "scanned": scanned, "hits": hits}
109
+
110
+
111
+ def answer(arguments):
112
+ """The text smart_search returns for `mode=dossier`: the compact JSON of `query`. Raises ValueError for a missing
113
+ folder or text, or a `timeout_ms`/`max_hits` out of range, so the caller sees the error instead of an empty dossier."""
114
+ root = arguments.get("project_root")
115
+ if not isinstance(root, str) or not os.path.isdir(root):
116
+ raise ValueError("smart_search mode=dossier requires 'project_root' pointing to an existing folder")
117
+ text = next((arguments[key] for key in ("query_identifiers", "query_comments", "doc_query")
118
+ if isinstance(arguments.get(key), str) and arguments[key].strip()), "")
119
+ if not _terms(text):
120
+ raise ValueError("smart_search mode=dossier requires 'query_identifiers' (or 'doc_query') with at least one word.")
121
+ timeout_ms = _bounded(arguments, "timeout_ms", DEFAULT_TIMEOUT_MS, 1, MAX_TIMEOUT_MS)
122
+ max_hits = _bounded(arguments, "max_hits", DEFAULT_MAX_HITS, 1, MAX_HITS)
123
+ return json.dumps(query(root, text, timeout_ms, max_hits), ensure_ascii=False, separators=(",", ":"))
124
+
125
+
126
+ def _bounded(arguments, name, default, low, high):
127
+ value = arguments.get(name, default)
128
+ if isinstance(value, bool) or not isinstance(value, int) or not low <= value <= high:
129
+ raise ValueError(f"{name} must be an integer from {low} to {high}.")
130
+ return value
package/endpoint_sync.py CHANGED
@@ -15,6 +15,7 @@ import urllib.parse
15
15
 
16
16
  SERVER = "smart-tool"
17
17
  HOOK_PATH = "/hooks/pretool"
18
+ POST_HOOK_PATH = "/hooks/posttool"
18
19
  _CODEX_URL_RE = re.compile(r'(\[mcp_servers\.smart-tool\][^\[]*?\burl\s*=\s*")http://127\.0\.0\.1:\d+(/mcp")')
19
20
 
20
21
 
@@ -58,14 +59,17 @@ def _claude_mcp(text, base):
58
59
 
59
60
 
60
61
  def _claude_hook(text, base):
62
+ """settings.json text with our PreToolUse and PostToolUse hook URLs moved to base, or None when none changed."""
61
63
  data = json.loads(text)
62
64
  changed = False
63
- groups = ((data.get("hooks") or {}).get("PreToolUse") or []) if isinstance(data, dict) else []
64
- for group in groups if isinstance(groups, list) else []:
65
- for hook in (group.get("hooks") or []) if isinstance(group, dict) else []:
66
- if isinstance(hook, dict) and HOOK_PATH in str(hook.get("url", "")):
67
- new = _rebase(hook["url"], base)
68
- changed, hook["url"] = changed or new != hook["url"], new
65
+ hooks = (data.get("hooks") or {}) if isinstance(data, dict) else {}
66
+ for event, path in (("PreToolUse", HOOK_PATH), ("PostToolUse", POST_HOOK_PATH)):
67
+ groups = (hooks.get(event) or []) if isinstance(hooks, dict) else []
68
+ for group in groups if isinstance(groups, list) else []:
69
+ for hook in (group.get("hooks") or []) if isinstance(group, dict) else []:
70
+ if isinstance(hook, dict) and path in str(hook.get("url", "")):
71
+ new = _rebase(hook["url"], base)
72
+ changed, hook["url"] = changed or new != hook["url"], new
69
73
  return json.dumps(data, indent=2, ensure_ascii=False) if changed else None
70
74
 
71
75
 
package/hook_decision.py CHANGED
@@ -1,13 +1,15 @@
1
- """Decisão do PreToolUse do Smart Tool, tomada dentro do daemon já aquecido.
1
+ """Decisão do PreToolUse e do PostToolUse do Smart Tool, tomada dentro do daemon já aquecido.
2
2
 
3
- O Claude Code chama a rota POST /hooks/pretool como hook `type: "http"` (sem processo por chamada); o Codex usa o
4
- hook de comando `hooks/pretool_router.py`, que só repassa o payload para a mesma rota.
3
+ O Claude Code chama as rotas POST /hooks/pretool e /hooks/posttool como hooks `type: "http"` (sem processo por
4
+ chamada); o Codex usa o hook de comando `hooks/pretool_router.py`, que só repassa o payload para /hooks/pretool.
5
5
 
6
- INVARIANTE: a saída só pode ser `{}` (neutra) ou `deny`. `permissionDecision: "allow"` pula a confirmação do usuário
7
- no Claude Code, e nenhuma decisão aqui é sobre periculosidade, só sobre custo de contexto. Diagnóstico vai em
6
+ Uma busca nativa que a regra redireciona, e WebFetch/WebSearch, não são negadas: o Smart Tool responde no lugar e o
7
+ texto volta como saída da própria chamada (`tool_redirect`). INVARIANTE: a saída do PreToolUse é `{}`, `updatedInput`
8
+ sem `permissionDecision` (as regras de permissão do usuário julgam a chamada reescrita), `allow` só junto do comando
9
+ que o próprio hook escreveu para imprimir a resposta no Codex (`tool_redirect.is_codex_command`), ou `deny` quando a
10
+ chamada não dá para montar. Nenhuma decisão aqui é sobre periculosidade, só sobre custo de contexto. Diagnóstico vai em
8
11
  `systemMessage`, que não altera permissão.
9
12
  """
10
- import json
11
13
  import os
12
14
 
13
15
  import code_graph
@@ -20,9 +22,18 @@ import index_profile
20
22
  import index_scope
21
23
  import endpoint_sync
22
24
  import project_store
25
+ import redirect_rule
23
26
  import router
27
+ import tool_redirect
24
28
 
25
29
  WEB_TOOLS = ("WebSearch", "WebFetch")
30
+ # A warm smart_search takes 4 to 13 s with the reranker, and in Codex a late answer is a lost one (no output
31
+ # replacement): a redirected shell search waits this long within the daemon's HOOK_SHELL_BUDGET_S. The PostToolUse
32
+ # entry has its own client timeout (60 s).
33
+ PRE_WAIT_S = 10.0
34
+ SEARCH_POST_WAIT_S = 15
35
+ WEB_POST_WAIT_S = 50
36
+ SINGLE_LANGUAGE_REASON = "redirected native search: its pattern is the only query there is"
26
37
  EDIT_TOOLS = ("Edit", "MultiEdit", "Write", "apply_patch")
27
38
  MAX_DOC_FINDINGS = 5
28
39
  MAX_DUPLICATE_FINDINGS = 3
@@ -102,13 +113,16 @@ def agent_has_smart_tool(agent_type, cwd):
102
113
 
103
114
 
104
115
  def _search_root(target, cwd):
105
- """project_root for smart_search: the registered project holding the folder the redirected search reads, else that
106
- folder; the session folder when the rule names none."""
116
+ """project_root for smart_search: the registered project holding the folder the redirected search reads, else the
117
+ session folder when it holds that folder (a subfolder is not indexed on its own), else that folder."""
107
118
  target = os.path.abspath(target or cwd or ".")
108
119
  key = os.path.normcase(target) + os.sep
109
120
  roots = [p["root"] for p in project_store.all_projects()
110
121
  if key.startswith(os.path.normcase(os.path.abspath(p["root"])).rstrip(os.sep) + os.sep)]
111
- return max(roots, key=len) if roots else target
122
+ if roots:
123
+ return max(roots, key=len)
124
+ session = os.path.abspath(cwd) if cwd else None
125
+ return session if session and key.startswith(os.path.normcase(session).rstrip(os.sep) + os.sep) else target
112
126
 
113
127
 
114
128
  def _tool_name(client, tool):
@@ -124,14 +138,14 @@ def _load_hint(client, tool):
124
138
 
125
139
  def redirect_message(client, tool_name, target, reason, cwd):
126
140
  """Deny text for a broad raw search: the exact tool and arguments to call (project_root from the folder the search
127
- reads), and that rewriting the same search in Bash, python, node or PowerShell is the bypass the rule stops."""
141
+ reads), and that rewriting the same search in Bash, python, node or PowerShell is the bypass the rule stops. It
142
+ never suggests a way around the rule (narrower or per-file searches): the only way offered is smart_search."""
128
143
  root = _search_root(target, cwd).replace("\\", "/")
129
144
  return (f"Blocked by Smart Tool, a routing rule set by the user, not a failure ({tool_name}: {clean_reason(reason)}). "
130
145
  f'Run this search with {_tool_name(client, "smart_search")}: project_root="{root}", query_identifiers = what '
131
146
  f"you are looking for in identifier terms (plus query_comments when the project has two languages)."
132
147
  f'{_load_hint(client, "smart_search")} Do not repeat the same search through Bash, python, node or '
133
- f"PowerShell: that bypasses the rule. Reading one known file, or searching inside one known file, is never "
134
- f"blocked.")
148
+ f"PowerShell: that bypasses the rule.")
135
149
 
136
150
 
137
151
  def web_message(client, tool_name, url, why):
@@ -146,24 +160,6 @@ def web_message(client, tool_name, url, why):
146
160
  f"{_load_hint(client, tool)} Do not fetch it through {fetchers}: that bypasses the rule.")
147
161
 
148
162
 
149
- def smart_tool_in_session(cwd):
150
- """Claude Code loads MCP servers from ~/.claude.json (user and per project) and the project's .mcp.json."""
151
- with open(endpoint_sync.claude_json(), encoding="utf-8") as stream:
152
- data = json.load(stream)
153
- key = os.path.normcase(os.path.normpath(cwd or ""))
154
- project = next((value for path, value in (data.get("projects") or {}).items()
155
- if os.path.normcase(os.path.normpath(path)) == key), {})
156
- if SMART_TOOL_SERVER in (project.get("disabledMcpServers") or []):
157
- return False
158
- if SMART_TOOL_SERVER in (data.get("mcpServers") or {}) or SMART_TOOL_SERVER in (project.get("mcpServers") or {}):
159
- return True
160
- try:
161
- with open(os.path.join(cwd or "", ".mcp.json"), encoding="utf-8") as stream:
162
- return SMART_TOOL_SERVER in (json.load(stream).get("mcpServers") or {})
163
- except (OSError, ValueError):
164
- return False
165
-
166
-
167
163
  def advise(reason):
168
164
  """Same routing advice without blocking: the agent sees it next to the tool result and decides next time."""
169
165
  return {"hookSpecificOutput": {"hookEventName": "PreToolUse",
@@ -255,10 +251,12 @@ def _edit_review_scoped(payload, doc_mode, duplicate_mode):
255
251
  return {"hookSpecificOutput": {"hookEventName": "PreToolUse", "additionalContext": message}}
256
252
 
257
253
 
258
- def decide(payload, client, web_route):
254
+ def decide(payload, client, web_route, jobs):
259
255
  """Hook output for one PreToolUse payload: edits follow doc_mode (require | remind | off) and duplicate_mode
260
- (warn | off), the other tools follow hook_mode (redirect | advise | off). A subagent whose tool list has no
261
- Smart Tool MCP tool is never redirected: it has nothing to switch to."""
256
+ (warn | off), the other tools follow hook_mode (redirect | advise | off). In redirect mode the Smart Tool call that
257
+ replaces a redirected one starts in `jobs` under the call's tool_use_id (see `_redirect`); only a search whose
258
+ query cannot be built, or a client that sends no tool_use_id, is denied with the exact call to make, and never in a
259
+ subagent whose tool list has no Smart Tool MCP tool: it has nothing to switch to."""
262
260
  cfg = config.load_config()
263
261
  if isinstance(payload, dict) and payload.get("tool_name") in EDIT_TOOLS:
264
262
  doc_mode, duplicate_mode = config.doc_mode(cfg), config.duplicate_mode(cfg)
@@ -274,30 +272,96 @@ def decide(payload, client, web_route):
274
272
  mode = config.hook_mode(cfg)
275
273
  if mode == "off" or not isinstance(payload, dict):
276
274
  return {}
277
- output = _route(payload, client, web_route, cfg)
278
- reason = (output.get("hookSpecificOutput") or {}).get("permissionDecisionReason")
279
- if reason and not agent_has_smart_tool(payload.get("agent_type") if payload.get("agent_id") else None,
280
- payload.get("cwd")):
275
+ plan = _route(payload, client, web_route, cfg)
276
+ if "kind" not in plan:
277
+ return plan
278
+ if mode == "advise":
279
+ return advise(plan["message"])
280
+ if plan["kind"] and payload.get("tool_use_id"):
281
+ return _redirect(payload, client, plan, jobs)
282
+ if not agent_has_smart_tool(payload.get("agent_type") if payload.get("agent_id") else None, payload.get("cwd")):
283
+ return {}
284
+ return deny(plan["message"])
285
+
286
+
287
+ def _redirect(payload, client, plan, jobs):
288
+ """Starts the Smart Tool call of a redirected one. A shell search whose answer comes within PRE_WAIT_S is rewritten
289
+ so the answer is all it prints: a no-op whose output the PostToolUse replaces in Claude Code, a `cat` of a file
290
+ holding the answer in Codex (which has no output replacement and applies a rewrite only with `allow`). Anything
291
+ else runs as the agent wrote it and, in Claude Code, `after` swaps its output for the answer."""
292
+ key, tool_name = payload["tool_use_id"], payload["tool_name"]
293
+ tool_input = payload.get("tool_input") if isinstance(payload.get("tool_input"), dict) else {}
294
+ jobs.start(key, plan["kind"], plan["arguments"])
295
+ if tool_name not in tool_redirect.NO_OP:
296
+ return {}
297
+ text = _answer(jobs, key, PRE_WAIT_S, tool_name)
298
+ if text is None:
299
+ return {}
300
+ if client != "codex":
301
+ return {"hookSpecificOutput": {"hookEventName": "PreToolUse",
302
+ "updatedInput": {**tool_input, "command": tool_redirect.NO_OP[tool_name]}}}
303
+ jobs.forget(key)
304
+ _log_served(client, payload)
305
+ return {"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "allow",
306
+ "permissionDecisionReason": "Smart Tool answered this search",
307
+ "updatedInput": {**tool_input, "command": tool_redirect.codex_command(text)}}}
308
+
309
+
310
+ def _answer(jobs, key, timeout, tool_name):
311
+ """The Smart Tool text of key within timeout; None when it is not ready or the call failed (logged: the native call
312
+ then runs as written)."""
313
+ try:
314
+ text = jobs.wait(key, timeout)
315
+ except Exception as exc:
316
+ jobs.forget(key)
317
+ router._log_error(f"redirect of {tool_name} not served: {type(exc).__name__}: {exc}")
318
+ return None
319
+ return text if isinstance(text, str) and text.strip() else None
320
+
321
+
322
+ def _log_served(client, payload):
323
+ router.CLIENT.set(client)
324
+ router.SESSION.set(payload.get("session_id"))
325
+ router._log_decision(payload.get("tool_name"), {}, "served", "Smart Tool answer returned as the call's output")
326
+
327
+
328
+ def after(payload, client, jobs):
329
+ """PostToolUse output: the call's own response with the Smart Tool answer started for its tool_use_id in the field
330
+ the model reads (`updatedToolOutput`), or `{}` when there is none, it did not come in time or the response has an
331
+ unknown shape (the native output stays)."""
332
+ if not isinstance(payload, dict) or not payload.get("tool_use_id"):
333
+ return {}
334
+ key, tool_name = payload["tool_use_id"], payload.get("tool_name")
335
+ text = _answer(jobs, key, WEB_POST_WAIT_S if tool_name in WEB_TOOLS else SEARCH_POST_WAIT_S, tool_name)
336
+ jobs.forget(key)
337
+ output = tool_redirect.output_for(tool_name, payload.get("tool_response"), text) if text else None
338
+ if output is None:
281
339
  return {}
282
- return advise(reason) if mode == "advise" and reason else output
340
+ _log_served(client, payload)
341
+ return {"hookSpecificOutput": {"hookEventName": "PostToolUse", "updatedToolOutput": output}}
283
342
 
284
343
 
285
344
  def _route(payload, client, web_route, cfg):
345
+ """`{}` or a `systemMessage` output when the call runs untouched, else the redirect plan: `kind` and `arguments`
346
+ of the Smart Tool call (kind None when no query can be built from the call) and `message`, the exact call for an
347
+ agent that has to make it itself."""
286
348
  tool_name = payload.get("tool_name", "")
287
349
  tool_input = payload.get("tool_input") if isinstance(payload.get("tool_input"), dict) else {}
288
350
  cwd = payload.get("cwd")
289
351
  if tool_name in WEB_TOOLS:
290
- if not cfg.get("router_model"):
291
- return {}
292
- try:
293
- present = smart_tool_in_session(cwd)
294
- except (OSError, ValueError):
295
- present = False
296
- if not present:
352
+ if not cfg.get("router_model") or tool_input.get("allowed_domains") or tool_input.get("blocked_domains"):
297
353
  return {}
298
354
  url = str(tool_input.get("url") or "")
299
355
  decision = web_route(tool_name, url)
300
- return deny(web_message(client, tool_name, url, clean_reason(decision.get("reason")))) if decision.get("redirect") else {}
356
+ if not decision.get("redirect"):
357
+ return {}
358
+ if tool_name == "WebFetch":
359
+ kind, arguments = "web_fetch", {"url": url, "prompt": str(tool_input.get("prompt") or "")}
360
+ else:
361
+ query = str(tool_input.get("query") or "")
362
+ kind, arguments = "web_search", {"query": query, "query_en": query}
363
+ return {"kind": kind if all(arguments.values()) else None, "arguments": arguments,
364
+ "message": web_message(client, tool_name, url, clean_reason(decision.get("reason")))}
301
365
  router.CLIENT.set(client)
302
366
  router.SESSION.set(payload.get("session_id"))
303
367
  try:
@@ -308,6 +372,10 @@ def _route(payload, client, web_route, cfg):
308
372
  except Exception:
309
373
  pass
310
374
  return {"systemMessage": f"Smart Tool unavailable, routing skipped: {type(exc).__name__}"}
311
- if decision == "redirect":
312
- return deny(redirect_message(client, tool_name, target, reason, cwd))
313
- return {}
375
+ if decision != "redirect" or (tool_name in tool_redirect.NO_OP and tool_input.get("run_in_background")):
376
+ return {}
377
+ terms = redirect_rule.search_terms(tool_name, tool_input)
378
+ arguments = {"project_root": _search_root(target, cwd), "query_identifiers": terms,
379
+ "single_language_reason": SINGLE_LANGUAGE_REASON}
380
+ return {"kind": "smart_search" if terms else None, "arguments": arguments,
381
+ "message": redirect_message(client, tool_name, target, reason, cwd)}
@@ -15,7 +15,8 @@ sys.stdout.reconfigure(encoding="utf-8")
15
15
  sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), ".."))
16
16
  import daemon_launcher
17
17
 
18
- TIMEOUT_S = 5
18
+ # Above the daemon's budget for a redirected shell search (smart_tool_daemon.HOOK_SHELL_BUDGET_S), below the entry's 15 s.
19
+ TIMEOUT_S = 14
19
20
 
20
21
 
21
22
  def _client():
@@ -97,8 +97,9 @@ def _next_in_session(rows, index):
97
97
 
98
98
 
99
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
100
+ """Redirects of native searches in the last days and what came next in the same session: the Smart Tool answer
101
+ returned as the call's output (served), a smart_search call (followed), an allowed native call such as reading a
102
+ file it found (native), another redirect (blocked_again), or no other
102
103
  call within FOLLOW_WINDOW_S. Redirects logged without a session (before 0.9.15, or a client that sends none) count
103
104
  as unknown. tokens_per_call holds the measured context of each side, so the panel never claims a saving it did
104
105
  not measure."""
@@ -120,6 +121,8 @@ def redirects(days=7):
120
121
  after = _next_in_session(own, own.index(row))
121
122
  if after is None:
122
123
  outcomes["no_other_call"] += 1
124
+ elif after.get("decision") == "served":
125
+ outcomes["served"] += 1
123
126
  elif str(after.get("tool_name", "")).startswith("mcp__smart-tool__"):
124
127
  outcomes["followed"] += 1
125
128
  elif after.get("decision") == "redirect":
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@allansantos-dev/smart-tool",
3
- "version": "0.9.22",
3
+ "version": "0.9.24",
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",
package/redirect_rule.py CHANGED
@@ -76,6 +76,10 @@ _CWD_WALK = re.compile(r"os\.getcwd\(\)|process\.cwd\(\)|Path\(\)|os\.walk\(\s*\
76
76
  _SINGLE_QUOTED = re.compile(r"'([^'\n]+)'")
77
77
  _DOUBLE_QUOTED = re.compile(r'"([^"\n]+)"')
78
78
  _PS_READ = re.compile(r"\b(?:get-content|gc|select-string|sls|cat|type)\b|\[io\.file\]", re.IGNORECASE)
79
+ _MATCHED_LITERAL = re.compile(r"""(?:\bre\.(?:search|findall|finditer|match|fullmatch|compile)\(\s*r?|"""
80
+ r"""\.(?:includes|indexOf|match|matchAll|search|test)\(\s*)(['"])(.+?)\1|"""
81
+ r"""(['"])([^'"\n]+)\3\s+in\s+\w+""")
82
+ QUERY_MAX_CHARS = 400
79
83
  _ASSIGN = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*)=(.*)$")
80
84
  _VARIABLE = re.compile(r"\$\{(\w+)\}|\$(\w+)")
81
85
 
@@ -318,29 +322,35 @@ def _inner_script(tokens):
318
322
 
319
323
 
320
324
  def _search_args(verb, tokens):
321
- """Path arguments of a grep-like command (the pattern and flag values dropped) and whether it is recursive."""
325
+ """(path arguments, recursive, patterns) of a grep-like command: the paths without the pattern and flag values,
326
+ whether it walks folders, and the text it looks for (`-e`/`-Pattern`/`/c:` values, else the first argument)."""
322
327
  if verb in ("select-string", "sls"):
323
328
  recursive = False
324
329
  else:
325
330
  recursive = verb in ALWAYS_RECURSIVE or any(
326
331
  t in RECURSIVE_FLAGS or (re.fullmatch(r"-[a-zA-Z]+", t) and ("r" in t or "R" in t)) for t in tokens)
327
- args, paths, skip, path_next, pattern_given = [], [], False, False, False
332
+ args, paths, patterns, skip, path_next, pattern_given = [], [], [], None, False, False
328
333
  for token in tokens:
329
334
  low = token.lower()
330
335
  if skip:
331
- skip = False
336
+ if skip == "pattern":
337
+ patterns.append(token)
338
+ skip = None
332
339
  elif path_next:
333
340
  paths.append(token)
334
341
  path_next = False
335
342
  elif token in PATTERN_FLAGS or low == "-pattern":
336
- skip, pattern_given = True, True
343
+ skip, pattern_given = ("value" if token in ("-f", "--file") else "pattern"), True
337
344
  elif low in ("-path", "-literalpath"):
338
345
  path_next = True
339
346
  elif token in VALUE_FLAGS or low in ("-include", "-exclude", "-context", "-encoding"):
340
- skip = True
347
+ skip = "value"
348
+ elif verb == "findstr" and low.startswith("/c:"):
349
+ patterns.append(token[3:])
350
+ pattern_given = True
341
351
  elif not token.startswith("-") and not (verb == "findstr" and token.startswith("/")):
342
352
  args.append(token)
343
- return paths + (args if pattern_given else args[1:]), recursive
353
+ return paths + (args if pattern_given else args[1:]), recursive, patterns if pattern_given else args[:1]
344
354
 
345
355
 
346
356
  def _reader_files(verb, tokens):
@@ -484,13 +494,19 @@ def _shell(command, cwd, state, powershell, depth):
484
494
  return verdict
485
495
 
486
496
 
487
- def _xargs_command(tokens):
488
- """The verb xargs runs, past its own flags."""
497
+ def _xargs_tokens(tokens):
498
+ """The command xargs runs, past its own flags."""
489
499
  rest = tokens[1:]
490
500
  while rest and rest[0].startswith("-"):
491
501
  flag = rest.pop(0)
492
502
  if flag in ("-I", "-n", "-P", "-d", "-L", "-s", "-E", "-a", "--delimiter", "--max-args", "--max-procs") and rest:
493
503
  rest.pop(0)
504
+ return rest
505
+
506
+
507
+ def _xargs_command(tokens):
508
+ """The verb xargs runs, past its own flags."""
509
+ rest = _xargs_tokens(tokens)
494
510
  return rest[0].lower() if rest else None
495
511
 
496
512
 
@@ -519,7 +535,7 @@ def _git(tokens, variables, base, cwd):
519
535
 
520
536
  def _search(verb, tokens, variables, base, cwd, verdict):
521
537
  """(redirect or None, verdict so far) for a grep-like command."""
522
- args, recursive = _search_args(verb, tokens[1:])
538
+ args, recursive, _patterns = _search_args(verb, tokens[1:])
523
539
  if LISTING in args:
524
540
  return (("redirect", base, "content search over the files of a listing") if _folder(base, cwd) else None), verdict
525
541
  if not args:
@@ -545,6 +561,56 @@ def _search(verb, tokens, variables, base, cwd, verdict):
545
561
  return None, verdict
546
562
 
547
563
 
564
+ def _command_patterns(command, powershell, depth):
565
+ """Patterns of the grep-like commands, `git grep`, `xargs grep` and `find -exec grep` of a shell command, inner
566
+ scripts and substitutions included."""
567
+ text, inner = _substitutions(_strip_heredocs(command), powershell)
568
+ found = []
569
+ for script in inner if depth < MAX_NESTING else ():
570
+ found += _command_patterns(script, powershell, depth + 1)
571
+ for segment, _after_pipe in segments(text):
572
+ tokens = _unwrap(_split(segment, powershell), {})
573
+ if not tokens:
574
+ continue
575
+ verb = tokens[0].lower()
576
+ script = _inner_script(tokens) if depth < MAX_NESTING else None
577
+ if script:
578
+ found += _command_patterns(script, re.sub(r"\.exe$", "", verb) in ("powershell", "pwsh", "cmd"), depth + 1)
579
+ continue
580
+ if verb == "xargs":
581
+ tokens = _xargs_tokens(tokens)
582
+ elif verb == "find":
583
+ start = next((i + 1 for i, t in enumerate(tokens) if t in ("-exec", "-execdir", "-ok", "-okdir")), None)
584
+ tokens = tokens[start:] if start else []
585
+ elif verb == "git":
586
+ tokens = tokens[tokens.index("grep"):] if "grep" in tokens else []
587
+ tokens = tokens[:tokens.index("--")] if "--" in tokens else tokens
588
+ if tokens and tokens[0].lower() in SEARCHERS | {"grep"}:
589
+ found += _search_args(tokens[0].lower(), tokens[1:])[2]
590
+ return found
591
+
592
+
593
+ def _regex_words(pattern):
594
+ """The literal words of a regular expression: classes, quantifiers, escapes and operators become spaces."""
595
+ text = re.sub(r"\[[^\]]*\]|\{\d*,?\d*\}|\\[a-zA-Z]|\(\?[:=!<]*", " ", pattern)
596
+ return re.sub(r"[\\^$.*+?()|{}\[\]]", " ", text)
597
+
598
+
599
+ def search_terms(tool_name, tool_input):
600
+ """The smart_search query of a redirected call: the words of the Grep pattern, of the patterns a shell command
601
+ searches for, or else of the string literals an inline script matches against. Empty when none is found."""
602
+ if tool_name == "Grep":
603
+ patterns = [str(tool_input.get("pattern") or "")]
604
+ else:
605
+ command = str(tool_input.get("command") or "")
606
+ patterns = _command_patterns(command, tool_name == "PowerShell", 0) or [
607
+ match.group(2) or match.group(4) for match in _MATCHED_LITERAL.finditer(command)]
608
+ words = []
609
+ for pattern in patterns:
610
+ words += [word for word in _regex_words(pattern).split() if word not in words]
611
+ return " ".join(words)[:QUERY_MAX_CHARS]
612
+
613
+
548
614
  def decide(tool_name, tool_input, cwd):
549
615
  """(decision, target, reason) for a Grep, Glob or Bash call: decision is redirect or allow, target the folder that
550
616
  would be searched (None when allowed)."""
package/setup_ui.py CHANGED
@@ -1281,7 +1281,7 @@ function agentCard(item) {
1281
1281
  const plan = await post("/setup/integration", { client: item.client, action: "preview" });
1282
1282
  setMsg(msg, "", "");
1283
1283
  if (plan.installed) { await loadIntegration(); return; }
1284
- confirmFile.textContent = (item.hook_state === "outdated" ? "Replaces Smart Tool's entry with this one under " : "Adds this entry under ") + plan.event + " in " + plan.file;
1284
+ confirmFile.textContent = (item.hook_state === "outdated" ? "Replaces Smart Tool's entries with these, by event, in " : "Adds these entries, by event, in ") + plan.file;
1285
1285
  preview.textContent = JSON.stringify(plan.change, null, 2);
1286
1286
  confirm.hidden = false;
1287
1287
  start.hidden = true;
@@ -50,6 +50,7 @@ import index_views
50
50
  import index_inventory
51
51
  import usage_meter
52
52
  import document_text
53
+ import dossier
53
54
  import embedding_cache
54
55
  import model_defaults
55
56
  import project_identity
@@ -73,6 +74,7 @@ import gateway
73
74
  import code_graph
74
75
  import hook_decision
75
76
  import endpoint_sync
77
+ import tool_redirect
76
78
 
77
79
  RUN_DIR = paths.DATA_DIR
78
80
  REGISTRY_PATH = os.path.join(RUN_DIR, "daemon.json")
@@ -331,18 +333,15 @@ def _smart_search_job_payload(job_id):
331
333
  return payload
332
334
 
333
335
  # Claude Code defers MCP tools behind tool search; the tools the hook redirects to (and their job polling) load
334
- # upfront, so a blocked agent already has the replacement in its tool list.
336
+ # upfront, so an agent denied by the hook already has the replacement in its tool list.
335
337
  ALWAYS_LOAD = {"anthropic/alwaysLoad": True}
336
338
  SERVER_INSTRUCTIONS = (
337
339
  "Smart Tool serves an indexed semantic search over the user's projects and a cheaper web reader. Use smart_search "
338
340
  "FIRST to explore code in the user's projects (where something is implemented, how a flow works, what already "
339
341
  "exists to reuse) before reading files one by one; Grep/Read are for an exact string or a file you already know. "
340
- "Use web_search/web_fetch for any web research. The user also installed "
341
- "a PreToolUse hook that blocks content searches over a project folder (grep -r, rg, git grep, Grep on a folder) "
342
- "and native WebFetch/WebSearch. A call blocked by Smart Tool is a routing rule, not a failure: make the call the block "
343
- "message names (smart_search with project_root and query_identifiers, web_fetch with url and prompt, web_search "
344
- "with query). Never retry the same search or download through Bash, python, node, PowerShell, curl or wget: that "
345
- "bypasses the rule the user set. Reading one known file, or searching inside one known file, is never blocked. "
342
+ "Use web_search/web_fetch for any web research. If a call is ever denied by Smart Tool, that is a routing rule the "
343
+ "user set, not a failure: make the call the message names, never the same search or download through Bash, python, "
344
+ "node, PowerShell, curl or wget. "
346
345
  "Before changing a function, project_manage action=graph with symbol lists its callers and tests; after editing, "
347
346
  "project_manage action=affected_tests lists the tests to run. When smart_search returns nothing, retry smart_search with "
348
347
  "other terms; do not switch to Grep, Read of folders or shell search. A helper agent (smart-scout, a cheap model) is "
@@ -423,6 +422,12 @@ TOOLS = [
423
422
  "test": {"type": "integer", "minimum": 1, "maximum": 20},
424
423
  "doc": {"type": "integer", "minimum": 1, "maximum": 20}}}],
425
424
  "description": "Results per block: one number for all blocks or {code, test, doc}; each 1-20, total at most 20. Defaults to the project's search_limits, else 5"},
425
+ "mode": {"type": "string", "enum": ["search", "dossier"], "default": "search",
426
+ "description": "dossier answers only with ids and a short excerpt, by keyword from disk and without an index, from docs/research, the backlog, CLAUDE.md and AGENTS.md; it takes query_identifiers or doc_query, timeout_ms and max_hits and ignores the other fields"},
427
+ "timeout_ms": {"type": "integer", "minimum": 1, "maximum": 5000, "default": 800,
428
+ "description": "mode=dossier only: scan budget; past it the answer is marked degraded"},
429
+ "max_hits": {"type": "integer", "minimum": 1, "maximum": 10, "default": 5,
430
+ "description": "mode=dossier only: hits returned"},
426
431
  },
427
432
  "required": ["project_root"],
428
433
  },
@@ -1443,6 +1448,7 @@ def _optional_text(arguments, name):
1443
1448
 
1444
1449
  _SMART_SEARCH_FIELDS = {"project_root", "query_identifiers", "query_comments", "doc_query",
1445
1450
  "single_language_reason", "group", "top_k"}
1451
+ _DOSSIER_FIELDS = {"project_root", "query_identifiers", "query_comments", "doc_query", "mode", "timeout_ms", "max_hits"}
1446
1452
 
1447
1453
 
1448
1454
  def _reject_kind(message):
@@ -1455,6 +1461,17 @@ def _reject_kind(message):
1455
1461
 
1456
1462
 
1457
1463
  def _handle_smart_search(arguments):
1464
+ mode = arguments.get("mode", "search") if isinstance(arguments, dict) else "search"
1465
+ if mode == "dossier":
1466
+ unknown = set(arguments) - _DOSSIER_FIELDS
1467
+ if unknown:
1468
+ raise ValueError(f"Unknown fields in smart_search mode=dossier: {', '.join(sorted(unknown))}. "
1469
+ f"Accepted: {', '.join(sorted(_DOSSIER_FIELDS))}.")
1470
+ _metric("search", group="dossier")
1471
+ return dossier.answer(arguments)
1472
+ if mode != "search":
1473
+ raise ValueError("mode must be search or dossier.")
1474
+ arguments = {key: value for key, value in arguments.items() if key != "mode"}
1458
1475
  try:
1459
1476
  arguments = _smart_search_arguments(arguments)
1460
1477
  except ValueError as exc:
@@ -3580,10 +3597,14 @@ HOOK_MAX_BODY_BYTES = 4 * 1024 * 1024
3580
3597
  # without one and says so in the log. Edit reviews (docs, copies) are the slow ones, so they have their own small
3581
3598
  # pool: at most HOOK_EDIT_SLOTS run at once and a further edit is let through unreviewed instead of queueing.
3582
3599
  HOOK_BUDGET_S = 4.0
3600
+ # A redirected shell search waits up to hook_decision.PRE_WAIT_S for its answer; any other Bash decision takes
3601
+ # milliseconds, so the larger budget only matters for those.
3602
+ HOOK_SHELL_BUDGET_S = 11.0
3583
3603
  HOOK_ANALYZER_TIMEOUT_S = 10
3584
3604
  HOOK_SLOW_LOG_S = 1.0
3585
3605
  HOOK_EDIT_SLOTS = 2
3586
- _HOOK_POOL = concurrent.futures.ThreadPoolExecutor(4, thread_name_prefix="hook")
3606
+ # A redirected shell search holds its worker while it waits for the answer (hook_decision.PRE_WAIT_S).
3607
+ _HOOK_POOL = concurrent.futures.ThreadPoolExecutor(8, thread_name_prefix="hook")
3587
3608
  _HOOK_EDIT_POOL = concurrent.futures.ThreadPoolExecutor(HOOK_EDIT_SLOTS, thread_name_prefix="hook-edit")
3588
3609
  _HOOK_EDIT_SLOTS = threading.BoundedSemaphore(HOOK_EDIT_SLOTS)
3589
3610
 
@@ -3593,20 +3614,22 @@ def _hook_work(payload, client, slot):
3593
3614
  (the worker may outlive the request that gave up on it)."""
3594
3615
  code_graph.ANALYZER_TIMEOUT_S.set(HOOK_ANALYZER_TIMEOUT_S)
3595
3616
  try:
3596
- return hook_decision.decide(payload, client, _web_route)
3617
+ return hook_decision.decide(payload, client, _web_route, _REDIRECTS)
3597
3618
  finally:
3598
3619
  if slot:
3599
3620
  slot.release()
3600
3621
 
3601
3622
 
3602
3623
  def _decide_within_budget(payload, client):
3603
- """The hook decision of `payload`, or None when it did not come within HOOK_BUDGET_S or no edit slot was free (the
3624
+ """The hook decision of `payload`, or None when it did not come within HOOK_BUDGET_S (HOOK_SHELL_BUDGET_S for a shell
3625
+ call) or no edit slot was free (the
3604
3626
  tool then runs as if the hook had nothing to say). Both cases, and any answer slower than HOOK_SLOW_LOG_S, leave one
3605
3627
  line in the daemon log with the tool, the file or command and the time."""
3606
3628
  tool = payload.get("tool_name") if isinstance(payload, dict) else None
3607
3629
  tool_input = payload.get("tool_input") if isinstance(payload, dict) else None
3608
3630
  target = str((tool_input or {}).get("file_path") or (tool_input or {}).get("command") or "")[:80]
3609
3631
  edit = tool in hook_decision.EDIT_TOOLS
3632
+ budget = HOOK_SHELL_BUDGET_S if tool in tool_redirect.NO_OP else HOOK_BUDGET_S
3610
3633
  if edit and not _HOOK_EDIT_SLOTS.acquire(blocking=False):
3611
3634
  _log(f"PreToolUse hook skipped the review of {tool} {target}: {HOOK_EDIT_SLOTS} edit reviews already running, "
3612
3635
  "the edit goes through without one")
@@ -3620,9 +3643,9 @@ def _decide_within_budget(payload, client):
3620
3643
  _HOOK_EDIT_SLOTS.release()
3621
3644
  raise
3622
3645
  try:
3623
- output = future.result(timeout=HOOK_BUDGET_S)
3646
+ output = future.result(timeout=budget)
3624
3647
  except concurrent.futures.TimeoutError:
3625
- _log(f"PreToolUse hook over {HOOK_BUDGET_S:g} s for {tool} {target}: answered without a decision, the work "
3648
+ _log(f"PreToolUse hook over {budget:g} s for {tool} {target}: answered without a decision, the work "
3626
3649
  "finishes in the background")
3627
3650
  return None
3628
3651
  took = time.monotonic() - started
@@ -3631,9 +3654,53 @@ def _decide_within_budget(payload, client):
3631
3654
  return output
3632
3655
 
3633
3656
 
3657
+ def _redirected_search(arguments):
3658
+ """smart_search text for a redirected native search, waiting up to SMART_SEARCH_SYNC_WAIT_S; raises when the search
3659
+ is rejected, fails or is still running then. The hook's single_language_reason only passes the language check, it is
3660
+ not repeated as a warning. The answer opens with `tool_redirect.search_notice`: the agent is told its search was
3661
+ redirected, whether the index is still loading, and to keep using smart_search."""
3662
+ checked = _smart_search_arguments(arguments)
3663
+ checked.pop("single_language_reason", None)
3664
+ job_id, _future = _submit_project_job("smart_search", checked)
3665
+ deadline = time.monotonic() + SMART_SEARCH_SYNC_WAIT_S
3666
+ payload = _smart_search_job_payload(job_id)
3667
+ while payload["status"] == "pending" and time.monotonic() < deadline:
3668
+ time.sleep(0.1)
3669
+ payload = _smart_search_job_payload(job_id)
3670
+ if payload["status"] != "done":
3671
+ raise RuntimeError(f"smart_search job {job_id} is {payload['status']}: {payload.get('error') or ''}"[:300])
3672
+ indexing = str(payload.get("warning") or "").startswith("Indexing in progress")
3673
+ return f"{tool_redirect.search_notice(indexing)}\n{_agent_search_answer(payload)}"
3674
+
3675
+
3676
+ def _redirected_text(handler):
3677
+ """A tool handler whose answer is always text (web_search may answer with a JSON object)."""
3678
+ def run(arguments):
3679
+ result = handler(arguments)
3680
+ return result if isinstance(result, str) else _to_json_sanitized(result)
3681
+ return run
3682
+
3683
+
3684
+ _REDIRECTS = tool_redirect.Jobs({"smart_search": _redirected_search, "web_fetch": _redirected_text(_handle_web_fetch),
3685
+ "web_search": _redirected_text(_handle_web_search)})
3686
+
3687
+
3688
+ def _posttool_hook(handler):
3689
+ """PostToolUse output for the Claude Code hook: the Smart Tool answer of a redirected call as the call's output, or
3690
+ `{}`. Always 200, like the PreToolUse route."""
3691
+ client = (urllib.parse.parse_qs(urllib.parse.urlsplit(handler.path).query).get("client") or [""])[0]
3692
+ try:
3693
+ payload = json.loads(handler._read_body(HOOK_MAX_BODY_BYTES) or b"{}")
3694
+ return hook_decision.after(payload, client or None, _REDIRECTS)
3695
+ except Exception as exc:
3696
+ _log(f"PostToolUse hook without an answer: {type(exc).__name__}: {exc}")
3697
+ return {}
3698
+
3699
+
3634
3700
  def _pretool_hook(handler):
3635
- """PreToolUse decision for the hook (Claude Code `type: "http"`, Codex via the thin command). Always 200 with `{}`
3636
- or `deny`: a non-2xx answer would show as a hook error on every tool call, and `allow` would skip the user's
3701
+ """PreToolUse decision for the hook (Claude Code `type: "http"`, Codex via the thin command). Always 200 with `{}`,
3702
+ `updatedInput`, `deny`, or `allow` only for the command the hook wrote to print a Smart Tool answer in Codex: a
3703
+ non-2xx answer would show as a hook error on every tool call, and any other `allow` would skip the user's
3637
3704
  permission prompt."""
3638
3705
  client = (urllib.parse.parse_qs(urllib.parse.urlsplit(handler.path).query).get("client") or [""])[0]
3639
3706
  try:
@@ -3649,7 +3716,10 @@ def _pretool_hook(handler):
3649
3716
  if output is None:
3650
3717
  return {}
3651
3718
  specific = output.get("hookSpecificOutput") or {}
3652
- if specific.get("permissionDecision", "deny") != "deny":
3719
+ decision = specific.get("permissionDecision", "deny")
3720
+ if decision == "allow" and tool_redirect.is_codex_command((specific.get("updatedInput") or {}).get("command")):
3721
+ return output
3722
+ if decision != "deny":
3653
3723
  return {}
3654
3724
  return output
3655
3725
 
@@ -3964,6 +4034,8 @@ class MCPHandler(BaseHTTPRequestHandler):
3964
4034
  self._write_json(200, result)
3965
4035
 
3966
4036
  def do_POST(self):
4037
+ """Routes a POST: setup actions, the hook routes (/hooks/pretool, /hooks/posttool, /hooks/session-audit) and
4038
+ the MCP endpoint (/mcp); anything else is 404."""
3967
4039
  if self._reject_foreign_origin():
3968
4040
  return
3969
4041
  if self.path == "/setup/projects":
@@ -3983,6 +4055,9 @@ class MCPHandler(BaseHTTPRequestHandler):
3983
4055
  if urllib.parse.urlsplit(self.path).path == "/hooks/pretool":
3984
4056
  self._write_json(200, _pretool_hook(self))
3985
4057
  return
4058
+ if urllib.parse.urlsplit(self.path).path == "/hooks/posttool":
4059
+ self._write_json(200, _posttool_hook(self))
4060
+ return
3986
4061
  if urllib.parse.urlsplit(self.path).path == "/hooks/session-audit":
3987
4062
  self._write_json(200, _session_audit_hook(self))
3988
4063
  return
@@ -0,0 +1,112 @@
1
+ """Transparent redirect of native searches and web calls to the Smart Tool.
2
+
3
+ The PreToolUse hook starts the Smart Tool call that replaces a native one (smart_search for a folder search, web_fetch
4
+ or web_search for WebFetch/WebSearch) under the call's `tool_use_id`, and the PostToolUse hook puts its text in the
5
+ native tool's output, in the shape that tool returns: the agent reads the Smart Tool answer as the result of the call it
6
+ made. Measured on Claude Code 2.1.300: `updatedInput` without `permissionDecision` is applied (the user's permission
7
+ rules still judge the rewritten call) and `updatedToolOutput` replaces the output of Grep, Bash, WebFetch and WebSearch
8
+ when it keeps the tool's shape; a PostToolUseFailure cannot replace anything, so a shell search whose answer is ready in
9
+ the PreToolUse is rewritten to a no-op that always succeeds (a grep with no match exits 1). Codex has no output
10
+ replacement: its shell call is rewritten to print a file holding the answer, which Codex only applies with `allow`.
11
+ """
12
+ import concurrent.futures
13
+ import os
14
+ import threading
15
+ import time
16
+ import uuid
17
+
18
+ import paths
19
+
20
+ RESULT_TTL_S = 600
21
+ RESULTS_DIR = os.path.join(paths.DATA_DIR, "redirects")
22
+ NO_OP = {"Bash": "true", "PowerShell": "$null"}
23
+ CODEX_PREFIX = "cat '"
24
+ _POOL = concurrent.futures.ThreadPoolExecutor(4, thread_name_prefix="redirect")
25
+
26
+
27
+ class Jobs:
28
+ """Smart Tool calls started for native tool calls, by `tool_use_id`; each is dropped once read or after
29
+ RESULT_TTL_S."""
30
+
31
+ def __init__(self, runners):
32
+ self._runners = runners
33
+ self._futures = {}
34
+ self._lock = threading.Lock()
35
+
36
+ def start(self, key, kind, arguments):
37
+ """Runs `runners[kind](arguments)` in the background under key (a second start of the same key is ignored)."""
38
+ now = time.monotonic()
39
+ with self._lock:
40
+ for old in [k for k, (at, _f) in self._futures.items() if now - at > RESULT_TTL_S]:
41
+ del self._futures[old]
42
+ if key not in self._futures:
43
+ self._futures[key] = (now, _POOL.submit(self._runners[kind], arguments))
44
+
45
+ def wait(self, key, timeout):
46
+ """The text of key's call when it finished within timeout seconds, else None (the call keeps running and a
47
+ later wait may still get it). Raises what the call raised."""
48
+ with self._lock:
49
+ entry = self._futures.get(key)
50
+ if entry is None:
51
+ return None
52
+ try:
53
+ return entry[1].result(timeout=timeout)
54
+ except concurrent.futures.TimeoutError:
55
+ return None
56
+
57
+ def forget(self, key):
58
+ """Drops key's call once its text was used or will never be read."""
59
+ with self._lock:
60
+ self._futures.pop(key, None)
61
+
62
+
63
+ def search_notice(indexing):
64
+ """First line of a redirected search's answer: the agent made a native search, Smart Tool answered it. While the
65
+ index loads the answer is a keyword search of the disk; either way the agent is told to keep using smart_search."""
66
+ state = ("The index of this project is still loading, so this answer is a keyword search of the files on disk; "
67
+ "the next searches will have the index ready. " if indexing else "")
68
+ return ("Smart Tool: your search was redirected to smart_search, which searches the project index and returns "
69
+ f"related code with its dependency map. {state}Keep using smart_search for searches of the project.")
70
+
71
+
72
+ def output_for(tool_name, response, text):
73
+ """`updatedToolOutput` for a native tool: its own response with the Smart Tool text in the field the model reads,
74
+ or None when the response has an unknown shape."""
75
+ if not isinstance(response, dict):
76
+ return None
77
+ if tool_name == "Grep":
78
+ return {**response, "mode": "content", "content": text, "numLines": len(text.splitlines()), "numFiles": 0,
79
+ "filenames": []}
80
+ if tool_name in NO_OP:
81
+ return {**response, "stdout": text, "stderr": "", "interrupted": False}
82
+ if tool_name == "WebFetch":
83
+ return {**response, "result": text}
84
+ if tool_name == "WebSearch":
85
+ return {**response, "results": [text]}
86
+ return None
87
+
88
+
89
+ def codex_command(text):
90
+ """Shell command that prints text from a file: `cat` with a quoted forward-slash path runs the same in bash and
91
+ PowerShell (an alias of Get-Content there), the shells Codex uses."""
92
+ os.makedirs(RESULTS_DIR, exist_ok=True)
93
+ now = time.time()
94
+ for name in os.listdir(RESULTS_DIR):
95
+ path = os.path.join(RESULTS_DIR, name)
96
+ try:
97
+ if now - os.path.getmtime(path) > RESULT_TTL_S:
98
+ os.remove(path)
99
+ except OSError:
100
+ pass
101
+ path = os.path.join(RESULTS_DIR, f"{uuid.uuid4().hex}.txt")
102
+ with open(path, "w", encoding="utf-8", newline="\n") as stream:
103
+ stream.write(text)
104
+ return f"{CODEX_PREFIX}{path.replace(os.sep, '/')}'"
105
+
106
+
107
+ def is_codex_command(command):
108
+ """Whether a shell command is one codex_command wrote: the only input the hook approves with `allow`."""
109
+ if not isinstance(command, str) or not command.startswith(CODEX_PREFIX) or not command.endswith("'"):
110
+ return False
111
+ path = os.path.normpath(command[len(CODEX_PREFIX):-1])
112
+ return os.path.dirname(os.path.normcase(path)) == os.path.normcase(os.path.normpath(RESULTS_DIR)) and "'" not in path
package/version.py CHANGED
@@ -1,7 +1,7 @@
1
1
  """Single source of the Smart Tool version and of the User-Agent sent to public APIs."""
2
2
  import re
3
3
 
4
- VERSION = "0.9.22"
4
+ VERSION = "0.9.24"
5
5
  _CONTACT_RE = re.compile(r"^(?:[^\s@()<>;]+@[^\s@()<>;]+\.[^\s@()<>;]+|https?://[^\s()<>;]+)$")
6
6
 
7
7