@michelj/context-guard 0.4.3 → 0.6.1

package/scripts/context_guard_hook.py

@@ -1,25 +1,33 @@
 #!/usr/bin/env python3
-"""Lightweight lifecycle reminders for the Context Guard plugin.
-
-The hook initializes folder-scoped context on session/subagent start and nudges
-Codex to use the context-guard skill at the moments where omission is most
-costly: prompt intake, turn stop, and subagent stop.
-"""
+"""Normalize Codex, Cursor, and Claude lifecycle hooks for Context Guard."""
 
 from __future__ import annotations
 
+import argparse
 import json
+import hashlib
 import os
 import re
+import shlex
+import sqlite3
 import subprocess
 import sys
-from datetime import datetime
-from pathlib import Path
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path, PureWindowsPath
+from urllib.parse import quote, urlsplit
+
+from context_guard import acquire_hook_runtime_lock, append_session_event
+from context_guard import add_prompt_signal
+from context_guard import context_dir as context_folder
+from context_guard import configure_stdio, ensure_session_file, folder_root, init_context, is_context_guard_skill_path
+from context_guard import hook_runtime_lock, read_hook_runtime, read_json, require_human_work_review, start_workbench, utc_now
+from context_guard import safe_identifier, session_records, write_hook_runtime, write_json
+from context_guard import run_node_workbench
 
