flash-context 0.2.0__tar.gz → 0.3.1__tar.gz

flash_context-0.3.1/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+User-visible changes and migration instructions for each release.
+
+## [Unreleased]
+
+## [0.3.1] - 2026-11-01
+
+### Fixed
+
+- Report the flash-context package version during MCP initialization instead of
+  the MCP SDK version.
+- Reuse repeated tool observations without discarding fresh searches in the same
+  batch; execute same-turn duplicates only once and stop all-repeat stalls.
+- Continue implementation searches after documentation-only citations within the
+  existing turn budget. Documentation-only fallbacks retain citations and snippets
+  with explicit incomplete-result metadata and warnings.
+
+### Changed
+
+- Describe deterministic lookup and delegated model search together in the README.
+
+### Migration
+
+- Implementation questions may use additional turns before returning documentation
+  evidence. These fallbacks set `truncated: true`; partial cited CLI results still
+  exit 0. Budgets, configuration keys, and result schemas are unchanged.
+
+## [0.3.0] - 2026-11-01
+
+### Fixed
+
+- Resolve bare file-path queries locally with bounded previews and find unique
+  Python definitions even when many references precede them.
+- Keep literal and scoped searches from scanning unrelated directory trees while
+  preserving safety checks and existing resource limits.
+- Surface scan failures from the initial file sample and CLI result warnings.
+- Describe the MCP exploration tool during discovery and use tool-specific
+  trajectory counters instead of misleading empty read-content counts.
+
+### Migration
+
+- Citation objects no longer include the unused `reason` field. Consumers should
+  read `path`, `start_line`, and `end_line` without expecting `reason: null`.
+- The CLI now exits 6 for empty results after scan-budget exhaustion or a tool
+  processing timeout, retaining text/JSON on stdout and warnings on stderr.
+  Partial cited results and complete empty searches still exit 0.
+- Trajectory tool entries now include only their relevant counter:
+  `content_length` (read), `hit_count` (grep), or `match_count` (glob).
+
+### Changed
+
+- Prompt the explorer to prefer implementation source for coding questions and
+  the smallest supporting citation ranges. Validation checks safe line coverage;
+  precision and relevance remain model-dependent.
+- Publish GitHub releases automatically after PyPI installation verification,
+  using this changelog and the same distribution artifacts uploaded to PyPI.
+- Refresh package-index metadata during release installation retries.
+
+## [0.2.0] - 2026-11-01
+
+### Changed
+
+- Enforce deny/ignore rules on requested and resolved paths, including environment
+  files, private-key names, and runtime histories. Prune denied directories.
+- Bound scan bytes, directory entries, processing time, regex execution, tool
+  batches, and model observations; report incomplete coverage explicitly.
+- Improve exact-lookup routing, read ranges, truncation metadata, and structured
+  endpoint/filesystem failures across CLI and MCP.
+- Keep optional trajectory logs metadata-only and outside the inspected root.
+
+### Migration
+
+- Move any trajectory directory inside the inspected repository outside it, or
+  disable logging with `FLASH_CONTEXT_TRAJ_DIR=`. Empty/null settings disable
+  inherited logging. Existing logs remain untouched.
+
+## [0.1.0] - 2026-11-01
+
+### Added
+
+- Initial Python CLI and optional MCP adapter sharing a read-only explorer core.
+- OpenAI-compatible tool-call loop with bounded Read/Glob/Grep repository tools,
+  root-scoped path validation, validated citations, and raw source snippets.
+- Exact path/symbol lookup shortcuts, concurrent local tools, and configurable
+  endpoint settings and limits.
+- Wheel/source packaging and tag-driven TestPyPI/PyPI publication and smoke checks.

