code-context-control 2.40.0__py3-none-any.whl → 2.42.0__py3-none-any.whl

cli/_hook_utils.py

@@ -1,5 +1,12 @@
-"""Shared utilities for C3 hook scripts — supports Claude Code and Gemini CLI."""
+"""Shared utilities for C3 hook scripts — supports Claude Code and Gemini CLI.
+
+Also owns the consolidated enforcement state (.c3/enforcement_state.json):
+a single file replacing the previous trio of last_c3_call.json,
+unlocked_files.json, and ad-hoc writers spread across four hook scripts.
+All hook reads/writes of enforcement state MUST go through this module.
+"""
 import json
+import os
 import sys
 import traceback
 from datetime import datetime, timezone
@@ -8,6 +15,23 @@ from pathlib import Path
 # Max size of hook_errors.log before it is rotated (50 KB)
 _LOG_MAX_BYTES = 50 * 1024
 
+# ── Consolidated enforcement state ───────────────────────────────────────────
+# Canonical file (the ONLY file written from v2.42 on):
+#   {
+#     "session_id": "<claude session id or ''>",
+#     "last_c3_call": {"ts": "<ISO UTC>", "tool": "c3_search", "read_unlocked": true},
+#     "unlocked_files": {"<resolved path>": ["read", "edit"]}
+#   }
+# Legacy files (READ as fallback for one release; never written anymore):
+ENFORCEMENT_STATE_FILE = ".c3/enforcement_state.json"
+LEGACY_SIGNAL_FILE = ".c3/last_c3_call.json"
+LEGACY_UNLOCK_FILE = ".c3/unlocked_files.json"
+
+# Critical state-layer warnings (e.g. corrupted state JSON) surfaced by the
+# dispatcher as an additionalContext line so enforcement never silently stops
+# enforcing. Drained via drain_state_warnings().
+STATE_WARNINGS: list = []
+
 
 def log_hook_error(hook_name: str, exc: BaseException) -> None:
     """Append a timestamped error entry to .c3/hook_errors.log.
@@ -34,6 +58,161 @@ def log_hook_error(hook_name: str, exc: BaseException) -> None:
     except Exception:
         pass  # Absolutely must not propagate
 
+def drain_state_warnings() -> list:
+    """Return and clear accumulated critical state warnings.
+
+    Called by the dispatcher after each sub-hook so corruption events become
+    a visible "[c3:hook-error] ..." additionalContext line instead of a
+    silent enforcement gap.
+    """
+    warnings = STATE_WARNINGS[:]
+    STATE_WARNINGS.clear()
+    return warnings
+
+
+def _empty_state(session_id: str = "") -> dict:
+    return {"session_id": session_id or "", "last_c3_call": None, "unlocked_files": {}}
+
+
+def _atomic_write_json(path: Path, data: dict) -> None:
+    """Write JSON atomically: temp file in the same directory + os.replace."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f"{path.name}.tmp{os.getpid()}")
+    tmp.write_text(json.dumps(data), encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def _read_legacy_state(base: Path) -> dict:
+    """Build a state view from the pre-v2.42 files (read-only fallback)."""
+    state = _empty_state()
+    signal_path = base / LEGACY_SIGNAL_FILE
+    if signal_path.exists():
+        try:
+            data = json.loads(signal_path.read_text(encoding="utf-8"))
+            if isinstance(data, dict) and data.get("timestamp"):
+                state["last_c3_call"] = {
+                    "ts": str(data.get("timestamp")),
+                    "tool": str(data.get("tool", "")),
+                    "read_unlocked": bool(data.get("read_unlocked", False)),
+                }
+        except Exception:
+            pass  # Legacy file corruption is not critical — new file supersedes it
+    unlock_path = base / LEGACY_UNLOCK_FILE
+    if unlock_path.exists():
+        try:
+            data = json.loads(unlock_path.read_text(encoding="utf-8"))
+            if isinstance(data, dict):
+                state["unlocked_files"] = {
+                    str(k): list(v) for k, v in data.items() if isinstance(v, list)
+                }
+        except Exception:
+            pass
+    return state
+
+
+def load_enforcement_state(project_path: Path | None = None, session_id: str = "") -> dict:
+    """Load consolidated enforcement state with legacy fallback + session scoping.
+
+    - Missing new file → read legacy last_c3_call.json / unlocked_files.json
+      (one-release migration path; writes only ever go to the new file).
+    - Corrupted new file → quarantine to *.corrupt, log, push a critical
+      warning to STATE_WARNINGS, and return empty state (fail-open to the
+      advisory path, never a hard-deny surprise).
+    - session_id mismatch → state written by another session is STALE:
+      return empty state for the current session.
+    """
+    base = project_path if project_path is not None else Path.cwd()
+    state_path = base / ENFORCEMENT_STATE_FILE
+    state = None
+    if state_path.exists():
+        try:
+            data = json.loads(state_path.read_text(encoding="utf-8"))
+            if not isinstance(data, dict):
+                raise ValueError("enforcement_state.json root is not an object")
+            state = _empty_state()
+            state["session_id"] = str(data.get("session_id") or "")
+            last_call = data.get("last_c3_call")
+            state["last_c3_call"] = last_call if isinstance(last_call, dict) else None
+            unlocked = data.get("unlocked_files")
+            state["unlocked_files"] = unlocked if isinstance(unlocked, dict) else {}
+        except Exception as exc:
+            log_hook_error("enforcement_state", exc)
+            try:
+                state_path.replace(state_path.with_name(state_path.name + ".corrupt"))
+            except Exception:
+                pass
+            STATE_WARNINGS.append(
+                "[c3:hook-error] enforcement_state: corrupted "
+                f"{ENFORCEMENT_STATE_FILE} quarantined ({type(exc).__name__}); "
+                "see .c3/hook_errors.log"
+            )
+            return _empty_state(session_id)
+    if state is None:
+        state = _read_legacy_state(base)
+    # Session scoping: hook payloads carry session_id; state from a different
+    # session must not grant unlocks (signal files used to survive /clear).
+    if session_id and state.get("session_id") and state["session_id"] != session_id:
+        return _empty_state(session_id)
+    return state
+
+
+def save_enforcement_state(state: dict, project_path: Path | None = None) -> None:
+    """Atomically persist the consolidated enforcement state."""
+    base = project_path if project_path is not None else Path.cwd()
+    try:
+        _atomic_write_json(base / ENFORCEMENT_STATE_FILE, state)
+    except Exception as exc:
+        log_hook_error("enforcement_state", exc)
+
+
+def record_c3_signal(
+    tool: str,
+    read_unlocked: bool,
+    session_id: str = "",
+    project_path: Path | None = None,
+) -> None:
+    """Record 'a c3_* tool just completed' in the consolidated state."""
+    state = load_enforcement_state(project_path, session_id=session_id)
+    if session_id:
+        state["session_id"] = session_id
+    state["last_c3_call"] = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "tool": tool,
+        "read_unlocked": bool(read_unlocked),
+    }
+    save_enforcement_state(state, project_path)
+
+
+def record_unlocked_files(
+    paths,
+    categories,
+    session_id: str = "",
+    project_path: Path | None = None,
+) -> None:
+    """Merge sticky per-file unlock categories into the consolidated state."""
+    cats_to_add = {c for c in categories if c}
+    if not cats_to_add:
+        return
+    state = load_enforcement_state(project_path, session_id=session_id)
+    if session_id:
+        state["session_id"] = session_id
+    changed = False
+    for fp in paths:
+        if not fp:
+            continue
+        try:
+            normalized = str(Path(fp).resolve())
+        except OSError:
+            continue
+        cats = set(state["unlocked_files"].get(normalized, []))
+        merged = sorted(cats | cats_to_add)
+        if merged != state["unlocked_files"].get(normalized):
+            state["unlocked_files"][normalized] = merged
+            changed = True
+    if changed:
+        save_enforcement_state(state, project_path)
+
+
 # Map Gemini CLI built-in tool names → canonical Claude Code equivalents
 GEMINI_TOOL_MAP = {
     "run_shell_command": "Bash",
@@ -84,34 +263,23 @@ def get_tool_input_path(data: dict) -> str:
     )
 
 
