code-context-control 2.28.0__py3-none-any.whl

cli/hook_pretool_enforce.py

@@ -0,0 +1,334 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: two-mode enforcement for native tools.
+
+Read-class tools (Read/Grep/Glob/FindFiles/SearchText) are **ADVISORY** —
+if no c3_* tool was used first, the call proceeds with a selection-time
+hint injected via additionalContext. Drift is still cheap to recover from
+for read-only operations.
+
+Write-class tools (Edit/Write) are **BLOCKED** — file mutations must go
+through c3_edit so the ledger captures every change. Hard-deny with
+redirect message.
+
+This replaces the previous all-blocking behavior. Rationale: blocking read
+tools treats Claude adversarially and creates cliffs at every edge case
+(new tool variants, Windows quirks). Advisory read + blocked write keeps
+the ledger intact without strangling the model's own good judgment.
+
+Supports both Claude Code and Gemini CLI via _hook_utils.
+"""
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from _hook_utils import log_hook_error, normalize_tool_name
+
+# How many activity-log lines to scan backwards
+LOOKBACK = 20  # Fix 1: increased from 3 — activity log only has c3_* entries
+
+# Signal file written by hook_c3_signal.py after any c3_* tool completes
+_SIGNAL_FILE = ".c3/last_c3_call.json"
+_SIGNAL_MAX_AGE_SECS = 600  # 10 minutes
+
+# Session-sticky unlock file: tracks files accessed via c3_* tools, per-category
+_UNLOCK_FILE = ".c3/unlocked_files.json"
+
+# Which unlock category each native tool requires
+_TOOL_CATEGORY = {
+    "Read": "read", "Grep": "read", "Glob": "read",
+    "FindFiles": "read", "SearchText": "read", "Edit": "edit",
+    "Write": "edit",
+}
+
+# Which unlock category each c3 tool grants
+_C3_GRANTS = {
+    "c3_search": "read", "c3_compress": "read", "c3_read": "read",
+    "c3_filter": "read", "c3_validate": "read", "c3_impact": "read",
+    "c3_edit": "edit", "c3_edits": "edit", "c3_agent": "both",
+    "c3_delegate": "read", "c3_session": "read", "c3_memory": "read",
+    "c3_status": "read",
+}
+
+# c3 tools that satisfy the "used c3 first" requirement per native tool
+_PREREQS = {
+    "Read":       {"c3_search", "c3_compress", "c3_read", "c3_filter",
+                   "c3_validate", "c3_impact", "c3_edit", "c3_agent", "c3_delegate"},
+    "Grep":       {"c3_search", "c3_compress", "c3_filter", "c3_validate",
+                   "c3_impact", "c3_agent", "c3_delegate"},
+    "Glob":       {"c3_search", "c3_filter", "c3_agent", "c3_delegate"},
+    "FindFiles":  {"c3_search", "c3_filter", "c3_agent", "c3_delegate"},
+    "SearchText": {"c3_search", "c3_compress", "c3_read", "c3_filter",
+                   "c3_impact", "c3_agent", "c3_delegate"},
+    "Edit":       {"c3_edit", "c3_edits", "c3_agent"},
+    "Write":      {"c3_edit", "c3_edits", "c3_agent"},
+    "MultiEdit":  {"c3_edit", "c3_edits", "c3_agent"},
+}
+
+# Read-class tools: advisory (allow + nudge when no c3 used first).
+# Write-class tools: blocked (ledger integrity).
+_ADVISORY_TOOLS = {"Read", "Grep", "Glob", "FindFiles", "SearchText"}
+_BLOCKED_TOOLS = {"Edit", "Write", "MultiEdit"}
+
+# Redirect messages per native tool
+_REDIRECTS = {
+    "Read": (
+        "Use c3_compress(file_path='...', mode='map') to map the file first, "
+        "then c3_read(file_path='...', symbols=['...']) for surgical extraction."
+    ),
+    "Grep": (
+        "Use c3_search(query='...', action='code') for pattern matching, "
+        "or c3_search(query='...', action='semantic') for concept search."
+    ),
+    "Glob": (
+        "Use c3_search(query='...', action='files') for file discovery."
+    ),
+    "FindFiles": (
+        "Use c3_search(query='...', action='files') for file discovery."
+    ),
+    "SearchText": (
+        "Use c3_search(query='...', action='code') for code search."
+    ),
+    "Edit": (
+        "Use c3_edit(file_path='...', old_string='...', new_string='...', summary='...') "
+        "for file edits — it reads, patches, writes, and logs in one step."
+    ),
+    "Write": (
+        "Use c3_edit(file_path='...', old_string='...', new_string='...', summary='...') "
+        "for file modifications. For new files, use native Write only after c3_search/c3_compress."
+    ),
+}
+
+
+def _tail_lines(path: Path, n: int) -> list[str]:
+    """Read last n lines of a file without loading the whole file.
+
+    Activity logs grow to megabytes over a session; the enforcer only inspects
+    the tail window, so reading the whole file on every native tool call was
+    pure overhead.
+    """
+    try:
+        with open(path, "rb") as f:
+            f.seek(0, 2)
+            size = f.tell()
+            if size == 0:
+                return []
+            block = 4096
+            chunks = []
+            seen_newlines = 0
+            pos = size
+            while pos > 0 and seen_newlines <= n:
+                read_size = min(block, pos)
+                pos -= read_size
+                f.seek(pos)
+                data = f.read(read_size)
+                seen_newlines += data.count(b"\n")
+                chunks.append(data)
+        blob = b"".join(reversed(chunks))
+        text = blob.decode("utf-8", errors="replace")
+        return text.splitlines()[-n:]
+    except Exception:
+        return []
+
+
+def _load_unlocked(project_path: Path) -> dict:
+    """Load per-category unlock map: {normalized_path: ["read"], ...}."""
+    unlock_path = project_path / _UNLOCK_FILE
+    if not unlock_path.exists():
+        return {}
+    try:
+        data = json.loads(unlock_path.read_text(encoding="utf-8"))
+        return data if isinstance(data, dict) else {}
+    except Exception:
+        return {}
+
+
+def _save_unlocked(project_path: Path, unlocked: dict):
+    """Persist the per-category unlock map."""
+    unlock_path = project_path / _UNLOCK_FILE
+    unlock_path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        unlock_path.write_text(json.dumps(unlocked), encoding="utf-8")
+    except Exception:
+        pass
+
+
+def _record_unlock(project_path: Path, file_path: str, category: str):
+    """Add a file path to the sticky unlock map for the given category."""
+    if not file_path or not category:
+        return
+    unlocked = _load_unlocked(project_path)
+    normalized = str(Path(file_path).resolve()) if file_path else ""
+    if not normalized:
+        return
+    cats = set(unlocked.get(normalized, []))
+    if category == "both":
+        cats.update({"read", "edit"})
+    else:
+        cats.add(category)
+    unlocked[normalized] = sorted(cats)
+    _save_unlocked(project_path, unlocked)
+
+
+def _is_file_unlocked(project_path: Path, file_path: str, category: str) -> bool:
+    """Check if a file is unlocked for the given operation category."""
+    if not file_path:
+        return False
+    unlocked = _load_unlocked(project_path)
+    normalized = str(Path(file_path).resolve()) if file_path else ""
+    cats = unlocked.get(normalized, [])
+    return category in cats or "both" in cats
+
+
+def _check_signal_file(project_path: Path) -> tuple[bool, bool]:
+    """Read last_c3_call.json written by hook_c3_signal.py.
+
+    Returns (recent, read_unlocked):
+      recent:        True if a c3_* tool completed within _SIGNAL_MAX_AGE_SECS
+      read_unlocked: True if that tool was c3_search/c3_compress/c3_filter
+    """
+    signal_path = project_path / _SIGNAL_FILE
+    if not signal_path.exists():
+        return False, False
+    try:
+        data = json.loads(signal_path.read_text(encoding="utf-8"))
+        ts = datetime.fromisoformat(data["timestamp"])
+        age = (datetime.now(timezone.utc) - ts).total_seconds()
+        recent = age <= _SIGNAL_MAX_AGE_SECS
+        return recent, bool(data.get("read_unlocked", False)) and recent
+    except Exception:
+        return False, False
+
+
+def _check_c3_used(project_path: Path, tool_name: str, tool_input: dict) -> tuple[bool, str]:
+    """Check if a qualifying c3 tool was recently used.
+
+    Returns (allowed, via) where via is one of:
+      'signal'   -- fresh c3_* signal file (within 10 min) — no reminder
+      'unlock'   -- sticky file unlock only, no fresh signal — emit reminder
+      'activity' -- activity log hit within last LOOKBACK entries — no reminder
+      ''         -- not allowed
+    """
+    allowed = _PREREQS.get(tool_name, set())
+    if not allowed:
+        return True, "signal"  # No prereqs defined → allow without reminder
+
+    native_target = (
+        tool_input.get("file_path", "")
+        or tool_input.get("path", "")
+        or tool_input.get("pattern", "")
+        or tool_input.get("query", "")
+        or ""
+    )
+    required_cat = _TOOL_CATEGORY.get(tool_name, "read")
+
+    # ── Fix 4: signal file — primary, fast, reliable ─────────────────────────
+    signal_recent, signal_read_unlocked = _check_signal_file(project_path)
+    if signal_recent:
+        # Fix 5: Grep/Glob without file path needs a read-unlocking tool
+        if not native_target and tool_name in ("Grep", "Glob", "FindFiles", "SearchText"):
+            if signal_read_unlocked:
+                return True, "signal"
+            # Signal exists but not read-unlocking (e.g. c3_memory) — fall through
+        else:
+            if native_target:
+                _record_unlock(project_path, native_target, required_cat)
+            return True, "signal"
+
+    # ── Sticky file unlock (per-file, persists across turns) ─────────────────
+    if native_target and _is_file_unlocked(project_path, native_target, required_cat):
+        return True, "unlock"  # allowed but no fresh signal — emit reminder
+
+    # ── Fix 1: activity log scan (LOOKBACK increased to 20) ──────────────────
+    log_file = project_path / ".c3" / "activity_log.jsonl"
+    if not log_file.exists():
+        return False, ""
+
+    try:
+        lines = _tail_lines(log_file, LOOKBACK)
+    except Exception:
+        return False, ""
+
+    for line in reversed(lines):
+        try:
+            entry = json.loads(line)
+        except (json.JSONDecodeError, ValueError):
+            continue
+
+        if entry.get("type") != "tool_call":
+            continue
+
+        tool = entry.get("tool", "")
+        if tool not in allowed:
+            continue
+
+        if native_target:
+            grant = _C3_GRANTS.get(tool, required_cat)
+            _record_unlock(project_path, native_target, grant)
+        return True, "activity"
+
+    return False, ""
+
+
+def main():
+    try:
+        raw = sys.stdin.read()
+        if not raw.strip():
+            return
+
+        data = json.loads(raw)
+        tool_name = normalize_tool_name(data.get("tool_name", ""))
+
+        if tool_name not in _PREREQS:
+            return  # Not a tool we enforce — pass through
+
+        tool_input = data.get("tool_input", {})
+        project_path = Path.cwd()
+
+        allowed, via = _check_c3_used(project_path, tool_name, tool_input)
+
+        if allowed:
+            # Sticky-unlock only: gentle drift-guard nudge, still allow.
+            if via == "unlock":
+                print(json.dumps({
+                    "additionalContext": (
+                        f"[c3:drift-guard] {tool_name} allowed via sticky unlock "
+                        f"— no recent c3_* call detected. "
+                        f"Prefer c3_search/c3_compress to keep the ledger warm."
+                    )
+                }))
+            return  # satisfied prereq — allow
+
+        # No c3_* prereq met. Advisory vs blocked split.
+        redirect = _REDIRECTS.get(tool_name, "Prefer a c3_* tool.")
+
+        if tool_name in _ADVISORY_TOOLS:
+            # Read-class: allow, but inject a selection-time hint.
+            print(json.dumps({
+                "additionalContext": (
+                    f"[c3:hint] Native `{tool_name}` is running without a prior c3_* call. "
+                    f"For better index awareness next time: {redirect}"
+                )
+            }))
+            return
+
+        # Write-class: hard block. Ledger integrity matters more than flexibility.
+        reason = (
+            f"[c3:enforce] Native `{tool_name}` is blocked to preserve the edit ledger. "
+            f"{redirect}"
+        )
+        response = {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": reason,
+            }
+        }
+        print(json.dumps(response))
+
+    except Exception as _e:
+        log_hook_error("hook_pretool_enforce", _e)
+
+
+if __name__ == "__main__":
+    main()

cli/hook_read.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+"""PostToolUse/AfterTool hook for Read/read_file/SearchText/FindFiles.
+
+Checks if the model used required C3 tools before standard discovery or reads:
+- Code/docs files: c3_search / c3_compress(mode='map') / c3_read
+- Log/data files (.log/.txt/.jsonl): c3_filter(file_path='...')
+
+If not, injects strong additionalContext guidance. Also queues the file
+for async file memory indexing.
+
+Supports both Claude Code (PostToolUse/Read) and Gemini CLI (AfterTool/read_file).
+"""
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from cli._hook_utils import emit_additional_context, get_tool_output, log_hook_error, normalize_tool_name  # noqa: E402
+
+CODE_PRE_READ_TOOLS = {"c3_search", "c3_compress", "c3_read"}
+DATA_PRE_READ_TOOLS = {"c3_extract", "c3_filter"}
+C3_TOOLS = CODE_PRE_READ_TOOLS | DATA_PRE_READ_TOOLS
+LOOKBACK = 30
+
+
+def _check_c3_used(project_path: Path, rel_path: str, allowed_tools=None) -> bool:
+    """Check activity log for recent C3 tool calls targeting this file."""
+    log_file = project_path / ".c3" / "activity_log.jsonl"
+    if not log_file.exists():
+        return False
+    allowed = set(allowed_tools or C3_TOOLS)
+
+    try:
+        lines = log_file.read_text(encoding="utf-8").strip().splitlines()
+    except Exception:
+        return False
+
+    for line in reversed(lines[-LOOKBACK:]):
+        try:
+            entry = json.loads(line)
+        except (json.JSONDecodeError, ValueError):
+            continue
+
+        if entry.get("type") != "tool_call":
+            continue
+
+        tool = entry.get("tool", "")
+        if tool not in allowed:
+            continue
+
+        args = entry.get("args", {})
+        tool_path = args.get("file_path", "") or args.get("query", "")
+        tool_path_norm = tool_path.replace("\\", "/").strip("/")
+        rel_norm = rel_path.replace("\\", "/").strip("/")
+
+        if rel_norm in tool_path_norm or tool_path_norm in rel_norm:
+            return True
+
+        if tool == "c3_search":
+            filename = Path(rel_path).name
+            if filename and filename in tool_path:
+                return True
+
+    return False
+
+
+def main():
+    try:
+        raw = sys.stdin.read()
+        if not raw.strip():
+            return
+
+        data = json.loads(raw)
+
+        # Normalize Gemini tool names to Claude equivalents
+        tool_name = normalize_tool_name(data.get("tool_name", ""))
+        if tool_name not in ("Read", "FindFiles", "SearchText"):
+            return
+
+        result_text, is_gemini = get_tool_output(data)
+        if not result_text or not isinstance(result_text, str):
+            return
+
+        project_path = Path.cwd()
+
+        if tool_name == "FindFiles":
+            if not _check_c3_used(project_path, "", allowed_tools=["c3_search"]):
+                emit_additional_context(
+                    "\u26a0\ufe0f [c3:enforce] Standard file discovery is fallback-only in this project.\n\n"
+                    "Before `FindFiles`, use a core C3 discovery tool:\n"
+                    "  c3_search(query=\"<your pattern>\", action=\"files\")\n\n"
+                    "Use `FindFiles` only after a C3 result narrows the target.",
+                    is_gemini,
+                )
+            return
+
+        if tool_name == "SearchText":
+            if not _check_c3_used(project_path, "", allowed_tools=["c3_search", "c3_compress", "c3_read"]):
+                emit_additional_context(
+                    "\u26a0\ufe0f [c3:enforce] Standard text search is fallback-only in this project.\n\n"
+                    "Before `SearchText`, use a core C3 tool first:\n"
+                    "  c3_search(query=\"<symbol or concept>\", action=\"code\")\n"
+                    "  c3_compress(file_path=\"<candidate file>\", mode=\"map\")\n\n"
+                    "Use `SearchText` only after C3 narrows the scope.",
+                    is_gemini,
+                )
+            return
+
+        # Read tool: extract file_path from tool_input (Claude: file_path, Gemini: path)
+        tool_input = data.get("tool_input", {})
+        file_path = tool_input.get("file_path", "") or tool_input.get("path", "")
+        if not file_path:
+            return
+
+        line_count = result_text.count("\n") + 1
+
+        try:
+            rel_path = str(Path(file_path).resolve().relative_to(project_path.resolve()))
+        except ValueError:
+            rel_path = file_path
+        rel_path = rel_path.replace("\\", "/")
+
+        queue_path = project_path / ".c3" / "file_memory" / "_queue.txt"
+        queue_path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            with open(queue_path, "a", encoding="utf-8") as handle:
+                handle.write(rel_path + "\n")
+        except Exception:
+            pass
+
+        # Clear this file from edit-unlock pending list (Edit prerequisite satisfied)
+        pending_path = project_path / ".c3" / "edit_unlock_pending.txt"
+        try:
+            if pending_path.exists():
+                pending = set(
+                    line.strip() for line in
+                    pending_path.read_text(encoding="utf-8").splitlines()
+                    if line.strip()
+                )
+                # Match against both the raw file_path and the rel_path
+                to_remove = set()
+                fp_norm = file_path.replace("\\", "/").strip("/")
+                rel_norm = rel_path.replace("\\", "/").strip("/")
+                for p in pending:
+                    p_norm = p.replace("\\", "/").strip("/")
+                    if p_norm == fp_norm or p_norm == rel_norm or fp_norm.endswith(p_norm) or rel_norm.endswith(p_norm):
+                        to_remove.add(p)
+                if to_remove:
+                    pending -= to_remove
+                    pending_path.write_text(
+                        "\n".join(sorted(pending)) + "\n" if pending else "",
+                        encoding="utf-8",
+                    )
+        except Exception:
+            pass
+
+        ext = Path(rel_path).suffix.lower()
+        code_and_doc_exts = {
+            ".py", ".js", ".ts", ".tsx", ".jsx", ".go", ".rs", ".java",
+            ".rb", ".c", ".cpp", ".h", ".cs", ".r", ".R",
+            ".html", ".css", ".json", ".yaml", ".yml", ".sql", ".md",
+        }
+        data_exts = {".log", ".txt", ".jsonl"}
+
+        if ext not in code_and_doc_exts and ext not in data_exts:
+            return
+
+        is_data_file = ext in data_exts
+        required_tools = DATA_PRE_READ_TOOLS if is_data_file else CODE_PRE_READ_TOOLS
+        if _check_c3_used(project_path, rel_path, allowed_tools=required_tools):
+            return
+
+        if is_data_file:
+            emit_additional_context(
+                f"\u26a0\ufe0f [c3:enforce] STOP. You read `{rel_path}` without running a core C3 data tool first.\n\n"
+                "STRICT PREREQUISITE for `.log`/`.txt`/`.jsonl`:\n"
+                f"  1. c3_filter(file_path=\"{rel_path}\", pattern=\"<optional pattern>\")\n"
+                "  2. Read only the extracted signal if needed\n\n"
+                "Use standard `Read` only after `c3_filter` narrows the result.",
+                is_gemini,
+            )
+            return
+
+        emit_additional_context(
+            f"\u26a0\ufe0f [c3:enforce] STOP. You read `{rel_path}` ({line_count} lines) without using a core C3 tool first.\n\n"
+            "Required workflow before standard `Read`:\n"
+            f"  1. c3_search(query=\"{Path(rel_path).name}\", action=\"code\") or c3_compress(file_path=\"{rel_path}\", mode=\"map\")\n"
+            f"  2. c3_read(file_path=\"{rel_path}\", symbols=['ClassName', 'func_name']) or c3_read(file_path=\"{rel_path}\", lines=[[start, end]])\n"
+            "  3. Use standard `Read` only for a narrow follow-up if C3 output is insufficient\n\n"
+            "Core C3 tools are mandatory here: `c3_search`, `c3_compress`, `c3_read`.",
+            is_gemini,
+        )
+    except Exception as _e:
+        log_hook_error("hook_read", _e)
+
+
+if __name__ == "__main__":
+    main()

cli/hook_session_stats.py

@@ -0,0 +1,62 @@
+"""Stop hook: capture Claude Code session token/cost stats to .c3/session_stats.jsonl.
+
+Triggered by the Claude Code 'Stop' event. Receives JSON on stdin:
+  {
+    "session_id": "...",
+    "transcript_path": "...",
+    "stop_reason": "end_turn" | "max_turns" | ...,
+    "cost_usd": 0.042,
+    "usage": {
+      "input_tokens": 12400,
+      "output_tokens": 850,
+      "cache_creation_input_tokens": 0,
+      "cache_read_input_tokens": 11200
+    }
+  }
+
+Appends one JSON line per session to .c3/session_stats.jsonl.
+"""
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from cli._hook_utils import log_hook_error  # noqa: E402
+
+
+def main() -> None:
+    try:
+        data = json.load(sys.stdin)
+    except Exception as exc:
+        log_hook_error("hook_session_stats", exc)
+        sys.exit(0)
+
+    try:
+        usage = data.get("usage") or {}
+        entry = {
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "session_id": data.get("session_id"),
+            "stop_reason": data.get("stop_reason"),
+            "cost_usd": data.get("cost_usd"),
+            "input_tokens": usage.get("input_tokens", 0),
+            "output_tokens": usage.get("output_tokens", 0),
+            "cache_creation_tokens": usage.get("cache_creation_input_tokens", 0),
+            "cache_read_tokens": usage.get("cache_read_input_tokens", 0),
+        }
+
+        # Claude Code runs hooks from the project root, so .c3/ is relative to CWD.
+        stats_dir = Path(".c3")
+        if stats_dir.exists():
+            stats_path = stats_dir / "session_stats.jsonl"
+            with open(stats_path, "a", encoding="utf-8") as f:
+                f.write(json.dumps(entry) + "\n")
+    except Exception as exc:
+        log_hook_error("hook_session_stats", exc)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()