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

cli/hook_edit_unlock.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""PostToolUse hook for c3_read, c3_compress, and c3_agent.
+
+Tracks which editable files have been explored via C3 tools but not yet
+natively Read. Emits a batched nudge so the model can unlock Edit for all
+pending files in one message with parallel Read(limit=1) calls.
+
+Supports both Claude Code (PostToolUse) and Gemini CLI (AfterTool).
+"""
+
+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, log_hook_error  # noqa: E402
+
+EDITABLE_EXTS = {
+    ".py", ".js", ".ts", ".tsx", ".jsx", ".go", ".rs", ".java",
+    ".rb", ".c", ".cpp", ".h", ".cs", ".html", ".css",
+    ".json", ".yaml", ".yml", ".toml", ".sql", ".md", ".txt",
+    ".sh", ".bat", ".ps1", ".r",
+}
+
+HANDLED_TOOLS = {
+    "mcp__c3__c3_read",
+    "mcp__c3__c3_compress",
+    "mcp__c3__c3_agent",
+}
+
+PENDING_FILE = ".c3/edit_unlock_pending.txt"
+
+
+def _get_pending_path() -> Path:
+    return Path.cwd() / PENDING_FILE
+
+
+def _load_pending() -> set:
+    p = _get_pending_path()
+    if not p.exists():
+        return set()
+    try:
+        return set(line.strip() for line in p.read_text(encoding="utf-8").splitlines() if line.strip())
+    except Exception:
+        return set()
+
+
+def _save_pending(paths: set):
+    p = _get_pending_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        p.write_text("\n".join(sorted(paths)) + "\n" if paths else "", encoding="utf-8")
+    except Exception:
+        pass
+
+
+def _extract_files_from_tool(tool_name: str, tool_input: dict, tool_response: str) -> list:
+    """Extract file paths that were touched by the tool call."""
+    files = []
+
+    if tool_name in ("mcp__c3__c3_read", "mcp__c3__c3_compress"):
+        file_path = (tool_input.get("file_path") or "").strip()
+        if file_path:
+            # Support comma-separated paths
+            files.extend(p.strip() for p in file_path.split(",") if p.strip())
+
+    elif tool_name == "mcp__c3__c3_agent":
+        # Extract scope (comma-separated file paths) from agent workflows
+        scope = (tool_input.get("scope") or "").strip()
+        if scope:
+            candidates = [p.strip() for p in scope.split(",") if p.strip()]
+            # Only include if they look like file paths
+            files.extend(p for p in candidates if "." in p)
+
+        # Also parse file paths from the response for review_changes/investigate
+        if isinstance(tool_response, str):
+            for line in tool_response.split("\n"):
+                line = line.strip()
+                # Match "## path/to/file.py" from compress output
+                if line.startswith("## ") and "." in line:
+                    candidate = line[3:].split(" ")[0].strip()
+                    if Path(candidate).suffix.lower() in EDITABLE_EXTS:
+                        files.append(candidate)
+
+    return files
+
+
+def main():
+    try:
+        raw = sys.stdin.read()
+        if not raw.strip():
+            return
+
+        data = json.loads(raw)
+        tool_name = data.get("tool_name", "")
+
+        if tool_name not in HANDLED_TOOLS:
+            return
+
+        # Detect IDE format
+        is_gemini = isinstance(data.get("tool_response", ""), dict)
+
+        tool_input = data.get("tool_input", {})
+        tool_response = data.get("tool_response", "")
+        if isinstance(tool_response, dict):
+            tool_response = str(tool_response.get("llmContent", ""))
+
+        # Extract file paths touched by this tool
+        touched = _extract_files_from_tool(tool_name, tool_input, tool_response)
+
+        # Filter to editable extensions only
+        editable = [p for p in touched if Path(p).suffix.lower() in EDITABLE_EXTS]
+        if not editable:
+            return
+
+        # Load existing pending set and add new files
+        pending = _load_pending()
+        new_files = [p for p in editable if p not in pending]
+        if not new_files:
+            # All files already pending — skip duplicate nudge
+            return
+
+        pending.update(new_files)
+        _save_pending(pending)
+
+        # Record sticky unlocks so enforcement hook allows future native
+        # tool calls on these files without requiring a fresh c3_* call
+        unlock_path = Path.cwd() / ".c3" / "unlocked_files.txt"
+        try:
+            existing = set(
+                line.strip() for line in
+                unlock_path.read_text(encoding="utf-8").splitlines()
+                if line.strip()
+            ) if unlock_path.exists() else set()
+            for fp in editable:
+                resolved = str(Path(fp).resolve())
+                existing.add(resolved)
+            unlock_path.parent.mkdir(parents=True, exist_ok=True)
+            unlock_path.write_text(
+                "\n".join(sorted(existing)) + "\n",
+                encoding="utf-8",
+            )
+        except Exception:
+            pass
+
+        # Emit batched nudge with all pending files
+        # Prefer c3_edit (no unlock needed). Native Edit is also unlocked via sticky file set.
+        if len(pending) == 1:
+            fp = next(iter(pending))
+            msg = (
+                f'[c3:edit-ready] "{fp}" unlocked for editing. '
+                f'Use c3_edit(file_path="{fp}", old_string=..., new_string=...) — preferred. '
+                f'Native Edit also unlocked (Read(limit=1) first if Claude Code requires it).'
+            )
+        else:
+            files_list = ", ".join(f'"{p}"' for p in sorted(pending))
+            msg = (
+                f"[c3:edit-ready] {len(pending)} files unlocked for editing: {files_list}. "
+                f"Use c3_edit(file_path=...) for each — preferred. "
+                f"Native Edit also unlocked (Read(limit=1) first if Claude Code requires it)."
+            )
+
+        emit_additional_context(msg, is_gemini)
+    except Exception as _e:
+        log_hook_error("hook_edit_unlock", _e)
+
+
+if __name__ == "__main__":
+    main()

cli/hook_filter.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""PostToolUse/AfterTool hook for Bash/run_shell_command — filter noisy terminal output via C3.
+
+Reads tool result JSON from stdin. If filtering yields meaningful savings, writes a
+replacement `tool_result` (Claude) or `additionalContext` (Gemini). Otherwise emits
+compact hints to encourage token-safe follow-up actions.
+
+Claude Code — register in .claude/settings.local.json:
+  "hooks": {"PostToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "python cli/hook_filter.py"}]}]}
+
+Gemini CLI — register in .gemini/settings.json:
+  "hooks": {"AfterTool": [{"matcher": "run_shell_command", "hooks": [{"type": "command", "command": "python cli/hook_filter.py"}]}]}
+"""
+import json
+import re
+import sys
+from pathlib import Path
+
+# Lines threshold to suggest c3_delegate summarize
+LONG_OUTPUT_LINES = 80
+# Lines threshold to nudge explicit c3_filter usage
+FILTER_HINT_LINES = 20
+
+# Patterns that indicate an error/failure worth diagnosing
+_ERROR_PATTERNS = re.compile(
+    r"(Traceback \(most recent call last\)|\bError:|\bException:|\bFAILED\b|\bERROR\b)",
+    re.MULTILINE,
+)
+
+# Add project root to path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from cli._hook_utils import (  # noqa: E402
+    emit_additional_context,
+    emit_filtered_output,
+    get_tool_output,
+    log_hook_error,
+    normalize_tool_name,
+)
+
+
+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 != "Bash":
+            return
+
+        output, is_gemini = get_tool_output(data)
+        if not output or not isinstance(output, str):
+            return
+        line_count = output.count("\n") + 1
+
+        from core.config import load_hybrid_config
+        from services.output_filter import OutputFilter
+
+        # Determine project path from cwd
+        project_path = str(Path.cwd())
+        config = load_hybrid_config(project_path)
+
+        if config.get("HYBRID_DISABLE_TIER1"):
+            return
+
+        # Filter medium/large outputs; short outputs still get hints.
+        if len(output) >= 200:
+            filt = OutputFilter(config)
+            result = filt.filter(output, use_llm=True)
+
+            # Only replace if meaningful savings (>10%)
+            if result["savings_pct"] > 10:
+                # Store original for c3_raw retrieval
+                raw_cache = Path(project_path) / ".c3" / "last_raw_output.txt"
+                raw_cache.parent.mkdir(parents=True, exist_ok=True)
+                raw_cache.write_text(output, encoding="utf-8")
+
+                filtered = result["filtered"]
+                if not filtered.startswith("[c3:filter"):
+                    prefix = f"[c3:filter:pass{result['pass_used']}|{result['savings_pct']}%saved] "
+                    filtered = prefix + filtered
+
+                emit_filtered_output(filtered, is_gemini)
+                return
+
+        # Output was not replaced - provide hints.
+        hints = _build_hints(output, line_count=line_count)
+        if hints:
+            emit_additional_context(hints, is_gemini)
+
+    except Exception as _e:
+        log_hook_error("hook_filter", _e)
+
+
+def _build_hints(output: str, line_count: int | None = None) -> str:
+    """Return [c3:hint] lines suggesting token-safe next actions."""
+    hints = []
+    if line_count is None:
+        line_count = output.count("\n") + 1
+
+    if line_count >= FILTER_HINT_LINES:
+        hints.append(
+            f"[c3:hint:filter] Output is {line_count} lines. "
+            "Run c3_filter(text='<raw output>') before further analysis to reduce token noise."
+        )
+
+    # Error/traceback detected - suggest diagnose
+    if _ERROR_PATTERNS.search(output):
+        hints.append(
+            "[c3:hint:delegate] Error output detected. "
+            "Use c3_delegate(task_type='diagnose', task='<describe the error>') "
+            "to root-cause it with a local LLM and save Claude tokens."
+        )
+
+    # Very long output - suggest summarize
+    if line_count >= LONG_OUTPUT_LINES and not _ERROR_PATTERNS.search(output):
+        hints.append(
+            f"[c3:hint:delegate] Output is {line_count} lines. "
+            "Use c3_delegate(task_type='summarize', task='summarize this output', context='<paste key lines>')."
+        )
+
+    return "\n".join(hints)
+
+
+if __name__ == "__main__":
+    main()