-def record_json_unlocks(editable: list, project_path: Path | None = None) -> None:
-    """Record file paths as read+edit unlocked in .c3/unlocked_files.json.
+def record_json_unlocks(
+    editable: list,
+    project_path: Path | None = None,
+    session_id: str = "",
+) -> None:
+    """Record file paths as read+edit unlocked in the enforcement state.
 
-    This is the map that hook_pretool_enforce.py actually reads (the plain
-    .txt unlock list is not consumed by any hook). Mirrors the behaviour of
-    cli/hook_c3read._record_json_unlocks so c3_compress/c3_agent sticky
-    unlocks reach the enforcer. Fails silently on I/O errors.
+    Compatibility wrapper kept for existing callers (hook_edit_unlock,
+    hook_c3read): unlocks now land in .c3/enforcement_state.json via the
+    consolidated state layer instead of the legacy unlocked_files.json.
+    Fails silently on I/O errors.
     """
-    base = project_path if project_path is not None else Path.cwd()
-    json_path = base / ".c3" / "unlocked_files.json"
     try:
-        existing: dict = {}
-        if json_path.exists():
-            try:
-                existing = json.loads(json_path.read_text(encoding="utf-8"))
-                if not isinstance(existing, dict):
-                    existing = {}
-            except Exception:
-                existing = {}
-        for fp in editable:
-            if not fp:
-                continue
-            normalized = str(Path(fp).resolve())
-            cats = set(existing.get(normalized, []))
-            cats.update({"read", "edit"})
-            existing[normalized] = sorted(cats)
-        json_path.parent.mkdir(parents=True, exist_ok=True)
-        json_path.write_text(json.dumps(existing), encoding="utf-8")
+        record_unlocked_files(
+            editable, {"read", "edit"},
+            session_id=session_id, project_path=project_path,
+        )
     except Exception:
         pass
 

cli/c3.py

@@ -85,7 +85,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.40.0"
+__version__ = "2.42.0"
 
 
 def _command_deps() -> CommandDeps:
@@ -4448,7 +4448,7 @@ def _uninstall_mcp_all(project_path: str):
                     # Remove hooks
                     hooks = settings.get("hooks", {}).get("PostToolUse", [])
                     new_hooks = []
-                    c3_hook_files = {"hook_filter.py", "hook_read.py", "hook_c3read.py"}
+                    c3_hook_files = {"hook_filter.py", "hook_read.py", "hook_c3read.py", "hook_dispatch.py"}
                     for h in hooks:
                         if h.get("matcher") in ("Bash", "Read", "mcp__c3__c3_read"):
                             h["hooks"] = [hook for hook in h.get("hooks", [])
@@ -5011,17 +5011,16 @@ def cmd_install_mcp(args):
         # file; "cmd /c …" returns "cmd: command not found"). The single-quoted paths are
         # correct — bash strips them and re-quotes for cmd.exe, preserving spaces/parens.
         _hook_prefix = "cmd.exe /c " if sys.platform == "win32" else ""
-        hook_filter_cmd    = f"{_hook_prefix}{shlex.quote(sys.executable)} {shlex.quote(str(cli_dir / 'hook_filter.py'))}"
-        hook_read_cmd      = f"{_hook_prefix}{shlex.quote(sys.executable)} {shlex.quote(str(cli_dir / 'hook_read.py'))}"
-        hook_c3read_cmd    = f"{_hook_prefix}{shlex.quote(sys.executable)} {shlex.quote(str(cli_dir / 'hook_c3read.py'))}"
-        hook_enforce_cmd   = f"{_hook_prefix}{shlex.quote(sys.executable)} {shlex.quote(str(cli_dir / 'hook_pretool_enforce.py'))}"
-        hook_edit_unlock_cmd = f"{_hook_prefix}{shlex.quote(sys.executable)} {shlex.quote(str(cli_dir / 'hook_edit_unlock.py'))}"
-        hook_edit_ledger_cmd = f"{_hook_prefix}{shlex.quote(sys.executable)} {shlex.quote(str(cli_dir / 'hook_edit_ledger.py'))}"
-        hook_ghost_files_cmd = f"{_hook_prefix}{shlex.quote(sys.executable)} {shlex.quote(str(cli_dir / 'hook_ghost_files.py'))}"
-        hook_session_stats_cmd = f"{_hook_prefix}{shlex.quote(sys.executable)} {shlex.quote(str(cli_dir / 'hook_session_stats.py'))}"
-        hook_auto_snapshot_cmd = f"{_hook_prefix}{shlex.quote(sys.executable)} {shlex.quote(str(cli_dir / 'hook_auto_snapshot.py'))}"
-        hook_terse_advisor_cmd = f"{_hook_prefix}{shlex.quote(sys.executable)} {shlex.quote(str(cli_dir / 'hook_terse_advisor.py'))}"
-        hook_c3_signal_cmd = f"{_hook_prefix}{shlex.quote(sys.executable)} {shlex.quote(str(cli_dir / 'hook_c3_signal.py'))}"
+        # v2.42: single dispatcher script per hook event instead of N separate
+        # per-hook commands. One interpreter spawn per event; the dispatcher
+        # (cli/hook_dispatch.py) runs all applicable sub-hooks in-process.
+        _dispatch_base = (
+            f"{_hook_prefix}{shlex.quote(sys.executable)} "
+            f"{shlex.quote(str(cli_dir / 'hook_dispatch.py'))}"
+        )
+        hook_pretool_cmd  = f"{_dispatch_base} pretool"
+        hook_posttool_cmd = f"{_dispatch_base} posttool"
+        hook_stop_cmd     = f"{_dispatch_base} stop"
 
         # Tool matcher names differ by IDE: Gemini uses snake_case built-in names.
         if profile.name == "gemini":
@@ -5045,130 +5044,48 @@ def cmd_install_mcp(args):
             extra_edit_matchers = ["MultiEdit", "NotebookEdit"]
 
         # ── PostToolUse hooks ──
+        # Matcher set is unchanged from pre-v2.42; every matcher now points at
+        # the single posttool dispatcher (which sub-hooks run for which tool
+        # moved into cli/hook_dispatch.py). One spawn per event instead of
+        # up to three.
+        _post_matcher_names = [
+            shell_matcher,
+            read_matcher,
+            "mcp__c3__c3_read",
+            "mcp__c3__c3_shell",
+            "mcp__c3__c3_search",
+            "mcp__c3__c3_compress",
+            "mcp__c3__c3_filter",
+            "mcp__c3__c3_memory",
+            "mcp__c3__c3_validate",
+            "mcp__c3__c3_edit",
+            "mcp__c3__c3_edits",
+            "mcp__c3__c3_impact",
+            "mcp__c3__c3_status",
+            "mcp__c3__c3_delegate",
+            "mcp__c3__c3_session",
+            "mcp__c3__c3_agent",
+            edit_matcher,
+            write_matcher,
+            *extra_edit_matchers,
+        ]
         desired_post_hooks = [
-            {
-                "matcher": shell_matcher,
-                "hooks": [
-                    {"type": "command", "command": hook_filter_cmd},
-                    {"type": "command", "command": hook_ghost_files_cmd},
-                ]
-            },
-            {
-                "matcher": read_matcher,
-                "hooks": [
-                    {"type": "command", "command": hook_read_cmd},
-                    {"type": "command", "command": hook_ghost_files_cmd},
-                ]
-            },
-            {
-                "matcher": "mcp__c3__c3_read",
-                "hooks": [
-                    {"type": "command", "command": hook_c3read_cmd},
-                    {"type": "command", "command": hook_c3_signal_cmd},
-                    {"type": "command", "command": hook_ghost_files_cmd},
-                ]
-            },
-            {
-                "matcher": "mcp__c3__c3_shell",
-                "hooks": [
-                    {"type": "command", "command": hook_c3_signal_cmd},
-                    {"type": "command", "command": hook_ghost_files_cmd},
-                ]
-            },
-            {
-                "matcher": "mcp__c3__c3_search",
-                "hooks": [{"type": "command", "command": hook_c3_signal_cmd}]
-            },
-            {
-                "matcher": "mcp__c3__c3_compress",
-                "hooks": [
-                    {"type": "command", "command": hook_edit_unlock_cmd},
-                    {"type": "command", "command": hook_c3_signal_cmd},
-                ]
-            },
-            {
-                "matcher": "mcp__c3__c3_filter",
-                "hooks": [{"type": "command", "command": hook_c3_signal_cmd}]
-            },
-            {
-                "matcher": "mcp__c3__c3_memory",
-                "hooks": [{"type": "command", "command": hook_c3_signal_cmd}]
-            },
-            {
-                "matcher": "mcp__c3__c3_validate",
-                "hooks": [{"type": "command", "command": hook_c3_signal_cmd}]
-            },
-            {
-                "matcher": "mcp__c3__c3_edit",
-                "hooks": [{"type": "command", "command": hook_c3_signal_cmd}]
-            },
-            {
-                "matcher": "mcp__c3__c3_edits",
-                "hooks": [{"type": "command", "command": hook_c3_signal_cmd}]
-            },
-            {
-                "matcher": "mcp__c3__c3_impact",
-                "hooks": [{"type": "command", "command": hook_c3_signal_cmd}]
-            },
-            {
-                "matcher": "mcp__c3__c3_status",
-                "hooks": [{"type": "command", "command": hook_c3_signal_cmd}]
-            },
-            {
-                "matcher": "mcp__c3__c3_delegate",
-                "hooks": [{"type": "command", "command": hook_c3_signal_cmd}]
-            },
-            {
-                "matcher": "mcp__c3__c3_session",
-                "hooks": [{"type": "command", "command": hook_c3_signal_cmd}]
-            },
-            {
-                "matcher": "mcp__c3__c3_agent",
-                "hooks": [
-                    {"type": "command", "command": hook_edit_unlock_cmd},
-                    {"type": "command", "command": hook_c3_signal_cmd},
-                ]
-            },
-            {
-                "matcher": edit_matcher,
-                "hooks": [{"type": "command", "command": hook_edit_ledger_cmd}]
-            },
-            {
-                "matcher": write_matcher,
-                "hooks": [{"type": "command", "command": hook_edit_ledger_cmd}]
-            },
-            *[
-                {"matcher": m, "hooks": [{"type": "command", "command": hook_edit_ledger_cmd}]}
-                for m in extra_edit_matchers
-            ],
+            {"matcher": m, "hooks": [{"type": "command", "command": hook_posttool_cmd}]}
+            for m in _post_matcher_names
         ]
 
         # ── PreToolUse hooks (enforcement — blocks native tools without prior c3_*) ──
+        _pre_matcher_names = [
+            read_matcher,
+            grep_matcher,
+            glob_matcher,
+            edit_matcher,
+            write_matcher,
+            *extra_edit_matchers,
+        ]
         desired_pre_hooks = [
-            {
-                "matcher": read_matcher,
-                "hooks": [{"type": "command", "command": hook_enforce_cmd}]
-            },
-            {
-                "matcher": grep_matcher,
-                "hooks": [{"type": "command", "command": hook_enforce_cmd}]
-            },
-            {
-                "matcher": glob_matcher,
-                "hooks": [{"type": "command", "command": hook_enforce_cmd}]
-            },
-            {
-                "matcher": edit_matcher,
-                "hooks": [{"type": "command", "command": hook_enforce_cmd}]
-            },
-            {
-                "matcher": write_matcher,
-                "hooks": [{"type": "command", "command": hook_enforce_cmd}]
-            },
-            *[
-                {"matcher": m, "hooks": [{"type": "command", "command": hook_enforce_cmd}]}
-                for m in extra_edit_matchers
-            ],
+            {"matcher": m, "hooks": [{"type": "command", "command": hook_pretool_cmd}]}
+            for m in _pre_matcher_names
         ]
 
         # Merge: replace existing C3 hooks (so re-running install-mcp updates commands),
@@ -5198,18 +5115,19 @@ def cmd_install_mcp(args):
             {
                 "matcher": "",
                 "hooks": [
-                    {"type": "command", "command": hook_session_stats_cmd},
-                    {"type": "command", "command": hook_auto_snapshot_cmd},
-                    {"type": "command", "command": hook_terse_advisor_cmd},
+                    {"type": "command", "command": hook_stop_cmd},
                 ]
             },
         ]
         stop_event = "Stop"
         # Replace only C3's own stop hooks (identified by our hook scripts) and
         # keep every user-added stop hook — including matcher-less ones, which
-        # are the normal shape for Stop hooks.
+        # are the normal shape for Stop hooks. The pre-v2.42 script names stay
+        # in this tuple so re-running install-mcp migrates old per-hook
+        # entries to the dispatcher.
         _c3_stop_scripts = (
             "hook_session_stats.py", "hook_auto_snapshot.py", "hook_terse_advisor.py",
+            "hook_dispatch.py",
         )
 
         def _is_c3_stop_hook(entry: dict) -> bool:
@@ -5259,9 +5177,9 @@ def cmd_install_mcp(args):
             json.dump(settings, f, indent=2)
 
         print(f"Wrote {settings_path}")
-        print(f"  Hooks ({hook_event}): {shell_matcher} (filter+ghost) + {read_matcher}/{edit_matcher}/{write_matcher} (ledger) + c3_read/c3_compress/c3_agent (unlock)")
-        print(f"  Hooks ({pre_event}): {read_matcher}/{grep_matcher}/{glob_matcher}/{edit_matcher}/{write_matcher} (c3 enforcement)")
-        print("  Hooks (Stop): session_stats + auto_snapshot")
+        print(f"  Hooks ({hook_event}): dispatcher (1 spawn/event) — filter/ghost/read-guard/ledger/unlock/signal via cli/hook_dispatch.py posttool")
+        print(f"  Hooks ({pre_event}): dispatcher — {read_matcher}/{grep_matcher}/{glob_matcher}/{edit_matcher}/{write_matcher} (c3 enforcement)")
+        print("  Hooks (Stop): dispatcher — session_stats + auto_snapshot + terse_advisor")
         if profile.name == "claude-code":
             print("  Claude MCP prompt settings enabled for this project")
         if perm_tier and profile.name == "claude-code":

cli/hook_auto_snapshot.py

@@ -52,9 +52,11 @@ def _call_server(port: int, stop_hook_data: dict) -> bool:
         return False
 
 
-def _fallback_snapshot(stop_hook_data: dict) -> None:
+def _fallback_snapshot(stop_hook_data: dict, base: Path | None = None) -> None:
     """Lightweight file-based snapshot when the UI server is not running."""
-    c3_dir = Path(".c3")
+    if base is None:
+        base = Path.cwd()
+    c3_dir = base / ".c3"
     if not c3_dir.exists():
         return
 
@@ -116,6 +118,19 @@ def _fallback_snapshot(stop_hook_data: dict) -> None:
         json.dump(snapshot, f, indent=2)
 
 
+def run(payload: dict, project_path: Path | None = None):
+    """Core logic — importable by the dispatcher and tests. Returns None."""
+    base = project_path if project_path is not None else Path.cwd()
+    port = _find_server_port(str(base))
+
+    if port and _call_server(port, payload):
+        return None
+
+    # Server not running or unreachable — fallback
+    _fallback_snapshot(payload, base)
+    return None
+
+
 def main() -> None:
     try:
         data = json.load(sys.stdin)
@@ -124,14 +139,7 @@ def main() -> None:
         sys.exit(0)
 
     try:
-        project_path = str(Path.cwd())
-        port = _find_server_port(project_path)
-
-        if port and _call_server(port, data):
-            sys.exit(0)
-
-        # Server not running or unreachable — fallback
-        _fallback_snapshot(data)
+        run(data)
     except Exception as exc:
         log_hook_error("hook_auto_snapshot", exc)
 

cli/hook_c3_signal.py

@@ -1,58 +1,65 @@
 """PostToolUse hook: record c3_* tool call signal for enforcement.
 
 Fires after: c3_search, c3_compress, c3_filter, c3_memory, c3_validate,
