Detects context drift between the AI's loaded snapshot and the current codebase.

    Two detection modes:
    - **Hash-based** (preferred): Pass ``file_hashes`` as ``{file_path: sha256_hash}``.
      V.I.S.O.R. compares the provided hashes against the indexed ``file_hash`` column.
      If they differ, the file has changed since the agent last read it.
    - **Timestamp-based** (fallback): Compares ``loaded_at`` against ``file_changelog``
      entries when hashes are not supplied.

    Args:
        context_files: List of file paths the agent currently holds in context.
        loaded_at:     ISO-8601 timestamp of when the agent loaded its context.
        file_hashes:   Optional dict mapping file_path → sha256 hash the agent last saw.
    

    Directly controls the V.I.S.O.R Developer HUD to visually highlight specific files you are actively reasoning about.
    Use this tool sequentially as you investigate the codebase to give the developer real-time 3D visual feedback of your attention and intent.
    Pass an empty list for file_paths to clear the active focus.

    Args:
        file_paths: List of absolute or relative paths to files you want to highlight on the graph.
        intent: A concise 2-4 word description of what you are doing (e.g. "Reviewing Auth Flow", "Checking Schema").
    

    Returns all indexed AST nodes matching a symbol name, including file path,
    node type (class/function/import), and precise line range.

    Useful for answering: *"Where is `VectorDBClient` defined and what does it do?"*

    Args:
        symbol: The exact or partial name of the class, function, or import to look up.
    

    Traverses the import edges graph from the file containing ``symbol``
    and returns the full transitive dependency chain (max depth 5).

    Useful for answering: *"What does `auth.py` ultimately depend on?"*

    Args:
        symbol: Name of a class or function. Its source file becomes the
                root of the BFS traversal.
    

    **Context Intelligence Engine** — the most powerful V.I.S.O.R. tool.

    Builds a ranked, token-budget-enforced context payload from a natural
    language query. Combines four signals:
    - Embedding similarity (semantic proximity)
    - Exact symbol name match
    - Co-location in the same file as the top hit
    - Dependency graph distance

    Returns a scored list of code nodes ready to be injected into an LLM
    prompt, capped at 8,000 tokens to prevent context overflow.

    Example:
        ``build_context("how is authentication handled")``