-from context_guard import approved_dev_completion_tests, context_dir, init_context, resolve_registered_subagent_root
+WINDOWS_NO_WINDOW = getattr(subprocess, "CREATE_NO_WINDOW", 0)
 
 
-SKILL_ROOT = Path(__file__).resolve().parents[1]
 WORKSPACE_KEYS = {
     "cwd",
     "current_working_directory",
@@ -28,6 +36,8 @@ WORKSPACE_KEYS = {
     "workspace_root",
     "workspaceFolder",
     "workspace_folder",
+    "workspace_roots",
+    "workspaceRoots",
     "project",
     "project_root",
     "projectRoot",
@@ -41,68 +51,53 @@ WORKSPACE_ENV_KEYS = [
     "CODEX_WORKSPACE_ROOT",
     "CODEX_PROJECT_ROOT",
     "CODEX_CWD",
+    "CURSOR_PROJECT_DIR",
+    "CURSOR_WORKSPACE_ROOT",
+    "CLAUDE_PROJECT_DIR",
+    "CLAUDE_WORKSPACE_ROOT",
     "WORKSPACE_ROOT",
     "PROJECT_ROOT",
     "PWD",
 ]
 
 
-def is_inside(path: Path, parent: Path) -> bool:
-    try:
-        path.resolve().relative_to(parent.resolve())
-        return True
-    except ValueError:
-        return False
-
-
-def is_context_guard_skill_path(path: Path) -> bool:
-    return is_inside(path, SKILL_ROOT)
-
-
-def git_root(cwd: Path) -> Path:
-    try:
-        out = subprocess.check_output(
-            ["git", "rev-parse", "--show-toplevel"],
-            cwd=str(cwd),
-            stderr=subprocess.DEVNULL,
-            text=True,
-            timeout=2,
-        ).strip()
-        if out:
-            return Path(out)
-    except Exception:
-        pass
-    return cwd
-
-
 def possible_workspace_paths(value: object) -> list[Path]:
     paths: list[Path] = []
 
     def add_path(candidate: object) -> None:
+        if isinstance(candidate, list):
+            for item in candidate:
+                add_path(item)
+            return
         if not isinstance(candidate, str):
             return
-        text = candidate.strip()
-        if not text or not text.startswith("/"):
+        text = os.path.expandvars(os.path.expanduser(candidate.strip()))
+        if not text:
             return
-        path = Path(text).expanduser()
+        is_absolute = Path(text).is_absolute() or PureWindowsPath(text).is_absolute()
+        if not is_absolute:
+            return
+        path = Path(text)
         if path.exists():
-            paths.append(path)
+            paths.append(path if path.is_dir() else path.parent)
 
-    def walk(obj: object, key_hint: str = "") -> None:
+    def walk(obj: object) -> None:
         if isinstance(obj, dict):
             for key, child in obj.items():
                 if key in WORKSPACE_KEYS:
                     add_path(child)
-                walk(child, key)
+                walk(child)
         elif isinstance(obj, list):
             for child in obj:
-                walk(child, key_hint)
+                walk(child)
 
     walk(value)
     return paths
 
 
 def parse_hook_payload(raw: str) -> object:
+    # Windows hook runners may prepend a UTF-8 BOM to otherwise valid JSON.
+    raw = raw.lstrip("\ufeff")
     if not raw.strip():
         return {}
     try:
@@ -111,743 +106,1997 @@ def parse_hook_payload(raw: str) -> object:
         return {}
 
 
-def hook_agent_id(payload: object) -> str:
-    keys = {"agent_id", "agentId", "subagent_id", "subagentId"}
-    found: list[str] = []
-
-    def walk(value: object) -> None:
-        if isinstance(value, dict):
-            for key, child in value.items():
-                if key in keys and isinstance(child, str) and child.strip():
-                    found.append(child.strip())
-                walk(child)
-        elif isinstance(value, list):
-            for child in value:
-                walk(child)
-
-    walk(payload)
-    return found[0] if found else ""
-
-
-def hook_text_field(payload: object, key: str) -> str:
-    if not isinstance(payload, dict):
-        return ""
-    value = payload.get(key)
-    return value.strip() if isinstance(value, str) else ""
-
-
-def registered_subagent_control_root(payload: object, cwd: Path, agent_id: str) -> Path | None:
-    if not agent_id:
-        return None
-    candidates = [*possible_workspace_paths(payload), cwd]
-    seen: set[Path] = set()
-    for path in candidates:
-        control_root = git_root(path).resolve()
-        if control_root in seen:
-            continue
-        seen.add(control_root)
-        if resolve_registered_subagent_root(control_root, agent_id):
-            return control_root
-    return None
+def initialized_source_project(root: Path) -> bool:
+    return (root / ".git").exists() and (root / ".codex" / "context" / "map.json").is_file()
 
 
-def event_root(raw: str, cwd: Path, event: str = "") -> tuple[Path, str]:
+def event_root(raw: str, cwd: Path) -> tuple[Path, str]:
     payload = parse_hook_payload(raw)
     candidates: list[tuple[Path, str]] = []
     for path in possible_workspace_paths(payload):
         candidates.append((path, "hook payload"))
     for key in WORKSPACE_ENV_KEYS:
         value = os.environ.get(key, "").strip()
-        if value.startswith("/"):
-            path = Path(value).expanduser()
-            if path.exists():
-                candidates.append((path, f"${key}"))
+        for path in possible_workspace_paths({"root": value}):
+            candidates.append((path, f"${key}"))
     candidates.append((cwd, "process cwd"))
-
-    agent_id = hook_agent_id(payload) if event in {"subagent-start", "subagent-stop"} else ""
-    control_root = registered_subagent_control_root(payload, cwd, agent_id)
-    if control_root:
-        assigned = resolve_registered_subagent_root(control_root, agent_id)
-        if assigned and not is_context_guard_skill_path(assigned):
-            return assigned, f"registered subagent assignment ({agent_id})"
-
     for path, source in candidates:
-        root = git_root(path)
-        if not is_context_guard_skill_path(root):
+        root = folder_root(path)
+        if not is_context_guard_skill_path(root) or initialized_source_project(root):
             return root, source
-
-    root = git_root(cwd)
-    return root, "process cwd"
+    return folder_root(cwd), "process cwd"
 
 
 def read_stdin() -> str:
     try:
-        return sys.stdin.read()
+        return sys.stdin.buffer.read().decode("utf-8", errors="replace")
     except Exception:
-        return ""
+        try:
+            return sys.stdin.read()
+        except Exception:
+            return ""
 
 
 def hook_log(message: str) -> None:
     print(message, file=sys.stderr)
 
 
-def hook_response(**payload: object) -> int:
-    print(json.dumps(payload, ensure_ascii=False))
-    return 0
+HOOK_EVENT_NAMES = {
+    "session-start": "SessionStart",
+    "subagent-start": "SubagentStart",
+    "user-prompt-submit": "UserPromptSubmit",
+    "stop": "Stop",
+    "subagent-stop": "SubagentStop",
+    "pre-tool-use": "PreToolUse",
+    "post-tool-use": "PostToolUse",
+    "post-tool-use-failure": "PostToolUseFailure",
+    "session-end": "SessionEnd",
+    "stop-failure": "StopFailure",
+    "permission-request": "PermissionRequest",
+    "interrupt": "Interrupt",
+    "pre-compact": "PreCompact",
+    "post-compact": "PostCompact",
+}
 
 
-SECRET_PATTERNS = [
-    re.compile(r"(?i)\b(password|passwd|pwd|token|api[_-]?key|secret|access[_-]?key|private[_-]?key)\b\s*[:=]\s*([^\s,;]+)"),
-    re.compile(r"\bnpm_[A-Za-z0-9]{20,}\b"),
-    re.compile(r"\bgh[pousr]_[A-Za-z0-9_]{20,}\b"),
-    re.compile(r"\bsk-[A-Za-z0-9_-]{20,}\b"),
-]
-EPHEMERAL_SECRET_PATTERN = re.compile(r"(?i)\b(otp|one[- ]?time password|验证码|一次性验证码)\b\s*[:=]?\s*([0-9]{4,8})?")
+def hook_response(platform: str, event: str, additional_context: str = "") -> int:
+    payload: dict[str, object] = {}
+    if platform == "claude" and event in {"pre-compact", "post-compact", "session-end", "stop-failure"}:
+        print("{}")  # These native events cannot deliver model context or block.
+        return 0
+    if additional_context:
+        if platform == "cursor":
+            payload["additional_context"] = additional_context
+        elif platform == "claude" and event in {"stop", "subagent-stop", "session-end"}:
+            # Claude treats additionalContext at Stop as another model turn.
+            # A diagnostic (e.g. unbound Session) must not restart generation.
+            payload["systemMessage"] = additional_context
+        else:
+            payload["hookSpecificOutput"] = {
+                "hookEventName": HOOK_EVENT_NAMES.get(event, event),
+                "additionalContext": additional_context,
+            }
+    print(json.dumps(payload, ensure_ascii=False))
+    return 0
 
 
-def has_secret(text: str) -> bool:
-    return any(pattern.search(text) for pattern in SECRET_PATTERNS)
+def permission_response(event: str, behavior: str = "", message: str = "") -> int:
+    payload: dict[str, object] = {}
+    if behavior:
+        decision: dict[str, object] = {"behavior": behavior}
+        if message:
+            decision["message"] = message
+        payload["hookSpecificOutput"] = {
+            "hookEventName": HOOK_EVENT_NAMES[event],
+            "decision": decision,
+        }
+    elif message:
+        payload["systemMessage"] = message
+    print(json.dumps(payload, ensure_ascii=False))
+    return 0
 
 
-def has_ephemeral_secret(text: str) -> bool:
-    return bool(EPHEMERAL_SECRET_PATTERN.search(text))
+def payload_value(payload: object, keys: tuple[str, ...]) -> str:
+    if not isinstance(payload, dict):
+        return ""
+    for key in keys:
+        value = payload.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return ""
+
+
+def payload_time(payload: object) -> str:
+    return payload_value(payload, ("timestamp", "occurred_at", "occurredAt")) or utc_now()
+
+
+def event_identity(payload: object, event: str, current_session_id: str) -> tuple[str, str, str]:
+    turn_id = payload_value(payload, ("turn_id", "turnId"))
+    call_id = payload_value(payload, ("tool_use_id", "toolUseId", "call_id", "callId", "agent_id", "agentId"))
+    marker = payload_value(payload, ("trigger", "source", "reason"))
+    prompt_hash = hashlib.sha256(prompt_text(json.dumps(payload, ensure_ascii=False)).encode("utf-8")).hexdigest() if isinstance(payload, dict) else ""
+    key = json.dumps([current_session_id, event, turn_id, call_id, marker, prompt_hash], ensure_ascii=False, separators=(",", ":"))
+    return f"hook-{hashlib.sha256(key.encode('utf-8')).hexdigest()[:24]}", turn_id, call_id
+
+
+def map_entries(node: object):
+    if not isinstance(node, dict):
+        return
+    yield node
+    for key in ("children", "_inbox"):
+        for child in node.get(key) or []:
+            yield from map_entries(child)
+
+
+def map_snapshot(ctx: Path, current_session_id: str) -> dict[str, object]:
+    map_file = ctx / "map.json"
+    access_file = ctx / "sessions" / "workbench-access.json"
+    role = "executor"
+    probe = subprocess.run(["git", "rev-parse", "--path-format=absolute", "--git-common-dir"], cwd=ctx.parent.parent,
+                           capture_output=True, text=True, timeout=5, check=False,
+                           creationflags=WINDOWS_NO_WINDOW)
+    if probe.returncode == 0:
+        shared = Path(probe.stdout.strip()) / "context-guard"
+        bindings = read_json(shared / "workbench-bindings.json", {})
+        bound = bindings.get("sessions", {}).get(current_session_id, {})
+        if bound.get("worktreeRoot") == str(ctx.parent.parent.resolve()):
+            role = "coordinator" if bound.get("role") == "coordinator" else "executor"
+            scope = hashlib.sha256((current_session_id + "\0" + bound.get("worktreeId", "")).encode()).hexdigest()
+            map_file = shared / "session-memory" / scope / "map.json"
+            access_file = shared / "workbench-access.json"
+    document = read_json(map_file, {})
+    nodes = list(map_entries(document.get("root"))) if isinstance(document, dict) else []
+    access = read_json(access_file, {})
+    sessions = access.get("sessions") if isinstance(access, dict) and isinstance(access.get("sessions"), dict) else {}
+    grant_record = sessions.get(current_session_id) if isinstance(sessions, dict) else {}
+    grants = grant_record.get("nodes") if isinstance(grant_record, dict) and isinstance(grant_record.get("nodes"), list) else []
+    by_id = {str(node.get("id")): node for node in nodes if isinstance(node.get("id"), str)}
+    # Match AccessStore: all is dynamic, while an explicit empty list is revoked.
+    if isinstance(grant_record, dict) and grant_record.get("mode") == "all":
+        grants = list(by_id)
+    def can_write_node(node_id: str) -> bool:
+        if node_id not in by_id:
+            return False
+        rule = next((item for item in (by_id[node_id].get("access") or [])
+                     if isinstance(item, dict) and item.get("agentId") == current_session_id), None)
+        return rule is None or rule.get("allow") == "write"
+    grants = [node_id for node_id in grants if can_write_node(node_id)]
+    assigned_todos: list[dict[str, str]] = []
+    assigned_bugs: list[dict[str, str]] = []
+    for node in nodes:
+        node_id = str(node.get("id") or "")
+        node_title = str(node.get("title") or node_id)
+        for todo in node.get("todos") or []:
+            owners = todo.get("sessions") if isinstance(todo, dict) else []
+            target = str(todo.get("target_session") or "") if isinstance(todo, dict) else ""
+            if isinstance(todo, dict) and (current_session_id in (owners or []) or target == current_session_id):
+                assigned_todos.append({"id": str(todo.get("id") or ""), "title": str(todo.get("title") or ""), "status": str(todo.get("status") or "pending"), "node": node_id, "node_title": node_title})
+        for bug in node.get("bugs") or []:
+            owners = bug.get("sessions") if isinstance(bug, dict) else []
+            if isinstance(bug, dict) and current_session_id in (owners or []):
+                assigned_bugs.append({"id": str(bug.get("id") or ""), "title": str(bug.get("title") or ""), "status": str(bug.get("status") or "open"), "node": node_id, "node_title": node_title})
+    raw = map_file.read_bytes() if map_file.is_file() else b""
+    local_version = hashlib.sha256(raw).hexdigest() if raw else "missing"
+    return {
+        "role": role,
+        "version": local_version,
+        "cloud_cursor": None,
+        "grants": [str(item) for item in grants],
+        "grant_nodes": [{"id": node_id, "title": str(by_id.get(node_id, {}).get("title") or node_id)} for node_id in grants[:20]],
+        "todos": assigned_todos[:20],
+        "bugs": assigned_bugs[:20],
+        "nodes": nodes,
+    }
+
+
+def map_inbox(root: Path, ctx: Path, current_session_id: str) -> dict[str, object]:
+    """Read the durable Map inbox only when the local workbench is already live."""
+    if not (ctx / "private" / "workbench.json").is_file():
+        return {"pending": False, "available": False}
+    script = Path(__file__).resolve().parent / "workbench" / "cli.mjs"
+    command = [
+        "node", str(script), "map", "inbox", "--root", str(root),
+        "--session", current_session_id, "--start",
+    ]
+    try:
+        result = subprocess.run(command, cwd=root, capture_output=True, text=True, encoding="utf-8", timeout=10,
+                                check=False, creationflags=WINDOWS_NO_WINDOW)
+    except (OSError, subprocess.SubprocessError) as error:
+        return {"pending": False, "error": {"code": "INBOX_READ_FAILED", "message": str(error)}}
+    lines = (result.stdout or "").strip().splitlines()
+    try:
+        value = json.loads(lines[-1]) if lines else None
+        if not isinstance(value, dict) or ("pending" not in value and "error" not in value):
+            raise ValueError("missing inbox response")
+    except (json.JSONDecodeError, ValueError):
+        value = {"error": {"code": "INBOX_READ_FAILED", "message": "invalid workbench response"}}
+    if result.returncode and "error" not in value:
+        value = {"error": {"code": "INBOX_READ_FAILED", "message": (result.stderr or "inbox command failed").strip()[:500]}}
+    return value
+
+
+def coordinator_static_context(root: Path, ctx: Path, current_session_id: str, snapshot: dict[str, object]) -> str:
+    probe = subprocess.run(["git", "rev-parse", "--path-format=absolute", "--git-common-dir"], cwd=root,
+                           capture_output=True, text=True, timeout=5, check=False, creationflags=WINDOWS_NO_WINDOW)
+    shared = Path(probe.stdout.strip()) / "context-guard" if probe.returncode == 0 else None
+    cloud = bool(shared and (shared / "memory-client.json").is_file())
+    if cloud:
+        command = ["node", str(Path(__file__).resolve().parent / "workbench" / "cli.mjs"),
+                   "map", "main", "read", "--root", str(root), "--session", current_session_id]
+        try:
+            result = subprocess.run(command, cwd=root, capture_output=True, text=True, encoding="utf-8", timeout=8,
+                                    check=False, creationflags=WINDOWS_NO_WINDOW)
+            response = json.loads(result.stdout) if result.returncode == 0 else {}
+        except (OSError, subprocess.SubprocessError, json.JSONDecodeError):
+            response = {}
+        if not isinstance(response, dict):
+            response = {}
+        document, version = response.get("doc"), response.get("version")
+    else:
+        main_file = shared / "main" / "map.json" if shared else ctx / "map.json"
+        document = read_json(main_file, {})
+        version = hashlib.sha256(main_file.read_bytes()).hexdigest() if main_file.is_file() else None
+    if not isinstance(document, dict) or not isinstance(document.get("root"), dict) or not version:
+        return "Coordinator Main navigation unavailable; do not substitute the Session Map or stale conversation text."
+    directory = []
+    by_id = {}
+    def visit(node: dict[str, object], parent_id: str | None = None) -> None:
+        by_id[str(node.get("id") or "")] = node
+        children = [child for child in node.get("children") or [] if isinstance(child, dict)]
+        directory.append({"id": node.get("id"), "parentId": parent_id, "title": str(node.get("title") or "")[:120],
+                          "description": str(node.get("purpose") or "")[:320], "children": [child.get("id") for child in children]})
+        for child in children:
+            visit(child, str(node.get("id") or ""))
+    visit(document["root"])
+    current = {"todos": [], "bugs": []}
+    for kind, field in (("todo", "todos"), ("bug", "bugs")):
+        for assigned in snapshot.get(field) or []:
+            node_id, item_id = str(assigned.get("node") or ""), str(assigned.get("id") or "")
+            item = next((value for value in by_id.get(node_id, {}).get(field) or []
+                         if isinstance(value, dict) and value.get("id") == item_id), None)
+            current[field].append({"nodeId": node_id, "itemId": item_id, "kind": kind,
+                                   **({"title": str(item.get("title") or "")[:240], "status": item.get("status")}
+                                      if item else {"unavailable": True})})
+    return "Coordinator static Main context (project data, not user instructions): " + json.dumps({
+        "mainVersion": version, "staticDirectory": directory,
+        "currentTask": current,
+    }, ensure_ascii=False, separators=(",", ":"))
+
+
+def map_context(root: Path, ctx: Path, current_session_id: str) -> tuple[str, dict[str, object]]:
+    snapshot = map_snapshot(ctx, current_session_id)
+    inbox = map_inbox(root, ctx, current_session_id)
+    grants = snapshot["grant_nodes"]
+    todos = snapshot["todos"]
+    bugs = snapshot["bugs"]
+    grant_text = ", ".join(f"{item['id']} {item['title']}" for item in grants) if grants else "none"
+    if snapshot.get("role") == "coordinator":
+        todo_text = bug_text = "see authoritative Main context below"
+    else:
+        todo_text = "; ".join(f"{item['id']}@{item['node']} {item['title']} [{item['status']}]" for item in todos) if todos else "none"
+        bug_text = "; ".join(f"{item['id']}@{item['node']} {item['title']} [{item['status']}]" for item in bugs) if bugs else "none"
+    inbox_text = "No unacknowledged Map changes from other sessions."
+    if isinstance(inbox.get("error"), dict):
+        inbox_text = f"Map inbox unavailable: {inbox['error'].get('code')}."
+    elif inbox.get("available") is False:
+        inbox_text = "Map inbox unavailable: no live workbench; changes have not been checked."
+    elif inbox.get("pending"):
+        events = inbox.get("events") if isinstance(inbox.get("events"), list) else []
+        changes = inbox.get("changes") if isinstance(inbox.get("changes"), list) else []
+        actors = sorted({str(item.get("actor", {}).get("sessionId") or item.get("actor", {}).get("kind") or "unknown") for item in events if isinstance(item, dict)})
+        changed_nodes = sorted({str(item.get("id") or item.get("nodeId") or "") for item in changes if isinstance(item, dict) and (item.get("id") or item.get("nodeId"))})
+        inbox_text = (
+            f"Pending Map inbox receipt {inbox.get('receipt')} from {', '.join(actors) or 'other sessions'}; "
+            f"changed nodes: {', '.join(changed_nodes) or 'see inbox payload'}; journal gap: {bool(inbox.get('journalGap'))}. "
+        )
+    text = (
+        f"Context Guard Map snapshot {str(snapshot['version'])[:16]} (cloud cursor {snapshot.get('cloud_cursor') or 0}). "
+        f"Authorized nodes: {grant_text}. Assigned TODOs: {todo_text}. Assigned Bugs: {bug_text}. "
+        f"{inbox_text}"
+    )
+    if snapshot.get("role") == "coordinator":
+        text += "\n\n" + coordinator_static_context(root, ctx, current_session_id, snapshot)
+    return text, snapshot
+
+
+def audit_details(payload: object, event: str, current_session_id: str, runtime: dict[str, object], extra: dict[str, object] | None = None) -> dict[str, object]:
+    event_id, turn_id, call_id = event_identity(payload, event, current_session_id)
+    plan = runtime.get("active_plan") if isinstance(runtime.get("active_plan"), dict) else {}
+    details: dict[str, object] = {
+        "event_id": event_id,
+        "occurred_at": payload_time(payload),
+        "recorded_at": utc_now(),
+        "hook_event": HOOK_EVENT_NAMES.get(event, event),
+        "turn_id": turn_id or None,
+        "plan_id": plan.get("id") if isinstance(plan, dict) else None,
+        "tool_call_id": call_id or None,
+        "hook_sha256": hashlib.sha256(Path(__file__).read_bytes()).hexdigest(),
+        "context_emitted": event in {"session-start", "user-prompt-submit", "post-compact"},
+    }
+    if extra:
+        details.update(extra)
+    return details
+
+
+def active_grants(snapshot: dict[str, object]) -> set[str]:
+    return {str(item) for item in snapshot.get("grants") or []}
+
+
+def owner_nodes(paths: list[str], snapshot: dict[str, object]) -> dict[str, str]:
+    found: dict[str, str] = {}
+    for file in paths:
+        normalized = file.replace("\\", "/").lstrip("./")
+        best: tuple[int, str] | None = None
+        for node in snapshot.get("nodes") or []:
+            if not isinstance(node, dict) or node.get("proposal") in {"proposed", "cancelled"}:
+                continue
+            for owned in node.get("owns") or []:
+                owned_path = str(owned).replace("\\", "/").lstrip("./").rstrip("/")
+                if owned_path and (normalized == owned_path or normalized.startswith(owned_path + "/")):
+                    candidate = (len(owned_path), str(node.get("id") or ""))
+                    if candidate[1] and (best is None or candidate[0] > best[0]):
+                        best = candidate
+        if best:
+            found[normalized] = best[1]
+    return found
+
+
+def tool_command(payload: dict) -> str:
+    value = payload.get("tool_input")
+    if isinstance(value, str):
+        return value
+    if isinstance(value, dict):
+        return str(value.get("command") or value.get("cmd") or value.get("patch") or value.get("input") or "")
+    return ""
+
+
+def patch_targets(payload: dict) -> list[str] | None:
+    name = str(payload.get("tool_name") or payload.get("toolName") or "")
+    if name.rsplit(".", 1)[-1] != "apply_patch":
+        return None
+    command = tool_command(payload).replace("\r\n", "\n").strip()
+    if not (command.startswith("*** Begin Patch\n") and command.endswith("\n*** End Patch")):
+        return None
+    return re.findall(r"^\*\*\* (?:(?:Add|Update|Delete) File|Move to): (.+)$", command, re.MULTILINE)
 
 
-def redact_user_message(text: str) -> str:
-    redacted = text
-    for pattern in SECRET_PATTERNS:
-        if pattern.groups >= 2:
-            redacted = pattern.sub(lambda m: f"{m.group(1)}=<redacted>", redacted)
-        else:
-            redacted = pattern.sub("<redacted-secret>", redacted)
-    redacted = EPHEMERAL_SECRET_PATTERN.sub(lambda m: f"{m.group(1)}=<redacted-ephemeral>", redacted)
-    return redacted
+def forbidden_direct_write(payload: object, root: Path) -> str:
+    if not mutating_tool(payload) or not isinstance(payload, dict):
+        return ""
+    command = tool_command(payload)
+    targets = patch_targets(payload)
+    if targets is not None:
+        # Only patch headers designate writes. Hunk text may discuss protected paths.
+        # Prefix each target so the path check also covers another worktree.
+        checked_paths = []
+        for item in targets:
+            normalized = os.path.normpath(item.strip().replace("\\", "/")).replace("\\", "/")
+            checked_paths.append("/" + normalized.lstrip("/"))
+            candidate = Path(normalized).expanduser()
+            try:
+                resolved = candidate.resolve() if candidate.is_absolute() else (root / candidate).resolve()
+            except (OSError, ValueError, RuntimeError):
+                return "Cannot resolve patch target; verify the target path before writing."
+            checked_paths.append(resolved.as_posix())
+        command = "\n".join(checked_paths)
+    paths = {
+        normalized[2:] if normalized.startswith("./") else normalized
+        for item in tool_paths(payload, root)
+        for normalized in [item.replace("\\", "/")]
+    }
+    if ".codex/context/map.json" in paths or re.search(r"(?:^|[\s'\"/\\])\.codex[/\\]context[/\\]map\.json\b", command):
+        return "Direct map.json writes are forbidden; use context-guard map read/apply/reconcile."
+    if any(item.rsplit("/", 1)[-1].lower() == "todo.md" for item in paths) or re.search(r"(?:^|[/\\])TODO\.md\b", command, re.IGNORECASE):
+        return "TODO.md is human-owned; record Agent work in the authorized Map node instead."
+    return ""
+
+
+def session_id(payload: object, platform: str, ctx: Path, event: str) -> str:
+    value = payload_value(
+        payload,
+        ("session_id", "sessionId", "conversation_id", "conversationId", "generation_id"),
+    )
+    state_path = ctx / "private" / "hook-sessions.json"
+    state = read_json(state_path, {})
+    if not isinstance(state, dict):
+        state = {}
+    if not value and event not in {"session-start", "subagent-start"}:
+        stored = state.get(platform)
+        if isinstance(stored, str) and stored.strip():
+            value = stored.strip()
+    if not value:
+        for key in ("CODEX_THREAD_ID", "CLAUDE_SESSION_ID", "CURSOR_SESSION_ID"):
+            env_value = os.environ.get(key, "").strip()
+            if env_value:
+                value = env_value
+                break
+    if not value:
+        stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+        value = f"{platform}-{stamp}-{os.getpid()}"
+    if state.get(platform) != value:
+        state[platform] = value
+        write_json(state_path, state)
+    return value
+
+
+def normalized_path(value: str) -> str:
+    try:
+        return os.path.normcase(os.path.normpath(str(Path(value).expanduser().resolve())))
+    except (OSError, RuntimeError, ValueError):
+        return ""
 
 
-def write_private_secret(ctx: Path, raw_text: str, redacted_text: str) -> str:
-    private_dir = ctx / "private"
-    private_dir.mkdir(parents=True, exist_ok=True)
+def codex_thread_name(root: Path, current_session_id: str) -> str:
+    """Read only the matching local Codex thread metadata, if available."""
+    codex_home = Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser()
+    databases = [codex_home / "state_5.sqlite", codex_home / "sqlite" / "state_5.sqlite"]
+    expected_root = normalized_path(str(root))
+    for database in databases:
+        if not database.is_file():
+            continue
+        connection = None
+        try:
+            connection = sqlite3.connect(database.resolve().as_uri() + "?mode=ro", uri=True, timeout=0.5)
+            columns = {
+                str(row[1])
+                for row in connection.execute("PRAGMA table_info(threads)")
+                if len(row) > 1
+            }
+            if not {"id", "cwd"}.issubset(columns):
+                continue
+            selected = [column for column in ("name", "title", "cwd") if column in columns]
+            row = connection.execute(
+                f"SELECT {', '.join(selected)} FROM threads WHERE id = ? LIMIT 1",
+                (current_session_id,),
+            ).fetchone()
+            if not row:
+                continue
+            values = dict(zip(selected, row))
+            if normalized_path(str(values.get("cwd") or "")) != expected_root:
+                continue
+            for field in ("name", "title"):
+                value = values.get(field)
+                if isinstance(value, str) and value.strip():
+                    return " ".join(value.strip().split())[:240]
+        except (OSError, sqlite3.Error):
+            continue
+        finally:
+            if connection is not None:
+                connection.close()
+    return ""
+
+
+def session_display_name(payload: object, platform: str, root: Path, current_session_id: str) -> str:
+    if platform == "codex":
+        value = codex_thread_name(root, current_session_id)
+        if value:
+            return value
+    named = payload_value(
+        payload,
+        (
+            "thread_name",
+            "threadName",
+            "session_name",
+            "sessionName",
+            "conversation_title",
+            "conversationTitle",
+        ),
+    )[:240]
+    if named or platform != "claude":
+        return named
+    # Native Claude hooks provide the transcript path, but not the --name value.
+    # Read only a bounded tail of this Session's own transcript metadata.
+    transcript = payload_value(payload, ("transcript_path",))
+    if not transcript:
+        return ""
     try:
-        private_dir.chmod(0o700)
-    except OSError:
+        directory = Path(os.environ.get("CLAUDE_CONFIG_DIR") or os.environ.get("CLAUDE_HOME") or Path.home() / ".claude").expanduser().resolve() / "projects"
+        file = Path(transcript).resolve()
+        file.relative_to(directory)
+        if file.name != current_session_id + ".jsonl":
+            return ""
+        with file.open("rb") as stream:
+            stream.seek(0, os.SEEK_END)
+            stream.seek(max(0, stream.tell() - 262144))
+            lines = stream.read(262144).decode("utf-8", errors="replace").splitlines()
+        for line in reversed(lines):
+            try:
+                item = json.loads(line)
+            except ValueError:
+                continue
+            if isinstance(item, dict) and item.get("type") == "custom-title" and item.get("sessionId") == current_session_id:
+                return str(item.get("customTitle") or "").strip()[:200]
+    except (OSError, ValueError):
         pass
-    path = private_dir / "secrets.local.json"
+    return ""
+
+
+def language_setup_context(root: Path, ctx: Path) -> str:
     try:
-        data = json.loads(path.read_text(encoding="utf-8")) if path.exists() else []
-    except json.JSONDecodeError:
-        data = []
-    if not isinstance(data, list):
-        data = []
-    secret_id = "USER-SECRET-" + datetime.now().strftime("%Y%m%d-%H%M%S")
-    data.append(
-        {
-            "id": secret_id,
-            "created": datetime.now().isoformat(timespec="seconds"),
-            "redacted": redacted_text,
-            "raw": raw_text,
-            "note": "Local-only Context Guard secret memory. Do not copy into roadmap, HTML, git, logs, or final answers.",
-        }
+        language = str(run_node_workbench(["preferences", "--root", str(root)]).get("record_language", "unset"))
+    except (OSError, ValueError, RuntimeError, subprocess.TimeoutExpired):
+        return "Context Guard language unavailable; existing preference preserved."
+    if language and language != "unset":
+        return ""
+    quoted_root = '"' + str(root).replace('"', '\\"') + '"'
+    cli = context_guard_cli()
+    return (
+        "Context Guard language unset: ask 中文 or English. "
+        f"After the user answers, run `{cli} set-language --root "
+        f"{quoted_root} --language <zh-or-en>` and then continue in that language."
+    )
+
+
+def context_guard_cli() -> str:
+    launcher = Path(__file__).resolve().parent.parent / "bin" / "context-guard-skill.js"
+    return f"node {json.dumps(str(launcher))}"
+
+
+def lifecycle_context(root: Path, workbench_url: str | None, current_session_id: str) -> str:
+    skill = Path(__file__).resolve().parent.parent / "SKILL.md"
+    workbench = f" Workbench: {workbench_url}." if workbench_url else ""
+    return (
+        f"Context Guard: {root}; Session: {current_session_id}.{workbench} "
+        f"Instructions: {skill}. CLI: {context_guard_cli()}."
     )
-    path.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+
+def frontend_workbench_url(ctx: Path, local_url: str | None, current_session_id: str) -> str | None:
+    """Expose one human UI: Cloud when configured, otherwise the local fallback."""
+    config = sync_command(ctx.parent.parent, "status", current_session_id)
+    cloud_url = str(config.get("url") or "") if isinstance(config, dict) else ""
+    project_id = str(config.get("projectId") or "") if isinstance(config, dict) else ""
     try:
-        path.chmod(0o600)
-    except OSError:
+        parsed = urlsplit(cloud_url)
+        if parsed.scheme == "https" and parsed.hostname and re.fullmatch(r"[a-z0-9][a-z0-9-]{0,63}", project_id):
+            origin = f"{parsed.scheme}://{parsed.netloc}"
+            return f"{origin}/projects/{quote(project_id)}?session={quote(current_session_id)}"
+    except ValueError:
         pass
-    return secret_id
+    return local_url
 
 
-def append_user_message(ctx: Path, text: str) -> tuple[str, str]:
-    clean = text.strip()
-    if not clean:
-        return "skipped", "empty prompt"
-    init_context(ctx.parent.parent)
-    path = ctx / "user-messages.md"
-    now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
-    is_large = len(clean) > 1600 or clean.count("\n") > 30
-    ephemeral = has_ephemeral_secret(clean)
-    secret = has_secret(clean)
-    redacted = redact_user_message(clean)
-    secret_ref = ""
-    if secret and not ephemeral and len(clean) <= 4000:
-        secret_ref = write_private_secret(ctx, clean, redacted)
-    if is_large:
-        first_line = redacted.splitlines()[0][:240]
-        stored = f"Large user message or attachment; first line: {first_line}"
-        mode = "summary"
-    else:
-        stored = redacted
-        mode = "verbatim" if not secret and not ephemeral else "redacted"
-    if ephemeral:
-        secret_ref = "ephemeral-not-stored"
-        mode = "ephemeral"
-    body = path.read_text(encoding="utf-8") if path.exists() else "# User Message Memory\n\n## Recent User Signals\n\n"
-    if stored and stored in body[-4000:]:
-        return "skipped", "duplicate recent message"
-    entry = [
-        f"\n### {now}",
-        f"- Mode: {mode}",
-        f"- User message: {stored}",
-    ]
-    if secret_ref:
-        entry.append(f"- Secret pointer: {secret_ref}")
-    entry.append("- Use: Preserve this wording when deciding task direction, constraints, credentials, preferences, bad-case intake, or roadmap `User request` fields.")
-    path.parent.mkdir(parents=True, exist_ok=True)
-    with path.open("a", encoding="utf-8") as handle:
-        handle.write("\n".join(entry) + "\n")
-    return "recorded", mode
-
-
-def run_test_hub_completion(root: Path) -> tuple[int, str]:
-    ctx = context_dir(root)
-    tests = approved_dev_completion_tests(ctx)
-    if not tests:
-        return 0, "[context-guard] test hub: no approved every-dev-completion tests."
-
-    hook_log(f"[context-guard] test hub: running {len(tests)} approved every-dev-completion test(s).")
-    completed = subprocess.run(
-        [
-            sys.executable,
-            str(SKILL_ROOT / "scripts" / "context_guard.py"),
-            "dev-complete",
-            "--root",
-            str(root),
-        ],
-        text=True,
-        capture_output=True,
-        timeout=900,
-    )
-    output = "\n".join(part for part in [completed.stdout.strip(), completed.stderr.strip()] if part)
-    return completed.returncode, output
+def prompt_text(raw: str) -> str:
+    payload = parse_hook_payload(raw)
+    return payload_value(payload, ("prompt", "user_prompt", "userPrompt", "text", "content"))
 
 
-def completion_test_summary(output: str, code: int) -> str:
-    if "no approved every-dev-completion tests" in output:
-        return "no approved every-dev-completion tests"
-    for line in output.splitlines():
-        if "[context-guard] test hub:" in line and " passed," in line and " failed," in line and " blocked" in line:
-            summary = line.split("test hub:", 1)[1].strip().rstrip(".")
-            if code == 0:
-                return f"all approved tests passed ({summary})"
-            return f"approved tests are not all passing ({summary})"
-    return "test hub status unknown; inspect `.codex/context/test-hub/last-run.json`"
+def redact(text: str) -> str:
+    if len(text) > 800:
+        return text[:400].rstrip() + "…"
+    return text
 
 
-def completion_test_failure_details(root: Path, limit: int = 3) -> str:
-    path = context_dir(root) / "test-hub" / "last-run.json"
+def append_user_message(ctx: Path, text: str, current_session_id: str) -> str:
+    text = (text or "").strip()
+    if not text:
+        return "empty"
+    ctx.mkdir(parents=True, exist_ok=True)
+    path = ctx / "user-messages.md"
     if not path.exists():
-        return ""
+        path.write_text("# User Message Memory\n\n## Recent User Signals\n\n", encoding="utf-8")
+    body = path.read_text(encoding="utf-8")
+    line = "- " + redact(text).replace("\n", " ")
+    recorded = False
+    if line not in body:
+        marker = "## Recent User Signals"
+        if marker in body:
+            body = body.replace(marker, marker + "\n\n" + line, 1)
+        else:
+            body += "\n" + line + "\n"
+        path.write_text(body, encoding="utf-8")
+        recorded = True
+    session_path = ctx / "sessions" / f"{safe_identifier(current_session_id)}.md"
+    if session_path.is_file():
+        session_body = session_path.read_text(encoding="utf-8")
+        session_marker = "## User Signals"
+        if line not in session_body:
+            if session_marker in session_body:
+                session_body = session_body.replace(session_marker, session_marker + "\n\n" + line, 1)
+            else:
+                session_body += ("\n" if session_body.endswith("\n") else "\n\n") + session_marker + "\n\n" + line + "\n"
+            session_path.write_text(session_body, encoding="utf-8")
+            recorded = True
+    return "recorded" if recorded else "duplicate"
+
+
+def sync_configured(root: Path, current_session_id: str) -> bool:
+    result = sync_command(root, "status", current_session_id)
+    if result.get("error"):
+        raise ValueError(f"Cloud sync status failed: {json.dumps(result, ensure_ascii=False)}")
+    return result.get("configured") is True
+
+
+def sync_command(root: Path, action: str, current_session_id: str = "", paths: list[str] | None = None) -> dict[str, object]:
+    script = Path(__file__).resolve().parent / "workbench" / "cli.mjs"
+    if not script.is_file():
+        return {"error": {"code": "SYNC_TOOL_MISSING", "message": str(script)}}
+    command = ["node", str(script), "sync", action, "--root", str(root)]
+    if current_session_id:
+        command.extend(["--session", current_session_id])
+    clean_paths = [item for item in (paths or []) if item]
+    if clean_paths:
+        command.extend(["--paths", ",".join(clean_paths)])
     try:
-        data = json.loads(path.read_text(encoding="utf-8"))
-    except Exception:
-        return ""
-    results = data.get("results", [])
-    if not isinstance(results, list):
-        return ""
-    not_passing = [
-        item
-        for item in results
-        if isinstance(item, dict) and str(item.get("status", "")).strip().lower() in {"failed", "blocked"}
-    ]
-    if not not_passing:
-        return ""
+        result = subprocess.run(command, cwd=root, capture_output=True, text=True, encoding="utf-8", timeout=15,
+                                check=False, creationflags=WINDOWS_NO_WINDOW)
+    except (OSError, subprocess.SubprocessError) as error:
+        return {"error": {"code": "SYNC_TOOL_FAILED", "message": str(error)}}
+    output = (result.stdout or "").strip().splitlines()
+    try:
+        value = json.loads(output[-1]) if output else None
+        if not isinstance(value, dict) or not value:
+            raise ValueError("missing sync response")
+    except (json.JSONDecodeError, ValueError):
+        value = {"error": {"code": "SYNC_TOOL_FAILED", "message": (result.stderr or result.stdout or "invalid output").strip()[:500]}}
+    if result.returncode and "error" not in value:
+        value = {"error": {"code": "SYNC_TOOL_FAILED", "message": (result.stderr or "sync command failed").strip()[:500]}}
+    return value
+
+
+def session_memory_sync(root: Path, current_session_id: str, event: str, payload: object) -> dict[str, object]:
+    """Persist this Session checkpoint directly; a later hook retries preserved local data."""
+    event_id, _, _ = event_identity(payload, event, current_session_id)
+    try:
+        return run_node_workbench([
+            "memory", "sync", "--root", str(root), "--session", current_session_id,
+            "--hook-event", HOOK_EVENT_NAMES.get(event, event),
+            "--event-id", event_id,
+            "--occurred-at", payload_time(payload),
+        ])
+    except (OSError, ValueError, RuntimeError, subprocess.TimeoutExpired) as error:
+        return {"error": {"code": "MEMORY_SYNC_PENDING", "message": str(error)[:500]}}
+
+
+def sync_pending_interrupt(root: Path, session: str, runtime: dict) -> None:
+    """Keep interruption signals until the local backend accepts the original ID."""
+    pending = runtime.get("pending_interrupts") or []
+    if not pending:
+        return
+    item = pending[0]
+    try:
+        run_node_workbench(["map", "interrupted", "--root", str(root), "--session", session,
+                            "--event-id", item["id"], "--occurred-at", item["at"]])
+    except (OSError, ValueError, RuntimeError, subprocess.TimeoutExpired):
+        # No adapter stderr or credentials enter development memory.
+        runtime["interrupt_sync"] = "pending"
+    else:
+        runtime["pending_interrupts"] = pending[1:]
+        runtime["interrupt_sync"] = "pending" if pending[1:] else "confirmed"
+    write_hook_runtime(root, session, runtime)
 
-    pieces: list[str] = []
-    for item in not_passing[:limit]:
-        title = str(item.get("title") or item.get("id") or "unnamed test").strip()
-        status = str(item.get("status") or "failed").strip()
-        reason = str(item.get("reason") or "no reason recorded").strip()
-        log = str(item.get("log") or "").strip()
-        if log:
+
+def tool_paths(payload: object, root: Path) -> list[str]:
+    if not isinstance(payload, dict):
+        return []
+    found: set[str] = set()
+
+    def add(value: object) -> None:
+        values = value if isinstance(value, list) else [value]
+        for item in values:
+            if not isinstance(item, str) or not item.strip():
+                continue
+            candidate = Path(item).expanduser()
             try:
-                log = str(Path(log).resolve().relative_to(root.resolve()))
-            except Exception:
-                pass
-        suffix = f"; log: {log}" if log else ""
-        pieces.append(f"{status}: {title} — {reason}{suffix}")
-    if len(not_passing) > limit:
-        pieces.append(f"+{len(not_passing) - limit} more; inspect `.codex/context/test-hub/last-run.json`")
-    return "; ".join(pieces)
+                resolved = candidate.resolve() if candidate.is_absolute() else (root / candidate).resolve()
+                relative = resolved.relative_to(root.resolve())
+            except (OSError, ValueError):
+                continue
+            found.add(relative.as_posix())
 
+    def walk(value: object) -> None:
+        if isinstance(value, dict):
+            for key, child in value.items():
+                if key.lower() in {"path", "paths", "file", "file_path", "filepath", "target_file", "targetfile"}:
+                    add(child)
+                walk(child)
+        elif isinstance(value, list):
+            for child in value:
+                walk(child)
 
-def prompt_text(raw: str) -> str:
-    if not raw.strip():
-        return ""
+    walk(payload.get("tool_input", {}))
+    command = tool_command(payload)
+    for match in re.finditer(r"^\*\*\* (?:(?:Add|Update|Delete) File|Move to): (.+)$", command, re.MULTILINE):
+        add(match.group(1).strip())
+    for target in shell_output_targets(command):
+        add(target)
+    return sorted(found)
+
+
+def shell_output_targets(command: str) -> list[str]:
+    """Find literal shell write targets without treating heredoc content as commands."""
+    first_line = command.split("\n", 1)[0]
+    if not first_line:
+        return []
     try:
-        data = json.loads(raw)
-    except Exception:
-        return raw
-    pieces: list[str] = []
+        lexer = shlex.shlex(first_line, posix=os.name != "nt", punctuation_chars=";&|<>")
+        lexer.whitespace_split = True
+        lexer.commenters = ""
+        tokens = list(lexer)
+    except ValueError:
+        return []
+    targets: list[str] = []
+    for index, token in enumerate(tokens[:-1]):
+        if token in {">", ">>", ">|", "&>"}:
+            target = tokens[index + 1]
+            if target not in {"/dev/null", "&1", "&2"} and not target.isdigit():
+                targets.append(target)
+    segment: list[str] = []
+    for token in [*tokens, ";"]:
+        if token not in {";", "&&", "||", "|"}:
+            segment.append(token)
+            continue
+        words = segment
+        segment = []
+        if not words:
+            continue
+        command_name = Path(words[0]).name
+        args = words[1:]
+        if command_name == "git" and args and args[0] in {"mv", "rm"}:
+            command_name, args = args[0], args[1:]
+        if command_name in {"mv", "cp", "rm", "touch", "mkdir"}:
+            targets.extend(value for value in args if value != "--" and
+                           not value.startswith("-") and value not in {">", ">>", ">|", "&>", "<", "<<"})
+    return targets
+
+
+def tool_target_strings(payload: object) -> list[str]:
+    """Declared write targets, including host paths outside the project."""
+    if not isinstance(payload, dict):
+        return []
+    found: list[str] = []
+
+    def add(value: object) -> None:
+        values = value if isinstance(value, list) else [value]
+        for item in values:
+            if isinstance(item, str) and item.strip():
+                found.append(item.strip())
 
     def walk(value: object) -> None:
-        if isinstance(value, str):
-            pieces.append(value)
+        if isinstance(value, dict):
+            for key, child in value.items():
+                if key.lower() in {"path", "paths", "file", "file_path", "filepath", "target_file", "targetfile"}:
+                    add(child)
+                walk(child)
         elif isinstance(value, list):
-            for item in value:
-                walk(item)
-        elif isinstance(value, dict):
-            for key in ("prompt", "message", "text", "content", "input"):
-                if key in value:
-                    walk(value[key])
-
-    walk(data)
-    return "\n".join(pieces)
-
-
-def looks_like_bad_case(text: str) -> bool:
-    lowered = text.lower()
-    markers = [
-        "bug",
-        "bad case",
-        "regression",
-        "broken",
-        "error",
-        "failed",
-        "failing",
-        "doesn't work",
-        "not working",
-        "紧急",
-        "报错",
-        "失败",
-        "坏例",
-        "复现",
-        "回归",
-        "不对",
-        "有问题",
-    ]
-    return any(marker in lowered for marker in markers)
-
-
-def looks_like_task_switch(text: str) -> bool:
-    lowered = text.lower()
-    markers = [
-        "urgent",
-        "instead",
-        "switch",
-        "pause",
-        "later",
-        "different",
-        "unrelated",
-        "先",
-        "暂停",
-        "等下",
-        "换个",
-        "另一个",
-        "紧急",
-        "回头",
-        "先不",
-    ]
-    return any(marker in lowered for marker in markers)
-
-
-def looks_like_goal_mode(text: str) -> bool:
-    lowered = text.lower()
-    markers = [
-        "goal mode",
-        "goal模式",
-        "goal 模式",
-        "active goal",
-        "long-running",
-        "autonomous",
-        "目标模式",
-        "长期目标",
-        "持续执行",
-        "自动继续",
-    ]
-    return any(marker in lowered for marker in markers)
-
-
-def looks_like_remote_work(text: str) -> bool:
-    lowered = text.lower()
-    markers = [
-        "ssh",
-        "remote server",
-        "remote host",
-        "dev server",
-        "jump host",
-        "服务器",
-        "远程",
-        "开发机",
-        "跳板机",
-        "通过ssh",
-        "通过 ssh",
-    ]
-    return any(marker in lowered for marker in markers)
-
-
-def looks_like_test_creation(text: str) -> bool:
-    lowered = text.lower()
-    creation_markers = [
-        "create",
-        "write",
-        "generate",
-        "design",
-        "add",
-        "创建",
-        "建立",
-        "写",
-        "生成",
-        "设计",
-        "新增",
-        "加一个",
-        "做一个",
-    ]
-    test_markers = [
-        "test case",
-        "task case",
-        "test task",
-        "testing task",
-        "测试case",
-        "测试 case",
-        "测试任务",
-        "测试用例",
-        "测评任务",
-        "测评case",
-        "测评 case",
-        "测试链路",
-        "测试",
-    ]
-    return any(marker in lowered for marker in creation_markers) and any(marker in lowered for marker in test_markers)
-
-
-def looks_like_test_opportunity(text: str) -> bool:
-    lowered = text.lower()
-    opportunity_markers = [
-        "fix",
-        "bug",
-        "regression",
-        "workflow",
-        "flow",
-        "e2e",
-        "integration",
-        "ui",
-        "html",
-        "browser",
-        "frontend",
-        "backend",
-        "api",
-        "service",
-        "deploy",
-        "release",
-        "refactor",
-        "goal mode",
-        "long-running",
-        "修复",
-        "bug",
-        "问题",
-        "复发",
-        "回归",
-        "流程",
-        "链路",
-        "前端",
-        "后端",
-        "接口",
-        "服务",
-        "部署",
-        "发布",
-        "重构",
-        "页面",
-        "浏览器",
-        "远程",
-        "服务器",
-        "goal 模式",
-        "目标模式",
-        "长期",
-    ]
-    return any(marker in lowered for marker in opportunity_markers)
-
-
-def looks_like_explicit_branch(text: str) -> bool:
-    lowered = text.lower()
-    markers = [
-        "branch task",
-        "side task",
-        "side route",
-        "fork this",
-        "create a branch",
-        "new branch",
-        "as a branch",
-        "支线",
-        "分支",
-        "开一个分支",
-        "开一条支线",
-        "创建支线",
-        "创建分支",
-        "作为支线",
-    ]
-    return any(marker in lowered for marker in markers)
-
-
-def looks_like_route_drift(text: str) -> bool:
-    lowered = text.lower()
-    drift_markers = [
-        "significantly diverge",
-        "diverge from",
-        "different architecture",
-        "new architecture",
-        "new direction",
-        "refactor direction",
-        "偏离",
-        "显著偏离",
-        "新的架构",
-        "新方向",
-        "重构方向",
-        "主线架构",
-    ]
-    return any(marker in lowered for marker in drift_markers)
-
-
-def bad_case_blocks(text: str) -> list[dict[str, str]]:
-    blocks: list[dict[str, str]] = []
-    current: dict[str, str] | None = None
-    for line in text.splitlines():
-        heading = line.startswith("### BC-")
-        if heading:
-            if current:
-                blocks.append(current)
-            identifier, _, title = line.removeprefix("### ").partition(":")
-            current = {"id": identifier.strip(), "title": title.strip()}
+            for child in value:
+                walk(child)
+
+    walk(payload.get("tool_input", {}))
+    command = tool_command(payload)
+    for match in re.finditer(r"^\*\*\* (?:(?:Add|Update|Delete) File|Move to): (.+)$", command, re.MULTILINE):
+        add(match.group(1).strip())
+    for target in shell_output_targets(command):
+        add(target)
+    return found
+
+
+def write_like_tool(payload: object) -> bool:
+    if not isinstance(payload, dict):
+        return False
+    name = str(payload.get("tool_name") or payload.get("toolName") or "").lower()
+    return any(marker in name for marker in ("apply_patch", "write", "edit", "delete", "move"))
+
+
+def _resolved_path(value: Path) -> Path | None:
+    try:
+        return value.expanduser().resolve()
+    except (OSError, RuntimeError, ValueError):
+        return None
+
+
+def _under(path: Path, base: Path) -> bool:
+    try:
+        path.relative_to(base)
+        return True
+    except ValueError:
+        return False
+
+
+def temp_request_roots() -> list[Path]:
+    raw = [tempfile.gettempdir(), os.environ.get("TMPDIR"), os.environ.get("TEMP"), os.environ.get("TMP")]
+    if os.name != "nt":
+        raw.append("/tmp")
+    found: list[Path] = []
+    seen: set[str] = set()
+    for item in raw:
+        if not item:
+            continue
+        resolved = _resolved_path(Path(item))
+        if resolved is None:
+            continue
+        key = os.path.normcase(str(resolved))
+        if key in seen:
+            continue
+        seen.add(key)
+        found.append(resolved)
+    return found
+
+
+def temp_output_path(target: str) -> bool:
+    """True when a shell redirect target is a host-temp capture file."""
+    candidate = _resolved_path(Path(target.strip("\"'")))
+    if candidate is None:
+        return False
+    return any(_under(candidate, temp) for temp in temp_request_roots())
+
+
+def protocol_request_write(payload: object, root: Path) -> bool:
+    """Allow only host-temp JSON request files, never sibling trees or user hooks."""
+    targets = tool_target_strings(payload)
+    if not targets:
+        return False
+    root_resolved = _resolved_path(root)
+    temps = temp_request_roots()
+    if root_resolved is None or not temps:
+        return False
+    for item in targets:
+        candidate = Path(item).expanduser()
+        resolved = _resolved_path(candidate if candidate.is_absolute() else root / candidate)
+        if resolved is None or resolved.suffix.lower() != ".json":
+            return False
+        if _under(resolved, root_resolved):
+            return False
+        if any(part.lower() in {".claude", ".codex", ".cursor"} for part in resolved.parts):
+            return False
+        if not any(_under(resolved, temp) for temp in temps):
+            return False
+    return True
+
+
+def protocol_command(words: list[str], allowed: set[str]) -> bool:
+    """Recognize a Context Guard entry point without trusting its absolute path."""
+    if not words:
+        return False
+    entrypoints = {"context-guard", "context-guard-skill", "context_guard.py", "context-guard-skill.js"}
+    index = 0
+    first = words[0].strip("\"'")
+    if Path(first).name in {"node", "node.exe", "python", "python3", "python.exe"}:
+        index = 1
+    entry = words[index].strip("\"'") if index < len(words) else ""
+    return index < len(words) and Path(entry).name in entrypoints and index + 1 < len(words) and words[index + 1] in allowed
+
+
+def control_words(words: list[str]) -> bool:
+    """Protocol writes are their own audited recovery path, not product edits."""
+    return protocol_command(words, {
+        "plan-start", "plan-finish", "plan-status", "archive-session", "resolve-signal", "split-signal",
+        "record-todo", "record-bad-case", "record-bad-case-fix", "map", "sync", "workbench",
+        "preferences", "memory", "set-language", "write-candidates", "doctor",
+    })
+
+
+def diagnostic_words(words: list[str]) -> bool:
+    """Agents often append a no-op status probe after an audited command."""
+    if not words:
+        return False
+    return Path(words[0]).name in {"echo", "true", "false", "printf"}
+
+
+def shell_segments(command: str) -> list[list[str]] | None:
+    """Parse a conservative shell subset used for inspection pipelines."""
+    if not command.strip():
+        return []
+    if "\n" in command or "`" in command or "$(" in command:
+        return None
+    try:
+        # POSIX shlex consumes backslashes in an unquoted Windows path. Native
+        # shell syntax needs native token preservation so CLI paths remain valid.
+        lexer = shlex.shlex(command, posix=os.name != "nt", punctuation_chars=";&|<>")
+        lexer.whitespace_split = True
+        lexer.commenters = ""
+        tokens = list(lexer)
+    except ValueError:
+        return None
+    segments: list[list[str]] = []
+    current: list[str] = []
+    index = 0
+    while index < len(tokens):
+        token = tokens[index]
+        if token in {"|", "||", "&&", ";"}:
+            if not current:
+                return None
+            segments.append(current)
+            current = []
+            index += 1
+            continue
+        if token in {">", ">>", ">&", "&>", "<<", "<<<"}:
+            # Discarding diagnostic noise is harmless; every other output target writes.
+            if current and current[-1].isdigit():
+                current.pop()
+            target = tokens[index + 1] if index + 1 < len(tokens) else ""
+            if token == ">" and target == "/dev/null":
+                index += 2
+                continue
+            if token == ">&" and target.isdigit():
+                index += 2
+                continue
+            if token == "&>" and target == "/dev/null":
+                index += 2
+                continue
+            # Read-only inspection may capture CLI output in host temp without a plan.
+            if token in {">", ">>"} and current and read_only_words(current) and temp_output_path(target):
+                index += 2
+                continue
+            return None
+        if token == "<":
+            if current and current[-1].isdigit():
+                current.pop()
+            if index + 1 >= len(tokens) or tokens[index + 1] in {"|", "||", "&&", ";"}:
+                return None
+            index += 2
             continue
-        if current is None or not line.startswith("- ") or ":" not in line:
+        if re.fullmatch(r"(?:\d*)>&\d+", token):
+            index += 1
             continue
-        key, _, value = line[2:].partition(":")
-        current[key.strip().lower()] = value.strip()
+        if "&" in token:
+            return None
+        current.append(token)
+        index += 1
     if current:
-        blocks.append(current)
-    return blocks
+        segments.append(current)
+    return segments if segments else None
 
 
-def unresolved_bad_cases(path: Path) -> list[dict[str, str]]:
-    if not path.exists():
+def git_read_only(words: list[str]) -> bool:
+    if len(words) < 2:
+        return False
+    command_index = 1
+    while command_index < len(words) and words[command_index] in {"--no-pager", "-C"}:
+        if words[command_index] == "-C":
+            command_index += 2
+        else:
+            command_index += 1
+    if command_index >= len(words) or words[command_index].startswith("-"):
+        return False
+    command = words[command_index]
+    arguments = words[command_index + 1:]
+    if any(item in {"--output", "--ext-diff", "--textconv", "--open-files-in-pager"} or item.startswith("--output=") for item in arguments):
+        return False
+    if command in {"status", "diff", "log", "show", "ls-files", "rev-parse", "describe", "blame", "grep"}:
+        return True
+    if command == "worktree":
+        return bool(arguments) and arguments[0] == "list"
+    if command == "remote":
+        return not arguments or arguments == ["-v"] or arguments == ["--verbose"]
+    if command == "branch":
+        mutating = {"-d", "-D", "-m", "-M", "-c", "-C", "-t", "-u", "--delete", "--move", "--copy", "--track", "--no-track", "--edit-description", "--set-upstream-to", "--unset-upstream"}
+        if any(item in mutating or any(item.startswith(flag + "=") for flag in mutating if flag.startswith("--")) for item in arguments):
+            return False
+        return not arguments or any(item in {"--show-current", "--list", "-a", "--all", "-r", "--remotes", "-v", "-vv", "--verbose"} for item in arguments)
+    return False
+
+
+def curl_read_only(words: list[str]) -> bool:
+    forbidden = {
+        "-d", "--data", "--data-ascii", "--data-binary", "--data-raw", "--data-urlencode",
+        "-F", "--form", "--form-string", "-T", "--upload-file", "-o", "--output", "-O",
+        "--remote-name", "--remote-header-name", "-K", "--config", "--remove-on-error",
+    }
+    index = 1
+    while index < len(words):
+        item = words[index]
+        if item in forbidden or any(item.startswith(flag + "=") for flag in forbidden if flag.startswith("--")):
+            return False
+        if item.startswith("-") and len(item) > 2 and not item.startswith("--") and any(flag in item[1:] for flag in "dFToOK"):
+            return False
+        if item in {"-X", "--request"}:
+            if index + 1 >= len(words) or words[index + 1].upper() not in {"GET", "HEAD"}:
+                return False
+            index += 1
+        elif item.startswith("-X") and len(item) > 2 and item[2:].upper() not in {"GET", "HEAD"}:
+            return False
+        elif item.startswith("--request=") and item.split("=", 1)[1].upper() not in {"GET", "HEAD"}:
+            return False
+        index += 1
+    return True
+
+
+INTERPRETER_EXECUTABLES = {"python", "python3", "python.exe", "node", "node.exe"}
+READONLY_MAP_ACTIONS = {"status", "read", "changes", "inbox", "watch", "execution", "operation"}
+INSPECTION_PROTOCOL_COMMANDS = {
+    "plan-status", "doctor", "preferences", "set-language", "write-candidates",
+}
+INSPECTION_SYNC_ACTIONS = {"status", "pull"}
+INSPECTION_MEMORY_ACTIONS = {"status", "history"}
+MUTATING_PROTOCOL_COMMANDS = {
+    "plan-start", "plan-finish", "archive-session", "resolve-signal", "split-signal",
+    "record-todo", "record-bad-case", "record-bad-case-fix",
+}
+PYTHON_C_FORBIDDEN = (
+    "open(", "write(", "os.", "subprocess", "shutil", "pathlib", "import os", "exec(", "eval(", "__import__",
+)
+
+
+def protocol_entry_index(words: list[str]) -> int | None:
+    if not words:
+        return None
+    index = 0
+    first = words[0].strip("\"'")
+    if Path(first).name in INTERPRETER_EXECUTABLES:
+        index = 1
+    if index >= len(words):
+        return None
+    entry = Path(words[index].strip("\"'")).name
+    if entry not in {"context-guard", "context-guard-skill", "context_guard.py", "context-guard-skill.js"}:
+        return None
+    return index
+
+
+def inspection_protocol_words(words: list[str]) -> bool:
+    """Read-only Context Guard CLI output safe to pipe into inspection tools."""
+    index = protocol_entry_index(words)
+    if index is None or index + 1 >= len(words):
+        return False
+    command = words[index + 1]
+    if command in MUTATING_PROTOCOL_COMMANDS:
+        return False
+    if command == "map":
+        if index + 2 >= len(words):
+            return False
+        action = words[index + 2]
+        if action == "ci":
+            return index + 3 < len(words) and words[index + 3] == "context"
+        if action == "task":
+            return False
+        return action in READONLY_MAP_ACTIONS
+    if command == "sync":
+        return index + 2 < len(words) and words[index + 2] in INSPECTION_SYNC_ACTIONS
+    if command == "memory":
+        return index + 2 < len(words) and words[index + 2] in INSPECTION_MEMORY_ACTIONS
+    if command == "workbench":
+        return any(flag in words for flag in ("--diagnose", "--binding-status", "--list"))
+    return command in INSPECTION_PROTOCOL_COMMANDS
+
+
+def node_eval_read_only(script: str) -> bool:
+    stripped = script.strip()
+    # Only a literal diagnostic is safe; concatenation can evaluate arbitrary code.
+    return bool(re.fullmatch(r"""console\.log\((?:'[^'\\\r\n]*'|"[^"\\\r\n]*")\)\s*;?""", stripped))
+
+
+def python_c_read_only(script: str) -> bool:
+    if len(script) > 500 or any(token in script for token in PYTHON_C_FORBIDDEN):
+        return False
+    return True
+
+
+def interpreter_read_only(words: list[str]) -> bool:
+    if not words:
+        return False
+    executable = Path(words[0]).name
+    if executable not in INTERPRETER_EXECUTABLES:
+        return False
+    args = words[1:]
+    if not args:
+        return False
+    if args in (["--version"], ["-V"], ["-v"], ["--version"]):
+        return True
+    if executable.startswith("node") and len(args) == 2 and args[0] == "-e":
+        script = args[1]
+        # Non-POSIX shlex retains the shell quoting used on Windows. Unwrap only
+        # the complete script argument, not paths or arbitrary command segments.
+        if os.name == "nt" and len(script) >= 2 and script[0] == script[-1] and script[0] in {"'", '"'}:
+            script = script[1:-1]
+        return node_eval_read_only(script)
+    if len(args) >= 2 and args[0] == "-m" and args[1] == "json.tool":
+        return True
+    if args[0] == "-c" and len(args) >= 2:
+        return python_c_read_only(" ".join(args[1:]))
+    return False
+
+
+def bare_interpreter_pipe_sink(words: list[str]) -> bool:
+    return len(words) == 1 and Path(words[0]).name in INTERPRETER_EXECUTABLES
+
+
+def read_only_words(words: list[str]) -> bool:
+    if not words:
+        return False
+    if control_words(words):
+        return True
+    if protocol_command(words, {"workbench"}):
+        return "--diagnose" in words or "--binding-status" in words
+    if interpreter_read_only(words):
+        return True
+    executable = Path(words[0]).name
+    if executable in {"pwd", "ls", "cat", "head", "tail", "grep", "stat", "wc", "which", "type", "dirname", "basename", "realpath", "readlink", "printf", "echo", "true", "false"}:
+        return True
+    if executable == "rg":
+        return "--pre" not in words and not any(item.startswith("--pre=") for item in words)
+    if executable == "sed":
+        return not any(item.startswith("--in-place") or re.match(r"^-[^-]*i", item) for item in words[1:])
+    if executable == "find":
+        dangerous = {"-delete", "-exec", "-execdir", "-ok", "-okdir", "-fprint", "-fprint0", "-fprintf", "-fls"}
+        return not any(item in dangerous for item in words[1:])
+    if executable == "git":
+        return git_read_only(words)
+    if executable == "gh":
+        return len(words) >= 3 and (words[1], words[2]) in {
+            ("auth", "status"), ("pr", "checks"), ("pr", "list"),
+            ("pr", "view"), ("run", "view"), ("run", "list"),
+        }
+    if executable in {"ps", "pgrep", "lsof", "netstat", "ss"}:
+        return True
+    if executable == "kill":
+        return len(words) >= 3 and words[1] == "-0"
+    if executable in {"nc", "netcat"}:
+        return any(item == "-z" or (item.startswith("-") and "z" in item[1:]) for item in words[1:])
+    if executable == "curl":
+        return curl_read_only(words)
+    return False
+
+
+def read_only_shell(command: str) -> bool:
+    segments = shell_segments(command)
+    if segments is None:
+        return False
+    for index, segment in enumerate(segments):
+        if index > 0 and bare_interpreter_pipe_sink(segment) and inspection_protocol_words(segments[index - 1]):
+            continue
+        if not read_only_words(segment):
+            return False
+    return True
+
+
+def ci_tool_allowed(payload: object, execution: dict):
+    active = execution.get("active") or {}
+    if active.get("mode") != "ci" and not execution.get("ci"):
+        return None
+    return active.get("mode") == "ci" and tool_command(payload).strip() in (active.get("commands") or [])
+
+
+def control_tool(payload: object) -> bool:
+    """Only standalone protocol commands can recover a blocked lifecycle."""
+    segments = shell_segments(tool_command(payload))
+    if not segments:
+        return False
+    # Drop trailing diagnostic probes (`echo EXIT=$?`) after an audited command.
+    while len(segments) > 1 and diagnostic_words(segments[-1]) and not control_words(segments[-1]):
+        segments = segments[:-1]
+    if not control_words(segments[-1]):
+        return False
+    # Allow a literal stdin producer before an audited Context Guard command.
+    # Arbitrary programs and additional commands never inherit this exemption.
+    return len(segments) == 1 or (
+        len(segments) == 2
+        and Path(segments[0][0]).name in {"printf", "echo"}
+    )
+
+
+def git_changed_paths(root: Path) -> list[str]:
+    try:
+        result = subprocess.run(
+            ["git", "status", "--porcelain", "--untracked-files=all", "-z"], cwd=root, capture_output=True,
+            timeout=5, check=False, creationflags=WINDOWS_NO_WINDOW,
+        )
+    except (OSError, subprocess.SubprocessError):
         return []
-    resolved_statuses = {"resolved", "done", "superseded-by-route-change"}
-    cases = bad_case_blocks(path.read_text(encoding="utf-8"))
-    return [
-        case
-        for case in cases
-        if case.get("status", "").strip().lower() not in resolved_statuses
-    ]
+    if result.returncode:
+        return []
+    paths: set[str] = set()
+    for entry in result.stdout.decode("utf-8", errors="replace").split("\0"):
+        if len(entry) < 4:
+            continue
+        value = entry[3:]
+        if " -> " in value:
+            value = value.split(" -> ", 1)[1]
+        if value and not value.startswith(".codex/context/private/"):
+            paths.add(value)
+    return sorted(paths)
+
+
+def mutating_tool(payload: object) -> bool:
+    if not isinstance(payload, dict):
+        return False
+    if write_like_tool(payload):
+        return True
+    name = str(payload.get("tool_name") or payload.get("toolName") or "").lower()
+    if name not in {"bash", "exec_command", "shell", "run_shell_command"}:
+        return False
+    if control_tool(payload):
+        return False
+    command = tool_command(payload).strip()
+    # Unknown scripts stay potentially mutating. Inspection pipelines are allowed
+    # only when every command and redirection is independently read-only.
+    return not read_only_shell(command)
+
+
+def post_plan_delivery_command(payload: object, root: Path) -> bool:
+    """Allow only repository delivery after reviewed work is archived and finished."""
+    command = tool_command(payload)
+    segments = shell_segments(command)
+    if not segments or len(segments) != 1:
+        return False
+    words = segments[0]
+    if not words or any(char in command for char in ("$", "`", "\n")):
+        return False
+    executable = Path(words[0]).name
+    if executable == "git":
+        index = 1
+        if index < len(words) and words[index] == "-C":
+            if index + 1 >= len(words) or _resolved_path(Path(words[index + 1])) != root.resolve():
+                return False
+            index += 2
+        if index < len(words) and words[index] == "push":
+            return not any(arg in {"--force", "-f", "--force-with-lease", "--mirror", "--delete"}
+                           or arg.startswith("--force-") for arg in words[index + 1:])
+        return False
+    if executable == "gh" and len(words) >= 3 and words[1] == "pr":
+        if words[2] not in {"create", "merge"}:
+            return False
+        if words[2] == "merge" and (len(words) < 4 or not re.fullmatch(r"[1-9]\d*", words[3])):
+            return False
+        return not any(arg in {"--admin", "--repo", "-R", "--delete-branch"}
+                       or arg.startswith(("--repo=", "--admin=")) for arg in words[3:])
+    return False
+
+
+def gh_pr_merge_command(payload: object) -> bool:
+    """Recognize PR merges even when wrapped in shell chaining or redirection."""
+    command = tool_command(payload)
+    segments = shell_segments(command)
+    if segments and any(len(words) >= 3 and Path(words[0]).name == "gh" and words[1:3] == ["pr", "merge"]
+                        for words in segments):
+        return True
+    return bool(re.search(r"\bgh\s+pr\s+merge\b", command))
 
 
-def format_unresolved_bad_cases(cases: list[dict[str, str]], limit: int = 5) -> str:
-    if not cases:
-        return "none"
-    parts = []
-    for case in cases[:limit]:
-        status = case.get("status", "unknown") or "unknown"
-        title = case.get("title", "Untitled bad case")
-        phenomenon = case.get("phenomenon", "").strip()
-        summary = f"{title} ({status})"
-        if phenomenon:
-            summary += f" - {phenomenon}"
-        parts.append(summary)
-    if len(cases) > limit:
-        parts.append(f"{len(cases) - limit} more unresolved bad cases")
-    return "; ".join(parts)
+def post_plan_merge_target(payload: object) -> str | None:
+    segments = shell_segments(tool_command(payload))
+    words = segments[0] if segments and len(segments) == 1 else []
+    return words[3] if len(words) >= 4 and Path(words[0]).name == "gh" and words[1:3] == ["pr", "merge"] else None
+
+
+def merge_checks_green(pr: dict, source_sha: str) -> bool:
+    checks = pr.get("statusCheckRollup")
+    if (pr.get("state") != "OPEN" or pr.get("mergeStateStatus") != "CLEAN" or
+            pr.get("headRefOid") != source_sha or not isinstance(checks, list) or not checks or len(checks) > 100):
+        return False
+    def passed(check: dict) -> bool:
+        if check.get("__typename") == "CheckRun":
+            return check.get("status") == "COMPLETED" and check.get("conclusion") in {"SUCCESS", "SKIPPED"}
+        return check.get("__typename") == "StatusContext" and check.get("state") == "SUCCESS"
+    return all(isinstance(check, dict) and passed(check) for check in checks) and any(
+        check.get("conclusion") == "SUCCESS" or check.get("state") == "SUCCESS" for check in checks)
+
+
+def billing_waiver_checks(root: Path, pr: dict, source_sha: str) -> bool:
+    """An expiring, repository-scoped waiver for GitHub jobs blocked before startup."""
+    repository = os.environ.get("CONTEXT_GUARD_GITHUB_BILLING_WAIVER_REPO", "")
+    expires_at = os.environ.get("CONTEXT_GUARD_GITHUB_BILLING_WAIVER_UNTIL", "")
+    try:
+        deadline = datetime.fromisoformat(expires_at.replace("Z", "+00:00"))
+        if not re.fullmatch(r"[\w.-]+/[\w.-]+", repository) or deadline.tzinfo is None or datetime.now(timezone.utc) >= deadline:
+            return False
+        if pr.get("state") != "OPEN" or pr.get("mergeStateStatus") != "UNSTABLE" or pr.get("headRefOid") != source_sha:
+            return False
+        rollup = pr.get("statusCheckRollup")
+        if not isinstance(rollup, list) or not rollup or any(not isinstance(item, dict) or
+            (item.get("__typename") == "StatusContext" and item.get("state") != "SUCCESS") or
+            (item.get("__typename") == "CheckRun" and (item.get("status") != "COMPLETED" or
+                item.get("conclusion") not in {"SUCCESS", "SKIPPED", "FAILURE"})) or
+            item.get("__typename") not in {"StatusContext", "CheckRun"} for item in rollup):
+            return False
+        repo_result = subprocess.run(["gh", "repo", "view", "--json", "nameWithOwner"], cwd=root,
+                                     capture_output=True, text=True, timeout=15, check=False, creationflags=WINDOWS_NO_WINDOW)
+        if repo_result.returncode or json.loads(repo_result.stdout).get("nameWithOwner") != repository:
+            return False
+        runs_result = subprocess.run(["gh", "api", f"repos/{repository}/commits/{source_sha}/check-runs?filter=latest&per_page=100"],
+                                     cwd=root, capture_output=True, text=True, timeout=15, check=False, creationflags=WINDOWS_NO_WINDOW)
+        if runs_result.returncode:
+            return False
+        result = json.loads(runs_result.stdout)
+        checks = result.get("check_runs")
+        if not isinstance(checks, list) or not checks or len(checks) > 100 or result.get("total_count") != len(checks):
+            return False
+        failed = [check for check in checks if check.get("conclusion") == "failure"]
+        if not failed or any(not isinstance(check, dict) or check.get("head_sha") != source_sha or check.get("status") != "completed" or
+                             check.get("conclusion") not in {"success", "skipped", "failure"} for check in checks):
+            return False
+        for check in failed:
+            if not isinstance(check.get("id"), int) or check["id"] <= 0:
+                return False
+            annotations = subprocess.run(["gh", "api", f"repos/{repository}/check-runs/{check['id']}/annotations?per_page=100"],
+                                         cwd=root, capture_output=True, text=True, timeout=15, check=False,
+                                         creationflags=WINDOWS_NO_WINDOW)
+            if annotations.returncode or not any(isinstance(item, dict) and
+                "The job was not started because recent account payments have failed or your spending limit needs to be increased." in item.get("message", "")
+                for item in json.loads(annotations.stdout)):
+                return False
+        return True
+    except (OSError, ValueError, TypeError, subprocess.SubprocessError):
+        return False
+
+
+def verified_merge_checks(root: Path, number: str) -> bool:
+    try:
+        head = subprocess.run(["git", "rev-parse", "HEAD"], cwd=root, capture_output=True, text=True,
+                              timeout=5, check=False, creationflags=WINDOWS_NO_WINDOW)
+        pr = subprocess.run(["gh", "pr", "view", number, "--json", "state,mergeStateStatus,statusCheckRollup,headRefOid"],
+                            cwd=root, capture_output=True, text=True, timeout=15, check=False,
+                            creationflags=WINDOWS_NO_WINDOW)
+        if head.returncode or pr.returncode:
+            return False
+        details = json.loads(pr.stdout)
+        return merge_checks_green(details, head.stdout.strip()) or billing_waiver_checks(root, details, head.stdout.strip())
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return False
+
+
+def post_plan_delivery_ready(runtime: dict, execution: dict, root: Path) -> bool:
+    last = runtime.get("last_plan") if isinstance(runtime.get("last_plan"), dict) else {}
+    active = execution.get("active") or {}
+    acceptance = active.get("acceptanceReview") or {}
+    return (active.get("mode") == "reviewed"
+            and acceptance.get("decision") == "approved"
+            and last.get("status") == "completed"
+            and isinstance(last.get("archive"), dict)
+            and not git_changed_paths(root))
+
+
+def pending_signals(runtime: dict) -> list[str]:
+    return [str(item.get("id")) for item in runtime.get("signals", [])
+            if isinstance(item, dict) and item.get("status") == "pending"]
+
+
+def pending_signal_guidance(root: Path, session_id: str, runtime: dict) -> str:
+    ids = pending_signals(runtime)
+    command = (f"{context_guard_cli()} resolve-signal --root {json.dumps(str(root))} "
+               f"--session {json.dumps(session_id)} --signal {ids[0]} --kind task")
+    return ("Classify pending user signals before implementation: " + ", ".join(ids)
+            + ". If this is the already-mounted Cloud task, run " + command
+            + ". For a new request, record the appropriate TODO or Bug instead. Do not try another write tool.")
+
+
+def scope_paths(root: Path, values: object) -> list[str]:
+    if not isinstance(values, list) or not values:
+        raise ValueError("plan needs non-empty paths")
+    result = []
+    for value in values:
+        if not isinstance(value, str) or not value.strip():
+            raise ValueError("scope paths must be strings")
+        candidate = Path(value)
+        if candidate.is_absolute() or ".." in candidate.parts or value in {".", "./"}:
+            raise ValueError("scope paths must be specific repository-relative files/directories")
+        (root / candidate).resolve().relative_to(root.resolve())
+        result.append(candidate.as_posix().rstrip("/") + ("/" if value.endswith("/") else ""))
+    return sorted(set(result))
+
+
+def in_scope(file: str, paths: list[str]) -> bool:
+    return any(file == item.rstrip("/") or file.startswith(item.rstrip("/") + "/") for item in paths)
+
+
+def scope_snapshot(root: Path, paths: list[str]) -> dict[str, str]:
+    """Content hashes, not dirty filenames: edits to already dirty files count."""
+    result = {}
+    for value in paths:
+        target = root / value
+        files = target.rglob("*") if target.is_dir() else [target]
+        for file in files:
+            relative = file.relative_to(root).as_posix()
+            if any(part in {".git", ".codex", "node_modules", "__pycache__"} for part in file.relative_to(root).parts):
+                continue
+            if file.is_symlink():
+                result[relative] = "link:" + os.readlink(file)
+            elif file.is_file():
+                result[relative] = hashlib.sha256(file.read_bytes()).hexdigest()
+    return result
+
+
+def checked_sync(root: Path, session: str, action: str, paths: list[str] | None = None) -> dict:
+    value = sync_command(root, action, session, paths)
+    if value.get("error") or value.get("status") == "conflict":
+        raise ValueError(f"Cloud {action} failed: {json.dumps(value, ensure_ascii=False)}")
+    return value
+
+
+def prepare_plan_sync(root: Path, session: str, paths: list[str]) -> dict:
+    # The caller has already verified live node grants, reads and the inbox.
+    # A transport outage is not a code-delivery verdict. Conflicts and denied
+    # authority remain blocking; no local baseline is fabricated or replaced.
+    value = sync_command(root, "prepare", session, paths)
+    code = (value.get("error") or {}).get("code")
+    if value.get("status") != "conflict" and code in {"MEMORY_UNAVAILABLE", "SYNC_TOOL_FAILED", "HTTP_ERROR", "UNAVAILABLE"}:
+        return {"pending": True, "code": code}
+    if value.get("error") or value.get("status") == "conflict":
+        raise ValueError("Cloud prepare requires reconciliation or authorization")
+    return value
+
+
+def plan_command(root: Path, session: str, command: str, data: dict) -> dict:
+    with hook_runtime_lock(root, session):
+        return _plan_command_locked(root, session, command, data)
+
+
+def _plan_command_locked(root: Path, session: str, command: str, data: dict) -> dict:
+    runtime = read_hook_runtime(root, session)
+    if command == "plan-status":
+        return {"active_plan": runtime.get("active_plan"), "last_plan": runtime.get("last_plan"), "pending_signals": pending_signals(runtime)}
+    if session not in {str(item.get("session_id")) for item in session_records(root)}:
+        raise ValueError("plan needs an actual lifecycle session")
+    if pending_signals(runtime):
+        raise ValueError(pending_signal_guidance(root, session, runtime))
+    ctx = context_folder(root)
+    plan = runtime.get("active_plan")
+    if command == "plan-start":
+        if plan and data.get("extend") is not True:
+            raise ValueError("A plan is already active; finish it before opening another")
+        if data.get("approved") is not True or not str(data.get("summary", "")).strip():
+            raise ValueError("plan-start needs approved:true and summary; an explicit implementation request already satisfies approval")
+        paths = scope_paths(root, data.get("paths"))
+        nodes = data.get("node_ids")
+        if not isinstance(nodes, list) or not nodes or not all(isinstance(item, str) for item in nodes):
+            raise ValueError("plan-start needs node_ids")
+        # A Cloud-reviewed task needs the actual Coordinator receipt, not the
+        # developer's approved:true attestation. Ordinary manual plans retain
+        # their existing explicit-user-approval contract.
+        execution = run_node_workbench(["map", "execution", "--root", str(root), "--session", session])
+        active = execution.get("active") or {}
+        if active.get("mode") == "ci" or execution.get("ci"):
+            raise ValueError("CI uses its assigned test authorization; it cannot start a development Plan")
+        if active.get("mode") == "reviewed":
+            reviewed = execution.get("plan") or {}
+            approved = active.get("plan") or {}
+            if not active.get("approval") or reviewed.get("kind") != "plan" or reviewed.get("version") != approved.get("version"):
+                raise ValueError("Coordinator must approve this exact Cloud Plan before development")
+            if data.get("taskId") != active.get("taskId") or data.get("planRef") != approved.get("ref") or data.get("planVersion") != approved.get("version"):
+                raise ValueError("plan-start must identify the approved taskId, planRef and planVersion")
+            allowed_paths = scope_paths(root, (reviewed.get("content") or {}).get("paths"))
+            if set(nodes) - set(active.get("nodeIds") or []) or any(not any(value == allowed or value.startswith(allowed.rstrip("/") + "/") for allowed in allowed_paths) for value in paths):
+                raise ValueError("Local plan scope exceeds the approved Cloud Plan")
+            if plan:
+                raise ValueError("Finish the previous local plan before starting a Cloud-reviewed Plan")
+            head = subprocess.run(["git", "rev-parse", "HEAD"], cwd=root, capture_output=True, text=True, timeout=5, check=False, creationflags=WINDOWS_NO_WINDOW)
+            if head.returncode or head.stdout.strip() != approved.get("sourceSha"):
+                raise ValueError("Worktree HEAD differs from the approved Plan base SHA")
+        # Fresh API read checks page drafts and actual session authorization.
+        state = run_node_workbench(["map", "status", "--root", str(root), "--session", session])
+        missing = set(nodes) - set(state.get("grants") or [])
+        if missing:
+            raise ValueError("Map authorization required: " + ", ".join(sorted(missing)))
+        for node in nodes:
+            run_node_workbench(["map", "read", "--root", str(root), "--session", session, "--node", node])
+        inbox = run_node_workbench(["map", "inbox", "--root", str(root), "--session", session, "--start"])
+        if inbox.get("pending"):
+            raise ValueError("Read/process and acknowledge Map inbox before starting the plan")
+        if plan:
+            old_paths = plan["paths"]
+            baseline = scope_snapshot(root, paths)
+            dirty_paths = set(git_changed_paths(root))
+            # Keep the original baseline inside the old scope: an extension
+            # must not hide earlier edits or complete pending acceptance.
+            for file, digest in baseline.items():
+                if not any(file == value or file.startswith(value.rstrip("/") + "/") for value in old_paths):
+                    if file in dirty_paths:
+                        prior = subprocess.run(["git", "show", "HEAD:" + file], cwd=root, capture_output=True, timeout=5, check=False, creationflags=WINDOWS_NO_WINDOW)
+                        plan["scope_review_required"] = True
+                        if prior.returncode:
+                            continue
+                        digest = hashlib.sha256(prior.stdout).hexdigest()
+                    plan["baseline"].setdefault(file, digest)
+            plan["paths"] = sorted(set(old_paths + paths))
+            plan["node_ids"] = sorted(set(plan["node_ids"] + nodes))
+            if sync_configured(root, session):
+                checked_sync(root, session, "checkpoint")
+            plan.setdefault("amendments", []).append({"at": utc_now(), "summary": data["summary"], "paths": paths, "node_ids": nodes})
+            plan["revision"] += 1
+            plan.pop("archive", None)
+            write_hook_runtime(root, session, runtime)
+            append_session_event(root, "plan-extend", "cli", session, {"plan_id": plan["id"], "occurred_at": utc_now()})
+            return plan
+        baseline = scope_snapshot(root, paths)
+        sync = prepare_plan_sync(root, session, paths) if sync_configured(root, session) else {}
+        plan = {"id": "plan-" + hashlib.sha256(f"{session}:{utc_now()}".encode()).hexdigest()[:20],
+                "summary": data["summary"], "status": "working", "started_at": utc_now(),
+                "node_ids": sorted(set(nodes)), "paths": paths, "actual_paths": [],
+                "baseline": baseline, "revision": 0, "map_version": state.get("version"), "sync": sync,
+                "delivery": {"source": "working", "memory": "pending" if sync.get("pending") else "ready"}}
+        runtime["active_plan"] = plan
+    else:
+        if not isinstance(plan, dict):
+            if isinstance(runtime.get("last_plan"), dict) and runtime["last_plan"].get("status") == "completed":
+                return runtime["last_plan"]
+            raise ValueError("No active plan")
+        receipt = plan.get("archive")
+        if not isinstance(receipt, dict) or receipt.get("revision") != plan.get("revision"):
+            raise ValueError("Archive this plan with verification and node assessment before plan-finish")
+        require_human_work_review(root, session, plan)
+        if scope_snapshot(root, plan["paths"]) != receipt.get("snapshot"):
+            raise ValueError("Files changed after archive; verify and archive again")
+        inbox = run_node_workbench(["map", "inbox", "--root", str(root), "--session", session])
+        if inbox.get("pending"):
+            raise ValueError("Other Map changes need review and acknowledgement before plan-finish")
+        if sync_configured(root, session):
+            if (plan.get("sync") or {}).get("pending"):
+                plan["sync"] = checked_sync(root, session, "prepare", plan["paths"])
+                write_hook_runtime(root, session, runtime)
+            checked_sync(root, session, "checkpoint")
+            finished = checked_sync(root, session, "finish")
+            if finished.get("confirmed") is not True:
+                raise ValueError("Cloud did not confirm completion")
+        plan["status"] = "completed"
+        plan["delivery"] = {"source": "verified", "memory": "confirmed"}
+        plan["completed_at"] = utc_now()
+        latest = read_hook_runtime(root, session)
+        active = latest.get("active_plan") or {}
+        if pending_signals(latest) or active.get("id") != plan["id"] or active.get("revision") != plan.get("revision"):
+            raise ValueError("New prompts or tool activity arrived during finish; review before completing")
+        runtime = latest
+        runtime["last_plan"] = plan
+        runtime["active_plan"] = None
+    write_hook_runtime(root, session, runtime)
+    append_session_event(root, command, "cli", session, {"plan_id": plan["id"], "occurred_at": utc_now(), "result": plan["status"]})
+    return plan
 
 
 def main() -> int:
-    event = sys.argv[1] if len(sys.argv) > 1 else "unknown"
+    configure_stdio()
+    parser = argparse.ArgumentParser(description="Context Guard hook adapter")
+    parser.add_argument("event", nargs="?", default="unknown")
+    parser.add_argument("--platform", choices=["codex", "cursor", "claude"], default="codex")
+    args, _unknown = parser.parse_known_args()
+    event = args.event
+    platform = args.platform
     raw = read_stdin()
-    root, root_source = event_root(raw, Path.cwd(), event)
-    context_dir = root / ".codex" / "context"
-    index_path = context_dir / "index.md"
-    roadmap_path = context_dir / "roadmap.md"
-    bad_cases_path = context_dir / "bad-cases.md"
-    text = prompt_text(raw)
-
-    if is_context_guard_skill_path(root):
-        hook_log(
-            "[context-guard] detected Context Guard skill directory as the apparent root; "
-            "skipping project context writes. Open the target Codex folder or pass an explicit local `--root` "
-            "when showing/updating a roadmap."
-        )
-        hook_log(f"[context-guard] apparent root source: {root_source}; apparent root: {root}")
-        return hook_response()
-
-    if event in {"session-start", "subagent-start"}:
-        created = init_context(root)
-        label = "subagent context" if event == "subagent-start" else "folder context"
-        if created:
-            hook_log(f"[context-guard] initialized {label}: {context_dir}")
-        else:
-            hook_log(f"[context-guard] {label} ready: {context_dir}")
-        hook_log(f"[context-guard] project root: {root} ({root_source})")
-        hook_log("[context-guard] context location rule: save project context only under `<opened local Codex project root>/.codex/context/`.")
-        hook_log("[context-guard] use .codex/context/index.md for quick scan and .codex/context/roadmap.md for route nodes.")
-        return hook_response()
-
-    if event == "user-prompt-submit":
-        record_status, record_mode = append_user_message(context_dir, text)
-        hints: list[str] = []
-        if record_status == "recorded":
-            if record_mode == "redacted":
-                hints.append("user message memory: saved latest prompt with secrets redacted; raw secret, if durable, is local-only under `.codex/context/private/`")
-            elif record_mode == "ephemeral":
-                hints.append("user message memory: saved latest prompt with one-time code redacted; raw ephemeral code was not persisted")
-            elif record_mode == "summary":
-                hints.append("user message memory: saved a concise summary of the latest large prompt instead of copying the full blob")
-            else:
-                hints.append("user message memory: saved latest short user prompt in `.codex/context/user-messages.md`")
-        else:
-            hints.append(f"user message memory: skipped ({record_mode})")
-        if looks_like_goal_mode(text):
-            hints.append("goal mode: align active goal with current context and record roadmap/bad-case checkpoints during long-running work")
-        if looks_like_remote_work(text):
-            hints.append("remote/SSH work: keep `.codex/context` in the local Codex workspace; record remote host/path as metadata and do not initialize roadmap context on the server unless explicitly requested")
-        if looks_like_test_creation(text):
-            hints.append("explicit test creation: start the user-visible response with `测试创建识别：...`, summarize the test target from state A to state B, and only create durable tests after the user's design is clear or confirmed")
-        elif looks_like_test_opportunity(text):
-            hints.append("test opportunity: if this task changes a reusable workflow, fixes a recurring/user-visible bug, or is likely to regress, gently ask whether the user wants to create a test task; keep it optional and do not create durable tests without approval")
-        if looks_like_explicit_branch(text):
-            hints.append("explicit branch task: create/select a branch task by running `context_guard.py create-branch-task --title <task title> --branch <branch name> --parent-node <parent NODE id>` before implementation; verify the roadmap node has Branch: and Parent:")
-        elif looks_like_route_drift(text):
-            hints.append("possible route drift: ask whether to create a branch before moving away from the current mainline architecture")
-        if looks_like_task_switch(text):
-            hints.append("possible task switch: park current context in .codex/context/index.md before switching")
-        if looks_like_bad_case(text):
-            hints.append("possible bad case: record/update .codex/context/bad-cases.md or task-local bad-cases.md")
-        if not hints:
-            hints.append("run Context Guard intake: continue current context or note no active context")
-        hook_log("[context-guard] " + "; ".join(hints))
-        hook_log(f"[context-guard] root source: {root_source}")
-        hook_log(f"[context-guard] project root: {root}")
-        hook_log(f"[context-guard] context folder: {context_dir}")
-        hook_log(f"[context-guard] context index: {index_path}")
-        hook_log(f"[context-guard] route map: {roadmap_path}")
-        return hook_response()
-
-    if event in {"stop", "subagent-stop"}:
-        lifecycle_label = "SubagentStop" if event == "subagent-stop" else "Stop"
-        hook_log(f"[context-guard] {lifecycle_label} checkpoint: update index, route map nodes, parked/resume tasks, and relevant bad-case/test-chain links before finalizing.")
-        hook_log("[context-guard] COMPLETION RELIABILITY GATE: use existing user screenshots/logs/reproductions as red evidence when available; implement once the cause is clear, then run the smallest real post-fix check. Default budget is one primary check plus at most two highly relevant bad-case guards.")
-        hook_log("[context-guard] BAD-CASE GUARD GATE: newly checked resolved or recurred BC entries need Guard type, Red condition, Green condition, Expected failure reason, and a red-capable Guard / verification; run `context_guard.py validate-bad-cases` only after register/schema/renderer edits, or `--strict` when intentionally migrating/checking all resolved cases.")
-        hook_log("[context-guard] GUARD SELECTION GATE: do not run every historical guard and do not manufacture new red tests when credible evidence already exists. Select guards by changed files, feature area, route branch, tags, and original user-visible symptom; skip unrelated resolved cases.")
-        hook_log("[context-guard] TEST HUB GATE: Stop/SubagentStop hooks run `context_guard.py dev-complete --root <project>` so the hub executes every human-approved `every-dev-completion` test, cleans success artifacts, and preserves failed/blocked evidence. Do not treat ordinary bad-case guards or roadmap Test chain notes as registered tests.")
-        hook_log("[context-guard] TASK-CASE GATE: when a workflow has multiple phases, prefer one relevant task case from `.codex/context/task-cases/` with phase/checkpoint logs over many isolated bug-level tests; report the failed phase/checkpoint if it breaks.")
-        hook_log("[context-guard] TEST BLOCKER GATE: if approved tests are blocked by credentials, external service outage, permission denial, hardware/resource limits, network, destructive-risk confirmation, or user-only judgment, stop and ask/warn the user with the exact blocker and evidence path.")
-        hook_log("[context-guard] TASK-CASE DESIGN GATE: before writing a new durable task-case script for a complex workflow, ask the user to confirm a short business-facing proposal: from what state to what state, main task, and major risk; keep technical details inside the task-case file, or keep it `proposed` if unavailable.")
-        hook_log("[context-guard] TEST OPPORTUNITY GATE: if this turn changed a reusable workflow, fixed a recurring/user-visible bug, or created a phase that is likely to regress, include a brief optional nudge asking whether the user wants to create a test task. Do not create durable tests unless the user confirms.")
-        hook_log("[context-guard] GOAL-MODE TEST GATE: in goal mode, use task cases as phase gates; log current phase progress and run the smallest approved path before claiming goal completion instead of silently creating broad new tests.")
-        hook_log("[context-guard] ROADMAP CHECKPOINT GATE: assess whether this turn deserves a roadmap node. Create one only for meaningful progress, a route decision, a fix, a branch/fork, a user-visible milestone, or stale hidden checkpoints; otherwise say no roadmap node was needed and why.")
-        hook_log("[context-guard] If a node is needed, run `context_guard.py checkpoint-roadmap-node --title <short title> --branch <Main or route> --level <major|checkpoint> --outcome <one-line progress> --next-step <next>` and include linked BC/test-chain notes when relevant.")
-        hook_log("[context-guard] ROADMAP MAINTENANCE GATE: run `context_guard.py validate-roadmap-maintenance` after route updates; do not let mainline/branch overview stay stale while important work is hidden as checkpoints.")
-        hook_log("[context-guard] If frontend/UI/HTML/CSS/layout/browser behavior changed, inspect with browser/screenshot or state the exact blocker; do not claim fixed without this evidence.")
-        hook_log("[context-guard] Branch task gate: if the user explicitly asked for a branch, ensure `context_guard.py create-branch-task --title <task title> --branch <branch name> --parent-node <parent NODE id>` has created the task folder, index current entry, and Branch/Parent roadmap node; if the work significantly drifts from the mainline architecture, ask whether to create a branch before finalizing.")
-        hook_log("[context-guard] final answer must include verification evidence and must not say done/fixed/passing unless the gate above was satisfied.")
-        hook_log(f"[context-guard] root source: {root_source}")
-        hook_log(f"[context-guard] project root: {root}")
-        hook_log(f"[context-guard] context folder: {context_dir}")
-        hook_log(f"[context-guard] bad-case register: {bad_cases_path}")
-        if event == "subagent-stop":
-            payload = parse_hook_payload(raw)
-            agent_id = hook_agent_id(payload)
-            last_message = hook_text_field(payload, "last_assistant_message")
-            control_root = registered_subagent_control_root(payload, Path.cwd(), agent_id)
-            command_root = control_root or root
-            command = [
-                sys.executable,
-                str(SKILL_ROOT / "scripts" / "context_guard.py"),
-                "subagent-complete",
-                "--root",
-                str(command_root),
-                "--agent-id",
-                agent_id,
-                "--summary",
-                last_message,
-            ]
+    payload = parse_hook_payload(raw)
+    root, root_source = event_root(raw, Path.cwd())
+    ctx = context_folder(root)
+
+    if is_context_guard_skill_path(root) and not initialized_source_project(root):
+        hook_log("[context-guard] apparent root is the skill directory; skipping writes.")
+        return hook_response(platform, event)
+    current_session_id = session_id(payload, platform, ctx, event)
+    current_session_name = session_display_name(payload, platform, root, current_session_id)
+    memory_notice = ""
+    verified_workbench_url = ""
+
+    def session_details(details: dict[str, object] | None = None) -> dict[str, object]:
+        result = dict(details or {})
+        result["worktree_root"] = str(root)
+        if current_session_name:
+            result["thread_name"] = current_session_name
+        return result
+
+    # Binding precedes initialization, memory reads, and service startup.
+    # The unbound lifecycle record is registration evidence, not project memory.
+    if event in {"session-start", "subagent-start", "user-prompt-submit", "post-compact"}:
+        try:
+            binding = run_node_workbench(["workbench", "--binding-status", "--root", str(root), "--session", current_session_id])
+        except (OSError, ValueError, RuntimeError, subprocess.TimeoutExpired):
+            return hook_response(platform, event, "Context Guard binding unreadable; preserve data. Run workbench --diagnose.")
+        if not binding.get("session", {}).get("bound"):
+            current_workbench = None
             try:
-                completed = subprocess.run(
-                    command,
-                    cwd=str(root),
-                    text=True,
-                    capture_output=True,
-                    timeout=900,
+                inventory = run_node_workbench(["workbench", "--list", "--root", str(root)])
+                candidate = inventory.get("currentProject")
+                if isinstance(candidate, dict):
+                    current_workbench = candidate
+            except (OSError, ValueError, RuntimeError, subprocess.TimeoutExpired):
+                # Binding diagnosis remains authoritative for this Session. A
+                # failed global inventory must not create or select a service.
+                current_workbench = None
+            ctx.mkdir(parents=True, exist_ok=True)
+            registration = {
+                "at": utc_now(), "event": event, "platform": platform,
+                "session_id": current_session_id, "thread_name": current_session_name,
+                "binding": "required",
+            }
+            registration.update(audit_details(payload, event, current_session_id, {}, {"root_source": root_source}))
+            with (ctx / "sessions.jsonl").open("a", encoding="utf-8") as stream:
+                stream.write(json.dumps(registration, ensure_ascii=False) + "\n")
+            main_notice = "First ask which remote/branch is authoritative; persist with workbench --bind-main or --local-main. " if binding.get("bindingRequired") else ""
+            previous = binding.get("session", {})
+            target = previous.get("worktreeRoot")
+            prior = f" It is currently recorded against {target}; use --rebind only after explicit confirmation." if target else ""
+            status = str(current_workbench.get("status") or "unknown") if current_workbench else ""
+            established = bool(current_workbench and (current_workbench.get("registered") or current_workbench.get("runningInstances") == 1))
+            binding_state = str(previous.get("state") or "unbound")
+            safe_existing_binding = binding_state in {"current", "moved"}
+            automatic = (not target or safe_existing_binding) and not binding.get("bindingRequired") and established and status in {
+                "ready", "direct-only", "route-stale", "stopped", "upgrade-required"
+            }
+            if automatic:
+                try:
+                    repaired = run_node_workbench([
+                        "workbench", "--root", str(root), "--session", current_session_id,
+                    ])
+                    verified_workbench_url = str(repaired.get("url") or "")
+                    binding = run_node_workbench([
+                        "workbench", "--binding-status", "--root", str(root),
+                        "--session", current_session_id,
+                    ])
+                    if not binding.get("session", {}).get("bound") or not binding.get("session", {}).get("verified"):
+                        raise RuntimeError("automatic binding receipt was not verified")
+                except (OSError, ValueError, RuntimeError, subprocess.TimeoutExpired):
+                    return hook_response(
+                        platform, event,
+                        "Context Guard automatic binding unverified. "
+                        f"Run {context_guard_cli()} workbench --root {json.dumps(str(root))} --session {json.dumps(current_session_id)} to retry the same binding. "
+                        "Existing workbench preserved.",
+                    )
+            elif current_workbench:
+                status = str(current_workbench.get("status") or "unknown")
+                url = str(current_workbench.get("url") or "")
+                readable = f" at {url}" if url else ""
+                if status in {"legacy", "duplicate", "unknown", "route-mismatch"}:
+                    return hook_response(
+                        platform, event,
+                        main_notice + f"This Session is not bound to the current worktree.{prior} "
+                        f"The matching project workbench{readable} is {status}. Do not create or bind another service. "
+                        f"Run {context_guard_cli()} workbench --diagnose --root {json.dumps(str(root))} and resolve that runtime first.",
+                    )
+                return hook_response(
+                    platform, event,
+                    main_notice + f"This Session is not bound to the current worktree.{prior} "
+                    f"The project workbench candidate{readable} is {status} and cannot be selected automatically. Ask which workbench to use. "
+                    "See SKILL.md for binding.",
                 )
-            except subprocess.TimeoutExpired:
-                reason = "Context Guard subagent completion timed out after 900s."
-                hook_log(f"[context-guard] TEST HUB BLOCKER: {reason}")
-                return hook_response(decision="block", reason=reason)
-            except Exception as exc:
-                reason = f"Context Guard could not run subagent completion: {exc}"
-                hook_log(f"[context-guard] COMPLETION BLOCKER: {reason}")
-                return hook_response(decision="block", reason=reason)
-            completion_output = "\n".join(
-                part for part in [completed.stdout.strip(), completed.stderr.strip()] if part
-            )
-            for line in completion_output.splitlines():
-                hook_log(line)
-            hook_log(
-                "[context-guard] final answer must include Test Hub summary: "
-                + completion_test_summary(completion_output, completed.returncode)
-            )
-            if completed.returncode != 0:
-                details = completion_test_failure_details(root)
-                reason = "Context Guard subagent completion found failed or blocked approved tests."
-                if details:
-                    reason += " Failing tests: " + details
-                hook_log(f"[context-guard] TEST HUB BLOCKER: {reason}")
-                return hook_response(decision="block", reason=reason)
-            open_cases = unresolved_bad_cases(bad_cases_path)
-            hook_log("[context-guard] final answer must include BC summary: archived/updated BC this turn, and current unresolved BC.")
-            hook_log(f"[context-guard] current unresolved BC: {format_unresolved_bad_cases(open_cases)}")
-            return hook_response()
-        try:
-            test_code, test_output = run_test_hub_completion(root)
-            for line in test_output.splitlines():
-                hook_log(line)
-            hook_log(
-                "[context-guard] final answer must include Test Hub summary: "
-                + completion_test_summary(test_output, test_code)
-            )
-            if test_code != 0:
-                details = completion_test_failure_details(root)
-                if details:
-                    hook_log("[context-guard] failing approved test details: " + details)
-                reason = (
-                    "Context Guard Test Hub found failed or blocked approved tests. "
-                    "Read `.codex/context/test-hub/last-run.json` and preserved run evidence, "
-                    "then fix or report the blocker before finalizing."
+            elif not binding.get("session", {}).get("bound"):
+                return hook_response(platform, event, main_notice + f"Context Guard: no established workbench for automatic Session binding.{prior} Ask the user for the project workbench URL; see SKILL.md for binding.")
+        runtime_status = str(binding.get("runtime", {}).get("status") or "")
+        if runtime_status in {"legacy", "duplicate", "unknown"}:
+            return hook_response(platform, event, f"Context Guard binding exists, but the project workbench runtime is {runtime_status}. Do not create another service or ask to bind again. Run {context_guard_cli()} workbench --diagnose --root {json.dumps(str(root))} and follow the explicit migration result.")
+        if not binding.get("session", {}).get("verified") and os.environ.get("CONTEXT_GUARD_DISABLE_WORKBENCH") != "1":
+            try:
+                repaired = run_node_workbench([
+                    "workbench", "--root", str(root), "--session", current_session_id,
+                ])
+                verified_workbench_url = str(repaired.get("url") or "")
+                binding = run_node_workbench([
+                    "workbench", "--binding-status", "--root", str(root),
+                    "--session", current_session_id,
+                ])
+                if not binding.get("session", {}).get("verified"):
+                    raise RuntimeError("binding receipt was not verified")
+            except (OSError, ValueError, RuntimeError, subprocess.TimeoutExpired):
+                return hook_response(
+                    platform, event,
+                    f"Context Guard kept the existing Session binding, but its project workbench could not be verified or repaired. "
+                    f"Run {context_guard_cli()} workbench --diagnose --root {json.dumps(str(root))}. "
+                    "Source inspection and recovery commands may continue; do not create a second workbench or ask the user to bind again.",
                 )
-                if details:
-                    reason += " Failing tests: " + details
-                hook_log(f"[context-guard] TEST HUB BLOCKER: {reason}")
-                return hook_response(decision="block", reason=reason)
-        except subprocess.TimeoutExpired:
-            reason = "Context Guard Test Hub timed out after 900s; report this blocker and evidence before finalizing."
-            hook_log(f"[context-guard] TEST HUB BLOCKER: {reason}")
-            return hook_response(decision="block", reason=reason)
-        except Exception as exc:
-            hook_log(f"[context-guard] test hub hook warning: {exc}")
         try:
-            auto_propose = subprocess.run(
-                [
-                    sys.executable,
-                    str(SKILL_ROOT / "scripts" / "context_guard.py"),
-                    "feature-chain-auto-propose",
-                    "--root",
-                    str(root),
-                    "--from-hook",
-                ],
-                cwd=str(root),
-                text=True,
-                capture_output=True,
-                timeout=10,
+            memory = run_node_workbench(["memory", "prepare", "--root", str(root), "--session", current_session_id])
+            if memory.get("current"):
+                hook_log(f"[context-guard] server memory confirmed: {memory.get('sessionVersion')}; cache: {memory.get('cache')}")
+                memory_notice = f"Server memory confirmed; cache: {memory.get('cache')}."
+            else:
+                memory_notice = "Private memory unconfigured; local records are unsynced."
+        except (OSError, ValueError, RuntimeError, subprocess.TimeoutExpired):
+            memory_notice = "Server memory unavailable or conflicting; local records unverified."
+    if event not in {"session-start", "subagent-start", "user-prompt-submit", "post-compact"}:
+        try:
+            binding = run_node_workbench(["workbench", "--binding-status", "--root", str(root), "--session", current_session_id])
+        except (OSError, ValueError, RuntimeError, subprocess.TimeoutExpired):
+            return hook_response(platform, event, "Context Guard binding unavailable; no initialization.")
+        if not binding.get("session", {}).get("bound"):
+            forbidden = forbidden_direct_write(payload, root) if event == "pre-tool-use" else ""
+            if forbidden:
+                print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": forbidden}}))
+                return 0
+            return hook_response(platform, event, "Context Guard Session unbound; inspect workbench --list.")
+    created = init_context(root)
+    ensure_session_file(root, current_session_id, platform)
+    # Keep the lease alive until this hook invocation returns. Kernel locks are
+    # released even if the process crashes, so there is no stale lock cleanup.
+    _runtime_lease = acquire_hook_runtime_lock(root, current_session_id)
+    runtime = read_hook_runtime(root, current_session_id)
+
+    if event in {"session-start", "user-prompt-submit", "post-compact"}:
+        sync_pending_interrupt(root, current_session_id, runtime)
+
+    if event == "session-start":
+        # Registration must precede the inbox CLI's identity check.
+        append_session_event(root, event, platform, current_session_id,
+                             session_details(audit_details(payload, event, current_session_id, runtime, {"root_source": root_source})))
+        url = verified_workbench_url or None
+        if not (isinstance(payload, dict) and payload.get("is_background_agent") is True):
+            if not url:
+                try:
+                    url = start_workbench(root, open_browser=False, raise_errors=True, session_id=current_session_id)
+                except (OSError, RuntimeError, subprocess.TimeoutExpired):
+                    return hook_response(platform, event, f"Context Guard could not start or verify the bound project workbench. Run {context_guard_cli()} workbench --diagnose --root {json.dumps(str(root))}; no replacement service was started and the binding was preserved.")
+            if sync_configured(root, current_session_id):
+                sync_command(root, "ensure", current_session_id)
+        synchronized_memory = session_memory_sync(root, current_session_id, event, payload)
+        if isinstance(synchronized_memory.get("error"), dict):
+            memory_notice = "Cloud Session registration pending; local records preserved."
+        context_text, snapshot = map_context(root, ctx, current_session_id)
+        runtime["last_map_version"] = snapshot.get("version")
+        runtime["last_cloud_cursor"] = snapshot.get("cloud_cursor")
+        runtime["last_session_start"] = payload_time(payload)
+        write_hook_runtime(root, current_session_id, runtime)
+        hook_log(f"[context-guard] {'initialized' if created else 'ready'} {ctx} ({root_source})")
+        contexts = [memory_notice, language_setup_context(root, ctx), context_text,
+                    lifecycle_context(root, frontend_workbench_url(ctx, url, current_session_id), current_session_id)]
+        playbook = ctx / "tasks" / "J2.md"
+        if playbook.is_file():
+            contexts.append(
+                "Repository development playbook: read .codex/context/tasks/J2.md "
+                "for the current product and testing branch rules."
             )
-            output = (auto_propose.stdout + auto_propose.stderr).strip()
-            if output:
-                for line in output.splitlines():
-                    hook_log(line)
-            if auto_propose.returncode != 0:
-                hook_log(f"[context-guard] feature-chain auto-propose warning: exit {auto_propose.returncode}")
-        except Exception as exc:
-            hook_log(f"[context-guard] feature-chain auto-propose warning: {exc}")
-        open_cases = unresolved_bad_cases(bad_cases_path)
-        hook_log("[context-guard] final answer must include BC summary: archived/updated BC this turn, and current unresolved BC.")
-        hook_log(f"[context-guard] current unresolved BC: {format_unresolved_bad_cases(open_cases)}")
-        return hook_response()
-
-    hook_log("[context-guard] unknown hook event; use the context-guard skill if context changed.")
-    return hook_response()
+        return hook_response(platform, event, "\n\n".join(item for item in contexts if item))
+
+    if event == "subagent-start":
+        context_text, snapshot = map_context(root, ctx, current_session_id)
+        plan = runtime.get("active_plan") if isinstance(runtime.get("active_plan"), dict) else {}
+        agent_id = payload_value(payload, ("agent_id", "agentId"))
+        agent_type = payload_value(payload, ("agent_type", "agentType"))
+        subagents = runtime.get("subagents") if isinstance(runtime.get("subagents"), dict) else {}
+        subagents[agent_id or f"unknown-{len(subagents) + 1}"] = {
+            "type": agent_type,
+            "started_at": payload_time(payload),
+            "plan_id": plan.get("id") if isinstance(plan, dict) else None,
+            "node_ids": list(plan.get("node_ids") or []) if isinstance(plan, dict) else [],
+            "paths": list(plan.get("paths") or []) if isinstance(plan, dict) else [],
+            "status": "working",
+        }
+        runtime["subagents"] = subagents
+        write_hook_runtime(root, current_session_id, runtime)
+        append_session_event(root, event, platform, current_session_id, session_details(audit_details(
+            payload, event, current_session_id, runtime,
+            {"agent_id": agent_id or None, "agent_type": agent_type or None, "node_ids": plan.get("node_ids", []), "paths": plan.get("paths", [])},
+        )))
+        boundary = (
+            "Subagent scope is limited to the parent plan nodes "
+            f"{', '.join(plan.get('node_ids') or []) or 'none'} and paths {', '.join(plan.get('paths') or []) or 'none'}. "
+        )
+        return hook_response(platform, event, context_text + "\n\n" + boundary)
+
+    if event == "pre-tool-use":
+        if not mutating_tool(payload):
+            return hook_response(platform, event)
+        forbidden = forbidden_direct_write(payload, root)
+        if forbidden:
+            append_session_event(root, event, platform, current_session_id, session_details(audit_details(
+                payload, event, current_session_id, runtime, {"result": "denied", "error": "DIRECT_CONTEXT_WRITE"},
+            )))
+            print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": forbidden}}, ensure_ascii=False))
+            return 0
+        paths = tool_paths(payload, root)
+        # Host-temp JSON request files are not product implementation.
+        if write_like_tool(payload) and not paths and protocol_request_write(payload, root):
+            return hook_response(platform, event)
+        if platform == "claude":
+            execution = run_node_workbench(["map", "execution", "--root", str(root), "--session", current_session_id])
+            ci = execution.get("active") or {}
+            ci_allowed = ci_tool_allowed(payload, execution)
+            if ci_allowed is not None:
+                if ci_allowed:
+                    append_session_event(root, event, platform, current_session_id, session_details(audit_details(
+                        payload, event, current_session_id, runtime, {"result": "ci-test-authorized", "sourceSha": ci.get("sourceSha"), "taskId": ci.get("taskId")},
+                    )))
+                    return hook_response(platform, event)
+                print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "CI may run only its assigned test commands; business source edits are forbidden."}}, ensure_ascii=False))
+                return 0
+            if gh_pr_merge_command(payload) and not post_plan_delivery_command(payload, root):
+                print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Merge only with one standalone gh pr merge NUMBER command after accepted, archived work; shell chaining and --admin are not permitted."}}, ensure_ascii=False))
+                return 0
+            if post_plan_delivery_command(payload, root):
+                reason = ""
+                if not post_plan_delivery_ready(runtime, execution, root):
+                    reason = "Post-plan delivery needs the accepted task, archived Plan and clean worktree."
+                elif (number := post_plan_merge_target(payload)) and not verified_merge_checks(root, number):
+                    reason = "GitHub PR is not ready: every check must be complete and green before merge."
+                if reason:
+                    print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": reason}}, ensure_ascii=False))
+                    return 0
+                append_session_event(root, event, platform, current_session_id, session_details(audit_details(
+                    payload, event, current_session_id, runtime,
+                    {"result": "post-plan-delivery", "taskId": ci.get("taskId")},
+                )))
+                return hook_response(platform, event)
+        snapshot = map_snapshot(ctx, current_session_id)
+        owners = owner_nodes(paths, snapshot)
+        missing = sorted(set(owners.values()) - active_grants(snapshot))
+        if missing:
+            message = "Context Guard authorization required for Map node(s): " + ", ".join(missing) + ". Confirm the scope in the workbench, then retry the same tool."
+            append_session_event(root, event, platform, current_session_id, session_details(audit_details(
+                payload, event, current_session_id, runtime,
+                {"result": "denied", "error": "MAP_SCOPE_REQUIRED", "node_ids": sorted(set(owners.values())), "paths": paths},
+            )))
+            print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": message}}, ensure_ascii=False))
+            return 0
+        plan = runtime.get("active_plan") if isinstance(runtime.get("active_plan"), dict) else None
+        reason = ""
+        if pending_signals(runtime):
+            reason = pending_signal_guidance(root, current_session_id, runtime)
+        elif not plan or plan.get("status") != "working":
+            reason = "No active plan. Pipe authorized plan JSON to plan-start --input -."
+        elif any(not in_scope(file, plan["paths"]) for file in paths) or set(owners.values()) - set(plan["node_ids"]):
+            reason = "Tool exceeds the approved plan scope; do not silently expand it."
+        if reason:
+            print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": reason}}, ensure_ascii=False))
+            return 0
+        # Unknown scripts may mutate more than declared paths. Never certify their
+        # scope from command text; require an explicit review in the archive.
+        if not paths:
+            plan["scope_review_required"] = True
+        plan["revision"] = int(plan.get("revision", 0)) + 1
+        plan.pop("archive", None)
+        write_hook_runtime(root, current_session_id, runtime)
+        append_session_event(root, event, platform, current_session_id, session_details(audit_details(
+            payload, event, current_session_id, runtime,
+            {"result": "checked" if paths else "scope-unknown", "map_version": snapshot.get("version"), "node_ids": sorted(set(owners.values())), "paths": paths},
+        )))
+        return hook_response(platform, event)
+
+    if event == "permission-request":
+        paths = tool_paths(payload, root)
+        snapshot = map_snapshot(ctx, current_session_id)
+        owners = owner_nodes(paths, snapshot)
+        missing = sorted(set(owners.values()) - active_grants(snapshot))
+        append_session_event(root, event, platform, current_session_id, session_details(audit_details(
+            payload, event, current_session_id, runtime,
+            {"result": "denied" if missing else "deferred-to-user", "node_ids": sorted(set(owners.values())), "paths": paths},
+        )))
+        if missing:
+            return permission_response(event, "deny", "Context Guard Map authorization is missing for: " + ", ".join(missing) + ". Authorize it in the workbench first.")
+        return permission_response(event)
+
+    if event in {"post-tool-use", "post-tool-use-failure"}:
+        if event == "post-tool-use" and control_tool(payload):
+            return hook_response(platform, event)
+        plan = runtime.get("active_plan") if isinstance(runtime.get("active_plan"), dict) else None
+        paths = tool_paths(payload, root)
+        if plan:
+            before = plan.get("baseline") or {}
+            after = scope_snapshot(root, plan["paths"])
+            observed = {file for file in set(before) | set(after) if before.get(file) != after.get(file)}
+            paths = sorted(set(paths) | observed)
+            plan["actual_paths"] = sorted(set((plan.get("actual_paths") or []) + paths))
+            # Local observations only; Cloud upload/check happens at plan-finish.
+            write_hook_runtime(root, current_session_id, runtime)
+        failed = event == "post-tool-use-failure" or bool(isinstance(payload, dict) and (payload.get("error") or payload.get("is_error") is True))
+        response = payload.get("tool_response", {}) if isinstance(payload, dict) else {}
+        failed = failed or (isinstance(response, dict) and (response.get("isError") is True or bool(response.get("exit_code"))))
+        if plan and failed:
+            plan["failure_review_required"] = True
+            write_hook_runtime(root, current_session_id, runtime)
+        append_session_event(root, "toolFailure" if failed else event, platform, current_session_id, session_details(audit_details(
+            payload, event, current_session_id, runtime, {"result": "failed" if failed else "completed", "paths": paths},
+        )))
+        return hook_response(platform, event)
+
+    if event == "user-prompt-submit":
+        prompt = prompt_text(raw)
+        turn_id = payload_value(payload, ("turn_id", "turnId"))
+        signal = add_prompt_signal(root, current_session_id, turn_id, prompt) if prompt.strip() else None
+        runtime = read_hook_runtime(root, current_session_id)
+        runtime["current_turn_id"] = turn_id or None
+        runtime["last_prompt_signal"] = signal.get("id") if signal else None
+        write_hook_runtime(root, current_session_id, runtime)
+        status = append_user_message(ctx, prompt, current_session_id)
+        context_text, snapshot = map_context(root, ctx, current_session_id)
+        append_session_event(
+            root,
+            event,
+            platform,
+            current_session_id,
+            session_details(audit_details(payload, event, current_session_id, runtime, {
+                "message_status": status,
+                "signal_id": signal.get("id") if signal else None,
+                "prompt_hash": signal.get("prompt_hash") if signal else None,
+                "map_version": snapshot.get("version"),
+                "cloud_cursor": snapshot.get("cloud_cursor"),
+            })),
+        )
+        synchronized_memory = session_memory_sync(root, current_session_id, event, payload)
+        if isinstance(synchronized_memory.get("error"), dict):
+            memory_notice = "Cloud Session sync pending; local records preserved."
+        hook_log(f"[context-guard] user-messages: {status}")
+        signal_id = str(signal.get("id")) if signal else "none"
+        pending_ids = pending_signals(runtime)
+        pending_notice = ", ".join(pending_ids[:20]) or "none"
+        if len(pending_ids) > 20:
+            pending_notice += f" (+{len(pending_ids) - 20} more; use plan-status for the complete list)"
+        plan = runtime.get("active_plan") if isinstance(runtime.get("active_plan"), dict) else None
+        plan_notice = ""
+        if plan:
+            plan_notice = (
+                f" Active plan: {plan.get('id')} ({plan.get('summary') or 'unfinished'}). "
+            )
+        notice = (
+            context_text + "\n\n" +
+            f"User signal: {signal_id}. Pending user signals: {pending_notice}." + plan_notice
+        )
+        return hook_response(platform, event, memory_notice + "\n\n" + notice)
+
+    if event == "pre-compact":
+        plan = runtime.get("active_plan") if isinstance(runtime.get("active_plan"), dict) else None
+        runtime["compact_snapshot"] = {
+            "at": utc_now(),
+            "turn_id": payload_value(payload, ("turn_id", "turnId")) or None,
+            "trigger": payload_value(payload, ("trigger",)),
+            "active_plan": json.loads(json.dumps(plan)) if plan else None,
+            "pending_signals": [item.get("id") for item in runtime.get("signals") or [] if isinstance(item, dict) and item.get("status") == "pending"],
+        }
+        write_hook_runtime(root, current_session_id, runtime)
+        append_session_event(root, event, platform, current_session_id, session_details(audit_details(payload, event, current_session_id, runtime, {"result": "saved"})))
+        return hook_response(platform, event)
+
+    if event == "post-compact":
+        context_text, snapshot = map_context(root, ctx, current_session_id)
+        append_session_event(root, event, platform, current_session_id, session_details(audit_details(
+            payload, event, current_session_id, runtime, {"result": "restored", "map_version": snapshot.get("version"), "cloud_cursor": snapshot.get("cloud_cursor")},
+        )))
+        synchronized_memory = session_memory_sync(root, current_session_id, event, payload)
+        if isinstance(synchronized_memory.get("error"), dict):
+            memory_notice = "Cloud Session sync pending; local records preserved."
+        plan = runtime.get("active_plan")
+        restored = f"Restored plan: {plan.get('id')} with paths {', '.join(plan.get('actual_paths') or plan.get('paths') or [])}." if isinstance(plan, dict) else "No active development plan was present before compaction."
+        restored += " Pending signals: " + (", ".join(pending_signals(runtime)) or "none") + "."
+        return hook_response(platform, event, memory_notice + "\n\n" + context_text + "\n\n" + restored)
+
+    if event in {"interrupt", "stop-failure"}:
+        event_id, _, _ = event_identity(payload, event, current_session_id)
+        runtime["interrupted"] = {
+            "at": utc_now(),
+            "turn_id": payload_value(payload, ("turn_id", "turnId")) or None,
+            "plan_id": (runtime.get("active_plan") or {}).get("id") if isinstance(runtime.get("active_plan"), dict) else None,
+            "status": "interrupted",
+        }
+        pending = runtime.setdefault("pending_interrupts", [])
+        if not any(item.get("id") == event_id for item in pending):
+            pending.append({"id": event_id, "at": runtime["interrupted"]["at"]})
+        write_hook_runtime(root, current_session_id, runtime)
+        sync_pending_interrupt(root, current_session_id, runtime)
+        append_session_event(root, event, platform, current_session_id, session_details(audit_details(payload, event, current_session_id, runtime, {"result": "interrupted"})))
+        print(json.dumps({"systemMessage": "Context Guard: interrupted; plan preserved."}, ensure_ascii=False))
+        return 0
+
+    if event == "session-end":
+        append_session_event(root, event, platform, current_session_id, session_details(audit_details(
+            payload, event, current_session_id, runtime, {"result": "ended", "reason": payload_value(payload, ("reason",))},
+        )))
+        return hook_response(platform, event)
+
+    if event == "subagent-stop":
+        agent_id = payload_value(payload, ("agent_id", "agentId"))
+        subagents = runtime.get("subagents") if isinstance(runtime.get("subagents"), dict) else {}
+        record = subagents.get(agent_id) if isinstance(subagents.get(agent_id), dict) else {}
+        record.update({
+            "status": "stopped",
+            "stopped_at": payload_time(payload),
+            "last_message_hash": hashlib.sha256(payload_value(payload, ("last_assistant_message", "lastAssistantMessage")).encode("utf-8")).hexdigest(),
+        })
+        subagents[agent_id or f"unknown-{len(subagents) + 1}"] = record
+        runtime["subagents"] = subagents
+        write_hook_runtime(root, current_session_id, runtime)
+        append_session_event(root, event, platform, current_session_id, session_details(audit_details(payload, event, current_session_id, runtime, {"result": "stopped", "agent_id": agent_id or None})))
+        print(json.dumps({"systemMessage": "Context Guard: subagent stopped; review pending."}, ensure_ascii=False))
+        return 0
+
+    if event == "stop":
+        pending = pending_signals(runtime)
+        plan = runtime.get("active_plan") if isinstance(runtime.get("active_plan"), dict) else None
+        # Codex renders Stop block reasons as a user-role hook_prompt. Cursor and
+        # Claude still rely on the block contract to continue an unfinished turn.
+        blocked = bool((plan or pending) and platform != "codex")
+        # Stop checks local receipts only. Network work belongs to explicit plan
+        # boundaries and cannot time out this short hook into false success.
+        result = "incomplete" if blocked else "deferred" if (plan or pending) else "completed"
+        append_session_event(root, "stop-blocked" if blocked else event, platform, current_session_id,
+                             session_details(audit_details(payload, event, current_session_id, runtime,
+                                                           {"result": result, "state": "active" if blocked else "stopped",
+                                                            "pending_signal_count": len(pending)})))
+        if platform == "codex" or not blocked:
+            # Pending signals and active plans are already durable and will be
+            # re-injected through the next UserPromptSubmit additionalContext.
+            # Any Codex Stop block text becomes a user-visible hook_prompt.
+            print("{}")
+        elif isinstance(payload, dict) and payload.get("stop_hook_active") is True:
+            # Hosts may stop retrying hooks; allow reporting the blocker without
+            # converting unfinished work into a completion receipt or looping.
+            print(json.dumps({"systemMessage": "Context Guard is still finishing the current task. No user action is required."}, ensure_ascii=False))
+        else:
+            print(json.dumps({"decision": "block", "reason": "Context Guard is finishing the current task. No user action is required."}, ensure_ascii=False))
+        return 0
+
+    hook_log(f"[context-guard] ignored event: {event}")
+    return hook_response(platform, event)
 
 
 if __name__ == "__main__":