@allansantos-dev/smart-tool 0.9.1 → 0.9.3

package/edit_preview.py

@@ -0,0 +1,92 @@
+"""The files an agent edit would produce, computed before the edit runs: Claude Code Edit, MultiEdit and Write, and
+Codex apply_patch (*** Begin Patch / Update File / Add File). Returns (absolute path, text before or None, text after)
+for each file it can rebuild; an edit it cannot rebuild yields nothing, so a hook built on it never blocks wrongly."""
+import os
+
+
+def _read(path):
+    try:
+        with open(path, encoding="utf-8") as stream:
+            return stream.read()
+    except (OSError, UnicodeDecodeError):
+        return None
+
+
+def _replace(text, old, new, every):
+    if not old or old not in text:
+        return None
+    return text.replace(old, new) if every else text.replace(old, new, 1)
+
+
+def _claude(tool, data):
+    path = data.get("file_path")
+    if not isinstance(path, str) or not os.path.isabs(path):
+        return []
+    before = _read(path)
+    if tool == "Write":
+        content = data.get("content")
+        return [(path, before, content)] if isinstance(content, str) else []
+    if before is None:
+        return []
+    edits = data.get("edits") if tool == "MultiEdit" else [data]
+    after = before
+    for edit in edits or []:
+        after = _replace(after, edit.get("old_string"), edit.get("new_string", ""), edit.get("replace_all") is True)
+        if after is None:
+            return []
+    return [(path, before, after)]
+
+
+def _apply_hunks(text, hunks):
+    lines = text.splitlines()
+    for old, new in hunks:
+        if not old:
+            lines.extend(new)
+            continue
+        at = next((i for i in range(len(lines) - len(old) + 1) if lines[i:i + len(old)] == old), None)
+        if at is None:
+            return None
+        lines[at:at + len(old)] = new
+    return "\n".join(lines) + ("\n" if text.endswith("\n") or not text else "")
+
+
+def _codex(patch, cwd):
+    if not isinstance(patch, str) or "*** Begin Patch" not in patch:
+        return []
+    files, current = [], None
+    for raw in patch.splitlines():
+        if raw.startswith(("*** Update File: ", "*** Add File: ")):
+            current = {"action": raw.split(":", 1)[0][4:], "path": raw.split(":", 1)[1].strip(), "hunks": [[[], []]]}
+            files.append(current)
+        elif raw.startswith(("*** Delete File: ", "*** End Patch", "*** Move to: ")) or current is None:
+            current = None if raw.startswith(("*** Delete File: ", "*** End Patch")) else current
+        elif raw.startswith("@@"):
+            current["hunks"].append([[], []])
+        elif raw.startswith("+"):
+            current["hunks"][-1][1].append(raw[1:])
+        elif raw.startswith("-"):
+            current["hunks"][-1][0].append(raw[1:])
+        elif raw.startswith(" ") or raw == "":
+            current["hunks"][-1][0].append(raw[1:])
+            current["hunks"][-1][1].append(raw[1:])
+    results = []
+    for entry in files:
+        path = entry["path"] if os.path.isabs(entry["path"]) else os.path.join(cwd or os.getcwd(), entry["path"])
+        hunks = [hunk for hunk in entry["hunks"] if hunk[0] or hunk[1]]
+        if entry["action"] == "Add File":
+            results.append((path, None, "\n".join(line for hunk in hunks for line in hunk[1]) + "\n"))
+            continue
+        before = _read(path)
+        after = _apply_hunks(before, hunks) if before is not None else None
+        if after is not None:
+            results.append((path, before, after))
+    return results
+
+
+def preview(tool_name, tool_input, cwd=None):
+    data = tool_input if isinstance(tool_input, dict) else {}
+    if tool_name in ("Edit", "MultiEdit", "Write") and "file_path" in data:
+        return _claude(tool_name, data)
+    if tool_name in ("apply_patch", "Edit", "Write") and "command" in data:
+        return _codex(data.get("command"), cwd)
+    return []

package/hook_decision.py

@@ -10,11 +10,20 @@ no Claude Code, e nenhuma decisão aqui é sobre periculosidade, só sobre custo
 import json
 import os
 
+import code_graph
+import code_impact
 import config
