code-context-control 2.122.0__tar.gz → 2.123.0__tar.gz

{code_context_control-2.122.0/code_context_control.egg-info → code_context_control-2.123.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.122.0
+Version: 2.123.0
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0

{code_context_control-2.122.0 → code_context_control-2.123.0}/cli/c3.py

@@ -92,7 +92,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.122.0"
+__version__ = "2.123.0"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):
@@ -271,7 +271,7 @@ _STALE_MCP_TOOLS = {
     "mcp__c3__c3_remember",           # → c3_memory(action='add')
     "mcp__c3__c3_recall",             # → c3_memory(action='recall')
     "mcp__c3__c3_sltm_add",           # → c3_memory(action='add')
-    "mcp__c3__c3_file_map",           # → c3_compress(mode='map')
+    "mcp__c3__c3_file_map",           # → c3_read(file_path) map
     "mcp__c3__c3_extract",            # → c3_read
     "mcp__c3__c3_transcript_search",  # → c3_search(action='transcript')
     "mcp__c3__c3_session_log",        # → c3_session(action='log')
@@ -3971,7 +3971,7 @@ def cmd_benchmark(args):
             "prompt_budget_multiplier": round(_prompt_gain(comp_comp, comp_orig), 2),
         },
         "file_navigation": {
-            "description": "Use c3_compress(mode='map') to choose targeted reads instead of opening whole files blindly.",
+            "description": "Use the c3_read file map to choose targeted reads instead of opening whole files blindly.",
             "performance_metric": "map success rate",
             "with_c3": {"tool": "c3_compress(mode='map')", "total_tokens": file_map_comp, "avg_latency_ms": round(_avg(file_map_c3_latencies), 2), "performance": round((file_map_successes / len(file_map_sample) * 100), 1) if file_map_sample else 0.0},
             "without_c3": {"approach": "read full files into context", "total_tokens": file_map_orig, "avg_latency_ms": round(_avg(file_map_baseline_latencies), 2), "performance": 100.0},
@@ -5005,7 +5005,7 @@ back to native tools as the task progresses.
 
 ## Quick Reference
 - **Search**: `c3_search(query=..., action='code|files|semantic')` — before Grep/Glob
-- **Read**: `c3_compress(mode='map')` then `c3_read(symbols=...)` — before native Read
+- **Read**: `c3_read(file_path)` maps a file (or directory), then `c3_read(symbols=['Class.method'])` — before native Read
 - **Impact**: `c3_impact(target='symbol')` — blast-radius check before editing shared symbols
 - **Edit**: `c3_edit(file_path=..., old_string=..., new_string=...)` — before Edit/Write
 - **Validate**: `c3_validate(file_path=...)` — after every edit (pyright/tsc type check if installed)

{code_context_control-2.122.0 → code_context_control-2.123.0}/cli/guide/index.html

@@ -636,7 +636,7 @@
             <span>Discover files / content — never start with Grep/Glob</span>
           </div>
           <div class="quick-item">
-            <code>3. c3_compress(mode='map') + c3_read(symbols=…)</code>
+            <code>3. c3_read(file_path) + c3_read(symbols=…)</code>
             <span>Map then surgically read — never start with native Read</span>
           </div>
           <div class="quick-item">

{code_context_control-2.122.0 → code_context_control-2.123.0}/cli/guide/workflow.html

@@ -315,7 +315,7 @@
           <tr>
             <td><span class="badge badge-blue">3</span></td>
             <td><strong>Map + Read</strong></td>
-            <td><code>c3_compress(mode='map')</code> → <code>c3_read(symbols=…)</code></td>
+            <td><code>c3_read(file_path)</code> (map) → <code>c3_read(symbols=…)</code></td>
             <td>Before reading any file content</td>
           </tr>
           <tr>

{code_context_control-2.122.0 → code_context_control-2.123.0}/cli/hook_pretool_enforce.py

@@ -130,7 +130,7 @@ _VAULT_FILES = frozenset({"config.json", "secrets.enc", "cred_state.json",
 # Redirect messages per native tool
 _REDIRECTS = {
     "Read": (
-        "Use c3_compress(file_path='...', mode='map') to map the file first, "
+        "Use c3_read(file_path='...') to map the file first (one line per symbol), "
         "then c3_read(file_path='...', symbols=['...']) for surgical extraction."
     ),
     "Grep": (

{code_context_control-2.122.0 → code_context_control-2.123.0}/cli/tools/read.py

@@ -177,6 +177,22 @@ def handle_read(file_path: str, symbols: Any = None, lines: Any = None,
 
     rel_path = str(full.resolve().relative_to(Path(svc.project_path).resolve())).replace("\\", "/")
 
+    if full.is_dir():
+        # A directory maps to one line per file, budgeted
+        # (docs/file-map.md § Directories). `lines=<int>` sets the budget.
+        from services.dir_map import DEFAULT_MAX_TOKENS, render_directory_map
+        budget = DEFAULT_MAX_TOKENS
+        if isinstance(lines, int) and not isinstance(lines, bool) and lines > 0:
+            budget = lines
+        text, dir_detail = render_directory_map(svc, rel_path, max_tokens=budget)
+        tok = count_tokens(text)
+        if finalize is None:
+            return text
+        return finalize_with_tokens(
+            finalize, svc, "c3_read", {"file": file_path}, text,
+            f"dir:{dir_detail['files']}files->{tok}tok",
+            optimized_tokens=tok, response_tokens=tok, detail=dir_detail)
+
     # Resolve ranges
     ranges = []
 

{code_context_control-2.122.0 → code_context_control-2.123.0/code_context_control.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.122.0
+Version: 2.123.0
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0

{code_context_control-2.122.0 → code_context_control-2.123.0}/code_context_control.egg-info/SOURCES.txt

@@ -217,6 +217,7 @@ services/conversation_store.py
 services/cred_audit.py
 services/cred_telemetry.py
 services/credential_store.py
+services/dir_map.py
 services/doc_index.py
 services/e2e_benchmark.py
 services/e2e_evaluator.py
@@ -345,6 +346,7 @@ tests/test_credentials_tool.py
 tests/test_creds_cli_smoke.py
 tests/test_delegate_cascade.py
 tests/test_delegate_version_probe.py
+tests/test_dir_map_c3.py
 tests/test_e2e_benchmark.py
 tests/test_edit_ledger_deadline.py
 tests/test_edit_ledger_hook.py

{code_context_control-2.122.0 → code_context_control-2.123.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "code-context-control"
-version = "2.122.0"
+version = "2.123.0"
 description = "Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub."
 readme = "README.md"
 requires-python = ">=3.10"

{code_context_control-2.122.0 → code_context_control-2.123.0}/services/claude_md.py

@@ -32,7 +32,7 @@ When falling back, state which c3_* tool was attempted and why it was insufficie
 ## Workflow (follow this order — do not skip steps)
 1. **RECALL**: `c3_memory(action='recall')` — before any multi-step or context-dependent task. Large memory stores: use `index` first (compact list), then `fetch` for specific IDs
 2. **SEARCH FIRST**: `c3_search(action='code|files|semantic')` — before ANY file discovery or content search. Never start with Grep/Glob
-3. **MAP before READ**: `c3_compress(mode='map')` then `c3_read(symbols=...|lines=...)` — for ANY file read. Never start with native Read. Use `mode='ast'` for knowledge-graph overview (requires codebase-memory-mcp)
+3. **MAP before READ**: `c3_read(file_path)` with no symbols/lines returns the file map (one line per symbol with signature and `[La-Lb]` range, ~10% of the file's tokens; a directory path maps its files), then `c3_read(symbols=['Class.method']|lines=[a,b])` for the source you need. Never start with native Read. `c3_compress` is the same map for a comma-separated batch (legacy; removed in 2.124.0)
 4. **IMPACT** (shared symbols): `c3_impact(target='symbol')` — blast-radius check before editing any function/class used across files
 5. **EDIT via C3**: `c3_edit(file_path, old_string, new_string, summary)` — for ALL edits. Parallel across files; `edits=[]` batch for same file
 6. **FILTER**: `c3_filter(text=...)` — for terminal output >10 lines or log files
@@ -55,7 +55,7 @@ In plan mode, all c3_* read tools (search, read, compress, filter, validate, sta
 ## Anti-patterns (DO NOT do these)
 - Starting with native file search/read/grep without a prior c3_* call
 - Using native Edit when c3_edit is available
-- Reading entire files when c3_compress + c3_read would be more surgical
+- Reading entire files when a c3_read map + a symbol read would be more surgical
 - Skipping c3_validate after making edits"""
 
 # Pointer that replaces the embedded Project Context tree (v2.60.0).
@@ -73,14 +73,14 @@ C3_NANO_WORKFLOW = """\
 ## C3 Tools — MANDATORY
 Native tools BLOCKED unless c3_* called first. State reason when falling back.
 1. c3_search(action='code|files|semantic') — BEFORE any search/grep/glob
-2. c3_compress(mode='map') then c3_read(symbols=...|lines=...) — BEFORE any file read
+2. c3_read(file_path) maps a file (or directory); then c3_read(symbols=['Class.method']|lines=[a,b]) — BEFORE any file read
 3. c3_edit(file_path, old_string, new_string, summary) — for ALL edits; edits=[{...}] batch
 4. c3_filter(text='...') — output >10 lines
 5. c3_validate(file_path) — after edits
 6. c3_session(action='log'|'snapshot') — decisions / before /clear
 7. `[c3-access:confirm]` = PAUSE, not block: a human approves this exact write (agent-config files — .mcp.json, instruction docs, .claude bodies — hold by default). Read the S8 tail: wait on the request it names (c3_override(action='wait', request_id='...', timeout_s=180)), then retry once. Never retry early, never route around it.
 Plan mode: all c3_* read tools work normally — skip edit/delegate steps.
-DO NOT: start with native Read/Grep/Glob/Edit, skip c3_validate, read full files without c3_compress."""
+DO NOT: start with native Read/Grep/Glob/Edit, skip c3_validate, read full files without mapping them first."""
 
 
 # --- Per-IDE workflow adaptation ----------------------------------------------

{code_context_control-2.122.0 → code_context_control-2.123.0}/services/codex_integration.py

@@ -8,7 +8,7 @@ CODEX_WORKFLOW = """# C3 — Codex workflow
 
 Use C3 for repository intelligence and audited changes:
 1. Recall relevant project facts with c3_memory; inspect .c3/MAP.md.
-2. Find candidates with c3_search; map with c3_compress(mode='map'), then
+2. Find candidates with c3_search; map with c3_read(file_path) (no symbols), then
    read exact symbols or lines with c3_read. Check shared changes with c3_impact.
 3. Edit with c3_edit, validate with c3_validate, and record decisions with
    c3_session(action='log'). Preserve unrelated work.

code_context_control-2.123.0/services/dir_map.py

@@ -0,0 +1,176 @@
+"""Directory maps — one line per file, budgeted, for `c3_read('<dir>')`.
+
+    # services/ (58 files, 41,203L)
+    compressor.py (809L python) — CodeCompressor; compress_file; STRUCTURE_PATTERNS
+    file_map.py (280L python) — render_map; parse_signature; parse_map; KINDS
+    …
+    … 12 more files
+
+Files are ranked the way a reader would want them: recently edited first
+(the edit ledger), then by how much structure they hold (symbol count),
+then by path. The map is filled to a token budget and closes with how
+many files it left out. Traversal is bounded — the scanner's SKIP_DIRS
+and .gitignore pruning, never following symlinks, a hard file cap — and
+structure comes from file_memory records, extracting on the fly only
+for a bounded number of code files (docs/file-map.md § Directories).
+"""
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Optional
+
+from core import count_tokens
+from services.file_memory import CODE_EXTENSIONS, LANG_MAP
+from services.scanner import iter_files
+
+DEFAULT_MAX_TOKENS = 1500
+MAX_FILES = 400            # hard traversal cap
+MAX_EXTRACT_FILES = 120    # code files parsed on the fly, per call
+EXTRACT_DEADLINE_S = 3.0   # then the rest show line counts only
+MAX_EXTRACT_BYTES = 200 * 1024
+SYMBOLS_PER_FILE = 6
+LEDGER_LOOKBACK = 300      # recent ledger entries consulted for ranking
+
+
+def _recent_edit_ranks(svc) -> dict:
+    """path -> recency rank (0 = most recent) from the edit ledger."""
+    ledger = getattr(svc, "edit_ledger", None)
+    if ledger is None:
+        return {}
+    try:
+        entries = ledger.get_history(limit=LEDGER_LOOKBACK)
+    except Exception:
+        return {}
+    ranks: dict = {}
+    for entry in entries or []:
+        f = str((entry or {}).get("file") or "").replace("\\", "/")
+        if f and f not in ranks:
+            ranks[f] = len(ranks)
+    return ranks
+
+
+#: What a reader wants to see first on a one-line summary of a file.
+_SYMBOL_PRIORITY = {"class": 0, "interface": 0, "struct": 0, "trait": 0, "enum": 0,
+                    "function": 1, "method": 1, "type": 2, "heading": 2, "section": 2,
+                    "constant": 3, "variable": 3}
+_SKIP_SYMBOL_TYPES = {"import", "decorator", "comment", "content", "property", "impl"}
+
+
+def _structural_sections(record: Optional[dict]) -> list:
+    return [s for s in (record or {}).get("sections") or []
+            if s.get("type") not in _SKIP_SYMBOL_TYPES
+            and str(s.get("name") or "").strip() not in ("", "(full file)")]
+
+
+def _top_symbols(record: Optional[dict]) -> list:
+    """Up to SYMBOLS_PER_FILE names: classes first, then functions, then the
+    rest, constants last — each group in source order."""
+    picked = sorted(enumerate(_structural_sections(record)),
+                    key=lambda iv: (_SYMBOL_PRIORITY.get(iv[1].get("type"), 2),
+                                    str(iv[1].get("name") or "").startswith("_"),
+                                    iv[0]))
+    names = []
+    for _, s in picked[:SYMBOLS_PER_FILE]:
+        name = str(s.get("name") or "").strip()
+        if s.get("type") == "heading":
+            name = name.split(":", 1)[-1].strip()
+        names.append(name)
+    return names
+
+
+def _line_count(path: Path) -> int:
+    try:
+        with open(path, "rb") as fh:
+            return sum(1 for _ in fh)
+    except OSError:
+        return 0
+
+
+def render_directory_map(svc, rel_dir: str, *, max_tokens: int = DEFAULT_MAX_TOKENS) -> tuple:
+    """Return (text, detail) for the directory `rel_dir` (project-relative, posix)."""
+    root = Path(svc.project_path).resolve()
+    rel_dir = str(rel_dir).replace("\\", "/").strip("/")
+    target = (root / rel_dir).resolve() if rel_dir else root
+    label = (rel_dir + "/") if rel_dir else "./"
+
+    files = []
+    capped = False
+    for fp in iter_files(target, max_files=MAX_FILES + 1):
+        if len(files) >= MAX_FILES:
+            capped = True
+            break
+        try:
+            files.append(fp.resolve().relative_to(root).as_posix())
+        except ValueError:
+            continue
+
+    store = getattr(svc, "file_memory", None)
+    recent = _recent_edit_ranks(svc)
+    started = time.monotonic()
+    extracted = 0
+    rows = []
+    total_lines = 0
+    for rel in files:
+        record = None
+        if store is not None:
+            try:
+                record = store.get(rel)
+            except Exception:
+                record = None
+            ext = Path(rel).suffix.lower()
+            if (record is None and ext in CODE_EXTENSIONS
+                    and extracted < MAX_EXTRACT_FILES
+                    and time.monotonic() - started < EXTRACT_DEADLINE_S):
+                try:
+                    if (root / rel).stat().st_size <= MAX_EXTRACT_BYTES:
+                        record = store.update(rel)
+                        extracted += 1
+                except Exception:
+                    record = None
+        lines = int((record or {}).get("lines") or 0) or _line_count(root / rel)
+        total_lines += lines
+        ext = Path(rel).suffix.lower()
+        lang = str((record or {}).get("language") or LANG_MAP.get(ext) or ext.lstrip(".") or "")
+        symbols = _top_symbols(record)
+        rows.append({
+            "rel": rel,
+            "name": rel[len(rel_dir) + 1:] if rel_dir and rel.startswith(rel_dir + "/") else rel,
+            "lines": lines,
+            "lang": lang,
+            "symbols": symbols,
+            "recent": recent.get(rel, 10 ** 6),
+            "nsym": len(_structural_sections(record)),
+        })
+
+    rows.sort(key=lambda r: (r["recent"], -r["nsym"], r["rel"]))
+
+    header = f"# {label} ({len(files)}{'+' if capped else ''} files, {total_lines:,}L)"
+    body = []
+    for r in rows:
+        line = f"{r['name']} ({r['lines']}L {r['lang']})".rstrip()
+        if r["symbols"]:
+            line += " — " + "; ".join(r["symbols"])
+        body.append(line)
+
+    kept = list(body)
+    while kept and count_tokens("\n".join([header] + kept)) > max_tokens:
+        kept.pop()
+    dropped = len(body) - len(kept)
+    parts = [header] + kept
+    if dropped:
+        parts.append(f"… {dropped} more files")
+    if capped:
+        parts.append(f"[dir_map] traversal capped at {MAX_FILES} files; map a subdirectory")
+    # In source order the reader gets recency first; say so once.
+    parts.append("[dir_map] recently edited first, then by structure; "
+                 "c3_read('<file>') maps one file")
+    text = "\n".join(parts)
+    detail = {
+        "backend": "directory",
+        "files": len(files),
+        "listed": len(kept),
+        "extracted": extracted,
+        "capped": capped,
+    }
+    return text, detail

code_context_control-2.123.0/tests/test_dir_map_c3.py

@@ -0,0 +1,176 @@
+"""C3 of the c3_compress remediation: c3_read maps directories too.
+
+The one thing c3_read could not do that c3_compress could was a batch,
+and neither could map a directory. Now `c3_read('<dir>')` renders one
+line per file under a token budget, recently edited files first, then the
+ones with the most structure. These tests pin the shape, the ranking, the
+budget and the traversal bounds (docs/file-map.md § Directories), plus the
+instruction surfaces that now teach the c3_read(file_path) form.
+"""
+from __future__ import annotations
+
+import json
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from types import SimpleNamespace
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from cli.tools.read import handle_read  # noqa: E402
+from core import count_tokens  # noqa: E402
+from services import dir_map  # noqa: E402
+from services.file_memory import FileMemoryStore  # noqa: E402
+from services.session_manager import SessionManager  # noqa: E402
+
+
+def _py(n_funcs: int, prefix: str) -> str:
+    parts = ["import os\n\n"]
+    if n_funcs:
+        parts.append(f"class {prefix.title()}Thing:\n    def run(self):\n        return 1\n\n")
+    for i in range(n_funcs):
+        parts.append(f"def {prefix}_{i}(x):\n    return x + {i}\n\n")
+    return "".join(parts)
+
+
+class _Ledger:
+    def __init__(self, files):
+        self._files = files
+
+    def get_history(self, limit=50):
+        return [{"file": f} for f in self._files]
+
+
+def _svc(tmp, ledger=None, session=False):
+    sm = None
+    if session:
+        sm = SessionManager(tmp)
+        sm.start_session("t")
+    return SimpleNamespace(project_path=tmp, file_memory=FileMemoryStore(tmp),
+                           edit_ledger=ledger, session_mgr=sm, hybrid_config={})
+
+
+def _fin(sm):
+    def finalize(name, args, resp, summ, **kw):
+        sm.log_tool_call(name, args, summ)
+        sm.track_response(name, resp, kw.get("response_tokens", 0))
+        return resp
+    return finalize
+
+
+class TestDirectoryMap(unittest.TestCase):
+    def _tree(self, tmp):
+        root = Path(tmp)
+        (root / "pkg").mkdir()
+        (root / "pkg" / "big.py").write_text(_py(8, "big"), encoding="utf-8")
+        (root / "pkg" / "small.py").write_text(_py(1, "small"), encoding="utf-8")
+        (root / "pkg" / "notes.md").write_text("# Notes\n\n## Later\n\ntext\n", encoding="utf-8")
+        (root / "pkg" / "data.txt").write_text("a\nb\nc\n", encoding="utf-8")
+        (root / "pkg" / "node_modules").mkdir()
+        (root / "pkg" / "node_modules" / "dep.js").write_text("module.exports = 1;\n", encoding="utf-8")
+        return root
+
+    def test_shape_and_ranking_by_structure(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            self._tree(tmp)
+            out = handle_read("pkg", None, None, True, _svc(tmp), None)
+            lines = out.splitlines()
+            self.assertEqual(lines[0], "# pkg/ (4 files, 47L)")
+            self.assertTrue(lines[1].startswith("big.py (30L python) — BigThing; big_0; big_1; big_2; big_3; big_4"))
+            self.assertIn("small.py (9L python) — SmallThing; small_0", lines)
+            self.assertIn("notes.md (5L markdown) — Notes; Later", lines)
+            self.assertIn("data.txt (3L txt)", lines)
+            self.assertNotIn("dep.js", out)
+            self.assertTrue(lines[-1].startswith("[dir_map] recently edited first"))
+
+    def test_recent_edits_rank_first(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            self._tree(tmp)
+            svc = _svc(tmp, ledger=_Ledger(["pkg/small.py", "pkg/data.txt"]))
+            lines = handle_read("pkg", None, None, True, svc, None).splitlines()
+            self.assertTrue(lines[1].startswith("small.py"))
+            self.assertTrue(lines[2].startswith("data.txt"))
+            self.assertTrue(lines[3].startswith("big.py"))
+
+    def test_budget_drops_from_the_end_and_counts(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            self._tree(tmp)
+            out = handle_read("pkg", None, 30, True, _svc(tmp), None)
+            self.assertLessEqual(count_tokens("\n".join(out.splitlines()[:-1])),
+                                 30 + count_tokens("… 3 more files"))
+            self.assertIn("… ", out)
+            self.assertIn("more files", out)
+
+    def test_traversal_cap_and_no_symlink_follow(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = self._tree(tmp)
+            link = root / "pkg" / "loop"
+            try:
+                link.symlink_to(root / "pkg", target_is_directory=True)
+                linked = True
+            except (OSError, NotImplementedError):
+                linked = False
+            old = dir_map.MAX_FILES
+            dir_map.MAX_FILES = 2
+            try:
+                out = handle_read("pkg", None, None, True, _svc(tmp), None)
+            finally:
+                dir_map.MAX_FILES = old
+            self.assertIn("# pkg/ (2+ files", out)
+            self.assertIn("traversal capped at 2 files", out)
+            if linked:
+                self.assertNotIn("loop/", out)
+
+    def test_root_directory_and_telemetry_detail(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            self._tree(tmp)
+            svc = _svc(tmp, session=True)
+            out = handle_read(".", None, None, True, svc, _fin(svc.session_mgr))
+            self.assertTrue(out.startswith("# ./ ("))
+            self.assertIn("pkg/big.py (30L python)", out)
+            rows = [json.loads(line) for line in
+                    (Path(tmp) / ".c3" / "tool_telemetry.jsonl").read_text(encoding="utf-8").splitlines()]
+            detail = rows[-1]["detail"]
+            self.assertEqual(detail["backend"], "directory")
+            self.assertEqual(detail["files"], 4)
+            self.assertEqual(detail["listed"], 4)
+            self.assertGreaterEqual(detail["extracted"], 2)
+            self.assertFalse(detail["capped"])
+
+    def test_extraction_is_bounded(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / "many").mkdir()
+            for i in range(6):
+                (root / "many" / f"m{i}.py").write_text(_py(1, f"m{i}"), encoding="utf-8")
+            old = dir_map.MAX_EXTRACT_FILES
+            dir_map.MAX_EXTRACT_FILES = 2
+            try:
+                text, detail = dir_map.render_directory_map(_svc(tmp), "many")
+            finally:
+                dir_map.MAX_EXTRACT_FILES = old
+            self.assertEqual(detail["extracted"], 2)
+            self.assertEqual(detail["files"], 6)
+            # Unparsed files still show a line count.
+            self.assertEqual(sum(1 for line in text.splitlines() if "(9L python)" in line), 6)
+
+
+class TestInstructionSurfaces(unittest.TestCase):
+    def test_managed_block_teaches_read_first(self):
+        from services import claude_md
+        text = claude_md.C3_WORKFLOW if hasattr(claude_md, "C3_WORKFLOW") else ""
+        src = Path(claude_md.__file__).read_text(encoding="utf-8")
+        self.assertIn("`c3_read(file_path)` with no symbols/lines returns the file map", src)
+        self.assertNotIn("`c3_compress(mode='map')` then `c3_read(symbols=...|lines=...)`", src)
+        self.assertIn("c3_read(file_path) maps a file (or directory)", src)
+        del text
+
+    def test_hook_redirect_names_c3_read(self):
+        from cli import hook_pretool_enforce as hook
+        self.assertIn("c3_read(file_path='...') to map the file first", hook._REDIRECTS["Read"])
+        self.assertNotIn("c3_compress", hook._REDIRECTS["Read"])
+
+
+if __name__ == "__main__":
+    unittest.main()