honestcode 0.5.0__py3-none-any.whl

honestcode/mcp/tools.py

@@ -0,0 +1,2002 @@
+"""
+Tool implementations for the HonestCode MCP server.
+
+Each function is decorated with @mcp.tool() in server.py. They provide the
+hallucination-detection capabilities exposed to MCP clients:
+  - index_project        : build the project symbol index
+  - load_project_deps    : load dependency APIs from requirements/pyproject
+  - check_symbol         : verify a symbol is defined
+  - check_api            : verify a library API call is correct
+  - execute_code         : run code in a sandbox
+  - scan_file            : scan a file for potential hallucinations
+  - load_package_apis    : load a package's API signatures
+  - get_project_stats    : index statistics
+  - validate_types       : AST-based type checking
+  - find_dead_code       : find potentially unused symbols
+  - find_similar_code    : find similar/duplicate functions
+  - explore_call_graph   : explore callers/callees of a symbol
+  - search_code          : search source code with regex
+"""
+
+from __future__ import annotations
+
+import ast
+import importlib.metadata
+import importlib.util
+import logging
+import os
+import re
+import sqlite3
+import subprocess
+import sys
+import sysconfig
+import threading
+import time
+from contextlib import suppress
+from pathlib import Path
+
+from honestcode.graph.graph_store import CallGraph, GraphCache
+from honestcode.graph.watcher import ProjectWatcher
+from honestcode.honest.router import HonestRouter
+from honestcode.honest.symbol_index import ProjectIndex, get_project_index
+from honestcode.mcp.knowledge_base import APIKnowledgeBase
+from honestcode.sandbox import SandboxExecutor
+from honestcode.structure.extractor import StructureExtractor
+from honestcode.structure.relations import ParseResult
+from honestcode.structure.utils import (
+    call_name,
+    iter_python_files,
+    module_name_for,
+    read_python_source,
+    stdlib_roots,
+)
+from honestcode.verify.evidence import (
+    ACTION_INSPECT,
+    CONFIDENCE_LOW,
+    KIND_SYNTAX_ERROR,
+    KIND_UNDEFINED_SYMBOL,
+    Finding,
+    build_report,
+    render_text,
+)
+from honestcode.verify.verify import (
+    resolve_package_relative_imports,
+    star_imports_unresolved,
+    valid_imported_names,
+    verify_tree,
+)
+
+__all__ = [
+    "index_project",
+    "load_project_deps",
+    "check_symbol",
+    "check_api",
+    "execute_code",
+    "scan_file",
+    "load_package_apis",
+    "get_project_stats",
+    "validate_types",
+    "find_dead_code",
+    "find_similar_code",
+    "explore_call_graph",
+    "search_code",
+    "choose_tool",
+    "verify_file",
+    "reset_dependency_state",
+]
+
+logger = logging.getLogger(__name__)
+
+_AUTO_INDEX_ENABLED = os.environ.get("HONESTCODE_AUTO_INDEX", "1").lower() not in {
+    "0",
+    "false",
+    "no",
+    "off",
+}
+# Auto-declaring the project's dependencies (without importing them) is what
+# keeps a normal project from reporting every `from dep import X` as undefined
+# when the MCP server runs in a different interpreter than the project's venv.
+_AUTO_DEPS_ENABLED = os.environ.get("HONESTCODE_AUTO_DEPS", "1").lower() not in {
+    "0",
+    "false",
+    "no",
+    "off",
+}
+_PROJECT_MARKERS = (".honestcode", ".git", "pyproject.toml", "setup.py", "requirements.txt")
+
+# How many package levels above the verified file may be adopted as the import
+# root when no project marker exists.
+_MAX_PACKAGE_WALK = 4
+
+
+def _find_project_root(start: Path) -> Path | None:
+    """Walk upward from *start* looking for a project marker."""
+    cur = start.resolve()
+    for candidate in [cur, *cur.parents]:
+        if (candidate / ".honestcode" / "config.json").exists():
+            return candidate
+        if (candidate / ".git").exists():
+            return candidate
+    for candidate in [cur, *cur.parents]:
+        if any((candidate / m).exists() for m in _PROJECT_MARKERS):
+            return candidate
+    return None
+
+
+def _package_root(start: Path) -> Path | None:
+    """Return the import root for a directory, walking out of packages.
+
+    Python treats the first ancestor without an ``__init__.py`` as the import
+    root. Walking out to it keeps sibling packages inside the indexed scope —
+    indexing only the verified file's own directory hid them and reported
+    correct cross-package imports as undefined symbols.
+
+    The walk is bounded: a project root that is itself a package would otherwise
+    let the search climb into a shared directory (a temp or home folder) and
+    index unrelated trees.
+    """
+    current = start.resolve()
+    for _ in range(_MAX_PACKAGE_WALK):
+        if not (current / "__init__.py").exists():
+            break
+        current = current.parent
+    if current == current.parent:  # filesystem root — never index an entire drive
+        return None
+    return current
+
+
+# Per-root index memo so scanning files from two projects in one session never
+# grounds one of them with the other's index. Entries hold whatever
+# get_project_index returned last; freshness is re-validated inside it.
+_index_by_root: dict[str, ProjectIndex] = {}
+
+# Project root -> manifest fingerprint for the last automatic dependency
+# declaration. Keeps the (cheap, but not free) manifest parse out of every scan
+# while still noticing an edited requirements.txt / pyproject.toml.
+_deps_stamp_by_root: dict[str, tuple] = {}
+
+
+def _index_for_file(path: Path) -> ProjectIndex | None:
+    """Resolve the (fresh) project index for the project containing *path*.
+
+    Resolution order:
+    1. the **nearest explicitly indexed root** (a root passed to
+       ``index_project``) that contains *path* — an explicit binding is a
+       deliberate statement of scope and must win over generic upward marker
+       discovery. Nested projects rely on this: a demo directory indexed
+       explicitly inside a git repo must not be verified against the repo
+       root's index, or its local module names stop resolving and findings
+       are silently lost;
+    2. the nearest project above *path* discovered via markers;
+    3. ``None`` (scan_file then falls back to trusting-import behaviour).
+
+    ``get_project_index`` validates its cache against the tree's file metadata
+    on every call, so the returned index always reflects files written moments
+    ago. Per-root memoization additionally keeps a session that touches two
+    projects from grounding one with the other's index.
+    """
+    global _project_index, _project_root
+    if not _AUTO_INDEX_ENABLED:
+        with _state_lock:
+            return _project_index
+
+    resolved = path.resolve()
+    root = _nearest_explicit_root(resolved)
+    if root is None:
+        root = _find_project_root(path)
+    if root is None:
+        # No marker anywhere: index from the file's package root. Agents work in
+        # scratch/workspace directories all the time; giving up here made
+        # verify_file silently return "pass" for broken code.
+        root = _package_root(resolved.parent)
+        if root is None:
+            return None
+
+    fresh = get_project_index(root, force_rebuild=False)
+    with _state_lock:
+        _index_by_root[str(root)] = fresh
+        _project_index = fresh
+        _project_root = root
+    return fresh
+
+
+def _nearest_explicit_root(resolved: Path) -> Path | None:
+    """Return the deepest explicitly indexed root containing *resolved*."""
+    with _state_lock:
+        candidates = [Path(r) for r in _index_by_root]
+        proot = _project_root
+    if proot is not None and Path(proot) not in candidates:
+        candidates.append(Path(proot))
+    best: Path | None = None
+    for cand in candidates:
+        try:
+            resolved.relative_to(cand)
+        except ValueError:
+            continue
+        if best is None or len(cand.parts) > len(best.parts):
+            best = cand
+    return best
+
+
+def _ensure_index_for(path: Path) -> bool:
+    """Auto-index the project containing *path* when no index is loaded.
+
+    Kept for backwards compatibility; ``scan_file`` now uses
+    :func:`_index_for_file`, which is per-project-root and always fresh.
+    """
+    global _project_index, _project_root
+    with _state_lock:
+        if _project_index is not None or not _AUTO_INDEX_ENABLED:
+            return False
+    root = _find_project_root(path)
+    if root is None:
+        return False
+    idx = get_project_index(root, force_rebuild=False)
+    with _state_lock:
+        _project_index = idx
+        _project_root = root
+        _invalidate_graph_cache()
+    return True
+
+
+# ── Global server state ────────────────────────────────────────────────
+_state_lock = threading.RLock()
+_project_index: ProjectIndex | None = None
+_project_root: Path | None = None
+_dep_kb: APIKnowledgeBase = APIKnowledgeBase()
+_sandbox: SandboxExecutor = SandboxExecutor()
+_extractor: StructureExtractor = StructureExtractor()
+# In-memory call-graph cache keyed by resolved project root. The SQLite
+# GraphCache on disk is the source of truth; this is just a hot layer.
+_graph_mem_cache: dict[str, CallGraph] = {}
+
+
+def _cache_dir() -> Path:
+    """Directory for symbol/graph caches (override with HONESTCODE_CACHE_DIR)."""
+    return Path(os.environ.get("HONESTCODE_CACHE_DIR", os.path.expanduser("~/.cache/honestcode")))
+
+
+def _manifest_stamp(root: Path) -> tuple | None:
+    """Fingerprint the dependency manifests, or ``None`` when neither exists."""
+    stamp: list[tuple] = []
+    found = False
+    for name in ("requirements.txt", "pyproject.toml"):
+        path = root / name
+        try:
+            st = path.stat()
+        except OSError:
+            stamp.append((name, None, None))
+            continue
+        found = True
+        stamp.append((name, st.st_mtime_ns, st.st_size))
+    return tuple(stamp) if found else None
+
+
+def _ensure_deps_for(root: Path) -> None:
+    """Declare the project's dependencies so their imports are not hallucinations.
+
+    Declared-only on purpose: importing every requirement would execute
+    arbitrary installed code and make the first scan of a data-science project
+    take minutes. Import trust is what prevents ``from flask import Flask``
+    from becoming an ``undefined_symbol`` finding when the server and the
+    project do not share an interpreter; member-level invented-API checks stay
+    silent for packages whose surfaces were never enumerated.
+    """
+    if not _AUTO_DEPS_ENABLED:
+        return
+    stamp = _manifest_stamp(root)
+    if stamp is None:
+        return
+    key = str(root.resolve())
+    with _state_lock:
+        if _deps_stamp_by_root.get(key) == stamp:
+            return
+    try:
+        load_project_deps(str(root), import_packages=False)
+    except Exception:  # noqa: BLE001 - dependency metadata must never break a scan
+        logger.debug("Could not declare dependencies for %s", root, exc_info=True)
+        return
+    with _state_lock:
+        _deps_stamp_by_root[key] = stamp
+
+
+# ── Internal helpers ───────────────────────────────────────────────────
+def _module_name(p: Path, root: Path) -> str:
+    """Infer a dotted module name from *p* relative to *root*.
+
+    Thin alias for :func:`honestcode.structure.utils.module_name_for` — the
+    single implementation of this logic (it used to be copied in four places).
+    """
+    return module_name_for(p, root)
+
+
+def _resolve_relative_module(current_module: str, level: int, target: str) -> str:
+    """Resolve a relative import target to an absolute module name."""
+    if level == 0:
+        return target
+    parts = current_module.split(".")
+    if level > len(parts):
+        return ""
+    prefix = parts[:-level]
+    if target:
+        prefix.append(target)
+    return ".".join(prefix)
+
+
+def _normalize_imported_symbols(
+    imported_symbols: dict[str, str],
+    tree: ast.AST,
+    module: str,
+) -> dict[str, str]:
+    """Convert relative import sources to absolute module names.
+
+    ``StructureExtractor`` stores relative imports without their leading dots.
+    Normalizing them here lets ``valid_imported_names`` validate them against
+    the project index without producing false positives on intra-package
+    imports.
+    """
+    normalized = dict(imported_symbols)
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.ImportFrom):
+            continue
+        if node.level == 0:
+            continue
+        target = node.module or ""
+        abs_module = _resolve_relative_module(module, node.level, target)
+        if not abs_module:
+            continue
+        for alias in node.names:
+            if alias.name == "*":
+                # Restate a relative star import as an absolute one: drop the
+                # raw key the extractor wrote, add the resolved source.
+                normalized.pop(f"*{target}", None)
+                normalized[f"*{abs_module}"] = abs_module
+                continue
+            local = alias.asname or alias.name
+            normalized[local] = f"{abs_module}.{alias.name}"
+    return normalized
+
+
+def _with_module_prefix(p: Path, root: Path, res: ParseResult) -> ParseResult:
+    """Return a copy of *res* whose symbol names are prefixed by their module."""
+    module = _module_name(p, root)
+    if not module:
+        return res
+    prefix = module + "."
+
+    def prefixed(d: dict[str, tuple[int, int]]) -> dict[str, tuple[int, int]]:
+        return {prefix + k if not k.startswith(prefix) else k: v for k, v in d.items()}
+
+    return ParseResult(
+        edges=res.edges,
+        func_defs=prefixed(res.func_defs),
+        class_defs=prefixed(res.class_defs),
+        var_defs=prefixed(res.var_defs),
+        imports=res.imports,
+        imported_symbols=res.imported_symbols,
+        exported_symbols={
+            prefix + s if not s.startswith(prefix) else s for s in (res.exported_symbols or set())
+        },
+        class_bases={
+            prefix + k if not k.startswith(prefix) else k: v
+            for k, v in (res.class_bases or {}).items()
+        },
+    )
+
+
+def _parse_results_for(root: Path) -> dict[Path, ParseResult]:
+    """Parse every indexable *.py file under root and return a path -> result map."""
+    results: dict[Path, ParseResult] = {}
+    for p in iter_python_files(root):
+        try:
+            res = _extractor.parse_file(p)
+            results[p] = _with_module_prefix(p, root, res)
+        except Exception:  # noqa: BLE001
+            continue
+    return results
+
+
+def _normalize_code(text: str) -> str:
+    """Normalize code for similarity comparison."""
+    lines = text.splitlines()
+    out: list[str] = []
+    for line in lines:
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        out.append(re.sub(r"\s+", " ", stripped))
+    return "\n".join(out)
+
+
+def _build_call_graph(root: Path) -> CallGraph:
+    """Build a project-wide definition/reference graph from ASTs.
+
+    Reference ``context`` is recorded as the **module-qualified** enclosing
+    symbol name (e.g. ``pkg.core.main``) when derivable, so that callers of
+    ``explore_call_graph`` can match by the same key they pass in. The short
+    name (``main``) is still recorded as a secondary key for backwards
+    compatibility with short-name lookups.
+    """
+    graph = CallGraph()
+
+    for p, res in _parse_results_for(root).items():
+        # Build a lineno -> module-qualified enclosing context map for this file.
+        # Map from short name -> qualified name using the (already-prefixed)
+        # function/class defs returned by _parse_results_for.
+        module = _module_name(p, root)
+        qualified_by_short: dict[str, str] = {}
+        for qname in list(res.func_defs.keys()) + list(res.class_defs.keys()):
+            short = qname.split(".")[-1]
+            qualified_by_short.setdefault(short, qname)
+
+        # Definitions
+        for name, (start, end) in res.func_defs.items():
+            graph.definitions.setdefault(name, []).append((p, start + 1, end + 1, "function"))
+        for name, (start, end) in res.class_defs.items():
+            graph.definitions.setdefault(name, []).append((p, start + 1, end + 1, "class"))
+        for name, (start, end) in res.var_defs.items():
+            graph.definitions.setdefault(name, []).append((p, start + 1, end + 1, "variable"))
+
+        # AST-level references with enclosing context (module-qualified).
+        # The extractor's same-scope edges are intentionally not re-recorded
+        # here: the AST walk below already captures every Name/Attribute/
+        # Call reference (with context), and re-adding edges would duplicate
+        # caller entries with wrong (definition) line numbers.
+        imported = res.imported_symbols or {}
+        try:
+            tree = ast.parse(p.read_text(encoding="utf-8"), filename=str(p))
+        except SyntaxError:
+            continue
+
+        for node in ast.iter_child_nodes(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                ctx = qualified_by_short.get(node.name, node.name)
+                _record_reference(node, p, graph, ctx, imported, module)
+                _collect_refs_in(node, p, graph, ctx, qualified_by_short, imported, module)
+            else:
+                _record_reference(node, p, graph, module or None, imported, module)
+                _collect_refs_in(
+                    node, p, graph, module or None, qualified_by_short, imported, module
+                )
+
+    return graph
+
+
+def _collect_refs_in(
+    node: ast.AST,
+    p: Path,
+    graph: CallGraph,
+    context: str | None,
+    qualified_by_short: dict[str, str] | None = None,
+    imported: dict[str, str] | None = None,
+    module: str | None = None,
+) -> None:
+    """Collect call/name references inside *node*, attaching *context*.
+
+    When *qualified_by_short* is provided and a nested ``FunctionDef`` /
+    ``ClassDef`` is encountered, the context is updated to that node's
+    module-qualified name (looked up by its short name) so that references
+    inside a class method are attributed to ``pkg.Mod.Class.method`` rather
+    than to the enclosing class.
+    """
+    for child in ast.iter_child_nodes(node):
+        if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            # Recurse with the child's qualified name as the new context.
+            if qualified_by_short is not None:
+                child_ctx = qualified_by_short.get(child.name)
+                if child_ctx is None:
+                    # Build a dotted path from the current context.
+                    child_ctx = f"{context}.{child.name}" if context else child.name
+            else:
+                child_ctx = child.name
+            _record_reference(child, p, graph, child_ctx, imported, module)
+            _collect_refs_in(child, p, graph, child_ctx, qualified_by_short, imported, module)
+        else:
+            _record_reference(child, p, graph, context, imported, module)
+            _collect_refs_in(child, p, graph, context, qualified_by_short, imported, module)
+
+
+def _record_reference(
+    child: ast.AST,
+    p: Path,
+    graph: CallGraph,
+    context: str | None,
+    imported: dict[str, str] | None = None,
+    module: str | None = None,
+) -> None:
+    """Record a single AST node as a reference if it is a call/name/attribute.
+
+    When *imported* is given, the reference is additionally recorded under its
+    import-resolved qualified name — ``verify_tree`` written after ``from
+    honestcode.verify.verify import verify_tree`` is stored both as
+    ``verify_tree`` and as ``honestcode.verify.verify.verify_tree``. Without
+    the qualified form, definition-side keys (which are module-qualified) and
+    reference-side keys (which are written as in source) never met, and
+    ``find_dead_code`` reported live entry points as dead.
+    """
+    key: str | None = None
+    kind = "reference"
+    if isinstance(child, ast.Call):
+        key = call_name(child.func)
+        kind = "call"
+    elif isinstance(child, ast.Name):
+        if isinstance(child.ctx, ast.Store):
+            return
+        key = child.id
+    elif isinstance(child, ast.Attribute):
+        if isinstance(child.ctx, ast.Store):
+            return
+        key = call_name(child)
+        kind = "attribute"
+    if not key:
+        return
+    graph.references.setdefault(key, []).append((p, child.lineno, kind, context))
+    if imported is not None:
+        head, _, rest = key.partition(".")
+        src = imported.get(head)
+        # Only dotted absolute sources qualify; relative-import sources cannot
+        # be resolved reliably here (the leading dots are lost by the parser).
+        if src and "." in src:
+            qual = f"{src}.{rest}" if rest else src
+            if qual != key:
+                graph.references.setdefault(qual, []).append((p, child.lineno, kind, context))
+
+
+# ── Tools ──────────────────────────────────────────────────────────────
+def _invalidate_graph_cache() -> None:
+    """Drop the in-memory call-graph cache (after re-indexing)."""
+    with _state_lock:
+        _graph_mem_cache.clear()
+
+
+def _get_call_graph(root: Path) -> CallGraph:
+    """Return a fresh call graph, reading from the SQLite cache when possible.
+
+    Falls back to a full AST rebuild and persists it to disk, so repeated graph
+    queries (call-graph, dead-code, impact, affected) stay fast on large repos.
+    """
+    with _state_lock:
+        cached = _graph_mem_cache.get(str(root))
+    if cached is not None:
+        return cached
+
+    cache = GraphCache.for_root(root, _cache_dir())
+    if cache.is_fresh(root):
+        loaded = cache.load()
+        if loaded is not None:
+            with _state_lock:
+                _graph_mem_cache[str(root)] = loaded
+            return loaded
+
+    graph = _build_call_graph(root)
+    try:
+        cache.save(graph, root)
+    except OSError:
+        logger.debug("Could not persist graph cache for %s", root)
+    with _state_lock:
+        _graph_mem_cache[str(root)] = graph
+    return graph
+
+
+# One background watcher per watched root. A single global used to mean the
+# second ``index_project(watch=True)`` silently went unwatched while still
+# reporting ``watching: true``.
+_watchers: dict[str, ProjectWatcher] = {}
+
+
+def _ensure_watcher(root: Path) -> None:
+    """Start a background file watcher that auto-reindexes on changes."""
+    key = str(root)
+    with _state_lock:
+        if key in _watchers:
+            return
+
+    def _on_change(changed: list) -> None:
+        global _project_index, _project_root
+        idx = get_project_index(root, force_rebuild=False)
+        with _state_lock:
+            _index_by_root[key] = idx
+            # The watched root only becomes "the" project when the session is
+            # not already anchored elsewhere; multi-root sessions keep the
+            # last explicitly indexed project for the graph tools.
+            if _project_root is None or Path(_project_root) == root:
+                _project_index = idx
+                _project_root = root
+            _invalidate_graph_cache()
+        logger.info("Watcher: re-indexed after %d file changes", len(changed))
+
+    watcher = ProjectWatcher(root, _on_change).start()
+    with _state_lock:
+        _watchers[key] = watcher
+
+
+def stop_watching() -> dict:
+    """Stop every background file watcher, if any."""
+    with _state_lock:
+        if not _watchers:
+            return {"success": True, "watching": False}
+        watchers = list(_watchers.values())
+        _watchers.clear()
+    for watcher in watchers:
+        watcher.stop()
+    return {"success": True, "watching": False}
+
+
+def index_project(root_path: str, force_rebuild: bool = False, watch: bool = False) -> dict:
+    """Build (or reuse) the symbol index for a project directory."""
+    global _project_index, _project_root
+    root = Path(root_path)
+    if not root.exists():
+        return {"success": False, "error": f"Path does not exist: {root_path}"}
+    resolved = root.resolve()
+    idx = get_project_index(resolved, force_rebuild=force_rebuild)
+    with _state_lock:
+        _project_root = resolved
+        _project_index = idx
+        _index_by_root[str(resolved)] = idx
+        _invalidate_graph_cache()
+    if watch:
+        _ensure_watcher(resolved)
+    return {
+        "success": True,
+        "symbols_indexed": len(idx.symbols),
+        "root": str(resolved),
+        "cached": idx.cached,
+        "watching": str(resolved) in _watchers,
+    }
+
+
+def load_project_deps(root_path: str, import_packages: bool = True) -> dict:
+    """Load dependency APIs declared in requirements.txt / pyproject.toml.
+
+    With ``import_packages=False`` the declared packages are only *registered*
+    (their imports become trusted) without importing them — useful for
+    offline/hermetic analysis and benchmarks, where installing or importing
+    every dependency is undesirable. Member-level invented-API checks stay
+    silent for packages that were declared but not imported.
+    """
+    root = Path(root_path)
+    loaded: list[str] = []
+    for candidate in ("requirements.txt", "pyproject.toml"):
+        f = root / candidate
+        if not f.exists():
+            continue
+        pkgs = _parse_requires(f)
+        for pkg in pkgs:
+            try:
+                if not import_packages:
+                    _dep_kb.declare_package(pkg)
+                    loaded.append(pkg)
+                    continue
+                n = _dep_kb.load_package(pkg)
+                if n:
+                    loaded.append(pkg)
+            except Exception:  # noqa: BLE001
+                logger.debug("Failed to load package %s", pkg)
+    return {"success": True, "packages_loaded": loaded, "total_apis": len(_dep_kb.all_names())}
+
+
+def _parse_requires(f: Path) -> list[str]:
+    text = f.read_text(encoding="utf-8")
+    pkgs: list[str] = []
+    if f.name == "requirements.txt":
+        for line in text.splitlines():
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            # Skip pip options / VCS installs.
+            if line.startswith("-") or line.startswith("http://") or line.startswith("https://"):
+                continue
+            m = re.match(r"^([A-Za-z0-9_.\-]+)", line)
+            if m:
+                pkgs.append(m.group(1))
+    else:  # pyproject.toml
+        pkgs.extend(_parse_pyproject_deps(text))
+    return pkgs
+
+
+def _parse_pyproject_deps(text: str) -> list[str]:
+    """Extract package names from pyproject.toml, preferring TOML parsing."""
+    try:
+        try:
+            import tomllib  # Python 3.11+
+        except ImportError:
+            import tomli as tomllib  # type: ignore[no-redef]
+        data = tomllib.loads(text)
+        deps: list[str] = []
+        for key in ("project.dependencies", "tool.poetry.dependencies"):
+            parts = key.split(".")
+            cur = data
+            for part in parts:
+                cur = cur.get(part, {})
+            if isinstance(cur, list):
+                deps.extend(_strip_version_spec(d) for d in cur if isinstance(d, str))
+            elif isinstance(cur, dict):
+                # Poetry declares dependencies as {name: version} pairs.
+                deps.extend(k for k in cur if isinstance(k, str))
+        # Optional groups are still declared project dependencies: the project
+        # may legitimately import them (HonestCode's own optional integrations
+        # are the motivating case). Trusting the declaration silences the
+        # import; member surfaces remain silent until the package is loaded.
+        optional = data.get("project", {}).get("optional-dependencies", {})
+        if isinstance(optional, dict):
+            for group in optional.values():
+                if isinstance(group, list):
+                    deps.extend(_strip_version_spec(d) for d in group if isinstance(d, str))
+        return deps
+    except Exception:  # noqa: BLE001
+        pass
+
+    # Fallback regex for quoted / unquoted declarations.
+    pkgs: list[str] = []
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        # "name>=1.0" or name = ">=1.0"
+        m = re.match(r'^["\']?([A-Za-z0-9_.\-]+)["\']?\s*(?:[<>=!~^]=?|$|\s)', line)
+        if m:
+            pkgs.append(m.group(1))
+    return pkgs
+
+
+def _strip_version_spec(dep: str) -> str:
+    """Return the package name part of a dependency specifier."""
+    dep = dep.strip()
+    m = re.match(r"^([A-Za-z0-9_.\-]+)", dep)
+    return m.group(1) if m else dep
+
+
+def check_symbol(symbol_name: str, file_path: str | None = None) -> dict:
+    """Check whether a symbol is defined in the project.
+
+    When *file_path* is supplied, the symbol must be defined in that file: the
+    parameter used to be accepted and then ignored, so a caller could not ask
+    the narrower question it promises.
+    """
+    with _state_lock:
+        idx = _project_index
+    if idx is None:
+        return {"success": False, "error": "Project not indexed. Call index_project first."}
+
+    info = idx.symbols.get(symbol_name)
+    if file_path:
+        root = Path(idx.root)
+        candidate = Path(file_path)
+        try:
+            rel = candidate.resolve().relative_to(root.resolve()).as_posix()
+        except (OSError, ValueError):
+            rel = str(candidate).replace("\\", "/")
+        info_in_file = [
+            symbol_info
+            for name, symbol_info in idx.symbols.items()
+            if symbol_info.file == rel and (name == symbol_name or name.endswith(f".{symbol_name}"))
+        ]
+        # A short name is matched by its qualified suffix, so the file filter
+        # has to run even when the bare name itself was not an index key.
+        info = info_in_file[0] if info_in_file else None
+
+    return {
+        "success": True,
+        "symbol": symbol_name,
+        "defined": info is not None,
+        "location": {"file": info.file, "line": info.line} if info else None,
+        **({"file": file_path} if file_path else {}),
+    }
+
+
+def _is_stdlib_root(name: str) -> bool:
+    """Whether *name* is a standard-library root that really is the stdlib.
+
+    ``sys.stdlib_module_names`` alone is not enough: a workspace file called
+    ``math.py`` shadows the real module for imports from the server's cwd, so
+    the spec's origin must sit inside the interpreter's stdlib directory (or
+    the module must be baked in) before importing it is allowed.
+    """
+    if name not in stdlib_roots():
+        return False
+    try:
+        spec = importlib.util.find_spec(name)
+    except Exception:  # noqa: BLE001 - a broken spec is not a stdlib module
+        return False
+    if spec is None:
+        return False
+    origin = getattr(spec, "origin", None)
+    if origin in (None, "built-in", "frozen"):
+        # A workspace directory can shadow a stdlib name as a namespace
+        # package (origin None); only genuinely built-in/frozen modules are
+        # safe to trust in that case. "built-in"/"frozen" cannot be shadowed.
+        return origin is not None or name in sys.builtin_module_names
+    stdlib_dir = Path(sysconfig.get_paths()["stdlib"]).resolve()
+    try:
+        return Path(origin).resolve().is_relative_to(stdlib_dir)
+    except (OSError, ValueError):
+        return False
+
+
+def _installed_import_root(name: str) -> bool:
+    """Whether *name* is an installed distribution or a real import root.
+
+    ``check_api`` imports the base package on demand to answer a CLI caller
+    who cannot run ``load-package`` first. Importing executes code, so the
+    gate must not open for a bare file in the workspace: an agent-written
+    ``evil_payload.py`` next to the server's cwd is importable via ``sys.path``
+    but is not an installed distribution, and importing it would run
+    agent-authored code inside the server process. Distribution metadata is
+    read without executing anything.
+    """
+    if name in _dep_kb.roots() or _is_stdlib_root(name):
+        return True
+    try:
+        importlib.metadata.distribution(name)
+        return True
+    except Exception:  # noqa: BLE001 - not installed under this spelling
+        pass
+    try:
+        return name in importlib.metadata.packages_distributions()
+    except Exception:  # noqa: BLE001 - metadata unavailable
+        return False
+
+
+def check_api(api_name: str) -> dict:
+    """Verify a library API call is correct (e.g. pd.read_exel -> read_excel)."""
+    if _dep_kb.has(api_name):
+        return {"success": True, "api": api_name, "valid": True}
+
+    base = api_name.split(".")[0]
+    dep_names = _dep_kb.all_names()
+    base_known = _dep_kb.has(base) or any(k.startswith(base + ".") for k in dep_names)
+    if not base_known and _installed_import_root(base):
+        # A CLI invocation is a fresh process: the user cannot first run
+        # ``load-package`` and then ``check-api``. Load the base package on
+        # demand — but only when it is genuinely installed (or already
+        # declared); an uninstalled name must not be imported, or a file the
+        # agent dropped into the workspace gets executed server-side.
+        with suppress(Exception):  # an absent package is a valid answer
+            _dep_kb.load_package(base)
+        dep_names = _dep_kb.all_names()
+        base_known = _dep_kb.has(base) or any(k.startswith(base + ".") for k in dep_names)
+    if not base_known:
+        return {
+            "success": True,
+            "api": api_name,
+            "valid": False,
+            "reason": "unknown module",
+            "suggestion": [],
+        }
+
+    members = [k for k in dep_names if k.startswith(base + ".")]
+    attr_part = api_name.split(".")[-1]
+    exact = [m for m in members if m == api_name]
+    if exact:
+        return {"success": True, "api": api_name, "valid": True}
+
+    close = [m for m in members if m.split(".")[-1] == attr_part]
+    if close:
+        return {
+            "success": True,
+            "api": api_name,
+            "valid": False,
+            "reason": "Attribute not found on module",
+            "suggestion": close[:3],
+        }
+
+    from difflib import get_close_matches
+
+    fuzzy = get_close_matches(api_name, members, n=3, cutoff=0.6)
+    return {
+        "success": True,
+        "api": api_name,
+        "valid": False,
+        "reason": "Attribute not found on module",
+        "suggestion": fuzzy if fuzzy else members[:3],
+    }
+
+
+def execute_code(code: str, prelude: str = "", known_names: list[str] | None = None) -> dict:
+    """Execute code in a sandboxed subprocess and return structured results."""
+    result = _sandbox.execute(code=code, prelude=prelude, known_names=set(known_names or []))
+    return result.to_dict()
+
+
+def _collect_local_defined(tree: ast.AST) -> set[str]:
+    """Collect locally defined names (functions, classes, vars, parameters).
+
+    Includes parameters and assignment targets so that ``self.helper()`` or
+    ``client.fetch()`` are not flagged when ``self`` / ``client`` are bound
+    in the enclosing scope. Names bound by ``with ... as``, ``except ... as``,
+    lambda parameters, comprehension targets and ``global``/``nonlocal``
+    declarations count too — missing them reported ``fn()`` under
+    ``with Ctx() as fn:`` as an undefined symbol.
+    """
+    defined: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            defined.add(node.name)
+            _collect_arg_names(node.args, defined)
+        elif isinstance(node, ast.Lambda):
+            _collect_arg_names(node.args, defined)
+        elif isinstance(node, ast.ClassDef):
+            defined.add(node.name)
+        elif isinstance(node, ast.Assign):
+            for target in node.targets:
+                _collect_assign_targets(target, defined)
+        elif isinstance(node, (ast.AnnAssign, ast.AugAssign)) and isinstance(node.target, ast.Name):
+            defined.add(node.target.id)
+        elif isinstance(node, (ast.For, ast.AsyncFor)):
+            _collect_assign_targets(node.target, defined)
+        elif isinstance(node, (ast.With, ast.AsyncWith)):
+            for item in node.items:
+                if item.optional_vars is not None:
+                    _collect_assign_targets(item.optional_vars, defined)
+        elif isinstance(node, ast.ExceptHandler):
+            if node.name:
+                defined.add(node.name)
+        elif isinstance(node, ast.comprehension):
+            _collect_assign_targets(node.target, defined)
+        elif isinstance(node, (ast.Global, ast.Nonlocal)):
+            defined.update(node.names)
+        elif isinstance(node, ast.NamedExpr):  # walrus :=
+            if isinstance(node.target, ast.Name):
+                defined.add(node.target.id)
+    return defined
+
+
+def _collect_arg_names(args: ast.arguments, defined: set[str]) -> None:
+    for a in args.args + args.posonlyargs + args.kwonlyargs:
+        if a.arg:
+            defined.add(a.arg)
+    if args.vararg:
+        defined.add(args.vararg.arg)
+    if args.kwarg:
+        defined.add(args.kwarg.arg)
+
+
+def _collect_assign_targets(target: ast.expr, defined: set[str]) -> None:
+    if isinstance(target, ast.Name):
+        defined.add(target.id)
+    elif isinstance(target, (ast.Tuple, ast.List)):
+        for elt in target.elts:
+            _collect_assign_targets(elt, defined)
+    elif isinstance(target, ast.Starred):
+        _collect_assign_targets(target.value, defined)
+
+
+def _builtin_names() -> set[str]:
+    """Return the full set of Python builtin names (functions + exceptions)."""
+    import builtins
+
+    return set(dir(builtins))
+
+
+# Per-language aids for the heuristic non-Python scan: builtins that are legal
+# to call without a definition in the scanned file, and regexes that surface
+# names the file imports or declares. Without these, every cross-module call
+# was reported as "undefined" — pure noise that violated the project's
+# silence-beats-noise rule.
+_LANG_BUILTINS: dict[str, set[str]] = {
+    "javascript": {
+        "require",
+        "setTimeout",
+        "setInterval",
+        "clearTimeout",
+        "clearInterval",
+        "queueMicrotask",
+        "structuredClone",
+        "fetch",
+        "parseInt",
+        "parseFloat",
+        "isNaN",
+        "isFinite",
+        "encodeURIComponent",
+        "decodeURIComponent",
+        "Promise",
+        "URL",
+        "URLSearchParams",
+        "AbortController",
+        "TextEncoder",
+        "TextDecoder",
+        "Proxy",
+        "Reflect",
+        "Symbol",
+        "BigInt",
+        "Date",
+        "RegExp",
+    },
+    "go": {
+        "len",
+        "cap",
+        "make",
+        "new",
+        "append",
+        "copy",
+        "delete",
+        "panic",
+        "recover",
+        "print",
+        "println",
+        "close",
+        "min",
+        "max",
+        "clear",
+    },
+    "rust": {
+        "println",
+        "print",
+        "eprintln",
+        "eprint",
+        "format",
+        "vec",
+        "panic",
+        "assert",
+        "assert_eq",
+        "assert_ne",
+        "write",
+        "writeln",
+        "todo",
+        "unimplemented",
+        "matches",
+        "dbg",
+        "env",
+        "concat",
+        "stringify",
+        "include_str",
+        "include_bytes",
+        "cfg",
+    },
+}
+_LANG_BUILTINS["typescript"] = _LANG_BUILTINS["javascript"]
+_LANG_BUILTINS["tsx"] = _LANG_BUILTINS["javascript"]
+
+_LANG_IMPORT_PATTERNS: dict[str, list[str]] = {
+    # Each pattern's group(s) yield imported local names.
+    "javascript": [
+        r"import\s*\{([^}]+)\}\s*from",
+        r"import\s*\*\s*as\s+(\w+)",
+        r"import\s+(\w+)\s*(?:,|from)",
+        r"(?:const|let|var)\s*\{([^}]+)\}\s*=\s*require\(",
+        r"(?:const|let|var)\s+(\w+)\s*=\s*require\(",
+    ],
+    "go": [
+        r'import\s+(?:\w+\s+)?"([^"]+)"',
+        r'^\s*(?:\w+\s+)?"([^"]+)"',
+    ],
+    "rust": [
+        r"use\s+[\w:]*::\{([^}]+)\}",
+        r"use\s+([\w:]+)",
+    ],
+    "java": [
+        r"import\s+(?:static\s+)?([\w.]+)\s*;",
+    ],
+}
+_LANG_IMPORT_PATTERNS["typescript"] = _LANG_IMPORT_PATTERNS["javascript"]
+_LANG_IMPORT_PATTERNS["tsx"] = _LANG_IMPORT_PATTERNS["javascript"]
+
+# Language keywords / soft keywords that syntactically look like calls.
+_LANG_KEYWORDS: set[str] = {
+    "if",
+    "for",
+    "while",
+    "switch",
+    "catch",
+    "function",
+    "new",
+    "typeof",
+    "return",
+    "else",
+    "do",
+    "try",
+    "throw",
+    "case",
+    "await",
+    "async",
+    "yield",
+    "delete",
+    "void",
+    "instanceof",
+    "super",
+    "func",
+    "go",
+    "defer",
+    "select",
+    "fn",
+    "match",
+    "loop",
+    "unsafe",
+    "impl",
+    "dyn",
+    "move",
+    "synchronized",
+    "assert",
+}
+
+# Fallback declaration patterns for names tree-sitter may not surface
+# (variables, Go receivers, Java members) — best-effort, silence-biased.
+_LANG_DECL_PATTERNS: dict[str, list[str]] = {
+    "javascript": [
+        r"\b(?:const|let|var)\s+(\w+)",
+        r"\bfunction\s*\*?\s*(\w+)",
+        r"\bclass\s+(\w+)",
+    ],
+    "go": [
+        r"func\s+(?:\([^)]*\)\s*)?(\w+)\s*",
+        r"type\s+(\w+)\s+",
+        r"(?:^|\n)\s*(?:var|const)\s+(\w+)",
+    ],
+    "rust": [r"\blet\s+(?:mut\s+)?(\w+)", r"\b(?:static|const)\s+(\w+)"],
+    "java": [
+        r"\b(?:class|interface|enum)\s+(\w+)",
+        r"\b(?:public|protected|private)\s+[\w<>\[\],.\s]+?\s+(\w+)\s*\([^;)]*\)\s*[;{]",
+    ],
+}
+_LANG_DECL_PATTERNS["typescript"] = _LANG_DECL_PATTERNS["javascript"]
+_LANG_DECL_PATTERNS["tsx"] = _LANG_DECL_PATTERNS["javascript"]
+
+
+def _scan_non_python(p: Path) -> dict:
+    """Scan a non-Python file via the optional tree-sitter multi-language path.
+
+    This path is heuristic by nature: a call is reported only when its name is
+    neither defined in nor imported by the file (and is not a language builtin
+    or keyword), and every finding is marked ``confidence: low`` so agents and
+    humans treat it as a pointer, not a verdict.
+    """
+    from honestcode.structure import multi_lang
+
+    lang = multi_lang.detect_language(p)
+    if lang is None:
+        return {
+            "success": False,
+            "error": f"Unsupported language for {p.suffix or 'file'}. "
+            "Python is fully supported; other languages need the "
+            "multi-language extra: pip install -e '.[multi-language]'.",
+        }
+    try:
+        symbols = multi_lang.extract_symbols(p)
+    except multi_lang.TreeSitterUnavailable as exc:
+        return {
+            "success": False,
+            "error": f"{exc}. Language detected: {lang}. Run: pip install -e '.[multi-language]'",
+        }
+    except Exception as exc:  # noqa: BLE001
+        return {"success": False, "error": f"multi-language scan failed: {exc}"}
+    try:
+        # Heuristic regex scan: replacement characters only cost a missed match,
+        # whereas a hard UnicodeDecodeError would take the whole tool down.
+        source = p.read_text(encoding="utf-8", errors="replace")
+    except OSError as exc:
+        return {"success": False, "error": f"cannot read file: {exc}"}
+
+    defined = {s["name"] for s in symbols}
+
+    # Imported names: the last segment of the import target (plus, for
+    # multi-name forms, every declared local).
+    import_name_group = _LANG_IMPORT_PATTERNS.get(lang, [])
+    for pat in import_name_group:
+        for m in re.finditer(pat, source, re.MULTILINE):
+            for group in m.groups():
+                if not group:
+                    continue
+                for part in group.split(","):
+                    part = part.strip().split(" as ")[-1].strip()
+                    if part:
+                        defined.add(part.rsplit(":", 1)[-1].rsplit(".", 1)[-1])
+            # `use std::io;` / `import a.b.C;` — the tail is the used name.
+            tail = m.group(0).rstrip(";").split()[-1].strip("\"';,()")
+            if tail and re.fullmatch(r"[\w:./-]+", tail):
+                defined.add(tail.rsplit(":", 1)[-1].rsplit(".", 1)[-1])
+
+    for pat in _LANG_DECL_PATTERNS.get(lang, []):
+        for m in re.finditer(pat, source, re.MULTILINE):
+            for group in m.groups():
+                if group and group.isidentifier():
+                    defined.add(group)
+
+    builtins = _LANG_BUILTINS.get(lang, set())
+    keywords = _LANG_KEYWORDS
+
+    findings: list[Finding] = []
+    # Negative lookbehind skips attribute calls (``obj.method(``), which
+    # cannot be judged statically; keyword set covers language constructs
+    # that look like calls (``new Foo(``, ``require(``, ...).
+    for m in re.finditer(r"(?<![.\w$])([A-Za-z_$][\w$]*)\s*\(", source):
+        name = m.group(1)
+        if name in defined or name in builtins or name in keywords:
+            continue
+        findings.append(
+            Finding(
+                file=str(p),
+                line=source[: m.start()].count("\n") + 1,
+                kind=KIND_UNDEFINED_SYMBOL,
+                symbol=name,
+                message=(
+                    f"`{name}` is not defined or imported in this file "
+                    f"(heuristic {lang} scan — inspect before changing)."
+                ),
+                evidence={"language": lang, "heuristic": True},
+                confidence=CONFIDENCE_LOW,
+                action=ACTION_INSPECT,
+            )
+        )
+
+    report = build_report(file=str(p), findings=findings, checked=0)
+    report["language"] = lang
+    report["defined_symbols"] = len(defined)
+    return report
+
+
+def scan_file(file_path: str) -> dict:
+    """Scan a file for potential hallucinations: undefined symbols and invented APIs."""
+    p = Path(file_path)
+    if not p.exists():
+        return {"success": False, "error": f"File not found: {file_path}"}
+    if p.suffix.lower() != ".py":
+        return _scan_non_python(p)
+    try:
+        res = _extractor.parse_file(p)
+    except Exception as e:  # noqa: BLE001
+        return {"success": False, "error": str(e)}
+
+    # Ground the file against a FRESH index of its own project. Most agents
+    # call scan_file on a freshly-written path without remembering to call
+    # index_project first; resolving per-file also keeps a session that touches
+    # several projects from grounding one with another's index.
+    idx = _index_for_file(p)
+    if idx is not None:
+        _ensure_deps_for(Path(idx.root))
+    else:
+        fallback_root = _find_project_root(p)
+        if fallback_root is not None:
+            _ensure_deps_for(fallback_root)
+
+    with _state_lock:
+        dep_names = _dep_kb.all_names()
+        dep_roots = _dep_kb.roots() | {n.split(".", 1)[0] for n in dep_names} | stdlib_roots()
+        dep_enumerated = _dep_kb.enumerated_modules()
+
+    source = read_python_source(p)
+    if source is None:
+        return {"success": False, "error": f"cannot read file: {p}"}
+    try:
+        tree = ast.parse(source, filename=str(p))
+    except SyntaxError as e:
+        # A syntax error is itself a verification finding, not a tool failure:
+        # the agent needs the structured protocol (status/findings/text) so it
+        # can act on it like any other kind.
+        finding = Finding(
+            file=str(p),
+            line=e.lineno or 1,
+            kind=KIND_SYNTAX_ERROR,
+            symbol="<syntax>",
+            message=f"SyntaxError: {e.msg}",
+            evidence={"offset": e.offset or 0},
+            action=ACTION_INSPECT,
+        )
+        report = build_report(file=str(p), findings=[finding], checked=0)
+        report["defined_symbols"] = 0
+        return report
+
+    # Locally defined names (functions/classes/vars + parameters + loop targets).
+    defined = _collect_local_defined(tree)
+    # Module-qualified project symbols.
+    if idx is not None:
+        defined |= set(idx.symbols.keys())
+    # Names introduced by import statements, validated against the index and
+    # the loaded dependency API knowledge base.
+    module = _module_name(p, Path(idx.root)) if idx is not None else p.stem
+    imported_symbols = _normalize_imported_symbols(res.imported_symbols or {}, tree, module)
+    if idx is not None:
+        # A monorepo sub-project writes absolute imports meaning its own
+        # package (``from pkg.foo import Thing`` under ``services/web/``);
+        # against the repo-rooted index those names only exist one package
+        # level up. Re-point them so valid imports are not hallucinations.
+        imported_symbols = resolve_package_relative_imports(imported_symbols, idx, module)
+    defined |= valid_imported_names(imported_symbols, idx, dep_names, dep_roots)
+    # A star import whose source cannot be enumerated may have bound any name;
+    # unproven bare calls in this file must then stay silent.
+    star_open = star_imports_unresolved(imported_symbols, idx)
+    # Dependency API names.
+    defined |= dep_names
+    # Full builtin set instead of a hand-picked subset.
+    defined |= _builtin_names()
+
+    findings, checked = verify_tree(
+        tree,
+        path=p,
+        root=Path(idx.root) if idx is not None else None,
+        index=idx,
+        defined=defined,
+        dep_names=dep_names,
+        imported_symbols=imported_symbols,
+        dep_roots=dep_roots,
+        dep_enumerated=dep_enumerated,
+        star_open=star_open,
+    )
+    report = build_report(file=str(p), findings=findings, checked=checked)
+    report["defined_symbols"] = len(defined)
+    return report
+
+
+def verify_file(file_path: str) -> dict:
+    """Verify a file and return structured, agent-readable evidence.
+
+    Unlike ``scan_file`` (which also returns legacy ``issues``), this tool
+    exposes only the agent-facing protocol: ``status``, ``findings`` with
+    ``evidence``, and a human-readable ``text`` summary.
+    """
+    report = scan_file(file_path)
+    if not report.get("success", True):
+        return report
+    result = {
+        "success": True,
+        "status": report["status"],
+        "file": report["file"],
+        "findings": report["findings"],
+        "summary": report["summary"],
+        "text": render_text(report),
+    }
+    for key in ("language", "defined_symbols"):
+        if key in report:
+            result[key] = report[key]
+    return result
+
+
+def load_package_apis(package_name: str) -> dict:
+    """Load (and cache) API signatures for a specific package."""
+    count = _dep_kb.load_package(package_name)
+    return {"success": True, "package": package_name, "api_count": count}
+
+
+def reset_dependency_state() -> dict:
+    """Forget every loaded dependency API and declared root.
+
+    Used by tests and the accuracy benchmark to isolate scenarios; a live MCP
+    session has no reason to call this.
+    """
+    _dep_kb.reset()
+    with _state_lock:
+        _deps_stamp_by_root.clear()
+    return {"success": True}
+
+
+def get_project_stats() -> dict:
+    """Return statistics about the current index."""
+    with _state_lock:
+        idx = _project_index
+    if idx is None:
+        return {"success": False, "error": "Project not indexed."}
+    return {
+        "success": True,
+        "symbols": len(idx.symbols),
+        "dependency_apis": len(_dep_kb.all_names()),
+        "indexed": idx is not None,
+    }
+
+
+def validate_types(code: str) -> dict:
+    """Run a lightweight AST-based type check to catch obvious mismatches."""
+    try:
+        tree = ast.parse(code)
+    except SyntaxError as e:
+        return {"success": False, "error": f"SyntaxError: {e}"}
+
+    issues: list[dict] = []
+
+    for node in ast.walk(tree):
+        # 1. None iteration
+        if isinstance(node, (ast.For, ast.AsyncFor, ast.comprehension)):
+            _check_none_iterable(node.iter, issues)
+        if isinstance(node, ast.Compare):
+            for op, comparator in zip(node.ops, node.comparators, strict=True):
+                if isinstance(op, ast.In):
+                    _check_none_iterable(comparator, issues)
+
+        # 2. Calling a constant literal
+        if isinstance(node, ast.Call) and isinstance(node.func, ast.Constant):
+            issues.append(
+                {
+                    "type": "non_callable",
+                    "message": "Attempting to call a constant value",
+                    "line": node.lineno,
+                }
+            )
+
+        # 3. String method on non-string constant
+        if (
+            isinstance(node, ast.Attribute)
+            and node.attr in {"upper", "lower", "strip", "split", "join", "startswith", "endswith"}
+            and isinstance(node.value, ast.Constant)
+            and not isinstance(node.value.value, str)
+        ):
+            issues.append(
+                {
+                    "type": "type_mismatch",
+                    "message": f"'{node.attr}' called on non-string constant",
+                    "line": node.lineno,
+                }
+            )
+
+        # 4. Common builtins with wrong argument count
+        if isinstance(node, ast.Call) and isinstance(node.func, ast.Name):
+            _check_builtin_argc(node, issues)
+
+    return {"success": True, "issues": issues, "note": "AST structural check complete"}
+
+
+def _check_none_iterable(node: ast.expr, issues: list[dict]) -> None:
+    """Flag iterating over a None constant or expressions likely to return None.
+
+    Detects:
+    - Explicit ``None`` literal
+    - ``dict.get(...)`` / ``dict.pop(...)`` without a default value
+    - Call to functions that commonly return None (e.g. ``os.environ.get``)
+    """
+    if isinstance(node, ast.Constant) and node.value is None:
+        issues.append(
+            {
+                "type": "none_iteration",
+                "message": "Attempting to iterate over None",
+                "line": getattr(node, "lineno", 0),
+            }
+        )
+        return
+
+    # dict.get(key) without default returns None.
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute):
+        method = node.func.attr
+        if (
+            method in ("get", "pop")
+            and len(node.args) < 2
+            and not any(kw.arg == "default" for kw in node.keywords)
+        ):
+            issues.append(
+                {
+                    "type": "none_iteration",
+                    "message": f"'{method}' without default may return None",
+                    "line": getattr(node, "lineno", 0),
+                }
+            )
+
+
+def _check_builtin_argc(node: ast.Call, issues: list[dict]) -> None:
+    """Check argument counts for a small set of common builtins.
+
+    Rules are (min_positional, max_positional, allowed_keyword_names).
+    ``None`` means unbounded.
+    """
+    name = node.func.id
+    args = len(node.args)
+    kwargs = {kw.arg for kw in node.keywords if kw.arg is not None}  # exclude **kwargs
+    # ``str(object='', encoding=..., errors=...)`` accepts three positionals
+    # (``str(b'x', 'utf-8', 'strict')``) and the ``object`` keyword. ``max`` /
+    # ``min`` take ``key`` and ``default`` as keywords, and ``sorted``'s
+    # ``key``/``reverse`` are keyword-only — the previous table inverted all
+    # three and flagged valid calls.
+    rules = {
+        "len": (1, 1, set()),
+        "repr": (1, 1, set()),
+        "str": (0, 3, {"object", "encoding", "errors"}),
+        "int": (0, 2, {"base"}),
+        "float": (0, 1, set()),
+        "bool": (0, 1, set()),
+        "abs": (1, 1, set()),
+        "round": (1, 2, {"ndigits"}),
+        "sum": (1, 2, {"start"}),
+        "min": (1, None, {"key", "default"}),
+        "max": (1, None, {"key", "default"}),
+        "sorted": (1, 1, {"key", "reverse"}),
+        "enumerate": (1, 2, {"start"}),
+        "zip": (0, None, {"strict"}),
+        "map": (2, None, set()),
+        "filter": (2, None, set()),
+    }
+    if name not in rules:
+        return
+    min_args, max_args, allowed_kw = rules[name]
+
+    invalid_kw = kwargs - allowed_kw
+    if invalid_kw:
+        issues.append(
+            {
+                "type": "arg_count",
+                "message": f"'{name}' does not accept keyword argument(s): {', '.join(sorted(invalid_kw))}",
+                "line": node.lineno,
+            }
+        )
+        return
+
+    if args < min_args:
+        issues.append(
+            {
+                "type": "arg_count",
+                "message": f"'{name}' expects at least {min_args} positional argument(s)",
+                "line": node.lineno,
+            }
+        )
+    elif max_args is not None and args > max_args:
+        issues.append(
+            {
+                "type": "arg_count",
+                "message": f"'{name}' expects at most {max_args} positional argument(s)",
+                "line": node.lineno,
+            }
+        )
+
+
+def find_dead_code(
+    entrypoints: list[str] | None = None,
+    ignore_patterns: list[str] | None = None,
+    include_tests: bool = True,
+) -> dict:
+    """Find symbols that appear to be unused in the project."""
+    with _state_lock:
+        root = _project_root
+        idx = _project_index
+    if root is None or idx is None:
+        return {"success": False, "error": "Project not indexed. Call index_project first."}
+
+    ignore_res = [re.compile(p) for p in (ignore_patterns or [])]
+    graph = _get_call_graph(root)
+
+    alive: set[str] = set(entrypoints or [])
+
+    # Symbols referenced anywhere in the project are considered alive.
+    # Definitions are keyed by qualified name while references are keyed by
+    # the name as written in source (plus import-resolved qualified aliases —
+    # see _record_reference), so also match on the trailing component.
+    # Deliberately generous: dead-code must err toward silence, and a short
+    # name that matches an unrelated definition only costs a missed report,
+    # never a false one.
+    by_short: dict[str, list[str]] = {}
+    for def_name in graph.definitions:
+        by_short.setdefault(def_name.rsplit(".", 1)[-1], []).append(def_name)
+
+    for name in graph.references:
+        for def_name in by_short.get(name.rsplit(".", 1)[-1], ()):
+            alive.add(def_name)
+
+    if include_tests:
+        for name, locations in graph.definitions.items():
+            for p, _line, _end, _kind in locations:
+                if "test" in p.parts or p.name.startswith("test_"):
+                    alive.add(name)
+                    break
+
+    # Treat dunder hooks and public __init__ exports as alive.
+    for name in graph.definitions:
+        if name.startswith("__") and name.endswith("__"):
+            alive.add(name)
+
+    dead: list[dict] = []
+    for name, locations in graph.definitions.items():
+        if name in alive:
+            continue
+        filtered = [
+            (str(p), line, kind)
+            for p, line, _end, kind in locations
+            if not any(r.search(str(p)) for r in ignore_res)
+        ]
+        if filtered:
+            dead.append({"symbol": name, "locations": filtered})
+
+    return {"success": True, "dead_symbols": dead, "count": len(dead)}
+
+
+def find_similar_code(threshold: float = 0.85, time_budget: float = 30.0) -> dict:
+    """Find function-level code clones across the project.
+
+    Uses a length-ratio pre-filter to skip obviously dissimilar pairs before
+    running the more expensive ``SequenceMatcher``. The comparison loop is
+    quadratic in the number of functions, so it runs under a wall-clock budget
+    (*time_budget* seconds): on a corpus large enough to exhaust the budget
+    the pairs found so far are returned with ``truncated: true`` rather than
+    stalling the tool for minutes.
+    """
+    with _state_lock:
+        root = _project_root
+    if root is None:
+        return {"success": False, "error": "Project not indexed. Call index_project first."}
+
+    functions: list[tuple[Path, str, str, tuple[int, int]]] = []
+    for p, res in _parse_results_for(root).items():
+        code = read_python_source(p)
+        if code is None:
+            continue
+        for name, (start, end) in res.func_defs.items():
+            lines = code.splitlines()[start : end + 1]
+            body = _normalize_code("\n".join(lines))
+            functions.append((p, name, body, (start + 1, end + 1)))
+
+    from difflib import SequenceMatcher
+
+    deadline = time.monotonic() + max(1.0, time_budget)
+    truncated = False
+
+    # Pre-filter: group by similar length to avoid comparing very short or
+    # very different functions.  The similarity ratio between two strings is
+    # bounded by min(len(a), len(b)) / max(len(a), len(b)), so we can skip
+    # pairs whose length ratio is already below the threshold.
+    pairs: list[dict] = []
+    seen: set[tuple[tuple[str, str], tuple[str, str]]] = set()
+    for i, (p1, n1, b1, r1) in enumerate(functions):
+        len1 = len(b1)
+        if len1 < 30:
+            continue
+        if time.monotonic() > deadline:
+            truncated = True
+            break
+        for j in range(i + 1, len(functions)):
+            p2, n2, b2, r2 = functions[j]
+            len2 = len(b2)
+            if len2 < 30:
+                continue
+            # Length-ratio bound: if the shorter is less than threshold * longer, skip.
+            shorter, longer = (len1, len2) if len1 <= len2 else (len2, len1)
+            if shorter < threshold * longer:
+                continue
+            key = tuple(sorted([(str(p1), n1), (str(p2), n2)]))
+            if key in seen:
+                continue
+            ratio = SequenceMatcher(None, b1, b2).ratio()
+            if ratio >= threshold:
+                seen.add(key)
+                pairs.append(
+                    {
+                        "symbol_a": {"file": str(p1), "name": n1, "lines": r1},
+                        "symbol_b": {"file": str(p2), "name": n2, "lines": r2},
+                        "similarity": round(ratio, 3),
+                    }
+                )
+            if time.monotonic() > deadline:
+                truncated = True
+                break
+
+    pairs.sort(key=lambda x: x["similarity"], reverse=True)
+    result = {"success": True, "pairs": pairs, "count": len(pairs)}
+    if truncated:
+        result["truncated"] = True
+    return result
+
+
+def explore_call_graph(symbol_name: str) -> dict:
+    """Explore callers and callees of a symbol across the project."""
+    with _state_lock:
+        root = _project_root
+    if root is None:
+        return {"success": False, "error": "Project not indexed. Call index_project first."}
+
+    graph = _get_call_graph(root)
+
+    definitions = graph.definitions.get(symbol_name, [])
+    short_name = symbol_name.split(".")[-1]
+
+    # Names that count as "this symbol" — both the fully-qualified form and
+    # the short form, so a call context recorded as either will match.
+    self_names = {symbol_name, short_name}
+
+    # Callers: places that reference *symbol_name* (or its short name).
+    callers: list[dict] = []
+    seen_callers: set[tuple[str, int, str]] = set()
+    for ref_name, refs in graph.references.items():
+        if ref_name != symbol_name and ref_name != short_name:
+            continue
+        for p, line, kind, context in refs:
+            key = (str(p), line, context or "")
+            if key in seen_callers:
+                continue
+            seen_callers.add(key)
+            callers.append(
+                {
+                    "caller": context or "<module>",
+                    "file": str(p),
+                    "line": line,
+                    "kind": kind,
+                }
+            )
+
+    # Callees: symbols referenced from inside any of *symbol_name*'s definitions.
+    # A reference is "inside" when its enclosing context matches the symbol
+    # (by qualified or short name) AND it lives in the same file AND its line
+    # falls within the def's span (short names can collide across modules).
+    def_spans = [(p, line, end) for p, line, end, _kind in definitions]
+    callee_names: set[str] = set()
+    for ref_name, refs in graph.references.items():
+        for rp, rline, _rkind, rcontext in refs:
+            if rcontext not in self_names:
+                continue
+            if any(fp == rp and start <= rline <= end for fp, start, end in def_spans):
+                callee_names.add(ref_name)
+
+    callees: list[dict] = []
+    for callee in sorted(callee_names):
+        locations = graph.definitions.get(callee, [])
+        callees.append(
+            {
+                "callee": callee,
+                "defined": [
+                    {"file": str(p), "line": line, "kind": kind}
+                    for p, line, _end, kind in locations
+                ],
+            }
+        )
+
+    result: dict = {
+        "success": True,
+        "symbol": symbol_name,
+        "definitions": [
+            {"file": str(p), "line": line, "kind": kind} for p, line, _end, kind in definitions
+        ],
+        "callers": callers,
+        "callees": callees,
+    }
+    # Blast-radius summary: how far a change to this symbol would ripple.
+    if definitions:
+        impact = explore_impact(symbol_name, max_depth=3)
+        if impact.get("success"):
+            result["impact"] = impact["counts"]
+    return result
+
+
+def explore_impact(symbol_name: str, max_depth: int = 3) -> dict:
+    """Compute the blast radius of a symbol: transitively impacted symbols/files.
+
+    Walks the call graph in both directions (callers and callees) up to
+    ``max_depth`` hops and summarizes which symbols and files would be affected
+    if ``symbol_name`` changed.
+    """
+    with _state_lock:
+        root = _project_root
+    if root is None:
+        return {"success": False, "error": "Project not indexed. Call index_project first."}
+
+    graph = _get_call_graph(root)
+    if symbol_name not in graph.definitions:
+        return {"success": False, "error": f"Symbol not found in project: {symbol_name}"}
+
+    def _callers(name: str) -> set[str]:
+        """Symbols whose bodies reference *name* (or its short form)."""
+        short = name.split(".")[-1]
+        found: set[str] = set()
+        for ref_name, refs in graph.references.items():
+            if ref_name != name and ref_name != short:
+                continue
+            for _p, _line, _kind, context in refs:
+                if context:
+                    found.add(context)
+        return found
+
+    def _callees(name: str) -> set[str]:
+        """Symbols referenced from inside *name*'s definitions (same file)."""
+        spans = [(p, line, end) for p, line, end, _kind in graph.definitions.get(name, [])]
+        if not spans:
+            return set()
+        short = name.split(".")[-1]
+        found: set[str] = set()
+        for ref_name, refs in graph.references.items():
+            for rp, rline, _rkind, rcontext in refs:
+                if rcontext != name and rcontext != short:
+                    continue
+                if any(fp == rp and start <= rline <= end for fp, start, end in spans):
+                    found.add(ref_name)
+        return found
+
+    visited: set[str] = set()
+    frontier: set[str] = {symbol_name}
+    depth_map: dict[str, int] = {}
+    depth = 0
+    while frontier and depth < max_depth:
+        depth += 1
+        nxt: set[str] = set()
+        for name in frontier:
+            if name in visited:
+                continue
+            visited.add(name)
+            depth_map[name] = depth
+            nxt.update(_callers(name))
+            nxt.update(_callees(name))
+        frontier = nxt - visited
+
+    impacted_files: set[str] = set()
+    for name in visited:
+        for p, _line, _end, _kind in graph.definitions.get(name, []):
+            impacted_files.add(str(p))
+
+    return {
+        "success": True,
+        "symbol": symbol_name,
+        "max_depth": max_depth,
+        "impacted_symbols": sorted(visited),
+        "impacted_files": sorted(impacted_files),
+        "counts": {
+            "symbols": len(visited),
+            "files": len(impacted_files),
+            "depth": max(depth_map.values(), default=0),
+        },
+    }
+
+
+def _run_git(root: Path, *args: str) -> subprocess.CompletedProcess[str] | None:
+    try:
+        return subprocess.run(
+            ["git", "-C", str(root), *args],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+
+
+def affected_files(base: str = "HEAD", head: str | None = None, max_depth: int = 4) -> dict:
+    """Find files (especially tests) that may be affected by a git diff.
+
+    ``base`` (default ``HEAD``) is diffed against ``head`` when given, else the
+    working tree. Changed files' defined symbols are traced backwards through
+    the call graph so callers-of-callers up to ``max_depth`` hops are included.
+    """
+    with _state_lock:
+        root = _project_root
+    if root is None:
+        return {"success": False, "error": "Project not indexed. Call index_project first."}
+
+    def _valid_ref(ref: str) -> bool:
+        # A leading dash would be parsed by git as an option (``--output=...``
+        # writes a file); newlines cannot be legitimate refs either.
+        return bool(ref) and not ref.startswith("-") and "\n" not in ref and "\r" not in ref
+
+    if not _valid_ref(base) or (head is not None and not _valid_ref(head)):
+        return {
+            "success": False,
+            "error": f"invalid git ref: {base if not _valid_ref(base) else head}",
+        }
+
+    # ``--relative`` makes paths relative to the project root even when it is a
+    # subdirectory of the git repository; without it the changed paths and the
+    # graph's root-relative paths never matched and the result was silently empty.
+    if head:
+        proc = _run_git(root, "diff", "--relative", "--name-only", base, head)
+    else:
+        proc = _run_git(root, "diff", "--relative", "--name-only", base)
+    if proc is None or proc.returncode != 0:
+        err = (proc.stderr if proc else "git unavailable").strip()
+        return {"success": False, "error": f"git diff failed: {err}"}
+    changed = [line.strip() for line in proc.stdout.splitlines() if line.strip()]
+
+    graph = _get_call_graph(root)
+
+    # Symbols defined in changed files (paths are relative to the repo root).
+    # git always emits forward slashes; normalize Windows paths to match.
+    seeds: set[str] = set()
+    changed_set = {c.replace("\\", "/") for c in changed}
+    for name, locs in graph.definitions.items():
+        for p, _line, _end, _kind in locs:
+            try:
+                rel = str(p.relative_to(root)).replace("\\", "/")
+            except ValueError:
+                rel = str(p)
+            if rel in changed_set:
+                seeds.add(name)
+    if not seeds:
+        return {
+            "success": True,
+            "changed": changed,
+            "affected_files": [],
+            "affected_tests": [],
+            "propagation": 0,
+        }
+
+    # Reverse BFS (bounded by max_depth): who references these symbols,
+    # transitively. Depth counts hops from the seed symbols.
+    visited: set[str] = set()
+    frontier: set[str] = set(seeds)
+    depth = 0
+    while frontier and depth < max_depth:
+        depth += 1
+        nxt: set[str] = set()
+        for name in frontier:
+            if name in visited:
+                continue
+            visited.add(name)
+            short = name.split(".")[-1]
+            for ref_name, refs in graph.references.items():
+                if ref_name != name and ref_name != short:
+                    continue
+                for _p, _line, _kind, context in refs:
+                    if context and context not in visited:
+                        nxt.add(context)
+        frontier = nxt - visited
+        if len(visited) > 5000:  # safety valve for pathological graphs
+            break
+
+    affected: set[str] = set()
+    for name in visited:
+        for p, _line, _end, _kind in graph.definitions.get(name, []):
+            affected.add(str(p))
+
+    affected_tests = sorted(f for f in affected if "test" in f.lower())
+    return {
+        "success": True,
+        "changed": changed,
+        "affected_files": sorted(affected),
+        "affected_tests": affected_tests,
+        "propagation": len(visited) - len(seeds),
+    }
+
+
+def search_code(pattern: str, glob: str = "*.py") -> dict:
+    """Search project source code with a regex pattern."""
+    with _state_lock:
+        root = _project_root
+    if root is None:
+        return {"success": False, "error": "Project not indexed. Call index_project first."}
+
+    try:
+        regex = re.compile(pattern)
+    except re.error as e:
+        return {"success": False, "error": f"Invalid regex: {e}"}
+
+    # FTS5 acceleration: for plain .py searches, shrink the scan to a superset
+    # of candidate files via the full-text index, then run the exact regex only
+    # on those. Results are identical to a full scan, but large repos touch
+    # far fewer files. Falls back to a full scan when FTS5 is unavailable.
+    candidates: list[Path] | None = None
+    if glob == "*.py":
+        try:
+            cache = GraphCache.for_root(root, _cache_dir())
+            if not cache.is_fresh(root):
+                # First search after a change: (re)build the graph + FTS5 index
+                # once, then every later search hits the index.
+                _get_call_graph(root)
+            if cache.is_fresh(root):
+                rel_candidates = cache.search_candidate_files(pattern)
+                if rel_candidates is not None:
+                    if not rel_candidates:
+                        return {
+                            "success": True,
+                            "pattern": pattern,
+                            "matches": [],
+                            "count": 0,
+                            "engine": "fts5",
+                        }
+                    candidates = [root / rel for rel in rel_candidates]
+        except (OSError, sqlite3.Error):
+            candidates = None
+
+    matches: list[dict] = []
+    for p in candidates if candidates is not None else root.rglob(glob):
+        if "__pycache__" in p.parts:
+            continue
+        # read_python_source honours PEP 263 cookies and skips undecodable
+        # files instead of raising; a strict utf-8 read silently dropped every
+        # legally non-UTF-8 file from the search.
+        text = read_python_source(p)
+        if text is None:
+            continue
+        for m in regex.finditer(text):
+            line = text[: m.start()].count("\n") + 1
+            matches.append(
+                {
+                    "file": str(p),
+                    "line": line,
+                    "match": m.group(0)[:200],
+                }
+            )
+
+    return {
+        "success": True,
+        "pattern": pattern,
+        "matches": matches,
+        "count": len(matches),
+        "engine": "fts5" if candidates is not None else "regex",
+    }
+
+
+def choose_tool(query: str) -> dict:
+    """Choose the most appropriate tool for a natural-language query."""
+    choice = HonestRouter.choose_tool(query)
+    return {
+        "success": True,
+        "tool": choice.intent.value,
+        "confidence": round(choice.confidence, 3),
+        "reason": choice.reason,
+    }