+import doc_check
+import duplicates
+import edit_preview
 import endpoint_sync
+import project_store
 import router
 
 WEB_TOOLS = ("WebSearch", "WebFetch")
+EDIT_TOOLS = ("Edit", "MultiEdit", "Write", "apply_patch")
+MAX_DOC_FINDINGS = 5
+MAX_DUPLICATE_FINDINGS = 3
 SMART_TOOL_SERVER = "smart-tool"
 REASON_MAX_CHARS = 200
 
@@ -55,9 +64,94 @@ def advise(reason):
                                    "additionalContext": f"Smart Tool tip (the call was not blocked): {reason}"}}
 
 
+def _project_of(path):
+    target = os.path.normcase(os.path.abspath(path))
+    roots = [p["root"] for p in project_store.all_projects()
+             if target.startswith(os.path.normcase(os.path.abspath(p["root"])) + os.sep)]
+    return max(roots, key=len) if roots else None
+
+
+def _impact_line(root, rel, name):
+    """Callers and tests from the code graph, only when its analysis is already cached: the hook never waits for one."""
+    if not root or code_graph.cached_symbols(root)[0] is None:
+        return ""
+    try:
+        found = code_impact.impact(root, f"{rel}::{name}", limit=3)
+    except ValueError:
+        return ""
+    counts = found["counts"]
+    tests = ", ".join(f"{t['function']} ({t['path']})" for t in found["tests"])
+    calls = f"; tests calling it: {tests}" if tests else ""
+    return f" {counts['callers']} caller(s){calls}; project_manage affected_tests lists every test to run after the edit."
+
+
+def _doc_lines(findings):
+    lines = []
+    for root, rel, item in findings[:MAX_DOC_FINDINGS]:
+        if item["issue"] == "missing":
+            text = f"{item['name']} ({rel}:{item['start']}) has no docstring: write one (purpose, parameters, return)."
+        else:
+            text = (f"{item['name']} ({rel}:{item['start']}) changed its signature: update its docstring if the "
+                    f"contract changed.")
+        lines.append(text + _impact_line(root, rel, item["name"]))
+    if len(findings) > MAX_DOC_FINDINGS:
+        lines.append(f"{len(findings) - MAX_DOC_FINDINGS} more function(s) in the same situation.")
+    return "Smart Tool docs: " + " ".join(lines)
+
+
+def _duplicate_lines(findings):
+    lines = []
+    for rel, item in findings[:MAX_DUPLICATE_FINDINGS]:
+        existing = item["existing"]
+        where = f"{existing['name']} in {existing['path']}:{existing['lines']}"
+        if item["type"] == "exact":
+            lines.append(f"{item['name']} ({rel}:{item['lines']}) has the same body as {where}: reuse it instead of a copy.")
+        else:
+            lines.append(f"{item['name']} ({rel}:{item['lines']}) is near-identical to {where} (score {item['score']}, "
+                         f"local names ignored): check whether it can be reused.")
+    if len(findings) > MAX_DUPLICATE_FINDINGS:
+        lines.append(f"{len(findings) - MAX_DUPLICATE_FINDINGS} more copied function(s).")
+    return ("Smart Tool duplicates: " + " ".join(lines)
+            + " If the copy is intentional (moving the function, a deliberate fork), go ahead.")
+
+
+def _edit_review(payload, doc_mode, duplicate_mode):
+    """Checks of an edit before it runs. Docstrings follow doc_mode: missing ones deny the edit in require mode and
+    become a reminder in remind mode; a documented function whose signature changed always gets a reminder. Copies of
+    indexed functions follow duplicate_mode and only add context, never deny."""
+    doc_findings, duplicate_findings, failures = [], [], []
+    for path, before, after in edit_preview.preview(payload.get("tool_name"), payload.get("tool_input"), payload.get("cwd")):
+        if not doc_check.supported(path):
+            continue
+        root = _project_of(path)
+        rel = os.path.relpath(path, root).replace(os.sep, "/") if root else os.path.basename(path)
+        edited = doc_check.written(path, before, after)
+        if doc_mode != "off":
+            doc_findings += [(root, rel, item) for item in doc_check.review(path, before, after, edited)]
+        if duplicate_mode != "off" and root and edited["touched"]:
+            try:
+                duplicate_findings += [(rel, item) for item in duplicates.on_write(root, path, before, after, edited)]
+            except (ValueError, RuntimeError) as exc:
+                failures.append(f"Smart Tool duplicates check skipped: {exc}")
+    parts = ([_doc_lines(doc_findings)] if doc_findings else []) + \
+        ([_duplicate_lines(duplicate_findings)] if duplicate_findings else []) + failures
+    if not parts:
+        return {}
+    message = " ".join(parts)
+    if doc_mode == "require" and any(item["issue"] == "missing" for _root, _rel, item in doc_findings):
+        return deny(message + " Redo the edit with the docstring.")
+    return {"hookSpecificOutput": {"hookEventName": "PreToolUse", "additionalContext": message}}
+
+
 def decide(payload, client, web_route):