-             c3_session, c3_status, c3_impact, c3_agent, c3_shell.
+             c3_session, c3_status, c3_impact, c3_agent, c3_shell,
+             c3_read, c3_edit, c3_edits, c3_delegate.
 
-Writes .c3/last_c3_call.json:
+Writes the "last_c3_call" section of .c3/enforcement_state.json (via the
+consolidated state layer in cli/_hook_utils.py):
   {
-    "timestamp": "...",           ISO UTC timestamp
-    "tool": "c3_search",          short tool name (without mcp__c3__ prefix)
-    "read_unlocked": true/false   true for search/compress/filter
+    "session_id": "...",
+    "last_c3_call": {
+      "ts": "...",                  ISO UTC timestamp
+      "tool": "c3_search",          short tool name (without mcp__c3__ prefix)
+      "read_unlocked": true/false   true for search/compress/filter/read/impact/validate
+    },
+    ...
   }
 
-hook_pretool_enforce.py reads this file as the primary recency check.
-It replaces the fragile LOOKBACK-3 activity-log scan in long sessions.
+hook_pretool_enforce.py reads this as the primary recency check. Pre-v2.42
+installs wrote .c3/last_c3_call.json; that file is still read as a fallback
+for one release but is no longer written.
 """
 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
+from cli._hook_utils import log_hook_error, record_c3_signal  # noqa: E402
 
 # Tools that unlock generic read operations (Grep/Glob without a file path)
 _READ_UNLOCK_TOOLS = {"c3_search", "c3_compress", "c3_filter", "c3_read", "c3_impact", "c3_validate"}
 
-_SIGNAL_FILE = ".c3/last_c3_call.json"
 
+def run(payload: dict, project_path: Path | None = None):
+    """Record the c3_* signal in the consolidated enforcement state.
 