cli/hook_ghost_files.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+"""PostToolUse hook for Bash: detect and warn about ghost files.
+
+Ghost files are 0-byte (or near-0) files created in the project root when
+shell metacharacters in Bash commands are misinterpreted — e.g., Python type
+annotations like `-> dict` becoming `> dict` (output redirect), or pip
+specifiers like `flask>=3.0.0` becoming `> =3.0.0`.
+
+Runs after every Bash tool call. Scans the project root (non-recursively) for
+files that match ghost-file heuristics and emits a warning + auto-deletes them.
+
+Supports both Claude Code (PostToolUse) and Gemini CLI (AfterTool).
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from cli._hook_utils import emit_additional_context, log_hook_error  # noqa: E402
+
+# ── Ghost-file detection heuristics ──────────────────────────────────────────
+
+# Python builtin / typing names that should never be standalone files
+_PYTHON_TYPE_NAMES = {
+    "dict", "str", "int", "float", "bool", "list", "set", "tuple",
+    "bytes", "bytearray", "complex", "frozenset", "memoryview",
+    "type", "object", "range", "slice", "property", "classmethod",
+    "staticmethod", "super", "None", "True", "False", "Ellipsis",
+    # typing module
+    "Any", "Union", "Optional", "List", "Dict", "Set", "Tuple",
+    "Callable", "Iterator", "Generator", "Sequence", "Mapping",
+    "Awaitable", "Coroutine", "AsyncIterator", "AsyncGenerator",
+}
+
+# Max file size to consider a ghost (bytes). Genuine files are usually larger.
+_MAX_GHOST_SIZE = 4096
+
+# Version-number pattern: 3.0.0, 1.2, 10.20.30 — usually from pip specifiers.
+import re as _re
+
+_VERSION_RE = _re.compile(r"^\d+(\.\d+)+[`'\"$|]*$")
+
+# Extensions that are definitely NOT ghost files
+_SAFE_EXTENSIONS = {
+    ".py", ".js", ".ts", ".tsx", ".jsx", ".go", ".rs", ".java",
+    ".rb", ".c", ".cpp", ".h", ".cs", ".html", ".css", ".scss",
+    ".json", ".yaml", ".yml", ".toml", ".sql", ".md", ".txt",
+    ".sh", ".bat", ".ps1", ".r", ".xml", ".csv", ".ini", ".cfg",
+    ".lock", ".log", ".png", ".jpg", ".jpeg", ".gif", ".svg",
+    ".ico", ".woff", ".woff2", ".ttf", ".eot", ".map", ".gz",
+    ".zip", ".tar", ".whl", ".egg", ".pyc", ".pyo", ".so",
+    ".dll", ".exe", ".bin", ".dat", ".db", ".sqlite", ".gitignore",
+    ".gitattributes", ".editorconfig", ".prettierrc", ".eslintrc",
+    ".flake8", ".mypy", ".env", ".dockerignore", ".pdf",
+}
+
+# Known legitimate root-level files (no extension) in typical projects
+_SAFE_NAMES = {
+    "Makefile", "Dockerfile", "Procfile", "Vagrantfile", "Gemfile",
+    "Rakefile", "Brewfile", "Pipfile", "LICENSE", "CHANGELOG",
+    "CONTRIBUTING", "AUTHORS", "CODEOWNERS", "Makefile.am",
+}
+
+
+def _is_ghost_file(path: Path) -> bool:
+    """Return True if a file in the project root looks like a ghost."""
+    name = path.name
+
+    # Skip dotfiles/directories
+    if name.startswith("."):
+        return False
+
+    # Skip directories
+    if path.is_dir():
+        return False
+
+    suffix = path.suffix.lower()
+
+    # Skip files with safe extensions (real code/config files)
+    if suffix and suffix in _SAFE_EXTENSIONS:
+        return False
+
+    # Skip known legitimate extensionless files
+    if name in _SAFE_NAMES:
+        return False
+
+    # Skip files that are too large to be ghosts
+    try:
+        size = path.stat().st_size
+    except OSError:
+        return False
+
+    if size > _MAX_GHOST_SIZE:
+        return False
+
+    # Treat a "suffix" as real only if it matches a letter-led pattern
+    # (e.g. ".py", ".json"). Things like ".0" or ".0`" from a version
+    # string like "3.0.0`" are NOT real extensions — they're shell-redirect
+    # artifacts, and were escaping the 0-byte-extensionless filter below.
+    real_suffix = suffix and suffix[1:2].isalpha()
+
+    # ── Positive signals ─────────────────────────────────────
+
+    # Bare Python type name (e.g., "dict", "str")
+    if name in _PYTHON_TYPE_NAMES:
+        return True
+
+    # Partial type annotation (e.g., "tuple[float", "dict[str")
+    if "[" in name and not real_suffix:
+        return True
+
+    # Partial function-call syntax (e.g., "parseApiResponse(await")
+    # — fragments of JS/Python that Bash tokenized as a filename.
+    if ("(" in name or ")" in name) and not real_suffix:
+        return True
+
+    # Shell redirect artifact: starts with = (e.g., "=3.0.0" from >=3.0.0)
+    if name.startswith("="):
+        return True
+
+    # Starts with > or < (rare but possible)
+    if name.startswith(">") or name.startswith("<"):
+        return True
+
+    # Trailing backtick or other metacharacter — command-substitution leakage
+    if name.endswith("`") or name.endswith("$") or name.endswith("|"):
+        return True
+
+    # Version-like name (e.g., "3.0.0", "3.0.0`") without a real extension
+    # — classic `pip install foo>=3.0.0` ghost.
+    if size == 0 and not real_suffix and _VERSION_RE.match(name):
+        return True
+
+    # 0-byte file with no real extension and not in safe names
+    if size == 0 and not real_suffix:
+        return True
+
+    return False
+
+
+def scan_ghost_files(project_root: Path) -> list[dict]:
+    """Scan project root for ghost files. Returns list of {path, name, size, reason}."""
+    ghosts = []
+    try:
+        for entry in project_root.iterdir():
+            if not entry.is_file():
+                continue
+            if not _is_ghost_file(entry):
+                continue
+            size = entry.stat().st_size
+            name = entry.name
+
+            # Determine reason
+            if name in _PYTHON_TYPE_NAMES:
+                reason = "Python type name"
+            elif "[" in name:
+                reason = "partial type annotation"
+            elif "(" in name or ")" in name:
+                reason = "partial function-call syntax"
+            elif name.startswith("="):
+                reason = "pip version redirect (>=X.Y.Z)"
+            elif name.startswith(">") or name.startswith("<"):
+                reason = "shell redirect artifact"
+            elif name.endswith("`") or name.endswith("$") or name.endswith("|"):
+                reason = "shell metacharacter leak"
+            elif _VERSION_RE.match(name):
+                reason = "version-number leak (pip specifier)"
+            elif size == 0:
+                reason = "0-byte extensionless file"
+            else:
+                reason = "suspicious extensionless file"
+
+            ghosts.append({
+                "path": str(entry),
+                "name": name,
+                "size": size,
+                "reason": reason,
+            })
+    except OSError:
+        pass
+    return ghosts
+
+
+def cleanup_ghost_files(ghosts: list[dict]) -> list[str]:
+    """Delete ghost files. Returns list of successfully deleted names."""
+    deleted = []
+    for g in ghosts:
+        try:
+            os.remove(g["path"])
+            deleted.append(g["name"])
+        except OSError:
+            pass
+    return deleted
+
+
+def main():
+    try:
+        raw = sys.stdin.read()
+        if not raw.strip():
+            return
+
+        data = json.loads(raw)
+        tool_name = data.get("tool_name", "")
+
+        # Only trigger on Bash (Claude Code) or run_shell_command (Gemini)
+        if tool_name not in ("Bash", "run_shell_command"):
+            return
+
+        is_gemini = isinstance(data.get("tool_response", ""), dict)
+        project_root = Path.cwd()
+
+        ghosts = scan_ghost_files(project_root)
+        if not ghosts:
+            return
+
+        # Auto-delete ghost files
+        deleted = cleanup_ghost_files(ghosts)
+
+        if deleted:
+            names = ", ".join(f'"{n}"' for n in deleted)
+            msg = (
+                f"[c3:ghost-cleanup] Deleted {len(deleted)} ghost file(s) from project root: {names}. "
+                f"These were created by shell metacharacter misinterpretation in Bash commands "
+                f"(e.g., `> dict` from `-> dict` in Python type annotations, "
+                f"or `> =3.0.0` from `>=3.0.0` in pip specifiers). "
+                f"Tip: quote Bash commands carefully to avoid shell redirects."
+            )
+            emit_additional_context(msg, is_gemini)
+
+    except Exception as _e:
+        log_hook_error("hook_ghost_files", _e)
+
+
+if __name__ == "__main__":
+    main()