-    """Hook output for one PreToolUse payload, following config hook_mode (redirect | advise | off)."""
+    """Hook output for one PreToolUse payload: edits follow doc_mode (require | remind | off) and duplicate_mode
+    (warn | off), the other tools follow hook_mode (redirect | advise | off)."""
     cfg = config.load_config()
+    if isinstance(payload, dict) and payload.get("tool_name") in EDIT_TOOLS:
+        doc_mode, duplicate_mode = config.doc_mode(cfg), config.duplicate_mode(cfg)
+        if doc_mode == "off" and duplicate_mode == "off":
+            return {}
+        return _edit_review(payload, doc_mode, duplicate_mode)
     mode = config.hook_mode(cfg)
     if mode == "off" or not isinstance(payload, dict):
         return {}
@@ -82,7 +176,7 @@ def _route(payload, client, web_route, cfg):
             return {}
         decision = web_route(tool_name, str(tool_input.get("url") or ""))
         return deny(clean_reason(decision.get("reason"))) if decision.get("redirect") else {}
-    router.CLIENT = client
+    router.CLIENT.set(client)
     try:
         decision, reason = router.decide(tool_name, tool_input, router_model, cwd=cwd)
     except Exception as exc:

package/index_profile.py

@@ -17,7 +17,7 @@ DOC_DATA = {"html", "htm", "json", "csv", "xml", "yaml", "yml", "svg"}
 _NAME_DOC = re.compile(r"(^|/)(readme|changelog|license|licence|contributing|install|history|authors)(\.[^/]*)?$", re.I)
 _DIR_DOC = re.compile(r"(^|/)(docs?|adrs?|documentation)/", re.I)
 _TEST = re.compile(r"(^|/)(tests?|__tests__|spec|specs|e2e|fixtures?|testdata|test-utils?)(/|$)|(^|/)test_[^/]+\.py$|"
-                   r"(^|/)conftest\.py$|_test\.(py|go)$|\.(test|spec)\.[cm]?[jt]sx?$|(^|/)[^/]*[a-z0-9](?-i:Tests?)\.java$|"
+                   r"(^|/)conftest\.py$|_test\.(py|go)$|\.(test|spec)(-d)?\.[cm]?[jt]sx?$|(^|/)[^/]*[a-z0-9](?-i:Tests?)\.java$|"
                    r"(^|/)src/test/|(^|/)test[-_][^/]*\.[cm]?[jt]sx?$|[-_]test\.[cm]?[jt]sx?$", re.I)
 _TEST_PROSE = re.compile(r"(^|/)(tests?|__tests__|e2e|fixtures?|testdata|test-utils?)(/|$)|(^|/)src/test/", re.I)
 _TEXT_LINE = re.compile(r"[A-Za-zÀ-ú]{3,}\s+[A-Za-zÀ-ú]{3,}")

package/install_runtime.py

