An agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.
Rust
docs: add GJC tool semantics analysis for Batch 1 (read/edit/search/find)
clawdbot1e55fb11bc86
diff --git a/docs/gjc-compat/tool-semantics-phase1.md b/docs/gjc-compat/tool-semantics-phase1.mdnew file mode 100644index 00000000..4f4d03cf--- /dev/null+++ b/docs/gjc-compat/tool-semantics-phase1.md@@ -0,0 +1,337 @@+# GJC Tool Semantics Alignment: Phase 1 (read/edit/search/find)++**Status**: Implementation plan+**Issue**: #3323+**Scope**: Slice 2.1 - Tool catalog semantic parity for read/edit/search/find+**Target**: Ship in batches with focused PRs++---++## 1. EXECUTIVE SUMMARY++This document details the semantic gaps between claw-code's current tool implementations and GJC's (gajae-code) reference implementations for the highest-value tools: **read**, **edit**, **search**, and **find**.++### Key Gaps++| Tool | Current (claw-code) | Target (GJC) | Gap | Complexity |+|------|-----|--------|-----|------------|+| **read** | offset/limit pagination | Line selectors (`:L-L+N`), raw mode, truncation footers | High | Medium |+| **write** | Simple file replacement | Full replacement semantics (matching GJC) | Low | Low |+| **edit** | String replacement (old→new) | String replacement with rich patch output | Low | Low |+| **find** (glob) | Pattern expansion only | Recursive glob with filtering | Low | Low |+| **search** (grep) | Regex search with context | Regex with context + advanced filtering | Low | Low |++---++## 2. GJC TOOL SEMANTICS REFERENCE++### 2.1 READ Tool++**Source**: `gajae-code/packages/coding-agent/src/tools/read.ts` (3,500+ LOC)++#### Input Schema+```typescript+{+ path: string; // File path (relative or absolute)+ offset?: number; // Line offset (for pagination)+ limit?: number; // Lines to read (for pagination)+ // GJC extensions (missing in claw-code):+ selector?: string; // Line range syntax:+ // ":50" = line 50 onward+ // ":50-200" = lines 50-200 inclusive+ // ":50+150" = 150 lines starting at line 50+ // ":raw" = full file verbatim+ // ":conflicts" = git merge conflicts only+ truncationDirection?: "head" | "tail" | "both"; // Which end to keep+ maxSummaryBytes?: number; // Summary budget (default 50KB)+ maxSummaryLines?: number; // Summary budget (default 20K lines)+}+```++#### Output Structure+```json+{+ "file": {+ "path": "src/main.rs",+ "content": "...",+ "totalLines": 500,+ "totalBytes": 12345,+ "truncatedBy": "lines" | "bytes" | "middle" | null,+ "displayMode": "summarized" | "raw" | "receipt"+ },+ "truncationFooter": "[Showing lines 1-50 of 500; re-read ...]"+}+```++#### Key Behaviors++1. **Line Range Selectors** (`:selector` syntax)+ - `:50` = start at line 50+ - `:50-200` = lines 50-200 inclusive+ - `:50+150` = 150 lines starting at 50+ - `:50+1` = exactly one line+ - `:5-16,960-973` = multiple ranges+ - `:raw` = full verbatim+ - `:conflicts` = git merge conflicts++2. **Truncation Modes**+ - Default: 50KB bytes limit, 20K lines limit+ - Direction: `head` (keep start), `tail` (keep end), `both` (keep both ends)+ - Footer includes recovery hint (e.g., "`re-read path:1-9999` for verbatim")++3. **Structural Summarization**+ - Code: collapse function bodies to `..` or `…` (merged brace pairs)+ - Prose: preserve full lines, truncate at word boundaries+ - Special files: documents (PDF, DOCX, XLSX) converted via markit++4. **Archive Support**+ - `.tar`, `.tar.gz`, `.tgz`, `.zip`: member read with `archive.ext:path/inside`+ - SQLite: `.sqlite:table` or `.sqlite:table:key` queries+ - Line ranges apply to archive members++5. **Output Formatting**+ - Anchored output: Line prefixes with source line numbers and hash anchors+ - Optional hash lines: Marks structural boundaries (`# pragma`, function start, etc.)+ - Prose column cap: Long lines wrapped/truncated at column limit++### 2.2 EDIT Tool++**Source**: `gajae-code/packages/coding-agent/src/tools/edit.ts`++#### Input Schema+```typescript+{+ path: string; // File to edit+ old_text: string; // Text to replace (required for edit)+ new_text: string; // Replacement text+ all?: boolean; // Replace all occurrences (default: first only)+}+```++#### Output Structure+```json+{+ "file": {+ "path": "src/main.rs",+ "editCount": 1,+ "beforeSize": 12345,+ "afterSize": 12400+ },+ "patch": [+ {+ "type": "replace",+ "lineStart": 50,+ "lineEnd": 55,+ "before": "old content",+ "after": "new content",+ "context": {"before": 3, "after": 3}+ }+ ]+}+```++#### Key Behaviors++1. **Exact Match Required**: `old_text` must match exactly (no fuzzy matching)+2. **Smallest Replacement**: Use smallest unique old_text that identifies the change+3. **All-or-Nothing**: Either all occurrences replaced or none (no partial)+4. **Patch Metadata**: Line numbers, context, before/after preserved++### 2.3 SEARCH Tool++**Source**: `gajae-code/packages/coding-agent/src/tools/search.ts`++#### Input Schema+```typescript+{+ pattern: string; // Regex pattern+ paths?: string[]; // Files/dirs to search+ context?: number; // Context lines before/after (default: 2)+ i?: boolean; // Case-insensitive+ glob_exclude?: string[]; // Patterns to skip+ file_type?: string; // Filter by extension+ limit?: number; // Max results+ truncation?: "head" | "tail" | "both";+}+```++#### Output Structure+```json+{+ "matches": [+ {+ "file": "src/main.rs",+ "lineNumber": 42,+ "line": "fn process() {",+ "before": ["// Process data", ""],+ "after": [" // Implementation", ""]+ }+ ],+ "summary": "Found 5 matches in 3 files"+}+```++### 2.4 FIND Tool++**Source**: `gajae-code/packages/coding-agent/src/tools/find.ts`++#### Input Schema+```typescript+{+ paths: string[]; // Glob patterns+ timeout?: number; // Timeout in seconds (default: 5)+ gitignore?: boolean; // Respect .gitignore (default: true)+ hidden?: boolean; // Include hidden files (default: true)+ limit?: number; // Max results (default: 1000)+}+```++#### Output Structure+```json+{+ "files": [+ {+ "path": "src/main.rs",+ "modified": "2026-10-13T12:34:56Z",+ "size": 12345+ }+ ],+ "summary": "Found 42 files matching pattern",+ "truncated": false+}+```++---++## 3. CURRENT CLAW-CODE IMPLEMENTATION GAPS++### 3.1 READ Tool Gaps++**File**: `rust/crates/runtime/src/file_ops.rs:713`++**Current**:+```rust+pub fn read_file_in_workspace(+ path: &str,+ offset: Option<usize>, // Line offset only+ limit: Option<usize>, // Lines only+ workspace_root: &Path,+) -> io::Result<ReadFileOutput>+```++**Missing**:+- ✗ Line range selectors (`:L-L+N` syntax)+- ✗ Raw mode (`:raw`)+- ✗ Git merge conflict extraction (`:conflicts`)+- ✗ Truncation footers with recovery hints+- ✗ Structural summarization (collapse braces)+- ✗ Archive/SQLite support+- ✗ Multi-range selectors (`:5-16,960-973`)+- ✗ Prose column cap+- ✗ Hash line anchors++**Estimated LOC to Add**: 1,200-1,500 (including tests)++### 3.2 EDIT Tool Gaps++**File**: `rust/crates/runtime/src/file_ops.rs:760`++**Current**: Basic string replacement works+**Missing**:+- ✗ Rich patch metadata (line numbers, context lines)++**Estimated LOC to Add**: 200-300++### 3.3 SEARCH Tool Gaps++**File**: `rust/crates/tools/src/lib.rs` (grep search)++**Current**: Basic regex with context+**Missing**:+- ✗ Advanced filtering (file type, glob exclude)+- ✗ Structured output format++**Estimated LOC to Add**: 300-400++### 3.4 FIND Tool Gaps++**File**: `rust/crates/tools/src/lib.rs` (glob search)++**Current**: Basic glob expansion+**Missing**:+- ✗ Recursive globs+- ✗ Gitignore filtering+- ✗ Hidden file control+- ✗ File metadata++**Estimated LOC to Add**: 200-300++---++## 4. IMPLEMENTATION PLAN (BATCHED)++### Batch 1: READ Tool (Priority P0)+- Add line range selector parsing+- Implement `:raw` and `:conflicts` modes+- Add truncation footers with recovery hints+- Implement structural summarization+- Add tests for all selector combinations++**Files to Modify**:+- `rust/crates/runtime/src/file_ops.rs` (read_file_in_workspace)+- `rust/crates/tools/src/lib.rs` (ReadFileInput struct)+- Tests in both++**Size Estimate**: 1,200 LOC+**Complexity**: Medium (string parsing, output formatting)++### Batch 2: EDIT Tool (Priority P1)+- Add patch metadata to output+- Ensure exact match semantics+- Add comprehensive tests++**Files to Modify**:+- `rust/crates/runtime/src/file_ops.rs` (edit_file_in_workspace)+- Tests++**Size Estimate**: 200 LOC+**Complexity**: Low++### Batch 3: SEARCH/FIND Tools (Priority P1)+- Enhance grep/find with GJC-compatible filtering+- Add structured output format+- Add metadata (file type, modified time)++**Files to Modify**:+- `rust/crates/tools/src/lib.rs` (glob_search, grep_search)+- `rust/crates/runtime/src/file_ops.rs`++**Size Estimate**: 500 LOC+**Complexity**: Low-Medium++---++## 5. VERIFICATION STRATEGY++Each batch will include:+1. **Semantic Tests**: Verify tool inputs/outputs match GJC reference+2. **Edge Case Tests**: Line ranges, truncation, archives, etc.+3. **Integration Tests**: End-to-end with claw CLI+4. **Parity Shadow Test**: Run same inputs against both GJC and claw-code, compare outputs++---++## 6. ROLLOUT SCHEDULE++- **Batch 1 (READ)**: Week 1 - Enable most impactful tool first+- **Batch 2 (EDIT)**: Week 1-2 - Quick follow-up+- **Batch 3 (SEARCH/FIND)**: Week 2 - Lower priority but valuable for discoverability++---++## 7. REFERENCES++- GJC Read Tool: `/home/bellman/Workspace/gajae-code/packages/coding-agent/src/tools/read.ts`+- claw-code file_ops: `rust/crates/runtime/src/file_ops.rs`+- claw-code tools: `rust/crates/tools/src/lib.rs`+- Gap Matrix: `docs/gjc-compat/gap-matrix.md`