{flash_context-0.2.0 → flash_context-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flash-context
-Version: 0.2.0
+Version: 0.3.1
 Summary: Read-only context exploration and retrieval for AI agents, starting with codebases and repositories.
 Project-URL: Repository, https://github.com/zyf0717/flash-context
 Project-URL: Issues, https://github.com/zyf0717/flash-context/issues
@@ -28,8 +28,9 @@ Description-Content-Type: text/markdown
 [![Python versions](https://img.shields.io/pypi/pyversions/flash-context)](https://pypi.org/project/flash-context/)
 [![License](https://img.shields.io/pypi/l/flash-context)](LICENSE)
 
-Read-only context exploration and retrieval for AI agents,
-available as a Python CLI and Model Context Protocol (MCP) server.
+A lightweight, model-agnostic repository explorer that combines deterministic
+lookup with delegated LLM search to deliver compact, validated source evidence.
+Available as a Python CLI and Model Context Protocol (MCP) server.
 
 Delegate recursive, repetitive file search and reading to a utility model
 behind an OpenAI-compatible endpoint. The calling agent receives validated
@@ -39,10 +40,17 @@ Codebases and repositories are the current focus; the same tools explore
 documentation, configuration, and other local text files. CLI and MCP share one
 exploration core with read-only tools, path safety, and resource limits.
 Scans and regex execution are bounded; partial results report truncation.
+Citation validation checks safe paths and existing line coverage, not semantic
+relevance or minimal ranges. Citation precision depends on the explorer model.
+Implementation queries continue past documentation-only citations within the turn budget; documentation-only
+fallbacks carry incomplete-result metadata and warnings. Build outputs such as
+`dist/` remain excluded; inspect a source checkout for implementation evidence.
 Optional metadata-only trajectory logs must stay outside the inspected repository.
 
 Inspired by [FastContext](https://arxiv.org/abs/2606.14066), a now-withdrawn paper
-on delegating repository exploration to a dedicated model.
+on separating repository exploration from task solving, using specialized models
+to return focused file-line evidence while reducing the coding agent's context
+and token overhead.
 
 ## Quickstart
 
@@ -73,6 +81,14 @@ lookups can resolve locally without an endpoint. See the
 [CLI contract](specs/001-flash-context-explorer/contracts/cli.md) for options,
 output schemas, and exit codes.
 
+For example, `--query 'httpx/_client.py'` returns a bounded file preview, while
+`--query 'BaseTransport'` returns its definition if unique within a complete
+Python source/stub scan. Local successes report `turns_used: 0` in JSON.
+
+Warnings go to stderr in both output formats. An empty result after scan-budget
+exhaustion exits **6** while preserving stdout; a complete empty search exits
+**0**. For large repositories, see [scan-budget tuning](docs/configuration.md#large-repositories).
+
 ## MCP
 
 ```bash
@@ -87,6 +103,7 @@ See [MCP integration](docs/mcp.md) for editor configuration and source launches.
 - [Configuration](docs/configuration.md): endpoint settings, precedence, and limits.
 - [Architecture and scope](docs/architecture.md): design, status, specs, and references.
 - [Contributing](CONTRIBUTING.md): development setup, tests, and pull requests.
+- [Changelog](CHANGELOG.md): release history and migration instructions.
 - [Releasing](docs/releasing.md): package checks and tag-driven TestPyPI/PyPI publishing.
 
 ## License

{flash_context-0.2.0 → flash_context-0.3.1}/README.md

@@ -5,8 +5,9 @@
 [![Python versions](https://img.shields.io/pypi/pyversions/flash-context)](https://pypi.org/project/flash-context/)
 [![License](https://img.shields.io/pypi/l/flash-context)](LICENSE)
 
-Read-only context exploration and retrieval for AI agents,
-available as a Python CLI and Model Context Protocol (MCP) server.
+A lightweight, model-agnostic repository explorer that combines deterministic
+lookup with delegated LLM search to deliver compact, validated source evidence.
+Available as a Python CLI and Model Context Protocol (MCP) server.
 
 Delegate recursive, repetitive file search and reading to a utility model
 behind an OpenAI-compatible endpoint. The calling agent receives validated
@@ -16,10 +17,17 @@ Codebases and repositories are the current focus; the same tools explore
 documentation, configuration, and other local text files. CLI and MCP share one
 exploration core with read-only tools, path safety, and resource limits.
 Scans and regex execution are bounded; partial results report truncation.
+Citation validation checks safe paths and existing line coverage, not semantic
+relevance or minimal ranges. Citation precision depends on the explorer model.
+Implementation queries continue past documentation-only citations within the turn budget; documentation-only
+fallbacks carry incomplete-result metadata and warnings. Build outputs such as
+`dist/` remain excluded; inspect a source checkout for implementation evidence.
 Optional metadata-only trajectory logs must stay outside the inspected repository.
 
 Inspired by [FastContext](https://arxiv.org/abs/2606.14066), a now-withdrawn paper
-on delegating repository exploration to a dedicated model.
+on separating repository exploration from task solving, using specialized models
+to return focused file-line evidence while reducing the coding agent's context
+and token overhead.
 
 ## Quickstart
 
@@ -50,6 +58,14 @@ lookups can resolve locally without an endpoint. See the
 [CLI contract](specs/001-flash-context-explorer/contracts/cli.md) for options,
 output schemas, and exit codes.
 
+For example, `--query 'httpx/_client.py'` returns a bounded file preview, while
+`--query 'BaseTransport'` returns its definition if unique within a complete
+Python source/stub scan. Local successes report `turns_used: 0` in JSON.
+
+Warnings go to stderr in both output formats. An empty result after scan-budget
+exhaustion exits **6** while preserving stdout; a complete empty search exits
+**0**. For large repositories, see [scan-budget tuning](docs/configuration.md#large-repositories).
+
 ## MCP
 
 ```bash
@@ -64,6 +80,7 @@ See [MCP integration](docs/mcp.md) for editor configuration and source launches.
 - [Configuration](docs/configuration.md): endpoint settings, precedence, and limits.
 - [Architecture and scope](docs/architecture.md): design, status, specs, and references.
 - [Contributing](CONTRIBUTING.md): development setup, tests, and pull requests.
+- [Changelog](CHANGELOG.md): release history and migration instructions.
 - [Releasing](docs/releasing.md): package checks and tag-driven TestPyPI/PyPI publishing.
 
 ## License

{flash_context-0.2.0 → flash_context-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flash-context"
-version = "0.2.0"
+version = "0.3.1"
 description = "Read-only context exploration and retrieval for AI agents, starting with codebases and repositories."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -52,6 +52,7 @@ include = [
   "/src/flash_context",
   "/pyproject.toml",
   "/README.md",
+  "/CHANGELOG.md",
   "/LICENSE",
   "/config.yaml.example",
   "/.env.example",
@@ -74,5 +75,5 @@ select = ["E", "F", "I", "UP", "B", "SIM"]
 [tool.mypy]
 python_version = "3.13"
 strict = true
-files = ["src/flash_context", "tests/unit", "tests/contract"]
+files = ["src/flash_context", "tests/unit", "tests/contract", "scripts"]
 exclude = ["tests/fixtures"]

{flash_context-0.2.0 → flash_context-0.3.1}/src/flash_context/agent.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import json
 import re
 from concurrent.futures import ThreadPoolExecutor
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from pathlib import Path
 from typing import Any, Literal, cast
 
@@ -66,7 +66,8 @@ TOKEN_RE = re.compile(r"\b(?P<token>[A-Za-z_][A-Za-z0-9_]*)\b")
 class EvidenceState:
     reads: list[ToolObservation] = field(default_factory=list)
     citations: list[Citation] = field(default_factory=list)
-    seen_tool_calls: set[str] = field(default_factory=set)
+    observations: dict[str, ToolObservation] = field(default_factory=dict)
+    prefer_source: bool = False
 
 
 def explore(
@@ -99,10 +100,11 @@ def explore(
     )
     messages = _initial_messages(request, file_sample, settings)
     tools = tool_schemas()
-    truncated = False
-    warnings: list[str] = []
+    # A capped file sample is expected; actual scan failures must reach callers.
+    warnings = list(file_sample.warnings)
+    truncated = bool(warnings)
     last_content = ""
-    evidence = EvidenceState()
+    evidence = EvidenceState(prefer_source=_implementation_query(request.query))
 
     try:
         for turn in range(1, effective_max_turns + 1):
@@ -144,6 +146,7 @@ def explore(
                 recorder.finish(result=result)
                 return result
             recorder.record_model_turn(turn, message)
+            needs_source = False
             content_text = str(message.get("content") or "").strip()
             if content_text:
                 last_content = content_text
@@ -156,6 +159,12 @@ def explore(
                 )
                 if citations:
                     evidence.citations = citations
+                    needs_source = evidence.prefer_source and _documentation_only(
+                        citations
+                    )
+                if needs_source:
+                    last_content = ""
+                if citations and not needs_source:
                     if _message_has_tool_calls(message):
                         _append_warning_once(
                             warnings,
@@ -177,6 +186,11 @@ def explore(
             tool_calls = _extract_tool_calls(message)
             if not tool_calls:
                 citations = _best_current_citations(evidence)
+                if evidence.prefer_source and _documentation_only(citations):
+                    last_content = ""
+                    messages.append({"role": "assistant", "content": content_text})
+                    messages.append(_source_feedback())
+                    continue
                 if request.citation and content_text != NO_CITATIONS_FOUND:
                     _append_warning_once(
                         warnings,
@@ -186,7 +200,7 @@ def explore(
                     request=request,
                     repo_root=repo_root,
                     settings=settings,
-                    answer=content_text,
+                    answer="" if needs_source else content_text,
                     citations=citations,
                     turns_used=turn,
                     truncated=truncated,
@@ -218,8 +232,12 @@ def explore(
                 recorder.finish(result=result)
                 return result
 
-            repeated_call = _first_repeated_tool_call(evidence, tool_calls)
-            if repeated_call is not None:
+            fresh_calls: dict[str, ToolCall] = {}
+            for tool_call in tool_calls:
+                fingerprint = _tool_call_fingerprint(tool_call)
+                if fingerprint not in evidence.observations:
+                    fresh_calls.setdefault(fingerprint, tool_call)
+            if not fresh_calls:
                 _append_warning_once(
                     warnings,
                     "repeated tool call stopped exploration",
@@ -237,17 +255,18 @@ def explore(
                 )
                 recorder.finish(result=result)
                 return result
-            for tool_call in tool_calls:
-                evidence.seen_tool_calls.add(_tool_call_fingerprint(tool_call))
-
             messages.append(_assistant_tool_message(message))
             observations = _execute_tool_calls_parallel(
-                tool_calls,
+                list(fresh_calls.values()),
                 repo_root=repo_root,
                 settings=settings,
             )
-            for tool_call, observation in zip(tool_calls, observations, strict=True):
-                observation.tool_call_id = tool_call.id
+            evidence.observations.update(zip(fresh_calls, observations, strict=True))
+            for tool_call in tool_calls:
+                observation = replace(
+                    evidence.observations[_tool_call_fingerprint(tool_call)],
+                    tool_call_id=tool_call.id,
+                )
                 payload = _model_observation_payload(
                     observation,
                     max_chars=settings.max_observation_chars,
@@ -261,7 +280,9 @@ def explore(
                     and observation.path
                     and observation.line_range
                 ):
-                    evidence.reads.append(observation)
+                    read = replace(observation, tool_call_id=None)
+                    if read not in evidence.reads:
+                        evidence.reads.append(read)
                 recorder.record_observation(turn, tool_call.name, observation)
                 messages.append(
                     {
@@ -274,6 +295,8 @@ def explore(
                         ),
                     }
                 )
+            if needs_source:
+                messages.append(_source_feedback())
         if last_content:
             citations = _validated_citations_from_content(
                 last_content,
@@ -417,6 +440,13 @@ def _finalize_result(
     warnings: list[str],
 ) -> ExploreResult:
     citations = _merge_adjacent_citations(citations)[:MAX_FINAL_CITATIONS]
+    if _implementation_query(request.query) and _documentation_only(citations):
+        truncated = True
+        answer = _citation_text(citations)
+        _append_warning_once(
+            warnings,
+            "implementation source not verified; returning documentation evidence",
+        )
     if request.citation or (not answer and citations):
         answer = _citation_text(citations)
     raw_locations = _extract_raw_locations(
@@ -436,6 +466,7 @@ def _finalize_result(
             truncated
             or any(x.truncated for x in raw_locations)
             or "citation verification limit reached" in warnings
+            or "read scan budget exhausted" in warnings
         ),
         warnings=warnings,
     )
@@ -448,33 +479,30 @@ def _citation_text(citations: list[Citation]) -> str:
 
 
 def _merge_adjacent_citations(citations: list[Citation]) -> list[Citation]:
-    grouped: dict[str, list[tuple[int, Citation]]] = {}
+    grouped: dict[str, list[Citation]] = {}
     path_order: list[str] = []
     non_mergeable: list[Citation] = []
-    for index, citation in enumerate(citations):
+    for citation in citations:
         if citation.start_line is None or citation.end_line is None:
             non_mergeable.append(citation)
             continue
         if citation.path not in grouped:
             grouped[citation.path] = []
             path_order.append(citation.path)
-        grouped[citation.path].append((index, citation))
+        grouped[citation.path].append(citation)
 
     merged: list[Citation] = []
     for path in path_order:
         ranges = sorted(
             grouped[path],
             key=lambda item: (
-                item[1].start_line or 0,
-                item[1].end_line or 0,
+                item.start_line or 0,
+                item.end_line or 0,
             ),
         )
         current_start: int | None = None
         current_end: int | None = None
-        current_reason: str | None = None
-        current_reason_index: int | None = None
-
-        for index, citation in ranges:
+        for citation in ranges:
             start = citation.start_line
             end = citation.end_line
             if start is None or end is None:
@@ -482,27 +510,18 @@ def _merge_adjacent_citations(citations: list[Citation]) -> list[Citation]:
             if current_start is None or current_end is None:
                 current_start = start
                 current_end = end
-                current_reason = citation.reason
-                current_reason_index = index if citation.reason else None
                 continue
 
             if start <= current_end + 1:
                 current_end = max(current_end, end)
-                if citation.reason and (
-                    current_reason_index is None or index < current_reason_index
-                ):
-                    current_reason = citation.reason
-                    current_reason_index = index
                 continue
 
-            merged.append(Citation(path, current_start, current_end, current_reason))
+            merged.append(Citation(path, current_start, current_end))
             current_start = start
             current_end = end
-            current_reason = citation.reason
-            current_reason_index = index if citation.reason else None
 
         if current_start is not None and current_end is not None:
-            merged.append(Citation(path, current_start, current_end, current_reason))
+            merged.append(Citation(path, current_start, current_end))
 
     merged.extend(non_mergeable)
     return merged
@@ -562,6 +581,33 @@ def _try_exact_fast_path(
     repo_root: Path,
     settings: Settings,
 ) -> ExploreResult | None:
+    bare_path = request.query.strip()
+    if len(bare_path) >= 2 and bare_path[0] in "`'\"" and bare_path[-1] == bare_path[0]:
+        bare_path = bare_path[1:-1]
+    if re.fullmatch(r"(?:[A-Za-z0-9_.-]+/)*[A-Za-z0-9_.-]+", bare_path):
+        try:
+            observation = read_file(
+                repo_root=repo_root,
+                path=bare_path,
+                end_line=settings.max_read_lines,
+                max_bytes=settings.max_read_bytes,
+                preview=True,
+                ignore=settings.ignore,
+                limits=settings.limits,
+            )
+        except ExplorerError:
+            pass  # Missing, empty, or unsafe paths retain normal model routing.
+        else:
+            return _finalize_result(
+                request=request,
+                repo_root=repo_root,
+                settings=settings,
+                answer="",
+                citations=_citations_from_reads([observation]),
+                turns_used=0,
+                truncated=observation.truncated,
+                warnings=list(observation.warnings),
+            )
     if not _is_exact_lookup(request.query):
         return None
     evidence = EvidenceState()
@@ -748,7 +794,6 @@ def _exact_matches_in_file(
         grep_result,
         target=target,
         allow_assignment=allow_assignment,
-        definitions_only=False,
     )
     return citations if 0 < len(citations) <= MAX_FINAL_CITATIONS else []
 
@@ -759,32 +804,28 @@ def _unique_definition_citation(
     settings: Settings,
     symbol: str,
 ) -> Citation | None:
-    grep_result = _grep_exact_target(
+    definition_pattern = rf"^\s*(?:async\s+def|def|class)\s+{re.escape(symbol)}\b"
+    grep_result = repo_grep(
         repo_root=repo_root,
-        settings=settings,
-        target=symbol,
+        pattern=definition_pattern,
         glob="**/*.py",
+        max_results=2,
+        ignore=settings.ignore,
+        limits=settings.limits,
     )
-    pyi_result = _grep_exact_target(
+    pyi_result = repo_grep(
         repo_root=repo_root,
-        settings=settings,
-        target=symbol,
+        pattern=definition_pattern,
         glob="**/*.pyi",
+        max_results=2,
+        ignore=settings.ignore,
+        limits=settings.limits,
     )
-    citations = _citations_for_target_hits(
-        grep_result,
-        target=symbol,
-        allow_assignment=False,
-        definitions_only=True,
-    )
-    citations.extend(
-        _citations_for_target_hits(
-            pyi_result,
-            target=symbol,
-            allow_assignment=False,
-            definitions_only=True,
-        )
-    )
+    citations = [
+        Citation(hit.path, hit.line, hit.line)
+        for result in (grep_result, pyi_result)
+        for hit in result.hits
+    ]
     if grep_result.truncated or pyi_result.truncated or len(citations) > 1:
         return None
     return citations[0] if len(citations) == 1 else None
@@ -812,7 +853,6 @@ def _citations_for_target_hits(
     *,
     target: str,
     allow_assignment: bool,
-    definitions_only: bool,
 ) -> list[Citation]:
     citations: list[Citation] = []
     for hit in observation.hits:
@@ -820,7 +860,6 @@ def _citations_for_target_hits(
             hit.text,
             target=target,
             allow_assignment=allow_assignment,
-            definitions_only=definitions_only,
         ):
             citations.append(Citation(hit.path, hit.line, hit.line))
     return citations
@@ -831,14 +870,11 @@ def _line_matches_target(
     *,
     target: str,
     allow_assignment: bool,
-    definitions_only: bool,
 ) -> bool:
     escaped = re.escape(target)
     definition_pattern = rf"^\s*(?:async\s+def|def|class)\s+{escaped}\b"
     if re.search(definition_pattern, line):
         return True
-    if definitions_only:
-        return False
     if allow_assignment and re.search(rf"^\s*{escaped}\s*(?::|=)", line):
         return True
     return bool(re.search(rf"\b{escaped}\b", line))
@@ -862,6 +898,7 @@ def _validated_citations_from_content(
         repo_root=repo_root,
         settings=settings,
         evidence=evidence,
+        warnings=warnings,
     )
     if not validated:
         _append_warning_once(warnings, "invalid citation rejected")
@@ -874,6 +911,7 @@ def _validate_citations(
     repo_root: Path,
     settings: Settings,
     evidence: EvidenceState,
+    warnings: list[str],
 ) -> list[Citation]:
     validated: list[Citation] = []
     for citation in citations[:16]:
@@ -888,6 +926,7 @@ def _validate_citations(
             repo_root=repo_root,
             settings=settings,
             evidence=evidence,
+            warnings=warnings,
         )
         if verified is not None:
             validated.append(verified)
@@ -909,7 +948,6 @@ def _normalize_citation(citation: Citation) -> Citation | None:
         path=citation.path,
         start_line=citation.start_line,
         end_line=citation.end_line,
-        reason=citation.reason,
     )
 
 
@@ -961,6 +999,7 @@ def _verify_citation_by_read(
     repo_root: Path,
     settings: Settings,
     evidence: EvidenceState,
+    warnings: list[str],
 ) -> Citation | None:
     if citation.start_line is None or citation.end_line is None:
         return None
@@ -974,13 +1013,16 @@ def _verify_citation_by_read(
             ignore=settings.ignore,
             limits=settings.limits,
         )
-    except ExplorerError:
+    except ExplorerError as exc:
+        if exc.code == "TOOL_LIMIT_EXCEEDED":
+            _append_warning_once(warnings, "read scan budget exhausted")
         return None
+    for warning in observation.warnings:
+        _append_warning_once(warnings, warning)
     verified = Citation(
         path=observation.path or citation.path,
         start_line=citation.start_line,
         end_line=citation.end_line,
-        reason=citation.reason,
     )
     if verified.path != citation.path:
         return None
@@ -1003,6 +1045,19 @@ def _dedupe_citations(citations: list[Citation]) -> list[Citation]:
 
 
 def _best_current_citations(evidence: EvidenceState) -> list[Citation]:
+    if evidence.prefer_source:
+        source_reads = [
+            read for read in evidence.reads if not _documentation_path(read.path or "")
+        ]
+        source_citations = [
+            citation
+            for citation in evidence.citations
+            if not _documentation_path(citation.path)
+        ]
+        if source_citations or source_reads:
+            return source_citations[:MAX_FINAL_CITATIONS] or _citations_from_reads(
+                source_reads
+            )
     if evidence.citations:
         return evidence.citations[:MAX_FINAL_CITATIONS]
     return _citations_from_reads(evidence.reads)
@@ -1107,17 +1162,44 @@ def _tool_call_fingerprint(tool_call: ToolCall) -> str:
     )
 
 
-def _first_repeated_tool_call(
-    evidence: EvidenceState,
-    tool_calls: list[ToolCall],
-) -> ToolCall | None:
-    batch_fingerprints: set[str] = set()
-    for tool_call in tool_calls:
-        fingerprint = _tool_call_fingerprint(tool_call)
-        if fingerprint in evidence.seen_tool_calls or fingerprint in batch_fingerprints:
-            return tool_call
-        batch_fingerprints.add(fingerprint)
-    return None
+def _implementation_query(query: str) -> bool:
+    if _is_exact_lookup(query) or re.search(
+        r"\b(?:docs?|documentation|markdown|readme)\b", query, re.IGNORECASE
+    ):
+        return False
+    return bool(
+        re.search(
+            r"\b(?:implement\w*|handl\w*|code|functions?|methods?|classes|class)\b",
+            query,
+            re.IGNORECASE,
+        )
+    )
+
+
+def _documentation_path(path: str) -> bool:
+    name = Path(path).name.lower()
+    return Path(name).suffix in {".md", ".mdx", ".rst", ".txt", ".adoc"} or name in {
+        "readme",
+        "changelog",
+        "contributing",
+        "license",
+        "authors",
+    }
+
+
+def _documentation_only(citations: list[Citation]) -> bool:
+    return bool(citations) and all(_documentation_path(c.path) for c in citations)
+
+
+def _source_feedback() -> dict[str, str]:
+    return {
+        "role": "user",
+        "content": (
+            "These citations only establish documentation evidence. Continue searching "
+            "for implementation source using fresh, focused read-only tool calls. "
+            "Do not repeat previous calls or bypass denied paths."
+        ),
+    }
 
 
 def _message_has_tool_calls(message: dict[str, Any]) -> bool:
@@ -1232,6 +1314,11 @@ def _initial_messages(
                 "tool calls in the same turn. "
                 "For exact symbol, function, or class names, use repo_grep "
                 "before reading broad file ranges. "
+                "For implementation questions, prefer implementation source over "
+                "documentation or Markdown; use documentation when requested or "
+                "needed to support the answer. Cite the smallest line ranges "
+                "that support the answer, rather than whole files or classes "
+                "when a smaller function or region suffices. "
                 f"Use read_file line ranges of at most {settings.max_read_lines} "
                 "lines unless no narrower range is known. "
                 f"{output_contract}"
@@ -1464,7 +1551,11 @@ def _execute_tool_call(
                 limits=settings.limits,
             )
     except ExplorerError as exc:
-        return ToolObservation.from_error(exc, tool_call_id=tool_call.id)
+        observation = ToolObservation.from_error(exc, tool_call_id=tool_call.id)
+        if exc.code == "TOOL_LIMIT_EXCEEDED":
+            observation.truncated = True
+            observation.warnings.append("read scan budget exhausted")
+        return observation
     raise AssertionError(f"unhandled tool: {tool_call.name}")
 
 

{flash_context-0.2.0 → flash_context-0.3.1}/src/flash_context/cli.py

@@ -11,6 +11,15 @@ from flash_context.config import SettingsOverrides, load_settings
 from flash_context.mcp_server import run_mcp
 from flash_context.types import ExploreRequest, ExplorerError
 
+_SCAN_LIMIT_WARNINGS = frozenset(
+    {
+        "glob scan budget exhausted",
+        "grep scan budget exhausted",
+        "read scan budget exhausted",
+        "grep match timed out",
+    }
+)
+
 
 def main(argv: Sequence[str] | None = None) -> int:
     parser = _build_parser()
@@ -60,6 +69,12 @@ def _run_explore(args: argparse.Namespace) -> int:
         print(json.dumps(result.to_dict(), indent=2, sort_keys=True))
     else:
         print(format_text_result(result, citation=args.citation))
+    for warning in result.warnings:
+        print(f"WARNING: {warning}", file=sys.stderr)
+    if result.truncated and not result.warnings:
+        print("WARNING: Result truncated", file=sys.stderr)
+    if not result.citations and _SCAN_LIMIT_WARNINGS.intersection(result.warnings):
+        return 6
     return 0
 
 

{flash_context-0.2.0 → flash_context-0.3.1}/src/flash_context/logging.py

@@ -50,16 +50,19 @@ class TrajectoryRecorder:
         self, turn: int, tool_name: str, observation: ToolObservation
     ) -> None:
         if self._traj_dir is not None:
-            self._turns.append(
-                {
-                    "turn": turn,
-                    "tool": tool_name,
-                    "ok": observation.ok,
-                    "truncated": observation.truncated,
-                    "hit_count": len(observation.hits),
-                    "content_length": len(observation.content or ""),
-                }
-            )
+            metadata: dict[str, object] = {
+                "turn": turn,
+                "tool": tool_name,
+                "ok": observation.ok,
+                "truncated": observation.truncated,
+            }
+            if tool_name == "read_file":
+                metadata["content_length"] = len(observation.content or "")
+            elif tool_name == "repo_grep":
+                metadata["hit_count"] = len(observation.hits)
+            elif tool_name == "repo_glob":
+                metadata["match_count"] = len(observation.matches)
+            self._turns.append(metadata)
 
     def finish(
         self, *, result: ExploreResult | None = None, error: ExplorerError | None = None

{flash_context-0.2.0 → flash_context-0.3.1}/src/flash_context/mcp_server.py

@@ -6,6 +6,7 @@ from importlib import import_module
 from pathlib import Path
 from typing import Any
 
+from flash_context import __version__
 from flash_context.agent import explore
 from flash_context.config import Settings, SettingsOverrides, load_settings
 from flash_context.types import ExploreRequest, ExplorerError, ExploreResult
@@ -52,6 +53,8 @@ def create_server() -> Any:
         ) from exc
     fast_mcp = fastmcp_module.FastMCP
     server = fast_mcp("flash-context")
+    # FastMCP exposes no version argument; the low-level default is the SDK version.
+    server._mcp_server.version = __version__
 
     @server.tool()  # type: ignore[untyped-decorator]
     def explore_repository(
@@ -60,6 +63,13 @@ def create_server() -> Any:
         max_turns: int | None = None,
         citation: bool | None = None,
     ) -> dict[str, object]:
+        """Find code or local text relevant to a focused repository question.
+
+        Explore read-only when implementation locations or supporting evidence
+        are unknown. Return validated file-line citations and bounded source
+        snippets, with warnings for incomplete exploration. repo_root defaults
+        to the server's working directory.
+        """
         return explore_repository_handler(
             query=query,
             repo_root=repo_root,

{flash_context-0.2.0 → flash_context-0.3.1}/src/flash_context/tools/safety.py

@@ -173,7 +173,31 @@ class PathSafety:
             except OSError:
                 budget.warnings.append("search skipped an unreadable directory")
 
-        yield from walk(self.repo_root)
+        directory = self.repo_root
+        parts = Path(pattern).parts
+        try:
+            for index, part in enumerate(parts):
+                if any(char in part for char in "*?["):
+                    break
+                candidate = directory / part
+                budget.consume(entries=1)
+                self.ensure_allowed(candidate)
+                if index == len(parts) - 1:
+                    if candidate.exists() and not candidate.is_dir():
+                        yield self.resolve_existing_file(candidate)
+                    return
+                # Match the walker's policy: never traverse directory symlinks.
+                if candidate.is_symlink() or not candidate.is_dir():
+                    return
+                directory = candidate
+            yield from walk(directory)
+        except ExplorerError as exc:
+            if exc.code == "TOOL_LIMIT_EXCEEDED":
+                raise
+            if exc.code not in {"PATH_DENIED", "PATH_OUTSIDE_ROOT"}:
+                budget.warnings.append("search skipped an unreadable entry")
+        except OSError:
+            budget.warnings.append("search skipped an unreadable directory")
 
 
 def _matches_patterns(rel_path: str, patterns: tuple[str, ...]) -> bool:

{flash_context-0.2.0 → flash_context-0.3.1}/src/flash_context/types.py

@@ -49,14 +49,12 @@ class Citation:
     path: str
     start_line: int | None = None
     end_line: int | None = None
-    reason: str | None = None
 
     def to_dict(self) -> dict[str, object]:
         return {
             "path": self.path,
             "start_line": self.start_line,
             "end_line": self.end_line,
-            "reason": self.reason,
         }
 
     def label(self) -> str: