@michelj/context-guard 0.4.4 → 0.6.2

package/scripts/context_guard_hook.py

@@ -5,15 +5,27 @@ from __future__ import annotations
 
 import argparse
 import json
+import hashlib
 import os
+import re
+import shlex
+import sqlite3
+import subprocess
 import sys
+import tempfile
 from datetime import datetime, timezone
 from pathlib import Path, PureWindowsPath
+from urllib.parse import quote, urlsplit
 
-from context_guard import append_session_event
+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, folder_root, init_context, is_context_guard_skill_path
-from context_guard import read_preferences, start_workbench
+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
+
+WINDOWS_NO_WINDOW = getattr(subprocess, "CREATE_NO_WINDOW", 0)
 
 
 WORKSPACE_KEYS = {
@@ -84,6 +96,8 @@ def possible_workspace_paths(value: object) -> list[Path]:
 
 
 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:
@@ -92,6 +106,10 @@ def parse_hook_payload(raw: str) -> object:
         return {}
 
 
+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) -> tuple[Path, str]:
     payload = parse_hook_payload(raw)
     candidates: list[tuple[Path, str]] = []
@@ -104,7 +122,7 @@ def event_root(raw: str, cwd: Path) -> tuple[Path, str]:
     candidates.append((cwd, "process cwd"))
     for path, source in candidates:
         root = folder_root(path)
-        if not is_context_guard_skill_path(root):
+        if not is_context_guard_skill_path(root) or initialized_source_project(root):
             return root, source
     return folder_root(cwd), "process cwd"
 
@@ -129,14 +147,30 @@ HOOK_EVENT_NAMES = {
     "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",
 }
 
 
 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),
@@ -146,6 +180,22 @@ def hook_response(platform: str, event: str, additional_context: str = "") -> in
     return 0
 
 
+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 payload_value(payload: object, keys: tuple[str, ...]) -> str:
     if not isinstance(payload, dict):
         return ""
@@ -156,42 +206,456 @@ def payload_value(payload: object, keys: tuple[str, ...]) -> str:
     return ""
 
 
-def session_id(payload: object, platform: str) -> str:
+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 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"),
     )
-    if value:
-        return value
-    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
-    return f"{platform}-{stamp}-{os.getpid()}"
+    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 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:
+        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
+    return ""
 
 
 def language_setup_context(root: Path, ctx: Path) -> str:
-    language = str(read_preferences(ctx).get("record_language", "unset"))
+    try:
+        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 first-session setup is incomplete. Before substantive project work, "
-        "ask the user whether project context should be recorded in 中文 or English; do not infer it. "
-        "After the user answers, run `context-guard set-language --root "
+        "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 lifecycle_context(root: Path, workbench_url: str | None) -> str:
-    quoted_root = '"' + str(root).replace('"', '\\"') + '"'
+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 is active for {root}.{workbench} "
-        "Record a credible bad case with `context-guard record-bad-case --root "
-        f"{quoted_root} --title <title> --phenomenon <what-failed> --trigger <trigger> "
-        "--cause <cause-or-pending> --guard <regression-guard> --keys <comma-separated>`; "
-        "never store secrets in project context."
+        f"Context Guard: {root}; Session: {current_session_id}.{workbench} "
+        f"Instructions: {skill}. CLI: {context_guard_cli()}."
     )
 
 
+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:
+        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 local_url
+
+
 def prompt_text(raw: str) -> str:
     payload = parse_hook_payload(raw)
     return payload_value(payload, ("prompt", "user_prompt", "userPrompt", "text", "content"))
@@ -203,7 +667,7 @@ def redact(text: str) -> str:
     return text
 
 
-def append_user_message(ctx: Path, text: str) -> str:
+def append_user_message(ctx: Path, text: str, current_session_id: str) -> str:
     text = (text or "").strip()
     if not text:
         return "empty"
@@ -213,15 +677,958 @@ def append_user_message(ctx: Path, text: str) -> str:
         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", " ")
-    if line in body:
-        return "duplicate"
-    marker = "## Recent User Signals"
-    if marker in body:
-        body = body.replace(marker, marker + "\n\n" + line, 1)
+    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:
+        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)
+
+
+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:
+                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)
+
+    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:
+        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, 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)
+
+    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 re.fullmatch(r"(?:\d*)>&\d+", token):
+            index += 1
+            continue
+        if "&" in token:
+            return None
+        current.append(token)
+        index += 1
+    if current:
+        segments.append(current)
+    return segments if segments else None
+
+
+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 []
+    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 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:
-        body += "\n" + line + "\n"
-    path.write_text(body, encoding="utf-8")
-    return "recorded"
+        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:
@@ -236,34 +1643,174 @@ def main() -> int:
     payload = parse_hook_payload(raw)
     root, root_source = event_root(raw, Path.cwd())
     ctx = context_folder(root)
-    current_session_id = session_id(payload, platform)
 
-    if is_context_guard_skill_path(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 = ""
 
-    if event in {"session-start", "subagent-start"}:
-        created = init_context(root)
-        append_session_event(
-            root,
-            event,
-            platform,
-            current_session_id,
-            {"root_source": root_source},
-        )
-        url = None
-        if event == "session-start" and not (
-            isinstance(payload, dict) and payload.get("is_background_agent") is True
-        ):
-            start_reason = payload_value(payload, ("source", "reason", "session_start_type")).lower()
-            url = start_workbench(
-                root,
-                open_browser=start_reason not in {"resume", "clear", "compact"},
-            )
-        hook_log(
-            f"[context-guard] {'initialized' if created else 'ready'} {ctx} ({root_source})"
-        )
-        contexts = [language_setup_context(root, ctx), lifecycle_context(root, 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:
+                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.",
+                )
+            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.",
+                )
+        try:
+            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(
@@ -272,28 +1819,282 @@ def main() -> int:
             )
         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":
-        init_context(root)
-        status = append_user_message(ctx, prompt_text(raw))
+        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,
-            {"message_status": status},
+            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 in {"stop", "subagent-stop"}:
-        init_context(root)
-        append_session_event(root, event, platform, current_session_id)
-        hook_log(
-            "[context-guard] if this turn mattered, append sessions.jsonl and update bugs/tasks. "
-            "Do not run Test Hub or Roadmap HTML."
-        )
+    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)