-def main() -> None:
-    try:
-        raw = sys.stdin.read()
-        if not raw.strip():
-            return
-
-        data = json.loads(raw)
-        raw_tool = data.get("tool_name", "")
+    Returns None — this hook produces no output for the model.
+    """
+    raw_tool = payload.get("tool_name", "")
 
-        # Strip mcp__c3__ prefix → short name (e.g. "c3_search")
-        short_name = raw_tool.replace("mcp__c3__", "") if "mcp__c3__" in raw_tool else raw_tool
+    # Strip mcp__c3__ prefix → short name (e.g. "c3_search")
+    short_name = raw_tool.replace("mcp__c3__", "") if "mcp__c3__" in raw_tool else raw_tool
 
-        if not short_name.startswith("c3_"):
-            return
+    if not short_name.startswith("c3_"):
+        return None
 
-        signal = {
-            "timestamp": datetime.now(timezone.utc).isoformat(),
-            "tool": short_name,
-            "read_unlocked": short_name in _READ_UNLOCK_TOOLS,
-        }
+    record_c3_signal(
+        short_name,
+        short_name in _READ_UNLOCK_TOOLS,
+        session_id=str(payload.get("session_id") or ""),
+        project_path=project_path,
+    )
+    return None
 
-        signal_path = Path.cwd() / _SIGNAL_FILE
-        signal_path.parent.mkdir(parents=True, exist_ok=True)
-        signal_path.write_text(json.dumps(signal, indent=2), encoding="utf-8")
 
+def main() -> None:
+    try:
+        raw = sys.stdin.read()
+        if not raw.strip():
+            return
+        run(json.loads(raw))
     except Exception as exc:
         log_hook_error("hook_c3_signal", exc)