@@ -133,7 +133,7 @@ def _run(args, *, cwd=None, label="Web dependency", idle_s=600, stream=False, at
         except RuntimeError as exc:
             if attempt == attempts:
                 raise
-            print(f"{label}: {exc}; trying again.", flush=True)
+            print(f"{exc}; trying again.", flush=True)
 
 
 def _run_once(args, cwd, env, flags, label, idle_s, stream):
@@ -179,8 +179,10 @@ def _run_once(args, cwd, env, flags, label, idle_s, stream):
             time.sleep(0.5)
         reader.join(timeout=10)
         if process.returncode:
-            raise RuntimeError(f"{' '.join(map(str, args[:3]))} failed (exit {process.returncode}): "
-                               + "\n".join(tail)[-1500:])
+            if not stream:
+                for line in list(tail)[-15:]:
+                    print(f"{label}: {line}", flush=True)
+            raise RuntimeError(f"{label} failed (exit {process.returncode}): {tail[-1] if tail else 'no output'}")
 
 
 def _check():
@@ -193,6 +195,8 @@ def _check():
         "angular_parser":bool(node and ANGULAR_PARSER.is_file()),
         "browser_python": BROWSER_PYTHON.is_file(),
         "browser_packages": False,
+        "camoufox_browser": False,
+        "chromium_browser": False,
     }
     if status["browser_python"]:
         try:
@@ -203,9 +207,36 @@ def _check():
             status["browser_packages"] = result.returncode == 0
         except subprocess.TimeoutExpired:
             status["browser_packages"] = False
+    if status["browser_packages"]:
+        status.update(_browser_executables())
     return status
 
 
+_BROWSERS_PROBE = """
+import json, os
+from camoufox.pkgman import LAUNCH_FILE, OS_NAME, camoufox_path
+from playwright.sync_api import sync_playwright
+found = {}
+try:
+    found["camoufox_browser"] = os.path.isfile(os.path.join(camoufox_path(download_if_missing=False), LAUNCH_FILE[OS_NAME]))
+except Exception:
+    found["camoufox_browser"] = False
+with sync_playwright() as playwright:
+    found["chromium_browser"] = os.path.isfile(playwright.chromium.executable_path)
+print(json.dumps(found))
+"""
+
+
+def _browser_executables():
+    """Both browsers must exist on disk: a download tool reporting success is not enough."""
+    try:
+        result = subprocess.run([str(BROWSER_PYTHON), "-c", _BROWSERS_PROBE], capture_output=True, text=True,
+                                encoding="utf-8", errors="replace", check=False, timeout=60)
+        return json.loads(result.stdout.strip().splitlines()[-1])
+    except (subprocess.TimeoutExpired, ValueError, IndexError):
+        return {"camoufox_browser": False, "chromium_browser": False}
+
+
 def _link_existing_browser(existing, link):
     try:
         os.symlink(existing, link, target_is_directory=True)
@@ -268,9 +299,10 @@ def main():
                         help="Reuse an existing venv without duplicating files (useful when disk is low)")
     args = parser.parse_args()
     if args.check:
-        for name, ready in _check().items():
+        status = _check()
+        for name, ready in status.items():
             print(f"{name}: {'ok' if ready else 'missing'}")
-        return 0 if all(_check().values()) else 1
+        return 0 if all(status.values()) else 1
     try:
         install(args.reuse_browser_runtime)
     except (OSError, RuntimeError, subprocess.SubprocessError) as exc:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allansantos-dev/smart-tool",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Local MCP server that gives coding agents (Claude Code, Codex) cheaper, sharper tools than their built-in search. Windows.",
   "license": "Apache-2.0",
   "author": "Allan Santos",

package/router.py

