docs: Add REFERENCE.md - architectural study documentation

REFERENCE.md

@@ -0,0 +1,95 @@
+# 🎯 Claw Code - Reference Implementation
+
+> **Clean-room Claude Code harness - mirrored for architectural study**
+
+---
+
+## ⚠️ IMPORTANT: Reference Only
+
+This repository is a **mirror** of [instructkr/claw-code](https://github.com/instructkr/claw-code) for:
+- ✅ Studying agent harness engineering patterns
+- ✅ Comparing tool system architectures  
+- ✅ Learning clean-room implementation approaches
+
+**Do NOT copy code directly.** Study patterns, then implement independently.
+
+---
+
+## 📊 Stats
+
+| Metric | Value |
+|--------|-------|
+| **Python** | 2,138 LOC, 66 files |
+| **Rust** | 7,619 LOC, 28+ files |
+| **Total** | ~10K LOC |
+| **Author** | Sigrid Jin (@instructkr) |
+| **Origin** | WSJ-featured clean-room rewrite |
+
+---
+
+## 🏗️ Architecture
+
+### Python (`src/`)
+```
+runtime.py          → Agent runtime with routing
+├── tools.py        → Tool harness (Bash, File, MCP)
+├── commands.py     → Command system
+├── query_engine.py → LLM orchestration
+├── permissions.py  → Tool permission contexts
+└── bootstrap/      → Initialization
+```
+
+### Rust (`rust/crates/`)
+```
+api/                → Anthropic-compatible client
+tools/              → Tool system
+compat-harness/     → Compatibility layer
+rusty-claude-cli/   → CLI interface
+```
+
+---
+
+## 🔗 Key Patterns
+
+### 1. Tool Permission Context
+```python
+@dataclass
+class ToolPermissionContext:
+    deny_tools: set[str]
+    deny_prefixes: tuple[str, ...]
+    
+    def blocks(self, tool_name: str) -> bool:
+        return tool_name in self.deny_tools or \
+               any(tool_name.startswith(p) for p in self.deny_prefixes)
+```
+
+### 2. Execution Registry
+- Routes prompts to commands/tools
+- Filters by permission context
+- Handles execution lifecycle
+
+### 3. Session Persistence
+- JSON-based session store
+- Turn-by-turn history
+- Context preservation
+
+---
+
+## 📖 Branches
+
+- `main` - Python-first implementation
+- `dev/rust` - Rust port (active)
+- `rcc/*` - Rust CLI components
+
+---
+
+## 🔗 External Links
+
+- **Original Repo**: https://github.com/instructkr/claw-code
+- **Author**: @instructkr (Sigrid Jin)
+- **Context**: WSJ "The Trillion Dollar Race to Automate Our Entire Lives"
+
+---
+
+*Mirrored to Gitea: March 31, 2026*
+*For: Timmy Foundation architectural reference*

rust/Cargo.lock

@@ -212,7 +212,6 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "07bbe89c50d7a535e539b8c17bc0b49bdb77747034daa8087407d655f3f7cc1d"
 dependencies = [
  "futures-core",
- "futures-sink",
 ]
 
 [[package]]
@@ -221,18 +220,6 @@ version = "0.3.32"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7e3450815272ef58cec6d564423f6e755e25379b217b0bc688e295ba24df6b1d"
 
-[[package]]
-name = "futures-io"
-version = "0.3.32"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cecba35d7ad927e23624b22ad55235f2239cfa44fd10428eecbeba6d6a717718"
-
-[[package]]
-name = "futures-sink"
-version = "0.3.32"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c39754e157331b013978ec91992bde1ac089843443c49cbc7f46150b0fad0893"
-
 [[package]]
 name = "futures-task"
 version = "0.3.32"
@@ -246,10 +233,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "389ca41296e6190b48053de0321d02a77f32f8a5d2461dd38762c0593805c6d6"
 dependencies = [
  "futures-core",
- "futures-io",
- "futures-sink",
  "futures-task",
- "memchr",
  "pin-project-lite",
  "slab",
 ]
@@ -914,9 +898,7 @@ checksum = "eddd3ca559203180a307f12d114c268abf583f59b03cb906fd0b3ff8646c1147"
 dependencies = [
  "base64",
  "bytes",
- "futures-channel",
  "futures-core",
- "futures-util",
  "http",
  "http-body",
  "http-body-util",
@@ -1370,7 +1352,6 @@ dependencies = [
 name = "tools"
 version = "0.1.0"
 dependencies = [
- "reqwest",
  "runtime",
  "serde",
  "serde_json",

rust/crates/tools/.gitignore

@@ -1 +0,0 @@
-.clawd-agents/

rust/crates/tools/Cargo.toml

@@ -7,7 +7,6 @@ publish.workspace = true
 
 [dependencies]
 runtime = { path = "../runtime" }
-reqwest = { version = "0.12", default-features = false, features = ["blocking", "rustls-tls"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"