feat(tools): add context-efficient repository operations (#46)

* feat(tools): add context-efficient repository operations

* test(mcp): remove process-group teardown race

* chore(release): prepare 6.5.0

* docs: document repository-context tool modes

---------

Co-authored-by: Claude <claude@anthropic.com>

Author: ZhiXiao-Lin

CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.5.0] - 2026-07-28
+
+### Added
+
+- Added budget-bounded `read.files` calls for 1-32 text files with ordered
+  per-file results, isolated member failures, and lossless continuation
+  arguments that are included in the response budget.
+- Added `grep` output modes for content, paginated matching paths, paginated
+  per-file matching-line counts, and full-scan summaries without rendering
+  discarded match text.
+- Added read-only `edit` dry runs plus exact and maximum replacement-count
+  guards so mechanical edits can be previewed and bounded before CAS writes.
+
+### Changed
+
+- Added explicit `glob` ordering: `sort: "path"` provides deterministic lexical
+  order before cursor pagination, while the compatible `sort: "backend"`
+  default retains backend relevance or recency order.
+- Added explicit README attribution for the FastCtx repository-tool ergonomics
+  that informed these context-efficiency improvements.
+
 ## [6.4.3] - 2026-07-25
 
 ### Fixed

Cargo.lock

@@ -207,7 +207,7 @@ the model.
 
 | Concern | Built-in surface |
 | --- | --- |
-| Files and directories | `read`, `write`, `edit`, `patch`, `ls`, `glob`, `grep` with ranged or resumable operations and compare-and-swap mutation |
+| Files and directories | Budgeted single/multi-file `read`, `write`, previewable CAS `edit`, `patch`, `ls`, order-selectable paginated `glob`, and mode-selectable `grep` |
 | Commands and source control | Bounded `bash` plus typed `git` operations, cancellation, and Unix process-group termination |
 | Code intelligence | `code_symbols`, `code_navigation`, and `code_diagnostics`; source reading and mutation remain in file tools |
 | Web evidence | Multi-engine `web_search` and bounded `web_fetch` with structured failures, fallback, source normalization, and SSRF protections |
@@ -219,6 +219,51 @@ idempotent, resumable, cancellation-safe, paginated, output-kind, and parallel
 limits. `batch` parallelizes only calls that declare safe read-only behavior;
 mutations and unknown tools are serialized.
 
+### Context-efficient repository tools
+
+`read` can pack 1-32 known text files into one ordered response. The shared
+budget includes headers and the continuation itself, so the result reaches the
+model intact instead of relying on downstream truncation:
+
+```json
+{
+  "files": [
+    { "path": "src/lib.rs" },
+    { "path": "src/config.rs", "offset": 40, "limit": 80 }
+  ],
+  "max_output_bytes": 65536
+}
+```
+
+If the budget fills, copy `metadata.batch.continuation` back into `files`.
+Offsets and remaining per-file limits are advanced without repeating completed
+lines. One missing or unreadable member is reported in its own segment while
+the other files continue.
+
+`grep.output_mode` controls how much evidence enters the context:
+
+| Mode | Result |
+| --- | --- |
+| `content` | Matching lines with optional context (default) |
+| `files_with_matches` | Lexically cursor-paginated matching paths only |
+| `count` | Lexically cursor-paginated matching-line counts per file |
+| `summary` | Full-scan line and file totals without rendered matches |
+
+The non-content modes ask built-in workspace backends to count matches without
+constructing discarded match text. `glob` retains a backend's recency or
+relevance order by default; request `sort: "path"` when cursor pages require
+stable lexical ordering.
+
+Use `edit` with `dry_run: true` to receive the exact before/after diff without
+writing. The dry run is declared read-only and can be safely batched. Apply the
+result with `expected_replacements` and optionally `max_replacements` to reject
+stale or unexpectedly broad changes before the compare-and-swap write.
+
+These repository-context ergonomics were informed by
+[FastCtx](https://github.com/yc-duan/fastctx). Their implementation here stays
+inside A3S Code's workspace abstractions, capability declarations, permission
+path, remote-backend contracts, and structured metadata.
+
 ### Sandbox and credential boundaries
 
 Hosts can attach a `BashSandbox`. The fail-closed local `SrtBashSandbox` limits

README.md

@@ -1,6 +1,6 @@
 [package]
 name = "a3s-code-core"
-version = "6.4.3"
+version = "6.5.0"
 edition = "2021"
 authors = ["A3S Lab Team"]
 license = "MIT"

core/Cargo.toml

@@ -445,7 +445,7 @@ mod tests {
     ) -> StdioTransport {
         let args = vec![
             "-c".to_string(),
-            "touch \"$1\"; (sleep 0.30; touch \"$2\") & wait".to_string(),
+            "(sleep 0.30; : > \"$2\") & : > \"$1\"; wait".to_string(),
             "mcp-process-tree-test".to_string(),
             started.to_string_lossy().into_owned(),
             leaked.to_string_lossy().into_owned(),