@@ -5,6 +5,7 @@ modelo pequeno se deve deixar passar ou redirecionar pra `smart_search`. Cada de
 logada em `router-metrics.jsonl` pra orientar um classificador mais fino depois, com
 base em uso real — não numa suposição a priori.
 """
+import contextvars
 import json
 import os
 import paths
@@ -17,7 +18,8 @@ import index_scope
 import indexer
 import web_search_adapters
 
-CLIENT = None
+# Per request: the daemon serves each hook call on its own thread, so a module global mixed up clients.
+CLIENT = contextvars.ContextVar("router_client", default=None)
 METRICS_PATH = os.path.join(paths.DATA_DIR, "router-metrics.jsonl")
 
 _SYSTEM_PROMPT = (
@@ -266,7 +268,7 @@ def _log_decision(tool_name, tool_input, decision, reason, extra=None):
         "tool_input": _redacted_input(tool_input),
         "decision": decision,
         "reason": reason,
-        **({"client": CLIENT} if CLIENT else {}),
+        **({"client": CLIENT.get()} if CLIENT.get() else {}),
     }
     record.update(extra or {})
     try:

package/setup_ui.py

@@ -177,18 +177,31 @@ def handle_integration_get():
         mode, mode_error = config.hook_mode(), ""
     except ValueError as exc:
         mode, mode_error = "", str(exc)
+    try:
+        doc_mode, doc_error = config.doc_mode(), ""
+    except ValueError as exc:
+        doc_mode, doc_error = "", str(exc)
+    try:
+        duplicate_mode, duplicate_error = config.duplicate_mode(), ""
+    except ValueError as exc:
+        duplicate_mode, duplicate_error = "", str(exc)
     return {"daemon_url": setup_origin(), "clients": clients, "hook_mode": mode, "hook_mode_error": mode_error,
-            "hook_modes": list(config.HOOK_MODES)}
+            "hook_modes": list(config.HOOK_MODES), "doc_mode": doc_mode, "doc_mode_error": doc_error,
+            "doc_modes": list(config.DOC_MODES), "duplicate_mode": duplicate_mode,
+            "duplicate_mode_error": duplicate_error, "duplicate_modes": list(config.DUPLICATE_MODES)}
 
 
 def handle_integration_save(body):
     """`hook_mode` sets redirect/advise/off for every client; `register_mcp` runs the client's CLI; hook in two steps:
     `preview` shows the exact change, `install` writes it (with backup)."""
-    if isinstance(body, dict) and body.get("action") == "hook_mode":
-        if body.get("mode") not in config.HOOK_MODES:
-            raise SetupError("Invalid mode: use redirect, advise or off.")
+    if isinstance(body, dict) and body.get("action") in ("hook_mode", "doc_mode", "duplicate_mode"):
+        action = body["action"]
+        allowed = {"hook_mode": config.HOOK_MODES, "doc_mode": config.DOC_MODES,
+                   "duplicate_mode": config.DUPLICATE_MODES}[action]
+        if body.get("mode") not in allowed:
+            raise SetupError(f"Invalid mode: use {', '.join(allowed)}.")
         try:
-            config.update_config(lambda cfg: cfg.update(hook_mode=body["mode"]))
+            config.update_config(lambda cfg: cfg.update({action: body["mode"]}))
         except (OSError, config.ConfigCorruptedError) as exc:
             raise SetupError(str(exc))
         return handle_integration_get()
@@ -397,9 +410,18 @@ _PAGE_TEMPLATE = """<!doctype html>
   .pair { display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); gap: 12px; }
   label { display: block; font-size: .8rem; font-weight: 600; margin-bottom: 4px; }
   .hint { display: block; font-size: .76rem; color: var(--muted); margin-top: 3px; }
-  select, input[type=text], input[type=url], input[type=number], input[type=password] {
+  select, input:not([type]), input[type=text], input[type=url], input[type=number], input[type=password] {
     width: 100%; padding: 8px 10px; border-radius: 8px; border: 1px solid var(--line);
-    background: var(--bg); color: var(--ink); font: .84rem var(--mono); min-width: 0; max-width: 100%; }
+    background-color: var(--bg); color: var(--ink); font: .84rem var(--mono); min-width: 0; max-width: 100%; }
+  select, input[list] { appearance: none; padding-right: 34px; cursor: pointer;
+    background-image: linear-gradient(45deg, transparent 50%, var(--muted) 50%), linear-gradient(135deg, var(--muted) 50%, transparent 50%);
+    background-position: calc(100% - 17px) 52%, calc(100% - 12px) 52%; background-size: 5px 5px; background-repeat: no-repeat; }
+  input[list] { cursor: text; }
+  input[list]::-webkit-calendar-picker-indicator { opacity: 0; cursor: pointer; }
+  select:hover, input[list]:hover { border-color: var(--muted); }
+  .code-preview { display: block; margin: 10px 0 0; padding: 12px 14px; max-height: 320px; overflow: auto; white-space: pre;
+    font: .78rem/1.5 var(--mono); color: var(--ink); background: var(--bg); border: 1px solid var(--line); border-radius: 8px; }
+  .plan { margin-top: 12px; padding-top: 12px; border-top: 1px dashed var(--line); }
   input[type=password] { font-family: var(--body); }
   input::placeholder { color: var(--idle); }
   select:focus-visible, input:focus-visible, button:focus-visible { outline: 2px solid var(--signal); outline-offset: 2px; }
@@ -556,10 +578,23 @@ _PAGE_TEMPLATE = """<!doctype html>
           </select>
           <span class="hint" id="hook-mode-hint">Applies to every client on the next tool call; nothing is reinstalled.</span></div>
         <div class="actions"><button type="button" id="btn-save-hook-mode">Save behavior</button></div>
-        <div id="agents-list"></div>
-        <pre class="hint" id="agents-preview" hidden></pre>
-        <div class="actions"><button type="button" id="btn-agents-confirm" hidden>Confirm and write</button></div>
+        <div class="field" style="margin-top:16px"><label for="sel-doc-mode">Documentation on edit</label>
+          <select id="sel-doc-mode">
+            <option value="remind">Remind: the edit runs; the agent is told which touched functions lack a docstring (default)</option>
+            <option value="require">Require: an edit that leaves a touched function without a docstring is blocked until it adds one</option>
+            <option value="off">Off: no documentation checks</option>
+          </select>
+          <span class="hint">Only public functions the edit touches (private, nested and override functions are exempt, as in pydocstyle, eslint-plugin-jsdoc and Checkstyle). A documented function is mentioned again only when its signature changes; body-only edits stay silent.</span></div>
+        <div class="actions"><button type="button" id="btn-save-doc-mode">Save documentation</button></div>
+        <div class="field" style="margin-top:16px"><label for="sel-duplicate-mode">Duplicate functions on edit</label>
+          <select id="sel-duplicate-mode">
+            <option value="warn">Warn: the edit runs; the agent is told when a written function copies one already in the project (default)</option>
+            <option value="off">Off: no duplicate checks on edit</option>
+          </select>
+          <span class="hint">Compares functions the edit writes with the indexed code: identical bodies, and near-identical ones with only local names changed. Never blocks.</span></div>
+        <div class="actions"><button type="button" id="btn-save-duplicate-mode">Save duplicates</button></div>
         <div class="msg" id="agents-msg" role="status"></div>
+        <div id="agents-list"></div>
       </section>
 
       <section id="providers-section">
@@ -570,7 +605,10 @@ _PAGE_TEMPLATE = """<!doctype html>
           <span class="hint" id="contact-hint">Wikimedia asks tools to identify a contact in the User-Agent. It stays on this machine and is sent only to the search APIs.</span></div>
         <div class="actions"><button type="button" id="btn-save-contact">Save contact</button></div>
         <div class="msg" id="contact-msg" role="status"></div>
-        <div id="providers-list"></div>
+        <div class="field" style="margin-top:18px"><label for="provider-select">Provider</label>
+          <select id="provider-select"></select>
+          <span class="hint">Pick a provider to see its free tier and set or remove your key for it.</span></div>
+        <div id="provider-panel"></div>
       </section>
     </div>
   </div>
@@ -643,8 +681,10 @@ function renderGatewayFields() {
   for (const field of (adapter || { fields: [] }).fields) {
     const wrap = document.createElement("div");
     wrap.className = "field";
-    wrap.innerHTML = `<label></label><input autocomplete="off" spellcheck="false"><span class="hint"></span>`;
+    wrap.innerHTML = `<label></label><input type="text" autocomplete="off" spellcheck="false"><span class="hint"></span>`;
     const input = wrap.querySelector("input");
+    input.id = "gateway-field-" + field.name;
+    wrap.querySelector("label").htmlFor = input.id;
     wrap.querySelector("label").textContent = field.label + (field.required ? "" : " (optional)");
     input.dataset.field = field.name;
     input.dataset.secret = field.secret ? "1" : "";
@@ -831,14 +871,17 @@ $("btn-save-local-models").addEventListener("click", async () => {
   }
 });
 
-let agentsPlan = null;
 async function loadAgents() {
   try {
     const resp = await fetch("/setup/integration");
     const data = await resp.json();
     if (!resp.ok || data.error) throw new Error(data.error);
     if (document.activeElement !== $("sel-hook-mode")) $("sel-hook-mode").value = data.hook_mode;
+    if (document.activeElement !== $("sel-doc-mode")) $("sel-doc-mode").value = data.doc_mode;
+    if (document.activeElement !== $("sel-duplicate-mode")) $("sel-duplicate-mode").value = data.duplicate_mode;
     if (data.hook_mode_error) setMsg("agents-msg", "error", data.hook_mode_error);
+    if (data.doc_mode_error) setMsg("agents-msg", "error", data.doc_mode_error);
+    if (data.duplicate_mode_error) setMsg("agents-msg", "error", data.duplicate_mode_error);
     const list = $("agents-list");
     list.textContent = "";
     for (const item of data.clients) {
@@ -847,7 +890,9 @@ async function loadAgents() {
       const mcp = item.mcp_url ? "MCP registered: " + item.mcp_url : "smart-tool MCP not registered in this client";
       const hook = item.hook_error ? "Hook unreadable: " + item.hook_error : item.hook ? "Hook installed and up to date" : "Hook missing or outdated";
       row.innerHTML = `<div class="provider-head"><strong></strong><span class="state"></span></div><p class="hint mcp"></p><p class="hint mono cmd"></p><p class="hint file"></p>
-        <div class="actions"><button type="button" class="register">Register MCP</button><button type="button" class="hook">Install or update hook</button></div>`;
+        <div class="actions"><button type="button" class="register">Register MCP</button><button type="button" class="hook">Install or update hook</button></div>
+        <div class="plan" hidden><span class="hint plan-file"></span><pre class="code-preview"></pre>
+          <div class="actions"><button type="button" class="confirm">Confirm and write</button><button type="button" class="quiet cancel">Cancel</button></div></div>`;
       row.querySelector("strong").textContent = item.label;
       row.querySelector(".state").textContent = hook;
       row.querySelector(".mcp").textContent = mcp;
@@ -862,34 +907,37 @@ async function loadAgents() {
           const result = await post("/setup/integration", { client: item.client, action: "register_mcp" });
           setMsg("agents-msg", "ok", "MCP registered with: " + result.command + ". Reconnect open sessions (/mcp).");
           await loadAgents();
-$("btn-save-hook-mode").addEventListener("click", async () => {
-  try {
-    await post("/setup/integration", { action: "hook_mode", mode: $("sel-hook-mode").value });
-    setMsg("agents-msg", "ok", "Hook behavior saved; it applies on the next tool call.");
-    await loadAgents();
-  } catch (error) {
-    setMsg("agents-msg", "error", error.message);
-  }
-});
         } catch (error) {
           setMsg("agents-msg", "error", error.message);
           register.disabled = false;
         }
       });
       const button = row.querySelector(".hook");
+      const plan = row.querySelector(".plan");
       button.hidden = Boolean(item.hook);
       button.addEventListener("click", async () => {
         setMsg("agents-msg", "", "Preparing the change…");
         try {
-          agentsPlan = { client: item.client, ...(await post("/setup/integration", { client: item.client, action: "preview" })) };
-          $("agents-preview").textContent = item.file + "\\n" + JSON.stringify(agentsPlan.change, null, 2);
-          $("agents-preview").hidden = false;
-          $("btn-agents-confirm").hidden = false;
-          setMsg("agents-msg", "", "Review the entry above; the file is backed up before writing.");
+          const preview = await post("/setup/integration", { client: item.client, action: "preview" });
+          row.querySelector(".plan-file").textContent = "Entry added to " + preview.file + " (the file is backed up first):";
+          row.querySelector(".code-preview").textContent = JSON.stringify(preview.change, null, 2);
+          plan.hidden = false;
+          button.hidden = true;
+          setMsg("agents-msg", "", "");
+          row.querySelector(".confirm").onclick = async () => {
+            try {
+              const result = await post("/setup/integration", { client: item.client, action: "install", token: preview.token });
+              setMsg("agents-msg", "ok", item.label + ": hook written. Backup: " + (result.backup || "new file") + (result.after_install ? ". " + result.after_install : ""));
+              await loadAgents();
+            } catch (error) {
+              setMsg("agents-msg", "error", error.message);
+            }
+          };
         } catch (error) {
           setMsg("agents-msg", "error", error.message);
         }
       });
+      row.querySelector(".cancel").addEventListener("click", () => { plan.hidden = true; button.hidden = false; });
       list.appendChild(row);
     }
   } catch (error) {
@@ -897,14 +945,26 @@ $("btn-save-hook-mode").addEventListener("click", async () => {
   }
 }
 loadAgents();
-$("btn-agents-confirm").addEventListener("click", async () => {
-  if (!agentsPlan) return;
+$("btn-save-doc-mode").addEventListener("click", async () => {
+  try {
+    await post("/setup/integration", { action: "doc_mode", mode: $("sel-doc-mode").value });
+    setMsg("agents-msg", "ok", "Documentation setting saved; it applies on the next edit.");
+  } catch (error) {
+    setMsg("agents-msg", "error", error.message);
+  }
+});
+$("btn-save-duplicate-mode").addEventListener("click", async () => {
+  try {
+    await post("/setup/integration", { action: "duplicate_mode", mode: $("sel-duplicate-mode").value });
+    setMsg("agents-msg", "ok", "Duplicate setting saved; it applies on the next edit.");
+  } catch (error) {
+    setMsg("agents-msg", "error", error.message);
+  }
+});
+$("btn-save-hook-mode").addEventListener("click", async () => {
   try {
-    const result = await post("/setup/integration", { client: agentsPlan.client, action: "install", token: agentsPlan.token });
-    setMsg("agents-msg", "ok", "Hook written. Backup: " + (result.backup || "new file") + (result.after_install ? ". " + result.after_install : ""));
-    agentsPlan = null;
-    $("agents-preview").hidden = true;
-    $("btn-agents-confirm").hidden = true;
+    await post("/setup/integration", { action: "hook_mode", mode: $("sel-hook-mode").value });
+    setMsg("agents-msg", "ok", "Hook behavior saved; it applies on the next tool call.");
     await loadAgents();
   } catch (error) {
     setMsg("agents-msg", "error", error.message);
@@ -946,8 +1006,7 @@ function providerCard(name, info) {
       try {
         const data = await post("/setup/providers", { provider: name, action, ...(action === "save" ? { api_key: input.value.trim() } : {}) });
         input.value = "";
-        await loadProviders();
-        setMsg(name + "-msg", "ok", action === "save" ? `Key accepted by the provider (${data.validated_results} result(s) in the test) and protected on this Windows machine.` : "Key removed; free tier active.");
+        await loadProviders(action === "save" ? `Key accepted by the provider (${data.validated_results} result(s) in the test) and protected on this Windows machine.` : "Key removed; free tier active.");
       } catch (error) {
         setMsg(msg.id, "error", error.message);
         button.disabled = false;
@@ -966,13 +1025,27 @@ $("btn-save-contact").addEventListener("click", async () => {
   }
 });
 
-async function loadProviders() {
-  const list = $("providers-list");
+let providers = {};
+function showProvider(message) {
+  const name = $("provider-select").value;
+  $("provider-panel").replaceChildren(...(providers[name] ? [providerCard(name, providers[name])] : []));
+  if (message) setMsg(name + "-msg", "ok", message);
+}
+$("provider-select").addEventListener("change", () => showProvider());
+
+async function loadProviders(message) {
+  const list = $("provider-panel");
   try {
     const resp = await fetch("/setup/providers");
     const data = await resp.json();
     if (!resp.ok || data.error) throw new Error(data.error);
-    list.replaceChildren(...Object.entries(data.providers).map(([name, info]) => providerCard(name, info)));
+    providers = data.providers;
+    const select = $("provider-select");
+    const chosen = select.value;
+    select.replaceChildren(...Object.entries(providers).map(([name, info]) =>
+      new Option(info.label + " · " + ((providerLabels[info.status] || [null, info.status])[1]), name)));
+    if (chosen && providers[chosen]) select.value = chosen;
+    showProvider(message);
     if (document.activeElement !== $("contact-input")) $("contact-input").value = data.contact;
     $("contact-hint").textContent = "Sent as: " + data.user_agent;
   } catch (error) {